@salesforce/b2c-tooling-sdk 0.0.1 → 0.0.3

package/dist/cjs/config/dw-json.d.ts

@@ -0,0 +1,114 @@
+import type { AuthMethod } from '../auth/types.js';
+/**
+ * Configuration structure matching dw.json file format.
+ * Uses kebab-case keys to match the file format.
+ */
+export interface DwJsonConfig {
+    /** Instance name (for multi-config files) */
+    name?: string;
+    /** Whether this config is active (for multi-config files) */
+    active?: boolean;
+    /** B2C instance hostname */
+    hostname?: string;
+    /** Code version for deployments */
+    'code-version'?: string;
+    /** Username for Basic auth (WebDAV) */
+    username?: string;
+    /** Password/access-key for Basic auth (WebDAV) */
+    password?: string;
+    /** OAuth client ID */
+    'client-id'?: string;
+    /** OAuth client secret */
+    'client-secret'?: string;
+    /** OAuth scopes */
+    'oauth-scopes'?: string[];
+    /** SCAPI short code (kebab-case) */
+    'short-code'?: string;
+    /** SCAPI short code (camelCase) */
+    shortCode?: string;
+    /** SCAPI short code (alternate kebab-case) */
+    'scapi-shortcode'?: string;
+    /** Alternate hostname for WebDAV (if different from main hostname) */
+    'webdav-hostname'?: string;
+    /** Alternate hostname for WebDAV (legacy camelCase format) */
+    secureHostname?: string;
+    /** Alternate hostname for WebDAV (legacy kebab-case format) */
+    'secure-server'?: string;
+    /** Allowed authentication methods in priority order */
+    'auth-methods'?: AuthMethod[];
+    /** Account Manager hostname for OAuth */
+    'account-manager-host'?: string;
+    /** MRT project slug */
+    mrtProject?: string;
+    /** MRT environment name (e.g., staging, production) */
+    mrtEnvironment?: string;
+}
+/**
+ * dw.json with multi-config support (configs array).
+ */
+export interface DwJsonMultiConfig extends DwJsonConfig {
+    /** Array of named instance configurations */
+    configs?: DwJsonConfig[];
+}
+/**
+ * Options for loading dw.json.
+ */
+export interface LoadDwJsonOptions {
+    /** Named instance to select from configs array */
+    instance?: string;
+    /** Explicit path to dw.json (skips searching if provided) */
+    path?: string;
+    /** Starting directory for search (defaults to cwd) */
+    startDir?: string;
+}
+/**
+ * Result of loading dw.json configuration.
+ */
+export interface LoadDwJsonResult {
+    /** The parsed configuration */
+    config: DwJsonConfig;
+    /** The path to the dw.json file that was loaded */
+    path: string;
+}
+/**
+ * Finds dw.json by searching upward from the starting directory.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Path to dw.json if found, undefined otherwise
+ *
+ * @example
+ * const dwPath = findDwJson();
+ * if (dwPath) {
+ *   console.log(`Found dw.json at ${dwPath}`);
+ * }
+ */
+export declare function findDwJson(startDir?: string): string | undefined;
+/**
+ * Loads configuration from a dw.json file.
+ *
+ * If an explicit path is provided, uses that file. Otherwise, looks for dw.json
+ * in the startDir (or cwd). Does NOT search parent directories.
+ *
+ * Use `findDwJson()` if you need to search upward through parent directories.
+ *
+ * @param options - Loading options
+ * @returns The parsed config with its path, or undefined if no dw.json found
+ *
+ * @example
+ * // Load from ./dw.json (current directory)
+ * const result = loadDwJson();
+ * if (result) {
+ *   console.log(`Loaded from ${result.path}`);
+ *   console.log(result.config.hostname);
+ * }
+ *
+ * // Load from specific directory
+ * const result = loadDwJson({ startDir: '/path/to/project' });
+ *
+ * // Use named instance
+ * const result = loadDwJson({ instance: 'staging' });
+ *
+ * // Explicit path
+ * const result = loadDwJson({ path: './config/dw.json' });
+ */
+export declare function loadDwJson(options?: LoadDwJsonOptions): LoadDwJsonResult | undefined;

package/dist/cjs/config/dw-json.js

