feat(js,react): custom fetch option

Author: VojtechVidra

pnpm-lock.yaml

@@ -17,7 +17,7 @@
     "react-router": "^7.14.1"
   },
   "devDependencies": {
-    "@playwright/test": "^1.59.0",
+    "@playwright/test": "^1.59.1",
     "@types/node": "^24",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",

workspaces/e2e/package.json

@@ -1,4 +1,4 @@
-import type { Action as IAction } from "@flows/js";
+import type { CustomFetch, Action as IAction, LanguageOption } from "@flows/js";
 import {
   init,
   resetAllWorkflowsProgress,
@@ -13,13 +13,26 @@ import * as _surveyComponents from "@flows/js-components/survey-components";
 import "@flows/js-components/index.css";
 import type { StateMemory as IStateMemory } from "@flows/js";
 import { startWorkflow } from "@flows/js";
-import type { LanguageOption } from "@flows/shared";
 import { css, LitElement } from "lit";
 import { property } from "lit/decorators.js";
 import type { FlowsProperties } from "@flows/js";
 import { html, unsafeStatic } from "lit/static-html.js";
 
+const customFetchFn: CustomFetch = (url, options) => {
+  return fetch(url, {
+    ...options,
+    headers: {
+      ...(options?.headers as Record<string, string>),
+      "x-test-header": "my-custom-value",
+    },
+  });
+};
+
 const apiUrl = new URLSearchParams(window.location.search).get("apiUrl") ?? undefined;
+const customFetch =
+  new URLSearchParams(window.location.search).get("customFetch") === "true"
+    ? customFetchFn
+    : undefined;
 const noCurrentBlocks =
   new URLSearchParams(window.location.search).get("noCurrentBlocks") === "true";
 const language = new URLSearchParams(window.location.search).get("language") as LanguageOption;
@@ -117,6 +130,7 @@ init({
   userId: "testUserId",
   language,
   apiUrl,
+  customFetch,
   userProperties: {
     email: "test@flows.sh",
     age: 10,

workspaces/e2e/pages/js.ts

@@ -3,6 +3,8 @@ import type {
   StateMemory as IStateMemory,
   Action as IAction,
   LinkComponentType,
+  CustomFetch,
+  LanguageOption,
 } from "@flows/react";
 import {
   FlowsProvider,
@@ -23,9 +25,22 @@ import * as components from "@flows/react-components";
 import * as tourComponents from "@flows/react-components/tour";
 import * as surveyComponents from "@flows/react-components/survey";
 import "@flows/react-components/index.css";
-import type { LanguageOption } from "@flows/shared";
+
+const customFetchFn: CustomFetch = (url, options) => {
+  return fetch(url, {
+    ...options,
+    headers: {
+      ...(options?.headers as Record<string, string>),
+      "x-test-header": "my-custom-value",
+    },
+  });
+};
 
 const apiUrl = new URLSearchParams(window.location.search).get("apiUrl") ?? undefined;
+const customFetch =
+  new URLSearchParams(window.location.search).get("customFetch") === "true"
+    ? customFetchFn
+    : undefined;
 const noUserId = new URLSearchParams(window.location.search).get("noUserId") === "true";
 const noCurrentBlocks =
   new URLSearchParams(window.location.search).get("noCurrentBlocks") === "true";
@@ -149,6 +164,7 @@ createRoot(document.getElementById("root")!).render(
           age: 10,
         }}
         apiUrl={apiUrl}
+        customFetch={customFetch}
         components={{ ...components, Card, BlockTrigger, StateMemory, Action }}
         tourComponents={{ ...tourComponents, Card, Action }}
         surveyComponents={{ ...surveyComponents }}

workspaces/e2e/pages/react.tsx

@@ -0,0 +1,74 @@
+import { test } from "@playwright/test";
+import { mockBlocksEndpoint } from "./utils";
+import { randomUUID } from "crypto";
+import type { Block } from "@flows/shared";
+
+test.beforeEach(async ({ page }) => {
+  await page.routeWebSocket(
+    (url) => url.pathname === "/ws/sdk/block-updates",
+    () => {},
+  );
+});
+
+const getBlock = (): Block => ({
+  id: randomUUID(),
+  workflowId: randomUUID(),
+  type: "component",
+  componentType: "BasicsV2Modal",
+  data: { title: "Workflow block", body: "" },
+  exitNodes: ["continue"],
+  slottable: false,
+  propertyMeta: [
+    {
+      type: "action",
+      key: "primaryButton",
+      value: { label: "Continue" },
+    },
+  ],
+});
+
+const run = (packageName: string) => {
+  test(`${packageName} - should add custom header with custom fetch`, async ({ page }) => {
+    await mockBlocksEndpoint(page, [getBlock()]);
+    const blocksReq = page.waitForRequest((req) => {
+      return (
+        req.url() === "https://api.flows-cloud.com/v2/sdk/blocks" &&
+        req.headers()["x-test-header"] === "my-custom-value"
+      );
+    });
+    await page.goto(`/${packageName}.html?customFetch=true`);
+    await blocksReq;
+    const eventReq = page.waitForRequest((req) => {
+      return (
+        req.url() === "https://api.flows-cloud.com/v2/sdk/events" &&
+        req.headers()["x-test-header"] === "my-custom-value"
+      );
+    });
+    await page.getByText("Continue", { exact: true }).click();
+    await eventReq;
+  });
+  test(`${packageName} - custom header should not be present without custom fetch`, async ({
+    page,
+  }) => {
+    await mockBlocksEndpoint(page, [getBlock()]);
+    const blocksReq = page.waitForRequest((req) => {
+      return (
+        req.url() === "https://api.flows-cloud.com/v2/sdk/blocks" &&
+        req.headers()["x-test-header"] === undefined
+      );
+    });
+    await page.goto(`/${packageName}.html?customFetch=false`);
+    await blocksReq;
+    const eventReq = page.waitForRequest((req) => {
+      return (
+        req.url() === "https://api.flows-cloud.com/v2/sdk/events" &&
+        req.headers()["x-test-header"] === undefined
+      );
+    });
+    await page.getByText("Continue", { exact: true }).click();
+    await eventReq;
+  });
+};
+
+run("js");
+run("react");

workspaces/e2e/tests/custom-fetch.spec.ts

@@ -4,6 +4,7 @@ export type {
   BlockState,
   FlowsProperties,
   StateMemory,
+  CustomFetch,
   // Localization
   Locale,
   LanguageOption,

workspaces/js/src/index.ts

@@ -16,16 +16,8 @@ let locationChangeInterval: number | null = null;
 export const init = ({ debug, onDebugShortcut, ...options }: FlowsOptions): void => {
   const apiUrl = options.apiUrl ?? "https://api.flows-cloud.com";
   config.value = { ...options, apiUrl };
-  const { environment, organizationId, userId, userProperties, language } = options;
 
-  connectToWebsocketAndFetchBlocks({
-    apiUrl,
-    environment,
-    organizationId,
-    userId,
-    userProperties,
-    language,
-  });
+  connectToWebsocketAndFetchBlocks();
 
   if (locationChangeInterval !== null) clearInterval(locationChangeInterval);
   locationChangeInterval = window.setInterval(() => {

workspaces/js/src/init.ts

@@ -11,8 +11,8 @@ type SendEventProps = Pick<
 export const sendEvent = async (props: SendEventProps): Promise<void> => {
   const configuration = config.value;
   if (!configuration) return;
-  const { environment, organizationId, userId, apiUrl } = configuration;
-  await getApi(apiUrl, packageAndVersion).sendEvent({
+  const { environment, organizationId, userId, apiUrl, customFetch } = configuration;
+  await getApi({ apiUrl, version: packageAndVersion, customFetch }).sendEvent({
     ...props,
     environment,
     organizationId,
@@ -25,8 +25,8 @@ export const postSurvey = async (
 ) => {
   const configuration = config.value;
   if (!configuration) return;
-  const { apiUrl, environment, organizationId, userId } = configuration;
-  await getApi(apiUrl, packageAndVersion).postSurvey({
+  const { apiUrl, environment, organizationId, userId, customFetch } = configuration;
+  await getApi({ apiUrl, version: packageAndVersion, customFetch }).postSurvey({
     ...props,
     environment,
     organizationId,
@@ -54,6 +54,10 @@ export const fetchWorkflows = async (): Promise<WorkflowsResponse> => {
     return { workflows: [] };
   }
 
-  const { environment, organizationId, userId, apiUrl } = configuration;
-  return getApi(apiUrl, packageAndVersion).getWorkflows({ environment, organizationId, userId });
+  const { environment, organizationId, userId, apiUrl, customFetch } = configuration;
+  return getApi({ apiUrl, version: packageAndVersion, customFetch }).getWorkflows({
+    environment,
+    organizationId,
+    userId,
+  });
 };

workspaces/js/src/lib/api.ts

@@ -2,28 +2,20 @@ import {
   applyUpdateMessageToBlocksState,
   getApi,
   getUserLanguage,
-  type LanguageOption,
   log,
   parseWebsocketMessage,
-  type UserProperties,
 } from "@flows/shared";
-import { blocks, blocksError, blocksState, pendingMessages } from "../store";
+import { blocks, blocksError, blocksState, config, pendingMessages } from "../store";
 import { type Disconnect, websocket } from "./websocket";
 import { packageAndVersion } from "./constants";
 
-interface Props {
-  apiUrl: string;
-  environment: string;
-  organizationId: string;
-  userId: string;
-  userProperties?: UserProperties;
-  language?: LanguageOption;
-}
-
 let disconnect: Disconnect | null = null;
 
-export const connectToWebsocketAndFetchBlocks = (props: Props): void => {
-  const { environment, organizationId, userId, apiUrl } = props;
+export const connectToWebsocketAndFetchBlocks = (): void => {
+  const configuration = config.value;
+  if (!configuration) return;
+
+  const { environment, organizationId, userId, apiUrl, customFetch } = configuration;
   const params = { environment, organizationId, userId };
   const wsUrl = (() => {
     const wsBase = apiUrl.replace("https://", "wss://").replace("http://", "ws://");
@@ -32,11 +24,11 @@ export const connectToWebsocketAndFetchBlocks = (props: Props): void => {
 
   const fetchBlocks = (): void => {
     blocksError.value = false;
-    void getApi(apiUrl, packageAndVersion)
+    void getApi({ apiUrl, version: packageAndVersion, customFetch })
       .getBlocks({
         ...params,
-        language: getUserLanguage(props.language),
-        userProperties: props.userProperties,
+        language: getUserLanguage(configuration.language),
+        userProperties: configuration.userProperties,
       })
       .then((res) => {
         const blocksWithUpdates = pendingMessages.value.reduce(

workspaces/js/src/lib/blocks.ts

@@ -1,4 +1,4 @@
-import { type LanguageOption, type UserProperties } from "@flows/shared";
+import type { CustomFetch, LanguageOption, UserProperties } from "@flows/shared";
 
 export interface FlowsOptions {
   /**
@@ -21,6 +21,10 @@ export interface FlowsOptions {
    * Custom API URL useful when using proxy to send Flows requests through your own domain.
    */
   apiUrl?: string;
+  /**
+   * Custom fetch implementation useful when you need to customize api requests with custom headers, credentials, etc.
+   */
+  customFetch?: CustomFetch;
   /**
    * Language used to enable [localization](https://flows.sh/docs/localization). Based on the set language, the correct translation for the block data will be selected.
    * - `disabled` (default) - The user will be served content in the default language group of your organization.