fix(sdk): add automatic 401 retry with token refresh to openapi-fetch middleware (#103)

* fix(sdk): add automatic 401 retry with token refresh to openapi-fetch middleware

The SDK had automatic token refresh for auth.fetch() calls (WebDAV), but
openapi-fetch clients (OCAPI, SLAS, SCAPI, etc.) did not retry on 401.
For long-running operations, if a token expires mid-operation, API calls
would fail.

This adds an onResponse handler to createAuthMiddleware() that:
- Detects 401 responses
- Invalidates the cached token via auth.invalidateToken()
- Gets a fresh token via auth.getAuthorizationHeader()
- Retries the request once with the new token

Uses WeakSet/WeakMap to track retried requests and preserve request bodies.

* chore(sdk): add token refresh test script

Utility script for manually testing 401 retry behavior during long-running
operations. Polls active code version every 10 seconds.

Author: clavery

.changeset/auth-middleware-401-retry.md

@@ -0,0 +1,5 @@
+---
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+Add automatic 401 retry with token refresh to openapi-fetch middleware. This ensures API clients (OCAPI, SLAS, SCAPI, etc.) automatically refresh expired tokens during long-running operations.

packages/b2c-tooling-sdk/scripts/test-token-refresh.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env npx tsx
+/*
+ * 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
+ */
+
+/**
+ * Test script for verifying automatic 401 retry with token refresh.
+ *
+ * Polls the active code version every 10 seconds to test that long-running
+ * operations correctly handle token expiration and refresh.
+ *
+ * Usage:
+ *   # With command line args
+ *   npx tsx scripts/test-token-refresh.ts --client-id=YOUR_CLIENT_ID --client-secret=YOUR_SECRET
+ *
+ *   # With environment variables
+ *   SFCC_OAUTH_CLIENT_ID=xxx SFCC_OAUTH_CLIENT_SECRET=yyy npx tsx scripts/test-token-refresh.ts
+ *
+ *   # With trace logging to see token refresh behavior
+ *   SFCC_LOG_LEVEL=trace npx tsx scripts/test-token-refresh.ts --client-id=xxx --client-secret=yyy
+ *
+ *   # Disable redaction to see full tokens (NOT recommended for shared terminals)
+ *   SFCC_LOG_REDACT=false SFCC_LOG_LEVEL=trace npx tsx scripts/test-token-refresh.ts ...
+ *
+ *   # Implicit flow (client ID only, opens browser)
+ *   npx tsx scripts/test-token-refresh.ts --client-id=YOUR_CLIENT_ID
+ *
+ * The script will run until interrupted (Ctrl+C).
+ */
+
+import {resolveConfig} from '../src/config/resolver.js';
+import {configureLogger, getLogger} from '../src/logging/logger.js';
+import {getActiveCodeVersion} from '../src/operations/code/versions.js';
+
+function parseArgs(): {clientId?: string; clientSecret?: string} {
+  const args: {clientId?: string; clientSecret?: string} = {};
+
+  for (const arg of process.argv.slice(2)) {
+    if (arg.startsWith('--client-id=')) {
+      args.clientId = arg.slice('--client-id='.length);
+    } else if (arg.startsWith('--client-secret=')) {
+      args.clientSecret = arg.slice('--client-secret='.length);
+    }
+  }
+
+  return args;
+}
+
+const POLL_INTERVAL_MS = 10_000; // 10 seconds
+
+async function main() {
+  // Configure logger based on environment
+  const logLevel = (process.env.SFCC_LOG_LEVEL as 'trace' | 'debug' | 'info' | 'warn' | 'error') || 'info';
+  const redact = process.env.SFCC_LOG_REDACT !== 'false'; // Redaction on by default
+  configureLogger({level: logLevel, redact});
+
+  const logger = getLogger();
+
+  logger.info('=== Token Refresh Test Script ===');
+  logger.info(`Poll interval: ${POLL_INTERVAL_MS / 1000} seconds`);
+  logger.info(`Log level: ${logLevel}`);
+  logger.info('Press Ctrl+C to stop\n');
+
+  // Parse command line args
+  const args = parseArgs();
+
+  // Resolve config from dw.json / environment, with CLI overrides
+  const config = resolveConfig({
+    clientId: args.clientId || process.env.SFCC_OAUTH_CLIENT_ID,
+    clientSecret: args.clientSecret || process.env.SFCC_OAUTH_CLIENT_SECRET,
+  });
+
+  if (!config.hasB2CInstanceConfig()) {
+    logger.error('No B2C instance configuration found. Check dw.json or environment variables.');
+    process.exit(1);
+  }
+
+  const instance = config.createB2CInstance();
+  const authMethod = config.values.clientSecret ? 'client-credentials' : 'implicit';
+  logger.info({hostname: config.values.hostname, authMethod}, `Connected to: ${config.values.hostname}`);
+  logger.info(`Auth method: ${authMethod}${authMethod === 'implicit' ? ' (will open browser on first request)' : ''}`);
+
+  let pollCount = 0;
+  const startTime = Date.now();
+
+  const poll = async () => {
+    pollCount++;
+    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    const elapsedMinutes = Math.floor(elapsed / 60);
+    const elapsedSeconds = elapsed % 60;
+
+    try {
+      const activeVersion = await getActiveCodeVersion(instance);
+      const timestamp = new Date().toISOString();
+
+      logger.info(
+        {
+          poll: pollCount,
+          elapsed: `${elapsedMinutes}m ${elapsedSeconds}s`,
+          activeCodeVersion: activeVersion?.id,
+        },
+        `[${timestamp}] Poll #${pollCount} (${elapsedMinutes}m ${elapsedSeconds}s) - Active code version: ${activeVersion?.id ?? 'none'}`,
+      );
+    } catch (error) {
+      const timestamp = new Date().toISOString();
+      logger.error(
+        {
+          poll: pollCount,
+          elapsed: `${elapsedMinutes}m ${elapsedSeconds}s`,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        `[${timestamp}] Poll #${pollCount} FAILED: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  };
+
+  // Initial poll
+  await poll();
+
+  // Set up interval
+  const intervalId = setInterval(poll, POLL_INTERVAL_MS);
+
+  // Handle graceful shutdown
+  process.on('SIGINT', () => {
+    logger.info('\nShutting down...');
+    clearInterval(intervalId);
+
+    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    const elapsedMinutes = Math.floor(elapsed / 60);
+    const elapsedSeconds = elapsed % 60;
+
+    logger.info(
+      {totalPolls: pollCount, totalTime: `${elapsedMinutes}m ${elapsedSeconds}s`},
+      `\nCompleted ${pollCount} polls over ${elapsedMinutes}m ${elapsedSeconds}s`,
+    );
+    process.exit(0);
+  });
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

packages/b2c-tooling-sdk/src/auth/types.ts

@@ -25,6 +25,12 @@ export interface AuthStrategy {
    * Optional: Helper for legacy clients (like a strict WebDAV lib) that need the raw header.
    */
   getAuthorizationHeader?(): Promise<string>;
+
+  /**
+   * Optional: Invalidates the cached token, forcing re-authentication on next request.
+   * Used by middleware to retry requests after receiving a 401 response.
+   */
+  invalidateToken?(): void;
 }
 
 /**

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

@@ -38,24 +38,88 @@ function headersToObject(headers: Headers): Record<string, string> {
   return result;
 }
 
+// Track which requests have been retried to prevent infinite loops
+const retriedRequests = new WeakSet<Request>();
+
+// Store cloned request bodies for potential retry (body can only be read once)
+const requestBodies = new WeakMap<Request, ArrayBuffer | null>();
+
 /**
  * Creates authentication middleware for openapi-fetch.
  *
  * This middleware intercepts requests and adds OAuth authentication headers
- * using the provided AuthStrategy.
+ * using the provided AuthStrategy. It also handles 401 responses by invalidating
+ * the token and retrying the request once with a fresh token.
  *
  * @param auth - The authentication strategy to use
- * @returns Middleware that adds auth headers to requests
+ * @returns Middleware that adds auth headers to requests and retries on 401
  */
 export function createAuthMiddleware(auth: AuthStrategy): Middleware {
+  const logger = getLogger();
+
   return {
     async onRequest({request}) {
       if (auth.getAuthorizationHeader) {
         const authHeader = await auth.getAuthorizationHeader();
         request.headers.set('Authorization', authHeader);
       }
+
+      // Clone the request body before it gets consumed, so we can retry if needed
+      if (request.body && auth.invalidateToken && auth.getAuthorizationHeader) {
+        const clonedRequest = request.clone();
+        const bodyBuffer = await clonedRequest.arrayBuffer();
+        requestBodies.set(request, bodyBuffer);
+      }
+
       return request;
     },
+
+    async onResponse({request, response}) {
+      // Only retry on 401 if we haven't already retried this request
+      // and the strategy supports token invalidation
+      if (
+        response.status === 401 &&
+        !retriedRequests.has(request) &&
+        auth.invalidateToken &&
+        auth.getAuthorizationHeader
+      ) {
+        logger.debug('[AuthMiddleware] Received 401, invalidating token and retrying');
+
+        // Mark this request as retried to prevent infinite loops
+        retriedRequests.add(request);
+
+        // Invalidate the cached token
+        auth.invalidateToken();
+
+        // Get a fresh token
+        const newAuthHeader = await auth.getAuthorizationHeader();
+
+        // Rebuild the request with the new auth header
+        const newHeaders = new Headers(request.headers);
+        newHeaders.set('Authorization', newAuthHeader);
+
+        // Get the saved body (if any)
+        const savedBody = requestBodies.get(request);
+
+        // Create a new request with the fresh token
+        const retryRequest = new Request(request.url, {
+          method: request.method,
+          headers: newHeaders,
+          body: savedBody,
+          // TypeScript doesn't know about duplex, but it's needed for streaming bodies
+          ...(savedBody ? {duplex: 'half'} : {}),
+        } as RequestInit);
+
+        // Retry the request
+        const retryResponse = await fetch(retryRequest);
+
+        logger.debug({status: retryResponse.status}, `[AuthMiddleware] Retry response: ${retryResponse.status}`);
+
+        return retryResponse;
+      }
+
+      return response;
+    },
   };
 }