@stripe/extensibility-sdk 0.24.1 → 0.25.0

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

@@ -3,31 +3,55 @@
  * @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
  */
-declare const __brand: unique symbol;
+declare const __brand: '__brand';
 
 /* Excluded from this release type: __decimalBrand */
 
 /**
- * Opaque type-tag symbol used by SDK scalar types to carry Stripe type metadata.
+ * 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
+ */
+declare const __positiveIntegerBrand: '__positiveIntegerBrand';
+
+/**
+ * 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
  */
-declare const __stripeType: unique symbol;
+declare const __stripeType: '__stripeType';
 
 /** @public */
 declare type AnyTimeRange = {
@@ -462,59 +486,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
@@ -565,6 +589,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
@@ -582,10 +611,31 @@ export declare interface Decimal {
  *
  * @public
  */
-export declare const Decimal: {
-    from(value: bigint | number | string): Decimal;
-    zero: Decimal;
-};
+export declare const Decimal: DecimalCompanion;
+
+/** @public */
+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
+ */
+declare type DecimalLike = bigint | Decimal | Integer | number | string;
 
 /**
  * Precision specification for `Decimal.round()`.
@@ -870,6 +920,50 @@ declare namespace Extend {
 }
 export { Extend }
 
+/** A branded integer — a `number` guaranteed to satisfy `Number.isInteger`. @public */
+declare type Integer = {
+    readonly [__integerBrand]: true;
+    readonly [__stripeType]: 'int';
+} & number;
+
+/** Factory, type guard, and utilities for {@link (Integer:type)} branded values. @public */
+declare const Integer: IntegerCompanion;
+
+/** @public */
+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.
+ *
+ * A focused subset of {@link https://standards.ieee.org/ieee/754/6210/ | IEEE 754-2019} §4.3:
+ *
+ * | Direction      | Behavior                     | Examples (→ integer)           |
+ * | -------------- | ---------------------------- | ------------------------------ |
+ * | `'ceil'`       | Toward +∞                    | 1.1→2, -1.1→-1                |
+ * | `'floor'`      | Toward -∞                    | 1.9→1, -1.1→-2                |
+ * | `'round-down'` | Toward zero (truncate)       | 1.9→1, -1.9→-1                |
+ * | `'round-up'`   | Away from zero               | 1.1→2, -1.1→-2                |
+ * | `'half-up'`    | Nearest; ties away from zero | 0.5→1, -0.5→-1, 1.4→1         |
+ *
+ * @public
+ */
+declare type IntegerRoundDirection = 'ceil' | 'floor' | 'half-up' | 'round-down' | 'round-up';
+
 /** @public */
 declare namespace InvoiceCollectionSetting {
     /** @public */
@@ -1012,6 +1106,42 @@ export declare interface Percent {
     value: number;
 }
 
+/**
+ * A branded non-negative integer — a `number` guaranteed to be an integer ≥ 0.
+ *
+ * This is a subtype of {@link (Integer:type)}: every non-negative integer is an
+ * integer, so `PositiveInteger` values are assignable to `Integer` contexts.
+ * The reverse is not true — an `Integer` cannot be assigned where a
+ * `PositiveInteger` is expected without going through the `PositiveInteger.is()`
+ * type guard or `PositiveInteger.from()` factory.
+ *
+ * @remarks
+ * Despite the name, this type includes zero (`>= 0`, not `> 0`).
+ * The schema-level constraint `@minimum 0` should be added to fields
+ * typed as `PositiveInteger` to ensure the non-negativity invariant
+ * is enforced at validation time.
+ *
+ * @public
+ */
+declare type PositiveInteger = {
+    readonly [__integerBrand]: true;
+    readonly [__positiveIntegerBrand]: true;
+    readonly [__stripeType]: 'int';
+} & number;
+
+/** Factory, type guard, and utilities for {@link (PositiveInteger:type)} branded values. @public */
+declare const PositiveInteger: PositiveIntegerCompanion;
+
+/** @public */
+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 {
     /** @public */

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

@@ -3,40 +3,68 @@
  * @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
  */
-declare const __brand: unique symbol;
+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;
+declare const __decimalBrand: '__decimalBrand';
 
 /**
- * Opaque type-tag symbol used by SDK scalar types to carry Stripe type metadata.
+ * 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
+ */
+declare const __positiveIntegerBrand: '__positiveIntegerBrand';
+
+/**
+ * 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
  */
-declare const __stripeType: unique symbol;
+declare const __stripeType: '__stripeType';
 
 /** @public */
 declare type AnyTimeRange = {
@@ -504,52 +532,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
@@ -600,6 +628,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
@@ -617,10 +650,31 @@ export declare interface Decimal {
  *
  * @public
  */
-export declare const Decimal: {
-    from(value: bigint | number | string): Decimal;
-    zero: Decimal;
-};
+export declare const Decimal: DecimalCompanion;
+
+/** @public */
+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
+ */
+declare type DecimalLike = bigint | Decimal | Integer | number | string;
 
 /**
  * Precision specification for `Decimal.round()`.
@@ -906,6 +960,50 @@ declare namespace Extend {
 }
 export { Extend }
 
+/** A branded integer — a `number` guaranteed to satisfy `Number.isInteger`. @public */
+declare type Integer = {
+    readonly [__integerBrand]: true;
+    readonly [__stripeType]: 'int';
+} & number;
+
+/** Factory, type guard, and utilities for {@link (Integer:type)} branded values. @public */
+declare const Integer: IntegerCompanion;
+
+/** @public */
+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.
+ *
+ * A focused subset of {@link https://standards.ieee.org/ieee/754/6210/ | IEEE 754-2019} §4.3:
+ *
+ * | Direction      | Behavior                     | Examples (→ integer)           |
+ * | -------------- | ---------------------------- | ------------------------------ |
+ * | `'ceil'`       | Toward +∞                    | 1.1→2, -1.1→-1                |
+ * | `'floor'`      | Toward -∞                    | 1.9→1, -1.1→-2                |
+ * | `'round-down'` | Toward zero (truncate)       | 1.9→1, -1.9→-1                |
+ * | `'round-up'`   | Away from zero               | 1.1→2, -1.1→-2                |
+ * | `'half-up'`    | Nearest; ties away from zero | 0.5→1, -0.5→-1, 1.4→1         |
+ *
+ * @public
+ */
+declare type IntegerRoundDirection = 'ceil' | 'floor' | 'half-up' | 'round-down' | 'round-up';
+
 /** @public */
 declare namespace InvoiceCollectionSetting {
     /** @public */
@@ -1049,6 +1147,42 @@ export declare interface Percent {
     value: number;
 }
 
+/**
+ * A branded non-negative integer — a `number` guaranteed to be an integer ≥ 0.
+ *
+ * This is a subtype of {@link (Integer:type)}: every non-negative integer is an
+ * integer, so `PositiveInteger` values are assignable to `Integer` contexts.
+ * The reverse is not true — an `Integer` cannot be assigned where a
+ * `PositiveInteger` is expected without going through the `PositiveInteger.is()`
+ * type guard or `PositiveInteger.from()` factory.
+ *
+ * @remarks
+ * Despite the name, this type includes zero (`>= 0`, not `> 0`).
+ * The schema-level constraint `@minimum 0` should be added to fields
+ * typed as `PositiveInteger` to ensure the non-negativity invariant
+ * is enforced at validation time.
+ *
+ * @public
+ */
+declare type PositiveInteger = {
+    readonly [__integerBrand]: true;
+    readonly [__positiveIntegerBrand]: true;
+    readonly [__stripeType]: 'int';
+} & number;
+
+/** Factory, type guard, and utilities for {@link (PositiveInteger:type)} branded values. @public */
+declare const PositiveInteger: PositiveIntegerCompanion;
+
+/** @public */
+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 {
     /** @public */