@peable.to/contracts 0.4.0 → 1.1.0

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'];

package/dist/esm/vocabulary/identity.js

@@ -0,0 +1,9 @@
+/**
+ * Peable's own Oxy application: the identity the gateway runs as (`OxyServer`'s
+ * `applicationId`) and the one an Oxy service addresses when it calls the
+ * gateway. One constant, so the gateway's accepted audience and the SDK's
+ * requested one cannot name two different applications.
+ */
+export const PEABLE_OXY_APPLICATION_ID = '6a2f851751b784a86fd0e958';
+/** The service-token audience of Peable's gateway (`oxy-service:<application id>`). */
+export const PEABLE_SERVICE_AUDIENCE = `oxy-service:${PEABLE_OXY_APPLICATION_ID}`;

package/dist/esm/vocabulary/index.js

@@ -0,0 +1,23 @@
+// `@peable.to/contracts/vocabulary` — the zod-free half of the contract: the
+// closed value sets (currencies, statuses, event types, error codes) a schema
+// is built from. A bundle that must stay small imports this subpath, never the
+// package root, which constructs every schema at load.
+export * from './billingPortal.js';
+export * from './connect.js';
+export * from './dashboard.js';
+export * from './catalog.js';
+export * from './errors.js';
+export * from './invoices.js';
+export * from './events.js';
+export * from './lists.js';
+export * from './money.js';
+export * from './tax.js';
+export * from './subscriptions.js';
+export * from './reporting.js';
+export * from './payments.js';
+export * from './version.js';
+export * from './checkout.js';
+export * from './files.js';
+export * from './identity.js';
+export * from './merchants.js';
+export * from './paymentMethodConfigurations.js';

package/dist/esm/vocabulary/invoices.js

@@ -0,0 +1,49 @@
+// Invoices, invoice items, credit notes and the customer balance (ADR 0018
+// §2–4) — the closed value sets their schemas are built from. Zod-free:
+// `@peable.to/shared-types` re-exports them at runtime.
+export const INVOICE_STATUSES = ['draft', 'open', 'paid', 'void', 'uncollectible'];
+/** Why an invoice exists. */
+export const INVOICE_BILLING_REASONS = [
+    'manual',
+    'subscription_create',
+    'subscription_cycle',
+    'subscription_update',
+    'subscription_cancel',
+    'upcoming',
+];
+/**
+ * `automatic_tax.status` — Peable Tax (ADR 0011) is computed before an invoice
+ * finalizes (ADR 0018 §2).
+ *
+ *  - `requires_location_inputs` — the customer's location could not be
+ *    established; the invoice cannot finalize until it can.
+ *  - `failed`                   — the calculation failed closed (the provider
+ *    was unavailable, or disagreed with Peable's registrations); retried.
+ *  - `complete`                 — calculated (including `not_registered`,
+ *    which is a calculation that collects zero).
+ */
+export const AUTOMATIC_TAX_STATUSES = ['requires_location_inputs', 'failed', 'complete'];
+/** Where an invoice line comes from: a subscription item's period, or an invoice item. */
+export const INVOICE_LINE_TYPES = ['subscription', 'invoiceitem'];
+/** `pending_invoice_items_behavior` on an invoice create. Default `exclude` (Stripe's). */
+export const PENDING_INVOICE_ITEMS_BEHAVIORS = ['include', 'exclude'];
+export const CREDIT_NOTE_STATUSES = ['issued', 'void'];
+/** `pre_payment` reduces what an open invoice asks for; `post_payment` gives back on a paid one. */
+export const CREDIT_NOTE_TYPES = ['pre_payment', 'post_payment'];
+export const CREDIT_NOTE_REASONS = [
+    'duplicate',
+    'fraudulent',
+    'order_change',
+    'product_unsatisfactory',
+];
+/** A credit note line: part of an invoice line, or a custom amount. */
+export const CREDIT_NOTE_LINE_TYPES = ['invoice_line_item', 'custom_line_item'];
+export const CUSTOMER_BALANCE_TRANSACTION_TYPES = [
+    'adjustment',
+    'applied_to_invoice',
+    'credit_note',
+    'invoice_overpaid',
+    'unapplied_from_invoice',
+];
+/** The rails a hosted invoice is paid on: a card through the provider's fields, FairCoin from the payer's wallet. */
+export const PUBLIC_INVOICE_PAYMENT_METHOD_TYPES = ['card', 'faircoin'];

