@stripe/extensibility-test-helpers 0.2.7

package/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (C) 2026 Stripe, Inc. (https://stripe.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/extensibility-test-helpers-alpha.d.ts

@@ -0,0 +1,218 @@
+/**
+ * `@stripe/extensibility-test-helpers`
+ *
+ * Generic test client for Stripe resources.
+ *
+ * Works with both CustomObject subclasses and API objects like Customer.
+ * Backend implementations can be swapped for local testing vs sandbox.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Backend interface for storage/API operations.
+ * Implement for different environments (local, sandbox, production).
+ * @public
+ */
+export declare interface Backend {
+    /**
+     * Creates a new resource of the given object type.
+     * @param objectType - The Stripe object type string (e.g. `"customer"`).
+     * @param data - Fields to set on the new resource.
+     * @returns The created resource with a generated `id`.
+     */
+    create<T extends StripeResource>(objectType: string, data: Record<string, unknown>): Promise<T>;
+    /**
+     * Retrieves a resource by ID.
+     * @param objectType - The Stripe object type string.
+     * @param id - The resource ID.
+     * @returns The matching resource.
+     */
+    retrieve<T extends StripeResource>(objectType: string, id: string): Promise<T>;
+    /**
+     * Updates an existing resource by merging the provided fields.
+     * @param objectType - The Stripe object type string.
+     * @param id - The resource ID.
+     * @param data - Fields to merge into the existing resource.
+     * @returns The updated resource.
+     */
+    update<T extends StripeResource>(objectType: string, id: string, data: Record<string, unknown>): Promise<T>;
+    /**
+     * Deletes a resource by ID.
+     * @param objectType - The Stripe object type string.
+     * @param id - The resource ID.
+     */
+    delete(objectType: string, id: string): Promise<void>;
+    /**
+     * Lists resources of the given object type with optional pagination.
+     * @param objectType - The Stripe object type string.
+     * @param params - Optional pagination parameters.
+     * @returns A paginated list response.
+     */
+    list<T extends StripeResource>(objectType: string, params?: ListParams): Promise<ListResponse<T>>;
+}
+
+/**
+ * Input type for create - user-provided fields only.
+ *
+ * @public
+ */
+export declare type CreateInput<T extends StripeResource> = Partial<Omit<T, 'id' | 'object'>>;
+
+/**
+ * List pagination params.
+ * @public
+ */
+export declare interface ListParams {
+    /** Maximum number of items to return. Defaults to `10`. */
+    limit?: number;
+    /** Return items after the item with this ID (exclusive). Use for forward pagination. */
+    startingAfter?: string;
+    /** Return items before the item with this ID (exclusive). Use for backward pagination. */
+    endingBefore?: string;
+}
+
+/**
+ * Paginated list response.
+ * @public
+ */
+export declare interface ListResponse<T> {
+    /** The items in the current page. */
+    data: T[];
+    /** Whether additional items exist beyond this page. */
+    hasMore: boolean;
+}
+
+/**
+ * In-memory {@link Backend} implementation for use in unit tests.
+ *
+ * Each instance maintains its own isolated store. Use a shared instance
+ * when you need multiple clients to see the same data.
+ * @public
+ */
+export declare class LocalBackend implements Backend {
+    private store;
+    private idCounter;
+    private getCollection;
+    private generateId;
+    /** {@inheritDoc Backend.create} */
+    create<T extends StripeResource>(objectType: string, data: Record<string, unknown>): Promise<T>;
+    /** {@inheritDoc Backend.retrieve} */
+    retrieve<T extends StripeResource>(objectType: string, id: string): Promise<T>;
+    /** {@inheritDoc Backend.update} */
+    update<T extends StripeResource>(objectType: string, id: string, data: Record<string, unknown>): Promise<T>;
+    /** {@inheritDoc Backend.delete} */
+    delete(objectType: string, id: string): Promise<void>;
+    /** {@inheritDoc Backend.list} */
+    list<T extends StripeResource>(objectType: string, params?: ListParams): Promise<ListResponse<T>>;
+    /** Resets all stored objects and the ID counter. Useful in `beforeEach` hooks. */
+    clear(): void;
+}
+
+/**
+ * A class constructor that produces instances of T.
+ * @public
+ */
+export declare type ResourceClass<T extends StripeResource> = new (...args: unknown[]) => T;
+
+/**
+ * Minimal interface for any Stripe resource.
+ * Both CustomObject and API objects satisfy this.
+ * @public
+ */
+export declare interface StripeResource {
+    /** Unique identifier for the resource. */
+    id: string;
+    /** String identifying the object type, e.g. `"customer"` or `"custom_object.order"`. */
+    object: string;
+}
+
+/**
+ * Generic test client for any Stripe resource.
+ *
+ * @example
+ * ```ts
+ * const locations = new TestClient(Location);
+ * const customers = new TestClient(Customer);
+ *
+ * const loc = await locations.create({ address: '123 Main' });
+ * const cust = await customers.create({ email: 'test@example.com' });
+ * ```
+ * @public
+ */
+export declare class TestClient<T extends StripeResource> {
+    private ResourceClass;
+    private static sharedBackend;
+    private objectType;
+    private backend;
+    constructor(ResourceClass: ResourceClass<T>, options?: TestClientOptions);
+    /**
+     * Derive object type by instantiating the class and reading its `object` field.
+     *
+     * This works for classes that set `object` in their constructor or as a field
+     * initializer (e.g. `object = 'test.resource'`). It does **not** work for
+     * custom object classes that extend `BaseObject`, because `BaseObject.object`
+     * is only set after the build-time code transform runs — plain construction
+     * leaves it undefined. For those classes, pass `objectType` explicitly in the
+     * constructor options.
+     */
+    private deriveObjectType;
+    /**
+     * Hydrate plain data into a class instance.
+     * Returns an instance with the class's prototype (so methods work).
+     */
+    private hydrate;
+    /**
+     * Creates a new resource and returns it as a hydrated class instance.
+     *
+     * Injects standard platform field defaults (`created`, `updated`, `livemode`)
+     * before the caller's data, so the returned instance has the same shape a real
+     * Stripe backend would produce. Callers can override any default via `data`.
+     *
+     * @param data - Fields to set on the new resource (excluding `id` and `object`).
+     */
+    create(data: CreateInput<T>): Promise<T>;
+    /**
+     * Retrieves a resource by ID and returns it as a hydrated class instance.
+     * @param id - The resource ID.
+     */
+    retrieve(id: string): Promise<T>;
+    /**
+     * Merges the provided fields into an existing resource and returns the updated instance.
+     * @param id - The resource ID.
+     * @param data - Fields to merge into the existing resource (excluding `id` and `object`).
+     */
+    update(id: string, data: UpdateInput<T>): Promise<T>;
+    /**
+     * Deletes a resource by ID.
+     * @param id - The resource ID.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Lists resources with optional pagination, returning hydrated class instances.
+     * @param params - Optional pagination parameters.
+     */
+    list(params?: ListParams): Promise<ListResponse<T>>;
+    /** Clear all test data across all object types */
+    static clearAll(): void;
+}
+
+/**
+ * Options for constructing a {@link TestClient}.
+ * @public
+ */
+export declare interface TestClientOptions {
+    /** Explicit object type (if auto-derive doesn't work) */
+    objectType?: string;
+    /** Custom backend (defaults to shared LocalBackend) */
+    backend?: Backend;
+}
+
+/**
+ * Input type for update - partial user fields.
+ *
+ * @public
+ */
+export declare type UpdateInput<T extends StripeResource> = Partial<Omit<T, 'id' | 'object'>>;
+
+export { }

package/dist/extensibility-test-helpers-beta.d.ts

@@ -0,0 +1,218 @@
+/**
+ * `@stripe/extensibility-test-helpers`
+ *
+ * Generic test client for Stripe resources.
+ *
+ * Works with both CustomObject subclasses and API objects like Customer.
+ * Backend implementations can be swapped for local testing vs sandbox.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Backend interface for storage/API operations.
+ * Implement for different environments (local, sandbox, production).
+ * @public
+ */
+export declare interface Backend {
+    /**
+     * Creates a new resource of the given object type.
+     * @param objectType - The Stripe object type string (e.g. `"customer"`).
+     * @param data - Fields to set on the new resource.
+     * @returns The created resource with a generated `id`.
+     */
+    create<T extends StripeResource>(objectType: string, data: Record<string, unknown>): Promise<T>;
+    /**
+     * Retrieves a resource by ID.
+     * @param objectType - The Stripe object type string.
+     * @param id - The resource ID.
+     * @returns The matching resource.
+     */
+    retrieve<T extends StripeResource>(objectType: string, id: string): Promise<T>;
+    /**
+     * Updates an existing resource by merging the provided fields.
+     * @param objectType - The Stripe object type string.
+     * @param id - The resource ID.
+     * @param data - Fields to merge into the existing resource.
+     * @returns The updated resource.
+     */
+    update<T extends StripeResource>(objectType: string, id: string, data: Record<string, unknown>): Promise<T>;
+    /**
+     * Deletes a resource by ID.
+     * @param objectType - The Stripe object type string.
+     * @param id - The resource ID.
+     */
+    delete(objectType: string, id: string): Promise<void>;
+    /**
+     * Lists resources of the given object type with optional pagination.
+     * @param objectType - The Stripe object type string.
+     * @param params - Optional pagination parameters.
+     * @returns A paginated list response.
+     */
+    list<T extends StripeResource>(objectType: string, params?: ListParams): Promise<ListResponse<T>>;
+}
+
+/**
+ * Input type for create - user-provided fields only.
+ *
+ * @public
+ */
+export declare type CreateInput<T extends StripeResource> = Partial<Omit<T, 'id' | 'object'>>;
+
+/**
+ * List pagination params.
+ * @public
+ */
+export declare interface ListParams {
+    /** Maximum number of items to return. Defaults to `10`. */
+    limit?: number;
+    /** Return items after the item with this ID (exclusive). Use for forward pagination. */
+    startingAfter?: string;
+    /** Return items before the item with this ID (exclusive). Use for backward pagination. */
+    endingBefore?: string;
+}
+
+/**
+ * Paginated list response.
+ * @public
+ */
+export declare interface ListResponse<T> {
+    /** The items in the current page. */
+    data: T[];
+    /** Whether additional items exist beyond this page. */
+    hasMore: boolean;
+}
+
+/**
+ * In-memory {@link Backend} implementation for use in unit tests.
+ *
+ * Each instance maintains its own isolated store. Use a shared instance
+ * when you need multiple clients to see the same data.
+ * @public
+ */
+export declare class LocalBackend implements Backend {
+    private store;
+    private idCounter;
+    private getCollection;
+    private generateId;
+    /** {@inheritDoc Backend.create} */
+    create<T extends StripeResource>(objectType: string, data: Record<string, unknown>): Promise<T>;
+    /** {@inheritDoc Backend.retrieve} */
+    retrieve<T extends StripeResource>(objectType: string, id: string): Promise<T>;
+    /** {@inheritDoc Backend.update} */
+    update<T extends StripeResource>(objectType: string, id: string, data: Record<string, unknown>): Promise<T>;
+    /** {@inheritDoc Backend.delete} */
+    delete(objectType: string, id: string): Promise<void>;
+    /** {@inheritDoc Backend.list} */
+    list<T extends StripeResource>(objectType: string, params?: ListParams): Promise<ListResponse<T>>;
+    /** Resets all stored objects and the ID counter. Useful in `beforeEach` hooks. */
+    clear(): void;
+}
+
+/**
+ * A class constructor that produces instances of T.
+ * @public
+ */
+export declare type ResourceClass<T extends StripeResource> = new (...args: unknown[]) => T;
+
+/**
+ * Minimal interface for any Stripe resource.
+ * Both CustomObject and API objects satisfy this.
+ * @public
+ */
+export declare interface StripeResource {
+    /** Unique identifier for the resource. */
+    id: string;
+    /** String identifying the object type, e.g. `"customer"` or `"custom_object.order"`. */
+    object: string;
+}
+
+/**
+ * Generic test client for any Stripe resource.
+ *
+ * @example
+ * ```ts
+ * const locations = new TestClient(Location);
+ * const customers = new TestClient(Customer);
+ *
+ * const loc = await locations.create({ address: '123 Main' });
+ * const cust = await customers.create({ email: 'test@example.com' });
+ * ```
+ * @public
+ */
+export declare class TestClient<T extends StripeResource> {
+    private ResourceClass;
+    private static sharedBackend;
+    private objectType;
+    private backend;
+    constructor(ResourceClass: ResourceClass<T>, options?: TestClientOptions);
+    /**
+     * Derive object type by instantiating the class and reading its `object` field.
+     *
+     * This works for classes that set `object` in their constructor or as a field
+     * initializer (e.g. `object = 'test.resource'`). It does **not** work for
+     * custom object classes that extend `BaseObject`, because `BaseObject.object`
+     * is only set after the build-time code transform runs — plain construction
+     * leaves it undefined. For those classes, pass `objectType` explicitly in the
+     * constructor options.
+     */
+    private deriveObjectType;
+    /**
+     * Hydrate plain data into a class instance.
+     * Returns an instance with the class's prototype (so methods work).
+     */
+    private hydrate;
+    /**
+     * Creates a new resource and returns it as a hydrated class instance.
+     *
+     * Injects standard platform field defaults (`created`, `updated`, `livemode`)
+     * before the caller's data, so the returned instance has the same shape a real
+     * Stripe backend would produce. Callers can override any default via `data`.
+     *
+     * @param data - Fields to set on the new resource (excluding `id` and `object`).
+     */
+    create(data: CreateInput<T>): Promise<T>;
+    /**
+     * Retrieves a resource by ID and returns it as a hydrated class instance.
+     * @param id - The resource ID.
+     */
+    retrieve(id: string): Promise<T>;
+    /**
+     * Merges the provided fields into an existing resource and returns the updated instance.
+     * @param id - The resource ID.
+     * @param data - Fields to merge into the existing resource (excluding `id` and `object`).
+     */
+    update(id: string, data: UpdateInput<T>): Promise<T>;
+    /**
+     * Deletes a resource by ID.
+     * @param id - The resource ID.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Lists resources with optional pagination, returning hydrated class instances.
+     * @param params - Optional pagination parameters.
+     */
+    list(params?: ListParams): Promise<ListResponse<T>>;
+    /** Clear all test data across all object types */
+    static clearAll(): void;
+}
+
+/**
+ * Options for constructing a {@link TestClient}.
+ * @public
+ */
+export declare interface TestClientOptions {
+    /** Explicit object type (if auto-derive doesn't work) */
+    objectType?: string;
+    /** Custom backend (defaults to shared LocalBackend) */
+    backend?: Backend;
+}
+
+/**
+ * Input type for update - partial user fields.
+ *
+ * @public
+ */
+export declare type UpdateInput<T extends StripeResource> = Partial<Omit<T, 'id' | 'object'>>;
+
+export { }

package/dist/extensibility-test-helpers-internal.d.ts

@@ -0,0 +1,218 @@
+/**
+ * `@stripe/extensibility-test-helpers`
+ *
+ * Generic test client for Stripe resources.
+ *
+ * Works with both CustomObject subclasses and API objects like Customer.
+ * Backend implementations can be swapped for local testing vs sandbox.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Backend interface for storage/API operations.
+ * Implement for different environments (local, sandbox, production).
+ * @public
+ */
+export declare interface Backend {
+    /**
+     * Creates a new resource of the given object type.
+     * @param objectType - The Stripe object type string (e.g. `"customer"`).
+     * @param data - Fields to set on the new resource.
+     * @returns The created resource with a generated `id`.
+     */
+    create<T extends StripeResource>(objectType: string, data: Record<string, unknown>): Promise<T>;
+    /**
+     * Retrieves a resource by ID.
+     * @param objectType - The Stripe object type string.
+     * @param id - The resource ID.
+     * @returns The matching resource.
+     */
+    retrieve<T extends StripeResource>(objectType: string, id: string): Promise<T>;
+    /**
+     * Updates an existing resource by merging the provided fields.
+     * @param objectType - The Stripe object type string.
+     * @param id - The resource ID.
+     * @param data - Fields to merge into the existing resource.
+     * @returns The updated resource.
+     */
+    update<T extends StripeResource>(objectType: string, id: string, data: Record<string, unknown>): Promise<T>;
+    /**
+     * Deletes a resource by ID.
+     * @param objectType - The Stripe object type string.
+     * @param id - The resource ID.
+     */
+    delete(objectType: string, id: string): Promise<void>;
+    /**
+     * Lists resources of the given object type with optional pagination.
+     * @param objectType - The Stripe object type string.
+     * @param params - Optional pagination parameters.
+     * @returns A paginated list response.
+     */
+    list<T extends StripeResource>(objectType: string, params?: ListParams): Promise<ListResponse<T>>;
+}
+
+/**
+ * Input type for create - user-provided fields only.
+ *
+ * @public
+ */
+export declare type CreateInput<T extends StripeResource> = Partial<Omit<T, 'id' | 'object'>>;
+
+/**
+ * List pagination params.
+ * @public
+ */
+export declare interface ListParams {
+    /** Maximum number of items to return. Defaults to `10`. */
+    limit?: number;
+    /** Return items after the item with this ID (exclusive). Use for forward pagination. */
+    startingAfter?: string;
+    /** Return items before the item with this ID (exclusive). Use for backward pagination. */
+    endingBefore?: string;
+}
+
+/**
+ * Paginated list response.
+ * @public
+ */
+export declare interface ListResponse<T> {
+    /** The items in the current page. */
+    data: T[];
+    /** Whether additional items exist beyond this page. */
+    hasMore: boolean;
+}
+
+/**
+ * In-memory {@link Backend} implementation for use in unit tests.
+ *
+ * Each instance maintains its own isolated store. Use a shared instance
+ * when you need multiple clients to see the same data.
+ * @public
+ */
+export declare class LocalBackend implements Backend {
+    private store;
+    private idCounter;
+    private getCollection;
+    private generateId;
+    /** {@inheritDoc Backend.create} */
+    create<T extends StripeResource>(objectType: string, data: Record<string, unknown>): Promise<T>;
+    /** {@inheritDoc Backend.retrieve} */
+    retrieve<T extends StripeResource>(objectType: string, id: string): Promise<T>;
+    /** {@inheritDoc Backend.update} */
+    update<T extends StripeResource>(objectType: string, id: string, data: Record<string, unknown>): Promise<T>;
+    /** {@inheritDoc Backend.delete} */
+    delete(objectType: string, id: string): Promise<void>;
+    /** {@inheritDoc Backend.list} */
+    list<T extends StripeResource>(objectType: string, params?: ListParams): Promise<ListResponse<T>>;
+    /** Resets all stored objects and the ID counter. Useful in `beforeEach` hooks. */
+    clear(): void;
+}
+
+/**
+ * A class constructor that produces instances of T.
+ * @public
+ */
+export declare type ResourceClass<T extends StripeResource> = new (...args: unknown[]) => T;
+
+/**
+ * Minimal interface for any Stripe resource.
+ * Both CustomObject and API objects satisfy this.
+ * @public
+ */
+export declare interface StripeResource {
+    /** Unique identifier for the resource. */
+    id: string;
+    /** String identifying the object type, e.g. `"customer"` or `"custom_object.order"`. */
+    object: string;
+}
+
+/**
+ * Generic test client for any Stripe resource.
+ *
+ * @example
+ * ```ts
+ * const locations = new TestClient(Location);
+ * const customers = new TestClient(Customer);
+ *
+ * const loc = await locations.create({ address: '123 Main' });
+ * const cust = await customers.create({ email: 'test@example.com' });
+ * ```
+ * @public
+ */
+export declare class TestClient<T extends StripeResource> {
+    private ResourceClass;
+    private static sharedBackend;
+    private objectType;
+    private backend;
+    constructor(ResourceClass: ResourceClass<T>, options?: TestClientOptions);
+    /**
+     * Derive object type by instantiating the class and reading its `object` field.
+     *
+     * This works for classes that set `object` in their constructor or as a field
+     * initializer (e.g. `object = 'test.resource'`). It does **not** work for
+     * custom object classes that extend `BaseObject`, because `BaseObject.object`
+     * is only set after the build-time code transform runs — plain construction
+     * leaves it undefined. For those classes, pass `objectType` explicitly in the
+     * constructor options.
+     */
+    private deriveObjectType;
+    /**
+     * Hydrate plain data into a class instance.
+     * Returns an instance with the class's prototype (so methods work).
+     */
+    private hydrate;
+    /**
+     * Creates a new resource and returns it as a hydrated class instance.
+     *
+     * Injects standard platform field defaults (`created`, `updated`, `livemode`)
+     * before the caller's data, so the returned instance has the same shape a real
+     * Stripe backend would produce. Callers can override any default via `data`.
+     *
+     * @param data - Fields to set on the new resource (excluding `id` and `object`).
+     */
+    create(data: CreateInput<T>): Promise<T>;
+    /**
+     * Retrieves a resource by ID and returns it as a hydrated class instance.
+     * @param id - The resource ID.
+     */
+    retrieve(id: string): Promise<T>;
+    /**
+     * Merges the provided fields into an existing resource and returns the updated instance.
+     * @param id - The resource ID.
+     * @param data - Fields to merge into the existing resource (excluding `id` and `object`).
+     */
+    update(id: string, data: UpdateInput<T>): Promise<T>;
+    /**
+     * Deletes a resource by ID.
+     * @param id - The resource ID.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Lists resources with optional pagination, returning hydrated class instances.
+     * @param params - Optional pagination parameters.
+     */
+    list(params?: ListParams): Promise<ListResponse<T>>;
+    /** Clear all test data across all object types */
+    static clearAll(): void;
+}
+
+/**
+ * Options for constructing a {@link TestClient}.
+ * @public
+ */
+export declare interface TestClientOptions {
+    /** Explicit object type (if auto-derive doesn't work) */
+    objectType?: string;
+    /** Custom backend (defaults to shared LocalBackend) */
+    backend?: Backend;
+}
+
+/**
+ * Input type for update - partial user fields.
+ *
+ * @public
+ */
+export declare type UpdateInput<T extends StripeResource> = Partial<Omit<T, 'id' | 'object'>>;
+
+export { }