@peable.to/contracts 1.1.0 → 2.0.0

package/dist/cjs/resources/catalog/billing.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.billingRoutes = exports.cancelBillingSubscriptionParams = exports.billingFaircoinFxQuoteSchema = exports.billingFaircoinRenewalChoiceSchema = exports.billingFaircoinRenewalRevocationSchema = exports.billingFaircoinRenewalConsentSchema = exports.retrieveBillingInvoiceAuthorityQuery = exports.billingFinalInvoiceAuthoritySchema = exports.billingFinalInvoiceSchema = exports.billingInvoiceAuthoritySourceSchema = exports.billingInvoiceTaxLineSchema = exports.billingInvoiceStateSchema = exports.billingPaidInvoiceSchema = exports.createBillingPortalParams = exports.billingCheckoutOperationRecoverySchema = exports.billingCheckoutOperationSourceSchema = exports.billingCheckoutOperationParams = exports.retrieveBillingCheckoutOperationQuery = exports.billingCheckoutObservationSchema = exports.billingSubscriptionSchema = exports.billingEmbeddedCheckoutBindingSchema = exports.billingEmbeddedCheckoutActionSchema = exports.billingEmbeddedCheckoutConfigurationSchema = exports.billingEmbeddedCheckoutScopeSchema = exports.billingEmbeddedCheckoutSessionSchema = exports.billingCheckoutSessionSchema = exports.billingHostedSessionSchema = exports.createBillingCheckoutParams = exports.billingTaxQuoteSchema = exports.createBillingTaxQuoteParams = exports.billingCustomerSchema = exports.ensureBillingCustomerParams = exports.billingRailListSchema = exports.billingRailOptionSchema = exports.billingRailOfferSchema = exports.billingPriceRef = exports.billingCustomerRef = exports.billingInstant = exports.billingReturnUrl = exports.billingRailId = exports.billingIdempotencyKey = exports.billingReference = void 0;
 const zod_1 = require("zod");
 const objects_1 = require("../../common/objects");
+const primitives_1 = require("../../common/primitives");
 const route_1 = require("../../route");
 const catalog_1 = require("../../vocabulary/catalog");
 /**
@@ -50,8 +51,6 @@ exports.billingReturnUrl = zod_1.z
 }, 'An HTTPS return URL without credentials is required');
 /** An instant in signed billing evidence: integer Unix seconds that stay a safe integer. */
 exports.billingInstant = zod_1.z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
-/** A whole number of minor units (cents) in signed billing evidence. */
-const minorUnits = zod_1.z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
 /** A billing customer reference (`cus_…`). */
 exports.billingCustomerRef = zod_1.z
     .string()
@@ -85,7 +84,7 @@ exports.billingRailOfferSchema = (0, objects_1.defineComponent)('BillingRailOffe
     plan_id: zod_1.z.string(),
     interval: billingInterval,
     currency: zod_1.z.string(),
-    gross_minor_units: zod_1.z.number().int(),
+    gross_minor_units: primitives_1.amount,
     tax_treatment: taxTreatment,
 })
     .strict());
@@ -134,10 +133,10 @@ exports.createBillingTaxQuoteParams = zod_1.z
     customer_location_evidence_id: exports.billingReference.describe('A `tax.location_evidence` id (`taxloc_…`) recorded for this `store_id`.'),
 })
     .strict();
