@salesforce/b2c-tooling-sdk 1.3.2 → 1.5.0

package/dist/esm/operations/cap/install.d.ts

@@ -0,0 +1,53 @@
+import { B2CInstance } from '../../instance/index.js';
+import { type JobExecution, type WaitForJobOptions } from '../jobs/run.js';
+import { type CommerceAppManifest } from './validate.js';
+/**
+ * Options for CAP installation.
+ */
+export interface CommerceAppInstallOptions {
+    /** Target site ID to install the app on. */
+    siteId: string;
+    /** Keep the uploaded zip on the instance after install (default: false). */
+    keepArchive?: boolean;
+    /** Wait options for job completion. */
+    waitOptions?: WaitForJobOptions;
+}
+/**
+ * Result of a CAP installation.
+ */
+export interface CommerceAppInstallResult {
+    /** Job execution details. */
+    execution: JobExecution;
+    /** App name (id from commerce-app.json). */
+    appName: string;
+    /** App version. */
+    appVersion: string;
+    /** Uploaded archive filename. */
+    archiveFilename: string;
+    /** Whether the archive was kept on the instance. */
+    archiveKept: boolean;
+}
+/**
+ * Installs a Commerce App Package (CAP) on a B2C Commerce instance.
+ *
+ * Accepts a local directory or zip file. Reads the commerce-app.json manifest
+ * to determine app name, version, and domain. Uploads the zip to WebDAV and
+ * executes the sfcc-install-commerce-app system job.
+ *
+ * @param instance - B2C instance to install to
+ * @param target - Path to a CAP directory or .zip file
+ * @param options - Install options including required siteId
+ * @returns Install result with job execution details
+ * @throws JobExecutionError if the install job fails
+ *
+ * @example
+ * ```typescript
+ * const result = await commerceAppInstall(instance, './commerce-avalara-tax-app-v0.2.5', {
+ *   siteId: 'RefArch',
+ * });
+ * ```
+ */
+export declare function commerceAppInstall(instance: B2CInstance, target: string, options: CommerceAppInstallOptions): Promise<CommerceAppInstallResult>;
+export declare function readManifest(capDir: string): CommerceAppManifest;
+/** Prefix site ID with "Sites-" if not already present. */
+export declare function normalizeSiteId(siteId: string): string;

package/dist/esm/operations/cap/install.js

