@stripe/extensibility-dev-tools 0.23.5

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

@@ -0,0 +1,253 @@
+/**
+ * Custom object definition (internal representation with separate fields)
+ * @internal
+ */
+export interface _CustomObjectDefinition {
+    /** Object identifier (e.g., "device", "loyalty_card") */
+    id: string;
+    /** Specification type (e.g., "typescript") */
+    type: string;
+    /** Path to the definition file */
+    path: string;
+    /** Export name derived from id via PascalCase (e.g., "Device", "LoyaltyCard") */
+    name: string;
+}
+/**
+ * Custom object definition as stored in YAML (nested under definitions).
+ *
+ * `id` is the source of truth for identity. The export name used at build time
+ * is derived via `_toPascalCase(id)`, so `id` must be valid snake_case that
+ * round-trips cleanly (e.g., `device`, `loyalty_card`, `http_request`).
+ * Consecutive-uppercase class names like `MyHTTPClient` are NOT round-trip safe
+ * (`my_http_client` → `MyHttpClient`). A future `export_name` field may address
+ * this; for now, avoid ids that would produce ambiguous PascalCase names.
+ *
+ * @example
+ * ```yaml
+ * custom_object_definitions:
+ *   definitions:
+ *     - id: device
+ *       specification:
+ *         type: typescript
+ *         content: src/device.object.ts
+ * ```
+ *
+ * @internal
+ */
+export interface _CustomObjectDefinitionYaml {
+    /** Object identifier (e.g., `device`, `loyalty_card`). */
+    id: string;
+    /** Specification describing the type and source file for the definition. */
+    specification: {
+        type: string;
+        content: string;
+    };
+}
+/**
+ * Wrapper for custom_object_definitions in the manifest.
+ * @internal
+ */
+export interface _CustomObjectDefinitionsBlock {
+    /** List of custom object definition entries. */
+    definitions?: _CustomObjectDefinitionYaml[];
+}
+/**
+ * A reference to a schema file in the project (type + relative path).
+ *
+ * Note: stripe-cli-apps-plugin is the authoritative representation of the
+ * Stripe App manifest. Types here are a best-effort mirror.
+ * @internal
+ */
+export interface _SchemaReference {
+    /** The schema format. */
+    type: 'json_schema' | 'jsonforms';
+    /** Relative path to the schema file. Named `content` to match the manifest field. */
+    content: string;
+}
+/**
+ * Authentication configuration for an endpoint.
+ * @internal
+ */
+export interface _EndpointAuth {
+    /** The type of authentication. */
+    type: 'bearer_token' | 'header';
+    /** The name of the secret containing the authentication credential. */
+    secret_name: string;
+    /** The name of the header to use for authentication (required when type is 'header'). */
+    header_name?: string;
+}
+/**
+ * Configuration for a single endpoint environment (live, test, managed_sandbox).
+ * @internal
+ */
+export interface _EndpointDefinition {
+    /** The HTTPS URL of the endpoint. */
+    url?: string;
+    /** The purpose of the endpoint. */
+    purpose?: string;
+    /** Authentication configuration. */
+    auth?: _EndpointAuth;
+}
+/**
+ * Extension configuration schemas (JSON Schema for validation, UI Schema for rendering).
+ * @internal
+ */
+export interface _ExtensionConfiguration {
+    /** JSON Schema file for validating extension configuration. */
+    input_schema: _SchemaReference;
+    /** UI Schema file for rendering the configuration form. */
+    ui_schema: _SchemaReference;
+}
+/**
+ * Extension configuration for stripe-app.yaml
+ * @internal
+ */
+export interface _ExtensionConfig {
+    /** Extension identifier (e.g., `username.my-ext`). */
+    id: string;
+    /** Human-readable extension name. */
+    name: string;
+    /** Extension interface ID (e.g., `com.stripe.billing.bill`). */
+    interface_id: string;
+    /** Extension version string. */
+    version: string;
+    /** Developer-defined description for the extension (max 300 chars). */
+    description?: string;
+    /** Stripe API version to use for this extension (e.g., `2024-06-05`). */
+    stripe_version?: string;
+    /** Entry point script path, used by legacy script format. */
+    script_entry_point?: string;
+    /** Inline script definition (type + content path). */
+    script?: {
+        type: string;
+        content: string;
+    };
+    /** Required permissions for the extension. */
+    permissions: string[];
+    /** Method implementations keyed by method name. */
+    methods: Record<string, unknown>;
+    /** Optional configuration schemas for the extension. */
+    configuration?: _ExtensionConfiguration;
+    /** Remote function endpoints for the extension. */
+    endpoints?: {
+        /** The unique identifier for the endpoint. */
+        id: string;
+        /** The type of endpoint. */
+        type: 'remote_function' | 'custom_http';
+        /** Configuration for the live environment. */
+        live?: _EndpointDefinition;
+        /** Configuration for the managed sandbox environment. */
+        managed_sandbox?: _EndpointDefinition;
+        /** Configuration for the test environment. */
+        test?: _EndpointDefinition;
+    }[];
+}
+/**
+ * V2 manifest structure (stripe-app.yaml)
+ * @internal
+ */
+export interface _ManifestV2Data {
+    /** The app identifier. */
+    id: string;
+    /** The app display name. */
+    name: string;
+    /** The app version string. */
+    version: string;
+    /** Registered extension configurations. */
+    extensions?: _ExtensionConfig[];
+    /** Custom object definitions block. */
+    custom_object_definitions?: _CustomObjectDefinitionsBlock;
+    /** Additional manifest fields. */
+    [key: string]: unknown;
+}
+/**
+ * Manages stripe-app.yaml (V2) manifest file operations
+ *
+ * Capabilities:
+ * - Extensions (add, update, get)
+ * - App metadata (id, name)
+ *
+ * @example
+ * ```ts
+ * const manifest = await _ManifestV2.load('./stripe-app.yaml')
+ * manifest.addOrUpdateExtension({
+ *   id: 'username.my-ext',
+ *   name: 'my-ext',
+ *   interfaceId: 'com.stripe.test',
+ *   version: '0.0.1',
+ *   scriptEntryPoint: 'scripts/my-ext/index.ts',
+ *   permissions: [],
+ *   methods: { my_run: { implementation_type: 'script' } }
+ * })
+ * await manifest.save()
+ * ```
+ * @internal
+ */
+export declare class _ManifestV2 {
+    private readonly filePath;
+    private data;
+    private constructor();
+    /**
+     * Load stripe-app.yaml from disk
+     * @param filePath - Path to stripe-app.yaml
+     * @throws Error if file is invalid or cannot be read
+     */
+    static load(filePath: string): Promise<_ManifestV2>;
+    /**
+     * Get the app ID from the manifest
+     */
+    getAppId(): string | undefined;
+    /**
+     * Get the app name from the manifest
+     */
+    getAppName(): string | undefined;
+    /**
+     * Get all custom object definitions, parsed into internal format.
+     * Entries are guaranteed structurally valid by load-time validation.
+     */
+    getCustomObjects(): _CustomObjectDefinition[];
+    /**
+     * Check if a custom object exists by id
+     */
+    hasCustomObject(id: string): boolean;
+    /**
+     * 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: string, content: string, type?: string): boolean;
+    /**
+     * Remove a custom object definition by id
+     * @param id - Object identifier to remove
+     * @returns true if removed, false if not found
+     */
+    removeCustomObject(id: string): boolean;
+    /**
+     * 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: _ExtensionConfig): string;
+    /**
+     * Get a read-only view of all extensions
+     */
+    getExtensions(): readonly Readonly<_ExtensionConfig>[];
+    /**
+     * Get the raw manifest data (for reading other fields)
+     */
+    getRawData(): Readonly<_ManifestV2Data>;
+    /**
+     * Save changes back to disk
+     * @throws Error if file cannot be written
+     */
+    save(): Promise<void>;
+}
+//# sourceMappingURL=manifest-v2.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-v2.d.ts","sourceRoot":"","sources":["../../src/manifest/manifest-v2.ts"],"names":[],"mappings":"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"}

