@peable.to/shared-types 0.10.0 → 0.11.0

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.11.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",