@stripe/extensibility-dev-tools 0.23.5

package/dist/bin/manifest.js

@@ -0,0 +1,663 @@
+#!/usr/bin/env node
+
+// src/bin/manifest.ts
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { _createLogger, _writeJsonOutput } from "@stripe/extensibility-tool-utils";
+
+// src/manifest/stripe-app-manifest.ts
+import { _toSnakeCase } from "@stripe/extensibility-tool-utils";
+
+// src/manifest/manifest-v1.ts
+import { readFileSync, writeFileSync, existsSync } from "fs";
+function formatCustomObjectEntry(entry) {
+  return `${entry.filePath}#${entry.className}`;
+}
+function parseCustomObjectEntry(entryString) {
+  const parts = entryString.split("#");
+  if (parts.length !== 2) {
+    throw new Error(
+      `Invalid object entry format: ${entryString}. Expected format: "path/to/file.d.ts#ClassName"`
+    );
+  }
+  const [filePath, className] = parts;
+  if (!filePath || !className) {
+    throw new Error(
+      `Invalid object entry format: ${entryString}. Expected format: "path/to/file.d.ts#ClassName"`
+    );
+  }
+  return { filePath, className };
+}
+var _ManifestV1 = class __ManifestV1 {
+  constructor(filePath, data) {
+    this.filePath = filePath;
+    this.data = data;
+  }
+  /**
+   * Load stripe-app.json from disk
+   * @param filePath - Path to stripe-app.json
+   * @throws Error if file is invalid or cannot be read
+   */
+  static load(filePath) {
+    if (!existsSync(filePath)) {
+      throw new Error(`Manifest file not found: ${filePath}`);
+    }
+    const content = readFileSync(filePath, "utf-8");
+    const data = JSON.parse(content);
+    if (!data.id) {
+      throw new Error('Manifest must contain "id" field');
+    }
+    return new __ManifestV1(filePath, data);
+  }
+  /**
+   * Get the app ID from the manifest
+   */
+  getAppId() {
+    return this.data.id;
+  }
+  /**
+   * Get the app name from the manifest
+   */
+  getAppName() {
+    return this.data.name;
+  }
+  /**
+   * Get all custom objects as structured entries
+   */
+  getCustomObjects() {
+    const entries = [];
+    if (this.data.exported_custom_objects) {
+      for (const entry of this.data.exported_custom_objects) {
+        entries.push(parseCustomObjectEntry(entry));
+      }
+    }
+    return entries;
+  }
+  /**
+   * Check if a custom object entry exists in the manifest
+   */
+  hasCustomObject(entry) {
+    const objects = this.getCustomObjects();
+    return objects.some(
+      (existing) => existing.filePath === entry.filePath && existing.className === entry.className
+    );
+  }
+  /**
+   * Add a custom object entry to the manifest
+   * Does nothing if entry already exists
+   * @returns true if entry was added, false if it already existed
+   */
+  addCustomObject(entry) {
+    if (this.hasCustomObject(entry)) {
+      return false;
+    }
+    const entryString = formatCustomObjectEntry(entry);
+    this.data.exported_custom_objects ??= [];
+    this.data.exported_custom_objects.push(entryString);
+    return true;
+  }
+  /**
+   * Remove a custom object entry from the manifest
+   * @returns true if entry was removed, false if it didn't exist
+   */
+  removeCustomObject(entry) {
+    if (!this.data.exported_custom_objects) {
+      return false;
+    }
+    const entryString = formatCustomObjectEntry(entry);
+    const originalLength = this.data.exported_custom_objects.length;
+    this.data.exported_custom_objects = this.data.exported_custom_objects.filter(
+      (e) => e !== entryString
+    );
+    if (this.data.exported_custom_objects.length === 0) {
+      delete this.data.exported_custom_objects;
+    }
+    return this.data.exported_custom_objects?.length !== originalLength;
+  }
+  /**
+   * Get the raw manifest data (for reading other fields)
+   */
+  getRawData() {
+    return this.data;
+  }
+  /**
+   * Save changes back to disk
+   */
+  save() {
+    writeFileSync(this.filePath, JSON.stringify(this.data, null, 2) + "\n");
+  }
+};
+
+// src/manifest/manifest-v2.ts
+import { readFile, writeFile } from "fs/promises";
+import * as yaml from "yaml";
+import { _toPascalCase } from "@stripe/extensibility-tool-utils";
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isYamlObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateManifestV2Data(data) {
+  if (!isNonEmptyString(data.id)) {
+    throw new Error('Manifest must contain non-empty "id" field');
+  }
+  if (!isNonEmptyString(data.name)) {
+    throw new Error('Manifest must contain non-empty "name" field');
+  }
+  if (!isNonEmptyString(data.version)) {
+    throw new Error('Manifest must contain non-empty "version" field');
+  }
+  if ("extensions" in data && !Array.isArray(data.extensions)) {
+    throw new Error('Manifest field "extensions" must be an array when provided');
+  }
+  if ("custom_object_definitions" in data && !isYamlObject(data.custom_object_definitions)) {
+    throw new Error(
+      'Manifest field "custom_object_definitions" must be an object with a "definitions" array'
+    );
+  }
+  const coBlock = data.custom_object_definitions;
+  const definitions = isYamlObject(coBlock) ? coBlock.definitions : void 0;
+  if (!definitions) {
+    return;
+  }
+  if (!Array.isArray(definitions)) {
+    throw new Error(
+      'Manifest field "custom_object_definitions.definitions" must be an array'
+    );
+  }
+  for (let i = 0; i < definitions.length; i++) {
+    const def = definitions[i];
+    const prefix = `custom_object_definitions.definitions[${String(i)}]`;
+    if (!isYamlObject(def) || !isNonEmptyString(def.id)) {
+      throw new Error(
+        `${prefix}: missing or invalid "id" field. Got: ${JSON.stringify(def)}`
+      );
+    }
+    if (!isYamlObject(def.specification)) {
+      throw new Error(
+        `${prefix}: missing or invalid "specification" field. Expected: { type: "typescript", content: "path/to/file.ts" }. Got: ${JSON.stringify(def)}`
+      );
+    }
+    if (!isNonEmptyString(def.specification.type)) {
+      throw new Error(
+        `${prefix}: missing or invalid "specification.type" field. Got: ${JSON.stringify(def)}`
+      );
+    }
+    if (!isNonEmptyString(def.specification.content)) {
+      throw new Error(
+        `${prefix}: missing or invalid "specification.content" field. Got: ${JSON.stringify(def)}`
+      );
+    }
+  }
+}
+var _ManifestV2 = class __ManifestV2 {
+  constructor(filePath, data) {
+    this.filePath = filePath;
+    this.data = data;
+  }
+  /**
+   * Load stripe-app.yaml from disk
+   * @param filePath - Path to stripe-app.yaml
+   * @throws Error if file is invalid or cannot be read
+   */
+  static async load(filePath) {
+    try {
+      const content = await readFile(filePath, "utf-8");
+      const parsed = yaml.parse(content);
+      if (!isYamlObject(parsed)) {
+        throw new Error("Invalid stripe-app.yaml format: root must be an object");
+      }
+      validateManifestV2Data(parsed);
+      const data = parsed;
+      data.extensions ??= [];
+      return new __ManifestV2(filePath, data);
+    } catch (err) {
+      if (err instanceof Error) {
+        throw new Error(`Error reading stripe-app.yaml: ${err.message}`);
+      }
+      throw new Error(`Error reading stripe-app.yaml: ${String(err)}`);
+    }
+  }
+  /**
+   * Get the app ID from the manifest
+   */
+  getAppId() {
+    return this.data.id;
+  }
+  /**
+   * Get the app name from the manifest
+   */
+  getAppName() {
+    return this.data.name;
+  }
+  // ============================================================
+  // Custom Objects
+  // ============================================================
+  /**
+   * Get all custom object definitions, parsed into internal format.
+   * Entries are guaranteed structurally valid by load-time validation.
+   */
+  getCustomObjects() {
+    const definitions = this.data.custom_object_definitions?.definitions;
+    if (!definitions || definitions.length === 0) {
+      return [];
+    }
+    return definitions.map((def) => ({
+      id: def.id,
+      type: def.specification.type,
+      path: def.specification.content,
+      name: _toPascalCase(def.id)
+    }));
+  }
+  /**
+   * Check if a custom object exists by id
+   */
+  hasCustomObject(id) {
+    const definitions = this.data.custom_object_definitions?.definitions;
+    if (!definitions) return false;
+    return definitions.some((def) => def.id === id);
+  }
+  /**
+   * Add a custom object definition.
+   *
+   * Identity is keyed on `id` alone. The export name is derived via
+   * `_toPascalCase(id)` at read time, so `id` should be valid snake_case
+   * (e.g., "device", "loyalty_card", "http_request").
+   *
+   * @param id - Object identifier (e.g., "device", "loyalty_card")
+   * @param content - Path to the definition file (e.g., "src/device.object.ts")
+   * @param type - Specification type, defaults to "typescript"
+   * @returns true if added, false if already exists
+   */
+  addCustomObject(id, content, type = "typescript") {
+    if (this.hasCustomObject(id)) {
+      return false;
+    }
+    this.data.custom_object_definitions ??= {};
+    this.data.custom_object_definitions.definitions ??= [];
+    this.data.custom_object_definitions.definitions.push({
+      id,
+      specification: { type, content }
+    });
+    return true;
+  }
+  /**
+   * Remove a custom object definition by id
+   * @param id - Object identifier to remove
+   * @returns true if removed, false if not found
+   */
+  removeCustomObject(id) {
+    const block = this.data.custom_object_definitions;
+    if (!block?.definitions) {
+      return false;
+    }
+    const originalLength = block.definitions.length;
+    block.definitions = block.definitions.filter((def) => def.id !== id);
+    const newLength = block.definitions.length;
+    if (newLength === 0) {
+      delete this.data.custom_object_definitions;
+    }
+    return newLength < originalLength;
+  }
+  // ============================================================
+  // Extensions
+  // ============================================================
+  /**
+   * Add a new extension or update an existing one by ID
+   * If an extension with the provided ID exists, it will be replaced entirely
+   * @param extension - Extension configuration with all required fields including id
+   * @returns The extension ID
+   */
+  addOrUpdateExtension(extension) {
+    const newExtension = {
+      id: extension.id,
+      name: extension.name,
+      interface_id: extension.interface_id,
+      version: extension.version,
+      ...extension.description !== void 0 && {
+        description: extension.description
+      },
+      ...extension.stripe_version !== void 0 && {
+        stripe_version: extension.stripe_version
+      },
+      ...extension.script_entry_point !== void 0 && {
+        script_entry_point: extension.script_entry_point
+      },
+      ...extension.script !== void 0 && { script: extension.script },
+      permissions: extension.permissions,
+      methods: extension.methods,
+      ...extension.configuration !== void 0 && {
+        configuration: extension.configuration
+      },
+      ...extension.endpoints !== void 0 && {
+        endpoints: extension.endpoints
+      }
+    };
+    this.data.extensions ??= [];
+    const existingIndex = this.data.extensions.findIndex(
+      (ext) => ext.id === extension.id
+    );
+    if (existingIndex !== -1) {
+      this.data.extensions[existingIndex] = newExtension;
+    } else {
+      this.data.extensions.push(newExtension);
+    }
+    return extension.id;
+  }
+  /**
+   * Get a read-only view of all extensions
+   */
+  getExtensions() {
+    return this.data.extensions ?? [];
+  }
+  /**
+   * Get the raw manifest data (for reading other fields)
+   */
+  getRawData() {
+    return this.data;
+  }
+  /**
+   * Save changes back to disk
+   * @throws Error if file cannot be written
+   */
+  async save() {
+    try {
+      const updatedContent = yaml.stringify(this.data);
+      await writeFile(this.filePath, updatedContent, "utf-8");
+    } catch (err) {
+      if (err instanceof Error) {
+        throw new Error(`Error writing stripe-app.yaml: ${err.message}`);
+      }
+      throw new Error(`Error writing stripe-app.yaml: ${String(err)}`);
+    }
+  }
+};
+
+// src/manifest/stripe-app-manifest.ts
+var _StripeAppManifest = class __StripeAppManifest {
+  constructor(manifestPath, version, v1, v2) {
+    this.manifestPath = manifestPath;
+    this.version = version;
+    this.v1 = v1;
+    this.v2 = v2;
+  }
+  /**
+   * Load a manifest file, automatically detecting the version.
+   * @param manifestPath - Path to stripe-app.json or stripe-app.yaml
+   * @returns Loaded manifest instance
+   */
+  static async load(manifestPath) {
+    const version = __StripeAppManifest.detectVersion(manifestPath);
+    if (version === "v1") {
+      const reader = _ManifestV1.load(manifestPath);
+      return new __StripeAppManifest(manifestPath, version, reader, null);
+    } else {
+      const reader = await _ManifestV2.load(manifestPath);
+      return new __StripeAppManifest(manifestPath, version, null, reader);
+    }
+  }
+  /**
+   * Detect manifest version from file path.
+   * TODO: Add content-based detection if needed.
+   */
+  static detectVersion(manifestPath) {
+    const lowerPath = manifestPath.toLowerCase();
+    if (lowerPath.endsWith(".yaml") || lowerPath.endsWith(".yml")) {
+      return "v2";
+    }
+    if (lowerPath.endsWith(".json")) {
+      return "v1";
+    }
+    throw new Error(
+      `Cannot detect manifest version from path: ${manifestPath}. Expected .json (v1) or .yaml/.yml (v2) extension.`
+    );
+  }
+  /**
+   * Get the detected manifest version
+   */
+  getVersion() {
+    return this.version;
+  }
+  /**
+   * Get the manifest file path
+   */
+  getManifestPath() {
+    return this.manifestPath;
+  }
+  // ============================================================
+  // App Metadata (supported by both V1 and V2)
+  // ============================================================
+  /**
+   * Get the app ID from the manifest
+   */
+  getAppId() {
+    if (this.v1) {
+      return this.v1.getAppId();
+    }
+    if (this.v2) {
+      return this.v2.getAppId();
+    }
+    return void 0;
+  }
+  /**
+   * Get the app name from the manifest
+   */
+  getAppName() {
+    if (this.v1) {
+      return this.v1.getAppName();
+    }
+    if (this.v2) {
+      return this.v2.getAppName();
+    }
+    return void 0;
+  }
+  // ============================================================
+  // Custom Objects (supported by both V1 and V2)
+  // ============================================================
+  /**
+   * Get all custom objects from the manifest
+   */
+  getCustomObjects() {
+    if (this.v1) {
+      return this.v1.getCustomObjects();
+    }
+    if (this.v2) {
+      return this.v2.getCustomObjects().map((obj) => ({
+        filePath: obj.path,
+        className: obj.name
+      }));
+    }
+    return [];
+  }
+  /**
+   * Check if a custom object entry exists in the manifest.
+   *
+   * **V2 note:** Identity is keyed on `_toSnakeCase(className)` alone — `filePath`
+   * is not considered. Two entries with the same class name but different file
+   * paths are treated as the same object. The `_toSnakeCase` → `_toPascalCase`
+   * round-trip is lossless for typical class names but lossy for consecutive
+   * uppercase (e.g., `HTTPClient` → `http_client` → `HttpClient`). The manifest
+   * `id` field is the source of truth; see `_CustomObjectDefinitionYaml` docs.
+   */
+  hasCustomObject(entry) {
+    if (this.v1) {
+      return this.v1.hasCustomObject(entry);
+    }
+    if (this.v2) {
+      return this.v2.hasCustomObject(_toSnakeCase(entry.className));
+    }
+    return false;
+  }
+  /**
+   * Add a custom object entry to the manifest.
+   *
+   * **V2 note:** The manifest `id` is derived as `_toSnakeCase(className)` and
+   * `filePath` is stored as the specification `content` path. Identity/dedup
+   * is based on `id` alone — see `hasCustomObject` for details.
+   *
+   * @param entry - The custom object entry to add
+   * @returns true if entry was added, false if it already existed
+   */
+  addCustomObject(entry) {
+    if (this.v1) {
+      return this.v1.addCustomObject(entry);
+    }
+    if (this.v2) {
+      return this.v2.addCustomObject(_toSnakeCase(entry.className), entry.filePath);
+    }
+    return false;
+  }
+  /**
+   * Remove a custom object entry from the manifest.
+   *
+   * **V2 note:** Removal is keyed on `_toSnakeCase(className)` — `filePath` is
+   * not considered. See `hasCustomObject` for identity semantics.
+   *
+   * @param entry - The custom object entry to remove
+   * @returns true if entry was removed, false if it didn't exist
+   */
+  removeCustomObject(entry) {
+    if (this.v1) {
+      return this.v1.removeCustomObject(entry);
+    }
+    if (this.v2) {
+      return this.v2.removeCustomObject(_toSnakeCase(entry.className));
+    }
+    return false;
+  }
+  // ============================================================
+  // Extensions (V2 only)
+  // ============================================================
+  /**
+   * Get all extensions from the manifest
+   * @throws Error if manifest version doesn't support extensions
+   */
+  getExtensions() {
+    if (this.v2) {
+      return this.v2.getExtensions();
+    }
+    throw new Error("Extensions are not supported in V1 manifests (stripe-app.json)");
+  }
+  /**
+   * Add or update an extension in the manifest.
+   * If an extension with the same ID exists, it will be replaced.
+   *
+   * @param config - Full extension configuration
+   * @returns The extension ID
+   * @throws Error if manifest version doesn't support extensions
+   */
+  addOrUpdateExtension(config) {
+    if (this.v2) {
+      return this.v2.addOrUpdateExtension(config);
+    }
+    throw new Error("Extensions are not supported in V1 manifests (stripe-app.json)");
+  }
+  // ============================================================
+  // Persistence
+  // ============================================================
+  /**
+   * Save changes back to disk
+   */
+  async save() {
+    if (this.v1) {
+      this.v1.save();
+      return;
+    }
+    if (this.v2) {
+      await this.v2.save();
+      return;
+    }
+    throw new Error("No reader loaded - this should never happen");
+  }
+};
+
+// src/bin/manifest.ts
+var logger = _createLogger({ name: "manifest" });
+function requireV2Manifest(manifestPath) {
+  const lower = manifestPath.toLowerCase();
+  if (!lower.endsWith(".yaml") && !lower.endsWith(".yml")) {
+    throw new Error(
+      `This CLI requires a V2 manifest (stripe-app.yaml). Got: ${manifestPath}`
+    );
+  }
+}
+async function main() {
+  await yargs(hideBin(process.argv)).usage("Manage Stripe app manifests").help().version(false).demandCommand(1, "Specify a subcommand: read, add-custom-object").command(
+    "read",
+    "Read manifest contents",
+    (y) => y.option("path", {
+      type: "string",
+      description: "Path to stripe-app.yaml (V2 manifest)",
+      demandOption: true
+    }).option("output-path", {
+      type: "string",
+      description: "Write JSON result to this file instead of stdout"
+    }),
+    async (args) => {
+      requireV2Manifest(args.path);
+      const manifest = await _StripeAppManifest.load(args.path);
+      const result = {
+        appId: manifest.getAppId(),
+        appName: manifest.getAppName(),
+        customObjects: manifest.getCustomObjects()
+      };
+      if (args.outputPath) {
+        _writeJsonOutput(args.outputPath, result);
+      } else {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      }
+    }
+  ).command(
+    "add-custom-object",
+    "Add or update a custom object in the manifest (idempotent)",
+    (y) => y.option("path", {
+      type: "string",
+      description: "Path to stripe-app.yaml (V2 manifest)",
+      demandOption: true
+    }).option("file-path", {
+      type: "string",
+      description: "Source file path of the custom object",
+      demandOption: true
+    }).option("class-name", {
+      type: "string",
+      description: "Class name of the custom object",
+      demandOption: true
+    }).option("output-path", {
+      type: "string",
+      description: "Write JSON result to this file instead of stdout"
+    }),
+    async (args) => {
+      requireV2Manifest(args.path);
+      const manifest = await _StripeAppManifest.load(args.path);
+      const entry = {
+        filePath: args.filePath,
+        className: args.className
+      };
+      let outcome;
+      const existing = manifest.getCustomObjects().find((co) => co.className === entry.className);
+      if (existing?.filePath === entry.filePath) {
+        outcome = "unchanged";
+      } else if (existing) {
+        manifest.removeCustomObject(existing);
+        manifest.addCustomObject(entry);
+        await manifest.save();
+        outcome = "updated";
+      } else {
+        manifest.addCustomObject(entry);
+        await manifest.save();
+        outcome = "added";
+      }
+      const result = { outcome };
+      if (args.outputPath) {
+        _writeJsonOutput(args.outputPath, result);
+      } else {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      }
+    }
+  ).parse();
+}
+main().catch((err) => {
+  logger.error({ err }, "Unexpected error");
+  process.exit(1);
+});

package/dist/bin/rpc/dispatch.d.ts

@@ -0,0 +1,10 @@
+import type { RpcHandler, RpcResponse } from './types.js';
+/**
+ * Dispatch an RPC request to the appropriate handler.
+ *
+ * Accepts `unknown` because the input comes from untrusted JSON;
+ * performs runtime validation before routing.
+ * @internal
+ */
+export declare function dispatch(request: unknown, methods: Map<string, RpcHandler>): Promise<RpcResponse>;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/bin/rpc/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/bin/rpc/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG1D;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAC/B,OAAO,CAAC,WAAW,CAAC,CAkCtB"}

package/dist/bin/rpc/handlers.d.ts

@@ -0,0 +1,4 @@
+import type { RpcHandler } from './types.js';
+/** @internal */
+export declare const methods: Map<string, RpcHandler>;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/bin/rpc/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/bin/rpc/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA6B7C,gBAAgB;AAChB,eAAO,MAAM,OAAO,yBAGlB,CAAC"}