@firedrill-tools/trolley 0.1.1

package/test/conformance.mjs

@@ -0,0 +1,12 @@
+// Trolley Tool conformance target. A scripted Tool test, not a model-driven agent.
+// Node built-ins only: fetch against the Trolley-shaped REST routes (`Authorization: prsign <token>` or `Bearer`) and the
+// canonical Firedrill operation endpoint. Every flow fails loudly on an unexpected status, envelope or field.
+import { main } from "./harness.mjs";
+import "./flow-recipients.mjs";
+import "./flow-accounts.mjs";
+import "./flow-batches.mjs";
+import "./flow-processing.mjs";
+import "./flow-access.mjs";
+import "./flow-faults.mjs";
+
+await main();

package/test/flow-access.mjs

@@ -0,0 +1,54 @@
+// Access flows: read-only key, another merchant's key, fresh-install actor, actor without grants.
+import { A, B, P, R, api, assert, fails, flow } from "./harness.mjs";
+
+const payment = { recipient: { id: R(1) }, amount: "10.00", currency: "USD" };
+/** One schema-valid request per write operation (14). */
+const WRITES = [
+  ["POST", "/v1/recipients", { type: "individual", email: "probe@example.com", firstName: "Pro", lastName: "Be" }],
+  ["PATCH", `/v1/recipients/${R(1)}`, { phone: "503-555-0199" }],
+  ["DELETE", `/v1/recipients/${R(9)}`],
+  ["POST", `/v1/recipients/${R(10)}/accounts`, { type: "paypal", emailAddress: "harper.lin.payouts@example.com" }],
+  ["PATCH", `/v1/recipients/${R(3)}/accounts/${A(4)}`, { primary: true }],
+  ["DELETE", `/v1/recipients/${R(3)}/accounts/${A(4)}`],
+  ["POST", "/v1/batches", { description: "Probe" }],
+  ["PATCH", `/v1/batches/${B(1)}`, { description: "Probe" }],
+  ["DELETE", `/v1/batches/${B(6)}`],
+  ["POST", `/v1/batches/${B(2)}/generate-quote`],
+  ["POST", `/v1/batches/${B(1)}/start-processing`],
+  ["POST", `/v1/batches/${B(1)}/payments`, payment],
+  ["PATCH", `/v1/batches/${B(1)}/payments/${P(1)}`, { memo: "Probe" }],
+  ["DELETE", `/v1/batches/${B(1)}/payments/${P(1)}`],
+];
+/** One request per read operation (10, covering both payments.get and balances.list paths). */
+const READS = [
+  ["GET", `/v1/recipients/${R(1)}`], ["GET", "/v1/recipients"], ["GET", `/v1/recipients/${R(3)}/accounts`],
+  ["GET", `/v1/recipients/${R(3)}/accounts/${A(3)}`], ["GET", `/v1/batches/${B(1)}`], ["GET", "/v1/batches"],
+  ["GET", `/v1/batches/${B(1)}/summary`], ["GET", `/v1/batches/${B(1)}/payments`], ["GET", `/v1/batches/${B(1)}/payments/${P(1)}`],
+  ["GET", `/v1/payments/${P(1)}`], ["GET", "/v1/balances"], ["GET", "/v1/balances/paymentrails"],
+];
+
+flow("read-only", async () => {
+  for (const [method, path] of READS) await api(method, path);
+  for (const [method, path, body] of WRITES) await fails(method, path, 403, "not_authorized", { body });
+  assert.equal((await api("GET", "/v1/batches")).meta.records, 11);
+  assert.equal((await api("GET", "/v1/recipients?status=archived")).meta.records, 1);
+});
+
+flow("invalid-key", async () => {
+  for (const [method, path, body] of [...READS, ...WRITES]) await fails(method, path, 401, "invalid_api_key", { body });
+});
+
+flow("fresh-install", async () => {
+  assert.equal((await api("GET", "/v1/recipients")).meta.records, 13);
+  assert.equal((await api("GET", "/v1/balances")).balances.length, 3);
+  const batch = (await api("POST", "/v1/batches", { body: { description: "Fresh install check" } })).batch;
+  assert.equal(batch.status, "open");
+  assert.equal(batch.amount, "0.00");
+  assert.match(batch.id, /^B-[0-9A-Za-z]{22}$/);
+});
+
+flow("denied", async () => {
+  await fails("GET", "/v1/recipients", 403, "not_authorized");
+  await fails("POST", "/v1/batches", 403, "not_authorized", { body: { description: "Denied" } });
+  await fails("POST", `/v1/batches/${B(1)}/start-processing`, 403, "not_authorized");
+});

package/test/flow-accounts.mjs

