@salesforce/b2c-tooling-sdk 0.0.1 → 0.0.3

package/dist/esm/cli/cartridge-providers.d.ts

@@ -0,0 +1,149 @@
+import type { Hook } from '@oclif/core';
+import type { CartridgeMapping, FindCartridgesOptions } from '../operations/code/cartridges.js';
+import type { B2CInstance } from '../instance/index.js';
+/**
+ * Extended options for cartridge discovery that includes instance context.
+ */
+export interface CartridgeDiscoveryOptions extends FindCartridgesOptions {
+    /** Directory to search for cartridges */
+    directory: string;
+    /** Code version being deployed to (if known) */
+    codeVersion?: string;
+    /** B2C instance context (if available) */
+    instance?: B2CInstance;
+}
+/**
+ * Provider interface for custom cartridge discovery.
+ *
+ * Plugins can implement this interface to provide cartridges from custom sources
+ * such as remote Git repos, manifest files, or other locations.
+ *
+ * @example
+ * ```typescript
+ * const manifestProvider: CartridgeProvider = {
+ *   name: 'manifest-provider',
+ *   priority: 'before',
+ *   async findCartridges(options) {
+ *     const manifest = JSON.parse(await fs.readFile('cartridges.json', 'utf-8'));
+ *     return manifest.cartridges.map(c => ({
+ *       name: c.name,
+ *       src: path.resolve(c.path),
+ *       dest: c.name,
+ *     }));
+ *   },
+ * };
+ * ```
+ */
+export interface CartridgeProvider {
+    /** Unique name for this provider (used for logging) */
+    readonly name: string;
+    /**
+     * Priority relative to default provider.
+     * - 'before': Runs first, can provide cartridges that override defaults
+     * - 'after': Runs after defaults, adds additional cartridges
+     */
+    readonly priority: 'before' | 'after';
+    /**
+     * Find cartridges from this provider.
+     *
+     * @param options - Discovery options including directory, filters, and instance context
+     * @returns Array of cartridge mappings, or empty array if no cartridges available
+     */
+    findCartridges(options: CartridgeDiscoveryOptions): Promise<CartridgeMapping[]>;
+}
+/**
+ * Transformer interface for modifying cartridge mappings before deployment.
+ *
+ * Transformers run after all providers have contributed cartridges and can
+ * modify paths, rename cartridges, or filter the final list.
+ *
+ * @example
+ * ```typescript
+ * const versioningTransformer: CartridgeTransformer = {
+ *   name: 'versioning-transformer',
+ *   async transform(cartridges, options) {
+ *     // Append version suffix to cartridge names
+ *     return cartridges.map(c => ({
+ *       ...c,
+ *       dest: `${c.name}_v2`,
+ *     }));
+ *   },
+ * };
+ * ```
+ */
+export interface CartridgeTransformer {
+    /** Unique name for this transformer (used for logging) */
+    readonly name: string;
+    /**
+     * Transform cartridge mappings before deployment.
+     *
+     * Can modify paths, names, or filter cartridges.
+     *
+     * @param cartridges - Current list of cartridge mappings
+     * @param options - Discovery options for context
+     * @returns Transformed array of cartridge mappings
+     */
+    transform(cartridges: CartridgeMapping[], options: CartridgeDiscoveryOptions): Promise<CartridgeMapping[]>;
+}
+/**
+ * Options passed to the b2c:cartridge-providers hook.
+ */
+export interface CartridgeProvidersHookOptions {
+    /** Directory being searched for cartridges */
+    directory: string;
+    /** Command flags (for context) */
+    flags?: Record<string, unknown>;
+    /** Allow additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Result returned from the b2c:cartridge-providers hook.
+ */
+export interface CartridgeProvidersHookResult {
+    /** Cartridge providers to register */
+    providers?: CartridgeProvider[];
+    /** Cartridge transformers to register */
+    transformers?: CartridgeTransformer[];
+}
+/**
+ * Type for the b2c:cartridge-providers hook function.
+ */
+export type CartridgeProvidersHook = Hook<'b2c:cartridge-providers'>;
+/**
+ * Runner that manages cartridge providers and transformers.
+ *
+ * Collects providers from plugins and orchestrates discovery across
+ * all sources with proper priority ordering and deduplication.
+ */
+export declare class CartridgeProviderRunner {
+    private providers;
+    private transformers;
+    private logger?;
+    constructor(logger?: {
+        debug: (msg: string) => void;
+    });
+    /**
+     * Add providers and transformers to the runner.
+     */
+    addProviders(providers: CartridgeProvider[]): void;
+    /**
+     * Add transformers to the runner.
+     */
+    addTransformers(transformers: CartridgeTransformer[]): void;
+    /**
+     * Get count of registered providers.
+     */
+    get providerCount(): number;
+    /**
+     * Get count of registered transformers.
+     */
+    get transformerCount(): number;
+    /**
+     * Find cartridges using all registered providers and apply transformers.
+     *
+     * @param defaultCartridges - Cartridges from default discovery (SDK findCartridges)
+     * @param options - Discovery options
+     * @returns Final list of cartridge mappings
+     */
+    findCartridges(defaultCartridges: CartridgeMapping[], options: CartridgeDiscoveryOptions): Promise<CartridgeMapping[]>;
+}

package/dist/esm/cli/cartridge-providers.js

@@ -0,0 +1,103 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Runner that manages cartridge providers and transformers.
+ *
+ * Collects providers from plugins and orchestrates discovery across
+ * all sources with proper priority ordering and deduplication.
+ */
+export class CartridgeProviderRunner {
+    providers = [];
+    transformers = [];
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Add providers and transformers to the runner.
+     */
+    addProviders(providers) {
+        this.providers.push(...providers);
+    }
+    /**
+     * Add transformers to the runner.
+     */
+    addTransformers(transformers) {
+        this.transformers.push(...transformers);
+    }
+    /**
+     * Get count of registered providers.
+     */
+    get providerCount() {
+        return this.providers.length;
+    }
+    /**
+     * Get count of registered transformers.
+     */
+    get transformerCount() {
+        return this.transformers.length;
+    }
+    /**
+     * Find cartridges using all registered providers and apply transformers.
+     *
+     * @param defaultCartridges - Cartridges from default discovery (SDK findCartridges)
+     * @param options - Discovery options
+     * @returns Final list of cartridge mappings
+     */
+    async findCartridges(defaultCartridges, options) {
+        let cartridges = [];
+        // Run 'before' providers first
+        const beforeProviders = this.providers.filter((p) => p.priority === 'before');
+        for (const provider of beforeProviders) {
+            try {
+                this.logger?.debug(`Running cartridge provider: ${provider.name} (before)`);
+                const found = await provider.findCartridges(options);
+                cartridges.push(...found);
+                this.logger?.debug(`Provider ${provider.name} found ${found.length} cartridge(s)`);
+            }
+            catch (error) {
+                this.logger?.debug(`Provider ${provider.name} failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        // Add default cartridges
+        cartridges.push(...defaultCartridges);
+        // Run 'after' providers
+        const afterProviders = this.providers.filter((p) => p.priority === 'after');
+        for (const provider of afterProviders) {
+            try {
+                this.logger?.debug(`Running cartridge provider: ${provider.name} (after)`);
+                const found = await provider.findCartridges(options);
+                cartridges.push(...found);
+                this.logger?.debug(`Provider ${provider.name} found ${found.length} cartridge(s)`);
+            }
+            catch (error) {
+                this.logger?.debug(`Provider ${provider.name} failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        // Deduplicate by name (first wins)
+        const seen = new Set();
+        cartridges = cartridges.filter((c) => {
+            if (seen.has(c.name)) {
+                return false;
+            }
+            seen.add(c.name);
+            return true;
+        });
+        // Apply transformers in order
+        for (const transformer of this.transformers) {
+            try {
+                this.logger?.debug(`Running cartridge transformer: ${transformer.name}`);
+                cartridges = await transformer.transform(cartridges, options);
+                this.logger?.debug(`Transformer ${transformer.name} returned ${cartridges.length} cartridge(s)`);
+            }
+            catch (error) {
+                this.logger?.debug(`Transformer ${transformer.name} failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        return cartridges;
+    }
+}
+//# sourceMappingURL=cartridge-providers.js.map

package/dist/esm/cli/cartridge-providers.js.map

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

package/dist/esm/cli/config.d.ts

@@ -0,0 +1,75 @@
+/**
+ * CLI configuration utilities.
+ *
+ * This module provides configuration loading for CLI commands.
+ * It uses {@link resolveConfig} internally for consistent behavior.
+ *
+ * @module cli/config
+ */
+import type { AuthMethod } from '../auth/types.js';
+import { ALL_AUTH_METHODS } from '../auth/types.js';
+import { type NormalizedConfig, type ConfigSource, type ResolvedB2CConfig } from '../config/index.js';
+import { findDwJson } from '../config/dw-json.js';
+export type { AuthMethod };
+export { ALL_AUTH_METHODS };
+export { findDwJson };
+/**
+ * Options for loading configuration.
+ */
+export interface LoadConfigOptions {
+    /** Named instance from dw.json "configs" array */
+    instance?: string;
+    /** Explicit path to config file (skips searching if provided) */
+    configPath?: string;
+    /** Cloud origin for MRT ~/.mobify lookup (e.g., https://cloud-staging.mobify.com) */
+    cloudOrigin?: string;
+    /** Path to custom MRT credentials file (overrides default ~/.mobify) */
+    credentialsFile?: string;
+    /** Account Manager hostname for OAuth (passed to plugins for host-specific config) */
+    accountManagerHost?: string;
+}
+/**
+ * Plugin-provided configuration sources with priority ordering.
+ *
+ * Used by BaseCommand to pass sources collected from the `b2c:config-sources` hook
+ * to the configuration resolver.
+ */
+export interface PluginSources {
+    /**
+     * Sources with high priority (inserted BEFORE dw.json/~/.mobify).
+     * These sources can override values from default configuration files.
+     */
+    before?: ConfigSource[];
+    /**
+     * Sources with low priority (inserted AFTER dw.json/~/.mobify).
+     * These sources fill in gaps left by default configuration files.
+     */
+    after?: ConfigSource[];
+}
+/**
+ * Loads configuration with precedence: CLI flags/env vars > dw.json > ~/.mobify
+ *
+ * OCLIF handles environment variables automatically via flag `env` properties.
+ * The flags parameter already contains resolved env var values.
+ *
+ * Uses {@link resolveConfig} internally for consistent behavior across CLI and SDK.
+ *
+ * @param flags - Configuration values from CLI flags/env vars
+ * @param options - Loading options
+ * @param pluginSources - Optional sources from CLI plugins (via b2c:config-sources hook)
+ * @returns Resolved configuration with factory methods
+ *
+ * @example
+ * ```typescript
+ * // In a CLI command
+ * const config = loadConfig(
+ *   { hostname: this.flags.server, clientId: this.flags['client-id'] },
+ *   { instance: this.flags.instance }
+ * );
+ *
+ * if (config.hasB2CInstanceConfig()) {
+ *   const instance = config.createB2CInstance();
+ * }
+ * ```
+ */
+export declare function loadConfig(flags?: Partial<NormalizedConfig>, options?: LoadConfigOptions, pluginSources?: PluginSources): ResolvedB2CConfig;

package/dist/esm/cli/config.js

@@ -0,0 +1,65 @@
+import { ALL_AUTH_METHODS } from '../auth/types.js';
+import { resolveConfig } from '../config/index.js';
+import { findDwJson } from '../config/dw-json.js';
+import { getLogger } from '../logging/logger.js';
+export { ALL_AUTH_METHODS };
+export { findDwJson };
+/**
+ * Loads configuration with precedence: CLI flags/env vars > dw.json > ~/.mobify
+ *
+ * OCLIF handles environment variables automatically via flag `env` properties.
+ * The flags parameter already contains resolved env var values.
+ *
+ * Uses {@link resolveConfig} internally for consistent behavior across CLI and SDK.
+ *
+ * @param flags - Configuration values from CLI flags/env vars
+ * @param options - Loading options
+ * @param pluginSources - Optional sources from CLI plugins (via b2c:config-sources hook)
+ * @returns Resolved configuration with factory methods
+ *
+ * @example
+ * ```typescript
+ * // In a CLI command
+ * const config = loadConfig(
+ *   { hostname: this.flags.server, clientId: this.flags['client-id'] },
+ *   { instance: this.flags.instance }
+ * );
+ *
+ * if (config.hasB2CInstanceConfig()) {
+ *   const instance = config.createB2CInstance();
+ * }
+ * ```
+ */
+export function loadConfig(flags = {}, options = {}, pluginSources = {}) {
+    const logger = getLogger();
+    // Preserve instanceName from options.instance if not already in flags
+    const effectiveFlags = {
+        ...flags,
+        instanceName: flags.instanceName ?? options.instance,
+    };
+    const resolved = resolveConfig(effectiveFlags, {
+        instance: options.instance,
+        configPath: options.configPath,
+        hostnameProtection: true,
+        cloudOrigin: options.cloudOrigin,
+        credentialsFile: options.credentialsFile,
+        accountManagerHost: options.accountManagerHost,
+        sourcesBefore: pluginSources.before,
+        sourcesAfter: pluginSources.after,
+    });
+    // Log source summary
+    for (const source of resolved.sources) {
+        logger.trace({
+            source: source.name,
+            location: source.location,
+            fields: source.fields,
+            fieldsIgnored: source.fieldsIgnored,
+        }, `[${source.name}] Contributed fields`);
+    }
+    // Log warnings
+    for (const warning of resolved.warnings) {
+        logger.trace({ warning }, `[Config] ${warning.message}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=config.js.map

package/dist/esm/cli/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/cli/config.ts"],"names":[],"mappings":"AAcA,OAAO,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAC,aAAa,EAAmE,MAAM,oBAAoB,CAAC;AACnH,OAAO,EAAC,UAAU,EAAC,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAC,SAAS,EAAC,MAAM,sBAAsB,CAAC;AAI/C,OAAO,EAAC,gBAAgB,EAAC,CAAC;AAC1B,OAAO,EAAC,UAAU,EAAC,CAAC;AAqCpB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,UAAU,CACxB,QAAmC,EAAE,EACrC,UAA6B,EAAE,EAC/B,gBAA+B,EAAE;IAEjC,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAE3B,sEAAsE;IACtE,MAAM,cAAc,GAAG;QACrB,GAAG,KAAK;QACR,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,OAAO,CAAC,QAAQ;KACrD,CAAC;IAEF,MAAM,QAAQ,GAAG,aAAa,CAAC,cAAc,EAAE;QAC7C,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,kBAAkB,EAAE,IAAI;QACxB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;QAC9C,aAAa,EAAE,aAAa,CAAC,MAAM;QACnC,YAAY,EAAE,aAAa,CAAC,KAAK;KAClC,CAAC,CAAC;IAEH,qBAAqB;IACrB,KAAK,MAAM,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACtC,MAAM,CAAC,KAAK,CACV;YACE,MAAM,EAAE,MAAM,CAAC,IAAI;YACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,aAAa,EAAE,MAAM,CAAC,aAAa;SACpC,EACD,IAAI,MAAM,CAAC,IAAI,sBAAsB,CACtC,CAAC;IACJ,CAAC;IAED,eAAe;IACf,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACxC,MAAM,CAAC,KAAK,CAAC,EAAC,OAAO,EAAC,EAAE,YAAY,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/esm/cli/hooks.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Hook types for CLI plugin extensibility.
+ *
+ * This module defines the hook interfaces that plugins can implement to extend
+ * CLI functionality, particularly for custom configuration sources.
+ *
+ * ## Custom Config Sources Hook
+ *
+ * The `b2c:config-sources` hook allows plugins to provide custom {@link ConfigSource}
+ * implementations that integrate with the CLI's configuration resolution system.
+ *
+ * @example
+ * ```typescript
+ * // In your plugin's hooks/config-sources.ts
+ * import type { ConfigSourcesHook } from '@salesforce/b2c-tooling-sdk/cli';
+ * import { MyCustomSource } from '../sources/my-custom-source.js';
+ *
+ * const hook: ConfigSourcesHook = async function(options) {
+ *   return {
+ *     sources: [new MyCustomSource()],
+ *     priority: 'before', // Override dw.json defaults
+ *   };
+ * };
+ *
+ * export default hook;
+ * ```
+ *
+ * @module cli/hooks
+ */
+import type { Hook } from '@oclif/core';
+import type { ConfigSource, ResolveConfigOptions } from '../config/types.js';
+import type { HttpMiddlewareProvider } from '../clients/middleware-registry.js';
+/**
+ * Options passed to the `b2c:config-sources` hook.
+ *
+ * These options provide context about the current CLI invocation,
+ * allowing plugins to customize their config sources based on user input.
+ */
+export interface ConfigSourcesHookOptions {
+    /** The --instance flag value (if provided) */
+    instance?: string;
+    /** The --config flag value (if provided) */
+    configPath?: string;
+    /** Full ResolveConfigOptions for advanced sources that need more context */
+    resolveOptions: ResolveConfigOptions;
+    /**
+     * All parsed CLI flags from the current command.
+     *
+     * Plugins can check for flags they care about. Note that plugins cannot
+     * add flags to commands - they can only read flags that the CLI defines.
+     * For plugin-specific configuration, use environment variables instead.
+     */
+    flags?: Record<string, unknown>;
+    /** Index signature for oclif hook compatibility */
+    [key: string]: unknown;
+}
+/**
+ * Result returned by the `b2c:config-sources` hook.
+ *
+ * Plugins return one or more ConfigSource instances that will be integrated
+ * into the configuration resolution chain.
+ */
+export interface ConfigSourcesHookResult {
+    /** Config sources to add to the resolution chain */
+    sources: ConfigSource[];
+    /**
+     * Where to insert sources relative to default sources.
+     *
+     * - `'before'`: Higher priority than dw.json/~/.mobify (plugin overrides defaults)
+     * - `'after'`: Lower priority than defaults (plugin fills gaps)
+     *
+     * @default 'after'
+     */
+    priority?: 'before' | 'after';
+}
+/**
+ * Hook type for `b2c:config-sources`.
+ *
+ * Implement this hook in your oclif plugin to provide custom configuration sources.
+ * The hook is called during command initialization, after CLI flags are parsed
+ * but before configuration is resolved.
+ *
+ * ## Plugin Registration
+ *
+ * Register the hook in your plugin's package.json:
+ *
+ * ```json
+ * {
+ *   "oclif": {
+ *     "hooks": {
+ *       "b2c:config-sources": "./dist/hooks/config-sources.js"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ## Hook Context
+ *
+ * Inside the hook function, you have access to:
+ * - `this.config` - oclif Config object
+ * - `this.debug()`, `this.log()`, `this.warn()`, `this.error()` - logging methods
+ *
+ * @example
+ * ```typescript
+ * import type { ConfigSourcesHook } from '@salesforce/b2c-tooling-sdk/cli';
+ *
+ * const hook: ConfigSourcesHook = async function(options) {
+ *   this.debug(`Hook called with instance: ${options.instance}`);
+ *
+ *   // Load config from a custom source (e.g., secrets manager)
+ *   const source = new VaultConfigSource(options.instance);
+ *
+ *   return {
+ *     sources: [source],
+ *     priority: 'before', // Override dw.json with secrets
+ *   };
+ * };
+ *
+ * export default hook;
+ * ```
+ */
+export type ConfigSourcesHook = Hook<'b2c:config-sources'>;
+/**
+ * Options passed to the `b2c:http-middleware` hook.
+ */
+export interface HttpMiddlewareHookOptions {
+    /**
+     * All parsed CLI flags from the current command.
+     *
+     * Plugins can inspect flags but cannot add new flags to commands.
+     * For plugin-specific configuration, use environment variables instead.
+     */
+    flags?: Record<string, unknown>;
+    /** Index signature for oclif hook compatibility */
+    [key: string]: unknown;
+}
+/**
+ * Result returned by the `b2c:http-middleware` hook.
+ *
+ * Plugins return one or more HttpMiddlewareProvider instances that will be
+ * registered with the global middleware registry.
+ */
+export interface HttpMiddlewareHookResult {
+    /** Middleware providers to register */
+    providers: HttpMiddlewareProvider[];
+}
+/**
+ * Hook type for `b2c:http-middleware`.
+ *
+ * Implement this hook in your oclif plugin to provide custom HTTP middleware
+ * that will be applied to all API clients (OCAPI, SLAS, WebDAV, etc.).
+ *
+ * The hook is called during command initialization, after flags are parsed
+ * but before any API clients are created.
+ *
+ * ## Plugin Registration
+ *
+ * Register the hook in your plugin's package.json:
+ *
+ * ```json
+ * {
+ *   "oclif": {
+ *     "hooks": {
+ *       "b2c:http-middleware": "./dist/hooks/http-middleware.js"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ## Hook Context
+ *
+ * Inside the hook function, you have access to:
+ * - `this.config` - oclif Config object
+ * - `this.debug()`, `this.log()`, `this.warn()`, `this.error()` - logging methods
+ *
+ * @example
+ * ```typescript
+ * import type { HttpMiddlewareHook } from '@salesforce/b2c-tooling-sdk/cli';
+ * import type { HttpMiddlewareProvider } from '@salesforce/b2c-tooling-sdk/clients';
+ *
+ * const hook: HttpMiddlewareHook = async function(options) {
+ *   this.debug('Registering custom middleware');
+ *
+ *   const metricsProvider: HttpMiddlewareProvider = {
+ *     name: 'metrics-collector',
+ *     getMiddleware(clientType) {
+ *       return {
+ *         onRequest({ request }) {
+ *           (request as any)._startTime = Date.now();
+ *           return request;
+ *         },
+ *         onResponse({ request, response }) {
+ *           const duration = Date.now() - (request as any)._startTime;
+ *           console.log(`[${clientType}] ${request.method} ${request.url} ${response.status} ${duration}ms`);
+ *           return response;
+ *         },
+ *       };
+ *     },
+ *   };
+ *
+ *   return { providers: [metricsProvider] };
+ * };
+ *
+ * export default hook;
+ * ```
+ */
+export type HttpMiddlewareHook = Hook<'b2c:http-middleware'>;
+export type { B2COperationType, B2COperationContext, BeforeB2COperationResult, B2COperationResult, AfterB2COperationResult, B2COperationLifecycleProvider, B2COperationLifecycleHookOptions, B2COperationLifecycleHookResult, B2COperationLifecycleHook, } from './lifecycle.js';
+export { createB2COperationContext, B2CLifecycleRunner } from './lifecycle.js';
+export type { CartridgeDiscoveryOptions, CartridgeProvider, CartridgeTransformer, CartridgeProvidersHookOptions, CartridgeProvidersHookResult, CartridgeProvidersHook, } from './cartridge-providers.js';
+export { CartridgeProviderRunner } from './cartridge-providers.js';
+declare module '@oclif/core' {
+    interface Hooks {
+        'b2c:config-sources': {
+            options: ConfigSourcesHookOptions;
+            return: ConfigSourcesHookResult;
+        };
+        'b2c:http-middleware': {
+            options: HttpMiddlewareHookOptions;
+            return: HttpMiddlewareHookResult;
+        };
+        'b2c:operation-lifecycle': {
+            options: import('./lifecycle.js').B2COperationLifecycleHookOptions;
+            return: import('./lifecycle.js').B2COperationLifecycleHookResult;
+        };
+        'b2c:cartridge-providers': {
+            options: import('./cartridge-providers.js').CartridgeProvidersHookOptions;
+            return: import('./cartridge-providers.js').CartridgeProvidersHookResult;
+        };
+    }
+}

package/dist/esm/cli/hooks.js

@@ -0,0 +1,3 @@
+export { createB2COperationContext, B2CLifecycleRunner } from './lifecycle.js';
+export { CartridgeProviderRunner } from './cartridge-providers.js';
+//# sourceMappingURL=hooks.js.map

package/dist/esm/cli/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../../src/cli/hooks.ts"],"names":[],"mappings":"AA2OA,OAAO,EAAC,yBAAyB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAW7E,OAAO,EAAC,uBAAuB,EAAC,MAAM,0BAA0B,CAAC"}