@peable.to/contracts 0.3.0 → 1.0.0

package/dist/types/routes.d.ts

@@ -0,0 +1,23 @@
+import { billingEngineRoutes } from './resources/billingEngine';
+import { catalogRoutes } from './resources/catalog';
+import { checkoutRoutes } from './resources/checkout';
+import { connectRoutes } from './resources/connect';
+import { coreRoutes } from './resources/core';
+import { eventsRoutes } from './resources/events';
+import { paymentsRoutes } from './resources/payments';
+import { taxRoutes } from './resources/tax';
+/**
+ * Every public route of the gateway (ADR 0014 D5). The backend's coverage test
+ * proves this list and the mounted Express routes are the same set (dashboard
+ * routes excepted: they are Orbit's private surface), the OpenAPI document is
+ * generated from it, and the SDK's resource methods are generated from it.
+ */
+export type AnyRoute = (typeof coreRoutes)[number] | (typeof paymentsRoutes)[number] | (typeof checkoutRoutes)[number] | (typeof catalogRoutes)[number] | (typeof billingEngineRoutes)[number] | (typeof connectRoutes)[number] | (typeof taxRoutes)[number] | (typeof eventsRoutes)[number];
+export declare const routes: readonly AnyRoute[];
+/** Every route by its `operationId`. */
+export type RouteMap = {
+    [R in AnyRoute as R['operationId']]: R;
+};
+export type OperationId = keyof RouteMap;
+/** The route of an operation. */
+export declare function routeOf<K extends OperationId>(operationId: K): RouteMap[K];

package/dist/types/vocabulary/billingPortal.d.ts

@@ -0,0 +1,15 @@
+/** What a portal customer may edit about themselves. */
+export declare const PORTAL_CUSTOMER_UPDATES: readonly ["email", "name", "address", "phone"];
+export type PortalCustomerUpdate = (typeof PORTAL_CUSTOMER_UPDATES)[number];
+/** When a cancellation from the portal takes effect. */
+export declare const PORTAL_CANCEL_MODES: readonly ["at_period_end", "immediately"];
+export type PortalCancelMode = (typeof PORTAL_CANCEL_MODES)[number];
+/** How a cancellation from the portal prorates. */
+export declare const PORTAL_CANCEL_PRORATION_BEHAVIORS: readonly ["create_prorations", "none"];
+export type PortalCancelProrationBehavior = (typeof PORTAL_CANCEL_PRORATION_BEHAVIORS)[number];
+/** What a plan change from the portal may change. */
+export declare const PORTAL_SUBSCRIPTION_UPDATES: readonly ["price", "quantity"];
+export type PortalSubscriptionUpdate = (typeof PORTAL_SUBSCRIPTION_UPDATES)[number];
+/** What finishing a payment method update from the portal answered. */
+export declare const PORTAL_PAYMENT_METHOD_UPDATE_STATUSES: readonly ["succeeded", "pending"];
+export type PortalPaymentMethodUpdateStatus = (typeof PORTAL_PAYMENT_METHOD_UPDATE_STATUSES)[number];

package/dist/types/vocabulary/catalog.d.ts

