diff --git a/conservancy_beancount/plugin/__init__.py b/conservancy_beancount/plugin/__init__.py
index cc832113bc9a2129ced6aa7ed43c51b73ebd85e2..3d6f283bb37ee18c7aa12009b79cebd927f0dbca 100644
--- a/conservancy_beancount/plugin/__init__.py
+++ b/conservancy_beancount/plugin/__init__.py
@@ -51,6 +51,7 @@ class HookRegistry:
'.meta_expense_allocation': None,
'.meta_income_type': None,
'.meta_invoice': None,
+ '.meta_payable_documentation': None,
'.meta_paypal_id': ['MetaPayPalID'],
'.meta_project': None,
'.meta_receipt': None,
diff --git a/conservancy_beancount/plugin/meta_payable_documentation.py b/conservancy_beancount/plugin/meta_payable_documentation.py
new file mode 100644
index 0000000000000000000000000000000000000000..b100ff5896d4371a6b292985d42d7046315f6805
--- /dev/null
+++ b/conservancy_beancount/plugin/meta_payable_documentation.py
@@ -0,0 +1,32 @@
+"""meta_payable_documentation - Validate payables have supporting docs"""
+# Copyright © 2020 Brett Smith
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see .
+
+from . import core
+from .. import config as configmod
+from .. import data
+from .. import errors as errormod
+from ..beancount_types import (
+ Transaction,
+)
+
+class MetaPayableDocumentation(core._RequireLinksPostingMetadataHook):
+ CHECKED_METADATA = ['invoice', 'contract']
+
+ def _run_on_post(self, txn: Transaction, post: data.Posting) -> bool:
+ if post.account.is_under('Liabilities:Payable'):
+ return not post.is_credit()
+ else:
+ return False
diff --git a/tests/test_meta_payable_documentation.py b/tests/test_meta_payable_documentation.py
new file mode 100644
index 0000000000000000000000000000000000000000..425e5d97c77020e40226cc6d63c346965fb54f30
--- /dev/null
+++ b/tests/test_meta_payable_documentation.py
@@ -0,0 +1,182 @@
+"""Test metadata for payables includes supporting documentation"""
+# Copyright © 2020 Brett Smith
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see .
+
+import random
+
+import pytest
+
+from . import testutil
+
+from conservancy_beancount import errors as errormod
+from conservancy_beancount.plugin import meta_payable_documentation
+
+ACCOUNTS = [
+ 'Liabilities:Payable:Accounts',
+ 'Liabilities:Payable:Vacation',
+]
+
+SUPPORTING_METADATA = [
+ 'contract',
+ 'invoice',
+]
+
+NON_SUPPORTING_METADATA = [
+ 'approval',
+ 'check',
+ 'purchase-order',
+ 'receipt',
+ 'statement',
+]
+
+OTHER_ACCT = 'Expenses:Other'
+MISSING_MSG = f"{{}} missing invoice/contract".format
+
+# for supporting links, use the lists from testutil
+
+@pytest.fixture(scope='module')
+def hook():
+ config = testutil.TestConfig(rt_client=testutil.RTClient())
+ return meta_payable_documentation.MetaPayableDocumentation(config)
+
+def seed_meta(support_values=testutil.NON_LINK_METADATA_STRINGS, **kwargs):
+ meta = dict(testutil.combine_values(
+ SUPPORTING_METADATA,
+ support_values,
+ ))
+ meta.update(kwargs)
+ return meta
+
+def wrong_type_message(acct, key, wrong_value):
+ return "{} has wrong type of {}: expected str but is a {}".format(
+ acct,
+ key,
+ type(wrong_value).__name__,
+ )
+
+def check(hook, expected, test_acct, other_acct=OTHER_ACCT, *,
+ txn_meta={}, post_meta={}, min_amt=10):
+ amount = '{:.02f}'.format(min_amt + random.random() * 100)
+ txn = testutil.Transaction(**txn_meta, postings=[
+ (test_acct, f'-{amount}', post_meta),
+ (other_acct, amount),
+ ])
+ actual = {error.message for error in hook.run(txn)}
+ if expected is None:
+ assert not actual
+ elif isinstance(expected, str):
+ assert expected in actual
+ else:
+ assert actual == expected
+
+@pytest.mark.parametrize('acct,support_key,support_value', testutil.combine_values(
+ ACCOUNTS,
+ SUPPORTING_METADATA,
+ testutil.LINK_METADATA_STRINGS,
+))
+def test_valid_docs_in_post(hook, acct, support_key, support_value):
+ meta = seed_meta()
+ meta[support_key] = support_value
+ check(hook, None, acct, post_meta=meta)
+
+@pytest.mark.parametrize('acct,support_key,support_value', testutil.combine_values(
+ ACCOUNTS,
+ SUPPORTING_METADATA,
+ testutil.LINK_METADATA_STRINGS,
+))
+def test_valid_docs_in_txn(hook, acct, support_key, support_value):
+ meta = seed_meta()
+ meta[support_key] = support_value
+ check(hook, None, acct, txn_meta=meta)
+
+@pytest.mark.parametrize('acct,meta_type', testutil.combine_values(
+ ACCOUNTS,
+ ['post_meta', 'txn_meta'],
+))
+def test_no_valid_docs(hook, acct, meta_type):
+ meta = seed_meta()
+ meta.update((key, value) for key, value in testutil.combine_values(
+ NON_SUPPORTING_METADATA,
+ testutil.LINK_METADATA_STRINGS,
+ ))
+ check(hook, {MISSING_MSG(acct)}, acct, **{meta_type: meta})
+
+@pytest.mark.parametrize('acct,meta_type', testutil.combine_values(
+ ACCOUNTS,
+ ['post_meta', 'txn_meta'],
+))
+def test_docs_all_bad_type(hook, acct, meta_type):
+ meta = seed_meta(testutil.NON_STRING_METADATA_VALUES)
+ expected = {
+ wrong_type_message(acct, key, value)
+ for key, value in meta.items()
+ }
+ expected.add(MISSING_MSG(acct))
+ check(hook, expected, acct, **{meta_type: meta})
+
+@pytest.mark.parametrize('acct,support_key,support_value', testutil.combine_values(
+ ACCOUNTS,
+ SUPPORTING_METADATA,
+ testutil.LINK_METADATA_STRINGS,
+))
+def test_type_errors_reported_with_valid_post_docs(hook, acct, support_key, support_value):
+ meta = seed_meta(testutil.NON_STRING_METADATA_VALUES)
+ meta[support_key] = support_value
+ expected = {
+ wrong_type_message(acct, key, value)
+ for key, value in meta.items()
+ if key != support_key
+ }
+ check(hook, expected, acct, post_meta=meta)
+
+@pytest.mark.parametrize('acct,support_key,support_value', testutil.combine_values(
+ ACCOUNTS,
+ SUPPORTING_METADATA,
+ testutil.LINK_METADATA_STRINGS,
+))
+def test_type_errors_reported_with_valid_txn_docs(hook, acct, support_key, support_value):
+ meta = seed_meta(testutil.NON_STRING_METADATA_VALUES)
+ meta[support_key] = support_value
+ expected = {
+ wrong_type_message(acct, key, value)
+ for key, value in meta.items()
+ if key != support_key
+ }
+ check(hook, expected, acct, txn_meta=meta)
+
+@pytest.mark.parametrize('acct,other_acct', testutil.combine_values(
+ ACCOUNTS,
+ ['Assets:Checking', 'Liabilities:CreditCard'],
+))
+def test_paid_accts_not_checked(hook, acct, other_acct):
+ txn = testutil.Transaction(postings=[
+ (acct, 250),
+ (other_acct, -250),
+ ])
+ assert not list(hook.run(txn))
+
+@pytest.mark.parametrize('account', [
+ 'Assets:Bank:Checking',
+ 'Assets:Cash',
+ 'Assets:Receivable:Accounts',
+ 'Equity:OpeningBalance',
+ 'Expenses:BankingFees',
+ 'Income:Donations',
+ 'Liabilities:CreditCard',
+ 'Liabilities:UnearnedIncome:Donations',
+])
+def test_does_not_apply_to_other_accounts(hook, account):
+ meta = seed_meta()
+ check(hook, None, account, post_meta=meta)