@peable.to/contracts 0.3.0 → 1.0.0

package/dist/esm/resources/tax/reports.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { queryUnixSeconds } from '../../common/params.js';
+import { nullableString, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TAX_COLLECTIONS, TAX_REGISTRATION_SCHEMES } from '../../vocabulary/tax.js';
+import { taxCountry, taxMinorAmount, taxState } from './shared.js';
+/**
+ * The Peable Tax summary report: totals per jurisdiction, registration, tax
+ * type and rate — the lines a return (an OSS return, a state filing) is
+ * prepared from. A report is not a filed return.
+ */
+/** One filing line. Reversals are netted in: `taxable_amount` and `tax_amount` are net. */
+export const taxReportRowSchema = defineComponent('TaxReportRow', z
+    .object({
+    country: taxCountry,
+    state: taxState,
+    registration_id: nullableString.describe('The registration (`taxreg_…`) that collected.'),
+    scheme: z.enum(TAX_REGISTRATION_SCHEMES).nullable(),
+    collection: z.enum(TAX_COLLECTIONS),
+    tax_type: nullableString,
+    rate_percentage: nullableString.describe('Decimal string, e.g. `"20.0"`.'),
+    currency: z.string().describe('Uppercase ISO 4217.'),
+    transactions: z.number().int().nonnegative(),
+    reversals: z.number().int().nonnegative().describe('Reversals netted into this row.'),
+    taxable_amount: taxMinorAmount,
+    tax_amount: taxMinorAmount,
+})
+    .strict());
+export const taxReportSchema = defineObject('tax.report', 'TaxReport', z
+    .object({
+    object: z.literal('tax.report'),
+    from: unixSeconds.describe('Inclusive.'),
+    to: unixSeconds.describe('Exclusive.'),
+    rows: z.array(taxReportRowSchema),
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'tax.report',
+            from: 1790812800,
+            to: 1798761600,
+            rows: [
+                {
+                    country: 'DE',
+                    state: null,
+                    registration_id: 'taxreg_0193b8f2c1a87d3e9f4a',
+                    scheme: 'eu_oss_union',
+                    collection: 'collect',
+                    tax_type: 'vat',
+                    rate_percentage: '19.0',
+                    currency: 'EUR',
+                    transactions: 42,
+                    reversals: 1,
+                    taxable_amount: 41000,
+                    tax_amount: 7790,
+                },
+            ],
+        },
+    ],
+});
+/** The filing window: `from` inclusive, `to` exclusive, Unix seconds. */
+export const taxReportQuery = z
+    .object({
+    // Not `.describe()`d: a described copy would lose the integer spelling the
+    // OpenAPI document gives `queryUnixSeconds`. The route says what they mean.
+    from: queryUnixSeconds,
+    to: queryUnixSeconds,
+    format: z
+        .enum(['json', 'csv'])
+        .optional()
+        .describe('`csv` answers the rows as a `text/csv` attachment (a filing export) instead of JSON.'),
+})
+    .strict();
+export const taxReportRoutes = [
+    defineRoute({
+        operationId: 'retrieveTaxReportSummary',
+        method: 'get',
+        path: '/v1/tax/reports/summary',
+        tag: 'Tax',
+        summary: 'Summarize collected tax',
+        description: 'Totals per jurisdiction, registration, tax type and rate over `[from, to)` (Unix seconds, `from` inclusive, `to` exclusive, on `committed_at`), reversals netted in. With `format=csv`, the same rows as a `text/csv` attachment.',
+        auth: 'service',
+        scope: 'payments:read',
+        query: taxReportQuery,
+        response: taxReportSchema,
+        sdk: 'tax.reports.summary',
+    }),
+];