@@ -0,0 +1,97 @@
+import { type CurrencyCode } from './money';
+/** How a price's amount is computed from a quantity. */
+export declare const PRICE_BILLING_SCHEMES: readonly ["per_unit", "tiered"];
+export type PriceBillingScheme = (typeof PRICE_BILLING_SCHEMES)[number];
+/**
+ * How a tiered price reads its tiers.
+ *
+ *  - `volume`    — the WHOLE quantity is priced at the tier it falls into.
+ *  - `graduated` — each unit is priced at the tier it falls into, so a
+ *                  quantity crossing two tiers pays each tier's rate for its
+ *                  share, plus the flat amount of every tier it reaches.
+ */
+export declare const PRICE_TIERS_MODES: readonly ["graduated", "volume"];
+export type PriceTiersMode = (typeof PRICE_TIERS_MODES)[number];
+/** `recurring` when the price has a recurring component, `one_time` otherwise. */
+export declare const PRICE_TYPES: readonly ["one_time", "recurring"];
+export type PriceType = (typeof PRICE_TYPES)[number];
+export declare const RECURRING_INTERVALS: readonly ["day", "week", "month", "year"];
+export type RecurringInterval = (typeof RECURRING_INTERVALS)[number];
+/**
+ * `licensed` bills the quantity on the subscription. `metered` bills the usage
+ * a meter (`recurring.meter`, `mtr_…`) aggregated over the period, in arrears.
+ */
+export declare const RECURRING_USAGE_TYPES: readonly ["licensed", "metered"];
+export type RecurringUsageType = (typeof RECURRING_USAGE_TYPES)[number];
+/**
+ * Whether a price includes tax (Peable Tax, ADR 0011). `unspecified` defers to
+ * the merchant's default tax behavior; once a price says `inclusive` or
+ * `exclusive` it can never change.
+ */
+export declare const PRICE_TAX_BEHAVIORS: readonly ["inclusive", "exclusive", "unspecified"];
+export type PriceTaxBehavior = (typeof PRICE_TAX_BEHAVIORS)[number];
+export declare const TRANSFORM_QUANTITY_ROUNDS: readonly ["up", "down"];
+export type TransformQuantityRound = (typeof TRANSFORM_QUANTITY_ROUNDS)[number];
+/** How long a coupon's discount lasts once applied to a subscription. */
+export declare const COUPON_DURATIONS: readonly ["once", "repeating", "forever"];
+export type CouponDuration = (typeof COUPON_DURATIONS)[number];
+/** The bounds the gateway enforces, published so a form can say them first. */
+export declare const CATALOG_LIMITS: Readonly<{
+    productNameMax: 250;
+    productDescriptionMax: 40000;
+    productImagesMax: 8;
+    urlMax: 2048;
+    unitLabelMax: 12;
+    statementDescriptorMax: 22;
+    marketingFeaturesMax: 15;
+    marketingFeatureNameMax: 80;
+    priceNicknameMax: 250;
+    lookupKeyMax: 200;
+    lookupKeysFilterMax: 10;
+    priceTiersMax: 250;
+    couponIdMax: 64;
+    couponNameMax: 40;
+    couponAppliesToProductsMax: 100;
+    couponDurationInMonthsMax: 1200;
+    promotionCodeMax: 64;
+    idsFilterMax: 100;
+}>;
+/**
+ * The largest amount the catalog stores, in whole units of any currency, so a
+ * FAIR amount (8 decimals) and a EUR amount (2) are bounded at the same real
+ * size rather than the same number of digits.
+ */
+export declare const CATALOG_MAX_WHOLE_UNITS = 1000000000n;
+/** The largest base-unit amount of `currency` the catalog accepts. */
+export declare function maxBaseUnits(currency: CurrencyCode): bigint;
+/** The longest a recurring interval may be: three years, in each unit. */
+export declare const RECURRING_INTERVAL_COUNT_MAX: Readonly<Record<RecurringInterval, number>>;
+export declare const TEST_CLOCK_STATUSES: readonly ["ready", "advancing", "internal_failure"];
+export type TestClockStatus = (typeof TEST_CLOCK_STATUSES)[number];
+/** What dunning does to a subscription once the last retry has failed. */
+export declare const DUNNING_FINAL_ACTIONS: readonly ["cancel", "unpaid", "past_due"];
+export type DunningFinalAction = (typeof DUNNING_FINAL_ACTIONS)[number];
+/** What happens to the invoice itself once the last retry has failed. */
+export declare const DUNNING_INVOICE_ACTIONS: readonly ["leave_open", "mark_uncollectible"];
+export type DunningInvoiceAction = (typeof DUNNING_INVOICE_ACTIONS)[number];
+/** The bounds the gateway enforces on billing settings. */
+export declare const BILLING_SETTINGS_LIMITS: Readonly<{
+    retriesMax: 8;
+    retryDaysMax: 60;
+    daysUntilDueMax: 365;
+    invoicePrefixPattern: "^[A-Z0-9]{3,12}$";
+}>;
+/** How a meter combines a period's events into the quantity billed. */
+export declare const METER_AGGREGATIONS: readonly ["sum", "count", "last"];
+export type MeterAggregation = (typeof METER_AGGREGATIONS)[number];
+export declare const METER_STATUSES: readonly ["active", "inactive"];
+export type MeterStatus = (typeof METER_STATUSES)[number];
+/** A provider subscription's status, as the recurring transport observes it. */
+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];
+/** `fiat` (Stripe and any further provider) or `faircoin` (native, to the merchant's watch-only wallet). */
+export declare const BILLING_RAIL_SETTLEMENTS: readonly ["fiat", "faircoin"];
+export type BillingRailSettlement = (typeof BILLING_RAIL_SETTLEMENTS)[number];
+/** `automatic`: the provider charges each period. `payer_initiated`: each period is an explicit payment. */
+export declare const BILLING_RAIL_RENEWALS: readonly ["automatic", "payer_initiated"];
+export type BillingRailRenewal = (typeof BILLING_RAIL_RENEWALS)[number];

package/dist/types/vocabulary/checkout.d.ts

