@peable.to/contracts 0.4.0 → 1.0.0

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

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, listQuery, metadataCreateParam } from '../../common/params.js';
+import { livemode, metadata, nullableString, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TAX_DOCUMENT_CHECKLIST_STATUSES, TAX_DOCUMENT_KINDS } from '../../vocabulary/tax.js';
+import { complianceCountryParam, complianceIdParam, complianceStateParam, complianceTextParam, taxState, } from './shared.js';
+/**
+ * A supporting document (`taxdoc_…`): a `file_…` of purpose `tax_document`
+ * (private, never addressable by URL) with what it is for. Attaching a
+ * document proves nothing by itself; it is what a reviewer reads.
+ */
+export const taxDocumentSchema = defineObject('tax.document', 'TaxDocument', z
+    .object({
+    object: z.literal('tax.document'),
+    id: z.string().describe('`taxdoc_…`.'),
+    livemode,
+    file: z.string().describe('The file (`file_…`, purpose `tax_document`).'),
+    // The file's `status` vocabulary (`available` / `withheld` / `removed`).
+    file_status: z
+        .enum(['available', 'withheld', 'removed'])
+        .describe("The file's standing now: a `removed` file is a document that is gone."),
+    filename: nullableString,
+    kind: z.enum(TAX_DOCUMENT_KINDS),
+    country: nullableString.describe('ISO 3166-1 alpha-2.'),
+    state: taxState,
+    registration_declaration: nullableString.describe('The declaration (`taxrd_…`) it supports, when it names one.'),
+    description: nullableString,
+    metadata,
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'tax.document',
+            id: 'taxdoc_0193b8f2c1a87d3e9f4a',
+            livemode: false,
+            file: 'file_0193b8f2c1a87d3e9f4a',
+            file_status: 'available',
+            filename: 'oss-registration.pdf',
+            kind: 'registration_certificate',
+            country: 'ES',
+            state: null,
+            registration_declaration: 'taxrd_0193b8f2c1a87d3e9f4a',
+            description: null,
+            metadata: {},
+            created: 1793750400,
+        },
+    ],
+});
+export const taxDocumentChecklistItemSchema = defineComponent('TaxDocumentChecklistItem', z
+    .object({
+    key: z.string(),
+    kind: z.enum(TAX_DOCUMENT_KINDS),
+    country: nullableString,
+    state: taxState,
+    status: z
+        .enum(TAX_DOCUMENT_CHECKLIST_STATUSES)
+        .describe('`provided`: an available document is attached; `unavailable`: only removed ones are.'),
+    documents: z.array(z.string()).describe('The attached documents (`taxdoc_…`).'),
+    reason: z.string(),
+})
+    .strict());
+/** The documents the recorded facts call for, and which are attached. */
+export const taxDocumentChecklistSchema = defineObject('tax.document_checklist', 'TaxDocumentChecklist', z
+    .object({
+    object: z.literal('tax.document_checklist'),
+    livemode,
+    items: z.array(taxDocumentChecklistItemSchema),
+})
+    .strict());
+/** Orbit's attachment of a document (the owner's). Attaching the same file again answers the same document. */
+export const createTaxDocumentParams = z
+    .object({
+    file: complianceIdParam.describe('A `file_…` of purpose `tax_document`.'),
+    kind: z.enum(TAX_DOCUMENT_KINDS),
+    country: complianceCountryParam.nullable().optional(),
+    state: complianceStateParam.optional(),
+    registration_declaration: complianceIdParam.nullable().optional(),
+    description: complianceTextParam(500).optional(),
+    metadata: metadataCreateParam.optional(),
+})
+    .strict();
+export const listTaxDocumentsQuery = listQuery({});
+export const taxDocumentRoutes = [
+    defineRoute({
+        operationId: 'listTaxDocuments',
+        method: 'get',
+        path: '/v1/tax/documents',
+        tag: 'Tax compliance',
+        summary: 'List tax documents',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listTaxDocumentsQuery,
+        response: listOf(taxDocumentSchema),
+        sdk: 'tax.compliance.listDocuments',
+        expandable: 'tax.document',
+    }),
+    defineRoute({
+        operationId: 'retrieveTaxDocument',
+        method: 'get',
+        path: '/v1/tax/documents/{id}',
+        tag: 'Tax compliance',
+        summary: 'Retrieve a tax document',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The document (`taxdoc_…`).' },
+        query: expandOnlyQuery,
+        response: taxDocumentSchema,
+        sdk: 'tax.compliance.retrieveDocument',
+        expandable: 'tax.document',
+    }),
+    defineRoute({
+        operationId: 'retrieveTaxDocumentChecklist',
+        method: 'get',
+        path: '/v1/tax/document_checklist',
+        tag: 'Tax compliance',
+        summary: 'Retrieve the document checklist',
+        auth: 'service',
+        scope: 'payments:read',
+        response: taxDocumentChecklistSchema,
+        sdk: 'tax.compliance.retrieveDocumentChecklist',
+    }),
+];

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

