@salesforce/b2c-tooling-sdk 0.2.1 → 0.4.0

package/dist/cjs/operations/content/types.d.ts

@@ -0,0 +1,144 @@
+import type { WaitForJobOptions } from '../jobs/run.js';
+/**
+ * Node types in a content library tree.
+ */
+export type LibraryNodeType = 'LIBRARY' | 'PAGE' | 'CONTENT' | 'COMPONENT' | 'STATIC';
+/**
+ * Options for parsing a library XML string into a Library tree.
+ */
+export interface LibraryParseOptions {
+    /**
+     * Dot-notation paths for extracting static asset references from component JSON data.
+     * Use `*` as a wildcard to traverse arrays.
+     *
+     * @default ['image.path']
+     *
+     * @example
+     * ```typescript
+     * // Extract image paths from nested JSON
+     * { assetQuery: ['image.path', 'banners.*.image.src'] }
+     * ```
+     */
+    assetQuery?: string[];
+    /**
+     * Include orphan components (components not linked to any page) as root-level children.
+     * Useful for cleaning up unused components.
+     *
+     * @default false
+     */
+    keepOrphans?: boolean;
+}
+/**
+ * Options controlling tree traversal behavior.
+ */
+export interface TraverseOptions {
+    /** Traverse into hidden (filtered-out) subtrees. @default true */
+    traverseHidden?: boolean;
+    /** Execute callback for hidden nodes. @default false */
+    callbackHidden?: boolean;
+}
+/**
+ * Callback for tree traversal.
+ */
+export type TraverseCallback = (node: LibraryNodeData) => void;
+/**
+ * Callback for tree filtering. Return true to keep the node visible.
+ */
+export type FilterCallback = (node: LibraryNodeData) => boolean;
+/**
+ * A function that applies terminal color/style to text.
+ * Compatible with oclif's `ux.colorize(color, text)` signature.
+ */
+export type ColorizeFn = (color: string, text: string) => string;
+/**
+ * Options for generating a tree string visualization.
+ */
+export interface TreeStringOptions {
+    /** Whether to include hidden nodes in the output. @default false */
+    traverseHidden?: boolean;
+    /** Optional colorize function for terminal styling. When omitted, plain text is returned. */
+    colorize?: ColorizeFn;
+}
+/**
+ * Minimal interface for LibraryNode data (avoids circular import).
+ */
+export interface LibraryNodeData {
+    id: string;
+    type: LibraryNodeType;
+    typeId: string | null;
+    data: Record<string, unknown> | null;
+    parent: LibraryNodeData | null;
+    children: LibraryNodeData[];
+    hidden: boolean;
+    /** @internal Raw xml2js content object */
+    xml: Record<string, unknown> | null;
+}
+/**
+ * Options for fetching a content library from an instance or local file.
+ */
+export interface FetchContentLibraryOptions {
+    /** Use a local library XML file instead of fetching from the instance. */
+    libraryFile?: string;
+    /** Library is a site-private library (use site export path). */
+    isSiteLibrary?: boolean;
+    /** Asset query paths for static asset extraction. @default ['image.path'] */
+    assetQuery?: string[];
+    /** Include orphan components. @default false */
+    keepOrphans?: boolean;
+    /** Wait options for the export job. */
+    waitOptions?: WaitForJobOptions;
+}
+/**
+ * Result of fetching and parsing a content library.
+ */
+export interface FetchContentLibraryResult {
+    /** The parsed library tree (filter/traverse/mutate as needed). */
+    library: import('./library.js').Library;
+    /** The raw archive data buffer (for further processing or re-import). */
+    archiveData?: Buffer;
+}
+/**
+ * Options for the high-level content export operation.
+ */
+export interface ContentExportOptions {
+    /** Library is a site-private library. @default false */
+    isSiteLibrary?: boolean;
+    /** Asset query paths for static asset extraction. @default ['image.path'] */
+    assetQuery?: string[];
+    /** Use a local library XML file instead of fetching from instance. */
+    libraryFile?: string;
+    /** Skip asset downloads. @default false */
+    offline?: boolean;
+    /** Filter by folder classification IDs. */
+    folders?: string[];
+    /** Treat page IDs as regular expressions. @default false */
+    regex?: boolean;
+    /** Include orphan components. @default false */
+    keepOrphans?: boolean;
+    /** Wait options for the export job. */
+    waitOptions?: WaitForJobOptions;
+    /** Callback for asset download progress. */
+    onAssetProgress?: (asset: string, index: number, total: number, success: boolean) => void;
+}
+/**
+ * Result of a content export operation.
+ */
+export interface ContentExportResult {
+    /** The parsed and filtered library tree. */
+    library: import('./library.js').Library;
+    /** Output directory path. */
+    outputPath: string;
+    /** List of successfully downloaded asset paths. */
+    downloadedAssets: string[];
+    /** List of assets that failed to download. */
+    failedAssets: {
+        path: string;
+        error: string;
+    }[];
+    /** Number of pages in the filtered export. */
+    pageCount: number;
+    /** Number of content assets in the filtered export. */
+    contentCount: number;
+    /** Number of components in the filtered export. */
+    componentCount: number;
+}

