@peable.to/contracts 0.4.0 → 1.0.0

package/dist/esm/vocabulary/index.js

@@ -0,0 +1,21 @@
+// `@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 './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 './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'];

package/dist/esm/vocabulary/reporting.js

@@ -0,0 +1,24 @@
+// Reporting and request-log vocabulary: the report types Peable produces, a
+// run's lifecycle, and the methods and status classes a request log is
+// filtered by. Zod-free, like every vocabulary module.
+/**
+ * Every report Peable produces, by Stripe's versioned id: the trailing `.1` is
+ * the column layout's version, so a layout can change under a new id without
+ * changing a report a merchant already parses. The layouts themselves are
+ * `REPORT_TYPE_LAYOUTS` in `@peable.to/shared-types/reporting`.
+ */
+export const REPORT_TYPE_IDS = [
+    'payments.itemized.1',
+    'balance.summary.1',
+    'balance_transactions.itemized.1',
+    'payouts.itemized.1',
+    'refunds.itemized.1',
+    'disputes.itemized.1',
+];
+export const REPORT_RUN_STATUSES = ['pending', 'succeeded', 'failed'];
+/** The HTTP methods a request log records. */
+export const REQUEST_LOG_METHODS = ['GET', 'POST', 'DELETE', 'PATCH', 'PUT'];
+/** A request-log `status` filter's class form (`4xx` is 400–499). */
+export const REQUEST_LOG_STATUS_CLASSES = ['2xx', '3xx', '4xx', '5xx'];
+/** How long a request log is kept (and served). */
+export const REQUEST_LOG_RETENTION_DAYS = 30;

package/dist/esm/vocabulary/subscriptions.js

@@ -0,0 +1,57 @@
+// Subscriptions (ADR 0018 §1) — the closed value sets their schemas are built
+// from. Zod-free: `@peable.to/shared-types` re-exports them at runtime.
+/**
+ * Where a subscription stands — Stripe's eight.
+ *
+ *  - `incomplete`          — the first invoice is not paid yet; expires to
+ *                            `incomplete_expired` when nobody pays it in time.
+ *  - `incomplete_expired`  — terminal: the first invoice was never paid.
+ *  - `trialing`            — in a trial; nothing is charged until it ends.
+ *  - `active`              — in good standing.
+ *  - `past_due`            — a renewal invoice failed; dunning is retrying it.
+ *  - `unpaid`              — dunning gave up and the merchant's final action
+ *                            is `unpaid`: invoices are still created, access
+ *                            should be withdrawn.
+ *  - `canceled`            — terminal.
+ *  - `paused`              — a trial ended with no payment method and the
+ *                            trial's end behaviour was `pause`; resumed with
+ *                            `POST /v1/subscriptions/:id/resume`.
+ */
+export const SUBSCRIPTION_STATUSES = [
+    'incomplete',
+    'incomplete_expired',
+    'trialing',
+    'active',
+    'past_due',
+    'unpaid',
+    'canceled',
+    'paused',
+];
+/** `status=` on a subscription list: a status, `all` (including canceled), or `ended`. */
+export const SUBSCRIPTION_LIST_STATUSES = [...SUBSCRIPTION_STATUSES, 'all', 'ended'];
+/** How the subscription's invoices are collected. FairCoin is always `send_invoice`. */
+export const COLLECTION_METHODS = ['charge_automatically', 'send_invoice'];
+/** How a change mid-period is billed. */
+export const PRORATION_BEHAVIORS = ['create_prorations', 'none', 'always_invoice'];
+/** The proration behaviours a subscription CREATE accepts: there is nothing to invoice at once yet. */
+export const CREATE_PRORATION_BEHAVIORS = [
+    'create_prorations',
+    'none',
+];
+/** What a create does when the first invoice cannot be paid at once. */
+export const PAYMENT_BEHAVIORS = [
+    'allow_incomplete',
+    'default_incomplete',
+    'error_if_incomplete',
+];
+/** What happens to the invoices of a subscription whose collection is paused. */
+export const PAUSE_COLLECTION_BEHAVIORS = ['keep_as_draft', 'mark_uncollectible', 'void'];
+/** What a trial ending with no payment method does (`trial_settings.end_behavior`). */
+export const TRIAL_END_BEHAVIORS = ['cancel', 'create_invoice', 'pause'];
+/** Why a subscription was cancelled. */
+export const SUBSCRIPTION_CANCELLATION_REASONS = [
+    'cancellation_requested',
+    'payment_failed',
+];
+/** `billing_cycle_anchor` on a resume: a new period now (the default), or the anchor kept. */
+export const RESUME_BILLING_CYCLE_ANCHORS = ['now', 'unchanged'];