@peable.to/shared-types 0.10.0 → 0.11.0

package/dist/esm/paymentIntent.js

@@ -1,224 +1,127 @@
 /** {@link PaymentIntentRail} as the tuple the database CHECK reads. */
 export const PAYMENT_INTENT_RAILS = ['faircoin', 'card'];
 /**
- * Which statuses belong to which rail (ADR 0001 D5).
+ * The statuses only a CARD payment can reach (ADR 0019).
  *
- * The four chain states describe a transaction on a blockchain and the four
- * card states describe an authorization at a card acquirer; neither set is
- * expressible on the other rail. Mapping a card authorization onto `broadcast`
- * would be cheaper and would be a lie — nothing was broadcast, there is no
- * transaction, and `payment_intents_broadcast_requires_txid_check` would then
- * be demanding a txid from a payment that can never have one.
- *
- * `db/schema/payments.ts` renders these two sets into CHECK constraints, so the
- * restriction holds against a write that skipped the application.
+ * A FairCoin payment has no payment method to require (the payer's wallet signs
+ * on their own device), nothing to confirm server-side, and no authorization
+ * to capture — coins either arrive or they do not. `db/schema/payments.ts`
+ * renders this set into a CHECK, so the restriction holds against a write that
+ * skipped the application.
  */
-export const CHAIN_ONLY_STATUSES = [
-    'awaiting_approval',
-    'approved',
-    'broadcast',
-    'confirming',
-];
 export const CARD_ONLY_STATUSES = [
-    'requires_action',
-    'processing',
-    'refunded',
-    'partially_refunded',
+    'requires_payment_method',
+    'requires_confirmation',
+    'requires_capture',
 ];
 /**
- * Legal forward transitions of the PaymentIntent lifecycle. Terminal states
- * (refunded/expired/failed/rejected) allow no further transition here — the one
- * documented exception, a reorg dropping `settled` back to `confirming`, is
- * modelled by the backend state machine, not this happy-path table.
+ * Legal transitions of the PaymentIntent lifecycle.
  *
- * ONE table for both rails, deliberately. It answers "is this a legal lifecycle
- * edge at all"; WHICH rail may reach a given status is the separate, structural
- * question the two sets above answer, in the database. A rail-parameterised
- * table would put the same restriction in two places and let them disagree.
+ * ONE table for both rails. It answers "is this a legal lifecycle edge at all";
+ * WHICH rail may reach a given status is the separate, structural question
+ * {@link CARD_ONLY_STATUSES} answers in the database, and which EVENT may walk
+ * an edge is `LEGAL_SOURCES` in the backend's `services/intentState.ts`.
  *
  * Self-transitions are absent because `applyEvent` short-circuits on
- * `current === target` before consulting this table — that is the idempotent
- * re-poll of the settlement watcher, and a second partial refund, which change
- * an amount without changing a status.
+ * `current === target` — the idempotent re-poll of the settlement watcher.
+ *
+ * `succeeded` has no outgoing edge here. Its one exception — a chain reorg
+ * dropping a FairCoin payment back below its confirmation threshold,
+ * `succeeded → processing` — is modelled by the backend state machine, not this
+ * table. Refunds are not statuses: money coming back is `amount_refunded` and
+ * the refunds themselves (ADR 0019).
  */
 const ALLOWED = {
-    // `created` supports three paths: the rich wallet flow (→ awaiting_approval →
-    // approved → broadcast), the minimal path where the payer pays out-of-band
-    // and reports the txid directly (→ broadcast), and the card path (→
-    // requires_action for an SCA challenge, → processing, or straight to settled
-    // for a charge that confirms in one call). `failed` is reachable from here
-    // because a card can be declined on first confirmation, having never been
-    // anything else; no FairCoin path uses that edge, since `underpaid` is only
-    // emitted for an intent that already carries a txid.
-    created: [
-        'awaiting_approval',
-        'broadcast',
+    requires_payment_method: [
+        'requires_confirmation',
+        'requires_action',
+        'processing',
+        'requires_capture',
+        'succeeded',
+        'canceled',
+    ],
+    requires_confirmation: [
+        'requires_payment_method',
         'requires_action',
         'processing',
-        'settled',
-        'failed',
-        'rejected',
-        'expired',
+        'requires_capture',
+        'succeeded',
+        'canceled',
     ],
-    awaiting_approval: ['approved', 'rejected', 'expired'],
-    approved: ['broadcast', 'failed'],
-    broadcast: ['confirming', 'failed'],
-    confirming: ['settled', 'failed'],
-    requires_action: ['processing', 'settled', 'failed', 'expired', 'rejected'],
-    processing: ['settled', 'failed'],
-    /**
-     * A failed ATTEMPT is not a failed payment, on the card rail.
-     *
-     * `payment_intent.payment_failed` means one authorization attempt was
-     * declined; Stripe returns the PaymentIntent to `requires_payment_method` and
-     * the payer can confirm it again with another card. With `failed` terminal,
-     * the later `payment_intent.succeeded` was an ILLEGAL transition — so the
-     * drain recorded a processing failure and retried it forever, the payment
-     * stayed `failed`, and a merchant who had been paid was told their payment
-     * had been declined.
-     *
-     * On the chain rail `failed` means `underpaid`, which IS terminal — coins
-     * arrived and were not enough. Nothing here opens that door: `underpaid` is
-     * emitted only by the settlement watcher, and `LEGAL_SOURCES` in
-     * `services/intentState.ts` keeps every `card_*` event to card statuses and
-     * the chain's `confirmed` to `confirming`. This table answers "is the edge
-     * legal at all"; which rail may walk it is the separate question those two
-     * guards answer.
-     */
-    failed: ['requires_action', 'processing', 'settled'],
-    // Money coming back requires money to have arrived, so both refund states are
-    // reachable only from `settled`.
-    settled: ['refunded', 'partially_refunded'],
-    /**
-     * ...and money coming back can be UNDONE, which is why these edges run both
-     * ways.
-     *
-     * A refund is not final when the provider accepts it: a bank can reject one
-     * days later, and the provider then says so (`refund.failed`). Without a path
-     * back, a payment whose only refund failed would claim `refunded` forever —
-     * the merchant's books saying money went back that is still with them, and no
-     * transition anywhere able to correct it.
-     *
-     * The target is always recomputed from the SUM of succeeded refunds
-     * (`applyRefundToIntent`), never stepped, so these edges describe where that
-     * sum can legally land rather than a sequence anyone walks.
-     */
-    partially_refunded: ['refunded', 'settled'],
-    refunded: ['partially_refunded', 'settled'],
-    expired: [],
-    rejected: [],
+    // FairCoin: the payer broadcasts (→ processing), or the intent is cancelled
+    // or expires (→ canceled). Card: an SCA challenge resolved either way.
+    requires_action: [
+        'requires_payment_method',
+        'processing',
+        'requires_capture',
+        'succeeded',
+        'canceled',
+    ],
+    // FairCoin: confirmed (→ succeeded) or underpaid (→ canceled). Card: an async
+    // method settled, was authorized, or failed back to `requires_payment_method`.
+    processing: ['requires_payment_method', 'requires_capture', 'succeeded', 'canceled'],
+    requires_capture: ['processing', 'succeeded', 'canceled'],
+    succeeded: [],
+    canceled: [],
 };
 export function isValidStatusTransition(from, to) {
     return ALLOWED[from].includes(to);
 }
-/** Every legal `PaymentIntentStatus`, derived from `ALLOWED`'s keys — the
- * single source of truth consumed by the Gateway's list-route status filter. */
+/** Every `PaymentIntentStatus`, derived from `ALLOWED`'s keys. */
 export const PAYMENT_INTENT_STATUSES = Object.keys(ALLOWED);
-/**
- * The statuses a payer can still complete a payment FROM.
- *
- * **Twice now this question has been answered by walking the transition table,
- * and twice the table has moved underneath it.**
- *
- * The hosted checkout first asked leaf-ness — "has this status no outgoing
- * edges" — which meant `settled` while `settled` had none. Adding the refund
- * transitions (`settled → refunded | partially_refunded`) gave it edges, so a
- * settled payment stopped looking finished, and the checkout began REUSING a
- * remembered settled intent instead of minting a fresh one: a payer who had
- * already paid saw their old receipt forever, with no way to pay the link
- * again.
- *
- * The fix was reachability — "is `settled` still reachable" — and that held
- * until refunds could be UNDONE. `refunded → settled` (a bank rejecting a
- * refund days later) makes `settled` reachable from `settled` in two steps, so
- * reachability answers `true` for a payment that is finished, and the original
- * bug returns unchanged.
- *
- * So the set is stated, not derived. It is exactly the statuses in which the
- * gateway is still waiting on the PAYER — which is what the question means, in
- * the payer's own terms, and is the one formulation no edge added elsewhere can
- * silently change. `paymentIntent.test.ts` pins it against the table: every
- * member must still be able to reach `settled` without passing through a
- * post-settlement status, and no non-member may.
- */
-const PAYABLE_STATUSES = new Set([
-    'created',
-    'awaiting_approval',
-    'approved',
-    'broadcast',
-    'confirming',
-    'requires_action',
-    'processing',
-]);
+/** The statuses that end a payment: nothing leaves them (bar the reorg exception). */
+export const TERMINAL_STATUSES = ['succeeded', 'canceled'];
 /**
  * Whether a payer can still complete a payment against an intent in this
- * status.
- *
- * `settled` answers `false`: it is where paying ENDS. `partially_refunded`
- * answers `false` too — money can still move, but not from the payer.
+ * status — every non-terminal one. Stated, not derived from reachability:
+ * `paymentIntent.test.ts` pins it against the table.
  */
 export function canStillBePaid(status) {
-    return PAYABLE_STATUSES.has(status);
-}
-/**
- * The statuses a payment reaches only AFTER the payer has finished.
- *
- * Exported for the gate below rather than for production use: the property that
- * makes `PAYABLE_STATUSES` checkable is that a payable status reaches `settled`
- * without going through one of these.
- */
-export const POST_SETTLEMENT_STATUSES = [
-    'settled',
-    'refunded',
-    'partially_refunded',
-];
-/**
- * Whether `settled` is reachable from `status` without passing through a
- * post-settlement status. The derivation `canStillBePaid` used to BE, kept as
- * the thing that checks it rather than as the thing that answers it.
- */
-export function reachesSettlementFromPayer(status) {
-    const blocked = new Set(POST_SETTLEMENT_STATUSES);
-    // A payment that has ALREADY settled is one the payer has finished with,
-    // whatever edges lead out of it. Checked before the walk rather than inside
-    // it, because `partially_refunded → settled` is a direct edge and the walk
-    // would find it in one step — and that edge is a refund being undone, not a
-    // payer paying.
-    if (blocked.has(status))
-        return false;
-    const seen = new Set();
-    const queue = [...ALLOWED[status]];
-    while (queue.length > 0) {
-        const next = queue.shift();
-        if (next === 'settled')
-            return true;
-        if (seen.has(next) || blocked.has(next))
-            continue;
-        seen.add(next);
-        queue.push(...ALLOWED[next]);
-    }
-    return false;
+    return !TERMINAL_STATUSES.includes(status);
 }
 /**
  * The statuses an intent may still EXPIRE from (ADR 0012 D9).
  *
- * Exactly those whose transition list contains `expired`: the gateway is
- * waiting on a PERSON who has not paid. Once a FairCoin payer has reported a
- * broadcast (`broadcast`), or the chain is confirming it (`confirming`), the
- * intent NEVER expires, whatever `expiresAt` says — coins are moving and the
- * settlement watcher owns the row. A platform must therefore never cancel an
- * order because `expiresAt` passed: it releases a reservation on
- * `payment_intent.expired` (or `rejected`), and on nothing else.
+ * The gateway is waiting on a PERSON who has not paid: a FairCoin payer who has
+ * not broadcast (`requires_action`), or a card payer who has not completed a
+ * payment method or a challenge. Once a FairCoin payer has reported a
+ * transaction (`processing`) the intent NEVER expires, whatever `expires_at`
+ * says — coins are moving and the settlement watcher owns the row. An
+ * authorization held for capture (`requires_capture`) is the merchant's to
+ * capture or cancel and does not expire either.
  *
- * Stated rather than derived, for `PAYABLE_STATUSES`' reason; the gateway's
- * test suite pins it against the transition table.
+ * Expiry is a cancellation with `cancellation_reason: 'abandoned'`: a platform
+ * releases a reservation on `payment_intent.canceled`.
  */
 export const EXPIRABLE_STATUSES = [
-    'created',
-    'awaiting_approval',
+    'requires_payment_method',
+    'requires_confirmation',
     'requires_action',
 ];
 /** Whether an intent in this status can still expire. See {@link EXPIRABLE_STATUSES}. */
 export function canExpire(status) {
     return EXPIRABLE_STATUSES.includes(status);
 }
+export const PAYMENT_INTENT_CANCELLATION_REASONS = [
+    'abandoned',
+    'automatic',
+    'duplicate',
+    'fraudulent',
+    'requested_by_customer',
+    'underpaid',
+];
+/** The reasons a MERCHANT may give `POST /v1/payment_intents/:id/cancel`. */
+export const MERCHANT_CANCELLATION_REASONS = [
+    'abandoned',
+    'duplicate',
+    'fraudulent',
+    'requested_by_customer',
+];
+export const PAYMENT_INTENT_CAPTURE_METHODS = [
+    'automatic',
+    'manual',
+];
+export const PAYMENT_INTENT_SETUP_FUTURE_USAGES = [
+    'on_session',
+    'off_session',
+];

package/dist/esm/paymentMethod.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/setupIntent.js

@@ -0,0 +1,8 @@
+export const SETUP_INTENT_STATUSES = [
+    'requires_payment_method',
+    'requires_confirmation',
+    'requires_action',
+    'processing',
+    'canceled',
+    'succeeded',
+];

package/dist/esm/webhookEndpoint.js

@@ -0,0 +1,17 @@
+export const WEBHOOK_ENDPOINT_STATUSES = ['enabled', 'disabled'];
+/**
+ * Why an endpoint is `disabled`.
+ *
+ *  - `disabled_by_merchant` — its owner set `disabled: true`.
+ *  - `delivery_failures`    — every delivery to it failed for three days
+ *    straight, so Peable stopped sending. Re-enabling it (`disabled: false`)
+ *    starts the clock again.
+ */
+export const WEBHOOK_ENDPOINT_DISABLED_REASONS = [
+    'disabled_by_merchant',
+    'delivery_failures',
+];
+/** At most this many endpoints per merchant (per mode). */
+export const WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = 16;
+/** The longest a rolled secret may keep signing beside its replacement. */
+export const WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS = 24 * 60 * 60;

package/dist/esm/webhookSigner.js

@@ -9,32 +9,40 @@ function computeSignature(secret, rawBody, timestamp) {
 }
 /**
  * Produce a Stripe-style signature header for an outbound webhook:
- * `t=${timestamp},v1=${hexHmacSha256}`.
+ * `t=${timestamp},v1=${hex}` — with one `v1=` per secret.
+ *
+ * Several secrets are what make a rotation gapless: while an endpoint's rolled
+ * secret is still inside its overlap window, every delivery is signed with
+ * BOTH, so a receiver verifying with either one accepts it.
  */
 export function signWebhook(secret, rawBody, timestamp) {
-    return `t=${timestamp},v1=${computeSignature(secret, rawBody, timestamp)}`;
+    const secrets = typeof secret === 'string' ? [secret] : secret;
+    if (secrets.length === 0)
+        throw new Error('signWebhook needs at least one secret');
+    const signatures = secrets.map((s) => `v1=${computeSignature(s, rawBody, timestamp)}`);
+    return `t=${timestamp},${signatures.join(',')}`;
 }
 function parseHeader(header) {
     let timestamp = null;
-    let signature = null;
+    const signatures = [];
     for (const part of header.split(',')) {
         const separator = part.indexOf('=');
         if (separator === -1)
             continue;
-        const key = part.slice(0, separator);
-        const value = part.slice(separator + 1);
+        const key = part.slice(0, separator).trim();
+        const value = part.slice(separator + 1).trim();
         if (key === 't') {
             const parsed = Number(value);
             if (Number.isInteger(parsed))
                 timestamp = parsed;
         }
         else if (key === 'v1') {
-            signature = value;
+            signatures.push(value);
         }
     }
-    if (timestamp === null || signature === null)
+    if (timestamp === null || signatures.length === 0)
         return null;
-    return { timestamp, signature };
+    return { timestamp, signatures };
 }
 /**
  * Constant-time hex-string comparison. Returns false for unequal-length inputs
@@ -49,9 +57,13 @@ function constantTimeEqualHex(a, b) {
 }
 /**
  * Verify a webhook signature header against the raw body.
- * - Parses `t` and `v1` from the header.
+ *
+ * - Parses `t` and EVERY `v1` from the header.
  * - Rejects if the timestamp drifts more than `toleranceSec` from `nowSec`.
- * - Recomputes the expected signature and compares it in constant time.
+ * - Accepts when any `v1` matches the signature computed with any of
+ *   `secret` — so a receiver mid-rotation can pass both of its secrets, and a
+ *   delivery signed during the sender's overlap window verifies against
+ *   either.
  */
 export function verifyWebhook(secret, rawBody, header, toleranceSec, nowSec) {
     const parsed = parseHeader(header);
@@ -59,6 +71,17 @@ export function verifyWebhook(secret, rawBody, header, toleranceSec, nowSec) {
         return false;
     if (Math.abs(nowSec - parsed.timestamp) > toleranceSec)
         return false;
-    const expected = computeSignature(secret, rawBody, parsed.timestamp);
-    return constantTimeEqualHex(expected, parsed.signature);
+    const secrets = typeof secret === 'string' ? [secret] : secret;
+    let matched = false;
+    // Every comparison runs, so the time taken does not say which one matched.
+    for (const candidate of secrets) {
+        if (candidate.length === 0)
+            continue;
+        const expected = computeSignature(candidate, rawBody, parsed.timestamp);
+        for (const signature of parsed.signatures) {
+            if (constantTimeEqualHex(expected, signature))
+                matched = true;
+        }
+    }
+    return matched;
 }

package/dist/types/charge.d.ts

@@ -0,0 +1,56 @@
+import type { CurrencyCode } from './money';
+import type { PaymentIntent } from './paymentIntent';
+/** Card details safe to show: never the number, never the CVC. */
+export interface CardDetails {
+    brand: string | null;
+    last4: string | null;
+    exp_month: number | null;
+    exp_year: number | null;
+    /** ISO 3166-1 alpha-2 of the issuer. */
+    country: string | null;
+    /** `credit`, `debit`, `prepaid` or `unknown`. */
+    funding: string | null;
+}
+export interface ChargeOutcome {
+    /** `approved_by_network`, `declined_by_network`, `not_sent_to_network`, `reversed_after_approval`. */
+    network_status: string | null;
+    /** `normal`, `elevated`, `highest`, or `not_assessed`. */
+    risk_level: string | null;
+    /** `authorized`, `manual_review`, `issuer_declined`, `blocked`, `invalid`. */
+    type: string | null;
+    /** Peable's own one-line explanation for the merchant — never the provider's prose. */
+    seller_message: string | null;
+}
+export interface Charge {
+    id: string;
+    object: 'charge';
+    livemode: boolean;
+    /** `pi_…`, or the {@link PaymentIntent} with `expand[]=payment_intent`. */
+    payment_intent: string | PaymentIntent;
+    customer: string | null;
+    payment_method: string | null;
+    amount: string;
+    amount_captured: string;
+    amount_refunded: string;
+    currency: CurrencyCode;
+    /** Always `succeeded`: Peable records the authorization that succeeded, not failed attempts. */
+    status: 'succeeded';
+    paid: boolean;
+    captured: boolean;
+    /** All of it came back — by refunds, or by releasing an uncaptured authorization. */
+    refunded: boolean;
+    disputed: boolean;
+    outcome: ChargeOutcome | null;
+    payment_method_details: {
+        type: 'card';
+        card: CardDetails;
+    } | null;
+    /** Peable-hosted receipts land with Phase 3; the provider's own URL never reaches the wire. */
+    receipt_url: string | null;
+    /** A Peable balance transaction (`txn_…`) once the ledger exists (Phase 5). */
+    balance_transaction: string | null;
+    description: string | null;
+    receipt_email: string | null;
+    metadata: Record<string, string>;
+    created: number;
+}

package/dist/types/customer.d.ts

@@ -0,0 +1,39 @@
+import type { Address, AddressParams, Shipping, ShippingParams } from './paymentIntent';
+import type { PaymentMethod } from './paymentMethod';
+export interface Customer {
+    id: string;
+    object: 'customer';
+    livemode: boolean;
+    email: string | null;
+    name: string | null;
+    phone: string | null;
+    description: string | null;
+    address: Address | null;
+    shipping: Shipping | null;
+    invoice_settings: {
+        /** `pm_…`, or the {@link PaymentMethod} with `expand[]=invoice_settings.default_payment_method`. */
+        default_payment_method: string | PaymentMethod | null;
+    };
+    metadata: Record<string, string>;
+    created: number;
+}
+/** A deleted customer, as `DELETE /v1/customers/:id` answers. */
+export interface DeletedCustomer {
+    id: string;
+    object: 'customer';
+    deleted: true;
+}
+export interface CreateCustomerParams {
+    email?: string;
+    name?: string;
+    phone?: string;
+    description?: string;
+    address?: AddressParams;
+    shipping?: ShippingParams;
+    invoice_settings?: {
+        default_payment_method?: string;
+    };
+    metadata?: Record<string, string>;
+}
+/** `POST /v1/customers/:id`. A field sent as `""` is cleared; `metadata` is a patch. */
+export type UpdateCustomerParams = CreateCustomerParams;

package/dist/types/dispute.d.ts

@@ -3,8 +3,8 @@ import type { PaymentIntent } from './paymentIntent';
  * A dispute — the card network holding a settled payment's money while a
  * cardholder contests it.
  *
- * Published because `payment_intent.disputed` and `payment_intent.dispute_closed`
- * carry it as their `data.object`. It was route-local at first, with the webhook
+ * Published because `charge.dispute.created`, `charge.dispute.updated` and
+ * `charge.dispute.closed` carry it as their `data.object`. It was route-local at first, with the webhook
  * carrying the PaymentIntent and the detail reachable only through
  * `GET /v1/payment_intents/:id/disputes`. That was inconsistent with the reason
  * those two events exist: `disputed` is a DEADLINE, and a merchant who has to