package/dist/esm/vocabulary/lists.js

@@ -0,0 +1,19 @@
+// List and search bounds (ADR 0014 D1) — the gateway's, restated so a client
+// can check before it asks.
+export const LIST_LIMIT_DEFAULT = 10;
+export const LIST_LIMIT_MAX = 100;
+export const SEARCH_QUERY_MAX_LENGTH = 1000;
+export const SEARCH_QUERY_MAX_CLAUSES = 10;
+/** A `~` substring needs at least this many characters (Stripe's rule). */
+export const SEARCH_SUBSTRING_MIN_LENGTH = 3;
+/** Every searchable resource, by its path segment (`/v1/<resource>/search`). */
+export const SEARCHABLE_RESOURCES = [
+    'payment_intents',
+    'charges',
+    'customers',
+    'products',
+    'prices',
+    'refunds',
+    'subscriptions',
+    'invoices',
+];

package/dist/esm/vocabulary/merchants.js

@@ -0,0 +1,20 @@
+// Merchant vocabulary: the environments a merchant lives in, and the closed
+// sets branding draws from. Every branding value is from a CLOSED set or a
+// validated colour, so nothing a merchant stores can inject markup or a remote
+// font into a payer's page or an email. Zod-free.
+export const MERCHANT_ENVIRONMENTS = ['development', 'staging', 'production'];
+/** The fonts checkout may render in — system stacks only, no remote font is ever loaded. */
+export const BRANDING_FONTS = [
+    'system',
+    'inter',
+    'roboto',
+    'open_sans',
+    'lato',
+    'source_sans',
+    'noto_sans',
+    'serif',
+    'monospace',
+];
+export const BRANDING_BORDER_STYLES = ['rounded', 'rectangular', 'pill'];
+/** `#rrggbb`, lowercase — the only colour spelling branding stores. */
+export const BRANDING_COLOR_PATTERN = /^#[0-9a-f]{6}$/;

package/dist/esm/vocabulary/money.js

