@mandateops/audit 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,9 +1,8 @@
-import type { CapacityReading, HistoryReading, ReadingProfile } from "./reading.js";
+import type { CapacityReading, HistoryReading, ReadingProfile, StatusReading } 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 { 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";
+export * from "./providers/index.js";
+export { parseCapacityReading, parseHistoryReading, parseStatusReading, ReadingError, requireHistoryFits, } from "./reading.js";
+export type { AttemptEnd, AttemptResult, CapacityReading, Flow, HistoryEvent, HistoryReading, Instruction, MinorUnits, Payout, PayoutState, ReadingProfile, StatusReading, HistoryConsistency, CapacityConsistency, } from "./reading.js";
 /**
  * The largest amount the stand-in holds, the audit core's `u128` maximum.
  * `fixtures/wire/vectors.json` pins it for every reader.
@@ -21,11 +20,23 @@ export type ReadContext = Readonly<{
     viewerCredential: string;
     providerPayment: string;
 }>;
-/** Reads the backend, in the shape of `contracts/history-reading.md`. */
-export type Adapter = Readonly<{
+/**
+ * Reads a backend that reserves funds: its lifecycle and capacity, in the
+ * shape of `contracts/history-reading.md`.
+ */
+export type ReadingAdapter = Readonly<{
     history: (context: ReadContext) => Promise<HistoryReading>;
     capacity: (context: ReadContext) => Promise<CapacityReading>;
 }>;
+/**
+ * Reads the outcome a backend without reservations reports for the payout,
+ * judged against the provider's records under `payout-effects-only`.
+ */
+export type StatusAdapter = Readonly<{
+    status: (context: ReadContext) => Promise<StatusReading>;
+}>;
+/** Reads the backend: lifecycle and capacity, or only its reported status. */
+export type Adapter = ReadingAdapter | StatusAdapter;
 export declare const defineAdapter: (adapter: Adapter) => Adapter;
 /** The provider identity every effect must carry. */
 export type ProviderTerms = Readonly<{
@@ -213,7 +224,7 @@ 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 = 3;
+export declare const SESSION_PROTOCOL = 4;
 /** 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. */

package/dist/index.js

@@ -12,9 +12,10 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 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";
-export { parseCapacityReading, parseHistoryReading, ReadingError, requireHistoryFits, } from "./reading.js";
+import { parseCapacityReading, parseHistoryReading, parseStatusReading, requireHistoryFits, } from "./reading.js";
+// Every provider format and its types, from the one list that names them.
+export * from "./providers/index.js";
+export { parseCapacityReading, parseHistoryReading, parseStatusReading, ReadingError, requireHistoryFits, } from "./reading.js";
 const MINOR_UNITS = /^[1-9][0-9]*$/;
 /**
  * The largest amount the stand-in holds, the audit core's `u128` maximum.
@@ -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 = 3;
+export const SESSION_PROTOCOL = 4;
 /** Why a host of another protocol is refused, and how to fix it. */
 export function protocolMismatch(announced) {
     const host = announced === undefined
@@ -252,8 +253,15 @@ const readingProfile = (config) => config.financialProfile === "payout-effects-o
  */
 export function requireRunnable(config) {
     const profile = readingProfile(config);
-    if (profile === undefined && config.adapter) {
-        throw new AuditUsageError("payout-effects-only is judged on provider records alone: remove the adapter");
+    if (profile === undefined &&
+        config.adapter &&
+        !("status" in config.adapter)) {
+        throw new AuditUsageError("payout-effects-only reads no lifecycle or capacity: give it a status " +
+            "adapter (contracts/history-reading.md), or none");
+    }
+    if (profile !== undefined && config.adapter && "status" in config.adapter) {
+        throw new AuditUsageError(`${profile} reads lifecycle and capacity, not a status: a status ` +
+            "adapter is for payout-effects-only");
     }
     if (profile !== undefined && !config.adapter) {
         throw new AuditUsageError(`${profile} needs an adapter with history and capacity readings ` +
@@ -390,10 +398,12 @@ async function session(config, body, channel, backend, credentials) {
     const context = () => providerPayment === undefined
         ? undefined
         : { backend, viewerCredential, providerPayment };
+    const readings = config.adapter && "history" in config.adapter ? config.adapter : undefined;
+    const statusAdapter = config.adapter && "status" in config.adapter ? config.adapter : undefined;
     const readHistory = async (slot) => {
         const read = context();
-        if (config.adapter && profile && read && authorised) {
-            const { history } = config.adapter;
+        if (readings && profile && read && authorised) {
+            const { history } = readings;
             const reference = authorised.expected.reference;
             await reading(slot, async () => {
                 const taken = parseHistoryReading(await history(read));
@@ -404,11 +414,27 @@ async function session(config, body, channel, backend, credentials) {
     };
     const readCapacity = async (slot) => {
         const read = context();
-        const capacity = config.adapter?.capacity;
+        const capacity = readings?.capacity;
         if (capacity && read) {
             await reading(slot, async () => parseCapacityReading(await capacity(read)));
         }
     };
+    /**
+     * The backend's reported outcome, after the provider's records. Without a
+     * binding there is nothing to read by, which is reported, never skipped.
+     */
+    const readStatus = async () => {
+        if (!statusAdapter || !authorised)
+            return;
+        const reference = authorised.expected.reference;
+        const read = context();
+        await reading("capture_status", async () => {
+            if (!read) {
+                throw new AuditUsageError("a status adapter reads by the provider payment: call bindProviderPayment");
+            }
+            return parseStatusReading(await statusAdapter.status(read), reference);
+        });
+    };
     const requireBound = (doing) => {
         if (profile && (authorised || competing) && providerPayment === undefined) {
             throw new AuditUsageError(`${doing} under ${profile} needs bindProviderPayment first: adapters read by that identifier`);
@@ -582,6 +608,7 @@ async function session(config, body, channel, backend, credentials) {
     await readCapacity("capture_capacity");
     await channel.send({ type: "read_effects" });
     await readHistory("recapture_history");
+    await readStatus();
     const result = {
         ...parseResult(await channel.send({ type: "seal" })),
         reading_problems: problems,

package/dist/providers/fiat.d.ts

@@ -16,6 +16,15 @@ export declare const stripePayouts: (terms: LedgerTerms) => ProviderWire;
  * 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

@@ -152,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/dist/reading.d.ts

@@ -83,6 +83,16 @@ export type CapacityReading = Readonly<{
     committed: MinorUnits;
     consumed: MinorUnits;
 }>;
+/**
+ * The outcome the backend itself reports for one payout, taken once after
+ * the provider's records under `payout-effects-only`.
+ */
+export type StatusReading = Readonly<{
+    source: "adapter";
+    /** The reference given to `expectPayment`. */
+    payment: string;
+    state: PayoutState;
+}>;
 /** The profiles an adapter reading is taken under. */
 export type ReadingProfile = "payout-effects" | "payout-commitment";
 /**
@@ -101,6 +111,13 @@ export declare class ReadingError extends TypeError {
  * @throws {ReadingError} naming the first field that cannot be interpreted.
  */
 export declare function parseHistoryReading(value: unknown): HistoryReading;
+/**
+ * Check an untrusted status reading against the contract, and that it names
+ * the payout the test expects.
+ *
+ * @throws {ReadingError} naming the first field that cannot be interpreted.
+ */
+export declare function parseStatusReading(value: unknown, reference: string): StatusReading;
 /**
  * Check an untrusted capacity reading against the contract.
  *

package/dist/reading.js

@@ -231,6 +231,22 @@ export function parseHistoryReading(value) {
     });
     return value;
 }
+/**
+ * Check an untrusted status reading against the contract, and that it names
+ * the payout the test expects.
+ *
+ * @throws {ReadingError} naming the first field that cannot be interpreted.
+ */
+export function parseStatusReading(value, reference) {
+    const found = members(value, "", ["source", "payment", "state"]);
+    requireExactly("adapter", found["source"], "source");
+    requireText(found["payment"], "payment");
+    if (found["payment"] !== reference) {
+        refuse("payment", "the reference given to expectPayment", found["payment"]);
+    }
+    requireOneOf(STATES, found["state"], "state");
+    return value;
+}
 /**
  * Check an untrusted capacity reading against the contract.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandateops/audit",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "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",