@conduit-client/salesforce-lightning-service-worker 3.3.0 → 3.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Salesforce Lightning Service Worker
 
-A lightweight service worker utility for Salesforce Lightning applications that provides basic service worker registration and management functionality.
+A specialized HTTP client and service worker for Salesforce Lightning applications that provides automatic CSRF (Cross-Site Request Forgery) protection for API requests. This package ensures secure communication with Salesforce APIs by automatically managing CSRF tokens.
 
 ## Installation
 
@@ -10,72 +10,107 @@ npm install @conduit-client/salesforce-lightning-service-worker
 
 ## Usage
 
-This package exports two main functions that work together to implement service worker functionality in your application:
+This package provides two ways to use CSRF protection:
 
-### 1. Register the Service Worker (App Code)
+### 1. Using ConduitClient (Recommended)
 
-In your main application code, use the `registerServiceWorker` function to register your service worker:
+The `ConduitClient` provides a convenient wrapper around fetch with automatic CSRF protection:
 
 ```typescript
-import { registerServiceWorker } from '@conduit-client/salesforce-lightning-service-worker';
+import { ConduitClient } from '@conduit-client/salesforce-lightning-service-worker';
 
-// Register service worker with module type support
-const registration = await registerServiceWorker('./sw.js', { type: 'module' });
+// Create a client instance
+const client = ConduitClient.create();
+
+// Make API calls - CSRF protection is automatic for protected endpoints
+const response = await client.fetch('/services/data/v65.0/sobjects/Account', {
+  method: 'POST',
+  body: JSON.stringify({ Name: 'Test Account' }),
+});
 ```
 
-**Parameters:**
+### 2. Using Service Worker (Advanced)
+
+For applications that desire service worker-level CSRF protection:
 
-- `scriptUrl`: The URL path to your service worker file
-- `options`: Optional `RegistrationOptions` (e.g., `{ type: 'module' }` for ES6 module support)
+#### Register the Service Worker
+
+```typescript
+import { ConduitClient } from '@conduit-client/salesforce-lightning-service-worker';
 
-### 2. Create the Service Worker File
+// Register service worker for enhanced protection
+await ConduitClient.registerServiceWorker('./sw.js');
+```
 
-You must configure your bundler to expose a statically named service worker file (without hash tokens) that calls the `createServiceWorker` function:
+#### Create the Service Worker File
 
 ```typescript
-// sw.js or similar
-import { createServiceWorker } from '@conduit-client/salesforce-lightning-service-worker';
+// sw.js - served statically by your bundler
+import { ConduitClient } from '@conduit-client/salesforce-lightning-service-worker';
 
-createServiceWorker();
+// Define service worker behavior
+ConduitClient.defineServiceWorker({ debug: true });
 ```
 
+**NOTE: ** Note, if service worker registration fails the wrapper approach will remain in
+place in order to maintain CSRF protection.
+
 **Important Configuration Notes:**
 
-1. **Static File Name**: The service worker file must have a static name (e.g., `sw.js`) without hash tokens to ensure consistent registration/updates
-2. **Module Type**: If using ES6 imports in your service worker, register it with `{ type: 'module' }`
-3. **Scope**: The path from which the service worker file is served establishes the scope for which the service worker will apply. For example:
-   - `/sw.js` → Controls the entire origin
-   - `/app/sw.js` → Only controls paths under `/app/`
+1. **Static File Name**: The service worker file must have a static name (e.g., `sw.js`) without hash tokens
+2. **Module Type**: Use ES6 modules for modern bundlers
+3. **Scope**: Service worker scope determines which requests it can intercept
+
+## CSRF Protection Features
+
+This package provides automatic CSRF protection with the following features:
 
-## Service Worker Features
+### Automatic Token Management
 
-The `createServiceWorker` function sets up a basic service worker with:
+- **Token Caching**: CSRF tokens are cached using the Cache API for performance
+- **Token Refresh**: Automatically refreshes tokens when they become invalid
+- **Retry Logic**: Retries requests once with fresh tokens on authentication failures
+
+### Protected Endpoints
+
+- **Method Protection**: Automatically protects data-mutating methods (POST, PUT, PATCH, DELETE)
+- **URL Protection**: Currently protects all Salesforce API endpoints under `/services`
+- **Intelligent Detection**: Only applies CSRF protection where needed
+
+### Service Worker Integration
 
 - **Install Handler**: Skips waiting to activate immediately
 - **Activate Handler**: Claims all clients immediately
-- **Fetch Handler**: Intercepts and logs all `fetch` requests (currently passes through all requests)
+- **Fetch Interception**: Intercepts and enhances requests with CSRF tokens
 
