@peable.to/shared-types 0.10.0 → 0.12.0

package/dist/types/paymentIntent.d.ts

@@ -1,6 +1,9 @@
-import type { ConnectedAccount } from './settlement';
+import type { Charge } from './charge';
+import type { Customer } from './customer';
 import type { CurrencyCode } from './money';
 import type { NetworkType } from './network';
+import type { PaymentMethod } from './paymentMethod';
+import type { ConnectedAccount } from './settlement';
 /**
  * Which rail moves the money (ADR 0001 D1).
  *
@@ -11,65 +14,157 @@ import type { NetworkType } from './network';
 export type PaymentIntentRail = 'faircoin' | 'card';
 /** {@link PaymentIntentRail} as the tuple the database CHECK reads. */
 export declare const PAYMENT_INTENT_RAILS: readonly PaymentIntentRail[];
-export type PaymentIntentStatus = 'created' | 'awaiting_approval' | 'approved' | 'broadcast' | 'confirming' | 'requires_action' | 'processing' | 'settled' | 'refunded' | 'partially_refunded' | 'expired' | 'failed' | 'rejected';
 /**
- * Which statuses belong to which rail (ADR 0001 D5).
+ * Stripe's seven statuses, and no others (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.
+ * The FairCoin rail walks four of them: it is created in `requires_action`
+ * (the payer must broadcast a transaction — `next_action.faircoin_payment`),
+ * moves to `processing` once a transaction is reported and while it confirms,
+ * and ends `succeeded` or `canceled`. A card walks all seven.
+ */
+export type PaymentIntentStatus = 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'requires_capture' | 'canceled' | 'succeeded';
+/**
+ * The statuses only a CARD payment can reach (ADR 0019).
  *
- * `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 declare const CHAIN_ONLY_STATUSES: readonly PaymentIntentStatus[];
 export declare const CARD_ONLY_STATUSES: readonly PaymentIntentStatus[];
 export declare function isValidStatusTransition(from: PaymentIntentStatus, to: PaymentIntentStatus): boolean;
-/** 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 declare const PAYMENT_INTENT_STATUSES: readonly PaymentIntentStatus[];
+/** The statuses that end a payment: nothing leaves them (bar the reorg exception). */
+export declare const TERMINAL_STATUSES: readonly PaymentIntentStatus[];
 /**
  * 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 declare function canStillBePaid(status: PaymentIntentStatus): boolean;
 /**
- * The statuses a payment reaches only AFTER the payer has finished.
+ * The statuses an intent may still EXPIRE from (ADR 0012 D9).
  *
- * 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.
+ * 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.
+ *
+ * Expiry is a cancellation with `cancellation_reason: 'abandoned'`: a platform
+ * releases a reservation on `payment_intent.canceled`.
  */
-export declare const POST_SETTLEMENT_STATUSES: readonly PaymentIntentStatus[];
+export declare const EXPIRABLE_STATUSES: readonly PaymentIntentStatus[];
+/** Whether an intent in this status can still expire. See {@link EXPIRABLE_STATUSES}. */
+export declare function canExpire(status: PaymentIntentStatus): boolean;
 /**
- * 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.
+ * Why an intent was cancelled — Stripe's reasons, plus `underpaid`.
+ *
+ *  - `abandoned` — it expired: the payer never paid (the expiry sweeper).
+ *  - `requested_by_customer` / `duplicate` / `fraudulent` — the merchant said so
+ *    through `POST /v1/payment_intents/:id/cancel`.
+ *  - `underpaid` — FairCoin only: a transaction arrived at the address and paid
+ *    less than the amount. Peable never holds those coins, so it cannot ask for
+ *    the difference on the same intent; `last_payment_error` says what happened.
+ *  - `automatic` — the provider cancelled it on its own.
+ *
+ * `null` on a cancelled intent whose cause was never recorded (one cancelled
+ * without a reason, or migrated from the pre-0019 `rejected`).
  */
