@stripe/extensibility-script-build-tools 1.5.4

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/README.md

@@ -0,0 +1,180 @@
+# @stripe/extensibility-script-build-tools
+
+An esbuild plugin and dispatch shim for Stripe script extension entry points.
+
+## What it does
+
+The plugin intercepts the extension entry point during bundling and appends a
+`__stripe_platform_dispatch__` export — a table mapping the default-export class and each
+extension method to a pre-built factory closure. At runtime, the dispatch shim reads the
+table and calls through it: wire arguments go in, the factory converts them to SDK types,
+instantiates the class, calls the method, converts the SDK result back to wire format, and
+returns.
+
+This approach means transformation happens exactly once, at the true entry point, and the
+extension class itself is never modified. Methods can call each other freely.
+
+The plugin also introspects the class's Config type argument and, if it's a user-defined
+type, generates and appends a config descriptor function that the factory uses to validate
+and coerce config values from wire JSON.
+
+## Usage
+
+### Pre-flight analysis
+
+Before adding the plugin to a build, call `analyzeForDispatch` to check whether a full
+dispatch shim can be built for the entry point:
+
+```typescript
+import {
+  analyzeForDispatch,
+  createPlatformDispatchPlugin,
+} from '@stripe/extensibility-script-build-tools';
+import esbuild from 'esbuild';
+
+const analysis = analyzeForDispatch('src/index.ts');
+
+if (analysis !== null) {
+  // Full platform dispatch shim will be installed.
+  await esbuild.build({
+    entryPoints: ['src/index.ts'],
+    bundle: true,
+    plugins: [createPlatformDispatchPlugin(analysis)],
+  });
+} else {
+  // No shim. Build normally and route calls without dispatch.
+  await esbuild.build({ entryPoints: ['src/index.ts'], bundle: true });
+}
+```
+
+`analyzeForDispatch` returns `null` when any condition is not met:
+
+- The entry point has no named default export
+- The export does not implement a recognised extension interface
+- The installed SDK predates platform dispatch (no `$platformWrap*` factories)
+
+For non-extension scripts and any other configuration that doesn't conform to the
+extension framework, `null` is returned and the build proceeds without a shim.
+
+### Dispatch
+
+After building the bundle, import it and call the `dispatch` method baked
+directly into the table:
+
+```typescript
+import { DISPATCH_TABLE_EXPORT } from '@stripe/extensibility-script-build-tools';
+
+// mod is the dynamically-imported bundle
+const table = mod[DISPATCH_TABLE_EXPORT] as
+  | {
+      dispatch: (
+        exportName: string,
+        methodName: string,
+        wireArgs: unknown,
+        wireConfig: unknown,
+        ctx: unknown
+      ) => unknown;
+    }
+  | undefined;
+
+const result = table?.dispatch('default', 'computeDiscounts', wireArgs, wireConfig, ctx);
+```
+
+`dispatch` is a closure embedded in the bundle by the plugin. Calling it does
+not require importing any runtime helper from this package.
+
+## How the dispatch table works
+
+The plugin appends a block like this to the extension source:
+
+```typescript
+import * as __stripe_sdk_ext__ from '@stripe/apps-extensibility-sdk/extensions';
+export const __stripe_platform_dispatch__ = (() => {
+  const e = {
+    default: {
+      __class__: MyExtensionClass,
+      computeDiscounts:
+        __stripe_sdk_ext__.Billing.Bill.DiscountCalculation.$platformWrapComputeDiscounts(
+          transformMyConfig
+        ),
+    },
+  };
+  return Object.assign(e, {
+    dispatch: (exportName, methodName, wireArgs, wireConfig, ctx) => {
+      const entry = e[exportName];
+      // ... error checks ...
+      return entry[methodName](entry.__class__, wireArgs, wireConfig, ctx);
+    },
+  });
+})();
+```
+
+- `__class__` is the default-export class constructor, used to instantiate a fresh object
+  per call.
+- Each method entry is a closure `(cls, wireArgs, wireConfig, ctx) => wireResult` returned
+  by the `$platformWrap*` factory in the SDK. Config transformer is baked in if present.
+- `dispatch(exportName, methodName, wireArgs, wireConfig, ctx)` is a stable one-shot
+  entry point that looks up the export and method from the closure-captured entries and
+  calls through. Callers do not need any runtime helper from this package to invoke it.
+
+## Code flow
+
+```
+BUILD TIME
+──────────
+entry.ts  ──►  analyzeForDispatch()
+                   │
+                   ├─ resolveExtension()      ts-morph: reads implements clause,
+                   │                          looks up FQNs in BY_SDK_FQN registry
+                   │
+                   ├─ hasPlatformWrap()       require() the SDK; check $platformWrap*
+                   │                          exists → true (else return null)
+                   │
+                   └─ returns DispatchAnalysis (opaque)
+
+entry.ts  ──►  esbuild plugin (onLoad) — only if analysis is non-null
+                   │
+                   ├─ resolveConfigTransformer()  analyse Config type arg; emit
+                   │                              descriptor function if user-defined
+                   │
+                   └─ append to source:
+                        import * as __stripe_sdk_ext__ from '…/extensions';
+                        export const __stripe_platform_dispatch__ = (() => {
+                          const e = {
+                            default: {
+                              __class__: MyClass,
+                              computeDiscounts:
+                                __stripe_sdk_ext__.Billing.Bill
+                                  .DiscountCalculation
+                                  .$platformWrapComputeDiscounts(transformConfig),
+                            }
+                          };
+                          return Object.assign(e, { dispatch: … });
+                        })();
+
+RUNTIME
+───────
+platform  ──►  mod['__stripe_platform_dispatch__'].dispatch(
+                   'default', 'computeDiscounts', wireArgs, wireConfig, ctx)
+                   │
+                   └─ $platformWrapComputeDiscounts closure:
+                               1. apply(ArgsDescriptor, ProtoWireToType, wireArgs)
+                               2. transformConfig(wireConfig)
+                               3. new MyClass().computeDiscounts(request, config, ctx)
+                               4. apply(ResultDescriptor, TypeToProtoWire, result)
+                               └─► wireResult
+```
+
+## Failure behaviour
+
+- **`analyzeForDispatch` returns `null`.** Entry points without a named default export,
+  without a recognised interface, or pinned to a pre-dispatch SDK version all return
+  `null`. The caller builds without the plugin and records that calls should bypass
+  dispatch.
+
+- **`BuildUserError` thrown by `analyzeForDispatch`.** The source contains a reserved
+  identifier (`__stripe_sdk_ext__`, `__stripe_platform_dispatch__`,
+  `__stripe_shim_active__`). The author must rename the colliding identifier.
+
+- **`BuildSystemError` thrown by the plugin.** An unexpected error during config
+  transformer resolution. Wraps the original error.

