@salesforce/b2c-tooling-sdk 1.21.3 → 1.23.0

package/dist/esm/operations/ods/wait-for-clones.d.ts

@@ -0,0 +1,97 @@
+import type { OdsClient } from '../../clients/ods.js';
+import type { CloneState } from './wait-for-clone.js';
+/**
+ * Status of a single clone within a batch, as observed on one poll tick.
+ */
+export interface CloneBatchMemberStatus {
+    cloneId: string;
+    status: CloneState;
+    progressPercentage?: number;
+}
+/**
+ * Error thrown when a batch of sandbox clones does not all reach a terminal
+ * state (`COMPLETED` or `FAILED`) within the configured timeout while polling.
+ *
+ * @param sandboxId - ID of the source sandbox
+ * @param cloneIds - IDs of the clone operations being monitored
+ * @param timeoutSeconds - Timeout duration in seconds
+ * @param lastStatuses - Last observed status for each clone before the timeout occurred
+ */
+export declare class CloneBatchPollingTimeoutError extends Error {
+    readonly sandboxId: string;
+    readonly cloneIds: string[];
+    readonly timeoutSeconds: number;
+    readonly lastStatuses: CloneBatchMemberStatus[];
+    constructor(sandboxId: string, cloneIds: string[], timeoutSeconds: number, lastStatuses: CloneBatchMemberStatus[]);
+}
+/**
+ * Error thrown when an API request to fetch the status of a clone in a batch fails.
+ *
+ * @param sandboxId - ID of the source sandbox
+ * @param cloneId - ID of the clone operation whose status request failed
+ * @param message - Underlying error message from the API call
+ */
+export declare class CloneBatchPollingError extends Error {
+    readonly sandboxId: string;
+    readonly cloneId: string;
+    constructor(sandboxId: string, cloneId: string, message: string);
+}
+/**
+ * Error thrown when one or more clones in a batch enter the `FAILED` state.
+ *
+ * All clones in the batch reached a terminal state, but at least one of them failed.
+ *
+ * @param sandboxId - ID of the source sandbox
+ * @param failedCloneIds - IDs of the clones that reached the `FAILED` state
+ * @param statuses - Final status for every clone in the batch
+ */
+export declare class CloneBatchFailedError extends Error {
+    readonly sandboxId: string;
+    readonly failedCloneIds: string[];
+    readonly statuses: CloneBatchMemberStatus[];
+    constructor(sandboxId: string, failedCloneIds: string[], statuses: CloneBatchMemberStatus[]);
+}
+/**
+ * Information passed to the `onPoll` callback on each poll tick while waiting for a batch of clones.
+ */
+export interface WaitForClonesPollInfo {
+    sandboxId: string;
+    elapsedSeconds: number;
+    completed: number;
+    total: number;
+    clones: CloneBatchMemberStatus[];
+}
+/**
+ * Configuration options for {@link waitForClones} batch polling behavior.
+ */
+export interface WaitForClonesOptions {
+    sandboxId: string;
+    cloneIds: string[];
+    pollIntervalSeconds: number;
+    timeoutSeconds: number;
+    onPoll?: (info: WaitForClonesPollInfo) => void;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Waits for a batch of sandbox clones (created via 1 to many cloning) to all reach a
+ * terminal state by polling each clone's status against the ODS API.
+ *
+ * Polls at `pollIntervalSeconds` until every clone in `cloneIds` reaches
+ * `COMPLETED` or `FAILED`, or the configured timeout is exceeded. An initial
+ * poll delay equal to `pollIntervalSeconds` is applied before the first status
+ * check.
+ *
+ * @param client - ODS client for API calls
+ * @param options - Polling configuration options
+ * @param options.sandboxId - ID of the source sandbox
+ * @param options.cloneIds - IDs of the clone operations to monitor (e.g. `siblingCloneIds`)
+ * @param options.pollIntervalSeconds - Seconds between status checks
+ * @param options.timeoutSeconds - Maximum seconds to wait (`0` disables the timeout)
+ * @param options.onPoll - Optional callback invoked after each status poll with aggregate progress
+ * @param options.sleep - Optional custom sleep function (primarily for testing)
+ * @returns Promise that resolves with the final status of every clone once all reach `COMPLETED`
+ * @throws {CloneBatchPollingTimeoutError} If the timeout is exceeded before all clones complete
+ * @throws {CloneBatchPollingError} If an API request fails
+ * @throws {CloneBatchFailedError} If one or more clones enter the `FAILED` state
+ */
+export declare function waitForClones(client: OdsClient, options: WaitForClonesOptions): Promise<CloneBatchMemberStatus[]>;

package/dist/esm/operations/ods/wait-for-clones.js

@@ -0,0 +1,145 @@
+/*
+ * 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 { getLogger } from '../../logging/logger.js';
+/**
+ * Error thrown when a batch of sandbox clones does not all reach a terminal
+ * state (`COMPLETED` or `FAILED`) within the configured timeout while polling.
+ *
+ * @param sandboxId - ID of the source sandbox
+ * @param cloneIds - IDs of the clone operations being monitored
+ * @param timeoutSeconds - Timeout duration in seconds
+ * @param lastStatuses - Last observed status for each clone before the timeout occurred
+ */
+export class CloneBatchPollingTimeoutError extends Error {
+    sandboxId;
+    cloneIds;
+    timeoutSeconds;
+    lastStatuses;
+    constructor(sandboxId, cloneIds, timeoutSeconds, lastStatuses) {
+        const pending = lastStatuses.filter((s) => s.status !== 'COMPLETED' && s.status !== 'FAILED');
+        super(`Timeout waiting for ${cloneIds.length} clone(s) of sandbox ${sandboxId} after ${timeoutSeconds} seconds ` +
+            `(${pending.length} of ${cloneIds.length} still pending)`);
+        this.sandboxId = sandboxId;
+        this.cloneIds = cloneIds;
+        this.timeoutSeconds = timeoutSeconds;
+        this.lastStatuses = lastStatuses;
+        this.name = 'CloneBatchPollingTimeoutError';
+    }
+}
+/**
+ * Error thrown when an API request to fetch the status of a clone in a batch fails.
+ *
+ * @param sandboxId - ID of the source sandbox
+ * @param cloneId - ID of the clone operation whose status request failed
+ * @param message - Underlying error message from the API call
+ */
+export class CloneBatchPollingError extends Error {
+    sandboxId;
+    cloneId;
+    constructor(sandboxId, cloneId, message) {
+        super(`Failed to fetch clone status for ${cloneId} of sandbox ${sandboxId}: ${message}`);
+        this.sandboxId = sandboxId;
+        this.cloneId = cloneId;
+        this.name = 'CloneBatchPollingError';
+    }
+}
+/**
+ * Error thrown when one or more clones in a batch enter the `FAILED` state.
+ *
+ * All clones in the batch reached a terminal state, but at least one of them failed.
+ *
+ * @param sandboxId - ID of the source sandbox
+ * @param failedCloneIds - IDs of the clones that reached the `FAILED` state
+ * @param statuses - Final status for every clone in the batch
+ */
+export class CloneBatchFailedError extends Error {
+    sandboxId;
+    failedCloneIds;
+    statuses;
+    constructor(sandboxId, failedCloneIds, statuses) {
+        super(`${failedCloneIds.length} of ${statuses.length} clone(s) failed for sandbox ${sandboxId}`);
+        this.sandboxId = sandboxId;
+        this.failedCloneIds = failedCloneIds;
+        this.statuses = statuses;
+        this.name = 'CloneBatchFailedError';
+    }
+}
+async function defaultSleep(ms) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function isTerminal(status) {
+    return status === 'COMPLETED' || status === 'FAILED';
+}
+/**
+ * Waits for a batch of sandbox clones (created via 1 to many cloning) to all reach a
+ * terminal state by polling each clone's status against the ODS API.
+ *
+ * Polls at `pollIntervalSeconds` until every clone in `cloneIds` reaches
+ * `COMPLETED` or `FAILED`, or the configured timeout is exceeded. An initial
+ * poll delay equal to `pollIntervalSeconds` is applied before the first status
+ * check.
+ *
+ * @param client - ODS client for API calls
+ * @param options - Polling configuration options
+ * @param options.sandboxId - ID of the source sandbox
+ * @param options.cloneIds - IDs of the clone operations to monitor (e.g. `siblingCloneIds`)
+ * @param options.pollIntervalSeconds - Seconds between status checks
+ * @param options.timeoutSeconds - Maximum seconds to wait (`0` disables the timeout)
+ * @param options.onPoll - Optional callback invoked after each status poll with aggregate progress
+ * @param options.sleep - Optional custom sleep function (primarily for testing)
+ * @returns Promise that resolves with the final status of every clone once all reach `COMPLETED`
+ * @throws {CloneBatchPollingTimeoutError} If the timeout is exceeded before all clones complete
+ * @throws {CloneBatchPollingError} If an API request fails
+ * @throws {CloneBatchFailedError} If one or more clones enter the `FAILED` state
+ */
+export async function waitForClones(client, options) {
+    const logger = getLogger();
+    const { sandboxId, cloneIds, pollIntervalSeconds, timeoutSeconds } = options;
+    const sleepFn = options.sleep ?? defaultSleep;
+    const startTime = Date.now();
+    const pollIntervalMs = pollIntervalSeconds * 1000;
+    const timeoutMs = timeoutSeconds * 1000;
+    await sleepFn(pollIntervalMs);
+    const statusByCloneId = new Map(cloneIds.map((cloneId) => [cloneId, { cloneId, status: 'PENDING' }]));
+    while (true) {
+        const elapsedSeconds = Math.round((Date.now() - startTime) / 1000);
+        if (timeoutSeconds > 0 && Date.now() - startTime > timeoutMs) {
+            throw new CloneBatchPollingTimeoutError(sandboxId, cloneIds, timeoutSeconds, [...statusByCloneId.values()]);
+        }
+        const pendingCloneIds = cloneIds.filter((cloneId) => !isTerminal(statusByCloneId.get(cloneId).status));
+        await Promise.all(pendingCloneIds.map(async (cloneId) => {
+            const result = await client.GET('/sandboxes/{sandboxId}/clones/{cloneId}', {
+                params: {
+                    path: { sandboxId, cloneId },
+                },
+            });
+            if (!result.data?.data) {
+                throw new CloneBatchPollingError(sandboxId, cloneId, result.response?.statusText || 'Unknown error');
+            }
+            const clone = result.data.data;
+            statusByCloneId.set(cloneId, {
+                cloneId,
+                status: clone.status || 'PENDING',
+                progressPercentage: clone.progressPercentage,
+            });
+        }));
+        const lastStatuses = cloneIds.map((cloneId) => statusByCloneId.get(cloneId));
+        const completed = lastStatuses.filter((s) => isTerminal(s.status)).length;
+        logger.trace({ sandboxId, cloneIds, elapsedSeconds, statuses: lastStatuses }, '[ODS] Clone batch poll');
+        options.onPoll?.({ sandboxId, elapsedSeconds, completed, total: cloneIds.length, clones: lastStatuses });
+        if (completed === cloneIds.length) {
+            const failedCloneIds = lastStatuses.filter((s) => s.status === 'FAILED').map((s) => s.cloneId);
+            if (failedCloneIds.length > 0) {
+                throw new CloneBatchFailedError(sandboxId, failedCloneIds, lastStatuses);
+            }
+            return lastStatuses;
+        }
+        await sleepFn(pollIntervalMs);
+    }
+}
+//# sourceMappingURL=wait-for-clones.js.map

package/dist/esm/operations/ods/wait-for-clones.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/b2c-tooling-sdk",
   "description": "Core tooling library for Salesforce B2C Commerce CLI",
-  "version": "1.21.3",
+  "version": "1.23.0",
   "author": "Charles Lavery",
   "license": "Apache-2.0",
   "repository": "SalesforceCommerceCloud/b2c-developer-tooling",
@@ -266,6 +266,7 @@
     "generate:guides-index": "tsx scripts/generate-guides-index.ts",
     "check:guides-links": "tsx scripts/check-guides-links.ts",
     "generate:tooling-index": "tsx scripts/generate-tooling-index.ts",
+    "check:tooling-index": "tsx scripts/generate-tooling-index.ts --check",
     "generate:help-corpus": "tsx scripts/generate-help-corpus.ts",
     "enrich:docs": "tsx scripts/enrich-docs.ts"
   }

