@stripe/extensibility-dev-tools 0.23.5

package/dist/extensibility-dev-tools-manifest-internal.d.ts

@@ -0,0 +1,461 @@
+/**
+ * Custom object definition (internal representation with separate fields)
+ * @internal
+ */
+export declare 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;
+}
+
+/**
+ * Wrapper for custom_object_definitions in the manifest.
+ * @internal
+ */
+export declare interface _CustomObjectDefinitionsBlock {
+    /** List of custom object definition entries. */
+    definitions?: _CustomObjectDefinitionYaml[];
+}
+
+/**
+ * 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 declare interface _CustomObjectDefinitionYaml {
+    /** Object identifier (e.g., `device`, `loyalty_card`). */
+    id: string;
+    /** Specification describing the type and source file for the definition. */
+    specification: {
+        content: string;
+        type: string;
+    };
+}
+
+/**
+ * A parsed custom object entry referencing a file path and export class name.
+ * @internal
+ */
+export declare 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;
+}
+
+/**
+ * Authentication configuration for an endpoint.
+ * @internal
+ */
+export declare 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 declare interface _EndpointDefinition {
+    /** The HTTPS URL of the endpoint. */
+    url?: string;
+    /** The purpose of the endpoint. */
+    purpose?: string;
+    /** Authentication configuration. */
+    auth?: _EndpointAuth;
+}
+
+/**
+ * Extension configuration for stripe-app.yaml
+ * @internal
+ */
+export declare 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?: {
+        content: string;
+        type: 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?: {
+        id: string;
+        live?: _EndpointDefinition;
+        managed_sandbox?: _EndpointDefinition;
+        test?: _EndpointDefinition;
+        type: 'custom_http' | 'remote_function';
+    }[];
+}
+
+/**
+ * Extension configuration schemas (JSON Schema for validation, UI Schema for rendering).
+ * @internal
+ */
+export declare interface _ExtensionConfiguration {
+    /** JSON Schema file for validating extension configuration. */
+    input_schema: _SchemaReference;
+    /** UI Schema file for rendering the configuration form. */
+    ui_schema: _SchemaReference;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * V1 manifest structure (stripe-app.json)
+ * @internal
+ */
+export declare 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;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * V2 manifest structure (stripe-app.yaml)
+ * @internal
+ */
+export declare 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;
+}
+
+/**
+ * Manifest version types
+ * @internal
+ */
+export declare type _ManifestVersion = 'v1' | 'v2';
+
+/**
+ * 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 declare interface _SchemaReference {
+    /** The schema format. */
+    type: 'json_schema' | 'jsonforms';
+    /** Relative path to the schema file. Named `content` to match the manifest field. */
+    content: string;
+}
+
+/**
+ * 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>;
+}
+
+export { }

package/dist/extensibility-dev-tools-manifest-public.d.ts

@@ -0,0 +1,31 @@
+/* Excluded from this release type: _CustomObjectDefinition */
+
+/* Excluded from this release type: _CustomObjectDefinitionsBlock */
+
+/* Excluded from this release type: _CustomObjectDefinitionYaml */
+
+/* Excluded from this release type: _CustomObjectEntry */
+
+/* Excluded from this release type: _EndpointAuth */
+
+/* Excluded from this release type: _EndpointDefinition */
+
+/* Excluded from this release type: _ExtensionConfig */
+
+/* Excluded from this release type: _ExtensionConfiguration */
+
+/* Excluded from this release type: _ManifestV1 */
+
+/* Excluded from this release type: _ManifestV1Data */
+
+/* Excluded from this release type: _ManifestV2 */
+
+/* Excluded from this release type: _ManifestV2Data */
+
+/* Excluded from this release type: _ManifestVersion */
+
+/* Excluded from this release type: _SchemaReference */
+
+/* Excluded from this release type: _StripeAppManifest */
+
+export { }

package/dist/extensibility-dev-tools-public.d.ts

