@stripe/extensibility-custom-objects 0.7.4

package/dist/extensibility-custom-objects-internal.d.ts

@@ -0,0 +1,680 @@
+/**
+ * Stripe Custom Objects SDK
+ *
+ * Provides decorators and runtime support for defining custom object types
+ * that integrate with the Stripe platform. Custom objects are defined using
+ * TypeScript classes with decorators, then transformed at build time using
+ * `@stripe/extensibility-custom-objects-tools`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Checks if a proxied object has pending changes.
+ *
+ * @internal
+ */
+export declare function __hasPendingChanges(obj: BaseObject): boolean;
+
+/**
+ * Flushes pending field changes into the proxy's slated-updates accumulator.
+ *
+ * Called by the auto-save code injected at the end of each `@Action` method.
+ * BaseObject.save() performs an equivalent flush directly via the shared
+ * _flushPendingToSlated helper.
+ *
+ * @internal
+ */
+export declare function __queueSave(obj: BaseObject): void;
+
+/**
+ * Marks an instance method as an action on a custom object.
+ *
+ * This decorator is **inert at runtime** — it does not modify the method in any way.
+ * It serves as a marker for the build-time transformer, which extracts action metadata
+ * and generates the necessary platform registration code.
+ *
+ * Can only be applied to instance methods, not static methods. Applying `@Action`
+ * to a static method is a TypeScript compile error.
+ *
+ * All naming metadata is expressed via TSDoc annotation tags in a JSDoc comment
+ * on the method: `@apiName`, `@displayName`, `@description`.
+ *
+ * @example
+ * Use TSDoc tags in a JSDoc comment above the decorator,
+ * e.g. `@apiName mark_delivered` and `@displayName Mark Delivered`,
+ * then apply the bare decorator `@Action`.
+ *
+ * @public
+ */
+export declare function Action(_target: (...args: never) => unknown, _context: InstanceMethodDecoratorContext): void;
+
+/**
+ * Metadata describing a single action method.
+ *
+ * @internal
+ */
+export declare interface _ActionMetadata {
+    /** Name of the method */
+    methodName: string;
+    /** API name for this action (derived from method name or overridden via the apiName TSDoc tag) */
+    apiName: string;
+}
+
+/**
+ * Assembles an update payload from pending proxy updates.
+ *
+ * Fields prefixed with `fields.` are grouped into a nested `fields` object.
+ * All other fields appear at the top level.
+ *
+ * @example
+ * ```typescript
+ * assemblePayload([
+ *   { field: 'status', value: 'active' },
+ *   { field: 'fields.email', value: 'alice@example.com' },
+ * ]);
+ * // Returns: { status: 'active', fields: { email: 'alice@example.com' } }
+ * ```
+ *
+ * @internal
+ */
+export declare function _assemblePayload(pendingUpdates: {
+    field: string;
+    value: unknown;
+}[]): Record<string, unknown>;
+
+/**
+ * Abstract base class for all custom objects.
+ *
+ * Provides built-in platform fields (id, object, created, updated, livemode)
+ * and a typed `fields` container for user-defined fields. The generic parameter
+ * `T` describes the shape of user fields accessible via `this.fields`.
+ *
+ * @remarks
+ * **Definite assignment assertions (`!`)**: All platform fields (`id`, `object`,
+ * `created`, `updated`, `livemode`, `fields`) use the TypeScript definite assignment
+ * assertion operator. This suppresses the "property has no initializer" error because
+ * these fields are intentionally left unset by the zero-argument constructor.
+ *
+ * The runtime (`executeInstanceMethod` in `invoke.ts`) is solely responsible for
+ * populating these fields via `Object.assign` and `hydrateInstance` **before** the
+ * dirty-tracking proxy is installed. Code that constructs a subclass directly
+ * (bypassing the runtime) will have `undefined` values for all platform fields at
+ * runtime, despite the types suggesting otherwise.
+ *
+ * @typeParam T - Shape of user-defined fields stored in `fields`
+ * @public
+ */
+export declare abstract class BaseObject<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** Unique identifier assigned by the platform */
+    readonly id: string;
+    /** Object type identifier assigned by the platform */
+    readonly object: string;
+    /** Timestamp when the object was created */
+    readonly created: Date;
+    /** Timestamp when the object was last updated */
+    readonly updated: Date;
+    /** Whether the object exists in live mode (true) or test mode (false). @public */
+    readonly livemode: boolean;
+    /**
+     * User-defined fields container. Populated during hydration via Object.assign
+     * before the dirty-tracking proxy is installed.
+     * Access individual fields as `this.fields.fieldName`.
+     *
+     * @remarks
+     * The generic type `T` describes the shape of available fields after
+     * hydration, not at construction time. Fields may be undefined before
+     * the instance is hydrated with data from the platform.
+     *
+     * @public
+     */
+    readonly fields: T;
+    /**
+     * Flushes pending field mutations into the slated-updates accumulator.
+     *
+     * When called from a transformed action (no save handler configured), this
+     * records which fields were mutated so that the Logic wrapper can include them
+     * in the response envelope's `updatedFields`. No network call is made.
+     *
+     * When a save handler is configured (runtime invoke path), the handler is
+     * called for actual persistence and its result is returned.
+     *
+     * @returns The save result including `updatedFieldCount` (unique fields flushed)
+     * @throws Error if the object is not proxied
+     * @public
+     */
+    save(): Promise<SaveResult>;
+    /**
+     * Discard all pending changes and restore field values to their
+     * last-saved state. Has no effect if the object is not proxied.
+     *
+     * @public
+     */
+    revert(): void;
+}
+
+/**
+ * Builds the ExecuteMethodResponse envelope for a completed action.
+ * Reads and clears the slated-updates accumulator, returning
+ * `{ methodReturnValue, updatedFields }`.
+ *
+ * @internal
+ */
+export declare function _buildMethodResponse(obj: BaseObject, methodReturnValue: unknown): {
+    methodReturnValue: unknown;
+    updatedFields: Record<string, unknown>;
+};
+
+/**
+ * Clears all registered classes.
+ * Primarily for testing.
+ *
+ * @internal
+ */
+export declare function _clearRegistry(): void;
+
+/**
+ * Clears the slated-updates accumulator on an instance.
+ *
+ * Called twice during executeMethod: once before the action (to ensure
+ * no stale state from a previous invocation leaks in) and once inside
+ * buildEnvelope after the accumulated updates have been read.
+ *
+ * @internal
+ */
+export declare function _clearSlatedUpdates(obj: BaseObject): void;
+
+/**
+ * Commits the proxy state: clears pending updates and updates the saved snapshot.
+ *
+ * @internal
+ */
+export declare function _commitProxyState(state: _ProxyState): void;
+
+/**
+ * Creates a new runtime event emitter.
+ * Listeners are isolated: if one throws, others still receive the event.
+ *
+ * @internal
+ */
+export declare function _createEventEmitter(): _RuntimeEventEmitter;
+
+/**
+ * Creates a proxied custom object instance with change tracking.
+ *
+ * @internal
+ */
+export declare function _createInstanceProxy<T extends BaseObject>(instance: T, options?: _CreateProxyOptions): _ProxiedObject<T>;
+
+/**
+ * Options for creating a proxied custom object instance.
+ *
+ * @internal
+ */
+export declare interface _CreateProxyOptions {
+    /** Event emitter for telemetry */
+    eventEmitter?: _RuntimeEventEmitter;
+    /** Save handler for persistence */
+    saveHandler?: _SaveHandler;
+}
+
+/**
+ * Marks a class as a custom fields container for a custom object.
+ *
+ * This decorator is **inert at runtime** — it does not modify the class in any way.
+ * It serves as a marker for the build-time transformer, which discovers the fields
+ * class by this decorator and extracts field metadata from its members.
+ *
+ * The fields class must contain only field declarations (no methods). Use
+ * TSDoc tags from `@stripe/extensibility-jsonschema` on each field to control
+ * display and validation. Exactly one field should be tagged `primaryField`
+ * and at most one `secondaryField`.
+ *
+ * @public
+ */
+export declare function CustomFields(_target: new (...args: unknown[]) => unknown, _context: ClassDecoratorContext): void;
+
+/**
+ * Marks a class as a custom object type.
+ *
+ * This decorator is **inert at runtime** — it does not modify the class in any way.
+ * It serves as a marker for the build-time transformer, which extracts metadata
+ * and generates the necessary platform registration code.
+ *
+ * All naming metadata is expressed via TSDoc annotation tags in a JSDoc comment
+ * on the class: `@apiName`, `@displayName`, `@description`.
+ *
+ * @example
+ * Use TSDoc tags in a JSDoc comment above the decorator,
+ * e.g. `@apiName installment_plan` and `@displayName Installment plan`,
+ * then apply the bare decorator `@CustomObject`.
+ *
+ * @public
+ */
+export declare function CustomObject(_target: new (...args: unknown[]) => unknown, _context: ClassDecoratorContext): void;
+
+/**
+ * Constructor type for custom object classes.
+ *
+ * @internal
+ */
+export declare interface _CustomObjectConstructor<T extends BaseObject = BaseObject> {
+    /** Constructs a new instance of the custom object class. */
+    new (): T;
+    /** Platform metadata attached by the `CustomObject` decorator at build time */
+    __platformMeta__?: _PlatformMetadata;
+}
+
+/**
+ * Executes a custom object method (instance or class/static).
+ * Dispatches to the appropriate handler based on whether instanceId is present.
+ *
+ * @internal
+ */
+export declare function _executeMethod(request: _ExecuteMethodRequest, options?: _ExecuteMethodOptions): Promise<unknown>;
+
+/**
+ * Options for executing a custom object method.
+ *
+ * @internal
+ */
+export declare interface _ExecuteMethodOptions {
+    /** Event emitter for telemetry */
+    eventEmitter?: _RuntimeEventEmitter;
+}
+
+/**
+ * Request structure for invoking custom object methods.
+ *
+ * @internal
+ */
+export declare interface _ExecuteMethodRequest {
+    /** API name of the custom object class */
+    apiName: string;
+    /** Name of the method to invoke */
+    methodName: string;
+    /** Instance ID for instance methods */
+    instanceId?: string;
+    /** Instance field data for hydration (instance methods only) */
+    instanceData?: Record<string, unknown>;
+    /** Arguments to pass to the method */
+    args?: unknown[];
+}
+
+/**
+ * Extracts the proxy state from a proxied object.
+ * Returns undefined if the object is not proxied.
+ *
+ * @internal
+ */
+export declare function _getProxyState(obj: BaseObject): _ProxyState | undefined;
+
+/**
+ * Returns all registered API names.
+ *
+ * @internal
+ */
+export declare function _getRegisteredApiNames(): string[];
+
+/**
+ * Retrieves a registered custom object constructor by api name.
+ *
+ * @internal
+ */
+export declare function _getRegisteredClass(apiName: string): _CustomObjectConstructor | undefined;
+
+/**
+ * Returns a snapshot of the accumulated slated updates from save() or
+ * __queueSave() calls during an action. Callers should call
+ * _clearSlatedUpdates after reading to reset for the next invocation.
+ *
+ * @internal
+ */
+export declare function _getSlatedUpdates(obj: BaseObject): Record<string, unknown>;
+
+/**
+ * Type guard to check if an object has a proxy state.
+ *
+ * @internal
+ */
+export declare function _hasProxyState(obj: unknown): obj is Record<typeof _PROXY_STATE, _ProxyState>;
+
+/**
+ * Symbol key for accessing the instance context (state + handlers).
+ *
+ * Local (non-global) symbol so that external code cannot reconstruct the key
+ * via Symbol.for() and reach into internal proxy state.
+ *
+ * @internal
+ */
+export declare const _INSTANCE_CONTEXT: unique symbol;
+
+/**
+ * Context data stored on each proxied instance.
+ *
+ * @internal
+ */
+export declare interface _InstanceContext {
+    /** Proxy state for change tracking */
+    state: _ProxyState;
+    /** Optional event emitter for telemetry */
+    eventEmitter?: _RuntimeEventEmitter;
+    /** Optional save handler for persistence */
+    saveHandler?: _SaveHandler;
+}
+
+/**
+ * Context type that restricts decorator application to instance methods only.
+ * Uses `{ readonly static: false }` to make TypeScript reject `@Action` on static methods.
+ *
+ * @public
+ */
+export declare type InstanceMethodDecoratorContext = { readonly static: false } & ClassMethodDecoratorContext;
+
+/**
+ * Event emitted when a method invocation begins.
+ *
+ * @internal
+ */
+export declare interface _InvokeBeginEvent {
+    /** Discriminant for the invoke:begin event. */
+    type: 'invoke:begin';
+    /** The method invocation request being dispatched. */
+    request: _ExecuteMethodRequest;
+}
+
+/**
+ * Event emitted when a method invocation completes successfully.
+ *
+ * @internal
+ */
+export declare interface _InvokeCompleteEvent {
+    /** Discriminant for the invoke:complete event. */
+    type: 'invoke:complete';
+    /** Value returned by the method. */
+    result: unknown;
+}
+
+/**
+ * Event emitted when a method invocation throws an error.
+ *
+ * @internal
+ */
+export declare interface _InvokeErrorEvent {
+    /** Discriminant for the invoke:error event. */
+    type: 'invoke:error';
+    /** The thrown error value. */
+    error: unknown;
+}
+
+/**
+ * Checks if a field should be tracked for changes.
+ *
+ * @internal
+ */
+export declare function _isTrackedField(field: string): boolean;
+
+/**
+ * Persists a custom object instance to the platform.
+ * Throws if the object is not proxied.
+ *
+ * @internal
+ */
+export declare function _persistObject(obj: BaseObject, options?: _PersistOptions): Promise<void>;
+
+/**
+ * Options for persistence operations.
+ *
+ * @internal
+ */
+export declare interface _PersistOptions {
+    /** Event emitter for telemetry */
+    eventEmitter?: _RuntimeEventEmitter;
+    /** Fetch function (for testing with mocks) */
+    fetchFn?: typeof fetch;
+    /** Base URL for the persistence API */
+    baseUrl?: string;
+}
+
+/**
+ * Platform metadata attached to custom object constructors via decorators.
+ *
+ * @internal
+ */
+export declare interface _PlatformMetadata {
+    /** API name of the custom object */
+    apiName: string;
+    /** Registered actions by category */
+    actions: { instance: Record<string, _ActionMetadata> };
+}
+
+/**
+ * Result of creating a proxied instance.
+ *
+ * @internal
+ */
+export declare interface _ProxiedObject<T> {
+    /** The proxied instance */
+    proxy: T;
+    /** The proxy state for change tracking */
+    state: _ProxyState;
+}
+
+/**
+ * Symbol key for accessing the proxy state on a proxied instance.
+ *
+ * Local (non-global) symbol so that external code cannot reconstruct the key
+ * via Symbol.for() and reach into internal proxy state.
+ *
+ * @internal
+ */
+export declare const _PROXY_STATE: unique symbol;
+
+/**
+ * Event emitted when a field is set through the proxy.
+ *
+ * @internal
+ */
+export declare interface _ProxySetEvent {
+    /** Discriminant for the proxy:set event. */
+    type: 'proxy:set';
+    /** Name of the field that was set. */
+    field: string;
+    /** New value assigned to the field. */
+    value: unknown;
+    /** Unix epoch milliseconds when the set occurred. */
+    timestamp: number;
+}
+
+/**
+ * Internal state maintained by the proxy for change tracking.
+ *
+ * @internal
+ */
+export declare interface _ProxyState {
+    /** Current field values as seen through the proxy */
+    fields: Record<string, unknown>;
+    /** Queue of updates since last save */
+    pendingUpdates: _UpdateFrame[];
+    /** Snapshot of data as it existed at last save */
+    lastSavedSnapshot: Record<string, unknown>;
+    /**
+     * When true, the fields proxy (and its recursive sub-proxies) skip
+     * dirty-tracking. Set by the Logic wrapper before hydration from a
+     * platform point-read, cleared immediately after. This prevents
+     * hydration from producing spurious pending updates.
+     *
+     * @internal
+     */
+    hydrating: boolean;
+    /**
+     * Accumulated field updates from save() or __queueSave() calls during
+     * an action execution. Flushed from pendingUpdates by each save call.
+     * The Logic wrapper reads this after the action returns to populate
+     * `updatedFields` in the response envelope, then clears it.
+     *
+     * @internal
+     */
+    slatedUpdates: Record<string, unknown>;
+}
+
+/**
+ * Registers a custom object class by its api name.
+ * Validates that the class has platform metadata attached.
+ *
+ * @internal
+ */
+export declare function _registerClass<T extends BaseObject>(constructor: _CustomObjectConstructor<T>): void;
+
+/**
+ * Union of all runtime events.
+ *
+ * @internal
+ */
+export declare type _RuntimeEvent = _InvokeBeginEvent | _InvokeCompleteEvent | _InvokeErrorEvent | _ProxySetEvent | _SaveBeginEvent | _SaveCompleteEvent | _SpanBeginEvent | _SpanEndEvent | _SpanErrorEvent;
+
+/**
+ * Event emitter interface for runtime telemetry.
+ *
+ * @internal
+ */
+export declare interface _RuntimeEventEmitter {
+    /** Broadcasts an event to all subscribed listeners */
+    emit(event: _RuntimeEvent): void;
+    /** Registers a listener; returns an unsubscribe function */
+    subscribe(listener: (event: _RuntimeEvent) => void): () => void;
+}
+
+/**
+ * Event emitted when a save operation begins.
+ *
+ * @internal
+ */
+export declare interface _SaveBeginEvent {
+    /** Discriminant for the save:begin event. */
+    type: 'save:begin';
+    /** Field data being submitted to the platform. */
+    payload: Record<string, unknown>;
+}
+
+/**
+ * Event emitted when a save operation completes successfully.
+ *
+ * @internal
+ */
+export declare interface _SaveCompleteEvent {
+    /** Discriminant for the save:complete event. */
+    type: 'save:complete';
+    /** Raw response returned by the platform after a successful save. */
+    response: Record<string, unknown>;
+}
+
+/**
+ * Handler function that persists a custom object instance.
+ * This is called by BaseObject.save() when configured.
+ *
+ * @internal
+ */
+export declare type _SaveHandler = (obj: BaseObject, state: _ProxyState, eventEmitter?: _RuntimeEventEmitter) => Promise<SaveResult>;
+
+/**
+ * Result returned from save operations.
+ *
+ * @public
+ */
+export declare interface SaveResult {
+    /** Number of fields updated */
+    updatedFieldCount: number;
+}
+
+/**
+ * Event emitted when a method execution span begins.
+ *
+ * @internal
+ */
+export declare interface _SpanBeginEvent {
+    /** Discriminant for the span:begin event. */
+    type: 'span:begin';
+    /** Unique identifier for correlating begin/end/error events within a single span. */
+    spanId: string;
+    /** Name of the method being executed. */
+    name: string;
+    /** Arguments passed to the method. */
+    params?: unknown;
+    /** Whether the method is a static class method. */
+    isStatic?: boolean;
+    /** Nesting depth for recursive or nested method calls. */
+    depth?: number;
+}
+
+/**
+ * Event emitted when a method execution span ends successfully.
+ *
+ * @internal
+ */
+export declare interface _SpanEndEvent {
+    /** Discriminant for the span:end event. */
+    type: 'span:end';
+    /** Unique identifier correlating this event to the matching span:begin. */
+    spanId: string;
+    /** Name of the method that completed. */
+    name: string;
+    /** Elapsed time in milliseconds from span:begin to span:end. */
+    duration: number;
+    /** Value returned by the method, if any. */
+    result?: unknown;
+    /** Whether the method is a static class method. */
+    isStatic?: boolean;
+    /** Nesting depth for recursive or nested method calls. */
+    depth?: number;
+}
+
+/**
+ * Event emitted when a method execution span encounters an error.
+ *
+ * @internal
+ */
+export declare interface _SpanErrorEvent {
+    /** Discriminant for the span:error event. */
+    type: 'span:error';
+    /** Unique identifier correlating this event to the matching span:begin. */
+    spanId: string;
+    /** Name of the method that threw. */
+    name: string;
+    /** Elapsed time in milliseconds from span:begin to the point of failure. */
+    duration: number;
+    /** Serializable representation of the thrown error. */
+    error: {
+        message: string;
+        name: string;
+        stack?: string;
+    };
+    /** Whether the method is a static class method. */
+    isStatic?: boolean;
+    /** Nesting depth for recursive or nested method calls. */
+    depth?: number;
+}
+
+/**
+ * Fields that are not tracked for changes by the proxy.
+ * These are system-managed fields that should not appear in pendingUpdates.
+ *
+ * @internal
+ */
+export declare const _UNTRACKED_FIELDS: Set<string>;
+
+/**
+ * Represents a single field update in the proxy's change tracking.
+ *
+ * @internal
+ */
+export declare interface _UpdateFrame {
+    /** Name of the field that was modified. */
+    field: string;
+    /** Value assigned to the field at the time of the update. */
+    value: unknown;
+    /** Unix epoch milliseconds when the update was recorded. */
+    timestamp: number;
+}
+
+export { }