@@ -0,0 +1,49 @@
+export declare const CHECKOUT_SESSION_MODES: readonly ["payment", "setup", "subscription"];
+export type CheckoutSessionMode = (typeof CHECKOUT_SESSION_MODES)[number];
+export declare const CHECKOUT_SESSION_STATUSES: readonly ["open", "complete", "expired"];
+export type CheckoutSessionStatus = (typeof CHECKOUT_SESSION_STATUSES)[number];
+export declare const CHECKOUT_PAYMENT_STATUSES: readonly ["paid", "unpaid", "no_payment_required"];
+export type CheckoutSessionPaymentStatus = (typeof CHECKOUT_PAYMENT_STATUSES)[number];
+export declare const CHECKOUT_UI_MODES: readonly ["hosted", "embedded"];
+export type CheckoutUiMode = (typeof CHECKOUT_UI_MODES)[number];
+/** The languages the hosted and embedded checkout speak. */
+export declare const CHECKOUT_LOCALES: readonly ["en", "es", "fr", "de", "it", "pt"];
+export type CheckoutLocale = (typeof CHECKOUT_LOCALES)[number];
+export declare const CHECKOUT_SUBMIT_TYPES: readonly ["auto", "pay", "book", "donate"];
+export type CheckoutSubmitType = (typeof CHECKOUT_SUBMIT_TYPES)[number];
+export declare const CHECKOUT_CUSTOMER_CREATIONS: readonly ["always", "if_required"];
+export type CheckoutCustomerCreation = (typeof CHECKOUT_CUSTOMER_CREATIONS)[number];
+export declare const CHECKOUT_BILLING_ADDRESS_COLLECTIONS: readonly ["auto", "required"];
+export type CheckoutBillingAddressCollection = (typeof CHECKOUT_BILLING_ADDRESS_COLLECTIONS)[number];
+export declare const CHECKOUT_CUSTOM_FIELD_TYPES: readonly ["text", "numeric", "dropdown"];
+export type CheckoutCustomFieldType = (typeof CHECKOUT_CUSTOM_FIELD_TYPES)[number];
+/** Stripe's tax id types Peable collects; `eu_vat` covers every EU member state. */
+export declare const CHECKOUT_TAX_ID_TYPES: readonly ["eu_vat", "gb_vat", "ch_vat", "no_vat", "us_ein", "ca_bn"];
+export type CheckoutTaxIdType = (typeof CHECKOUT_TAX_ID_TYPES)[number];
+/**
+ * Bounds of the session contract, shared by the gateway's validators and the
+ * clients that build requests, so the two cannot drift.
+ */
+export declare const CHECKOUT_LIMITS: Readonly<{
+    lineItemsMax: 20;
+    quantityMax: 999999;
+    customFieldsMax: 3;
+    customFieldKeyMax: 200;
+    customFieldLabelMax: 50;
+    customFieldTextMax: 255;
+    dropdownOptionsMax: 200;
+    dropdownOptionLabelMax: 100;
+    dropdownOptionValueMax: 100;
+    clientReferenceIdMax: 200;
+    /** `expires_at` must be between 30 minutes and 24 hours from creation. */
+    expiresMinSeconds: number;
+    expiresMaxSeconds: number;
+    shippingCountriesMax: 250;
+    termsTextMax: 1200;
+}>;
+/** The template a `success_url` may carry; replaced with the session's `cs_…`. */
+export declare const CHECKOUT_SESSION_ID_TEMPLATE = "{CHECKOUT_SESSION_ID}";
+export declare const PAYMENT_LINK_LIMITS: Readonly<{
+    lineItemsMax: 20;
+    customMessageMax: 500;
+}>;

package/dist/types/vocabulary/connect.d.ts