@@ -0,0 +1,63 @@
+// Recipient accounts flow: list, get, create per payout method, primary switching, immutable fields, disable.
+import { A, R, api, assert, fails, flow } from "./harness.mjs";
+
+flow("accounts", async () => {
+  await fails("POST", `/v1/recipients/${R(999)}/accounts`, 404, "not_found", { body: { type: "paypal", emailAddress: "nobody@example.com" } });
+  await fails("PATCH", `/v1/recipients/${R(3)}/accounts/${A(99)}`, 404, "not_found", { body: { primary: true } });
+  const listed = await api("GET", `/v1/recipients/${R(3)}/accounts`);
+  assert.deepEqual(listed.accounts.map((account) => account.id), [A(3), A(4)], "active accounts, primary first");
+  assert.equal(listed.accounts[0].primary, true);
+  assert.equal(listed.accounts[0].accountNum, "*****5521");
+  const disabled = (await api("GET", `/v1/recipients/${R(3)}/accounts/${A(5)}`)).account;
+  assert.equal(disabled.status, "disabled");
+  assert.equal(disabled.disabledAt, "2026-07-02T15:30:00.000Z");
+  await fails("GET", `/v1/recipients/${R(3)}/accounts/${A(1)}`, 404, "not_found");
+  await fails("GET", `/v1/recipients/${R(999)}/accounts`, 404, "not_found");
+
+  const bank = { type: "bank-transfer", currency: "USD", country: "US", accountHolderName: "Maya Castellanos", accountNum: "000123456789" };
+  await fails("POST", `/v1/recipients/${R(1)}/accounts`, 400, "empty_field", { field: "branchId", body: bank });
+  const created = (await api("POST", `/v1/recipients/${R(1)}/accounts`, { body: { ...bank, branchId: "000222333" } })).account;
+  assert.equal(created.accountNum, "*****6789");
+  assert.equal(created.primary, false, "an existing primary stays primary");
+  assert.equal(created.recipientAccountId, created.id);
+  assert.equal(created.routeType, "ach");
+
+  const promoted = (await api("PATCH", `/v1/recipients/${R(1)}/accounts/${created.id}`, { body: { primary: true } })).account;
+  assert.equal(promoted.primary, true);
+  const relisted = await api("GET", `/v1/recipients/${R(1)}/accounts`);
+  assert.deepEqual(relisted.accounts.map((account) => [account.id, account.primary]), [[created.id, true], [A(1), false]]);
+  await fails("PATCH", `/v1/recipients/${R(1)}/accounts/${created.id}`, 400, "invalid_field", { field: "accountNum", body: { accountNum: "999999999" } });
+  await fails("PATCH", `/v1/recipients/${R(1)}/accounts/${created.id}`, 400, "invalid_field", { field: "primary", body: { primary: false } });
+  await fails("PATCH", `/v1/recipients/${R(1)}/accounts/${created.id}`, 400, "invalid_field", { field: "emailAddress", body: { emailAddress: "x@example.com" } });
+  await fails("PATCH", `/v1/recipients/${R(1)}/accounts/${created.id}`, 400, "empty_field", { field: "body", body: {} });
+  const renamed = (await api("PATCH", `/v1/recipients/${R(1)}/accounts/${created.id}`, { body: { accountHolderName: "Maya R. Castellanos" } })).account;
+  assert.equal(renamed.accountHolderName, "Maya R. Castellanos");
+
+  await fails("POST", `/v1/recipients/${R(1)}/accounts`, 400, "invalid_field", { field: "type", body: { type: "debit-card" } });
+  const mailing = { name: "Maya Castellanos", street1: "1 Rue Principale", city: "Québec", region: "QC", postal: "G1R 4P5", country: "CA" };
+  await fails("POST", `/v1/recipients/${R(1)}/accounts`, 400, "invalid_field", { field: "mailing.country", body: { type: "check", mailing } });
+  await fails("POST", `/v1/recipients/${R(11)}/accounts`, 400, "invalid_status", { body: { type: "paypal", emailAddress: "old.jordan@example.com" } });
+  await fails("POST", `/v1/recipients/${R(5)}/accounts`, 400, "invalid_field", { field: "iban", body: { type: "bank-transfer", currency: "EUR", country: "DE", accountHolderName: "L W", iban: "FR7630006000011234567890189" } });
+  const iban = (await api("POST", `/v1/recipients/${R(5)}/accounts`, { body: { type: "bank-transfer", currency: "EUR", country: "DE", accountHolderName: "Lukasz Wisniewski", iban: "DE89 3704 0044 0532 0130 00" } })).account;
+  assert.equal(iban.iban, "*****3000");
+  assert.equal(iban.accountNum, null);
+  assert.equal(iban.routeType, "sepa");
+
+  // Harper Lin has an address but no payout method: adding Venmo makes the recipient active.
+  const venmo = (await api("POST", `/v1/recipients/${R(10)}/accounts`, { body: { type: "venmo", phoneNumber: "(206) 555-0110" } })).account;
+  assert.equal(venmo.primary, true);
+  assert.equal(venmo.phoneNumber, "2065550110");
+  assert.equal((await api("GET", `/v1/recipients/${R(10)}`)).recipient.status, "active");
+
+  // Removing Maya's primary leaves no primary: the recipient becomes incomplete until another account is promoted.
+  assert.deepEqual(await api("DELETE", `/v1/recipients/${R(1)}/accounts/${created.id}`), { ok: true });
+  assert.equal((await api("GET", `/v1/recipients/${R(1)}`)).recipient.status, "incomplete");
+  await fails("DELETE", `/v1/recipients/${R(1)}/accounts/${created.id}`, 400, "invalid_status");
+  await fails("PATCH", `/v1/recipients/${R(1)}/accounts/${created.id}`, 400, "invalid_status", { body: { accountHolderName: "Nobody" } });
+  await fails("DELETE", `/v1/recipients/${R(1)}/accounts/${A(1)}`, 400, "invalid_status");
+  await fails("DELETE", `/v1/recipients/${R(1)}/accounts/${A(99)}`, 404, "not_found");
+  const repromoted = (await api("PATCH", `/v1/recipients/${R(1)}/accounts/${A(1)}`, { body: { primary: true } })).account;
+  assert.equal(repromoted.status, "primary");
+  assert.equal((await api("GET", `/v1/recipients/${R(1)}`)).recipient.status, "active");
+  assert.equal((await api("GET", `/v1/recipients/${R(1)}/accounts/${created.id}`)).account.status, "disabled");
+});