@@ -0,0 +1,142 @@
+/*
+ * 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
+ */
+/**
+ * dw.json configuration file loading.
+ *
+ * This module provides utilities for loading B2C Commerce configuration from
+ * dw.json files, the standard configuration format used by B2C development tools.
+ *
+ * @module config
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getLogger } from '../logging/logger.js';
+/**
+ * Finds dw.json by searching upward from the starting directory.
+ *
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Path to dw.json if found, undefined otherwise
+ *
+ * @example
+ * const dwPath = findDwJson();
+ * if (dwPath) {
+ *   console.log(`Found dw.json at ${dwPath}`);
+ * }
+ */
+export function findDwJson(startDir = process.cwd()) {
+    let dir = startDir;
+    const root = path.parse(dir).root;
+    while (dir !== root) {
+        const dwJsonPath = path.join(dir, 'dw.json');
+        if (fs.existsSync(dwJsonPath)) {
+            return dwJsonPath;
+        }
+        dir = path.dirname(dir);
+    }
+    return undefined;
+}
+/**
+ * Selects the appropriate config from a multi-config dw.json.
+ *
+ * Selection priority:
+ * 1. Named instance (if `instance` option provided)
+ * 2. Config marked as `active: true`
+ * 3. Root-level config
+ */
+function selectConfig(json, instanceName) {
+    const logger = getLogger();
+    // Single config or no configs array
+    if (!Array.isArray(json.configs) || json.configs.length === 0) {
+        logger.trace({ selection: 'root', instanceName: json.name }, `[DwJsonSource] Selected config "${json.name ?? 'root'}" (single config)`);
+        return json;
+    }
+    // Find by instance name
+    if (instanceName) {
+        // Check root first
+        if (json.name === instanceName) {
+            logger.trace({ selection: 'named', instanceName }, `[DwJsonSource] Selected config "${instanceName}" by name (root)`);
+            return json;
+        }
+        // Then check configs array
+        const found = json.configs.find((c) => c.name === instanceName);
+        if (found) {
+            logger.trace({ selection: 'named', instanceName }, `[DwJsonSource] Selected config "${instanceName}" by name`);
+            return found;
+        }
+        // Instance explicitly requested but not found - return undefined
+        logger.trace({ requestedInstance: instanceName }, `[DwJsonSource] Named instance "${instanceName}" not found`);
+        return undefined;
+    }
+    // Find active config
+    if (json.active === false) {
+        // Root is inactive, look for active in configs
+        const activeConfig = json.configs.find((c) => c.active === true);
+        if (activeConfig) {
+            logger.trace({ selection: 'active', instanceName: activeConfig.name }, `[DwJsonSource] Selected config "${activeConfig.name}" by active flag`);
+            return activeConfig;
+        }
+    }
+    // Default to root config
+    logger.trace({ selection: 'root', instanceName: json.name }, `[DwJsonSource] Selected config "${json.name ?? 'root'}" (default to root)`);
+    return json;
+}
+/**
+ * Loads configuration from a dw.json file.
+ *
+ * If an explicit path is provided, uses that file. Otherwise, looks for dw.json
+ * in the startDir (or cwd). Does NOT search parent directories.
+ *
+ * Use `findDwJson()` if you need to search upward through parent directories.
+ *
+ * @param options - Loading options
+ * @returns The parsed config with its path, or undefined if no dw.json found
+ *
+ * @example
+ * // Load from ./dw.json (current directory)
+ * const result = loadDwJson();
+ * if (result) {
+ *   console.log(`Loaded from ${result.path}`);
+ *   console.log(result.config.hostname);
+ * }
+ *
+ * // Load from specific directory
+ * const result = loadDwJson({ startDir: '/path/to/project' });
+ *
+ * // Use named instance
+ * const result = loadDwJson({ instance: 'staging' });
+ *
+ * // Explicit path
+ * const result = loadDwJson({ path: './config/dw.json' });
+ */
+export function loadDwJson(options = {}) {
+    const logger = getLogger();
+    // If explicit path provided, use it. Otherwise default to ./dw.json (no upward search)
+    const dwJsonPath = options.path ?? path.join(options.startDir || process.cwd(), 'dw.json');
+    logger.trace({ path: dwJsonPath }, '[DwJsonSource] Checking for config file');
+    if (!fs.existsSync(dwJsonPath)) {
+        logger.trace({ path: dwJsonPath }, '[DwJsonSource] No config file found');
+        return undefined;
+    }
+    try {
+        const content = fs.readFileSync(dwJsonPath, 'utf8');
+        const json = JSON.parse(content);
+        const config = selectConfig(json, options.instance);
+        if (!config) {
+            return undefined;
+        }
+        return {
+            config,
+            path: dwJsonPath,
+        };
+    }
+    catch (error) {
+        // Invalid JSON or read error
+        const message = error instanceof Error ? error.message : String(error);
+        logger.trace({ path: dwJsonPath, error: message }, '[DwJsonSource] Failed to parse config file');
+        return undefined;
+    }
+}
+//# sourceMappingURL=dw-json.js.map

