@peable.to/shared-types 0.6.0 → 0.8.0

package/dist/cjs/dispute.js

@@ -1,17 +1,2 @@
 "use strict";
-/**
- * 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.
- */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/list.js

@@ -0,0 +1,3 @@
+"use strict";
+// The one list contract (ADR 0014 D1), for every list endpoint.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/tax.js

@@ -1,4 +1,6 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAX_LOCATION_EVIDENCE_TYPES = exports.TAX_REGISTRATION_SCHEMES = void 0;
 /**
  * Peable Tax — the wire contract.
  *
@@ -11,8 +13,6 @@
  *
  * Amounts are integers in the currency's minor unit, like the billing quote.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TAX_LOCATION_EVIDENCE_TYPES = exports.TAX_REGISTRATION_SCHEMES = void 0;
 /** How a registration lets the seller collect. `standard`/`simplified` cover
  * one country; the EU One-Stop-Shop schemes cover every EU member state from
  * one identification state; the US is per state; Canadian PST/QST is per

package/dist/esm/dispute.js

@@ -1,16 +1 @@
-/**
- * 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.
- */
 export {};

package/dist/esm/list.js

@@ -0,0 +1,2 @@
+// The one list contract (ADR 0014 D1), for every list endpoint.
+export {};

package/dist/types/checkoutSession.d.ts

@@ -3,11 +3,18 @@ import type { CurrencyCode } from './money';
 import type { NetworkType } from './network';
 import type { MerchantDisplay } from './merchantDisplay';
 import type { PaymentIntent, PaymentIntentRail } from './paymentIntent';
