@stripe/extensibility-sdk 0.24.0 → 0.25.0

package/dist/extensibility-sdk-stdlib-beta.d.ts

@@ -1,32 +1,57 @@
+/**
+ * @deprecated Import from `@stripe/extensibility-sdk` instead.
+ * @packageDocumentation
+ */
+
 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';
 
 /* Excluded from this release type: _apply */
 
@@ -38,7 +63,7 @@ export declare const __stripeType: unique symbol;
 
 /* Excluded from this release type: _ApplyStrategy */
 
-/** 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 */
@@ -82,59 +107,59 @@ export declare type Currency = 'aed' | 'afn' | 'all' | 'amd' | 'ang' | 'aoa' | '
  * @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
@@ -185,6 +210,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
@@ -202,10 +232,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()`.
@@ -263,6 +314,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.
@@ -303,11 +366,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.
@@ -390,11 +468,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;
+}
 
 /* Excluded from this release type: _ProtoEnum */
 
@@ -468,7 +553,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;
 
 /** A branded string representing an ISO 8601 datetime. @public */
@@ -480,6 +565,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 */

package/dist/extensibility-sdk-stdlib-internal.d.ts

@@ -1,48 +1,70 @@
+/**
+ * @deprecated Import from `@stripe/extensibility-sdk` instead.
+ * @packageDocumentation
+ */
+
 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';
 
 /**
- * Unique brand symbol for the {@link Decimal} type.
+ * Unique brand key for the `Decimal` type.
  *
- * Using a dedicated symbol (rather than the shared `__brand`) lets formspec's
+ * Using a dedicated key (rather than the shared `__brand`) lets formspec's
  * structural brand-detection distinguish `Decimal` from other SDK branded
  * types (e.g., `Ref`, `StreetAddress`) that also carry `[__brand]`.
  *
+ * String-literal const (not `unique symbol`) so that independent
+ * declaration rollups (root vs subpath) produce structurally compatible
+ * branded types.
+ *
  * @internal
  */
-declare const __decimalBrand: unique symbol;
+export declare const __decimalBrand: '__decimalBrand';
 
 /**
- * Distinct brand for PositiveInteger so an Integer is not assignable to
+ * 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.
- * @internal
+ *
+ * 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
  */
-declare const __positiveIntegerBrand: unique symbol;
+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';
 
 /**
  * Apply a strategy to a field array, transforming each field.
@@ -113,7 +135,7 @@ export declare interface _ApplyStrategy {
     applyOneofField(typeName: string, oneof: _OneofFieldDescriptor, input: Record<string, unknown>, strategy: _ApplyStrategy, result: Record<string, unknown>, excludeWireKeys: Set<string>): void;
 }
 
-/** 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;
 
 /**
@@ -213,52 +235,52 @@ export declare interface Decimal {
      * 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
@@ -309,6 +331,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
@@ -326,10 +353,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()`.
@@ -387,6 +435,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.
@@ -469,11 +529,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.
@@ -603,11 +678,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;
+}
 
 /**
  * Bidirectional enum spec for proto-backed enums. Accepts a single
@@ -742,7 +824,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;
 
 /** A branded string representing an ISO 8601 datetime. @public */
@@ -754,6 +836,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>;
+
 /**
  * Apply an element transform to each item in an array.
  *