package/dist/esm/resources/tax/reviewItems.js

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, listQuery } from '../../common/params.js';
+import { livemode, nullableString, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TAX_REVIEW_DECISIONS, TAX_REVIEW_ITEM_STATUSES, TAX_REVIEW_SEVERITIES, } from '../../vocabulary/tax.js';
+import { complianceTextParam, taxState } from './shared.js';
+/** The owner's recorded decision, with who and when. */
+export const taxReviewDecisionSchema = defineComponent('TaxReviewDecision', z
+    .object({
+    decision: z.enum(TAX_REVIEW_DECISIONS),
+    note: nullableString,
+    decided_by: z.string().describe('The Oxy user who decided.'),
+    decided_at: unixSeconds,
+})
+    .strict());
+/**
+ * A finding that needs a person (`taxrev_…`): opened by an assessment, kept
+ * open while later ones find it again, and closed only by the owner's
+ * decision in Orbit. No decision activates collection.
+ */
+export const taxReviewItemSchema = defineObject('tax.review_item', 'TaxReviewItem', z
+    .object({
+    object: z.literal('tax.review_item'),
+    id: z.string().describe('`taxrev_…`.'),
+    livemode,
+    code: z
+        .string()
+        .describe('Machine reason, e.g. `threshold_exceeded`, `registration_status_unknown`.'),
+    severity: z.enum(TAX_REVIEW_SEVERITIES),
+    status: z.enum(TAX_REVIEW_ITEM_STATUSES),
+    rule: nullableString,
+    country: nullableString,
+    state: taxState,
+    message: z.string(),
+    first_assessment: nullableString.describe('The assessment (`taxasm_…`) that opened it.'),
+    latest_assessment: nullableString.describe('The latest assessment (`taxasm_…`) that found it again.'),
+    decision: taxReviewDecisionSchema.nullable(),
+    created: unixSeconds,
+    updated: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'tax.review_item',
+            id: 'taxrev_0193b8f2c1a87d3e9f4a',
+            livemode: false,
+            code: 'threshold_approaching',
+            severity: 'review',
+            status: 'open',
+            rule: 'us_tx_sales_tax',
+            country: 'US',
+            state: 'TX',
+            message: 'Texas revenue is at or above 80% of the safe-harbor threshold.',
+            first_assessment: 'taxasm_0193b8f2c1a87d3e9f4a',
+            latest_assessment: 'taxasm_0193b8f2c1a87d3e9f4a',
+            decision: null,
+            created: 1793750400,
+            updated: 1793750400,
+        },
+    ],
+});
+/** Orbit's decision on an open item (the owner's, never a service credential's). */
+export const resolveTaxReviewItemParams = z
+    .object({
+    decision: z.enum(TAX_REVIEW_DECISIONS),
+    note: complianceTextParam(1000)
+        .optional()
+        .describe("Required for `not_required` and `accepted_risk`: the owner's reason."),
+})
+    .strict()
+    .superRefine((input, ctx) => {
+    if ((input.decision === 'not_required' || input.decision === 'accepted_risk') && !input.note)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['note'],
+            message: `a ${input.decision} decision records the owner's reason in note`,
+        });
+});
+export const listTaxReviewItemsQuery = listQuery({
+    status: z.enum(TAX_REVIEW_ITEM_STATUSES).optional().describe('Only items in this status.'),
+});
+export const taxReviewItemRoutes = [
+    defineRoute({
+        operationId: 'listTaxReviewItems',
+        method: 'get',
+        path: '/v1/tax/review_items',
+        tag: 'Tax compliance',
+        summary: 'List review items',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listTaxReviewItemsQuery,
+        response: listOf(taxReviewItemSchema),
+        sdk: 'tax.compliance.listReviewItems',
+        expandable: 'tax.review_item',
+    }),
+    defineRoute({
+        operationId: 'retrieveTaxReviewItem',
+        method: 'get',
+        path: '/v1/tax/review_items/{id}',
+        tag: 'Tax compliance',
+        summary: 'Retrieve a review item',
+        description: "Deciding an item is the owner's, in Orbit; a service credential only reads it.",
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The review item (`taxrev_…`).' },
+        query: expandOnlyQuery,
+        response: taxReviewItemSchema,
+        sdk: 'tax.compliance.retrieveReviewItem',
+        expandable: 'tax.review_item',
+    }),
+];

