@peable.to/contracts 0.4.0 → 1.0.0

package/dist/cjs/vocabulary/paymentMethodConfigurations.js

@@ -0,0 +1,36 @@
+"use strict";
+// Payment method breadth on the card rail (`pmc_…`, `pmd_…`). Zod-free.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAYMENT_METHOD_UNAVAILABLE_REASONS = exports.PAYMENT_METHOD_CONFIGURATION_TYPES = void 0;
+/**
+ * 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).
+ */
+exports.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.
+ */
+exports.PAYMENT_METHOD_UNAVAILABLE_REASONS = [
+    'provider_unsupported',
+    'requires_card',
+];

package/dist/cjs/vocabulary/payments.js

@@ -0,0 +1,195 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIMULATED_FAIRCOIN_OUTCOMES = exports.ENRICH_MAX_ADDRESSES = exports.ENRICHMENT_KINDS = exports.SOCIAL_PAYMENT_DIRECTIONS = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.SETUP_INTENT_CANCELLATION_REASONS = exports.SETUP_INTENT_USAGES = exports.SETUP_INTENT_STATUSES = exports.DISPUTE_EVIDENCE_TEXT_MAX = exports.DISPUTE_FILE_EVIDENCE_FIELDS = exports.DISPUTE_TEXT_EVIDENCE_FIELDS = exports.DISPUTE_REASONS = exports.DISPUTE_STATUSES = exports.SETTLEMENT_STATUSES = exports.REFUND_ORIGINS = exports.REFUND_REASONS = exports.REFUND_STATUSES = exports.CLIENT_ACTION_KINDS = exports.PAYMENT_ERROR_TYPES = exports.PAYMENT_METHOD_TYPES = exports.CARD_RAIL_PAYMENT_METHOD_TYPES = exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = exports.PAYMENT_INTENT_CAPTURE_METHODS = exports.MERCHANT_CANCELLATION_REASONS = exports.PAYMENT_INTENT_CANCELLATION_REASONS = exports.PAYMENT_INTENT_STATUSES = exports.PAYMENT_INTENT_RAILS = void 0;
+/**
+ * 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.
+ */
+exports.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.
+ */
+exports.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).
+ */
+exports.PAYMENT_INTENT_CANCELLATION_REASONS = [
+    'abandoned',
+    'automatic',
+    'duplicate',
+    'fraudulent',
+    'requested_by_customer',
+    'underpaid',
+];
+/** The reasons a MERCHANT may give `POST /v1/payment_intents/:id/cancel`. */
+exports.MERCHANT_CANCELLATION_REASONS = [
+    'abandoned',
+    'duplicate',
+    'fraudulent',
+    'requested_by_customer',
+];
+/** When a card is captured: at confirmation, or by `POST …/capture` (card only). */
+exports.PAYMENT_INTENT_CAPTURE_METHODS = ['automatic', 'manual'];
+/** Card only: keep the payment method on the customer for later (ADR 0016). */
+exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = ['on_session', 'off_session'];
+/** The card-rail types a PaymentIntent can carry in `payment_method_types`. */
+exports.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`.
+ */
+exports.PAYMENT_METHOD_TYPES = ['faircoin', ...exports.CARD_RAIL_PAYMENT_METHOD_TYPES];
+/** The kinds of `last_payment_error` (and a SetupIntent's `last_setup_error`). */
+exports.PAYMENT_ERROR_TYPES = ['card_error', 'payment_error', 'api_error'];
+/** How the payer's client continues: a confirmation credential, or a redirect. */
+exports.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`.
+ */
+exports.REFUND_STATUSES = ['pending', 'succeeded', 'failed', 'canceled'];
+/** Stripe's refund reasons. */
+exports.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`.
+ */
+exports.REFUND_ORIGINS = ['merchant', 'provider'];
+/** Where a payment's settlement figures stand. `unknown` is not zero. */
+exports.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`.
+ */
+exports.DISPUTE_STATUSES = ['needs_response', 'under_review', 'won', 'lost'];
+/** Why the cardholder disputed — Stripe's enum; an unmapped network reason reads `general`. */
+exports.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.
+ */
+exports.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`. */
+exports.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. */
+exports.DISPUTE_EVIDENCE_TEXT_MAX = 20000;
+// ---------------------------------------------------------------------------
+// SetupIntents
+// ---------------------------------------------------------------------------
+exports.SETUP_INTENT_STATUSES = [
+    'requires_payment_method',
+    'requires_confirmation',
+    'requires_action',
+    'processing',
+    'canceled',
+    'succeeded',
+];
+exports.SETUP_INTENT_USAGES = ['on_session', 'off_session'];
+exports.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.
+ */
+exports.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.
+ */
+exports.SOCIAL_SOURCE_REF_MAX_LENGTH = 128;
+/** Which side of a social payment the caller was on. */
+exports.SOCIAL_PAYMENT_DIRECTIONS = ['sent', 'received'];
+/** Where a transaction's counterparty identity came from. */
+exports.ENRICHMENT_KINDS = ['merchant', 'user', 'unknown'];
+/** How many addresses one `POST /v1/enrich` resolves (and one social history lists). */
+exports.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'`).
+ */
+exports.SIMULATED_FAIRCOIN_OUTCOMES = ['settled', 'underpaid'];

