@peable.to/contracts 0.4.0 → 1.0.0

package/dist/types/resources/tax/settings.d.ts

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import { type Expand } from '../../common/objects';
+/**
+ * Peable Tax settings (ADR 0011): the seller's legal identity and defaults, and
+ * whether the owner has approved collection. Changed and approved by the owner
+ * in Orbit only; the merchant API reads them.
+ */
+/** An address as Peable Tax stores it: only `country` is always present. */
+export declare const taxAddressSchema: z.ZodObject<{
+    country: z.ZodString;
+    state: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    postal_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    line1: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    line2: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type TaxAddress = z.output<typeof taxAddressSchema>;
+/** An address in a tax request. */
+export declare const taxAddressParams: z.ZodObject<{
+    country: z.ZodString;
+    state: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    postal_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    line1: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    line2: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type TaxAddressParams = z.input<typeof taxAddressParams>;
+export declare const taxSettingsSchema: z.ZodObject<{
+    object: z.ZodLiteral<"tax.settings">;
+    merchant_id: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        draft: "draft";
+    }>;
+    legal_name: z.ZodNullable<z.ZodString>;
+    head_office: z.ZodNullable<z.ZodObject<{
+        country: z.ZodString;
+        state: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        postal_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        line1: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        line2: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+    default_tax_code: z.ZodString;
+    default_tax_behavior: z.ZodEnum<{
+        inclusive: "inclusive";
+        exclusive: "exclusive";
+    }>;
+    calculation_account: z.ZodEnum<{
+        none: "none";
+        platform: "platform";
+    }>;
+    provider: z.ZodNullable<z.ZodString>;
+    approved_at: z.ZodNullable<z.ZodNumber>;
+    approved_by: z.ZodNullable<z.ZodString>;
+    updated_at: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+export type TaxSettings = Expand<z.output<typeof taxSettingsSchema>>;
+declare module '../../common/objects' {
+    interface ObjectMap {
+        'tax.settings': TaxSettings;
+    }
+}
+/** Orbit's settings update (the owner's, never the merchant API's). Any change returns the settings to `draft`. */
+export declare const updateTaxSettingsParams: z.ZodObject<{
+    legal_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    head_office: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        country: z.ZodString;
+        state: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        postal_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        line1: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        line2: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+    default_tax_code: z.ZodOptional<z.ZodString>;
+    default_tax_behavior: z.ZodOptional<z.ZodEnum<{
+        inclusive: "inclusive";
+        exclusive: "exclusive";
+    }>>;
+}, z.core.$strict>;
+export type UpdateTaxSettingsParams = z.input<typeof updateTaxSettingsParams>;
+export declare const taxSettingsRoutes: readonly [{
+    readonly operationId: "retrieveTaxSettings";
+    readonly method: "get";
+    readonly path: "/v1/tax/settings";
+    readonly tag: "Tax";
+    readonly summary: "Retrieve tax settings";
+    readonly description: "Settings are changed, and collection approved, by the owner in Orbit. Until approved, `POST /v1/tax/calculations` refuses with `tax_settings_not_active`.";
+    readonly auth: "service";
+    readonly scope: "payments:read";
+    readonly response: z.ZodObject<{
+        object: z.ZodLiteral<"tax.settings">;
+        merchant_id: z.ZodString;
+        status: z.ZodEnum<{
+            active: "active";
+            draft: "draft";
+        }>;
+        legal_name: z.ZodNullable<z.ZodString>;
+        head_office: z.ZodNullable<z.ZodObject<{
+            country: z.ZodString;
+            state: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            postal_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            line1: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            line2: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strict>>;
+        default_tax_code: z.ZodString;
+        default_tax_behavior: z.ZodEnum<{
+            inclusive: "inclusive";
+            exclusive: "exclusive";
+        }>;
+        calculation_account: z.ZodEnum<{
+            none: "none";
+            platform: "platform";
+        }>;
+        provider: z.ZodNullable<z.ZodString>;
+        approved_at: z.ZodNullable<z.ZodNumber>;
+        approved_by: z.ZodNullable<z.ZodString>;
+        updated_at: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>;
+    readonly sdk: "tax.retrieveSettings";
+}];

package/dist/types/resources/tax/shared.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+/**
+ * Building blocks every Peable Tax resource shares.
+ *
+ * Tax AMOUNTS (calculations, transactions, the report) are integer JSON
+ * numbers in the currency's minor unit, as Peable Tax has always answered
+ * them: unlike a FAIR amount, a tax amount is denominated in a fiat currency
+ * and is bounded by the safe-integer checks the calculator applies. Business
+ * compliance (ADR 0020) amounts are base-unit strings, as ADR 0014 D1 has it.
+ */
+/** ISO 3166-1 alpha-2, as returned. */
+export declare const taxCountry: z.ZodString;
+/** An ISO 3166-2 subdivision without its country prefix (`CA`, `QC`), as returned. */
+export declare const taxState: z.ZodNullable<z.ZodString>;
+/** A minor-unit integer amount (cents), signed: a reversal's amounts are negative. */
+export declare const taxMinorAmount: z.ZodNumber;
+/** A Peable-side reference: a product, a customer, a refund. */
+export declare const taxReferenceParam: z.ZodString;
+/** An instant in a tax request body. */
+export declare const taxInstantParam: z.ZodNumber;
+/** An official source a rule rests on. */
+export declare const taxRuleSourceSchema: z.ZodObject<{
+    title: z.ZodString;
+    publisher: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strict>;
+export type TaxRuleSource = z.output<typeof taxRuleSourceSchema>;
+/** What a rule cannot see or decide, stated rather than implied. */
+export declare const taxCoverageLimitSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strict>;
+export type TaxCoverageLimit = z.output<typeof taxCoverageLimitSchema>;
+/** The facts a finding or a change rests on: field names, counts, ids — never personal data. */
+export declare const taxFacts: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+/** A country in a compliance request. */
+export declare const complianceCountryParam: z.ZodString;
+/** A subdivision in a compliance request; `null` for the whole country. */
+export declare const complianceStateParam: z.ZodNullable<z.ZodString>;
+/** Free text in a compliance request: trimmed, never empty (`null` clears it). */
+export declare const complianceTextParam: (max: number) => z.ZodNullable<z.ZodString>;
+/** An id another compliance object is linked by (`taxrd_…`, `taxreg_…`, `file_…`). */
+export declare const complianceIdParam: z.ZodString;

package/dist/types/resources/tax/transactions.d.ts

@@ -0,0 +1,404 @@
+import { z } from 'zod';
+import { type List } from '../../common/envelopes';
+import { type Expand } from '../../common/objects';
+/**
+ * A tax transaction (`taxtxn_…`, ADR 0011/0013): a calculation that was paid,
+ * created by Peable when the payment it priced is accepted on its rail. The
+ * report and filings are built from these. A `reversal` is a refund (or credit
+ * note) of an earlier transaction, netted into the original's report rows,
+ * never a deletion of it.
+ */
+/**
+ * What a reversal gave back: the original calculation's amounts, scaled to the
+ * refunded share and NEGATIVE (positive only when it reinstates an earlier
+ * reversal, e.g. a refund the bank later failed).
+ */
+export declare const taxTransactionReversalSchema: z.ZodObject<{
+    amount_total: z.ZodNumber;
+    amount_net: z.ZodNumber;
+    tax_amount: z.ZodNumber;
+    line_items: z.ZodArray<z.ZodObject<{
+        reference: z.ZodString;
+        quantity: z.ZodNumber;
+        tax_code: z.ZodString;
+        tax_behavior: z.ZodEnum<{
+            inclusive: "inclusive";
+            exclusive: "exclusive";
+        }>;
+        amount: z.ZodNumber;
+        amount_tax: z.ZodNumber;
+        amount_net: z.ZodNumber;
+        breakdown: z.ZodArray<z.ZodObject<{
+            country: z.ZodString;
+            state: z.ZodNullable<z.ZodString>;
+            level: z.ZodNullable<z.ZodString>;
+            display_name: z.ZodNullable<z.ZodString>;
+            tax_type: z.ZodNullable<z.ZodString>;
+            rate_percentage: z.ZodNullable<z.ZodString>;
+            taxable_amount: z.ZodNumber;
+            amount: z.ZodNumber;
+            inclusive: z.ZodBoolean;
+            taxability_reason: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type TaxTransactionReversal = z.output<typeof taxTransactionReversalSchema>;
+export declare const taxTransactionSchema: z.ZodObject<{
+    object: z.ZodLiteral<"tax.transaction">;
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        transaction: "transaction";
+        reversal: "reversal";
+    }>;
+    calculation_id: z.ZodString;
+    reference: z.ZodString;
+    rail: z.ZodString;
+    committed_at: z.ZodNumber;
+    reversal_of: z.ZodNullable<z.ZodString>;
+    reversal: z.ZodNullable<z.ZodObject<{
+        amount_total: z.ZodNumber;
+        amount_net: z.ZodNumber;
+        tax_amount: z.ZodNumber;
+        line_items: z.ZodArray<z.ZodObject<{
+            reference: z.ZodString;
+            quantity: z.ZodNumber;
+            tax_code: z.ZodString;
+            tax_behavior: z.ZodEnum<{
+                inclusive: "inclusive";
+                exclusive: "exclusive";
+            }>;
+            amount: z.ZodNumber;
+            amount_tax: z.ZodNumber;
+            amount_net: z.ZodNumber;
+            breakdown: z.ZodArray<z.ZodObject<{
+                country: z.ZodString;
+                state: z.ZodNullable<z.ZodString>;
+                level: z.ZodNullable<z.ZodString>;
+                display_name: z.ZodNullable<z.ZodString>;
+                tax_type: z.ZodNullable<z.ZodString>;
+                rate_percentage: z.ZodNullable<z.ZodString>;
+                taxable_amount: z.ZodNumber;
+                amount: z.ZodNumber;
+                inclusive: z.ZodBoolean;
+                taxability_reason: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    calculation: z.ZodObject<{
+        object: z.ZodLiteral<"tax.calculation">;
+        id: z.ZodString;
+        currency: z.ZodString;
+        collection: z.ZodEnum<{
+            collect: "collect";
+            not_registered: "not_registered";
+            nontaxable: "nontaxable";
+        }>;
+        registration_id: z.ZodNullable<z.ZodString>;
+        provider: z.ZodNullable<z.ZodString>;
+        provider_calculation_ref: z.ZodNullable<z.ZodString>;
+        customer_location_evidence_id: z.ZodString;
+        country: z.ZodString;
+        state: z.ZodNullable<z.ZodString>;
+        amount_total: z.ZodNumber;
+        amount_net: z.ZodNumber;
+        tax_amount_exclusive: z.ZodNumber;
+        tax_amount_inclusive: z.ZodNumber;
+        line_items: z.ZodArray<z.ZodObject<{
+            reference: z.ZodString;
+            quantity: z.ZodNumber;
+            tax_code: z.ZodString;
+            tax_behavior: z.ZodEnum<{
+                inclusive: "inclusive";
+                exclusive: "exclusive";
+            }>;
+            amount: z.ZodNumber;
+            amount_tax: z.ZodNumber;
+            amount_net: z.ZodNumber;
+            breakdown: z.ZodArray<z.ZodObject<{
+                country: z.ZodString;
+                state: z.ZodNullable<z.ZodString>;
+                level: z.ZodNullable<z.ZodString>;
+                display_name: z.ZodNullable<z.ZodString>;
+                tax_type: z.ZodNullable<z.ZodString>;
+                rate_percentage: z.ZodNullable<z.ZodString>;
+                taxable_amount: z.ZodNumber;
+                amount: z.ZodNumber;
+                inclusive: z.ZodBoolean;
+                taxability_reason: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        tax_date: z.ZodNumber;
+        created: z.ZodNumber;
+        expires_at: z.ZodNumber;
+        livemode: z.ZodBoolean;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type TaxTransaction = Expand<z.output<typeof taxTransactionSchema>>;
+declare module '../../common/objects' {
+    interface ObjectMap {
+        'tax.transaction': TaxTransaction;
+    }
+}
+export type TaxTransactionList = List<TaxTransaction>;
+/** The shared list parameters; `created[...]` filters `committed_at`. */
+export declare const listTaxTransactionsQuery: 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<import("../..").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<import("../..").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>>>;
+}, z.core.$strict>;
+export type ListTaxTransactionsParams = z.input<typeof listTaxTransactionsQuery>;
+/**
+ * Record a refund made outside Peable (a FairCoin payment is refunded from the
+ * seller's own wallet, never by the gateway). Card refunds and credit notes are
+ * observed from the provider instead, so the two cannot double-count one refund.
+ */
+export declare const createTaxReversalParams: z.ZodObject<{
+    reference: z.ZodString;
+    amount: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type CreateTaxReversalParams = z.input<typeof createTaxReversalParams>;
+export declare const taxTransactionRoutes: readonly [{
+    readonly operationId: "listTaxTransactions";
+    readonly method: "get";
+    readonly path: "/v1/tax/transactions";
+    readonly tag: "Tax";
+    readonly summary: "List tax transactions";
+    readonly description: "Newest first. `created` filters on `committed_at` — the tax date a filing period is judged by.";
+    readonly auth: "service";
+    readonly scope: "payments:read";
+    readonly query: 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<import("../..").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<import("../..").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>>>;
+    }, z.core.$strict>;
+    readonly response: z.ZodObject<{
+        object: z.ZodLiteral<"list">;
+        data: z.ZodArray<z.ZodObject<{
+            object: z.ZodLiteral<"tax.transaction">;
+            id: z.ZodString;
+            type: z.ZodEnum<{
+                transaction: "transaction";
+                reversal: "reversal";
+            }>;
+            calculation_id: z.ZodString;
+            reference: z.ZodString;
+            rail: z.ZodString;
+            committed_at: z.ZodNumber;
+            reversal_of: z.ZodNullable<z.ZodString>;
+            reversal: z.ZodNullable<z.ZodObject<{
+                amount_total: z.ZodNumber;
+                amount_net: z.ZodNumber;
+                tax_amount: z.ZodNumber;
+                line_items: z.ZodArray<z.ZodObject<{
+                    reference: z.ZodString;
+                    quantity: z.ZodNumber;
+                    tax_code: z.ZodString;
+                    tax_behavior: z.ZodEnum<{
+                        inclusive: "inclusive";
+                        exclusive: "exclusive";
+                    }>;
+                    amount: z.ZodNumber;
+                    amount_tax: z.ZodNumber;
+                    amount_net: z.ZodNumber;
+                    breakdown: z.ZodArray<z.ZodObject<{
+                        country: z.ZodString;
+                        state: z.ZodNullable<z.ZodString>;
+                        level: z.ZodNullable<z.ZodString>;
+                        display_name: z.ZodNullable<z.ZodString>;
+                        tax_type: z.ZodNullable<z.ZodString>;
+                        rate_percentage: z.ZodNullable<z.ZodString>;
+                        taxable_amount: z.ZodNumber;
+                        amount: z.ZodNumber;
+                        inclusive: z.ZodBoolean;
+                        taxability_reason: z.ZodString;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            calculation: z.ZodObject<{
+                object: z.ZodLiteral<"tax.calculation">;
+                id: z.ZodString;
+                currency: z.ZodString;
+                collection: z.ZodEnum<{
+                    collect: "collect";
+                    not_registered: "not_registered";
+                    nontaxable: "nontaxable";
+                }>;
+                registration_id: z.ZodNullable<z.ZodString>;
+                provider: z.ZodNullable<z.ZodString>;
+                provider_calculation_ref: z.ZodNullable<z.ZodString>;
+                customer_location_evidence_id: z.ZodString;
+                country: z.ZodString;
+                state: z.ZodNullable<z.ZodString>;
+                amount_total: z.ZodNumber;
+                amount_net: z.ZodNumber;
+                tax_amount_exclusive: z.ZodNumber;
+                tax_amount_inclusive: z.ZodNumber;
+                line_items: z.ZodArray<z.ZodObject<{
+                    reference: z.ZodString;
+                    quantity: z.ZodNumber;
+                    tax_code: z.ZodString;
+                    tax_behavior: z.ZodEnum<{
+                        inclusive: "inclusive";
+                        exclusive: "exclusive";
+                    }>;
+                    amount: z.ZodNumber;
+                    amount_tax: z.ZodNumber;
+                    amount_net: z.ZodNumber;
+                    breakdown: z.ZodArray<z.ZodObject<{
+                        country: z.ZodString;
+                        state: z.ZodNullable<z.ZodString>;
+                        level: z.ZodNullable<z.ZodString>;
+                        display_name: z.ZodNullable<z.ZodString>;
+                        tax_type: z.ZodNullable<z.ZodString>;
+                        rate_percentage: z.ZodNullable<z.ZodString>;
+                        taxable_amount: z.ZodNumber;
+                        amount: z.ZodNumber;
+                        inclusive: z.ZodBoolean;
+                        taxability_reason: z.ZodString;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
+                tax_date: z.ZodNumber;
+                created: z.ZodNumber;
+                expires_at: z.ZodNumber;
+                livemode: z.ZodBoolean;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        has_more: z.ZodBoolean;
+        url: z.ZodString;
+    }, z.core.$strict>;
+    readonly sdk: "tax.transactions.list";
+    readonly expandable: "tax.transaction";
+}, {
+    readonly operationId: "createTaxReversal";
+    readonly method: "post";
+    readonly path: "/v1/tax/transactions/{id}/reversals";
+    readonly tag: "Tax";
+    readonly summary: "Reverse a tax transaction";
+    readonly description: "For a refund the rail cannot report itself (FairCoin). Card refunds and credit notes, and Orbit invoices, are reversed from their own records and are refused here.";
+    readonly auth: "service";
+    readonly scope: "payments:write";
+    readonly idempotent: true;
+    readonly params: {
+        readonly id: "The original transaction (`taxtxn_…`).";
+    };
+    readonly body: z.ZodObject<{
+        reference: z.ZodString;
+        amount: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    readonly response: z.ZodObject<{
+        object: z.ZodLiteral<"tax.transaction">;
+        id: z.ZodString;
+        type: z.ZodEnum<{
+            transaction: "transaction";
+            reversal: "reversal";
+        }>;
+        calculation_id: z.ZodString;
+        reference: z.ZodString;
+        rail: z.ZodString;
+        committed_at: z.ZodNumber;
+        reversal_of: z.ZodNullable<z.ZodString>;
+        reversal: z.ZodNullable<z.ZodObject<{
+            amount_total: z.ZodNumber;
+            amount_net: z.ZodNumber;
+            tax_amount: z.ZodNumber;
+            line_items: z.ZodArray<z.ZodObject<{
+                reference: z.ZodString;
+                quantity: z.ZodNumber;
+                tax_code: z.ZodString;
+                tax_behavior: z.ZodEnum<{
+                    inclusive: "inclusive";
+                    exclusive: "exclusive";
+                }>;
+                amount: z.ZodNumber;
+                amount_tax: z.ZodNumber;
+                amount_net: z.ZodNumber;
+                breakdown: z.ZodArray<z.ZodObject<{
+                    country: z.ZodString;
+                    state: z.ZodNullable<z.ZodString>;
+                    level: z.ZodNullable<z.ZodString>;
+                    display_name: z.ZodNullable<z.ZodString>;
+                    tax_type: z.ZodNullable<z.ZodString>;
+                    rate_percentage: z.ZodNullable<z.ZodString>;
+                    taxable_amount: z.ZodNumber;
+                    amount: z.ZodNumber;
+                    inclusive: z.ZodBoolean;
+                    taxability_reason: z.ZodString;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        calculation: z.ZodObject<{
+            object: z.ZodLiteral<"tax.calculation">;
+            id: z.ZodString;
+            currency: z.ZodString;
+            collection: z.ZodEnum<{
+                collect: "collect";
+                not_registered: "not_registered";
+                nontaxable: "nontaxable";
+            }>;
+            registration_id: z.ZodNullable<z.ZodString>;
+            provider: z.ZodNullable<z.ZodString>;
+            provider_calculation_ref: z.ZodNullable<z.ZodString>;
+            customer_location_evidence_id: z.ZodString;
+            country: z.ZodString;
+            state: z.ZodNullable<z.ZodString>;
+            amount_total: z.ZodNumber;
+            amount_net: z.ZodNumber;
+            tax_amount_exclusive: z.ZodNumber;
+            tax_amount_inclusive: z.ZodNumber;
+            line_items: z.ZodArray<z.ZodObject<{
+                reference: z.ZodString;
+                quantity: z.ZodNumber;
+                tax_code: z.ZodString;
+                tax_behavior: z.ZodEnum<{
+                    inclusive: "inclusive";
+                    exclusive: "exclusive";
+                }>;
+                amount: z.ZodNumber;
+                amount_tax: z.ZodNumber;
+                amount_net: z.ZodNumber;
+                breakdown: z.ZodArray<z.ZodObject<{
+                    country: z.ZodString;
+                    state: z.ZodNullable<z.ZodString>;
+                    level: z.ZodNullable<z.ZodString>;
+                    display_name: z.ZodNullable<z.ZodString>;
+                    tax_type: z.ZodNullable<z.ZodString>;
+                    rate_percentage: z.ZodNullable<z.ZodString>;
+                    taxable_amount: z.ZodNumber;
+                    amount: z.ZodNumber;
+                    inclusive: z.ZodBoolean;
+                    taxability_reason: z.ZodString;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            tax_date: z.ZodNumber;
+            created: z.ZodNumber;
+            expires_at: z.ZodNumber;
+            livemode: z.ZodBoolean;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    readonly status: 201;
+    readonly sdk: "tax.transactions.createReversal";
+}];

package/dist/types/route.d.ts

@@ -0,0 +1,86 @@
+import type { z } from 'zod';
+import type { Expand } from './common/objects';
+/**
+ * One public route of the gateway, declared once (ADR 0014 D5).
+ *
+ * The backend validates its request with `query` / `body` (the SAME schema
+ * objects, imported), its route tests check every answer against `response`,
+ * the OpenAPI document is generated from the list of these, and the SDK's
+ * methods are generated from `sdk` — so the four cannot disagree.
+ */
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete';
+/**
+ * Who may call it.
+ *
+ * - `service`: an Oxy service token (`Authorization: Bearer …`) the merchant's
+ *   server mints from its application credential — the merchant API;
+ * - `user`: an Oxy user session (`Authorization: Bearer …`) — the person, in
+ *   the Peable app or an Oxy app (social payments, contributions, onboarding);
+ * - `public`: no credential. A payer-facing route, authorised by the
+ *   unguessable id or client secret it is called with.
+ */
+export type RouteAuth = 'service' | 'user' | 'public';
+/** A non-JSON success: bytes (a PDF, a CSV, a file's contents). */
+export interface BinaryResponse {
+    readonly kind: 'binary';
+    readonly contentType: string;
+}
+/** A Server-Sent Events stream (a live tail). */
+export interface StreamResponse {
+    readonly kind: 'stream';
+    /** The schema of each event's `data`. */
+    readonly event: z.ZodType;
+}
+export type RouteResponse = z.ZodType | BinaryResponse | StreamResponse;
+export interface RouteContract {
+    /** Unique, camelCase: `createCustomer`. */
+    readonly operationId: string;
+    readonly method: HttpMethod;
+    /** OpenAPI template: `/v1/customers/{id}`. */
+    readonly path: string;
+    /** The reference section it is listed under: `Customers`. */
+    readonly tag: string;
+    readonly summary: string;
+    readonly description?: string;
+    readonly auth: RouteAuth;
+    /** The Oxy scope a `service` route requires. */
+    readonly scope?: string;
+    /** Path parameters, in path order. Each is a string; documented here. */
+    readonly params?: Readonly<Record<string, string>>;
+    readonly query?: z.ZodType;
+    readonly body?: z.ZodType;
+    /** `multipart` for a file upload; JSON otherwise. */
+    readonly bodyEncoding?: 'json' | 'multipart';
+    /** Accepts `Idempotency-Key` (every merchant `POST` but the few ADR 0014 D3 names). */
+    readonly idempotent?: boolean;
+    /** Accepts `Peable-Account: ca_…` (a platform acting on a connected account). */
+    readonly peableAccount?: boolean;
+    /** Answers only in test mode. */
+    readonly testModeOnly?: boolean;
+    readonly response: RouteResponse;
+    /** The success status. Default 200. */
+    readonly status?: 200 | 201 | 202 | 204;
+    /**
+     * The SDK method, as a dotted path from the client: `customers.create`,
+     * `billing.meters.listEventSummaries`. Absent: not exposed by the server SDK
+     * (a payer route the browser entry owns, a route an Oxy app calls with a
+     * user session).
+     */
+    readonly sdk?: string;
+    /** The object type `expand[]` paths are rooted at (`x-peable-expandable`). */
+    readonly expandable?: string;
+}
+/** Declare a route, keeping its literal types for the SDK's inference. */
+export declare function defineRoute<const R extends RouteContract>(route: R): R;
+/** The parameters a route's body accepts (its wire input). */
+export type BodyOf<R extends RouteContract> = R['body'] extends z.ZodType ? z.input<R['body']> : never;
+/** The parameters a route's query accepts (its wire input). */
+export type QueryOf<R extends RouteContract> = R['query'] extends z.ZodType ? z.input<R['query']> : never;
+/** What a route answers with on success, references resolved. */
+export type ResponseOf<R extends RouteContract> = R['response'] extends z.ZodType ? Expand<z.output<R['response']>> : R['response'] extends BinaryResponse ? Uint8Array : R['response'] extends StreamResponse ? Expand<z.output<R['response']['event']>> : never;
+/** `/v1/customers/{id}` → `/v1/customers/:id`, Express's spelling. */
+export declare function expressPath(path: string): string;
+/** The path parameter names of a template, in order. */
+export declare function pathParamNames(path: string): string[];
+/** Whether `response` is a JSON schema (as opposed to bytes or a stream). */
+export declare function isJsonResponse(response: RouteResponse): response is z.ZodType;