package/test/flow-batches.mjs

@@ -0,0 +1,107 @@
+// Batch lifecycle flow: batches and payments CRUD, summary, quote, processing, terminal-state refusals, balances.
+import { B, P, R, api, assert, fails, flow } from "./harness.mjs";
+
+flow("batch-lifecycle", async () => {
+  // Declared errors of refused writes (nothing changes).
+  await fails("POST", "/v1/batches", 400, "empty_field", { field: "payments[0].recipient", body: { payments: [{ amount: "5.00", currency: "USD" }] } });
+  await fails("POST", "/v1/batches", 404, "not_found", { field: "payments[0].recipient", body: { payments: [{ recipient: { id: R(99) }, amount: "5.00", currency: "USD" }] } });
+  await fails("POST", "/v1/batches", 400, "invalid_status", { field: "payments[0].recipient", body: { payments: [{ recipient: { id: R(12) }, amount: "5.00", currency: "USD" }] } });
+  await fails("PATCH", `/v1/batches/${B(99)}`, 404, "not_found", { body: { description: "x" } });
+  await fails("DELETE", `/v1/batches/${B(99)}`, 404, "not_found");
+  await fails("POST", `/v1/batches/${B(99)}/generate-quote`, 404, "not_found");
+  await fails("GET", `/v1/batches/${B(1)}/payments?status=bogus`, 400, "invalid_field", { field: "status" });
+  await fails("PATCH", `/v1/batches/${B(1)}/payments/${P(1)}`, 400, "empty_field", { field: "body", body: {} });
+  await fails("PATCH", `/v1/batches/${B(1)}/payments/${P(99)}`, 404, "not_found", { body: { memo: "x" } });
+  await fails("DELETE", `/v1/batches/${B(1)}/payments/${P(99)}`, 404, "not_found");
+  assert.equal((await api("GET", "/v1/batches")).meta.records, 11);
+  const listed = await api("GET", "/v1/batches");
+  assert.equal(listed.batches.length, 10);
+  assert.deepEqual(listed.meta, { page: 1, pages: 2, records: 11 });
+  assert.equal((await api("GET", "/v1/batches?status=open")).meta.records, 6);
+  assert.deepEqual((await api("GET", "/v1/batches?search=editors")).batches.map((batch) => batch.id), [B(2)]);
+  const byAmount = await api("GET", "/v1/batches?orderBy=amount&sortBy=desc&pageSize=1");
+  assert.equal(byAmount.batches[0].id, B(3));
+  await fails("GET", "/v1/batches?status=bogus", 400, "invalid_field", { field: "status" });
+
+  const created = (await api("POST", "/v1/batches", {
+    body: {
+      description: "Freelance fixes", tags: ["adhoc"],
+      payments: [
+        { recipient: { email: "priya.raman@example.com" }, amount: "25.00", currency: "USD", memo: "Thumbnail" },
+        { recipient: { referenceId: "CR-1004" }, amount: "100.00", currency: "GBP", memo: "Captions" },
+      ],
+    },
+  })).batch;
+  assert.equal(created.status, "open");
+  assert.equal(created.currency, "USD");
+  assert.equal(created.totalPayments, 2);
+  assert.equal(created.amount, "154.04", "25.00 + (100.00 GBP / 0.781 + 1.00 fee)");
+  const reread = (await api("GET", `/v1/batches/${created.id}`)).batch;
+  assert.deepEqual([reread.status, reread.amount, reread.totalPayments, reread.description], ["open", "154.04", 2, "Freelance fixes"]);
+  assert.equal((await api("GET", "/v1/batches")).meta.records, 12, "the new batch is listed");
+  await fails("POST", "/v1/batches", 400, "invalid_field", { field: "currency", body: { currency: "XYZ" } });
+  await fails("GET", `/v1/batches/${B(99)}`, 404, "not_found");
+
+  const payments = await api("GET", `/v1/batches/${created.id}/payments`);
+  assert.equal(payments.payments.length, 2);
+  const [thumb, captions] = payments.payments;
+  assert.equal(captions.targetAmount, "100.00");
+  assert.equal(captions.targetCurrency, "GBP");
+  assert.equal(captions.exchangeRate, "0.781000");
+  await fails("POST", `/v1/batches/${created.id}/payments`, 404, "not_found", { field: "recipient", body: { recipient: { id: R(99) }, amount: "5.00", currency: "USD" } });
+  await fails("POST", `/v1/batches/${created.id}/payments`, 400, "invalid_status", { field: "recipient", body: { recipient: { id: R(12) }, amount: "5.00", currency: "USD" } });
+  await fails("POST", `/v1/batches/${created.id}/payments`, 400, "invalid_field", { field: "amount", body: { recipient: { id: R(1) }, amount: "10.5", currency: "USD" } });
+  await fails("POST", `/v1/batches/${created.id}/payments`, 400, "empty_field", { field: "recipient", body: { amount: "10.00", currency: "USD" } });
+  const added = (await api("POST", `/v1/batches/${created.id}/payments`, { body: { recipient: { id: R(7) }, amount: "12.00", currency: "USD", externalId: "FIX-3", category: "services" } })).payment;
+  assert.equal(added.payoutMethod, "venmo");
+  assert.equal(added.recipientFees, "0.75");
+  await fails("POST", `/v1/batches/${created.id}/payments`, 400, "invalid_field", { field: "externalId", body: { recipient: { id: R(1) }, amount: "10.00", currency: "USD", externalId: "FIX-3" } });
+
+  const patched = (await api("PATCH", `/v1/batches/${created.id}/payments/${thumb.id}`, { body: { memo: "Thumbnail set", coverFees: true } })).payment;
+  assert.equal(patched.memo, "Thumbnail set");
+  assert.equal(patched.merchantFees, "1.00");
+  await fails("PATCH", `/v1/batches/${created.id}/payments/${thumb.id}`, 400, "invalid_field", { field: "recipient", body: { recipient: { id: R(1) } } });
+  assert.equal((await api("GET", `/v1/batches/${created.id}/payments/${thumb.id}`)).payment.memo, "Thumbnail set");
+  const direct = (await api("GET", `/v1/payments/${captions.id}`)).payment;
+  assert.equal(direct.batch.id, created.id);
+  assert.equal(direct.recipient.id, R(4));
+  await fails("GET", `/v1/batches/${B(1)}/payments/${captions.id}`, 404, "not_found");
+  await fails("GET", `/v1/batches/${B(99)}/payments`, 404, "not_found");
+  assert.equal((await api("GET", `/v1/batches/${created.id}/payments?search=captions`)).meta.records, 1);
+  assert.deepEqual(await api("DELETE", `/v1/batches/${created.id}/payments/${captions.id}`), { ok: true });
+  await fails("GET", `/v1/payments/${captions.id}`, 404, "not_found");
+  const updated = (await api("PATCH", `/v1/batches/${created.id}`, { body: { description: "Freelance fixes (September)" } })).batch;
+  assert.equal(updated.totalPayments, 2);
+  assert.equal(updated.amount, "37.00");
+  await fails("PATCH", `/v1/batches/${created.id}`, 400, "invalid_field", { field: "currency", body: { currency: "CAD" } });
+
+  const summary = (await api("GET", `/v1/batches/${B(1)}/summary`)).batchSummary;
+  assert.deepEqual(summary.detail.paypal, { count: 1, totalFees: "1.00", merchantFees: "1.00", debitAmount: "441.00", sendingAmount: "440.00", totalWithheld: "0.00" });
+  assert.deepEqual(summary.total, { count: 3, totalFees: "2.75", merchantFees: "1.00", debitAmount: "1241.00", sendingAmount: "1240.00", totalWithheld: "0.00" });
+  await fails("GET", `/v1/batches/${B(99)}/summary`, 404, "not_found");
+
+  const quoted = (await api("POST", `/v1/batches/${B(2)}/generate-quote`, { raw: "{}", headers: { "content-type": "application/json" } })).batch;
+  assert.equal(quoted.quoteExpiredAt, "2026-09-15T15:30:00.000Z");
+  const fx = (await api("GET", `/v1/batches/${B(2)}/payments`)).payments;
+  assert.deepEqual(fx.map((payment) => [payment.targetCurrency, payment.targetAmount]), [["GBP", "624.02"], ["EUR", "591.89"]]);
+
+  const processed = (await api("POST", `/v1/batches/${B(1)}/start-processing`)).batch;
+  assert.equal(processed.status, "complete");
+  assert.equal(processed.sentAt, "2026-09-15T14:00:00.000Z");
+  const settled = (await api("GET", `/v1/batches/${B(1)}/payments?status=processed`)).payments;
+  assert.equal(settled.length, 3);
+  const balances = await api("GET", "/v1/balances");
+  assert.equal(balances.balances[0].amount, "17179.55");
+  assert.equal(balances.serverTime, "2026-09-15T14:00:00.000Z");
+  assert.equal((await api("GET", "/v1/balances/paypal")).balances.length, 1);
+  await fails("GET", "/v1/balances/venmo", 400, "invalid_field", { field: "kind" });
+
+  await fails("PATCH", `/v1/batches/${B(1)}/payments/${P(1)}`, 400, "invalid_status", { body: { memo: "late" } });
+  await fails("DELETE", `/v1/batches/${B(7)}/payments/${P(11)}`, 400, "invalid_status");
+  await fails("PATCH", `/v1/batches/${B(7)}`, 400, "invalid_status", { body: { description: "August" } });
+  await fails("DELETE", `/v1/batches/${B(1)}`, 400, "invalid_status");
+  await fails("POST", `/v1/batches/${B(1)}/generate-quote`, 406, "invalid_status");
+  await fails("POST", `/v1/batches/${B(1)}/start-processing`, 409, "invalid_status");
+  assert.deepEqual(await api("DELETE", `/v1/batches/${B(6)}`), { ok: true });
+  await fails("GET", `/v1/batches/${B(6)}`, 404, "not_found");
+});

