@stripe/extensibility-sdk 0.24.1 → 0.25.0

package/README.md

@@ -0,0 +1,355 @@
+# @stripe/extensibility-sdk
+
+Runtime SDK for Stripe script extensions. Provides TypeScript extension interfaces, a
+Stripe-safe arbitrary-precision `Decimal` type, scalar primitives, and the wire-format
+transformation framework used by the platform dispatcher.
+
+---
+
+## Subpath exports
+
+| Import path                               | Use for                                          |
+| ----------------------------------------- | ------------------------------------------------ |
+| `@stripe/extensibility-sdk/extensions`    | Implementing extension interfaces                |
+| `@stripe/extensibility-sdk/stdlib`        | `Decimal`, scalar types, `Ref`, wire errors      |
+| `@stripe/extensibility-sdk/internal`      | Internal registry metadata (used by build tools) |
+| `@stripe/extensibility-sdk/jsonschema`    | JSON Schema types and helpers                    |
+| `@stripe/extensibility-sdk/config-values` | Configuration value types and helpers            |
+
+---
+
+## Extension interfaces
+
+Each extension interface is a TypeScript interface your default-export class must implement.
+The `Config` type parameter is the shape of your extension's configuration object.
+
+### Billing
+
+#### `Billing.Bill.DiscountCalculation`
+
+Computes discounts applied to a bill.
+
+```typescript
+import type { Billing, Context } from '@stripe/extensibility-sdk/extensions';
+
+interface MyConfig extends Record<string, unknown> {
+  maxDiscountPercent: number;
+}
+
+export default class MyExtension implements Billing.Bill.DiscountCalculation<MyConfig> {
+  computeDiscounts(
+    request: Billing.Bill.DiscountCalculation.DiscountableItem,
+    config: MyConfig,
+    context: Context
+  ): Billing.Bill.DiscountCalculation.DiscountResult {
+    const { grossAmount } = request;
+    const discountAmount = grossAmount.amount
+      .mul(config.maxDiscountPercent)
+      .div(100, 8, 'half-even');
+    return {
+      discount: {
+        amount: { amount: discountAmount, currency: grossAmount.currency },
+      },
+    };
+  }
+}
+```
+
+Key types in the `Billing.Bill.DiscountCalculation` namespace:
+
+| Type               | Description                                                               |
+| ------------------ | ------------------------------------------------------------------------- |
+| `DiscountableItem` | Request: line items, gross amount, customer, billing reason, subscription |
+| `DiscountResult`   | Response: discount with `MonetaryAmount`                                  |
+| `LineItem`         | A single line with subtotal, quantity, price, period                      |
+| `Price`            | Price with scheme, tiers, recurring config                                |
+| `BillingReason`    | Enum: `'subscription_cycle'`, `'manual'`, etc.                            |
+| `AnyTimeRange`     | Discriminated union: `oneTime` \| `timeRange`                             |
+| `MonetaryAmount`   | `{ amount: Decimal; currency: Currency }`                                 |
+
+---
+
+#### `Billing.CustomerBalanceApplication`
+
+Computes how much of a customer's credit balance to apply to a bill.
+
+```typescript
+import type { Billing, Context } from '@stripe/extensibility-sdk/extensions';
+
+export default class MyExtension implements Billing.CustomerBalanceApplication<
+  Record<string, unknown>
+> {
+  computeAppliedCustomerBalance(
+    request: Billing.CustomerBalanceApplication.CustomerBalanceApplicationInput,
+    _config: Record<string, unknown>,
+    _context: Context
+  ): Billing.CustomerBalanceApplication.CustomerBalanceApplicationResult {
+    // Apply at most 50% of the bill total from the customer balance
+    const halfTotal = request.totalAmount.amount.div(2, 8, 'half-even');
+    const applied = request.customerBalance.amount.lt(halfTotal)
+      ? request.customerBalance.amount
+      : halfTotal;
+    return {
+      appliedCustomerBalance: { amount: applied, currency: request.totalAmount.currency },
+    };
+  }
+}
+```
+
+Key types:
+
+| Type                               | Description                                                        |
+| ---------------------------------- | ------------------------------------------------------------------ |
+| `CustomerBalanceApplicationInput`  | `{ totalAmount: MonetaryAmount; customerBalance: MonetaryAmount }` |
+| `CustomerBalanceApplicationResult` | `{ appliedCustomerBalance: MonetaryAmount }`                       |
+
+---
+
+#### `Billing.InvoiceCollectionSetting`
+
+Overrides collection settings (payment method, auto-advance, etc.) for an invoice.
+
+```typescript
+import type { Billing, Context } from '@stripe/extensibility-sdk/extensions';
+
+export default class MyExtension implements Billing.InvoiceCollectionSetting<
+  Record<string, unknown>
+> {
+  collectionOverride(
+    request: Billing.InvoiceCollectionSetting.InvoiceCollectionRequest,
+    _config: Record<string, unknown>,
+    _context: Context
+  ): Billing.InvoiceCollectionSetting.InvoiceCollectionResponse {
+    const isSubscription = request.parent.type === 'subscription';
+    return {
+      autoAdvance: isSubscription,
+    };
+  }
+}
+```
+
+Key types:
+
+| Type                        | Description                                                                                                         |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `InvoiceCollectionRequest`  | Request: collection settings, parent, customer                                                                      |
+| `InvoiceCollectionResponse` | Response: optional `autoAdvance` override                                                                           |
+| `CollectionSettings`        | Current settings with `autoAdvance`, `collectionMethod`, `paymentMethods`                                           |
+| `ParentType`                | `'subscription'` \| `'contract'` \| `'quote'` \| `'billing_cadence'` \| `'subscription_schedule'` \| `'standalone'` |
+| `CollectionMethod`          | `'charge_automatically'` \| `'send_invoice'`                                                                        |
+| `PaymentMethodType`         | `'card'` \| `'sepa_debit'` \| …                                                                                     |
+
+---
+
+#### `Billing.Prorations`
+
+Computes proration adjustments when subscription items change mid-period.
+
+```typescript
+import type { Billing, Context } from '@stripe/extensibility-sdk/extensions';
+
+export default class MyExtension implements Billing.Prorations<Record<string, unknown>> {
+  prorateItems(
+    request: Billing.Prorations.ProrateItemsInput,
+    _config: Record<string, unknown>,
+    _context: Context
+  ): Billing.Prorations.ProrateItemsResult {
+    return {
+      items: request.items.map((item) => ({
+        key: item.key,
+        prorationFactor: item.currentProrationFactor,
+        lineItemPeriod: item.servicePeriod,
+      })),
+    };
+  }
+}
+```
+
+Key types:
+
+| Type                 | Description                                                       |
+| -------------------- | ----------------------------------------------------------------- |
+| `ProrateItemsInput`  | `{ items: ProratableItem[] }`                                     |
+| `ProrateItemsResult` | `{ items: ProratedItem[] }`                                       |
+| `ProratableItem`     | Line item with key, type, price, proration factor, service period |
+| `ProratedItem`       | Output: key, proration factor, line item period                   |
+| `ItemType`           | `'credit'` \| `'debit'`                                           |
+
+---
+
+### Core
+
+#### `Core.Workflows.CustomAction`
+
+Implements a custom action callable from Stripe workflows. `execute` is required;
+`getFormState` is optional and drives dynamic form rendering.
+
+```typescript
+import type { Core, Context } from '@stripe/extensibility-sdk/extensions';
+
+interface MyConfig extends Record<string, unknown> {
+  webhookEndpoint: string;
+  webhookPath: string;
+}
+
+export default class MyExtension implements Core.Workflows.CustomAction<MyConfig> {
+  async execute(
+    request: Core.Workflows.CustomAction.ExecuteCustomActionRequest,
+    config: MyConfig,
+    _context: Context
+  ): Promise<Core.Workflows.CustomAction.ExecuteCustomActionResponse> {
+    const { customInput } = request;
+
+    await endpointFetch({
+      endpoint: config.webhookEndpoint,
+      path: config.webhookPath,
+      method: 'POST',
+      body: JSON.stringify(customInput),
+    });
+
+    return {};
+  }
+
+  async getFormState(
+    request: Core.Workflows.CustomAction.GetFormStateRequest,
+    _config: MyConfig,
+    _context: Context
+  ): Promise<Core.Workflows.CustomAction.GetFormStateResponse> {
+    return { values: request.values, config: {} };
+  }
+}
+```
+
+Key types:
+
+| Type                          | Description                                                            |
+| ----------------------------- | ---------------------------------------------------------------------- |
+| `ExecuteCustomActionRequest`  | `{ customInput: Record<string, unknown> }`                             |
+| `ExecuteCustomActionResponse` | `Record<string, never>` (empty object)                                 |
+| `GetFormStateRequest`         | `{ values: Record<string, unknown>; changedField?: string }`           |
+| `GetFormStateResponse`        | `{ values: Record<string, unknown>; config: Record<string, unknown> }` |
+
+Both `execute` and `getFormState` may return synchronously or as `Promise`.
+
+---
+
+### Context
+
+Every extension method receives a `Context` as its third argument:
+
+```typescript
+import type { Context } from '@stripe/extensibility-sdk/extensions';
+
+function handleContext(context: Context) {
+  console.log(context.type); // e.g. "core.workflows.custom_workflow_action"
+  console.log(context.id); // unique call ID, for debugging
+  console.log(context.livemode);
+  console.log(context.stripeContext); // set for cross-account calls
+  console.log(context.clockTime); // optional SDK-provided clock timestamp
+}
+```
+
+---
+
+## Stdlib
+
+### `Decimal`
+
+Arbitrary-precision decimal arithmetic backed by `big.js`. All monetary values in
+extension interface requests and responses use `Decimal`.
+
+```typescript
+import { Decimal } from '@stripe/extensibility-sdk/stdlib';
+
+const a = Decimal.from('10.50');
+const b = Decimal.from(3);
+
+a.add(b); // Decimal('13.50')
+a.sub(b); // Decimal('7.50')
+a.mul(b); // Decimal('31.50')
+a.div(b, 8, 'half-even'); // Decimal('3.50000000')
+
+a.round({ precision: 2, direction: 'half-even' }); // Decimal('10.50')
+a.round('penny'); // Decimal('10.50') — preset shorthand
+
+a.eq(Decimal.from('10.50')); // true
+a.lt(b); // false
+a.lte(b); // false
+a.gt(b); // true
+a.gte(b); // true
+
+a.toString(); // '10.50'
+a.toFixed(4, 'half-even'); // '10.5000'
+```
+
+**Rounding directions:** `'ceil'` · `'floor'` · `'round-down'` · `'round-up'` ·
+`'half-up'` · `'half-down'` · `'half-even'`
+
+**Rounding presets:** `'penny'` (2 dp, `half-even`) · `'dollar'` (0 dp, `half-even`)
+
+`div()` and `toFixed()` always require an explicit precision and rounding direction —
+there are no implicit defaults to prevent silent precision loss.
+
+---
+
+### Scalar types
+
+| Type              | Description                | Constructor                          |
+| ----------------- | -------------------------- | ------------------------------------ |
+| `Integer`         | Whole number (no decimals) | `Integer.from(n, direction)`         |
+| `PositiveInteger` | Non-negative integer (≥ 0) | `PositiveInteger.from(n, direction)` |
+| `Timestamp`       | ISO 8601 datetime string   | `Timestamp.create(s)`                |
+| `StreetAddress`   | Non-empty string           | `StreetAddress.create(s)`            |
+
+These are branded types — they carry a compile-time brand so TypeScript rejects raw
+`number` or `string` where the stricter type is required.
+
+```typescript
+import { Integer, PositiveInteger, Timestamp } from '@stripe/extensibility-sdk/stdlib';
+
+const count = Integer.from(42, 'round-down'); // Integer
+const qty = PositiveInteger.from(3, 'round-down'); // PositiveInteger
+const ts = Timestamp.create('2024-01-15T00:00:00.000Z'); // Timestamp
+```
+
+---
+
+### `Ref`
+
+A typed reference to a Stripe object (ID + optional resolved value).
+
+```typescript
+import { Ref } from '@stripe/extensibility-sdk/stdlib';
+
+type CustomerRef = Ref<{ id: string; name: string }>;
+```
+
+---
+
+### Wire errors
+
+Thrown by the platform dispatch wrapper when wire-format data is invalid.
+
+| Class            | When thrown                                               |
+| ---------------- | --------------------------------------------------------- |
+| `WireReadError`  | Invalid or missing field in the **incoming** wire request |
+| `WireWriteError` | Invalid or missing field in the **outgoing** SDK response |
+
+```typescript
+import { WireReadError, WireWriteError } from '@stripe/extensibility-sdk/stdlib';
+```
+
+In production, the platform catches and surfaces these as structured errors. In tests,
+assert against them directly by invoking the generated interface-specific
+`$platformWrap...` helper for the interface under test. For example:
+
+```typescript
+// Pseudocode: replace `$platformWrap...` with the generated wrapper for your interface.
+expect(() => $platformWrap...(MyImpl, badInput, {}, ctx)).toThrow(WireReadError);
+```
+
+---
+
+## License
+
+MIT

