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": patch
+---
+
+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": patch
+---
+
+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

@@ -41,24 +41,28 @@ export const client = createClient({
   logger:
     (process.env.NODE_ENV !== 'production' && process.env.CLIENT_LOGGER !== 'false') ||
     process.env.CLIENT_LOGGER === 'true',
-  getChannelId: async (defaultChannelId: string) => {
-    const locale = await getLocale();
+  getChannelId: async (defaultChannelId: string, locale?: string) => {
+    const resolvedLocale = locale ?? (await getLocale());
 
     // We use the default channelId as a fallback, but it is not ideal in some scenarios.
-    return getChannelIdFromLocale(locale) ?? defaultChannelId;
+    return getChannelIdFromLocale(resolvedLocale) ?? defaultChannelId;
   },
   beforeRequest: async (fetchOptions) => {
     // We can't serialize a `Headers` object within this method so we have to opt into using a plain object
     const requestHeaders: Record<string, string> = {};
     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

@@ -49,7 +49,7 @@ type GraphQLErrorPolicy = 'none' | 'all' | 'auth' | 'ignore';
 class Client<FetcherRequestInit extends RequestInit = RequestInit> {
   private backendUserAgent: string;
   private readonly defaultChannelId: string;
-  private getChannelId: (defaultChannelId: string) => Promise<string> | string;
+  private getChannelId: (defaultChannelId: string, locale?: string) => Promise<string> | string;
   private beforeRequest?: (
     fetchOptions?: FetcherRequestInit,
   ) => Promise<Partial<FetcherRequestInit> | undefined> | Partial<FetcherRequestInit> | undefined;
@@ -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,
     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>> {
@@ -126,6 +130,7 @@ class Client<FetcherRequestInit extends RequestInit = RequestInit> {
       channelId,
       operationInfo.name,
       operationInfo.type,
+      locale,
     );
     const { headers: additionalFetchHeaders = {}, ...additionalFetchOptions } =
       (await this.beforeRequest?.(fetchOptions)) ?? {};
@@ -143,6 +148,7 @@ class Client<FetcherRequestInit extends RequestInit = RequestInit> {
         ...(this.trustedProxySecret && { 'X-BC-Trusted-Proxy-Secret': this.trustedProxySecret }),
         ...Object.fromEntries(new Headers(additionalFetchHeaders).entries()),
         ...Object.fromEntries(new Headers(headers).entries()),
+        ...(locale && { 'Accept-Language': locale }),
       },
       body: JSON.stringify({
         query,
@@ -210,8 +216,8 @@ class Client<FetcherRequestInit extends RequestInit = RequestInit> {
     return response.text();
   }
 
-  private async getCanonicalUrl(channelId?: string) {
-    const resolvedChannelId = channelId ?? (await this.getChannelId(this.defaultChannelId));
+  private async getCanonicalUrl(channelId?: string, locale?: string) {
+    const resolvedChannelId = channelId ?? (await this.getChannelId(this.defaultChannelId, locale));
 
     return `https://store-${this.config.storeHash}-${resolvedChannelId}.${graphqlApiDomain}`;
   }
@@ -220,8 +226,9 @@ class Client<FetcherRequestInit extends RequestInit = RequestInit> {
     channelId?: string,
     operationName?: string,
     operationType?: string,
+    locale?: string,
   ) {
-    const baseUrl = new URL(`${await this.getCanonicalUrl(channelId)}/graphql`);
+    const baseUrl = new URL(`${await this.getCanonicalUrl(channelId, locale)}/graphql`);
 
     if (operationName) {
       baseUrl.searchParams.set('operation', operationName);