@peable.to/contracts 1.2.0 → 3.0.0

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

@@ -1,10 +1,10 @@
 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 { nullableString, signedAmount, 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';
+import { taxCountry, 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
@@ -23,8 +23,8 @@ export const taxReportRowSchema = defineComponent('TaxReportRow', z
     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,
+    taxable_amount: signedAmount,
+    tax_amount: signedAmount,
 })
     .strict());
 export const taxReportSchema = defineObject('tax.report', 'TaxReport', z
@@ -52,8 +52,8 @@ export const taxReportSchema = defineObject('tax.report', 'TaxReport', z
                     currency: 'EUR',
                     transactions: 42,
                     reversals: 1,
-                    taxable_amount: 41000,
-                    tax_amount: 7790,
+                    taxable_amount: '41000',
+                    tax_amount: '7790',
                 },
             ],
         },

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

@@ -4,11 +4,12 @@ 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.
+ * 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. */
 export const taxCountry = z.string().describe('ISO 3166-1 alpha-2.');
@@ -17,11 +18,6 @@ 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()

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

@@ -2,11 +2,11 @@ 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 { nullableString, signedAmount, unixSeconds } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
 import { TAX_TRANSACTION_TYPES } from '../../vocabulary/tax.js';
+import { baseUnitAmountParam } from '../catalog/shared.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
@@ -21,9 +21,9 @@ import { taxMinorAmount } from './shared.js';
  */
 export const taxTransactionReversalSchema = defineComponent('TaxTransactionReversal', z
     .object({
-    amount_total: taxMinorAmount,
-    amount_net: taxMinorAmount,
-    tax_amount: taxMinorAmount,
+    amount_total: signedAmount,
+    amount_net: signedAmount,
+    tax_amount: signedAmount,
     line_items: z.array(taxCalculationLineItemSchema),
 })
     .strict());
@@ -56,13 +56,10 @@ export const createTaxReversalParams = z
         .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()