package/dist/config-values/generate.d.ts

@@ -2,6 +2,8 @@
  * Emits TypeScript code for a config field descriptor constant and its
  * corresponding `transformX` function.
  *
+ * @deprecated Import from `@stripe/extensibility-sdk` instead.
+ *
  * @see ./parse.ts — produces the ConfigAnalysisResult input
  */
 import type { ConfigAnalysisResult } from './parse.js';

package/dist/config-values/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/config-values/generate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAuB,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAG5E,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,6BAA6B,GACnC,MAAM,YAAY,CAAC;AAMpB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC,6DAA6D;IAC7D,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,oBAAoB,GAC3B,yBAAyB,CA8C3B"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/config-values/generate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAuB,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAG5E,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,6BAA6B,GACnC,MAAM,YAAY,CAAC;AAMpB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC,6DAA6D;IAC7D,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,oBAAoB,GAC3B,yBAAyB,CA8C3B"}

package/dist/extensibility-sdk-alpha.d.ts

@@ -12,32 +12,52 @@
 import { __integerBrand } from '@formspec/core';
 
 /**
- * Opaque brand symbol used as a property key in SDK branded types.
+ * Opaque brand key used as a property key in SDK branded types.
  *
  * @remarks
  * You do not need to use this directly — it is already embedded in
- * branded values returned by factory functions like {@link (Integer:type)}.create().
- * The `unique symbol` key makes the brand non-enumerable and impossible
- * to forge without access to this symbol.
+ * branded values returned by factory functions like {@link (Integer:type)}.from().
+ *
+ * String-literal const (not `unique symbol`) so that independent
+ * declaration rollups (root vs subpath) produce structurally compatible
+ * branded types.
  *
  * @public
  */