@@ -0,0 +1,62 @@
+/** Which half of an account a business type opens: the provider's two kinds. */
+export declare const ACCOUNT_BUSINESS_TYPES: readonly ["individual", "company"];
+export type AccountBusinessType = (typeof ACCOUNT_BUSINESS_TYPES)[number];
+/** A capability's state as the provider reports it; `null` on the wire means never requested. */
+export declare const ACCOUNT_CAPABILITY_STATUSES: readonly ["active", "pending", "inactive"];
+export type AccountCapabilityStatus = (typeof ACCOUNT_CAPABILITY_STATUSES)[number];
+/** Whose account an `account` is: the merchant's own, or one of its marketplace sellers. */
+export declare const ACCOUNT_TYPES: readonly ["merchant", "connected"];
+export type AccountType = (typeof ACCOUNT_TYPES)[number];
+/** What a hosted onboarding link for the merchant's own account is for. */
+export declare const ACCOUNT_LINK_TYPES: readonly ["account_onboarding", "account_update"];
+export type AccountLinkType = (typeof ACCOUNT_LINK_TYPES)[number];
+/**
+ * Which rails a seller's account was opened for (ADR 0012 D1). One seller is
+ * ONE `ca_…`: `card` is the provider account a marketplace settles to by
+ * transfer, `faircoin` is the seller's own watch-only key.
+ */
+export declare const CONNECTED_ACCOUNT_RAILS: readonly ["card", "faircoin"];
+export type ConnectedAccountRail = (typeof CONNECTED_ACCOUNT_RAILS)[number];
+/**
+ * Where a seller's FairCoin half stands: `pending` until the seller registers
+ * a key, `active` once they did.
+ */
+export declare const CONNECTED_ACCOUNT_FAIRCOIN_STATUSES: readonly ["pending", "active"];
+export type ConnectedAccountFaircoinStatus = (typeof CONNECTED_ACCOUNT_FAIRCOIN_STATUSES)[number];
+export declare const PAYOUT_INTERVALS: readonly ["manual", "daily", "weekly", "monthly"];
+export type PayoutInterval = (typeof PAYOUT_INTERVALS)[number];
+export declare const PAYOUT_WEEKLY_ANCHORS: readonly ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
+export type PayoutWeeklyAnchor = (typeof PAYOUT_WEEKLY_ANCHORS)[number];
+/** Orbit's vocabulary for what moved — the provider's own types, provider-neutral. */
+export declare const BALANCE_TRANSACTION_TYPES: readonly ["charge", "payment", "refund", "payment_refund", "adjustment", "application_fee", "application_fee_refund", "payout", "payout_cancel", "payout_failure", "transfer", "transfer_refund", "dispute", "dispute_reversal", "processing_fee", "faircoin_payment", "faircoin_payment_reversal", "other"];
+export type BalanceTransactionType = (typeof BALANCE_TRANSACTION_TYPES)[number];
+/**
+ * - `pending` / `available` — the provider's own status for the funds.
+ * - `informational` — a FairCoin payment: recorded, never part of a payable balance.
+ */
+export declare const BALANCE_TRANSACTION_STATUSES: readonly ["available", "pending", "informational"];
+export type BalanceTransactionStatus = (typeof BALANCE_TRANSACTION_STATUSES)[number];
+/** One component of a transaction's fee. `processing_fee` is the acquirer's own. */
+export declare const BALANCE_TRANSACTION_FEE_TYPES: readonly ["application_fee", "processing_fee", "tax", "other"];
+export type BalanceTransactionFeeType = (typeof BALANCE_TRANSACTION_FEE_TYPES)[number];
+export declare const PAYOUT_STATUSES: readonly ["pending", "in_transit", "paid", "failed", "canceled"];
+export type PayoutStatus = (typeof PAYOUT_STATUSES)[number];
+export declare const PAYOUT_METHODS: readonly ["standard", "instant"];
+export type PayoutMethod = (typeof PAYOUT_METHODS)[number];
+export declare const PAYOUT_DESTINATION_TYPES: readonly ["bank_account", "card"];
+export type PayoutDestinationType = (typeof PAYOUT_DESTINATION_TYPES)[number];
+/**
+ * A payout reconciliation report's state: `complete` once the payout is `paid`
+ * and its transactions were read from the provider, `pending` before.
+ */
+export declare const PAYOUT_RECONCILIATION_STATUSES: readonly ["complete", "pending"];
+export type PayoutReconciliationStatus = (typeof PAYOUT_RECONCILIATION_STATUSES)[number];
+/** What the daily reconciliation found disagreeing with the provider. Never auto-corrected. */
+export declare const RECONCILIATION_MISMATCH_KINDS: readonly ["missing_in_ledger", "amount_mismatch", "status_mismatch", "missing_at_provider", "payout_mismatch", "unbalanced_journal"];
+export type ReconciliationMismatchKind = (typeof RECONCILIATION_MISMATCH_KINDS)[number];
+/** Where one settlement stands. */
+export declare const TRANSFER_STATUSES: readonly ["pending", "paid", "partially_reversed", "reversed", "failed"];
+export type TransferStatus = (typeof TRANSFER_STATUSES)[number];
+/** Where one reversal of a settlement stands. */
+export declare const TRANSFER_REVERSAL_STATUSES: readonly ["pending", "succeeded", "failed"];
+export type TransferReversalStatus = (typeof TRANSFER_REVERSAL_STATUSES)[number];

package/dist/types/vocabulary/errors.d.ts

