@peable.to/contracts 0.4.0 → 1.1.0

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

package/dist/esm/vocabulary/tax.js

@@ -0,0 +1,233 @@
+// 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.
+// ── 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.
+ */
+export const 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.
+ */
+export const 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. */
+export const TAX_BEHAVIORS = ['inclusive', 'exclusive'];
+/** `active` once the owner approved; any edit returns the settings to `draft`. */
+export const 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.
+ */
+export const TAX_CALCULATION_ACCOUNTS = ['platform', 'none'];
+/** `pending_approval` until the owner approves; `scheduled` before `active_from`. */
+export const TAX_REGISTRATION_STATUSES = [
+    'pending_approval',
+    'scheduled',
+    'active',
+    'expired',
+];
+/** Only `sufficient` evidence can be calculated against. */
+export const 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).
+ */
+export const TAX_COLLECTIONS = ['collect', 'not_registered', 'nontaxable'];
+/** A sale, or a refund (or credit note) of one. */
+export const 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.
+ */
+export const 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. */
+export const NONTAXABLE_TAX_CODE = 'txcd_00000000';
+/** The code a merchant's settings start with: electronically supplied services. */
+export const DEFAULT_TAX_CODE = 'txcd_10000000';
+const KNOWN_TAX_CODES = new Set(TAX_CODES.map((code) => code.id));
+/** Whether `id` is one of {@link TAX_CODES}. */
+export 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. */
+export const TAX_LEGAL_ENTITY_TYPES = [
+    'corporation',
+    'limited_liability_company',
+    'partnership',
+    'sole_proprietorship',
+    'nonprofit',
+    'public_body',
+    'other',
+    'unknown',
+];
+export const TAX_CUSTOMER_TYPES = ['consumers', 'businesses', 'both', 'unknown'];
+export const 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.
+ */
+export const 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`.
+ */
+export const TAX_REGISTRATION_DECLARATION_STATUSES = [
+    'unknown',
+    'not_registered',
+    'application_pending',
+    'registered',
+    'rejected',
+    'ended',
+];
+export const TAX_FILING_FREQUENCIES = ['monthly', 'quarterly', 'annual', 'unknown'];
+export const 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. */
+export const TAX_DOCUMENT_CHECKLIST_STATUSES = ['provided', 'missing', 'unavailable'];
+/** The tax a jurisdiction rule is about. */
+export const TAX_TYPES = ['vat', 'sales_tax'];
+/** The window a rule's threshold is measured over. */
+export const TAX_THRESHOLD_PERIODS = [
+    'current_or_previous_calendar_year',
+    'preceding_twelve_calendar_months',
+];
+/** Whether a tax professional has signed a rule off. */
+export const 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.
+ */
+export const TAX_OBLIGATION_OUTCOMES = [
+    'registration_declared',
+    'likely_required',
+    'approaching_threshold',
+    'not_indicated',
+    'uncertain',
+    'unsupported',
+];
+export const TAX_REVIEW_ITEM_STATUSES = ['open', 'resolved', 'dismissed'];
+export const TAX_REVIEW_SEVERITIES = ['action_required', 'review'];
+/** What the owner decided. None of them activates collection. */
+export const 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. */
+export const TAX_ACTOR_TYPES = ['user', 'service', 'system'];
+export const TAX_DEADLINE_KINDS = ['return', 'payment', 'registration'];
+export const TAX_DEADLINE_STATUSES = ['upcoming', 'due_soon', 'passed'];
+export const TAX_COMPLIANCE_CAPABILITY_STATUSES = [
+    'available',
+    'limited',
+    'not_available',
+    'out_of_scope',
+];
+/** VAT/sales tax, corporate income tax and annual company filings are different obligations. */
+export const TAX_COMPLIANCE_CAPABILITY_CATEGORIES = [
+    'vat_sales_tax',
+    'corporate_income_tax',
+    'annual_company_filings',
+    'workflow',
+];

package/dist/esm/vocabulary/version.js

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export const PEABLE_API_VERSION = '2026-11-03';
+/** Every wire date the gateway serves. Dated versions side by side are a later decision (ADR 0014 D2). */
+export const PEABLE_API_VERSIONS = [PEABLE_API_VERSION];

package/dist/types/common/address.d.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+/**
+ * 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 declare const addressSchema: z.ZodObject<{
+    line1: z.ZodNullable<z.ZodString>;
+    line2: z.ZodNullable<z.ZodString>;
+    city: z.ZodNullable<z.ZodString>;
+    state: z.ZodNullable<z.ZodString>;
+    postal_code: z.ZodNullable<z.ZodString>;
+    country: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type Address = z.output<typeof addressSchema>;
+export declare const shippingSchema: z.ZodObject<{
+    name: z.ZodString;
+    phone: z.ZodNullable<z.ZodString>;
+    address: z.ZodObject<{
+        line1: z.ZodNullable<z.ZodString>;
+        line2: z.ZodNullable<z.ZodString>;
+        city: z.ZodNullable<z.ZodString>;
+        state: z.ZodNullable<z.ZodString>;
+        postal_code: z.ZodNullable<z.ZodString>;
+        country: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    carrier: z.ZodNullable<z.ZodString>;
+    tracking_number: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type Shipping = z.output<typeof shippingSchema>;
+/** An address as a request carries it: every field optional. */
+export declare const addressParams: z.ZodObject<{
+    line1: z.ZodOptional<z.ZodString>;
+    line2: z.ZodOptional<z.ZodString>;
+    city: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    postal_code: z.ZodOptional<z.ZodString>;
+    country: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AddressParams = z.input<typeof addressParams>;
+/** Shipping as a request carries it: only `name` and `address` are required. */
+export declare const shippingParams: z.ZodObject<{
+    name: z.ZodString;
+    phone: z.ZodOptional<z.ZodString>;
+    address: z.ZodObject<{
+        line1: z.ZodOptional<z.ZodString>;
+        line2: z.ZodOptional<z.ZodString>;
+        city: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodString>;
+        postal_code: z.ZodOptional<z.ZodString>;
+        country: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    carrier: z.ZodOptional<z.ZodString>;
+    tracking_number: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ShippingParams = z.input<typeof shippingParams>;
+export declare const emailParam: z.ZodEmail;
+/** A request address in the stored (and wire) shape: every field present. */
+export declare function toAddress(input: z.output<typeof addressParams>): Address;
+/** Request shipping in the stored (and wire) shape. */
+export declare function toShipping(input: z.output<typeof shippingParams>): Shipping;

package/dist/types/common/envelopes.d.ts

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+/**
+ * The envelopes every resource shares (ADR 0014 D1): the list, the search
+ * result, the deleted tombstone and the error.
+ */
+/**
+ * One page of a list, newest first. `url` is the path that was listed, so a
+ * page carries enough to fetch the next one without the caller remembering
+ * where it came from.
+ */
+export declare function listOf<T extends z.ZodType>(item: T): z.ZodObject<{
+    object: z.ZodLiteral<"list">;
+    data: z.ZodArray<T>;
+    has_more: z.ZodBoolean;
+    url: z.ZodString;
+}, z.core.$strict>;
+/**
+ * One page of a search. Pages FORWARD only, by an opaque `next_page` token
+ * passed back as `page`, bound to the query it came from.
+ */
+export declare function searchResultOf<T extends z.ZodType>(item: T): z.ZodObject<{
+    object: z.ZodLiteral<"search_result">;
+    data: z.ZodArray<T>;
+    has_more: z.ZodBoolean;
+    next_page: z.ZodNullable<z.ZodString>;
+    url: z.ZodString;
+    total_count: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** A deleted object, as its `DELETE` answers: `{id, object, deleted: true}`. */
+export declare function deletedOf<T extends string>(object: T): z.ZodObject<{
+    id: z.ZodString;
+    object: z.ZodLiteral<T>;
+    deleted: z.ZodLiteral<true>;
+}, z.core.$strict>;
+/** The error object inside every non-2xx answer. */
+export declare const apiErrorSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        api_error: "api_error";
+        authentication_error: "authentication_error";
+        card_error: "card_error";
+        idempotency_error: "idempotency_error";
+        invalid_request_error: "invalid_request_error";
+        permission_error: "permission_error";
+        rate_limit_error: "rate_limit_error";
+    }>;
+    code: z.ZodOptional<z.ZodString>;
+    decline_code: z.ZodOptional<z.ZodString>;
+    param: z.ZodOptional<z.ZodString>;
+    message: z.ZodString;
+    doc_url: z.ZodOptional<z.ZodURL>;
+    request_id: z.ZodNullable<z.ZodString>;
+    payment_intent: z.ZodOptional<z.ZodLazy<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+    invoice: z.ZodOptional<z.ZodLazy<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+    refresh_url: z.ZodOptional<z.ZodURL>;
+}, z.core.$strict>;
+/** `{ error: {...} }` — every non-2xx answer. */
+export declare const errorEnvelopeSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        type: z.ZodEnum<{
+            api_error: "api_error";
+            authentication_error: "authentication_error";
+            card_error: "card_error";
+            idempotency_error: "idempotency_error";
+            invalid_request_error: "invalid_request_error";
+            permission_error: "permission_error";
+            rate_limit_error: "rate_limit_error";
+        }>;
+        code: z.ZodOptional<z.ZodString>;
+        decline_code: z.ZodOptional<z.ZodString>;
+        param: z.ZodOptional<z.ZodString>;
+        message: z.ZodString;
+        doc_url: z.ZodOptional<z.ZodURL>;
+        request_id: z.ZodNullable<z.ZodString>;
+        payment_intent: z.ZodOptional<z.ZodLazy<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+        invoice: z.ZodOptional<z.ZodLazy<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+        refresh_url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ApiError = z.output<typeof apiErrorSchema>;
+export type ErrorEnvelope = z.output<typeof errorEnvelopeSchema>;
+/** One page of a list of `T` — the type of every `listOf(…)` answer. */
+export type List<T> = Omit<z.output<ReturnType<typeof listOf<z.ZodNever>>>, 'data'> & {
+    data: T[];
+};
+/** One page of a search over `T` — the type of every `searchResultOf(…)` answer. */
+export type SearchResult<T> = Omit<z.output<ReturnType<typeof searchResultOf<z.ZodNever>>>, 'data'> & {
+    data: T[];
+};

package/dist/types/common/objects.d.ts

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+/**
+ * The object registry: every named wire object (`Customer`, `PaymentIntent`, …)
+ * is defined ONCE, here in `packages/contracts`, and registered under its
+ * OpenAPI component name and its `object` value.
+ *
+ * Three things read it:
+ *
+ * - `expandable(type)` — a reference that `expand[]` can replace with the
+ *   object it names validates against the registered schema;
+ * - the OpenAPI generator — every registered object is a
+ *   `#/components/schemas/<Name>` and every reference to it is a `$ref`;
+ * - {@link Expand} — the TypeScript half, which turns a reference's marker
+ *   into the object type, so `Customer['invoice_settings']['default_payment_method']`
+ *   is `string | PaymentMethod | null` without the schemas referencing each
+ *   other at the type level (which TypeScript cannot infer, and which the
+ *   declaration emitter would elide to `any`).
+ */
+/** OpenAPI-facing metadata a schema can carry. */
+export interface ContractMeta {
+    /** The component name: `#/components/schemas/<id>`. */
+    id?: string;
+    title?: string;
+    description?: string;
+    /** Example values, rendered in the reference and the OpenAPI document. */
+    examples?: readonly unknown[];
+    deprecated?: boolean;
+    /** On an expandable reference: the `object` type `expand[]` replaces it with. */
+    'x-peable-expandable'?: string;
+    /** Replaces the generated JSON Schema of this node (a query integer's wire spelling). */
+    jsonSchema?: Record<string, unknown>;
+}
+/** The one registry every contract schema's metadata lives in. */
+export declare const contractRegistry: z.core.$ZodRegistry<ContractMeta, z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+declare const refBrand: unique symbol;
+/**
+ * The TYPE of an expandable reference before {@link Expand} resolves it. Never
+ * a runtime value: at runtime the reference is an id string or the object.
+ */
+export interface Ref<K extends string> {
+    readonly [refBrand]: K;
+}
+/**
+ * `object` value → wire type, for every object a reference can expand into.
+ *
+ * Each resource module adds its own entries by declaration merging:
+ *
+ * ```ts
+ * declare module '../common/objects' {
+ *   interface ObjectMap { customer: Customer }
+ * }
+ * ```
+ *
+ * so a resource is registered by the same file that defines it.
+ */
+export interface ObjectMap {
+}
+/** Every object type a reference can name. */
+export type ObjectType = keyof ObjectMap;
+/**
+ * A schema's output with every {@link Ref} replaced by the object it names —
+ * the wire type. Homomorphic, so optional and readonly modifiers survive.
+ */
+export type Expand<T> = T extends Ref<infer K> ? K extends keyof ObjectMap ? ObjectMap[K] : never : T extends readonly (infer U)[] ? Expand<U>[] : T extends object ? {
+    [P in keyof T]: Expand<T[P]>;
+} : T;
+/** The wire type a schema describes (its output, references resolved). */
+export type Wire<S extends z.ZodType> = Expand<z.output<S>>;
+/** The parameters a request schema accepts as sent on the wire (its input). */
+export type Params<S extends z.ZodType> = z.input<S>;
+/**
+ * Register a wire object: its `object` value (the key references use) and its
+ * component name. Returns the schema so a definition reads as one expression.
+ */
+export declare function defineObject<T extends z.ZodType>(type: string, id: string, schema: T, meta?: Omit<ContractMeta, 'id'>): T;
+/**
+ * Register a named schema that is not an expandable object — a tombstone, a
+ * shared sub-object, a polymorphic payload — as `#/components/schemas/<id>`.
+ */
+export declare function defineComponent<T extends z.ZodType>(id: string, schema: T, meta?: Omit<ContractMeta, 'id'>): T;
+/** The registered schema of `type`, or `undefined`. */
+export declare function objectSchema(type: string): z.ZodType | undefined;
+/**
+ * The registered schema of `type`. Resolved lazily (a reference is declared
+ * before the module defining its target has loaded), and loud when nothing
+ * registers it: a reference to an unknown object is a contract bug.
+ */
+export declare function resolveObject(type: string): z.ZodType;
+/** Every registered object type, in registration order. */
+export declare function objectTypes(): string[];
+/**
+ * A reference `expand[]` can replace: the id (`cus_…`) or, expanded, the
+ * object. The naming rule (`lib/expand.ts` in the backend): an expandable
+ * reference is spelled WITHOUT `_id`, and a field without `_id` that is not
+ * expandable is a bug.
+ */
+export declare function expandable<K extends string>(type: K, description?: string): z.ZodType<string | Ref<K>, string | Ref<K>>;
+/**
+ * A field that always carries the FULL object `type` names (never an id): a
+ * subscription item's `price`, a payer view's `payment_intent`, a report run's
+ * result `file`. Validated against the registered schema and typed through
+ * {@link Ref}, so {@link Expand} resolves it to that object's wire type.
+ */
+export declare function embedded<K extends string>(type: K, description?: string): z.ZodType<Ref<K>, Ref<K>>;
+/** Attach OpenAPI metadata to a schema without changing its type. */
+export declare function describe<T extends z.ZodType>(schema: T, meta: ContractMeta): T;
+export {};