Month-end checklist for 2026-08

OK    Spend without a receipt: 0
CHECK Spend not exported to accounting yet: 3
OK    Invoices still waiting for approval: 0
OK    Invoices whose export failed: 0
OK    Declined card payments: 0

"""Month-end close checklist: what is still missing before closing a month.

Usage: python3 month_end_checklist.py [YYYY-MM]   (default: last month)
Needs SPENDESK_CLIENT_ID and SPENDESK_CLIENT_SECRET; SPENDESK_COMPANY_ID with an organisation-level key.
Scopes: experimental:payable-search:read, experimental:invoice:read, experimental:transaction:read, user:read.
"""
import base64, datetime as dt, json, os, sys, urllib.parse, urllib.request

BASE = os.environ.get("SPENDESK_BASE_URL", "https://public-api.spendesk.com")
COMPANY = os.environ.get("SPENDESK_COMPANY_ID")


def token():
    creds = base64.b64encode(f"{os.environ['SPENDESK_CLIENT_ID']}:{os.environ['SPENDESK_CLIENT_SECRET']}".encode()).decode()
    req = urllib.request.Request(BASE + "/v1/auth/token", data=b"grant_type=client_credentials",
                                 headers={"Authorization": "Basic " + creds, "Content-Type": "application/x-www-form-urlencoded"})
    return json.load(urllib.request.urlopen(req))["access_token"]


TOKEN = token()


def api(method, path, query=None, body=None):
    url = BASE + path + ("?" + urllib.parse.urlencode(query, doseq=True) if query else "")
    headers = {"Authorization": "Bearer " + TOKEN, "Content-Type": "application/json"}
    if COMPANY:
        headers["X-Company-Id"] = COMPANY
    req = urllib.request.Request(url, method=method, headers=headers, data=json.dumps(body).encode() if body else None)
    return json.load(urllib.request.urlopen(req))


today = dt.date.today()
month = sys.argv[1] if len(sys.argv) > 1 else (today.replace(day=1) - dt.timedelta(days=1)).strftime("%Y-%m")
first = dt.date.fromisoformat(month + "-01")
last = (first + dt.timedelta(days=32)).replace(day=1) - dt.timedelta(days=1)
company = COMPANY or api("GET", "/v1/users", {"pageSize": 1})["data"][0]["companyId"]


def search(extra_filter):
    """Payables of the month matching one more filter, every page."""
    found, cursor = [], None
    while True:
        body = {"filters": {"operator": "and", "subfilters": [
            {"field": "payableDate", "operator": "between",
             "value": {"from": f"{first}T00:00:00.000Z", "to": f"{last}T23:59:59.999Z"}},
            extra_filter]}, "limit": 100}
        if cursor:
            body["cursor"] = cursor
        page = api("POST", "/v1/payables/search", body=body)
        found += page["payables"]
        cursor = page.get("nextCursor")
        if not cursor:
            return found


def invoices(query):
    """Invoices issued in the month matching the query, every page."""
    found, cursor = [], None
    while True:
        page = api("GET", f"/v2/companies/{company}/invoices",
                   dict(query, issuedAfter=str(first), issuedBefore=str(last), limit=100, **({"cursor": cursor} if cursor else {})))
        found += page["data"]
        cursor = page["meta"]["pagination"]["nextCursor"]
        if not cursor:
            return found


checks = {
    "Spend without a receipt": search({"field": "documentaryEvidenceStatus", "operator": "=", "value": ["missing", "declaredAsInvalid"]}),
    "Spend not exported to accounting yet": search({"field": "bookkeepingStatus", "operator": "=", "value": ["toPrepare", "toExport"]}),
    "Invoices still waiting for approval": invoices({"approvalStatus": ["pending"]}),
    "Invoices whose export failed": invoices({"exportStatus": ["failed"]}),
    "Declined card payments": api("GET", "/v1/transactions/failed", {"startDate": str(first), "endDate": str(last)})["data"],
}
print(f"Month-end checklist for {month}\n")
for label, items in checks.items():
    print(f"{'OK' if not items else 'CHECK':<6}{label}: {len(items)}")