@@ -0,0 +1,98 @@
+// Money vocabulary. Every monetary value moves through the gateway as a
+// canonical integer string in the currency's SMALLEST unit — m⊜ for FairCoin,
+// cents for a fiat currency — so no float ever touches one.
+//
+// Zod-free on purpose: `@peable.to/contracts/vocabulary` is what a bundle that
+// must stay small (the wallet, the hosted checkout) imports at runtime, through
+// `@peable.to/shared-types`.
+/**
+ * The currencies this gateway can denominate a payment in: FairCoin on the
+ * chain rail, and on the card rail the fiat set the provider settles for the
+ * payment methods Orbit offers (cards, wallets, SEPA Debit, iDEAL, Bancontact,
+ * EPS). A local method narrows it further per payment
+ * (`PAYMENT_METHOD_CURRENCIES` in `paymentMethodConfiguration.ts`).
+ *
+ * A closed set, and the database mirrors it as a CHECK
+ * (`db/schema/valueSets.ts`). ADR 0001 D4: the scale of an amount is a property
+ * of its currency and is NOT implied by the field's type, which is why
+ * {@link CURRENCY_DECIMALS} exists and why {@link UNITS_PER_COIN} must never be
+ * used to interpret a fiat amount.
+ */
+export const CURRENCY_CODES = [
+    'FAIR',
+    'EUR',
+    'USD',
+    'GBP',
+    'CHF',
+    'SEK',
+    'NOK',
+    'DKK',
+    'PLN',
+    'CZK',
+    'CAD',
+    'AUD',
+    'JPY',
+];
+/** Whether an arbitrary string is a currency this gateway knows. */
+export function isCurrencyCode(value) {
+    return CURRENCY_CODES.includes(value);
+}
+/**
+ * How many decimal places each currency's smallest unit represents — i.e. an
+ * amount of `1` means `10^-decimals` of one whole unit.
+ *
+ * ISO 4217's minor units for every fiat member (JPY has none). FairCoin's 8 is
+ * a consensus constant and is pinned against {@link UNITS_PER_COIN} by this
+ * package's own tests, so the two spellings of one fact cannot drift.
+ */
+export const CURRENCY_DECIMALS = Object.freeze({
+    FAIR: 8,
+    EUR: 2,
+    USD: 2,
+    GBP: 2,
+    CHF: 2,
+    SEK: 2,
+    NOK: 2,
+    DKK: 2,
+    PLN: 2,
+    CZK: 2,
+    CAD: 2,
+    AUD: 2,
+    // A zero-decimal currency: an amount of `1` is one yen, never a hundredth of
+    // one. The provider counts JPY the same way, so the base unit crosses as is.
+    JPY: 0,
+});
+/** The fiat members — every currency the card rail can denominate a payment in. */
+export const FIAT_CURRENCY_CODES = CURRENCY_CODES.filter((code) => code !== 'FAIR');
+/** The decimal places of `currency`'s smallest unit. */
+export function decimalsFor(currency) {
+    return CURRENCY_DECIMALS[currency];
+}
+/**
+ * Frozen FairCoin consensus constant (smallest units per FAIR). Mirrors
+ * `@fairco.in/core`'s branding.ts; inlined to keep this module zero-dependency
+ * for a clean CJS+ESM publish — must stay a bigint, never converted to number.
+ *
+ * FAIRCOIN ONLY. A fiat amount has its own scale (`CURRENCY_DECIMALS`), and
+ * dividing a EUR amount by this constant is off by six orders of magnitude with
+ * nothing failing.
+ */
+export const UNITS_PER_COIN = 100000000n;
+/** The spelling of a base-unit amount: digits, no sign, no leading zeros but `0`. */
+export const BASE_UNIT_PATTERN = /^(0|[1-9][0-9]*)$/;
+/** A signed base-unit amount (a customer balance, a balance transaction's net). */
+export const SIGNED_BASE_UNIT_PATTERN = /^(0|-?[1-9][0-9]*)$/;
+/**
+ * True only for a canonical non-negative integer string in the currency's
+ * smallest unit: one or more decimal digits, no sign, no decimal point, no
+ * leading zeros (except the literal "0"). Floats and negatives are rejected.
+ *
+ * Currency-agnostic on purpose — the pattern is about the SPELLING of an
+ * amount, not its scale, and the same one is restated as a CHECK in the
+ * database (`BASE_UNIT_STRING_PATTERN`), byte-identical.
+ */
+export function isBaseUnitString(s) {
+    return BASE_UNIT_PATTERN.test(s);
+}
+/** FairCoin network identifier, mirroring `@fairco.in/core`'s `NetworkType`. */
+export const NETWORK_TYPES = ['mainnet', 'testnet'];

package/dist/esm/vocabulary/paymentMethodConfigurations.js

@@ -0,0 +1,33 @@
+// Payment method breadth on the card rail (`pmc_…`, `pmd_…`). Zod-free.
+/**
+ * The methods a configuration can turn on.
+ *
+ * `apple_pay` and `google_pay` are WALLETS over a card: a payment made with one
+ * is a `card` payment, so they appear here and never in a PaymentIntent's
+ * `payment_method_types`. `bizum` is listed because merchants ask for it and the
+ * honest answer is a reason, not an absence: the provider does not offer it.
+ *
+ * Deliberately absent: the provider's own consumer wallet (its brand on Orbit's
+ * checkout, `payment-provider-boundary.md`) and giropay (discontinued by the
+ * scheme).
+ */
+export const PAYMENT_METHOD_CONFIGURATION_TYPES = [
+    'card',
+    'apple_pay',
+    'google_pay',
+    'sepa_debit',
+    'ideal',
+    'bancontact',
+    'eps',
+    'bizum',
+];
+/**
+ * Why a method cannot be offered whatever the merchant chooses.
+ *
+ *  - `provider_unsupported` — the processing provider does not offer it;
+ *  - `requires_card` — a wallet rides on card payments, and card is off.
+ */
+export const PAYMENT_METHOD_UNAVAILABLE_REASONS = [
+    'provider_unsupported',
+    'requires_card',
+];

package/dist/esm/vocabulary/payments.js