-/** A signed, immutable, single-use Peable Tax quote (schema version 2). */
+/** A signed, immutable, single-use Peable Tax quote (schema version 3). */
 exports.billingTaxQuoteSchema = (0, objects_1.defineComponent)('BillingTaxQuote', zod_1.z
     .object({
-    schema_version: zod_1.z.literal(2),
+    schema_version: zod_1.z.literal(3),
     source: zod_1.z
         .object({
         merchant_id: exports.billingReference,
@@ -152,9 +151,9 @@ exports.billingTaxQuoteSchema = (0, objects_1.defineComponent)('BillingTaxQuote'
         .object({
         id: exports.billingReference,
         currency: zod_1.z.string().regex(/^[A-Z]{3}$/),
-        gross_minor_units: minorUnits,
-        net_minor_units: minorUnits,
-        tax_minor_units: minorUnits,
+        gross_minor_units: primitives_1.amount,
+        net_minor_units: primitives_1.amount,
+        tax_minor_units: primitives_1.amount,
         tax_treatment: taxTreatment,
         seller_id: exports.billingReference,
         invoice_issuer_id: exports.billingReference,
@@ -223,7 +222,7 @@ exports.billingEmbeddedCheckoutActionSchema = (0, objects_1.defineComponent)('Bi
     session_id: zod_1.z.string(),
     client_secret: zod_1.z.string(),
     publishable_key: zod_1.z.string(),
-    amount_minor_units: zod_1.z.number().int(),
+    amount_minor_units: primitives_1.amount,
     currency: zod_1.z.string(),
 })
     .strict());
@@ -353,10 +352,9 @@ exports.billingPaidInvoiceSchema = (0, objects_1.defineComponent)('BillingPaidIn
     plan_id: zod_1.z.string(),
     livemode: zod_1.z.boolean(),
     currency: zod_1.z.string(),
-    amount_paid: zod_1.z.string(),
-    net_amount: zod_1.z.string().nullable(),
-    tax_amount: zod_1.z
-        .string()
+    amount_paid: primitives_1.amount,
+    net_amount: primitives_1.amount.nullable(),
+    tax_amount: primitives_1.amount
         .nullable()
         .describe('A provider observation, not a tax quote or seller configuration.'),
     period_start: zod_1.z.number().int(),
@@ -368,7 +366,7 @@ exports.billingPaidInvoiceSchema = (0, objects_1.defineComponent)('BillingPaidIn
 exports.billingInvoiceStateSchema = (0, objects_1.defineComponent)('BillingInvoiceState', exports.billingPaidInvoiceSchema
     .extend({
     charge_id: zod_1.z.string(),
-    amount_refunded: zod_1.z.string(),
+    amount_refunded: primitives_1.amount,
     state: zod_1.z.enum(['paid', 'fully_refunded', 'partially_refunded']),
 })
     .strict());
@@ -380,8 +378,8 @@ exports.billingInvoiceTaxLineSchema = (0, objects_1.defineComponent)('BillingInv
     state: zod_1.z.string().nullable(),
     tax_type: zod_1.z.string().nullable(),
     rate_percentage: zod_1.z.string().nullable(),
-    taxable_minor_units: minorUnits,
-    tax_minor_units: minorUnits,
+    taxable_minor_units: primitives_1.amount,
+    tax_minor_units: primitives_1.amount,
     inclusive: zod_1.z.boolean(),
     taxability_reason: zod_1.z.string().min(1),
 })
@@ -409,10 +407,10 @@ exports.billingFinalInvoiceSchema = (0, objects_1.defineComponent)('BillingFinal
     .object({
     platform: zod_1.z.literal('peable'),
     currency: zod_1.z.string().regex(/^[A-Z]{3}$/),
-    gross_minor_units: minorUnits,
-    net_minor_units: minorUnits,
-    tax_minor_units: minorUnits,
-    merchant_fee_minor_units: minorUnits,
+    gross_minor_units: primitives_1.amount,
+    net_minor_units: primitives_1.amount,
+    tax_minor_units: primitives_1.amount,
+    merchant_fee_minor_units: primitives_1.amount,
     tax_treatment: taxTreatment,
     seller_id: exports.billingReference,
     invoice_issuer_id: exports.billingReference,
@@ -455,10 +453,10 @@ exports.billingFinalInvoiceSchema = (0, objects_1.defineComponent)('BillingFinal
         .describe('Present only when asked for (`include=tax_lines`): the frozen Peable Tax lines behind `tax_minor_units`, covered by the same signature.'),
 })
     .strict());
-/** A signed final invoice authority (schema version 2). Verify it against the pinned keys. */
+/** A signed final invoice authority (schema version 3). Verify it against the pinned keys. */
 exports.billingFinalInvoiceAuthoritySchema = (0, objects_1.defineComponent)('BillingFinalInvoiceAuthority', zod_1.z
     .object({
-    schema_version: zod_1.z.literal(2),
+    schema_version: zod_1.z.literal(3),
     source: exports.billingInvoiceAuthoritySourceSchema,
     invoice: exports.billingFinalInvoiceSchema,
     method: zod_1.z.enum(['card', 'faircoin']),
@@ -526,7 +524,7 @@ exports.billingFaircoinFxQuoteSchema = (0, objects_1.defineComponent)('BillingFa
     .object({
     id: zod_1.z.string(),
     currency: zod_1.z.literal('USD'),
-    gross_minor_units: zod_1.z.number().int(),
+    gross_minor_units: primitives_1.amount,
     amount_base_units: zod_1.z.string(),
     usd_per_fair: zod_1.z.string(),
     source: zod_1.z.string(),

package/dist/cjs/resources/tax/calculations.js

@@ -6,7 +6,8 @@ const objects_1 = require("../../common/objects");
 const primitives_1 = require("../../common/primitives");
 const route_1 = require("../../route");
 const tax_1 = require("../../vocabulary/tax");
-const shared_1 = require("./shared");
+const shared_1 = require("../catalog/shared");
+const shared_2 = require("./shared");
 /**
  * A tax calculation (`taxcalc_…`, ADR 0011): a frozen answer. Peable decides
  * whether a registration covers the customer's evidenced location and asks
@@ -15,14 +16,14 @@ const shared_1 = require("./shared");
  */
 exports.taxBreakdownEntrySchema = (0, objects_1.defineComponent)('TaxBreakdownEntry', zod_1.z
     .object({
-    country: shared_1.taxCountry,
-    state: shared_1.taxState,
+    country: shared_2.taxCountry,
+    state: shared_2.taxState,
     level: primitives_1.nullableString.describe('The jurisdiction level (`country`, `state`, …).'),
     display_name: primitives_1.nullableString,
     tax_type: primitives_1.nullableString.describe('`vat`, `sales_tax`, …; `null` when no tax is imposed.'),
     rate_percentage: primitives_1.nullableString.describe('Decimal string, e.g. `"20.0"`; `null` when no tax is imposed.'),
-    taxable_amount: shared_1.taxMinorAmount,
-    amount: shared_1.taxMinorAmount,
+    taxable_amount: primitives_1.signedAmount,
+    amount: primitives_1.signedAmount,
     inclusive: zod_1.z.boolean(),
     taxability_reason: zod_1.z
         .string()
@@ -35,9 +36,9 @@ exports.taxCalculationLineItemSchema = (0, objects_1.defineComponent)('TaxCalcul
     quantity: zod_1.z.number().int(),
     tax_code: zod_1.z.string(),
     tax_behavior: zod_1.z.enum(tax_1.TAX_BEHAVIORS),
-    amount: shared_1.taxMinorAmount.describe('As given: includes tax when inclusive.'),
-    amount_tax: shared_1.taxMinorAmount,
-    amount_net: shared_1.taxMinorAmount.describe('Excluding tax.'),
+    amount: primitives_1.signedAmount.describe('As given: includes tax when inclusive.'),
+    amount_tax: primitives_1.signedAmount,
+    amount_net: primitives_1.signedAmount.describe('Excluding tax.'),
     breakdown: zod_1.z.array(exports.taxBreakdownEntrySchema),
 })
     .strict());
@@ -53,12 +54,12 @@ exports.taxCalculationSchema = (0, objects_1.defineObject)('tax.calculation', 'T
     provider: primitives_1.nullableString,
     provider_calculation_ref: primitives_1.nullableString,
     customer_location_evidence_id: zod_1.z.string().describe('`taxloc_…`.'),
-    country: shared_1.taxCountry,
-    state: shared_1.taxState,
-    amount_total: shared_1.taxMinorAmount.describe('What the customer pays.'),
-    amount_net: shared_1.taxMinorAmount,
-    tax_amount_exclusive: shared_1.taxMinorAmount,
-    tax_amount_inclusive: shared_1.taxMinorAmount,
+    country: shared_2.taxCountry,
+    state: shared_2.taxState,
+    amount_total: primitives_1.amount.describe('What the customer pays.'),
+    amount_net: primitives_1.amount,
+    tax_amount_exclusive: primitives_1.amount,
+    tax_amount_inclusive: primitives_1.amount,
     line_items: zod_1.z.array(exports.taxCalculationLineItemSchema),
     tax_date: primitives_1.unixSeconds,
     created: primitives_1.unixSeconds,
@@ -78,19 +79,19 @@ exports.taxCalculationSchema = (0, objects_1.defineObject)('tax.calculation', 'T
             customer_location_evidence_id: 'taxloc_0193b8f2c1a87d3e9f4a',
             country: 'DE',
             state: null,
-            amount_total: 1190,
-            amount_net: 1000,
-            tax_amount_exclusive: 190,
-            tax_amount_inclusive: 0,
+            amount_total: '1190',
+            amount_net: '1000',
+            tax_amount_exclusive: '190',
+            tax_amount_inclusive: '0',
             line_items: [
                 {
                     reference: 'plan_pro_monthly',
                     quantity: 1,
                     tax_code: 'txcd_10103001',
                     tax_behavior: 'exclusive',
-                    amount: 1000,
-                    amount_tax: 190,
-                    amount_net: 1000,
+                    amount: '1000',
+                    amount_tax: '190',
+                    amount_net: '1000',
                     breakdown: [
                         {
                             country: 'DE',
@@ -99,8 +100,8 @@ exports.taxCalculationSchema = (0, objects_1.defineObject)('tax.calculation', 'T
                             display_name: 'VAT',
                             tax_type: 'vat',
                             rate_percentage: '19.0',
-                            taxable_amount: 1000,
-                            amount: 190,
+                            taxable_amount: '1000',
+                            amount: '190',
                             inclusive: false,
                             taxability_reason: 'standard_rated',
                         },
@@ -114,15 +115,17 @@ exports.taxCalculationSchema = (0, objects_1.defineObject)('tax.calculation', 'T
         },
     ],
 });
+/**
+ * The largest line a tax provider is asked to price: the provider's own API
+ * counts amounts in integers that stay exact in a JS number (Stripe Tax).
+ */
+const TAX_LINE_AMOUNT_MAX = BigInt(Number.MAX_SAFE_INTEGER);
 exports.taxLineItemParams = zod_1.z
     .object({
     reference: zod_1.z.string().min(1).max(200),
-    amount: zod_1.z
-        .number()
-        .int()
-        .nonnegative()
-        .safe()
-        .describe('Unit amount × quantity, minor units. Includes tax when inclusive.'),
+    amount: shared_1.baseUnitAmountParam
+        .refine((value) => BigInt(value) <= TAX_LINE_AMOUNT_MAX, 'exceeds the largest amount a tax provider prices')
+        .describe('Unit amount × quantity, base units. Includes tax when inclusive.'),
     quantity: zod_1.z.number().int().positive().max(1000000).optional(),
     tax_code: zod_1.z
         .string()
@@ -137,7 +140,7 @@ exports.taxLineItemParams = zod_1.z
 exports.createTaxCalculationParams = zod_1.z
     .object({
     currency: zod_1.z.string().regex(/^[A-Za-z]{3}$/),
-    customer_location_evidence_id: shared_1.taxReferenceParam.describe('Sufficient, unexpired evidence (`taxloc_…`).'),
+    customer_location_evidence_id: shared_2.taxReferenceParam.describe('Sufficient, unexpired evidence (`taxloc_…`).'),
     line_items: zod_1.z
         .array(exports.taxLineItemParams)
         .min(1)

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

@@ -26,8 +26,8 @@ exports.taxReportRowSchema = (0, objects_1.defineComponent)('TaxReportRow', zod_
     currency: zod_1.z.string().describe('Uppercase ISO 4217.'),
     transactions: zod_1.z.number().int().nonnegative(),
     reversals: zod_1.z.number().int().nonnegative().describe('Reversals netted into this row.'),
-    taxable_amount: shared_1.taxMinorAmount,
-    tax_amount: shared_1.taxMinorAmount,
+    taxable_amount: primitives_1.signedAmount,
+    tax_amount: primitives_1.signedAmount,
 })
     .strict());
 exports.taxReportSchema = (0, objects_1.defineObject)('tax.report', 'TaxReport', zod_1.z
@@ -55,8 +55,8 @@ exports.taxReportSchema = (0, objects_1.defineObject)('tax.report', 'TaxReport',
                     currency: 'EUR',
                     transactions: 42,
                     reversals: 1,
-                    taxable_amount: 41000,
-                    tax_amount: 7790,
+                    taxable_amount: '41000',
+                    tax_amount: '7790',
                 },
             ],
         },

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

@@ -1,17 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.complianceIdParam = exports.complianceTextParam = exports.complianceStateParam = exports.complianceCountryParam = exports.taxFacts = exports.taxCoverageLimitSchema = exports.taxRuleSourceSchema = exports.taxInstantParam = exports.taxReferenceParam = exports.taxMinorAmount = exports.taxState = exports.taxCountry = void 0;
+exports.complianceIdParam = exports.complianceTextParam = exports.complianceStateParam = exports.complianceCountryParam = exports.taxFacts = exports.taxCoverageLimitSchema = exports.taxRuleSourceSchema = exports.taxInstantParam = exports.taxReferenceParam = exports.taxState = exports.taxCountry = void 0;
 const zod_1 = require("zod");
 const objects_1 = require("../../common/objects");
 const params_1 = require("../../common/params");
 /**
  * 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.
+ * Every tax amount — a calculation's, a transaction's, a reversal's, a report
+ * row's, a compliance measure's — is a base-unit integer STRING of its
+ * `currency`, as ADR 0014 D1 has it for every amount on the wire: `amount`
+ * where it cannot be negative, `signedAmount` where a reversal makes it so
+ * (a line item and its breakdown carry a reversal's negative share, and a
+ * report row nets them in).
  */
 /** ISO 3166-1 alpha-2, as returned. */
 exports.taxCountry = zod_1.z.string().describe('ISO 3166-1 alpha-2.');
@@ -20,11 +21,6 @@ exports.taxState = zod_1.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. */
-exports.taxMinorAmount = zod_1.z
-    .number()
-    .int()
-    .describe('Minor units of `currency` (cents), as an integer.');
 /** A Peable-side reference: a product, a customer, a refund. */
 exports.taxReferenceParam = zod_1.z
     .string()

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

@@ -8,8 +8,8 @@ const params_1 = require("../../common/params");
 const primitives_1 = require("../../common/primitives");
 const route_1 = require("../../route");
 const tax_1 = require("../../vocabulary/tax");
+const shared_1 = require("../catalog/shared");
 const calculations_1 = require("./calculations");
-const shared_1 = require("./shared");
 /**
  * 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
@@ -24,9 +24,9 @@ const shared_1 = require("./shared");
  */
 exports.taxTransactionReversalSchema = (0, objects_1.defineComponent)('TaxTransactionReversal', zod_1.z
     .object({
-    amount_total: shared_1.taxMinorAmount,
-    amount_net: shared_1.taxMinorAmount,
-    tax_amount: shared_1.taxMinorAmount,
+    amount_total: primitives_1.signedAmount,
+    amount_net: primitives_1.signedAmount,
+    tax_amount: primitives_1.signedAmount,
     line_items: zod_1.z.array(calculations_1.taxCalculationLineItemSchema),
 })
     .strict());
@@ -59,13 +59,10 @@ exports.createTaxReversalParams = zod_1.z
         .max(200)
         .regex(/^[A-Za-z0-9_.:-]+$/)
         .describe("The refund's own reference; a repeated reference returns the same reversal."),
-    amount: zod_1.z
-        .number()
-        .int()
-        .positive()
-        .safe()
+    amount: shared_1.baseUnitAmountParam
+        .refine((value) => value !== '0', 'must be positive')
         .optional()
-        .describe('Gross minor units refunded (what the payer got back). Omitted: everything not yet reversed.'),
+        .describe('Gross base units refunded (what the payer got back). Omitted: everything not yet reversed.'),
 })
     .strict();
 exports.taxTransactionRoutes = [

package/dist/cjs/vocabulary/money.js

@@ -16,7 +16,7 @@ exports.isBaseUnitString = isBaseUnitString;
  * chain rail, and on the card rail the fiat set the provider settles for the
  * payment methods Orbit offers (cards, wallets, SEPA Debit, iDEAL, Bancontact,
  * EPS). A local method narrows it further per payment
- * (`PAYMENT_METHOD_CURRENCIES` in `paymentMethodConfiguration.ts`).
+ * (`PAYMENT_METHOD_CURRENCIES` in `paymentMethodConfigurations.ts`).
  *
  * A closed set, and the database mirrors it as a CHECK
  * (`db/schema/valueSets.ts`). ADR 0001 D4: the scale of an amount is a property

package/dist/cjs/vocabulary/paymentMethodConfigurations.js

@@ -1,7 +1,8 @@
 "use strict";
 // Payment method breadth on the card rail (`pmc_…`, `pmd_…`). Zod-free.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PAYMENT_METHOD_UNAVAILABLE_REASONS = exports.PAYMENT_METHOD_CONFIGURATION_TYPES = void 0;
+exports.PAYMENT_METHOD_CURRENCIES = exports.PAYMENT_METHOD_UNAVAILABLE_REASONS = exports.PAYMENT_METHOD_CONFIGURATION_TYPES = void 0;
+const money_1 = require("./money");
 /**
  * The methods a configuration can turn on.
  *
@@ -34,3 +35,18 @@ exports.PAYMENT_METHOD_UNAVAILABLE_REASONS = [
     'provider_unsupported',
     'requires_card',
 ];
+/**
+ * The currencies each method can take a payment in. A method is offered on a
+ * payment only when its currency is listed — so iDEAL never appears on a USD
+ * payment, and a payer is never shown a method that would fail.
+ */
+exports.PAYMENT_METHOD_CURRENCIES = Object.freeze({
+    card: money_1.FIAT_CURRENCY_CODES,
+    apple_pay: money_1.FIAT_CURRENCY_CODES,
+    google_pay: money_1.FIAT_CURRENCY_CODES,
+    sepa_debit: ['EUR'],
+    ideal: ['EUR'],
+    bancontact: ['EUR'],
+    eps: ['EUR'],
+    bizum: ['EUR'],
+});

package/dist/esm/resources/catalog/billing.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { defineComponent } from '../../common/objects.js';
+import { amount } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
 import { BILLING_RAIL_RENEWALS, BILLING_RAIL_SETTLEMENTS, BILLING_SUBSCRIPTION_STATUSES, } from '../../vocabulary/catalog.js';
 /**
@@ -47,8 +48,6 @@ export const billingReturnUrl = z
 }, 'An HTTPS return URL without credentials is required');
 /** An instant in signed billing evidence: integer Unix seconds that stay a safe integer. */
 export const billingInstant = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
-/** A whole number of minor units (cents) in signed billing evidence. */
-const minorUnits = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
 /** A billing customer reference (`cus_…`). */
 export const billingCustomerRef = z
     .string()
@@ -82,7 +81,7 @@ export const billingRailOfferSchema = defineComponent('BillingRailOffer', z
     plan_id: z.string(),
     interval: billingInterval,
     currency: z.string(),
-    gross_minor_units: z.number().int(),
+    gross_minor_units: amount,
     tax_treatment: taxTreatment,
 })
     .strict());
@@ -131,10 +130,10 @@ export const createBillingTaxQuoteParams = z
     customer_location_evidence_id: billingReference.describe('A `tax.location_evidence` id (`taxloc_…`) recorded for this `store_id`.'),
 })
     .strict();
-/** A signed, immutable, single-use Peable Tax quote (schema version 2). */
+/** A signed, immutable, single-use Peable Tax quote (schema version 3). */
 export const billingTaxQuoteSchema = defineComponent('BillingTaxQuote', z
     .object({
-    schema_version: z.literal(2),
+    schema_version: z.literal(3),
     source: z
         .object({
         merchant_id: billingReference,
@@ -149,9 +148,9 @@ export const billingTaxQuoteSchema = defineComponent('BillingTaxQuote', z
         .object({
         id: billingReference,
         currency: z.string().regex(/^[A-Z]{3}$/),
-        gross_minor_units: minorUnits,
-        net_minor_units: minorUnits,
-        tax_minor_units: minorUnits,
+        gross_minor_units: amount,
+        net_minor_units: amount,
+        tax_minor_units: amount,
         tax_treatment: taxTreatment,
         seller_id: billingReference,
         invoice_issuer_id: billingReference,
@@ -220,7 +219,7 @@ export const billingEmbeddedCheckoutActionSchema = defineComponent('BillingEmbed
     session_id: z.string(),
     client_secret: z.string(),
     publishable_key: z.string(),
-    amount_minor_units: z.number().int(),
+    amount_minor_units: amount,
     currency: z.string(),
 })
     .strict());
@@ -350,10 +349,9 @@ export const billingPaidInvoiceSchema = defineComponent('BillingPaidInvoice', z
     plan_id: z.string(),
     livemode: z.boolean(),
     currency: z.string(),
-    amount_paid: z.string(),
-    net_amount: z.string().nullable(),
-    tax_amount: z
-        .string()
+    amount_paid: amount,
+    net_amount: amount.nullable(),
+    tax_amount: amount
         .nullable()
         .describe('A provider observation, not a tax quote or seller configuration.'),
     period_start: z.number().int(),
@@ -365,7 +363,7 @@ export const billingPaidInvoiceSchema = defineComponent('BillingPaidInvoice', z
 export const billingInvoiceStateSchema = defineComponent('BillingInvoiceState', billingPaidInvoiceSchema
     .extend({
     charge_id: z.string(),
-    amount_refunded: z.string(),
+    amount_refunded: amount,
     state: z.enum(['paid', 'fully_refunded', 'partially_refunded']),
 })
     .strict());
@@ -377,8 +375,8 @@ export const billingInvoiceTaxLineSchema = defineComponent('BillingInvoiceTaxLin
     state: z.string().nullable(),
     tax_type: z.string().nullable(),
     rate_percentage: z.string().nullable(),
-    taxable_minor_units: minorUnits,
-    tax_minor_units: minorUnits,
+    taxable_minor_units: amount,
+    tax_minor_units: amount,
     inclusive: z.boolean(),
     taxability_reason: z.string().min(1),
 })
@@ -406,10 +404,10 @@ export const billingFinalInvoiceSchema = defineComponent('BillingFinalInvoice',
     .object({
     platform: z.literal('peable'),
     currency: z.string().regex(/^[A-Z]{3}$/),
-    gross_minor_units: minorUnits,
-    net_minor_units: minorUnits,
-    tax_minor_units: minorUnits,
-    merchant_fee_minor_units: minorUnits,
+    gross_minor_units: amount,
+    net_minor_units: amount,
+    tax_minor_units: amount,
+    merchant_fee_minor_units: amount,
     tax_treatment: taxTreatment,
     seller_id: billingReference,
     invoice_issuer_id: billingReference,
@@ -452,10 +450,10 @@ export const billingFinalInvoiceSchema = defineComponent('BillingFinalInvoice',
         .describe('Present only when asked for (`include=tax_lines`): the frozen Peable Tax lines behind `tax_minor_units`, covered by the same signature.'),
 })
     .strict());
-/** A signed final invoice authority (schema version 2). Verify it against the pinned keys. */
+/** A signed final invoice authority (schema version 3). Verify it against the pinned keys. */
 export const billingFinalInvoiceAuthoritySchema = defineComponent('BillingFinalInvoiceAuthority', z
     .object({
-    schema_version: z.literal(2),
+    schema_version: z.literal(3),
     source: billingInvoiceAuthoritySourceSchema,
     invoice: billingFinalInvoiceSchema,
     method: z.enum(['card', 'faircoin']),
@@ -523,7 +521,7 @@ export const billingFaircoinFxQuoteSchema = defineComponent('BillingFaircoinFxQu
     .object({
     id: z.string(),
     currency: z.literal('USD'),
-    gross_minor_units: z.number().int(),
+    gross_minor_units: amount,
     amount_base_units: z.string(),
     usd_per_fair: z.string(),
     source: z.string(),

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

@@ -1,9 +1,10 @@
 import { z } from 'zod';
 import { defineComponent, defineObject } from '../../common/objects.js';
-import { livemode, nullableString, unixSeconds } from '../../common/primitives.js';
+import { amount, livemode, nullableString, signedAmount, unixSeconds, } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
 import { TAX_BEHAVIORS, TAX_COLLECTIONS } from '../../vocabulary/tax.js';
-import { taxCountry, taxMinorAmount, taxReferenceParam, taxState } from './shared.js';
+import { baseUnitAmountParam } from '../catalog/shared.js';
+import { taxCountry, taxReferenceParam, taxState } from './shared.js';
 /**
  * A tax calculation (`taxcalc_…`, ADR 0011): a frozen answer. Peable decides
  * whether a registration covers the customer's evidenced location and asks
@@ -18,8 +19,8 @@ export const taxBreakdownEntrySchema = defineComponent('TaxBreakdownEntry', z
     display_name: nullableString,
     tax_type: nullableString.describe('`vat`, `sales_tax`, …; `null` when no tax is imposed.'),
     rate_percentage: nullableString.describe('Decimal string, e.g. `"20.0"`; `null` when no tax is imposed.'),
-    taxable_amount: taxMinorAmount,
-    amount: taxMinorAmount,
+    taxable_amount: signedAmount,
+    amount: signedAmount,
     inclusive: z.boolean(),
     taxability_reason: z
         .string()
@@ -32,9 +33,9 @@ export const taxCalculationLineItemSchema = defineComponent('TaxCalculationLineI
     quantity: z.number().int(),
     tax_code: z.string(),
     tax_behavior: z.enum(TAX_BEHAVIORS),
-    amount: taxMinorAmount.describe('As given: includes tax when inclusive.'),
-    amount_tax: taxMinorAmount,
-    amount_net: taxMinorAmount.describe('Excluding tax.'),
+    amount: signedAmount.describe('As given: includes tax when inclusive.'),
+    amount_tax: signedAmount,
+    amount_net: signedAmount.describe('Excluding tax.'),
     breakdown: z.array(taxBreakdownEntrySchema),
 })
     .strict());
@@ -52,10 +53,10 @@ export const taxCalculationSchema = defineObject('tax.calculation', 'TaxCalculat
     customer_location_evidence_id: z.string().describe('`taxloc_…`.'),
     country: taxCountry,
     state: taxState,
-    amount_total: taxMinorAmount.describe('What the customer pays.'),
-    amount_net: taxMinorAmount,
-    tax_amount_exclusive: taxMinorAmount,
-    tax_amount_inclusive: taxMinorAmount,
+    amount_total: amount.describe('What the customer pays.'),
+    amount_net: amount,
+    tax_amount_exclusive: amount,
+    tax_amount_inclusive: amount,
     line_items: z.array(taxCalculationLineItemSchema),
     tax_date: unixSeconds,
     created: unixSeconds,
@@ -75,19 +76,19 @@ export const taxCalculationSchema = defineObject('tax.calculation', 'TaxCalculat
             customer_location_evidence_id: 'taxloc_0193b8f2c1a87d3e9f4a',
             country: 'DE',
             state: null,
-            amount_total: 1190,
-            amount_net: 1000,
-            tax_amount_exclusive: 190,
-            tax_amount_inclusive: 0,
+            amount_total: '1190',
+            amount_net: '1000',
+            tax_amount_exclusive: '190',
+            tax_amount_inclusive: '0',
             line_items: [
                 {
                     reference: 'plan_pro_monthly',
                     quantity: 1,
                     tax_code: 'txcd_10103001',
                     tax_behavior: 'exclusive',
-                    amount: 1000,
-                    amount_tax: 190,
-                    amount_net: 1000,
+                    amount: '1000',
+                    amount_tax: '190',
+                    amount_net: '1000',
                     breakdown: [
                         {
                             country: 'DE',
@@ -96,8 +97,8 @@ export const taxCalculationSchema = defineObject('tax.calculation', 'TaxCalculat
                             display_name: 'VAT',
                             tax_type: 'vat',
                             rate_percentage: '19.0',
-                            taxable_amount: 1000,
-                            amount: 190,
+                            taxable_amount: '1000',
+                            amount: '190',
                             inclusive: false,
                             taxability_reason: 'standard_rated',
                         },
@@ -111,15 +112,17 @@ export const taxCalculationSchema = defineObject('tax.calculation', 'TaxCalculat
         },
     ],
 });
+/**
+ * The largest line a tax provider is asked to price: the provider's own API
+ * counts amounts in integers that stay exact in a JS number (Stripe Tax).
+ */
+const TAX_LINE_AMOUNT_MAX = BigInt(Number.MAX_SAFE_INTEGER);
 export const taxLineItemParams = z
     .object({
     reference: z.string().min(1).max(200),
-    amount: z
-        .number()
-        .int()
-        .nonnegative()
-        .safe()
-        .describe('Unit amount × quantity, minor units. Includes tax when inclusive.'),
+    amount: baseUnitAmountParam
+        .refine((value) => BigInt(value) <= TAX_LINE_AMOUNT_MAX, 'exceeds the largest amount a tax provider prices')
+        .describe('Unit amount × quantity, base units. Includes tax when inclusive.'),
     quantity: z.number().int().positive().max(1000000).optional(),
     tax_code: z
         .string()