@salesforce/b2c-tooling-sdk 1.24.2 → 2.1.0

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

@@ -0,0 +1,132 @@
+/*
+ * 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 fallback wrapper for SCAPI/OCAPI dual backends.
+ *
+ * Builds a Proxy that implements the same interface as the underlying
+ * backends. Each method call routes through {@link withFallback}: try SCAPI
+ * first; on a recognized safe fallback trigger (for example `invalid_scope`,
+ * a typed rejected HTTP response, or a SCAPI-side capability gap), fall back to
+ * OCAPI for that call and pin to OCAPI for the rest of the wrapper's life.
+ * Note that a successful SCAPI call only pins *softly* — a later call that
+ * trips a fallback trigger still routes to OCAPI and re-pins, so a flow
+ * that reads under a read-only scope and then needs to write isn't stuck.
+ * The `name` property reflects the currently-active backend ('scapi' before
+ * the first call resolves, then whichever survived).
+ *
+ * @module clients/scapi-fallback-backend
+ */
+import { getLogger } from '../logging/logger.js';
+import { isFallbackTrigger } from './scapi-backend-utils.js';
+/**
+ * Wraps a SCAPI call with automatic OCAPI fallback on a recognized
+ * fallback trigger ({@link isFallbackTrigger}).
+ *
+ * Standalone helper so the Proxy traps and any future direct callers share
+ * one definition.
+ */
+async function withFallback(state, fn) {
+    // Once we've fallen back to OCAPI, stay there — there's no SCAPI surface to
+    // re-attempt. Errors propagate from OCAPI directly.
+    if (state.resolved === state.ocapi) {
+        return fn(state.ocapi);
+    }
+    // Either unresolved (first call), or already pinned to SCAPI by a prior
+    // successful call. We still try SCAPI, but a fallback-trigger error here
+    // routes this call through OCAPI and re-pins. This handles the case where
+    // a read succeeds (pinning SCAPI) and then a write fails because the
+    // ScopeTierManager has been downgraded to read-only — the write should
+    // still satisfy through OCAPI rather than throwing.
+    const target = state.resolved ?? state.scapi;
+    try {
+        const result = await fn(target);
+        if (!state.resolved)
+            state.resolved = state.scapi;
+        return result;
+    }
+    catch (error) {
+        if (isFallbackTrigger(error)) {
+            getLogger().info(`SCAPI ${state.domainName} unavailable for this operation, falling back to OCAPI`);
+            state.resolved = state.ocapi;
+            return fn(state.ocapi);
+        }
+        throw error;
+    }
+}
+/**
+ * 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 function createFallbackBackend(scapi, ocapi, domainName) {
+    const state = { scapi, ocapi, domainName };
+    return new Proxy(scapi, {
+        get(target, prop, receiver) {
+            // Special property: `name` reflects whichever backend has handled requests so far.
+            if (prop === 'name') {
+                return (state.resolved ?? scapi).name;
+            }
+            const value = Reflect.get(target, prop, receiver);
+            // Non-functions (constants, getters): return as-is from the SCAPI backend.
+            // Wrappers don't currently expose any non-method state besides `name`,
+            // but this keeps the Proxy transparent for property access.
+            if (typeof value !== 'function') {
+                return value;
+            }
+            // For each method, return a wrapper that routes the call through fallback.
+            // We must look up the method by name on the resolved backend (not on the
+            // SCAPI target we're proxying), since the OCAPI backend may have a
+            // different implementation.
+            //
+            // If the method is missing from OCAPI (e.g., a SCAPI-only capability like
+            // delete), don't attempt a fallback — let SCAPI handle it directly.
+            // The caller should use the type-guard pattern (e.g. supportsDeleteJobExecution)
+            // to detect this before calling.
+            const ocapiHasMethod = typeof ocapi[prop] === 'function';
+            if (!ocapiHasMethod) {
+                return (...args) => {
+                    const fn = scapi[prop];
+                    return fn.apply(scapi, args);
+                };
+            }
+            return (...args) => withFallback(state, (backend) => {
+                const fn = backend[prop];
+                if (typeof fn !== 'function') {
+                    throw new TypeError(`Method ${String(prop)} is not a function on ${backend.name} backend`);
+                }
+                return fn.apply(backend, args);
+            });
+        },
+    });
+}
+//# sourceMappingURL=scapi-fallback-backend.js.map

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

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

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

@@ -0,0 +1,32 @@
+import type { Client } from 'openapi-fetch';
+import type { AuthStrategy } from '../auth/types.js';
+import type { paths, components } from './scapi-jobs.generated.js';
+import { type ScapiClientConfig } from './scapi-client-factory.js';
+import { buildTenantScope, toOrganizationId, normalizeTenantId } from './custom-apis.js';
+import type { ScopeCascade } from './middleware.js';
+export { toOrganizationId, normalizeTenantId, buildTenantScope };
+export type { paths, components };
+export type ScapiJobsClient = Client<paths>;
+export type ScapiJobsResponse<T> = T extends {
+    content: {
+        'application/json': infer R;
+    };
+} ? R : never;
+export type ScapiJobsError = components['schemas']['ErrorResponse'];
+export type JobExecution = components['schemas']['JobExecution'];
+export type JobStepExecution = components['schemas']['JobStepExecution'];
+export type JobParameter = components['schemas']['JobParameter'];
+export type ExecutionStatus = components['schemas']['ExecutionStatus'];
+export type ExitStatus = components['schemas']['ExitStatus'];
+export type JobExecutionSearchResult = components['schemas']['JobExecutionSearchResult'];
+/**
+ * Per-operation scope cascade for SCAPI Jobs.
+ *
+ * Reads accept either rw or ro; writes require rw. The auth middleware tries
+ * each candidate against AM in order, caches the first that survives, and
+ * lets a broader cached token satisfy a later narrower request without an
+ * extra round trip.
+ */
+export declare const SCAPI_JOBS_CASCADE: ScopeCascade;
+export type ScapiJobsClientConfig = ScapiClientConfig;
+export declare function createScapiJobsClient(config: ScapiJobsClientConfig, auth: AuthStrategy): ScapiJobsClient;