Bookkeeper

intent

automates the full bookkeeping intake pipeline: finds invoice emails in gmail, extracts structured data via ocr, verifies the corresponding payment in stripe, and posts accounting entries to xero with reconciliation status. use this when you need to turn incoming invoices into auditable accounting records without manual data entry. this is orchestration across upstream tools, not a replacement for financial controls.

inputs

required credentials

• MATON_API_KEY (env var): gateway token for gmail, stripe, xero access. test with echo "$MATON_API_KEY" | wc -c before running. stop if missing.
• DEEPREAD_API_KEY (env var): ocr extraction service token. test with echo "$DEEPREAD_API_KEY" | wc -c. stop if missing.

required installed skills

install via npm if not present:

npx -y clawhub@latest install gmail deepread-ocr stripe-api xero
npx -y clawhub@latest update --all

verified minimum versions: gmail 1.0.6, deepread-ocr 1.0.6, stripe-api 1.0.8, xero 1.0.4.

user-supplied parameters

• company_base_currency (string): e.g. "USD", "EUR". required.
• invoice_keywords (array): search terms for inbox detection. default: ["invoice", "rechnung", "receipt", "quittung"].
• vendor_rules (object): vendor name to expense account mapping. e.g. {"AWS": "Hosting", "Twilio": "Communications"}.
• date_tolerance_days (integer): invoice date to payment date window. default: 3.
• amount_tolerance (string or float): "exact" or e.g. 0.50 for +/- $0.50. default: "exact".
• auto_post_policy (enum): "manual-review" or "auto-if-high-confidence". required. do not default to auto-post.
• attachment_policy (enum): "store-link" or "attach-binary-if-supported". default: "store-link".

external connections

• Gmail API: via MATON_API_KEY. requires OAuth scope for labels, attachments, and message updates.
• DeepRead OCR: async service, via DEEPREAD_API_KEY. supports webhook callbacks (preferred) or polling.
• Stripe API: via MATON_API_KEY. read access to charges, payment_intents, invoices, and balance transactions.
• Xero API: via MATON_API_KEY. write access to contacts, bills (ACCPAY), and payments.

procedure

step 1: scan gmail for invoice candidates

inputs: invoice_keywords, optional sender constraints (e.g. "from:aws@amazon.com").

process:

1. construct gmail query: has:attachment (subject:{keyword1} OR subject:{keyword2} ...) [optional: from:known_vendor]
2. fetch matching messages with full payload (headers, metadata, attachment list).
3. filter for pdf, image, or other invoice-like mimetypes.

outputs: list of candidate messages with: message_id, sender, received_date, attachment_filename, attachment_id.

edge cases:

• rate limit (gmail quota): pause and retry after 60 seconds.
• no candidates found: return empty intake summary, exit cleanly.
• attachment fetch fails: log error, skip message, continue scan.

step 2: extract structured data from attachments via deepread ocr

inputs: attachment payload (binary or uri), invoice schema (vendor, invoice_date, invoice_number, total_amount, tax_amount, currency).

process:

1. for each candidate attachment, send to deepread ocr with schema.
2. submit async job, get job_id.
3. poll or wait for webhook with results (webhook preferred; polling every 5 seconds, max 60 seconds timeout).
4. parse response: extract fields, capture hil_flag (high-uncertainty flag) and reason per field.

outputs: structured invoice record with: vendor, invoice_date, invoice_number, total_amount, tax_amount, currency, ocr_confidence_ok (boolean), hil_fields (list of uncertain fields with reasons).

edge cases:

• ocr job timeout after 60 seconds: queue attachment for manual retry, do not block.
• critical fields missing (vendor, total, date, number): mark hil_flag=true, route to review.
• ocr service unavailable (5xx): log error, retry message in next batch.
• low confidence (e.g. < 70%): set ocr_confidence_ok=false, do not auto-post.

step 3: verify payment in stripe

inputs: invoice total_amount, currency, invoice_date, vendor name, amount_tolerance, date_tolerance_days.

process:

1. query stripe for charges/payment_intents within date window (invoice_date +/- date_tolerance_days).
2. filter by currency and amount (within tolerance).
3. check status: must be succeeded/paid.
4. collect metadata: transaction_id, actual_amount, actual_date, description/metadata hints.

outputs: payment_match object with: matched (boolean), transaction_id (or null), amount, date, confidence_reason.

edge cases:

• no payment found: matched=false, post as unpaid bill to xero per auto_post_policy.
• multiple candidates match: matched=false, mark ambiguous_match=true, route to review.
• stripe service unavailable: retry step 3 with exponential backoff (max 3 attempts).
• amount exceeds tolerance: matched=false, log variance, route to review.
• payment date outside window: matched=false, log date gap, route to review.

step 4: check for duplicates and apply quality gates

inputs: normalized transaction record (vendor, invoice_number, total_amount, company_base_currency).

process:

1. query xero for existing bills matching vendor + invoice_number + total.
2. if found: return duplicate_found=true, do not proceed.
3. check quality gates:
   • vendor identified: yes/no
   • invoice_number, invoice_date, total_amount all present: yes/no
   • hil_flag fields resolved or acceptable: yes/no
   • ocr_confidence_ok: yes/no
   • payment_match confidence meets policy threshold: yes/no
4. if all gates pass: proceed to step 5. else: add to review queue.

outputs: quality_gate_result (passed/failed), fail_reasons (list of gate failures).

edge cases:

• xero query fails: skip duplicate check, proceed cautiously with idempotency key.
• policy threshold undefined: default to manual_review.

step 5: create accounting entry in xero

inputs: normalized invoice record, vendor_rules, auto_post_policy, attachment_policy, xero idempotency_key.

process:

1. lookup vendor in xero contacts; if missing, create contact with sender email and vendor name.
2. determine expense account from vendor_rules; default to generic "Accounts Payable" if unmapped.
3. create bill (Type=ACCPAY) with:
   • contact_id (vendor)
   • invoice_number, invoice_date
   • line items: amount, tax, account code
   • reference fields: original gmail message_id, deepread job_id, stripe transaction_id (if matched)
   • description: include source audit trail
4. if payment_match=true and auto_post_policy="auto-if-high-confidence": mark bill as paid with payment_id from stripe.
5. if auto_post_policy="manual-review": mark bill as draft, add to review queue.
6. per attachment_policy:
   • if "attach-binary-if-supported": attempt to upload attachment via xero file endpoint (if available); fall back to link.
   • if "store-link": add file reference/uri in description.

outputs: xero bill_id, contact_id, bill_status, attachment_reference.

edge cases:

• vendor contact creation fails: stop, report error, add record to review queue.
• bill creation fails (validation error): log details, add to review queue.
• xero service unavailable: log error, store idempotency_key, retry in background.
• attachment upload unsupported: fall back to link reference.
• duplicate bill already posted (idempotency key collision): return existing bill_id, do not re-post.

step 6: update gmail and log traceability

inputs: message_id, xero_bill_id, processing metadata.

process:

1. apply label to processed message (e.g. "bookkeeper/processed" or "bookkeeper/review-needed" based on outcome).
2. store processing log record (in memory or persistent log) with:
   • gmail_message_id
   • attachment_name
   • extraction confidence
   • payment_match evidence (yes/no, transaction_id)
   • xero_bill_id
   • quality_gate_result
   • idempotency_key
3. if review needed: also store in review queue for operator action.

outputs: label_applied (boolean), log_stored (boolean).

edge cases:

• label application fails: log warning, do not block completion.
• persistent log unavailable: log to stdout/stderr as fallback.

decision points

decision 1: critical ocr fields missing or high-uncertainty?

• if yes: set hil_flag=true, route to review queue, do not auto-post.
• if no: proceed to payment verification.

decision 2: payment found in stripe within tolerance and date window?

• if yes (matched=true): proceed to quality gates with high confidence.
• if no (matched=false) and auto_post_policy="manual-review": create unpaid bill in xero, route to review.
• if no (matched=false) and auto_post_policy="auto-if-high-confidence": create unpaid bill in xero only if ocr confidence is very high (>85%), else route to review.
• if multiple candidates (ambiguous): route to review regardless of policy.