-export declare function reachesSettlementFromPayer(status: PaymentIntentStatus): boolean;
+export type PaymentIntentCancellationReason = 'abandoned' | 'automatic' | 'duplicate' | 'fraudulent' | 'requested_by_customer' | 'underpaid';
+export declare const PAYMENT_INTENT_CANCELLATION_REASONS: readonly PaymentIntentCancellationReason[];
+/** The reasons a MERCHANT may give `POST /v1/payment_intents/:id/cancel`. */
+export declare const MERCHANT_CANCELLATION_REASONS: readonly ["abandoned", "duplicate", "fraudulent", "requested_by_customer"];
+/** When a card is captured: at confirmation, or by `POST …/capture` (card only). */
+export type PaymentIntentCaptureMethod = 'automatic' | 'manual';
+export declare const PAYMENT_INTENT_CAPTURE_METHODS: readonly PaymentIntentCaptureMethod[];
+/** Card only: keep the payment method on the customer for later (ADR 0016). */
+export type PaymentIntentSetupFutureUsage = 'on_session' | 'off_session';
+export declare const PAYMENT_INTENT_SETUP_FUTURE_USAGES: readonly PaymentIntentSetupFutureUsage[];
+/** The payment method types a rail accepts. One per rail today. */
+export type PaymentMethodType = 'card' | 'faircoin';
+/** Why the last attempt failed. Peable's words, never the provider's raw prose. */
+export interface PaymentIntentLastPaymentError {
+    /** `card_error` for a declined card; `payment_error` for a FairCoin underpayment. */
+    type: 'card_error' | 'payment_error' | 'api_error';
+    code: string | null;
+    decline_code: string | null;
+    message: string;
+}
+/** A postal address — Stripe's shape. */
+export interface Address {
+    line1: string | null;
+    line2: string | null;
+    city: string | null;
+    state: string | null;
+    postal_code: string | null;
+    /** ISO 3166-1 alpha-2. */
+    country: string | null;
+}
+export interface Shipping {
+    name: string;
+    phone: string | null;
+    address: Address;
+    carrier: string | null;
+    tracking_number: string | null;
+}
+/** An address as a request carries it: every field optional. */
+export interface AddressParams {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    postal_code?: string;
+    country?: string;
+}
+/** Shipping as a request carries it: only `name` and `address` are required. */
+export interface ShippingParams {
+    name: string;
+    phone?: string;
+    address: AddressParams;
+    carrier?: string;
+    tracking_number?: string;
+}
 /**
- * The statuses an intent may still EXPIRE from (ADR 0012 D9).
+ * What the payer must do next (`status: 'requires_action'`).
  *
- * 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.
+ *  - `faircoin_payment` — send exactly `amount` (base units) to `address` on
+ *    `network`; `uri` is the BIP21-style `faircoin:` URI a wallet scans.
+ *  - `use_peable_sdk` — a card challenge; `@peable.to/sdk/checkout` fetches the
+ *    provider's confirmation credential through `POST …/client_action` and
+ *    completes it. The credential is never on the intent itself.
+ */
+export type PaymentIntentNextAction = {
+    type: 'faircoin_payment';
+    faircoin_payment: {
+        address: string;
+        network: NetworkType;
+        amount: string;
+        currency: 'FAIR';
+        uri: string;
+    };
+} | {
+    type: 'use_peable_sdk';
+};
+/**
+ * The chain side of a FairCoin payment. `null` on a card payment.
  *
- * Stated rather than derived, for `PAYABLE_STATUSES`' reason; the gateway's
- * test suite pins it against the transition table.
+ * `txid` and `confirmations` describe the transaction the payer reported:
+ * `null`/`0` while the intent is `requires_action`, and the watcher's count
+ * against `required_confirmations` while it is `processing`.
  */