package/specs/ods-api-v1.json

@@ -1251,6 +1251,15 @@
                                 "Completed"
                             ]
                         }
+                    },
+                    {
+                        "name": "batchId",
+                        "in": "query",
+                        "description": "Filter clones by their 1 to many batch identifier. When provided, returns only clones belonging to that batch. Optional.",
+                        "required": false,
+                        "schema": {
+                            "type": "string"
+                        }
                     }
                 ],
                 "responses": {
@@ -2916,6 +2925,19 @@
                     "databaseTransferSize": {
                         "type": "integer",
                         "format": "int64"
+                    },
+                    "batchId": {
+                        "type": "string",
+                        "nullable": true,
+                        "description": "Shared batch identifier for clones created together via 1 to many cloning. Absent for single (1:1) clones."
+                    },
+                    "siblingCloneIds": {
+                        "type": "array",
+                        "nullable": true,
+                        "items": {
+                            "type": "string"
+                        },
+                        "description": "cloneIds of all clones in the same 1 to many batch, in target-index order (element i = cloneId of target index i). Includes this clone. Absent for single (1:1) clones."
                     }
                 }
             },
@@ -2925,6 +2947,19 @@
                     "cloneId": {
                         "type": "string",
                         "example": "zyom-002-017-180620251331"
+                    },
+                    "batchId": {
+                        "type": "string",
+                        "nullable": true,
+                        "description": "Shared batch identifier when this create fanned out to multiple clones (1 to many). Absent for single (1:1) clones."
+                    },
+                    "siblingCloneIds": {
+                        "type": "array",
+                        "nullable": true,
+                        "items": {
+                            "type": "string"
+                        },
+                        "description": "cloneIds of all clones created by this 1 to many request. Absent for single (1:1) clones."
                     }
                 }
             },
