@salesforce/b2c-tooling-sdk 0.3.0 → 0.4.0

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

@@ -0,0 +1,137 @@
+import type { LibraryNodeType, LibraryParseOptions, TraverseOptions, TraverseCallback, FilterCallback, TreeStringOptions } from './types.js';
+/**
+ * A node in the content library tree.
+ *
+ * Represents a library, page, content asset, component, or static asset reference.
+ */
+export declare class LibraryNode {
+    id: string;
+    type: LibraryNodeType;
+    typeId: string | null;
+    data: Record<string, unknown> | null;
+    parent: LibraryNode | null;
+    children: LibraryNode[];
+    hidden: boolean;
+    /** @internal Raw xml2js content object */
+    xml: Record<string, unknown> | null;
+    constructor(values: {
+        id: string;
+        type: LibraryNodeType;
+        typeId: string | null;
+        data: Record<string, unknown> | null;
+        parent: LibraryNode | null;
+        children: LibraryNode[];
+        hidden: boolean;
+        xml: Record<string, unknown> | null;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Provides an interface for manipulating B2C Commerce content libraries.
+ *
+ * Use the static `Library.parse()` factory to create instances from library XML.
+ * The library tree supports filtering, traversal, mutation, and serialization
+ * back to importable XML.
+ *
+ * @example
+ * ```typescript
+ * const library = await Library.parse(xmlString);
+ *
+ * // Filter to specific pages
+ * library.filter(node => node.id === 'homepage');
+ *
+ * // Traverse visible nodes
+ * library.traverse(node => {
+ *   console.log(node.id, node.type);
+ * });
+ *
+ * // Serialize back to XML
+ * const xml = await library.toXMLString({ traverseHidden: false });
+ * ```
+ */
+export declare class Library {
+    assetQuery: string[];
+    tree: LibraryNode;
+    /** @internal Raw xml2js parsed object */
+    xml: Record<string, unknown>;
+    /** @internal */
+    constructor(guard: symbol);
+    /**
+     * Parse library XML into a Library tree.
+     *
+     * @param libraryXML - Raw XML string of a content library
+     * @param options - Parse options
+     * @returns Parsed Library instance
+     */
+    static parse(libraryXML: string, { assetQuery, keepOrphans }?: LibraryParseOptions): Promise<Library>;
+    /**
+     * Depth-first traversal of the library tree.
+     *
+     * @param callback - Function called for each visited node
+     * @param options - Traversal options
+     * @returns this (for chaining)
+     */
+    traverse(callback: TraverseCallback, { traverseHidden, callbackHidden }?: TraverseOptions): this;
+    /**
+     * Generator-based depth-first iteration of the library tree.
+     *
+     * @param options - Traversal options
+     * @yields LibraryNode for each visited node
+     *
+     * @example
+     * ```typescript
+     * for (const node of library.nodes()) {
+     *   console.log(node.id, node.type);
+     * }
+     * ```
+     */
+    nodes({ traverseHidden, callbackHidden }?: TraverseOptions): Generator<LibraryNode>;
+    /**
+     * Filter the library tree by setting hidden flags on root children.
+     *
+     * @param predicate - Return true to keep the node visible
+     * @param options - Filter options
+     * @returns this (for chaining)
+     */
+    filter(predicate: FilterCallback, { recursive }?: {
+        recursive?: boolean | undefined;
+    }): this;
+    /**
+     * Move a node from its current parent to the root of the library tree.
+     *
+     * Useful for exporting individual components that are normally nested under pages.
+     * The node is removed from its original parent's children and added as a root child.
+     *
+     * @param node - The node to promote
+     * @returns this (for chaining)
+     */
+    promoteToRoot(node: LibraryNode): this;
+    /**
+     * Reset all hidden flags, making every node visible again.
+     *
+     * @returns this (for chaining)
+     */
+    reset(): this;
+    /**
+     * Serialize the library back to importable XML.
+     *
+     * Only includes visible content unless `traverseHidden` is true.
+     *
+     * @param options - Serialization options
+     * @returns XML string
+     */
+    toXMLString({ traverseHidden }?: {
+        traverseHidden?: boolean;
+    }): Promise<string>;
+    /**
+     * Returns a text tree visualization of the library structure.
+     *
+     * @param options - Tree string options (traversal and optional colorize function)
+     * @returns Multi-line tree string
+     */
+    getTreeString({ traverseHidden, colorize }?: TreeStringOptions): string;
+    /**
+     * Returns a JSON-safe representation of the library tree.
+     */
+    toJSON(): Record<string, unknown>;
+}

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

@@ -0,0 +1,392 @@
+/*
+ * 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 * as xml2js from 'xml2js';
+import { getLogger } from '../../logging/logger.js';
+import { extractAssetPaths } from './asset-query.js';
+/**
+ * A node in the content library tree.
+ *
+ * Represents a library, page, content asset, component, or static asset reference.
+ */
+export class LibraryNode {
+    id;
+    type;
+    typeId;
+    data;
+    parent;
+    children;
+    hidden;
+    /** @internal Raw xml2js content object */
+    xml;
+    constructor(values) {
+        this.id = values.id;
+        this.type = values.type;
+        this.typeId = values.typeId;
+        this.data = values.data;
+        this.parent = values.parent;
+        this.children = values.children;
+        this.hidden = values.hidden;
+        this.xml = values.xml;
+    }
+    toJSON() {
+        return {
+            id: this.id,
+            type: this.type,
+            typeId: this.typeId,
+            data: this.data,
+            children: this.children,
+            hidden: this.hidden,
+        };
+    }
+}
+/**
+ * Recursively processes a content XML element into a LibraryNode tree.
+ *
+ * Extracts child components via content-links and static assets via asset queries.
+ */
+function processContent(content, allContent, assetQuery) {
+    const logger = getLogger();
+    const attrs = content['$'];
+    const contentId = attrs['content-id'];
+    const contentType = content['type']?.[0] ?? null;
+    const dataElements = content['data'];
+    const node = new LibraryNode({
+        id: contentId,
+        type: contentType ? (contentType.startsWith('page.') ? 'PAGE' : 'COMPONENT') : 'CONTENT',
+        typeId: contentType,
+        data: null,
+        children: [],
+        xml: content,
+        hidden: false,
+        parent: null,
+    });
+    // Parse JSON data and extract asset paths
+    if (dataElements?.[0]?.['_']) {
+        try {
+            const dataJson = JSON.parse(dataElements[0]['_']);
+            node.data = dataJson;
+            const assetPaths = extractAssetPaths(dataJson, assetQuery);
+            for (const assetPath of assetPaths) {
+                node.children.push(new LibraryNode({
+                    id: assetPath,
+                    type: 'STATIC',
+                    typeId: null,
+                    data: null,
+                    parent: node,
+                    children: [],
+                    hidden: false,
+                    xml: null,
+                }));
+            }
+        }
+        catch {
+            logger.warn({ contentId }, `Could not parse JSON data for content ${contentId}`);
+        }
+    }
+    // Recurse into content-links
+    const contentLinks = content['content-links'];
+    if (contentLinks?.[0]?.['content-link']) {
+        const links = contentLinks[0]['content-link'];
+        for (const link of links) {
+            const linkAttrs = link['$'];
+            const linkId = linkAttrs['content-id'];
+            if (!allContent[linkId]) {
+                logger.warn(`Cannot find component ${linkId} in library; skipping...`);
+                continue;
+            }
+            const componentNode = processContent(allContent[linkId], allContent, assetQuery);
+            componentNode.parent = node;
+            node.children.push(componentNode);
+        }
+    }
+    return node;
+}
+/** Private guard to enforce use of Library.parse() */
+const CONSTRUCTOR_GUARD = Symbol('Library.parse');
+/**
+ * Provides an interface for manipulating B2C Commerce content libraries.
+ *
+ * Use the static `Library.parse()` factory to create instances from library XML.
+ * The library tree supports filtering, traversal, mutation, and serialization
+ * back to importable XML.
+ *
+ * @example
+ * ```typescript
+ * const library = await Library.parse(xmlString);
+ *
+ * // Filter to specific pages
+ * library.filter(node => node.id === 'homepage');
+ *
+ * // Traverse visible nodes
+ * library.traverse(node => {
+ *   console.log(node.id, node.type);
+ * });
+ *
+ * // Serialize back to XML
+ * const xml = await library.toXMLString({ traverseHidden: false });
+ * ```
+ */
+export class Library {
+    assetQuery = [];
+    tree;
+    /** @internal Raw xml2js parsed object */
+    xml;
+    /** @internal */
+    constructor(guard) {
+        if (guard !== CONSTRUCTOR_GUARD) {
+            throw new Error('Use Library.parse() to construct a Library instance');
+        }
+    }
+    /**
+     * Parse library XML into a Library tree.
+     *
+     * @param libraryXML - Raw XML string of a content library
+     * @param options - Parse options
+     * @returns Parsed Library instance
+     */
+    static async parse(libraryXML, { assetQuery = ['image.path'], keepOrphans = false } = {}) {
+        const xml = (await xml2js.parseStringPromise(libraryXML));
+        const libraryElement = xml['library'];
+        const attrs = libraryElement['$'];
+        const libraryId = attrs['library-id'];
+        const contentArray = libraryElement['content'];
+        const library = new Library(CONSTRUCTOR_GUARD);
+        library.assetQuery = assetQuery;
+        const root = new LibraryNode({
+            id: libraryId,
+            type: 'LIBRARY',
+            typeId: null,
+            children: [],
+            data: null,
+            parent: null,
+            hidden: false,
+            xml: null,
+        });
+        // Index all content by ID
+        const contentById = {};
+        for (const c of contentArray) {
+            const cAttrs = c['$'];
+            contentById[cAttrs['content-id']] = c;
+        }
+        // Process pages and root-level content (no type = content asset)
+        for (const c of contentArray) {
+            const cType = c['type']?.[0];
+            if ((cType && cType.startsWith('page.')) || !cType) {
+                const node = processContent(c, contentById, assetQuery);
+                node.parent = root;
+                root.children.push(node);
+            }
+        }
+        library.xml = xml;
+        library.tree = root;
+        // Optionally include orphan components
+        if (keepOrphans) {
+            const processedIds = new Set();
+            library.traverse((node) => {
+                processedIds.add(node.id);
+            });
+            for (const c of contentArray) {
+                const cAttrs = c['$'];
+                const cId = cAttrs['content-id'];
+                if (!processedIds.has(cId)) {
+                    const node = processContent(c, contentById, assetQuery);
+                    node.parent = root;
+                    root.children.push(node);
+                }
+            }
+        }
+        // Remove headers and folders from xml (not needed for filtered export)
+        delete libraryElement['header'];
+        delete libraryElement['folder'];
+        return library;
+    }
+    /**
+     * Depth-first traversal of the library tree.
+     *
+     * @param callback - Function called for each visited node
+     * @param options - Traversal options
+     * @returns this (for chaining)
+     */
+    traverse(callback, { traverseHidden = true, callbackHidden = false } = {}) {
+        function walk(node) {
+            if (!node.hidden || traverseHidden) {
+                for (const child of node.children) {
+                    walk(child);
+                }
+            }
+            if (!node.hidden || callbackHidden) {
+                callback(node);
+            }
+        }
+        for (const child of this.tree.children) {
+            walk(child);
+        }
+        return this;
+    }
+    /**
+     * Generator-based depth-first iteration of the library tree.
+     *
+     * @param options - Traversal options
+     * @yields LibraryNode for each visited node
+     *
+     * @example
+     * ```typescript
+     * for (const node of library.nodes()) {
+     *   console.log(node.id, node.type);
+     * }
+     * ```
+     */
+    *nodes({ traverseHidden = true, callbackHidden = false } = {}) {
+        function* walk(node) {
+            if (!node.hidden || traverseHidden) {
+                for (const child of node.children) {
+                    yield* walk(child);
+                }
+            }
+            if (!node.hidden || callbackHidden) {
+                yield node;
+            }
+        }
+        for (const child of this.tree.children) {
+            yield* walk(child);
+        }
+    }
+    /**
+     * Filter the library tree by setting hidden flags on root children.
+     *
+     * @param predicate - Return true to keep the node visible
+     * @param options - Filter options
+     * @returns this (for chaining)
+     */
+    filter(predicate, { recursive = false } = {}) {
+        if (!recursive) {
+            for (const child of this.tree.children) {
+                child.hidden = !predicate(child);
+            }
+        }
+        else {
+            this.traverse((n) => {
+                n.hidden = !predicate(n);
+            }, { traverseHidden: true, callbackHidden: true });
+        }
+        return this;
+    }
+    /**
+     * Move a node from its current parent to the root of the library tree.
+     *
+     * Useful for exporting individual components that are normally nested under pages.
+     * The node is removed from its original parent's children and added as a root child.
+     *
+     * @param node - The node to promote
+     * @returns this (for chaining)
+     */
+    promoteToRoot(node) {
+        if (node.parent && node.parent !== this.tree) {
+            node.parent.children = node.parent.children.filter((c) => c !== node);
+        }
+        if (!this.tree.children.includes(node)) {
+            node.parent = this.tree;
+            node.hidden = false;
+            this.tree.children.push(node);
+        }
+        return this;
+    }
+    /**
+     * Reset all hidden flags, making every node visible again.
+     *
+     * @returns this (for chaining)
+     */
+    reset() {
+        this.traverse((n) => {
+            n.hidden = false;
+        }, { traverseHidden: true, callbackHidden: true });
+        return this;
+    }
+    /**
+     * Serialize the library back to importable XML.
+     *
+     * Only includes visible content unless `traverseHidden` is true.
+     *
+     * @param options - Serialization options
+     * @returns XML string
+     */
+    async toXMLString({ traverseHidden = true } = {}) {
+        const libraryElement = this.xml['library'];
+        delete libraryElement['content'];
+        libraryElement['content'] = [];
+        this.traverse((n) => {
+            const node = n;
+            if (node.data && node.xml) {
+                const dataEl = node.xml['data']?.[0];
+                if (dataEl) {
+                    dataEl['_'] = JSON.stringify(node.data, null, 2);
+                }
+            }
+            if (node.xml) {
+                libraryElement['content'].push(node.xml);
+            }
+        }, { traverseHidden });
+        const builder = new xml2js.Builder();
+        return builder.buildObject(this.xml);
+    }
+    /**
+     * Returns a text tree visualization of the library structure.
+     *
+     * @param options - Tree string options (traversal and optional colorize function)
+     * @returns Multi-line tree string
+     */
+    getTreeString({ traverseHidden = false, colorize } = {}) {
+        const lines = [];
+        const c = colorize ?? ((_color, text) => text);
+        function formatNode(node) {
+            switch (node.type) {
+                case 'COMPONENT': {
+                    return node.typeId ? `${c('cyan', node.typeId)} ${c('dim', `(${node.id})`)}` : node.id;
+                }
+                case 'CONTENT': {
+                    return `${c('bold', node.id)} ${c('dim', '(CONTENT ASSET)')}`;
+                }
+                case 'PAGE': {
+                    const name = c('bold', node.id);
+                    return node.typeId ? `${name} ${c('dim', `(typeId: ${node.typeId})`)}` : name;
+                }
+                case 'STATIC': {
+                    return `${c('green', node.id)} ${c('dim', '(STATIC ASSET)')}`;
+                }
+                default: {
+                    return node.id;
+                }
+            }
+        }
+        function visibleChildren(node) {
+            return traverseHidden ? node.children : node.children.filter((child) => !child.hidden);
+        }
+        function renderSubtree(children, prefix) {
+            for (let i = 0; i < children.length; i++) {
+                const node = children[i];
+                const isLast = i === children.length - 1;
+                const connector = isLast ? '└── ' : '├── ';
+                const extension = isLast ? '    ' : '│   ';
+                const hiddenTag = node.hidden ? ` ${c('yellow', '[HIDDEN]')}` : '';
+                lines.push(`${c('dim', prefix + connector)}${formatNode(node)}${hiddenTag}`);
+                renderSubtree(visibleChildren(node), prefix + extension);
+            }
+        }
+        for (const child of visibleChildren(this.tree)) {
+            const hiddenTag = child.hidden ? ` ${c('yellow', '[HIDDEN]')}` : '';
+            lines.push(`${formatNode(child)}${hiddenTag}`);
+            renderSubtree(visibleChildren(child), '');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Returns a JSON-safe representation of the library tree.
+     */
+    toJSON() {
+        return this.tree.toJSON();
+    }
+}
+//# sourceMappingURL=library.js.map

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

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

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;
+}