@peable.to/shared-types 0.2.0 → 0.3.1-oxy-one.0

package/dist/esm/paymentIntent.js

@@ -1,22 +1,111 @@
+/** {@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 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.
+ */
+export const CHAIN_ONLY_STATUSES = [
+    'awaiting_approval',
+    'approved',
+    'broadcast',
+    'confirming',
+];
+export const CARD_ONLY_STATUSES = [
+    'requires_action',
+    'processing',
+    'refunded',
+    'partially_refunded',
+];
 /**
  * Legal forward transitions of the PaymentIntent lifecycle. Terminal states
- * (settled/expired/failed/rejected) allow no further transition here — the one
+ * (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.
+ *
+ * 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.
+ *
+ * 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.
  */
 const ALLOWED = {
-    // `created` supports two paths: the rich wallet flow (→ awaiting_approval →
-    // approved → broadcast) AND the minimal path where the payer pays out-of-band
-    // and reports the txid directly (→ broadcast), or the merchant cancels an
-    // unpaid intent (→ rejected). Both are legal forward transitions.
-    created: ['awaiting_approval', 'broadcast', 'rejected', 'expired'],
+    // `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_action',
+        'processing',
+        'settled',
+        'failed',
+        'rejected',
+        'expired',
+    ],
     awaiting_approval: ['approved', 'rejected', 'expired'],
     approved: ['broadcast', 'failed'],
     broadcast: ['confirming', 'failed'],
     confirming: ['settled', 'failed'],
-    settled: [],
+    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: [],
-    failed: [],
     rejected: [],
 };
 export function isValidStatusTransition(from, to) {
@@ -25,3 +114,88 @@ export function isValidStatusTransition(from, to) {
 /** Every legal `PaymentIntentStatus`, derived from `ALLOWED`'s keys — the
  * single source of truth consumed by the Gateway's list-route status filter. */
 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',
+]);
+/**
+ * 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.
+ */
+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;
+}

package/dist/esm/settlement.js

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

package/dist/esm/social.js

@@ -1,4 +1,21 @@
 // Social-receive + transaction-enrichment contracts — shared by the Peable
 // Gateway backend, the wallet frontend, and (indirectly) the enrichment
 // service's callers. Mirrors the Stripe-parity style of paymentIntent.ts.
-export {};
+/**
+ * Longest `SocialPaymentSource.app` the gateway accepts. An app slug, not a
+ * label — 32 characters is more than any Oxy app id needs and short enough that
+ * the column can never become a place to put prose.
+ *
+ * Published with the contract because it is what a request is REFUSED for: a
+ * caller that cannot read the bound from the types finds it out with a 422.
+ */
+export const SOCIAL_SOURCE_APP_MAX_LENGTH = 32;
+/**
+ * Longest `SocialPaymentSource.ref` the gateway accepts.
+ *
+ * The bound is the whole defence here, because the value is opaque: Peable
+ * never parses, resolves or links a `ref`, so nothing downstream would notice
+ * it growing. 128 characters holds any id an app mints (a uuid, a snowflake, a
+ * base64 hash) and refuses a payload.
+ */
+export const SOCIAL_SOURCE_REF_MAX_LENGTH = 128;

package/dist/types/billing.d.ts

