normalize tenant ids

Author: clavery

.claude/skills/api-client-development/SKILL.md

@@ -172,19 +172,22 @@ SCAPI APIs use an `organizationId` path parameter with the `f_ecom_` prefix, but
 
 ```typescript
 // From @salesforce/b2c-tooling-sdk (or clients/custom-apis.ts)
-import {toOrganizationId, toTenantId, buildTenantScope} from '@salesforce/b2c-tooling-sdk';
+import {toOrganizationId, normalizeTenantId, buildTenantScope} from '@salesforce/b2c-tooling-sdk';
 
-// Convert tenant ID to organization ID (adds f_ecom_ prefix)
+// Convert tenant ID to organization ID (normalizes + adds f_ecom_ prefix)
 toOrganizationId('zzxy_prd')        // Returns 'f_ecom_zzxy_prd'
 toOrganizationId('f_ecom_zzxy_prd') // Returns 'f_ecom_zzxy_prd' (unchanged)
+toOrganizationId('zzxy-prd')        // Returns 'f_ecom_zzxy_prd' (hyphen normalized)
 
-// Extract raw tenant ID (strips f_ecom_ prefix)
-toTenantId('f_ecom_zzxy_prd')       // Returns 'zzxy_prd'
-toTenantId('zzxy_prd')              // Returns 'zzxy_prd' (unchanged)
+// Normalize any tenant/org ID form to canonical underscore format
+normalizeTenantId('f_ecom_zzxy_prd')                              // Returns 'zzxy_prd'
+normalizeTenantId('zzxy-prd')                                     // Returns 'zzxy_prd'
+normalizeTenantId('zzxy-prd.dx.commercecloud.salesforce.com')     // Returns 'zzxy_prd'
 
-// Build tenant-specific OAuth scope
+// Build tenant-specific OAuth scope (normalizes input)
 buildTenantScope('zzxy_prd')        // Returns 'SALESFORCE_COMMERCE_API:zzxy_prd'
 buildTenantScope('f_ecom_zzxy_prd') // Returns 'SALESFORCE_COMMERCE_API:zzxy_prd'
+buildTenantScope('zzxy-prd')        // Returns 'SALESFORCE_COMMERCE_API:zzxy_prd'
 ```
 
 ### Constants
