@peable.to/shared-types 0.10.0 → 0.12.0

package/dist/types/event.d.ts

@@ -1,73 +1,18 @@
+import type { Charge } from './charge';
+import type { Coupon, Price, Product, PromotionCode } from './catalog';
+import type { Customer } from './customer';
 import type { Dispute } from './dispute';
 import type { PaymentIntent } from './paymentIntent';
-import type { ConnectedAccount } from './settlement';
-export type WebhookEventType = 'payment_intent.confirming' | 'payment_intent.settled' | 'payment_intent.failed' | 'payment_intent.rejected' | 'payment_intent.expired'
+import type { PaymentMethod } from './paymentMethod';
+import type { ConnectedAccount, Refund } from './settlement';
+import type { SetupIntent } from './setupIntent';
+import type { WebhookEndpoint } from './webhookEndpoint';
 /**
- * Money went back to the payer.
- *
- * Both of these exist for the refund a merchant did NOT initiate — one made
- * from the provider's own dashboard, or a dispute the network resolved
- * against the merchant. A merchant who only ever learned about their own
- * refunds would reconcile to a balance that disagrees with the provider's,
- * with nothing to explain the difference.
- *
- * Additive to a published contract: an existing consumer that switches on
- * this union keeps compiling and simply never matches them.
- */
- | 'payment_intent.refunded' | 'payment_intent.partially_refunded'
-/**
- * The network is holding this payment's money while a cardholder contests it.
- *
- * Two events and not one because the two moments demand different things of a
- * merchant. `disputed` is a DEADLINE — evidence is due, and a merchant who
- * learns about it late has already lost. `dispute_closed` carries the outcome,
- * which is when the money is finally theirs or finally gone.
- *
- * Neither is a payment-intent STATUS. A dispute is the network's process, not
- * a stage of the payment's lifecycle — the payment stayed `settled` throughout
- * and may end there. That is also how Stripe models it: a charge is
- * `disputed`, a PaymentIntent has no such status.
- *
- * These two carry a {@link Dispute} as their `data.object`, NOT the payment
- * intent — see {@link WebhookEventPayload}. The `paymentIntentId` on it is
- * how a consumer gets back to the payment.
- *
- * Additive to a published contract: an existing consumer that switches on
- * this union keeps compiling and simply never matches them.
- */
- | 'payment_intent.disputed' | 'payment_intent.dispute_closed'
-/**
- * A seller's account changed — their READINESS, in practice.
- *
- * The first event here that is not about a payment, and it exists because
- * readiness is the one fact about a seller a marketplace cannot act without
- * and could not learn: the gateway refreshed the account row from the
- * provider and told the merchant nothing, so the only ways to find out a
- * seller had finished onboarding were to poll `GET /v1/connected_accounts`
- * or to attempt a settlement and read the refusal.
- *
- * Emitted when the fields a merchant ACTS on change — payability, the two
- * capabilities, the requirement counts, the disabled reasons — and not on
- * every refresh. A periodic sync sweep re-reads every account whether or not
- * anything moved, and an event per sweep would be a stream a merchant learns
- * to ignore.
- *
- * It carries a {@link ConnectedAccount} and its delivery names NO payment
- * intent, which is why `WebhookDelivery.intentId` is nullable.
- *
- * Additive to a published contract: an existing consumer that switches on
- * this union keeps compiling and simply never matches it.
- */
- | 'connected_account.updated' | 'billing.observation.updated';
-/**
- * Which resource each event type carries under `data.object`.
- *
- * TOTAL over `WebhookEventType`, so a new event type cannot be added without
- * saying what it delivers. That matters more here than anywhere else in this
- * contract: `data.object` is the whole payload, and an event type added with
- * the default would silently ship a PaymentIntent to a consumer expecting
- * something else — which typechecks on both sides and fails only in production.
+ * The wire date every response names in `Peable-Version`, and the
+ * `api_version` an event is stored under (ADR 0014 D2/D4). One constant, so
+ * the header and the stored events cannot name two different wires.
  */
