@peable.to/contracts 0.3.0 → 1.0.0

package/dist/esm/vocabulary/billingPortal.js

@@ -0,0 +1,12 @@
+// The customer portal (ADR 0018 §9) — the closed value sets its schemas are
+// built from. Zod-free: `@peable.to/shared-types` re-exports them at runtime.
+/** What a portal customer may edit about themselves. */
+export const PORTAL_CUSTOMER_UPDATES = ['email', 'name', 'address', 'phone'];
+/** When a cancellation from the portal takes effect. */
+export const PORTAL_CANCEL_MODES = ['at_period_end', 'immediately'];
+/** How a cancellation from the portal prorates. */
+export const PORTAL_CANCEL_PRORATION_BEHAVIORS = ['create_prorations', 'none'];
+/** What a plan change from the portal may change. */
+export const PORTAL_SUBSCRIPTION_UPDATES = ['price', 'quantity'];
+/** What finishing a payment method update from the portal answered. */
+export const PORTAL_PAYMENT_METHOD_UPDATE_STATUSES = ['succeeded', 'pending'];

package/dist/esm/vocabulary/catalog.js

@@ -0,0 +1,106 @@
+// The catalog's and the billing engine platform's closed value sets (ADR 0016,
+// ADR 0018): what a price, a coupon, a test clock, a meter and the billing
+// settings can say, and the bounds the gateway enforces — restated so a form
+// can say them first. Zod-free: the wallet bundles this.
+import { decimalsFor } from './money.js';
+/** How a price's amount is computed from a quantity. */
+export const PRICE_BILLING_SCHEMES = ['per_unit', 'tiered'];
+/**
+ * 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 const PRICE_TIERS_MODES = ['graduated', 'volume'];
+/** `recurring` when the price has a recurring component, `one_time` otherwise. */
+export const PRICE_TYPES = ['one_time', 'recurring'];
+export const RECURRING_INTERVALS = ['day', 'week', 'month', 'year'];
+/**
+ * `licensed` bills the quantity on the subscription. `metered` bills the usage
+ * a meter (`recurring.meter`, `mtr_…`) aggregated over the period, in arrears.
+ */
+export const RECURRING_USAGE_TYPES = ['licensed', 'metered'];
+/**
+ * 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 const PRICE_TAX_BEHAVIORS = ['inclusive', 'exclusive', 'unspecified'];
+export const TRANSFORM_QUANTITY_ROUNDS = ['up', 'down'];
+/** How long a coupon's discount lasts once applied to a subscription. */
+export const COUPON_DURATIONS = ['once', 'repeating', 'forever'];
+/** The bounds the gateway enforces, published so a form can say them first. */
+export const CATALOG_LIMITS = Object.freeze({
+    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 const CATALOG_MAX_WHOLE_UNITS = 1000000000n;
+/** The largest base-unit amount of `currency` the catalog accepts. */
+export function maxBaseUnits(currency) {
+    return CATALOG_MAX_WHOLE_UNITS * 10n ** BigInt(decimalsFor(currency)) - 1n;
+}
+/** The longest a recurring interval may be: three years, in each unit. */
+export const RECURRING_INTERVAL_COUNT_MAX = Object.freeze({
+    day: 1095,
+    week: 156,
+    month: 36,
+    year: 3,
+});
+// ---- Test clocks -------------------------------------------------------------
+export const TEST_CLOCK_STATUSES = ['ready', 'advancing', 'internal_failure'];
+// ---- Billing settings --------------------------------------------------------
+/** What dunning does to a subscription once the last retry has failed. */
+export const DUNNING_FINAL_ACTIONS = ['cancel', 'unpaid', 'past_due'];
+/** What happens to the invoice itself once the last retry has failed. */
+export const DUNNING_INVOICE_ACTIONS = ['leave_open', 'mark_uncollectible'];
+/** The bounds the gateway enforces on billing settings. */
+export const BILLING_SETTINGS_LIMITS = Object.freeze({
+    retriesMax: 8,
+    retryDaysMax: 60,
+    daysUntilDueMax: 365,
+    invoicePrefixPattern: '^[A-Z0-9]{3,12}$',
+});
+// ---- Meters ------------------------------------------------------------------
+/** How a meter combines a period's events into the quantity billed. */
+export const METER_AGGREGATIONS = ['sum', 'count', 'last'];
+export const METER_STATUSES = ['active', 'inactive'];
+// ---- Recurring billing transport (`/v1/billing/*`) ---------------------------
+/** A provider subscription's status, as the recurring transport observes it. */
+export const BILLING_SUBSCRIPTION_STATUSES = [
+    'incomplete',
+    'incomplete_expired',
+    'trialing',
+    'active',
+    'past_due',
+    'canceled',
+    'unpaid',
+    'paused',
+];
+/** `fiat` (Stripe and any further provider) or `faircoin` (native, to the merchant's watch-only wallet). */
+export const BILLING_RAIL_SETTLEMENTS = ['fiat', 'faircoin'];
+/** `automatic`: the provider charges each period. `payer_initiated`: each period is an explicit payment. */
+export const BILLING_RAIL_RENEWALS = ['automatic', 'payer_initiated'];
+// Product tax codes are Peable Tax's vocabulary: `vocabulary/tax.ts` (`TAX_CODES`).

package/dist/esm/vocabulary/checkout.js

@@ -0,0 +1,50 @@
+// Checkout vocabulary (Orbit Phase 3): the closed value sets and bounds of
+// Checkout Sessions and Payment Links. Zod-free, so the hosted checkout and
+// the wallet import them without the schemas (`@peable.to/contracts/vocabulary`,
+// re-exported by `@peable.to/shared-types`).
+export const CHECKOUT_SESSION_MODES = ['payment', 'setup', 'subscription'];
+export const CHECKOUT_SESSION_STATUSES = ['open', 'complete', 'expired'];
+export const CHECKOUT_PAYMENT_STATUSES = ['paid', 'unpaid', 'no_payment_required'];
+export const CHECKOUT_UI_MODES = ['hosted', 'embedded'];
+/** The languages the hosted and embedded checkout speak. */
+export const CHECKOUT_LOCALES = ['en', 'es', 'fr', 'de', 'it', 'pt'];
+export const CHECKOUT_SUBMIT_TYPES = ['auto', 'pay', 'book', 'donate'];
+export const CHECKOUT_CUSTOMER_CREATIONS = ['always', 'if_required'];
+export const CHECKOUT_BILLING_ADDRESS_COLLECTIONS = ['auto', 'required'];
+export const CHECKOUT_CUSTOM_FIELD_TYPES = ['text', 'numeric', 'dropdown'];
+/** Stripe's tax id types Peable collects; `eu_vat` covers every EU member state. */
+export const CHECKOUT_TAX_ID_TYPES = [
+    'eu_vat',
+    'gb_vat',
+    'ch_vat',
+    'no_vat',
+    'us_ein',
+    'ca_bn',
+];
+/**
+ * Bounds of the session contract, shared by the gateway's validators and the
+ * clients that build requests, so the two cannot drift.
+ */
+export const CHECKOUT_LIMITS = Object.freeze({
+    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: 30 * 60,
+    expiresMaxSeconds: 24 * 3600,
+    shippingCountriesMax: 250,
+    termsTextMax: 1200,
+});
+/** The template a `success_url` may carry; replaced with the session's `cs_…`. */
+export const CHECKOUT_SESSION_ID_TEMPLATE = '{CHECKOUT_SESSION_ID}';
+export const PAYMENT_LINK_LIMITS = Object.freeze({
+    lineItemsMax: 20,
+    customMessageMax: 500,
+});

package/dist/esm/vocabulary/connect.js

@@ -0,0 +1,92 @@
+// Connect and money vocabulary (ADR 0012, ADR 0015): the closed value sets of
+// accounts, balances, payouts, application fees, transfers and reconciliation.
+// Zod-free, like every vocabulary module.
+/** Which half of an account a business type opens: the provider's two kinds. */
+export const ACCOUNT_BUSINESS_TYPES = ['individual', 'company'];
+/** A capability's state as the provider reports it; `null` on the wire means never requested. */
+export const ACCOUNT_CAPABILITY_STATUSES = ['active', 'pending', 'inactive'];
+/** Whose account an `account` is: the merchant's own, or one of its marketplace sellers. */
+export const ACCOUNT_TYPES = ['merchant', 'connected'];
+/** What a hosted onboarding link for the merchant's own account is for. */
+export const ACCOUNT_LINK_TYPES = ['account_onboarding', 'account_update'];
+/**
+ * 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 const CONNECTED_ACCOUNT_RAILS = ['card', 'faircoin'];
+/**
+ * Where a seller's FairCoin half stands: `pending` until the seller registers
+ * a key, `active` once they did.
+ */
+export const CONNECTED_ACCOUNT_FAIRCOIN_STATUSES = ['pending', 'active'];
+export const PAYOUT_INTERVALS = ['manual', 'daily', 'weekly', 'monthly'];
+export const PAYOUT_WEEKLY_ANCHORS = [
+    'monday',
+    'tuesday',
+    'wednesday',
+    'thursday',
+    'friday',
+    'saturday',
+    'sunday',
+];
+/** Orbit's vocabulary for what moved — the provider's own types, provider-neutral. */
+export const BALANCE_TRANSACTION_TYPES = [
+    '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',
+];
+/**
+ * - `pending` / `available` — the provider's own status for the funds.
+ * - `informational` — a FairCoin payment: recorded, never part of a payable balance.
+ */
+export const BALANCE_TRANSACTION_STATUSES = ['available', 'pending', 'informational'];
+/** One component of a transaction's fee. `processing_fee` is the acquirer's own. */
+export const BALANCE_TRANSACTION_FEE_TYPES = [
+    'application_fee',
+    'processing_fee',
+    'tax',
+    'other',
+];
+export const PAYOUT_STATUSES = ['pending', 'in_transit', 'paid', 'failed', 'canceled'];
+export const PAYOUT_METHODS = ['standard', 'instant'];
+export const PAYOUT_DESTINATION_TYPES = ['bank_account', 'card'];
+/**
+ * A payout reconciliation report's state: `complete` once the payout is `paid`
+ * and its transactions were read from the provider, `pending` before.
+ */
+export const PAYOUT_RECONCILIATION_STATUSES = ['complete', 'pending'];
+/** What the daily reconciliation found disagreeing with the provider. Never auto-corrected. */
+export const RECONCILIATION_MISMATCH_KINDS = [
+    'missing_in_ledger',
+    'amount_mismatch',
+    'status_mismatch',
+    'missing_at_provider',
+    'payout_mismatch',
+    'unbalanced_journal',
+];
+/** Where one settlement stands. */
+export const TRANSFER_STATUSES = [
+    'pending',
+    'paid',
+    'partially_reversed',
+    'reversed',
+    'failed',
+];
+/** Where one reversal of a settlement stands. */
+export const TRANSFER_REVERSAL_STATUSES = ['pending', 'succeeded', 'failed'];

package/dist/esm/vocabulary/errors.js

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

package/dist/esm/vocabulary/events.js

@@ -0,0 +1,173 @@
+// The event vocabulary (ADR 0014 D4, ADR 0019): every event type the gateway
+// emits and the `object` type its `data.object` carries. Zod-free, so the SDK's
+// signature check, the CLI and the backend's CHECK constraints read the same
+// closed set without constructing a schema.
+/**
+ * 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 const WEBHOOK_EVENT_OBJECTS = {
+    'payment_intent.created': 'payment_intent',
+    'payment_intent.requires_action': 'payment_intent',
+    'payment_intent.processing': 'payment_intent',
+    'payment_intent.amount_capturable_updated': 'payment_intent',
+    'payment_intent.succeeded': 'payment_intent',
+    'payment_intent.payment_failed': 'payment_intent',
+    'payment_intent.canceled': 'payment_intent',
+    'charge.refunded': 'charge',
+    'charge.dispute.created': 'dispute',
+    'charge.dispute.updated': 'dispute',
+    'charge.dispute.closed': 'dispute',
+    'charge.dispute.funds_withdrawn': 'dispute',
+    'charge.dispute.funds_reinstated': 'dispute',
+    'refund.created': 'refund',
+    'refund.updated': 'refund',
+    'refund.failed': 'refund',
+    'customer.created': 'customer',
+    'customer.updated': 'customer',
+    'customer.deleted': 'customer',
+    'payment_method.attached': 'payment_method',
+    'payment_method.detached': 'payment_method',
+    'payment_method.updated': 'payment_method',
+    'setup_intent.created': 'setup_intent',
+    'setup_intent.requires_action': 'setup_intent',
+    'setup_intent.succeeded': 'setup_intent',
+    'setup_intent.setup_failed': 'setup_intent',
+    'setup_intent.canceled': 'setup_intent',
+    'billing.observation.updated': 'billing_observation',
+    'connected_account.updated': 'connected_account',
+    'product.created': 'product',
+    'product.updated': 'product',
+    'product.deleted': 'product',
+    'price.created': 'price',
+    'price.updated': 'price',
+    'coupon.created': 'coupon',
+    'coupon.updated': 'coupon',
+    'coupon.deleted': 'coupon',
+    'promotion_code.created': 'promotion_code',
+    'promotion_code.updated': 'promotion_code',
+    'account.updated': 'account',
+    'application_fee.created': 'application_fee',
+    'application_fee.refunded': 'application_fee',
+    'payout.created': 'payout',
+    'payout.updated': 'payout',
+    'payout.paid': 'payout',
+    'payout.failed': 'payout',
+    'payout.canceled': 'payout',
+    'balance.available': 'balance',
+    'checkout.session.completed': 'checkout_session',
+    'checkout.session.expired': 'checkout_session',
+    'checkout.session.async_payment_succeeded': 'checkout_session',
+    'checkout.session.async_payment_failed': 'checkout_session',
+    'payment_link.created': 'payment_link',
+    'payment_link.updated': 'payment_link',
+    'reporting.report_run.succeeded': 'reporting.report_run',
+    'reporting.report_run.failed': 'reporting.report_run',
+    'customer.subscription.created': 'subscription',
+    'customer.subscription.updated': 'subscription',
+    'customer.subscription.deleted': 'subscription',
+    'customer.subscription.trial_will_end': 'subscription',
+    'customer.subscription.paused': 'subscription',
+    'customer.subscription.resumed': 'subscription',
+    'invoice.created': 'invoice',
+    'invoice.updated': 'invoice',
+    'invoice.deleted': 'invoice',
+    'invoice.finalized': 'invoice',
+    'invoice.paid': 'invoice',
+    'invoice.payment_failed': 'invoice',
+    'invoice.payment_action_required': 'invoice',
+    'invoice.voided': 'invoice',
+    'invoice.marked_uncollectible': 'invoice',
+    'invoice.upcoming': 'invoice',
+    'invoice.sent': 'invoice',
+    'invoiceitem.created': 'invoiceitem',
+    'invoiceitem.deleted': 'invoiceitem',
+    'credit_note.created': 'credit_note',
+    'credit_note.updated': 'credit_note',
+    'credit_note.voided': 'credit_note',
+    'test_helpers.test_clock.created': 'test_helpers.test_clock',
+    'test_helpers.test_clock.advancing': 'test_helpers.test_clock',
+    'test_helpers.test_clock.ready': 'test_helpers.test_clock',
+    'test_helpers.test_clock.deleted': 'test_helpers.test_clock',
+    'billing.meter.created': 'billing.meter',
+    'billing.meter.updated': 'billing.meter',
+    'billing.meter.deactivated': 'billing.meter',
+    'billing.meter.reactivated': 'billing.meter',
+    'entitlements.active_entitlement_summary.updated': 'entitlements.active_entitlement_summary',
+    'billing_portal.configuration.created': 'billing_portal.configuration',
+    'billing_portal.configuration.updated': 'billing_portal.configuration',
+    'billing_portal.session.created': 'billing_portal.session',
+    'tax.assessment.created': 'tax.assessment',
+    'tax.review_item.created': 'tax.review_item',
+    'tax.review_item.updated': 'tax.review_item',
+    'webhook_endpoint.test': 'webhook_endpoint',
+};
+/** Every event type, in {@link WEBHOOK_EVENT_OBJECTS} order. */
+export const WEBHOOK_EVENT_TYPES = Object.keys(WEBHOOK_EVENT_OBJECTS);
+/**
+ * The event types never fanned out by subscription — sent only to the one
+ * endpoint they name. `enabled_events` refuses them.
+ */
+export const TARGETED_WEBHOOK_EVENT_TYPES = [
+    'webhook_endpoint.test',
+];
+/** What `enabled_events` may hold: `*`, then every subscribable type. */
+export const WEBHOOK_ENABLED_EVENTS = [
+    '*',
+    ...WEBHOOK_EVENT_TYPES.filter((type) => !TARGETED_WEBHOOK_EVENT_TYPES.includes(type)),
+];
+export const WEBHOOK_ENDPOINT_STATUSES = ['enabled', 'disabled'];
+/**
+ * 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 const WEBHOOK_ENDPOINT_DISABLED_REASONS = [
+    'disabled_by_merchant',
+    'delivery_failures',
+];
+/** At most this many endpoints per merchant (per mode). */
+export const WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = 16;
+/** The longest an endpoint's `description` may be. */
+export const WEBHOOK_ENDPOINT_DESCRIPTION_MAX = 5000;
+/** The longest a rolled secret may keep signing beside its replacement. */
+export const WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS = 24 * 60 * 60;
+/**
+ * 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 const WEBHOOK_DELIVERY_STATUSES = ['pending', 'delivered', 'failed', 'dead'];

package/dist/esm/vocabulary/files.js

@@ -0,0 +1,41 @@
+// Files vocabulary (`file_…`): what a file is for, the formats it is stored
+// in, and whether its bytes are being served. Zod-free.
+/**
+ * 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 const FILE_PURPOSES = [
+    'dispute_evidence',
+    'business_logo',
+    'identity_document',
+    'additional_verification',
+    'finance_report_run',
+    'tax_document',
+];
+/**
+ * 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 const FILE_UPLOAD_PURPOSES = [
+    'dispute_evidence',
+    'business_logo',
+    'identity_document',
+    'additional_verification',
+    'tax_document',
+];
+/** The stored format, by its conventional extension (Stripe's `type`). */
+export const FILE_TYPES = ['pdf', 'png', 'jpg', 'csv'];
+/**
+ * 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 const FILE_STATUSES = ['available', 'withheld', 'removed'];