-## Example Implementation
+## Complete Example
 
 ```typescript
-// Main app code
-import { registerServiceWorker } from '@conduit-client/salesforce-lightning-service-worker';
-
-async function initializeApp() {
-  try {
-    const registration = await registerServiceWorker('./sw.js', { type: 'module' });
-    console.log('Service worker registered:', registration?.scope);
-  } catch (error) {
-    console.error('Service worker registration failed:', error);
-  }
+// Main application code
+import { ConduitClient } from '@conduit-client/salesforce-lightning-service-worker';
+
+async function setupApiClient() {
+  // Optionally register service worker for enhanced protection
+  await ConduitClient.registerServiceWorker('./sw.js');
+
+  // Create client for API calls
+  const client = ConduitClient.create();
+
+  // Make API calls - CSRF protection is automatic
+  const account = await client.fetch('/services/data/v65.0/sobjects/Account', {
+    method: 'POST',
+    body: JSON.stringify({ Name: 'New Account' }),
+  });
+
+  return client;
 }
 ```
 
 ```typescript
-// sw.js (served statically by your bundler)
-import { createServiceWorker } from '@conduit-client/salesforce-lightning-service-worker';
+// sw.js - Service worker file if `registerServiceWorker` is used
+import { ConduitClient } from '@conduit-client/salesforce-lightning-service-worker';
 
-createServiceWorker();
+ConduitClient.defineServiceWorker({ debug: false });
 ```
 
 ## Development

package/dist/index.js

@@ -5,6 +5,7 @@
  */
 const CACHE_VERSION = 1;
 const CACHE_NAME = `salesforce-lightning-service-worker-${CACHE_VERSION}`;
