@salesforce/b2c-tooling-sdk 1.24.2 → 2.0.0

package/dist/esm/operations/jobs/discover.js

@@ -16,28 +16,27 @@
  */
 import { B2CInstance } from '../../instance/index.js';
 import { getLogger } from '../../logging/logger.js';
-/** A discoverable category and the OCAPI path used to list it. */
-const DISCOVERABLE = [
-    { key: 'sites', path: '/sites', label: 'sites' },
-    { key: 'catalogs', path: '/catalogs', label: 'catalogs' },
-    { key: 'inventoryLists', path: '/inventory_lists', label: 'inventory lists' },
-];
+import { assertOcapiCompatibilityAllowed } from '../../clients/scapi-backend-utils.js';
+import { createCatalogsBackend } from '../catalogs/index.js';
+import { createSitesBackend } from '../sites/index.js';
 /** Page size for paginated list endpoints (OCAPI default is 25). */
 const PAGE_COUNT = 200;
 /**
- * Lists one paginated OCAPI collection, following `start`/`count` until all
+ * Lists inventory lists through the remaining paginated OCAPI collection,
+ * following `start`/`count` until all
  * documents are read. Returns the `id` of each document.
  */
-async function listIds(instance, path) {
+async function listInventoryListIds(instance) {
+    assertOcapiCompatibilityAllowed(instance.apiBackend, 'inventory-list enumeration');
     const ids = [];
     let start = 0;
     // OCAPI collections page via start/count; `total` reports the full size.
     for (;;) {
-        const { data, error } = await instance.ocapi.GET(path, {
+        const { data, error } = await instance.ocapi.GET('/inventory_lists', {
             params: { query: { start, count: PAGE_COUNT } },
         });
         if (error || !data) {
-            throw new Error(error?.fault?.message ?? `Failed to list ${path}`);
+            throw new Error(error?.fault?.message ?? 'Failed to list inventory lists');
         }
         for (const item of data.data ?? []) {
             if (item.id) {
@@ -56,7 +55,7 @@ async function listIds(instance, path) {
  * Discovers the data units that can be exported from an instance.
  *
  * Each category is read independently: a failure in one (e.g. the OCAPI client
- * lacks read permission for catalogs) records a warning and leaves that list
+ * lacks read permission for a category) records a warning and leaves that list
  * empty rather than failing the whole discovery, so the caller can still offer
  * the categories that succeeded.
  *
@@ -72,16 +71,47 @@ async function listIds(instance, path) {
 export async function discoverExportableUnits(instance) {
     const logger = getLogger();
     const result = { sites: [], catalogs: [], inventoryLists: [], warnings: [] };
-    await Promise.all(DISCOVERABLE.map(async ({ key, path, label }) => {
-        try {
-            result[key] = (await listIds(instance, path)).sort((a, b) => a.localeCompare(b));
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            logger.debug({ path, err: message }, `Failed to discover ${label}`);
-            result.warnings.push(`Could not list ${label}: ${message}`);
-        }
-    }));
+    await Promise.all([
+        // Sites: SCAPI (site/sites) with OCAPI fallback.
+        (async () => {
+            try {
+                const sites = await createSitesBackend({ instance }).listSites();
+                result.sites = sites
+                    .map((s) => s.id)
+                    .filter((id) => !!id)
+                    .sort((a, b) => a.localeCompare(b));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.debug({ err: message }, 'Failed to discover sites');
+                result.warnings.push(`Could not list sites: ${message}`);
+            }
+        })(),
+        // Catalogs: SCAPI product/catalogs with OCAPI fallback.
+        (async () => {
+            try {
+                const catalogs = await createCatalogsBackend({ instance }).listCatalogs();
+                result.catalogs = catalogs.map(({ id }) => id).sort((a, b) => a.localeCompare(b));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.debug({ err: message }, 'Failed to discover catalogs');
+                result.warnings.push(`Could not list catalogs: ${message}`);
+            }
+        })(),
+        // The live SCAPI inventory APIs expose list detail/records but no
+        // organization-level inventory-list enumeration endpoint yet.
+        (async () => {
+            try {
+                result.inventoryLists = (await listInventoryListIds(instance)).sort((a, b) => a.localeCompare(b));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.debug({ err: message }, 'Failed to discover inventory lists');
+                result.warnings.push(`Could not list inventory lists: ${message}`);
+            }
+        })(),
+    ]);
     return result;
 }
 //# sourceMappingURL=discover.js.map

package/dist/esm/operations/jobs/discover.js.map

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

package/dist/esm/operations/jobs/index.d.ts

@@ -1,69 +1,26 @@
 /**
  * Job execution operations for B2C Commerce.
  *
- * This module provides functions for running and monitoring jobs
- * on B2C Commerce instances via OCAPI.
+ * SDK consumers should call SCAPI ops directly via the free functions
+ * exported from `./scapi-ops` (or, for legacy code, the OCAPI free
+ * functions exported from `./run`). The CLI's `BackendDispatcher`
+ * arbitrates between them based on the user's `apiBackend` preference;
+ * that policy lives in the CLI layer.
  *
- * ## Core Job Functions
- *
- * - {@link executeJob} - Start a job execution
- * - {@link getJobExecution} - Get the status of a job execution
- * - {@link waitForJob} - Wait for a job to complete
- * - {@link searchJobExecutions} - Search for job executions
- * - {@link findRunningJobExecution} - Find a running execution
- * - {@link getJobLog} - Retrieve job log file content
- *
- * ## System Jobs
- *
- * - {@link siteArchiveImport} - Import a site archive
- * - {@link siteArchiveImportSet} - Apply an ordered, receipted set of site archives
- * - {@link siteArchiveImportSplit} - Import a large site archive in multiple parts
- * - {@link siteArchiveExport} - Export a site archive
- * - {@link siteArchiveExportToPath} - Export and save to local path
- *
- * ## Usage
- *
- * ```typescript
- * import {
- *   executeJob,
- *   waitForJob,
- *   searchJobExecutions,
- *   siteArchiveImport,
- *   siteArchiveExport,
- * } from '@salesforce/b2c-tooling-sdk/operations/jobs';
- * import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
- *
- * const config = resolveConfig();
- * const instance = config.createB2CInstance();
- *
- * // Run a custom job and wait for completion
- * const execution = await executeJob(instance, 'my-job-id');
- * const result = await waitForJob(instance, 'my-job-id', execution.id);
- *
- * // Search for recent job executions
- * const results = await searchJobExecutions(instance, {
- *   jobId: 'my-job-id',
- *   count: 10
- * });
- *
- * // Import a site archive
- * await siteArchiveImport(instance, './my-import-data');
- *
- * // Export site data
- * const exportResult = await siteArchiveExport(instance, {
- *   global_data: { meta_data: true }
- * });
- * ```
- *
- * ## Authentication
- *
- * Job operations require OAuth authentication with appropriate OCAPI permissions
- * for the /jobs and /job_execution_search resources.
+ * Ordered import sets are exported from `./import-set` and continue to use
+ * the site-archive/WebDAV workflow.
  *
  * @module operations/jobs
  */
 export { executeJob, getJobExecution, waitForJob, searchJobExecutions, findRunningJobExecution, getJobLog, getJobErrorMessage, JobExecutionError, } from './run.js';
 export type { JobExecution, JobStepExecution, JobExecutionStatus, JobExecutionParameter, ExecuteJobOptions, WaitForJobOptions, WaitForJobPollInfo, SearchJobExecutionsOptions, JobExecutionSearchResult, } from './run.js';
+export { executeJob as scapiExecuteJob, getJobExecution as scapiGetJobExecution, searchJobExecutions as scapiSearchJobExecutions, deleteJobExecution as scapiDeleteJobExecution, getJobLog as scapiGetJobLog, ScapiJobStartError, } from './scapi-ops.js';
+export type { ExecuteJobScapiOptions, SearchJobExecutionsScapiOptions } from './scapi-ops.js';
+export type { JobExecutionInfo, JobStepExecutionResult, JobExecutionSearchResults } from './types.js';
+export { waitForJobExecution, CanonicalJobExecutionError } from './wait-canonical.js';
+export { mapOcapiExecution, mapOcapiSearchResult, mapCanonicalToOcapiExecution } from './ocapi-mapping.js';
+export { runSystemJob } from './run-system-job.js';
+export type { SystemJobSpec } from './run-system-job.js';
 export { siteArchiveImport, siteArchiveImportSplit, siteArchiveExport, siteArchiveExportToBuffer, siteArchiveExportToPath, } from './site-archive.js';
 export { discoverImportSet, siteArchiveImportSet, ImportSetStateError } from './import-set.js';
 export type { DiscoverImportSetOptions, ImportSetItem, ImportSetReceipt, ImportSetItemResult, ImportSetResult, ImportSetEvent, ImportSetLockOwner, SiteArchiveImportSetOptions, } from './import-set.js';

package/dist/esm/operations/jobs/index.js

@@ -6,70 +6,26 @@
 /**
  * Job execution operations for B2C Commerce.
  *
- * This module provides functions for running and monitoring jobs
- * on B2C Commerce instances via OCAPI.
+ * SDK consumers should call SCAPI ops directly via the free functions
+ * exported from `./scapi-ops` (or, for legacy code, the OCAPI free
+ * functions exported from `./run`). The CLI's `BackendDispatcher`
+ * arbitrates between them based on the user's `apiBackend` preference;
+ * that policy lives in the CLI layer.
  *
- * ## Core Job Functions
- *
- * - {@link executeJob} - Start a job execution
- * - {@link getJobExecution} - Get the status of a job execution
- * - {@link waitForJob} - Wait for a job to complete
- * - {@link searchJobExecutions} - Search for job executions
- * - {@link findRunningJobExecution} - Find a running execution
- * - {@link getJobLog} - Retrieve job log file content
- *
- * ## System Jobs
- *
- * - {@link siteArchiveImport} - Import a site archive
- * - {@link siteArchiveImportSet} - Apply an ordered, receipted set of site archives
- * - {@link siteArchiveImportSplit} - Import a large site archive in multiple parts
- * - {@link siteArchiveExport} - Export a site archive
- * - {@link siteArchiveExportToPath} - Export and save to local path
- *
- * ## Usage
- *
- * ```typescript
- * import {
- *   executeJob,
- *   waitForJob,
- *   searchJobExecutions,
- *   siteArchiveImport,
- *   siteArchiveExport,
- * } from '@salesforce/b2c-tooling-sdk/operations/jobs';
- * import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
- *
- * const config = resolveConfig();
- * const instance = config.createB2CInstance();
- *
- * // Run a custom job and wait for completion
- * const execution = await executeJob(instance, 'my-job-id');
- * const result = await waitForJob(instance, 'my-job-id', execution.id);
- *
- * // Search for recent job executions
- * const results = await searchJobExecutions(instance, {
- *   jobId: 'my-job-id',
- *   count: 10
- * });
- *
- * // Import a site archive
- * await siteArchiveImport(instance, './my-import-data');
- *
- * // Export site data
- * const exportResult = await siteArchiveExport(instance, {
- *   global_data: { meta_data: true }
- * });
- * ```
- *
- * ## Authentication
- *
- * Job operations require OAuth authentication with appropriate OCAPI permissions
- * for the /jobs and /job_execution_search resources.
+ * Ordered import sets are exported from `./import-set` and continue to use
+ * the site-archive/WebDAV workflow.
  *
  * @module operations/jobs
  */
-// Core job execution
+// OCAPI ops (legacy — will be removed when OCAPI is deprecated)
 export { executeJob, getJobExecution, waitForJob, searchJobExecutions, findRunningJobExecution, getJobLog, getJobErrorMessage, JobExecutionError, } from './run.js';
-// Site archive import/export
+// SCAPI ops + canonical types (primary surface)
+export { executeJob as scapiExecuteJob, getJobExecution as scapiGetJobExecution, searchJobExecutions as scapiSearchJobExecutions, deleteJobExecution as scapiDeleteJobExecution, getJobLog as scapiGetJobLog, ScapiJobStartError, } from './scapi-ops.js';
+// Backend-agnostic helpers
+export { waitForJobExecution, CanonicalJobExecutionError } from './wait-canonical.js';
+export { mapOcapiExecution, mapOcapiSearchResult, mapCanonicalToOcapiExecution } from './ocapi-mapping.js';
+export { runSystemJob } from './run-system-job.js';
+// Site archive import/export (uses OCAPI WebDAV path)
 export { siteArchiveImport, siteArchiveImportSplit, siteArchiveExport, siteArchiveExportToBuffer, siteArchiveExportToPath, } from './site-archive.js';
 // Ordered, idempotent import sets
 export { discoverImportSet, siteArchiveImportSet, ImportSetStateError } from './import-set.js';

package/dist/esm/operations/jobs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/operations/jobs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,qBAAqB;AACrB,OAAO,EACL,UAAU,EACV,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,uBAAuB,EACvB,SAAS,EACT,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAclB,6BAA6B;AAC7B,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,kCAAkC;AAClC,OAAO,EAAC,iBAAiB,EAAE,oBAAoB,EAAE,mBAAmB,EAAC,MAAM,iBAAiB,CAAC;AA0B7F,iCAAiC;AACjC,OAAO,EAAC,uBAAuB,EAAC,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/operations/jobs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;GAaG;AAEH,gEAAgE;AAChE,OAAO,EACL,UAAU,EACV,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,uBAAuB,EACvB,SAAS,EACT,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAclB,gDAAgD;AAChD,OAAO,EACL,UAAU,IAAI,eAAe,EAC7B,eAAe,IAAI,oBAAoB,EACvC,mBAAmB,IAAI,wBAAwB,EAC/C,kBAAkB,IAAI,uBAAuB,EAC7C,SAAS,IAAI,cAAc,EAC3B,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAIxB,2BAA2B;AAC3B,OAAO,EAAC,mBAAmB,EAAE,0BAA0B,EAAC,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAC,iBAAiB,EAAE,oBAAoB,EAAE,4BAA4B,EAAC,MAAM,oBAAoB,CAAC;AACzG,OAAO,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AAGjD,sDAAsD;AACtD,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,kCAAkC;AAClC,OAAO,EAAC,iBAAiB,EAAE,oBAAoB,EAAE,mBAAmB,EAAC,MAAM,iBAAiB,CAAC;AA0B7F,iCAAiC;AACjC,OAAO,EAAC,uBAAuB,EAAC,MAAM,eAAe,CAAC"}

package/dist/esm/operations/jobs/ocapi-mapping.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Mapping helpers from raw OCAPI shapes (snake_case) to canonical
+ * {@link JobExecutionInfo} (camelCase).
+ *
+ * These exist as transitional utilities to bridge the two API shapes. They
+ * will be deleted along with the OCAPI ops once OCAPI is removed.
+ *
+ * @module operations/jobs/ocapi-mapping
+ */
+import type { JobExecution } from './run.js';
+import type { JobExecutionInfo, JobExecutionSearchResults } from './types.js';
+/** Map a raw OCAPI {@link JobExecution} into the canonical shape. */
+export declare function mapOcapiExecution(ocapi: JobExecution): JobExecutionInfo;
+/**
+ * Map a canonical {@link JobExecutionInfo} back into the raw OCAPI
+ * {@link JobExecution} (snake_case) shape.
+ *
+ * The reverse of {@link mapOcapiExecution}. System-job operations
+ * (site-archive import/export, CAP install/uninstall) expose the raw OCAPI
+ * `JobExecution` in their public result/error types; when those operations are
+ * served over SCAPI, the canonical result is mapped back through this so the
+ * public contract stays identical across backends.
+ *
+ * Prefers the original OCAPI payload when present in `_raw` (lossless
+ * round-trip for the OCAPI path); otherwise projects the canonical fields.
+ */
+export declare function mapCanonicalToOcapiExecution(canonical: JobExecutionInfo): JobExecution;
+/** Map a raw OCAPI search result into the canonical shape. */
+export declare function mapOcapiSearchResult(result: {
+    total: number;
+    count: number;
+    start: number;
+    hits: JobExecution[];
+}): JobExecutionSearchResults;

package/dist/esm/operations/jobs/ocapi-mapping.js

@@ -0,0 +1,100 @@
+function mapStepExecution(step) {
+    return {
+        id: step.id,
+        stepId: step.step_id,
+        executionStatus: step.execution_status,
+        exitStatus: step.exit_status
+            ? {
+                code: step.exit_status.code ?? '',
+                message: step.exit_status.message,
+                status: step.exit_status.status,
+            }
+            : undefined,
+        duration: step.duration,
+    };
+}
+/** Map a raw OCAPI {@link JobExecution} into the canonical shape. */
+export function mapOcapiExecution(ocapi) {
+    return {
+        id: ocapi.id ?? '',
+        jobId: ocapi.job_id ?? '',
+        executionStatus: (ocapi.execution_status ?? 'unknown'),
+        exitStatus: ocapi.exit_status
+            ? {
+                code: ocapi.exit_status.code ?? '',
+                message: ocapi.exit_status.message,
+                status: ocapi.exit_status.status,
+            }
+            : undefined,
+        startTime: ocapi.start_time,
+        endTime: ocapi.end_time,
+        duration: ocapi.duration,
+        stepExecutions: ocapi.step_executions?.map(mapStepExecution),
+        logFilePath: ocapi.log_file_path,
+        isLogFileExisting: ocapi.is_log_file_existing,
+        parameters: ocapi.parameters,
+        _raw: ocapi,
+    };
+}
+function mapCanonicalStepExecution(step) {
+    return {
+        id: step.id,
+        step_id: step.stepId,
+        execution_status: step.executionStatus,
+        exit_status: step.exitStatus
+            ? {
+                code: step.exitStatus.code,
+                message: step.exitStatus.message,
+                status: step.exitStatus.status,
+            }
+            : undefined,
+        duration: step.duration,
+    };
+}
+/**
+ * Map a canonical {@link JobExecutionInfo} back into the raw OCAPI
+ * {@link JobExecution} (snake_case) shape.
+ *
+ * The reverse of {@link mapOcapiExecution}. System-job operations
+ * (site-archive import/export, CAP install/uninstall) expose the raw OCAPI
+ * `JobExecution` in their public result/error types; when those operations are
+ * served over SCAPI, the canonical result is mapped back through this so the
+ * public contract stays identical across backends.
+ *
+ * Prefers the original OCAPI payload when present in `_raw` (lossless
+ * round-trip for the OCAPI path); otherwise projects the canonical fields.
+ */
+export function mapCanonicalToOcapiExecution(canonical) {
+    if (canonical._raw && typeof canonical._raw === 'object' && 'execution_status' in canonical._raw) {
+        return canonical._raw;
+    }
+    return {
+        id: canonical.id,
+        job_id: canonical.jobId,
+        execution_status: canonical.executionStatus,
+        exit_status: canonical.exitStatus
+            ? {
+                code: canonical.exitStatus.code,
+                message: canonical.exitStatus.message,
+                status: canonical.exitStatus.status,
+            }
+            : undefined,
+        start_time: canonical.startTime,
+        end_time: canonical.endTime,
+        duration: canonical.duration,
+        step_executions: canonical.stepExecutions?.map(mapCanonicalStepExecution),
+        log_file_path: canonical.logFilePath,
+        is_log_file_existing: canonical.isLogFileExisting,
+        parameters: canonical.parameters,
+    };
+}
+/** Map a raw OCAPI search result into the canonical shape. */
+export function mapOcapiSearchResult(result) {
+    return {
+        total: result.total,
+        limit: result.count,
+        offset: result.start,
+        hits: result.hits.map(mapOcapiExecution),
+    };
+}
+//# sourceMappingURL=ocapi-mapping.js.map

package/dist/esm/operations/jobs/ocapi-mapping.js.map

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

package/dist/esm/operations/jobs/run-system-job.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Dual-backend runner for B2C Commerce **system jobs** (site-archive
+ * import/export, CAP install/uninstall).
+ *
+ * These operations all follow the same shape: trigger a named system job,
+ * wait for it to finish, and surface the job log on failure. This module
+ * centralizes that flow over either backend so each operation declares only
+ * its job ID and request body — not the OCAPI-vs-SCAPI plumbing.
+ *
+ * ## Contract
+ *
+ * The public result/error types of every caller expose the **raw OCAPI**
+ * {@link JobExecution} (snake_case). To keep that contract identical across
+ * backends, the SCAPI path maps its canonical result back to the OCAPI shape
+ * via {@link mapCanonicalToOcapiExecution}, and a SCAPI job failure is
+ * re-thrown as the raw {@link JobExecutionError} — so a caller's existing
+ * `catch (JobExecutionError) → getJobLog(instance, err.execution)` works
+ * unchanged regardless of which backend served the job.
+ *
+ * ## Backend selection & fallback
+ *
+ * Honors {@link B2CInstance.apiBackend}:
+ *   - `'ocapi'`: always OCAPI.
+ *   - `'scapi'`: always SCAPI (throws if the instance can't reach SCAPI).
+ *   - `'auto'` (default): SCAPI when {@link B2CInstance.scapiClientConfig} is
+ *     available, else OCAPI. **Fallback to OCAPI happens only when the SCAPI
+ *     start provably created no job** — an Account Manager scope rejection
+ *     (before the POST) or a client-side rejection status (the server refused
+ *     the start). Ambiguous failures (network drop after dispatch, timeout,
+ *     5xx) and any post-start failure propagate without a re-run, because
+ *     re-running a mutating system job over OCAPI could execute it twice. See
+ *     {@link isSafeStartFallback}.
+ *
+ * ## Lifecycle
+ *
+ * Lives alongside the other transitional jobs plumbing. When OCAPI is removed,
+ * delete the OCAPI branch and inline the SCAPI calls.
+ *
+ * @module operations/jobs/run-system-job
+ */
+import type { B2CInstance } from '../../instance/index.js';
+import { type JobExecution, type WaitForJobOptions } from './run.js';
+/**
+ * Declarative description of a system job to run. The operation supplies its
+ * job ID and the two request-body forms; this module drives the rest.
+ */
+export interface SystemJobSpec {
+    /** System job ID, e.g. `sfcc-site-archive-import`. */
+    jobId: string;
+    /**
+     * System-job configuration sent on both APIs (e.g.
+     * `{file_name}`, `{export_file, data_units}`, or the CAP `{app_name, ...}`
+     * shape). These system jobs retain snake_case fields on SCAPI. When the
+     * instance rejects it with `UnknownPropertyException`, the
+     * OCAPI path retries with {@link parameters}.
+     */
+    body: Record<string, unknown>;
+    /**
+     * Job parameters (`[{name, value}]`) for the OCAPI internal-user retry.
+     * System jobs do not use the generic SCAPI JobExecutionRequest body.
+     */
+    parameters: Array<{
+        name: string;
+        value: string;
+    }>;
+    /** Scopes named in the OCAPI-deprecation error (the rw jobs scope). */
+    deprecatedScopes?: string[];
+    /** Whether to wait for completion (default `true`). */
+    wait?: boolean;
+    /** Wait options forwarded to the poll loop. */
+    waitOptions?: WaitForJobOptions;
+    /** Human-readable verb for error messages, e.g. `'execute import job'`. */
+    failVerb: string;
+}
+/**
+ * Starts a system job (waiting for completion unless `spec.wait === false`)
+ * and returns the raw OCAPI {@link JobExecution}. Throws {@link JobExecutionError}
+ * (raw) when the job fails, or {@link OcapiDeprecatedError} when the only
+ * reachable backend is a deprecated OCAPI.
+ */
+export declare function runSystemJob(instance: B2CInstance, spec: SystemJobSpec): Promise<JobExecution>;