Merge pull request #113 from Relewise/feat/allow-setting-cache-mode

feat: allow overwriting the cache mode

Author: brianhdk

README.md

@@ -40,6 +40,18 @@ Replace the `RELEWISE_DATASET_ID`, `RELEWISE_API_KEY` and `RELEWISE_SERVER_URL`
 After which you have access to various methods depending on the client you've bootstrapped.
 
 ***Note: serverUrl is not required and will default to https://api.relewise.com/*** 
+
+#### Cache mode
+By default, clients use `cache: 'no-cache'` to ensure responses are always fresh — this prevents stale results that could break personalization.
+However, some service workers (often used in integrations) do not support the `no-cache` mode.
+
+```ts
+const integrator = new Integrator(RELEWISE_DATASET_ID, RELEWISE_API_KEY, {
+    serverUrl: RELEWISE_SERVER_URL,
+    cache: 'default'
+});
+```
+
 ### Tracking
 
 If you need to track e.g. Product-, Category or Content Views, track Cart Updates or Completed Orders in your solution, you need to use the `Tracker` 

packages/client/src/relewise.client.ts

@@ -1,12 +1,12 @@
-import { error } from 'console';
 import version from './version';
 
 export interface RelewiseClientOptions {
     serverUrl?: string;
+    cache?: RequestCache;
 }
 
 export interface RelewiseRequestOptions {
-    abortSignal?: AbortSignal
+    abortSignal?: AbortSignal;
 }
 
 export class ProblemDetailsError extends Error {
@@ -35,6 +35,7 @@ export abstract class RelewiseClient {
     private readonly _serverUrl: string = 'https://api.relewise.com';
     private readonly _urlPath: string = 'v1';
     private readonly _apiKeyHeader: string;
+    private readonly cache: RequestCache = 'no-cache';
 
     constructor(protected readonly datasetId: string, protected readonly apiKey: string, options?: RelewiseClientOptions) {
         if (!datasetId) throw new Error('Dataset id cannot be null or empty. Please contact Relewise if you don\'t have an account already or would like a free demo license');
@@ -45,6 +46,9 @@ export abstract class RelewiseClient {
         if (options?.serverUrl) {
             this._serverUrl = options.serverUrl;
         }
+        if (options?.cache) {
+            this.cache = options.cache;
+        }
     }
 
     public get serverUrl(): string {
@@ -64,26 +68,26 @@ export abstract class RelewiseClient {
                 },
                 body: JSON.stringify(data),
                 signal: options?.abortSignal,
-                cache: 'no-cache',
+                cache: this.cache,
             });
 
             if (!response.ok) {
                 let responseMessage: HttpProblemDetails | null = null;
-    
-                try { 
+
+                try {
                     responseMessage = await response.json();
-                } catch (_) { 
+                } catch (_) {
                 }
-    
+
                 const details = responseMessage?.detail ? `Details: ${responseMessage.detail}\n` : '';
-    
+
                 throw new ProblemDetailsError(`Error when calling the Relewise API.\n\nTitle: ${response.statusText}\nStatus: ${response.status}\n${details}\nRead more in the details property if there is error response or look in the network tab.`, responseMessage);
             }
 
             return await this.parseJson<TResponse>(response);
 
         } catch (err) {
-           this.handleRequestError(err);
+            this.handleRequestError(err);
         }
     }
 
@@ -97,11 +101,50 @@ export abstract class RelewiseClient {
     private handleRequestError(err: unknown): never {
         if (err instanceof ProblemDetailsError) throw err;
         if (err instanceof DOMException) throw err;
-        
-        console.error("Network error or preflight request failed. Check API Key and Dataset ID.");
-        throw new Error("Network error or preflight request failed. Check API Key and Dataset ID.");
+
+        let extraInfo = '';
+        let possibleCause: string | null = null;
+
+        if (err instanceof Error) {
+            extraInfo += `\nOriginal error: ${err.name} - ${err.message}`;
+            if ((err as any).code) {
+                extraInfo += `\nCode: ${(err as any).code}`;
+            }
+
+            const message = err.message.toLowerCase();
+
+            if (message.includes('failed to fetch')) {
+                possibleCause = 'Failed to connect to API. Possible network outage, incorrect server URL, or CORS/preflight issue.';
+            }
+            else if (message.includes('401') || message.includes('unauthorized')) {
+                possibleCause = 'Unauthorized: Your API Key might be missing, expired, or incorrect.';
+            }
+            else if (message.includes('403') || message.includes('forbidden')) {
+                possibleCause = 'Forbidden: Your API Key might not have access to this dataset.';
+            }
+            else if (message.includes('404') || message.includes('not found')) {
+                possibleCause = 'Not Found: The Dataset ID or endpoint may be incorrect.';
+            }
+        }
+        else {
+            extraInfo += `\nNon-Error thrown: ${JSON.stringify(err)}`;
+        }
+
+        const errorMessage =
+            "Network error or preflight request failed.\n" +
+            (possibleCause ? `Possible cause: ${possibleCause}\n` : "") +
+            "Troubleshooting steps:\n" +
+            "- Check your API Key is correct and active\n" +
+            "- Verify the Dataset ID exists and is correctly spelled\n" +
+            "- Ensure the server URL is reachable from your network\n" +
+            "- Check browser console/network tab for blocked requests or CORS issues" +
+            extraInfo;
+
+        console.error(errorMessage);
+        throw new Error(errorMessage);
     }
 
+
     private async parseJson<T>(response: Response): Promise<T | undefined> {
         try {
             return await response.json();