package/test/flow-faults.mjs

@@ -0,0 +1,58 @@
+// Fault flows: rate limiting, payout partner outage, lost processing response, and the scan bound.
+import { A, B, P, R, api, assert, fails, flow } from "./harness.mjs";
+
+flow("rate-limited", async () => {
+  await fails("GET", "/v1/recipients", 429, "rate_limit_exceeded");
+  await fails("GET", "/v1/batches?status=open", 429, "rate_limit_exceeded");
+  await fails("GET", `/v1/batches/${B(1)}/payments`, 429, "rate_limit_exceeded");
+  assert.equal((await api("GET", `/v1/recipients/${R(1)}`)).recipient.id, R(1), "retrieves are not rate limited");
+});
+
+flow("partner-outage", async () => {
+  await fails("POST", `/v1/recipients/${R(10)}/accounts`, 500, "partner_integration_error", { body: { type: "paypal", emailAddress: "harper.lin.payouts@example.com" } });
+  assert.equal((await api("GET", `/v1/recipients/${R(10)}`)).recipient.accounts.length, 0, "no account was created");
+  await fails("POST", `/v1/batches/${B(2)}/generate-quote`, 500, "partner_integration_error");
+  assert.equal((await api("GET", `/v1/batches/${B(2)}`)).batch.quoteExpiredAt, "2026-09-15T12:30:00.000Z");
+});
+
+flow("response-lost", async () => {
+  await fails("POST", `/v1/batches/${B(1)}/start-processing`, 500, "internal_server_error");
+  // The response was lost, but the payout happened: check before retrying.
+  const batch = (await api("GET", `/v1/batches/${B(1)}`)).batch;
+  assert.equal(batch.status, "complete");
+  const balances = await api("GET", "/v1/balances");
+  assert.equal(balances.balances[0].amount, "17179.55");
+  // A careless retry is refused because the batch is no longer open; nothing is paid twice.
+  const retry = await api("POST", `/v1/batches/${B(1)}/start-processing`, { status: RETRY_STATUS });
+  assert.equal(retry.ok, false);
+  assert.equal((await api("GET", "/v1/balances")).balances[0].amount, "17179.55");
+});
+
+const RETRY_STATUS = 409;
+
+flow("tight-limits", async () => {
+  const bound = (method, path, body) => fails(method, path, 500, "internal_server_error", { body });
+  await bound("POST", "/v1/recipients", { type: "individual", email: "bound.probe@example.com", firstName: "Bound", lastName: "Probe" });
+  await bound("GET", `/v1/recipients/${R(3)}`);
+  await bound("PATCH", `/v1/recipients/${R(1)}`, { email: "maya.c@example.com" });
+  await bound("DELETE", `/v1/recipients/${R(2)}`);
+  await bound("GET", "/v1/recipients");
+  await bound("POST", `/v1/recipients/${R(3)}/accounts`, { type: "paypal", emailAddress: "etienne.second@example.com" });
+  await bound("GET", `/v1/recipients/${R(3)}/accounts`);
+  await bound("PATCH", `/v1/recipients/${R(3)}/accounts/${A(4)}`, { primary: true });
+  await bound("DELETE", `/v1/recipients/${R(3)}/accounts/${A(4)}`);
+  await bound("POST", "/v1/batches", { payments: [{ recipient: { email: "maya.castellanos@example.com" }, amount: "10.00", currency: "USD" }] });
+  await bound("GET", `/v1/batches/${B(1)}`);
+  await bound("PATCH", `/v1/batches/${B(1)}`, { description: "bound" });
+  await bound("DELETE", `/v1/batches/${B(1)}`);
+  await bound("GET", "/v1/batches");
+  await bound("POST", `/v1/batches/${B(1)}/generate-quote`);
+  await bound("POST", `/v1/batches/${B(1)}/start-processing`);
+  await bound("GET", `/v1/batches/${B(1)}/summary`);
+  await bound("POST", `/v1/batches/${B(1)}/payments`, { recipient: { id: R(6) }, amount: "5.00", currency: "USD" });
+  await bound("GET", `/v1/batches/${B(1)}/payments`);
+  await bound("PATCH", `/v1/batches/${B(1)}/payments/${P(1)}`, { externalId: "BOUND-1" });
+  await bound("GET", "/v1/balances");
+  // Reads that need no scan still work.
+  assert.equal((await api("GET", `/v1/recipients/${R(1)}/accounts/${A(1)}`)).account.id, A(1));
+});