package/dist/cjs/vocabulary/reporting.js

@@ -0,0 +1,27 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUEST_LOG_RETENTION_DAYS = exports.REQUEST_LOG_STATUS_CLASSES = exports.REQUEST_LOG_METHODS = exports.REPORT_RUN_STATUSES = exports.REPORT_TYPE_IDS = void 0;
+/**
+ * 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`.
+ */
+exports.REPORT_TYPE_IDS = [
+    'payments.itemized.1',
+    'balance.summary.1',
+    'balance_transactions.itemized.1',
+    'payouts.itemized.1',
+    'refunds.itemized.1',
+    'disputes.itemized.1',
+];
+exports.REPORT_RUN_STATUSES = ['pending', 'succeeded', 'failed'];
+/** The HTTP methods a request log records. */
+exports.REQUEST_LOG_METHODS = ['GET', 'POST', 'DELETE', 'PATCH', 'PUT'];
+/** A request-log `status` filter's class form (`4xx` is 400–499). */
+exports.REQUEST_LOG_STATUS_CLASSES = ['2xx', '3xx', '4xx', '5xx'];
+/** How long a request log is kept (and served). */
+exports.REQUEST_LOG_RETENTION_DAYS = 30;

package/dist/cjs/vocabulary/subscriptions.js

@@ -0,0 +1,60 @@
+"use strict";
+// Subscriptions (ADR 0018 §1) — the closed value sets their schemas are built
+// from. Zod-free: `@peable.to/shared-types` re-exports them at runtime.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESUME_BILLING_CYCLE_ANCHORS = exports.SUBSCRIPTION_CANCELLATION_REASONS = exports.TRIAL_END_BEHAVIORS = exports.PAUSE_COLLECTION_BEHAVIORS = exports.PAYMENT_BEHAVIORS = exports.CREATE_PRORATION_BEHAVIORS = exports.PRORATION_BEHAVIORS = exports.COLLECTION_METHODS = exports.SUBSCRIPTION_LIST_STATUSES = exports.SUBSCRIPTION_STATUSES = void 0;
+/**
+ * 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`.
+ */
+exports.SUBSCRIPTION_STATUSES = [
+    'incomplete',
+    'incomplete_expired',
+    'trialing',
+    'active',
+    'past_due',
+    'unpaid',
+    'canceled',
+    'paused',
+];
+/** `status=` on a subscription list: a status, `all` (including canceled), or `ended`. */
+exports.SUBSCRIPTION_LIST_STATUSES = [...exports.SUBSCRIPTION_STATUSES, 'all', 'ended'];
+/** How the subscription's invoices are collected. FairCoin is always `send_invoice`. */
+exports.COLLECTION_METHODS = ['charge_automatically', 'send_invoice'];
+/** How a change mid-period is billed. */
+exports.PRORATION_BEHAVIORS = ['create_prorations', 'none', 'always_invoice'];
+/** The proration behaviours a subscription CREATE accepts: there is nothing to invoice at once yet. */
+exports.CREATE_PRORATION_BEHAVIORS = [
+    'create_prorations',
+    'none',
+];
+/** What a create does when the first invoice cannot be paid at once. */
+exports.PAYMENT_BEHAVIORS = [
+    'allow_incomplete',
+    'default_incomplete',
+    'error_if_incomplete',
+];
+/** What happens to the invoices of a subscription whose collection is paused. */
+exports.PAUSE_COLLECTION_BEHAVIORS = ['keep_as_draft', 'mark_uncollectible', 'void'];
+/** What a trial ending with no payment method does (`trial_settings.end_behavior`). */
+exports.TRIAL_END_BEHAVIORS = ['cancel', 'create_invoice', 'pause'];
+/** Why a subscription was cancelled. */
+exports.SUBSCRIPTION_CANCELLATION_REASONS = [
+    'cancellation_requested',
+    'payment_failed',
+];
+/** `billing_cycle_anchor` on a resume: a new period now (the default), or the anchor kept. */
+exports.RESUME_BILLING_CYCLE_ANCHORS = ['now', 'unchanged'];

