@peable.to/shared-types 0.11.0 → 0.13.0

package/dist/cjs/catalog.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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;
+/** How a price's amount is computed from a quantity. */
+exports.PRICE_BILLING_SCHEMES = ['per_unit', 'tiered'];
+/**
+ * How a tiered price reads its tiers.
+ *
+ *  - `volume`    — the WHOLE quantity is priced at the tier it falls into.
+ *  - `graduated` — each unit is priced at the tier it falls into, so a
+ *                  quantity crossing two tiers pays each tier's rate for its
+ *                  share, plus the flat amount of every tier it reaches.
+ */
+exports.PRICE_TIERS_MODES = ['graduated', 'volume'];
+/** `recurring` when the price has a recurring component, `one_time` otherwise. */
+exports.PRICE_TYPES = ['one_time', 'recurring'];
+exports.RECURRING_INTERVALS = ['day', 'week', 'month', 'year'];
+/**
+ * `licensed` bills the quantity on the subscription. `metered` bills reported
+ * usage and needs a meter; meters are not part of Orbit yet, so the gateway
+ * refuses a metered price rather than store one nothing can bill.
+ */
+exports.RECURRING_USAGE_TYPES = ['licensed', 'metered'];
+/**
+ * Whether a price includes tax (Peable Tax, ADR 0011). `unspecified` defers to
+ * the merchant's default tax behavior; once a price says `inclusive` or
+ * `exclusive` it can never change.
+ */
+exports.PRICE_TAX_BEHAVIORS = ['inclusive', 'exclusive', 'unspecified'];
+exports.TRANSFORM_QUANTITY_ROUNDS = ['up', 'down'];
+/** How long a coupon's discount lasts once applied to a subscription. */
+exports.COUPON_DURATIONS = ['once', 'repeating', 'forever'];
+/** The bounds the gateway enforces, published so a form can say them first. */
+exports.CATALOG_LIMITS = Object.freeze({
+    productNameMax: 250,
+    productDescriptionMax: 40000,
+    productImagesMax: 8,
+    urlMax: 2048,
+    unitLabelMax: 12,
+    statementDescriptorMax: 22,
+    marketingFeaturesMax: 15,
+    marketingFeatureNameMax: 80,
+    priceNicknameMax: 250,
+    lookupKeyMax: 200,
+    lookupKeysFilterMax: 10,
+    priceTiersMax: 250,
+    couponIdMax: 64,
+    couponNameMax: 40,
+    couponAppliesToProductsMax: 100,
+    couponDurationInMonthsMax: 1200,
+    promotionCodeMax: 64,
+    idsFilterMax: 100,
+});

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TAX_LOCATION_EVIDENCE_TYPES = exports.TAX_REGISTRATION_SCHEMES = exports.PEABLE_BILLING_AUTHORITY_KEYS = exports.canonicalBillingTaxQuote = exports.canonicalBillingAuthority = exports.BILLING_SUBSCRIPTION_STATUSES = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.MERCHANT_ENVIRONMENTS = exports.verifyWebhook = exports.signWebhook = exports.WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS = exports.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = exports.WEBHOOK_ENDPOINT_DISABLED_REASONS = exports.WEBHOOK_ENDPOINT_STATUSES = exports.PEABLE_API_VERSION = exports.SETUP_INTENT_STATUSES = exports.isValidStatusTransition = exports.canStillBePaid = exports.canExpire = exports.TERMINAL_STATUSES = exports.PAYMENT_INTENT_STATUSES = exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = exports.PAYMENT_INTENT_RAILS = exports.PAYMENT_INTENT_CAPTURE_METHODS = exports.PAYMENT_INTENT_CANCELLATION_REASONS = exports.MERCHANT_CANCELLATION_REASONS = exports.EXPIRABLE_STATUSES = exports.CARD_ONLY_STATUSES = exports.isCurrencyCode = exports.decimalsFor = exports.CURRENCY_DECIMALS = exports.CURRENCY_CODES = exports.isBaseUnitString = exports.UNITS_PER_COIN = void 0;
+exports.TAX_LOCATION_EVIDENCE_TYPES = exports.TAX_REGISTRATION_SCHEMES = exports.PEABLE_BILLING_AUTHORITY_KEYS = exports.canonicalBillingTaxQuote = exports.canonicalBillingAuthority = exports.BILLING_SUBSCRIPTION_STATUSES = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.MERCHANT_ENVIRONMENTS = exports.verifyWebhook = exports.signWebhook = exports.SIMULATED_FAIRCOIN_OUTCOMES = exports.REQUEST_LOG_RETENTION_DAYS = exports.REQUEST_LOG_METHODS = 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 = exports.WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS = exports.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = exports.WEBHOOK_ENDPOINT_DISABLED_REASONS = exports.WEBHOOK_ENDPOINT_STATUSES = exports.PEABLE_API_VERSION = exports.SETUP_INTENT_STATUSES = exports.isValidStatusTransition = exports.canStillBePaid = exports.canExpire = exports.TERMINAL_STATUSES = exports.PAYMENT_INTENT_STATUSES = exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = exports.PAYMENT_INTENT_RAILS = exports.PAYMENT_INTENT_CAPTURE_METHODS = exports.PAYMENT_INTENT_CANCELLATION_REASONS = exports.MERCHANT_CANCELLATION_REASONS = exports.EXPIRABLE_STATUSES = exports.CARD_ONLY_STATUSES = exports.isCurrencyCode = exports.decimalsFor = exports.CURRENCY_DECIMALS = exports.CURRENCY_CODES = exports.isBaseUnitString = exports.UNITS_PER_COIN = void 0;
 // @peable.to/shared-types — public API for the Peable Gateway contract.
 var money_1 = require("./money");
 Object.defineProperty(exports, "UNITS_PER_COIN", { enumerable: true, get: function () { return money_1.UNITS_PER_COIN; } });