package/dist/cjs/config/dw-json.js.map

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

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

@@ -0,0 +1,96 @@
+/**
+ * Configuration loading utilities.
+ *
+ * This module provides utilities for loading B2C Commerce configuration.
+ * The preferred high-level API is {@link resolveConfig}, which returns
+ * a rich configuration object with factory methods.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
+ *
+ * const config = resolveConfig({
+ *   hostname: process.env.SFCC_SERVER,
+ *   clientId: process.env.SFCC_CLIENT_ID,
+ *   mrtApiKey: process.env.MRT_API_KEY,
+ * });
+ *
+ * // Check what's available and create objects
+ * if (config.hasB2CInstanceConfig()) {
+ *   const instance = config.createB2CInstance();
+ *   await instance.webdav.propfind('Cartridges');
+ * }
+ *
+ * if (config.hasMrtConfig()) {
+ *   const mrtClient = config.createMrtClient({ project: 'my-project' });
+ * }
+ * ```
+ *
+ * ## Resolution Priority
+ *
+ * Configuration is resolved with the following precedence (highest to lowest):
+ *
+ * 1. **Explicit overrides** - Values passed to `resolve()`, `createInstance()`, etc.
+ * 2. **Configuration sources** - dw.json, ~/.mobify (in order)
+ *
+ * Later sources only fill in missing values—they do not override values from
+ * higher-priority sources.
+ *
+ * ## Hostname Mismatch Protection
+ *
+ * The configuration system includes safety protection against accidentally using
+ * credentials from one instance with a different hostname. When you explicitly
+ * specify a hostname that differs from the dw.json hostname:
+ *
+ * - The entire base configuration from dw.json is ignored
+ * - Only your explicit overrides are used
+ * - A warning is included in the resolution result
+ *
+ * This prevents credential leakage between different B2C instances.
+ *
+ * ## Default Configuration Sources
+ *
+ * The default sources loaded by {@link createConfigResolver} are:
+ *
+ * - **dw.json** - Project configuration file, searched upward from cwd
+ * - **~/.mobify** - Home directory file for MRT API key
+ *
+ * ## Custom Configuration Sources
+ *
+ * Implement the {@link ConfigSource} interface to create custom sources:
+ *
+ * ```typescript
+ * import { ConfigResolver, type ConfigSource, type ConfigLoadResult } from '@salesforce/b2c-tooling-sdk/config';
+ *
+ * class MySource implements ConfigSource {
+ *   name = 'my-source';
+ *   load(options): ConfigLoadResult | undefined {
+ *     return {
+ *       config: { hostname: 'custom.example.com' },
+ *       location: '/path/to/source',
+ *     };
+ *   }
+ * }
+ *
+ * const resolver = new ConfigResolver([new MySource()]);
+ * ```
+ *
+ * ## Lower-Level APIs
+ *
+ * For advanced use cases, you can use the lower-level dw.json loading functions:
+ *
+ * ```typescript
+ * import { loadDwJson, findDwJson } from '@salesforce/b2c-tooling-sdk/config';
+ *
+ * const dwJsonPath = findDwJson();
+ * const config = loadDwJson({ path: dwJsonPath, instance: 'staging' });
+ * ```
+ *
+ * @module config
+ */
+export { resolveConfig, ConfigResolver, createConfigResolver } from './resolver.js';
+export type { NormalizedConfig, ConfigSource, ConfigLoadResult, ConfigSourceInfo, ConfigResolutionResult, ConfigWarning, ConfigWarningCode, ResolveConfigOptions, ResolvedB2CConfig, CreateOAuthOptions, CreateMrtClientOptions, } from './types.js';
+export { createInstanceFromConfig } from './mapping.js';
+export { loadDwJson, findDwJson } from './dw-json.js';
+export type { DwJsonConfig, DwJsonMultiConfig, LoadDwJsonOptions, LoadDwJsonResult } from './dw-json.js';