@@ -0,0 +1,183 @@
+/*
+ * 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
+ */
+/**
+ * Commerce App Package (CAP) installation.
+ *
+ * Uploads a CAP to WebDAV and runs the sfcc-install-commerce-app system job.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import JSZip from 'jszip';
+import { B2CInstance } from '../../instance/index.js';
+import { getLogger } from '../../logging/logger.js';
+import { waitForJob, JobExecutionError, getJobLog } from '../jobs/run.js';
+import { addDirectoryToZip } from '../util/zip.js';
+import {} from './validate.js';
+const INSTALL_JOB_ID = 'sfcc-install-commerce-app';
+/**
+ * Installs a Commerce App Package (CAP) on a B2C Commerce instance.
+ *
+ * Accepts a local directory or zip file. Reads the commerce-app.json manifest
+ * to determine app name, version, and domain. Uploads the zip to WebDAV and
+ * executes the sfcc-install-commerce-app system job.
+ *
+ * @param instance - B2C instance to install to
+ * @param target - Path to a CAP directory or .zip file
+ * @param options - Install options including required siteId
+ * @returns Install result with job execution details
+ * @throws JobExecutionError if the install job fails
+ *
+ * @example
+ * ```typescript
+ * const result = await commerceAppInstall(instance, './commerce-avalara-tax-app-v0.2.5', {
+ *   siteId: 'RefArch',
+ * });
+ * ```
+ */
+export async function commerceAppInstall(instance, target, options) {
+    const logger = getLogger();
+    const { siteId: rawSiteId, keepArchive = false, waitOptions } = options;
+    const siteId = normalizeSiteId(rawSiteId);
+    if (!fs.existsSync(target)) {
+        throw new Error(`Target not found: ${target}`);
+    }
+    const stat = fs.statSync(target);
+    let archiveContent;
+    let archiveFilename;
+    let manifest;
+    if (stat.isDirectory()) {
+        manifest = readManifest(target);
+        archiveFilename = `${manifest.id}-v${manifest.version}.zip`;
+        logger.debug({ path: target }, `Packaging CAP directory: ${target}`);
+        archiveContent = await createArchiveFromDirectory(target, `${manifest.id}-v${manifest.version}`);
+    }
+    else if (stat.isFile() && target.endsWith('.zip')) {
+        manifest = await readManifestFromZip(target);
+        archiveFilename = path.basename(target);
+        archiveContent = await fs.promises.readFile(target);
+    }
+    else {
+        throw new Error(`Target must be a directory or .zip file: ${target}`);
+    }
+    const uploadDir = 'Impex/commerce-apps';
+    const webdavUploadPath = `${uploadDir}/${archiveFilename}`;
+    const appPath = `webdav/Sites/${webdavUploadPath}`;
+    logger.debug({ path: webdavUploadPath }, `Uploading CAP to ${webdavUploadPath}`);
+    await instance.webdav.mkcol(uploadDir);
+    await instance.webdav.put(webdavUploadPath, archiveContent, 'application/zip');
+    logger.debug({ path: webdavUploadPath }, `CAP uploaded: ${webdavUploadPath}`);
+    // Execute the install job
+    logger.debug({ jobId: INSTALL_JOB_ID, appName: manifest.id, siteId }, `Executing ${INSTALL_JOB_ID} job`);
+    let execution;
+    // Try direct body format first (standard OCAPI format)
+    const { data, error } = await instance.ocapi.POST('/jobs/{job_id}/executions', {
+        params: { path: { job_id: INSTALL_JOB_ID } },
+        body: {
+            app_name: manifest.id,
+            app_source: 'WebDAV',
+            app_domain: manifest.domain,
+            site_id: siteId,
+            app_path: appPath,
+        },
+    });
+    if (error?.fault?.type === 'UnknownPropertyException' &&
+        error.fault.arguments?.document === 'job_execution_request') {
+        // Retry with parameters format (internal/support users)
+        logger.warn('Retrying with parameters format for internal users');
+        const { data: retryData, error: retryError } = await instance.ocapi.POST('/jobs/{job_id}/executions', {
+            params: { path: { job_id: INSTALL_JOB_ID } },
+            body: {
+                parameters: [
+                    { name: 'AppName', value: manifest.id },
+                    { name: 'AppSource', value: 'WebDAV' },
+                    { name: 'AppDomain', value: manifest.domain },
+                    { name: 'SiteId', value: siteId },
+                    { name: 'AppPath', value: appPath },
+                ],
+            },
+        });
+        if (retryError || !retryData) {
+            throw new Error(retryError?.fault?.message ?? 'Failed to start install job');
+        }
+        execution = retryData;
+    }
+    else if (error || !data) {
+        throw new Error(error?.fault?.message ?? 'Failed to start install job');
+    }
+    else {
+        execution = data;
+    }
+    logger.debug({ jobId: INSTALL_JOB_ID, executionId: execution.id }, `Install job started: ${execution.id}`);
+    // Wait for job completion
+    let finalExecution;
+    try {
+        finalExecution = await waitForJob(instance, INSTALL_JOB_ID, execution.id, waitOptions);
+    }
+    catch (err) {
+        if (err instanceof JobExecutionError) {
+            try {
+                const log = await getJobLog(instance, err.execution);
+                logger.error({ jobId: INSTALL_JOB_ID, log }, `Job log:\n${log}`);
+            }
+            catch {
+                logger.error({ jobId: INSTALL_JOB_ID }, 'Could not retrieve job log');
+            }
+        }
+        throw err;
+    }
+    // Clean up archive unless keeping
+    if (!keepArchive) {
+        await instance.webdav.delete(webdavUploadPath);
+        logger.debug({ path: webdavUploadPath }, `Archive deleted: ${webdavUploadPath}`);
+    }
+    return {
+        execution: finalExecution,
+        appName: manifest.id,
+        appVersion: manifest.version,
+        archiveFilename,
+        archiveKept: keepArchive,
+    };
+}
+export function readManifest(capDir) {
+    const manifestPath = path.join(capDir, 'commerce-app.json');
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error(`commerce-app.json not found in: ${capDir}`);
+    }
+    try {
+        return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    }
+    catch {
+        throw new Error(`Failed to parse commerce-app.json in: ${capDir}`);
+    }
+}
+async function readManifestFromZip(zipPath) {
+    const data = await fs.promises.readFile(zipPath);
+    const zip = await JSZip.loadAsync(data);
+    // Find commerce-app.json at root or one level deep
+    for (const [filePath, entry] of Object.entries(zip.files)) {
+        if (!entry.dir && (filePath === 'commerce-app.json' || filePath.match(/^[^/]+\/commerce-app\.json$/))) {
+            try {
+                const content = await entry.async('string');
+                return JSON.parse(content);
+            }
+            catch {
+                throw new Error('Failed to parse commerce-app.json from zip');
+            }
+        }
+    }
+    throw new Error('commerce-app.json not found in zip');
+}
+/** Prefix site ID with "Sites-" if not already present. */
+export function normalizeSiteId(siteId) {
+    return siteId.startsWith('Sites-') ? siteId : `Sites-${siteId}`;
+}
+async function createArchiveFromDirectory(dirPath, archiveDirName) {
+    const zip = new JSZip();
+    const rootFolder = zip.folder(archiveDirName);
+    await addDirectoryToZip(rootFolder, dirPath);
+    return zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE', compressionOptions: { level: 9 } });
+}
+//# sourceMappingURL=install.js.map

