@stripe/extensibility-dev-tools 0.23.5

package/dist/manifest/index.cjs

@@ -0,0 +1,610 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/manifest/index.ts
+var manifest_exports = {};
+__export(manifest_exports, {
+  _ManifestV1: () => _ManifestV1,
+  _ManifestV2: () => _ManifestV2,
+  _StripeAppManifest: () => _StripeAppManifest
+});
+module.exports = __toCommonJS(manifest_exports);
+
+// src/manifest/stripe-app-manifest.ts
+var import_extensibility_tool_utils2 = require("@stripe/extensibility-tool-utils");
+
+// src/manifest/manifest-v1.ts
+var import_fs = require("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 (!(0, import_fs.existsSync)(filePath)) {
+      throw new Error(`Manifest file not found: ${filePath}`);
+    }
+    const content = (0, import_fs.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() {
+    (0, import_fs.writeFileSync)(this.filePath, JSON.stringify(this.data, null, 2) + "\n");
+  }
+};
+
+// src/manifest/manifest-v2.ts
+var import_promises = require("fs/promises");
+var yaml = __toESM(require("yaml"), 1);
+var import_extensibility_tool_utils = require("@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 (0, import_promises.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: (0, import_extensibility_tool_utils._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 (0, import_promises.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((0, import_extensibility_tool_utils2._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((0, import_extensibility_tool_utils2._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((0, import_extensibility_tool_utils2._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");
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  _ManifestV1,
+  _ManifestV2,
+  _StripeAppManifest
+});

package/dist/manifest/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @deprecated NOT FOR EXTERNAL USE. This subpath is Stripe-internal and will be removed in a future release. External consumers must not depend on it.
+ * @internal
+ */
+export { _StripeAppManifest, type _ManifestVersion } from './stripe-app-manifest.js';
+export { _ManifestV1, type _ManifestV1Data, type _CustomObjectEntry, } from './manifest-v1.js';
+export { _ManifestV2, type _ManifestV2Data, type _ExtensionConfig, type _ExtensionConfiguration, type _EndpointDefinition, type _EndpointAuth, type _SchemaReference, type _CustomObjectDefinition, type _CustomObjectDefinitionYaml, type _CustomObjectDefinitionsBlock, } from './manifest-v2.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/manifest/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/manifest/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGrF,OAAO,EACL,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,6BAA6B,GACnC,MAAM,kBAAkB,CAAC"}