@mandateops/audit 0.2.0 → 0.4.2

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import type { CapacityReading, HistoryReading, ReadingProfile } from "./reading.js";
 import type { ProviderWire, StagedWire } from "./providers/index.js";
-export { bridge, circleMint, adyen, airwallex, checkout, dwolla, fireblocks, flutterwave, modernTreasury, molliePayouts, paypal, paystack, peach, razorpayx, revolut, stitch, stripePayouts, stripeTransfers, wise, } from "./providers/index.js";
-export type { CheckoutTerms, CurrencyTerms, BridgeTerms, FireblocksTerms, LedgerTerms, MollieTerms, OwnAccountTerms, ProviderWire, SourcedTerms, StagedWire, TermDefaults, WiseRoutes, WiseTerms, } from "./providers/index.js";
+export * from "./providers/index.js";
 export { parseCapacityReading, parseHistoryReading, ReadingError, requireHistoryFits, } from "./reading.js";
 export type { AttemptEnd, AttemptResult, CapacityReading, Flow, HistoryEvent, HistoryReading, Instruction, MinorUnits, Payout, PayoutState, ReadingProfile, HistoryConsistency, CapacityConsistency, } from "./reading.js";
 /**
@@ -181,6 +180,12 @@ export type SealedResult = Readonly<{
         reasons?: readonly unknown[];
     }>;
     record_published: boolean;
+    /**
+     * Why the run cannot pass whatever its properties say, such as
+     * `overlap_not_established` for a race the host could not show in flight
+     * together, or `capacity_exceeded` for competitors accepted past their limit.
+     */
+    reason?: string;
 }>;
 /** A deployment that may have outlived its run, and what removes it. */
 export type TeardownFailure = Readonly<{
@@ -207,12 +212,28 @@ type Credentials = Readonly<Record<ServiceRole, string>>;
  * The session protocol this SDK speaks. The host announces its own when
  * ready; the two must match, as they do for an SDK shipped with its CLI.
  */
-export declare const SESSION_PROTOCOL = 2;
+export declare const SESSION_PROTOCOL = 3;
 /** Why a host of another protocol is refused, and how to fix it. */
 export declare function protocolMismatch(announced: number | undefined): string;
 /** A sealed result, checked before anything reads it. */
 export declare function parseResult(value: unknown): SealedResult;
 export type LossMode = "cut_connection" | "hold_response" | "crash_process";
+/** What the host's gate saw of one race. */
+export type RaceReport = Readonly<{
+    parties: number;
+    /** Every party arrived and all were in flight at the backend at once. */
+    overlap_established: boolean;
+    /** Why overlap was not established, when it was not. */
+    reason?: string;
+}>;
+/** Each party's own result, and whether the race really overlapped. */
+export type RaceResult<T> = Readonly<{
+    settled: readonly PromiseSettledResult<T>[];
+    report: RaceReport;
+}>;
+/** Fewest and most parties one race holds; the host enforces the same. */
+export declare const MIN_RACE_PARTIES = 2;
+export declare const MAX_RACE_PARTIES = 8;
 export type Fixture = Readonly<{
     /** The deployed service's base URL. Optional convenience for `fetch`. */
     app: string;
@@ -220,6 +241,26 @@ export type Fixture = Readonly<{
     credentials: Credentials;
     provider: Readonly<{
         expectPayment: (expected: ExpectedPayment) => Promise<Authorised>;
+        /**
+         * Declares payments that compete for the one capacity limit, in place of
+         * `expectPayment`. Bind each one the backend accepted; the first bound is
+         * the payout judged, and the accepted ones together must stay within
+         * `shared.limitMinor`. `capacityLimitMinor` stays the limit of one
+         * payout's own capacity readings. A competition must be raced through `concurrency.race`.
+         */
+        expectCompetingPayments: (expected: readonly ExpectedPayment[], shared: Readonly<{
+            limitMinor: string;
+        }>) => Promise<readonly Authorised[]>;
+    }>;
+    concurrency: Readonly<{
+        /**
+         * Runs `parties` submissions at once through a host gate in front of the
+         * backend: each `submit` gets the gate's base URL in place of `app`. The
+         * gate releases the requests only when all have arrived, so they meet at
+         * the backend's reservation boundary together. A race the gate cannot
+         * show overlapped does not pass.
+         */
+        race: <T>(parties: number, submit: (url: string, party: number) => Promise<T>) => Promise<RaceResult<T>>;
     }>;
     faults: Readonly<{
         /**

package/dist/index.js

@@ -13,7 +13,8 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { parseCapacityReading, parseHistoryReading, requireHistoryFits, } from "./reading.js";
-export { bridge, circleMint, adyen, airwallex, checkout, dwolla, fireblocks, flutterwave, modernTreasury, molliePayouts, paypal, paystack, peach, razorpayx, revolut, stitch, stripePayouts, stripeTransfers, wise, } from "./providers/index.js";
+// Every provider format and its types, from the one list that names them.
+export * from "./providers/index.js";
 export { parseCapacityReading, parseHistoryReading, ReadingError, requireHistoryFits, } from "./reading.js";
 const MINOR_UNITS = /^[1-9][0-9]*$/;
 /**
@@ -75,7 +76,7 @@ const isRecord = (value) => typeof value === "object" && value !== null && !Arra
  * The session protocol this SDK speaks. The host announces its own when
  * ready; the two must match, as they do for an SDK shipped with its CLI.
  */
-export const SESSION_PROTOCOL = 2;
+export const SESSION_PROTOCOL = 3;
 /** Why a host of another protocol is refused, and how to fix it. */
 export function protocolMismatch(announced) {
     const host = announced === undefined
@@ -135,7 +136,8 @@ export function parseResult(value) {
         Array.isArray(value["properties"]) &&
         value["properties"].every(isDecision) &&
         isVerdict(value["verdict"]) &&
-        typeof value["record_published"] === "boolean";
+        typeof value["record_published"] === "boolean" &&
+        (value["reason"] === undefined || typeof value["reason"] === "string");
     if (!valid)
         throw new TypeError("audit host sealed a result this SDK cannot read; the @mandateops/audit package and the mandateops CLI are probably different versions: add the SDK shipped with your CLI (its sdk/mandateops-audit-VERSION.tgz)");
     return value;
@@ -225,6 +227,13 @@ class Channel {
         return reply.body;
     }
 }
+/** Fewest and most parties one race holds; the host enforces the same. */
+export const MIN_RACE_PARTIES = 2;
+export const MAX_RACE_PARTIES = 8;
+const isRaceReport = (value) => isRecord(value) &&
+    typeof value["parties"] === "number" &&
+    typeof value["overlap_established"] === "boolean" &&
+    (value["reason"] === undefined || typeof value["reason"] === "string");
 /**
  * The whole run, for a test runner's own timeout: startup, the body, closing
  * work on either side of the longest wait, and teardown, which may take as
@@ -402,7 +411,7 @@ async function session(config, body, channel, backend, credentials) {
         }
     };
     const requireBound = (doing) => {
-        if (profile && authorised && providerPayment === undefined) {
+        if (profile && (authorised || competing) && providerPayment === undefined) {
             throw new AuditUsageError(`${doing} under ${profile} needs bindProviderPayment first: adapters read by that identifier`);
         }
     };
@@ -413,6 +422,18 @@ async function session(config, body, channel, backend, credentials) {
             throw new AuditUsageError(`${doing}: ${FAULT_STAGE_MEANS[fault]}`);
         }
     };
+    const authorisationOf = (expected) => ({
+        instruction: wireInstruction(expected),
+        capacity_limit: minorUnits(config.capacityLimitMinor),
+        provider: {
+            account: config.system.providerTerms.account,
+            operation: config.system.providerTerms.operation,
+            idempotency_scope: config.system.providerTerms.idempotencyScope,
+        },
+        ...(expected.outcome ? { expected_outcome: expected.outcome } : {}),
+    });
+    /** Declared through `expectCompetingPayments`: nothing is judged until one is bound. */
+    let competing = false;
     const budgetSpent = new AbortController();
     const fixture = {
         signal: budgetSpent.signal,
@@ -422,16 +443,7 @@ async function session(config, body, channel, backend, credentials) {
             expectPayment: async (expected) => {
                 await fromBody({
                     type: "authorise",
-                    authorisation: {
-                        instruction: wireInstruction(expected),
-                        capacity_limit: minorUnits(config.capacityLimitMinor),
-                        provider: {
-                            account: config.system.providerTerms.account,
-                            operation: config.system.providerTerms.operation,
-                            idempotency_scope: config.system.providerTerms.idempotencyScope,
-                        },
-                        ...(expected.outcome ? { expected_outcome: expected.outcome } : {}),
-                    },
+                    authorisation: authorisationOf(expected),
                 });
                 authorised = {
                     expected,
@@ -442,6 +454,55 @@ async function session(config, body, channel, backend, credentials) {
                 };
                 return authorised;
             },
+            expectCompetingPayments: async (expected, shared) => {
+                if (expected.length < MIN_RACE_PARTIES ||
+                    expected.length > MAX_RACE_PARTIES) {
+                    throw new AuditUsageError(`expectCompetingPayments takes ${String(MIN_RACE_PARTIES)}-${String(MAX_RACE_PARTIES)} payments`);
+                }
+                if (expected.some((entrant) => entrant.outcome !== undefined)) {
+                    throw new AuditUsageError("expectCompetingPayments is judged on backend readings: declare no outcome");
+                }
+                await fromBody({
+                    type: "authorise_competition",
+                    authorisations: expected.map((entrant) => authorisationOf(entrant)),
+                    shared_limit: minorUnits(shared.limitMinor),
+                });
+                competing = true;
+                const entrants = expected.map((entrant, competitor) => ({
+                    expected: entrant,
+                    bindProviderPayment: async (payment) => {
+                        await fromBody({
+                            type: "bind_provider_payment",
+                            payment,
+                            competitor,
+                        });
+                        // The first one bound is the payout the host judges and adapters read.
+                        if (providerPayment === undefined) {
+                            providerPayment = payment;
+                            authorised = entrants[competitor];
+                        }
+                    },
+                }));
+                return entrants;
+            },
+        },
+        concurrency: {
+            race: async (parties, submit) => {
+                if (!Number.isSafeInteger(parties) ||
+                    parties < MIN_RACE_PARTIES ||
+                    parties > MAX_RACE_PARTIES) {
+                    throw new AuditUsageError(`race takes ${String(MIN_RACE_PARTIES)}-${String(MAX_RACE_PARTIES)} parties`);
+                }
+                const opened = await fromBody({ type: "open_gate", parties });
+                const url = isRecord(opened) ? opened["url"] : undefined;
+                if (typeof url !== "string")
+                    throw new Error("audit host opened a gate without an address");
+                const settled = await Promise.allSettled(Array.from({ length: parties }, (_, party) => submit(url, party)));
+                const report = await fromBody({ type: "close_gate" });
+                if (!isRaceReport(report))
+                    throw new Error("audit host closed a gate without a report");
+                return { settled, report };
+            },
         },
         faults: {
             loseResponseAfterCommit: async ({ payment, mode }) => {

package/dist/providers/fiat.d.ts

@@ -8,8 +8,23 @@ import type { CheckoutTerms, LedgerTerms, MollieTerms, ProviderWire, SourcedTerm
 export declare const paystack: (terms: LedgerTerms) => ProviderWire;
 /** `POST /v1/payouts`. A request without `destination` is refused here. */
 export declare const stripePayouts: (terms: LedgerTerms) => ProviderWire;
-/** `POST /v1/transfers`, to a connected account. */
+/**
+ * `POST /v1/transfers`, to a connected account. Checked against Stripe test
+ * mode on API version 2026-10-28.endive: a first transfer, a replay under the
+ * same key, the same key with another amount (`idempotency_error`), a refusal
+ * for funds (`balance_insufficient`) and its replay agree. Stripe also marks a
+ * replay with `Idempotent-Replayed`, which this format does not send.
+ */
 export declare const stripeTransfers: (terms: LedgerTerms) => ProviderWire;
+/**
+ * Stripe Connect payouts: `POST /v1/accounts` and `POST /v1/accounts/:accountId/external_accounts`
+ * set up the recipient, `POST /v1/transfers` moves the money to it (the
+ * payment, as `stripeTransfers`), and `POST /v1/payouts` with a
+ * `Stripe-Account` header pays out of the connected account's balance. The
+ * key is optional, as at Stripe: a transfer sent without `Idempotency-Key`
+ * is a new transfer each time, so a retry after a lost reply pays again.
+ */
+export declare const stripeConnect: (terms: LedgerTerms) => ProviderWire;
 /**
  * `POST /v3/transfers`. Keyed on the unique `reference`, as v3 coverage of
  * `X-Idempotency-Key` and v3 reference reuse are unverified. The amount is a

package/dist/providers/fiat.js

@@ -88,6 +88,9 @@ const stripe = (path, terms, paid) => ({
         destination: "destination",
     },
     fixed: terms,
+    // Stripe saves a refusal under its key and replays it, as observed in test
+    // mode on API version 2026-10-28.endive.
+    refusals: "final",
     replies: {
         paid: {
             status: 200,
@@ -99,7 +102,7 @@ const stripe = (path, terms, paid) => ({
                 ...paid,
             },
         },
-        // The status of both failures is unverified.
+        // Both statuses were observed for transfers in test mode.
         declined: {
             status: 400,
             body: {
@@ -133,7 +136,13 @@ export const stripePayouts = (terms) => stripe("/v1/payouts", terms, {
     status: "pending",
     type: "bank_account",
 });
-/** `POST /v1/transfers`, to a connected account. */
+/**
+ * `POST /v1/transfers`, to a connected account. Checked against Stripe test
+ * mode on API version 2026-10-28.endive: a first transfer, a replay under the
+ * same key, the same key with another amount (`idempotency_error`), a refusal
+ * for funds (`balance_insufficient`) and its replay agree. Stripe also marks a
+ * replay with `Idempotent-Replayed`, which this format does not send.
+ */
 export const stripeTransfers = (terms) => stripe("/v1/transfers", terms, {
     id: "tr_{{effectId}}",
     object: "transfer",
@@ -143,6 +152,23 @@ export const stripeTransfers = (terms) => stripe("/v1/transfers", terms, {
     reversals: { object: "list", data: [], has_more: false },
     reversed: false,
 });
+/**
+ * Stripe Connect payouts: `POST /v1/accounts` and `POST /v1/accounts/:accountId/external_accounts`
+ * set up the recipient, `POST /v1/transfers` moves the money to it (the
+ * payment, as `stripeTransfers`), and `POST /v1/payouts` with a
+ * `Stripe-Account` header pays out of the connected account's balance. The
+ * key is optional, as at Stripe: a transfer sent without `Idempotency-Key`
+ * is a new transfer each time, so a retry after a lost reply pays again.
+ */
+export const stripeConnect = (terms) => ({
+    ...stripeTransfers(terms),
+    key: { header: "idempotency-key", maxLength: 255, optional: true },
+    connect: {
+        accounts: "/v1/accounts",
+        externalAccounts: "/v1/accounts/:accountId/external_accounts",
+        payouts: "/v1/payouts",
+    },
+});
 /**
  * `POST /v3/transfers`. Keyed on the unique `reference`, as v3 coverage of
  * `X-Idempotency-Key` and v3 reference reuse are unverified. The amount is a

package/dist/providers/index.d.ts

@@ -5,5 +5,5 @@
  * that provider behaves.
  */
 export { bridge, circleMint, fireblocks } from "./crypto.js";
-export { adyen, airwallex, checkout, dwolla, flutterwave, modernTreasury, molliePayouts, paypal, paystack, peach, razorpayx, revolut, stitch, stripePayouts, stripeTransfers, wise, } from "./fiat.js";
+export { adyen, airwallex, checkout, dwolla, flutterwave, modernTreasury, molliePayouts, paypal, paystack, peach, razorpayx, revolut, stitch, stripeConnect, stripePayouts, stripeTransfers, wise, } from "./fiat.js";
 export type * from "./types.js";

package/dist/providers/index.js

@@ -5,4 +5,4 @@
  * that provider behaves.
  */
 export { bridge, circleMint, fireblocks } from "./crypto.js";
-export { adyen, airwallex, checkout, dwolla, flutterwave, modernTreasury, molliePayouts, paypal, paystack, peach, razorpayx, revolut, stitch, stripePayouts, stripeTransfers, wise, } from "./fiat.js";
+export { adyen, airwallex, checkout, dwolla, flutterwave, modernTreasury, molliePayouts, paypal, paystack, peach, razorpayx, revolut, stitch, stripeConnect, stripePayouts, stripeTransfers, wise, } from "./fiat.js";

package/dist/providers/types.d.ts

@@ -57,6 +57,7 @@ export type WireKeyShape = "uuid_v4" | "lowercase_slug";
 export type WireKey = Readonly<{
     header: string;
     maxLength?: number;
+    optional?: boolean;
 } | {
     field: string;
     maxLength?: number;
@@ -106,6 +107,14 @@ export type ProviderWire = Readonly<{
         conflict: Reply;
         duplicate?: Reply;
     }>;
+    /** Stripe Connect's setup and payout calls around a transfer. */
+    connect?: ConnectRoutes;
+}>;
+/** Where Stripe Connect's account setup and payout calls sit. */
+export type ConnectRoutes = Readonly<{
+    accounts: string;
+    externalAccounts: string;
+    payouts: string;
 }>;
 /** A format of several calls, which the stand-in holds as its own flow. */
 export type StagedWire = Readonly<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandateops/audit",
-  "version": "0.2.0",
+  "version": "0.4.2",
   "description": "Write audit tests that check a payout backend keeps one payment identity, money limits and commitments when a provider commits but the reply is lost. Needs the mandateops CLI.",
   "license": "Apache-2.0",
   "homepage": "https://getmandateops.com",