-export declare const EXPIRABLE_STATUSES: readonly PaymentIntentStatus[];
-/** Whether an intent in this status can still expire. See {@link EXPIRABLE_STATUSES}. */
-export declare function canExpire(status: PaymentIntentStatus): boolean;
+export interface PaymentIntentFaircoin {
+    network: NetworkType;
+    /** Watch-only receive address derived per intent from the merchant's (or seller's) xpub. */
+    address: string;
+    txid: string | null;
+    confirmations: number;
+    required_confirmations: number;
+}
 export interface PaymentIntent {
     id: string;
     object: 'payment_intent';
@@ -81,83 +176,119 @@ export interface PaymentIntent {
     status: PaymentIntentStatus;
     /** Which rail moves this payment. Decides which fields below are populated. */
     rail: PaymentIntentRail;
+    payment_method_types: PaymentMethodType[];
     /**
      * Amount in the currency's SMALLEST unit as a canonical integer string.
      * Never a float, and never interpretable without `currency`: m⊜ (10^-8 FAIR)
      * on the faircoin rail, cents on a fiat one.
      */
     amount: string;
+    /** What can still be captured: the authorized amount while `requires_capture`, else `"0"`. */
+    amount_capturable: string;
+    /** What was received: the captured amount once `succeeded`, else `"0"`. */
+    amount_received: string;
+    /** The sum of SUCCEEDED refunds on this payment. Refund state lives on the refunds. */
+    amount_refunded: string;
     currency: CurrencyCode;
-    /** FairCoin rail only. `null` on a card payment, which has no network. */
-    network: NetworkType | null;
-    /**
-     * Watch-only receive address derived per-intent from the merchant xpub.
-     * FairCoin rail only; `null` on a card payment, which reserves no address.
-     */
-    address: string | null;
+    capture_method: PaymentIntentCaptureMethod;
+    setup_future_usage: PaymentIntentSetupFutureUsage | null;
+    /** `cus_…`, or the {@link Customer} with `expand[]=customer`. */
+    customer: string | Customer | null;
+    /** `pm_…`, or the {@link PaymentMethod} with `expand[]=payment_method`. Card only. */
+    payment_method: string | PaymentMethod | null;
+    /** `ch_…`, or the {@link Charge} with `expand[]=latest_charge`. Card only. */
+    latest_charge: string | Charge | null;
+    next_action: PaymentIntentNextAction | null;
+    last_payment_error: PaymentIntentLastPaymentError | null;
+    cancellation_reason: PaymentIntentCancellationReason | null;
+    canceled_at: number | null;
+    description: string | null;
+    receipt_email: string | null;
+    /** Card only. */
+    statement_descriptor_suffix: string | null;
+    shipping: Shipping | null;
+    /** The chain side. FairCoin rail only; `null` on a card payment. */
+    faircoin: PaymentIntentFaircoin | null;
+    /** The merchant's PUBLIC `merch_…`. */
     merchant_id: string;
     /**
      * The seller this payment is made ON BEHALF OF (`ca_…`), or `null` for a
      * payment to the merchant itself (ADR 0012 D5). On-behalf payments are
-     * FairCoin only, and `address` derives from that seller's own key.
-     *
-     * The seller's `ca_…`, or the {@link ConnectedAccount} itself when the
-     * request asked for `expand[]=connected_account`.
+     * FairCoin only, and `faircoin.address` derives from that seller's own key.
      */
     connected_account: string | ConnectedAccount | null;
-    txid: string | null;
-    /** On-chain confirmations. Structurally `0` for the whole life of a card payment. */
-    confirmations: number;
     client_secret: string;
     metadata: Record<string, string>;
-    /**
-     * When an UNPAID intent expires. Meaningful only while {@link canExpire}
-     * is true for `status` — see `canExpire` below.
-     */
+    /** When an UNPAID intent expires. Meaningful only while `can_expire`. */
     expires_at: number;
-    /**
-     * Whether this intent can still expire (ADR 0012 D9). `false` once the payer
-     * has reported a broadcast: a FairCoin payment that is `broadcast` or
-     * `confirming` NEVER expires, so a platform must not cancel the order for it.
-     *
-     * Optional in the type only for fixtures written against earlier versions;
-     * a gateway at this version always sends it.
-     */
-    can_expire?: boolean;
+    /** Whether this intent can still expire (ADR 0012 D9). */
+    can_expire: boolean;
     created: number;
     updated_at: number;
 }
+/** `POST /v1/payment_intents`. */
 export interface CreatePaymentIntentParams {
     /** Amount in the currency's smallest unit, as a canonical integer string. */
     amount: string;
-    /**
-     * Defaults to `'faircoin'` — the rail this gateway shipped with, so every
-     * integration written before ADR 0001 keeps working unchanged.
-     */
+    /** Defaults to `'faircoin'`. */
     rail?: PaymentIntentRail;
     /** Required on the faircoin rail; refused on the card rail, which has none. */
     network?: NetworkType;
     /** Defaults to `'FAIR'` on the faircoin rail; required on the card rail. */
     currency?: CurrencyCode;
+    /** Must name the rail's own type: `['card']` or `['faircoin']`. */
+    payment_method_types?: PaymentMethodType[];
+    /** `cus_…`. */
+    customer?: string;
+    /** `pm_…`, card only. A saved payment method of `customer`. */
+    payment_method?: string;
+    /** Card only: confirm in the same call (needs `payment_method`). */
+    confirm?: boolean;
+    /** Card only, with `confirm`: the customer is not present (needs `customer`). */
+    off_session?: boolean;
+    /** Card only. */
+    setup_future_usage?: PaymentIntentSetupFutureUsage;
+    /** Card only. Defaults to `'automatic'`. */
+    capture_method?: PaymentIntentCaptureMethod;
+    receipt_email?: string;
+    description?: string;
+    /** Card only. */
+    statement_descriptor_suffix?: string;
+    shipping?: ShippingParams;
     metadata?: Record<string, string>;
     expires_in_seconds?: number;
-    /**
-     * Create the payment ON BEHALF OF this connected account (`ca_…`) — the
-     * address derives from the seller's own key and the coins go straight to
-     * their wallet (ADR 0012 D5). FairCoin only: combined with `rail: 'card'` it
-     * is refused. The account's FairCoin half must be `active` and `network`
-     * must be the account's network.
-     */
+    /** FairCoin only: pay this seller (`ca_…`, ADR 0012 D5). */
     connected_account?: string;
+    /** Card only, with `confirm`: where a redirect-based challenge returns. */
+    return_url?: string;
 }
 /**
- * `POST /v1/payment_intents/:id`. Only the merchant's own `metadata` is
- * mutable on an intent: everything else is either the payment itself or the
- * state machine's, which moves only through its own operations.
- *
- * `metadata` is a PATCH: named keys are set, a key sent as `""` is removed,
- * keys not named are kept.
+ * `POST /v1/payment_intents/:id`. The merchant's own bookkeeping only —
+ * the amount, rail and status are the payment and move through their own
+ * operations. `metadata` is a PATCH (`""` unsets a key).
  */
 export interface UpdatePaymentIntentParams {
     metadata?: Record<string, string>;
+    description?: string;
+    receipt_email?: string;
+    shipping?: ShippingParams;
+}
+/** `POST /v1/payment_intents/:id/confirm` (card only). */
+export interface ConfirmPaymentIntentParams {
+    /** `pm_…`; defaults to the intent's own. */
+    payment_method?: string;
+    off_session?: boolean;
+    setup_future_usage?: PaymentIntentSetupFutureUsage;
+    return_url?: string;
+    receipt_email?: string;
+    shipping?: ShippingParams;
+}
+/** `POST /v1/payment_intents/:id/capture` (card only, `requires_capture`). */
+export interface CapturePaymentIntentParams {
+    /** Base units, at most the authorized amount; defaults to all of it. */
+    amount_to_capture?: string;
+}
+/** `POST /v1/payment_intents/:id/cancel`. */
+export interface CancelPaymentIntentParams {
+    cancellation_reason?: (typeof MERCHANT_CANCELLATION_REASONS)[number];
 }

package/dist/types/paymentMethod.d.ts

@@ -0,0 +1,33 @@
+import type { CardDetails } from './charge';
+import type { Customer } from './customer';
+import type { Address, AddressParams } from './paymentIntent';
+export interface BillingDetails {
+    address: Address | null;
+    email: string | null;
+    name: string | null;
+    phone: string | null;
+}
+export interface PaymentMethod {
+    id: string;
+    object: 'payment_method';
+    livemode: boolean;
+    type: 'card';
+    card: CardDetails;
+    billing_details: BillingDetails;
+    /** `cus_…`, or the {@link Customer} with `expand[]=customer`; `null` once detached. */
+    customer: string | Customer | null;
+    metadata: Record<string, string>;
+    created: number;
+}
+export interface UpdatePaymentMethodParams {
+    billing_details?: {
+        address?: AddressParams;
+        email?: string;
+        name?: string;
+        phone?: string;
+    };
+    metadata?: Record<string, string>;
+}
+export interface AttachPaymentMethodParams {
+    customer: string;
+}

package/dist/types/settlement.d.ts

@@ -229,15 +229,6 @@ export interface Refund {
     amount: string;
     currency: CurrencyCode | string;
     status: RefundStatus;
-    /**
-     * Where the PAYMENT stands after this refund.
-     *
-     * On the refund deliberately: a caller that has just refunded needs to know
-     * whether the payment is now `partially_refunded` or `refunded`, and making
-     * them re-read the intent is a round trip whose answer can move on before it
-     * arrives.
-     */
-    payment_status: string;
     failure_code: string | null;
     created: number;
     updated_at: number;

package/dist/types/setupIntent.d.ts

@@ -0,0 +1,39 @@
+import type { Customer } from './customer';
+import type { PaymentIntentLastPaymentError } from './paymentIntent';
+import type { PaymentMethod } from './paymentMethod';
+export type SetupIntentStatus = 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'canceled' | 'succeeded';
+export declare const SETUP_INTENT_STATUSES: readonly SetupIntentStatus[];
+export type SetupIntentUsage = 'on_session' | 'off_session';
+export type SetupIntentCancellationReason = 'abandoned' | 'duplicate' | 'requested_by_customer';
+export interface SetupIntent {
+    id: string;
+    object: 'setup_intent';
+    livemode: boolean;
+    status: SetupIntentStatus;
+    usage: SetupIntentUsage;
+    payment_method_types: ['card'];
+    /** `cus_…`, or the {@link Customer} with `expand[]=customer`. */
+    customer: string | Customer | null;
+    /** The `pm_…` it saved, once `succeeded`. */
+    payment_method: string | PaymentMethod | null;
+    /** Possession of it lets the payer's browser confirm this SetupIntent. */
+    client_secret: string;
+    next_action: {
+        type: 'use_peable_sdk';
+    } | null;
+    last_setup_error: PaymentIntentLastPaymentError | null;
+    cancellation_reason: SetupIntentCancellationReason | null;
+    description: string | null;
+    metadata: Record<string, string>;
+    created: number;
+}
+export interface CreateSetupIntentParams {
+    customer?: string;
+    usage?: SetupIntentUsage;
+    payment_method_types?: ['card'];
+    description?: string;
+    metadata?: Record<string, string>;
+}
+export interface CancelSetupIntentParams {
+    cancellation_reason?: SetupIntentCancellationReason;
+}

package/dist/types/webhookDelivery.d.ts

@@ -2,52 +2,35 @@ import type { WebhookEventType } from './event';
 /**
  * Where one webhook delivery stands (ADR 0001 D7).
  *
- * Was `'delivered' | 'failed'` — the two outcomes an inline, best-effort
- * delivery could report once it had already given up. Delivery is now a durable
- * outbox, so a delivery exists BEFORE any attempt and this set has to say so.
- *
- *  - `pending`   — enqueued and will be attempted. `nextAttemptAt` says when.
+ *  - `pending`   — will be attempted. `next_attempt_at` says when.
  *  - `delivered` — terminal success.
- *  - `failed`    — the endpoint REFUSED it (a 4xx, a blocked address). No retry
+ *  - `failed`    — the endpoint REFUSED it (a 4xx, a blocked address), or the
+ *                  endpoint was disabled before it could be attempted. No retry
  *                  can fix that, so none is made.
- *  - `dead`      — every attempt failed transiently and the budget ran out. The
- *                  envelope is kept and can be redelivered by hand.
- *
- * ⚠️ Widening a published union is a breaking change for a consumer that
- * switches exhaustively on it. It is the honest shape: the previous one could
- * not describe a delivery that had not been attempted yet, which is now the
- * state every delivery starts in.
+ *  - `dead`      — every attempt failed transiently over three days and the
+ *                  budget ran out. It can be redelivered by hand.
  */
 export type WebhookDeliveryStatus = 'pending' | 'delivered' | 'failed' | 'dead';
+/**
+ * One event sent to one webhook endpoint (ADR 0014 D4). An event that matches
+ * three endpoints is three deliveries, each with its own attempts.
+ */
 export interface WebhookDelivery {
     id: string;
     object: 'webhook_delivery';
-    /**
-     * Which of the provider's two worlds this object belongs to (ADR 0017):
-     * `true` for a `production` merchant, `false` for every other environment.
-     */
+    /** The mode of the merchant it was sent for (ADR 0017). */
     livemode: boolean;
-    merchant_id: string;
-    /**
-     * The `pi_…` this delivery is about — `null` when the event is not about a
-     * payment.
-     *
-     * Nullable since `connected_account.updated`, which is about a SELLER. The
-     * alternative was to name an unrelated payment to keep the field a string,
-     * which is worse than a null: a consumer correlating on it would attach a
-     * seller's readiness change to a payment that has nothing to do with it.
-     */
-    intent_id: string | null;
+    /** The `evt_…` delivered — `GET /v1/events/:id` returns it. */
     event_id: string;
     event_type: WebhookEventType;
+    /** The `we_…` it was sent to. */
+    webhook_endpoint_id: string;
+    /** The URL actually POSTed to, as of the latest attempt. */
     url: string;
     attempts: number;
     delivered: boolean;
     last_status: WebhookDeliveryStatus;
-    /**
-     * Why the last attempt did not succeed — operator-facing, never a secret.
-     * Absent while pending with no attempts, and after a success.
-     */
+    /** Why the last attempt did not succeed — operator-facing, never a secret. */
     last_error?: string;
     /** When the next attempt is due, Unix seconds. Absent once the delivery is terminal. */
     next_attempt_at?: number;

package/dist/types/webhookEndpoint.d.ts

@@ -0,0 +1,81 @@
+import type { WebhookEventType } from './event';
+/**
+ * A webhook endpoint (`we_…`) — one URL a merchant receives events at, with
+ * the event types it wants and the secret deliveries to it are signed with
+ * (ADR 0014 D4).
+ *
+ * A merchant may hold several; every event fans out to each ENABLED endpoint
+ * whose `enabled_events` matches it, as one delivery per endpoint.
+ */
+/** `'*'` subscribes to every event type, including ones added later. */
+export type WebhookEnabledEvent = WebhookEventType | '*';
+export declare const WEBHOOK_ENDPOINT_STATUSES: readonly ["enabled", "disabled"];
+export type WebhookEndpointStatus = (typeof WEBHOOK_ENDPOINT_STATUSES)[number];
+/**
+ * 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 declare const WEBHOOK_ENDPOINT_DISABLED_REASONS: readonly ["disabled_by_merchant", "delivery_failures"];
+export type WebhookEndpointDisabledReason = (typeof WEBHOOK_ENDPOINT_DISABLED_REASONS)[number];
+/** At most this many endpoints per merchant (per mode). */
+export declare const WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = 16;
+/** The longest a rolled secret may keep signing beside its replacement. */
+export declare const WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS: number;
+export interface WebhookEndpoint {
+    id: string;
+    object: 'webhook_endpoint';
+    /** The mode of the merchant that owns it (ADR 0017). */
+    livemode: boolean;
+    url: string;
+    description: string | null;
+    enabled_events: WebhookEnabledEvent[];
+    status: WebhookEndpointStatus;
+    /** `null` exactly when `status` is `enabled`. */
+    disabled_reason: WebhookEndpointDisabledReason | null;
+    /** The wire version events are rendered with for this endpoint. */
+    api_version: string;
+    metadata: Record<string, string>;
+    /**
+     * The signing secret (`whsec_…`). Present ONLY on the response that
+     * created it — the create, and a `roll_secret`. Peable never shows it again;
+     * a lost secret is rolled, not retrieved.
+     */
+    secret?: string;
+    created: number;
+    updated_at: number;
+}
+/** What `DELETE /v1/webhook_endpoints/:id` answers. */
+export interface DeletedWebhookEndpoint {
+    id: string;
+    object: 'webhook_endpoint';
+    deleted: true;
+}
+export interface CreateWebhookEndpointParams {
+    /** An `https` URL (a test-mode endpoint may also use `http`), ports 80/443 only. */
+    url: string;
+    enabled_events: WebhookEnabledEvent[];
+    description?: string;
+    metadata?: Record<string, string>;
+}
+export interface UpdateWebhookEndpointParams {
+    url?: string;
+    enabled_events?: WebhookEnabledEvent[];
+    /** `true` stops deliveries; `false` re-enables an endpoint, whatever disabled it. */
+    disabled?: boolean;
+    /** `''` clears it. */
+    description?: string;
+    /** Merged: named keys are set, a key sent as `''` is removed. */
+    metadata?: Record<string, string>;
+}
+export interface RollWebhookEndpointSecretParams {
+    /**
+     * How long the PREVIOUS secret keeps signing beside the new one, in seconds
+     * (0–86400, default 0). While both are live every delivery carries two
+     * `v1=` signatures, so a receiver can switch secrets without a gap.
+     */
+    expires_in_seconds?: number;
+}

package/dist/types/webhookSigner.d.ts

@@ -1,12 +1,20 @@
 /**
  * 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 declare function signWebhook(secret: string, rawBody: string, timestamp: number): string;
+export declare function signWebhook(secret: string | readonly string[], rawBody: string, timestamp: number): string;
 /**
  * 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 declare function verifyWebhook(secret: string, rawBody: string, header: string, toleranceSec: number, nowSec: number): boolean;
+export declare function verifyWebhook(secret: string | readonly string[], rawBody: string, header: string, toleranceSec: number, nowSec: number): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/shared-types",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Shared TypeScript types for the Peable Gateway — the wire contract shared by the backend, SDK, and frontend.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",