Purpose

Automate preparatory bookkeeping from incoming email to accounting records.

Core objective:

1. detect invoice email,
2. extract structured invoice data,
3. verify payment event,
4. create accounting entry and reconciliation status.

This is orchestration logic across upstream tools; it is not a replacement for financial controls.

Required Installed Skills

• gmail (inspected latest: 1.0.6)
• deepread-ocr (inspected latest: 1.0.6)
• stripe-api (inspected latest: 1.0.8)
• xero (inspected latest: 1.0.4)

Install/update:

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

Required Credentials

• MATON_API_KEY (for Gmail, Stripe, Xero through Maton gateway)
• DEEPREAD_API_KEY (for OCR extraction)

Preflight:

echo "$MATON_API_KEY" | wc -c
echo "$DEEPREAD_API_KEY" | wc -c

If missing, stop before any bookkeeping action.

Inputs the LM Must Collect First

• company_base_currency
• invoice_keywords (default: invoice, rechnung, receipt, quittung)
• vendor_rules (for example AWS -> Hosting expense account)
• date_tolerance_days for matching (default: 3)
• amount_tolerance (default: exact, or configurable small tolerance)
• auto_post_policy (manual-review, auto-if-high-confidence)
• attachment_policy (store-link, attach-binary-if-supported)

Do not auto-post financial records without explicit policy.

Tool Responsibilities

Gmail (gmail)

Use for intake and attachment discovery.

Relevant behavior:

• query messages with Gmail operators (for example has:attachment, subject:invoice, sender filters)
• fetch message metadata and full payload for parsing
• label/update messages after processing (for traceability)

DeepRead OCR (deepread-ocr)

Use for extracting structured fields from invoice PDFs/images.

Relevant behavior:

• async processing (queued -> completed/failed)
• schema-driven extraction
• field-level hil_flag and reason for uncertainty
• webhook or polling modes

Stripe (stripe-api)

Use for payment-side verification.

Relevant behavior:

• query charges/payment_intents/invoices/balance transactions
• verify amount, currency, status, and date proximity

Xero (xero)

Use for accounting record creation and payment/reconciliation visibility.

Relevant behavior:

• create contacts if missing
• create invoices/bills (ACCPAY for payable bills)
• list payments and bank transactions

Canonical Signal Chain

Stage 1: Inbox detection

Scan Gmail for candidate invoice emails.

Recommended query pattern:

• has:attachment (subject:invoice OR subject:rechnung OR subject:receipt OR subject:quittung)
• optional sender constraint for known vendors (for example from:aws)

Output:

• message ID
• sender
• received date
• attachment candidates

Stage 2: Attachment extraction

For each invoice candidate attachment:

1. send file to DeepRead OCR with invoice schema
2. wait for async completion (webhook preferred; polling fallback)
3. parse structured result

Minimum extracted fields:

• vendor
• invoice_date
• invoice_number
• total_amount
• tax_amount
• currency

Quality gate:

• if critical fields have hil_flag=true, route to review queue before posting.

Stage 3: Payment verification

Use Stripe to check whether corresponding payment occurred.

Matching policy:

• amount equals invoice total (within tolerance)
• currency matches
• date within tolerance window
• status is successful/paid

If multiple candidates match, mark as ambiguous_match and require review.

Stage 4: Accounting write

Use Xero for booking.

Default payable flow:

1. ensure vendor contact exists (create if needed)
2. create bill entry (Type: ACCPAY) with line item category (for example Hosting)
3. mark as paid/reconciled state only when Stripe verification is confident
4. include reference fields: invoice number, source message ID, payment reference

Attachment handling:

• if binary attachment endpoint/path is available in the active integration, attach file
• otherwise store durable file reference and include link/reference in description/metadata

Stage 5: Traceability updates

After successful processing:

• apply Gmail processed label
• store processing log (source email, extraction confidence, matching evidence, xero IDs)
• keep idempotency key to avoid duplicate posting

Scenario Mapping (AWS Invoice)

For the scenario "AWS invoice by email -> Xero + card match":

1. Gmail finds AWS email with PDF attachment.
2. DeepRead OCR extracts structured fields (vendor/date/total/tax/invoice number).
3. Stripe check confirms payment event around invoice date and amount.
4. Xero creates payable entry (ACCPAY) under Hosting category.
5. Record is marked paid only after confident match; source PDF linked/attached per policy.

Data Contract

Normalize to one transaction record before posting:

{
  "source": {
    "gmail_message_id": "...",
    "sender": "billing@aws.amazon.com",
    "attachment_name": "invoice.pdf"
  },
  "invoice": {
    "vendor": "AWS",
    "invoice_number": "INV-123",
    "invoice_date": "2024-05-01",
    "total": 53.20,
    "tax": 0.00,
    "currency": "USD",
    "ocr_confidence_ok": true
  },
  "payment_match": {
    "provider": "stripe",
    "matched": true,
    "transaction_id": "ch_...",
    "amount": 53.20,
    "date": "2024-05-01"
  },
  "accounting": {
    "system": "xero",
    "entry_type": "ACCPAY",
    "category": "Hosting",
    "status": "Paid"
  }
}

Output Contract

Always return:

• IntakeSummary
• emails scanned, invoice candidates found

• ExtractionSummary
• extracted fields and hil_flag status

• PaymentVerification
• matched/not matched + evidence

• AccountingAction
• created/updated records and IDs

• ReviewQueue
• any records requiring manual validation

Quality Gates

Before auto-posting:

• vendor identified
• invoice number/date/total present
• no critical hil_flag unresolved
• payment match confidence above policy threshold
• duplicate check passed (same vendor + invoice number + total)

If any gate fails, return Needs Review and do not auto-post.

Guardrails

• Never mark invoice as paid without payment evidence.
• Never silently overwrite existing accounting records.
• Never drop uncertain OCR fields; surface them explicitly.
• Prefer manual review when amount/date ambiguity exists.
• Preserve source audit trail for every booking action.

Failure Handling

• Gmail unavailable: stop intake and report connection issue.
• OCR job failed/timeout: keep email queued for retry.
• Stripe no match: post as unpaid bill or route to review per policy.
• Xero write failed: keep normalized record and retry safely with idempotency key.

Known Limits from Inspected Upstream Skills

• DeepRead OCR is asynchronous and may require webhook/polling orchestration.
• The inspected Xero skill docs emphasize core accounting endpoints but do not fully document attachment upload flow; attachment behavior depends on supported endpoint path in active integration.
• Stripe/Xero matching is orchestration logic here, not a single native "auto-reconcile" endpoint in these inspected skill docs.
• QuickBooks is not part of this researched stack; this meta-skill is Xero-first.

Treat these limits as mandatory operator disclosures.