@mandateops/audit 0.0.0-stage → 0.2.0

package/dist/providers/fiat.js

@@ -0,0 +1,594 @@
+import { CREATED_AT, CREATED_UNIX, undocumented } from "./common.js";
+/** The currencies these formats are tried with; any other is refused. */
+const CURRENCIES = [
+    "AUD",
+    "BHD",
+    "BRL",
+    "CAD",
+    "CHF",
+    "DKK",
+    "EUR",
+    "GBP",
+    "GHS",
+    "HKD",
+    "HUF",
+    "INR",
+    "JPY",
+    "KES",
+    "KRW",
+    "KWD",
+    "MXN",
+    "NGN",
+    "NOK",
+    "NZD",
+    "OMR",
+    "PLN",
+    "SEK",
+    "SGD",
+    "TWD",
+    "USD",
+    "ZAR",
+];
+/** ISO 4217 minor digits, as the runtime's own currency data states them. */
+const minorDigitsOf = (currency) => new Intl.NumberFormat("en", {
+    style: "currency",
+    currency,
+}).resolvedOptions().maximumFractionDigits ?? 0;
+const CURRENCY_DIGITS = Object.fromEntries(CURRENCIES.map((currency) => [currency, minorDigitsOf(currency)]));
+const DECIMAL = { scaleTerm: "currency", scales: CURRENCY_DIGITS };
+/**
+ * `POST /transfer`, from Paystack's published OpenAPI description. The amount
+ * is in kobo or pesewas, and a reference is lowercase alphanumeric with `-` and
+ * `_`. Reuse of a reference is unverified: its docs both reject one and advise
+ * retrying with it. `currency` is optional there, defaulting to NGN.
+ */
+export const paystack = (terms) => ({
+    path: "/transfer",
+    key: { field: "reference", shape: "lowercase_slug" },
+    fields: {
+        amount: "amount",
+        currency: "currency",
+        destination: "recipient",
+    },
+    defaults: { currency: "NGN" },
+    fixed: terms,
+    replies: {
+        paid: {
+            status: 200,
+            body: {
+                status: true,
+                message: "Transfer has been queued",
+                data: {
+                    amount: "{{amount:number}}",
+                    currency: "{{currency}}",
+                    reference: "{{key}}",
+                    source: "balance",
+                    status: "success",
+                    transfer_code: "TRF_{{effectId}}",
+                },
+            },
+        },
+        declined: {
+            status: 400,
+            body: { status: false, message: "Transfer declined" },
+        },
+        conflict: {
+            status: 400,
+            body: { status: false, message: "Duplicate Transaction Reference" },
+        },
+    },
+});
+const stripe = (path, terms, paid) => ({
+    path,
+    encoding: "form",
+    key: { header: "idempotency-key", maxLength: 255 },
+    fields: {
+        amount: "amount",
+        currency: "currency",
+        destination: "destination",
+    },
+    fixed: terms,
+    replies: {
+        paid: {
+            status: 200,
+            body: {
+                amount: "{{amount:number}}",
+                created: CREATED_UNIX,
+                currency: "{{currency}}",
+                livemode: false,
+                ...paid,
+            },
+        },
+        // The status of both failures is unverified.
+        declined: {
+            status: 400,
+            body: {
+                error: {
+                    type: "invalid_request_error",
+                    code: "balance_insufficient",
+                    message: "Insufficient funds",
+                },
+            },
+        },
+        conflict: {
+            status: 400,
+            body: {
+                error: {
+                    type: "idempotency_error",
+                    message: "Keys can only be used with the same parameters",
+                },
+            },
+        },
+    },
+});
+/** `POST /v1/payouts`. A request without `destination` is refused here. */
+export const stripePayouts = (terms) => stripe("/v1/payouts", terms, {
+    id: "po_{{effectId}}",
+    object: "payout",
+    arrival_date: CREATED_UNIX,
+    automatic: false,
+    method: "standard",
+    reconciliation_status: "not_applicable",
+    source_type: "card",
+    status: "pending",
+    type: "bank_account",
+});
+/** `POST /v1/transfers`, to a connected account. */
+export const stripeTransfers = (terms) => stripe("/v1/transfers", terms, {
+    id: "tr_{{effectId}}",
+    object: "transfer",
+    amount_reversed: 0,
+    destination: "{{destination}}",
+    metadata: {},
+    reversals: { object: "list", data: [], has_more: false },
+    reversed: false,
+});
+/**
+ * `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
+ * required integer whose unit is not stated, though samples look major; it is
+ * read as given. A synchronous refusal is unverified. The destination is
+ * `bank_account`, so a run authorises the two joined.
+ */
+export const flutterwave = (terms) => ({
+    path: "/v3/transfers",
+    key: { field: "reference" },
+    fields: { amount: "amount", currency: "currency" },
+    joined: { destination: ["account_bank", "account_number"] },
+    fixed: terms,
+    replies: {
+        paid: {
+            status: 200,
+            body: {
+                status: "success",
+                message: "Transfer Queued Successfully",
+                data: {
+                    id: "{{effectId}}",
+                    currency: "{{currency}}",
+                    amount: "{{amount:number}}",
+                    status: "NEW",
+                    reference: "{{key}}",
+                },
+            },
+        },
+        declined: undocumented(400),
+        conflict: undocumented(400),
+    },
+});
+/**
+ * `POST /transfers` of the Transfers API, to a transfer instrument. A refusal
+ * is a 202, as the published specification shows, and 422 is its validation
+ * status. A processed retry gets the first response; a reused key with a
+ * different body is unverified.
+ */
+export const adyen = (terms) => ({
+    path: "/transfers",
+    credential: { header: "x-api-key", prefix: "" },
+    key: { header: "idempotency-key" },
+    fields: {
+        account: "balanceAccountId",
+        amount: "amount.value",
+        currency: "amount.currency",
+        destination: "counterparty.transferInstrumentId",
+    },
+    fixed: terms,
+    replies: {
+        paid: {
+            status: 202,
+            body: {
+                id: "{{effectId}}",
+                amount: { value: "{{amount:number}}", currency: "{{currency}}" },
+                category: "bank",
+                counterparty: { transferInstrumentId: "{{destination}}" },
+                status: "authorised",
+            },
+        },
+        declined: {
+            status: 202,
+            body: {
+                amount: { value: "{{amount:number}}", currency: "{{currency}}" },
+                category: "bank",
+                counterparty: { transferInstrumentId: "{{destination}}" },
+                status: "refused",
+                reason: "notEnoughBalance",
+            },
+        },
+        conflict: undocumented(422),
+    },
+});
+/**
+ * `POST /transfers` between entities; the sample names no currency. Idempotency
+ * is documented for this route: only 2xx replies are cached, and a concurrent
+ * repeat gets 409. The field names come from non-canonical sources, and the
+ * amount's unit, the credential scheme and all failures are unverified.
+ */
+export const checkout = (terms) => ({
+    path: "/transfers",
+    key: { header: "cko-idempotency-key" },
+    fields: {
+        account: "source.id",
+        amount: "source.amount",
+        destination: "destination.id",
+    },
+    fixed: terms,
+    replies: {
+        paid: {
+            status: 201,
+            body: {
+                id: "tra_{{effectId}}",
+                status: "pending",
+                _links: { self: { href: "/transfers/tra_{{effectId}}" } },
+            },
+        },
+        declined: undocumented(422),
+        conflict: undocumented(422),
+    },
+});
+/** PayPal writes these whole, whatever ISO 4217 says. */
+const PAYPAL_DIGITS = { ...CURRENCY_DIGITS, HUF: 0, TWD: 0 };
+/**
+ * `POST /v1/payments/payouts`, one item per batch. An email receiver is not an
+ * identifier the lab can hold. A repeated batch id is rejected with a link to
+ * the original batch, within 30 days; that status is unverified. Insufficient
+ * funds is documented per item, so a synchronous refusal is unverified.
+ */
+export const paypal = (terms) => ({
+    path: "/v1/payments/payouts",
+    key: { field: "sender_batch_header.sender_batch_id" },
+    singleEntry: ["items"],
+    fields: {
+        amount: "items.0.amount.value",
+        currency: "items.0.amount.currency",
+        destination: "items.0.receiver",
+    },
+    fixed: terms,
+    amount: { scaleTerm: "currency", scales: PAYPAL_DIGITS },
+    replay: "duplicate_reply",
+    replies: {
+        paid: {
+            status: 201,
+            body: {
+                batch_header: {
+                    payout_batch_id: "{{effectId}}",
+                    batch_status: "PENDING",
+                    sender_batch_header: { sender_batch_id: "{{key}}" },
+                    time_created: CREATED_AT,
+                },
+                links: [],
+            },
+        },
+        declined: undocumented(400),
+        conflict: undocumented(400),
+        duplicate: {
+            status: 400,
+            body: {
+                links: [{ href: "/v1/payments/payouts/{{effectId}}", rel: "self" }],
+            },
+        },
+    },
+});
+/**
+ * `POST /v1/payouts`. A repeated key returns the first response; a changed body
+ * is unverified. Low balance is a payout state, so a refusal is a reply whose
+ * status says so, and every HTTP status here is unverified.
+ */
+export const razorpayx = (terms) => ({
+    path: "/v1/payouts",
+    credential: { basic: true },
+    key: { header: "x-payout-idempotency" },
+    fields: {
+        account: "account_number",
+        amount: "amount",
+        currency: "currency",
+        destination: "fund_account_id",
+    },
+    fixed: terms,
+    replies: {
+        paid: {
+            status: 200,
+            body: {
+                id: "pout_{{effectId}}",
+                entity: "payout",
+                amount: "{{amount:number}}",
+                currency: "{{currency}}",
+                status: "queued",
+            },
+        },
+        declined: {
+            status: 200,
+            body: {
+                id: "pout_{{payment}}",
+                entity: "payout",
+                amount: "{{amount:number}}",
+                currency: "{{currency}}",
+                status: "rejected",
+            },
+        },
+        conflict: undocumented(400),
+    },
+});
+const HAL_JSON = { "content-type": "application/hal+json" };
+const omitCurrency = ({ currency: _currency, ...rest }) => rest;
+const mollieError = (status, detail) => ({
+    status,
+    body: { status, title: detail, detail },
+    headers: HAL_JSON,
+});
+/**
+ * `POST /v2/payouts`, to the balance's configured bank account. `balanceId` is
+ * optional; `account` is what its absence means. Omitting `amount` pays out the
+ * whole balance, which the suite states as `wholeBalance`. The reply's
+ * `statusReason` is left out, as its codes are unverified.
+ */
+export const molliePayouts = ({ account, wholeBalance, ...terms }) => ({
+    path: "/v2/payouts",
+    key: { header: "idempotency-key" },
+    fields: {
+        account: "balanceId",
+        amount: "amount.value",
+        currency: "amount.currency",
+    },
+    defaults: { account, currency: terms.currency },
+    amountDefault: wholeBalance,
+    fixed: omitCurrency(terms),
+    amount: DECIMAL,
+    replies: {
+        paid: {
+            status: 201,
+            headers: HAL_JSON,
+            body: {
+                resource: "payout",
+                id: "{{effectId}}",
+                status: "requested",
+                createdAt: CREATED_AT,
+                mode: "test",
+            },
+        },
+        declined: mollieError(422, "Insufficient funds"),
+        conflict: mollieError(400, "Idempotency key reused"),
+    },
+});
+/**
+ * `POST /api/merchants/{merchantId}/payouts`, one payout per request. Failures
+ * are documented as `{ title, message, code }`; which code fits each refusal is
+ * unverified, so their bodies stay empty. The merchant is the account, and the
+ * destination is `branchCode--accountNumber`. A payout without `payoutId` has no
+ * idempotency, so each such request is its own payment.
+ */
+export const peach = (terms) => ({
+    path: "/api/merchants/:merchantId/payouts",
+    key: { field: "payouts.0.payoutId", optional: true },
+    singleEntry: ["payouts"],
+    fields: {
+        account: ":merchantId",
+        amount: "payouts.0.amount",
+        currency: "payouts.0.currency",
+    },
+    joined: {
+        destination: ["payouts.0.branchCode", "payouts.0.accountNumber"],
+    },
+    fixed: terms,
+    replay: "duplicate_reply",
+    replies: {
+        paid: {
+            status: 201,
+            body: {
+                payoutRequestId: "{{effectId}}",
+                created: CREATED_AT,
+                payouts: [
+                    { payoutId: "{{key}}", status: "pending", created: CREATED_AT },
+                ],
+            },
+        },
+        declined: undocumented(400),
+        conflict: undocumented(400),
+        duplicate: undocumented(400),
+    },
+});
+/**
+ * `POST /v2/disbursements`, ZAR only. The amount is read as decimal, and a
+ * repeated nonce gets 409. Insufficient funds is documented as a later `error`
+ * status, so a refusal is a reply in that status. The destination is
+ * `bankId--accountNumber`.
+ */
+export const stitch = (terms) => ({
+    path: "/v2/disbursements",
+    key: { field: "nonce" },
+    fields: {
+        amount: "amount.quantity",
+        currency: "amount.currency",
+    },
+    joined: { destination: ["beneficiary.bankId", "beneficiary.accountNumber"] },
+    fixed: terms,
+    amount: { scaleTerm: "currency", scales: { ZAR: 2 } },
+    replay: "duplicate_reply",
+    replies: {
+        paid: {
+            status: 201,
+            body: { id: "{{effectId}}", status: "pending", createdAt: CREATED_AT },
+        },
+        declined: {
+            status: 201,
+            body: { id: "{{payment}}", status: "error", createdAt: CREATED_AT },
+        },
+        conflict: undocumented(409),
+        duplicate: undocumented(409),
+    },
+});
+/**
+ * `POST /pay`, from `account_id` to a counterparty's account, per Revolut's
+ * OpenAPI description. A reused `request_id` makes no second transaction and
+ * answers the documented 400 for two weeks. The id is at most 40 characters.
+ */
+export const revolut = (terms) => {
+    const duplicate = {
+        status: 400,
+        body: { code: 3020, message: "Duplicate request: {{key}}" },
+    };
+    return {
+        path: "/pay",
+        key: { field: "request_id", maxLength: 40 },
+        fields: {
+            account: "account_id",
+            amount: "amount",
+            currency: "currency",
+            destination: "receiver.account_id",
+        },
+        fixed: terms,
+        amount: DECIMAL,
+        replay: "duplicate_reply",
+        replies: {
+            paid: {
+                status: 200,
+                body: { id: "{{effectId}}", state: "pending", created_at: CREATED_AT },
+            },
+            declined: undocumented(400),
+            conflict: duplicate,
+            duplicate,
+        },
+    };
+};
+/**
+ * `POST /api/payment_orders`. A key is at most 180 characters, and only
+ * successes are cached, with a concurrent repeat getting 409. The reply holds a
+ * few of the object's fields; its status, a changed body and the failures are
+ * unverified. `currency` is optional
+ * there, taken from the originating account, so pass it in `defaults`.
+ */
+export const modernTreasury = (terms, defaults = {}) => ({
+    path: "/api/payment_orders",
+    credential: { basic: true },
+    key: { header: "idempotency-key", maxLength: 180 },
+    fields: {
+        account: "originating_account_id",
+        amount: "amount",
+        currency: "currency",
+        destination: "receiving_account_id",
+    },
+    defaults,
+    fixed: terms,
+    replies: {
+        paid: {
+            status: 201,
+            body: {
+                id: "{{effectId}}",
+                object: "payment_order",
+                amount: "{{amount:number}}",
+                currency: "{{currency}}",
+                direction: "credit",
+                status: "approved",
+            },
+        },
+        declined: undocumented(422),
+        conflict: undocumented(422),
+    },
+});
+/**
+ * `POST /api/v1/transfers/create`. The amount is a string in the schema and a
+ * number in the example; either is read, as decimal, which is unverified, as
+ * is the `transfer_amount` name. Both failure codes are from Airwallex's
+ * transfer error list.
+ */
+export const airwallex = (terms) => {
+    const duplicate = {
+        status: 400,
+        body: { code: "duplicate_request_id", message: "duplicate_request_id" },
+    };
+    return {
+        path: "/api/v1/transfers/create",
+        key: { field: "request_id" },
+        fields: {
+            amount: "transfer_amount",
+            currency: "transfer_currency",
+            destination: "beneficiary_id",
+        },
+        fixed: terms,
+        amount: DECIMAL,
+        replay: "duplicate_reply",
+        replies: {
+            paid: {
+                status: 201,
+                body: {
+                    id: "{{effectId}}",
+                    request_id: "{{key}}",
+                    status: "NEW",
+                    created_at: CREATED_AT,
+                },
+            },
+            declined: {
+                status: 400,
+                body: { code: "balance_insufficient", message: "balance_insufficient" },
+            },
+            conflict: duplicate,
+            duplicate,
+        },
+    };
+};
+const DWOLLA_FUNDING = "/funding-sources/";
+/**
+ * `POST /transfers`, answered by a `Location`, relative so a client following
+ * it stays in the lab. A repeated key gets 201 with the same `Location`; a 409
+ * there means the original is still processing, so it is not used for a changed
+ * body, whose status is unverified, as are failure bodies.
+ */
+export const dwolla = (terms) => {
+    const location = { location: "/transfers/{{effectId}}" };
+    return {
+        path: "/transfers",
+        jsonType: "application/vnd.dwolla.v1.hal+json",
+        key: { header: "idempotency-key" },
+        fields: {
+            account: "_links.source.href",
+            amount: "amount.value",
+            currency: "amount.currency",
+            destination: "_links.destination.href",
+        },
+        urlFields: { account: DWOLLA_FUNDING, destination: DWOLLA_FUNDING },
+        fixed: terms,
+        amount: DECIMAL,
+        replies: {
+            paid: { status: 201, body: null, headers: location },
+            declined: undocumented(400),
+            conflict: undocumented(400),
+        },
+    };
+};
+const WISE_ROUTES = {
+    quotes: "/v3/profiles/:profileId/quotes",
+    transfers: "/v1/transfers",
+    fund: "/v3/profiles/:profileId/transfers/:transferId/payments",
+};
+/**
+ * Quote, transfer, then fund, from Wise's API reference. Only the fund call
+ * moves money. The account is the quote's profile, the currency its source and
+ * the asset its target; `customerTransactionId` is the key, and a repeat makes
+ * no duplicate, though its reply body and quote reuse are unverified. Wise also
+ * serves dated bases such as `/2026Q4`, so a client may override the routes.
+ * Recipient creation is not imitated.
+ */
+export const wise = (terms, routes = WISE_ROUTES) => ({
+    flow: "wise",
+    fixed: terms,
+    scales: CURRENCY_DIGITS,
+    routes,
+});

package/dist/providers/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Provider formats the stand-in can speak, so a customer's provider client can
+ * run against it within the subset `contracts/synthetic-provider.md` states per
+ * format. Each imitates one payout call's shape; none of them establishes how
+ * 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 type * from "./types.js";

package/dist/providers/index.js

@@ -0,0 +1,8 @@
+/**
+ * Provider formats the stand-in can speak, so a customer's provider client can
+ * run against it within the subset `contracts/synthetic-provider.md` states per
+ * format. Each imitates one payout call's shape; none of them establishes how
+ * 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";