@salesforce/b2c-tooling-sdk 1.24.2 → 2.0.0

package/dist/esm/clients/scapi-merchant-roles.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-merchant-roles.generated.js.map

package/dist/esm/clients/scapi-merchant-roles.generated.js.map

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

package/dist/esm/clients/scapi-merchant-roles.js

@@ -0,0 +1,12 @@
+import { buildScapiClient } from './scapi-client-factory.js';
+export const SCAPI_MERCHANT_ROLES_READ_SCOPES = ['sfcc.roles'];
+export const SCAPI_MERCHANT_ROLES_RW_SCOPES = ['sfcc.roles.rw'];
+export function createScapiMerchantRolesClient(config, auth) {
+    return buildScapiClient({
+        pathSegment: 'merchant/roles/v1',
+        domainKey: 'scapi-merchant-roles',
+        defaultScopes: SCAPI_MERCHANT_ROLES_RW_SCOPES,
+        logPrefix: 'SCAPI-ROLES',
+    }, config, auth);
+}
+//# sourceMappingURL=scapi-merchant-roles.js.map

package/dist/esm/clients/scapi-merchant-roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scapi-merchant-roles.js","sourceRoot":"","sources":["../../../src/clients/scapi-merchant-roles.ts"],"names":[],"mappings":"AAQA,OAAO,EAAC,gBAAgB,EAAyB,MAAM,2BAA2B,CAAC;AAWnF,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,YAAY,CAAC,CAAC;AAC/D,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,eAAe,CAAC,CAAC;AAIhE,MAAM,UAAU,8BAA8B,CAC5C,MAAsC,EACtC,IAAkB;IAElB,OAAO,gBAAgB,CACrB;QACE,WAAW,EAAE,mBAAmB;QAChC,SAAS,EAAE,sBAAsB;QACjC,aAAa,EAAE,8BAA8B;QAC7C,SAAS,EAAE,aAAa;KACzB,EACD,MAAM,EACN,IAAI,CACL,CAAC;AACJ,CAAC"}

package/dist/esm/clients/scapi-merchant-users.d.ts

@@ -0,0 +1,19 @@
+import type { Client } from 'openapi-fetch';
+import type { AuthStrategy } from '../auth/types.js';
+import type { paths, components } from './scapi-merchant-users.generated.js';
+import { type ScapiClientConfig } from './scapi-client-factory.js';
+export type { paths, components };
+export type ScapiMerchantUsersClient = Client<paths>;
+export type ScapiMerchantUsersResponse<T> = T extends {
+    content: {
+        'application/json': infer R;
+    };
+} ? R : never;
+export type ScapiMerchantUsersError = components['schemas']['ErrorResponse'];
+export type User = components['schemas']['User'];
+export type UserUpdateRequest = components['schemas']['UserUpdateRequest'];
+export type UserSearch = components['schemas']['UserSearch'];
+export declare const SCAPI_MERCHANT_USERS_READ_SCOPES: string[];
+export declare const SCAPI_MERCHANT_USERS_RW_SCOPES: string[];
+export type ScapiMerchantUsersClientConfig = ScapiClientConfig;
+export declare function createScapiMerchantUsersClient(config: ScapiMerchantUsersClientConfig, auth: AuthStrategy): ScapiMerchantUsersClient;

package/dist/esm/clients/scapi-merchant-users.generated.d.ts