package/dist/esm/operations/cap/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../../../src/operations/cap/install.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;GAIG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAC,WAAW,EAAC,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAC,SAAS,EAAC,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAC,UAAU,EAAE,iBAAiB,EAAE,SAAS,EAA4C,MAAM,gBAAgB,CAAC;AACnH,OAAO,EAAC,iBAAiB,EAAC,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAA0B,MAAM,eAAe,CAAC;AAEvD,MAAM,cAAc,GAAG,2BAA2B,CAAC;AA8BnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAqB,EACrB,MAAc,EACd,OAAkC;IAElC,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,EAAC,MAAM,EAAE,SAAS,EAAE,WAAW,GAAG,KAAK,EAAE,WAAW,EAAC,GAAG,OAAO,CAAC;IACtE,MAAM,MAAM,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IAE1C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,IAAI,cAAsB,CAAC;IAC3B,IAAI,eAAuB,CAAC;IAC5B,IAAI,QAA6B,CAAC;IAElC,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACvB,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QAChC,eAAe,GAAG,GAAG,QAAQ,CAAC,EAAE,KAAK,QAAQ,CAAC,OAAO,MAAM,CAAC;QAC5D,MAAM,CAAC,KAAK,CAAC,EAAC,IAAI,EAAE,MAAM,EAAC,EAAE,4BAA4B,MAAM,EAAE,CAAC,CAAC;QACnE,cAAc,GAAG,MAAM,0BAA0B,CAAC,MAAM,EAAE,GAAG,QAAQ,CAAC,EAAE,KAAK,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACnG,CAAC;SAAM,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACpD,QAAQ,GAAG,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC7C,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACxC,cAAc,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtD,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,4CAA4C,MAAM,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,SAAS,GAAG,qBAAqB,CAAC;IACxC,MAAM,gBAAgB,GAAG,GAAG,SAAS,IAAI,eAAe,EAAE,CAAC;IAC3D,MAAM,OAAO,GAAG,gBAAgB,gBAAgB,EAAE,CAAC;IAEnD,MAAM,CAAC,KAAK,CAAC,EAAC,IAAI,EAAE,gBAAgB,EAAC,EAAE,oBAAoB,gBAAgB,EAAE,CAAC,CAAC;IAC/E,MAAM,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACvC,MAAM,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,gBAAgB,EAAE,cAAc,EAAE,iBAAiB,CAAC,CAAC;IAC/E,MAAM,CAAC,KAAK,CAAC,EAAC,IAAI,EAAE,gBAAgB,EAAC,EAAE,iBAAiB,gBAAgB,EAAE,CAAC,CAAC;IAE5E,0BAA0B;IAC1B,MAAM,CAAC,KAAK,CAAC,EAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAC,EAAE,aAAa,cAAc,MAAM,CAAC,CAAC;IAEvG,IAAI,SAAuB,CAAC;IAE5B,uDAAuD;IACvD,MAAM,EAAC,IAAI,EAAE,KAAK,EAAC,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,2BAA2B,EAAE;QAC3E,MAAM,EAAE,EAAC,IAAI,EAAE,EAAC,MAAM,EAAE,cAAc,EAAC,EAAC;QACxC,IAAI,EAAE;YACJ,QAAQ,EAAE,QAAQ,CAAC,EAAE;YACrB,UAAU,EAAE,QAAQ;YACpB,UAAU,EAAE,QAAQ,CAAC,MAAM;YAC3B,OAAO,EAAE,MAAM;YACf,QAAQ,EAAE,OAAO;SACG;KACvB,CAAC,CAAC;IAEH,IACE,KAAK,EAAE,KAAK,EAAE,IAAI,KAAK,0BAA0B;QAChD,KAAK,CAAC,KAAK,CAAC,SAAqC,EAAE,QAAQ,KAAK,uBAAuB,EACxF,CAAC;QACD,wDAAwD;QACxD,MAAM,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;QAElE,MAAM,EAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAC,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,2BAA2B,EAAE;YAClG,MAAM,EAAE,EAAC,IAAI,EAAE,EAAC,MAAM,EAAE,cAAc,EAAC,EAAC;YACxC,IAAI,EAAE;gBACJ,UAAU,EAAE;oBACV,EAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,EAAC;oBACrC,EAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAC;oBACpC,EAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAC;oBAC3C,EAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAC;oBAC/B,EAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAC;iBAClC;aACmB;SACvB,CAAC,CAAC;QAEH,IAAI,UAAU,IAAI,CAAC,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,IAAI,6BAA6B,CAAC,CAAC;QAC/E,CAAC;QAED,SAAS,GAAG,SAAS,CAAC;IACxB,CAAC;SAAM,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,IAAI,6BAA6B,CAAC,CAAC;IAC1E,CAAC;SAAM,CAAC;QACN,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,EAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,EAAC,EAAE,wBAAwB,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC;IAEzG,0BAA0B;IAC1B,IAAI,cAA4B,CAAC;IACjC,IAAI,CAAC;QACH,cAAc,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,CAAC,EAAG,EAAE,WAAW,CAAC,CAAC;IAC1F,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,iBAAiB,EAAE,CAAC;YACrC,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;gBACrD,MAAM,CAAC,KAAK,CAAC,EAAC,KAAK,EAAE,cAAc,EAAE,GAAG,EAAC,EAAE,aAAa,GAAG,EAAE,CAAC,CAAC;YACjE,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,CAAC,KAAK,CAAC,EAAC,KAAK,EAAE,cAAc,EAAC,EAAE,4BAA4B,CAAC,CAAC;YACtE,CAAC;QACH,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,kCAAkC;IAClC,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;QAC/C,MAAM,CAAC,KAAK,CAAC,EAAC,IAAI,EAAE,gBAAgB,EAAC,EAAE,oBAAoB,gBAAgB,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,OAAO;QACL,SAAS,EAAE,cAAc;QACzB,OAAO,EAAE,QAAQ,CAAC,EAAE;QACpB,UAAU,EAAE,QAAQ,CAAC,OAAO;QAC5B,eAAe;QACf,WAAW,EAAE,WAAW;KACzB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC5D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,mCAAmC,MAAM,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAwB,CAAC;IACnF,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,yCAAyC,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC;AACH,CAAC;AAED,KAAK,UAAU,mBAAmB,CAAC,OAAe;IAChD,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAExC,mDAAmD;IACnD,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1D,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,QAAQ,KAAK,mBAAmB,IAAI,QAAQ,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC,EAAE,CAAC;YACtG,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAC5C,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAwB,CAAC;YACpD,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;AACxD,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC;AAClE,CAAC;AAED,KAAK,UAAU,0BAA0B,CAAC,OAAe,EAAE,cAAsB;IAC/E,MAAM,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;IACxB,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,cAAc,CAAE,CAAC;IAC/C,MAAM,iBAAiB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC7C,OAAO,GAAG,CAAC,aAAa,CAAC,EAAC,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,EAAC,KAAK,EAAE,CAAC,EAAC,EAAC,CAAC,CAAC;AACzG,CAAC"}

