@stripe/extensibility-sdk 0.25.0 → 0.27.1

package/README.md

@@ -10,8 +10,8 @@ transformation framework used by the platform dispatcher.
 
 | Import path                               | Use for                                          |
 | ----------------------------------------- | ------------------------------------------------ |
+| `@stripe/extensibility-sdk`               | `Decimal`, scalar types, `Ref`, wire errors      |
 | `@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            |
@@ -259,7 +259,7 @@ Arbitrary-precision decimal arithmetic backed by `big.js`. All monetary values i
 extension interface requests and responses use `Decimal`.
 
 ```typescript
-import { Decimal } from '@stripe/extensibility-sdk/stdlib';
+import { Decimal } from '@stripe/extensibility-sdk';
 
 const a = Decimal.from('10.50');
 const b = Decimal.from(3);
@@ -298,18 +298,15 @@ there are no implicit defaults to prevent silent precision loss.
 | ----------------- | -------------------------- | ------------------------------------ |
 | `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';
+import { Integer, PositiveInteger } from '@stripe/extensibility-sdk';
 
 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
 ```
 
 ---
@@ -319,9 +316,10 @@ const ts = Timestamp.create('2024-01-15T00:00:00.000Z'); // Timestamp
 A typed reference to a Stripe object (ID + optional resolved value).
 
 ```typescript
-import { Ref } from '@stripe/extensibility-sdk/stdlib';
+import type { Ref } from '@stripe/extensibility-sdk';
+import type { Customer } from '@stripe/extensibility-api-objects';
 
-type CustomerRef = Ref<{ id: string; name: string }>;
+type CustomerRef = Ref<Customer>;
 ```
 
 ---
@@ -336,7 +334,7 @@ Thrown by the platform dispatch wrapper when wire-format data is invalid.
 | `WireWriteError` | Invalid or missing field in the **outgoing** SDK response |
 
 ```typescript
-import { WireReadError, WireWriteError } from '@stripe/extensibility-sdk/stdlib';
+import { WireReadError, WireWriteError } from '@stripe/extensibility-sdk';
 ```
 
 In production, the platform catches and surfaces these as structured errors. In tests,

package/dist/config-values/generate.cjs

@@ -157,7 +157,7 @@ function isStdlibDecimalType(type) {
     if (symbol?.getName() !== "Decimal") return false;
     return symbol.getDeclarations().some((declaration) => {
       const srcPath = declaration.getSourceFile().getFilePath();
-      return srcPath.includes("stdlib/decimal") || srcPath.includes("stdlib/index");
+      return srcPath.includes("stdlib/decimal") || srcPath.includes("stdlib/index") || srcPath.includes("extensibility-sdk");
     });
   });
 }

package/dist/config-values/generate.js

@@ -128,7 +128,7 @@ function isStdlibDecimalType(type) {
     if (symbol?.getName() !== "Decimal") return false;
     return symbol.getDeclarations().some((declaration) => {
       const srcPath = declaration.getSourceFile().getFilePath();
-      return srcPath.includes("stdlib/decimal") || srcPath.includes("stdlib/index");
+      return srcPath.includes("stdlib/decimal") || srcPath.includes("stdlib/index") || srcPath.includes("extensibility-sdk");
     });
   });
 }

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