@@ -0,0 +1,192 @@
+// The payments vocabulary (ADR 0014 D5): the closed value sets the payment
+// intent, charge, refund, dispute, setup intent, social and test-helper
+// contracts are built from. Zod-free, so the wallet and the shared types read
+// them without bundling a schema.
+/**
+ * Which rail moves the money (ADR 0001 D1). On the INTENT, not on the merchant:
+ * one merchant takes both, and the rail decides which fields mean anything.
+ */
+export const PAYMENT_INTENT_RAILS = ['faircoin', 'card'];
+/**
+ * Stripe's seven statuses, and no others (ADR 0019). The FairCoin rail walks
+ * four of them (`requires_action` → `processing` → `succeeded` | `canceled`); a
+ * card walks all seven. The order is the lifecycle table's
+ * (`@peable.to/shared-types`), which the database CHECK is rendered from.
+ */
+export const PAYMENT_INTENT_STATUSES = [
+    'requires_payment_method',
+    'requires_confirmation',
+    'requires_action',
+    'processing',
+    'requires_capture',
+    'succeeded',
+    'canceled',
+];
+/**
+ * Why an intent was cancelled — Stripe's reasons, plus `underpaid` (FairCoin
+ * only: a transaction paid less than the amount).
+ */
+export const PAYMENT_INTENT_CANCELLATION_REASONS = [
+    'abandoned',
+    'automatic',
+    'duplicate',
+    'fraudulent',
+    'requested_by_customer',
+    'underpaid',
+];
+/** The reasons a MERCHANT may give `POST /v1/payment_intents/:id/cancel`. */
+export const MERCHANT_CANCELLATION_REASONS = [
+    'abandoned',
+    'duplicate',
+    'fraudulent',
+    'requested_by_customer',
+];
+/** When a card is captured: at confirmation, or by `POST …/capture` (card only). */
+export const PAYMENT_INTENT_CAPTURE_METHODS = ['automatic', 'manual'];
+/** Card only: keep the payment method on the customer for later (ADR 0016). */
+export const PAYMENT_INTENT_SETUP_FUTURE_USAGES = ['on_session', 'off_session'];
+/** The card-rail types a PaymentIntent can carry in `payment_method_types`. */
+export const CARD_RAIL_PAYMENT_METHOD_TYPES = [
+    'card',
+    'sepa_debit',
+    'ideal',
+    'bancontact',
+    'eps',
+];
+/**
+ * Every payment method type a PaymentIntent can carry: `faircoin` on the chain
+ * rail, the card rail's otherwise. Wallets (Apple Pay, Google Pay) are `card`.
+ */
+export const PAYMENT_METHOD_TYPES = ['faircoin', ...CARD_RAIL_PAYMENT_METHOD_TYPES];
+/** The kinds of `last_payment_error` (and a SetupIntent's `last_setup_error`). */
+export const PAYMENT_ERROR_TYPES = ['card_error', 'payment_error', 'api_error'];
+/** How the payer's client continues: a confirmation credential, or a redirect. */
+export const CLIENT_ACTION_KINDS = ['client_secret', 'redirect'];
+// ---------------------------------------------------------------------------
+// Refunds and settlements
+// ---------------------------------------------------------------------------
+/**
+ * Where one refund stands — the MONEY's own lifecycle, not the payment's.
+ * `canceled` only through `POST /v1/refunds/:id/cancel`.
+ */
+export const REFUND_STATUSES = ['pending', 'succeeded', 'failed', 'canceled'];
+/** Stripe's refund reasons. */
+export const REFUND_REASONS = ['duplicate', 'fraudulent', 'requested_by_customer'];
+/**
+ * Who created a refund. `provider`: it appeared at the acquirer (a dashboard
+ * refund, a dispute's resolution) and was imported, without an `external_ref`.
+ */
+export const REFUND_ORIGINS = ['merchant', 'provider'];
+/** Where a payment's settlement figures stand. `unknown` is not zero. */
+export const SETTLEMENT_STATUSES = ['available', 'pending', 'unknown'];
+// ---------------------------------------------------------------------------
+// Disputes
+// ---------------------------------------------------------------------------
+/**
+ * Where a dispute stands. `needs_response` and `under_review` are open; `won`
+ * and `lost` are terminal. There is deliberately no `closed`.
+ */
+export const DISPUTE_STATUSES = ['needs_response', 'under_review', 'won', 'lost'];
+/** Why the cardholder disputed — Stripe's enum; an unmapped network reason reads `general`. */
+export const DISPUTE_REASONS = [
+    'bank_cannot_process',
+    'check_returned',
+    'credit_not_processed',
+    'customer_initiated',
+    'debit_not_authorized',
+    'duplicate',
+    'fraudulent',
+    'general',
+    'incorrect_account_details',
+    'insufficient_funds',
+    'noncompliant',
+    'product_not_received',
+    'product_unacceptable',
+    'subscription_canceled',
+    'unrecognized',
+];
+/**
+ * The TEXT evidence fields — the network's names, never a Peable paraphrase: a
+ * merchant assembling a defence reads their acquirer's guidance, and renamed
+ * fields would make it not apply. The Stripe adapter's name map is a total
+ * `Record` over this set, so a field added here does not compile until it
+ * carries it.
+ */
+export const DISPUTE_TEXT_EVIDENCE_FIELDS = [
+    'access_activity_log',
+    'billing_address',
+    'cancellation_policy_disclosure',
+    'cancellation_rebuttal',
+    'customer_email_address',
+    'customer_name',
+    'customer_purchase_ip',
+    'duplicate_charge_explanation',
+    'product_description',
+    'refund_policy_disclosure',
+    'refund_refusal_explanation',
+    'service_date',
+    'shipping_address',
+    'shipping_carrier',
+    'shipping_date',
+    'shipping_tracking_number',
+    'uncategorized_text',
+];
+/** The FILE evidence fields: each names a `file_…` of purpose `dispute_evidence`. */
+export const DISPUTE_FILE_EVIDENCE_FIELDS = [
+    'cancellation_policy',
+    'customer_communication',
+    'customer_signature',
+    'duplicate_charge_documentation',
+    'receipt',
+    'refund_policy',
+    'service_documentation',
+    'shipping_documentation',
+    'uncategorized_file',
+];
+/** The provider's ceiling on one TEXT evidence field, restated where the request is parsed. */
+export const DISPUTE_EVIDENCE_TEXT_MAX = 20000;
+// ---------------------------------------------------------------------------
+// SetupIntents
+// ---------------------------------------------------------------------------
+export const SETUP_INTENT_STATUSES = [
+    'requires_payment_method',
+    'requires_confirmation',
+    'requires_action',
+    'processing',
+    'canceled',
+    'succeeded',
+];
+export const SETUP_INTENT_USAGES = ['on_session', 'off_session'];
+export const SETUP_INTENT_CANCELLATION_REASONS = [
+    'abandoned',
+    'duplicate',
+    'requested_by_customer',
+];
+// ---------------------------------------------------------------------------
+// Social payments and enrichment
+// ---------------------------------------------------------------------------
+/**
+ * Longest `source.app` of a social payment: an app slug, not a label. The
+ * column CHECK reads the same bound.
+ */
+export const SOCIAL_SOURCE_APP_MAX_LENGTH = 32;
+/**
+ * Longest `source.ref` of a social payment. The bound is the whole defence: the
+ * value is opaque, so nothing downstream would notice it growing.
+ */
+export const SOCIAL_SOURCE_REF_MAX_LENGTH = 128;
+/** Which side of a social payment the caller was on. */
+export const SOCIAL_PAYMENT_DIRECTIONS = ['sent', 'received'];
+/** Where a transaction's counterparty identity came from. */
+export const ENRICHMENT_KINDS = ['merchant', 'user', 'unknown'];
+/** How many addresses one `POST /v1/enrich` resolves (and one social history lists). */
+export const ENRICH_MAX_ADDRESSES = 50;
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+/**
+ * What `simulate_faircoin_payment` pretends the payer did: `settled` paid the
+ * full amount (`processing` → `succeeded`); `underpaid` sent less
+ * (`processing` → `canceled`, `cancellation_reason: 'underpaid'`).
+ */
+export const SIMULATED_FAIRCOIN_OUTCOMES = ['settled', 'underpaid'];