Release v5.2.0 - Add maintenance mode detection

Add automatic maintenance mode detection via throwOnMaintenanceHeader option.

When enabled, the SDK detects maintenance windows by checking the
sfdc_maintenance response header and throws MaintenanceError (503)
when the value is 'system' or 'site'.

Key features:
- Opt-in via client configuration (backward compatible)
- New MaintenanceError class with detailed error information
- Works with all API endpoints
- Takes precedence over other error handling
- Comprehensive test coverage (100%)

Changes:
- Add MaintenanceError class and tests
- Add throwOnMaintenanceHeader to ClientConfig
- Add header check in doFetch()
- Export MaintenanceError from helpers
- Update README with usage documentation
- Update CHANGELOG for v5.2.0
- Bump version to 5.2.0

Author: priandsf

CHANGELOG.md

@@ -1,5 +1,32 @@
 # CHANGELOG
 
+## v5.2.0
+
+### API Versions
+
+| API Name | API Version |
+|----------|-------------|
+| shopper-login | 1.46.0 |
+| shopper-baskets | 1.11.0 |
+| shopper-baskets | 2.5.1 |
+| shopper-configurations | 1.2.0 |
+| shopper-consents | 1.1.4 |
+| shopper-context | 1.1.3 |
+| shopper-customers | 1.6.1 |
+| shopper-experience | 1.2.1 |
+| shopper-gift-certificates | 1.2.0 |
+| shopper-orders | 1.12.1 |
+| shopper-payments | 1.4.0 |
+| shopper-products | 1.3.0 |
+| shopper-promotions | 1.2.0 |
+| shopper-search | 1.8.0 |
+| shopper-seo | 1.0.17 |
+| shopper-stores | 1.2.0 |
+
+### Enhancements
+
+- Add automatic maintenance mode detection via `throwOnMaintenanceHeader` client config option. When enabled, the SDK throws `MaintenanceError` (503) if the server responds with `sfdc_maintenance` header set to `'system'` or `'site'`. This feature is opt-in and fully backward compatible.
+
 ## v5.1.0
 
 ### API Versions

README.md