package/dist/cjs/operations/content/types.js

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

package/dist/cjs/operations/content/types.js.map

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

package/dist/cjs/operations/logs/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Log operations for B2C Commerce instances.
+ *
+ * This module provides functions for listing, tailing, and analyzing log files
+ * on B2C Commerce instances via WebDAV.
+ *
+ * @module operations/logs
+ *
+ * @example
+ * List log files:
+ * ```typescript
+ * import { listLogFiles } from '@salesforce/b2c-tooling-sdk/operations/logs';
+ *
+ * const files = await listLogFiles(instance, {
+ *   prefixes: ['error', 'customerror'],
+ *   sortBy: 'date',
+ *   sortOrder: 'desc'
+ * });
+ *
+ * for (const file of files) {
+ *   console.log(`${file.name} (${file.size} bytes)`);
+ * }
+ * ```
+ *
+ * @example
+ * Tail logs in real-time:
+ * ```typescript
+ * import { tailLogs, createPathNormalizer } from '@salesforce/b2c-tooling-sdk/operations/logs';
+ *
+ * const normalizer = createPathNormalizer({ cartridgePath: './cartridges' });
+ *
+ * const { stop, done } = await tailLogs(instance, {
+ *   prefixes: ['error', 'customerror'],
+ *   pathNormalizer: normalizer,
+ *   onEntry: (entry) => {
+ *     console.log(`[${entry.file}] ${entry.level}: ${entry.message}`);
+ *   },
+ *   onError: (err) => console.error('Error:', err),
+ * });
+ *
+ * // Stop after 30 seconds
+ * setTimeout(() => stop(), 30000);
+ *
+ * await done;
+ * ```
+ *
+ * @example
+ * Get recent logs (one-shot):
+ * ```typescript
+ * import { getRecentLogs } from '@salesforce/b2c-tooling-sdk/operations/logs';
+ *
+ * const entries = await getRecentLogs(instance, {
+ *   prefixes: ['error'],
+ *   maxEntries: 50
+ * });
+ *
+ * for (const entry of entries) {
+ *   console.log(`[${entry.timestamp}] ${entry.message}`);
+ * }
+ * ```
+ */
+export type { GetRecentLogsOptions, ListLogsOptions, LogEntry, LogFile, TailLogsCallbacks, TailLogsOptions, TailLogsResult, } from './types.js';
+export { extractPrefix, listLogFiles } from './list.js';
+export { aggregateLogEntries, getRecentLogs, parseLogEntry, splitLines, tailLogs } from './tail.js';
+export { createPathNormalizer, discoverAndCreateNormalizer, extractPaths, type PathNormalizerOptions, } from './path-normalizer.js';

package/dist/cjs/operations/logs/index.js