package/dist/esm/resources/tax/ruleSet.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { amount, currency, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TAX_RULE_REVIEW_STATUSES, TAX_THRESHOLD_PERIODS, TAX_TYPES } from '../../vocabulary/tax.js';
+import { taxCoverageLimitSchema, taxRuleSourceSchema, taxState } from './shared.js';
+/**
+ * The jurisdiction rule set (ADR 0020): versioned CODE, not data a request can
+ * change. A version is immutable once published; an assessment stores the
+ * version it ran under and replays through the same one. Only the rules listed
+ * are supported; every other jurisdiction is `unsupported`, stated as such.
+ */
+export const taxRuleThresholdSchema = defineComponent('TaxRuleThreshold', z
+    .object({
+    amount,
+    currency,
+    period: z.enum(TAX_THRESHOLD_PERIODS),
+})
+    .strict());
+/**
+ * One supported jurisdiction rule. `review.status` says whether a tax
+ * professional has signed it off — an `unreviewed` rule's findings always go
+ * to the review queue rather than standing on their own.
+ */
+export const taxJurisdictionRuleSchema = defineObject('tax.jurisdiction_rule', 'TaxJurisdictionRule', z
+    .object({
+    object: z.literal('tax.jurisdiction_rule'),
+    id: z.string().describe('Stable, e.g. `eu_vat_b2c_cross_border`.'),
+    rule_set_version: z.string(),
+    name: z.string(),
+    tax_type: z.enum(TAX_TYPES),
+    countries: z.array(z.string()).describe('ISO 3166-1 alpha-2 codes the rule covers.'),
+    state: taxState,
+    effective_from: unixSeconds,
+    threshold: taxRuleThresholdSchema.nullable(),
+    sources: z.array(taxRuleSourceSchema),
+    coverage_limits: z.array(taxCoverageLimitSchema),
+    review: z.object({ status: z.enum(TAX_RULE_REVIEW_STATUSES), note: z.string() }).strict(),
+})
+    .strict());
+export const taxRuleSetSchema = defineObject('tax.rule_set', 'TaxRuleSet', z
+    .object({
+    object: z.literal('tax.rule_set'),
+    version: z.string(),
+    published: unixSeconds,
+    rules: z.array(taxJurisdictionRuleSchema),
+    unsupported: z
+        .string()
+        .describe('Everything not listed is `unsupported`, stated rather than implied.'),
+})
+    .strict());
+export const taxRuleSetRoutes = [
+    defineRoute({
+        operationId: 'retrieveTaxRuleSet',
+        method: 'get',
+        path: '/v1/tax/rule_set',
+        tag: 'Tax compliance',
+        summary: 'Retrieve the current rule set',
+        description: 'The rules assessments currently run under, with their sources and limits.',
+        auth: 'service',
+        scope: 'payments:read',
+        response: taxRuleSetSchema,
+        sdk: 'tax.compliance.retrieveRuleSet',
+    }),
+];

package/dist/esm/resources/tax/salesDestinations.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, listQuery, metadataCreateParam, metadataUpdateParam, } from '../../common/params.js';
+import { livemode, metadata, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TAX_CUSTOMER_TYPES } from '../../vocabulary/tax.js';
+import { complianceCountryParam, complianceStateParam, taxCountry, taxInstantParam, taxState, } from './shared.js';
+/**
+ * Where the business SAYS it sells (`taxdest_…`). Actual sales come from Peable
+ * Tax transactions; an assessment compares the two.
+ */
+export const taxSalesDestinationSchema = defineObject('tax.sales_destination', 'TaxSalesDestination', z
+    .object({
+    object: z.literal('tax.sales_destination'),
+    id: z.string().describe('`taxdest_…`.'),
+    livemode,
+    country: taxCountry,
+    state: taxState,
+    customer_types: z.enum(TAX_CUSTOMER_TYPES),
+    started: unixSeconds.nullable(),
+    ended: unixSeconds.nullable(),
+    metadata,
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'tax.sales_destination',
+            id: 'taxdest_0193b8f2c1a87d3e9f4a',
+            livemode: false,
+            country: 'US',
+            state: 'TX',
+            customer_types: 'consumers',
+            started: 1767225600,
+            ended: null,
+            metadata: {},
+            created: 1793750400,
+        },
+    ],
+});
+/** Orbit's new sales destination (the owner's). */
+export const createTaxSalesDestinationParams = z
+    .object({
+    country: complianceCountryParam,
+    state: complianceStateParam.optional(),
+    customer_types: z.enum(TAX_CUSTOMER_TYPES).optional(),
+    started: taxInstantParam.nullable().optional(),
+    ended: taxInstantParam.nullable().optional(),
+    metadata: metadataCreateParam.optional(),
+})
+    .strict();
+/** Orbit's update (the owner's): the place is fixed; `metadata` is a patch. */
+export const updateTaxSalesDestinationParams = z
+    .object({
+    customer_types: z.enum(TAX_CUSTOMER_TYPES).optional(),
+    started: taxInstantParam.nullable().optional(),
+    ended: taxInstantParam.nullable().optional(),
+    metadata: metadataUpdateParam.optional(),
+})
+    .strict();
+export const listTaxSalesDestinationsQuery = listQuery({});
+export const taxSalesDestinationRoutes = [
+    defineRoute({
+        operationId: 'listTaxSalesDestinations',
+        method: 'get',
+        path: '/v1/tax/sales_destinations',
+        tag: 'Tax compliance',
+        summary: 'List sales destinations',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listTaxSalesDestinationsQuery,
+        response: listOf(taxSalesDestinationSchema),
+        sdk: 'tax.compliance.listSalesDestinations',
+        expandable: 'tax.sales_destination',
+    }),
+    defineRoute({
+        operationId: 'retrieveTaxSalesDestination',
+        method: 'get',
+        path: '/v1/tax/sales_destinations/{id}',
+        tag: 'Tax compliance',
+        summary: 'Retrieve a sales destination',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The sales destination (`taxdest_…`).' },
+        query: expandOnlyQuery,
+        response: taxSalesDestinationSchema,
+        sdk: 'tax.compliance.retrieveSalesDestination',
+        expandable: 'tax.sales_destination',
+    }),
+];

