@salesforce/b2c-tooling-sdk 1.24.2 → 2.0.0

package/dist/esm/clients/scapi-backend-utils.js

@@ -0,0 +1,180 @@
+import { getApiErrorMessage } from './error-utils.js';
+/** Platform release used when documenting currently-unavailable SCAPI capabilities. */
+export const SCAPI_CAPABILITY_BASELINE_RELEASE = '26.8';
+/** Error raised when browser-based Account Manager user auth is passed to a SCAPI Admin client. */
+export class ScapiUserAuthUnsupportedError extends Error {
+    constructor() {
+        super(`SCAPI Admin APIs do not currently support browser user authentication as of B2C Commerce release ${SCAPI_CAPABILITY_BASELINE_RELEASE}. ` +
+            'Use client credentials or JWT Bearer authentication, or set apiBackend to "ocapi" ' +
+            '(CLI: --api-backend ocapi) for now. The tooling will be updated when SCAPI support becomes available.');
+        this.name = 'ScapiUserAuthUnsupportedError';
+    }
+}
+/** Reject browser user-auth strategies before a SCAPI request is attempted. */
+export function assertScapiAdminAuthSupported(auth) {
+    if ('authMethod' in auth && (auth.authMethod === 'user' || auth.authMethod === 'implicit')) {
+        throw new ScapiUserAuthUnsupportedError();
+    }
+}
+/**
+ * Returns a copy of `auth` with `additionalScopes` merged in, or the original
+ * `auth` if the strategy doesn't support scope merging (e.g., basic/api-key
+ * auth, or a stored-session strategy where scopes were fixed at acquisition).
+ *
+ * Centralized so SCAPI client factories don't have to keep extending an
+ * `instanceof` chain as new OAuth strategy types are added.
+ */
+export function withScopes(auth, additionalScopes) {
+    assertScapiAdminAuthSupported(auth);
+    if (typeof auth.withAdditionalScopes === 'function') {
+        return auth.withAdditionalScopes(additionalScopes);
+    }
+    return auth;
+}
+/**
+ * Detects an Account Manager `invalid_scope` error.
+ *
+ * When a client's API client doesn't have the requested scope configured,
+ * Account Manager returns `{"error":"invalid_scope", ...}` on the token
+ * request. The OAuth strategy surfaces that as an Error whose message
+ * contains `invalid_scope`.
+ *
+ * Used by fallback wrappers to decide whether to downgrade to OCAPI.
+ */
+export function isInvalidScopeError(error) {
+    return error instanceof Error && error.message.includes('invalid_scope');
+}
+/**
+ * Thrown by SCAPI backends when a requested operation cannot be expressed on
+ * SCAPI (e.g., toggling the `disabled` flag via the SCAPI Users PATCH, which
+ * the SCAPI schema does not include). The fallback wrapper recognizes this
+ * and falls back to OCAPI; in explicit `scapi` mode it propagates so the
+ * caller sees the limitation.
+ */
+export class ScapiCapabilityUnsupportedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ScapiCapabilityUnsupportedError';
+    }
+}
+/** Builds the canonical error for a capability absent from the current live SCAPI schemas. */
+export function scapiCapabilityUnsupportedMessage(capability) {
+    return (`SCAPI does not currently support ${capability} as of B2C Commerce release ${SCAPI_CAPABILITY_BASELINE_RELEASE}. ` +
+        'Set apiBackend to "ocapi" (CLI: --api-backend ocapi) for now. ' +
+        'The tooling will be updated when SCAPI support becomes available.');
+}
+/**
+ * Prevents an OCAPI-only compatibility operation from silently contacting
+ * OCAPI when the caller explicitly selected SCAPI. `auto` remains eligible
+ * for the temporary compatibility path, while explicit OCAPI is always
+ * allowed.
+ */
+export function assertOcapiCompatibilityAllowed(preference, capability) {
+    if (preference === 'scapi') {
+        throw new ScapiCapabilityUnsupportedError(scapiCapabilityUnsupportedMessage(capability));
+    }
+}
+/**
+ * HTTP statuses that prove SCAPI rejected a request before performing it.
+ *
+ * These are safe for the temporary `auto` compatibility mode to retry over
+ * OCAPI. Ambiguous responses (`429`, `5xx`) and network failures are excluded
+ * because a mutating request might already have reached the platform.
+ */
+export const SAFE_SCAPI_FALLBACK_STATUSES = new Set([400, 401, 403, 404, 405, 406, 415]);
+/**
+ * A structured SCAPI response failure. Backends must retain the response
+ * status so the shared fallback policy can distinguish a definite rejection
+ * from an ambiguous transport/server failure.
+ */
+export class ScapiRequestError extends Error {
+    status;
+    constructor(message, 
+    /** HTTP status returned by SCAPI. */
+    status, options) {
+        super(message, options);
+        this.status = status;
+        this.name = 'ScapiRequestError';
+    }
+}
+/** Creates a structured SCAPI error using the repository's common formatter. */
+export function createScapiRequestError(error, response, fallbackMessage) {
+    const message = error ? getApiErrorMessage(error, response) : fallbackMessage;
+    return new ScapiRequestError(message || fallbackMessage, response.status, { cause: error });
+}
+/**
+ * Detects whether an error should trigger an OCAPI fallback. Currently:
+ *   - {@link isInvalidScopeError}: AM rejected the requested scope.
+ *   - {@link ScapiCapabilityUnsupportedError}: the SCAPI surface lacks the
+ *     capability the caller asked for.
+ *   - {@link ScapiRequestError}: SCAPI definitively rejected the request with
+ *     a safe client-error status.
+ */
+export function isFallbackTrigger(error) {
+    return (isInvalidScopeError(error) ||
+        error instanceof ScapiCapabilityUnsupportedError ||
+        (error instanceof ScapiRequestError && SAFE_SCAPI_FALLBACK_STATUSES.has(error.status)));
+}
+/**
+ * Message for when explicit SCAPI is requested but the instance can't reach it.
+ *
+ * Names both reasons the SCAPI client config can be unavailable — missing
+ * coordinates OR an auth flow that can't request scopes — because a user who
+ * hits this in explicit `--api-backend scapi` mode often *does* have shortCode
+ * and tenantId configured; the real blocker can be browser user auth, which
+ * SCAPI Admin APIs do not currently support, or a fixed-scope stored token.
+ * The old message only mentioned missing credentials, which was misleading.
+ */
+export function scapiUnavailableMessage(domainName) {
+    return (`${domainName} SCAPI backend requires shortCode, tenantId, and a stateless OAuth flow ` +
+        `(client-credentials or JWT Bearer) that can request the required scopes. ` +
+        `Browser user auth (Authorization Code + PKCE or implicit) is not supported by SCAPI Admin APIs ` +
+        `as of B2C Commerce release ${SCAPI_CAPABILITY_BASELINE_RELEASE} and is currently OCAPI/WebDAV-only; ` +
+        `fixed-token stored sessions cannot request SCAPI scopes — ` +
+        `use client-credentials/JWT, or set --api-backend ocapi for now. ` +
+        `The tooling will be updated when SCAPI support becomes available.`);
+}
+/**
+ * Generic tri-state backend resolver shared by SCAPI-vs-OCAPI and SCAPI-vs-legacy
+ * domains — the single definition of the preference/availability precedence.
+ *
+ * - Explicit primary → primary.
+ * - Explicit `'scapi'` → `'scapi'`, throwing `unavailableMessage()` when the SCAPI
+ *   config is missing (fail loud; never silently downgrade).
+ * - `'auto'` → `'scapi'` when config is available, otherwise the primary backend.
+ */
+export function resolvePreferredBackend(opts) {
+    const { preference, primary, hasScapiConfig, unavailableMessage } = opts;
+    if (preference === primary)
+        return primary;
+    if (preference === 'scapi') {
+        if (!hasScapiConfig) {
+            throw new Error(unavailableMessage());
+        }
+        return 'scapi';
+    }
+    // auto
+    return hasScapiConfig ? 'scapi' : primary;
+}
+/**
+ * Resolves a user preference + config availability into a concrete backend choice.
+ *
+ * - Explicit `'ocapi'` always returns `'ocapi'`.
+ * - Explicit `'scapi'` requires SCAPI config and throws if missing.
+ * - `'auto'` returns `'scapi'` if SCAPI config is available, otherwise `'ocapi'`.
+ *
+ * Throws an error with the domain name in the message when explicit SCAPI is
+ * requested without the required configuration. The error identifies release
+ * 26.8 as the current platform capability baseline so it can be revised when
+ * SCAPI adds support.
+ */
+export function resolveScapiOrOcapi(opts) {
+    const { preference, hasScapiConfig, domainName } = opts;
+    return resolvePreferredBackend({
+        preference,
+        primary: 'ocapi',
+        hasScapiConfig,
+        unavailableMessage: () => scapiUnavailableMessage(domainName),
+    });
+}
+//# sourceMappingURL=scapi-backend-utils.js.map