@@ -0,0 +1,86 @@
+/** Recurring billing transport. Store/plan references belong to the authenticated app;
+ * they do not identify an Oxy payer or convey entitlements. */
+export declare const BILLING_SUBSCRIPTION_STATUSES: readonly ["incomplete", "incomplete_expired", "trialing", "active", "past_due", "canceled", "unpaid", "paused"];
+export type BillingSubscriptionStatus = (typeof BILLING_SUBSCRIPTION_STATUSES)[number];
+export interface BillingCustomer {
+    providerCustomerId: string;
+}
+export interface EnsureBillingCustomerParams {
+    storeId: string;
+    storeName: string;
+}
+export interface CreateBillingCheckoutParams {
+    providerCustomerId: string;
+    providerPriceId: string;
+    trialDays: number;
+    returnUrl: string;
+    storeId: string;
+    planId: string;
+}
+export interface CreateBillingPortalParams {
+    providerCustomerId: string;
+    returnUrl: string;
+}
+/** Sensitive owner-only URL. The gateway refuses replay after expiresAt. */
+export interface BillingHostedSession {
+    url: string;
+    expiresAt: string;
+}
+/** Provider observations only. Consumers own plan/status/entitlement interpretation. */
+export interface BillingSubscription {
+    providerSubscriptionId: string;
+    /** Discovery only; invoice must still be read and proven paid. */
+    latestInvoiceId?: string | null;
+    providerCustomerId: string;
+    providerPriceId: string;
+    storeId: string;
+    planId: string;
+    livemode: boolean;
+    status: BillingSubscriptionStatus;
+    interval: 'month' | 'year';
+    cancelAtPeriodEnd: boolean;
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    trialEndsAt: string | null;
+    cancelAt: string | null;
+    cancelledAt: string | null;
+}
+/** Owned recurring checkout correlation; completing checkout is not paid evidence. */
+export interface BillingCheckoutSession extends BillingHostedSession {
+    id: string;
+}
+export interface BillingCheckoutObservation {
+    id: string;
+    status: 'open' | 'complete' | 'expired';
+    storeId: string;
+    planId: string;
+    providerCustomerId: string;
+    providerPriceId: string;
+    subscription: BillingSubscription | null;
+}
+/** Authenticated authoritative read, one settled full non-prorated line only.
+ * Tax figures are provider observations, not a tax quote or seller configuration. */
+export interface BillingInvoiceState extends BillingPaidInvoice {
+    chargeId: string;
+    amountRefunded: string;
+    state: 'paid' | 'fully_refunded' | 'partially_refunded';
+}
+export interface BillingPaidInvoice {
+    invoiceId: string;
+    lineId: string;
+    paymentIntentId: string;
+    providerSubscriptionId: string;
+    providerCustomerId: string;
+    providerPriceId: string;
+    storeId: string;
+    planId: string;
+    livemode: boolean;
+    currency: string;
+    amountPaid: string;
+    netAmount: string | null;
+    taxAmount: string | null;
+    periodStart: string;
+    periodEnd: string;
+    paidAt: string;
+    observedAt: string;
+}

package/dist/types/checkoutSession.d.ts

@@ -1,6 +1,7 @@
+import type { CurrencyCode } from './money';
 import type { NetworkType } from './network';
 import type { MerchantDisplay } from './merchantDisplay';