package/dist/config-introspect.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generates a config transformer for the default-export class in `entryPoint`.
+ *
+ * Resolves the first Config type argument from the class's `implements` clause,
+ * analyzes its structure, and returns the generated TypeScript code plus the
+ * exported function name. Returns `null` if no parseable Config type is found.
+ *
+ * The returned `code` should be appended to the entry point source before
+ * bundling. The `functionName` is the identifier to pass as `configTransformer`
+ * in the `$platformWrap*` factory call.
+ * @internal
+ */
+export declare function resolveConfigTransformer(entryPoint: string): {
+    code: string;
+    functionName: string;
+} | null;
+//# sourceMappingURL=config-introspect.d.ts.map

package/dist/config-introspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-introspect.d.ts","sourceRoot":"","sources":["../src/config-introspect.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA6B/C"}

package/dist/dispatch.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Stable one-shot dispatch function baked into the table by the plugin.
+ * @internal
+ */
+export type BuiltInDispatchFn = (exportName: string, methodName: string, wireArgs: unknown, wireConfig: unknown, ctx: unknown) => unknown;
+/** @internal */
+export interface DispatchTable {
+    dispatch: BuiltInDispatchFn;
+}
+/**
+ * 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
+ */
+export declare function _createPlatformDispatch(mod: Record<string, unknown>): ((exportName: string, methodName: string, wireArgs: unknown, wireConfig: unknown, ctx: unknown) => unknown) | null;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,OAAO,EACnB,GAAG,EAAE,OAAO,KACT,OAAO,CAAC;AAEb,gBAAgB;AAChB,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAE1B,CAAC,CACC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,OAAO,EACnB,GAAG,EAAE,OAAO,KACT,OAAO,CAAC,GACb,IAAI,CAQP"}

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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
+ */
+export 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
+ */
+export 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);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,gEAAgE;IACvD,IAAI,SAAqB;CACnC;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAMxC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,OAAO;IANzB,gEAAgE;IACvD,IAAI,SAAuB;gBAGlC,OAAO,EAAE,MAAM;IACf,2DAA2D;IAClD,KAAK,EAAE,OAAO;CAI1B"}