@@ -138,6 +138,40 @@ try {
 }
 ```
 
+#### `throwOnMaintenanceHeader`
+
+When `true`, the SDK automatically detects maintenance mode by checking the `sfdc_maintenance` response header. If the header value is `'system'` or `'site'`, the SDK throws a `MaintenanceError` with status 503. This is useful for handling scheduled maintenance windows and displaying appropriate messaging to users. By default, this flag is `false` for backwards compatibility.
+
+```js
+import {ShopperProducts, helpers} from 'commerce-sdk-isomorphic';
+const {MaintenanceError} = helpers;
+
+const config = {
+  throwOnMaintenanceHeader: true,
+  // rest of the config object...
+};
+
+const shopperProducts = new ShopperProducts(config);
+
+// in an async function
+try {
+  const product = await shopperProducts.getProduct({
+    parameters: {id: 'product-id'},
+  });
+} catch (e) {
+  if (e instanceof MaintenanceError) {
+    console.log(`Service in maintenance: ${e.maintenanceType}`); // 'system' or 'site'
+    console.log(`Status: ${e.status}`); // 503
+    // Display maintenance page to user
+  } else {
+    // Handle other errors
+    console.error('API error:', e);
+  }
+}
+```
+
+**Note:** The maintenance check occurs before other error handling and applies even when using `rawResponse: true`.
+
 #### Additional Config Settings
 
 * `headers`: Headers to include with API requests.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "commerce-sdk-isomorphic",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "private": false,
   "description": "Salesforce Commerce SDK Isomorphic",
   "bugs": {

src/static/clientConfig.test.ts

@@ -26,6 +26,7 @@ describe('ClientConfig constructor', () => {
       proxy: 'https://proxy.com',
       transformRequest: ClientConfig.defaults.transformRequest,
       throwOnBadResponse: false,
+      throwOnMaintenanceHeader: false,
       fetch: fetch as FetchFunction,
     };
     expect(new ClientConfig(init)).toEqual({...init});

src/static/clientConfig.ts

@@ -41,6 +41,7 @@ export interface ClientConfigInit<Params extends BaseUriParameters> {
     headers: {[key: string]: string}
   ) => Required<FetchOptions>['body'];
   throwOnBadResponse?: boolean;
+  throwOnMaintenanceHeader?: boolean;
 }
 
 /**
@@ -67,6 +68,8 @@ export default class ClientConfig<Params extends BaseUriParameters>
 
   public throwOnBadResponse: boolean;
 
+  public throwOnMaintenanceHeader: boolean;
+
   constructor(config: ClientConfigInit<Params>) {
     this.headers = {...config.headers};
     this.parameters = {...config.parameters};
@@ -89,6 +92,7 @@ export default class ClientConfig<Params extends BaseUriParameters>
       this.proxy = config.proxy;
     }
     this.throwOnBadResponse = !!config.throwOnBadResponse;
+    this.throwOnMaintenanceHeader = !!config.throwOnMaintenanceHeader;
 
     this.fetch = config.fetch;
   }

src/static/helpers/fetchHelper.test.ts

@@ -8,6 +8,8 @@ import nock from 'nock';
 import {Response} from 'node-fetch';
 import * as environment from './environment';
 import ClientConfig from '../clientConfig';
+import MaintenanceError from '../maintenanceError';
+import ResponseError from '../responseError';
 import {doFetch, encodeSCAPISpecialCharacters} from './fetchHelper';
 
 describe('doFetch', () => {
@@ -158,6 +160,140 @@ describe('doFetch', () => {
       expect.objectContaining(clientConfig.fetchOptions)
     );
   });
+
+  describe('maintenance header check', () => {
+    test('throws MaintenanceError when sfdc_maintenance header is "system"', async () => {
+      nock(basePath)
+        .post(endpointPath)
+        .query({siteId: 'site_id'})
+        .reply(200, responseBody, {sfdc_maintenance: 'system'});
+
+      const copyClientConfig = {...clientConfig, throwOnMaintenanceHeader: true};
+
+      try {
+        await doFetch(url, options, copyClientConfig);
+        fail('Expected MaintenanceError to be thrown');
+      } catch (error) {
+        expect(error).toBeInstanceOf(MaintenanceError);
+        if (error instanceof MaintenanceError) {
+          expect(error.message).toBe('Service unavailable due to system maintenance');
+        }
+      }
+    });
+
+    test('throws MaintenanceError when sfdc_maintenance header is "site"', async () => {
+      nock(basePath)
+        .post(endpointPath)
+        .query({siteId: 'site_id'})
+        .reply(200, responseBody, {sfdc_maintenance: 'site'});
+
+      const copyClientConfig = {...clientConfig, throwOnMaintenanceHeader: true};
+
+      try {
+        await doFetch(url, options, copyClientConfig);
+        fail('Expected MaintenanceError to be thrown');
+      } catch (error) {
+        expect(error).toBeInstanceOf(MaintenanceError);
+        if (error instanceof MaintenanceError) {
+          expect(error.message).toBe('Service unavailable due to site maintenance');
+        }
+      }
+    });
+
+    test('does not throw when sfdc_maintenance header has different value', async () => {
+      nock(basePath)
+        .post(endpointPath)
+        .query({siteId: 'site_id'})
+        .reply(200, responseBody, {sfdc_maintenance: 'other'});
+
+      const copyClientConfig = {...clientConfig, throwOnMaintenanceHeader: true};
+      const data = await doFetch(url, options, copyClientConfig);
+      expect(data).toEqual(responseBody);
+    });
+
+    test('does not throw when throwOnMaintenanceHeader is false', async () => {
+      nock(basePath)
+        .post(endpointPath)
+        .query({siteId: 'site_id'})
+        .reply(200, responseBody, {sfdc_maintenance: 'system'});
+
+      const copyClientConfig = {...clientConfig, throwOnMaintenanceHeader: false};
+      const data = await doFetch(url, options, copyClientConfig);
+      expect(data).toEqual(responseBody);
+    });
+
+    test('does not throw when throwOnMaintenanceHeader is not set', async () => {
+      nock(basePath)
+        .post(endpointPath)
+        .query({siteId: 'site_id'})
+        .reply(200, responseBody, {sfdc_maintenance: 'system'});
+
+      const data = await doFetch(url, options, clientConfig);
+      expect(data).toEqual(responseBody);
+    });
+
+    test('throws MaintenanceError even when rawResponse is true', async () => {
+      nock(basePath)
+        .post(endpointPath)
+        .query({siteId: 'site_id'})
+        .reply(200, responseBody, {sfdc_maintenance: 'system'});
+
+      const copyClientConfig = {...clientConfig, throwOnMaintenanceHeader: true};
+
+      try {
+        await doFetch(url, options, copyClientConfig, true);
+        fail('Expected MaintenanceError to be thrown');
+      } catch (error) {
+        expect(error).toBeInstanceOf(MaintenanceError);
+      }
+    });
+
+    test('MaintenanceError contains correct properties', async () => {
+      nock(basePath)
+        .post(endpointPath)
+        .query({siteId: 'site_id'})
+        .reply(200, responseBody, {sfdc_maintenance: 'site'});
+
+      const copyClientConfig = {...clientConfig, throwOnMaintenanceHeader: true};
+
+      try {
+        await doFetch(url, options, copyClientConfig);
+        fail('Expected MaintenanceError to be thrown');
+      } catch (error) {
+        expect(error).toBeInstanceOf(MaintenanceError);
+        if (error instanceof MaintenanceError) {
+          expect(error.status).toBe(503);
+          expect(error.maintenanceType).toBe('site');
+          expect(error.name).toBe('MaintenanceError');
+          expect(error.response).toBeInstanceOf(Response);
+        }
+      }
+    });
+
+    test('throws MaintenanceError before throwOnBadResponse', async () => {
+      nock(basePath)
+        .post(endpointPath)
+        .query({siteId: 'site_id'})
+        .reply(400, responseBody, {sfdc_maintenance: 'system'});
+
+      const copyClientConfig = {
+        ...clientConfig,
+        throwOnMaintenanceHeader: true,
+        throwOnBadResponse: true,
+      };
+
+      try {
+        await doFetch(url, options, copyClientConfig);
+        fail('Expected MaintenanceError to be thrown');
+      } catch (error) {
+        expect(error).toBeInstanceOf(MaintenanceError);
+        expect(error).not.toBeInstanceOf(ResponseError);
+        if (error instanceof Error) {
+          expect(error.message).not.toContain('400 Bad Request');
+        }
+      }
+    });
+  });
 });
 
 describe('encodeSCAPISpecialCharacters', () => {

src/static/helpers/fetchHelper.ts

@@ -8,6 +8,7 @@ import {BodyInit} from 'node-fetch';
 import {BaseUriParameters} from '.';
 import type {FetchOptions} from '../clientConfig';
 import ResponseError from '../responseError';
+import MaintenanceError from '../maintenanceError';
 import {fetch} from './environment';
 import {ClientConfigInit} from '../clientConfig';
 
@@ -55,6 +56,15 @@ export const doFetch = async <Params extends BaseUriParameters>(
   const fetcher = clientConfig?.fetch || fetch;
 
   const response = await fetcher(url, requestOptions);
+
+  // Check for maintenance header before processing response
+  if (clientConfig?.throwOnMaintenanceHeader) {
+    const maintenanceHeader = response.headers.get('sfdc_maintenance');
+    if (maintenanceHeader === 'system' || maintenanceHeader === 'site') {
+      throw new MaintenanceError(response, maintenanceHeader);
+    }
+  }
+
   if (rawResponse) {
     return response;
   }

src/static/helpers/index.ts

@@ -11,3 +11,4 @@ export * from './slasHelper';
 export * from './types';
 export * from './customApi';
 export * from './fetchHelper';
+export {default as MaintenanceError} from '../maintenanceError';

src/static/maintenanceError.test.ts

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import {Response} from 'node-fetch';
+import MaintenanceError from './maintenanceError';
+
+describe('MaintenanceError', () => {
+  test('creates error with system maintenance type', () => {
+    const response = new Response('{}', {
+      status: 200,
+      headers: {sfdc_maintenance: 'system'},
+    });
+
+    const error = new MaintenanceError(response, 'system');
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(MaintenanceError);
+    expect(error.name).toBe('MaintenanceError');
+    expect(error.message).toBe('Service unavailable due to system maintenance');
+    expect(error.status).toBe(503);
+    expect(error.maintenanceType).toBe('system');
+    expect(error.response).toBe(response);
+  });
+
+  test('creates error with site maintenance type', () => {
+    const response = new Response('{}', {
+      status: 200,
+      headers: {sfdc_maintenance: 'site'},
+    });
+
+    const error = new MaintenanceError(response, 'site');
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(MaintenanceError);
+    expect(error.name).toBe('MaintenanceError');
+    expect(error.message).toBe('Service unavailable due to site maintenance');
+    expect(error.status).toBe(503);
+    expect(error.maintenanceType).toBe('site');
+    expect(error.response).toBe(response);
+  });
+
+  test('error can be caught and properties accessed', () => {
+    const response = new Response('{}', {status: 200});
+    const error = new MaintenanceError(response, 'system');
+
+    try {
+      throw error;
+    } catch (caught) {
+      expect(caught).toBeInstanceOf(MaintenanceError);
+      if (caught instanceof MaintenanceError) {
+        expect(caught.status).toBe(503);
+        expect(caught.maintenanceType).toBe('system');
+        expect(caught.response).toBe(response);
+      }
+    }
+  });
+
+  test('error has correct property types', () => {
+    const response = new Response('{}', {status: 200});
+    const error = new MaintenanceError(response, 'system');
+
+    expect(error.status).toBe(503);
+    expect(typeof error.status).toBe('number');
+    expect(error.maintenanceType).toBe('system');
+    expect(['system', 'site']).toContain(error.maintenanceType);
+  });
+});

src/static/maintenanceError.ts

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+/**
+ * Error thrown when the sfdc_maintenance header is detected in a response
+ * and throwOnMaintenanceHeader is enabled in client configuration.
+ *
+ * @class MaintenanceError
+ * @extends Error
+ */
+export default class MaintenanceError extends Error {
+  public readonly response: Response | import('node-fetch').Response;
+
+  public readonly maintenanceType: 'system' | 'site';
+
+  public readonly status = 503;
+
+  constructor(
+    response: Response | import('node-fetch').Response,
+    maintenanceType: 'system' | 'site'
+  ) {
+    super(`Service unavailable due to ${maintenanceType} maintenance`);
+    this.name = 'MaintenanceError';
+    this.response = response;
+    this.maintenanceType = maintenanceType;
+  }
+}