@@ -0,0 +1,145 @@
+/** `error.type`: the broad class a caller branches on first. */
+export declare const ERROR_TYPES: readonly ["api_error", "authentication_error", "card_error", "idempotency_error", "invalid_request_error", "permission_error", "rate_limit_error"];
+export type ErrorType = (typeof ERROR_TYPES)[number];
+/** What each `error.type` means, and the HTTP status it comes with. */
+export declare const ERROR_TYPE_DESCRIPTIONS: Readonly<Record<ErrorType, string>>;
+/**
+ * Where every code is documented: the error-code page of Peable's docs on the
+ * Oxy developer site, generated from this file (`bun run generate:api-docs`,
+ * `packages/sdk/docs/errors.mdx`). The trailing slash is the page's canonical
+ * form; each code is its own fragment.
+ */
+export declare const ERROR_DOCS_BASE_URL = "https://oxy.so/developers/docs/peable/errors/";
+/** The `doc_url` of a code. */
+export declare function errorDocUrl(code: string): string;
+/**
+ * Every `error.code` the gateway answers with, and what it means. The keys ARE
+ * the list — {@link ERROR_CODES} is derived from them — so a new code cannot be
+ * added without its description.
+ */
+export declare const ERROR_CODE_DESCRIPTIONS: {
+    readonly account_invalid: "The `Peable-Account` header names no connected account of this platform.";
+    readonly account_missing: "The merchant has no account object yet.";
+    readonly amount_not_representable: "The amount does not fit the currency or the rail.";
+    readonly billing_not_enabled: "Billing is not enabled for this merchant.";
+    readonly billing_provider_unavailable: "The billing provider could not be reached; retry.";
+    readonly domain_taken: "The domain is already registered by another merchant.";
+    readonly file_too_large: "The uploaded file is larger than its purpose allows.";
+    readonly file_unavailable: "The file exists but its contents cannot be served right now.";
+    readonly idempotency_error: "The `Idempotency-Key` was used with a different request, or its first request is still running.";
+    readonly idempotency_key_invalid: "The `Idempotency-Key` header is not a valid key.";
+    readonly insufficient_scope: "The credential is valid but was not granted the Oxy scope this route requires (`payments:read`, `payments:write`, …); `message` names it.";
+    readonly invalid_billing_request: "The billing request is not valid for this subscription or offer.";
+    readonly keyless_recipient: "The recipient has no receive key, so no address can be derived for them.";
+    readonly link_not_found: "The link does not exist or is no longer active.";
+    readonly live_payments_gated: "Live payments are not enabled for this application yet.";
+    readonly local_test_request_required: "This test helper only answers a local test request.";
+    readonly parameter_invalid: "A parameter is invalid; `param` names it.";
+    readonly parameter_missing: "A required parameter is missing; `param` names it.";
+    readonly parameter_unknown: "The request carries a parameter this route does not accept; `param` names it.";
+    readonly payment_intent_unexpected_state: "The PaymentIntent is in a status that does not allow this operation.";
+    readonly payout_not_allowed: "Payouts cannot be created for this account.";
+    readonly rate_limited: "Too many requests; back off and retry.";
+    readonly refund_not_cancelable: "The refund has already left a cancelable state.";
+    readonly resource_conflict: "The object changed under this request; read it again and retry.";
+    readonly resource_missing: "The object does not exist, or this credential cannot read it.";
+    readonly setup_intent_unexpected_state: "The SetupIntent is in a status that does not allow this operation.";
+    readonly tax_not_enabled: "Peable Tax is not enabled for this merchant.";
+    readonly test_mode_only: "This operation exists in test mode only.";
+    readonly too_many_streams: "Too many live streams are open for this merchant.";
+    readonly url_invalid: "The URL is not an allowed https URL.";
+    readonly watch_only_violation: "The extended key carries a private key. Peable only ever accepts watch-only (public) keys.";
+    readonly webhook_endpoint_disabled: "The webhook endpoint is disabled.";
+    readonly webhook_endpoint_limit_reached: "The merchant already has the maximum number of webhook endpoints.";
+    readonly account_not_ready: "The connected account cannot take this payment yet: its onboarding or a capability is incomplete.";
+    readonly approval_incomplete: "The tax settings cannot be approved yet: a legal name and head office are required, or they changed during the approval.";
+    readonly approval_requires_provider: "Registered sales need a tax provider, and this application has none: the approval would leave covered sales unpriceable.";
+    readonly checkout_session_expired: "The Checkout Session has expired.";
+    readonly checkout_session_not_open: "The Checkout Session is no longer open (complete or expired).";
+    readonly customer_location_conflicting: "The customer's location evidence disagrees, so the sale cannot be placed in one jurisdiction.";
+    readonly customer_location_expired: "The customer's location evidence is too old to price a sale with.";
+    readonly customer_location_insufficient: "There is not enough evidence of the customer's location to decide whether the sale is taxed.";
+    readonly customer_location_invalid: "The tax provider could not use the customer's location.";
+    readonly dispute_already_submitted: "Evidence for this dispute has already been submitted; it is one shot.";
+    readonly dispute_not_answerable: "The dispute is in a status that no longer accepts evidence.";
+    readonly idempotency_conflict: "The same operation key was used for a different billing request.";
+    readonly identity_conflict: "The billing identity already belongs to another customer or subscription.";
+    readonly in_progress: "The same operation is still running; retry with the same key.";
+    readonly invalid_provider_response: "The provider answered with something Peable cannot trust; the operation was not applied.";
+    readonly invalid_registration: "The tax registration is not valid.";
+    readonly invalid_registration_declaration: "The tax registration declaration is not valid.";
+    readonly invalid_tax_code: "The tax code does not exist.";
+    readonly invalid_tax_document: "The tax document is not valid for its declared purpose.";
+    readonly invalid_tax_request: "The tax request is not valid.";
+    readonly lookup_key_taken: "Another price already uses this `lookup_key`.";
+    readonly mode_unavailable: "This Checkout mode is not available to this merchant.";
+    readonly not_found: "The object does not exist, or this credential cannot read it.";
+    readonly payment_link_inactive: "The Payment Link is deactivated.";
+    readonly price_is_default: "The price is its product's `default_price` and cannot be archived.";
+    readonly product_has_prices: "The product still has prices; archive it instead.";
+    readonly product_in_use: "The product is referenced by a subscription or a link.";
+    readonly promotion_code_invalid: "The promotion code does not exist, is inactive or does not apply.";
+    readonly promotion_code_taken: "Another active promotion code already uses this `code`.";
+    readonly provider_unavailable: "The payment provider could not be reached; retry.";
+    readonly rail_unavailable: "The payment rail this request needs is not available.";
+    readonly reconciliation_required: "The billing operation has an unknown outcome at the provider and is being reconciled.";
+    readonly registration_immutable: "An approved or ended tax registration cannot be deleted or changed this way; end it instead.";
+    readonly resource_already_exists: "An object with this identity already exists.";
+    readonly result_expired: "The stored result of this operation has expired.";
+    readonly review_item_not_open: "The review item is already resolved or dismissed.";
+    readonly rule_set_version_unavailable: "The tax rule set version is not available.";
+    readonly subscription_line_invalid: "A subscription line item is not valid for Checkout.";
+    readonly tax_behavior_locked: "The price's `tax_behavior` cannot change once set.";
+    readonly tax_calculation_unavailable: "Tax could not be calculated; a covered sale fails closed.";
+    readonly tax_provider_registration_mismatch: "The provider's registrations disagree with the ones Peable has approved.";
+    readonly tax_settings_not_active: "Tax settings are not active for this merchant.";
+    readonly local_test_unavailable: "The local test checkout is not available.";
+    readonly local_test_configuration_unavailable: "The local test checkout has no provider configuration.";
+    readonly local_test_subscription_unavailable: "The local test subscription cannot be read.";
+    readonly rail_mismatch: "The operation does not apply to the rail this payment uses.";
+    readonly checkout_session_changed: "The Checkout Session changed while this request ran (a price, a discount, its tax); read it again and retry.";
+    readonly checkout_session_locked: "The Checkout Session is being confirmed and cannot change.";
+    readonly tax_calculation_failed: "The tax for this Checkout Session could not be calculated.";
+    readonly payment_cancellation_failed: "The payment could not be cancelled at the provider; the Checkout Session stays as it was.";
+    readonly invoice_not_editable: "The invoice is finalized and can no longer be edited.";
+    readonly invoice_unexpected_state: "The invoice is in a status that does not allow this operation.";
+    readonly invoice_no_customer_line_items: "The invoice has no line items to finalize.";
+    readonly invoice_payment_intent_requires_action: "The invoice's payment needs the customer to act (a card challenge).";
+    readonly subscription_unexpected_state: "The subscription is in a status that does not allow this operation.";
+    readonly customer_currency_mismatch: "The currency differs from the customer's billing currency.";
+    readonly customer_test_clock_mismatch: "The objects live on different test clocks.";
+    readonly coupon_invalid: "The coupon does not exist or is no longer valid.";
+    readonly coupon_currency_mismatch: "The coupon's currency differs from the purchase's.";
+    readonly coupon_not_applicable: "The coupon does not apply to these products.";
+    readonly promotion_code_inactive: "The promotion code is inactive.";
+    readonly promotion_code_customer_mismatch: "The promotion code is restricted to another customer.";
+    readonly promotion_code_expired: "The promotion code has expired.";
+    readonly promotion_code_max_redemptions: "The promotion code has been redeemed its maximum number of times.";
+    readonly promotion_code_minimum_amount: "The purchase is below the promotion code minimum amount.";
+    readonly payment_method_missing: "No payment method is available to charge.";
+    readonly faircoin_cannot_debit: "A FairCoin invoice cannot be charged automatically: the payer signs every payment.";
+    readonly credit_note_exceeds_invoice: "The credit note's amount exceeds what the invoice can still credit.";
+    readonly test_clock_unexpected_state: "The test clock is advancing; wait until it is ready.";
+    readonly meter_event_customer_missing: "The meter event names no customer of this merchant.";
+    readonly feature_lookup_key_taken: "Another feature already uses this `lookup_key`.";
+    readonly portal_feature_disabled: "The customer portal configuration does not allow this action.";
+    readonly portal_session_expired: "The customer portal session has expired.";
+    readonly card_declined: "The card was declined.";
+    readonly promotion_code_first_time_only: "The promotion code is for a customer's first purchase only.";
+    readonly network_mismatch: "The FairCoin network differs from the one this object uses.";
+    readonly link_expired: "The onboarding link has expired or was already used; `refresh_url` is where the seller gets a fresh one.";
+    readonly wrong_seller: "The onboarding link names a different Oxy account; sign in as the seller it was minted for.";
+    readonly already_registered: "The seller already registered a FairCoin key, and it cannot be changed.";
+    readonly key_in_use: "The key already receives payments for another account.";
+    readonly no_faircoin_half: "The connected account has no FairCoin half to register a key for.";
+    readonly merchant_missing: "The application has no merchant in this environment yet; register one (Orbit shows \"Set up payments\").";
+    readonly application_membership_required: "The signed-in Oxy account is not a member of the account that owns this application.";
+    readonly permission_required: "The member lacks an Oxy permission this needs; `param` names it (`billing:read`, `billing:manage`). An owner grants it in Oxy Console.";
+    readonly membership_unavailable: "Oxy could not be asked whether the signed-in person is a member of this application; retry.";
+    readonly session_invalid: "Oxy no longer accepts the signed-in session; sign in again.";
+};
+export type ErrorCode = keyof typeof ERROR_CODE_DESCRIPTIONS;
+/** Every error code, sorted. */
+export declare const ERROR_CODES: [ErrorCode, ...ErrorCode[]];
+/** Whether a string is a documented error code. */
+export declare function isErrorCode(value: string): value is ErrorCode;

