@stripe/extensibility-dev-tools 0.23.5

package/dist/manifest/index.js

@@ -0,0 +1,571 @@
+// 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");
+  }
+};
+export {
+  _ManifestV1,
+  _ManifestV2,
+  _StripeAppManifest
+};

package/dist/manifest/manifest-v1.d.ts

@@ -0,0 +1,102 @@
+/**
+ * V1 manifest structure (stripe-app.json)
+ * @internal
+ */
+export interface _ManifestV1Data {
+    /** The app identifier. */
+    id: string;
+    /** The app version string. */
+    version: string;
+    /** The app display name. */
+    name: string;
+    /** List of custom object entries in `path#ClassName` format. */
+    exported_custom_objects?: string[];
+    /** Additional manifest fields. */
+    [key: string]: unknown;
+}
+/**
+ * A parsed custom object entry referencing a file path and export class name.
+ * @internal
+ */
+export interface _CustomObjectEntry {
+    /** Relative path to the type definition file (e.g., `src/device.d.ts`). */
+    filePath: string;
+    /** Name of the exported class in the definition file. */
+    className: string;
+}
+/**
+ * Format a custom object entry as the manifest string format
+ * @param entry - The custom object entry
+ * @returns String in format "path/to/file.d.ts#ClassName"
+ * @internal
+ */
+export declare function formatCustomObjectEntry(entry: _CustomObjectEntry): string;
+/**
+ * Parse a custom object entry string into structured format
+ * @param entryString - String in format "path/to/file.d.ts#ClassName"
+ * @returns Parsed CustomObjectEntry
+ * @internal
+ */
+export declare function parseCustomObjectEntry(entryString: string): _CustomObjectEntry;
+/**
+ * Manages stripe-app.json (V1) manifest file operations
+ *
+ * Capabilities:
+ * - Custom objects (add, remove, has, get)
+ * - App metadata (id, name)
+ *
+ * @example
+ * ```ts
+ * const manifest = await ManifestV1.load('./stripe-app.json')
+ * manifest.addCustomObject({ filePath: 'src/device.d.ts', className: 'Device' })
+ * await manifest.save()
+ * ```
+ * @internal
+ */
+export declare class _ManifestV1 {
+    private readonly filePath;
+    private data;
+    private constructor();
+    /**
+     * 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: string): _ManifestV1;
+    /**
+     * Get the app ID from the manifest
+     */
+    getAppId(): string;
+    /**
+     * Get the app name from the manifest
+     */
+    getAppName(): string;
+    /**
+     * Get all custom objects as structured entries
+     */
+    getCustomObjects(): _CustomObjectEntry[];
+    /**
+     * Check if a custom object entry exists in the manifest
+     */
+    hasCustomObject(entry: _CustomObjectEntry): boolean;
+    /**
+     * 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: _CustomObjectEntry): boolean;
+    /**
+     * Remove a custom object entry from the manifest
+     * @returns true if entry was removed, false if it didn't exist
+     */
+    removeCustomObject(entry: _CustomObjectEntry): boolean;
+    /**
+     * Get the raw manifest data (for reading other fields)
+     */
+    getRawData(): Readonly<_ManifestV1Data>;
+    /**
+     * Save changes back to disk
+     */
+    save(): void;
+}
+//# sourceMappingURL=manifest-v1.d.ts.map

package/dist/manifest/manifest-v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-v1.d.ts","sourceRoot":"","sources":["../../src/manifest/manifest-v1.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,kCAAkC;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,CAc9E;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,IAAI;IAFd,OAAO;IAKP;;;;OAIG;IACH,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW;IAgB1C;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,gBAAgB,IAAI,kBAAkB,EAAE;IAUxC;;OAEG;IACH,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO;IAQnD;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO;IAanD;;;OAGG;IACH,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO;IAoBtD;;OAEG;IACH,UAAU,IAAI,QAAQ,CAAC,eAAe,CAAC;IAIvC;;OAEG;IACH,IAAI,IAAI,IAAI;CAGb"}