@peable.to/contracts 0.4.0 → 1.1.0

package/dist/cjs/vocabulary/dashboard.js

@@ -0,0 +1,68 @@
+"use strict";
+// What a signed-in person may do in Orbit — the ONE map from a dashboard
+// action to the Oxy application permission it needs. Zod-free. The gateway
+// gates every `/v1/dashboard/applications/:id/*` and contribution route on it
+// (a refusal is `permission_required`, `param` naming the permission), and
+// Orbit hides or disables what the person lacks with the SAME map, so the two
+// can never disagree about who may do what.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_UPLOAD_ACTION = exports.DASHBOARD_PERMISSIONS = void 0;
+exports.allowsDashboardAction = allowsDashboardAction;
+/**
+ * The permissions are oxy-api's own APPLICATION vocabulary
+ * (`packages/api/src/utils/accountRoles.ts`, `APPLICATION_PERMISSIONS`): Oxy
+ * resolves the person's role, grants and revokes on the account that owns the
+ * application into `callerMembership.permissions`, and that list — from
+ * `apps.get` on the gateway, from `apps.list` in Orbit — is the whole answer.
+ * Peable never reads a role name and keeps no membership copy.
+ */
+exports.DASHBOARD_PERMISSIONS = {
+    /**
+     * Every read, the searches and a report run (it materialises the same rows a
+     * download streams). oxy-api answers an application only to a holder of
+     * `app:read`, so this is membership itself.
+     */
+    read: 'app:read',
+    /**
+     * The integration's configuration: branding and customer emails, the
+     * catalog, checkout sessions and payment links, contribution links, payment
+     * methods and wallet domains, a business logo.
+     */
+    configure: 'app:update',
+    /** Webhook endpoints and their signing secrets, test events, redelivery. */
+    webhooks: 'webhooks:update',
+    /**
+     * Money and who receives it: the merchant registration (its watch-only key
+     * and confirmations), the provider account and its onboarding and identity
+     * documents, payouts, sellers and transfers, disputes and their evidence, the
+     * billing engine, and every Peable Tax change or decision.
+     */
+    money: 'billing:manage',
+    /** Peable Tax reads and previews (ADR 0011, ADR 0020). */
+    taxRead: 'billing:read',
+};
+/**
+ * A permission that CONTAINS another: whoever may manage billing may read it.
+ * Stated once so the gateway and Orbit apply the same containment.
+ */
+const IMPLIED_BY = {
+    'billing:read': 'billing:manage',
+};
+/** Whether `held` (Oxy's `callerMembership.permissions`) allows `action`. */
+function allowsDashboardAction(held, action) {
+    const required = exports.DASHBOARD_PERMISSIONS[action];
+    const container = IMPLIED_BY[required];
+    return held.includes(required) || (container !== undefined && held.includes(container));
+}
+/**
+ * Uploading a file is the first half of USING it, so it needs what the use
+ * needs: a logo is configuration, everything else is evidence or identity for
+ * money (a dispute, the provider account, Peable Tax).
+ */
+exports.FILE_UPLOAD_ACTION = {
+    business_logo: 'configure',
+    dispute_evidence: 'money',
+    identity_document: 'money',
+    additional_verification: 'money',
+    tax_document: 'money',
+};

package/dist/cjs/vocabulary/errors.js

