Purpose

Automate preparatory bookkeeping from incoming email to accounting records.

Core objective:

• detect invoice email,
• extract structured invoice data,
• verify payment event,
• create accounting entry and reconciliation status.

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)

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)

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)

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)

• message ID
• sender
• received date
• attachment candidates

Stage 2: Attachment extraction

For each invoice candidate attachment:

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

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

• 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

Stage 4: Accounting write

Use Xero for booking.

Default payable flow:

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

• 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":

• Gmail finds AWS email with PDF attachment.
• DeepRead OCR extracts structured fields (vendor/date/total/tax/invoice number).
• Stripe check confirms payment event around invoice date and amount.
• Xero creates payable entry (ACCPAY) under Hosting category.
• 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": "[email protected]",
    "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)

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.