@stripe/extensibility-sdk 0.25.0 → 0.27.1

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

@@ -75,7 +75,7 @@ declare namespace Bill {
 declare namespace Billing {
     export {
         CustomerBalanceApplication,
-        InvoiceCollectionSetting,
+        InvoiceCollectionOptions,
         Prorations,
         RecurringBillingItemHandling,
         Bill,
@@ -472,7 +472,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'));
@@ -965,58 +965,65 @@ declare interface IntegerCompanion {
 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[];
     }
@@ -1024,55 +1031,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>;
 }
 
 /**
@@ -1402,6 +1387,15 @@ declare namespace RecurringBillingItemHandling {
     }
     /** @public */
     type Item = ({
+        creditedItems: 'invoiceItem';
+        invoiceItem: CreditedInvoiceItem;
+    } | {
+        creditedItems: 'invoiceLineItems';
+        invoiceLineItems: InvoiceLineItems;
+    } | {
+        creditedItems: 'other';
+        otherCreditedItems: string;
+    }) & ({
         customPricingUnitOverageRate: CustomPricingUnitOverageRate;
         priceKind: 'customPricingUnitOverageRate';
     } | {
@@ -1423,6 +1417,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;

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

@@ -31,7 +31,7 @@ export declare const __brand: '__brand';
  *
  * 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]`.
+ * types (e.g., `Ref`) that also carry `[__brand]`.
  *
  * String-literal const (not `unique symbol`) so that independent
  * declaration rollups (root vs subpath) produce structurally compatible
@@ -163,7 +163,7 @@ declare namespace Bill {
 declare namespace Billing {
     export {
         CustomerBalanceApplication,
-        InvoiceCollectionSetting,
+        InvoiceCollectionOptions,
         Prorations,
         RecurringBillingItemHandling,
         Bill,
@@ -612,7 +612,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'));
@@ -1203,58 +1203,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[];
     }
@@ -1262,77 +1269,36 @@ 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;
+    function prepareResultOverrideOptions(result: InvoiceCollectionOptionsResult): InvoiceCollectionOptionsResult;
     /** @internal */
-    function $platformWrapCollectionOverride(configTransformer?: (wireConfig: unknown, appCtx: _ConfigApplicationContext) => unknown): (cls: new () => { collectionOverride(...a: unknown[]): unknown }, wireArgs: unknown, wireConfig: unknown, ctx: unknown) => unknown;
+    function $platformWrapOverrideOptions(configTransformer?: (wireConfig: unknown, appCtx: _ConfigApplicationContext) => unknown): (cls: new () => { overrideOptions(...a: unknown[]): unknown }, wireArgs: unknown, wireConfig: unknown, ctx: unknown) => unknown;
     /**
      * @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;
-
 /**
  * Returns `true` if `value` conforms to the `PromiseLike` contract:
  * a non-null object or function with a callable `then` method.
@@ -1761,6 +1727,15 @@ declare namespace RecurringBillingItemHandling {
     }
     /** @public */
     type Item = ({
+        creditedItems: 'invoiceItem';
+        invoiceItem: CreditedInvoiceItem;
+    } | {
+        creditedItems: 'invoiceLineItems';
+        invoiceLineItems: InvoiceLineItems;
+    } | {
+        creditedItems: 'other';
+        otherCreditedItems: string;
+    }) & ({
         customPricingUnitOverageRate: CustomPricingUnitOverageRate;
         priceKind: 'customPricingUnitOverageRate';
     } | {
@@ -1782,6 +1757,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;
@@ -2045,13 +2054,10 @@ 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> };
-
 /**
  * Wraps a transformer so that a `null` / `undefined` result throws
  * `WireParseError('Required field is missing')`, which `strategy.applyField`
- * will catch and re-throw as WireReadError / WireWriteError with field context.
+ * will catch and re-throw as _WireReadError / _WireWriteError with field context.
  *
  * The inner transformer runs first, so strategies that backfill absent values
  * (e.g. clock-aware `translateDateTime`) can satisfy the requirement.
@@ -2098,15 +2104,6 @@ export declare class _ShapeDescriptor<_S extends _ApplyStrategy = _ApplyStrategy
     constructor(typeName: string, fields: _FieldDescriptor[], oneofFields?: _OneofFieldDescriptor[]);
 }
 
-/** 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;
 
@@ -2121,15 +2118,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>`.
  *
@@ -2139,7 +2127,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 }
@@ -2274,9 +2262,9 @@ export declare class _UnionDescriptor<_S extends _ApplyStrategy = _ApplyStrategy
  * Indicates malformed or unexpected data from the proto infrastructure —
  * not a bug in the user's code.
  *
- * @public
+ * @internal
  */
-export declare class WireReadError extends Error {
+export declare class _WireReadError extends Error {
     /**
      * Error class name for `instanceof`-free identification.
      * @internal
@@ -2289,9 +2277,9 @@ export declare class WireReadError extends Error {
  * Indicates that the user's code returned a value that cannot be translated
  * back to wire format.
  *
- * @public
+ * @internal
  */
-export declare class WireWriteError extends Error {
+export declare class _WireWriteError extends Error {
     /**
      * Error class name for `instanceof`-free identification.
      * @internal