The Close Cycle

A pass begins with a scheduled GET and ends with a JSON receipt. Between those two points the application resolves a bank key, upserts accounts, walks every transaction page, and writes what it has not seen before.

The repository contains both src/server/sync.ts and src/server/sync/index.ts. Both export runIncrementalSync, runFullSync and getSyncStatus. Only one of them ever runs.

Under the module resolution this project uses — tsconfig.json sets "moduleResolution": "bundler" — the bare specifier @/server/sync resolves to the file sync.ts in preference to the directory's index.ts. Every production import uses the bare specifier. Every test that exercises the categorisation trigger uses the deep path @/server/sync/index.

src/lib/mercury/ holds a typed client: a class, a singleton accessor, a reset function for tests, and a structured error. It is a careful piece of work — and the live sync path does not use it. src/server/sync.ts calls fetch directly against the same base URL. The client is reached only through the shadowed sync/accounts.ts and sync/transactions.ts.

new MercuryClient(key, opts?)

Throws 'Mercury API key is required' on an empty or whitespace-only key. Options accept maxRetries, retryBaseDelay and timeout.

getBaseUrl()

Returns https://api.mercury.com/api/v1, exposed so a test can assert it without reaching into a private field.

getAccounts() / getAccount(id)

/accounts and /account/{id}. The single-account call rejects with 'Account ID is required' for a blank id, before any network call.

getTransactions(id, opts?)

/account/{id}/transactions. Query parameters are start, end, limit, offset and status.

getAllTransactionsForAccount(id, since?)

Pages at pageSize = 500, incrementing offset, until a short page arrives or the accumulated count reaches the reported total.

getMercuryClient()

Lazy singleton over MERCURY_API_KEY; throws 'MERCURY_API_KEY environment variable is not set' when unset.

Transport settings

The synthesised 408 is worth noting: because isRetryable() covers only 429 and 5xx, a client-side timeout is not retried, while a server-side 503 is.

Error taxonomy

Every cell is a separate assertion in __tests__/lib/mercury/client.test.ts. An authentication failure is explicitly not retryable, so a revoked key fails fast rather than consuming the retry budget.

Running the client suite

The Mercury tests are split. Twenty-seven unit tests always run; six integration tests make real API calls and are gated behind three conditions — a key must be present, native fetch must exist, and SKIP_MERCURY_INTEGRATION must not be set. When they are skipped the suite prints the reason rather than staying silent.

$ npm test -- __tests__/lib/mercury/client.test.ts

> gogenticcfo@0.1.0 test
> jest __tests__/lib/mercury/client.test.ts

  console.log
    Integration tests: SKIPPED (MERCURY_API_KEY not set)

      at Object.<anonymous> (__tests__/lib/mercury/client.test.ts:352:7)

PASS __tests__/lib/mercury/client.test.ts
  MercuryClient
    constructor
      ✓ should create a client with a valid API key
      ✓ should throw an error when API key is empty
      ✓ should throw an error when API key is whitespace
      ✓ should accept custom configuration
    getBaseUrl
      ✓ should return the correct base URL
  MercuryError
    isRetryable
      ✓ should return true for 429 status
      ✓ should return false for 401 status
  MercuryClient Integration Tests
    ○ skipped 6 tests

Test Suites: 1 passed, 1 total
Tests:       6 skipped, 27 passed, 33 total

The console.log line is emitted by the suite itself — an “Integration Tests Status” block at the foot of the file exists purely to report why the integration describe was skipped. The totals reconcile: 33 it blocks in the file, six of them inside the conditionally skipped describe, and TASKS.md 2.2 independently records “27 tests”. The test script is plain jest, so npm test -- <path> forwards the path straight through.

Running the cycle twice must not double the ledger. The guarantee is structural — transactions.mercury_id carries a UNIQUE constraint — and the live path leans on it directly with onConflictDoUpdate.

// accounts
.onConflictDoUpdate({ target: accounts.mercuryId, /* name, type, balance, lastSyncedAt */ })

// transactions — note what is NOT in the update set
.onConflictDoUpdate({ target: transactions.mercuryId, set: {
    amount, description, counterpartyName, syncedAt
    // categoryId    — preserved, so a classification is never undone
    // date          — preserved
    // direction     — preserved
}})

Excluding categoryId from the update set is what makes a re-sync safe: a manual override, or a category the model assigned, survives every subsequent pass. It also means a correction to date or direction upstream will never propagate.

What a freshly synced row looks like

tx.aiCategorized       === false
tx.categoryId          === null
tx.manuallyOverridden  === false

// signed-to-unsigned conversion, asserted on the same rows:
upstream  50000  →  amount 50000, direction 'inflow'
upstream -15000  →  amount 15000, direction 'outflow'
upstream      0  →  amount     0, direction 'inflow'

The zero case carries its own test, titled “should return ‘inflow’ for zero (edge case)”. A fee reversal of exactly zero therefore lands on the inflow side of every aggregate.

Bank counterparty strings are noisy: the same vendor arrives with a run number, a reference, an order id or a processor prefix appended. Before anything is matched or learned, the string passes through normalizeVendorName in src/server/patterns/index.ts.

Vendor strings shown here are the test fixtures' own examples — well-known software and transport brands used to illustrate a string-handling rule, not counterparties drawn from the ledger.

The rest of the pattern module

findPatternMatch(name)

Exact ilike first, then a substring scan. A hit increments match_count as a side effect — a read that writes.

createPattern(pattern, categoryId, source)

Insert or update a row in category_patterns. source defaults to 'manual_rule'.

applyPatternToTransactions(pattern, categoryId)

Bulk update: sets category_id and ai_categorized on every transaction whose counterparty matches, excluding rows already flagged manually_overridden. Returns the affected row count.

The classifier is built to call the model as rarely as possible. Learned patterns are consulted first, and only vendors that no rule covers are batched off to Claude. Every accepted answer becomes a rule, so the population needing inference shrinks with use.

The closed vocabulary

The model is not free to invent a category. The prompt lists twelve labels with parenthetical examples and demands a bare JSON object; the reply is then looked up case-insensitively against the twelve seeded names, and a miss resolves to Other. The vocabulary is fixed at the data layer, not merely requested in prose.

Who calls it

Two scheduled endpoints on interlocking intervals, declared in vercel.json, with deliberately different authorisation postures.

{
  "crons": [
    { "path": "/api/cron/sync",  "schedule": "*/5 * * * *"  },
    { "path": "/api/categorize", "schedule": "*/10 * * * *" }
  ]
}

The shared cron helpers

Endpoint contracts

The timestamp field is asserted to round-trip: new Date(json.timestamp).toISOString() === json.timestamp. A third cron-adjacent route, GET /api/cron/health, is public and unauthenticated by design and returns { status: 'healthy', timestamp }.