@@ -91,7 +91,7 @@ declare namespace Bill {
 declare namespace Billing {
     export {
         CustomerBalanceApplication,
-        InvoiceCollectionSetting,
+        InvoiceCollectionOptions,
         Prorations,
         RecurringBillingItemHandling,
         Bill,
@@ -495,7 +495,7 @@ declare interface CustomerBalanceApplication<Config> {
  *
  * @example
  * ```ts
- * import { Decimal, RoundDirection } from '@stripe/extensibility-sdk/stdlib';
+ * import { Decimal, RoundDirection } from '@stripe/extensibility-sdk';
  *
  * const price = Decimal.from('19.99');
  * const tax   = price.mul(Decimal.from('0.0825'));
@@ -1034,58 +1034,65 @@ export declare interface IntegerCompanion {
 export declare type IntegerRoundDirection = 'ceil' | 'floor' | 'half-up' | 'round-down' | 'round-up';
 
 /** @public */
-declare namespace InvoiceCollectionSetting {
+declare namespace InvoiceCollectionOptions {
     /** @public */
-    type ParentType = 'billing_cadence' | 'contract' | 'quote' | 'standalone' | 'subscription_schedule' | 'subscription';
-    /** @public */
-    type PaymentMethodType = 'ach_credit_transfer' | 'ach_debit' | 'affirm' | 'afterpay_clearpay' | 'alipay' | 'au_becs_debit' | 'bacs_debit' | 'bancontact' | 'boleto' | 'card' | 'cashapp' | 'eps' | 'fpx' | 'giropay' | 'grabpay' | 'ideal' | 'klarna' | 'konbini' | 'link' | 'multibanco' | 'oxxo' | 'p24' | 'paynow' | 'paypal' | 'promptpay' | 'sepa_credit_transfer' | 'sepa_debit' | 'sofort' | 'us_bank_account' | 'wechat_pay';
+    type PaymentMethodType = 'ach_credit_transfer' | 'ach_debit' | 'affirm' | 'afterpay_clearpay' | 'alipay' | 'au_becs_debit' | 'bacs_debit' | 'bancontact' | 'blik' | 'boleto' | 'card' | 'cashapp' | 'eps' | 'fpx' | 'giropay' | 'grabpay' | 'ideal' | 'klarna' | 'konbini' | 'link' | 'multibanco' | 'oxxo' | 'p24' | 'paynow' | 'paypal' | 'promptpay' | 'sepa_credit_transfer' | 'sepa_debit' | 'sofort' | 'us_bank_account' | 'wechat_pay';
     /** @public */
     type CollectionMethod = 'charge_automatically' | 'send_invoice';
     /**
-     * The result of the invoice collection settings override extension.
+     * The result of the invoice collection options override extension.
      * @public
      */
-    interface InvoiceCollectionResponse {
+    interface InvoiceCollectionOptionsResult {
         /** Override the auto-advancement setting. Set to false to keep the invoice in draft. Return null to use the default. */
         autoAdvance?: boolean;
     }
     /** @public */
-    type InvoiceCollectionRequest = ({
+    type InvoiceCollectionOptionsInput = ({
         customer: Customer;
         payer: 'customer';
     } | {
         otherPayer: string;
         payer: 'other';
-    }) & {
-        collectionSettings: CollectionSettings;
-        parent: Parent;
-    };
+    }) & ({
+        invoiceParentType: 'other';
+        otherInvoiceParentType: string;
+    } | {
+        invoiceParentType: 'subscription';
+        subscription: SubscriptionParent;
+    } | { invoiceParentType: 'cadence' } | { invoiceParentType: 'contract' } | { invoiceParentType: 'quote' } | { invoiceParentType: 'schedule' }) & { collectionOptions: CollectionOptions };
     /** @public */
     interface Customer {
         id: string;
         metadata: Record<string, string>;
     }
+    /** @public */
+    type ContractParent = Record<string, never>;
     /**
-     * The parent resource that triggered the invoice creation.
+     * The Subscription that triggered the invoice creation.
      * @public
      */
-    interface Parent {
-        /** The type of parent resource (for example, subscription or contract). */
-        type: ParentType;
-        /** Custom key-value pairs attached to the parent resource. */
+    interface SubscriptionParent {
+        /** The unique identifier for the subscription. */
+        id: string;
+        /** The metadata of the subscription. */
         metadata: Record<string, string>;
     }
+    /** @public */
+    type ScheduleParent = Record<string, never>;
+    /** @public */
+    type QuoteParent = Record<string, never>;
+    /** @public */
+    type CadenceParent = Record<string, never>;
     /**
-     * The collection settings for an invoice.
+     * The collection options for an invoice.
      * @public
      */
-    interface CollectionSettings {
+    interface CollectionOptions {
         /** Whether the invoice automatically advances through its lifecycle. */
         autoAdvance: boolean;
         /** The payment collection method: charge_automatically or send_invoice. */
         collectionMethod: CollectionMethod;
-        /** The delay before the invoice is finalized, in hours. */
-        finalizationGracePeriod: number;
         /** The payment methods configured for this invoice. */
         paymentMethods: PaymentMethodType[];
     }
@@ -1093,76 +1100,35 @@ declare namespace InvoiceCollectionSetting {
      * @public
      * @deprecated Platform dispatch handles wire/SDK conversion.
      */
-    function prepareArgsCollectionOverride(proto: unknown): InvoiceCollectionRequest;
+    function prepareArgsOverrideOptions(proto: unknown): InvoiceCollectionOptionsInput;
     /**
      * @public
      * @deprecated Platform dispatch handles wire/SDK conversion.
      */
-    function prepareResultCollectionOverride(result: InvoiceCollectionResponse): InvoiceCollectionResponse;
-    /* Excluded from this release type: $platformWrapCollectionOverride */
+    function prepareResultOverrideOptions(result: InvoiceCollectionOptionsResult): InvoiceCollectionOptionsResult;
+    /* Excluded from this release type: $platformWrapOverrideOptions */
     /**
      * @public
      * @deprecated Platform dispatch handles wire/SDK conversion.
      */
-    const prepareArgs: typeof prepareArgsCollectionOverride;
+    const prepareArgs: typeof prepareArgsOverrideOptions;
     /**
      * @public
      * @deprecated Platform dispatch handles wire/SDK conversion.
      */
-    const prepareResult: typeof prepareResultCollectionOverride;
+    const prepareResult: typeof prepareResultOverrideOptions;
     /**
-     * Overrides invoice collection settings before a draft invoice is created.
+     * Overrides invoice collection options before a draft invoice is created.
      * @public
      */
-    type CollectionOverrideFunction<Config> = (request: InvoiceCollectionRequest, config: Config, context: Context) => InvoiceCollectionResponse;
+    type OverrideOptionsFunction<Config> = (request: InvoiceCollectionOptionsInput, config: Config, context: Context) => InvoiceCollectionOptionsResult;
 }
 
-/**
- * @example
- * ```ts
- * import type { Billing, Context } from '@stripe/extensibility-sdk';
- *
- * // eslint-disable-next-line @typescript-eslint/no-empty-object-type
- * interface MyInvoiceCollectionSettingConfig {}
- *
- * export default class MyInvoiceCollectionSetting implements Billing.InvoiceCollectionSetting<MyInvoiceCollectionSettingConfig> {
- *   collectionOverride(
- *     _request: Billing.InvoiceCollectionSetting.InvoiceCollectionRequest,
- *     _config: MyInvoiceCollectionSettingConfig,
- *     _context: Context
- *   ) {
- *     // TODO: implement your collection setting logic here
- *
- *     return {};
- *   }
- * }
- *
- * ```
- * @public
- */
-declare interface InvoiceCollectionSetting<Config> {
-    collectionOverride: InvoiceCollectionSetting.CollectionOverrideFunction<Config>;
+/** @public */
+declare interface InvoiceCollectionOptions<Config> {
+    overrideOptions: InvoiceCollectionOptions.OverrideOptionsFunction<Config>;
 }
 
-/**
- * Check whether a value is a `Decimal` instance.
- *
- * @remarks
- * Use this instead of `instanceof` — the underlying class is not
- * publicly exported, so `instanceof` checks are not available to
- * consumers.
- *
- * @example
- * ```ts
- * if (isDecimal(value)) {
- *   value.add(Decimal.from('1')); // value is Decimal
- * }
- * ```
- *
- * @public
- */
-export declare function isDecimal(value: unknown): value is Decimal;
-
 /* Excluded from this release type: _isPromiseLike */
 
 /* Excluded from this release type: _JsonWireToType */
@@ -1506,6 +1472,15 @@ declare namespace RecurringBillingItemHandling {
     }
     /** @public */
     type Item = ({
+        creditedItems: 'invoiceItem';
+        invoiceItem: CreditedInvoiceItem;
+    } | {
+        creditedItems: 'invoiceLineItems';
+        invoiceLineItems: InvoiceLineItems;
+    } | {
+        creditedItems: 'other';
+        otherCreditedItems: string;
+    }) & ({
         customPricingUnitOverageRate: CustomPricingUnitOverageRate;
         priceKind: 'customPricingUnitOverageRate';
     } | {
@@ -1527,6 +1502,40 @@ declare namespace RecurringBillingItemHandling {
         servicePeriod: AnyTimeRange;
         type: ItemType;
     };
+    /**
+     * The invoice item corresponding to a credit item.
+     * @public
+     */
+    interface CreditedInvoiceItem {
+        /** The id of the invoice item. */
+        id: string;
+    }
+    /**
+     * Information about debit line items corresponding to a credit item.
+     * @public
+     */
+    interface InvoiceLineItems {
+        /** The invoice containing the line items. */
+        invoice: CreditedInvoice;
+        /** The line items corresponding to the credit. */
+        invoiceLineItems: CreditedInvoiceLineItem[];
+    }
+    /**
+     * The invoice line item corresponding to a credit item.
+     * @public
+     */
+    interface CreditedInvoiceLineItem {
+        /** The id of the invoice line item. */
+        id: string;
+    }
+    /**
+     * The invoice corresponding to a credit item.
+     * @public
+     */
+    interface CreditedInvoice {
+        /** The id of the invoice. */
+        id: string;
+    }
     /** @public */
     interface CustomPricingUnitOverageRate {
         id: string;
@@ -1787,9 +1796,6 @@ export declare type Ref<T extends {
     readonly [__stripeType]: 'string';
 };
 
-/** Factory for creating {@link (Ref:type)} values from an object with `object` and `id` fields. @public */
-export declare const Ref: { create: <T extends { readonly object: string }>(step: { readonly id: string } & T) => Ref<T> };
-
 /* Excluded from this release type: _required */
 
 /**
@@ -1816,15 +1822,6 @@ export declare type RoundDirection = 'ceil' | 'floor' | 'half-down' | 'half-even
 
 /* Excluded from this release type: _ShapeDescriptor */
 
-/** A branded string representing a street address. @public */
-export declare type StreetAddress = {
-    readonly [__brand]: 'StreetAddress';
-    readonly [__stripeType]: 'string';
-} & string;
-
-/** 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 key used in SDK scalar types. @public */
 export declare type StripeTypeSymbol = typeof __stripeType;
 
@@ -1839,15 +1836,6 @@ declare interface TimeRange {
     endDate: Date;
 }
 
-/** A branded string representing an ISO 8601 datetime. @public */
-export declare type Timestamp = {
-    readonly [__brand]: 'Timestamp';
-    readonly [__stripeType]: 'string';
-} & string;
-
-/** 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>`.
  *
@@ -1857,7 +1845,7 @@ export declare const Timestamp: { create: (value: string) => Timestamp };
  *
  * @example
  * ```typescript
- * import { toConst } from '@stripe/extensibility-sdk/stdlib';
+ * import { toConst } from '@stripe/extensibility-sdk';
  *
  * const DEFAULTS = toConst({ timeout: 30, retries: 3 });
  * // Type: { readonly timeout: 30; readonly retries: 3 }
@@ -1892,31 +1880,9 @@ export declare function toConst<T>(value: T): DeepReadonly<T>;
 
 /* Excluded from this release type: _UnionDescriptor */
 
-/**
- * Shared types and error classes for the transform pipeline.
- * See transforms.ts for the module overview.
- */
-/**
- * Thrown when incoming wire data (proto → SDK) cannot be parsed.
- * Indicates malformed or unexpected data from the proto infrastructure —
- * not a bug in the user's code.
- *
- * @public
- */
-export declare class WireReadError extends Error {
-    /* Excluded from this release type: name */
-}
+/* Excluded from this release type: _WireReadError */
 
-/**
- * Thrown when outgoing SDK data (SDK → proto) cannot be serialized.
- * Indicates that the user's code returned a value that cannot be translated
- * back to wire format.
- *
- * @public
- */
-export declare class WireWriteError extends Error {
-    /* Excluded from this release type: name */
-}
+/* Excluded from this release type: _WireWriteError */
 
 declare namespace Workflows {
     export {