package/dist/esm/resources/tax/settings.js

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { nullableString, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TAX_BEHAVIORS, TAX_CALCULATION_ACCOUNTS, TAX_SETTINGS_STATUSES, } from '../../vocabulary/tax.js';
+import { taxCountry } from './shared.js';
+/**
+ * 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 const taxAddressSchema = defineComponent('TaxAddress', z
+    .object({
+    country: taxCountry,
+    state: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('ISO 3166-2 subdivision without the country prefix (`CA`, `QC`).'),
+    postal_code: z.string().nullable().optional(),
+    city: z.string().nullable().optional(),
+    line1: z.string().nullable().optional(),
+    line2: z.string().nullable().optional(),
+})
+    .strict());
+const addressLine = z.string().trim().min(1).max(200).nullish();
+/** An address in a tax request. */
+export const taxAddressParams = z
+    .object({
+    country: z.string().regex(/^[A-Z]{2}$/),
+    state: z
+        .string()
+        .regex(/^[A-Z0-9]{1,3}$/)
+        .nullish(),
+    postal_code: z.string().trim().min(1).max(20).nullish(),
+    city: addressLine,
+    line1: addressLine,
+    line2: addressLine,
+})
+    .strict();
+export const taxSettingsSchema = defineObject('tax.settings', 'TaxSettings', z
+    .object({
+    object: z.literal('tax.settings'),
+    merchant_id: z.string().describe('The merchant (`merch_…`) these settings belong to.'),
+    status: z
+        .enum(TAX_SETTINGS_STATUSES)
+        .describe('`active` once the owner approved; any edit returns it to `draft`.'),
+    legal_name: nullableString,
+    head_office: taxAddressSchema.nullable(),
+    default_tax_code: z.string().describe('The `txcd_…` a line without its own code uses.'),
+    default_tax_behavior: z.enum(TAX_BEHAVIORS),
+    calculation_account: z
+        .enum(TAX_CALCULATION_ACCOUNTS)
+        .describe("`platform`: Peable's own provider account (official Oxy applications only). `none`: registered sales cannot be calculated and fail closed."),
+    provider: nullableString.describe('The provider that calculates registered sales, when one is reachable.'),
+    approved_at: unixSeconds.nullable(),
+    approved_by: nullableString.describe('The Oxy user who approved collection.'),
+    updated_at: unixSeconds.nullable(),
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'tax.settings',
+            merchant_id: 'merch_0193b8f2c1a87d3e9f4a',
+            status: 'active',
+            legal_name: 'Example Software SL',
+            head_office: { country: 'ES', state: null, postal_code: '08001', city: 'Barcelona' },
+            default_tax_code: 'txcd_10103001',
+            default_tax_behavior: 'exclusive',
+            calculation_account: 'platform',
+            provider: 'stripe_tax',
+            approved_at: 1793750400,
+            approved_by: 'user_42',
+            updated_at: 1793750400,
+        },
+    ],
+});
+/** Orbit's settings update (the owner's, never the merchant API's). Any change returns the settings to `draft`. */
+export const updateTaxSettingsParams = z
+    .object({
+    legal_name: z.string().trim().min(1).max(200).nullable().optional(),
+    head_office: taxAddressParams.nullable().optional(),
+    default_tax_code: z.string().optional(),
+    default_tax_behavior: z.enum(TAX_BEHAVIORS).optional(),
+})
+    .strict();
+export const taxSettingsRoutes = [
+    defineRoute({
+        operationId: 'retrieveTaxSettings',
+        method: 'get',
+        path: '/v1/tax/settings',
+        tag: 'Tax',
+        summary: 'Retrieve tax settings',
+        description: 'Settings are changed, and collection approved, by the owner in Orbit. Until approved, `POST /v1/tax/calculations` refuses with `tax_settings_not_active`.',
+        auth: 'service',
+        scope: 'payments:read',
+        response: taxSettingsSchema,
+        sdk: 'tax.retrieveSettings',
+    }),
+];