package/dist/esm/clients/scapi-backend-utils.js.map

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

package/dist/esm/clients/scapi-catalogs.d.ts

@@ -0,0 +1,12 @@
+import type { Client } from 'openapi-fetch';
+import type { AuthStrategy } from '../auth/types.js';
+import type { paths, components } from './scapi-catalogs.generated.js';
+import { type ScapiClientConfig } from './scapi-client-factory.js';
+import type { ScopeCascade } from './middleware.js';
+export type { paths, components };
+export type ScapiCatalogsClient = Client<paths>;
+export type ScapiCatalogsClientConfig = ScapiClientConfig;
+export type Catalog = components['schemas']['Catalog'];
+export type Catalogs = components['schemas']['Catalogs'];
+export declare const SCAPI_CATALOGS_CASCADE: ScopeCascade;
+export declare function createScapiCatalogsClient(config: ScapiCatalogsClientConfig, auth: AuthStrategy): ScapiCatalogsClient;

package/dist/esm/clients/scapi-catalogs.generated.d.ts

@@ -0,0 +1,104 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/organizations/{organizationId}/catalogs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getCatalogs"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        Catalog: {
+            id: string;
+            name?: {
+                [key: string]: string;
+            };
+            description?: {
+                [key: string]: string;
+            };
+            online?: boolean;
+        } & {
+            [key: string]: unknown;
+        };
+        Catalogs: {
+            data: components["schemas"]["Catalog"][];
+            limit: number;
+            offset: number;
+            total: number;
+        };
+        ErrorResponse: {
+            title: string;
+            type: string;
+            detail: string;
+            instance?: string;
+        } & {
+            [key: string]: unknown;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    getCatalogs: {
+        parameters: {
+            query?: {
+                limit?: number;
+                offset?: number;
+            };
+            header?: never;
+            path: {
+                organizationId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Catalogs retrieved successfully. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Catalogs"];
+                };
+            };
+            /** @description Bad Request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+}

package/dist/esm/clients/scapi-catalogs.generated.js

@@ -0,0 +1,6 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};
+//# sourceMappingURL=scapi-catalogs.generated.js.map

package/dist/esm/clients/scapi-catalogs.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scapi-catalogs.generated.js","sourceRoot":"","sources":["../../../src/clients/scapi-catalogs.generated.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/esm/clients/scapi-catalogs.js

@@ -0,0 +1,14 @@
+import { buildScapiClient } from './scapi-client-factory.js';
+export const SCAPI_CATALOGS_CASCADE = {
+    read: [['sfcc.catalogs.rw'], ['sfcc.catalogs']],
+    write: [['sfcc.catalogs.rw']],
+};
+export function createScapiCatalogsClient(config, auth) {
+    return buildScapiClient({
+        pathSegment: 'product/catalogs/v1',
+        domainKey: 'scapi-catalogs',
+        scopeCascade: SCAPI_CATALOGS_CASCADE,
+        logPrefix: 'SCAPI-CATALOGS',
+    }, config, auth);
+}
+//# sourceMappingURL=scapi-catalogs.js.map

package/dist/esm/clients/scapi-catalogs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scapi-catalogs.js","sourceRoot":"","sources":["../../../src/clients/scapi-catalogs.ts"],"names":[],"mappings":"AAQA,OAAO,EAAC,gBAAgB,EAAyB,MAAM,2BAA2B,CAAC;AASnF,MAAM,CAAC,MAAM,sBAAsB,GAAiB;IAClD,IAAI,EAAE,CAAC,CAAC,kBAAkB,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,kBAAkB,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,UAAU,yBAAyB,CAAC,MAAiC,EAAE,IAAkB;IAC7F,OAAO,gBAAgB,CACrB;QACE,WAAW,EAAE,qBAAqB;QAClC,SAAS,EAAE,gBAAgB;QAC3B,YAAY,EAAE,sBAAsB;QACpC,SAAS,EAAE,gBAAgB;KAC5B,EACD,MAAM,EACN,IAAI,CACL,CAAC;AACJ,CAAC"}

package/dist/esm/clients/scapi-client-factory.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Generic builder for SCAPI Admin API clients.
+ *
+ * The four new SCAPI clients (jobs, scripts, merchant-users, merchant-roles)
+ * each had ~20 lines of nearly-identical setup: build the openapi-fetch
+ * client with a domain URL, install auth middleware with merged scopes,
+ * install plugin middleware from the registry, then rate-limit and logging.
+ *
+ * This module collapses that setup into one helper.
+ *
+ * @module clients/scapi-client-factory
+ */
+import { type Client } from 'openapi-fetch';
+import type { AuthStrategy } from '../auth/types.js';
+import { type ScopeCascade } from './middleware.js';
+import { type HttpClientType, type MiddlewareRegistry } from './middleware-registry.js';
+export interface BuildScapiClientOptions {
+    /**
+     * URL path segment after the SCAPI host root, e.g. `'operation/jobs/v1'`.
+     */
+    pathSegment: string;
+    /**
+     * Middleware registry key, e.g. `'scapi-jobs'`. Plugin middleware
+     * registered under this key gets installed on the client.
+     */
+    domainKey: HttpClientType;
+    /**
+     * Per-operation scope cascade. When supplied, operations attach a
+     * `x-b2c-scope-mode` header (`'read'` or `'write'`) and the auth
+     * middleware walks the matching cascade until AM accepts one. Mutually
+     * exclusive with {@link defaultScopes}; new domains should prefer this.
+     */
+    scopeCascade?: ScopeCascade;
+    /**
+     * Legacy: a single scope set requested for every operation. Used by
+     * domains that still rely on `ScopeTierManager` to switch clients
+     * between rw and ro. Mutually exclusive with {@link scopeCascade}.
+     *
+     * @deprecated Use {@link scopeCascade} for new domains.
+     */
+    defaultScopes?: string[];
+    /**
+     * Logging/rate-limit prefix, e.g. `'SCAPI-JOBS'`. Used in log lines.
+     */
+    logPrefix: string;
+}
+export interface ScapiClientConfig {
+    shortCode: string;
+    tenantId: string;
+    /**
+     * Override the requested scopes. When omitted, defaults to
+     * `[...defaultScopes, buildTenantScope(tenantId)]`.
+     */
+    scopes?: string[];
+    /** Override the global middleware registry (mainly for tests). */
+    middlewareRegistry?: MiddlewareRegistry;
+}
+/**
+ * Builds a typed openapi-fetch client for a SCAPI Admin API.
+ *
+ * @param options - Domain-specific URL/key/scopes/log-prefix
+ * @param config - Caller-supplied shortCode, tenantId, optional overrides
+ * @param auth - Auth strategy (scopes are merged via {@link withScopes})
+ *
+ * @example
+ * ```ts
+ * export function createScapiJobsClient(config: ScapiClientConfig, auth: AuthStrategy): ScapiJobsClient {
+ *   return buildScapiClient<paths>(
+ *     {
+ *       pathSegment: 'operation/jobs/v1',
+ *       domainKey: 'scapi-jobs',
+ *       defaultScopes: SCAPI_JOBS_RW_SCOPES,
+ *       logPrefix: 'SCAPI-JOBS',
+ *     },
+ *     config,
+ *     auth,
+ *   );
+ * }
+ * ```
+ */
+export declare function buildScapiClient<P extends Record<string, any>>(options: BuildScapiClientOptions, config: ScapiClientConfig, auth: AuthStrategy): Client<P>;

package/dist/esm/clients/scapi-client-factory.js

@@ -0,0 +1,84 @@
+/*
+ * 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
+ */
+/**
+ * Generic builder for SCAPI Admin API clients.
+ *
+ * The four new SCAPI clients (jobs, scripts, merchant-users, merchant-roles)
+ * each had ~20 lines of nearly-identical setup: build the openapi-fetch
+ * client with a domain URL, install auth middleware with merged scopes,
+ * install plugin middleware from the registry, then rate-limit and logging.
+ *
+ * This module collapses that setup into one helper.
+ *
+ * @module clients/scapi-client-factory
+ */
+import createClient, {} from 'openapi-fetch';
+import { createAuthMiddleware, createLoggingMiddleware, createRateLimitMiddleware, createScapiAuthMiddleware, } from './middleware.js';
+import { globalMiddlewareRegistry } from './middleware-registry.js';
+import { buildTenantScope } from './custom-apis.js';
+import { withScopes } from './scapi-backend-utils.js';
+/**
+ * Builds a typed openapi-fetch client for a SCAPI Admin API.
+ *
+ * @param options - Domain-specific URL/key/scopes/log-prefix
+ * @param config - Caller-supplied shortCode, tenantId, optional overrides
+ * @param auth - Auth strategy (scopes are merged via {@link withScopes})
+ *
+ * @example
+ * ```ts
+ * export function createScapiJobsClient(config: ScapiClientConfig, auth: AuthStrategy): ScapiJobsClient {
+ *   return buildScapiClient<paths>(
+ *     {
+ *       pathSegment: 'operation/jobs/v1',
+ *       domainKey: 'scapi-jobs',
+ *       defaultScopes: SCAPI_JOBS_RW_SCOPES,
+ *       logPrefix: 'SCAPI-JOBS',
+ *     },
+ *     config,
+ *     auth,
+ *   );
+ * }
+ * ```
+ */
+// `paths` types from openapi-typescript are `interface paths { ... }` shapes
+// which don't satisfy `Record<string, unknown>`. The unconstrained generic
+// is fine since openapi-fetch's `Client<P>` constraint handles the shape check.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildScapiClient(options, config, auth) {
+    const registry = config.middlewareRegistry ?? globalMiddlewareRegistry;
+    if (options.scopeCascade && options.defaultScopes) {
+        throw new Error(`[buildScapiClient] ${options.domainKey}: scopeCascade and defaultScopes are mutually exclusive.`);
+    }
+    if (!options.scopeCascade && !options.defaultScopes) {
+        throw new Error(`[buildScapiClient] ${options.domainKey}: must provide either scopeCascade or defaultScopes.`);
+    }
+    const client = createClient({
+        baseUrl: `https://${config.shortCode}.api.commercecloud.salesforce.com/${options.pathSegment}`,
+    });
+    if (options.scopeCascade) {
+        // Cascade-aware path: bake the tenant scope into the auth strategy as a
+        // "base scope" applied to every cascade attempt; the cascade itself only
+        // varies the domain (rw/ro) scope per operation.
+        const tenantBase = config.scopes ?? [buildTenantScope(config.tenantId)];
+        const scopedAuth = withScopes(auth, tenantBase);
+        client.use(createScapiAuthMiddleware(scopedAuth, options.scopeCascade));
+    }
+    else {
+        // Legacy path: single static scope set requested for every operation.
+        // Used by domains still on ScopeTierManager (scripts/users/roles until
+        // they migrate to scopeCascade).
+        const requiredScopes = config.scopes ?? [...options.defaultScopes, buildTenantScope(config.tenantId)];
+        const scopedAuth = withScopes(auth, requiredScopes);
+        client.use(createAuthMiddleware(scopedAuth));
+    }
+    for (const middleware of registry.getMiddleware(options.domainKey)) {
+        client.use(middleware);
+    }
+    client.use(createRateLimitMiddleware({ prefix: options.logPrefix }));
+    client.use(createLoggingMiddleware(options.logPrefix));
+    return client;
+}
+//# sourceMappingURL=scapi-client-factory.js.map

package/dist/esm/clients/scapi-client-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scapi-client-factory.js","sourceRoot":"","sources":["../../../src/clients/scapi-client-factory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;GAWG;AACH,OAAO,YAAY,EAAE,EAAa,MAAM,eAAe,CAAC;AAExD,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,GAE1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAC,wBAAwB,EAA+C,MAAM,0BAA0B,CAAC;AAChH,OAAO,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAC,UAAU,EAAC,MAAM,0BAA0B,CAAC;AA6CpD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,6EAA6E;AAC7E,2EAA2E;AAC3E,gFAAgF;AAChF,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAC9B,OAAgC,EAChC,MAAyB,EACzB,IAAkB;IAElB,MAAM,QAAQ,GAAG,MAAM,CAAC,kBAAkB,IAAI,wBAAwB,CAAC;IAEvE,IAAI,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,sBAAsB,OAAO,CAAC,SAAS,0DAA0D,CAAC,CAAC;IACrH,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,sBAAsB,OAAO,CAAC,SAAS,sDAAsD,CAAC,CAAC;IACjH,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAI;QAC7B,OAAO,EAAE,WAAW,MAAM,CAAC,SAAS,qCAAqC,OAAO,CAAC,WAAW,EAAE;KAC/F,CAAC,CAAC;IAEH,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzB,wEAAwE;QACxE,yEAAyE;QACzE,iDAAiD;QACjD,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QACxE,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAChD,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,UAAU,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IAC1E,CAAC;SAAM,CAAC;QACN,sEAAsE;QACtE,uEAAuE;QACvE,iCAAiC;QACjC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,OAAO,CAAC,aAAc,EAAE,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QACvG,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QACpD,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,MAAM,UAAU,IAAI,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACnE,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,EAAC,MAAM,EAAE,OAAO,CAAC,SAAS,EAAC,CAAC,CAAC,CAAC;IACnE,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IAEvD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/esm/clients/scapi-fallback-backend.d.ts

@@ -0,0 +1,34 @@
+import { type BackendBase } from './scapi-backend-utils.js';
+/**
+ * Creates a fallback wrapper over `scapi` and `ocapi` backends.
+ *
+ * The returned object presents the same interface as `T`. Method calls are
+ * intercepted: the first call tries SCAPI; on a safe fallback trigger it falls back
+ * to OCAPI. The choice is cached for the wrapper's lifetime.
+ *
+ * **Contract:**
+ * - Both `scapi` and `ocapi` must implement `T`. TypeScript enforces this
+ *   at the call site since both are typed as `T`.
+ * - Only methods of `T` are routed through the fallback logic. The `name`
+ *   getter is special-cased to reflect the resolved backend.
+ * - **Non-method properties** are returned from the SCAPI target only and
+ *   are not switched on fallback. By convention, backends should be method
+ *   bags — any state beyond `name` should be encapsulated, not exposed.
+ * - **Concurrency:** if two calls race before resolution, both may attempt
+ *   SCAPI. This is benign for read operations (idempotent retries) and
+ *   acceptable for writes (both either succeed or fail with the same
+ *   error). Each Proxy instance has its own state, so this concerns only
+ *   shared use of a single wrapper.
+ *
+ * @param scapi - Primary (SCAPI) backend implementation
+ * @param ocapi - Fallback (OCAPI) backend implementation
+ * @param domainName - Used in fallback log messages, e.g. `'jobs'`
+ * @returns A Proxy over `scapi` whose methods route through fallback logic
+ *
+ * @example
+ * ```ts
+ * const backend = createFallbackBackend<JobsBackend>(scapiJobs, ocapiJobs, 'jobs');
+ * await backend.executeJob('my-job'); // tries SCAPI, may fall back to OCAPI
+ * ```
+ */
+export declare function createFallbackBackend<T extends BackendBase>(scapi: T, ocapi: T, domainName: string): T;