@salesforce/b2c-tooling-sdk 0.0.1 → 0.0.3

package/dist/esm/logging/logger.js

@@ -0,0 +1,111 @@
+/*
+ * 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
+ */
+/**
+ * Logger using pino with pretty printing by default.
+ */
+import pino from 'pino';
+import pretty from 'pino-pretty';
+const REDACT_FIELDS = [
+    'password',
+    'client_secret',
+    'clientSecret',
+    'access_token',
+    'accessToken',
+    'refresh_token',
+    'refreshToken',
+    'api_key',
+    'apiKey',
+    'token',
+    'secret',
+    'authorization',
+    'Authorization',
+];
+const REDACT_PATHS = REDACT_FIELDS.flatMap((field) => [field, `*.${field}`]);
+function censor(value, path) {
+    // Special handling for authorization headers
+    if (path[path.length - 1].toLowerCase() === 'authorization' && typeof value === 'string') {
+        const parts = value.split(' ');
+        if (parts.length === 2) {
+            const [scheme, credentials] = parts;
+            // For Basic auth, decode, redact password, and re-encode
+            if (scheme.toLowerCase() === 'basic') {
+                try {
+                    const decoded = Buffer.from(credentials, 'base64').toString('utf-8');
+                    const colonIndex = decoded.indexOf(':');
+                    if (colonIndex !== -1) {
+                        const username = decoded.slice(0, colonIndex);
+                        const redacted = Buffer.from(`${username}:REDACTED`).toString('base64');
+                        return `Basic ${redacted}`;
+                    }
+                }
+                catch {
+                    // If decoding fails, fall through to default behavior
+                }
+            }
+            // For other schemes (Bearer, etc.), show scheme and partial token
+            return `${scheme} ${credentials.slice(0, 6)}...REDACTED`;
+        }
+    }
+    if (typeof value === 'string' && value.length > 10) {
+        return `${value.slice(0, 4)}...REDACTED`;
+    }
+    return 'REDACTED';
+}
+let globalLogger = null;
+let globalOptions = { level: 'silent' };
+function createPinoLogger(options) {
+    const level = options.level ?? 'info';
+    const fd = options.fd ?? 2; // Default to stderr
+    const colorize = options.colorize ?? true;
+    const pinoOptions = {
+        level,
+        base: options.baseContext ?? {},
+        formatters: {
+            level: (label) => ({ level: label }),
+        },
+    };
+    if (options.redact !== false) {
+        pinoOptions.redact = {
+            paths: REDACT_PATHS,
+            censor,
+        };
+    }
+    // JSON output
+    if (options.json) {
+        return pino(pinoOptions, pino.destination({ fd, sync: true }));
+    }
+    // Pretty print (default)
+    const isVerbose = level === 'debug' || level === 'trace';
+    const prettyStream = pretty({
+        destination: fd,
+        sync: true,
+        colorize,
+        ignore: 'pid,hostname' + (isVerbose ? '' : ',time'),
+        hideObject: !isVerbose,
+    });
+    return pino(pinoOptions, prettyStream);
+}
+export function createLogger(options = {}) {
+    return createPinoLogger({ ...globalOptions, ...options });
+}
+export function configureLogger(options) {
+    globalOptions = { ...globalOptions, ...options };
+    globalLogger = createPinoLogger(globalOptions);
+}
+export function getLogger() {
+    if (!globalLogger) {
+        globalLogger = createPinoLogger(globalOptions);
+    }
+    return globalLogger;
+}
+export function resetLogger() {
+    globalLogger = null;
+    globalOptions = { level: 'silent' };
+}
+export function createSilentLogger() {
+    return createLogger({ level: 'silent' });
+}
+//# sourceMappingURL=logger.js.map

package/dist/esm/logging/logger.js.map

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

