@peable.to/contracts 0.4.0 → 1.0.0

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 {};

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

@@ -0,0 +1,156 @@
+import { z } from 'zod';
+/**
+ * An integer in a query string. Arrives as a string from a URL, as a number
+ * from a typed caller; both are the same request.
+ */
+export declare function queryInteger(bounds?: {
+    min?: number;
+    max?: number;
+}): z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>;
+/** `true` / `false` in a query string (or a real boolean from a typed caller). */
+export declare const queryBoolean: z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
+    true: "true";
+    false: "false";
+}>]>, z.ZodTransform<boolean, boolean | "true" | "false">>;
+/** The latest representable instant (9999-12-31T23:59:59Z), the bound of every Unix-seconds parameter. */
+export declare const MAX_UNIX_SECONDS = 253402300799;
+/** Unix seconds in a body. */
+export declare const unixSecondsParam: z.ZodNumber;
+/** Unix seconds in a query string. */
+export declare const queryUnixSeconds: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>;
+/** A range over a Unix-seconds field; each bound optional, together a conjunction. */
+export interface RangeFilter {
+    readonly gt?: number | undefined;
+    readonly gte?: number | undefined;
+    readonly lt?: number | undefined;
+    readonly lte?: number | undefined;
+}
+/**
+ * `created=X` (exactly that second) or `created[gt|gte|lt|lte]=X`. The bare
+ * form is normalized to the range `[X, X]` so the repository reads one shape.
+ */
+export declare const rangeParam: z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>, z.ZodTransform<RangeFilter, number>>, z.ZodPipe<z.ZodObject<{
+    gt: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+    gte: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+    lt: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+    lte: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+}, z.core.$strict>, z.ZodTransform<RangeFilter, {
+    gt?: number | undefined;
+    gte?: number | undefined;
+    lt?: number | undefined;
+    lte?: number | undefined;
+}>>]>;
+/**
+ * `expand[]=a&expand[]=b` arrives as an array; `expand=a` as a string. Both
+ * mean the same request. Dot paths, at most four levels; on a list every path
+ * starts with `data.`.
+ */
+export declare const expandParam: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>, z.ZodArray<z.ZodString>>;
+/** The public id of a cursor. Bounded so a cursor is never an unbounded index probe. */
+export declare const cursorParam: z.ZodString;
+/** An object id in a body or query. */
+export declare const idParam: z.ZodString;
+/** The list limit: 1–100, default 10. */
+export declare const limitParam: z.ZodPipe<z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>, z.ZodTransform<number, number | undefined>>;
+/** The parameters every list accepts. */
+export declare const listShape: {
+    limit: z.ZodPipe<z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>, z.ZodTransform<number, number | undefined>>;
+    starting_after: z.ZodOptional<z.ZodString>;
+    ending_before: z.ZodOptional<z.ZodString>;
+    created: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>, z.ZodTransform<RangeFilter, number>>, z.ZodPipe<z.ZodObject<{
+        gt: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+        gte: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+        lt: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+        lte: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+    }, z.core.$strict>, z.ZodTransform<RangeFilter, {
+        gt?: number | undefined;
+        gte?: number | undefined;
+        lt?: number | undefined;
+        lte?: number | undefined;
+    }>>]>>;
+    expand: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>, z.ZodArray<z.ZodString>>>;
+};
+/**
+ * A list query: the shared parameters plus the route's own filters.
+ *
+ * `.strict()`: an unknown parameter is a 400 naming it, never silently ignored
+ * — `?stauts=settled` answering every intent is a filter the caller believes
+ * they applied.
+ */
+export declare function listQuery<S extends z.ZodRawShape>(filters: S): z.ZodObject<{
+    limit: z.ZodPipe<z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>, z.ZodTransform<number, number | undefined>>;
+    starting_after: z.ZodOptional<z.ZodString>;
+    ending_before: z.ZodOptional<z.ZodString>;
+    created: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>, z.ZodTransform<RangeFilter, number>>, z.ZodPipe<z.ZodObject<{
+        gt: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+        gte: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+        lt: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+        lte: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>;
+    }, z.core.$strict>, z.ZodTransform<RangeFilter, {
+        gt?: number | undefined;
+        gte?: number | undefined;
+        lt?: number | undefined;
+        lte?: number | undefined;
+    }>>]>>;
+    expand: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>, z.ZodArray<z.ZodString>>>;
+} & S extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strict>;
+/** A retrieve's query: `expand[]` and nothing else unless the route says so. */
+export declare function retrieveQuery<S extends z.ZodRawShape>(extra: S): z.ZodObject<{
+    expand: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>, z.ZodArray<z.ZodString>>>;
+} & S extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strict>;
+/** The query of a route that takes `expand[]` only. */
+export declare const expandOnlyQuery: z.ZodObject<{
+    expand: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>, z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
+/** The query of a route that takes no parameters at all. */
+export declare const emptyQuery: z.ZodObject<{}, z.core.$strict>;
+/** The parameters every `GET /v1/<objects>/search` accepts. */
+export declare const searchShape: {
+    query: z.ZodString;
+    limit: z.ZodPipe<z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>, z.ZodTransform<number, number | undefined>>;
+    page: z.ZodOptional<z.ZodString>;
+    expand: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>, z.ZodArray<z.ZodString>>>;
+};
+/** A search query. */
+export declare const searchQuery: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodPipe<z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>, z.ZodNumber>>, z.ZodTransform<number, number | undefined>>;
+    page: z.ZodOptional<z.ZodString>;
+    expand: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>, z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
+/** The parameters every list accepts, as a caller sends them. */
+export type ListParams = z.input<ReturnType<typeof listQuery<Record<never, z.ZodType>>>>;
+/** A Unix-seconds range as a caller sends it: bounds, each optional. */
+export type RangeQuery = Extract<z.input<typeof rangeParam>, object>;
+/** The parameter a single read or write accepts to expand its answer. */
+export interface ExpandParams {
+    /** Dot paths, at most four levels deep (`['payment_intent.connected_account']`). */
+    expand?: string[];
+}
+/** The parameters every search accepts, as a caller sends them. */
+export type SearchParams = z.input<typeof searchQuery>;
+export declare const METADATA_MAX_KEYS = 50;
+export declare const METADATA_KEY_MAX = 40;
+export declare const METADATA_VALUE_MAX = 500;
+/** A metadata update, as the repository applies it. */
+export interface MetadataPatch {
+    readonly set: Record<string, string>;
+    readonly unset: readonly string[];
+}
+/**
+ * The bag a create stores. Empty values are dropped: there is nothing to unset
+ * yet.
+ */
+export declare const metadataCreateParam: z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodString>, z.ZodTransform<Record<string, string>, Record<string, string>>>;
+/**
+ * The patch an update applies: named keys are set, a key sent as `""` is
+ * removed, keys not named are kept. The 50-key limit is then judged on the
+ * merged result, which only the database can see.
+ */
+export declare const metadataUpdateParam: z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodString>, z.ZodTransform<MetadataPatch, Record<string, string>>>;
+/** The answer when the MERGED bag would exceed the key limit. */
+export declare const METADATA_LIMIT_MESSAGE = "metadata holds at most 50 keys";
+/** `""` clears a field on an update, Stripe's rule. */
+export declare const clearable: <T extends z.ZodType>(schema: T) => z.ZodUnion<readonly [T, z.ZodLiteral<"">]>;
+/** Bounded text. */
+export declare const text: (max: number) => z.ZodString;