package/test/flow-processing.mjs

@@ -0,0 +1,41 @@
+// Processing rules flow: expired quote, insufficient funds, route minimum, empty batch, per-payment failures.
+import { B, api, assert, fails, flow } from "./harness.mjs";
+
+const balance = async () => (await api("GET", "/v1/balances/paymentrails")).balances.find((row) => row.currency === "USD").amount;
+
+flow("processing-rules", async () => {
+  await fails("POST", `/v1/batches/${B(2)}/start-processing`, 400, "expired_quote");
+  assert.equal((await api("GET", `/v1/batches/${B(2)}`)).batch.status, "open", "a refused call changes nothing");
+  await api("POST", `/v1/batches/${B(2)}/generate-quote`);
+  assert.equal((await api("POST", `/v1/batches/${B(2)}/start-processing`)).batch.status, "complete");
+  assert.equal(await balance(), "16970.55");
+
+  await fails("POST", `/v1/batches/${B(3)}/start-processing`, 400, "non_sufficient_funds");
+  assert.equal(await balance(), "16970.55");
+  await fails("POST", `/v1/batches/${B(5)}/start-processing`, 400, "invalid_field", { field: "amount" });
+  await fails("POST", `/v1/batches/${B(6)}/start-processing`, 409, "invalid_status");
+  await fails("POST", `/v1/batches/${B(99)}/start-processing`, 404, "not_found");
+
+  const mixed = (await api("POST", `/v1/batches/${B(4)}/start-processing`)).batch;
+  assert.equal(mixed.status, "complete");
+  const results = (await api("GET", `/v1/batches/${B(4)}/payments`)).payments;
+  assert.deepEqual(results.map((payment) => [payment.status, payment.failureMessage]), [["processed", null], ["failed", "Recipient is not active"]]);
+  assert.equal(await balance(), "16820.55");
+
+  // A recipient that becomes incomplete after the payment was added: the payment fails and the batch fails.
+  const kai = (await api("POST", "/v1/recipients", {
+    body: {
+      type: "individual", email: "kai.moreno@example.com", firstName: "Kai", lastName: "Moreno",
+      address: { street1: "12 Ocean Ave", city: "San Diego", region: "CA", postalCode: "92101", country: "US" },
+      accounts: [{ type: "venmo", phoneNumber: "619-555-0142" }],
+    },
+  })).recipient;
+  assert.equal(kai.status, "active");
+  const batch = (await api("POST", "/v1/batches", { body: { description: "Kai one-off", payments: [{ recipient: { id: kai.id }, amount: "40.00", currency: "USD" }] } })).batch;
+  const incomplete = (await api("PATCH", `/v1/recipients/${kai.id}`, { body: { address: { street1: "" } } })).recipient;
+  assert.equal(incomplete.status, "incomplete");
+  const failed = (await api("POST", `/v1/batches/${batch.id}/start-processing`)).batch;
+  assert.equal(failed.status, "failed");
+  assert.equal(failed.completedAt, "2026-09-15T14:00:00.000Z");
+  assert.equal(await balance(), "16820.55", "failed payments debit nothing");
+});