@@ -0,0 +1,73 @@
+/*
+ * 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
+ */
+/**
+ * Log operations for B2C Commerce instances.
+ *
+ * This module provides functions for listing, tailing, and analyzing log files
+ * on B2C Commerce instances via WebDAV.
+ *
+ * @module operations/logs
+ *
+ * @example
+ * List log files:
+ * ```typescript
+ * import { listLogFiles } from '@salesforce/b2c-tooling-sdk/operations/logs';
+ *
+ * const files = await listLogFiles(instance, {
+ *   prefixes: ['error', 'customerror'],
+ *   sortBy: 'date',
+ *   sortOrder: 'desc'
+ * });
+ *
+ * for (const file of files) {
+ *   console.log(`${file.name} (${file.size} bytes)`);
+ * }
+ * ```
+ *
+ * @example
+ * Tail logs in real-time:
+ * ```typescript
+ * import { tailLogs, createPathNormalizer } from '@salesforce/b2c-tooling-sdk/operations/logs';
+ *
+ * const normalizer = createPathNormalizer({ cartridgePath: './cartridges' });
+ *
+ * const { stop, done } = await tailLogs(instance, {
+ *   prefixes: ['error', 'customerror'],
+ *   pathNormalizer: normalizer,
+ *   onEntry: (entry) => {
+ *     console.log(`[${entry.file}] ${entry.level}: ${entry.message}`);
+ *   },
+ *   onError: (err) => console.error('Error:', err),
+ * });
+ *
+ * // Stop after 30 seconds
+ * setTimeout(() => stop(), 30000);
+ *
+ * await done;
+ * ```
+ *
+ * @example
+ * Get recent logs (one-shot):
+ * ```typescript
+ * import { getRecentLogs } from '@salesforce/b2c-tooling-sdk/operations/logs';
+ *
+ * const entries = await getRecentLogs(instance, {
+ *   prefixes: ['error'],
+ *   maxEntries: 50
+ * });
+ *
+ * for (const entry of entries) {
+ *   console.log(`[${entry.timestamp}] ${entry.message}`);
+ * }
+ * ```
+ */
+// List operations
+export { extractPrefix, listLogFiles } from './list.js';
+// Tail operations
+export { aggregateLogEntries, getRecentLogs, parseLogEntry, splitLines, tailLogs } from './tail.js';
+// Path normalization
+export { createPathNormalizer, discoverAndCreateNormalizer, extractPaths, } from './path-normalizer.js';
+//# sourceMappingURL=index.js.map

package/dist/cjs/operations/logs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/operations/logs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAaH,kBAAkB;AAClB,OAAO,EAAC,aAAa,EAAE,YAAY,EAAC,MAAM,WAAW,CAAC;AAEtD,kBAAkB;AAClB,OAAO,EAAC,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAC,MAAM,WAAW,CAAC;AAElG,qBAAqB;AACrB,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,YAAY,GAEb,MAAM,sBAAsB,CAAC"}

package/dist/cjs/operations/logs/list.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Log file listing operations.
+ */
+import type { B2CInstance } from '../../instance/index.js';
+import type { ListLogsOptions, LogFile } from './types.js';
+/**
+ * Extracts the log prefix from a filename.
+ *
+ * @param filename - Log file name (e.g., "error-blade1-20250125.log")
+ * @returns The prefix (e.g., "error") or "unknown"
+ *
+ * @example
+ * extractPrefix("error-blade1-20250125.log") // "error"
+ * extractPrefix("customerror-blade1-20250125.log") // "customerror"
+ * extractPrefix("custom-mylog-blade1-20250125.log") // "custom-mylog"
+ */
+export declare function extractPrefix(filename: string): string;
+/**
+ * Lists log files on a B2C Commerce instance.
+ *
+ * @param instance - B2C instance to list logs from
+ * @param options - Listing options (filters, sorting)
+ * @returns Array of log files
+ *
+ * @example
+ * ```typescript
+ * // List all error and customerror logs
+ * const logs = await listLogFiles(instance, {
+ *   prefixes: ['error', 'customerror'],
+ *   sortBy: 'date',
+ *   sortOrder: 'desc'
+ * });
+ * ```
+ */
+export declare function listLogFiles(instance: B2CInstance, options?: ListLogsOptions): Promise<LogFile[]>;

package/dist/cjs/operations/logs/list.js

