@affiliateo/web 4.8.0 → 4.9.0

package/README.md

@@ -229,13 +229,51 @@ async function handleSignOut() {
 ```
 
 The browser then counts as a new anonymous customer of your app, so whoever
-signs in next (or nobody) isn't counted as the person who just left.
+signs in next (or nobody) isn't counted as the person who just left. Their Live
+Chat goes too: the next person to open the chat starts a new thread.
 Everything already recorded stays with them. Tracking carries on as before:
 same visitor id, same affiliate. If a different user signs in without a
 sign-out in between, the browser switches to them on its own.
 
+## Live Chat
+
+Let visitors chat with you in real time; you answer from the Live Chat inbox in
+your Affiliateo dashboard. Add **Live Chat** from the App Store in your dashboard
+and switch it on for this app: the chat bubble then shows on your site by itself,
+with nothing else to install. Visitors don't need an account.
+
+```tsx
+import { openChat } from '@affiliateo/web'
+
+// Open the chat from your own button
+<button onClick={openChat}>Chat with us</button>
+
+// No bubble, only your own button
+<AffiliateoProvider appId="..." chat="hidden">
+
+// Never load the chat
+<AffiliateoProvider appId="..." chat={false}>
+
+// Your own look, over the dashboard's (4.15.0); leave out what the dashboard should decide
+<AffiliateoProvider appId="..." chatLook={{ color: '#7C3AED', iconColor: '#FFFFFF', sendColor: '#007AFF', placeholder: 'Ask us anything', style: 'glass', corner: 'bottom-left', size: 56 }}>
+```
+
+The bubble can be dragged anywhere and remembers where it was left, shows a red
+number for unread replies and a green dot while someone on your team is online,
+and opens the chat beside it (full screen on a phone). The plain `<script>` snippet
+(t.js) does the same; there, `data-chat="off"` or `data-chat-bubble="hidden"` on
+the script tag, `data-chat-color`, `data-chat-icon-color`, `data-chat-send-color`,
+`data-chat-style`, `data-chat-corner`, `data-chat-size` and `data-chat-placeholder`
+(the message box text, in your own words and language) for your own look, and
+`AffiliateoChat.open()` from your own button.
+
 ## Changelog
 
+- **4.9.0:** Live Chat (see above): the chat bubble loads by itself once the
+  business switches it on; new `chat` prop and `openChat()`, `closeChat()`,
+  `showChatBubble()`, `hideChatBubble()`. `logout()` and `reset()` forget the
+  person's chat.
+
 - **4.8.0:** new `logout()` for sign-out. `reset()` is now the same as
   `logout()`: it used to mint a new visitor id and drop the affiliate ref,
   which split one person into two visitors. `identify()` skips placeholder ids,

package/dist/chat.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Live Chat (4.9.0): the chat bubble on a website that uses this package
+ * instead of the t.js snippet. Same behaviour as the snippet: once the
+ * business switches Live Chat on for this app in its Affiliateo dashboard,
+ * the bubble shows by itself. It is Affiliateo's own chat.js, loaded from the
+ * same origin as the API, so the website bubble looks and behaves the same
+ * whichever way a site installed Affiliateo.
+ *
+ * Asked once per visit: a site with the chat off is remembered for ten
+ * minutes in this tab (the same key t.js uses), so it costs one small request
+ * per visit, not per page.
+ */
+import type { ChatLook } from './types';
+export interface LoadLiveChatOptions {
+    apiBase: string;
+    appId: string;
+    /** The tracking visitor, so the inbox names them the way the tracking pages do. Null while opted out. */
+    visitorId: string | null;
+    /** The signed-in user id from identify(). Null while opted out. */
+    userId: string | null;
+    /** 'hidden' loads the chat without a bubble, for a site that opens it from its own button. */
+    bubble?: 'visible' | 'hidden';
+    theme?: 'light' | 'dark';
+    /** The site's own look for the bubble, over the dashboard's. */
+    look?: ChatLook;
+    log: (msg: string, data?: unknown) => void;
+}
+export declare function loadLiveChat(opts: LoadLiveChatOptions): void;
+/** Open the chat window, from your own button. Does nothing while the chat is off or still loading. */
+export declare function openChat(): void;
+/** Close the chat window. */
+export declare function closeChat(): void;
+/** Show the chat bubble (after hideChatBubble, or with chat="hidden"). */
+export declare function showChatBubble(): void;
+/** Hide the chat bubble, and close the window. */
+export declare function hideChatBubble(): void;
+/**
+ * The person signed out (logout(), reset()): their chat goes, so whoever
+ * signs in next starts a new thread. The token chat.js keeps goes from
+ * localStorage even while chat.js is still loading; once it has loaded, it
+ * also closes the window and clears the red number.
+ */
+export declare function forgetLiveChat(appId: string): void;

package/dist/chat.js

@@ -0,0 +1,117 @@
+/**
+ * Live Chat (4.9.0): the chat bubble on a website that uses this package
+ * instead of the t.js snippet. Same behaviour as the snippet: once the
+ * business switches Live Chat on for this app in its Affiliateo dashboard,
+ * the bubble shows by itself. It is Affiliateo's own chat.js, loaded from the
+ * same origin as the API, so the website bubble looks and behaves the same
+ * whichever way a site installed Affiliateo.
+ *
+ * Asked once per visit: a site with the chat off is remembered for ten
+ * minutes in this tab (the same key t.js uses), so it costs one small request
+ * per visit, not per page.
+ */
+const OFF_FOR_MS = 10 * 60 * 1000;
+function chatGlobal() {
+    if (typeof window === 'undefined')
+        return undefined;
+    return window.AffiliateoChat;
+}
+export function loadLiveChat(opts) {
+    if (typeof window === 'undefined' || typeof document === 'undefined' || typeof fetch !== 'function')
+        return;
+    if (!opts.appId || chatGlobal()?.__loaded)
+        return;
+    if (document.querySelector('script[data-affiliateo-chat]'))
+        return;
+    const offKey = `affiliateo_chat_off:${opts.appId}`;
+    try {
+        const off = sessionStorage.getItem(offKey);
+        if (off && Date.now() - Number(off) < OFF_FOR_MS)
+            return;
+    }
+    catch {
+        /* storage refused: ask */
+    }
+    fetch(`${opts.apiBase}/api/live-chat/config?app=${encodeURIComponent(opts.appId)}`)
+        .then((r) => (r.ok ? r.json() : null))
+        .then((config) => {
+        if (!config || !config.enabled) {
+            try {
+                sessionStorage.setItem(offKey, String(Date.now()));
+            }
+            catch {
+                /* storage refused */
+            }
+            opts.log('chat: off for this app');
+            return;
+        }
+        if (chatGlobal()?.__loaded || document.querySelector('script[data-affiliateo-chat]'))
+            return;
+        const script = document.createElement('script');
+        script.src = `${opts.apiBase}/chat.js`;
+        script.async = true;
+        script.setAttribute('data-affiliateo-chat', '');
+        script.setAttribute('data-app', opts.appId);
+        if (opts.visitorId)
+            script.setAttribute('data-visitor', opts.visitorId);
+        if (opts.userId)
+            script.setAttribute('data-user', opts.userId.slice(0, 128));
+        if (opts.bubble === 'hidden')
+            script.setAttribute('data-bubble', 'hidden');
+        if (opts.theme)
+            script.setAttribute('data-theme', opts.theme);
+        const look = opts.look;
+        if (look?.color)
+            script.setAttribute('data-color', look.color);
+        if (look?.iconColor)
+            script.setAttribute('data-icon-color', look.iconColor);
+        if (look?.sendColor)
+            script.setAttribute('data-send-color', look.sendColor);
+        if (look?.placeholder)
+            script.setAttribute('data-placeholder', look.placeholder.slice(0, 60));
+        if (look?.style)
+            script.setAttribute('data-style', look.style);
+        if (look?.corner)
+            script.setAttribute('data-corner', look.corner);
+        if (look?.size)
+            script.setAttribute('data-size', String(look.size));
+        (document.head || document.documentElement).appendChild(script);
+        opts.log('chat: loading the bubble');
+    })
+        .catch(() => opts.log('chat: config check failed (network)'));
+}
+/** Open the chat window, from your own button. Does nothing while the chat is off or still loading. */
+export function openChat() {
+    chatGlobal()?.open?.();
+}
+/** Close the chat window. */
+export function closeChat() {
+    chatGlobal()?.close?.();
+}
+/** Show the chat bubble (after hideChatBubble, or with chat="hidden"). */
+export function showChatBubble() {
+    chatGlobal()?.show?.();
+}
+/** Hide the chat bubble, and close the window. */
+export function hideChatBubble() {
+    chatGlobal()?.hide?.();
+}
+/**
+ * The person signed out (logout(), reset()): their chat goes, so whoever
+ * signs in next starts a new thread. The token chat.js keeps goes from
+ * localStorage even while chat.js is still loading; once it has loaded, it
+ * also closes the window and clears the red number.
+ */
+export function forgetLiveChat(appId) {
+    if (typeof window === 'undefined')
+        return;
+    if (appId) {
+        try {
+            localStorage.removeItem(`affiliateo_chat_token:${appId}`);
+        }
+        catch {
+            /* storage refused */
+        }
+    }
+    chatGlobal()?.__forget?.();
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { AffiliateoProvider, useAffiliateRef, getAttribution } from './provider';
-export type { AffiliateoConfig, AffiliateoContextValue } from './types';
+export { openChat, closeChat, showChatBubble, hideChatBubble } from './chat';
+export type { AffiliateoConfig, AffiliateoContextValue, ChatLook } from './types';

package/dist/index.js

@@ -1,2 +1,3 @@
 'use client';
 export { AffiliateoProvider, useAffiliateRef, getAttribution } from './provider';
+export { openChat, closeChat, showChatBubble, hideChatBubble } from './chat';

package/dist/provider.d.ts

@@ -18,6 +18,6 @@ export declare function useAffiliateRef(): AffiliateoContextValue;
  * ```
  */
 export declare function getAttribution(): Record<string, string>;
-export declare function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, children, }: AffiliateoConfig & {
+export declare function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, chat, chatLook, children, }: AffiliateoConfig & {
     children: React.ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/provider.js

@@ -6,6 +6,7 @@ import { isLikelyBot } from './bot-detect';
 import { isDevHost } from './dev-host';
 import { mintTurnstileToken, consumeTurnstileToken } from './turnstile';
 import { usableUserId } from './user-id';
+import { forgetLiveChat, loadLiveChat } from './chat';
 const DEFAULT_API_URL = 'https://affiliateo.com';
 const LS_VISITOR_ID = 'affiliateo_visitor_id';
 const LS_REF = 'affiliateo_ref';
@@ -195,7 +196,7 @@ let providerMountCount = 0;
 function isProductionBuild() {
     return typeof process !== 'undefined' && process?.env?.NODE_ENV === 'production';
 }
-export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, children, }) {
+export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, chat, chatLook, children, }) {
     // Normalize autoCapturePageviews. Three shapes:
     //   - undefined / true / object → auto-capture ON (with object overrides)
     //   - false → auto-capture OFF entirely (host must call trackPageview)
@@ -365,8 +366,8 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
     // browser starts over as a new anonymous customer of the app, so whoever
     // signs in next (or nobody) is not counted as the person who just left,
     // and everything already recorded stays with them. Forgets the stored
-    // user id. The visitor id, the affiliate ref, the session and tracking
-    // itself all carry on unchanged.
+    // user id and their Live Chat. The visitor id, the affiliate ref, the
+    // session and tracking itself all carry on unchanged.
     const logout = useCallback(async () => {
         try {
             if (typeof window === 'undefined')
@@ -374,6 +375,7 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
             log('logout');
             lsRemove(LS_USER_ID);
             lsRemove(LS_USER_SENT);
+            forgetLiveChat(appIdRef.current);
             if (isOptedOut())
                 return;
             const cid = appIdRef.current;
@@ -1028,5 +1030,24 @@ export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames
         // The boot configuration comes off bootRef above, so this list is what
         // legitimately rebuilds the pipeline.
     }, [apiBase, allowedHostnames, allowLocalhost, allowIframe, log, track, identify, trackPageview, reset, logout, optOut, optIn, flush]);
+    // Live Chat (4.9.0, chat.ts). After the tracking effect above has read or
+    // minted the visitor id, so the inbox can name the visitor. Neither the
+    // visitor nor the signed-in user goes along while tracking is opted out.
+    useEffect(() => {
+        if (chat === false || !resolvedAppId)
+            return;
+        const optedOut = isOptedOut();
+        loadLiveChat({
+            apiBase,
+            appId: resolvedAppId,
+            visitorId: optedOut ? null : visitorIdRef.current ?? lsGet(LS_VISITOR_ID),
+            userId: optedOut ? null : usableUserId(lsGet(LS_USER_ID)),
+            bubble: chat === 'hidden' ? 'hidden' : 'visible',
+            look: chatLook,
+            log,
+        });
+        // The look is read when the bubble loads.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [chat, resolvedAppId, apiBase, log]);
     return (_jsx(AffiliateoContext.Provider, { value: state, children: children }));
 }

package/dist/types.d.ts

@@ -80,6 +80,17 @@ export interface AffiliateoConfig {
     /** Pageview auto-capture behavior. Pass `false` to disable entirely
      *  (you'll call `trackPageview()` yourself). Pass an object to fine-tune.
      *  Defaults to `true` (auto-capture everything). */
+    /** Live Chat (4.9.0). Once the business switches Live Chat on for this
+     *  app in its Affiliateo dashboard, a chat bubble shows on the site.
+     *  `true` (the default) shows it; `'hidden'` loads the chat without a
+     *  bubble, for a site that calls `openChat()` from its own button; `false`
+     *  never loads it. */
+    chat?: boolean | 'hidden';
+    /** Your own look for the chat bubble (4.15.0), over the Live Chat settings
+     *  in your dashboard: anything left out keeps the dashboard's choice.
+     *  sendColor colors the send button and the person's own messages;
+     *  placeholder is the message box text, in your own words and language. */
+    chatLook?: ChatLook;
     autoCapturePageviews?: boolean | {
         /** Fire the initial pageview on mount. Defaults to true. Set false
          *  for cookie-consent flows where you want to defer until the user
@@ -152,7 +163,8 @@ export interface AffiliateoContextValue {
     /** The user signed out (4.8.0). Call it on sign-out: this browser starts
      *  over as a new anonymous customer of the app, so whoever signs in next
      *  (or nobody) is not counted as the person who just left, and everything
-     *  already recorded stays with them. Forgets the stored user id. The
+     *  already recorded stays with them. Forgets the stored user id, and
+     *  their Live Chat: the next person to open it starts a new thread. The
      *  visitor id, the affiliate ref and tracking carry on unchanged.
      *
      *  Example:
@@ -209,3 +221,16 @@ export interface AffiliateoContextValue {
      *  flush). Safe to await without timeout concerns. */
     flush: () => Promise<void>;
 }
+/** The chat bubble's look, set in code (4.15.0). Colors are hex ("#7C3AED"). */
+export interface ChatLook {
+    color?: string;
+    iconColor?: string;
+    /** The chat's send button and the person's own messages (iMessage blue unless the dashboard says otherwise). */
+    sendColor?: string;
+    /** The message box text, in your own words and language (up to 60 characters): pass your app's own translation. */
+    placeholder?: string;
+    style?: 'solid' | 'glass';
+    corner?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** In pixels, 40 to 80. */
+    size?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@affiliateo/web",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Affiliateo web SDK: affiliate attribution and tracking for web apps",
   "main": "dist/index.js",
   "module": "dist/index.js",