@@ -31,6 +31,21 @@ Object.defineProperty(exports, "WEBHOOK_ENDPOINT_STATUSES", { enumerable: true,
 Object.defineProperty(exports, "WEBHOOK_ENDPOINT_DISABLED_REASONS", { enumerable: true, get: function () { return webhookEndpoint_1.WEBHOOK_ENDPOINT_DISABLED_REASONS; } });
 Object.defineProperty(exports, "WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT", { enumerable: true, get: function () { return webhookEndpoint_1.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT; } });
 Object.defineProperty(exports, "WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS", { enumerable: true, get: function () { return webhookEndpoint_1.WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS; } });
+var catalog_1 = require("./catalog");
+Object.defineProperty(exports, "PRICE_BILLING_SCHEMES", { enumerable: true, get: function () { return catalog_1.PRICE_BILLING_SCHEMES; } });
+Object.defineProperty(exports, "PRICE_TIERS_MODES", { enumerable: true, get: function () { return catalog_1.PRICE_TIERS_MODES; } });
+Object.defineProperty(exports, "PRICE_TYPES", { enumerable: true, get: function () { return catalog_1.PRICE_TYPES; } });
+Object.defineProperty(exports, "RECURRING_INTERVALS", { enumerable: true, get: function () { return catalog_1.RECURRING_INTERVALS; } });
+Object.defineProperty(exports, "RECURRING_USAGE_TYPES", { enumerable: true, get: function () { return catalog_1.RECURRING_USAGE_TYPES; } });
+Object.defineProperty(exports, "PRICE_TAX_BEHAVIORS", { enumerable: true, get: function () { return catalog_1.PRICE_TAX_BEHAVIORS; } });
+Object.defineProperty(exports, "TRANSFORM_QUANTITY_ROUNDS", { enumerable: true, get: function () { return catalog_1.TRANSFORM_QUANTITY_ROUNDS; } });
+Object.defineProperty(exports, "COUPON_DURATIONS", { enumerable: true, get: function () { return catalog_1.COUPON_DURATIONS; } });
+Object.defineProperty(exports, "CATALOG_LIMITS", { enumerable: true, get: function () { return catalog_1.CATALOG_LIMITS; } });
+var requestLog_1 = require("./requestLog");
+Object.defineProperty(exports, "REQUEST_LOG_METHODS", { enumerable: true, get: function () { return requestLog_1.REQUEST_LOG_METHODS; } });
+Object.defineProperty(exports, "REQUEST_LOG_RETENTION_DAYS", { enumerable: true, get: function () { return requestLog_1.REQUEST_LOG_RETENTION_DAYS; } });
+var testHelpers_1 = require("./testHelpers");
+Object.defineProperty(exports, "SIMULATED_FAIRCOIN_OUTCOMES", { enumerable: true, get: function () { return testHelpers_1.SIMULATED_FAIRCOIN_OUTCOMES; } });
 var webhookSigner_1 = require("./webhookSigner");
 Object.defineProperty(exports, "signWebhook", { enumerable: true, get: function () { return webhookSigner_1.signWebhook; } });
 Object.defineProperty(exports, "verifyWebhook", { enumerable: true, get: function () { return webhookSigner_1.verifyWebhook; } });

package/dist/cjs/requestLog.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUEST_LOG_RETENTION_DAYS = exports.REQUEST_LOG_METHODS = void 0;
+/**
+ * One merchant API request, as Peable recorded it (`req_…`) — the request log
+ * Orbit and `peable logs tail` read.
+ *
+ * Its `id` IS the `Request-Id` that request was answered with, so the id a
+ * merchant quotes to support and the log row are the same thing.
+ *
+ * Deliberately thin: method, path (no query string), status, duration and the
+ * `Idempotency-Key` it carried. No body, no headers, no query string, no
+ * caller address — a log a merchant can read is a log that must not hold what
+ * a request carried. Kept 30 days.
+ */
+exports.REQUEST_LOG_METHODS = ['GET', 'POST', 'DELETE', 'PATCH', 'PUT'];
+/** How long a request log is kept (and served). */
+exports.REQUEST_LOG_RETENTION_DAYS = 30;

package/dist/cjs/testHelpers.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Test helpers (`/v1/test_helpers/*`) — test mode only.
+ *
+ * They drive a test-mode object through the SAME state machine a real payment
+ * moves through, so a merchant can exercise their integration end to end
+ * without a wallet or a card: every transition a helper makes is one the
+ * gateway would make, with the same events and webhooks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIMULATED_FAIRCOIN_OUTCOMES = void 0;
+/**
+ * What `simulate_faircoin_payment` pretends the payer did.
+ *
+ *  - `settled`   — paid the full amount, which is then seen in the mempool and
+ *    confirmed: `broadcast → confirming → settled`
+ *    (`payment_intent.confirming`, then `payment_intent.settled`).
+ *  - `underpaid` — sent less than the amount: `broadcast → failed`
+ *    (`payment_intent.failed`).
+ */
+exports.SIMULATED_FAIRCOIN_OUTCOMES = ['settled', 'underpaid'];

package/dist/esm/catalog.js

@@ -0,0 +1,50 @@
+/** How a price's amount is computed from a quantity. */
+export const PRICE_BILLING_SCHEMES = ['per_unit', 'tiered'];
+/**
+ * How a tiered price reads its tiers.
+ *
+ *  - `volume`    — the WHOLE quantity is priced at the tier it falls into.
+ *  - `graduated` — each unit is priced at the tier it falls into, so a
+ *                  quantity crossing two tiers pays each tier's rate for its
+ *                  share, plus the flat amount of every tier it reaches.
+ */
+export const PRICE_TIERS_MODES = ['graduated', 'volume'];
+/** `recurring` when the price has a recurring component, `one_time` otherwise. */
+export const PRICE_TYPES = ['one_time', 'recurring'];
+export const RECURRING_INTERVALS = ['day', 'week', 'month', 'year'];
+/**
+ * `licensed` bills the quantity on the subscription. `metered` bills reported
+ * usage and needs a meter; meters are not part of Orbit yet, so the gateway
+ * refuses a metered price rather than store one nothing can bill.
+ */
+export const RECURRING_USAGE_TYPES = ['licensed', 'metered'];
+/**
+ * Whether a price includes tax (Peable Tax, ADR 0011). `unspecified` defers to
+ * the merchant's default tax behavior; once a price says `inclusive` or
+ * `exclusive` it can never change.
+ */
+export const PRICE_TAX_BEHAVIORS = ['inclusive', 'exclusive', 'unspecified'];
+export const TRANSFORM_QUANTITY_ROUNDS = ['up', 'down'];
+/** How long a coupon's discount lasts once applied to a subscription. */
+export const COUPON_DURATIONS = ['once', 'repeating', 'forever'];
+/** The bounds the gateway enforces, published so a form can say them first. */
+export const CATALOG_LIMITS = Object.freeze({
+    productNameMax: 250,
+    productDescriptionMax: 40000,
+    productImagesMax: 8,
+    urlMax: 2048,
+    unitLabelMax: 12,
+    statementDescriptorMax: 22,
+    marketingFeaturesMax: 15,
+    marketingFeatureNameMax: 80,
+    priceNicknameMax: 250,
+    lookupKeyMax: 200,
+    lookupKeysFilterMax: 10,
+    priceTiersMax: 250,
+    couponIdMax: 64,
+    couponNameMax: 40,
+    couponAppliesToProductsMax: 100,
+    couponDurationInMonthsMax: 1200,
+    promotionCodeMax: 64,
+    idsFilterMax: 100,
+});

package/dist/esm/index.js

@@ -4,6 +4,9 @@ export { CARD_ONLY_STATUSES, EXPIRABLE_STATUSES, MERCHANT_CANCELLATION_REASONS,
 export { SETUP_INTENT_STATUSES, } from './setupIntent.js';
 export { PEABLE_API_VERSION, } from './event.js';
 export { WEBHOOK_ENDPOINT_STATUSES, WEBHOOK_ENDPOINT_DISABLED_REASONS, WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT, WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS, } from './webhookEndpoint.js';
+export { PRICE_BILLING_SCHEMES, PRICE_TIERS_MODES, PRICE_TYPES, RECURRING_INTERVALS, RECURRING_USAGE_TYPES, PRICE_TAX_BEHAVIORS, TRANSFORM_QUANTITY_ROUNDS, COUPON_DURATIONS, CATALOG_LIMITS, } from './catalog.js';
+export { REQUEST_LOG_METHODS, REQUEST_LOG_RETENTION_DAYS, } from './requestLog.js';
+export { SIMULATED_FAIRCOIN_OUTCOMES, } from './testHelpers.js';
 export { signWebhook, verifyWebhook } from './webhookSigner.js';
 export { MERCHANT_ENVIRONMENTS, } from './merchant.js';
 export { SOCIAL_SOURCE_APP_MAX_LENGTH, SOCIAL_SOURCE_REF_MAX_LENGTH, } from './social.js';

package/dist/esm/requestLog.js

@@ -0,0 +1,15 @@
+/**
+ * One merchant API request, as Peable recorded it (`req_…`) — the request log
+ * Orbit and `peable logs tail` read.
+ *
+ * Its `id` IS the `Request-Id` that request was answered with, so the id a
+ * merchant quotes to support and the log row are the same thing.
+ *
+ * Deliberately thin: method, path (no query string), status, duration and the
+ * `Idempotency-Key` it carried. No body, no headers, no query string, no
+ * caller address — a log a merchant can read is a log that must not hold what
+ * a request carried. Kept 30 days.
+ */
+export const REQUEST_LOG_METHODS = ['GET', 'POST', 'DELETE', 'PATCH', 'PUT'];
+/** How long a request log is kept (and served). */
+export const REQUEST_LOG_RETENTION_DAYS = 30;

package/dist/esm/testHelpers.js

@@ -0,0 +1,18 @@
+/**
+ * Test helpers (`/v1/test_helpers/*`) — test mode only.
+ *
+ * They drive a test-mode object through the SAME state machine a real payment
+ * moves through, so a merchant can exercise their integration end to end
+ * without a wallet or a card: every transition a helper makes is one the
+ * gateway would make, with the same events and webhooks.
+ */
+/**
+ * What `simulate_faircoin_payment` pretends the payer did.
+ *
+ *  - `settled`   — paid the full amount, which is then seen in the mempool and
+ *    confirmed: `broadcast → confirming → settled`
+ *    (`payment_intent.confirming`, then `payment_intent.settled`).
+ *  - `underpaid` — sent less than the amount: `broadcast → failed`
+ *    (`payment_intent.failed`).
+ */
+export const SIMULATED_FAIRCOIN_OUTCOMES = ['settled', 'underpaid'];

package/dist/types/catalog.d.ts

@@ -0,0 +1,390 @@
+import type { ListParams } from './list';
+import type { Customer } from './customer';
+import type { CurrencyCode } from './money';
+/** How a price's amount is computed from a quantity. */
+export declare const PRICE_BILLING_SCHEMES: readonly ["per_unit", "tiered"];
+export type PriceBillingScheme = (typeof PRICE_BILLING_SCHEMES)[number];
+/**
+ * How a tiered price reads its tiers.
+ *
+ *  - `volume`    — the WHOLE quantity is priced at the tier it falls into.
+ *  - `graduated` — each unit is priced at the tier it falls into, so a
+ *                  quantity crossing two tiers pays each tier's rate for its
+ *                  share, plus the flat amount of every tier it reaches.
+ */
+export declare const PRICE_TIERS_MODES: readonly ["graduated", "volume"];
+export type PriceTiersMode = (typeof PRICE_TIERS_MODES)[number];
+/** `recurring` when the price has a recurring component, `one_time` otherwise. */
+export declare const PRICE_TYPES: readonly ["one_time", "recurring"];
+export type PriceType = (typeof PRICE_TYPES)[number];
+export declare const RECURRING_INTERVALS: readonly ["day", "week", "month", "year"];
+export type RecurringInterval = (typeof RECURRING_INTERVALS)[number];
+/**
+ * `licensed` bills the quantity on the subscription. `metered` bills reported
+ * usage and needs a meter; meters are not part of Orbit yet, so the gateway
+ * refuses a metered price rather than store one nothing can bill.
+ */
+export declare const RECURRING_USAGE_TYPES: readonly ["licensed", "metered"];
+export type RecurringUsageType = (typeof RECURRING_USAGE_TYPES)[number];
+/**
+ * Whether a price includes tax (Peable Tax, ADR 0011). `unspecified` defers to
+ * the merchant's default tax behavior; once a price says `inclusive` or
+ * `exclusive` it can never change.
+ */
+export declare const PRICE_TAX_BEHAVIORS: readonly ["inclusive", "exclusive", "unspecified"];
+export type PriceTaxBehavior = (typeof PRICE_TAX_BEHAVIORS)[number];
+export declare const TRANSFORM_QUANTITY_ROUNDS: readonly ["up", "down"];
+export type TransformQuantityRound = (typeof TRANSFORM_QUANTITY_ROUNDS)[number];
+/** How long a coupon's discount lasts once applied to a subscription. */
+export declare const COUPON_DURATIONS: readonly ["once", "repeating", "forever"];
+export type CouponDuration = (typeof COUPON_DURATIONS)[number];
+/** The bounds the gateway enforces, published so a form can say them first. */
+export declare const CATALOG_LIMITS: Readonly<{
+    productNameMax: 250;
+    productDescriptionMax: 40000;
+    productImagesMax: 8;
+    urlMax: 2048;
+    unitLabelMax: 12;
+    statementDescriptorMax: 22;
+    marketingFeaturesMax: 15;
+    marketingFeatureNameMax: 80;
+    priceNicknameMax: 250;
+    lookupKeyMax: 200;
+    lookupKeysFilterMax: 10;
+    priceTiersMax: 250;
+    couponIdMax: 64;
+    couponNameMax: 40;
+    couponAppliesToProductsMax: 100;
+    couponDurationInMonthsMax: 1200;
+    promotionCodeMax: 64;
+    idsFilterMax: 100;
+}>;
+/** A product feature shown on pricing tables and checkout (Stripe's marketing features). */
+export interface ProductMarketingFeature {
+    name: string;
+}
+/**
+ * A product (`prod_…`) — what a merchant sells. Its prices say how much.
+ *
+ * A product with prices cannot be deleted; set `active: false` to archive it.
+ */
+export interface Product {
+    id: string;
+    object: 'product';
+    /** The mode of the merchant that owns it (ADR 0017). */
+    livemode: boolean;
+    active: boolean;
+    name: string;
+    description: string | null;
+    /** Up to 8 image URLs. */
+    images: string[];
+    metadata: Record<string, string>;
+    /** A Peable Tax code (`txcd_…`), or `null` for the merchant's default. */
+    tax_code: string | null;
+    /** The product's default price — a `price_…`, or the Price when expanded. */
+    default_price: string | Price | null;
+    /** The unit a quantity counts (`seat`), shown on receipts and invoices. */
+    unit_label: string | null;
+    url: string | null;
+    /** What appears on a card statement; at most 22 characters. */
+    statement_descriptor: string | null;
+    marketing_features: ProductMarketingFeature[];
+    created: number;
+    updated: number;
+}
+/** What `DELETE /v1/products/:id` answers. */
+export interface DeletedProduct {
+    id: string;
+    object: 'product';
+    deleted: true;
+}
+/**
+ * One tier of a tiered price. `up_to` is the last quantity the tier covers
+ * (inclusive), and `null` on the last tier, which covers everything above —
+ * sent as `'inf'`. Each amount is a base-unit string; at least one is set.
+ */
+export interface PriceTier {
+    up_to: number | null;
+    unit_amount: string | null;
+    flat_amount: string | null;
+}
+/**
+ * Divide the quantity before pricing it: `divide_by: 10, round: 'up'` bills
+ * 11 units as 2 packs of ten. Per-unit prices only.
+ */
+export interface PriceTransformQuantity {
+    divide_by: number;
+    round: TransformQuantityRound;
+}
+export interface PriceRecurring {
+    interval: RecurringInterval;
+    /** Intervals between billings: `interval: 'month', interval_count: 3` is quarterly. At most three years. */
+    interval_count: number;
+    usage_type: RecurringUsageType;
+}
+/**
+ * A price (`price_…`) — how much a product costs, in one currency, once or per
+ * interval.
+ *
+ * IMMUTABLE once created except for `active`, `nickname`, `metadata`,
+ * `lookup_key` and — while it is `unspecified` — `tax_behavior`. To change an
+ * amount, create a new price and archive the old one: a subscription priced
+ * from it must keep meaning what it meant.
+ */
+export interface Price {
+    id: string;
+    object: 'price';
+    livemode: boolean;
+    active: boolean;
+    /** The product it prices — a `prod_…`, or the Product when expanded. */
+    product: string | Product;
+    currency: CurrencyCode;
+    /** Base units per unit; `null` on a tiered price. */
+    unit_amount: string | null;
+    billing_scheme: PriceBillingScheme;
+    /** `null` unless `billing_scheme` is `tiered`. */
+    tiers: PriceTier[] | null;
+    tiers_mode: PriceTiersMode | null;
+    transform_quantity: PriceTransformQuantity | null;
+    type: PriceType;
+    /** `null` exactly when `type` is `one_time`. */
+    recurring: PriceRecurring | null;
+    tax_behavior: PriceTaxBehavior;
+    /**
+     * The merchant's own stable name for this price, unique among its prices
+     * (per mode): retrieve the current price of a plan with `lookup_keys[]`
+     * without storing an id that changes whenever the amount does.
+     */
+    lookup_key: string | null;
+    nickname: string | null;
+    metadata: Record<string, string>;
+    created: number;
+}
+/**
+ * A coupon — a discount, by percentage or by a fixed amount in one currency.
+ * Its `id` is the merchant's own (`SUMMER25`) or generated (`coupon_…`), and
+ * names that one coupon forever: a deleted coupon's id is never reused.
+ *
+ * Only `name` and `metadata` can change; the terms of a discount a customer
+ * already holds cannot.
+ */
+export interface Coupon {
+    id: string;
+    object: 'coupon';
+    livemode: boolean;
+    name: string | null;
+    /** 0 < x ≤ 100, at most two decimals. Set exactly when `amount_off` is not. */
+    percent_off: number | null;
+    /** Base units taken off, in `currency`. */
+    amount_off: string | null;
+    currency: CurrencyCode | null;
+    duration: CouponDuration;
+    /** Months a `repeating` coupon lasts; `null` otherwise. */
+    duration_in_months: number | null;
+    max_redemptions: number | null;
+    /** The last instant (Unix seconds) it can be redeemed. */
+    redeem_by: number | null;
+    times_redeemed: number;
+    /** Whether it can still be redeemed: not past `redeem_by` and not used up. */
+    valid: boolean;
+    /** The products it is restricted to, or `null` for every product. */
+    applies_to: {
+        products: string[];
+    } | null;
+    metadata: Record<string, string>;
+    created: number;
+}
+/** What `DELETE /v1/coupons/:id` answers. Existing discounts are not affected. */
+export interface DeletedCoupon {
+    id: string;
+    object: 'coupon';
+    deleted: true;
+}
+export interface PromotionCodeRestrictions {
+    /** Only a customer's first transaction may redeem it. */
+    first_time_transaction: boolean;
+    /** The smallest order total (base units) it applies to, in `minimum_amount_currency`. */
+    minimum_amount: string | null;
+    minimum_amount_currency: CurrencyCode | null;
+}
+/**
+ * A promotion code (`promo_…`) — a customer-facing `code` that redeems a
+ * coupon, with its own limits. Codes are case-insensitive and unique among a
+ * merchant's ACTIVE codes.
+ */
+export interface PromotionCode {
+    id: string;
+    object: 'promotion_code';
+    livemode: boolean;
+    code: string;
+    /** The coupon it redeems — its id, or the Coupon when expanded. */
+    coupon: string | Coupon;
+    /** The one customer who may redeem it (`cus_…`, or the Customer when expanded); `null` for anyone. */
+    customer: string | Customer | null;
+    active: boolean;
+    max_redemptions: number | null;
+    /** Unix seconds; never after the coupon's `redeem_by`. */
+    expires_at: number | null;
+    times_redeemed: number;
+    restrictions: PromotionCodeRestrictions;
+    metadata: Record<string, string>;
+    created: number;
+}
+export interface RecurringParams {
+    interval: RecurringInterval;
+    /** Default 1. */
+    interval_count?: number;
+    /** Default `licensed`. */
+    usage_type?: RecurringUsageType;
+}
+export interface PriceTierParams {
+    /** A positive integer, ascending; the last tier is `'inf'`. */
+    up_to: number | 'inf';
+    unit_amount?: string;
+    flat_amount?: string;
+}
+/**
+ * An inline price (Stripe's `price_data`): what a checkout line item or an
+ * invoice item names when it has no stored `price_…`. Per-unit only.
+ */
+export interface PriceDataParams {
+    currency: CurrencyCode;
+    /** The `prod_…` it prices. */
+    product: string;
+    unit_amount: string;
+    recurring?: Omit<RecurringParams, 'usage_type'>;
+    tax_behavior?: PriceTaxBehavior;
+}
+/** `default_price_data` on a product create: `price_data` for the product being created. */
+export type DefaultPriceDataParams = Omit<PriceDataParams, 'product'>;
+export interface CreateProductParams {
+    name: string;
+    active?: boolean;
+    description?: string;
+    images?: string[];
+    metadata?: Record<string, string>;
+    tax_code?: string;
+    /** Create the product's default price with it. */
+    default_price_data?: DefaultPriceDataParams;
+    unit_label?: string;
+    url?: string;
+    statement_descriptor?: string;
+    marketing_features?: ProductMarketingFeature[];
+}
+/** `''` clears an optional text field; `metadata` is merged. */
+export interface UpdateProductParams {
+    name?: string;
+    active?: boolean;
+    description?: string;
+    images?: string[];
+    metadata?: Record<string, string>;
+    tax_code?: string;
+    /** One of this product's active prices; `''` clears it. */
+    default_price?: string;
+    unit_label?: string;
+    url?: string;
+    statement_descriptor?: string;
+    marketing_features?: ProductMarketingFeature[];
+}
+export interface ProductListParams extends ListParams {
+    active?: boolean;
+    /** Only these products (at most 100). */
+    ids?: string[];
+}
+export interface CreatePriceParams {
+    product: string;
+    currency: CurrencyCode;
+    /** Required for `per_unit`; absent for `tiered`. */
+    unit_amount?: string;
+    /** Default `per_unit`. */
+    billing_scheme?: PriceBillingScheme;
+    tiers?: PriceTierParams[];
+    tiers_mode?: PriceTiersMode;
+    transform_quantity?: PriceTransformQuantity;
+    /** Present: a recurring price. Absent: one-time. */
+    recurring?: RecurringParams;
+    /** Default `unspecified`. */
+    tax_behavior?: PriceTaxBehavior;
+    lookup_key?: string;
+    /** Move `lookup_key` here from the price that holds it. */
+    transfer_lookup_key?: boolean;
+    nickname?: string;
+    active?: boolean;
+    metadata?: Record<string, string>;
+}
+export interface UpdatePriceParams {
+    active?: boolean;
+    /** `''` clears it. */
+    nickname?: string;
+    metadata?: Record<string, string>;
+    /** `''` clears it. */
+    lookup_key?: string;
+    transfer_lookup_key?: boolean;
+    /** Only while the price's is `unspecified`. */
+    tax_behavior?: PriceTaxBehavior;
+}
+export interface PriceListParams extends ListParams {
+    product?: string;
+    active?: boolean;
+    type?: PriceType;
+    currency?: CurrencyCode;
+    /** At most 10. */
+    lookup_keys?: string[];
+    recurring?: {
+        interval?: RecurringInterval;
+        usage_type?: RecurringUsageType;
+    };
+}
+export interface CreateCouponParams {
+    /** Your own id (`SUMMER25`); generated (`coupon_…`) when absent. */
+    id?: string;
+    name?: string;
+    percent_off?: number;
+    amount_off?: string;
+    /** Required with `amount_off`. */
+    currency?: CurrencyCode;
+    /** Default `once`. */
+    duration?: CouponDuration;
+    /** Required for `repeating`. */
+    duration_in_months?: number;
+    max_redemptions?: number;
+    /** Unix seconds, in the future. */
+    redeem_by?: number;
+    applies_to?: {
+        products: string[];
+    };
+    metadata?: Record<string, string>;
+}
+export interface UpdateCouponParams {
+    /** `''` clears it. */
+    name?: string;
+    metadata?: Record<string, string>;
+}
+export interface CreatePromotionCodeParams {
+    coupon: string;
+    /** Letters and digits; generated when absent. */
+    code?: string;
+    /** Only this customer (`cus_…`) may redeem it. */
+    customer?: string;
+    active?: boolean;
+    max_redemptions?: number;
+    expires_at?: number;
+    restrictions?: {
+        first_time_transaction?: boolean;
+        minimum_amount?: string;
+        minimum_amount_currency?: CurrencyCode;
+    };
+    metadata?: Record<string, string>;
+}
+export interface UpdatePromotionCodeParams {
+    active?: boolean;
+    metadata?: Record<string, string>;
+}
+export interface PromotionCodeListParams extends ListParams {
+    /** Case-insensitive. */
+    code?: string;
+    coupon?: string;
+    customer?: string;
+    active?: boolean;
+}
+export type CouponListParams = ListParams;

package/dist/types/event.d.ts

@@ -1,4 +1,5 @@
 import type { Charge } from './charge';
+import type { Coupon, Price, Product, PromotionCode } from './catalog';
 import type { Customer } from './customer';
 import type { Dispute } from './dispute';
 import type { PaymentIntent } from './paymentIntent';
@@ -72,6 +73,26 @@ export interface WebhookEventPayload {
     'setup_intent.succeeded': SetupIntent;
     'setup_intent.setup_failed': SetupIntent;
     'setup_intent.canceled': SetupIntent;
+    /**
+     * The catalog (ADR 0018): each create, update and delete of a product,
+     * price, coupon or promotion code, carrying the object as it stands after
+     * the change (a deleted one as it stood before). An update names the moved
+     * fields in `data.previous_attributes`; an update that moved nothing records
+     * no event. Prices and promotion codes are never deleted — they are archived
+     * with `active: false` — so there is no `price.deleted` or
+     * `promotion_code.deleted`: a type that can never be sent is a promise the
+     * catalog cannot keep.
+     */
+    'product.created': Product;
+    'product.updated': Product;
+    'product.deleted': Product;
+    'price.created': Price;
+    'price.updated': Price;
+    'coupon.created': Coupon;
+    'coupon.updated': Coupon;
+    'coupon.deleted': Coupon;
+    'promotion_code.created': PromotionCode;
+    'promotion_code.updated': PromotionCode;
     /**
      * A seller's account changed — their READINESS, in practice. Emitted when the
      * fields a merchant ACTS on change, not on every refresh. It names no payment

package/dist/types/index.d.ts

@@ -8,9 +8,12 @@ export type { AttachPaymentMethodParams, BillingDetails, PaymentMethod, UpdatePa
 export { type CancelSetupIntentParams, type CreateSetupIntentParams, type SetupIntent, type SetupIntentCancellationReason, type SetupIntentStatus, type SetupIntentUsage, SETUP_INTENT_STATUSES, } from './setupIntent';
 export { PEABLE_API_VERSION, type WebhookEventType, type WebhookEvent, type WebhookEventPayload, type WebhookEventRequest, type BillingObservation, } from './event';
 export { WEBHOOK_ENDPOINT_STATUSES, WEBHOOK_ENDPOINT_DISABLED_REASONS, WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT, WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS, type WebhookEnabledEvent, type WebhookEndpoint, type WebhookEndpointStatus, type WebhookEndpointDisabledReason, type DeletedWebhookEndpoint, type CreateWebhookEndpointParams, type UpdateWebhookEndpointParams, type RollWebhookEndpointSecretParams, } from './webhookEndpoint';
+export { PRICE_BILLING_SCHEMES, PRICE_TIERS_MODES, PRICE_TYPES, RECURRING_INTERVALS, RECURRING_USAGE_TYPES, PRICE_TAX_BEHAVIORS, TRANSFORM_QUANTITY_ROUNDS, COUPON_DURATIONS, CATALOG_LIMITS, type PriceBillingScheme, type PriceTiersMode, type PriceType, type RecurringInterval, type RecurringUsageType, type PriceTaxBehavior, type TransformQuantityRound, type CouponDuration, type ProductMarketingFeature, type Product, type DeletedProduct, type PriceTier, type PriceTransformQuantity, type PriceRecurring, type Price, type Coupon, type DeletedCoupon, type PromotionCodeRestrictions, type PromotionCode, type RecurringParams, type PriceTierParams, type PriceDataParams, type DefaultPriceDataParams, type CreateProductParams, type UpdateProductParams, type ProductListParams, type CreatePriceParams, type UpdatePriceParams, type PriceListParams, type CreateCouponParams, type UpdateCouponParams, type CouponListParams, type CreatePromotionCodeParams, type UpdatePromotionCodeParams, type PromotionCodeListParams, } from './catalog';
 export type { Dispute, DisputeEvidence, DisputeStatus } from './dispute';
 export type { CapabilityStatus, ConnectedAccount, ConnectedAccountFaircoin, ConnectedAccountFaircoinStatus, ConnectedAccountRail, Refund, RefundOrigin, RefundStatus, Settlement, Transfer, TransferReversal, TransferReversalStatus, TransferStatus, TransferWithReversal, } from './settlement';
 export type { WebhookDelivery, WebhookDeliveryStatus, } from './webhookDelivery';
+export { REQUEST_LOG_METHODS, REQUEST_LOG_RETENTION_DAYS, type RequestLog, type RequestLogListParams, type RequestLogMethod, type RequestLogStatusFilter, } from './requestLog';
+export { SIMULATED_FAIRCOIN_OUTCOMES, type SimulatedFaircoinOutcome, type SimulateFaircoinPaymentParams, } from './testHelpers';
 export { signWebhook, verifyWebhook } from './webhookSigner';
 export { type MerchantEnvironment, type Merchant, MERCHANT_ENVIRONMENTS, } from './merchant';
 export type { MerchantDisplay } from './merchantDisplay';

package/dist/types/requestLog.d.ts

@@ -0,0 +1,40 @@
+import type { ListParams } from './list';
+/**
+ * One merchant API request, as Peable recorded it (`req_…`) — the request log
+ * Orbit and `peable logs tail` read.
+ *
+ * Its `id` IS the `Request-Id` that request was answered with, so the id a
+ * merchant quotes to support and the log row are the same thing.
+ *
+ * Deliberately thin: method, path (no query string), status, duration and the
+ * `Idempotency-Key` it carried. No body, no headers, no query string, no
+ * caller address — a log a merchant can read is a log that must not hold what
+ * a request carried. Kept 30 days.
+ */
+export declare const REQUEST_LOG_METHODS: readonly ["GET", "POST", "DELETE", "PATCH", "PUT"];
+export type RequestLogMethod = (typeof REQUEST_LOG_METHODS)[number];
+export interface RequestLog {
+    /** The request's `Request-Id` (`req_…`). */
+    id: string;
+    object: 'request_log';
+    livemode: boolean;
+    method: RequestLogMethod;
+    /** The path that was requested, without its query string. */
+    path: string;
+    /** The HTTP status it was answered with. */
+    status: number;
+    /** How long the gateway took to answer, in milliseconds. */
+    duration_ms: number;
+    /** The `Idempotency-Key` the request carried, if it carried a valid one. */
+    idempotency_key: string | null;
+    /** When it was answered, Unix seconds. */
+    created: number;
+}
+/** `status`: one code (`404`) or a class (`2xx`, `4xx`, `5xx`). */
+export type RequestLogStatusFilter = number | '2xx' | '3xx' | '4xx' | '5xx';
+export interface RequestLogListParams extends ListParams {
+    status?: RequestLogStatusFilter;
+    method?: RequestLogMethod;
+}
+/** How long a request log is kept (and served). */
+export declare const REQUEST_LOG_RETENTION_DAYS = 30;

package/dist/types/testHelpers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Test helpers (`/v1/test_helpers/*`) — test mode only.
+ *
+ * They drive a test-mode object through the SAME state machine a real payment
+ * moves through, so a merchant can exercise their integration end to end
+ * without a wallet or a card: every transition a helper makes is one the
+ * gateway would make, with the same events and webhooks.
+ */
+/**
+ * What `simulate_faircoin_payment` pretends the payer did.
+ *
+ *  - `settled`   — paid the full amount, which is then seen in the mempool and
+ *    confirmed: `broadcast → confirming → settled`
+ *    (`payment_intent.confirming`, then `payment_intent.settled`).
+ *  - `underpaid` — sent less than the amount: `broadcast → failed`
+ *    (`payment_intent.failed`).
+ */
+export declare const SIMULATED_FAIRCOIN_OUTCOMES: readonly ["settled", "underpaid"];
+export type SimulatedFaircoinOutcome = (typeof SIMULATED_FAIRCOIN_OUTCOMES)[number];
+export interface SimulateFaircoinPaymentParams {
+    /** Default `settled`. */
+    outcome?: SimulatedFaircoinOutcome;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/shared-types",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Shared TypeScript types for the Peable Gateway — the wire contract shared by the backend, SDK, and frontend.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",