@stripe/extensibility-script-build-tools 1.5.4

package/dist/index.d.cts

@@ -0,0 +1,89 @@
+import * as esbuild from 'esbuild';
+
+/**
+ * Thrown when the user's extension source contains a problem that prevents
+ * the platform dispatch plugin from processing it. The message is directly
+ * actionable by the extension author.
+ * @internal
+ */
+declare class _BuildUserError extends Error {
+    /** Error class name, overridden for stack trace readability. */
+    name: string;
+}
+/**
+ * Wraps an unexpected error caught by the platform dispatch plugin. Indicates
+ * a bug in the plugin or an unanticipated environment condition, not a problem
+ * with the extension author's code.
+ * @internal
+ */
+declare class _BuildSystemError extends Error {
+    /** The original error that triggered this system error. */
+    readonly cause: unknown;
+    /** Error class name, overridden for stack trace readability. */
+    name: string;
+    constructor(message: string, 
+    /** The original error that triggered this system error. */
+    cause: unknown);
+}
+
+declare const _brand: unique symbol;
+/**
+ * Pre-computed analysis result from `_analyzeForDispatch`. Treat as opaque —
+ * pass directly to `_createPlatformDispatchPlugin` without inspecting or
+ * constructing.
+ * @internal
+ */
+interface _DispatchAnalysis {
+    /** Nominal brand that prevents construction outside this module. */
+    readonly [_brand]: never;
+}
+/**
+ * Analyzes the extension entry point to determine if a full platform dispatch
+ * shim can be built. Returns opaque analysis data when all conditions are met:
+ *
+ * - The entry point has a named default export
+ * - The export implements a recognised extension interface
+ * - The installed SDK version provides `$platformWrap*` factories
+ *
+ * Returns `null` if any condition is not met (old SDK, unrecognised interface,
+ * no named default export, or non-extension script). The caller should treat
+ * `null` as "build without the plugin".
+ *
+ * Throws `_BuildUserError` if a reserved identifier collision is detected in
+ * the source (only checked when a shim would otherwise be installed).
+ * @internal
+ */
+declare function _analyzeForDispatch(entryPoint: string): _DispatchAnalysis | null;
+/**
+ * Creates an esbuild plugin that appends a proxy dispatch table export
+ * (`__stripe_platform_dispatch__`) to the extension entry point.
+ *
+ * Requires pre-computed analysis from `_analyzeForDispatch`. The plugin uses
+ * the cached source and descriptor data directly, avoiding redundant file
+ * reads and SDK introspection during the build.
+ * @internal
+ */
+declare function _createPlatformDispatchPlugin(analysis: _DispatchAnalysis): esbuild.Plugin;
+
+/**
+ * Creates a platform dispatch invoker from a bundled extension module.
+ *
+ * Reads `mod['__stripe_platform_dispatch__'].dispatch` and returns a callable
+ * that forwards to it.
+ *
+ * Returns `null` only if the dispatch table export is entirely absent —
+ * meaning the module was not built with the platform dispatch plugin at all.
+ * When the plugin was used, the table is always present (even for entry points
+ * with no recognised extension interface), so callers can use `null` as an
+ * unambiguous "plugin not run" signal.
+ * @internal
+ */
+declare function _createPlatformDispatch(mod: Record<string, unknown>): ((exportName: string, methodName: string, wireArgs: unknown, wireConfig: unknown, ctx: unknown) => unknown) | null;
+
+/**
+ * Name of the dispatch table export injected by the platform dispatch plugin.
+ * @internal
+ */
+declare const _DISPATCH_TABLE_EXPORT = "__stripe_platform_dispatch__";
+
+export { _BuildSystemError, _BuildUserError, _DISPATCH_TABLE_EXPORT, type _DispatchAnalysis, _analyzeForDispatch, _createPlatformDispatch, _createPlatformDispatchPlugin };

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import * as esbuild from 'esbuild';
+
+/**
+ * Thrown when the user's extension source contains a problem that prevents
+ * the platform dispatch plugin from processing it. The message is directly
+ * actionable by the extension author.
+ * @internal
+ */
+declare class _BuildUserError extends Error {
+    /** Error class name, overridden for stack trace readability. */
+    name: string;
+}
+/**
+ * Wraps an unexpected error caught by the platform dispatch plugin. Indicates
+ * a bug in the plugin or an unanticipated environment condition, not a problem
+ * with the extension author's code.
+ * @internal
+ */
+declare class _BuildSystemError extends Error {
+    /** The original error that triggered this system error. */
+    readonly cause: unknown;
+    /** Error class name, overridden for stack trace readability. */
+    name: string;
+    constructor(message: string, 
+    /** The original error that triggered this system error. */
+    cause: unknown);
+}
+
+declare const _brand: unique symbol;
+/**
+ * Pre-computed analysis result from `_analyzeForDispatch`. Treat as opaque —
+ * pass directly to `_createPlatformDispatchPlugin` without inspecting or
+ * constructing.
+ * @internal
+ */
+interface _DispatchAnalysis {
+    /** Nominal brand that prevents construction outside this module. */
+    readonly [_brand]: never;
+}
+/**
+ * Analyzes the extension entry point to determine if a full platform dispatch
+ * shim can be built. Returns opaque analysis data when all conditions are met:
+ *
+ * - The entry point has a named default export
+ * - The export implements a recognised extension interface
+ * - The installed SDK version provides `$platformWrap*` factories
+ *
+ * Returns `null` if any condition is not met (old SDK, unrecognised interface,
+ * no named default export, or non-extension script). The caller should treat
+ * `null` as "build without the plugin".
+ *
+ * Throws `_BuildUserError` if a reserved identifier collision is detected in
+ * the source (only checked when a shim would otherwise be installed).
+ * @internal
+ */
+declare function _analyzeForDispatch(entryPoint: string): _DispatchAnalysis | null;
+/**
+ * Creates an esbuild plugin that appends a proxy dispatch table export
+ * (`__stripe_platform_dispatch__`) to the extension entry point.
+ *
+ * Requires pre-computed analysis from `_analyzeForDispatch`. The plugin uses
+ * the cached source and descriptor data directly, avoiding redundant file
+ * reads and SDK introspection during the build.
+ * @internal
+ */
+declare function _createPlatformDispatchPlugin(analysis: _DispatchAnalysis): esbuild.Plugin;
+
+/**
+ * Creates a platform dispatch invoker from a bundled extension module.
+ *
+ * Reads `mod['__stripe_platform_dispatch__'].dispatch` and returns a callable
+ * that forwards to it.
+ *
+ * Returns `null` only if the dispatch table export is entirely absent —
+ * meaning the module was not built with the platform dispatch plugin at all.
+ * When the plugin was used, the table is always present (even for entry points
+ * with no recognised extension interface), so callers can use `null` as an
+ * unambiguous "plugin not run" signal.
+ * @internal
+ */
+declare function _createPlatformDispatch(mod: Record<string, unknown>): ((exportName: string, methodName: string, wireArgs: unknown, wireConfig: unknown, ctx: unknown) => unknown) | null;
+
+/**
+ * Name of the dispatch table export injected by the platform dispatch plugin.
+ * @internal
+ */
+declare const _DISPATCH_TABLE_EXPORT = "__stripe_platform_dispatch__";
+
+export { _BuildSystemError, _BuildUserError, _DISPATCH_TABLE_EXPORT, type _DispatchAnalysis, _analyzeForDispatch, _createPlatformDispatch, _createPlatformDispatchPlugin };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,mBAAmB,EACnB,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,KAAK,iBAAiB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC"}