package/dist/esm/resources/tax/shared.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { defineComponent } from '../../common/objects.js';
+import { unixSecondsParam } from '../../common/params.js';
+/**
+ * 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 const taxCountry = z.string().describe('ISO 3166-1 alpha-2.');
+/** An ISO 3166-2 subdivision without its country prefix (`CA`, `QC`), as returned. */
+export const taxState = z
+    .string()
+    .nullable()
+    .describe('ISO 3166-2 subdivision without the country prefix (`CA`, `QC`).');
+/** A minor-unit integer amount (cents), signed: a reversal's amounts are negative. */
+export const taxMinorAmount = z
+    .number()
+    .int()
+    .describe('Minor units of `currency` (cents), as an integer.');
+/** A Peable-side reference: a product, a customer, a refund. */
+export const taxReferenceParam = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z0-9_.:-]+$/);
+/** An instant in a tax request body. */
+export const taxInstantParam = unixSecondsParam;
+/** An official source a rule rests on. */
+export const taxRuleSourceSchema = defineComponent('TaxRuleSource', z
+    .object({
+    title: z.string(),
+    publisher: z.string(),
+    url: z.string(),
+})
+    .strict());
+/** What a rule cannot see or decide, stated rather than implied. */
+export const taxCoverageLimitSchema = defineComponent('TaxCoverageLimit', z.object({ code: z.string(), message: z.string() }).strict());
+/** The facts a finding or a change rests on: field names, counts, ids — never personal data. */
+export const taxFacts = z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()]));
+// ── Business compliance request fields (ADR 0020) ────────────────────────────
+/** A country in a compliance request. */
+export const complianceCountryParam = z
+    .string()
+    .regex(/^[A-Z]{2}$/, 'a country is an ISO 3166-1 alpha-2 code');
+/** A subdivision in a compliance request; `null` for the whole country. */
+export const complianceStateParam = z
+    .string()
+    .regex(/^[A-Z0-9]{1,3}$/, 'a state is its ISO 3166-2 subdivision code')
+    .nullable();
+/** Free text in a compliance request: trimmed, never empty (`null` clears it). */
+export const complianceTextParam = (max) => z.string().trim().min(1).max(max).nullable();
+/** An id another compliance object is linked by (`taxrd_…`, `taxreg_…`, `file_…`). */
+export const complianceIdParam = z.string().min(1).max(64);

