[tela]

Stacked on #4. Merge #4 first. The base branch is feat/seeded-world-and-reset, and GitHub retargets this to main once that branch is merged and deleted.

Motivation

The seeded world needs a lender to act on it. This adds ACME Commerce Lenders' own logic: a merchant applies, the lender connects to the merchant's Stripe, Plaid and Xero accounts, reads what they hold, and makes a working-capital offer. It is served over HTTP so the UI and the inspector have something to call.

Changes

• feat(shared): let the recording proxy serve calls in process: the lender makes its own vendor calls, so each one is recorded without opening a port that could clash with LocalStack's.
• feat(acme): record when the world's history ends: "the last 30 days" is measured from that moment and not from the wall clock, because seeding moves the app emulators' clocks ahead.
• feat(acme): read a merchant's data from Stripe, Plaid and Xero: connects to each account, pages through all 941 charges, and reads payouts, the bank account and the invoices. Every call is recorded and credentials are masked in the recording.
• feat(acme): price a traceable working-capital offer: the advance is the last 30 days of card sales rounded down to $500, for a flat 8% fee. Each number names the vendor call it came from. Plaid's balance is shown but does not change the offer, because the app emulator's fixture is too thin to price against.
• feat(acme): add the application flow from apply to offer: apply, connect, review, offer, each refused out of order. A failed step saves nothing and can be retried.
• test(acme): share the fake vendors between test packages
• feat(acme): serve the application flow as an HTTP API: status, reset, the steps, and the recorded vendor calls. A reset waits for in-flight calls and they wait for it.
• docs(acme): document the application API and the seeded offer

For the seeded merchant the offer is a $30,000 advance for a $2,400 fee ($32,400 to repay), on sales growth of 14.8%.

Tests

On the final tip:

$ make vet          # exit 0
$ make test         # exit 0
ok  apps/acme-commerce-lenders/core
ok  apps/acme-commerce-lenders/internal/api
ok  apps/acme-commerce-lenders/internal/cli
ok  apps/acme-commerce-lenders/internal/ui
ok  apps/acme-commerce-lenders/lender
ok  apps/acme-commerce-lenders/world
ok  shared/emulator
ok  shared/seed
ok  shared/vendorcfg
ok  shared/wire
$ make check-kits   # exit 0
$ make build        # exit 0
$ gofmt -l .        # no output

The seeded merchant's offer is pinned by a test. Its numbers were checked against a separate Python implementation of the world's order generator, which agrees on 941 orders, a gross of $81,083.84, last-30-day sales of $30,423.72, and an advance of $30,000. Each of the eight commits was also checked out on its own and passes gofmt, go vet, go test -race and make check-kits.

Run for real, with Plaid, Xero and Stripe built from WonderTwin-AI/wondertwin origin/main (9a92fbdf), and then again with Stripe served by a running LocalStack and Plaid and Xero run locally. In both, over HTTP:

POST /api/reset                          # 200, seeded in 0.2 s locally, 1.7 s with Stripe in LocalStack
POST /api/applications                   # 201 app-0001
POST /api/applications/app-0001/offer    # 409 before the earlier steps, as designed
POST .../connect, .../review, .../offer  # 200 each
  stripe: 941 orders, last 30 days $30,423.72, 12 payouts
  xero:   $16,150.00 outstanding, $5,400.00 overdue
  offer:  approved, advance $30,000.00, fee $2,400.00, growth 14.8%
GET /api/events                          # 18 recorded calls; Plaid's access token and secret masked

Both runs gave identical numbers, and each recorded call says whether LocalStack or a local process served it.

Not tested: running with the network off.

Related

DOC-581