package/dist/cjs/vocabulary/tax.js

@@ -0,0 +1,237 @@
+"use strict";
+// Peable Tax vocabulary (ADR 0011, ADR 0020): the closed value sets the tax
+// contracts are built from, and the database mirrors as CHECKs. Zod-free, so
+// Orbit and the shared types read them at runtime without constructing a schema.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAX_COMPLIANCE_CAPABILITY_CATEGORIES = exports.TAX_COMPLIANCE_CAPABILITY_STATUSES = exports.TAX_DEADLINE_STATUSES = exports.TAX_DEADLINE_KINDS = exports.TAX_ACTOR_TYPES = exports.TAX_REVIEW_DECISIONS = exports.TAX_REVIEW_SEVERITIES = exports.TAX_REVIEW_ITEM_STATUSES = exports.TAX_OBLIGATION_OUTCOMES = exports.TAX_RULE_REVIEW_STATUSES = exports.TAX_THRESHOLD_PERIODS = exports.TAX_TYPES = exports.TAX_DOCUMENT_CHECKLIST_STATUSES = exports.TAX_DOCUMENT_KINDS = exports.TAX_FILING_FREQUENCIES = exports.TAX_REGISTRATION_DECLARATION_STATUSES = exports.TAX_OPERATING_LOCATION_KINDS = exports.TAX_SUPPLY_TYPES = exports.TAX_CUSTOMER_TYPES = exports.TAX_LEGAL_ENTITY_TYPES = exports.DEFAULT_TAX_CODE = exports.NONTAXABLE_TAX_CODE = exports.TAX_CODES = exports.TAX_TRANSACTION_TYPES = exports.TAX_COLLECTIONS = exports.TAX_EVIDENCE_STATUSES = exports.TAX_REGISTRATION_STATUSES = exports.TAX_CALCULATION_ACCOUNTS = exports.TAX_SETTINGS_STATUSES = exports.TAX_BEHAVIORS = exports.TAX_LOCATION_EVIDENCE_TYPES = exports.TAX_REGISTRATION_SCHEMES = void 0;
+exports.isKnownTaxCode = isKnownTaxCode;
+// ── Collection (ADR 0011) ────────────────────────────────────────────────────
+/**
+ * How a registration lets the seller collect. `standard`/`simplified` cover one
+ * country; the EU One-Stop-Shop schemes cover every EU member state from one
+ * identification state; the US is per state; Canadian PST/QST is per province.
+ */
+exports.TAX_REGISTRATION_SCHEMES = [
+    'standard',
+    'simplified',
+    'eu_oss_union',
+    'eu_oss_non_union',
+    'us_state_sales_tax',
+    'ca_provincial',
+];
+/**
+ * Location evidence a jurisdiction accepts. There is deliberately no language,
+ * currency, locale or timezone: none of them is evidence of where a customer
+ * lives, and Peable cannot be told otherwise.
+ */
+exports.TAX_LOCATION_EVIDENCE_TYPES = [
+    'billing_address',
+    'ip_address',
+    'payment_method_country',
+    'bank_country',
+    'sim_country',
+    'landline_country',
+];
+/** Whether a line's amount includes its tax (`inclusive`) or tax is added on top. */
+exports.TAX_BEHAVIORS = ['inclusive', 'exclusive'];
+/** `active` once the owner approved; any edit returns the settings to `draft`. */
+exports.TAX_SETTINGS_STATUSES = ['draft', 'active'];
+/**
+ * Which provider account calculates for a merchant. `platform`: Peable's own
+ * provider account, available only to official Oxy applications, whose seller
+ * is the platform's legal entity. `none`: no provider; sales in a registered
+ * jurisdiction cannot be calculated and fail closed.
+ */
+exports.TAX_CALCULATION_ACCOUNTS = ['platform', 'none'];
+/** `pending_approval` until the owner approves; `scheduled` before `active_from`. */
+exports.TAX_REGISTRATION_STATUSES = [
+    'pending_approval',
+    'scheduled',
+    'active',
+    'expired',
+];
+/** Only `sufficient` evidence can be calculated against. */
+exports.TAX_EVIDENCE_STATUSES = ['sufficient', 'insufficient', 'conflicting'];
+/**
+ * Why a calculation's tax is what it is: `collect` (a registration covers the
+ * customer and the provider calculated), `not_registered` (no registration
+ * covers them: zero tax, recorded as such), `nontaxable` (every line used the
+ * nontaxable code).
+ */
+exports.TAX_COLLECTIONS = ['collect', 'not_registered', 'nontaxable'];
+/** A sale, or a refund (or credit note) of one. */
+exports.TAX_TRANSACTION_TYPES = ['transaction', 'reversal'];
+/**
+ * The product tax codes Peable accepts, starting with digital services and
+ * SaaS — what every Oxy application sells. Ids are Stripe Tax's tax codes, so a
+ * code means the same thing to Peable and to the provider calculating it.
+ * Adding a category is adding a row here; classifying a product is the seller's
+ * decision.
+ */
+exports.TAX_CODES = Object.freeze([
+    {
+        id: 'txcd_00000000',
+        name: 'Nontaxable',
+        description: 'A product that is not subject to tax anywhere. No tax is calculated.',
+    },
+    {
+        id: 'txcd_10000000',
+        name: 'General - Electronically Supplied Services',
+        description: 'A service delivered electronically over the internet with minimal human involvement.',
+    },
+    {
+        id: 'txcd_10103000',
+        name: 'Software as a service (SaaS) - personal use',
+        description: 'Hosted software accessed online, sold to consumers for personal use.',
+    },
+    {
+        id: 'txcd_10103001',
+        name: 'Software as a service (SaaS) - business use',
+        description: 'Hosted software accessed online, sold to businesses for business use.',
+    },
+    {
+        id: 'txcd_10202000',
+        name: 'Downloadable Software - personal use',
+        description: 'Software downloaded to the customer’s device, for personal use.',
+    },
+    {
+        id: 'txcd_10202003',
+        name: 'Downloadable Software - business use',
+        description: 'Software downloaded to the customer’s device, for business use.',
+    },
+    {
+        id: 'txcd_10701100',
+        name: 'Website Hosting',
+        description: 'Hosting of a website or web application on the seller’s servers.',
+    },
+]);
+/** The code of a product that is taxed nowhere. */
+exports.NONTAXABLE_TAX_CODE = 'txcd_00000000';
+/** The code a merchant's settings start with: electronically supplied services. */
+exports.DEFAULT_TAX_CODE = 'txcd_10000000';
+const KNOWN_TAX_CODES = new Set(exports.TAX_CODES.map((code) => code.id));
+/** Whether `id` is one of {@link TAX_CODES}. */
+function isKnownTaxCode(id) {
+    return KNOWN_TAX_CODES.has(id);
+}
+// ── Business compliance (ADR 0020) ───────────────────────────────────────────
+/** `unknown` is an answer, not a gap: the owner says they do not know yet. */
+exports.TAX_LEGAL_ENTITY_TYPES = [
+    'corporation',
+    'limited_liability_company',
+    'partnership',
+    'sole_proprietorship',
+    'nonprofit',
+    'public_body',
+    'other',
+    'unknown',
+];
+exports.TAX_CUSTOMER_TYPES = ['consumers', 'businesses', 'both', 'unknown'];
+exports.TAX_SUPPLY_TYPES = [
+    'digital_services',
+    'software_as_a_service',
+    'physical_goods',
+    'professional_services',
+    'other',
+];
+/**
+ * Where the business ACTUALLY operates. `head_office` and `fixed_establishment`
+ * are the owner's statement of establishment (the EU rule reads them); any
+ * location in a US state is physical presence there.
+ */
+exports.TAX_OPERATING_LOCATION_KINDS = [
+    'head_office',
+    'fixed_establishment',
+    'office',
+    'warehouse',
+    'employees',
+    'inventory',
+    'other',
+];
+/**
+ * Where the business stands with a tax authority, IN ITS OWN WORDS.
+ *
+ *  - `unknown` — the owner does not know; an assessment escalates it.
+ *  - `not_registered` — the owner says there is no registration.
+ *  - `application_pending` — an application was made outside Peable and the
+ *    authority has not answered: an ambiguous outcome, never treated as
+ *    registered.
+ *  - `registered` — the owner says the authority registered the business, from
+ *    `effective_from`.
+ *  - `rejected` — the authority refused the application.
+ *  - `ended` — the registration ended at `effective_to`.
+ */
+exports.TAX_REGISTRATION_DECLARATION_STATUSES = [
+    'unknown',
+    'not_registered',
+    'application_pending',
+    'registered',
+    'rejected',
+    'ended',
+];
+exports.TAX_FILING_FREQUENCIES = ['monthly', 'quarterly', 'annual', 'unknown'];
+exports.TAX_DOCUMENT_KINDS = [
+    'registration_certificate',
+    'authority_correspondence',
+    'incorporation_record',
+    'filing_confirmation',
+    'payment_receipt',
+    'other',
+];
+/** `provided`: an available document is attached; `unavailable`: only removed ones are. */
+exports.TAX_DOCUMENT_CHECKLIST_STATUSES = ['provided', 'missing', 'unavailable'];
+/** The tax a jurisdiction rule is about. */
+exports.TAX_TYPES = ['vat', 'sales_tax'];
+/** The window a rule's threshold is measured over. */
+exports.TAX_THRESHOLD_PERIODS = [
+    'current_or_previous_calendar_year',
+    'preceding_twelve_calendar_months',
+];
+/** Whether a tax professional has signed a rule off. */
+exports.TAX_RULE_REVIEW_STATUSES = ['unreviewed', 'reviewed'];
+/**
+ * What an assessment found for one jurisdiction.
+ *
+ *  - `registration_declared` — the owner declares a registration in force.
+ *  - `likely_required` — the rule indicates an obligation; a person decides.
+ *  - `approaching_threshold` — at or above 80% of the threshold.
+ *  - `not_indicated` — nothing in the recorded facts indicates one.
+ *  - `uncertain` — the facts are missing or contradictory; escalated.
+ *  - `unsupported` — sales exist where no supported rule applies.
+ */
+exports.TAX_OBLIGATION_OUTCOMES = [
+    'registration_declared',
+    'likely_required',
+    'approaching_threshold',
+    'not_indicated',
+    'uncertain',
+    'unsupported',
+];
+exports.TAX_REVIEW_ITEM_STATUSES = ['open', 'resolved', 'dismissed'];
+exports.TAX_REVIEW_SEVERITIES = ['action_required', 'review'];
+/** What the owner decided. None of them activates collection. */
+exports.TAX_REVIEW_DECISIONS = [
+    'will_register',
+    'registered_outside_peable',
+    'not_required',
+    'accepted_risk',
+    'facts_corrected',
+    'dismissed',
+];
+/** Who recorded a compliance change: the owner, a service credential, or Peable itself. */
+exports.TAX_ACTOR_TYPES = ['user', 'service', 'system'];
+exports.TAX_DEADLINE_KINDS = ['return', 'payment', 'registration'];
+exports.TAX_DEADLINE_STATUSES = ['upcoming', 'due_soon', 'passed'];
+exports.TAX_COMPLIANCE_CAPABILITY_STATUSES = [
+    'available',
+    'limited',
+    'not_available',
+    'out_of_scope',
+];
+/** VAT/sales tax, corporate income tax and annual company filings are different obligations. */
+exports.TAX_COMPLIANCE_CAPABILITY_CATEGORIES = [
+    'vat_sales_tax',
+    'corporate_income_tax',
+    'annual_company_filings',
+    'workflow',
+];