package/dist/esm/resources/tax/transactions.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { listQuery } from '../../common/params.js';
+import { nullableString, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TAX_TRANSACTION_TYPES } from '../../vocabulary/tax.js';
+import { taxCalculationLineItemSchema, taxCalculationSchema } from './calculations.js';
+import { taxMinorAmount } from './shared.js';
+/**
+ * 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 const taxTransactionReversalSchema = defineComponent('TaxTransactionReversal', z
+    .object({
+    amount_total: taxMinorAmount,
+    amount_net: taxMinorAmount,
+    tax_amount: taxMinorAmount,
+    line_items: z.array(taxCalculationLineItemSchema),
+})
+    .strict());
+export const taxTransactionSchema = defineObject('tax.transaction', 'TaxTransaction', z
+    .object({
+    object: z.literal('tax.transaction'),
+    id: z.string().describe('`taxtxn_…`.'),
+    type: z.enum(TAX_TRANSACTION_TYPES),
+    calculation_id: z.string().describe('The calculation (`taxcalc_…`) that was paid.'),
+    reference: z.string().describe("The rail's own object, e.g. the invoice id."),
+    rail: z.string(),
+    committed_at: unixSeconds.describe('The tax date a filing period is judged by.'),
+    reversal_of: nullableString.describe("The original transaction's id, for a reversal."),
+    reversal: taxTransactionReversalSchema.nullable(),
+    calculation: taxCalculationSchema,
+})
+    .strict());
+/** The shared list parameters; `created[...]` filters `committed_at`. */
+export const listTaxTransactionsQuery = listQuery({});
+/**
+ * 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 const createTaxReversalParams = z
+    .object({
+    reference: z
+        .string()
+        .min(1)
+        .max(200)
+        .regex(/^[A-Za-z0-9_.:-]+$/)
+        .describe("The refund's own reference; a repeated reference returns the same reversal."),
+    amount: z
+        .number()
+        .int()
+        .positive()
+        .safe()
+        .optional()
+        .describe('Gross minor units refunded (what the payer got back). Omitted: everything not yet reversed.'),
+})
+    .strict();
+export const taxTransactionRoutes = [
+    defineRoute({
+        operationId: 'listTaxTransactions',
+        method: 'get',
+        path: '/v1/tax/transactions',
+        tag: 'Tax',
+        summary: 'List tax transactions',
+        description: 'Newest first. `created` filters on `committed_at` — the tax date a filing period is judged by.',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listTaxTransactionsQuery,
+        response: listOf(taxTransactionSchema),
+        sdk: 'tax.transactions.list',
+        expandable: 'tax.transaction',
+    }),
+    defineRoute({
+        operationId: 'createTaxReversal',
+        method: 'post',
+        path: '/v1/tax/transactions/{id}/reversals',
+        tag: 'Tax',
+        summary: 'Reverse a tax transaction',
+        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.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: { id: 'The original transaction (`taxtxn_…`).' },
+        body: createTaxReversalParams,
+        response: taxTransactionSchema,
+        status: 201,
+        sdk: 'tax.transactions.createReversal',
+    }),
+];

package/dist/esm/route.js

@@ -0,0 +1,16 @@
+/** Declare a route, keeping its literal types for the SDK's inference. */
+export function defineRoute(route) {
+    return route;
+}
+/** `/v1/customers/{id}` → `/v1/customers/:id`, Express's spelling. */
+export function expressPath(path) {
+    return path.replace(/\{([^}]+)\}/g, ':$1');
+}
+/** The path parameter names of a template, in order. */
+export function pathParamNames(path) {
+    return [...path.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]);
+}
+/** Whether `response` is a JSON schema (as opposed to bytes or a stream). */
+export function isJsonResponse(response) {
+    return '_zod' in response;
+}

package/dist/esm/routes.js

@@ -0,0 +1,27 @@
+import { billingEngineRoutes } from './resources/billingEngine/index.js';
+import { catalogRoutes } from './resources/catalog/index.js';
+import { checkoutRoutes } from './resources/checkout/index.js';
+import { connectRoutes } from './resources/connect/index.js';
+import { coreRoutes } from './resources/core/index.js';
+import { eventsRoutes } from './resources/events/index.js';
+import { paymentsRoutes } from './resources/payments/index.js';
+import { taxRoutes } from './resources/tax/index.js';
+// Annotated, not inferred: the inferred tuple of every route is larger than the
+// declaration emitter serializes. Each group's own tuple keeps its literal types.
+export const routes = [
+    ...coreRoutes,
+    ...paymentsRoutes,
+    ...checkoutRoutes,
+    ...catalogRoutes,
+    ...billingEngineRoutes,
+    ...connectRoutes,
+    ...taxRoutes,
+    ...eventsRoutes,
+];
+/** The route of an operation. */
+export function routeOf(operationId) {
+    const route = routes.find((candidate) => candidate.operationId === operationId);
+    if (!route)
+        throw new Error(`no route '${operationId}'`);
+    return route;
+}