@@ -0,0 +1,199 @@
+/**
+ * `@stripe/extensibility-dev-tools`
+ *
+ * Development tools for Stripe Apps extension projects:
+ * - Template system for code generation
+ * - Dependency management
+ * - Manifest parsing (stripe-app.yaml)
+ * - Workspace regeneration
+ *
+ * @packageDocumentation
+ */
+
+import { z } from 'zod';
+
+/* Excluded from this release type: _advancedDiffPrompt */
+
+/* Excluded from this release type: _CheckResult */
+
+/* Excluded from this release type: _CliContext */
+
+/* Excluded from this release type: _CliUx */
+
+/* Excluded from this release type: _CommitOptions */
+
+/* Excluded from this release type: _CommitResult */
+
+/* Excluded from this release type: _ConflictResult */
+
+/* Excluded from this release type: _createCliContext */
+
+/* Excluded from this release type: _createExtensionEslintConfigFile */
+
+/* Excluded from this release type: _createSimpleSingleFileTemplate */
+
+/* Excluded from this release type: _createSimpleTemplate */
+
+/* Excluded from this release type: _CustomObjectDefinition */
+
+/* Excluded from this release type: _CustomObjectDefinitionsBlock */
+
+/* Excluded from this release type: _CustomObjectDefinitionYaml */
+
+/* Excluded from this release type: _CustomObjectEntry */
+
+/* Excluded from this release type: _defaultServices */
+
+/* Excluded from this release type: _Dependency */
+
+/* Excluded from this release type: _DependencyAction */
+
+/* Excluded from this release type: _DependencyHandler */
+
+/* Excluded from this release type: _DependencyManager */
+
+/* Excluded from this release type: _DependencyManagerOptions */
+
+/* Excluded from this release type: _detectPackageManager */
+
+/* Excluded from this release type: _devNpmDep */
+
+/* Excluded from this release type: _DevNpmDependency */
+
+/* Excluded from this release type: _EndpointAuth */
+
+/* Excluded from this release type: _EndpointDefinition */
+
+/* Excluded from this release type: _EnsureDependenciesInput */
+
+/* Excluded from this release type: _ExtensionConfig */
+
+/* Excluded from this release type: _ExtensionConfiguration */
+
+/* Excluded from this release type: _ExtensionMethodInfo */
+
+/* Excluded from this release type: _ExtensionParams */
+
+/* Excluded from this release type: _ExtensionTemplate */
+
+/* Excluded from this release type: _ExtensionTemplateInfo */
+
+/* Excluded from this release type: _ExtensionTemplateManager */
+
+/* Excluded from this release type: _ExtensionTemplateOutput */
+
+/* Excluded from this release type: _FileWriteResult */
+
+/* Excluded from this release type: _FileWriterOptions */
+
+/* Excluded from this release type: _fs */
+
+/* Excluded from this release type: _GeneratedFile */
+
+/* Excluded from this release type: _ManifestV1 */
+
+/* Excluded from this release type: _ManifestV1Data */
+
+/* Excluded from this release type: _ManifestV2 */
+
+/* Excluded from this release type: _ManifestV2Data */
+
+/* Excluded from this release type: _ManifestVersion */
+
+/* Excluded from this release type: _npmDep */
+
+/* Excluded from this release type: _NpmDependency */
+
+/* Excluded from this release type: _NpmDependencyHandler */
+
+/* Excluded from this release type: _NpmHandlerOptions */
+
+/* Excluded from this release type: _OverwriteDecision */
+
+/* Excluded from this release type: _OverwritePromptCallback */
+
+/* Excluded from this release type: _PackageManager */
+
+/* Excluded from this release type: _PackageMetadata */
+
+/* Excluded from this release type: _PendingChange */
+
+/* Excluded from this release type: _PostGenerationHook */
+
+/* Excluded from this release type: _promptOverwrite */
+
+/* Excluded from this release type: _regenAppProjectWorkspace */
+
+/* Excluded from this release type: _RegenWorkspaceOptions */
+
+/* Excluded from this release type: _regenWorkspaceOptionsSchema */
+
+/* Excluded from this release type: _resolvePackageMetadata */
+
+/* Excluded from this release type: _rootTemplateManager */
+
+/* Excluded from this release type: _RootWorkspaceOutput */
+
+/* Excluded from this release type: _RootWorkspaceParams */
+
+/* Excluded from this release type: _rootWorkspaceTemplate */
+
+/* Excluded from this release type: _SchemaReference */
+
+/* Excluded from this release type: _SingleTemplateManager */
+
+/* Excluded from this release type: _StripeAppManifest */
+
+/* Excluded from this release type: _stripeCliPluginDep */
+
+/* Excluded from this release type: _StripeCliPluginDependency */
+
+/* Excluded from this release type: _StripeCliPluginHandler */
+
+/* Excluded from this release type: _StripeCliPluginHandlerOptions */
+
+/* Excluded from this release type: _Template */
+
+/* Excluded from this release type: _TemplateContext */
+
+/* Excluded from this release type: _TemplateFS */
+
+/* Excluded from this release type: _TemplateManager */
+
+/* Excluded from this release type: _templateManager */
+
+/* Excluded from this release type: _TemplateOutput */
+
+/* Excluded from this release type: _WorkspaceDependency */
+
+/* Excluded from this release type: _WorkspaceDependencyManager */
+
+/* Excluded from this release type: _WorkspaceExtensionConfig */
+
+/* Excluded from this release type: _WorkspaceFileWriteResult */
+
+/* Excluded from this release type: _WorkspaceFileWriterOptions */
+
+/* Excluded from this release type: _WorkspaceGeneratedFile */
+
+/* Excluded from this release type: _WorkspaceGenerateResult */
+
+/* Excluded from this release type: _WorkspaceManifest */
+
+/* Excluded from this release type: _WorkspaceOverwriteDecision */
+
+/* Excluded from this release type: _WorkspaceOverwritePromptCallback */
+
+/* Excluded from this release type: _WorkspacePendingChange */
+
+/* Excluded from this release type: _WorkspacePostGenerationHook */
+
+/* Excluded from this release type: _WorkspaceServices */
+
+/* Excluded from this release type: _WorkspaceWriteMode */
+
+/* Excluded from this release type: _writeGeneratedFiles */
+
+/* Excluded from this release type: _WriteMode */
+
+export { }

package/dist/extensibility-dev-tools-schemas-alpha.d.ts

@@ -0,0 +1,9 @@
+/* Excluded from this release type: buildExtensionSchemas */
+
+/* Excluded from this release type: BuildExtensionSchemasOptions */
+
+/* Excluded from this release type: BuildExtensionSchemasResult */
+
+/* Excluded from this release type: SchemaFileInfo */
+
+export { }