package/dist/extensibility-script-build-tools-alpha.d.ts

@@ -0,0 +1,19 @@
+import * as esbuild from 'esbuild';
+
+/* Excluded from this release type: _analyzeForDispatch */
+
+declare const _brand: unique symbol;
+
+/* Excluded from this release type: _BuildSystemError */
+
+/* Excluded from this release type: _BuildUserError */
+
+/* Excluded from this release type: _createPlatformDispatch */
+
+/* Excluded from this release type: _createPlatformDispatchPlugin */
+
+/* Excluded from this release type: _DISPATCH_TABLE_EXPORT */
+
+/* Excluded from this release type: _DispatchAnalysis */
+
+export { }

package/dist/extensibility-script-build-tools-beta.d.ts

@@ -0,0 +1,19 @@
+import * as esbuild from 'esbuild';
+
+/* Excluded from this release type: _analyzeForDispatch */
+
+declare const _brand: unique symbol;
+
+/* Excluded from this release type: _BuildSystemError */
+
+/* Excluded from this release type: _BuildUserError */
+
+/* Excluded from this release type: _createPlatformDispatch */
+
+/* Excluded from this release type: _createPlatformDispatchPlugin */
+
+/* Excluded from this release type: _DISPATCH_TABLE_EXPORT */
+
+/* Excluded from this release type: _DispatchAnalysis */
+
+export { }

package/dist/extensibility-script-build-tools-internal.d.ts

@@ -0,0 +1,93 @@
+import * as esbuild from 'esbuild';
+
+/**
+ * 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
+ */
+export declare function _analyzeForDispatch(entryPoint: string): _DispatchAnalysis | null;
+
+declare const _brand: unique symbol;
+
+/**
+ * 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
+ */
+export 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);
+}
+
+/**
+ * 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
+ */
+export declare class _BuildUserError extends Error {
+    /** Error class name, overridden for stack trace readability. */
+    name: string;
+}
+
+/**
+ * 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
+ */
+export declare function _createPlatformDispatch(mod: Record<string, unknown>): ((exportName: string, methodName: string, wireArgs: unknown, wireConfig: unknown, ctx: unknown) => unknown) | 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
+ */
+export declare function _createPlatformDispatchPlugin(analysis: _DispatchAnalysis): esbuild.Plugin;
+
+/**
+ * Name of the dispatch table export injected by the platform dispatch plugin.
+ * @internal
+ */
+export declare const _DISPATCH_TABLE_EXPORT = "__stripe_platform_dispatch__";
+
+/**
+ * Pre-computed analysis result from `_analyzeForDispatch`. Treat as opaque —
+ * pass directly to `_createPlatformDispatchPlugin` without inspecting or
+ * constructing.
+ * @internal
+ */
+export declare interface _DispatchAnalysis {
+    /** Nominal brand that prevents construction outside this module. */
+    readonly [_brand]: never;
+}
+
+export { }

package/dist/extensibility-script-build-tools-public.d.ts

@@ -0,0 +1,19 @@
+import * as esbuild from 'esbuild';
+
+/* Excluded from this release type: _analyzeForDispatch */
+
+declare const _brand: unique symbol;
+
+/* Excluded from this release type: _BuildSystemError */
+
+/* Excluded from this release type: _BuildUserError */
+
+/* Excluded from this release type: _createPlatformDispatch */
+
+/* Excluded from this release type: _createPlatformDispatchPlugin */
+
+/* Excluded from this release type: _DISPATCH_TABLE_EXPORT */
+
+/* Excluded from this release type: _DispatchAnalysis */
+
+export { }