@@ -0,0 +1,144 @@
+import { getLogger } from '../../logging/logger.js';
+/**
+ * Known log file prefixes in B2C Commerce.
+ * Used to extract the prefix from log file names.
+ */
+const LOG_PREFIXES = [
+    // Custom logs (must check first due to "custom" prefix)
+    'customdebug',
+    'custominfo',
+    'customwarn',
+    'customerror',
+    'customfatal',
+    // System logs
+    'error',
+    'warn',
+    'info',
+    'debug',
+    'fatal',
+    'api',
+    'deprecation',
+    'jobs',
+    'staging',
+    'quota',
+    'sql',
+    'service',
+    'syslog',
+    'security',
+    'analytics',
+    'migration',
+    // Custom named logs (format: custom-<name>-...)
+    'custom',
+];
+/**
+ * Extracts the log prefix from a filename.
+ *
+ * @param filename - Log file name (e.g., "error-blade1-20250125.log")
+ * @returns The prefix (e.g., "error") or "unknown"
+ *
+ * @example
+ * extractPrefix("error-blade1-20250125.log") // "error"
+ * extractPrefix("customerror-blade1-20250125.log") // "customerror"
+ * extractPrefix("custom-mylog-blade1-20250125.log") // "custom-mylog"
+ */
+export function extractPrefix(filename) {
+    // Handle custom-<name> pattern (e.g., custom-mylog-blade1-...)
+    // Custom log names use word characters only (no dashes) to distinguish from hostname
+    const customMatch = filename.match(/^(custom-[a-zA-Z0-9_]+)-/);
+    if (customMatch) {
+        return customMatch[1];
+    }
+    // Check known prefixes (order matters - longer matches first)
+    for (const prefix of LOG_PREFIXES) {
+        if (filename.startsWith(`${prefix}-`) || filename.startsWith(`${prefix}_`)) {
+            return prefix;
+        }
+    }
+    // Fallback: extract first segment before dash or underscore
+    const match = filename.match(/^([a-zA-Z]+)[-_]/);
+    return match ? match[1] : 'unknown';
+}
+/**
+ * Lists log files on a B2C Commerce instance.
+ *
+ * @param instance - B2C instance to list logs from
+ * @param options - Listing options (filters, sorting)
+ * @returns Array of log files
+ *
+ * @example
+ * ```typescript
+ * // List all error and customerror logs
+ * const logs = await listLogFiles(instance, {
+ *   prefixes: ['error', 'customerror'],
+ *   sortBy: 'date',
+ *   sortOrder: 'desc'
+ * });
+ * ```
+ */
+export async function listLogFiles(instance, options = {}) {
+    const logger = getLogger();
+    const { prefixes, sortBy = 'date', sortOrder = 'desc' } = options;
+    logger.debug({ prefixes, sortBy, sortOrder }, 'Listing log files');
+    // Get all files from Logs directory
+    const entries = await instance.webdav.propfind('Logs', '1');
+    // Filter to only log files (not directories, not the Logs directory itself)
+    const logFiles = entries
+        .filter((entry) => {
+        // Skip directories
+        if (entry.isCollection)
+            return false;
+        // Skip if not a .log file
+        const name = entry.displayName || entry.href.split('/').pop() || '';
+        if (!name.endsWith('.log'))
+            return false;
+        return true;
+    })
+        .map((entry) => {
+        const name = entry.displayName || entry.href.split('/').pop() || '';
+        const prefix = extractPrefix(name);
+        return {
+            name,
+            prefix,
+            size: entry.contentLength || 0,
+            lastModified: entry.lastModified || new Date(0),
+            path: `Logs/${name}`,
+        };
+    });
+    // Filter by prefix if specified
+    let filtered = logFiles;
+    if (prefixes && prefixes.length > 0) {
+        const prefixSet = new Set(prefixes.map((p) => p.toLowerCase()));
+        filtered = logFiles.filter((file) => {
+            // Check exact prefix match
+            if (prefixSet.has(file.prefix.toLowerCase()))
+                return true;
+            // Also check if the prefix starts with any of the specified prefixes
+            // This handles cases like "custom-mylog" matching "custom"
+            for (const p of prefixSet) {
+                if (file.prefix.toLowerCase().startsWith(p))
+                    return true;
+            }
+            return false;
+        });
+    }
+    // Sort the results
+    filtered.sort((a, b) => {
+        let comparison = 0;
+        switch (sortBy) {
+            case 'name':
+                comparison = a.name.localeCompare(b.name);
+                break;
+            case 'size':
+                comparison = a.size - b.size;
+                break;
+            case 'date':
+            default:
+                comparison = a.lastModified.getTime() - b.lastModified.getTime();
+                break;
+        }
+        return sortOrder === 'desc' ? -comparison : comparison;
+    });
+    logger.debug({ count: filtered.length }, `Found ${filtered.length} log files`);
+    return filtered;
+}
+//# sourceMappingURL=list.js.map