package/dist/types/vocabulary/events.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Event type → the `object` value of the resource under `data.object`.
+ *
+ * TOTAL and the ONLY list: {@link WEBHOOK_EVENT_TYPES} is 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 precise payload TYPE is `WebhookEventPayload` (`resources/events`), the
+ * registered object of each value.
+ *
+ * The order is the database's: the backend's CHECK constraints list the types
+ * in this order, so reordering it is a migration.
+ *
+ * - `payment_intent.*` 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.*` 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`; its events carry the Dispute, never the evidence (which is not
+ *   stored).
+ * - The catalog has no `price.deleted` or `promotion_code.deleted`: those are
+ *   archived with `active: false`, and a type that can never be sent is a
+ *   promise the catalog cannot keep.
+ */
+export declare const WEBHOOK_EVENT_OBJECTS: {
+    readonly 'payment_intent.created': "payment_intent";
+    readonly 'payment_intent.requires_action': "payment_intent";
+    readonly 'payment_intent.processing': "payment_intent";
+    readonly 'payment_intent.amount_capturable_updated': "payment_intent";
+    readonly 'payment_intent.succeeded': "payment_intent";
+    readonly 'payment_intent.payment_failed': "payment_intent";
+    readonly 'payment_intent.canceled': "payment_intent";
+    readonly 'charge.refunded': "charge";
+    readonly 'charge.dispute.created': "dispute";
+    readonly 'charge.dispute.updated': "dispute";
+    readonly 'charge.dispute.closed': "dispute";
+    readonly 'charge.dispute.funds_withdrawn': "dispute";
+    readonly 'charge.dispute.funds_reinstated': "dispute";
+    readonly 'refund.created': "refund";
+    readonly 'refund.updated': "refund";
+    readonly 'refund.failed': "refund";
+    readonly 'customer.created': "customer";
+    readonly 'customer.updated': "customer";
+    readonly 'customer.deleted': "customer";
+    readonly 'payment_method.attached': "payment_method";
+    readonly 'payment_method.detached': "payment_method";
+    readonly 'payment_method.updated': "payment_method";
+    readonly 'setup_intent.created': "setup_intent";
+    readonly 'setup_intent.requires_action': "setup_intent";
+    readonly 'setup_intent.succeeded': "setup_intent";
+    readonly 'setup_intent.setup_failed': "setup_intent";
+    readonly 'setup_intent.canceled': "setup_intent";
+    readonly 'billing.observation.updated': "billing_observation";
+    readonly 'connected_account.updated': "connected_account";
+    readonly 'product.created': "product";
+    readonly 'product.updated': "product";
+    readonly 'product.deleted': "product";
+    readonly 'price.created': "price";
+    readonly 'price.updated': "price";
+    readonly 'coupon.created': "coupon";
+    readonly 'coupon.updated': "coupon";
+    readonly 'coupon.deleted': "coupon";
+    readonly 'promotion_code.created': "promotion_code";
+    readonly 'promotion_code.updated': "promotion_code";
+    readonly 'account.updated': "account";
+    readonly 'application_fee.created': "application_fee";
+    readonly 'application_fee.refunded': "application_fee";
+    readonly 'payout.created': "payout";
+    readonly 'payout.updated': "payout";
+    readonly 'payout.paid': "payout";
+    readonly 'payout.failed': "payout";
+    readonly 'payout.canceled': "payout";
+    readonly 'balance.available': "balance";
+    readonly 'checkout.session.completed': "checkout_session";
+    readonly 'checkout.session.expired': "checkout_session";
+    readonly 'checkout.session.async_payment_succeeded': "checkout_session";
+    readonly 'checkout.session.async_payment_failed': "checkout_session";
+    readonly 'payment_link.created': "payment_link";
+    readonly 'payment_link.updated': "payment_link";
+    readonly 'reporting.report_run.succeeded': "reporting.report_run";
+    readonly 'reporting.report_run.failed': "reporting.report_run";
+    readonly 'customer.subscription.created': "subscription";
+    readonly 'customer.subscription.updated': "subscription";
+    readonly 'customer.subscription.deleted': "subscription";
+    readonly 'customer.subscription.trial_will_end': "subscription";
+    readonly 'customer.subscription.paused': "subscription";
+    readonly 'customer.subscription.resumed': "subscription";
+    readonly 'invoice.created': "invoice";
+    readonly 'invoice.updated': "invoice";
+    readonly 'invoice.deleted': "invoice";
+    readonly 'invoice.finalized': "invoice";
+    readonly 'invoice.paid': "invoice";
+    readonly 'invoice.payment_failed': "invoice";
+    readonly 'invoice.payment_action_required': "invoice";
+    readonly 'invoice.voided': "invoice";
+    readonly 'invoice.marked_uncollectible': "invoice";
+    readonly 'invoice.upcoming': "invoice";
+    readonly 'invoice.sent': "invoice";
+    readonly 'invoiceitem.created': "invoiceitem";
+    readonly 'invoiceitem.deleted': "invoiceitem";
+    readonly 'credit_note.created': "credit_note";
+    readonly 'credit_note.updated': "credit_note";
+    readonly 'credit_note.voided': "credit_note";
+    readonly 'test_helpers.test_clock.created': "test_helpers.test_clock";
+    readonly 'test_helpers.test_clock.advancing': "test_helpers.test_clock";
+    readonly 'test_helpers.test_clock.ready': "test_helpers.test_clock";
+    readonly 'test_helpers.test_clock.deleted': "test_helpers.test_clock";
+    readonly 'billing.meter.created': "billing.meter";
+    readonly 'billing.meter.updated': "billing.meter";
+    readonly 'billing.meter.deactivated': "billing.meter";
+    readonly 'billing.meter.reactivated': "billing.meter";
+    readonly 'entitlements.active_entitlement_summary.updated': "entitlements.active_entitlement_summary";
+    readonly 'billing_portal.configuration.created': "billing_portal.configuration";
+    readonly 'billing_portal.configuration.updated': "billing_portal.configuration";
+    readonly 'billing_portal.session.created': "billing_portal.session";
+    readonly 'tax.assessment.created': "tax.assessment";
+    readonly 'tax.review_item.created': "tax.review_item";
+    readonly 'tax.review_item.updated': "tax.review_item";
+    readonly 'webhook_endpoint.test': "webhook_endpoint";
+};
+/** Every event type, Stripe's names (ADR 0019). */
+export type WebhookEventType = keyof typeof WEBHOOK_EVENT_OBJECTS;
+/** The `object` type an event of type `T` carries under `data.object`. */
+export type WebhookEventObjectType<T extends WebhookEventType = WebhookEventType> = (typeof WEBHOOK_EVENT_OBJECTS)[T];
+/** Every event type, in {@link WEBHOOK_EVENT_OBJECTS} order. */
+export declare const WEBHOOK_EVENT_TYPES: [WebhookEventType, ...WebhookEventType[]];
+/**
+ * The event types never fanned out by subscription — sent only to the one
+ * endpoint they name. `enabled_events` refuses them.
+ */
+export declare const TARGETED_WEBHOOK_EVENT_TYPES: readonly ["webhook_endpoint.test"];
+export type TargetedWebhookEventType = (typeof TARGETED_WEBHOOK_EVENT_TYPES)[number];
+/** `'*'` subscribes to every event type, including ones added later. */
+export type WebhookEnabledEvent = Exclude<WebhookEventType, TargetedWebhookEventType> | '*';
+/** What `enabled_events` may hold: `*`, then every subscribable type. */
+export declare const WEBHOOK_ENABLED_EVENTS: [WebhookEnabledEvent, ...WebhookEnabledEvent[]];
+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 an endpoint's `description` may be. */
+export declare const WEBHOOK_ENDPOINT_DESCRIPTION_MAX = 5000;
+/** The longest a rolled secret may keep signing beside its replacement. */
+export declare const WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS: number;
+/**
+ * Where one webhook delivery stands (ADR 0001 D7).
+ *
+ *  - `pending`   — will be attempted. `next_attempt_at` says when.
+ *  - `delivered` — terminal success.
+ *  - `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 over three days and the
+ *                  budget ran out. It can be redelivered by hand.
+ */
+export declare const WEBHOOK_DELIVERY_STATUSES: readonly ["pending", "delivered", "failed", "dead"];
+export type WebhookDeliveryStatus = (typeof WEBHOOK_DELIVERY_STATUSES)[number];