package/dist/cjs/vocabulary/version.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PEABLE_API_VERSIONS = exports.PEABLE_API_VERSION = void 0;
+/**
+ * The date of the one wire (ADR 0014 D2): echoed as `Peable-Version` on every
+ * response, the `api_version` every event is stored under, and the only value
+ * a caller may send in `Peable-Version`. One constant, so the header, the
+ * stored events and the SDK's `apiVersion` cannot name two different wires.
+ */
+exports.PEABLE_API_VERSION = '2026-11-03';
+/** Every wire date the gateway serves. Dated versions side by side are a later decision (ADR 0014 D2). */
+exports.PEABLE_API_VERSIONS = [exports.PEABLE_API_VERSION];

package/dist/esm/common/address.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { contractRegistry } from './objects.js';
+/**
+ * Stripe's address and shipping shapes — as returned (every field present,
+ * `null` when not given) and as a request carries them (every field optional).
+ * Shared by every object that holds one: intents, customers, payment methods,
+ * checkout sessions.
+ */
+export const addressSchema = z
+    .object({
+    line1: z.string().nullable(),
+    line2: z.string().nullable(),
+    city: z.string().nullable(),
+    state: z.string().nullable(),
+    postal_code: z.string().nullable(),
+    country: z.string().nullable().describe('ISO 3166-1 alpha-2.'),
+})
+    .strict();
+contractRegistry.add(addressSchema, { id: 'Address' });
+export const shippingSchema = z
+    .object({
+    name: z.string(),
+    phone: z.string().nullable(),
+    address: addressSchema,
+    carrier: z.string().nullable(),
+    tracking_number: z.string().nullable(),
+})
+    .strict();
+contractRegistry.add(shippingSchema, { id: 'Shipping' });
+const line = z.string().max(500);
+/** An address as a request carries it: every field optional. */
+export const addressParams = z
+    .object({
+    line1: line.optional(),
+    line2: line.optional(),
+    city: line.optional(),
+    state: line.optional(),
+    postal_code: z.string().max(40).optional(),
+    country: z
+        .string()
+        .regex(/^[A-Z]{2}$/, 'country must be an ISO 3166-1 alpha-2 code')
+        .optional(),
+})
+    .strict();
+/** Shipping as a request carries it: only `name` and `address` are required. */
+export const shippingParams = z
+    .object({
+    name: z.string().min(1).max(500),
+    phone: z.string().max(40).optional(),
+    address: addressParams,
+    carrier: z.string().max(200).optional(),
+    tracking_number: z.string().max(200).optional(),
+})
+    .strict();
+export const emailParam = z.email().max(512);
+/** A request address in the stored (and wire) shape: every field present. */
+export function toAddress(input) {
+    return {
+        line1: input.line1 ?? null,
+        line2: input.line2 ?? null,
+        city: input.city ?? null,
+        state: input.state ?? null,
+        postal_code: input.postal_code ?? null,
+        country: input.country ?? null,
+    };
+}
+/** Request shipping in the stored (and wire) shape. */
+export function toShipping(input) {
+    return {
+        name: input.name,
+        phone: input.phone ?? null,
+        address: toAddress(input.address),
+        carrier: input.carrier ?? null,
+        tracking_number: input.tracking_number ?? null,
+    };
+}