package/dist/cjs/operations/logs/list.js.map

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

package/dist/cjs/operations/logs/path-normalizer.d.ts

@@ -0,0 +1,82 @@
+import { type CartridgeMapping } from '../code/cartridges.js';
+/**
+ * Options for creating a path normalizer.
+ */
+export interface PathNormalizerOptions {
+    /**
+     * Local path to the cartridges directory (simple mode).
+     * All cartridge references will be prefixed with this path.
+     * @example "./cartridges" or "/Users/dev/project/cartridges"
+     */
+    cartridgePath?: string;
+    /**
+     * Discovered cartridge mappings (precise mode).
+     * Each cartridge is mapped to its actual local path.
+     * Takes precedence over cartridgePath for known cartridges.
+     */
+    cartridges?: CartridgeMapping[];
+}
+/**
+ * Creates a path normalizer function for converting remote cartridge paths
+ * to local paths in log messages.
+ *
+ * Supports two modes:
+ * 1. **Cartridge mappings** (precise): Uses discovered cartridges to map each
+ *    cartridge name to its actual local path. Best for projects with cartridges
+ *    in different locations.
+ * 2. **Cartridge path** (simple): Prefixes all paths with a base directory.
+ *    Best when all cartridges are in a single directory.
+ *
+ * @param options - Normalizer options
+ * @returns Function that normalizes paths in a message string, or undefined if no options provided
+ *
+ * @example
+ * ```typescript
+ * // Using discovered cartridges (recommended)
+ * const cartridges = findCartridges('./my-project');
+ * const normalize = createPathNormalizer({ cartridges });
+ *
+ * // Using simple cartridge path
+ * const normalize = createPathNormalizer({ cartridgePath: './cartridges' });
+ *
+ * // Input: "(app_storefront/cartridge/controllers/Home.js:45)"
+ * // Output: "(./cartridges/app_storefront/cartridge/controllers/Home.js:45)"
+ * const normalized = normalize(logMessage);
+ * ```
+ */
+export declare function createPathNormalizer(options: PathNormalizerOptions): ((message: string) => string) | undefined;
+/**
+ * Discovers cartridges and creates a path normalizer automatically.
+ *
+ * This is a convenience function that combines `findCartridges` with
+ * `createPathNormalizer` for easy setup. Cartridge paths are converted
+ * to relative paths from the current working directory.
+ *
+ * @param directory - Directory to search for cartridges (defaults to cwd)
+ * @returns Path normalizer function, or undefined if no cartridges found
+ *
+ * @example
+ * ```typescript
+ * // Auto-discover cartridges from current directory
+ * const normalize = discoverAndCreateNormalizer();
+ *
+ * // Auto-discover from specific directory
+ * const normalize = discoverAndCreateNormalizer('./my-project');
+ * ```
+ */
+export declare function discoverAndCreateNormalizer(directory?: string): ((message: string) => string) | undefined;
+/**
+ * Extracts all cartridge paths from a message.
+ *
+ * Useful for testing or analysis of log messages.
+ *
+ * @param message - Log message to extract paths from
+ * @returns Array of extracted paths
+ *
+ * @example
+ * ```typescript
+ * const paths = extractPaths("Error at (app_storefront/cartridge/controllers/Home.js:45)");
+ * // Returns: ["app_storefront/cartridge/controllers/Home.js:45"]
+ * ```
+ */
+export declare function extractPaths(message: string): string[];