@peable.to/contracts 2.0.0 → 3.1.0

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

@@ -17,7 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.catalogRoutes = exports.queryIdList = exports.queryFlag = exports.baseUnitAmountParam = void 0;
 // Contracts of this group: one module per resource, re-exported here, and
 // their routes concatenated into `catalogRoutes`.
-const billing_1 = require("./billing");
 const billingSettings_1 = require("./billingSettings");
 const coupons_1 = require("./coupons");
 const entitlements_1 = require("./entitlements");
@@ -26,7 +25,6 @@ const prices_1 = require("./prices");
 const products_1 = require("./products");
 const promotionCodes_1 = require("./promotionCodes");
 const testClocks_1 = require("./testClocks");
-__exportStar(require("./billing"), exports);
 __exportStar(require("./billingSettings"), exports);
 __exportStar(require("./coupons"), exports);
 __exportStar(require("./entitlements"), exports);
@@ -42,8 +40,7 @@ Object.defineProperty(exports, "queryFlag", { enumerable: true, get: function ()
 Object.defineProperty(exports, "queryIdList", { enumerable: true, get: function () { return shared_1.queryIdList; } });
 /**
  * The catalog (products, prices, coupons, promotion codes), entitlements, the
- * billing engine's platform objects (test clocks, billing settings, meters)
- * and the recurring billing transport (`/v1/billing/*`).
+ * billing engine's platform objects (test clocks, billing settings, meters).
  */
 exports.catalogRoutes = [
     ...products_1.productRoutes,
@@ -54,5 +51,4 @@ exports.catalogRoutes = [
     ...testClocks_1.testClockRoutes,
     ...billingSettings_1.billingSettingsRoutes,
     ...meters_1.meterRoutes,
-    ...billing_1.billingRoutes,
 ];

package/dist/cjs/resources/checkout/checkoutSessions.js

@@ -4,7 +4,6 @@ exports.checkoutSessionRoutes = exports.expireCheckoutSessionTestHelperParams =
 const zod_1 = require("zod");
 const catalog_1 = require("../../vocabulary/catalog");
 const payments_1 = require("../../vocabulary/payments");
-const billing_1 = require("../catalog/billing");
 const objects_1 = require("../../common/objects");
 const envelopes_1 = require("../../common/envelopes");
 const objects_2 = require("../../common/objects");
@@ -183,9 +182,6 @@ exports.checkoutSessionPublicSchema = (0, objects_2.defineComponent)('CheckoutSe
         .string()
         .nullable()
         .describe("The card provider's PUBLIC key for this session's mode, so the payment fields can mount before the payment exists. `null` on FairCoin."),
-    billing_quote: billing_1.billingFaircoinFxQuoteSchema
-        .optional()
-        .describe('FairCoin billing invoices: the frozen USD price and FAIR settlement quote.'),
 })
     .strict());
 // ---- Merchant create/update ---------------------------------------------------

package/dist/cjs/resources/events/events.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.eventRoutes = exports.WEBHOOK_EVENT_DESCRIPTIONS = exports.streamEventsQuery = exports.retrieveEventQuery = exports.listEventsQuery = exports.listEventsFilters = exports.eventSchema = exports.eventRequestSchema = exports.billingObservationSchema = void 0;
+exports.eventRoutes = exports.WEBHOOK_EVENT_DESCRIPTIONS = exports.streamEventsQuery = exports.retrieveEventQuery = exports.listEventsQuery = exports.listEventsFilters = exports.eventSchema = exports.eventRequestSchema = void 0;
 exports.eventSchemaOf = eventSchemaOf;
 const zod_1 = require("zod");
 const envelopes_1 = require("../../common/envelopes");
@@ -16,36 +16,6 @@ const events_1 = require("../../vocabulary/events");
  * every matching webhook endpoint: a delivery's body and `GET /v1/events/:id`
  * are byte for byte the same object.
  */
-/**
- * The payload of `billing.observation.updated`: a wake-up, never paid or grant
- * authority. Re-read the owner-bound resource it names.
- */
-exports.billingObservationSchema = (0, objects_1.defineObject)('billing_observation', 'BillingObservation', zod_1.z
-    .object({
-    object: zod_1.z.literal('billing_observation'),
-    livemode: primitives_1.livemode.describe('The mode of the billing cohort observed (ADR 0017).'),
-    resource_kind: zod_1.z.enum(['subscription', 'invoice']),
-    resource_id: zod_1.z.string().describe('The provider subscription or invoice observed.'),
-    subscription_id: zod_1.z
-        .string()
-        .optional()
-        .describe('Owner-scoped wake-up hint only; re-read the subscription before resolving a payer.'),
-    revision: zod_1.z.number().int().describe('The observation revision; later revisions are newer.'),
-    observed_at: primitives_1.unixSeconds,
-})
-    .strict(), {
-    examples: [
-        {
-            object: 'billing_observation',
-            livemode: false,
-            resource_kind: 'subscription',
-            resource_id: 'sub_1Q2w3E4r5T6y7U8i',
-            subscription_id: 'sub_1Q2w3E4r5T6y7U8i',
-            revision: 3,
-            observed_at: 1793750400,
-        },
-    ],
-});
 /**
  * What caused an event, when an API request did (Stripe's `event.request`).
  * Both `null` for an event caused by something else — the chain watcher, the
@@ -242,7 +212,6 @@ exports.WEBHOOK_EVENT_DESCRIPTIONS = {
     'setup_intent.succeeded': 'A SetupIntent succeeded: its PaymentMethod is saved.',
     'setup_intent.setup_failed': 'A SetupIntent attempt failed.',
     'setup_intent.canceled': 'A SetupIntent was canceled.',
-    'billing.observation.updated': 'A recurring billing resource was observed to change. A wake-up only: re-read the resource.',
     'connected_account.updated': "A seller's connected account changed — its readiness, in practice.",
     'product.created': 'A Product was created.',
     'product.updated': 'A Product was updated; `previous_attributes` names what moved.',

package/dist/cjs/resources/events/webhookDeliveries.js

@@ -26,7 +26,7 @@ exports.webhookDeliverySchema = (0, objects_1.defineObject)('webhook_delivery',
     delivered: zod_1.z.boolean(),
     last_status: zod_1.z
         .enum(events_1.WEBHOOK_DELIVERY_STATUSES)
-        .describe('`pending`: will be attempted (`next_attempt_at`). `delivered`: terminal success. `failed`: the endpoint refused it (a 4xx, a blocked address) or was disabled first — never retried. `dead`: every attempt failed transiently for three days; it can be redelivered.'),
+        .describe('`pending`: will be attempted (`next_attempt_at`). `delivered`: terminal success. `failed`: the endpoint refused it (a 4xx, a blocked address), was disabled first, or its stored url breaks the registration rules — never retried. `dead`: every attempt failed transiently for three days; it can be redelivered.'),
     last_error: zod_1.z
         .string()
         .optional()

package/dist/cjs/resources/events/webhookEndpoints.js

@@ -29,7 +29,7 @@ const endpointShape = {
     disabled_reason: zod_1.z
         .enum(events_1.WEBHOOK_ENDPOINT_DISABLED_REASONS)
         .nullable()
-        .describe('`null` exactly when `status` is `enabled`. `delivery_failures`: every delivery failed for three days straight.'),
+        .describe('`null` exactly when `status` is `enabled`. `delivery_failures`: every delivery failed for three days straight. `url_refused`: the stored `url` breaks the registration rules, judged before every delivery; re-enable it with a `url` that passes.'),
     api_version: zod_1.z.string().describe('The wire version events are rendered with for this endpoint.'),
     metadata: primitives_1.metadata,
     created: primitives_1.unixSeconds,

package/dist/cjs/resources/payments/disputes.js

@@ -7,6 +7,7 @@ const objects_1 = require("../../common/objects");
 const params_1 = require("../../common/params");
 const primitives_1 = require("../../common/primitives");
 const route_1 = require("../../route");
+const refunds_1 = require("./refunds");
 const payments_1 = require("../../vocabulary/payments");
 /**
  * Disputes (`dp_…`) — the card network holding a payment's money while a
@@ -201,4 +202,19 @@ exports.disputeRoutes = [
         response: exports.disputeSchema,
         sdk: 'disputes.close',
     }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveDisputeSettlement',
+        method: 'get',
+        path: '/v1/disputes/{disputeId}/settlement',
+        tag: 'Disputes',
+        summary: "Retrieve a dispute's settlement",
+        description: 'What the dispute WITHDREW from the settlement balance — `gross` the principal, `fee` the dispute fee, a negative `net` — in the settlement currency, read live from the provider. An inquiry moves no money: `unknown`, every figure `null`, never `0`. A reinstatement after a won dispute is not this figure.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: disputeId,
+        query: params_1.expandOnlyQuery,
+        response: refunds_1.settlementSchema,
+        sdk: 'disputes.settlement',
+        expandable: 'settlement',
+    }),
 ];

package/dist/cjs/resources/payments/refunds.js

@@ -10,7 +10,8 @@ const route_1 = require("../../route");
 const money_1 = require("../../vocabulary/money");
 const payments_1 = require("../../vocabulary/payments");
 /**
- * Refunds (`re_…`) and a payment's settlement figures. The provider's own
+ * Refunds (`re_…`) and the settlement figures of a payment, a refund or a
+ * dispute. The provider's own
  * refund id never appears: a merchant integrates against Peable and never
  * learns which acquirer sat behind it (ADR 0001 D3).
  */
@@ -56,23 +57,42 @@ exports.refundSchema = (0, objects_1.defineObject)('refund', 'Refund', zod_1.z
     ],
 });
 /**
- * What a payment actually came to, as the PROVIDER reports it. Every figure is
- * nullable and that is the contract: "the fee was zero" and "the fee is not
- * known yet" are different facts, and `status` says which produced the nulls.
- * It reports what the provider took; it attributes that cost to nobody.
+ * One movement of the settlement balance, as the PROVIDER reports it: what a
+ * payment brought in (`GET /v1/payment_intents/{intentId}/settlement`), what a
+ * refund took out (`GET /v1/refunds/{id}/settlement`) or what a dispute
+ * withdrew (`GET /v1/disputes/{disputeId}/settlement`). `refund` and `dispute`
+ * say which: both `null` for a payment's.
+ *
+ * Every figure is nullable and that is the contract: "the fee was zero" and
+ * "the fee is not known yet" are different facts, and `status` says which
+ * produced the nulls. It reports what the provider took; it attributes that
+ * cost to nobody.
+ *
+ * The signs: `gross` is the MAGNITUDE of the movement, `fee` the provider's fee
+ * on it (positive when charged, negative when returned), `net` its SIGNED
+ * effect on the balance — so `net = gross − fee` for a payment and
+ * `net = −gross − fee` for a refund or a dispute.
  */
 exports.settlementSchema = (0, objects_1.defineObject)('settlement', 'Settlement', zod_1.z
     .object({
     object: zod_1.z.literal('settlement'),
     livemode: primitives_1.livemode,
-    payment_intent: (0, objects_1.expandable)('payment_intent', 'The `pi_…` this describes, or the PaymentIntent with `expand[]=payment_intent`.'),
+    payment_intent: (0, objects_1.expandable)('payment_intent', 'The `pi_…` this describes (the refunded or disputed payment, for a refund or a dispute), or the PaymentIntent with `expand[]=payment_intent`.'),
+    refund: (0, objects_1.expandable)('refund', 'The `re_…` whose movement this is, or the Refund with `expand[]=refund`; `null` unless this is the settlement of a refund.').nullable(),
+    dispute: (0, objects_1.expandable)('dispute', 'The `dp_…` whose withdrawal this is, or the Dispute with `expand[]=dispute`; `null` unless this is the settlement of a dispute.').nullable(),
     status: zod_1.z
         .enum(payments_1.SETTLEMENT_STATUSES)
-        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**.'),
-    gross: primitives_1.amount.nullable().describe('Base units of `currency`.'),
-    fee: primitives_1.amount.nullable(),
-    net: primitives_1.signedAmount.nullable(),
-    currency: primitives_1.nullableString.describe("The SETTLEMENT currency (uppercase ISO 4217), which may differ from the payment's."),
+        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**. A dispute inquiry, which moves no money, and a refund that failed or was canceled are `unknown`.'),
+    gross: primitives_1.amount
+        .nullable()
+        .describe('The MAGNITUDE of the movement, never negative, in base units of `currency`: what the payment brought in, the refund took out or the dispute withdrew.'),
+    fee: primitives_1.signedAmount
+        .nullable()
+        .describe("The provider's fee on THIS movement, as the provider signs it: positive when charged to the balance (a payment's processing fee, a dispute fee), negative when returned to it (part of the original fee on some refunds). A refund's is usually `0`."),
+    net: primitives_1.signedAmount
+        .nullable()
+        .describe('The SIGNED effect on the balance: positive for a payment, negative for a refund or a dispute. Always `gross − fee` for a payment and `−gross − fee` for a refund or a dispute.'),
+    currency: primitives_1.nullableString.describe("The SETTLEMENT currency (uppercase ISO 4217) every figure is in, which may differ from the payment's, refund's or dispute's."),
     available_on: primitives_1.unixSeconds.nullable().describe('When the funds become available.'),
     exchange_rate: zod_1.z
         .number()
@@ -228,6 +248,21 @@ exports.refundRoutes = [
         sdk: 'refunds.settlement',
         expandable: 'settlement',
     }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveRefundSettlement',
+        method: 'get',
+        path: '/v1/refunds/{id}/settlement',
+        tag: 'Refunds',
+        summary: "Retrieve a refund's settlement",
+        description: 'What the refund took off the settlement balance — `gross`, `fee`, a negative `net` — in the settlement currency, read live from the provider. A missing figure is `null` with a `status`, never `0`; a refund that failed or was canceled is `unknown`.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: refundId,
+        query: params_1.expandOnlyQuery,
+        response: exports.settlementSchema,
+        sdk: 'refunds.refundSettlement',
+        expandable: 'settlement',
+    }),
     (0, route_1.defineRoute)({
         operationId: 'searchRefunds',
         method: 'get',

package/dist/cjs/vocabulary/catalog.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BILLING_RAIL_RENEWALS = exports.BILLING_RAIL_SETTLEMENTS = exports.BILLING_SUBSCRIPTION_STATUSES = exports.METER_STATUSES = exports.METER_AGGREGATIONS = exports.BILLING_SETTINGS_LIMITS = exports.DUNNING_INVOICE_ACTIONS = exports.DUNNING_FINAL_ACTIONS = exports.TEST_CLOCK_STATUSES = exports.RECURRING_INTERVAL_COUNT_MAX = exports.CATALOG_MAX_WHOLE_UNITS = exports.CATALOG_LIMITS = exports.COUPON_DURATIONS = exports.TRANSFORM_QUANTITY_ROUNDS = exports.PRICE_TAX_BEHAVIORS = exports.RECURRING_USAGE_TYPES = exports.RECURRING_INTERVALS = exports.PRICE_TYPES = exports.PRICE_TIERS_MODES = exports.PRICE_BILLING_SCHEMES = void 0;
+exports.METER_STATUSES = exports.METER_AGGREGATIONS = exports.BILLING_SETTINGS_LIMITS = exports.DUNNING_INVOICE_ACTIONS = exports.DUNNING_FINAL_ACTIONS = exports.TEST_CLOCK_STATUSES = exports.RECURRING_INTERVAL_COUNT_MAX = exports.CATALOG_MAX_WHOLE_UNITS = exports.CATALOG_LIMITS = exports.COUPON_DURATIONS = exports.TRANSFORM_QUANTITY_ROUNDS = exports.PRICE_TAX_BEHAVIORS = exports.RECURRING_USAGE_TYPES = exports.RECURRING_INTERVALS = exports.PRICE_TYPES = exports.PRICE_TIERS_MODES = exports.PRICE_BILLING_SCHEMES = void 0;
 exports.maxBaseUnits = maxBaseUnits;
 // The catalog's and the billing engine platform's closed value sets (ADR 0016,
 // ADR 0018): what a price, a coupon, a test clock, a meter and the billing
@@ -91,20 +91,4 @@ exports.BILLING_SETTINGS_LIMITS = Object.freeze({
 /** How a meter combines a period's events into the quantity billed. */
 exports.METER_AGGREGATIONS = ['sum', 'count', 'last'];
 exports.METER_STATUSES = ['active', 'inactive'];
-// ---- Recurring billing transport (`/v1/billing/*`) ---------------------------
-/** A provider subscription's status, as the recurring transport observes it. */
-exports.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). */
-exports.BILLING_RAIL_SETTLEMENTS = ['fiat', 'faircoin'];
-/** `automatic`: the provider charges each period. `payer_initiated`: each period is an explicit payment. */
-exports.BILLING_RAIL_RENEWALS = ['automatic', 'payer_initiated'];
 // Product tax codes are Peable Tax's vocabulary: `vocabulary/tax.ts` (`TAX_CODES`).

package/dist/cjs/vocabulary/errors.js

@@ -47,19 +47,15 @@ exports.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.',
@@ -88,10 +84,7 @@ exports.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.',
@@ -106,12 +99,9 @@ exports.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.',
@@ -119,9 +109,6 @@ exports.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/cjs/vocabulary/events.js

@@ -61,7 +61,6 @@ exports.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',
@@ -151,10 +150,15 @@ exports.WEBHOOK_ENDPOINT_STATUSES = ['enabled', 'disabled'];
  *  - `delivery_failures`    — every delivery to it failed for three days
  *    straight, so Peable stopped sending. Re-enabling it (`disabled: false`)
  *    starts the clock again.
+ *  - `url_refused`          — its stored `url` breaks the rules a URL is
+ *    registered under (https in live mode, ports 80/443, no private, loopback
+ *    or reserved address), judged again before every delivery, so Peable never
+ *    sent to it. It is re-enabled only together with a `url` that passes.
  */
 exports.WEBHOOK_ENDPOINT_DISABLED_REASONS = [
     'disabled_by_merchant',
     'delivery_failures',
+    'url_refused',
 ];
 /** At most this many endpoints per merchant (per mode). */
 exports.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = 16;

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

@@ -1,6 +1,5 @@
 // Contracts of this group: one module per resource, re-exported here, and
 // their routes concatenated into `catalogRoutes`.
-import { billingRoutes } from './billing.js';
 import { billingSettingsRoutes } from './billingSettings.js';
 import { couponRoutes } from './coupons.js';
 import { entitlementRoutes } from './entitlements.js';
@@ -9,7 +8,6 @@ import { priceRoutes } from './prices.js';
 import { productRoutes } from './products.js';
 import { promotionCodeRoutes } from './promotionCodes.js';
 import { testClockRoutes } from './testClocks.js';
-export * from './billing.js';
 export * from './billingSettings.js';
 export * from './coupons.js';
 export * from './entitlements.js';
@@ -22,8 +20,7 @@ export * from './testClocks.js';
 export { baseUnitAmountParam, queryFlag, queryIdList } from './shared.js';
 /**
  * The catalog (products, prices, coupons, promotion codes), entitlements, the
- * billing engine's platform objects (test clocks, billing settings, meters)
- * and the recurring billing transport (`/v1/billing/*`).
+ * billing engine's platform objects (test clocks, billing settings, meters).
  */
 export const catalogRoutes = [
     ...productRoutes,
@@ -34,5 +31,4 @@ export const catalogRoutes = [
     ...testClockRoutes,
     ...billingSettingsRoutes,
     ...meterRoutes,
-    ...billingRoutes,
 ];

package/dist/esm/resources/checkout/checkoutSessions.js

@@ -1,7 +1,6 @@
 import { z } from 'zod';
 import { CATALOG_LIMITS, PRICE_TAX_BEHAVIORS, RECURRING_INTERVALS } from '../../vocabulary/catalog.js';
 import { SETUP_INTENT_STATUSES } from '../../vocabulary/payments.js';
-import { billingFaircoinFxQuoteSchema } from '../catalog/billing.js';
 import { embedded } from '../../common/objects.js';
 import { listOf } from '../../common/envelopes.js';
 import { defineComponent, defineObject, expandable } from '../../common/objects.js';
@@ -180,9 +179,6 @@ export const checkoutSessionPublicSchema = defineComponent('CheckoutSessionPubli
         .string()
         .nullable()
         .describe("The card provider's PUBLIC key for this session's mode, so the payment fields can mount before the payment exists. `null` on FairCoin."),
-    billing_quote: billingFaircoinFxQuoteSchema
-        .optional()
-        .describe('FairCoin billing invoices: the frozen USD price and FAIR settlement quote.'),
 })
     .strict());
 // ---- Merchant create/update ---------------------------------------------------

package/dist/esm/resources/events/events.js

@@ -12,36 +12,6 @@ import { WEBHOOK_EVENT_OBJECTS, WEBHOOK_EVENT_TYPES, } from '../../vocabulary/ev
  * every matching webhook endpoint: a delivery's body and `GET /v1/events/:id`
  * are byte for byte the same object.
  */
-/**
- * The payload of `billing.observation.updated`: a wake-up, never paid or grant
- * authority. Re-read the owner-bound resource it names.
- */
-export const billingObservationSchema = defineObject('billing_observation', 'BillingObservation', z
-    .object({
-    object: z.literal('billing_observation'),
-    livemode: livemode.describe('The mode of the billing cohort observed (ADR 0017).'),
-    resource_kind: z.enum(['subscription', 'invoice']),
-    resource_id: z.string().describe('The provider subscription or invoice observed.'),
-    subscription_id: z
-        .string()
-        .optional()
-        .describe('Owner-scoped wake-up hint only; re-read the subscription before resolving a payer.'),
-    revision: z.number().int().describe('The observation revision; later revisions are newer.'),
-    observed_at: unixSeconds,
-})
-    .strict(), {
-    examples: [
-        {
-            object: 'billing_observation',
-            livemode: false,
-            resource_kind: 'subscription',
-            resource_id: 'sub_1Q2w3E4r5T6y7U8i',
-            subscription_id: 'sub_1Q2w3E4r5T6y7U8i',
-            revision: 3,
-            observed_at: 1793750400,
-        },
-    ],
-});
 /**
  * What caused an event, when an API request did (Stripe's `event.request`).
  * Both `null` for an event caused by something else — the chain watcher, the
@@ -238,7 +208,6 @@ export const WEBHOOK_EVENT_DESCRIPTIONS = {
     'setup_intent.succeeded': 'A SetupIntent succeeded: its PaymentMethod is saved.',
     'setup_intent.setup_failed': 'A SetupIntent attempt failed.',
     'setup_intent.canceled': 'A SetupIntent was canceled.',
-    'billing.observation.updated': 'A recurring billing resource was observed to change. A wake-up only: re-read the resource.',
     'connected_account.updated': "A seller's connected account changed — its readiness, in practice.",
     'product.created': 'A Product was created.',
     'product.updated': 'A Product was updated; `previous_attributes` names what moved.',

package/dist/esm/resources/events/webhookDeliveries.js

@@ -23,7 +23,7 @@ export const webhookDeliverySchema = defineObject('webhook_delivery', 'WebhookDe
     delivered: z.boolean(),
     last_status: z
         .enum(WEBHOOK_DELIVERY_STATUSES)
-        .describe('`pending`: will be attempted (`next_attempt_at`). `delivered`: terminal success. `failed`: the endpoint refused it (a 4xx, a blocked address) or was disabled first — never retried. `dead`: every attempt failed transiently for three days; it can be redelivered.'),
+        .describe('`pending`: will be attempted (`next_attempt_at`). `delivered`: terminal success. `failed`: the endpoint refused it (a 4xx, a blocked address), was disabled first, or its stored url breaks the registration rules — never retried. `dead`: every attempt failed transiently for three days; it can be redelivered.'),
     last_error: z
         .string()
         .optional()

package/dist/esm/resources/events/webhookEndpoints.js

@@ -26,7 +26,7 @@ const endpointShape = {
     disabled_reason: z
         .enum(WEBHOOK_ENDPOINT_DISABLED_REASONS)
         .nullable()
-        .describe('`null` exactly when `status` is `enabled`. `delivery_failures`: every delivery failed for three days straight.'),
+        .describe('`null` exactly when `status` is `enabled`. `delivery_failures`: every delivery failed for three days straight. `url_refused`: the stored `url` breaks the registration rules, judged before every delivery; re-enable it with a `url` that passes.'),
     api_version: z.string().describe('The wire version events are rendered with for this endpoint.'),
     metadata,
     created: unixSeconds,

package/dist/esm/resources/payments/disputes.js

@@ -4,6 +4,7 @@ import { defineComponent, defineObject, expandable } from '../../common/objects.
 import { expandOnlyQuery, idParam, listQuery, metadataUpdateParam } from '../../common/params.js';
 import { amount, currency, livemode, metadata, unixSeconds } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
+import { settlementSchema } from './refunds.js';
 import { DISPUTE_EVIDENCE_TEXT_MAX, DISPUTE_FILE_EVIDENCE_FIELDS, DISPUTE_REASONS, DISPUTE_STATUSES, DISPUTE_TEXT_EVIDENCE_FIELDS, } from '../../vocabulary/payments.js';
 /**
  * Disputes (`dp_…`) — the card network holding a payment's money while a
@@ -198,4 +199,19 @@ export const disputeRoutes = [
         response: disputeSchema,
         sdk: 'disputes.close',
     }),
+    defineRoute({
+        operationId: 'retrieveDisputeSettlement',
+        method: 'get',
+        path: '/v1/disputes/{disputeId}/settlement',
+        tag: 'Disputes',
+        summary: "Retrieve a dispute's settlement",
+        description: 'What the dispute WITHDREW from the settlement balance — `gross` the principal, `fee` the dispute fee, a negative `net` — in the settlement currency, read live from the provider. An inquiry moves no money: `unknown`, every figure `null`, never `0`. A reinstatement after a won dispute is not this figure.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: disputeId,
+        query: expandOnlyQuery,
+        response: settlementSchema,
+        sdk: 'disputes.settlement',
+        expandable: 'settlement',
+    }),
 ];

package/dist/esm/resources/payments/refunds.js

@@ -7,7 +7,8 @@ import { defineRoute } from '../../route.js';
 import { isBaseUnitString } from '../../vocabulary/money.js';
 import { REFUND_ORIGINS, REFUND_REASONS, REFUND_STATUSES, SETTLEMENT_STATUSES, } from '../../vocabulary/payments.js';
 /**
- * Refunds (`re_…`) and a payment's settlement figures. The provider's own
+ * Refunds (`re_…`) and the settlement figures of a payment, a refund or a
+ * dispute. The provider's own
  * refund id never appears: a merchant integrates against Peable and never
  * learns which acquirer sat behind it (ADR 0001 D3).
  */
@@ -53,23 +54,42 @@ export const refundSchema = defineObject('refund', 'Refund', z
     ],
 });
 /**
- * What a payment actually came to, as the PROVIDER reports it. Every figure is
- * nullable and that is the contract: "the fee was zero" and "the fee is not
- * known yet" are different facts, and `status` says which produced the nulls.
- * It reports what the provider took; it attributes that cost to nobody.
+ * One movement of the settlement balance, as the PROVIDER reports it: what a
+ * payment brought in (`GET /v1/payment_intents/{intentId}/settlement`), what a
+ * refund took out (`GET /v1/refunds/{id}/settlement`) or what a dispute
+ * withdrew (`GET /v1/disputes/{disputeId}/settlement`). `refund` and `dispute`
+ * say which: both `null` for a payment's.
+ *
+ * Every figure is nullable and that is the contract: "the fee was zero" and
+ * "the fee is not known yet" are different facts, and `status` says which
+ * produced the nulls. It reports what the provider took; it attributes that
+ * cost to nobody.
+ *
+ * The signs: `gross` is the MAGNITUDE of the movement, `fee` the provider's fee
+ * on it (positive when charged, negative when returned), `net` its SIGNED
+ * effect on the balance — so `net = gross − fee` for a payment and
+ * `net = −gross − fee` for a refund or a dispute.
  */
 export const settlementSchema = defineObject('settlement', 'Settlement', z
     .object({
     object: z.literal('settlement'),
     livemode,
-    payment_intent: expandable('payment_intent', 'The `pi_…` this describes, or the PaymentIntent with `expand[]=payment_intent`.'),
+    payment_intent: expandable('payment_intent', 'The `pi_…` this describes (the refunded or disputed payment, for a refund or a dispute), or the PaymentIntent with `expand[]=payment_intent`.'),
+    refund: expandable('refund', 'The `re_…` whose movement this is, or the Refund with `expand[]=refund`; `null` unless this is the settlement of a refund.').nullable(),
+    dispute: expandable('dispute', 'The `dp_…` whose withdrawal this is, or the Dispute with `expand[]=dispute`; `null` unless this is the settlement of a dispute.').nullable(),
     status: z
         .enum(SETTLEMENT_STATUSES)
-        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**.'),
-    gross: amount.nullable().describe('Base units of `currency`.'),
-    fee: amount.nullable(),
-    net: signedAmount.nullable(),
-    currency: nullableString.describe("The SETTLEMENT currency (uppercase ISO 4217), which may differ from the payment's."),
+        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**. A dispute inquiry, which moves no money, and a refund that failed or was canceled are `unknown`.'),
+    gross: amount
+        .nullable()
+        .describe('The MAGNITUDE of the movement, never negative, in base units of `currency`: what the payment brought in, the refund took out or the dispute withdrew.'),
+    fee: signedAmount
+        .nullable()
+        .describe("The provider's fee on THIS movement, as the provider signs it: positive when charged to the balance (a payment's processing fee, a dispute fee), negative when returned to it (part of the original fee on some refunds). A refund's is usually `0`."),
+    net: signedAmount
+        .nullable()
+        .describe('The SIGNED effect on the balance: positive for a payment, negative for a refund or a dispute. Always `gross − fee` for a payment and `−gross − fee` for a refund or a dispute.'),
+    currency: nullableString.describe("The SETTLEMENT currency (uppercase ISO 4217) every figure is in, which may differ from the payment's, refund's or dispute's."),
     available_on: unixSeconds.nullable().describe('When the funds become available.'),
     exchange_rate: z
         .number()
@@ -225,6 +245,21 @@ export const refundRoutes = [
         sdk: 'refunds.settlement',
         expandable: 'settlement',
     }),
+    defineRoute({
+        operationId: 'retrieveRefundSettlement',
+        method: 'get',
+        path: '/v1/refunds/{id}/settlement',
+        tag: 'Refunds',
+        summary: "Retrieve a refund's settlement",
+        description: 'What the refund took off the settlement balance — `gross`, `fee`, a negative `net` — in the settlement currency, read live from the provider. A missing figure is `null` with a `status`, never `0`; a refund that failed or was canceled is `unknown`.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: refundId,
+        query: expandOnlyQuery,
+        response: settlementSchema,
+        sdk: 'refunds.refundSettlement',
+        expandable: 'settlement',
+    }),
     defineRoute({
         operationId: 'searchRefunds',
         method: 'get',

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`).