+import type { ConnectedAccount } from './settlement';
 /** The merchant/SDK-facing DTO — returned on create and by merchant retrieve. */
 export interface CheckoutSession {
     id: string;
     object: 'checkout_session';
-    payment_intent_id: string;
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
+    /** The wrapped payment's `pi_…`, or the {@link PaymentIntent} with `expand[]=payment_intent`. */
+    payment_intent: string | PaymentIntent;
     /** The wrapped intent's `client_secret`, returned to the merchant on create. */
     client_secret: string;
     amount: string;
@@ -16,10 +23,10 @@ export interface CheckoutSession {
     /** FairCoin rail only; `null` on a card session. */
     network: NetworkType | null;
     /**
-     * The seller the wrapped payment is made on behalf of (`ca_…`), or `null`
-     * (ADR 0012 D5). Optional in the type for older fixtures; always sent.
+     * The seller the wrapped payment is made on behalf of (`ca_…`, or the
+     * object with `expand[]=connected_account`), or `null` (ADR 0012 D5).
      */
-    connected_account_id?: string | null;
+    connected_account: string | ConnectedAccount | null;
     metadata: Record<string, string>;
     success_url?: string;
     cancel_url?: string;
@@ -39,6 +46,11 @@ export interface CheckoutSessionPublic {
     billing_quote?: BillingFaircoinFxQuote;
     id: string;
     object: 'checkout_session';
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
     success_url?: string;
     cancel_url?: string;
     merchant: MerchantDisplay;
@@ -58,3 +70,7 @@ export interface CreateCheckoutSessionParams {
     /** Pay this seller (`ca_…`) rather than the merchant — see `CreatePaymentIntentParams.connectedAccount`. */
     connected_account?: string;
 }
+/** `POST /v1/checkout_sessions/:id` — the merchant's `metadata`, as a patch. */
+export interface UpdateCheckoutSessionParams {
+    metadata?: Record<string, string>;
+}

package/dist/types/connect.d.ts

@@ -34,6 +34,11 @@ export interface ConnectOnboardingComplete {
  */
 export interface AccountLink {
     object: 'account_link';
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
     url: string;
     expires_at: number;
 }

package/dist/types/dispute.d.ts

@@ -1,3 +1,4 @@
+import type { PaymentIntent } from './paymentIntent';
 /**
  * A dispute — the card network holding a settled payment's money while a
  * cardholder contests it.
@@ -25,8 +26,13 @@ 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`. */
-    payment_intent_id: string;
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
+    /** The disputed payment's `pi_…`, or the {@link PaymentIntent} with `expand[]=payment_intent`. */
+    payment_intent: string | PaymentIntent;
     /**
      * Amount in the currency's smallest unit as a canonical integer string —
      * the same encoding every other money field on these contracts uses.

package/dist/types/event.d.ts

@@ -71,6 +71,8 @@ export type WebhookEventType = 'payment_intent.confirming' | 'payment_intent.set
 /** Wake-up only. Re-read the owner-bound SDK resource; this is never paid or grant authority. */
 export interface BillingObservation {
     object: 'billing_observation';
+    /** The mode of the billing cohort observed (ADR 0017). */
+    livemode: boolean;
     resource_kind: 'subscription' | 'invoice';
     resource_id: string;
     revision: number;
@@ -115,6 +117,8 @@ export type WebhookEvent<K extends WebhookEventType = WebhookEventType> = {
     [T in K]: {
         id: string;
         object: 'event';
+        /** The mode of the merchant it was sent to, and of the object it carries (ADR 0017). */
+        livemode: boolean;
         type: T;
         created: number;
         /**

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 export { UNITS_PER_COIN, isBaseUnitString, type CurrencyCode, CURRENCY_CODES, CURRENCY_DECIMALS, decimalsFor, isCurrencyCode, } from './money';
 export type { NetworkType } from './network';
-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, EXPIRABLE_STATUSES, canExpire, } from './paymentIntent';
+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 { Dispute, DisputeEvidence, DisputeStatus } from './dispute';
 export type { CapabilityStatus, ConnectedAccount, ConnectedAccountFaircoin, ConnectedAccountFaircoinStatus, ConnectedAccountRail, Refund, RefundOrigin, RefundStatus, Settlement, Transfer, TransferReversal, TransferReversalStatus, TransferStatus, TransferWithReversal, } from './settlement';
@@ -9,8 +10,8 @@ export { signWebhook, verifyWebhook } from './webhookSigner';
 export { type MerchantEnvironment, type Merchant, MERCHANT_ENVIRONMENTS, } from './merchant';
 export type { MerchantDisplay } from './merchantDisplay';
 export type { AccountLink, ConnectOnboarding, ConnectOnboardingComplete, RegisterFaircoinKeyParams, } from './connect';
-export type { PaymentLink, PublicPaymentLink, CreatePaymentLinkParams, } from './paymentLink';
-export type { CheckoutSession, CheckoutSessionPublic, CreateCheckoutSessionParams, } from './checkoutSession';
+export type { PaymentLink, PublicPaymentLink, CreatePaymentLinkParams, UpdatePaymentLinkParams, } from './paymentLink';
+export type { CheckoutSession, CheckoutSessionPublic, CreateCheckoutSessionParams, UpdateCheckoutSessionParams, } from './checkoutSession';
 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 CreateBillingTaxQuoteParams, type BillingTaxQuote, type BillingInvoiceAuthoritySource, type BillingFinalInvoice, type BillingFinalInvoiceAuthority, type BillingFaircoinRenewalChoice, type BillingFaircoinRenewalConsent, type BillingFaircoinRenewalRevocation, type BillingCheckoutSession, type BillingCheckoutObservation, type RetrieveBillingCheckoutOperationParams, type BillingCheckoutOperationSource, type BillingCheckoutOperationRecovery, type BillingPaidInvoice, type BillingInvoiceState, type BillingCustomer, type BillingRail, type BillingRailSettlement, type BillingRailOffer, type BillingRailOption, type BillingRailList, type EnsureBillingCustomerParams, type CreateBillingCheckoutParams, type CreateBillingPortalParams, type BillingHostedSession, type BillingSubscription, } from './billing';
 export { canonicalBillingAuthority, canonicalBillingTaxQuote, PEABLE_BILLING_AUTHORITY_KEYS, } from './billing-authority';

package/dist/types/list.d.ts

@@ -0,0 +1,52 @@
+/**
+ * One page of a list, newest first.
+ *
+ * `url` is the path that was listed (`/v1/payment_intents`,
+ * `/v1/payment_intents/pi_…/refunds`), so a page carries enough to fetch the
+ * next one without the caller remembering where it came from.
+ */
+export interface List<T> {
+    object: 'list';
+    data: T[];
+    /** Whether another page exists in the direction this one was read. */
+    has_more: boolean;
+    url: string;
+}
+/**
+ * A range over an integer Unix-seconds field, Stripe's `created[gt]=…` form.
+ * Each bound is optional; together they are a conjunction.
+ */
+export interface RangeQuery {
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+}
+/** The parameters every list accepts. A route adds its own filters beside them. */
+export interface ListParams {
+    /** 1–100. Default 10. */
+    limit?: number;
+    /**
+     * The id of the LAST object of the previous page: the next page is the
+     * objects older than it. Mutually exclusive with `ending_before`.
+     */
+    starting_after?: string;
+    /**
+     * The id of the FIRST object of the current page: the page returned is the
+     * objects newer than it, still newest first, with `has_more` saying whether
+     * there are newer ones still.
+     */
+    ending_before?: string;
+    /** Exactly this second (`number`), or a range. Unix seconds. */
+    created?: number | RangeQuery;
+    /**
+     * Expand references into objects, `data.`-prefixed on a list
+     * (`['data.payment_intent']`). At most four levels deep.
+     */
+    expand?: string[];
+}
+/** The parameter a single read or write accepts to expand its answer. */
+export interface ExpandParams {
+    /** Dot paths, at most four levels deep (`['payment_intent.connected_account']`). */
+    expand?: string[];
+}

package/dist/types/merchant.d.ts

@@ -4,6 +4,11 @@ export type MerchantEnvironment = (typeof MERCHANT_ENVIRONMENTS)[number];
 export interface Merchant {
     id: string;
     object: 'merchant';
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
     oxy_app_id: string;
     environment: MerchantEnvironment;
     /**

package/dist/types/paymentIntent.d.ts

@@ -1,3 +1,4 @@
+import type { ConnectedAccount } from './settlement';
 import type { CurrencyCode } from './money';
 import type { NetworkType } from './network';
 /**
@@ -72,6 +73,11 @@ export declare function canExpire(status: PaymentIntentStatus): boolean;
 export interface PaymentIntent {
     id: string;
     object: 'payment_intent';
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
     status: PaymentIntentStatus;
     /** Which rail moves this payment. Decides which fields below are populated. */
     rail: PaymentIntentRail;
@@ -95,10 +101,10 @@ export interface PaymentIntent {
      * payment to the merchant itself (ADR 0012 D5). On-behalf payments are
      * FairCoin only, and `address` derives from that seller's own key.
      *
-     * Optional in the type only so fixtures written against earlier versions
-     * still compile; a gateway at this version always sends it.
+     * The seller's `ca_…`, or the {@link ConnectedAccount} itself when the
+     * request asked for `expand[]=connected_account`.
      */
-    connected_account_id?: string | null;
+    connected_account: string | ConnectedAccount | null;
     txid: string | null;
     /** On-chain confirmations. Structurally `0` for the whole life of a card payment. */
     confirmations: number;
@@ -144,3 +150,14 @@ export interface CreatePaymentIntentParams {
      */
     connected_account?: 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.
+ */
+export interface UpdatePaymentIntentParams {
+    metadata?: Record<string, string>;
+}

package/dist/types/paymentLink.d.ts

@@ -7,6 +7,11 @@ import type { PaymentIntentRail } from './paymentIntent';
 export interface PaymentLink {
     id: string;
     object: 'payment_link';
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
     contribution?: ContributionDetails;
     /**
      * Amount in the currency's smallest unit, as a canonical integer string.
@@ -30,6 +35,11 @@ export interface PaymentLink {
 export interface PublicPaymentLink {
     id: string;
     object: 'payment_link';
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
     contribution?: ContributionDetails;
     amount: string;
     currency: CurrencyCode;
@@ -49,3 +59,14 @@ export interface CreatePaymentLinkParams {
     metadata?: Record<string, string>;
     success_url?: string;
 }
+/**
+ * `POST /v1/payment_links/:id`. `amount`/`network` are deliberately absent — a
+ * link's price is immutable once shared.
+ */
+export interface UpdatePaymentLinkParams {
+    active?: boolean;
+    /** A patch: named keys are set, `""` removes a key, others are kept. */
+    metadata?: Record<string, string>;
+    /** `null` removes it. */
+    success_url?: string | null;
+}

package/dist/types/settlement.d.ts

@@ -1,5 +1,6 @@
 import type { CurrencyCode } from './money';
 import type { NetworkType } from './network';
+import type { PaymentIntent } from './paymentIntent';
 /** How a provider reports one capability on a seller's account. */
 export type CapabilityStatus = 'active' | 'pending' | 'inactive';
 /** Where one settlement stands. */
@@ -42,6 +43,11 @@ export interface ConnectedAccountFaircoin {
 export interface ConnectedAccount {
     id: string;
     object: 'connected_account';
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
     /** The merchant's OWN id for this seller — how they address it. */
     external_ref: string;
     /** Which halves this account has. Never empty. */
@@ -96,12 +102,17 @@ export interface ConnectedAccount {
 export interface Transfer {
     id: string;
     object: 'transfer';
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
     /** The merchant's OWN id for what this settles. Their idempotency. */
     external_ref: string;
-    /** The `ca_…` of the seller — never their account id at the provider. */
-    connected_account_id: string;
-    /** The `pi_…` this settlement was funded by — never an internal primary key. */
-    payment_intent_id: string;
+    /** The seller's `ca_…` — never their account id at the provider — or the object, expanded. */
+    connected_account: string | ConnectedAccount;
+    /** The `pi_…` this settlement was funded by, or the {@link PaymentIntent}, expanded. */
+    payment_intent: string | PaymentIntent;
     amount: string;
     currency: string;
     /**
@@ -127,6 +138,11 @@ export interface Transfer {
 export interface TransferReversal {
     id: string;
     object: 'transfer_reversal';
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
     /** The merchant's own id for this reversal — their `Idempotency-Key`. */
     external_ref: string;
     amount: string;
@@ -163,8 +179,13 @@ export interface TransferWithReversal extends Transfer {
  */
 export interface Settlement {
     object: 'settlement';
-    /** The `pi_…` this describes. */
-    payment_intent_id: string;
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
+    /** The `pi_…` this describes, or the {@link PaymentIntent} with `expand[]=payment_intent`. */
+    payment_intent: string | PaymentIntent;
     /**
      *  - `available` — settled; these figures are final.
      *  - `pending`   — a settlement record exists and is not final yet.
@@ -195,10 +216,16 @@ export type RefundOrigin = 'merchant' | 'provider';
 export interface Refund {
     id: string;
     object: 'refund';
+    /**
+     * Which of the provider's two worlds this object belongs to (ADR 0017):
+     * `true` for a `production` merchant, `false` for every other environment.
+     */
+    livemode: boolean;
     /** `null` on an IMPORTED refund; see {@link RefundOrigin}. */
     external_ref: string | null;
     origin: RefundOrigin;
-    payment_intent_id: string;
+    /** The refunded payment's `pi_…`, or the {@link PaymentIntent} with `expand[]=payment_intent`. */
+    payment_intent: string | PaymentIntent;
     amount: string;
     currency: CurrencyCode | string;
     status: RefundStatus;

package/dist/types/tax.d.ts

@@ -1,3 +1,4 @@
+import type { List, ListParams } from './list';
 /**
  * Peable Tax — the wire contract.
  *
@@ -239,19 +240,13 @@ export interface CreateTaxReversalParams {
      * that is not yet reversed. */
     amount?: number;
 }
-export interface TaxTransactionList {
-    object: 'list';
-    data: TaxTransaction[];
-    has_more: boolean;
-}
-export interface ListTaxTransactionsParams {
-    /** Inclusive, Unix seconds. */
-    from: number;
-    /** Exclusive, Unix seconds. */
-    to: number;
-    limit?: number;
-    starting_after?: string;
-}
+export type TaxTransactionList = List<TaxTransaction>;
+/**
+ * `GET /v1/tax/transactions`. `created` filters on `committed_at` — the tax
+ * date a filing period is judged by — and the list is newest first, like every
+ * other list.
+ */
+export type ListTaxTransactionsParams = Omit<ListParams, 'expand'>;
 /** One filing line: totals per jurisdiction, registration, tax type and rate. */
 export interface TaxReportRow {
     country: string;

package/dist/types/webhookDelivery.d.ts

@@ -22,6 +22,11 @@ export type WebhookDeliveryStatus = 'pending' | 'delivered' | 'failed' | 'dead';
 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.
+     */
+    livemode: boolean;
     merchant_id: string;
     /**
      * The `pi_…` this delivery is about — `null` when the event is not about a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/shared-types",
-  "version": "0.6.0",
+  "version": "0.8.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",
@@ -74,6 +74,6 @@
     "@types/bun": "latest"
   },
   "dependencies": {
-    "@peable.to/contracts": "0.3.0"
+    "@peable.to/contracts": "0.4.0"
   }
 }