@@ -0,0 +1,63 @@
+// Peable Tax (ADR 0011) and its business compliance (ADR 0020): one module per
+// resource, re-exported here, and their routes concatenated into `taxRoutes`.
+import { taxAssessmentRoutes } from './assessments.js';
+import { taxBusinessProfileRoutes } from './businessProfile.js';
+import { taxCalculationRoutes } from './calculations.js';
+import { taxCapabilityRoutes } from './capabilities.js';
+import { taxCodeRoutes } from './codes.js';
+import { taxComplianceActionRoutes } from './complianceActions.js';
+import { taxDeadlineRoutes } from './deadlines.js';
+import { taxDocumentRoutes } from './documents.js';
+import { taxLocationEvidenceRoutes } from './locationEvidence.js';
+import { taxOperatingLocationRoutes } from './operatingLocations.js';
+import { taxProductRoutes } from './products.js';
+import { taxRegistrationDeclarationRoutes } from './registrationDeclarations.js';
+import { taxRegistrationRoutes } from './registrations.js';
+import { taxReportRoutes } from './reports.js';
+import { taxReviewItemRoutes } from './reviewItems.js';
+import { taxRuleSetRoutes } from './ruleSet.js';
+import { taxSalesDestinationRoutes } from './salesDestinations.js';
+import { taxSettingsRoutes } from './settings.js';
+import { taxTransactionRoutes } from './transactions.js';
+export * from './assessments.js';
+export * from './businessProfile.js';
+export * from './calculations.js';
+export * from './capabilities.js';
+export * from './codes.js';
+export * from './complianceActions.js';
+export * from './deadlines.js';
+export * from './documents.js';
+export * from './locationEvidence.js';
+export * from './operatingLocations.js';
+export * from './products.js';
+export * from './registrationDeclarations.js';
+export * from './registrations.js';
+export * from './reports.js';
+export * from './reviewItems.js';
+export * from './ruleSet.js';
+export * from './salesDestinations.js';
+export * from './settings.js';
+export * from './shared.js';
+export * from './transactions.js';
+/** Peable Tax: collection (settings, evidence, calculations, transactions, reports) and business compliance. */
+export const taxRoutes = [
+    ...taxCodeRoutes,
+    ...taxSettingsRoutes,
+    ...taxRegistrationRoutes,
+    ...taxProductRoutes,
+    ...taxLocationEvidenceRoutes,
+    ...taxCalculationRoutes,
+    ...taxTransactionRoutes,
+    ...taxReportRoutes,
+    ...taxBusinessProfileRoutes,
+    ...taxOperatingLocationRoutes,
+    ...taxSalesDestinationRoutes,
+    ...taxRegistrationDeclarationRoutes,
+    ...taxDocumentRoutes,
+    ...taxRuleSetRoutes,
+    ...taxCapabilityRoutes,
+    ...taxDeadlineRoutes,
+    ...taxAssessmentRoutes,
+    ...taxReviewItemRoutes,
+    ...taxComplianceActionRoutes,
+];

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

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { livemode, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TAX_EVIDENCE_STATUSES, TAX_LOCATION_EVIDENCE_TYPES } from '../../vocabulary/tax.js';
+import { taxAddressParams } from './settings.js';
+import { taxCountry, taxReferenceParam, taxState } from './shared.js';
+/**
+ * Customer location evidence (`taxloc_…`, ADR 0011): what places a customer
+ * in a jurisdiction, judged against that jurisdiction's own rule. There is
+ * deliberately no language, currency, locale or timezone evidence. An IP
+ * address is never stored; at most its salted hash.
+ */
+/** An item as judged: the place it points at, never more of the customer than the rule needs. */
+export const taxLocationEvidenceResultItemSchema = defineComponent('TaxLocationEvidenceResultItem', z
+    .object({
+    type: z.enum(TAX_LOCATION_EVIDENCE_TYPES),
+    country: taxCountry,
+    state: taxState,
+})
+    .strict());
+export const taxLocationEvidenceSchema = defineObject('tax.location_evidence', 'TaxLocationEvidence', z
+    .object({
+    object: z.literal('tax.location_evidence'),
+    id: z.string().describe('`taxloc_…`.'),
+    customer_ref: z.string().describe('The customer this evidence is about.'),
+    status: z
+        .enum(TAX_EVIDENCE_STATUSES)
+        .describe('Only `sufficient` evidence can be calculated against.'),
+    rule: z
+        .string()
+        .describe('The jurisdiction rule applied: `eu_digital_two_items`, `gb_digital_two_items`, `us_billing_address`, `ca_billing_address`, `default_one_item`, or `none` when no item names a country.'),
+    country: taxCountry
+        .nullable()
+        .describe('Where the evidence places the customer, when it does.'),
+    state: taxState,
+    items: z.array(taxLocationEvidenceResultItemSchema),
+    observed_at: unixSeconds,
+    expires_at: unixSeconds.describe('Evidence stays usable for a day.'),
+    livemode,
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'tax.location_evidence',
+            id: 'taxloc_0193b8f2c1a87d3e9f4a',
+            customer_ref: 'cus_0193b8f2c1a87d3e9f4a',
+            status: 'sufficient',
+            rule: 'eu_digital_two_items',
+            country: 'DE',
+            state: null,
+            items: [
+                { type: 'billing_address', country: 'DE', state: null },
+                { type: 'ip_address', country: 'DE', state: null },
+            ],
+            observed_at: 1793750400,
+            expires_at: 1793836800,
+            livemode: false,
+        },
+    ],
+});
+const evidenceCountry = z.string().regex(/^[A-Z]{2}$/);
+const evidenceState = z
+    .string()
+    .regex(/^[A-Z0-9]{1,3}$/)
+    .nullish();
+const ipv4 = z.ipv4();
+const ipv6 = z.ipv6();
+/**
+ * One piece of evidence. Strict: an item claiming a language, currency, locale
+ * or timezone is not a smaller kind of evidence, it is refused.
+ */
+export const taxLocationEvidenceItemParams = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('billing_address'), address: taxAddressParams }).strict(),
+    z
+        .object({
+        type: z.literal('ip_address'),
+        ip_address: z
+            .string()
+            .refine((value) => ipv4.safeParse(value).success || ipv6.safeParse(value).success, 'Not an IP address'),
+        country: evidenceCountry,
+        state: evidenceState,
+    })
+        .strict(),
+    z
+        .object({
+        type: z.enum(['payment_method_country', 'bank_country', 'sim_country', 'landline_country']),
+        country: evidenceCountry,
+    })
+        .strict(),
+]);
+/** At least one item and at most six. */
+export const taxLocationEvidenceItemsParam = z.array(taxLocationEvidenceItemParams).min(1).max(6);
+export const createTaxLocationEvidenceParams = z
+    .object({
+    customer_ref: taxReferenceParam.describe('The customer this evidence is about; for billing, the `storeId`.'),
+    evidence: taxLocationEvidenceItemsParam,
+})
+    .strict();
+export const taxLocationEvidenceRoutes = [
+    defineRoute({
+        operationId: 'createTaxLocationEvidence',
+        method: 'post',
+        path: '/v1/tax/location_evidence',
+        tag: 'Tax',
+        summary: 'Record customer location evidence',
+        description: "Judged at once against the customer's jurisdiction rule; the answer says whether it is `sufficient` to calculate against.",
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createTaxLocationEvidenceParams,
+        response: taxLocationEvidenceSchema,
+        status: 201,
+        sdk: 'tax.locationEvidence.create',
+    }),
+    defineRoute({
+        operationId: 'retrieveTaxLocationEvidence',
+        method: 'get',
+        path: '/v1/tax/location_evidence/{id}',
+        tag: 'Tax',
+        summary: 'Retrieve customer location evidence',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The evidence (`taxloc_…`).' },
+        response: taxLocationEvidenceSchema,
+        sdk: 'tax.locationEvidence.retrieve',
+    }),
+];

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