+export declare const PEABLE_API_VERSION = "2026-11-03";
 /** Wake-up only. Re-read the owner-bound SDK resource; this is never paid or grant authority. */
 export interface BillingObservation {
     object: 'billing_observation';
@@ -80,18 +25,101 @@ export interface BillingObservation {
     revision: number;
     observed_at: number;
 }
+/**
+ * Which resource each event type carries under `data.object`.
+ *
+ * TOTAL over {@link WebhookEventType} (which is derived from its keys), so a new
+ * event type cannot exist without saying what it delivers: an event added with
+ * a default would silently ship a PaymentIntent to a consumer expecting
+ * something else — which typechecks on both sides and fails only in production.
+ *
+ * The `payment_intent.*` events follow the status the intent reached
+ * (ADR 0019): `created` when it is minted, then one per transition —
+ * `requires_action`, `processing`, `amount_capturable_updated` (authorized,
+ * awaiting capture), `succeeded`, `payment_failed` (an attempt failed; a card
+ * returns to `requires_payment_method`, a FairCoin underpayment is also
+ * `canceled`) and `canceled` (by the merchant, by expiry — `abandoned` — or
+ * underpaid).
+ *
+ * Refunds are not PaymentIntent statuses: `refund.created|updated|failed` carry
+ * the Refund, and `charge.refunded` the Charge whose `amount_refunded` moved.
+ * A dispute is the network's process beside a payment that stays `succeeded`:
+ * `charge.dispute.created` is a DEADLINE (evidence is due), `closed` carries
+ * the outcome.
+ */
 export interface WebhookEventPayload {
-    'billing.observation.updated': BillingObservation;
-    'payment_intent.confirming': PaymentIntent;
-    'payment_intent.settled': PaymentIntent;
-    'payment_intent.failed': PaymentIntent;
-    'payment_intent.rejected': PaymentIntent;
-    'payment_intent.expired': PaymentIntent;
-    'payment_intent.refunded': PaymentIntent;
-    'payment_intent.partially_refunded': PaymentIntent;
-    'payment_intent.disputed': Dispute;
-    'payment_intent.dispute_closed': Dispute;
+    'payment_intent.created': PaymentIntent;
+    'payment_intent.requires_action': PaymentIntent;
+    'payment_intent.processing': PaymentIntent;
+    'payment_intent.amount_capturable_updated': PaymentIntent;
+    'payment_intent.succeeded': PaymentIntent;
+    'payment_intent.payment_failed': PaymentIntent;
+    'payment_intent.canceled': PaymentIntent;
+    'charge.refunded': Charge;
+    'charge.dispute.created': Dispute;
+    'charge.dispute.updated': Dispute;
+    'charge.dispute.closed': Dispute;
+    'refund.created': Refund;
+    'refund.updated': Refund;
+    'refund.failed': Refund;
+    'customer.created': Customer;
+    'customer.updated': Customer;
+    'customer.deleted': Customer;
+    'payment_method.attached': PaymentMethod;
+    'payment_method.detached': PaymentMethod;
+    'payment_method.updated': PaymentMethod;
+    'setup_intent.created': SetupIntent;
+    'setup_intent.requires_action': SetupIntent;
+    'setup_intent.succeeded': SetupIntent;
+    'setup_intent.setup_failed': SetupIntent;
+    'setup_intent.canceled': SetupIntent;
+    /**
+     * The catalog (ADR 0018): each create, update and delete of a product,
+     * price, coupon or promotion code, carrying the object as it stands after
+     * the change (a deleted one as it stood before). An update names the moved
+     * fields in `data.previous_attributes`; an update that moved nothing records
+     * no event. Prices and promotion codes are never deleted — they are archived
+     * with `active: false` — so there is no `price.deleted` or
+     * `promotion_code.deleted`: a type that can never be sent is a promise the
+     * catalog cannot keep.
+     */
+    'product.created': Product;
+    'product.updated': Product;
+    'product.deleted': Product;
+    'price.created': Price;
+    'price.updated': Price;
+    'coupon.created': Coupon;
+    'coupon.updated': Coupon;
+    'coupon.deleted': Coupon;
+    'promotion_code.created': PromotionCode;
+    'promotion_code.updated': PromotionCode;
+    /**
+     * A seller's account changed — their READINESS, in practice. Emitted when the
+     * fields a merchant ACTS on change, not on every refresh. It names no payment
+     * intent.
+     */
     'connected_account.updated': ConnectedAccount;
+    'billing.observation.updated': BillingObservation;
+    /**
+     * A synthetic event sent to ONE endpoint when its owner asks to test it
+     * (Orbit's "send test event"). Stored like any other event, but it never fans
+     * out and it cannot be subscribed to: `enabled_events` refuses it. The
+     * endpoint being tested, as `GET /v1/webhook_endpoints/:id` returns it.
+     */
+    'webhook_endpoint.test': WebhookEndpoint;
+}
+/** Every event type, Stripe's names. */
+export type WebhookEventType = keyof WebhookEventPayload;
+/**
+ * What caused an event, when an API request did (Stripe's `event.request`).
+ * Both `null` for an event caused by something else — the chain watcher, the
+ * expiry sweeper, a provider's own notification.
+ */
+export interface WebhookEventRequest {
+    /** The `Request-Id` of the request whose change produced the event. */
+    id: string | null;
+    /** The `Idempotency-Key` that request carried, if any. */
+    idempotency_key: string | null;
 }
 /**
  * One delivered event.
@@ -100,20 +128,13 @@ export interface WebhookEventPayload {
  * a switch on `type` with no cast:
  *
  * ```ts
- * if (event.type === 'payment_intent.disputed') {
+ * if (event.type === 'charge.dispute.created') {
  *   event.data.object.evidence_due_at; // Dispute, not PaymentIntent
  * }
  * ```
  *
- * That correlation is the whole point of building it this way rather than as
- * `{ type: WebhookEventType; data: { object: PaymentIntent | Dispute } }`,
- * which typechecks identically at the boundary and then lets a consumer read a
- * `Dispute`'s fields off a settlement.
- *
- * The parameter narrows to a subset of event types — `WebhookEvent<'payment_intent.disputed'>`
- * is the dispute event alone. It takes an event TYPE and not a payload type,
- * because the payload is derivable from the event and the reverse is not: two
- * event types share `Dispute`.
+ * The parameter narrows to a subset of event types —
+ * `WebhookEvent<'payment_intent.succeeded'>` is that event alone.
  */
 export type WebhookEvent<K extends WebhookEventType = WebhookEventType> = {
     [T in K]: {
@@ -126,13 +147,23 @@ export type WebhookEvent<K extends WebhookEventType = WebhookEventType> = {
         /**
          * The connected account (`ca_…`) this event is about — Stripe's
          * `event.account` (ADR 0012 D7). Present on every event for an on-behalf
-         * payment and on `connected_account.updated`; absent on events about the
-         * merchant's own payments. Lets a platform route an event to a seller
-         * without opening `data.object`.
+         * payment and on `connected_account.updated`; absent otherwise.
          */
         account?: string;
+        /**
+         * The wire version the event was rendered with — the `Peable-Version` of
+         * the deployment that stored it. An event is a stored snapshot; it is not
+         * re-rendered when the wire moves on.
+         */
+        api_version: string;
         data: {
             object: WebhookEventPayload[T];
+            /**
+             * The fields of `object` that this change moved, with their values
+             * BEFORE it. Absent when the event is not a change of an existing object.
+             */
+            previous_attributes?: Record<string, unknown>;
         };
+        request: WebhookEventRequest;
     };
 }[K];

package/dist/types/index.d.ts

@@ -1,8 +1,14 @@
 export { UNITS_PER_COIN, isBaseUnitString, type CurrencyCode, CURRENCY_CODES, CURRENCY_DECIMALS, decimalsFor, isCurrencyCode, } from './money';
 export type { NetworkType } from './network';
 export type { ExpandParams, List, ListParams, RangeQuery } from './list';
-export { type PaymentIntentStatus, type PaymentIntentRail, type PaymentIntent, type CreatePaymentIntentParams, type UpdatePaymentIntentParams, isValidStatusTransition, canStillBePaid, reachesSettlementFromPayer, POST_SETTLEMENT_STATUSES, PAYMENT_INTENT_STATUSES, PAYMENT_INTENT_RAILS, CHAIN_ONLY_STATUSES, CARD_ONLY_STATUSES, EXPIRABLE_STATUSES, canExpire, } from './paymentIntent';
-export type { WebhookEventType, WebhookEvent, WebhookEventPayload, BillingObservation, } from './event';
+export { type Address, type AddressParams, type CancelPaymentIntentParams, type CapturePaymentIntentParams, type ConfirmPaymentIntentParams, type CreatePaymentIntentParams, type PaymentIntent, type PaymentIntentCancellationReason, type PaymentIntentCaptureMethod, type PaymentIntentFaircoin, type PaymentIntentLastPaymentError, type PaymentIntentNextAction, type PaymentIntentRail, type PaymentIntentSetupFutureUsage, type PaymentIntentStatus, type PaymentMethodType, type Shipping, type ShippingParams, type UpdatePaymentIntentParams, CARD_ONLY_STATUSES, EXPIRABLE_STATUSES, MERCHANT_CANCELLATION_REASONS, PAYMENT_INTENT_CANCELLATION_REASONS, PAYMENT_INTENT_CAPTURE_METHODS, PAYMENT_INTENT_RAILS, PAYMENT_INTENT_SETUP_FUTURE_USAGES, PAYMENT_INTENT_STATUSES, TERMINAL_STATUSES, canExpire, canStillBePaid, isValidStatusTransition, } from './paymentIntent';
+export type { CardDetails, Charge, ChargeOutcome } from './charge';
+export type { CreateCustomerParams, Customer, DeletedCustomer, UpdateCustomerParams, } from './customer';
+export type { AttachPaymentMethodParams, BillingDetails, PaymentMethod, UpdatePaymentMethodParams, } from './paymentMethod';
+export { type CancelSetupIntentParams, type CreateSetupIntentParams, type SetupIntent, type SetupIntentCancellationReason, type SetupIntentStatus, type SetupIntentUsage, SETUP_INTENT_STATUSES, } from './setupIntent';
+export { PEABLE_API_VERSION, type WebhookEventType, type WebhookEvent, type WebhookEventPayload, type WebhookEventRequest, type BillingObservation, } from './event';
+export { WEBHOOK_ENDPOINT_STATUSES, WEBHOOK_ENDPOINT_DISABLED_REASONS, WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT, WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS, type WebhookEnabledEvent, type WebhookEndpoint, type WebhookEndpointStatus, type WebhookEndpointDisabledReason, type DeletedWebhookEndpoint, type CreateWebhookEndpointParams, type UpdateWebhookEndpointParams, type RollWebhookEndpointSecretParams, } from './webhookEndpoint';
+export { PRICE_BILLING_SCHEMES, PRICE_TIERS_MODES, PRICE_TYPES, RECURRING_INTERVALS, RECURRING_USAGE_TYPES, PRICE_TAX_BEHAVIORS, TRANSFORM_QUANTITY_ROUNDS, COUPON_DURATIONS, CATALOG_LIMITS, type PriceBillingScheme, type PriceTiersMode, type PriceType, type RecurringInterval, type RecurringUsageType, type PriceTaxBehavior, type TransformQuantityRound, type CouponDuration, type ProductMarketingFeature, type Product, type DeletedProduct, type PriceTier, type PriceTransformQuantity, type PriceRecurring, type Price, type Coupon, type DeletedCoupon, type PromotionCodeRestrictions, type PromotionCode, type RecurringParams, type PriceTierParams, type PriceDataParams, type DefaultPriceDataParams, type CreateProductParams, type UpdateProductParams, type ProductListParams, type CreatePriceParams, type UpdatePriceParams, type PriceListParams, type CreateCouponParams, type UpdateCouponParams, type CouponListParams, type CreatePromotionCodeParams, type UpdatePromotionCodeParams, type PromotionCodeListParams, } from './catalog';
 export type { Dispute, DisputeEvidence, DisputeStatus } from './dispute';
 export type { CapabilityStatus, ConnectedAccount, ConnectedAccountFaircoin, ConnectedAccountFaircoinStatus, ConnectedAccountRail, Refund, RefundOrigin, RefundStatus, Settlement, Transfer, TransferReversal, TransferReversalStatus, TransferStatus, TransferWithReversal, } from './settlement';
 export type { WebhookDelivery, WebhookDeliveryStatus, } from './webhookDelivery';

package/dist/types/merchant.d.ts

@@ -23,7 +23,6 @@ export interface Merchant {
     network: NetworkType | null;
     /** `null` on a card-only merchant. Nullable together with `network`. */
     xpub: string | null;
-    webhook_url?: string;
     required_confirmations: number;
     /**
      * Payer-facing branding. Absent when unset — `MerchantDisplay` is what a