@@ -0,0 +1,300 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/organizations/{organizationId}/users": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getUsers"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/organizations/{organizationId}/users/{login}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getUser"];
+        put: operations["createOrReplaceUser"];
+        post?: never;
+        delete: operations["deleteUser"];
+        options?: never;
+        head?: never;
+        patch: operations["updateUser"];
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        OrganizationId: string;
+        Select: string;
+        /**
+         * Format: int32
+         * @default 0
+         */
+        Total: number;
+        ResultBase: {
+            /** Format: int32 */
+            limit: number;
+            total: components["schemas"]["Total"];
+        };
+        /**
+         * Format: int32
+         * @default 0
+         */
+        Offset: number;
+        PaginatedResultBase: {
+            offset: components["schemas"]["Offset"];
+        } & WithRequired<components["schemas"]["ResultBase"], "limit" | "total">;
+        LanguageCountry: string;
+        LanguageCode: string;
+        /** @default default */
+        DefaultFallback: string;
+        LocaleCode: components["schemas"]["LanguageCountry"] | components["schemas"]["LanguageCode"] | components["schemas"]["DefaultFallback"];
+        User: {
+            login: string;
+            password?: string;
+            email: string;
+            firstName?: string;
+            lastName?: string;
+            externalId?: string;
+            disabled?: boolean;
+            locked?: boolean;
+            /** Format: date */
+            lastLoginDate?: string;
+            /** Format: date-time */
+            passwordExpirationDate?: string;
+            /** Format: date-time */
+            passwordModificationDate?: string;
+            preferredDataLocale?: components["schemas"]["LocaleCode"];
+            preferredUiLocale?: components["schemas"]["LocaleCode"];
+            roles?: string[];
+        };
+        UserSearch: {
+            data: components["schemas"]["User"][];
+        } & components["schemas"]["PaginatedResultBase"];
+        ErrorResponse: {
+            title: string;
+            type: string;
+            detail: string;
+            instance?: string;
+        } & {
+            [key: string]: unknown;
+        };
+        UserUpdateRequest: {
+            email?: string;
+            firstName?: string;
+            lastName?: string;
+            externalId?: string;
+            preferredDataLocale?: components["schemas"]["LocaleCode"];
+            preferredUiLocale?: components["schemas"]["LocaleCode"];
+        };
+    };
+    responses: never;
+    parameters: {
+        organizationId: components["schemas"]["OrganizationId"];
+        select: components["schemas"]["Select"];
+        login: string;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    getUsers: {
+        parameters: {
+            query?: {
+                select?: components["schemas"]["Select"];
+                limit?: number;
+                offset?: number;
+            };
+            header?: never;
+            path: {
+                organizationId: components["schemas"]["OrganizationId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Returns the collection of users */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["UserSearch"];
+                };
+            };
+        };
+    };
+    getUser: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                organizationId: components["schemas"]["OrganizationId"];
+                login: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Returns the user details */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["User"];
+                };
+            };
+            /** @description User not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    createOrReplaceUser: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                organizationId: components["schemas"]["OrganizationId"];
+                login: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["User"];
+            };
+        };
+        responses: {
+            /** @description The user was successfully updated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["User"];
+                };
+            };
+            /** @description The user was successfully created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["User"];
+                };
+            };
+            /** @description Bad Request - Invalid user request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    deleteUser: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                organizationId: components["schemas"]["OrganizationId"];
+                login: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The user was successfully deleted */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description User not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    updateUser: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                organizationId: components["schemas"]["OrganizationId"];
+                login: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["UserUpdateRequest"];
+            };
+        };
+        responses: {
+            /** @description The user was successfully updated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["User"];
+                };
+            };
+            /** @description Bad Request - Invalid user update request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description User not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+}
+type WithRequired<T, K extends keyof T> = T & {
+    [P in K]-?: T[P];
+};
+export {};

package/dist/esm/clients/scapi-merchant-users.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-merchant-users.generated.js.map

package/dist/esm/clients/scapi-merchant-users.generated.js.map

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

package/dist/esm/clients/scapi-merchant-users.js

@@ -0,0 +1,12 @@
+import { buildScapiClient } from './scapi-client-factory.js';
+export const SCAPI_MERCHANT_USERS_READ_SCOPES = ['sfcc.users'];
+export const SCAPI_MERCHANT_USERS_RW_SCOPES = ['sfcc.users.rw'];
+export function createScapiMerchantUsersClient(config, auth) {
+    return buildScapiClient({
+        pathSegment: 'merchant/users/v1',
+        domainKey: 'scapi-merchant-users',
+        defaultScopes: SCAPI_MERCHANT_USERS_RW_SCOPES,
+        logPrefix: 'SCAPI-USERS',
+    }, config, auth);
+}
+//# sourceMappingURL=scapi-merchant-users.js.map

package/dist/esm/clients/scapi-merchant-users.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scapi-merchant-users.js","sourceRoot":"","sources":["../../../src/clients/scapi-merchant-users.ts"],"names":[],"mappings":"AAQA,OAAO,EAAC,gBAAgB,EAAyB,MAAM,2BAA2B,CAAC;AAWnF,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,YAAY,CAAC,CAAC;AAC/D,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,eAAe,CAAC,CAAC;AAIhE,MAAM,UAAU,8BAA8B,CAC5C,MAAsC,EACtC,IAAkB;IAElB,OAAO,gBAAgB,CACrB;QACE,WAAW,EAAE,mBAAmB;QAChC,SAAS,EAAE,sBAAsB;QACjC,aAAa,EAAE,8BAA8B;QAC7C,SAAS,EAAE,aAAa;KACzB,EACD,MAAM,EACN,IAAI,CACL,CAAC;AACJ,CAAC"}

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

@@ -13,11 +13,10 @@
  * @module clients/scapi-schemas
  */
 import createClient, {} from 'openapi-fetch';
-import { OAuthStrategy } from '../auth/oauth.js';
-import { JwtOAuthStrategy } from '../auth/oauth-jwt.js';
 import { createAuthMiddleware, createLoggingMiddleware } from './middleware.js';
 import { globalMiddlewareRegistry } from './middleware-registry.js';
 import { toOrganizationId, normalizeTenantId, buildTenantScope } from './custom-apis.js';
+import { withScopes } from './scapi-backend-utils.js';
 /**
  * Re-export organization/tenant utilities for convenience.
  */
@@ -82,9 +81,7 @@ export function createScapiSchemasClient(config, auth) {
     // Build required scopes: domain scope + tenant-specific scope
     const requiredScopes = config.scopes ?? [...SCAPI_SCHEMAS_DEFAULT_SCOPES, buildTenantScope(config.tenantId)];
     // If auth supports scopes, add required scopes; otherwise use as-is
-    const scopedAuth = auth instanceof OAuthStrategy || auth instanceof JwtOAuthStrategy
-        ? auth.withAdditionalScopes(requiredScopes)
-        : auth;
+    const scopedAuth = withScopes(auth, requiredScopes);
     // Core middleware: auth first
     client.use(createAuthMiddleware(scopedAuth));
     // Plugin middleware from registry

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

@@ -1 +1 @@
-{"version":3,"file":"scapi-schemas.js","sourceRoot":"","sources":["../../../src/clients/scapi-schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;GAQG;AACH,OAAO,YAAY,EAAE,EAAa,MAAM,eAAe,CAAC;AAExD,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAC,oBAAoB,EAAE,uBAAuB,EAAC,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAC,wBAAwB,EAA0B,MAAM,0BAA0B,CAAC;AAC3F,OAAO,EAAC,gBAAgB,EAAE,iBAAiB,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAOvF;;GAEG;AACH,OAAO,EAAC,gBAAgB,EAAE,iBAAiB,EAAE,gBAAgB,EAAC,CAAC;AA+D/D,kEAAkE;AAClE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAiCnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAgC,EAAE,IAAkB;IAC3F,MAAM,QAAQ,GAAG,MAAM,CAAC,kBAAkB,IAAI,wBAAwB,CAAC;IAEvE,MAAM,MAAM,GAAG,YAAY,CAAQ;QACjC,OAAO,EAAE,WAAW,MAAM,CAAC,SAAS,uDAAuD;KAC5F,CAAC,CAAC;IAEH,8DAA8D;IAC9D,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,4BAA4B,EAAE,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE7G,oEAAoE;IACpE,MAAM,UAAU,GACd,IAAI,YAAY,aAAa,IAAI,IAAI,YAAY,gBAAgB;QAC/D,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,cAAc,CAAC;QAC3C,CAAC,CAAC,IAAI,CAAC;IAEX,8BAA8B;IAC9B,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC,CAAC;IAE7C,kCAAkC;IAClC,KAAK,MAAM,UAAU,IAAI,QAAQ,CAAC,aAAa,CAAC,eAAe,CAAC,EAAE,CAAC;QACjE,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACzB,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,eAAe,CAAC,CAAC,CAAC;IAErD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"scapi-schemas.js","sourceRoot":"","sources":["../../../src/clients/scapi-schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;GAQG;AACH,OAAO,YAAY,EAAE,EAAa,MAAM,eAAe,CAAC;AAGxD,OAAO,EAAC,oBAAoB,EAAE,uBAAuB,EAAC,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAC,wBAAwB,EAA0B,MAAM,0BAA0B,CAAC;AAC3F,OAAO,EAAC,gBAAgB,EAAE,iBAAiB,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AACvF,OAAO,EAAC,UAAU,EAAC,MAAM,0BAA0B,CAAC;AAOpD;;GAEG;AACH,OAAO,EAAC,gBAAgB,EAAE,iBAAiB,EAAE,gBAAgB,EAAC,CAAC;AA+D/D,kEAAkE;AAClE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAiCnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAgC,EAAE,IAAkB;IAC3F,MAAM,QAAQ,GAAG,MAAM,CAAC,kBAAkB,IAAI,wBAAwB,CAAC;IAEvE,MAAM,MAAM,GAAG,YAAY,CAAQ;QACjC,OAAO,EAAE,WAAW,MAAM,CAAC,SAAS,uDAAuD;KAC5F,CAAC,CAAC;IAEH,8DAA8D;IAC9D,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,4BAA4B,EAAE,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE7G,oEAAoE;IACpE,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IAEpD,8BAA8B;IAC9B,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC,CAAC;IAE7C,kCAAkC;IAClC,KAAK,MAAM,UAAU,IAAI,QAAQ,CAAC,aAAa,CAAC,eAAe,CAAC,EAAE,CAAC;QACjE,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACzB,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,eAAe,CAAC,CAAC,CAAC;IAErD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/esm/clients/scapi-scope-tier.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Scope-tier client manager for SCAPI domains with dual scopes.
+ *
+ * Many SCAPI Admin APIs expose two scopes — read-only and read-write
+ * (e.g., `sfcc.jobs` and `sfcc.jobs.rw`). A given API client may have only
+ * one of them configured in Account Manager. The optimistic strategy is to
+ * request `rw` first and downgrade to read-only only when `invalid_scope`
+ * is detected on a read operation.
+ *
+ * `ScopeTierManager` encapsulates that state machine so each SCAPI backend
+ * doesn't have to reimplement it. Write operations always require `rw`;
+ * if we already know the client only has read scope, the manager throws
+ * a descriptive error rather than making a doomed request.
+ *
+ * @module clients/scapi-scope-tier
+ */
+export type ScopeTier = 'rw' | 'read-only';
+export interface ScopeTierManagerOptions<C> {
+    /** Builds a typed SCAPI client with the given OAuth scopes. */
+    buildClient(scopes: string[]): C;
+    /** Scopes for read-write operations, e.g., `['sfcc.jobs.rw']`. */
+    rwScopes: string[];
+    /** Scopes for read-only operations, e.g., `['sfcc.jobs']`. */
+    readScopes: string[];
+    /** Domain name surfaced in error messages, e.g. `'Jobs'`, `'Scripts'`. */
+    domainName: string;
+}
+/**
+ * Lazy-initialized manager for clients at different scope tiers.
+ *
+ * - First read or write call builds the rw client and caches it.
+ * - If the caller detects an `invalid_scope` error on a read attempt, it
+ *   calls `downgradeToReadOnly()` and the next read uses the read-only client.
+ * - Once downgraded, write requests throw — the API client lacks rw scope.
+ *
+ * The same rw client serves both read and write while the rw scope is valid;
+ * we only build a separate read-only client after a downgrade.
+ */
+export declare class ScopeTierManager<C> {
+    private opts;
+    private rwClient?;
+    private readClient?;
+    private resolved?;
+    constructor(opts: ScopeTierManagerOptions<C>);
+    /** The currently-resolved tier, or undefined before first use. */
+    get resolvedTier(): ScopeTier | undefined;
+    /**
+     * Returns a client suitable for write operations. Throws if we've already
+     * downgraded to read-only — the API client doesn't have the rw scope.
+     *
+     * Throws {@link ScapiCapabilityUnsupportedError} so the SCAPI/OCAPI
+     * fallback wrapper recognizes this as a capability gap and routes the
+     * write through OCAPI in `auto` mode (instead of pinning to SCAPI after
+     * a successful read and then failing the write).
+     */
+    getClientForWrite(): C;
+    /**
+     * Returns a client suitable for read operations. Prefers the rw client if
+     * it's already been used successfully (rw scope grants read too).
+     */
+    getClientForRead(): C;
+    /**
+     * Marks the rw scope as unavailable and builds a read-only client.
+     * Subsequent `getClientForWrite()` calls will throw; reads use the
+     * read-only client.
+     */
+    downgradeToReadOnly(): void;
+    /**
+     * Runs a read operation, downgrading to the read-only client and retrying
+     * once if the rw attempt fails with `invalid_scope`. Backends should wrap
+     * their reads with this so an API client provisioned with only the
+     * read-only scope (e.g. `sfcc.scripts`) can still read through SCAPI.
+     *
+     * Writes do not go through this helper — they always require rw, and
+     * `getClientForWrite()` already throws after a downgrade.
+     */
+    tryRead<R>(fn: (client: C) => Promise<R>): Promise<R>;
+}

package/dist/esm/clients/scapi-scope-tier.js

@@ -0,0 +1,113 @@
+/*
+ * 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
+ */
+/**
+ * Scope-tier client manager for SCAPI domains with dual scopes.
+ *
+ * Many SCAPI Admin APIs expose two scopes — read-only and read-write
+ * (e.g., `sfcc.jobs` and `sfcc.jobs.rw`). A given API client may have only
+ * one of them configured in Account Manager. The optimistic strategy is to
+ * request `rw` first and downgrade to read-only only when `invalid_scope`
+ * is detected on a read operation.
+ *
+ * `ScopeTierManager` encapsulates that state machine so each SCAPI backend
+ * doesn't have to reimplement it. Write operations always require `rw`;
+ * if we already know the client only has read scope, the manager throws
+ * a descriptive error rather than making a doomed request.
+ *
+ * @module clients/scapi-scope-tier
+ */
+import { isInvalidScopeError, ScapiCapabilityUnsupportedError } from './scapi-backend-utils.js';
+/**
+ * Lazy-initialized manager for clients at different scope tiers.
+ *
+ * - First read or write call builds the rw client and caches it.
+ * - If the caller detects an `invalid_scope` error on a read attempt, it
+ *   calls `downgradeToReadOnly()` and the next read uses the read-only client.
+ * - Once downgraded, write requests throw — the API client lacks rw scope.
+ *
+ * The same rw client serves both read and write while the rw scope is valid;
+ * we only build a separate read-only client after a downgrade.
+ */
+export class ScopeTierManager {
+    opts;
+    rwClient;
+    readClient;
+    resolved;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** The currently-resolved tier, or undefined before first use. */
+    get resolvedTier() {
+        return this.resolved;
+    }
+    /**
+     * Returns a client suitable for write operations. Throws if we've already
+     * downgraded to read-only — the API client doesn't have the rw scope.
+     *
+     * Throws {@link ScapiCapabilityUnsupportedError} so the SCAPI/OCAPI
+     * fallback wrapper recognizes this as a capability gap and routes the
+     * write through OCAPI in `auto` mode (instead of pinning to SCAPI after
+     * a successful read and then failing the write).
+     */
+    getClientForWrite() {
+        if (this.resolved === 'read-only') {
+            throw new ScapiCapabilityUnsupportedError(`SCAPI ${this.opts.domainName} API requires the "${this.opts.rwScopes.join(' ')}" scope. ` +
+                `Add this scope to your API client in Account Manager.`);
+        }
+        if (!this.rwClient) {
+            this.rwClient = this.opts.buildClient(this.opts.rwScopes);
+        }
+        this.resolved = 'rw';
+        return this.rwClient;
+    }
+    /**
+     * Returns a client suitable for read operations. Prefers the rw client if
+     * it's already been used successfully (rw scope grants read too).
+     */
+    getClientForRead() {
+        if (this.resolved === 'read-only') {
+            // Already downgraded; readClient is built in downgradeToReadOnly()
+            return this.readClient;
+        }
+        if (!this.rwClient) {
+            this.rwClient = this.opts.buildClient(this.opts.rwScopes);
+        }
+        this.resolved = 'rw';
+        return this.rwClient;
+    }
+    /**
+     * Marks the rw scope as unavailable and builds a read-only client.
+     * Subsequent `getClientForWrite()` calls will throw; reads use the
+     * read-only client.
+     */
+    downgradeToReadOnly() {
+        this.resolved = 'read-only';
+        this.readClient = this.opts.buildClient(this.opts.readScopes);
+    }
+    /**
+     * Runs a read operation, downgrading to the read-only client and retrying
+     * once if the rw attempt fails with `invalid_scope`. Backends should wrap
+     * their reads with this so an API client provisioned with only the
+     * read-only scope (e.g. `sfcc.scripts`) can still read through SCAPI.
+     *
+     * Writes do not go through this helper — they always require rw, and
+     * `getClientForWrite()` already throws after a downgrade.
+     */
+    async tryRead(fn) {
+        const client = this.getClientForRead();
+        try {
+            return await fn(client);
+        }
+        catch (error) {
+            if (this.resolved === 'read-only' || !isInvalidScopeError(error)) {
+                throw error;
+            }
+            this.downgradeToReadOnly();
+            return fn(this.readClient);
+        }
+    }
+}
+//# sourceMappingURL=scapi-scope-tier.js.map

package/dist/esm/clients/scapi-scope-tier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scapi-scope-tier.js","sourceRoot":"","sources":["../../../src/clients/scapi-scope-tier.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,mBAAmB,EAAE,+BAA+B,EAAC,MAAM,0BAA0B,CAAC;AAe9F;;;;;;;;;;GAUG;AACH,MAAM,OAAO,gBAAgB;IAKP;IAJZ,QAAQ,CAAK;IACb,UAAU,CAAK;IACf,QAAQ,CAAa;IAE7B,YAAoB,IAAgC;QAAhC,SAAI,GAAJ,IAAI,CAA4B;IAAG,CAAC;IAExD,kEAAkE;IAClE,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;;;;;OAQG;IACH,iBAAiB;QACf,IAAI,IAAI,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;YAClC,MAAM,IAAI,+BAA+B,CACvC,SAAS,IAAI,CAAC,IAAI,CAAC,UAAU,sBAAsB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW;gBACxF,uDAAuD,CAC1D,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,gBAAgB;QACd,IAAI,IAAI,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;YAClC,mEAAmE;YACnE,OAAO,IAAI,CAAC,UAAW,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,mBAAmB;QACjB,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAChE,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO,CAAI,EAA6B;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACvC,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,IAAI,CAAC,QAAQ,KAAK,WAAW,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjE,MAAM,KAAK,CAAC;YACd,CAAC;YACD,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC3B,OAAO,EAAE,CAAC,IAAI,CAAC,UAAW,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;CACF"}

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

@@ -0,0 +1,17 @@
+import type { Client } from 'openapi-fetch';
+import type { AuthStrategy } from '../auth/types.js';
+import type { paths, components } from './scapi-scripts.generated.js';
+import { type ScapiClientConfig } from './scapi-client-factory.js';
+export type { paths, components };
+export type ScapiScriptsClient = Client<paths>;
+export type ScapiScriptsResponse<T> = T extends {
+    content: {
+        'application/json': infer R;
+    };
+} ? R : never;
+export type ScapiScriptsError = components['schemas']['ErrorResponse'];
+export type CodeVersion = components['schemas']['CodeVersion'];
+export declare const SCAPI_SCRIPTS_READ_SCOPES: string[];
+export declare const SCAPI_SCRIPTS_RW_SCOPES: string[];
+export type ScapiScriptsClientConfig = ScapiClientConfig;
+export declare function createScapiScriptsClient(config: ScapiScriptsClientConfig, auth: AuthStrategy): ScapiScriptsClient;