package/dist/esm/logging/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Logging types.
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
+export interface LogContext {
+    [key: string]: unknown;
+}
+export interface LoggerOptions {
+    /** Log level. Default: 'info' */
+    level?: LogLevel;
+    /** File descriptor to write to (1=stdout, 2=stderr). Default: 2 */
+    fd?: number;
+    /** Base context included in all log entries */
+    baseContext?: LogContext;
+    /** Enable secret redaction. Default: true */
+    redact?: boolean;
+    /** Output JSON lines instead of pretty print. Default: false */
+    json?: boolean;
+    /** Enable colors in pretty print mode. Default: true */
+    colorize?: boolean;
+}
+export interface Logger {
+    trace(message: string, context?: LogContext): void;
+    trace(context: LogContext, message: string): void;
+    debug(message: string, context?: LogContext): void;
+    debug(context: LogContext, message: string): void;
+    info(message: string, context?: LogContext): void;
+    info(context: LogContext, message: string): void;
+    warn(message: string, context?: LogContext): void;
+    warn(context: LogContext, message: string): void;
+    error(message: string, context?: LogContext): void;
+    error(context: LogContext, message: string): void;
+    fatal(message: string, context?: LogContext): void;
+    fatal(context: LogContext, message: string): void;
+    child(context: LogContext): Logger;
+}

package/dist/esm/logging/types.js

@@ -0,0 +1,10 @@
+/*
+ * 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
+ */
+/**
+ * Logging types.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/logging/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/logging/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;GAEG"}

package/dist/esm/operations/code/cartridges.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Represents a discovered cartridge in the local filesystem.
+ */
+export interface CartridgeMapping {
+    /** Cartridge name (directory name containing .project) */
+    name: string;
+    /** Absolute path to the cartridge directory */
+    src: string;
+    /** Destination name (same as name, used for WebDAV path) */
+    dest: string;
+}
+/**
+ * Options for finding cartridges.
+ */
+export interface FindCartridgesOptions {
+    /** Cartridge names to include (if empty, all are included) */
+    include?: string[];
+    /** Cartridge names to exclude */
+    exclude?: string[];
+}
+/**
+ * Find cartridges recursively in a directory.
+ *
+ * Cartridges are identified by the presence of a `.project` file
+ * (Eclipse project marker commonly used in SFCC development).
+ *
+ * @param directory - Directory to search for cartridges (defaults to cwd)
+ * @param options - Filter options for including/excluding cartridges
+ * @returns Array of discovered cartridge mappings
+ *
+ * @example
+ * ```typescript
+ * // Find all cartridges in current directory
+ * const cartridges = findCartridges();
+ *
+ * // Find cartridges in specific directory
+ * const cartridges = findCartridges('./my-project');
+ *
+ * // Find specific cartridges only
+ * const cartridges = findCartridges('.', { include: ['app_storefront_base'] });
+ *
+ * // Find all except certain cartridges
+ * const cartridges = findCartridges('.', { exclude: ['test_cartridge'] });
+ * ```
+ */
+export declare function findCartridges(directory?: string, options?: FindCartridgesOptions): CartridgeMapping[];

package/dist/esm/operations/code/cartridges.js

@@ -0,0 +1,59 @@
+/*
+ * 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
+ */
+import { globSync } from 'glob';
+import path from 'node:path';
+/**
+ * Find cartridges recursively in a directory.
+ *
+ * Cartridges are identified by the presence of a `.project` file
+ * (Eclipse project marker commonly used in SFCC development).
+ *
+ * @param directory - Directory to search for cartridges (defaults to cwd)
+ * @param options - Filter options for including/excluding cartridges
+ * @returns Array of discovered cartridge mappings
+ *
+ * @example
+ * ```typescript
+ * // Find all cartridges in current directory
+ * const cartridges = findCartridges();
+ *
+ * // Find cartridges in specific directory
+ * const cartridges = findCartridges('./my-project');
+ *
+ * // Find specific cartridges only
+ * const cartridges = findCartridges('.', { include: ['app_storefront_base'] });
+ *
+ * // Find all except certain cartridges
+ * const cartridges = findCartridges('.', { exclude: ['test_cartridge'] });
+ * ```
+ */
+export function findCartridges(directory, options = {}) {
+    const searchDir = directory ? path.resolve(directory) : process.cwd();
+    // Find all .project files (Eclipse project markers)
+    const projectFiles = globSync('**/.project', {
+        cwd: searchDir,
+        ignore: ['**/node_modules/**'],
+    });
+    let cartridges = projectFiles.map((f) => {
+        const dirname = path.resolve(searchDir, path.dirname(f));
+        const cartridgeName = path.basename(dirname);
+        return {
+            name: cartridgeName,
+            dest: cartridgeName,
+            src: dirname,
+        };
+    });
+    // Apply include filter
+    if (options.include && options.include.length > 0) {
+        cartridges = cartridges.filter((c) => options.include.includes(c.name));
+    }
+    // Apply exclude filter
+    if (options.exclude && options.exclude.length > 0) {
+        cartridges = cartridges.filter((c) => !options.exclude.includes(c.name));
+    }
+    return cartridges;
+}
+//# sourceMappingURL=cartridges.js.map