package/test/flow-recipients.mjs

@@ -0,0 +1,93 @@
+// Recipients flow: list paging, search, filters, ordering, validation, create, update, archive and restore.
+import { B, R, api, assert, fails, flow } from "./harness.mjs";
+
+flow("recipients", async () => {
+  const first = await api("GET", "/v1/recipients");
+  assert.equal(first.recipients.length, 10);
+  assert.deepEqual(first.meta, { page: 1, pages: 2, records: 13 });
+  assert.ok(first.recipients.every((recipient) => recipient.status !== "archived"), "archived recipients are hidden by default");
+  const second = await api("GET", "/v1/recipients?page=2", { scheme: "Bearer" });
+  assert.equal(second.recipients.length, 3);
+  const ids = new Set([...first.recipients, ...second.recipients].map((recipient) => recipient.id));
+  assert.equal(ids.size, 13, "pages do not overlap");
+  const beyond = await api("GET", "/v1/recipients?page=99");
+  assert.deepEqual(beyond.recipients, []);
+  assert.deepEqual(beyond.meta, { page: 99, pages: 2, records: 13 });
+
+  const quarry = await api("GET", "/v1/recipients?search=QUARRY");
+  assert.deepEqual(quarry.recipients.map((recipient) => recipient.id), [R(2)]);
+  const archived = await api("GET", "/v1/recipients?status=archived");
+  assert.deepEqual(archived.recipients.map((recipient) => recipient.id), [R(11)]);
+  const countries = await api("GET", "/v1/recipients?country=CA,GB&orderBy=name&sortBy=asc");
+  assert.deepEqual(countries.recipients.map((recipient) => recipient.id), [R(3), R(4)].sort((a, b) => (a === R(3) ? 1 : -1)));
+  const tagged = await api("GET", "/v1/recipients?tags=editor,video");
+  assert.deepEqual(tagged.recipients.map((recipient) => recipient.id), [R(6)]);
+  const byName = await api("GET", "/v1/recipients?orderBy=name&sortBy=asc&pageSize=1");
+  assert.equal(byName.recipients[0].name, "Estudio Nopal S.A. de C.V.");
+  const paypal = await api("GET", "/v1/recipients?payoutMethod=paypal&currency=usd");
+  assert.deepEqual(paypal.recipients.map((recipient) => recipient.id).sort(), [R(6), R(13)].sort());
+  await fails("GET", "/v1/recipients?pageSize=0", 400, "invalid_field", { field: "pageSize" });
+  await fails("GET", "/v1/recipients?pageSize=abc", 400, "invalid_field", { field: "pageSize" });
+  await fails("GET", "/v1/recipients?sortBy=up", 400, "invalid_field", { field: "sortBy" });
+  await fails("GET", "/v1/recipients?startDate=2026-01-01", 400, "invalid_field", { field: "startDate" });
+  await fails("GET", "/v1/recipients?search=%FF", 400, "invalid_field", { field: "search" });
+
+  const maya = (await api("GET", `/v1/recipients/${R(1)}`)).recipient;
+  assert.equal(maya.payoutMethod, "bank-transfer");
+  assert.equal(maya.routeType, "ach");
+  assert.equal(maya.primaryCurrency, "USD");
+  assert.equal(maya.accounts[0].accountNum, "*****2847");
+  await fails("GET", `/v1/recipients/${R(999)}`, 404, "not_found");
+  await fails("GET", "/v1/recipients/R-nope", 404, "not_found");
+
+  await fails("POST", "/v1/recipients", 400, "empty_field", { field: "firstName", body: { type: "individual", email: "rowan.pike@example.com", lastName: "Pike" } });
+  await fails("POST", "/v1/recipients", 400, "invalid_field", { field: "email", body: { type: "individual", email: "MAYA.castellanos@example.com", firstName: "M", lastName: "C" } });
+  await fails("POST", "/v1/recipients", 400, "invalid_field", { field: "email", body: { type: "individual", email: "not-an-email", firstName: "M", lastName: "C" } });
+
+  const studio = (await api("POST", "/v1/recipients", {
+    body: {
+      type: "business", email: "payables@northlantern.example.com", name: "North Lantern Studio", referenceId: "CR-2002",
+      address: { street1: "400 Mill Rd", city: "Burlington", region: "VT", postalCode: "05401", country: "US" },
+      accounts: [{ type: "check", mailing: { name: "North Lantern Studio", street1: "400 Mill Rd", city: "Burlington", region: "VT", postal: "05401", country: "US" } }],
+    },
+  })).recipient;
+  assert.equal(studio.status, "active");
+  assert.equal(studio.accounts.length, 1);
+  assert.equal(studio.accounts[0].primary, true);
+  assert.equal(studio.payoutMethod, "check");
+
+  const rowanBody = { type: "individual", email: "rowan.pike@example.com", firstName: "Rowan", lastName: "Pike", referenceId: "CR-2001", tags: ["writer"] };
+  const rowanKey = { "idempotency-key": "conformance-rowan-1" };
+  const rowan = (await api("POST", "/v1/recipients", { body: rowanBody, headers: rowanKey })).recipient;
+  assert.equal(rowan.status, "incomplete");
+  // Idempotency-Key (Firedrill addition): same key + same body replays the recorded recipient; a different body or an
+  // unsupported endpoint answers Trolley's invalid_field on the header; an over-long key is refused before dispatch.
+  const replay = (await api("POST", "/v1/recipients", { body: rowanBody, headers: rowanKey })).recipient;
+  assert.equal(replay.id, rowan.id, "same key and body replays the recorded outcome");
+  await fails("POST", "/v1/recipients", 400, "invalid_field", { field: "Idempotency-Key", body: { ...rowanBody, lastName: "Pyke" }, headers: rowanKey });
+  await fails("GET", "/v1/recipients?pageSize=1", 400, "invalid_field", { field: "Idempotency-Key", headers: rowanKey });
+  await fails("POST", "/v1/recipients", 400, "invalid_field", { field: "Idempotency-Key", body: rowanBody, headers: { "idempotency-key": "k".repeat(256) } });
+  const afterKeys = await api("GET", "/v1/recipients?search=rowan.pike");
+  assert.deepEqual(afterKeys.recipients.map((recipient) => recipient.id), [rowan.id], "refused key reuse created nothing");
+  assert.equal(rowan.name, "Rowan Pike");
+  const addressed = (await api("PATCH", `/v1/recipients/${rowan.id}`, { body: { address: { street1: "8 Quay St", city: "Halifax", region: "NS", postalCode: "B3J 1A1", country: "CA" }, phone: "902-555-0120" } })).recipient;
+  assert.equal(addressed.status, "incomplete", "an address without a payout method stays incomplete");
+  assert.equal(addressed.address.city, "Halifax");
+  const fetched = (await api("GET", `/v1/recipients/${rowan.id}`)).recipient;
+  assert.equal(fetched.phone, "902-555-0120");
+  await fails("PATCH", `/v1/recipients/${rowan.id}`, 400, "invalid_field", { field: "type", body: { type: "business" } });
+  await fails("PATCH", `/v1/recipients/${rowan.id}`, 400, "empty_field", { field: "email", body: { email: "" } });
+  await fails("PATCH", `/v1/recipients/${rowan.id}`, 400, "invalid_status", { body: { status: "active" } });
+  await fails("PATCH", `/v1/recipients/${rowan.id}`, 400, "invalid_field", { body: { id: "R-0000000000000000000001" } });
+  await fails("PATCH", `/v1/recipients/${R(999)}`, 404, "not_found", { body: { phone: "1" } });
+
+  await fails("DELETE", `/v1/recipients/${R(1)}`, 400, "invalid_status");
+  await fails("DELETE", `/v1/recipients/${R(999)}`, 404, "not_found");
+  assert.deepEqual(await api("DELETE", `/v1/recipients/${rowan.id}`), { ok: true });
+  assert.equal((await api("GET", `/v1/recipients/${rowan.id}`)).recipient.status, "archived");
+  assert.equal((await api("GET", "/v1/recipients")).meta.records, 14);
+  const restored = (await api("PATCH", `/v1/recipients/${rowan.id}`, { body: { status: "active" } })).recipient;
+  assert.equal(restored.status, "incomplete");
+  assert.equal((await api("GET", "/v1/recipients?search=CR-200")).meta.records, 2);
+  assert.ok(B(1));
+});