decision 3: duplicate bill already exists in xero?

• if yes: log duplicate, do not re-post, return existing bill_id.
• if no: proceed to step 5.

decision 4: all quality gates passed?

• if yes and auto_post_policy="auto-if-high-confidence" and payment_match=true: auto-post as paid bill.
• if yes and auto_post_policy="manual-review": auto-post as draft bill, add to review queue.
• if no: add record to review queue, do not post.

decision 5: attachment binary available and attachment_policy="attach-binary-if-supported"?

• if yes and xero attachment endpoint available: upload binary attachment.
• if yes but endpoint unavailable: store link reference in description.
• if no or policy="store-link": store link reference only.

output contract

always return a structured result object with the following sections:

intake_summary

• emails_scanned: integer
• invoice_candidates_found: integer
• candidate_messages: array of {message_id, sender, received_date, attachment_filename}

extraction_summary

• records_extracted: integer
• extraction_details: array of {gmail_message_id, vendor, invoice_number, invoice_date, total_amount, currency, ocr_confidence_ok, hil_fields: [{field_name, hil_flag, reason}]}
• extraction_failures: array of {message_id, reason}

payment_verification

• records_verified: integer
• verification_details: array of {invoice_number, matched: boolean, stripe_transaction_id, amount, date, confidence_reason}
• unmatched_records: array of {invoice_number, reason}
• ambiguous_matches: array of {invoice_number, candidates: integer}

accounting_action

• records_posted: integer
• posting_details: array of {invoice_number, xero_bill_id, bill_status, contact_id, attachment_reference}
• posting_failures: array of {invoice_number, reason}

review_queue

• records_needing_review: integer
• review_items: array of {gmail_message_id, invoice_number, reason_for_review, normalized_record: {...}}

processing_log

• start_time: iso8601
• end_time: iso8601
• duration_seconds: float
• idempotency_keys: array (for safe retry)

all data normalized to the contract schema:

{
  "source": {
    "gmail_message_id": "string",
    "sender": "string",
    "attachment_name": "string",
    "received_date": "iso8601"
  },
  "invoice": {
    "vendor": "string",
    "invoice_number": "string",
    "invoice_date": "iso8601",
    "total": "number",
    "tax": "number",
    "currency": "string",
    "ocr_confidence_ok": "boolean",
    "hil_fields": ["string"]
  },
  "payment_match": {
    "provider": "stripe",
    "matched": "boolean",
    "transaction_id": "string or null",
    "amount": "number or null",
    "date": "iso8601 or null"
  },
  "accounting": {
    "system": "xero",
    "entry_type": "ACCPAY",
    "category": "string",
    "status": "Draft | Paid",
    "bill_id": "string or null",
    "contact_id": "string or null"
  }
}

outcome signal

the skill succeeded if:

1. intake complete: emails_scanned > 0, invoice_candidates_found reflects expected result (zero if no invoices, >0 if invoices present).

2. extraction complete: extraction_summary.records_extracted matches expected count; hil_fields array is populated only for uncertain fields; no silent data loss.

3. payment verification complete: every extracted invoice has a verification_details entry (matched or unmatched); ambiguous_matches are flagged, not guessed.

4. accounting posted correctly:

   • if auto_post_policy="auto-if-high-confidence" and gates passed: xero_bill_id is non-null, bill_status="Paid" (if payment matched) or "Draft" (if unmatched).
   • if auto_post_policy="manual-review": xero_bill_id is non-null, bill_status="Draft", and record is in review_queue for operator sign-off.
   • no xero posting occurred without explicit policy decision.

5. no silent overwrites: if duplicate detected, existing bill_id is returned, not overwritten.

6. audit trail preserved: processing_log contains all idempotency_keys and source references; operator can trace any record back to original gmail message.

7. review queue populated correctly: any record with hil_flag=true, ocr_confidence_ok=false, payment_match=false, or quality gate failure is in review_queue. zero items in review_queue only if all records are high-confidence matches and auto-posted.

check logs for completion: if end_time is set and duration_seconds >= 0, the skill ran to completion (success or expected failure). if end_time is null or missing, the skill crashed or timed out.