package/dist/types/vocabulary/files.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What a file is FOR. Decided at upload and never changed: the purpose is what
+ * sets the type and size policy, who may see the bytes, and which objects may
+ * reference the file — a `business_logo` is public, a `dispute_evidence` file
+ * is private and can only be attached to the merchant's own disputes.
+ */
+export declare const FILE_PURPOSES: readonly ["dispute_evidence", "business_logo", "identity_document", "additional_verification", "finance_report_run", "tax_document"];
+export type FilePurpose = (typeof FILE_PURPOSES)[number];
+/**
+ * The purposes a merchant may upload or import. `finance_report_run` is not
+ * among them: a report's CSV is written by Peable's report runs
+ * (`/v1/reporting/report_runs`) and nobody else, so a file of that purpose is
+ * always a report Peable produced.
+ */
+export declare const FILE_UPLOAD_PURPOSES: readonly ["dispute_evidence", "business_logo", "identity_document", "additional_verification", "tax_document"];
+export type FileUploadPurpose = (typeof FILE_UPLOAD_PURPOSES)[number];
+/** The stored format, by its conventional extension (Stripe's `type`). */
+export declare const FILE_TYPES: readonly ["pdf", "png", "jpg", "csv"];
+export type FileType = (typeof FILE_TYPES)[number];
+/**
+ * Whether the bytes can be used right now.
+ *
+ *  - `available` — Oxy serves the file; it can be shown or forwarded.
+ *  - `withheld` — the file still exists and is not being served (its owner
+ *    trashed it or made it private); it can come back.
+ *  - `removed` — Oxy said the file is gone for good (deleted, taken down, lost).
+ *    The object stays so whatever referenced it can say why it stopped working.
+ */
+export declare const FILE_STATUSES: readonly ["available", "withheld", "removed"];
+export type FileStatus = (typeof FILE_STATUSES)[number];

package/dist/types/vocabulary/index.d.ts

@@ -0,0 +1,17 @@
+export * from './billingPortal';
+export * from './connect';
+export * from './catalog';
+export * from './errors';
+export * from './invoices';
+export * from './events';
+export * from './lists';
+export * from './money';
+export * from './tax';
+export * from './subscriptions';
+export * from './reporting';
+export * from './payments';
+export * from './version';
+export * from './checkout';
+export * from './files';
+export * from './merchants';
+export * from './paymentMethodConfigurations';