@sparrowdesk/react-chat 0.1.0

package/README.md

@@ -0,0 +1,9 @@
+# @sparrowdesk/react-chat
+
+SparrowDesk Chat Widget for React.
+
+```sh
+pnpm add @sparrowdesk/react-chat
+```
+
+See the [main README](../../README.md) for full documentation.

package/dist/index.d.ts

@@ -0,0 +1,151 @@
+import * as React$1 from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/internal/sparrowDeskWidget.d.ts
+interface SparrowDeskApi {
+  openWidget?: () => void;
+  closeWidget?: () => void;
+  hideWidget?: () => void;
+  onOpen?: (callback: () => void) => void;
+  onClose?: (callback: () => void) => void;
+  setTags?: (tags: string[]) => void;
+  setConversationFields?: (fields: Record<string, unknown>) => void;
+  setContactFields?: (fields: Record<string, unknown>) => void;
+  status?: 'open' | 'closed';
+}
+declare global {
+  interface Window {
+    SD_WIDGET_TOKEN?: string;
+    SD_WIDGET_DOMAIN?: string;
+    sparrowDesk?: SparrowDeskApi;
+  }
+}
+//#endregion
+//#region src/Chat.d.ts
+interface ChatProps {
+  /** SparrowDesk domain, e.g. "sparrowdesk7975310.sparrowdesk.com" */
+  domain: string;
+  /** SparrowDesk widget token */
+  token: string;
+  /** Optional tags (e.g. user identifiers) for the current session. */
+  tags?: string[];
+  /**
+   * Contact fields to set during init (expects internal_name keys).
+   * Invalid internal_names / invalid values are skipped by the widget itself.
+   */
+  contactFields?: Record<string, unknown>;
+  /**
+   * Conversation fields to set during init (expects internal_name keys).
+   * Invalid internal_names / invalid values are skipped by the widget itself.
+   */
+  conversationFields?: Record<string, unknown>;
+  /** Called once the widget API is available on `window.sparrowDesk`. */
+  onReady?: (api: SparrowDeskApi) => void;
+  /** Called when the widget opens (registered via `window.sparrowDesk.onOpen`). */
+  onOpen?: () => void;
+  /** Called when the widget closes (registered via `window.sparrowDesk.onClose`). */
+  onClose?: () => void;
+  /** If true, calls `window.sparrowDesk.openWidget()` once when ready. */
+  openOnInit?: boolean;
+  /** If true, calls `window.sparrowDesk.hideWidget()` once when ready. */
+  hideOnInit?: boolean;
+  /**
+   * Controls whether this component should set globals and inject the widget script.
+   * Set to `false` if SparrowDesk is loaded elsewhere and you only want to apply
+   * fields/tags + register callbacks.
+   */
+  shouldInitialize?: boolean;
+  /**
+   * If `false`, defers injecting the widget script + waiting for the API until
+   * the visitor interacts (when `initializeOnInteraction` is enabled).
+   *
+   * This is a performance optimization implemented at the wrapper level by delaying
+   * script injection.
+   */
+  connectOnPageLoad?: boolean;
+  /**
+   * When `connectOnPageLoad={false}`, if `true`, initialize the widget on the first
+   * user interaction (pointer or keyboard), then remove those listeners.
+   */
+  initializeOnInteraction?: boolean;
+  /** If true, removes the injected script tag on unmount. */
+  cleanupOnUnmount?: boolean;
+  /**
+   * How long to wait (ms) for `window.sparrowDesk` to become available after init.
+   * Defaults to 10s.
+   */
+  readyTimeoutMs?: number;
+}
+declare const Chat: React.FC<ChatProps>;
+//#endregion
+//#region src/SparrowDeskProvider.d.ts
+type SparrowDeskProviderProps = {
+  /** SparrowDesk domain, e.g. "sparrowdesk7975310.sparrowdesk.com" */
+  domain: string;
+  /** SparrowDesk widget token */
+  token: string;
+  children: React$1.ReactNode;
+  /**
+   * Controls whether this provider should set globals and inject the widget script.
+   * Set to `false` if SparrowDesk is loaded elsewhere (e.g. via Segment) and you only
+   * want the hook-based API.
+   */
+  shouldInitialize?: boolean;
+  /**
+   * If `false`, defers injecting the widget script + waiting for the API until
+   * you call `initialize()` (or invoke `openWidget`/`closeWidget`/`hideWidget`/etc),
+   * or until the first user interaction when `initializeOnInteraction` is enabled.
+   *
+   * This is a performance optimization implemented at the wrapper level by delaying
+   * script injection until you explicitly initialize.
+   */
+  connectOnPageLoad?: boolean;
+  /**
+   * When `connectOnPageLoad={false}`, if `true`, initialize on the first
+   * user interaction (pointer or keyboard). Defaults to `true`.
+   */
+  initializeOnInteraction?: boolean;
+  tags?: string[];
+  contactFields?: Record<string, unknown>;
+  conversationFields?: Record<string, unknown>;
+  onReady?: (api: SparrowDeskApi) => void;
+  onOpen?: () => void;
+  onClose?: () => void;
+  openOnInit?: boolean;
+  hideOnInit?: boolean;
+  cleanupOnUnmount?: boolean;
+  readyTimeoutMs?: number;
+};
+type SparrowDeskContextValue = {
+  isReady: boolean;
+  api: SparrowDeskApi | null;
+  /** Ensures the widget script is injected (if enabled) and begins waiting for the API. */
+  initialize: () => void;
+  openWidget: () => void;
+  closeWidget: () => void;
+  hideWidget: () => void;
+  setTags: (tags: string[]) => void;
+  setContactFields: (fields: Record<string, unknown>) => void;
+  setConversationFields: (fields: Record<string, unknown>) => void;
+};
+declare function useSparrowDesk(): SparrowDeskContextValue;
+declare function SparrowDeskProvider({
+  domain,
+  token,
+  children,
+  shouldInitialize,
+  connectOnPageLoad,
+  initializeOnInteraction,
+  tags,
+  contactFields,
+  conversationFields,
+  onReady,
+  onOpen,
+  onClose,
+  openOnInit,
+  hideOnInit,
+  cleanupOnUnmount,
+  readyTimeoutMs
+}: SparrowDeskProviderProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { Chat, type ChatProps, type SparrowDeskApi, type SparrowDeskContextValue, SparrowDeskProvider, type SparrowDeskProviderProps, useSparrowDesk };

package/dist/index.js

@@ -0,0 +1,400 @@
+import * as React from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/internal/sparrowDeskWidget.ts
+const DEFAULT_SCRIPT_SRC = "https://assets.cdn.sparrowdesk.com/chatbot/bundle/main.js";
+const DEFAULT_READY_TIMEOUT_MS = 1e4;
+const WIDGET_SCRIPT_SELECTOR = "script[data-sd-chat-widget=\"true\"]";
+function isBrowser() {
+	return globalThis.document !== void 0;
+}
+function normalizeRequired(value) {
+	return value.trim();
+}
+function setWidgetGlobals(domain, token) {
+	const w = globalThis;
+	w.SD_WIDGET_DOMAIN = domain;
+	w.SD_WIDGET_TOKEN = token;
+}
+const scriptEntriesBySrc = /* @__PURE__ */ new Map();
+function removeOtherWidgetScripts(keepSrc) {
+	document.querySelectorAll(WIDGET_SCRIPT_SELECTOR).forEach((script) => {
+		if (script.src !== keepSrc) script.remove();
+	});
+}
+function acquireWidgetScript(src, cleanupOnUnmount) {
+	const cached = scriptEntriesBySrc.get(src);
+	if (cached) {
+		cached.refCount += 1;
+		cached.cleanupWhenUnused ||= cleanupOnUnmount;
+		return { release() {
+			cached.refCount -= 1;
+			if (cached.refCount > 0) return;
+			if (cached.cleanupWhenUnused) cached.script.remove();
+			scriptEntriesBySrc.delete(src);
+		} };
+	}
+	const existing = document.querySelector(WIDGET_SCRIPT_SELECTOR);
+	const entry = {
+		script: existing?.src === src ? existing : (() => {
+			const el = document.createElement("script");
+			el.async = true;
+			el.src = src;
+			el.dataset["sdChatWidget"] = "true";
+			document.body.appendChild(el);
+			return el;
+		})(),
+		refCount: 1,
+		cleanupWhenUnused: cleanupOnUnmount
+	};
+	scriptEntriesBySrc.set(src, entry);
+	return { release() {
+		entry.refCount -= 1;
+		if (entry.refCount > 0) return;
+		if (entry.cleanupWhenUnused) entry.script.remove();
+		scriptEntriesBySrc.delete(src);
+	} };
+}
+async function waitForSparrowDeskApi(timeoutMs) {
+	const w = globalThis;
+	if (w.sparrowDesk) return w.sparrowDesk;
+	if (timeoutMs <= 0) return null;
+	const startedAt = Date.now();
+	while (Date.now() - startedAt < timeoutMs) {
+		if (w.sparrowDesk) return w.sparrowDesk;
+		await new Promise((r) => setTimeout(r, 50));
+	}
+	return null;
+}
+
+//#endregion
+//#region src/internal/useLatest.ts
+function useLatest(value) {
+	const ref = useRef(value);
+	useEffect(() => {
+		ref.current = value;
+	}, [value]);
+	return ref;
+}
+
+//#endregion
+//#region src/Chat.tsx
+const Chat = ({ domain, token, tags, contactFields, conversationFields, onReady, onOpen, onClose, openOnInit = false, hideOnInit = false, shouldInitialize = true, connectOnPageLoad = true, initializeOnInteraction = true, cleanupOnUnmount = false, readyTimeoutMs = DEFAULT_READY_TIMEOUT_MS }) => {
+	const normalized = useMemo(() => {
+		return {
+			domain: normalizeRequired(domain),
+			token: normalizeRequired(token)
+		};
+	}, [domain, token]);
+	const onOpenRef = useLatest(onOpen);
+	const onCloseRef = useLatest(onClose);
+	const onReadyRef = useLatest(onReady);
+	const tagsRef = useLatest(tags);
+	const contactFieldsRef = useLatest(contactFields);
+	const conversationFieldsRef = useLatest(conversationFields);
+	const registeredCallbacksRef = useRef(false);
+	const apiRef = useRef(null);
+	const didOpenOnceRef = useRef(false);
+	const didHideOnceRef = useRef(false);
+	const [shouldStart, setShouldStart] = useState(connectOnPageLoad);
+	useEffect(() => {
+		didOpenOnceRef.current = false;
+		didHideOnceRef.current = false;
+		apiRef.current = null;
+		registeredCallbacksRef.current = false;
+		setShouldStart(connectOnPageLoad);
+	}, [normalized.domain, normalized.token]);
+	useEffect(() => {
+		if (!isBrowser()) return;
+		if (!normalized.domain || !normalized.token) return;
+		setWidgetGlobals(normalized.domain, normalized.token);
+		if (!shouldInitialize) return;
+		if (!shouldStart) return;
+		removeOtherWidgetScripts(DEFAULT_SCRIPT_SRC);
+		const handle = acquireWidgetScript(DEFAULT_SCRIPT_SRC, cleanupOnUnmount);
+		return () => {
+			handle.release();
+		};
+	}, [
+		normalized.domain,
+		normalized.token,
+		cleanupOnUnmount,
+		shouldInitialize,
+		shouldStart
+	]);
+	useEffect(() => {
+		if (!isBrowser()) return;
+		if (!normalized.domain || !normalized.token) return;
+		if (!shouldStart) return;
+		let cancelled = false;
+		(async () => {
+			const api = await waitForSparrowDeskApi(readyTimeoutMs);
+			if (cancelled || !api) return;
+			apiRef.current = api;
+			if (!registeredCallbacksRef.current) {
+				api.onOpen?.(() => onOpenRef.current?.());
+				api.onClose?.(() => onCloseRef.current?.());
+				registeredCallbacksRef.current = true;
+			}
+			onReadyRef.current?.(api);
+			const latestTags = tagsRef.current;
+			const latestContactFields = contactFieldsRef.current;
+			const latestConversationFields = conversationFieldsRef.current;
+			if (Array.isArray(latestTags) && latestTags.length) api.setTags?.(latestTags);
+			if (latestContactFields && Object.keys(latestContactFields).length) api.setContactFields?.(latestContactFields);
+			if (latestConversationFields && Object.keys(latestConversationFields).length) api.setConversationFields?.(latestConversationFields);
+			if (hideOnInit && !didHideOnceRef.current) {
+				api.hideWidget?.();
+				didHideOnceRef.current = true;
+			}
+			if (openOnInit && !didOpenOnceRef.current) {
+				api.openWidget?.();
+				didOpenOnceRef.current = true;
+			}
+		})();
+		return () => {
+			cancelled = true;
+		};
+	}, [
+		normalized.domain,
+		normalized.token,
+		openOnInit,
+		hideOnInit,
+		readyTimeoutMs,
+		shouldStart
+	]);
+	useEffect(() => {
+		if (!isBrowser()) return;
+		if (connectOnPageLoad) return;
+		if (!initializeOnInteraction) return;
+		if (shouldStart) return;
+		if (!normalized.domain || !normalized.token) return;
+		const onFirstInteraction = () => {
+			setShouldStart(true);
+			cleanup();
+		};
+		const cleanup = () => {
+			document.removeEventListener("pointerdown", onFirstInteraction, true);
+			document.removeEventListener("keydown", onFirstInteraction, true);
+		};
+		document.addEventListener("pointerdown", onFirstInteraction, true);
+		document.addEventListener("keydown", onFirstInteraction, true);
+		return cleanup;
+	}, [
+		connectOnPageLoad,
+		initializeOnInteraction,
+		normalized.domain,
+		normalized.token,
+		shouldStart
+	]);
+	useEffect(() => {
+		const api = apiRef.current;
+		if (!api) return;
+		if (Array.isArray(tags) && tags.length) api.setTags?.(tags);
+		if (contactFields && Object.keys(contactFields).length) api.setContactFields?.(contactFields);
+		if (conversationFields && Object.keys(conversationFields).length) api.setConversationFields?.(conversationFields);
+	}, [
+		tags,
+		contactFields,
+		conversationFields
+	]);
+	if (!normalized.domain || !normalized.token) return null;
+	return /* @__PURE__ */ jsx("div", { "data-sd-chat-widget-container": "" });
+};
+
+//#endregion
+//#region src/SparrowDeskProvider.tsx
+const SparrowDeskContext = React.createContext(null);
+function useSparrowDesk() {
+	const value = React.useContext(SparrowDeskContext);
+	if (!value) throw new Error("useSparrowDesk must be used within <SparrowDeskProvider />");
+	return value;
+}
+function SparrowDeskProvider({ domain, token, children, shouldInitialize = true, connectOnPageLoad = true, initializeOnInteraction = true, tags, contactFields, conversationFields, onReady, onOpen, onClose, openOnInit = false, hideOnInit = false, cleanupOnUnmount = false, readyTimeoutMs = DEFAULT_READY_TIMEOUT_MS }) {
+	const normalized = useMemo(() => {
+		return {
+			domain: normalizeRequired(domain),
+			token: normalizeRequired(token)
+		};
+	}, [domain, token]);
+	const onReadyRef = useLatest(onReady);
+	const onOpenRef = useLatest(onOpen);
+	const onCloseRef = useLatest(onClose);
+	const tagsRef = useLatest(tags);
+	const contactFieldsRef = useLatest(contactFields);
+	const conversationFieldsRef = useLatest(conversationFields);
+	const openOnInitRef = useLatest(openOnInit);
+	const hideOnInitRef = useLatest(hideOnInit);
+	const apiRef = useRef(null);
+	const registeredCallbacksRef = useRef(false);
+	const didOpenOnceRef = useRef(false);
+	const didHideOnceRef = useRef(false);
+	const scriptHandleRef = useRef(null);
+	const initStartedRef = useRef(false);
+	const initCancelRef = useRef(null);
+	const pendingCallsRef = useRef([]);
+	const [isReady, setIsReady] = useState(false);
+	const [shouldStart, setShouldStart] = useState(connectOnPageLoad);
+	useEffect(() => {
+		setShouldStart(connectOnPageLoad);
+	}, [connectOnPageLoad]);
+	useEffect(() => {
+		didOpenOnceRef.current = false;
+		didHideOnceRef.current = false;
+		apiRef.current = null;
+		registeredCallbacksRef.current = false;
+		initStartedRef.current = false;
+		initCancelRef.current?.();
+		initCancelRef.current = null;
+		pendingCallsRef.current = [];
+		scriptHandleRef.current?.release();
+		scriptHandleRef.current = null;
+		setIsReady(false);
+		setShouldStart(connectOnPageLoad);
+	}, [
+		normalized.domain,
+		normalized.token,
+		connectOnPageLoad
+	]);
+	const initialize = React.useCallback(() => {
+		if (!isBrowser()) return;
+		if (!normalized.domain || !normalized.token) return;
+		setWidgetGlobals(normalized.domain, normalized.token);
+		if (shouldInitialize && !scriptHandleRef.current) {
+			removeOtherWidgetScripts(DEFAULT_SCRIPT_SRC);
+			scriptHandleRef.current = acquireWidgetScript(DEFAULT_SCRIPT_SRC, cleanupOnUnmount);
+		}
+		if (initStartedRef.current) return;
+		initStartedRef.current = true;
+		let cancelled = false;
+		initCancelRef.current = () => {
+			cancelled = true;
+		};
+		(async () => {
+			const api = await waitForSparrowDeskApi(readyTimeoutMs);
+			if (cancelled || !api) return;
+			apiRef.current = api;
+			setIsReady(true);
+			if (!registeredCallbacksRef.current) {
+				api.onOpen?.(() => onOpenRef.current?.());
+				api.onClose?.(() => onCloseRef.current?.());
+				registeredCallbacksRef.current = true;
+			}
+			onReadyRef.current?.(api);
+			const latestTags = tagsRef.current;
+			const latestContactFields = contactFieldsRef.current;
+			const latestConversationFields = conversationFieldsRef.current;
+			if (Array.isArray(latestTags) && latestTags.length) api.setTags?.(latestTags);
+			if (latestContactFields && Object.keys(latestContactFields).length) api.setContactFields?.(latestContactFields);
+			if (latestConversationFields && Object.keys(latestConversationFields).length) api.setConversationFields?.(latestConversationFields);
+			if (hideOnInitRef.current && !didHideOnceRef.current) {
+				api.hideWidget?.();
+				didHideOnceRef.current = true;
+			}
+			if (openOnInitRef.current && !didOpenOnceRef.current) {
+				api.openWidget?.();
+				didOpenOnceRef.current = true;
+			}
+			const pending = pendingCallsRef.current;
+			pendingCallsRef.current = [];
+			pending.forEach((fn) => fn(api));
+		})();
+	}, [
+		cleanupOnUnmount,
+		normalized.domain,
+		normalized.token,
+		readyTimeoutMs,
+		shouldInitialize
+	]);
+	useEffect(() => {
+		if (!isBrowser()) return;
+		if (!normalized.domain || !normalized.token) return;
+		setWidgetGlobals(normalized.domain, normalized.token);
+		if (!shouldStart) return;
+		initialize();
+		return () => {
+			initCancelRef.current?.();
+			initCancelRef.current = null;
+			if (!apiRef.current) initStartedRef.current = false;
+			scriptHandleRef.current?.release();
+			scriptHandleRef.current = null;
+		};
+	}, [
+		initialize,
+		normalized.domain,
+		normalized.token,
+		shouldStart
+	]);
+	useEffect(() => {
+		if (!isBrowser()) return;
+		if (connectOnPageLoad) return;
+		if (!initializeOnInteraction) return;
+		if (shouldStart) return;
+		if (!normalized.domain || !normalized.token) return;
+		const onFirstInteraction = () => {
+			setShouldStart(true);
+			cleanup();
+		};
+		const cleanup = () => {
+			document.removeEventListener("pointerdown", onFirstInteraction, true);
+			document.removeEventListener("keydown", onFirstInteraction, true);
+		};
+		document.addEventListener("pointerdown", onFirstInteraction, true);
+		document.addEventListener("keydown", onFirstInteraction, true);
+		return cleanup;
+	}, [
+		connectOnPageLoad,
+		initializeOnInteraction,
+		normalized.domain,
+		normalized.token,
+		shouldStart
+	]);
+	useEffect(() => {
+		const api = apiRef.current;
+		if (!api) return;
+		if (Array.isArray(tags) && tags.length) api.setTags?.(tags);
+		if (contactFields && Object.keys(contactFields).length) api.setContactFields?.(contactFields);
+		if (conversationFields && Object.keys(conversationFields).length) api.setConversationFields?.(conversationFields);
+	}, [
+		tags,
+		contactFields,
+		conversationFields
+	]);
+	const methods = useMemo(() => {
+		const callOrQueue = (fn) => {
+			const api = apiRef.current;
+			if (api) {
+				fn(api);
+				return;
+			}
+			if (!connectOnPageLoad) {
+				initialize();
+				pendingCallsRef.current.push(fn);
+			}
+		};
+		return {
+			initialize,
+			openWidget: () => callOrQueue((api) => api.openWidget?.()),
+			closeWidget: () => callOrQueue((api) => api.closeWidget?.()),
+			hideWidget: () => callOrQueue((api) => api.hideWidget?.()),
+			setTags: (t) => callOrQueue((api) => api.setTags?.(t)),
+			setContactFields: (f) => callOrQueue((api) => api.setContactFields?.(f)),
+			setConversationFields: (f) => callOrQueue((api) => api.setConversationFields?.(f))
+		};
+	}, [connectOnPageLoad, initialize]);
+	const value = useMemo(() => {
+		return {
+			...methods,
+			isReady,
+			api: apiRef.current
+		};
+	}, [methods, isReady]);
+	return /* @__PURE__ */ jsx(SparrowDeskContext.Provider, {
+		value,
+		children
+	});
+}
+
+//#endregion
+export { Chat, SparrowDeskProvider, useSparrowDesk };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@sparrowdesk/react-chat",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "SparrowDesk Chat Widget for React.",
+  "keywords": [
+    "sparrowdesk",
+    "chat",
+    "chat-widget",
+    "widget",
+    "support",
+    "customer-support",
+    "react"
+  ],
+  "author": "SparrowDesk",
+  "license": "MIT",
+  "homepage": "https://github.com/sparrowdesk/sd-chat-widget-react#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sparrowdesk/sd-chat-widget-react.git",
+    "directory": "packages/react-chat"
+  },
+  "bugs": {
+    "url": "https://github.com/sparrowdesk/sd-chat-widget-react/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "release": "bumpp && pnpm publish",
+    "prepublishOnly": "pnpm run build"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@tsconfig/strictest": "^2.0.8",
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/browser-playwright": "^4.0.16",
+    "bumpp": "^10.3.2",
+    "playwright": "^1.57.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tsdown": "^0.18.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16",
+    "vitest-browser-react": "^2.0.2"
+  }
+}