@salesforce/b2c-tooling-sdk 1.9.0 → 1.11.0

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

@@ -1,324 +0,0 @@
-/**
- * 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';
-import type { AuthMiddlewareProvider } from '../auth/middleware.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[];
-    /**
-     * Priority for the returned sources. Can be a string or number:
-     *
-     * String values (legacy, still supported):
-     * - `'before'`: Maps to priority -1 (higher priority than defaults)
-     * - `'after'`: Maps to priority 10 (lower priority than defaults)
-     *
-     * Numeric values (preferred):
-     * - Any number. Lower numbers = higher priority.
-     * - Built-in sources use priority 0.
-     * - package.json uses priority 1000.
-     *
-     * If a source already has a `priority` property set, it will not be overridden.
-     *
-     * @default 'after' (maps to 10)
-     */
-    priority?: 'before' | 'after' | number;
-}
-/**
- * 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'>;
-/**
- * Options passed to the `b2c:auth-middleware` hook.
- */
-export interface AuthMiddlewareHookOptions {
-    /**
-     * 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:auth-middleware` hook.
- *
- * Plugins return one or more AuthMiddlewareProvider instances that will be
- * registered with the global auth middleware registry.
- */
-export interface AuthMiddlewareHookResult {
-    /** Middleware providers to register */
-    providers: AuthMiddlewareProvider[];
-}
-/**
- * Hook type for `b2c:auth-middleware`.
- *
- * Implement this hook in your oclif plugin to provide custom middleware
- * that will be applied to OAuth token requests.
- *
- * The hook is called during command initialization, after flags are parsed
- * but before any authentication is performed.
- *
- * ## Plugin Registration
- *
- * Register the hook in your plugin's package.json:
- *
- * ```json
- * {
- *   "oclif": {
- *     "hooks": {
- *       "b2c:auth-middleware": "./dist/hooks/auth-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 { AuthMiddlewareHook } from '@salesforce/b2c-tooling-sdk/cli';
- * import type { AuthMiddlewareProvider } from '@salesforce/b2c-tooling-sdk/auth';
- *
- * const hook: AuthMiddlewareHook = async function(options) {
- *   this.debug('Registering auth middleware');
- *
- *   const userAgentProvider: AuthMiddlewareProvider = {
- *     name: 'custom-user-agent',
- *     getMiddleware() {
- *       return {
- *         onRequest({ request }) {
- *           request.headers.set('User-Agent', 'my-app/1.0');
- *           return request;
- *         },
- *       };
- *     },
- *   };
- *
- *   return { providers: [userAgentProvider] };
- * };
- *
- * export default hook;
- * ```
- */
-export type AuthMiddlewareHook = Hook<'b2c:auth-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:auth-middleware': {
-            options: AuthMiddlewareHookOptions;
-            return: AuthMiddlewareHookResult;
-        };
-        '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/cjs/cli/hooks.js

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

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

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

package/dist/cjs/cli/index.d.ts

@@ -1,108 +0,0 @@
-/**
- * CLI utilities and base command classes for building B2C Commerce CLI commands.
- *
- * This module provides reusable base classes, configuration loading, and table
- * rendering utilities for oclif-based CLI applications.
- *
- * ## Base Command Classes
- *
- * Extend these classes to create CLI commands with pre-configured functionality:
- *
- * - {@link BaseCommand} - Foundation class with logging, JSON output, and error handling
- * - {@link OAuthCommand} - Adds OAuth authentication setup
- * - {@link InstanceCommand} - Adds B2C Commerce instance configuration
- * - {@link CartridgeCommand} - Adds cartridge path configuration for code operations
- * - {@link JobCommand} - Adds job execution configuration
- * - {@link WebDavCommand} - Adds WebDAV root directory configuration for file operations
- * - {@link MrtCommand} - Adds Managed Runtime API authentication
- * - {@link OdsCommand} - Adds On-Demand Sandbox configuration
- *
- * ## Command Hierarchy
- *
- * Commands inherit in a chain, each adding specific functionality:
- *
- * ```
- * BaseCommand
- *   └─ OAuthCommand (adds OAuth)
- *        └─ InstanceCommand (adds instance config)
- *             ├─ CartridgeCommand (adds cartridge paths)
- *             ├─ JobCommand (adds job config)
- *             └─ WebDavCommand (adds WebDAV root config)
- *        └─ MrtCommand (adds MRT API auth)
- *        └─ OdsCommand (adds ODS config)
- * ```
- *
- * ## Example Usage
- *
- * ```typescript
- * import { InstanceCommand, createTable, type ColumnDef } from '@salesforce/b2c-tooling-sdk/cli';
- *
- * export default class ListSites extends InstanceCommand {
- *   static description = 'List all sites on the instance';
- *
- *   async run() {
- *     const client = await this.createOcapiClient();
- *     const sites = await client.getSites();
- *
- *     const columns: Record<string, ColumnDef<Site>> = {
- *       id: { header: 'ID', get: (s) => s.id },
- *       name: { header: 'Name', get: (s) => s.display_name },
- *     };
- *
- *     createTable(columns).render(sites, ['id', 'name']);
- *   }
- * }
- * ```
- *
- * ## Configuration Loading
- *
- * Use {@link loadConfig} to resolve configuration from multiple sources:
- *
- * ```typescript
- * import { loadConfig } from '@salesforce/b2c-tooling-sdk/cli';
- *
- * const config = await loadConfig({
- *   flags: { hostname: 'example.com' },
- *   configPath: './dw.json',
- * });
- * ```
- *
- * ## Table Rendering
- *
- * Use {@link createTable} for consistent tabular output:
- *
- * ```typescript
- * import { createTable, type ColumnDef } from '@salesforce/b2c-tooling-sdk/cli';
- *
- * const columns: Record<string, ColumnDef<Item>> = {
- *   id: { header: 'ID', get: (item) => item.id },
- *   status: { header: 'Status', get: (item) => item.status },
- * };
- *
- * createTable(columns).render(items, ['id', 'status']);
- * ```
- *
- * @module cli
- */
-export { BaseCommand } from './base-command.js';
-export type { Flags, Args } from './base-command.js';
-export { OAuthCommand } from './oauth-command.js';
-export { InstanceCommand } from './instance-command.js';
-export { CartridgeCommand } from './cartridge-command.js';
-export { JobCommand } from './job-command.js';
-export { MrtCommand } from './mrt-command.js';
-export { OdsCommand } from './ods-command.js';
-export { AmCommand } from './am-command.js';
-export { WebDavCommand, WEBDAV_ROOTS, VALID_ROOTS } from './webdav-command.js';
-export type { WebDavRootKey } from './webdav-command.js';
-export { loadConfig, findDwJson, extractOAuthFlags, extractInstanceFlags, extractMrtFlags, } from './config.js';
-export type { LoadConfigOptions, PluginSources, ParsedFlags, ExtractedMrtFlags } from './config.js';
-export type { ConfigSourcesHookOptions, ConfigSourcesHookResult, ConfigSourcesHook, HttpMiddlewareHookOptions, HttpMiddlewareHookResult, HttpMiddlewareHook, B2COperationType, B2COperationContext, BeforeB2COperationResult, B2COperationResult, AfterB2COperationResult, B2COperationLifecycleProvider, B2COperationLifecycleHookOptions, B2COperationLifecycleHookResult, B2COperationLifecycleHook, } from './hooks.js';
-export { createB2COperationContext, B2CLifecycleRunner } from './hooks.js';
-export {} from './hooks.js';
-export { TableRenderer, createTable } from './table.js';
-export type { ColumnDef, TableRenderOptions } from './table.js';
-export { columnFlagsFor, selectColumns } from './columns.js';
-export type { ColumnFlags, ColumnFlagsOptions, WarnFn } from './columns.js';
-export { printFieldsBlock } from './details.js';
-export type { DetailField, DetailFieldObject, DetailSection, DetailValue, PrintFieldsBlockOptions } from './details.js';

package/dist/cjs/cli/index.js

@@ -1,111 +0,0 @@
-/*
- * 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
- */
-/**
- * CLI utilities and base command classes for building B2C Commerce CLI commands.
- *
- * This module provides reusable base classes, configuration loading, and table
- * rendering utilities for oclif-based CLI applications.
- *
- * ## Base Command Classes
- *
- * Extend these classes to create CLI commands with pre-configured functionality:
- *
- * - {@link BaseCommand} - Foundation class with logging, JSON output, and error handling
- * - {@link OAuthCommand} - Adds OAuth authentication setup
- * - {@link InstanceCommand} - Adds B2C Commerce instance configuration
- * - {@link CartridgeCommand} - Adds cartridge path configuration for code operations
- * - {@link JobCommand} - Adds job execution configuration
- * - {@link WebDavCommand} - Adds WebDAV root directory configuration for file operations
- * - {@link MrtCommand} - Adds Managed Runtime API authentication
- * - {@link OdsCommand} - Adds On-Demand Sandbox configuration
- *
- * ## Command Hierarchy
- *
- * Commands inherit in a chain, each adding specific functionality:
- *
- * ```
- * BaseCommand
- *   └─ OAuthCommand (adds OAuth)
- *        └─ InstanceCommand (adds instance config)
- *             ├─ CartridgeCommand (adds cartridge paths)
- *             ├─ JobCommand (adds job config)
- *             └─ WebDavCommand (adds WebDAV root config)
- *        └─ MrtCommand (adds MRT API auth)
- *        └─ OdsCommand (adds ODS config)
- * ```
- *
- * ## Example Usage
- *
- * ```typescript
- * import { InstanceCommand, createTable, type ColumnDef } from '@salesforce/b2c-tooling-sdk/cli';
- *
- * export default class ListSites extends InstanceCommand {
- *   static description = 'List all sites on the instance';
- *
- *   async run() {
- *     const client = await this.createOcapiClient();
- *     const sites = await client.getSites();
- *
- *     const columns: Record<string, ColumnDef<Site>> = {
- *       id: { header: 'ID', get: (s) => s.id },
- *       name: { header: 'Name', get: (s) => s.display_name },
- *     };
- *
- *     createTable(columns).render(sites, ['id', 'name']);
- *   }
- * }
- * ```
- *
- * ## Configuration Loading
- *
- * Use {@link loadConfig} to resolve configuration from multiple sources:
- *
- * ```typescript
- * import { loadConfig } from '@salesforce/b2c-tooling-sdk/cli';
- *
- * const config = await loadConfig({
- *   flags: { hostname: 'example.com' },
- *   configPath: './dw.json',
- * });
- * ```
- *
- * ## Table Rendering
- *
- * Use {@link createTable} for consistent tabular output:
- *
- * ```typescript
- * import { createTable, type ColumnDef } from '@salesforce/b2c-tooling-sdk/cli';
- *
- * const columns: Record<string, ColumnDef<Item>> = {
- *   id: { header: 'ID', get: (item) => item.id },
- *   status: { header: 'Status', get: (item) => item.status },
- * };
- *
- * createTable(columns).render(items, ['id', 'status']);
- * ```
- *
- * @module cli
- */
-// Base command classes
-export { BaseCommand } from './base-command.js';
-export { OAuthCommand } from './oauth-command.js';
-export { InstanceCommand } from './instance-command.js';
-export { CartridgeCommand } from './cartridge-command.js';
-export { JobCommand } from './job-command.js';
-export { MrtCommand } from './mrt-command.js';
-export { OdsCommand } from './ods-command.js';
-export { AmCommand } from './am-command.js';
-export { WebDavCommand, WEBDAV_ROOTS, VALID_ROOTS } from './webdav-command.js';
-// Config utilities
-export { loadConfig, findDwJson, 
-// Flag extraction helpers for composable configuration
-extractOAuthFlags, extractInstanceFlags, extractMrtFlags, } from './config.js';
-export { createB2COperationContext, B2CLifecycleRunner } from './hooks.js';
-// Table rendering utilities
-export { TableRenderer, createTable } from './table.js';
-export { columnFlagsFor, selectColumns } from './columns.js';
-export { printFieldsBlock } from './details.js';
-//# sourceMappingURL=index.js.map

package/dist/cjs/cli/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAEH,uBAAuB;AACvB,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAC,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAE,YAAY,EAAE,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAG7E,mBAAmB;AACnB,OAAO,EACL,UAAU,EACV,UAAU;AACV,uDAAuD;AACvD,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,GAChB,MAAM,aAAa,CAAC;AAsBrB,OAAO,EAAC,yBAAyB,EAAE,kBAAkB,EAAC,MAAM,YAAY,CAAC;AAIzE,4BAA4B;AAC5B,OAAO,EAAC,aAAa,EAAE,WAAW,EAAC,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAC,cAAc,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAE3D,OAAO,EAAC,gBAAgB,EAAC,MAAM,cAAc,CAAC"}