tres-invoice-bill-matching

# TRES — Invoice/Bill Matching & ERP Sync

End-to-end workflow that lets the user close an open ERP invoice or bill against a blockchain transaction in
the TRES ledger, then optionally push the matched entry to the connected ERP.

The flow is the same regardless of which side the user starts from (a transaction hash or an invoice/bill ID).
The skill walks through seven conversational steps (verify ERP → identify input → fetch & suggest → user picks
→ configure payment account & fiat → confirm & apply → loop). Stay terse — show numbered options, capture the
user's pick, move on. Never run a mutation without explicit "yes" from the user.

---

## Ground rules

1. **Identify the org first.** Begin with `get_viewer` and tell the user "You're connected to **{orgName}**."
   This makes mistakes recoverable when someone has the wrong token.
2. **Read before write.** Always fetch the current state of the transaction, invoice/bill, and payment account
   before showing a change summary. Surprises are worse than slow.
3. **Mutations require explicit approval.** Show a summary table (Transaction · Invoice/Bill · Payment Account ·
   Fiat alignment · Sync) and ask "Apply these changes?" before any mutation. Only proceed on a clear yes.
4. **Use schema introspection when in doubt.** Field names, enum values, and argument shapes can drift. If a
   query/mutation errors with "unknown field" or "invalid enum", call `introspect(<TypeName>)` or
   `build_query(<operationName>)` and adjust — don't guess. Operations specifically called out as "verify at
   runtime" below are the ones most likely to need this.
5. **The skill is a loop.** After a successful match, ask "Match another?" and restart from Step 2. Don't
   re-check the ERP — that only happens once per session.

---

## Step 1 — Verify ERP is connected

Run:
```graphql
query { integration(first: 50) { results { id integratedApp isErp connectionStatus companyName } } }
```

Filter the results where `isErp == true` and `connectionStatus == "ACTIVE"`. The supported ERPs you should
recognize are **Xero**, **QuickBooks Online (QBO)**, and **NetSuite** — `integratedApp` values are `XERO`,
`QUICKBOOKS`, and `NETSUITE`. (If you encounter unknown values, `introspect("IntegrationsQueryNode")` will
confirm the enum.) Ignore rows where `integratedApp` is empty — the API occasionally returns a null row.

- **No connected ERP:** Tell the user they need to connect one before matching can happen, point them at
  `https://app.tres.finance/settings/integrations`, and stop.
- **One connected ERP:** Use it implicitly and just mention "Matching against **{companyName}** ({integratedApp})."
- **Multiple connected ERPs:** Ask which one to use — different ERPs have separate invoice/bill stores.

Cache the chosen ERP's `id`, `integratedApp`, and `companyName` for later steps and the loop.

---

## Step 2 — Identify what the user has

Ask whether they have:
- a **transaction hash** (e.g. `0x…`) — best case, pins the match immediately,
- an **invoice/bill ID or number** (numeric internal ID, or the human-facing `invoiceNumber`/`billNumber`),
- or **both**.

If they have neither, require at least one. If they're not sure whether their identifier is an invoice or a
bill, accept it and try both lookups in Step 3.

Also accept loose forms — "INV-123", "Bill 9988", "the bill for Acme last week". The `freeText` filter on
`erpInvoices` / `erpBills` handles these.

**Before moving on, always ask for the transaction date (or an approximate date range) if they haven't given
a tx hash.** Ledger volume is high — date is the single most useful filter for narrowing candidates. Also
offer: *"If you happen to have the tx hash, paste it now — it pins the match exactly."* Date matters both
directions (tx→bill and bill→tx).

---

## Step 3 — Fetch the known object and produce ranked match suggestions

There are two branches. Pick by what the user provided. If they provided both a tx hash *and* an invoice/bill
ID, skip ahead to Step 5 (match is already determined).

### Branch A — User has a transaction hash

1. Fetch the transaction with its sub-transactions:
   ```graphql
   query GetTx($hash: String!) {
     transaction(identifier: $hash, currency: "usd", limit: 1) {
       results {
         id identifier timestamp platform
         children {
           id amount balanceFactor isInternalTransfer
           fiatValue
           sender    { identifier displayName isInternal }
           recipient { identifier displayName isInternal }
           asset { symbol identifier }
         }
       }
     }
   }
   ```
2. Pick the **relevant sub-transaction**. Skip gas, skip internal transfers, prefer the one with the user's
   wallet on one side and an external counterparty on the other. Determine direction:
   - `balanceFactor` negative → outflow → look for a **bill** to close.
   - `balanceFactor` positive → inflow → look for an **invoice** to close.
   If multiple sub-txs qualify (e.g., a swap with multiple legs), present them and let the user pick one.
3. **For invoices (inflow), try backend match suggestions first** — they are pre-computed and ranked:
   ```graphql
   query Suggest($subTxIds: [String]!) {
     subTransactionToInvoiceMatchSuggestions(
       subTransactionId_In: $subTxIds, minScore: 0.3, ordering: "-score", first: 10
     ) {
       results {
         id score confidenceTier
         scoreBreakdown { txHashMatch primaryMatchFactors }
         invoice {
           id invoiceId invoiceNumber customerName origAmount balance dueDate billingStatus
           integration { integratedApp companyName }
         }
       }
     }
   }
   ```
   Important: this endpoint is **invoice-only**. For **bills (outflow), skip straight to the fallback below**
   — there is no backend bill-suggestion query exposed in the schema.
4. **Fallback (zero invoice suggestions, or always for bills):** query `erpInvoices` (inflow) or `erpBills`
   (outflow), filtered by:
   - amount window: `±20%` of the su