@@ -272,20 +275,19 @@ export function createCustomApisClient(
 export const ORGANIZATION_ID_PREFIX = 'f_ecom_';
 export const SCAPI_TENANT_SCOPE_PREFIX = 'SALESFORCE_COMMERCE_API:';
 
-export function toOrganizationId(tenantId: string): string {
-  return tenantId.startsWith(ORGANIZATION_ID_PREFIX)
-    ? tenantId
-    : `${ORGANIZATION_ID_PREFIX}${tenantId}`;
+export function normalizeTenantId(value: string): string {
+  let id = value.trim();
+  if (id.includes('.')) id = id.split('.')[0];
+  if (id.startsWith(ORGANIZATION_ID_PREFIX)) id = id.slice(ORGANIZATION_ID_PREFIX.length);
+  return id.replaceAll('-', '_');
 }
 
-export function toTenantId(value: string): string {
-  return value.startsWith(ORGANIZATION_ID_PREFIX)
-    ? value.slice(ORGANIZATION_ID_PREFIX.length)
-    : value;
+export function toOrganizationId(tenantId: string): string {
+  return `${ORGANIZATION_ID_PREFIX}${normalizeTenantId(tenantId)}`;
 }
 
 export function buildTenantScope(tenantId: string): string {
-  return `${SCAPI_TENANT_SCOPE_PREFIX}${toTenantId(tenantId)}`;
+  return `${SCAPI_TENANT_SCOPE_PREFIX}${normalizeTenantId(tenantId)}`;
 }
 ```
 
@@ -440,13 +442,13 @@ const {data, error} = await client.GET('/endpoint', {...});
 
 ## Troubleshooting
 
-**OAuth scope errors (401/403 from SCAPI)**: Ensure the client factory calls `auth.withAdditionalScopes()` with both the domain scope (e.g., `sfcc.custom-apis`) and the tenant-specific scope (`SALESFORCE_COMMERCE_API:<tenantId>`). Use `buildTenantScope()` to strip the `f_ecom_` prefix from tenant IDs before building scopes.
+**OAuth scope errors (401/403 from SCAPI)**: Ensure the client factory calls `auth.withAdditionalScopes()` with both the domain scope (e.g., `sfcc.custom-apis`) and the tenant-specific scope (`SALESFORCE_COMMERCE_API:<tenantId>`). Use `buildTenantScope()` which normalizes any tenant ID form (hyphenated, hostname, org ID) to canonical underscores before building scopes.
 
 **Type generation failures**: Check that the OpenAPI spec in `specs/` is valid YAML/JSON. Run `pnpm --filter @salesforce/b2c-tooling-sdk run generate:types` and inspect the output. Common issues: spec references external files that aren't present, or uses OpenAPI features not supported by openapi-typescript.
 
 **Middleware ordering issues**: Auth middleware should be added first (`client.use(createAuthMiddleware(...))`), then logging. In openapi-fetch, middleware runs in reverse registration order for requests, so auth registered first means it runs last — ensuring the logging middleware sees the final request with auth headers.
 
-**`organizationId` mismatch**: SCAPI path parameters need the `f_ecom_` prefix (use `toOrganizationId()`), while OAuth scopes need the raw tenant ID (use `toTenantId()`). Mixing these up causes 404s or scope errors.
+**`organizationId` mismatch**: SCAPI path parameters need the `f_ecom_` prefix (use `toOrganizationId()`), while OAuth scopes need the raw tenant ID (use `normalizeTenantId()`). Both functions accept any parseable form (hyphenated, hostname, org ID). Mixing these up causes 404s or scope errors.
 
 ## Checklist: New SCAPI Client
 

packages/b2c-tooling-sdk/src/cli/oauth-command.ts

@@ -12,6 +12,7 @@ import {OAuthStrategy} from '../auth/oauth.js';
 import {ImplicitOAuthStrategy} from '../auth/oauth-implicit.js';
 import {t} from '../i18n/index.js';
 import {DEFAULT_ACCOUNT_MANAGER_HOST} from '../defaults.js';
+import {normalizeTenantId} from '../clients/custom-apis.js';
 
 /**
  * Default OAuth authentication methods array used by getOAuthStrategy.
@@ -222,10 +223,6 @@ export abstract class OAuthCommand<T extends typeof Command> extends BaseCommand
         ),
       );
     }
-    // Strip optional f_ecom_ prefix so users can pass either the organization ID or tenant ID
-    if (tenantId.startsWith('f_ecom_')) {
-      return tenantId.slice('f_ecom_'.length);
-    }
-    return tenantId;
+    return normalizeTenantId(tenantId);
   }
 }

packages/b2c-tooling-sdk/src/clients/cdn-zones.ts

@@ -19,7 +19,7 @@ import {OAuthStrategy} from '../auth/oauth.js';
 import type {paths, components} from './cdn-zones.generated.js';
 import {createAuthMiddleware, createLoggingMiddleware} from './middleware.js';
 import {globalMiddlewareRegistry, type MiddlewareRegistry} from './middleware-registry.js';
-import {toOrganizationId, toTenantId, buildTenantScope} from './custom-apis.js';
+import {toOrganizationId, normalizeTenantId, buildTenantScope} from './custom-apis.js';
 
 /**
  * Re-export generated types for external use.
@@ -29,7 +29,7 @@ export type {paths, components};
 /**
  * Re-export organization/tenant utilities for convenience.
  */
-export {toOrganizationId, toTenantId, buildTenantScope};
+export {toOrganizationId, normalizeTenantId, buildTenantScope};
 
 /**
  * The typed CDN Zones client for eCDN management.

packages/b2c-tooling-sdk/src/clients/custom-apis.ts

@@ -183,27 +183,44 @@ export const SCAPI_TENANT_SCOPE_PREFIX = 'SALESFORCE_COMMERCE_API:';
  * toOrganizationId('f_ecom_zzxy_prd') // Returns 'f_ecom_zzxy_prd' (unchanged)
  */
 export function toOrganizationId(tenantId: string): string {
-  if (tenantId.startsWith(ORGANIZATION_ID_PREFIX)) {
-    return tenantId;
-  }
-  return `${ORGANIZATION_ID_PREFIX}${tenantId}`;
+  return `${ORGANIZATION_ID_PREFIX}${normalizeTenantId(tenantId)}`;
 }
 
 /**
- * Extracts the raw tenant ID by stripping the f_ecom_ prefix if present.
+ * Normalizes any parseable tenant/organization ID form to the canonical underscore format.
+ *
+ * Supported input forms (all resolve to `abcd_123`):
+ * - `abcd_123` — canonical tenant ID (returned as-is)
+ * - `abcd-123` — hyphenated tenant ID
+ * - `f_ecom_abcd_123` — organization ID
+ * - `f_ecom_abcd-123` — org ID with hyphenated tenant
+ * - `abcd-123.dx.commercecloud.salesforce.com` — sandbox hostname
  *
- * @param value - The tenant ID or organization ID (e.g., "zzxy_prd" or "f_ecom_zzxy_prd")
- * @returns The raw tenant ID without the prefix (e.g., "zzxy_prd")
+ * @param value - The tenant ID, organization ID, or hostname
+ * @returns The normalized tenant ID in canonical underscore format (e.g., "abcd_123")
  *
  * @example
- * toTenantId('f_ecom_zzxy_prd') // Returns 'zzxy_prd'
- * toTenantId('zzxy_prd')        // Returns 'zzxy_prd' (unchanged)
+ * normalizeTenantId('f_ecom_zzxy_prd') // Returns 'zzxy_prd'
+ * normalizeTenantId('zzxy-prd')        // Returns 'zzxy_prd'
+ * normalizeTenantId('zzxy-prd.dx.commercecloud.salesforce.com') // Returns 'zzxy_prd'
  */
-export function toTenantId(value: string): string {
-  if (value.startsWith(ORGANIZATION_ID_PREFIX)) {
-    return value.slice(ORGANIZATION_ID_PREFIX.length);
+export function normalizeTenantId(value: string): string {
+  let id = value.trim();
+
+  // Extract hostname prefix: "abcd-123.dx.commercecloud.salesforce.com" → "abcd-123"
+  if (id.includes('.')) {
+    id = id.split('.')[0];
   }
-  return value;
+
+  // Strip f_ecom_ prefix (handles org ID form)
+  if (id.startsWith(ORGANIZATION_ID_PREFIX)) {
+    id = id.slice(ORGANIZATION_ID_PREFIX.length);
+  }
+
+  // Convert hyphens to underscores
+  id = id.replaceAll('-', '_');
+
+  return id;
 }
 
 /**
@@ -217,5 +234,5 @@ export function toTenantId(value: string): string {
  * buildTenantScope('f_ecom_zzxy_prd') // Returns 'SALESFORCE_COMMERCE_API:zzxy_prd'
  */
 export function buildTenantScope(tenantId: string): string {
-  return `${SCAPI_TENANT_SCOPE_PREFIX}${toTenantId(tenantId)}`;
+  return `${SCAPI_TENANT_SCOPE_PREFIX}${normalizeTenantId(tenantId)}`;
 }

packages/b2c-tooling-sdk/src/clients/index.ts

@@ -183,7 +183,7 @@ export type {
 export {
   createCustomApisClient,
   toOrganizationId,
-  toTenantId,
+  normalizeTenantId,
   buildTenantScope,
   ORGANIZATION_ID_PREFIX,
   SCAPI_TENANT_SCOPE_PREFIX,

packages/b2c-tooling-sdk/src/clients/scapi-schemas.ts

@@ -18,7 +18,7 @@ import {OAuthStrategy} from '../auth/oauth.js';
 import type {paths, components} from './scapi-schemas.generated.js';
 import {createAuthMiddleware, createLoggingMiddleware} from './middleware.js';
 import {globalMiddlewareRegistry, type MiddlewareRegistry} from './middleware-registry.js';
-import {toOrganizationId, toTenantId, buildTenantScope} from './custom-apis.js';
+import {toOrganizationId, normalizeTenantId, buildTenantScope} from './custom-apis.js';
 
 /**
  * Re-export generated types for external use.
@@ -28,7 +28,7 @@ export type {paths, components};
 /**
  * Re-export organization/tenant utilities for convenience.
  */
-export {toOrganizationId, toTenantId, buildTenantScope};
+export {toOrganizationId, normalizeTenantId, buildTenantScope};
 
 /**
  * The typed SCAPI Schemas client for discovering available SCAPI APIs.

packages/b2c-tooling-sdk/src/index.ts

@@ -73,7 +73,7 @@ export {
   createCdnZonesClient,
   createCipClient,
   toOrganizationId,
-  toTenantId,
+  normalizeTenantId,
   buildTenantScope,
   getApiErrorMessage,
   isValidRoleTenantFilter,

packages/b2c-tooling-sdk/test/clients/custom-apis.test.ts

@@ -11,7 +11,7 @@ import {setupServer} from 'msw/node';
 import {
   createCustomApisClient,
   toOrganizationId,
-  toTenantId,
+  normalizeTenantId,
   buildTenantScope,
   ORGANIZATION_ID_PREFIX,
   SCAPI_TENANT_SCOPE_PREFIX,
@@ -329,15 +329,55 @@ describe('clients/custom-apis', () => {
     });
   });
 
+  describe('normalizeTenantId', () => {
+    it('returns canonical tenant ID unchanged', () => {
+      expect(normalizeTenantId('abcd_123')).to.equal('abcd_123');
+    });
+
+    it('converts hyphenated tenant ID to underscores', () => {
+      expect(normalizeTenantId('abcd-123')).to.equal('abcd_123');
+    });
+
+    it('strips f_ecom_ prefix from organization ID', () => {
+      expect(normalizeTenantId('f_ecom_abcd_123')).to.equal('abcd_123');
+    });
+
+    it('strips f_ecom_ prefix and converts hyphens', () => {
+      expect(normalizeTenantId('f_ecom_abcd-123')).to.equal('abcd_123');
+    });
+
+    it('extracts tenant from hostname', () => {
+      expect(normalizeTenantId('abcd-123.dx.commercecloud.salesforce.com')).to.equal('abcd_123');
+    });
+
+    it('trims whitespace', () => {
+      expect(normalizeTenantId('  abcd_123  ')).to.equal('abcd_123');
+    });
+
+    it('handles various formats', () => {
+      expect(normalizeTenantId('f_ecom_zzxy_prd')).to.equal('zzxy_prd');
+      expect(normalizeTenantId('zzxy_prd')).to.equal('zzxy_prd');
+      expect(normalizeTenantId('f_ecom_test')).to.equal('test');
+    });
+  });
+
   describe('toOrganizationId', () => {
     it('adds f_ecom_ prefix to tenant ID', () => {
       expect(toOrganizationId('zzxy_prd')).to.equal('f_ecom_zzxy_prd');
     });
 
-    it('returns unchanged if already has f_ecom_ prefix', () => {
+    it('normalizes and adds prefix for already-prefixed input', () => {
       expect(toOrganizationId('f_ecom_zzxy_prd')).to.equal('f_ecom_zzxy_prd');
     });
 
+    it('normalizes hyphenated input', () => {
+      expect(toOrganizationId('abcd-123')).to.equal('f_ecom_abcd_123');
+    });
+
+    it('normalizes hostname input', () => {
+      expect(toOrganizationId('abcd-123.dx.commercecloud.salesforce.com')).to.equal('f_ecom_abcd_123');
+    });
+
     it('handles various tenant ID formats', () => {
       expect(toOrganizationId('abcd_001')).to.equal('f_ecom_abcd_001');
       expect(toOrganizationId('test')).to.equal('f_ecom_test');
@@ -348,21 +388,6 @@ describe('clients/custom-apis', () => {
     });
   });
 
-  describe('toTenantId', () => {
-    it('strips f_ecom_ prefix from organization ID', () => {
-      expect(toTenantId('f_ecom_zzxy_prd')).to.equal('zzxy_prd');
-    });
-
-    it('returns unchanged if no f_ecom_ prefix', () => {
-      expect(toTenantId('zzxy_prd')).to.equal('zzxy_prd');
-    });
-
-    it('handles various formats', () => {
-      expect(toTenantId('f_ecom_abcd_001')).to.equal('abcd_001');
-      expect(toTenantId('f_ecom_test')).to.equal('test');
-    });
-  });
-
   describe('buildTenantScope', () => {
     it('builds scope from tenant ID', () => {
       expect(buildTenantScope('zzxy_prd')).to.equal('SALESFORCE_COMMERCE_API:zzxy_prd');
@@ -372,6 +397,15 @@ describe('clients/custom-apis', () => {
       expect(buildTenantScope('f_ecom_zzxy_prd')).to.equal('SALESFORCE_COMMERCE_API:zzxy_prd');
     });
 
+    it('normalizes hyphenated input', () => {
+      expect(buildTenantScope('abcd-123')).to.equal('SALESFORCE_COMMERCE_API:abcd_123');
+    });
+
+    it('normalizes hostname input', () => {
+      const input = 'abcd-123.dx.commercecloud.salesforce.com';
+      expect(buildTenantScope(input)).to.equal('SALESFORCE_COMMERCE_API:abcd_123');
+    });
+
     it('uses SCAPI_TENANT_SCOPE_PREFIX constant', () => {
       expect(SCAPI_TENANT_SCOPE_PREFIX).to.equal('SALESFORCE_COMMERCE_API:');
     });