package/dist/esm/operations/code/cartridges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cartridges.js","sourceRoot":"","sources":["../../../../src/operations/code/cartridges.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,QAAQ,EAAC,MAAM,MAAM,CAAC;AAC9B,OAAO,IAAI,MAAM,WAAW,CAAC;AAwB7B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,cAAc,CAAC,SAAkB,EAAE,UAAiC,EAAE;IACpF,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;IAEtE,oDAAoD;IACpD,MAAM,YAAY,GAAG,QAAQ,CAAC,aAAa,EAAE;QAC3C,GAAG,EAAE,SAAS;QACd,MAAM,EAAE,CAAC,oBAAoB,CAAC;KAC/B,CAAC,CAAC;IAEH,IAAI,UAAU,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACtC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACzD,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC7C,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,aAAa;YACnB,GAAG,EAAE,OAAO;SACb,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,uBAAuB;IACvB,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,OAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED,uBAAuB;IACvB,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/esm/operations/code/deploy.d.ts

@@ -0,0 +1,101 @@
+import type { B2CInstance } from '../../instance/index.js';
+import { type CartridgeMapping, type FindCartridgesOptions } from './cartridges.js';
+/**
+ * Options for deploying cartridges.
+ */
+export interface DeployOptions extends FindCartridgesOptions {
+    /** Reload (re-activate) the code version after deploy */
+    reload?: boolean;
+    /** Delete existing cartridges before uploading */
+    delete?: boolean;
+}
+/**
+ * Result of a cartridge deployment.
+ */
+export interface DeployResult {
+    /** Cartridges that were deployed */
+    cartridges: CartridgeMapping[];
+    /** Code version deployed to */
+    codeVersion: string;
+    /** Whether the code version was reloaded */
+    reloaded: boolean;
+}
+/**
+ * Deletes cartridges from an instance via WebDAV.
+ *
+ * This is a low-level function that deletes cartridge directories
+ * from the specified code version. Errors are silently ignored for
+ * cartridges that don't exist.
+ *
+ * Requires `instance.config.codeVersion` to be set.
+ *
+ * @param instance - B2C instance to delete from
+ * @param cartridges - Cartridge mappings to delete
+ * @throws Error if code version not set
+ *
+ * @example
+ * ```typescript
+ * const cartridges = findCartridges('./cartridges');
+ * await deleteCartridges(instance, cartridges);
+ * ```
+ */
+export declare function deleteCartridges(instance: B2CInstance, cartridges: CartridgeMapping[]): Promise<void>;
+/**
+ * Uploads cartridges to an instance via WebDAV.
+ *
+ * This is a low-level upload function that:
+ * 1. Creates a zip archive of the cartridges
+ * 2. Uploads it to WebDAV
+ * 3. Unzips on the server
+ * 4. Cleans up the temporary zip file
+ *
+ * Requires `instance.config.codeVersion` to be set.
+ *
+ * @param instance - B2C instance to upload to
+ * @param cartridges - Cartridge mappings to upload
+ * @throws Error if code version not set or upload fails
+ *
+ * @example
+ * ```typescript
+ * const cartridges = findCartridges('./cartridges');
+ * await uploadCartridges(instance, cartridges);
+ * ```
+ */
+export declare function uploadCartridges(instance: B2CInstance, cartridges: CartridgeMapping[]): Promise<void>;
+/**
+ * Finds and deploys cartridges from a directory to an instance.
+ *
+ * This is a high-level function that orchestrates the deployment process:
+ * 1. Finds cartridges in the specified directory (by .project files)
+ * 2. Applies include/exclude filters
+ * 3. Optionally deletes existing cartridges first
+ * 4. Creates a zip archive and uploads via WebDAV
+ * 5. Optionally reloads the code version
+ *
+ * Requires `instance.config.codeVersion` to be set.
+ *
+ * @param instance - B2C instance to deploy to (must have codeVersion set)
+ * @param directory - Directory to search for cartridges
+ * @param options - Deploy options (filters, reload, delete)
+ * @returns Deploy result with cartridges and status
+ * @throws Error if code version not set, no cartridges found, or deployment fails
+ *
+ * @example
+ * ```typescript
+ * // Simple deploy
+ * const result = await findAndDeployCartridges(instance, './cartridges');
+ *
+ * // Deploy specific cartridges with reload
+ * const result = await findAndDeployCartridges(instance, '.', {
+ *   include: ['app_storefront_base'],
+ *   reload: true,
+ * });
+ *
+ * // Delete existing cartridges before upload
+ * const result = await findAndDeployCartridges(instance, './cartridges', {
+ *   delete: true,
+ *   reload: true,
+ * });
+ * ```
+ */
+export declare function findAndDeployCartridges(instance: B2CInstance, directory: string, options?: DeployOptions): Promise<DeployResult>;