package/dist/esm/operations/cap/list.d.ts

@@ -0,0 +1,92 @@
+import { B2CInstance } from '../../instance/index.js';
+import type { JobExecution, WaitForJobOptions } from '../jobs/run.js';
+import type { CommerceAppManifest } from './validate.js';
+/**
+ * A commerce feature state parsed from the commerce-feature-states.xml export.
+ */
+export interface CommerceFeatureState {
+    siteId: string;
+    featureName: string;
+    featureType: string;
+    featureSource: string;
+    featureDomain: string;
+    installStatus: string;
+    configStatus: string;
+    featureVersionId: string;
+    installedAt: string;
+    configTasks?: unknown[];
+    installationMetadata?: unknown;
+}
+/**
+ * A locally discovered Commerce App Package.
+ */
+export interface LocalCommerceApp {
+    /** Absolute path to the directory containing commerce-app.json. */
+    path: string;
+    /** Parsed manifest from commerce-app.json. */
+    manifest: CommerceAppManifest;
+}
+/**
+ * Options for listing installed apps on an instance.
+ */
+export interface ListInstalledAppsOptions {
+    /** Specific site IDs to query. If omitted, discovers all sites via OCAPI. */
+    sites?: string[];
+    /** Wait options for the export job. */
+    waitOptions?: WaitForJobOptions;
+}
+/**
+ * Result of listing installed apps on an instance.
+ */
+export interface ListInstalledAppsResult {
+    /** Parsed commerce feature states from all queried sites. */
+    features: CommerceFeatureState[];
+    /** Job execution details. */
+    execution: JobExecution;
+}
+/**
+ * Discovers local Commerce App Packages by searching for commerce-app.json files.
+ *
+ * Walks the directory tree starting from `searchPath`, finds directories
+ * containing a `commerce-app.json` file, and reads each manifest.
+ *
+ * @param searchPath - Root directory to search
+ * @returns Array of discovered local apps with their paths and manifests
+ *
+ * @example
+ * ```typescript
+ * const apps = await discoverLocalApps('./my-workspace');
+ * for (const app of apps) {
+ *   console.log(`${app.manifest.id}@${app.manifest.version} at ${app.path}`);
+ * }
+ * ```
+ */
+export declare function discoverLocalApps(searchPath: string): Promise<LocalCommerceApp[]>;
+/**
+ * Lists installed Commerce Apps on a B2C instance by exporting commerce feature states.
+ *
+ * Attempts to export the `commerce_feature_states` data unit for each site.
+ * If the export fails (e.g. because the data unit is not yet supported on the server),
+ * falls back to a bundled stub fixture.
+ *
+ * @param instance - B2C instance to query
+ * @param options - Options including optional site filter and wait options
+ * @returns List of commerce feature states across all queried sites
+ *
+ * @example
+ * ```typescript
+ * const result = await listInstalledApps(instance);
+ * for (const state of result.features) {
+ *   console.log(`${state.featureName} (${state.installStatus}) on ${state.siteId}`);
+ * }
+ * ```
+ */
+export declare function listInstalledApps(instance: B2CInstance, options?: ListInstalledAppsOptions): Promise<ListInstalledAppsResult>;
+/**
+ * Parses a commerce-feature-states.xml string into CommerceFeatureState objects.
+ *
+ * @param xml - XML string to parse
+ * @param siteId - Site ID to associate with parsed states (used as fallback if not in XML attributes)
+ * @returns Array of parsed commerce feature states
+ */
+export declare function parseCommerceFeatureStatesXml(xml: string, siteId: string): Promise<CommerceFeatureState[]>;