-import type { PaymentIntent } from './paymentIntent';
+import type { PaymentIntent, PaymentIntentRail } from './paymentIntent';
 /** The merchant/SDK-facing DTO — returned on create and by merchant retrieve. */
 export interface CheckoutSession {
     id: string;
@@ -9,7 +10,10 @@ export interface CheckoutSession {
     /** The wrapped intent's `client_secret`, returned to the merchant on create. */
     clientSecret: string;
     amount: string;
-    network: NetworkType;
+    currency: CurrencyCode;
+    rail: PaymentIntentRail;
+    /** FairCoin rail only; `null` on a card session. */
+    network: NetworkType | null;
     metadata: Record<string, string>;
     successUrl?: string;
     cancelUrl?: string;
@@ -34,7 +38,12 @@ export interface CheckoutSessionPublic {
 }
 export interface CreateCheckoutSessionParams {
     amount: string;
-    network: NetworkType;
+    /** Defaults to `'faircoin'`, so pre-ADR-0001 integrations keep working. */
+    rail?: PaymentIntentRail;
+    /** Required on the faircoin rail; refused on the card rail. */
+    network?: NetworkType;
+    /** Defaults to `'FAIR'` on the faircoin rail; required on the card rail. */
+    currency?: CurrencyCode;
     metadata?: Record<string, string>;
     successUrl?: string;
     cancelUrl?: string;

package/dist/types/dispute.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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
+ * 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
+ * make a second call to learn when evidence is due is a merchant who can miss it
+ * while their integration is working exactly as documented.
+ *
+ * It is also what the provider does. Stripe's `charge.dispute.created` carries
+ * the dispute, not the charge — the parity was half-applied.
+ */
+/**
+ * Where the dispute stands.
+ *
+ * `needs_response` and `under_review` are open; `won` and `lost` are terminal
+ * and are the only two that say where the money ended up. There is deliberately
+ * no `closed`: a merchant who is told a dispute "closed" without being told
+ * which way has been given a notification and no information.
+ */
+export type DisputeStatus = 'needs_response' | 'under_review' | 'won' | 'lost';
+export interface Dispute {
+    id: string;
+    object: 'dispute';
+    /** The PUBLIC `pi_…` id, which is what every other contract here calls `id`. */
+    paymentIntentId: string;
+    /**
+     * Amount in the currency's smallest unit as a canonical integer string —
+     * the same encoding every other money field on these contracts uses.
+     *
+     * It is the DISPUTED amount, which may be less than the payment's: a
+     * cardholder can contest part of a charge.
+     */
+    amount: string;
+    currency: string;
+    status: DisputeStatus;
+    /**
+     * The network's reason, verbatim and unmapped.
+     *
+     * Deliberately an open string rather than a closed set. It is the one field a
+     * merchant argues against, and a gateway paraphrase would be the words they
+     * quote while the acquirer holds different ones. `null` when the network sent
+     * none.
+     */
+    reason: string | null;
+    /**
+     * When the network stops accepting evidence, ISO-8601.
+     *
+     * `null` once the dispute is closed — there is no deadline for a decision
+     * already made, and a closed dispute still showing one would put a response
+     * in front of a merchant that can no longer be given.
+     */
+    evidenceDueAt: string | null;
+    /**
+     * When the merchant's response reached the network, ISO-8601. `null` while
+     * none has been submitted.
+     *
+     * The timestamp and nothing else: the evidence itself is forwarded to the
+     * acquirer and never stored here. What it SAID is readable there, by someone
+     * with their own authorization — this gateway does not keep a copy of a
+     * customer's name, address and correspondence.
+     *
+     * Together with `evidenceDueAt` it answers the only two questions a merchant
+     * has about a live dispute: whether they still owe a response, and by when.
+     */
+    evidenceSubmittedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * A merchant's response to a dispute — the whole field set, declared once.
+ *
+ * ## Why this is the wire contract and not four private copies
+ *
+ * It was four: the backend's provider port, the route's zod schema, the Stripe
+ * adapter's name map, and the SDK's params type. Every one of them is the SAME
+ * list, and the cost of them drifting is specific and silent — a field added to
+ * three of the four is one a merchant sends, the gateway accepts, and the
+ * network never sees. They find out when the dispute is decided against them.
+ *
+ * So the set lives here, with the wire contracts, and the other three are
+ * pinned to it: `provider.ts` aliases it, `routes/disputes.ts` declares its
+ * schema `satisfies Record<keyof DisputeEvidence, …>`, and the Stripe adapter's
+ * map is a total `Record<keyof DisputeEvidence, …>`. Adding a field here makes
+ * all three fail to compile until they carry it.
+ *
+ * ## What is not here
+ *
+ * The field NAMES are the network's, spelled the way the rest of these
+ * contracts spell things. They are not a Peable vocabulary and are not mapped
+ * to one: a merchant assembling a defence is reading their acquirer's guidance,
+ * and a gateway that renamed the fields would make that guidance not apply.
+ *
+ * FILE attachments are deliberately absent. They need the provider's upload
+ * API, a size and type policy, and somewhere for the bytes to live on the way
+ * through — and offering half of that would let a merchant submit a defence
+ * missing the receipt it rests on.
+ *
+ * None of it is ever stored. It carries a customer's name, their email, a
+ * billing address and correspondence; it is forwarded to the acquirer and
+ * forgotten. What is recorded is `evidenceSubmittedAt` and nothing more.
+ */
+export interface DisputeEvidence {
+    productDescription?: string;
+    customerName?: string;
+    customerEmailAddress?: string;
+    customerPurchaseIp?: string;
+    billingAddress?: string;
+    shippingAddress?: string;
+    shippingCarrier?: string;
+    shippingDate?: string;
+    shippingTrackingNumber?: string;
+    serviceDate?: string;
+    accessActivityLog?: string;
+    cancellationPolicyDisclosure?: string;
+    cancellationRebuttal?: string;
+    duplicateChargeExplanation?: string;
+    refundPolicyDisclosure?: string;
+    refundRefusalExplanation?: string;
+    uncategorizedText?: string;
+}

package/dist/types/event.d.ts

@@ -1,11 +1,124 @@
+import type { Dispute } from './dispute';
 import type { PaymentIntent } from './paymentIntent';
-export type WebhookEventType = 'payment_intent.confirming' | 'payment_intent.settled' | 'payment_intent.failed' | 'payment_intent.rejected' | 'payment_intent.expired';
-export interface WebhookEvent<T = PaymentIntent> {
-    id: string;
-    object: 'event';
-    type: WebhookEventType;
-    created: string;
-    data: {
-        object: T;
-    };
+import type { ConnectedAccount } from './settlement';
+export type WebhookEventType = 'payment_intent.confirming' | 'payment_intent.settled' | 'payment_intent.failed' | 'payment_intent.rejected' | 'payment_intent.expired'
+/**
+ * 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.
+ */
+/** Wake-up only. Re-read the owner-bound SDK resource; this is never paid or grant authority. */
+export interface BillingObservation {
+    object: 'billing_observation';
+    resourceKind: 'subscription' | 'invoice';
+    resourceId: string;
+    revision: number;
+    observedAt: string;
+}
+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;
+    'connected_account.updated': ConnectedAccount;
 }
+/**
+ * One delivered event.
+ *
+ * A DISCRIMINATED union over every event type, so `data.object` is narrowed by
+ * a switch on `type` with no cast:
+ *
+ * ```ts
+ * if (event.type === 'payment_intent.disputed') {
+ *   event.data.object.evidenceDueAt; // 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`.
+ */
+export type WebhookEvent<K extends WebhookEventType = WebhookEventType> = {
+    [T in K]: {
+        id: string;
+        object: 'event';
+        type: T;
+        created: string;
+        data: {
+            object: WebhookEventPayload[T];
+        };
+    };
+}[K];

package/dist/types/index.d.ts

@@ -1,11 +1,14 @@
-export { UNITS_PER_COIN, isBaseUnitString } from './money';
+export { UNITS_PER_COIN, isBaseUnitString, type CurrencyCode, CURRENCY_CODES, CURRENCY_DECIMALS, decimalsFor, isCurrencyCode, } from './money';
 export { type NetworkType } from './network';
-export { type PaymentIntentStatus, type PaymentIntent, type CreatePaymentIntentParams, isValidStatusTransition, PAYMENT_INTENT_STATUSES, } from './paymentIntent';
-export { type WebhookEventType, type WebhookEvent } from './event';
-export { type WebhookDelivery } from './webhookDelivery';
+export { type PaymentIntentStatus, type PaymentIntentRail, type PaymentIntent, type CreatePaymentIntentParams, isValidStatusTransition, canStillBePaid, reachesSettlementFromPayer, POST_SETTLEMENT_STATUSES, PAYMENT_INTENT_STATUSES, PAYMENT_INTENT_RAILS, CHAIN_ONLY_STATUSES, CARD_ONLY_STATUSES, } from './paymentIntent';
+export { type WebhookEventType, type WebhookEvent, type WebhookEventPayload, type BillingObservation, } from './event';
+export { type Dispute, type DisputeEvidence, type DisputeStatus } from './dispute';
+export { type CapabilityStatus, type ConnectedAccount, type Refund, type RefundOrigin, type RefundStatus, type Settlement, type Transfer, type TransferReversal, type TransferReversalStatus, type TransferStatus, type TransferWithReversal, } from './settlement';
+export { type WebhookDelivery, type WebhookDeliveryStatus, } from './webhookDelivery';
 export { signWebhook, verifyWebhook } from './webhookSigner';
 export { type MerchantEnvironment, type Merchant, MERCHANT_ENVIRONMENTS, } from './merchant';
 export { type MerchantDisplay } from './merchantDisplay';
 export { type PaymentLink, type PublicPaymentLink, type CreatePaymentLinkParams, } from './paymentLink';
 export { type CheckoutSession, type CheckoutSessionPublic, type CreateCheckoutSessionParams, } from './checkoutSession';
-export { type SocialNextAddressResponse, type SocialReceiveCursorResponse, type EnrichmentKind, type EnrichmentResult, type EnrichRequest, type EnrichResponse, } from './social';
+export { SOCIAL_SOURCE_APP_MAX_LENGTH, SOCIAL_SOURCE_REF_MAX_LENGTH, type SocialPaymentSource, type SocialNextAddressRequest, type SocialNextAddressResponse, type SocialReceiveCursorResponse, type SocialPaymentDirection, type SocialPayment, type SocialPaymentsResponse, type EnrichmentKind, type EnrichmentResult, type EnrichRequest, type EnrichResponse, } from './social';
+export { BILLING_SUBSCRIPTION_STATUSES, type BillingSubscriptionStatus, type BillingCheckoutSession, type BillingCheckoutObservation, type BillingPaidInvoice, type BillingInvoiceState, type BillingCustomer, type EnsureBillingCustomerParams, type CreateBillingCheckoutParams, type CreateBillingPortalParams, type BillingHostedSession, type BillingSubscription, } from './billing';

package/dist/types/merchant.d.ts

@@ -6,10 +6,29 @@ export interface Merchant {
     object: 'merchant';
     oxyAppId: string;
     environment: MerchantEnvironment;
-    network: NetworkType;
-    xpub: string;
+    /**
+     * The FairCoin chain this merchant accepts on — `null` on a CARD-ONLY
+     * merchant.
+     *
+     * Nullable TOGETHER with `xpub`: they are two halves of one capability, and
+     * the gateway refuses a registration carrying only one. Registration used to
+     * demand both unconditionally, so a merchant who only wanted to take cards
+     * had to supply a watch-only key for a chain they never intended to use.
+     */
+    network: NetworkType | null;
+    /** `null` on a card-only merchant. Nullable together with `network`. */
+    xpub: string | null;
     webhookUrl?: string;
     requiredConfirmations: number;
+    /**
+     * Payer-facing branding. Absent when unset — `MerchantDisplay` is what a
+     * payer surface renders, and it substitutes a neutral fallback; these are
+     * the raw values the merchant owns.
+     */
+    displayName?: string;
+    /** Bare Oxy file id, not a URL. `MerchantDisplay.avatarUrl` resolves it. */
+    avatarFileId?: string;
+    description?: string;
     createdAt: string;
     updatedAt: string;
 }