package/dist/cjs/config/index.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
+ */
+/**
+ * Configuration loading utilities.
+ *
+ * This module provides utilities for loading B2C Commerce configuration.
+ * The preferred high-level API is {@link resolveConfig}, which returns
+ * a rich configuration object with factory methods.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
+ *
+ * const config = resolveConfig({
+ *   hostname: process.env.SFCC_SERVER,
+ *   clientId: process.env.SFCC_CLIENT_ID,
+ *   mrtApiKey: process.env.MRT_API_KEY,
+ * });
+ *
+ * // Check what's available and create objects
+ * if (config.hasB2CInstanceConfig()) {
+ *   const instance = config.createB2CInstance();
+ *   await instance.webdav.propfind('Cartridges');
+ * }
+ *
+ * if (config.hasMrtConfig()) {
+ *   const mrtClient = config.createMrtClient({ project: 'my-project' });
+ * }
+ * ```
+ *
+ * ## Resolution Priority
+ *
+ * Configuration is resolved with the following precedence (highest to lowest):
+ *
+ * 1. **Explicit overrides** - Values passed to `resolve()`, `createInstance()`, etc.
+ * 2. **Configuration sources** - dw.json, ~/.mobify (in order)
+ *
+ * Later sources only fill in missing values—they do not override values from
+ * higher-priority sources.
+ *
+ * ## Hostname Mismatch Protection
+ *
+ * The configuration system includes safety protection against accidentally using
+ * credentials from one instance with a different hostname. When you explicitly
+ * specify a hostname that differs from the dw.json hostname:
+ *
+ * - The entire base configuration from dw.json is ignored
+ * - Only your explicit overrides are used
+ * - A warning is included in the resolution result
+ *
+ * This prevents credential leakage between different B2C instances.
+ *
+ * ## Default Configuration Sources
+ *
+ * The default sources loaded by {@link createConfigResolver} are:
+ *
+ * - **dw.json** - Project configuration file, searched upward from cwd
+ * - **~/.mobify** - Home directory file for MRT API key
+ *
+ * ## Custom Configuration Sources
+ *
+ * Implement the {@link ConfigSource} interface to create custom sources:
+ *
+ * ```typescript
+ * import { ConfigResolver, type ConfigSource, type ConfigLoadResult } from '@salesforce/b2c-tooling-sdk/config';
+ *
+ * class MySource implements ConfigSource {
+ *   name = 'my-source';
+ *   load(options): ConfigLoadResult | undefined {
+ *     return {
+ *       config: { hostname: 'custom.example.com' },
+ *       location: '/path/to/source',
+ *     };
+ *   }
+ * }
+ *
+ * const resolver = new ConfigResolver([new MySource()]);
+ * ```
+ *
+ * ## Lower-Level APIs
+ *
+ * For advanced use cases, you can use the lower-level dw.json loading functions:
+ *
+ * ```typescript
+ * import { loadDwJson, findDwJson } from '@salesforce/b2c-tooling-sdk/config';
+ *
+ * const dwJsonPath = findDwJson();
+ * const config = loadDwJson({ path: dwJsonPath, instance: 'staging' });
+ * ```
+ *
+ * @module config
+ */
+// High-level API (preferred)
+export { resolveConfig, ConfigResolver, createConfigResolver } from './resolver.js';
+// Instance creation utility (public API for CLI commands)
+export { createInstanceFromConfig } from './mapping.js';
+// Low-level dw.json API (still available for advanced use)
+export { loadDwJson, findDwJson } from './dw-json.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AAEH,6BAA6B;AAC7B,OAAO,EAAC,aAAa,EAAE,cAAc,EAAE,oBAAoB,EAAC,MAAM,eAAe,CAAC;AAiBlF,0DAA0D;AAC1D,OAAO,EAAC,wBAAwB,EAAC,MAAM,cAAc,CAAC;AAEtD,2DAA2D;AAC3D,OAAO,EAAC,UAAU,EAAE,UAAU,EAAC,MAAM,cAAc,CAAC"}