package/dist/manifest/stripe-app-manifest.d.ts

@@ -0,0 +1,114 @@
+import type { _CustomObjectEntry } from './manifest-v1.js';
+import type { _ExtensionConfig } from './manifest-v2.js';
+/**
+ * Manifest version types
+ * @internal
+ */
+export type _ManifestVersion = 'v1' | 'v2';
+/**
+ * Unified interface for Stripe App manifest operations.
+ *
+ * This class provides an abstraction over both V1 (stripe-app.json) and V2 (stripe-app.yaml)
+ * manifest formats, automatically detecting the version and delegating to the appropriate reader.
+ *
+ * Capabilities by version:
+ * - V1 (JSON): Custom objects, app metadata
+ * - V2 (YAML): Extensions, custom objects, app metadata
+ *
+ * @example
+ * ```ts
+ * const manifest = await _StripeAppManifest.load('./stripe-app.yaml')
+ * manifest.addOrUpdateExtension({ ... })
+ * await manifest.save()
+ * ```
+ * @internal
+ */
+export declare class _StripeAppManifest {
+    private readonly manifestPath;
+    private readonly version;
+    private readonly v1;
+    private readonly v2;
+    private constructor();
+    /**
+     * Load a manifest file, automatically detecting the version.
+     * @param manifestPath - Path to stripe-app.json or stripe-app.yaml
+     * @returns Loaded manifest instance
+     */
+    static load(manifestPath: string): Promise<_StripeAppManifest>;
+    /**
+     * Detect manifest version from file path.
+     * TODO: Add content-based detection if needed.
+     */
+    private static detectVersion;
+    /**
+     * Get the detected manifest version
+     */
+    getVersion(): _ManifestVersion;
+    /**
+     * Get the manifest file path
+     */
+    getManifestPath(): string;
+    /**
+     * Get the app ID from the manifest
+     */
+    getAppId(): string | undefined;
+    /**
+     * Get the app name from the manifest
+     */
+    getAppName(): string | undefined;
+    /**
+     * Get all custom objects from the manifest
+     */
+    getCustomObjects(): _CustomObjectEntry[];
+    /**
+     * 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: _CustomObjectEntry): boolean;
+    /**
+     * 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: _CustomObjectEntry): boolean;
+    /**
+     * 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: _CustomObjectEntry): boolean;
+    /**
+     * Get all extensions from the manifest
+     * @throws Error if manifest version doesn't support extensions
+     */
+    getExtensions(): readonly Readonly<_ExtensionConfig>[];
+    /**
+     * 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: _ExtensionConfig): string;
+    /**
+     * Save changes back to disk
+     */
+    save(): Promise<void>;
+}
+//# sourceMappingURL=stripe-app-manifest.d.ts.map

package/dist/manifest/stripe-app-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe-app-manifest.d.ts","sourceRoot":"","sources":["../../src/manifest/stripe-app-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,EAAE;IAJrB,OAAO;IAOP;;;;OAIG;WACU,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAYpE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAc5B;;OAEG;IACH,UAAU,IAAI,gBAAgB;IAI9B;;OAEG;IACH,eAAe,IAAI,MAAM;IAQzB;;OAEG;IACH,QAAQ,IAAI,MAAM,GAAG,SAAS;IAU9B;;OAEG;IACH,UAAU,IAAI,MAAM,GAAG,SAAS;IAchC;;OAEG;IACH,gBAAgB,IAAI,kBAAkB,EAAE;IAcxC;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO;IAUnD;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO;IAUnD;;;;;;;;OAQG;IACH,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO;IActD;;;OAGG;IACH,aAAa,IAAI,SAAS,QAAQ,CAAC,gBAAgB,CAAC,EAAE;IAOtD;;;;;;;OAOG;IACH,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM;IAWtD;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAW5B"}