package/dist/esm/operations/cap/list.js

@@ -0,0 +1,231 @@
+/*
+ * 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
+ */
+/**
+ * Commerce App listing operations.
+ *
+ * Provides functions for discovering local Commerce App Packages and listing
+ * installed apps on a B2C Commerce instance via site archive export.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import JSZip from 'jszip';
+import * as xml2js from 'xml2js';
+import { B2CInstance } from '../../instance/index.js';
+import { getLogger } from '../../logging/logger.js';
+import { siteArchiveExportToBuffer } from '../jobs/site-archive.js';
+import { readManifest } from './install.js';
+/**
+ * Discovers local Commerce App Packages by searching for commerce-app.json files.
+ *
+ * Walks the directory tree starting from `searchPath`, finds directories
+ * containing a `commerce-app.json` file, and reads each manifest.
+ *
+ * @param searchPath - Root directory to search
+ * @returns Array of discovered local apps with their paths and manifests
+ *
+ * @example
+ * ```typescript
+ * const apps = await discoverLocalApps('./my-workspace');
+ * for (const app of apps) {
+ *   console.log(`${app.manifest.id}@${app.manifest.version} at ${app.path}`);
+ * }
+ * ```
+ */
+export async function discoverLocalApps(searchPath) {
+    const logger = getLogger();
+    const apps = [];
+    const resolvedPath = path.resolve(searchPath);
+    if (!fs.existsSync(resolvedPath)) {
+        return apps;
+    }
+    logger.debug({ searchPath: resolvedPath }, `Discovering local CAPs in: ${resolvedPath}`);
+    findCommerceApps(resolvedPath, apps, logger);
+    logger.debug({ count: apps.length }, `Found ${apps.length} local CAP(s)`);
+    return apps;
+}
+/**
+ * Recursively finds directories containing commerce-app.json.
+ * Stops descending into a directory once a commerce-app.json is found there.
+ */
+function findCommerceApps(dir, apps, logger) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const manifestPath = path.join(dir, 'commerce-app.json');
+    if (fs.existsSync(manifestPath)) {
+        try {
+            const manifest = readManifest(dir);
+            apps.push({ path: dir, manifest });
+        }
+        catch (err) {
+            logger.warn({ path: manifestPath, error: err }, `Skipping invalid commerce-app.json: ${manifestPath}`);
+        }
+        // Don't recurse into CAP directories
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+            findCommerceApps(path.join(dir, entry.name), apps, logger);
+        }
+    }
+}
+/**
+ * Lists installed Commerce Apps on a B2C instance by exporting commerce feature states.
+ *
+ * Attempts to export the `commerce_feature_states` data unit for each site.
+ * If the export fails (e.g. because the data unit is not yet supported on the server),
+ * falls back to a bundled stub fixture.
+ *
+ * @param instance - B2C instance to query
+ * @param options - Options including optional site filter and wait options
+ * @returns List of commerce feature states across all queried sites
+ *
+ * @example
+ * ```typescript
+ * const result = await listInstalledApps(instance);
+ * for (const state of result.features) {
+ *   console.log(`${state.featureName} (${state.installStatus}) on ${state.siteId}`);
+ * }
+ * ```
+ */
+export async function listInstalledApps(instance, options = {}) {
+    const logger = getLogger();
+    const { waitOptions } = options;
+    // Determine which sites to query
+    let siteIds;
+    if (options.sites && options.sites.length > 0) {
+        siteIds = options.sites;
+    }
+    else {
+        logger.debug('No sites specified, discovering all sites via OCAPI');
+        const { data, error } = await instance.ocapi.GET('/sites', {
+            params: { query: { select: '(**)' } },
+        });
+        if (error || !data) {
+            throw new Error(error?.fault?.message ?? 'Failed to list sites');
+        }
+        siteIds = (data.data ?? []).map((s) => s.id).filter((id) => !!id);
+        logger.debug({ siteIds }, `Discovered ${siteIds.length} site(s)`);
+    }
+    if (siteIds.length === 0) {
+        return { features: [], execution: undefined };
+    }
+    // Build export configuration for all sites with commerce_feature_states
+    const sitesConfig = {};
+    for (const siteId of siteIds) {
+        sitesConfig[siteId] = { commerce_feature_states: true };
+    }
+    logger.debug({ siteIds }, 'Exporting commerce_feature_states');
+    const exportResult = await siteArchiveExportToBuffer(instance, { sites: sitesConfig }, { waitOptions });
+    const states = await parseExportArchive(exportResult.data);
+    return { features: states, execution: exportResult.execution };
+}
+/**
+ * Parses a site archive export zip for commerce-feature-states.xml files.
+ */
+async function parseExportArchive(data) {
+    const logger = getLogger();
+    const zip = await JSZip.loadAsync(data);
+    const states = [];
+    const filePaths = Object.keys(zip.files).filter((p) => !zip.files[p].dir);
+    logger.debug({ filePaths }, `Export archive contains ${filePaths.length} file(s)`);
+    for (const [filePath, entry] of Object.entries(zip.files)) {
+        if (entry.dir)
+            continue;
+        const match = filePath.match(/sites\/([^/]+)\/commerce-feature-states\.xml$/);
+        if (match) {
+            const siteId = match[1];
+            const xml = await entry.async('string');
+            const parsed = await parseCommerceFeatureStatesXml(xml, siteId);
+            states.push(...parsed);
+        }
+    }
+    return states;
+}
+/**
+ * Parses a commerce-feature-states.xml string into CommerceFeatureState objects.
+ *
+ * @param xml - XML string to parse
+ * @param siteId - Site ID to associate with parsed states (used as fallback if not in XML attributes)
+ * @returns Array of parsed commerce feature states
+ */
+export async function parseCommerceFeatureStatesXml(xml, siteId) {
+    const parsed = await xml2js.parseStringPromise(xml, {
+        explicitArray: false,
+        tagNameProcessors: [(name) => name.replace(/^[^:]+:/, '')],
+    });
+    if (!parsed)
+        return [];
+    const root = parsed['commerce-feature-states'];
+    if (!root)
+        return [];
+    let entries = root['commerce-feature-state'];
+    if (!entries)
+        return [];
+    // Normalize to array (xml2js uses single object when there's only one element)
+    if (!Array.isArray(entries)) {
+        entries = [entries];
+    }
+    return entries.map((entry) => {
+        const attrs = (entry['$'] ?? {});
+        // Parse config-tasks as JSON if present
+        let configTasks;
+        if (typeof entry['config-tasks'] === 'string') {
+            try {
+                configTasks = JSON.parse(entry['config-tasks']);
+            }
+            catch {
+                // Leave as undefined if not valid JSON
+            }
+        }
+        // Parse installation-metadata as JSON if present
+        let installationMetadata;
+        if (typeof entry['installation-metadata'] === 'string') {
+            try {
+                const parsed = JSON.parse(entry['installation-metadata']);
+                if (typeof parsed.impexUninstallData === 'string') {
+                    try {
+                        parsed.impexUninstallData = JSON.parse(parsed.impexUninstallData);
+                    }
+                    catch {
+                        // leave as string
+                    }
+                }
+                installationMetadata = parsed;
+            }
+            catch {
+                // Leave as undefined if not valid JSON
+            }
+        }
+        return {
+            siteId: attrs['site-id'] || siteId,
+            featureName: attrs['feature-name'] || '',
+            featureType: getTextValue(entry['feature-type']),
+            featureSource: getTextValue(entry['feature-source']),
+            featureDomain: getTextValue(entry['feature-domain']),
+            installStatus: getTextValue(entry['install-status']),
+            configStatus: getTextValue(entry['config-status']),
+            featureVersionId: getTextValue(entry['feature-version-id']),
+            installedAt: getTextValue(entry['installed-at']),
+            configTasks,
+            installationMetadata,
+        };
+    });
+}
+/** Extract text value from xml2js parsed element (may be string or object with _). */
+function getTextValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value && typeof value === 'object' && '_' in value) {
+        return String(value['_']);
+    }
+    return '';
+}
+//# sourceMappingURL=list.js.map