package/test/harness.mjs

@@ -0,0 +1,87 @@
+// Conformance harness: Trolley-shaped HTTP calls against `firedrill serve`, Node built-ins only.
+import assert from "node:assert/strict";
+
+export const HTTP = process.env.FIREDRILL_HTTP_URL;
+export const TOKEN = process.env.FIREDRILL_HTTP_TOKEN;
+assert.ok(HTTP && TOKEN, "the http binding (FIREDRILL_HTTP_URL, FIREDRILL_HTTP_TOKEN) is required");
+
+const ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+function renderId(prefix, sequence) {
+  let n = sequence;
+  let out = "";
+  while (n > 0) {
+    out = ALPHABET[n % 62] + out;
+    n = Math.floor(n / 62);
+  }
+  return `${prefix}-${out.padStart(22, "0")}`;
+}
+// Starter ids (see starter.json): recipients 1–14, accounts 101–113, batches 201–211, payments 301–322.
+export const R = (n) => renderId("R", n);
+export const A = (n) => renderId("A", 100 + n);
+export const B = (n) => renderId("B", 200 + n);
+export const P = (n) => renderId("P", 300 + n);
+export const MERCHANT = "M-4Lk9Qx2Rb7Tn3Vw8Yz1Ca6";
+export { assert };
+
+/** Trolley-shaped request; asserts the status and returns the parsed JSON body. */
+export async function api(method, path, { body, status = 200, scheme = "prsign", headers = {}, raw } = {}) {
+  const init = { method, headers: { authorization: `${scheme} ${TOKEN}`, ...headers } };
+  if (raw !== undefined) {
+    init.body = raw;
+  } else if (body !== undefined) {
+    init.headers["content-type"] = "application/json";
+    init.body = JSON.stringify(body);
+  }
+  const response = await fetch(`${HTTP}${path}`, init);
+  const text = await response.text();
+  let json;
+  try {
+    json = text.length > 0 ? JSON.parse(text) : undefined;
+  } catch {
+    json = undefined;
+  }
+  if (response.status !== status) {
+    throw new Error(`${method} ${path}: expected HTTP ${status}, got ${response.status}: ${text.slice(0, 800)}`);
+  }
+  if (status === 200) assert.equal(json?.ok, true, `${method} ${path}: success body must carry ok:true`);
+  return json;
+}
+
+/** Asserts a Trolley error envelope with `code` (and `field` when given). */
+export async function fails(method, path, status, code, { body, field, raw, headers } = {}) {
+  const json = await api(method, path, { body, status, raw, headers });
+  assert.equal(json?.ok, false, `${method} ${path}: error body must carry ok:false`);
+  assert.ok(Array.isArray(json.errors) && json.errors.length >= 1, `${method} ${path}: errors array expected`);
+  assert.equal(json.errors[0].code, code, `${method} ${path}: error code ${JSON.stringify(json.errors)}`);
+  assert.equal(typeof json.errors[0].message, "string");
+  if (field !== undefined) assert.equal(json.errors[0].field, field, `${method} ${path}: error field ${JSON.stringify(json.errors)}`);
+  return json.errors[0];
+}
+
+/** Canonical operation call through the generic Firedrill HTTP binding. */
+export async function operation(operationId, args = {}) {
+  const response = await fetch(`${HTTP}/v1/operations/trolley/${operationId}`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${TOKEN}`, "content-type": "application/json" },
+    body: JSON.stringify({ arguments: args }),
+  });
+  const json = await response.json();
+  assert.ok(json && json.outcome, `canonical ${operationId}: outcome expected`);
+  return json.outcome;
+}
+
+const flows = new Map();
+export function flow(name, run) {
+  flows.set(name, run);
+}
+
+export async function main() {
+  let task = "";
+  for await (const chunk of process.stdin) task += chunk;
+  const instruction = String(JSON.parse(task).instruction ?? "");
+  const selected = [...flows.keys()].find((name) => instruction.includes(`the ${name} conformance flow`));
+  if (selected === undefined) throw new Error(`Unknown drill instruction: ${instruction}`);
+  await flows.get(selected)();
+  // The target protocol reads exactly one JSON value from stdout; diagnostics go to stderr.
+  process.stdout.write(JSON.stringify({ completed: true, flow: selected }));
+}