@@ -0,0 +1,175 @@
+"use strict";
+// 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`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_CODES = exports.ERROR_CODE_DESCRIPTIONS = exports.ERROR_DOCS_BASE_URL = exports.ERROR_TYPE_DESCRIPTIONS = exports.ERROR_TYPES = void 0;
+exports.errorDocUrl = errorDocUrl;
+exports.isErrorCode = isErrorCode;
+/** `error.type`: the broad class a caller branches on first. */
+exports.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. */
+exports.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.
+ */
+exports.ERROR_DOCS_BASE_URL = 'https://oxy.so/developers/docs/peable/errors/';
+/** The `doc_url` of a code. */
+function errorDocUrl(code) {
+    return `${exports.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.
+ */
+exports.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.',
+    account_membership_required: "The signed-in Oxy account is not a member of the Oxy account the path names (a contribution route's organization).",
+    permission_required: 'The member lacks the Oxy permission this action needs; `param` names it (`app:update`, `webhooks:update`, `billing:read`, `billing:manage`). An owner grants it in Oxy Console.',
+    membership_unavailable: 'Oxy could not be asked what the signed-in person may do on this application or account; retry.',
+    session_invalid: 'Oxy no longer accepts the signed-in session; sign in again.',
+};
+/** Every error code, sorted. */
+exports.ERROR_CODES = Object.keys(exports.ERROR_CODE_DESCRIPTIONS).sort();
+/** Whether a string is a documented error code. */
+function isErrorCode(value) {
+    return Object.hasOwn(exports.ERROR_CODE_DESCRIPTIONS, value);
+}

package/dist/cjs/vocabulary/events.js

@@ -0,0 +1,176 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_DELIVERY_STATUSES = exports.WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS = exports.WEBHOOK_ENDPOINT_DESCRIPTION_MAX = exports.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = exports.WEBHOOK_ENDPOINT_DISABLED_REASONS = exports.WEBHOOK_ENDPOINT_STATUSES = exports.WEBHOOK_ENABLED_EVENTS = exports.TARGETED_WEBHOOK_EVENT_TYPES = exports.WEBHOOK_EVENT_TYPES = exports.WEBHOOK_EVENT_OBJECTS = void 0;
+/**
+ * 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.
+ */
+exports.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. */
+exports.WEBHOOK_EVENT_TYPES = Object.keys(exports.WEBHOOK_EVENT_OBJECTS);
+/**
+ * The event types never fanned out by subscription — sent only to the one
+ * endpoint they name. `enabled_events` refuses them.
+ */
+exports.TARGETED_WEBHOOK_EVENT_TYPES = [
+    'webhook_endpoint.test',
+];
+/** What `enabled_events` may hold: `*`, then every subscribable type. */
+exports.WEBHOOK_ENABLED_EVENTS = [
+    '*',
+    ...exports.WEBHOOK_EVENT_TYPES.filter((type) => !exports.TARGETED_WEBHOOK_EVENT_TYPES.includes(type)),
+];
+exports.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.
+ */
+exports.WEBHOOK_ENDPOINT_DISABLED_REASONS = [
+    'disabled_by_merchant',
+    'delivery_failures',
+];
+/** At most this many endpoints per merchant (per mode). */
+exports.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = 16;
+/** The longest an endpoint's `description` may be. */
+exports.WEBHOOK_ENDPOINT_DESCRIPTION_MAX = 5000;
+/** The longest a rolled secret may keep signing beside its replacement. */
+exports.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.
+ */
+exports.WEBHOOK_DELIVERY_STATUSES = ['pending', 'delivered', 'failed', 'dead'];

package/dist/cjs/vocabulary/files.js

@@ -0,0 +1,44 @@
+"use strict";
+// Files vocabulary (`file_…`): what a file is for, the formats it is stored
+// in, and whether its bytes are being served. Zod-free.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_STATUSES = exports.FILE_TYPES = exports.FILE_UPLOAD_PURPOSES = exports.FILE_PURPOSES = void 0;
+/**
+ * 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.
+ */
+exports.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.
+ */
+exports.FILE_UPLOAD_PURPOSES = [
+    'dispute_evidence',
+    'business_logo',
+    'identity_document',
+    'additional_verification',
+    'tax_document',
+];
+/** The stored format, by its conventional extension (Stripe's `type`). */
+exports.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.
+ */
+exports.FILE_STATUSES = ['available', 'withheld', 'removed'];

package/dist/cjs/vocabulary/identity.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PEABLE_SERVICE_AUDIENCE = exports.PEABLE_OXY_APPLICATION_ID = void 0;
+/**
+ * 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.
+ */
+exports.PEABLE_OXY_APPLICATION_ID = '6a2f851751b784a86fd0e958';
+/** The service-token audience of Peable's gateway (`oxy-service:<application id>`). */
+exports.PEABLE_SERVICE_AUDIENCE = `oxy-service:${exports.PEABLE_OXY_APPLICATION_ID}`;

package/dist/cjs/vocabulary/index.js

@@ -0,0 +1,39 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// `@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.
+__exportStar(require("./billingPortal"), exports);
+__exportStar(require("./connect"), exports);
+__exportStar(require("./dashboard"), exports);
+__exportStar(require("./catalog"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./invoices"), exports);
+__exportStar(require("./events"), exports);
+__exportStar(require("./lists"), exports);
+__exportStar(require("./money"), exports);
+__exportStar(require("./tax"), exports);
+__exportStar(require("./subscriptions"), exports);
+__exportStar(require("./reporting"), exports);
+__exportStar(require("./payments"), exports);
+__exportStar(require("./version"), exports);
+__exportStar(require("./checkout"), exports);
+__exportStar(require("./files"), exports);
+__exportStar(require("./identity"), exports);
+__exportStar(require("./merchants"), exports);
+__exportStar(require("./paymentMethodConfigurations"), exports);

package/dist/cjs/vocabulary/invoices.js

@@ -0,0 +1,52 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PUBLIC_INVOICE_PAYMENT_METHOD_TYPES = exports.CUSTOMER_BALANCE_TRANSACTION_TYPES = exports.CREDIT_NOTE_LINE_TYPES = exports.CREDIT_NOTE_REASONS = exports.CREDIT_NOTE_TYPES = exports.CREDIT_NOTE_STATUSES = exports.PENDING_INVOICE_ITEMS_BEHAVIORS = exports.INVOICE_LINE_TYPES = exports.AUTOMATIC_TAX_STATUSES = exports.INVOICE_BILLING_REASONS = exports.INVOICE_STATUSES = void 0;
+exports.INVOICE_STATUSES = ['draft', 'open', 'paid', 'void', 'uncollectible'];
+/** Why an invoice exists. */
+exports.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).
+ */
+exports.AUTOMATIC_TAX_STATUSES = ['requires_location_inputs', 'failed', 'complete'];
+/** Where an invoice line comes from: a subscription item's period, or an invoice item. */
+exports.INVOICE_LINE_TYPES = ['subscription', 'invoiceitem'];
+/** `pending_invoice_items_behavior` on an invoice create. Default `exclude` (Stripe's). */
+exports.PENDING_INVOICE_ITEMS_BEHAVIORS = ['include', 'exclude'];
+exports.CREDIT_NOTE_STATUSES = ['issued', 'void'];
+/** `pre_payment` reduces what an open invoice asks for; `post_payment` gives back on a paid one. */
+exports.CREDIT_NOTE_TYPES = ['pre_payment', 'post_payment'];
+exports.CREDIT_NOTE_REASONS = [
+    'duplicate',
+    'fraudulent',
+    'order_change',
+    'product_unsatisfactory',
+];
+/** A credit note line: part of an invoice line, or a custom amount. */
+exports.CREDIT_NOTE_LINE_TYPES = ['invoice_line_item', 'custom_line_item'];
+exports.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. */
+exports.PUBLIC_INVOICE_PAYMENT_METHOD_TYPES = ['card', 'faircoin'];

package/dist/cjs/vocabulary/lists.js

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

package/dist/cjs/vocabulary/merchants.js

@@ -0,0 +1,23 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BRANDING_COLOR_PATTERN = exports.BRANDING_BORDER_STYLES = exports.BRANDING_FONTS = exports.MERCHANT_ENVIRONMENTS = void 0;
+exports.MERCHANT_ENVIRONMENTS = ['development', 'staging', 'production'];
+/** The fonts checkout may render in — system stacks only, no remote font is ever loaded. */
+exports.BRANDING_FONTS = [
+    'system',
+    'inter',
+    'roboto',
+    'open_sans',
+    'lato',
+    'source_sans',
+    'noto_sans',
+    'serif',
+    'monospace',
+];
+exports.BRANDING_BORDER_STYLES = ['rounded', 'rectangular', 'pill'];
+/** `#rrggbb`, lowercase — the only colour spelling branding stores. */
+exports.BRANDING_COLOR_PATTERN = /^#[0-9a-f]{6}$/;