package/dist/cjs/config/mapping.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Configuration mapping utilities.
+ *
+ * This module provides the single source of truth for mapping between
+ * different configuration formats (dw.json, normalized config, etc.).
+ *
+ * @module config/mapping
+ */
+import type { AuthConfig } from '../auth/types.js';
+import { B2CInstance } from '../instance/index.js';
+import type { DwJsonConfig } from './dw-json.js';
+import type { NormalizedConfig, ConfigWarning } from './types.js';
+/**
+ * Maps dw.json fields to normalized config format.
+ *
+ * This is the SINGLE place where dw.json field mapping happens.
+ * Handles multiple field name variants for backward compatibility:
+ * - WebDAV hostname: `webdav-hostname`, `secureHostname`, `secure-server`
+ * - Short code: `shortCode`, `short-code`, `scapi-shortcode`
+ *
+ * @param json - The raw dw.json config
+ * @returns Normalized configuration
+ *
+ * @example
+ * ```typescript
+ * import { mapDwJsonToNormalizedConfig } from '@salesforce/b2c-tooling-sdk/config';
+ *
+ * const dwJson = { hostname: 'example.com', 'code-version': 'v1' };
+ * const config = mapDwJsonToNormalizedConfig(dwJson);
+ * // { hostname: 'example.com', codeVersion: 'v1' }
+ * ```
+ */
+export declare function mapDwJsonToNormalizedConfig(json: DwJsonConfig): NormalizedConfig;
+/**
+ * Options for merging configurations.
+ */
+export interface MergeConfigOptions {
+    /**
+     * Whether to apply hostname mismatch protection.
+     * When true, if overrides.hostname differs from base.hostname,
+     * the entire base config is ignored.
+     * @default true
+     */
+    hostnameProtection?: boolean;
+}
+/**
+ * Result of merging configurations.
+ */
+export interface MergeConfigResult {
+    /** The merged configuration */
+    config: NormalizedConfig;
+    /** Warnings generated during merge (e.g., hostname mismatch) */
+    warnings: ConfigWarning[];
+    /** Whether a hostname mismatch was detected and base was ignored */
+    hostnameMismatch: boolean;
+}
+/**
+ * Merges configurations with hostname mismatch protection.
+ *
+ * Applies the precedence rule: overrides > base.
+ * If hostname protection is enabled and the override hostname differs from
+ * the base hostname, the entire base config is ignored to prevent
+ * credential leakage between different instances.
+ *
+ * @param overrides - Higher-priority config values (e.g., from CLI flags/env)
+ * @param base - Lower-priority config values (e.g., from dw.json)
+ * @param options - Merge options
+ * @returns Merged config with warnings
+ *
+ * @example
+ * ```typescript
+ * import { mergeConfigsWithProtection } from '@salesforce/b2c-tooling-sdk/config';
+ *
+ * const { config, warnings } = mergeConfigsWithProtection(
+ *   { hostname: 'staging.example.com' },
+ *   { hostname: 'prod.example.com', clientId: 'abc' },
+ *   { hostnameProtection: true }
+ * );
+ * // config = { hostname: 'staging.example.com' }
+ * // warnings = [{ code: 'HOSTNAME_MISMATCH', ... }]
+ * ```
+ */
+export declare function mergeConfigsWithProtection(overrides: Partial<NormalizedConfig>, base: NormalizedConfig, options?: MergeConfigOptions): MergeConfigResult;
+/**
+ * Gets the list of fields that have values in a config.
+ *
+ * Used for tracking which sources contributed which fields during
+ * configuration resolution.
+ *
+ * @param config - The configuration to inspect
+ * @returns Array of field names that have non-empty values
+ *
+ * @example
+ * ```typescript
+ * const config = { hostname: 'example.com', clientId: 'abc' };
+ * const fields = getPopulatedFields(config);
+ * // ['hostname', 'clientId']
+ * ```
+ */
+export declare function getPopulatedFields(config: NormalizedConfig): (keyof NormalizedConfig)[];
+/**
+ * Builds an AuthConfig from a NormalizedConfig.
+ *
+ * This is the single source of truth for converting normalized config
+ * to the AuthConfig format expected by B2CInstance.
+ *
+ * @param config - The normalized configuration
+ * @returns AuthConfig for B2CInstance
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   clientId: 'my-client-id',
+ *   clientSecret: 'my-secret',
+ *   username: 'admin',
+ *   password: 'pass',
+ * };
+ * const authConfig = buildAuthConfigFromNormalized(config);
+ * // { oauth: { clientId: '...', clientSecret: '...' }, basic: { username: '...', password: '...' } }
+ * ```
+ */
+export declare function buildAuthConfigFromNormalized(config: NormalizedConfig): AuthConfig;
+/**
+ * Creates a B2CInstance from a NormalizedConfig.
+ *
+ * This utility provides a single source of truth for instance creation
+ * from resolved configuration. It is used by both ConfigResolver.createInstance()
+ * and CLI commands (e.g., InstanceCommand).
+ *
+ * @param config - The normalized configuration (must include hostname)
+ * @returns Configured B2CInstance
+ * @throws Error if hostname is not available in config
+ *
+ * @example
+ * ```typescript
+ * import { createInstanceFromConfig } from '@salesforce/b2c-tooling-sdk/config';
+ *
+ * const config = { hostname: 'example.demandware.net', clientId: 'abc' };
+ * const instance = createInstanceFromConfig(config);
+ * await instance.webdav.mkcol('Cartridges/v1');
+ * ```
+ */
+export declare function createInstanceFromConfig(config: NormalizedConfig): B2CInstance;