@stripe/extensibility-sdk 0.26.0 → 1.0.0

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);
@@ -316,9 +316,34 @@ const qty = PositiveInteger.from(3, 'round-down'); // PositiveInteger
 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>;
+```
+
+---
+
+### 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';
+```
+
+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);
 ```
 
 ---

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,55 +1100,33 @@ 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>;
 }
 
 /* Excluded from this release type: _isPromiseLike */
@@ -1487,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';
     } | {
@@ -1508,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;
@@ -1768,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 */
 
 /**
@@ -1820,7 +1845,7 @@ declare interface TimeRange {
  *
  * @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 }

package/dist/extensibility-sdk-beta.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,55 +1100,33 @@ 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>;
 }
 
 /* Excluded from this release type: _isPromiseLike */
@@ -1487,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';
     } | {
@@ -1508,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;
@@ -1768,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 */
 
 /**
@@ -1820,7 +1845,7 @@ declare interface TimeRange {
  *
  * @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 }