@@ -0,0 +1,95 @@
+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, nullableString, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TAX_OPERATING_LOCATION_KINDS } from '../../vocabulary/tax.js';
+import { complianceCountryParam, complianceStateParam, complianceTextParam, taxCountry, taxInstantParam, taxState, } from './shared.js';
+/**
+ * Where the business ACTUALLY operates (`taxol_…`). `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 taxOperatingLocationSchema = defineObject('tax.operating_location', 'TaxOperatingLocation', z
+    .object({
+    object: z.literal('tax.operating_location'),
+    id: z.string().describe('`taxol_…`.'),
+    livemode,
+    kind: z.enum(TAX_OPERATING_LOCATION_KINDS),
+    country: taxCountry,
+    state: taxState,
+    description: nullableString,
+    started: unixSeconds.nullable(),
+    ended: unixSeconds.nullable().describe('Set once the business no longer operates there.'),
+    metadata,
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'tax.operating_location',
+            id: 'taxol_0193b8f2c1a87d3e9f4a',
+            livemode: false,
+            kind: 'head_office',
+            country: 'ES',
+            state: null,
+            description: 'Registered office, Barcelona',
+            started: 1735689600,
+            ended: null,
+            metadata: {},
+            created: 1793750400,
+        },
+    ],
+});
+/** Orbit's new operating location (the owner's). */
+export const createTaxOperatingLocationParams = z
+    .object({
+    kind: z.enum(TAX_OPERATING_LOCATION_KINDS),
+    country: complianceCountryParam,
+    state: complianceStateParam.optional(),
+    description: complianceTextParam(500).optional(),
+    started: taxInstantParam.nullable().optional(),
+    ended: taxInstantParam.nullable().optional(),
+    metadata: metadataCreateParam.optional(),
+})
+    .strict();
+/** Orbit's update (the owner's): `kind` and the place are fixed; `metadata` is a patch. */
+export const updateTaxOperatingLocationParams = z
+    .object({
+    description: complianceTextParam(500).optional(),
+    started: taxInstantParam.nullable().optional(),
+    ended: taxInstantParam.nullable().optional(),
+    metadata: metadataUpdateParam.optional(),
+})
+    .strict();
+export const listTaxOperatingLocationsQuery = listQuery({});
+export const taxOperatingLocationRoutes = [
+    defineRoute({
+        operationId: 'listTaxOperatingLocations',
+        method: 'get',
+        path: '/v1/tax/operating_locations',
+        tag: 'Tax compliance',
+        summary: 'List operating locations',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listTaxOperatingLocationsQuery,
+        response: listOf(taxOperatingLocationSchema),
+        sdk: 'tax.compliance.listOperatingLocations',
+        expandable: 'tax.operating_location',
+    }),
+    defineRoute({
+        operationId: 'retrieveTaxOperatingLocation',
+        method: 'get',
+        path: '/v1/tax/operating_locations/{id}',
+        tag: 'Tax compliance',
+        summary: 'Retrieve an operating location',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The operating location (`taxol_…`).' },
+        query: expandOnlyQuery,
+        response: taxOperatingLocationSchema,
+        sdk: 'tax.compliance.retrieveOperatingLocation',
+        expandable: 'tax.operating_location',
+    }),
+];

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

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineObject } from '../../common/objects.js';
+import { unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { taxReferenceParam } from './shared.js';
+/**
+ * A product's tax code: what a calculation line naming `product_ref` is taxed
+ * as when the line does not say. Classifying a product is the seller's call.
+ */
+export const taxProductCodeSchema = defineObject('tax.product', 'TaxProductCode', z
+    .object({
+    object: z.literal('tax.product'),
+    product_ref: z
+        .string()
+        .describe("The merchant's product or plan reference (a billing `planId`)."),
+    tax_code: z.string().describe('`txcd_…`.'),
+    updated_at: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'tax.product',
+            product_ref: 'plan_pro_monthly',
+            tax_code: 'txcd_10103001',
+            updated_at: 1793750400,
+        },
+    ],
+});
+/** `{productRef}` of `PUT /v1/tax/products/{productRef}`. */
+export const taxProductRefParam = taxReferenceParam;
+export const setTaxProductCodeParams = z
+    .object({ tax_code: z.string().describe('A `txcd_…` from `GET /v1/tax/codes`.') })
+    .strict();
+export const taxProductRoutes = [
+    defineRoute({
+        operationId: 'listTaxProducts',
+        method: 'get',
+        path: '/v1/tax/products',
+        tag: 'Tax',
+        summary: 'List product tax codes',
+        description: 'Every classified product, by `product_ref`: a complete list, `has_more` is `false`.',
+        auth: 'service',
+        scope: 'payments:read',
+        response: listOf(taxProductCodeSchema),
+        sdk: 'tax.products.list',
+    }),
+    defineRoute({
+        operationId: 'setTaxProductCode',
+        method: 'put',
+        path: '/v1/tax/products/{productRef}',
+        tag: 'Tax',
+        summary: "Set a product's tax code",
+        description: 'Creates the classification or replaces it.',
+        auth: 'service',
+        scope: 'payments:write',
+        params: {
+            productRef: "The merchant's product or plan reference: 1–128 of `A-Z a-z 0-9 _ . : -`.",
+        },
+        body: setTaxProductCodeParams,
+        response: taxProductCodeSchema,
+        sdk: 'tax.products.setTaxCode',
+    }),
+];

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

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject } from '../../common/objects.js';
+import { expandOnlyQuery, listQuery, metadataCreateParam, metadataUpdateParam, } from '../../common/params.js';
+import { livemode, metadata, nullableString, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TAX_FILING_FREQUENCIES, TAX_REGISTRATION_DECLARATION_STATUSES, TAX_REGISTRATION_SCHEMES, } from '../../vocabulary/tax.js';
+import { complianceCountryParam, complianceIdParam, complianceStateParam, complianceTextParam, taxCountry, taxInstantParam, taxState, } from './shared.js';
+/** No authority integration confirms anything yet: every declaration is `unverified`. */
+export const taxDeclarationVerificationSchema = defineComponent('TaxRegistrationDeclarationVerification', z
+    .object({
+    status: z.literal('unverified'),
+    reason: z.literal('no_authority_integration'),
+})
+    .strict());
+/**
+ * A declared registration status (`taxrd_…`): where the business stands with a
+ * tax authority, IN ITS OWN WORDS. Storing one is NOT registration with a
+ * government, and it never makes Peable collect: collection needs a Peable Tax
+ * registration (`taxreg_…`) the owner approved.
+ */
+export const taxRegistrationDeclarationSchema = defineObject('tax.registration_declaration', 'TaxRegistrationDeclaration', z
+    .object({
+    object: z.literal('tax.registration_declaration'),
+    id: z.string().describe('`taxrd_…`.'),
+    livemode,
+    country: taxCountry,
+    state: taxState,
+    scheme: z
+        .enum(TAX_REGISTRATION_SCHEMES)
+        .nullable()
+        .describe('The scheme, when the owner knows it; `null` for `unknown`.'),
+    status: z.enum(TAX_REGISTRATION_DECLARATION_STATUSES),
+    effective_from: unixSeconds.nullable(),
+    effective_to: unixSeconds.nullable(),
+    filing_frequency: z.enum(TAX_FILING_FREQUENCIES),
+    collection_registration: nullableString.describe('The Peable Tax collection registration (`taxreg_…`) it corresponds to, when there is one.'),
+    verification: taxDeclarationVerificationSchema,
+    note: nullableString,
+    metadata,
+    created: unixSeconds,
+    updated: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'tax.registration_declaration',
+            id: 'taxrd_0193b8f2c1a87d3e9f4a',
+            livemode: false,
+            country: 'ES',
+            state: null,
+            scheme: 'eu_oss_union',
+            status: 'registered',
+            effective_from: 1767225600,
+            effective_to: null,
+            filing_frequency: 'quarterly',
+            collection_registration: 'taxreg_0193b8f2c1a87d3e9f4a',
+            verification: { status: 'unverified', reason: 'no_authority_integration' },
+            note: null,
+            metadata: {},
+            created: 1793750400,
+            updated: 1793750400,
+        },
+    ],
+});
+const declarationFields = {
+    scheme: z.enum(TAX_REGISTRATION_SCHEMES).nullable().optional(),
+    status: z.enum(TAX_REGISTRATION_DECLARATION_STATUSES),
+    effective_from: taxInstantParam.nullable().optional(),
+    effective_to: taxInstantParam.nullable().optional(),
+    filing_frequency: z.enum(TAX_FILING_FREQUENCIES).optional(),
+    collection_registration: complianceIdParam.nullable().optional(),
+    note: complianceTextParam(1000).optional(),
+};
+/** Orbit's new declaration (the owner's). */
+export const createTaxRegistrationDeclarationParams = z
+    .object({
+    country: complianceCountryParam,
+    state: complianceStateParam.optional(),
+    ...declarationFields,
+    metadata: metadataCreateParam.optional(),
+})
+    .strict();
+/** Orbit's update (the owner's): the place is fixed; `metadata` is a patch. */
+export const updateTaxRegistrationDeclarationParams = z
+    .object({
+    ...declarationFields,
+    status: declarationFields.status.optional(),
+    metadata: metadataUpdateParam.optional(),
+})
+    .strict();
+export const listTaxRegistrationDeclarationsQuery = listQuery({});
+export const taxRegistrationDeclarationRoutes = [
+    defineRoute({
+        operationId: 'listTaxRegistrationDeclarations',
+        method: 'get',
+        path: '/v1/tax/registration_declarations',
+        tag: 'Tax compliance',
+        summary: 'List registration declarations',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listTaxRegistrationDeclarationsQuery,
+        response: listOf(taxRegistrationDeclarationSchema),
+        sdk: 'tax.compliance.listRegistrationDeclarations',
+        expandable: 'tax.registration_declaration',
+    }),
+    defineRoute({
+        operationId: 'retrieveTaxRegistrationDeclaration',
+        method: 'get',
+        path: '/v1/tax/registration_declarations/{id}',
+        tag: 'Tax compliance',
+        summary: 'Retrieve a registration declaration',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The declaration (`taxrd_…`).' },
+        query: expandOnlyQuery,
+        response: taxRegistrationDeclarationSchema,
+        sdk: 'tax.compliance.retrieveRegistrationDeclaration',
+        expandable: 'tax.registration_declaration',
+    }),
+];

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

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineObject } from '../../common/objects.js';
+import { nullableString, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TAX_REGISTRATION_SCHEMES, TAX_REGISTRATION_STATUSES } from '../../vocabulary/tax.js';
+import { taxCountry, taxInstantParam, taxState } from './shared.js';
+/**
+ * A Peable Tax registration (`taxreg_…`, ADR 0011): where the seller says it
+ * is registered to collect. Only registrations the owner approved make Peable
+ * collect. Registering with a government is the seller's job, never Peable's.
+ */
+export const taxRegistrationSchema = defineObject('tax.registration', 'TaxRegistration', z
+    .object({
+    object: z.literal('tax.registration'),
+    id: z.string().describe('`taxreg_…`.'),
+    country: taxCountry,
+    state: taxState,
+    scheme: z.enum(TAX_REGISTRATION_SCHEMES),
+    registration_number: nullableString.describe('The government-issued number (VAT id, state permit), when there is one.'),
+    active_from: unixSeconds,
+    expires_at: unixSeconds.nullable(),
+    status: z
+        .enum(TAX_REGISTRATION_STATUSES)
+        .describe('`pending_approval` until the owner approves; `scheduled` before `active_from`.'),
+    approved_at: unixSeconds.nullable(),
+    provider_registration_ref: nullableString.describe('The mirrored registration at the calculating provider, once synced.'),
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'tax.registration',
+            id: 'taxreg_0193b8f2c1a87d3e9f4a',
+            country: 'ES',
+            state: null,
+            scheme: 'eu_oss_union',
+            registration_number: 'ESB12345678',
+            active_from: 1793750400,
+            expires_at: null,
+            status: 'active',
+            approved_at: 1793750400,
+            provider_registration_ref: 'taxreg_1QxYz2AbCdEf',
+            created: 1793664000,
+        },
+    ],
+});
+/** Orbit's new registration (the owner's): pending until the owner approves. */
+export const createTaxRegistrationParams = z
+    .object({
+    country: z.string().regex(/^[A-Z]{2}$/),
+    state: z
+        .string()
+        .regex(/^[A-Z0-9]{1,3}$/)
+        .nullish(),
+    scheme: z.enum(TAX_REGISTRATION_SCHEMES),
+    registration_number: z.string().trim().min(1).max(64).nullish(),
+    active_from: taxInstantParam
+        .optional()
+        .describe('Unix seconds; omitted means immediately on approval.'),
+    expires_at: taxInstantParam.nullish(),
+})
+    .strict();
+/** Orbit's end of a registration at `expires_at`. */
+export const endTaxRegistrationParams = z.object({ expires_at: taxInstantParam }).strict();
+export const taxRegistrationRoutes = [
+    defineRoute({
+        operationId: 'listTaxRegistrations',
+        method: 'get',
+        path: '/v1/tax/registrations',
+        tag: 'Tax',
+        summary: 'List tax registrations',
+        description: 'Every registration of the merchant, oldest first: a complete list, `has_more` is `false`. Registrations are added and approved by the owner in Orbit.',
+        auth: 'service',
+        scope: 'payments:read',
+        response: listOf(taxRegistrationSchema),
+        sdk: 'tax.listRegistrations',
+    }),
+];