+const CSRF_HEADER = "X-CSRF-Token";
 async function withCache(callback) {
   if (caches) {
     const cache = await caches.open(CACHE_NAME);
@@ -19,7 +20,7 @@ function isProtectedMethod(method) {
 }
 function isProtectedUrl(urlString) {
   const url = new URL(urlString);
-  return url.pathname.startsWith("/services");
+  return url.pathname.includes("/services/data/v");
 }
 async function isTokenInvalid(response) {
   var _a;
@@ -29,61 +30,152 @@ async function isTokenInvalid(response) {
   }
   return false;
 }
-function createCsrfHandler(version) {
-  const CSRF_TOKEN_URL = `/services/data/v${version}/ui-api/session/csrf`;
+function createLightningFetch(config = {}) {
+  const { fireEvent = () => {
+  }, tokenSource } = config;
+  let tokenUrl = "/services/data/v65.0/ui-api/session/csrf";
+  let tokenProvider = obtainToken;
+  if (tokenSource) {
+    if (typeof tokenSource === "string" || tokenSource instanceof URL) {
+      tokenUrl = tokenSource;
+    } else if (typeof tokenSource === "function") {
+      tokenProvider = tokenSource;
+    }
+  }
+  function generateId() {
+    return Date.now().toString(36);
+  }
   async function obtainToken() {
-    let response = await withCache((cache) => cache.match(CSRF_TOKEN_URL));
+    const id = generateId();
+    fireEvent("csrf_token_obtain_start", id);
+    let response = await withCache((cache) => cache.match(tokenUrl));
     if (!response) {
-      response = await fetch(CSRF_TOKEN_URL, { method: "get" });
+      fireEvent("csrf_token_fetch_start", id);
+      response = await fetch(tokenUrl, { method: "get" });
+      fireEvent("csrf_token_fetch_complete", id, { status: response.status });
+    } else {
+      fireEvent("csrf_token_cache_hit", id);
     }
     const csrfToken = (await response.clone().json()).csrfToken;
-    await withCache((cache) => cache.put(CSRF_TOKEN_URL, response));
+    await withCache((cache) => cache.put(tokenUrl, response));
+    fireEvent("csrf_token_obtain_complete", id);
     return csrfToken;
   }
-  let tokenPromise = obtainToken();
+  let tokenPromise = tokenProvider();
   async function refreshToken() {
-    await withCache((cache) => cache.delete(CSRF_TOKEN_URL));
-    tokenPromise = obtainToken();
+    const id = generateId();
+    fireEvent("csrf_token_refresh_start", id);
+    await withCache((cache) => cache.delete(tokenUrl));
+    tokenPromise = tokenProvider();
+    fireEvent("csrf_token_refresh_complete", id);
   }
   async function fetchWithToken(request) {
     const headers = new Headers(request.headers);
-    headers.set("X-CSRF-Token", await tokenPromise);
+    if (!headers.has(CSRF_HEADER)) {
+      headers.set(CSRF_HEADER, await tokenPromise);
+    }
     return fetch(request, { headers });
   }
-  return async (request) => {
+  return async function lightningFetch2(input, init) {
+    const id = generateId();
+    const request = new Request(input, init);
     if (isProtectedMethod(request.method) && isProtectedUrl(request.url)) {
-      try {
-        const response = await fetchWithToken(request.clone());
-        if (await isTokenInvalid(response)) {
-          await refreshToken();
-          return fetchWithToken(request.clone());
-        } else {
-          return response;
-        }
-      } catch (error) {
-        return new Response(JSON.stringify({ error }), { status: 500 });
+      fireEvent("protected_request_start", id, { method: request.method, url: request.url });
+      const response = await fetchWithToken(request.clone());
+      if (await isTokenInvalid(response)) {
+        fireEvent("csrf_token_invalid", id, { status: response.status });
+        await refreshToken();
+        const retryResponse = await fetchWithToken(request.clone());
+        fireEvent("protected_request_complete", id, {
+          method: request.method,
+          url: request.url,
+          status: retryResponse.status,
+          retried: true
+        });
+        return retryResponse;
+      } else {
+        fireEvent("protected_request_complete", id, {
+          method: request.method,
+          url: request.url,
+          status: response.status,
+          retried: false
+        });
+        return response;
       }
     } else {
+      fireEvent("unprotected_request", id, { method: request.method, url: request.url });
       return fetch(request);
     }
   };
 }
-function createServiceWorker({ version, debug }) {
-  const scope = self;
-  scope.addEventListener("install", (event) => {
-    if (debug) console.log("[Service Worker] Installed");
-    event.waitUntil(scope.skipWaiting());
-  });
-  scope.addEventListener("activate", (event) => {
-    if (debug) console.log("[Service Worker] Activated");
-    event.waitUntil(scope.clients.claim());
-  });
-  const applyCsrfProtection = createCsrfHandler(version);
-  scope.addEventListener("fetch", (event) => {
-    event.respondWith(applyCsrfProtection(event.request));
-  });
+const lightningFetch = createLightningFetch();
+let clientFetch = lightningFetch;
+class ConduitClient {
+  constructor() {
+  }
+  /**
+   * Makes an HTTP request
+   *
+   * @param input - The URL, Request object, or relative path to request
+   * @param init - Optional request configuration that will be merged with defaults
+   * @returns Promise that resolves to the Response object
+   */
+  fetch(input, init = {}) {
+    return clientFetch(input, init);
+  }
+  /**
+   * Factory method to create a new ConduitClient instance
+   *
+   * @returns A new ConduitClient instance
+   */
+  static create() {
+    return new ConduitClient();
+  }
+  /**
+   * Registers a service worker for enhanced CSRF protection and caching.
+   * When successfully registered, the client will switch to using native fetch
+   * as the service worker will handle CSRF protection.
+   *
+   * The script URL must identify a source file that calls `defineServiceWorker`.
+   *
+   * @param scriptURL - URL or path to the service worker script
+   */
+  static async registerServiceWorker(scriptURL) {
+    if ("serviceWorker" in navigator) {
+      try {
+        const registration = await navigator.serviceWorker.register(scriptURL, {
+          type: "module"
+        });
+        clientFetch = fetch;
+        console.log("[Conduit Client] Service registration succeeded:", registration);
+      } catch (error) {
+        console.error(
+          "[Conduit Client] Service Worker registration failed (using decorated `fetch`):",
+          error
+        );
+      }
+    }
+  }
+  /**
+   * Defines the service worker behavior for CSRF protection.
+   *
+   * This method must be called within a service worker script whose URL is supplied to
+   * `registerServiceWorker`
+   */
+  static defineServiceWorker() {
+    const scope = self;
+    scope.addEventListener("install", (event) => {
+      event.waitUntil(scope.skipWaiting());
+    });
+    scope.addEventListener("activate", (event) => {
+      event.waitUntil(scope.clients.claim());
+    });
+    scope.addEventListener("fetch", (event) => {
+      event.respondWith(lightningFetch(event.request));
+    });
+  }
 }
 export {
-  createServiceWorker
+  ConduitClient
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/csrf.ts","../src/index.ts"],"sourcesContent":["const CACHE_VERSION = 1;\nconst CACHE_NAME = `salesforce-lightning-service-worker-${CACHE_VERSION}`;\n\n/**\n * Retrieves the cache and supplies it to a callback.\n *\n * @param callback\n */\nasync function withCache<T>(callback: (cache: Cache) => Promise<T>): Promise<T | undefined> {\n    // defend against the cache API not being available\n    if (caches) {\n        const cache = await caches.open(CACHE_NAME);\n        return callback(cache);\n    } else {\n        return undefined;\n    }\n}\n\n/**\n * Determine if an HTTP method is one that mutates data.\n */\nfunction isProtectedMethod(method: string) {\n    const normalizedMethod = method.toLowerCase();\n    return (\n        normalizedMethod === 'post' ||\n        normalizedMethod === 'put' ||\n        normalizedMethod === 'patch' ||\n        normalizedMethod === 'delete'\n    );\n}\n\n/**\n * Determine if the URL is for a path that has CSRF protection.\n *\n * Note: Could allow customization\n */\nfunction isProtectedUrl(urlString: string) {\n    const url = new URL(urlString);\n    return url.pathname.startsWith('/services');\n}\n\n/**\n * Check response for status and error code of an invalid token\n */\nasync function isTokenInvalid(response: Response) {\n    if (response.status === 400) {\n        // clone response to read body without consuming it\n        const body = await response.clone().json();\n\n        // check for specific error code\n        return body[0]?.errorCode === 'INVALID_ACCESS_TOKEN';\n    }\n\n    return false;\n}\n\nexport function createCsrfHandler(version: string) {\n    const CSRF_TOKEN_URL = `/services/data/v${version}/ui-api/session/csrf`;\n\n    async function obtainToken(): Promise<string> {\n        // look up response in cache\n        let response = await withCache((cache) => cache.match(CSRF_TOKEN_URL));\n\n        if (!response) {\n            // cached response not available to fetch\n            response = await fetch(CSRF_TOKEN_URL, { method: 'get' });\n        }\n\n        // extract token using clone so caching can still process\n        const csrfToken: string = (await response.clone().json()).csrfToken;\n\n        // store token response\n        await withCache((cache) => cache.put(CSRF_TOKEN_URL, response));\n\n        return csrfToken;\n    }\n\n    let tokenPromise = obtainToken();\n\n    /**\n     * Clear any cached token and retrieve a new one.\n     */\n    async function refreshToken() {\n        await withCache((cache) => cache.delete(CSRF_TOKEN_URL));\n\n        tokenPromise = obtainToken();\n    }\n\n    /**\n     * Make a request with the token header based on the supplied request\n     */\n    async function fetchWithToken(request: Request) {\n        // combine original headers with new csrf header\n        const headers = new Headers(request.headers);\n        headers.set('X-CSRF-Token', await tokenPromise!);\n\n        // make request with updated headers\n        return fetch(request, { headers });\n    }\n\n    /**\n     * Applies a valid CSRF token to targeted requests that modify data\n     */\n    return async (request: Request): Promise<Response> => {\n        // see if the method and url qualify for CSRF\n        if (isProtectedMethod(request.method) && isProtectedUrl(request.url)) {\n            try {\n                // make request with token, clone so that any retry isn't based on a consumed request\n                const response = await fetchWithToken(request.clone());\n\n                // see if token was bad\n                if (await isTokenInvalid(response)) {\n                    // it was, so refresh and try again\n                    await refreshToken();\n                    return fetchWithToken(request.clone());\n                } else {\n                    // use response\n                    return response;\n                }\n            } catch (error) {\n                // always need to return a response\n                return new Response(JSON.stringify({ error }), { status: 500 });\n            }\n        } else {\n            // protection not required, run as is\n            return fetch(request);\n        }\n    };\n}\n","import { createCsrfHandler } from './csrf';\n\nexport type Config = {\n    version: string;\n    debug?: boolean;\n};\n\n/**\n * Adds event listeners for setting up service worker.\n *\n * @param version\n * @param debug\n */\nexport function createServiceWorker({ version, debug }: Config) {\n    const scope = self as any as ServiceWorkerGlobalScope;\n\n    scope.addEventListener('install', (event) => {\n        if (debug) console.log('[Service Worker] Installed');\n\n        // Skip waiting to activate immediately\n        event.waitUntil(scope.skipWaiting());\n    });\n\n    scope.addEventListener('activate', (event) => {\n        if (debug) console.log('[Service Worker] Activated');\n\n        // Claim all clients immediately\n        event.waitUntil(scope.clients.claim());\n    });\n\n    const applyCsrfProtection = createCsrfHandler(version);\n    scope.addEventListener('fetch', (event) => {\n        // Apply CSRF protection\n        event.respondWith(applyCsrfProtection(event.request));\n    });\n}\n"],"names":[],"mappings":";;;;;AAAA,MAAM,gBAAgB;AACtB,MAAM,aAAa,uCAAuC,aAAa;AAOvE,eAAe,UAAa,UAAgE;AAExF,MAAI,QAAQ;AACR,UAAM,QAAQ,MAAM,OAAO,KAAK,UAAU;AAC1C,WAAO,SAAS,KAAK;AAAA,EACzB,OAAO;AACH,WAAO;AAAA,EACX;AACJ;AAKA,SAAS,kBAAkB,QAAgB;AACvC,QAAM,mBAAmB,OAAO,YAAA;AAChC,SACI,qBAAqB,UACrB,qBAAqB,SACrB,qBAAqB,WACrB,qBAAqB;AAE7B;AAOA,SAAS,eAAe,WAAmB;AACvC,QAAM,MAAM,IAAI,IAAI,SAAS;AAC7B,SAAO,IAAI,SAAS,WAAW,WAAW;AAC9C;AAKA,eAAe,eAAe,UAAoB;;AAC9C,MAAI,SAAS,WAAW,KAAK;AAEzB,UAAM,OAAO,MAAM,SAAS,MAAA,EAAQ,KAAA;AAGpC,aAAO,UAAK,CAAC,MAAN,mBAAS,eAAc;AAAA,EAClC;AAEA,SAAO;AACX;AAEO,SAAS,kBAAkB,SAAiB;AAC/C,QAAM,iBAAiB,mBAAmB,OAAO;AAEjD,iBAAe,cAA+B;AAE1C,QAAI,WAAW,MAAM,UAAU,CAAC,UAAU,MAAM,MAAM,cAAc,CAAC;AAErE,QAAI,CAAC,UAAU;AAEX,iBAAW,MAAM,MAAM,gBAAgB,EAAE,QAAQ,OAAO;AAAA,IAC5D;AAGA,UAAM,aAAqB,MAAM,SAAS,MAAA,EAAQ,QAAQ;AAG1D,UAAM,UAAU,CAAC,UAAU,MAAM,IAAI,gBAAgB,QAAQ,CAAC;AAE9D,WAAO;AAAA,EACX;AAEA,MAAI,eAAe,YAAA;AAKnB,iBAAe,eAAe;AAC1B,UAAM,UAAU,CAAC,UAAU,MAAM,OAAO,cAAc,CAAC;AAEvD,mBAAe,YAAA;AAAA,EACnB;AAKA,iBAAe,eAAe,SAAkB;AAE5C,UAAM,UAAU,IAAI,QAAQ,QAAQ,OAAO;AAC3C,YAAQ,IAAI,gBAAgB,MAAM,YAAa;AAG/C,WAAO,MAAM,SAAS,EAAE,SAAS;AAAA,EACrC;AAKA,SAAO,OAAO,YAAwC;AAElD,QAAI,kBAAkB,QAAQ,MAAM,KAAK,eAAe,QAAQ,GAAG,GAAG;AAClE,UAAI;AAEA,cAAM,WAAW,MAAM,eAAe,QAAQ,OAAO;AAGrD,YAAI,MAAM,eAAe,QAAQ,GAAG;AAEhC,gBAAM,aAAA;AACN,iBAAO,eAAe,QAAQ,OAAO;AAAA,QACzC,OAAO;AAEH,iBAAO;AAAA,QACX;AAAA,MACJ,SAAS,OAAO;AAEZ,eAAO,IAAI,SAAS,KAAK,UAAU,EAAE,MAAA,CAAO,GAAG,EAAE,QAAQ,KAAK;AAAA,MAClE;AAAA,IACJ,OAAO;AAEH,aAAO,MAAM,OAAO;AAAA,IACxB;AAAA,EACJ;AACJ;ACnHO,SAAS,oBAAoB,EAAE,SAAS,SAAiB;AAC5D,QAAM,QAAQ;AAEd,QAAM,iBAAiB,WAAW,CAAC,UAAU;AACzC,QAAI,MAAO,SAAQ,IAAI,4BAA4B;AAGnD,UAAM,UAAU,MAAM,aAAa;AAAA,EACvC,CAAC;AAED,QAAM,iBAAiB,YAAY,CAAC,UAAU;AAC1C,QAAI,MAAO,SAAQ,IAAI,4BAA4B;AAGnD,UAAM,UAAU,MAAM,QAAQ,MAAA,CAAO;AAAA,EACzC,CAAC;AAED,QAAM,sBAAsB,kBAAkB,OAAO;AACrD,QAAM,iBAAiB,SAAS,CAAC,UAAU;AAEvC,UAAM,YAAY,oBAAoB,MAAM,OAAO,CAAC;AAAA,EACxD,CAAC;AACL;"}
+{"version":3,"file":"index.js","sources":["../src/fetch.ts","../src/index.ts"],"sourcesContent":["// current version of the cache for token storage\nconst CACHE_VERSION = 1;\n// name of the cache used to store CSRF tokens\nconst CACHE_NAME = `salesforce-lightning-service-worker-${CACHE_VERSION}`;\n// header name\nconst CSRF_HEADER = 'X-CSRF-Token';\n\n/**\n * Provides a safe way to interact with the Cache API with fallback for unsupported environments.\n *\n * @param callback - Function that receives the cache instance and returns a promise\n * @returns The result of the callback, or undefined if caches API is not available\n */\nasync function withCache<T>(callback: (cache: Cache) => Promise<T>): Promise<T | undefined> {\n    // Defend against the cache API not being available (e.g., in some test environments)\n    if (caches) {\n        const cache = await caches.open(CACHE_NAME);\n        return callback(cache);\n    } else {\n        return undefined;\n    }\n}\n\n/**\n * Determines if an HTTP method is one that mutates data and requires CSRF protection.\n *\n * @param method - The HTTP method to check\n * @returns true if the method requires CSRF protection (POST, PUT, PATCH, DELETE)\n */\nfunction isProtectedMethod(method: string) {\n    const normalizedMethod = method.toLowerCase();\n    return (\n        normalizedMethod === 'post' ||\n        normalizedMethod === 'put' ||\n        normalizedMethod === 'patch' ||\n        normalizedMethod === 'delete'\n    );\n}\n\n/**\n * Determines if the URL is for a path that requires CSRF protection.\n * Currently protects all Salesforce API endpoints under '/services'.\n *\n * @param urlString - The full URL to check\n * @returns true if the URL requires CSRF protection\n * @note This could be made configurable in the future to support custom protected paths\n */\nfunction isProtectedUrl(urlString: string) {\n    const url = new URL(urlString);\n    // Agentforce Vibes IDE has the form `absproxy/PORT/services/data/...`\n    return url.pathname.includes('/services/data/v');\n}\n\n/**\n * Checks if a response indicates that the CSRF token is invalid.\n * Salesforce returns a 400 status with a specific error code when tokens are invalid.\n *\n * @param response - The HTTP response to check\n * @returns true if the response indicates an invalid CSRF token\n */\nasync function isTokenInvalid(response: Response) {\n    if (response.status === 400) {\n        // clone response to read body without consuming the original stream\n        const body = await response.clone().json();\n\n        // check for Salesforce's specific invalid token error code\n        return body[0]?.errorCode === 'INVALID_ACCESS_TOKEN';\n    }\n\n    return false;\n}\n\n/**\n * Configuration options for the Lightning fetch creation.\n */\nexport interface LightningFetchConfig {\n    /**\n     * Optional source for CSRF tokens. Can be:\n     * - string: URL path to token endpoint (e.g., '/custom/csrf-endpoint')\n     * - URL: Full URL object for token endpoint\n     * - function: Custom async function that returns a token string\n     *\n     * As a string or URL, default fetching and caching (if Cache API is\n     * available) will be used to obtain tokens\n     */\n    tokenSource?: string | URL | (() => Promise<string>);\n\n    /**\n     * Optional callback for firing events related to fetch operations.\n     * Can be used for instrumentation, logging, and monitoring.\n     */\n    fireEvent?: (eventName: string, id: string, data?: unknown) => void;\n}\n\n/**\n * Creates an enhanced fetch function with automatic CSRF token handling.\n * The returned function automatically adds CSRF tokens to protected requests\n * and handles token refresh when tokens become invalid.\n *\n * @param config - Optional configuration object\n * @returns An enhanced fetch function that handles CSRF protection\n */\nexport function createLightningFetch(config: LightningFetchConfig = {}): typeof fetch {\n    const { fireEvent = () => {}, tokenSource } = config;\n\n    // default url and provider\n    let tokenUrl: string | URL = '/services/data/v65.0/ui-api/session/csrf';\n    let tokenProvider = obtainToken;\n\n    if (tokenSource) {\n        if (typeof tokenSource === 'string' || tokenSource instanceof URL) {\n            // use supplied URL with built-in provider\n            tokenUrl = tokenSource;\n        } else if (typeof tokenSource === 'function') {\n            // use external provider\n            tokenProvider = tokenSource;\n        }\n    }\n\n    /**\n     * Creates a unique identifier to correlate a series of related events.\n     */\n    function generateId() {\n        return Date.now().toString(36);\n    }\n\n    /**\n     * Obtains a CSRF token, using cache when available or fetching a new one.\n     *\n     * @returns Promise that resolves to the CSRF token string\n     */\n    async function obtainToken(): Promise<string> {\n        const id = generateId();\n        fireEvent('csrf_token_obtain_start', id);\n\n        // try to get cached token response first\n        let response = await withCache((cache) => cache.match(tokenUrl));\n\n        if (!response) {\n            // no cached response available, fetch a new token\n            fireEvent('csrf_token_fetch_start', id);\n            response = await fetch(tokenUrl, { method: 'get' });\n            fireEvent('csrf_token_fetch_complete', id, { status: response.status });\n        } else {\n            fireEvent('csrf_token_cache_hit', id);\n        }\n\n        // extract token from response (clone to avoid consuming original stream)\n        const csrfToken: string = (await response.clone().json()).csrfToken;\n\n        // cache the response for future use\n        await withCache((cache) => cache.put(tokenUrl, response));\n\n        fireEvent('csrf_token_obtain_complete', id);\n        return csrfToken;\n    }\n\n    let tokenPromise = tokenProvider();\n\n    /**\n     * Clears any cached token and initiates retrieval of a fresh one.\n     * Used when the current token becomes invalid.\n     */\n    async function refreshToken() {\n        const id = generateId();\n        fireEvent('csrf_token_refresh_start', id);\n\n        // remove the invalid token from cache\n        await withCache((cache) => cache.delete(tokenUrl));\n\n        // start obtaining a new token\n        tokenPromise = tokenProvider();\n\n        fireEvent('csrf_token_refresh_complete', id);\n    }\n\n    /**\n     * Makes a request with the CSRF token header added.\n     *\n     * @param request - The original request to enhance with CSRF token\n     * @returns Promise that resolves to the response\n     */\n    async function fetchWithToken(request: Request) {\n        // clone original headers\n        const headers = new Headers(request.headers);\n\n        // either use provided token or add one that's been loaded\n        if (!headers.has(CSRF_HEADER)) {\n            headers.set(CSRF_HEADER, await tokenPromise!);\n        }\n\n        // execute request with CSRF token header\n        return fetch(request, { headers });\n    }\n\n    /**\n     * Enhanced fetch function that applies CSRF token protection to qualifying requests.\n     * Automatically adds CSRF tokens to data-mutating requests to protected URLs,\n     * with automatic token refresh when tokens become invalid.\n     *\n     * @param input - The request input (URL, Request, etc.)\n     * @param init - Optional request initialization options\n     * @returns Promise that resolves to the response\n     */\n    return async function lightningFetch(\n        input: RequestInfo | URL,\n        init?: RequestInit\n    ): Promise<Response> {\n        const id = generateId();\n        const request = new Request(input, init);\n\n        // check if this request requires CSRF protection (mutating method + protected URL)\n        if (isProtectedMethod(request.method) && isProtectedUrl(request.url)) {\n            fireEvent('protected_request_start', id, { method: request.method, url: request.url });\n\n            // make request with CSRF token (clone to allow retry with fresh request)\n            const response = await fetchWithToken(request.clone());\n\n            // check if the token was rejected\n            if (await isTokenInvalid(response)) {\n                fireEvent('csrf_token_invalid', id, { status: response.status });\n\n                // token is invalid, refresh and retry once\n                await refreshToken();\n                const retryResponse = await fetchWithToken(request.clone());\n\n                fireEvent('protected_request_complete', id, {\n                    method: request.method,\n                    url: request.url,\n                    status: retryResponse.status,\n                    retried: true,\n                });\n\n                return retryResponse;\n            } else {\n                fireEvent('protected_request_complete', id, {\n                    method: request.method,\n                    url: request.url,\n                    status: response.status,\n                    retried: false,\n                });\n\n                // token was valid, return the response\n                return response;\n            }\n        } else {\n            fireEvent('unprotected_request', id, { method: request.method, url: request.url });\n\n            // no CSRF protection required, use standard fetch\n            return fetch(request);\n        }\n    };\n}\n","import { createLightningFetch } from './fetch';\n\n/**\n * Type alias for the native fetch function\n */\ntype Fetch = typeof fetch;\n\nconst lightningFetch = createLightningFetch();\n\n/**\n * The fetch function used by the client. Defaults to enhanced fetch for CSRF protection.\n * Will be switched to native fetch when CSRF-based service worker is successfully registered.\n */\nlet clientFetch: Fetch = lightningFetch;\n\n/**\n * A client for making HTTP requests with CSRF protection.  By default, protection is provided by\n * wrapping the native `fetch` API with functionality that will apply a CSRF token to appropriate\n * requests.  This includes functionality to detect expired tokens, triggering a token refresh and\n * retry of the request.\n *\n * Optionally, CSRF protection can be offloaded to a service worker by making the appropriate calls\n * to `registerServiceWorker` and `defineServiceWorker`\n */\nexport class ConduitClient {\n    private constructor() {}\n\n    /**\n     * Makes an HTTP request\n     *\n     * @param input - The URL, Request object, or relative path to request\n     * @param init - Optional request configuration that will be merged with defaults\n     * @returns Promise that resolves to the Response object\n     */\n    fetch(input: string | URL | Request, init: RequestInit = {}): Promise<Response> {\n        return clientFetch(input, init);\n    }\n\n    /**\n     * Factory method to create a new ConduitClient instance\n     *\n     * @returns A new ConduitClient instance\n     */\n    static create() {\n        return new ConduitClient();\n    }\n\n    /**\n     * Registers a service worker for enhanced CSRF protection and caching.\n     * When successfully registered, the client will switch to using native fetch\n     * as the service worker will handle CSRF protection.\n     *\n     * The script URL must identify a source file that calls `defineServiceWorker`.\n     *\n     * @param scriptURL - URL or path to the service worker script\n     */\n    static async registerServiceWorker(scriptURL: string | URL) {\n        // check if service workers are supported in this environment\n        if ('serviceWorker' in navigator) {\n            try {\n                const registration = await navigator.serviceWorker.register(scriptURL, {\n                    type: 'module',\n                });\n\n                // successful registration, so switch to native fetch since service worker handles CSRF\n                clientFetch = fetch;\n\n                console.log('[Conduit Client] Service registration succeeded:', registration);\n            } catch (error) {\n                console.error(\n                    '[Conduit Client] Service Worker registration failed (using decorated `fetch`):',\n                    error\n                );\n            }\n        }\n    }\n\n    /**\n     * Defines the service worker behavior for CSRF protection.\n     *\n     * This method must be called within a service worker script whose URL is supplied to\n     * `registerServiceWorker`\n     */\n    static defineServiceWorker() {\n        const scope = self as any as ServiceWorkerGlobalScope;\n\n        // handle service worker installation\n        scope.addEventListener('install', (event) => {\n            // skip waiting phase to activate immediately\n            event.waitUntil(scope.skipWaiting());\n        });\n\n        // handle service worker activation\n        scope.addEventListener('activate', (event) => {\n            // take control of all clients immediately\n            event.waitUntil(scope.clients.claim());\n        });\n\n        // intercept all fetch requests and apply CSRF protection\n        scope.addEventListener('fetch', (event) => {\n            // use enhanced fetch to automatically handle CSRF tokens for protected requests\n            event.respondWith(lightningFetch(event.request));\n        });\n    }\n}\n"],"names":["lightningFetch"],"mappings":"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"}

package/dist/types/fetch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration options for the Lightning fetch creation.
+ */
+export interface LightningFetchConfig {
+    /**
+     * Optional source for CSRF tokens. Can be:
+     * - string: URL path to token endpoint (e.g., '/custom/csrf-endpoint')
+     * - URL: Full URL object for token endpoint
+     * - function: Custom async function that returns a token string
+     *
+     * As a string or URL, default fetching and caching (if Cache API is
+     * available) will be used to obtain tokens
+     */
+    tokenSource?: string | URL | (() => Promise<string>);
+    /**
+     * Optional callback for firing events related to fetch operations.
+     * Can be used for instrumentation, logging, and monitoring.
+     */
+    fireEvent?: (eventName: string, id: string, data?: unknown) => void;
+}
+/**
+ * Creates an enhanced fetch function with automatic CSRF token handling.
+ * The returned function automatically adds CSRF tokens to protected requests
+ * and handles token refresh when tokens become invalid.
+ *
+ * @param config - Optional configuration object
+ * @returns An enhanced fetch function that handles CSRF protection
+ */
+export declare function createLightningFetch(config?: LightningFetchConfig): typeof fetch;

package/dist/types/index.d.ts

@@ -1,11 +1,43 @@
-export type Config = {
-    version: string;
-    debug?: boolean;
-};
 /**
- * Adds event listeners for setting up service worker.
+ * A client for making HTTP requests with CSRF protection.  By default, protection is provided by
+ * wrapping the native `fetch` API with functionality that will apply a CSRF token to appropriate
+ * requests.  This includes functionality to detect expired tokens, triggering a token refresh and
+ * retry of the request.
  *
- * @param version
- * @param debug
+ * Optionally, CSRF protection can be offloaded to a service worker by making the appropriate calls
+ * to `registerServiceWorker` and `defineServiceWorker`
  */
-export declare function createServiceWorker({ version, debug }: Config): void;
+export declare class ConduitClient {
+    private constructor();
+    /**
+     * Makes an HTTP request
+     *
+     * @param input - The URL, Request object, or relative path to request
+     * @param init - Optional request configuration that will be merged with defaults
+     * @returns Promise that resolves to the Response object
+     */
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+    /**
+     * Factory method to create a new ConduitClient instance
+     *
+     * @returns A new ConduitClient instance
+     */
+    static create(): ConduitClient;
+    /**
+     * Registers a service worker for enhanced CSRF protection and caching.
+     * When successfully registered, the client will switch to using native fetch
+     * as the service worker will handle CSRF protection.
+     *
+     * The script URL must identify a source file that calls `defineServiceWorker`.
+     *
+     * @param scriptURL - URL or path to the service worker script
+     */
+    static registerServiceWorker(scriptURL: string | URL): Promise<void>;
+    /**
+     * Defines the service worker behavior for CSRF protection.
+     *
+     * This method must be called within a service worker script whose URL is supplied to
+     * `registerServiceWorker`
+     */
+    static defineServiceWorker(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@conduit-client/salesforce-lightning-service-worker",
-    "version": "3.3.0",
+    "version": "3.4.0",
     "private": false,
     "description": "Service worker for accessing Salesforce data",
     "type": "module",
@@ -32,7 +32,7 @@
     "size-limit": [
         {
             "path": "dist/index.js",
-            "limit": "917 B"
+            "limit": "1.65 kB"
         }
     ]
 }

package/dist/types/csrf.d.ts

@@ -1 +0,0 @@
-export declare function createCsrfHandler(version: string): (request: Request) => Promise<Response>;