@salesforce/b2c-tooling-sdk 1.24.2 → 2.1.0

package/dist/esm/operations/mrt/mrt-backend.js

@@ -0,0 +1,84 @@
+import { isFallbackTrigger, resolvePreferredBackend, SCAPI_CAPABILITY_BASELINE_RELEASE, } from '../../clients/scapi-backend-utils.js';
+import { getLogger } from '../../logging/logger.js';
+/**
+ * Error message for when explicit `--mrt-backend scapi` is requested but the
+ * SCAPI MRT prerequisites are missing. Names both reasons the connection can
+ * be unavailable — missing coordinates OR an auth flow SCAPI Admin does not
+ * accept. Unlike the OCAPI {@link scapiUnavailableMessage}, MRT resolves auth
+ * through the shared `getOAuthStrategy()` path, so a stored `b2c auth client`
+ * session counts as a supported flow here.
+ */
+export function mrtScapiUnavailableMessage() {
+    return (`The SCAPI MRT backend requires shortCode, tenantId, and an OAuth flow SCAPI Admin accepts ` +
+        `that can request the sfcc.storefront.* scopes — client-credentials or JWT Bearer, configured ` +
+        `directly (--client-id/--client-secret or JWT) or as a stored \`b2c auth client\` session. ` +
+        `Browser user auth (Authorization Code + PKCE or the deprecated implicit flow) is not supported ` +
+        `for SCAPI Admin as of B2C Commerce release ${SCAPI_CAPABILITY_BASELINE_RELEASE}. ` +
+        `Provide --short-code and --tenant-id with a supported flow, or use --mrt-backend legacy ` +
+        `(per-user API key via --api-key / ~/.mobify).`);
+}
+/**
+ * Resolves a preference plus SCAPI availability into a concrete backend.
+ *
+ * - `legacy` → always `legacy`.
+ * - `scapi` → `scapi`, throwing {@link mrtScapiUnavailableMessage} if the SCAPI
+ *   connection is missing (fail loud; never silently use legacy).
+ * - `auto` → `scapi` when a connection is available, otherwise `legacy`.
+ */
+export function resolveMrtBackend(opts) {
+    const { preference, hasScapiConfig } = opts;
+    return resolvePreferredBackend({
+        preference,
+        primary: 'legacy',
+        hasScapiConfig,
+        unavailableMessage: mrtScapiUnavailableMessage,
+    });
+}
+/**
+ * Resolves the backend and runs the matching branch.
+ *
+ * - `legacy` (explicit or `auto` with no SCAPI config): runs the legacy branch.
+ * - `scapi` (explicit): runs the SCAPI branch with **no** fallback — every
+ *   error surfaces, including 409 Conflict.
+ * - `auto` with a SCAPI connection: runs SCAPI optimistically; on a
+ *   {@link isFallbackTrigger safe} rejection (a definite pre-execution client
+ *   error or `invalid_scope`) it warns and retries on legacy — but only when a
+ *   legacy target exists ({@link RunMrtWithFallbackOptions.canFallbackToLegacy}).
+ *   With no legacy credentials, the original SCAPI error is rethrown so the user
+ *   sees the real failure rather than a "provide an API key" message. Ambiguous
+ *   failures (429, 5xx, network) and 409 Conflict never fall back — a mutating
+ *   deploy must not cross backends after the request may have reached SCAPI.
+ *
+ * @returns the backend that served the call and its result.
+ */
+export async function runMrtWithFallback(options, branches) {
+    const { preference, hasScapiConfig, canFallbackToLegacy = true, onFallback, onResolve } = options;
+    const backend = resolveMrtBackend({ preference, hasScapiConfig });
+    if (backend === 'legacy') {
+        onResolve?.('legacy');
+        return { backend: 'legacy', value: await branches.legacy() };
+    }
+    onResolve?.('scapi');
+    // Explicit SCAPI: no fallback, surface all errors.
+    if (preference === 'scapi') {
+        return { backend: 'scapi', value: await branches.scapi() };
+    }
+    // auto + SCAPI available: optimistic SCAPI with a one-shot safe fallback.
+    try {
+        return { backend: 'scapi', value: await branches.scapi() };
+    }
+    catch (error) {
+        // Rethrow the real SCAPI error on ambiguous/non-safe failures, or when
+        // there is no legacy target to fall back to (falling back would only
+        // surface a misleading "provide an API key" error).
+        if (!isFallbackTrigger(error) || !canFallbackToLegacy) {
+            throw error;
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        getLogger().warn({ reason }, '[MRT] SCAPI backend rejected the request; falling back to legacy MRT');
+        onFallback?.(reason);
+        onResolve?.('legacy');
+        return { backend: 'legacy', value: await branches.legacy() };
+    }
+}
+//# sourceMappingURL=mrt-backend.js.map

package/dist/esm/operations/mrt/mrt-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mrt-backend.js","sourceRoot":"","sources":["../../../../src/operations/mrt/mrt-backend.ts"],"names":[],"mappings":"AAyBA,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,iCAAiC,GAClC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAC,SAAS,EAAC,MAAM,yBAAyB,CAAC;AAyBlD;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO,CACL,4FAA4F;QAC5F,+FAA+F;QAC/F,4FAA4F;QAC5F,iGAAiG;QACjG,8CAA8C,iCAAiC,IAAI;QACnF,0FAA0F;QAC1F,+CAA+C,CAChD,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAiE;IACjG,MAAM,EAAC,UAAU,EAAE,cAAc,EAAC,GAAG,IAAI,CAAC;IAC1C,OAAO,uBAAuB,CAAC;QAC7B,UAAU;QACV,OAAO,EAAE,QAAQ;QACjB,cAAc;QACd,kBAAkB,EAAE,0BAA0B;KAC/C,CAAC,CAAC;AACL,CAAC;AA2CD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAkC,EAClC,QAA+B;IAE/B,MAAM,EAAC,UAAU,EAAE,cAAc,EAAE,mBAAmB,GAAG,IAAI,EAAE,UAAU,EAAE,SAAS,EAAC,GAAG,OAAO,CAAC;IAChG,MAAM,OAAO,GAAG,iBAAiB,CAAC,EAAC,UAAU,EAAE,cAAc,EAAC,CAAC,CAAC;IAEhE,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,SAAS,EAAE,CAAC,QAAQ,CAAC,CAAC;QACtB,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC,MAAM,EAAE,EAAC,CAAC;IAC7D,CAAC;IAED,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC;IAErB,mDAAmD;IACnD,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;QAC3B,OAAO,EAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC,KAAK,EAAE,EAAC,CAAC;IAC3D,CAAC;IAED,0EAA0E;IAC1E,IAAI,CAAC;QACH,OAAO,EAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC,KAAK,EAAE,EAAC,CAAC;IAC3D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,uEAAuE;QACvE,qEAAqE;QACrE,oDAAoD;QACpD,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC;YACtD,MAAM,KAAK,CAAC;QACd,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,SAAS,EAAE,CAAC,IAAI,CAAC,EAAC,MAAM,EAAC,EAAE,sEAAsE,CAAC,CAAC;QACnG,UAAU,EAAE,CAAC,MAAM,CAAC,CAAC;QACrB,SAAS,EAAE,CAAC,QAAQ,CAAC,CAAC;QACtB,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC,MAAM,EAAE,EAAC,CAAC;IAC7D,CAAC;AACH,CAAC"}

package/dist/esm/operations/mrt/push.d.ts

@@ -7,7 +7,9 @@
  */
 import type { AuthStrategy } from '../../auth/types.js';
 import type { MrtClient, components } from '../../clients/mrt.js';
-import type { CreateBundleOptions, Bundle } from './bundle.js';
+import { type Bundle as BundleScapi, type BundleUploadResponse } from '../../clients/storefront-deployments.js';
+import type { CreateBundleOptions, Bundle, BundleV2, CreateBundleV2Options } from './bundle.js';
+import { type MrtBackend, type MrtBackendPreference, type ScapiMrtConnection } from './mrt-backend.js';
 /**
  * Options for pushing a bundle to MRT.
  */
@@ -99,6 +101,88 @@ export declare function pushBundle(options: PushOptions, auth: AuthStrategy): Pr
  * @returns Result of the upload
  */
 export declare function uploadBundle(client: MrtClient, projectSlug: string, bundle: Bundle, target?: string): Promise<PushResult>;
+/**
+ * Options for pushing a v2-format bundle to MRT.
+ */
+export interface PushV2Options extends CreateBundleV2Options {
+    /**
+     * The project slug to upload to.
+     */
+    projectSlug: string;
+    /**
+     * MRT API origin URL.
+     * @default "https://cloud.mobify.com"
+     */
+    origin?: string;
+}
+/**
+ * Result of a v2 push (upload) operation.
+ */
+export interface PushV2Result {
+    /**
+     * The bundle ID assigned by MRT.
+     */
+    bundleId: number;
+    /**
+     * The project slug the bundle was uploaded to.
+     */
+    projectSlug: string;
+    /**
+     * The bundle message.
+     */
+    message: string;
+    /**
+     * Non-blocking warnings returned by MRT (e.g. deprecated runtime).
+     */
+    warnings: string[];
+    /**
+     * Server-computed ssrOnly/ssrShared file matches.
+     */
+    matches: Record<string, unknown>;
+}
+/**
+ * Builds a v2-format archive from a build directory and uploads it to MRT.
+ *
+ * This is upload-only: it does not deploy the bundle. Deploy separately with
+ * {@link createDeployment} (or the `b2c mrt bundle deploy <bundleId>` command).
+ *
+ * @param options - v2 push configuration options
+ * @param auth - Authentication strategy (ApiKeyStrategy)
+ * @returns Result of the upload operation
+ * @throws Error if the upload fails
+ *
+ * @example
+ * ```typescript
+ * import { ApiKeyStrategy } from '@salesforce/b2c-tooling-sdk/auth';
+ * import { pushBundleV2 } from '@salesforce/b2c-tooling-sdk/operations/mrt';
+ *
+ * const auth = new ApiKeyStrategy(process.env.MRT_API_KEY!, 'Authorization');
+ *
+ * const result = await pushBundleV2({
+ *   projectSlug: 'my-storefront',
+ *   ssrOnly: ['ssr.js'],
+ *   ssrShared: ['static/**\/*'],
+ *   buildDirectory: './build',
+ *   message: 'Release v1.0.0'
+ * }, auth);
+ *
+ * console.log(`Bundle ${result.bundleId} uploaded to ${result.projectSlug}`);
+ * ```
+ */
+export declare function pushBundleV2(options: PushV2Options, auth: AuthStrategy): Promise<PushV2Result>;
+/**
+ * Uploads a pre-built v2 bundle archive to MRT as multipart/form-data.
+ *
+ * Use this if you've already built a v2 bundle with {@link createBundleV2} and
+ * want to upload it separately.
+ *
+ * @param client - MRT client instance
+ * @param projectSlug - Project to upload to
+ * @param bundle - v2 bundle to upload
+ * @returns Result of the upload
+ * @throws Error if the upload fails or the response omits a bundle id
+ */
+export declare function uploadBundleV2(client: MrtClient, projectSlug: string, bundle: BundleV2): Promise<PushV2Result>;
 /**
  * Bundle list item from API.
  */
@@ -292,3 +376,203 @@ export interface BulkDeleteBundlesResult {
  * @throws Error if the request itself fails
  */
 export declare function bulkDeleteBundles(options: BulkDeleteBundlesOptions, auth: AuthStrategy): Promise<BulkDeleteBundlesResult>;
+/**
+ * A single bundle list row, normalized across the legacy and SCAPI backends so
+ * the CLI table renders one shape regardless of backend.
+ *
+ * Status is kept **raw** per backend (legacy numeric enum `0 | 1 | 2`, SCAPI
+ * string enum `"ok"` / `"broken"` / `"preparing"`) so display doesn't silently
+ * change for existing legacy users.
+ */
+export interface MrtBundleView {
+    /** Numeric bundle identifier. */
+    id?: number;
+    /** Human-readable bundle message/description. */
+    message?: string;
+    /** Raw backend status string. */
+    status?: string | number;
+    /** Email of the user who uploaded the bundle. */
+    user?: string;
+    /** Creation timestamp (ISO 8601). */
+    created?: string;
+    /** Backend that produced this row. */
+    backend: MrtBackend;
+}
+/** Normalizes a legacy MRT bundle list item into an {@link MrtBundleView}. */
+export declare function normalizeLegacyBundle(bundle: MrtBundle): MrtBundleView;
+/** Normalizes a SCAPI MRT {@link BundleScapi} into an {@link MrtBundleView}. */
+export declare function normalizeScapiBundle(bundle: BundleScapi): MrtBundleView;
+/**
+ * Lists bundles for a storefront via the SCAPI MRT Deployments API.
+ *
+ * Forwards the standard SCAPI `limit`/`offset` pagination query parameters when
+ * provided (the response echoes the full `total`), mirroring the legacy list and
+ * {@link listDeploymentsScapi}.
+ *
+ * @throws {ScapiRequestError} carrying the HTTP status on a non-2xx response.
+ */
+export declare function listBundlesScapi(conn: ScapiMrtConnection, params: {
+    storefrontId: string;
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    bundles: MrtBundleView[];
+    count: number;
+    raw: unknown;
+}>;
+/** Result of a SCAPI bundle upload. */
+export interface UploadBundleScapiResult {
+    /** Numeric bundle identifier assigned by SCAPI. */
+    bundleId: number;
+    /** Non-blocking warnings returned during bundle processing. */
+    warnings: string[];
+    /** Server-computed ssrOnly/ssrShared file matches. */
+    matches: Record<string, unknown>;
+    /** Raw, backend-native upload response, surfaced verbatim under `--json`. */
+    raw: BundleUploadResponse;
+}
+/**
+ * Uploads a pre-built v2 bundle archive to a storefront via the SCAPI MRT
+ * Deployments API as multipart/form-data.
+ *
+ * The multipart payload mirrors the legacy {@link uploadBundleV2} exactly (same
+ * `bundle`/`message`/`rootDir`/`configPath`/`matchMode` fields), so a bundle
+ * built with {@link createBundleV2} uploads identically on either backend. As
+ * with the legacy path, openapi-fetch passes the `FormData` body through
+ * unchanged and lets fetch set the multipart Content-Type + boundary.
+ *
+ * @throws {ScapiRequestError} carrying the HTTP status on a non-2xx response.
+ */
+export declare function uploadBundleScapi(conn: ScapiMrtConnection, params: {
+    storefrontId: string;
+    bundle: BundleV2;
+}): Promise<UploadBundleScapiResult>;
+/** Options for {@link listMrtBundles}. */
+export interface ListMrtBundlesBackendOptions {
+    /** Resolved `--mrt-backend` preference. */
+    preference: MrtBackendPreference;
+    /** SCAPI connection; when absent, `auto` uses legacy and `scapi` throws. */
+    scapiConnection?: ScapiMrtConnection;
+    /** Legacy API-key auth strategy. Optional; required only when the legacy backend actually runs. */
+    legacyAuth?: AuthStrategy;
+    /** Project slug (= SCAPI storefront ID). */
+    projectSlug: string;
+    /** Maximum results per page (forwarded to both backends). */
+    limit?: number;
+    /** Pagination offset (forwarded to both backends). */
+    offset?: number;
+    /** Legacy MRT API origin. */
+    origin?: string;
+    /** Invoked when `auto` falls back from SCAPI to legacy. */
+    onFallback?: (reason: string) => void;
+    /** Invoked with the backend that serves the call (for `-D` debug). */
+    onResolve?: (backend: MrtBackend) => void;
+}
+/** Backend-neutral bundle list result. */
+export interface MrtBundlesView {
+    /** Backend that served the list. */
+    backend: MrtBackend;
+    /** Total count reported by the backend. */
+    count: number;
+    /** Normalized bundle rows, consumed by the CLI table. */
+    bundles: MrtBundleView[];
+    /**
+     * The raw, backend-native list response, surfaced verbatim under `--json` so
+     * each backend keeps its original machine contract (legacy: the MRT Cloud API
+     * list shape — `count`/`next`/`previous`/`bundles`; SCAPI: the Storefront
+     * Deployments response — `data`/`total`). The normalized {@link bundles} feed
+     * the human table only.
+     */
+    raw: unknown;
+}
+/**
+ * Lists bundles, routing to the SCAPI or legacy backend per the given
+ * preference (with safe `auto` fallback). Returns normalized rows.
+ */
+export declare function listMrtBundles(options: ListMrtBundlesBackendOptions): Promise<MrtBundlesView>;
+/** Options for {@link pushMrtBundle}. */
+export interface PushMrtBundleBackendOptions {
+    /** Resolved `--mrt-backend` preference. */
+    preference: MrtBackendPreference;
+    /** SCAPI connection; when absent, `auto` uses legacy and `scapi` throws. */
+    scapiConnection?: ScapiMrtConnection;
+    /** Legacy API-key auth strategy. Optional; required only when the legacy backend actually runs. */
+    legacyAuth?: AuthStrategy;
+    /** Project slug (= SCAPI storefront ID). */
+    projectSlug: string;
+    /** Target/environment slug (= SCAPI environment ID). When omitted, the bundle is uploaded but not deployed. */
+    targetSlug?: string;
+    /** Bundle message/description. */
+    message?: string;
+    /** SSR runtime parameters. */
+    ssrParameters?: Record<string, unknown>;
+    /** Glob patterns for server-only files. */
+    ssrOnly?: string[];
+    /** Glob patterns for files shared between server and client. */
+    ssrShared?: string[];
+    /** Build output directory. */
+    buildDirectory?: string;
+    /** Directory to read `config.server.{ts,js}` from. */
+    projectDirectory?: string;
+    /** v2 archive root directory (v2 uploads only). */
+    rootDir?: string;
+    /** v2 in-archive config path (v2 uploads only). */
+    configPath?: string;
+    /** v2 match mode (v2 uploads only). */
+    matchMode?: BundleV2['matchMode'];
+    /**
+     * Use the v2 bundle format/endpoint. SCAPI is always v2 (this flag is
+     * redundant there). Legacy defaults to v1; set this to route the legacy push
+     * through the v2 endpoint so the `rootDir`/`configPath`/`matchMode` options
+     * take effect.
+     */
+    v2?: boolean;
+    /** Legacy MRT API origin. */
+    origin?: string;
+    /** Invoked when `auto` falls back from SCAPI to legacy. */
+    onFallback?: (reason: string) => void;
+    /** Invoked with the backend that serves the call (for `-D` debug). */
+    onResolve?: (backend: MrtBackend) => void;
+}
+/** Backend-neutral local-build push result. */
+export interface MrtPushResultView {
+    /** Backend that served the push (pins the `--wait` strategy). */
+    backend: MrtBackend;
+    /** Bundle that was uploaded. */
+    bundleId: number;
+    /** Resolved bundle message/description (the auto-generated default when none was given). */
+    message?: string;
+    /** Whether the bundle was also deployed (a target was provided). */
+    deployed: boolean;
+    /** SCAPI deployment UUID for `--wait` polling; undefined for legacy or upload-only. */
+    deploymentId?: string;
+    /** Initial deployment status; undefined for upload-only. */
+    status?: string;
+    /** Non-blocking warnings returned by the backend. */
+    warnings?: string[];
+    /**
+     * The raw, backend-native response, surfaced verbatim under `--json`. Legacy:
+     * the combined MRT Cloud API push result. SCAPI: `{bundle, deployment?}` — the
+     * upload response plus, when a target was given, the create-deployment
+     * response (the two native calls that make up a SCAPI local-build deploy).
+     */
+    raw: unknown;
+}
+/**
+ * Builds a bundle from a local build and pushes it, routing to the SCAPI or
+ * legacy backend per the given preference (with safe `auto` fallback). When a
+ * `targetSlug` is given the bundle is also deployed; otherwise it is uploaded
+ * only. The returned `backend` pins which `--wait` strategy the caller uses.
+ *
+ * **Bundle format:** SCAPI always uploads the v2 format. Legacy defaults to the
+ * v1 combined upload+deploy; set `v2` to route the legacy push through the v2
+ * endpoint instead (upload, then a separate deploy when a target is given), so
+ * the `rootDir`/`configPath`/`matchMode` options take effect on legacy too.
+ *
+ * **Fallback safety:** only the SCAPI *upload* is fallback-eligible — if it
+ * fails with a safe pre-execution error nothing was created, so `auto` retries
+ * on legacy. Once the upload succeeds a bundle exists on SCAPI, so a failure of
+ * the subsequent create-deployment is re-thrown as a plain `Error` (not a
+ * fallback trigger) to avoid re-uploading the whole build on legacy.
+ */
+export declare function pushMrtBundle(options: PushMrtBundleBackendOptions): Promise<MrtPushResultView>;