feat(core): add locale parameter to client.fetch() and harden beforeRequest

Add optional locale parameter to client.fetch() for use in cached
contexts. Wrap headers() call in beforeRequest with try/catch so it
gracefully degrades inside unstable_cache.

No changes to getChannelId or beforeRequest callback signatures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jorgemoya

.changeset/locale-param-client.md

@@ -0,0 +1,5 @@
+---
+"@bigcommerce/catalyst-client": minor
+---
+
+Add optional `locale` parameter to `client.fetch()`. This allows locale to be passed explicitly for use in cached contexts where `getLocale()` is unavailable.

.changeset/locale-param-core.md

@@ -0,0 +1,5 @@
+---
+"@bigcommerce/catalyst-core": minor
+---
+
+Wrap IP forwarding headers (`X-Forwarded-For`, `True-Client-IP`) in try/catch for safety inside `unstable_cache` contexts where `headers()` is unavailable.

core/client/index.ts

@@ -53,12 +53,16 @@ export const client = createClient({
     const locale = await getLocale();
 
     if (fetchOptions?.cache && ['no-store', 'no-cache'].includes(fetchOptions.cache)) {
-      const { headers } = await import('next/headers');
-      const ipAddress = (await headers()).get('X-Forwarded-For');
+      try {
+        const { headers } = await import('next/headers');
+        const ipAddress = (await headers()).get('X-Forwarded-For');
 
-      if (ipAddress) {
-        requestHeaders['X-Forwarded-For'] = ipAddress;
-        requestHeaders['True-Client-IP'] = ipAddress;
+        if (ipAddress) {
+          requestHeaders['X-Forwarded-For'] = ipAddress;
+          requestHeaders['True-Client-IP'] = ipAddress;
+        }
+      } catch {
+        // headers() is unavailable inside unstable_cache / 'use cache' contexts
       }
     }
 

packages/client/src/client.ts

@@ -85,6 +85,7 @@ class Client<FetcherRequestInit extends RequestInit = RequestInit> {
     customerAccessToken?: string;
     fetchOptions?: FetcherRequestInit;
     channelId?: string;
+    locale?: string;
     errorPolicy?: GraphQLErrorPolicy;
     validateCustomerAccessToken?: boolean;
   }): Promise<BigCommerceResponse<TResult>>;
@@ -96,6 +97,7 @@ class Client<FetcherRequestInit extends RequestInit = RequestInit> {
     customerAccessToken?: string;
     fetchOptions?: FetcherRequestInit;
     channelId?: string;
+    locale?: string;
     errorPolicy?: GraphQLErrorPolicy;
     validateCustomerAccessToken?: boolean;
   }): Promise<BigCommerceResponse<TResult>>;
@@ -106,6 +108,7 @@ class Client<FetcherRequestInit extends RequestInit = RequestInit> {
     customerAccessToken,
     fetchOptions = {} as FetcherRequestInit,
     channelId,
+    locale: _locale, // eslint-disable-line @typescript-eslint/no-unused-vars
     errorPolicy = 'none',
     validateCustomerAccessToken = true,
   }: {
@@ -114,6 +117,7 @@ class Client<FetcherRequestInit extends RequestInit = RequestInit> {
     customerAccessToken?: string;
     fetchOptions?: FetcherRequestInit;
     channelId?: string;
+    locale?: string;
     errorPolicy?: GraphQLErrorPolicy;
     validateCustomerAccessToken?: boolean;
   }): Promise<BigCommerceResponse<TResult>> {