@@ -2934,6 +2969,14 @@
                     "targetProfile": {
                         "$ref": "#/components/schemas/SandboxResourceProfile"
                     },
+                    "targetCount": {
+                        "type": "integer",
+                        "format": "int32",
+                        "minimum": 1,
+                        "maximum": 5,
+                        "default": 1,
+                        "description": "Number of sandbox clones to create from this source (1 to many cloning). Valid values are 1 to 5. Defaults to 1 (a single 1:1 clone). When greater than 1, the clones fan out as a batch sharing a batchId."
+                    },
                     "emails": {
                         "type": "array",
                         "items": {

package/dist/esm/auth/stateful-store.d.ts

@@ -1,49 +0,0 @@
-/**
- * Initialize the stateful store with the oclif data directory.
- * Call this from BaseCommand.init() with this.config.dataDir so the session
- * file is stored alongside other CLI data (e.g. ~/Library/Application Support/@salesforce/b2c-cli).
- */
-export declare function initializeStatefulStore(dataDir: string): void;
-/**
- * Stored session persisted by stateful auth commands.
- */
-export interface StatefulSession {
-    clientId: string;
-    accessToken: string;
-    refreshToken?: string | null;
-    /** Base64-encoded "clientId:clientSecret" for token renewal. */
-    renewBase?: string | null;
-    user?: string | null;
-}
-/**
- * Reads the current stateful session from the JSON file.
- * Returns null if no session file exists or the file is invalid.
- */
-export declare function getStoredSession(): StatefulSession | null;
-/**
- * Writes a session to the JSON file, creating the directory if needed.
- */
-export declare function setStoredSession(session: StatefulSession): void;
-/**
- * Clears the stored session by removing the session file.
- */
-export declare function clearStoredSession(): void;
-/**
- * Checks whether the stored access token is present and valid: not expired
- * (with a small buffer), optionally satisfies required scopes, and optionally
- * matches the expected client ID.
- * Does not perform network calls.
- *
- * @param session - Session from getStoredSession()
- * @param requiredScopes - If provided, token must include all of these scopes
- * @param expiryBufferSec - Seconds before exp to treat token as expired (default 60)
- * @param requiredClientId - If provided, session clientId must match
- * @returns true if token is present and valid for use
- */
-export declare function isStatefulTokenValid(session: StatefulSession, requiredScopes?: string[], expiryBufferSec?: number, requiredClientId?: string): boolean;
-/**
- * Resets the store path (for tests). After calling this, the next operation
- * will use the default data directory unless initializeStatefulStore() is called again.
- * @internal
- */
-export declare function resetStatefulStoreForTesting(): void;

package/dist/esm/auth/stateful-store.js

@@ -1,166 +0,0 @@
-/*
- * 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
- */
-/**
- * Stateful auth store backed by a JSON file in the oclif data directory
- * (e.g. ~/Library/Application Support/@salesforce/b2c-cli/auth-session.json on macOS).
- *
- * Initialize via initializeStatefulStore(dataDir) from BaseCommand.init() so the
- * session file is co-located with other CLI data. Falls back to an OS-appropriate
- * default path when used standalone (outside a CLI command).
- *
- * The stateful auth workflow (b2c auth client / b2c auth login / b2c auth logout)
- * is compatible with sfcc-ci command patterns. Session data is stored internally
- * in the CLI data directory, not in the sfcc-ci config store.
- *
- * @module auth/stateful-store
- */
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { homedir, platform } from 'node:os';
-import { DEFAULT_EXPIRY_BUFFER_SEC, decodeJwtTokenInfo } from './jwt-utils.js';
-import { getLogger } from '../logging/logger.js';
-const STATEFUL_AUTH_SESSION_STORE = 'auth-session.json';
-let storePath = null;
-/**
- * Computes the oclif-compatible data directory for @salesforce/b2c-cli.
- * Used as a fallback when initializeStatefulStore() has not been called.
- */
-function getDefaultDataDir() {
-    const home = homedir();
-    const name = '@salesforce/b2c-cli';
-    switch (platform()) {
-        case 'darwin':
-            return join(home, 'Library', 'Application Support', name);
-        case 'win32':
-            return join(process.env.LOCALAPPDATA ?? join(home, 'AppData', 'Local'), name);
-        default:
-            return join(process.env.XDG_DATA_HOME ?? join(home, '.local', 'share'), name);
-    }
-}
-function getSessionFilePath() {
-    return join(storePath ?? getDefaultDataDir(), STATEFUL_AUTH_SESSION_STORE);
-}
-/**
- * Initialize the stateful store with the oclif data directory.
- * Call this from BaseCommand.init() with this.config.dataDir so the session
- * file is stored alongside other CLI data (e.g. ~/Library/Application Support/@salesforce/b2c-cli).
- */
-export function initializeStatefulStore(dataDir) {
-    storePath = dataDir;
-}
-/**
- * Reads the current stateful session from the JSON file.
- * Returns null if no session file exists or the file is invalid.
- */
-export function getStoredSession() {
-    const filePath = getSessionFilePath();
-    if (!existsSync(filePath)) {
-        return null;
-    }
-    try {
-        const data = JSON.parse(readFileSync(filePath, 'utf8'));
-        if (!data.clientId || !data.accessToken) {
-            return null;
-        }
-        return {
-            clientId: data.clientId,
-            accessToken: data.accessToken,
-            refreshToken: data.refreshToken ?? null,
-            renewBase: data.renewBase ?? null,
-            user: data.user ?? null,
-        };
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Writes a session to the JSON file, creating the directory if needed.
- */
-export function setStoredSession(session) {
-    const filePath = getSessionFilePath();
-    const dir = join(filePath, '..');
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    const data = {
-        clientId: session.clientId,
-        accessToken: session.accessToken,
-        refreshToken: session.refreshToken ?? null,
-        renewBase: session.renewBase ?? null,
-        user: session.user ?? null,
-    };
-    // Atomic write: write to temp file then rename so a concurrent reader (or a
-    // crashed writer) never observes a partially written JSON document.
-    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-    writeFileSync(tmpPath, JSON.stringify(data, null, 2), 'utf8');
-    renameSync(tmpPath, filePath);
-}
-/**
- * Clears the stored session by removing the session file.
- */
-export function clearStoredSession() {
-    const filePath = getSessionFilePath();
-    if (existsSync(filePath)) {
-        try {
-            unlinkSync(filePath);
-        }
-        catch (err) {
-            getLogger().debug({ err, filePath }, '[StatefulAuth] Failed to remove session file');
-        }
-    }
-}
-/**
- * Checks whether the stored access token is present and valid: not expired
- * (with a small buffer), optionally satisfies required scopes, and optionally
- * matches the expected client ID.
- * Does not perform network calls.
- *
- * @param session - Session from getStoredSession()
- * @param requiredScopes - If provided, token must include all of these scopes
- * @param expiryBufferSec - Seconds before exp to treat token as expired (default 60)
- * @param requiredClientId - If provided, session clientId must match
- * @returns true if token is present and valid for use
- */
-export function isStatefulTokenValid(session, requiredScopes = [], expiryBufferSec = DEFAULT_EXPIRY_BUFFER_SEC, requiredClientId) {
-    const logger = getLogger();
-    if (requiredClientId && session.clientId !== requiredClientId) {
-        logger.debug({ storedClientId: session.clientId, requiredClientId }, '[StatefulAuth] Token client ID mismatch');
-        return false;
-    }
-    let info;
-    try {
-        info = decodeJwtTokenInfo(session.accessToken);
-    }
-    catch (error) {
-        logger.debug({ err: error }, '[StatefulAuth] Token invalid (e.g. not a JWT)');
-        return false;
-    }
-    if (info.expires.getTime() === 0) {
-        logger.debug('[StatefulAuth] Token has no exp claim; treating as invalid');
-        return false;
-    }
-    const nowSec = Math.floor(Date.now() / 1000);
-    const expSec = Math.floor(info.expires.getTime() / 1000);
-    if (nowSec >= expSec - expiryBufferSec) {
-        logger.debug('[StatefulAuth] Token missing or expired');
-        return false;
-    }
-    if (requiredScopes.length > 0 && !requiredScopes.every((s) => info.scopes.includes(s))) {
-        logger.debug({ requiredScopes, tokenScopes: info.scopes }, '[StatefulAuth] Token missing required scopes');
-        return false;
-    }
-    return true;
-}
-/**
- * Resets the store path (for tests). After calling this, the next operation
- * will use the default data directory unless initializeStatefulStore() is called again.
- * @internal
- */
-export function resetStatefulStoreForTesting() {
-    storePath = null;
-}
-//# sourceMappingURL=stateful-store.js.map

package/dist/esm/auth/stateful-store.js.map

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