+    amount: 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();
 export const taxTransactionRoutes = [

package/dist/esm/vocabulary/catalog.js

@@ -87,20 +87,4 @@ export const BILLING_SETTINGS_LIMITS = Object.freeze({
 /** How a meter combines a period's events into the quantity billed. */
 export const METER_AGGREGATIONS = ['sum', 'count', 'last'];
 export const METER_STATUSES = ['active', 'inactive'];
-// ---- Recurring billing transport (`/v1/billing/*`) ---------------------------
-/** A provider subscription's status, as the recurring transport observes it. */
-export const BILLING_SUBSCRIPTION_STATUSES = [
-    'incomplete',
-    'incomplete_expired',
-    'trialing',
-    'active',
-    'past_due',
-    'canceled',
-    'unpaid',
-    'paused',
-];
-/** `fiat` (Stripe and any further provider) or `faircoin` (native, to the merchant's watch-only wallet). */
-export const BILLING_RAIL_SETTLEMENTS = ['fiat', 'faircoin'];
-/** `automatic`: the provider charges each period. `payer_initiated`: each period is an explicit payment. */
-export const BILLING_RAIL_RENEWALS = ['automatic', 'payer_initiated'];
 // Product tax codes are Peable Tax's vocabulary: `vocabulary/tax.ts` (`TAX_CODES`).

package/dist/esm/vocabulary/errors.js

@@ -42,19 +42,15 @@ export const ERROR_CODE_DESCRIPTIONS = {
     account_invalid: 'The `Peable-Account` header names no connected account of this platform.',
     account_missing: 'The merchant has no account object yet.',
     amount_not_representable: 'The amount does not fit the currency or the rail.',
-    billing_not_enabled: 'Billing is not enabled for this merchant.',
-    billing_provider_unavailable: 'The billing provider could not be reached; retry.',
     domain_taken: 'The domain is already registered by another merchant.',
     file_too_large: 'The uploaded file is larger than its purpose allows.',
     file_unavailable: 'The file exists but its contents cannot be served right now.',
     idempotency_error: 'The `Idempotency-Key` was used with a different request, or its first request is still running.',
     idempotency_key_invalid: 'The `Idempotency-Key` header is not a valid key.',
     insufficient_scope: 'The credential is valid but was not granted the Oxy scope this route requires (`payments:read`, `payments:write`, …); `message` names it.',
-    invalid_billing_request: 'The billing request is not valid for this subscription or offer.',
     keyless_recipient: 'The recipient has no receive key, so no address can be derived for them.',
     link_not_found: 'The link does not exist or is no longer active.',
     live_payments_gated: 'Live payments are not enabled for this application yet.',
-    local_test_request_required: 'This test helper only answers a local test request.',
     parameter_invalid: 'A parameter is invalid; `param` names it.',
     parameter_missing: 'A required parameter is missing; `param` names it.',
     parameter_unknown: 'The request carries a parameter this route does not accept; `param` names it.',
@@ -83,10 +79,7 @@ export const ERROR_CODE_DESCRIPTIONS = {
     customer_location_invalid: "The tax provider could not use the customer's location.",
     dispute_already_submitted: 'Evidence for this dispute has already been submitted; it is one shot.',
     dispute_not_answerable: 'The dispute is in a status that no longer accepts evidence.',
-    idempotency_conflict: 'The same operation key was used for a different billing request.',
-    identity_conflict: 'The billing identity already belongs to another customer or subscription.',
     in_progress: 'The same operation is still running; retry with the same key.',
-    invalid_provider_response: 'The provider answered with something Peable cannot trust; the operation was not applied.',
     invalid_registration: 'The tax registration is not valid.',
     invalid_registration_declaration: 'The tax registration declaration is not valid.',
     invalid_tax_code: 'The tax code does not exist.',
@@ -101,12 +94,9 @@ export const ERROR_CODE_DESCRIPTIONS = {
     product_in_use: 'The product is referenced by a subscription or a link.',
     promotion_code_invalid: 'The promotion code does not exist, is inactive or does not apply.',
     promotion_code_taken: 'Another active promotion code already uses this `code`.',
-    provider_unavailable: 'The payment provider could not be reached; retry.',
     rail_unavailable: 'The payment rail this request needs is not available.',
-    reconciliation_required: 'The billing operation has an unknown outcome at the provider and is being reconciled.',
     registration_immutable: 'An approved or ended tax registration cannot be deleted or changed this way; end it instead.',
     resource_already_exists: 'An object with this identity already exists.',
-    result_expired: 'The stored result of this operation has expired.',
     review_item_not_open: 'The review item is already resolved or dismissed.',
     rule_set_version_unavailable: 'The tax rule set version is not available.',
     subscription_line_invalid: 'A subscription line item is not valid for Checkout.',
@@ -114,9 +104,6 @@ export const ERROR_CODE_DESCRIPTIONS = {
     tax_calculation_unavailable: 'Tax could not be calculated; a covered sale fails closed.',
     tax_provider_registration_mismatch: "The provider's registrations disagree with the ones Peable has approved.",
     tax_settings_not_active: 'Tax settings are not active for this merchant.',
-    local_test_unavailable: 'The local test checkout is not available.',
-    local_test_configuration_unavailable: 'The local test checkout has no provider configuration.',
-    local_test_subscription_unavailable: 'The local test subscription cannot be read.',
     rail_mismatch: 'The operation does not apply to the rail this payment uses.',
     checkout_session_changed: 'The Checkout Session changed while this request ran (a price, a discount, its tax); read it again and retry.',
     checkout_session_locked: 'The Checkout Session is being confirmed and cannot change.',

package/dist/esm/vocabulary/events.js

@@ -58,7 +58,6 @@ export const WEBHOOK_EVENT_OBJECTS = {
     'setup_intent.succeeded': 'setup_intent',
     'setup_intent.setup_failed': 'setup_intent',
     'setup_intent.canceled': 'setup_intent',
-    'billing.observation.updated': 'billing_observation',
     'connected_account.updated': 'connected_account',
     'product.created': 'product',
     'product.updated': 'product',