package/dist/esm/operations/cap/list.js.map

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

package/dist/esm/operations/cap/package.d.ts

@@ -0,0 +1,39 @@
+import { type CommerceAppManifest } from './validate.js';
+/**
+ * Options for CAP packaging.
+ */
+export interface CommerceAppPackageOptions {
+    /**
+     * Output path for the zip file.
+     * - If a directory: zip is written to `{outputPath}/{id}-v{version}.zip`
+     * - If a .zip path: written to that exact location
+     * - Default: current working directory
+     */
+    outputPath?: string;
+}
+/**
+ * Result of CAP packaging.
+ */
+export interface CommerceAppPackageResult {
+    /** Absolute path to the produced zip file. */
+    outputPath: string;
+    /** Parsed manifest. */
+    manifest: CommerceAppManifest;
+}
+/**
+ * Packages a CAP directory into a distributable .zip file.
+ *
+ * The zip root directory is named `{id}-v{version}/` as required by the CAP spec.
+ * Reads commerce-app.json to determine the app name and version.
+ *
+ * @param sourceDir - Path to the CAP directory
+ * @param options - Packaging options
+ * @returns Result with the output zip path and manifest
+ *
+ * @example
+ * ```typescript
+ * const result = await commerceAppPackage('./commerce-avalara-tax-app-v0.2.5');
+ * console.log(`Packaged to: ${result.outputPath}`);
+ * ```
+ */
+export declare function commerceAppPackage(sourceDir: string, options?: CommerceAppPackageOptions): Promise<CommerceAppPackageResult>;