-export declare const __brand: unique symbol;
+export declare const __brand: '__brand';
 
 /* Excluded from this release type: __decimalBrand */
 
-/* Excluded from this release type: __positiveIntegerBrand */
+/**
+ * Distinct brand key for PositiveInteger so an Integer is not assignable to
+ * PositiveInteger without going through the guard. PositiveInteger is a
+ * subtype of Integer (it carries both brands), so it can be used wherever
+ * Integer is expected.
+ *
+ * String-literal const (not `unique symbol`) so that independent
+ * declaration rollups (root vs subpath) produce structurally compatible
+ * branded types.
+ *
+ * For internal use only — may be removed in a future release.
+ *
+ * @public
+ */
+export declare const __positiveIntegerBrand: '__positiveIntegerBrand';
 
 /**
- * Opaque type-tag symbol used by SDK scalar types to carry Stripe type metadata.
+ * Opaque type-tag key used by SDK scalar types to carry Stripe type metadata.
  *
  * @remarks
  * You do not need to use this directly — it is already embedded in
- * branded values returned by factory functions like {@link (Integer:type)}.create().
+ * branded values returned by factory functions like {@link (Integer:type)}.from().
+ *
+ * String-literal const (not `unique symbol`) so that independent
+ * declaration rollups (root vs subpath) produce structurally compatible
+ * branded types.
  *
  * @public
  */