package/dist/esm/operations/code/deploy.js

@@ -0,0 +1,218 @@
+/*
+ * 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
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import JSZip from 'jszip';
+import { getLogger } from '../../logging/logger.js';
+import { findCartridges } from './cartridges.js';
+import { reloadCodeVersion } from './versions.js';
+const UNZIP_BODY = new URLSearchParams({ method: 'UNZIP' }).toString();
+/**
+ * Recursively adds a directory to a JSZip instance.
+ */
+async function addDirectoryToZip(zip, dirPath, zipPath) {
+    const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        const entryZipPath = path.join(zipPath, entry.name);
+        if (entry.isDirectory()) {
+            await addDirectoryToZip(zip, fullPath, entryZipPath);
+        }
+        else if (entry.isFile()) {
+            const content = await fs.promises.readFile(fullPath);
+            zip.file(entryZipPath, content);
+        }
+    }
+}
+/**
+ * Deletes cartridges from an instance via WebDAV.
+ *
+ * This is a low-level function that deletes cartridge directories
+ * from the specified code version. Errors are silently ignored for
+ * cartridges that don't exist.
+ *
+ * Requires `instance.config.codeVersion` to be set.
+ *
+ * @param instance - B2C instance to delete from
+ * @param cartridges - Cartridge mappings to delete
+ * @throws Error if code version not set
+ *
+ * @example
+ * ```typescript
+ * const cartridges = findCartridges('./cartridges');
+ * await deleteCartridges(instance, cartridges);
+ * ```
+ */
+export async function deleteCartridges(instance, cartridges) {
+    const logger = getLogger();
+    const codeVersion = instance.config.codeVersion;
+    if (!codeVersion) {
+        throw new Error('Code version required for cartridge deletion');
+    }
+    if (cartridges.length === 0) {
+        return;
+    }
+    const webdav = instance.webdav;
+    logger.debug({ count: cartridges.length }, `Deleting ${cartridges.length} cartridge(s)...`);
+    for (const c of cartridges) {
+        const cartridgePath = `Cartridges/${codeVersion}/${c.dest}`;
+        try {
+            await webdav.delete(cartridgePath);
+            logger.debug({ cartridgeName: c.dest, path: cartridgePath }, `Deleted ${cartridgePath}`);
+        }
+        catch {
+            // Ignore errors - cartridge may not exist
+            logger.debug({ cartridgeName: c.dest, path: cartridgePath }, `Could not delete ${cartridgePath} (may not exist)`);
+        }
+    }
+}
+/**
+ * Uploads cartridges to an instance via WebDAV.
+ *
+ * This is a low-level upload function that:
+ * 1. Creates a zip archive of the cartridges
+ * 2. Uploads it to WebDAV
+ * 3. Unzips on the server
+ * 4. Cleans up the temporary zip file
+ *
+ * Requires `instance.config.codeVersion` to be set.
+ *
+ * @param instance - B2C instance to upload to
+ * @param cartridges - Cartridge mappings to upload
+ * @throws Error if code version not set or upload fails
+ *
+ * @example
+ * ```typescript
+ * const cartridges = findCartridges('./cartridges');
+ * await uploadCartridges(instance, cartridges);
+ * ```
+ */
+export async function uploadCartridges(instance, cartridges) {
+    const logger = getLogger();
+    const codeVersion = instance.config.codeVersion;
+    if (!codeVersion) {
+        throw new Error('Code version required for cartridge upload');
+    }
+    if (cartridges.length === 0) {
+        throw new Error('No cartridges to upload');
+    }
+    const webdav = instance.webdav;
+    const now = Date.now();
+    const uploadPath = `Cartridges/_sync-${now}.zip`;
+    // Create zip archive
+    logger.debug('Creating cartridge archive...');
+    const zip = new JSZip();
+    for (const c of cartridges) {
+        await addDirectoryToZip(zip, c.src, path.join(codeVersion, c.dest));
+    }
+    const buffer = await zip.generateAsync({
+        type: 'nodebuffer',
+        compression: 'DEFLATE',
+        compressionOptions: { level: 9 },
+    });
+    logger.debug({ size: buffer.length }, `Archive created: ${buffer.length} bytes`);
+    // Upload archive
+    logger.debug({ uploadPath }, 'Uploading archive...');
+    await webdav.put(uploadPath, buffer, 'application/zip');
+    logger.debug('Archive uploaded');
+    // Unzip on server
+    logger.debug('Unzipping archive on server...');
+    const response = await webdav.request(uploadPath, {
+        method: 'POST',
+        body: UNZIP_BODY,
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+        },
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Failed to unzip archive: ${response.status} ${response.statusText} - ${text}`);
+    }
+    logger.debug('Archive unzipped');
+    // Delete temporary archive
+    await webdav.delete(uploadPath);
+    logger.debug('Temporary archive deleted');
+    logger.debug({ server: instance.config.hostname, codeVersion, cartridgeCount: cartridges.length }, `Uploaded ${cartridges.length} cartridges to ${instance.config.hostname}`);
+}
+/**
+ * Finds and deploys cartridges from a directory to an instance.
+ *
+ * This is a high-level function that orchestrates the deployment process:
+ * 1. Finds cartridges in the specified directory (by .project files)
+ * 2. Applies include/exclude filters
+ * 3. Optionally deletes existing cartridges first
+ * 4. Creates a zip archive and uploads via WebDAV
+ * 5. Optionally reloads the code version
+ *
+ * Requires `instance.config.codeVersion` to be set.
+ *
+ * @param instance - B2C instance to deploy to (must have codeVersion set)
+ * @param directory - Directory to search for cartridges
+ * @param options - Deploy options (filters, reload, delete)
+ * @returns Deploy result with cartridges and status
+ * @throws Error if code version not set, no cartridges found, or deployment fails
+ *
+ * @example
+ * ```typescript
+ * // Simple deploy
+ * const result = await findAndDeployCartridges(instance, './cartridges');
+ *
+ * // Deploy specific cartridges with reload
+ * const result = await findAndDeployCartridges(instance, '.', {
+ *   include: ['app_storefront_base'],
+ *   reload: true,
+ * });
+ *
+ * // Delete existing cartridges before upload
+ * const result = await findAndDeployCartridges(instance, './cartridges', {
+ *   delete: true,
+ *   reload: true,
+ * });
+ * ```
+ */
+export async function findAndDeployCartridges(instance, directory, options = {}) {
+    const logger = getLogger();
+    const codeVersion = instance.config.codeVersion;
+    if (!codeVersion) {
+        throw new Error('Code version required for deployment');
+    }
+    logger.debug({ directory }, 'Finding cartridges...');
+    const cartridges = findCartridges(directory, {
+        include: options.include,
+        exclude: options.exclude,
+    });
+    if (cartridges.length === 0) {
+        throw new Error(`No cartridges found in ${directory}`);
+    }
+    logger.debug({ count: cartridges.length }, `Found ${cartridges.length} cartridge(s)`);
+    for (const c of cartridges) {
+        logger.debug({ cartridgeName: c.name, path: c.src }, `  ${c.name}`);
+    }
+    // Optionally delete existing cartridges first
+    if (options.delete) {
+        await deleteCartridges(instance, cartridges);
+    }
+    // Upload cartridges
+    await uploadCartridges(instance, cartridges);
+    // Optionally reload
+    let reloaded = false;
+    if (options.reload) {
+        logger.debug('Reloading code version...');
+        try {
+            await reloadCodeVersion(instance, codeVersion);
+            reloaded = true;
+        }
+        catch (error) {
+            logger.debug({ error }, 'Could not reload code version');
+        }
+    }
+    return {
+        cartridges,
+        codeVersion,
+        reloaded,
+    };
+}
+//# sourceMappingURL=deploy.js.map

package/dist/esm/operations/code/deploy.js.map

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

package/dist/esm/operations/code/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Code deployment operations for B2C Commerce.
+ *
+ * This module provides functions for managing cartridge code versions
+ * on B2C Commerce instances via WebDAV and OCAPI.
+ *
+ * ## Cartridge Discovery
+ *
+ * - {@link findCartridges} - Find cartridges by .project files
+ *
+ * ## Code Versions
+ *
+ * - {@link listCodeVersions} - List all code versions on an instance
+ * - {@link getActiveCodeVersion} - Get the currently active code version
+ * - {@link activateCodeVersion} - Activate a code version
+ * - {@link reloadCodeVersion} - Reload (re-activate) a code version
+ * - {@link deleteCodeVersion} - Delete a code version
+ * - {@link createCodeVersion} - Create a new code version
+ *
+ * ## Deployment
+ *
+ * - {@link findAndDeployCartridges} - Find and deploy cartridges to an instance
+ * - {@link uploadCartridges} - Low-level cartridge upload
+ * - {@link deleteCartridges} - Low-level cartridge deletion
+ * - {@link watchCartridges} - Watch and sync file changes
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import {
+ *   findCartridges,
+ *   findAndDeployCartridges,
+ *   listCodeVersions,
+ *   activateCodeVersion,
+ *   watchCartridges,
+ * } from '@salesforce/b2c-tooling-sdk/operations/code';
+ * import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
+ *
+ * const config = resolveConfig();
+ * const instance = config.createB2CInstance();
+ *
+ * // Deploy cartridges (requires instance.config.codeVersion to be set)
+ * await findAndDeployCartridges(instance, './cartridges', { reload: true });
+ *
+ * // List code versions
+ * const versions = await listCodeVersions(instance);
+ *
+ * // Watch for changes
+ * const watcher = await watchCartridges(instance, './cartridges');
+ * ```
+ *
+ * ## Authentication
+ *
+ * - WebDAV operations support both Basic Auth and OAuth
+ * - OCAPI operations (code versions) require OAuth
+ *
+ * @module operations/code
+ */
+export { findCartridges } from './cartridges.js';
+export type { CartridgeMapping, FindCartridgesOptions } from './cartridges.js';
+export { listCodeVersions, getActiveCodeVersion, activateCodeVersion, reloadCodeVersion, deleteCodeVersion, createCodeVersion, } from './versions.js';
+export type { CodeVersion, CodeVersionResult } from './versions.js';
+export { findAndDeployCartridges, uploadCartridges, deleteCartridges } from './deploy.js';
+export type { DeployOptions, DeployResult } from './deploy.js';
+export { watchCartridges } from './watch.js';
+export type { WatchOptions, WatchResult } from './watch.js';