@salesforce/b2c-tooling-sdk 2.3.0 → 2.5.0

package/dist/esm/clients/custom-apis.js

@@ -89,6 +89,53 @@ export const SCAPI_TENANT_SCOPE_PREFIX = 'SALESFORCE_COMMERCE_API:';
 export function toOrganizationId(tenantId) {
     return `${ORGANIZATION_ID_PREFIX}${normalizeTenantId(tenantId)}`;
 }
+/**
+ * Sandbox hostnames encode the tenant ID in their first label, for example
+ * `abcd-123.dx.commercecloud.salesforce.com` (tenant `abcd_123`).
+ */
+const SANDBOX_HOSTNAME_REGEX = /^([a-z\d]{4})-(\d{3})\.(?:[a-z\d-]+\.)*dx\.commercecloud\.salesforce\.com$/i;
+/**
+ * Derives a tenant ID from a sandbox hostname.
+ *
+ * Returns `undefined` for any hostname that doesn't follow the sandbox naming
+ * convention, so callers never infer a tenant from an ambiguous hostname such as
+ * a primary instance group host.
+ *
+ * @param hostname - Instance hostname
+ * @returns The tenant ID in canonical underscore format, or undefined
+ *
+ * @example
+ * tenantIdFromSandboxHostname('zzpq-013.dx.commercecloud.salesforce.com') // Returns 'zzpq_013'
+ * tenantIdFromSandboxHostname('staging-realm-customer.demandware.net')  // Returns undefined
+ */
+export function tenantIdFromSandboxHostname(hostname) {
+    const match = hostname.trim().match(SANDBOX_HOSTNAME_REGEX);
+    if (!match)
+        return undefined;
+    return `${match[1]}_${match[2]}`.toLowerCase();
+}
+/** Sandbox tenant IDs are a four-character realm and a three-digit instance number. */
+const SANDBOX_TENANT_ID_REGEX = /^([a-z\d]{4})_(\d{3})$/i;
+/**
+ * Derives the sandbox hostname from a sandbox tenant ID.
+ *
+ * Returns `undefined` for any tenant ID that doesn't follow the sandbox naming
+ * convention (for example a production `abcd_prd` tenant), whose hostname can't
+ * be inferred.
+ *
+ * @param tenantId - Tenant ID or organization ID
+ * @returns The sandbox hostname, or undefined
+ *
+ * @example
+ * sandboxHostnameFromTenantId('f_ecom_zzpq_013') // Returns 'zzpq-013.dx.commercecloud.salesforce.com'
+ * sandboxHostnameFromTenantId('zzxy_prd')        // Returns undefined
+ */
+export function sandboxHostnameFromTenantId(tenantId) {
+    const match = normalizeTenantId(tenantId).match(SANDBOX_TENANT_ID_REGEX);
+    if (!match)
+        return undefined;
+    return `${match[1]}-${match[2]}.dx.commercecloud.salesforce.com`.toLowerCase();
+}
 /**
  * Normalizes any parseable tenant/organization ID form to the canonical underscore format.
  *
@@ -99,19 +146,25 @@ export function toOrganizationId(tenantId) {
  * - `f_ecom_abcd-123` — org ID with hyphenated tenant
  * - `abcd-123.dx.commercecloud.salesforce.com` — sandbox hostname
  *
- * @param value - The tenant ID, organization ID, or hostname
+ * Only sandbox hostnames carry the tenant ID by convention. Other hostnames
+ * (for example `staging-realm-customer.demandware.net`) are returned unchanged
+ * rather than guessing a tenant from the first label.
+ *
+ * @param value - The tenant ID, organization ID, or sandbox hostname
  * @returns The normalized tenant ID in canonical underscore format (e.g., "abcd_123")
  *
  * @example
  * normalizeTenantId('f_ecom_zzxy_prd') // Returns 'zzxy_prd'
  * normalizeTenantId('zzxy-prd')        // Returns 'zzxy_prd'
- * normalizeTenantId('zzxy-prd.dx.commercecloud.salesforce.com') // Returns 'zzxy_prd'
+ * normalizeTenantId('zzxy-001.dx.commercecloud.salesforce.com') // Returns 'zzxy_001'
  */
 export function normalizeTenantId(value) {
     let id = value.trim();
-    // Extract hostname prefix: "abcd-123.dx.commercecloud.salesforce.com" → "abcd-123"
     if (id.includes('.')) {
-        id = id.split('.')[0];
+        const fromHostname = tenantIdFromSandboxHostname(id);
+        if (!fromHostname)
+            return id;
+        id = fromHostname;
     }
     // Strip f_ecom_ prefix (handles org ID form)
     if (id.startsWith(ORGANIZATION_ID_PREFIX)) {

package/dist/esm/clients/custom-apis.js.map

@@ -1 +1 @@
-{"version":3,"file":"custom-apis.js","sourceRoot":"","sources":["../../../src/clients/custom-apis.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,UAAU,EAAC,MAAM,0BAA0B,CAAC;AAqDpD,gEAAgE;AAChE,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAiC/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA8B,EAAE,IAAkB;IACvF,MAAM,QAAQ,GAAG,MAAM,CAAC,kBAAkB,IAAI,wBAAwB,CAAC;IAEvE,MAAM,MAAM,GAAG,YAAY,CAAQ;QACjC,OAAO,EAAE,WAAW,MAAM,CAAC,SAAS,qDAAqD;KAC1F,CAAC,CAAC;IAEH,8DAA8D;IAC9D,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,0BAA0B,EAAE,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE3G,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,aAAa,CAAC,EAAE,CAAC;QAC/D,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACzB,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,aAAa,CAAC,CAAC,CAAC;IAEnD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+CAA+C;AAC/C,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC;AAEhD,oDAAoD;AACpD,MAAM,CAAC,MAAM,yBAAyB,GAAG,0BAA0B,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,GAAG,sBAAsB,GAAG,iBAAiB,CAAC,QAAQ,CAAC,EAAE,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAEtB,mFAAmF;IACnF,IAAI,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IAED,6CAA6C;IAC7C,IAAI,EAAE,CAAC,UAAU,CAAC,sBAAsB,CAAC,EAAE,CAAC;QAC1C,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED,iCAAiC;IACjC,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAE7B,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,GAAG,yBAAyB,GAAG,iBAAiB,CAAC,QAAQ,CAAC,EAAE,CAAC;AACtE,CAAC"}
+{"version":3,"file":"custom-apis.js","sourceRoot":"","sources":["../../../src/clients/custom-apis.ts"],"names":[],"mappings":"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"}

package/dist/esm/clients/index.d.ts

@@ -128,7 +128,7 @@ export { createOdsClient } from './ods.js';
 export type { OdsClient, OdsClientConfig, OdsError, OdsResponse, paths as OdsPaths, components as OdsComponents, } from './ods.js';
 export { createMrtClient, createMrtMaintenanceMiddleware, runWithMrtReadOnlyListener, DEFAULT_MRT_ORIGIN, MRT_READ_ONLY_HEADER, isMrtReadOnlyResponse, MrtMaintenanceError, } from './mrt.js';
 export type { MrtClient, MrtClientConfig, MrtError, MrtResponse, MrtReadOnlyListener, BuildPushResponse, paths as MrtPaths, components as MrtComponents, } from './mrt.js';
-export { createCustomApisClient, toOrganizationId, normalizeTenantId, buildTenantScope, ORGANIZATION_ID_PREFIX, SCAPI_TENANT_SCOPE_PREFIX, CUSTOM_APIS_DEFAULT_SCOPES, } from './custom-apis.js';
+export { createCustomApisClient, toOrganizationId, normalizeTenantId, tenantIdFromSandboxHostname, sandboxHostnameFromTenantId, buildTenantScope, ORGANIZATION_ID_PREFIX, SCAPI_TENANT_SCOPE_PREFIX, CUSTOM_APIS_DEFAULT_SCOPES, } from './custom-apis.js';
 export type { CustomApisClient, CustomApisClientConfig, CustomApisError, CustomApisResponse, paths as CustomApisPaths, components as CustomApisComponents, } from './custom-apis.js';
 export { createScapiSchemasClient, SCAPI_SCHEMAS_DEFAULT_SCOPES } from './scapi-schemas.js';
 export type { ScapiSchemasClient, ScapiSchemasClientConfig, ScapiSchemasError, ScapiSchemasResponse, SchemaListItem, SchemaListResult, OpenApiSchema, paths as ScapiSchemasPaths, components as ScapiSchemasComponents, } from './scapi-schemas.js';

package/dist/esm/clients/index.js

@@ -126,7 +126,7 @@ export { createSlasClient } from './slas-admin.js';
 export { createSlasShopperClient } from './slas-shopper.js';
 export { createOdsClient } from './ods.js';
 export { createMrtClient, createMrtMaintenanceMiddleware, runWithMrtReadOnlyListener, DEFAULT_MRT_ORIGIN, MRT_READ_ONLY_HEADER, isMrtReadOnlyResponse, MrtMaintenanceError, } from './mrt.js';
-export { createCustomApisClient, toOrganizationId, normalizeTenantId, buildTenantScope, ORGANIZATION_ID_PREFIX, SCAPI_TENANT_SCOPE_PREFIX, CUSTOM_APIS_DEFAULT_SCOPES, } from './custom-apis.js';
+export { createCustomApisClient, toOrganizationId, normalizeTenantId, tenantIdFromSandboxHostname, sandboxHostnameFromTenantId, buildTenantScope, ORGANIZATION_ID_PREFIX, SCAPI_TENANT_SCOPE_PREFIX, CUSTOM_APIS_DEFAULT_SCOPES, } from './custom-apis.js';
 export { createScapiSchemasClient, SCAPI_SCHEMAS_DEFAULT_SCOPES } from './scapi-schemas.js';
 export { createAccountManagerClient, createAccountManagerUsersClient, getUser, listUsers, createUser, updateUser, deleteUser, purgeUser, resetUser, findUserByLogin, fetchRoleMapping, resolveToInternalRole, resolveFromInternalRole, createAccountManagerRolesClient, getRole, listRoles, createAccountManagerApiClientsClient, createAccountManagerOrgsClient, isValidRoleTenantFilter, ROLE_TENANT_FILTER_PATTERN, } from './am-api.js';
 export { createCdnZonesClient, CDN_ZONES_READ_SCOPES, CDN_ZONES_RW_SCOPES } from './cdn-zones.js';

package/dist/esm/clients/index.js.map

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

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

@@ -77,6 +77,9 @@ export declare function assertOcapiCompatibilityAllowed(preference: ApiBackendPr
  * 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.
+ * `400` is excluded too: the request was authenticated and understood well
+ * enough to be validated, so the body/params are wrong and OCAPI would only
+ * hide that error (or fail differently). Fix the request instead.
  */
 export declare const SAFE_SCAPI_FALLBACK_STATUSES: Set<number>;
 /**
@@ -105,6 +108,18 @@ export declare function createScapiRequestError(error: unknown, response: Respon
  *     a safe client-error status.
  */
 export declare function isFallbackTrigger(error: unknown): boolean;
+/**
+ * Runs the OCAPI half of a SCAPI → OCAPI fallback and keeps the SCAPI failure
+ * visible if OCAPI also fails.
+ *
+ * Without this, a SCAPI rejection that reveals a real request problem (for
+ * example a 400 body-shape error) is replaced by an unrelated OCAPI error
+ * (typically "access isn't allowed for the current client"), which sends
+ * callers chasing the wrong cause. The OCAPI error is rethrown (type
+ * preserved) with the SCAPI rejection appended to its message and attached as
+ * `scapiError`.
+ */
+export declare function runOcapiFallback<T>(scapiError: unknown, ocapi: () => Promise<T>): Promise<T>;
 /**
  * Inputs to `resolveScapiOrOcapi`.
  */

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

@@ -80,8 +80,11 @@ export function assertOcapiCompatibilityAllowed(preference, capability) {
  * 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.
+ * `400` is excluded too: the request was authenticated and understood well
+ * enough to be validated, so the body/params are wrong and OCAPI would only
+ * hide that error (or fail differently). Fix the request instead.
  */
-export const SAFE_SCAPI_FALLBACK_STATUSES = new Set([400, 401, 403, 404, 405, 406, 415]);
+export const SAFE_SCAPI_FALLBACK_STATUSES = new Set([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
@@ -115,6 +118,30 @@ export function isFallbackTrigger(error) {
         error instanceof ScapiCapabilityUnsupportedError ||
         (error instanceof ScapiRequestError && SAFE_SCAPI_FALLBACK_STATUSES.has(error.status)));
 }
+/**
+ * Runs the OCAPI half of a SCAPI → OCAPI fallback and keeps the SCAPI failure
+ * visible if OCAPI also fails.
+ *
+ * Without this, a SCAPI rejection that reveals a real request problem (for
+ * example a 400 body-shape error) is replaced by an unrelated OCAPI error
+ * (typically "access isn't allowed for the current client"), which sends
+ * callers chasing the wrong cause. The OCAPI error is rethrown (type
+ * preserved) with the SCAPI rejection appended to its message and attached as
+ * `scapiError`.
+ */
+export async function runOcapiFallback(scapiError, ocapi) {
+    try {
+        return await ocapi();
+    }
+    catch (ocapiError) {
+        const scapiMessage = scapiError instanceof Error ? scapiError.message : String(scapiError);
+        if (ocapiError instanceof Error) {
+            ocapiError.message = `${ocapiError.message}\nThe SCAPI attempt was rejected first: ${scapiMessage}\nThe SCAPI error is usually the actionable one; retry with the SCAPI backend only (--api-backend scapi, or api-backend "scapi" in config / SFCC_API_BACKEND=scapi) to see only it.`;
+            ocapiError.scapiError = scapiError;
+        }
+        throw ocapiError;
+    }
+}
 /**
  * Message for when explicit SCAPI is requested but the instance can't reach it.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"scapi-backend-utils.js","sourceRoot":"","sources":["../../../src/clients/scapi-backend-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scapi-backend-utils.js","sourceRoot":"","sources":["../../../src/clients/scapi-backend-utils.ts"],"names":[],"mappings":"AAeA,OAAO,EAAC,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAWpD,uFAAuF;AACvF,MAAM,CAAC,MAAM,iCAAiC,GAAG,MAAM,CAAC;AAWxD,mGAAmG;AACnG,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACtD;QACE,KAAK,CACH,oGAAoG,iCAAiC,IAAI;YACvI,oFAAoF;YACpF,uGAAuG,CAC1G,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,UAAU,6BAA6B,CAAC,IAAkB;IAC9D,IAAI,YAAY,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,KAAK,MAAM,IAAI,IAAI,CAAC,UAAU,KAAK,UAAU,CAAC,EAAE,CAAC;QAC3F,MAAM,IAAI,6BAA6B,EAAE,CAAC;IAC5C,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,IAAkB,EAAE,gBAA0B;IACvE,6BAA6B,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,OAAO,IAAI,CAAC,oBAAoB,KAAK,UAAU,EAAE,CAAC;QACpD,OAAO,IAAI,CAAC,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IACxD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;IAChD,CAAC;CACF;AAED,8FAA8F;AAC9F,MAAM,UAAU,iCAAiC,CAAC,UAAkB;IAClE,OAAO,CACL,oCAAoC,UAAU,+BAA+B,iCAAiC,IAAI;QAClH,gEAAgE;QAChE,mEAAmE,CACpE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,+BAA+B,CAC7C,UAA4C,EAC5C,UAAkB;IAElB,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;QAC3B,MAAM,IAAI,+BAA+B,CAAC,iCAAiC,CAAC,UAAU,CAAC,CAAC,CAAC;IAC3F,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAEpF;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAIxB;IAHlB,YACE,OAAe;IACf,qCAAqC;IACrB,MAAc,EAC9B,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAHR,WAAM,GAAN,MAAM,CAAQ;QAI9B,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,gFAAgF;AAChF,MAAM,UAAU,uBAAuB,CACrC,KAAc,EACd,QAAyD,EACzD,eAAuB;IAEvB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC;IAC9E,OAAO,IAAI,iBAAiB,CAAC,OAAO,IAAI,eAAe,EAAE,QAAQ,CAAC,MAAM,EAAE,EAAC,KAAK,EAAE,KAAK,EAAC,CAAC,CAAC;AAC5F,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,CACL,mBAAmB,CAAC,KAAK,CAAC;QAC1B,KAAK,YAAY,+BAA+B;QAChD,CAAC,KAAK,YAAY,iBAAiB,IAAI,4BAA4B,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CACvF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAI,UAAmB,EAAE,KAAuB;IACpF,IAAI,CAAC;QACH,OAAO,MAAM,KAAK,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,UAAU,EAAE,CAAC;QACpB,MAAM,YAAY,GAAG,UAAU,YAAY,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC3F,IAAI,UAAU,YAAY,KAAK,EAAE,CAAC;YAChC,UAAU,CAAC,OAAO,GAAG,GAAG,UAAU,CAAC,OAAO,2CAA2C,YAAY,qLAAqL,CAAC;YACtR,UAA6C,CAAC,UAAU,GAAG,UAAU,CAAC;QACzE,CAAC;QACD,MAAM,UAAU,CAAC;IACnB,CAAC;AACH,CAAC;AAcD;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAkB;IACxD,OAAO,CACL,GAAG,UAAU,0EAA0E;QACvF,2EAA2E;QAC3E,iGAAiG;QACjG,8BAA8B,iCAAiC,uCAAuC;QACtG,4DAA4D;QAC5D,kEAAkE;QAClE,mEAAmE,CACpE,CAAC;AACJ,CAAC;AAcD;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAA8C;IAE9C,MAAM,EAAC,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAC,GAAG,IAAI,CAAC;IAEvE,IAAI,UAAU,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC;IAE3C,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,kBAAkB,EAAE,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO;IACP,OAAO,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAA2B;IAC7D,MAAM,EAAC,UAAU,EAAE,cAAc,EAAE,UAAU,EAAC,GAAG,IAAI,CAAC;IACtD,OAAO,uBAAuB,CAAC;QAC7B,UAAU;QACV,OAAO,EAAE,OAAO;QAChB,cAAc;QACd,kBAAkB,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,UAAU,CAAC;KAC9D,CAAC,CAAC;AACL,CAAC"}

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

@@ -20,7 +20,7 @@
  * @module clients/scapi-fallback-backend
  */
 import { getLogger } from '../logging/logger.js';
-import { isFallbackTrigger } from './scapi-backend-utils.js';
+import { isFallbackTrigger, runOcapiFallback } from './scapi-backend-utils.js';
 /**
  * Wraps a SCAPI call with automatic OCAPI fallback on a recognized
  * fallback trigger ({@link isFallbackTrigger}).
@@ -51,7 +51,7 @@ async function withFallback(state, fn) {
         if (isFallbackTrigger(error)) {
             getLogger().info(`SCAPI ${state.domainName} unavailable for this operation, falling back to OCAPI`);
             state.resolved = state.ocapi;
-            return fn(state.ocapi);
+            return runOcapiFallback(error, () => fn(state.ocapi));
         }
         throw error;
     }

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

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

@@ -183,7 +183,7 @@ export interface components {
         apiNamePath: string;
         /** @description The API version (e.g., v1) */
         apiVersionPath: string;
-        /** @description Comma-separated list of sections to expand (e.g., "custom_properties") */
+        /** @description Sections to add to the contract, as one comma-separated value (a repeated parameter is rejected). One or more of: all, custom_properties, descriptions, examples, external_docs, summaries, tags, titles. `all` includes every other value. Without it the contract omits operation summaries and descriptions. */
         expand: string;
     };
     requestBodies: never;
@@ -257,7 +257,7 @@ export interface operations {
     getSchema: {
         parameters: {
             query?: {
-                /** @description Comma-separated list of sections to expand (e.g., "custom_properties") */
+                /** @description Sections to add to the contract, as one comma-separated value (a repeated parameter is rejected). One or more of: all, custom_properties, descriptions, examples, external_docs, summaries, tags, titles. `all` includes every other value. Without it the contract omits operation summaries and descriptions. */
                 expand?: components["parameters"]["expand"];
             };
             header?: never;

package/dist/esm/compat/dispatcher.js

@@ -50,7 +50,7 @@
  * @module compat/dispatcher
  */
 import { getLogger } from '../logging/logger.js';
-import { isFallbackTrigger, scapiUnavailableMessage } from '../clients/scapi-backend-utils.js';
+import { isFallbackTrigger, runOcapiFallback, scapiUnavailableMessage, } from '../clients/scapi-backend-utils.js';
 /**
  * Stateful router that runs SCAPI optimistically and falls back to OCAPI
  * once on a safe capability/auth/request rejection, caching the choice for the lifetime of the
@@ -115,7 +115,7 @@ export class BackendDispatcher {
             if (isFallbackTrigger(error)) {
                 getLogger().info(`SCAPI ${this.domainName} unavailable for this operation, falling back to OCAPI`);
                 this.resolved = 'ocapi';
-                return branches.ocapi();
+                return runOcapiFallback(error, branches.ocapi);
             }
             throw error;
         }

package/dist/esm/compat/dispatcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../../src/compat/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,EAAC,SAAS,EAAC,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAC,iBAAiB,EAAE,uBAAuB,EAA4B,MAAM,mCAAmC,CAAC;AAkBxH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,iBAAiB;IAiBT;IAhBX,QAAQ,CAAmB;IAC3B,QAAQ,CAAK;IAErB;;;;;;;;;OASG;IACH,YACE,UAAgC,EAChC,WAAgC,EACf,UAAkB;QAAlB,eAAU,GAAV,UAAU,CAAQ;QAEnC,MAAM,KAAK,GAAG,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACjE,MAAM,QAAQ,GAAG,KAAK,KAAK,SAAS,CAAC;QACrC,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QAE/C,IAAI,UAAU,KAAK,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,UAAU,KAAK,OAAO;YAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACpD,IAAI,UAAU,KAAK,OAAO;YAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACpD,IAAI,UAAU,KAAK,MAAM,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAClE,CAAC;IAED,0EAA0E;IAC1E,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAG,CAAI,QAAgC;QAC3C,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC;QACvD,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,QAAS,CAAC,CAAC;QAErE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,QAAS,CAAC,CAAC;YACpD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;YACxB,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC7B,SAAS,EAAE,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,UAAU,wDAAwD,CAAC,CAAC;gBACnG,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;gBACxB,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC;YAC1B,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../../src/compat/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,EAAC,SAAS,EAAC,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,GAExB,MAAM,mCAAmC,CAAC;AAkB3C;;;;;;;;;;GAUG;AACH,MAAM,OAAO,iBAAiB;IAiBT;IAhBX,QAAQ,CAAmB;IAC3B,QAAQ,CAAK;IAErB;;;;;;;;;OASG;IACH,YACE,UAAgC,EAChC,WAAgC,EACf,UAAkB;QAAlB,eAAU,GAAV,UAAU,CAAQ;QAEnC,MAAM,KAAK,GAAG,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACjE,MAAM,QAAQ,GAAG,KAAK,KAAK,SAAS,CAAC;QACrC,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QAE/C,IAAI,UAAU,KAAK,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,UAAU,KAAK,OAAO;YAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACpD,IAAI,UAAU,KAAK,OAAO;YAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACpD,IAAI,UAAU,KAAK,MAAM,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAClE,CAAC;IAED,0EAA0E;IAC1E,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAG,CAAI,QAAgC;QAC3C,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC;QACvD,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,QAAS,CAAC,CAAC;QAErE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,QAAS,CAAC,CAAC;YACpD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;YACxB,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC7B,SAAS,EAAE,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,UAAU,wDAAwD,CAAC,CAAC;gBACnG,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;gBACxB,OAAO,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;YACjD,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/esm/config/config-origins.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Links resolution results to the source objects that produced them.
+ *
+ * Kept out of {@link ConfigSourceInfo} so serialized diagnostics never carry
+ * source instances (which may hold environment maps or secrets).
+ *
+ * @module config/config-origins
+ */
+import type { ConfigSource, ConfigSourceInfo, ResolveConfigOptions } from './types.js';
+/** A source that took part in resolution, with the options it was loaded with. */
+export interface ConfigOrigin {
+    source: ConfigSource;
+    info: ConfigSourceInfo;
+    options: ResolveConfigOptions;
+}
+/** @internal Associate origins with a resolution result or resolved config. */
+export declare function recordConfigOrigins(target: object, entries: readonly ConfigOrigin[] | undefined): void;
+/** Origins recorded for a resolution result or resolved config, in priority order. */
+export declare function getConfigOrigins(target: object): readonly ConfigOrigin[] | undefined;

package/dist/esm/config/config-origins.js

@@ -0,0 +1,11 @@
+const origins = new WeakMap();
+/** @internal Associate origins with a resolution result or resolved config. */
+export function recordConfigOrigins(target, entries) {
+    if (entries)
+        origins.set(target, entries);
+}
+/** Origins recorded for a resolution result or resolved config, in priority order. */
+export function getConfigOrigins(target) {
+    return origins.get(target);
+}
+//# sourceMappingURL=config-origins.js.map

package/dist/esm/config/config-origins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-origins.js","sourceRoot":"","sources":["../../../src/config/config-origins.ts"],"names":[],"mappings":"AAsBA,MAAM,OAAO,GAAG,IAAI,OAAO,EAAmC,CAAC;AAE/D,+EAA+E;AAC/E,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,OAA4C;IAC9F,IAAI,OAAO;QAAE,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC"}

package/dist/esm/config/config-write.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Read and write individual configuration fields at the source that supplies them.
+ *
+ * Writes go to the highest-priority source currently supplying a field, so the
+ * new value always takes effect. A field no source supplies goes to the entry
+ * that selected the instance (for example the active dw.json config). Sources
+ * that don't implement {@link ConfigSource.updateConfig} (shell environment,
+ * ~/.mobify, package.json) are never written; credential stores are written
+ * through {@link ConfigSource.storeCredential} for their declared fields.
+ *
+ * @module config/config-write
+ */
+import { type ConfigOrigin } from './config-origins.js';
+import { type JsonSchema } from './dw-json-schema.js';
+import type { ConfigSourceInfo, ConfigUpdateResult, NormalizedConfig, ResolvedB2CConfig } from './types.js';
+/** A settable configuration key. */
+export interface ConfigKey {
+    /** dw.json key (kebab-case) */
+    key: string;
+    /** Normalized config field */
+    field: keyof NormalizedConfig;
+    /** JSON Schema for the value */
+    schema: JsonSchema;
+}
+/** Error raised when a configuration field can't be read or written safely. */
+export declare class ConfigWriteError extends Error {
+    readonly code: 'CONFIG_KEY_UNKNOWN' | 'CONFIG_VALUE_INVALID' | 'CONFIG_SOURCE_READ_ONLY' | 'CONFIG_NO_WRITE_TARGET' | 'CONFIG_NOT_SET';
+    constructor(code: 'CONFIG_KEY_UNKNOWN' | 'CONFIG_VALUE_INVALID' | 'CONFIG_SOURCE_READ_ONLY' | 'CONFIG_NO_WRITE_TARGET' | 'CONFIG_NOT_SET', message: string);
+}
+/** All keys `setup set` accepts, in dw.json order. */
+export declare function listConfigKeys(): ConfigKey[];
+/**
+ * Resolve a user-supplied key (dw.json kebab-case, camelCase, a legacy alias,
+ * or the normalized field name) to a settable configuration key.
+ *
+ * @throws ConfigWriteError for unknown or unsettable keys
+ */
+export declare function resolveConfigKey(input: string): ConfigKey;
+/**
+ * Coerce a command-line value to the key's type.
+ *
+ * String keys keep the text as given. Other keys accept JSON (`true`,
+ * `["a","b"]`, `{"level":"NO_DELETE"}`); string-list keys also accept a
+ * plain or comma-separated value (`./schemas` becomes `["./schemas"]`).
+ *
+ * @throws ConfigWriteError when the value doesn't match the key's schema
+ */
+export declare function parseConfigValue(key: ConfigKey, raw: string): unknown;
+/** Where a field's value comes from and where a write would go. */
+export interface ConfigFieldLocation {
+    /** Source currently supplying the field, if any */
+    supplier?: ConfigSourceInfo;
+    /** Origin that a write would update */
+    target?: ConfigOrigin;
+    /** Why the field can't be written, when {@link target} is absent */
+    error?: ConfigWriteError;
+}
+/**
+ * Locate a field in a resolved configuration: which source supplies it and
+ * which source a write should update.
+ *
+ * The target is, in order: the source supplying the field; the source
+ * supplying the other half of its credential pair; or, for a field nothing
+ * sets, the source that supplied the instance itself (its `instanceName`, else
+ * its `hostname`). A derived value (a sandbox hostname worked out from its
+ * tenant ID) counts as supplied by the source of the field it came from. Every
+ * rule uses only {@link ConfigSourceInfo} and the optional write methods, so
+ * plugin sources take part the same way dw.json does.
+ */
+export declare function locateConfigField(config: ResolvedB2CConfig, field: keyof NormalizedConfig): ConfigFieldLocation;
+/**
+ * Set or remove (`value === undefined`) a field at the source that supplies it.
+ *
+ * @throws ConfigWriteError when the field has no writable target
+ */
+export declare function writeConfigField(config: ResolvedB2CConfig, field: keyof NormalizedConfig, value: unknown): Promise<ConfigUpdateResult & {
+    source: string;
+}>;
+/**
+ * Remove a field from the source that supplies it.
+ *
+ * @throws ConfigWriteError when the field isn't set or its source can't be written
+ */
+export declare function removeConfigField(config: ResolvedB2CConfig, field: keyof NormalizedConfig): Promise<ConfigUpdateResult & {
+    source: string;
+}>;