-export declare const __stripeType: unique symbol;
+export declare const __stripeType: '__stripeType';
 
 /** @public */
 declare type AnyTimeRange = {
@@ -84,7 +104,7 @@ declare namespace Billing {
 }
 export { Billing }
 
-/** The type of the opaque brand symbol used as a property key in SDK branded types. @public */
+/** The type of the opaque brand key used as a property key in SDK branded types. @public */
 export declare type BrandSymbol = typeof __brand;
 
 /* Excluded from this release type: _configAppContextFromContext */
@@ -489,59 +509,59 @@ declare interface CustomerBalanceApplication<Config> {
  * @public
  */
 export declare interface Decimal {
-    /* Excluded from this release type: [__brand] */
-    /* Excluded from this release type: [__decimalBrand] */
-    /* Excluded from this release type: [__stripeType] */
+    /* Excluded from this release type: __brand */
+    /* Excluded from this release type: __decimalBrand */
+    /* Excluded from this release type: __stripeType */
     /**
      * Return the sum of this value and `other`.
      * @public
      */
-    add(other: Decimal): Decimal;
+    add(other: DecimalLike): Decimal;
     /**
      * Return the difference of this value and `other`.
      * @public
      */
-    sub(other: Decimal): Decimal;
+    sub(other: DecimalLike): Decimal;
     /**
      * Return the product of this value and `other`.
      * @public
      */
-    mul(other: Decimal): Decimal;
+    mul(other: DecimalLike): Decimal;
     /**
      * Return the quotient of this value divided by `other`.
      * @public
      */
-    div(other: Decimal, precision: number, direction: RoundDirection): Decimal;
+    div(other: DecimalLike, precision: number, direction: RoundDirection): Decimal;
     /**
      * Three-way comparison: returns `-1`, `0`, or `1`.
      * @public
      */
-    cmp(other: Decimal): -1 | 0 | 1;
+    cmp(other: DecimalLike): -1 | 0 | 1;
     /**
      * Return `true` if this value is numerically equal to `other`.
      * @public
      */
-    eq(other: Decimal): boolean;
+    eq(other: DecimalLike): boolean;
     /**
      * Return `true` if this value is strictly less than `other`.
      * @public
      */
-    lt(other: Decimal): boolean;
+    lt(other: DecimalLike): boolean;
     /**
      * Return `true` if this value is less than or equal to `other`.
      * @public
      */
-    lte(other: Decimal): boolean;
+    lte(other: DecimalLike): boolean;
     /**
      * Return `true` if this value is strictly greater than `other`.
      * @public
      */
-    gt(other: Decimal): boolean;
+    gt(other: DecimalLike): boolean;
     /**
      * Return `true` if this value is greater than or equal to `other`.
      * @public
      */
-    gte(other: Decimal): boolean;
+    gte(other: DecimalLike): boolean;
     /**
      * Return `true` if this value is exactly zero.
      * @public
@@ -592,6 +612,11 @@ export declare interface Decimal {
      * @public
      */
     toFixed(decimalPlaces: number, direction: RoundDirection): string;
+    /**
+     * Convert to an {@link (Integer:type)} by rounding.
+     * @public
+     */
+    toInteger(direction: RoundDirection): Integer;
     /**
      * Rejects implicit coercion; explicit `String(d)` and template literals still work.
      * @public
@@ -609,10 +634,31 @@ export declare interface Decimal {
  *
  * @public
  */
-export declare const Decimal: {
-    from(value: bigint | number | string): Decimal;
-    zero: Decimal;
-};
+export declare const Decimal: DecimalCompanion;
+
+/** @public */
+export declare interface DecimalCompanion {
+    /** Type guard: narrows `unknown` to `Decimal`. @public */
+    is(value: unknown): value is Decimal;
+    /** Assertion guard: throws if not a `Decimal`. @public */
+    assert(value: unknown): asserts value is Decimal;
+    /** Create a Decimal from a {@link DecimalLike} value. @public */
+    from(value: DecimalLike): Decimal;
+    /** The Decimal value `0`. @public */
+    readonly zero: Decimal;
+}
+
+/**
+ * Values that can be coerced to a `Decimal` via `Decimal.from()`.
+ *
+ * @remarks
+ * This union is accepted by `Decimal.from()` and by all arithmetic and
+ * comparison methods on `Decimal` instances. Non-Decimal values are
+ * coerced via `Decimal.from()` before the operation.
+ *
+ * @public
+ */
+export declare type DecimalLike = bigint | Decimal | Integer | number | string;
 
 /**
  * Precision specification for `Decimal.round()`.
@@ -670,6 +716,18 @@ export declare const DecimalRoundingPresets: Readonly<{
     }>;
 }>;
 
+/**
+ * Recursively converts a type to a deeply-readonly version.
+ *
+ * Primitive types (`string`, `number`, `boolean`, `bigint`, `symbol`,
+ * `undefined`, `null`) are returned as-is. Arrays become `readonly` arrays
+ * of deeply-readonly elements. Object types have each property marked
+ * `readonly`, and the type of each property is recursively transformed.
+ *
+ * @public
+ */
+export declare type DeepReadonly<T> = T extends bigint | boolean | null | number | string | symbol | undefined ? T : T extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;
+
 /**
  * The IEEE 754 decimal128 coefficient size (34 digits) — the recommended
  * precision for `Decimal.div()` when full precision is desired.
@@ -937,11 +995,26 @@ export declare type Integer = {
     readonly [__stripeType]: 'int';
 } & number;
 
-/** Factory and type guard for {@link (Integer:type)} branded values. @public */
-export declare const Integer: {
-    from: (value: number, rounding: IntegerRoundDirection) => Integer;
-    is: (value: number) => value is Integer;
-};
+/** Factory, type guard, and utilities for {@link (Integer:type)} branded values. @public */
+export declare const Integer: IntegerCompanion;
+
+/** @public */
+export declare interface IntegerCompanion {
+    /** The Integer value `0`. @public */
+    readonly zero: Integer;
+    /** Type guard: narrows `unknown` to {@link (Integer:type)}. @public */
+    is(value: unknown): value is Integer;
+    /** Assertion guard: throws if not an {@link (Integer:type)}. @public */
+    assert(value: unknown): asserts value is Integer;
+    /** Coerce a value to {@link (Integer:type)} by rounding. @public */
+    from(value: Decimal | Integer | number | string, rounding: IntegerRoundDirection): Integer;
+    /** Lossless conversion to `Decimal`. @public */
+    toDecimal(value: Integer): Decimal;
+    /** Type guard: narrows {@link (Integer:type)} to {@link (PositiveInteger:type)}. @public */
+    isPositive(value: Integer): value is PositiveInteger;
+    /** Assertion guard: throws if the Integer is negative. @public */
+    assertIsPositive(value: Integer): asserts value is PositiveInteger;
+}
 
 /**
  * Rounding directions for coercing a number to an integer.
@@ -1154,11 +1227,18 @@ export declare type PositiveInteger = {
     readonly [__stripeType]: 'int';
 } & number;
 
-/** Factory and type guard for {@link (PositiveInteger:type)} branded values. @public */
-export declare const PositiveInteger: {
-    from: (value: number, rounding: IntegerRoundDirection) => PositiveInteger;
-    is: (value: number) => value is PositiveInteger;
-};
+/** Factory, type guard, and utilities for {@link (PositiveInteger:type)} branded values. @public */
+export declare const PositiveInteger: PositiveIntegerCompanion;
+
+/** @public */
+export declare interface PositiveIntegerCompanion {
+    /** Type guard: narrows `unknown` to {@link (PositiveInteger:type)}. @public */
+    is(value: unknown): value is PositiveInteger;
+    /** Assertion guard: throws if not a {@link (PositiveInteger:type)}. @public */
+    assert(value: unknown): asserts value is PositiveInteger;
+    /** Coerce a value to {@link (PositiveInteger:type)} by rounding. Throws if negative. @public */
+    from(value: Decimal | Integer | number | string, rounding: IntegerRoundDirection): PositiveInteger;
+}
 
 /** @public */
 declare namespace Prorations {
@@ -1745,7 +1825,7 @@ export declare type StreetAddress = {
 /** Factory for creating {@link (StreetAddress:type)} branded values. @public */
 export declare const StreetAddress: { create: (address: string) => StreetAddress };
 
-/** The type of the opaque Stripe type-tag symbol used in SDK scalar types. @public */
+/** The type of the opaque Stripe type-tag key used in SDK scalar types. @public */
 export declare type StripeTypeSymbol = typeof __stripeType;
 
 /**
@@ -1768,6 +1848,28 @@ export declare type Timestamp = {
 /** Factory for creating {@link (Timestamp:type)} branded values. @public */
 export declare const Timestamp: { create: (value: string) => Timestamp };
 
+/**
+ * Deep-freezes `value` and returns it typed as {@link DeepReadonly}`<T>`.
+ *
+ * Use this helper for module-scoped constant objects and arrays to satisfy
+ * the `dsl/no-module-scoped-mutable-const` lint rule. Unlike `Object.freeze`,
+ * which is shallow, `toConst` recursively freezes all nested objects and arrays.
+ *
+ * @example
+ * ```typescript
+ * import { toConst } from '@stripe/extensibility-sdk/stdlib';
+ *
+ * const DEFAULTS = toConst({ timeout: 30, retries: 3 });
+ * // Type: { readonly timeout: 30; readonly retries: 3 }
+ *
+ * const STATUSES = toConst(['active', 'pending', 'cancelled']);
+ * // Type: readonly ["active", "pending", "cancelled"]
+ * ```
+ *
+ * @public
+ */
+export declare function toConst<T>(value: T): DeepReadonly<T>;
+
 /* Excluded from this release type: _translateArray */
 
 /* Excluded from this release type: _translateDateTime */