@usereq/widget 0.1.0

package/src/runtime/bootstrap.ts

@@ -0,0 +1,309 @@
+import {
+  getCurrentConversation,
+  listConversationMessages,
+  mintWidgetSession,
+  sendPublicChatConfirmation,
+  sendPublicChatMessage,
+  startPublicChat,
+} from "./api";
+import { clearSession, loadSession, saveSession } from "./session-storage";
+import type { WidgetMessage, WidgetSessionState } from "../types";
+import { sortByCreatedAt } from "./messages";
+import {
+  encodeStopConfirmationPrompt,
+  encodeStopConfirmationResult,
+  type StopConfirmationDecision,
+} from "../shared/stop-confirmation";
+
+export type WidgetBootstrapState = {
+  session: WidgetSessionState;
+  conversationId?: string;
+  messages: WidgetMessage[];
+};
+
+export type WidgetBootstrapDeps = {
+  loadSession: typeof loadSession;
+  saveSession: typeof saveSession;
+  mintWidgetSession: typeof mintWidgetSession;
+  getCurrentConversation: typeof getCurrentConversation;
+  listConversationMessages: typeof listConversationMessages;
+  getOrigin: () => string;
+  now: () => number;
+};
+
+const defaultBootstrapDeps: WidgetBootstrapDeps = {
+  loadSession,
+  saveSession,
+  mintWidgetSession,
+  getCurrentConversation,
+  listConversationMessages,
+  getOrigin: () => window.location.origin,
+  now: () => Date.now(),
+};
+
+export function isSessionTokenValid(
+  session: WidgetSessionState | null,
+  nowMs: number = Date.now()
+): session is WidgetSessionState {
+  if (!session) return false;
+  const expiryMs = new Date(session.expiresAt).getTime();
+  return Number.isFinite(expiryMs) && expiryMs > nowMs;
+}
+
+async function ensureWidgetSession(input: {
+  agentId: string;
+  pageUrl?: string;
+  referrer?: string;
+}, deps: WidgetBootstrapDeps = defaultBootstrapDeps, options?: {
+  refreshWidgetConfig?: boolean;
+}): Promise<WidgetSessionState> {
+  const stored = deps.loadSession(input.agentId);
+  const hasValidStoredSession = isSessionTokenValid(stored, deps.now());
+
+  if (hasValidStoredSession && !options?.refreshWidgetConfig) {
+    return stored;
+  }
+
+  if (hasValidStoredSession && options?.refreshWidgetConfig) {
+    try {
+      const minted = await deps.mintWidgetSession({
+        agentId: input.agentId,
+        origin: deps.getOrigin(),
+        pageUrl: input.pageUrl,
+        referrer: input.referrer,
+      });
+
+      const refreshed: WidgetSessionState = {
+        ...stored,
+        widgetConfig: minted.widgetConfig,
+      };
+      deps.saveSession(input.agentId, refreshed);
+      return refreshed;
+    } catch {
+      return stored;
+    }
+  }
+
+  const minted = await deps.mintWidgetSession({
+    agentId: input.agentId,
+    origin: deps.getOrigin(),
+    pageUrl: input.pageUrl,
+    referrer: input.referrer,
+  });
+
+  const sessionState: WidgetSessionState = {
+    sessionToken: minted.sessionToken,
+    expiresAt: minted.expiresAt,
+    widgetConfig: minted.widgetConfig,
+  };
+  deps.saveSession(input.agentId, sessionState);
+  return sessionState;
+}
+
+export async function bootstrapWidgetWithDeps(input: {
+  agentId: string;
+  pageUrl?: string;
+  referrer?: string;
+}, deps: WidgetBootstrapDeps): Promise<WidgetBootstrapState> {
+  const session = await ensureWidgetSession(input, deps, {
+    refreshWidgetConfig: true,
+  });
+
+  let conversationId = session.conversationId;
+  let messages: WidgetMessage[] = [];
+
+  if (conversationId) {
+    try {
+      const transcript = await deps.listConversationMessages({
+        conversationId,
+        sessionToken: session.sessionToken,
+      });
+      messages = sortByCreatedAt(transcript.data);
+    } catch {
+      conversationId = undefined;
+      messages = [];
+    }
+  } else {
+    try {
+      const current = await deps.getCurrentConversation(session.sessionToken);
+      conversationId = current.conversation?.id ?? undefined;
+      if (conversationId) {
+        const transcript = await deps.listConversationMessages({
+          conversationId,
+          sessionToken: session.sessionToken,
+        });
+        messages = sortByCreatedAt(transcript.data);
+      }
+    } catch {
+      conversationId = undefined;
+      messages = [];
+    }
+  }
+
+  const sessionState: WidgetSessionState = {
+    ...session,
+    conversationId,
+  };
+  deps.saveSession(input.agentId, sessionState);
+
+  return {
+    session: sessionState,
+    conversationId,
+    messages,
+  };
+}
+
+export async function bootstrapWidget(input: {
+  agentId: string;
+  pageUrl?: string;
+  referrer?: string;
+}): Promise<WidgetBootstrapState> {
+  return bootstrapWidgetWithDeps(input, defaultBootstrapDeps);
+}
+
+export async function submitWidgetMessage(input: {
+  agentId: string;
+  content: string;
+}): Promise<{
+  session: WidgetSessionState;
+  conversationId: string;
+  messages: WidgetMessage[];
+  userMessage: WidgetMessage;
+  assistantMessages: WidgetMessage[];
+}> {
+  const stored = await ensureWidgetSession({
+    agentId: input.agentId,
+    pageUrl: window.location.href,
+    referrer: document.referrer || undefined,
+  });
+  if (!stored.conversationId) {
+    throw new Error("Widget conversation not started");
+  }
+
+  const response = await sendPublicChatMessage({
+    conversationId: stored.conversationId,
+    sessionToken: stored.sessionToken,
+    content: input.content,
+  });
+
+  const nextSession: WidgetSessionState = {
+    ...stored,
+    conversationId: stored.conversationId,
+  };
+  saveSession(input.agentId, nextSession);
+
+  return {
+    session: nextSession,
+    conversationId: stored.conversationId,
+    messages: sortByCreatedAt([
+      response.userMessage,
+      ...response.assistantMessages,
+    ]),
+    userMessage: response.userMessage,
+    assistantMessages: response.assistantMessages,
+  };
+}
+
+export async function submitWidgetStopConfirmation(input: {
+  agentId: string;
+  confirmationId: string;
+  prompt?: string;
+}): Promise<{
+  session: WidgetSessionState;
+  conversationId: string;
+  confirmationMessage: WidgetMessage;
+}>;
+export async function submitWidgetStopConfirmation(input: {
+  agentId: string;
+  confirmationId: string;
+  decision: StopConfirmationDecision;
+}): Promise<{
+  session: WidgetSessionState;
+  conversationId: string;
+  confirmationMessage: WidgetMessage;
+}>;
+export async function submitWidgetStopConfirmation(input: {
+  agentId: string;
+  confirmationId: string;
+  prompt?: string;
+  decision?: StopConfirmationDecision;
+}): Promise<{
+  session: WidgetSessionState;
+  conversationId: string;
+  confirmationMessage: WidgetMessage;
+}> {
+  const stored = await ensureWidgetSession({
+    agentId: input.agentId,
+    pageUrl: window.location.href,
+    referrer: document.referrer || undefined,
+  });
+  if (!stored.conversationId) {
+    throw new Error("Widget conversation not started");
+  }
+
+  const content =
+    input.decision != null
+      ? encodeStopConfirmationResult({
+          confirmationId: input.confirmationId,
+          decision: input.decision,
+        })
+      : encodeStopConfirmationPrompt({
+          confirmationId: input.confirmationId,
+          prompt: input.prompt,
+        });
+
+  const response = await sendPublicChatConfirmation({
+    conversationId: stored.conversationId,
+    sessionToken: stored.sessionToken,
+    content,
+  });
+
+  const nextSession: WidgetSessionState = {
+    ...stored,
+    conversationId: stored.conversationId,
+  };
+  saveSession(input.agentId, nextSession);
+
+  return {
+    session: nextSession,
+    conversationId: stored.conversationId,
+    confirmationMessage: response.confirmationMessage,
+  };
+}
+
+export async function startWidgetConversation(input: {
+  agentId: string;
+}): Promise<{
+  session: WidgetSessionState;
+  conversationId: string;
+  messages: WidgetMessage[];
+  welcomeMessage: WidgetMessage;
+}> {
+  const stored = await ensureWidgetSession({
+    agentId: input.agentId,
+    pageUrl: window.location.href,
+    referrer: document.referrer || undefined,
+  });
+
+  const response = await startPublicChat({
+    agentId: input.agentId,
+    sessionToken: stored.sessionToken,
+  });
+
+  const nextSession: WidgetSessionState = {
+    ...stored,
+    conversationId: response.conversation.id,
+  };
+  saveSession(input.agentId, nextSession);
+
+  return {
+    session: nextSession,
+    conversationId: response.conversation.id,
+    messages: sortByCreatedAt([response.welcomeMessage]),
+    welcomeMessage: response.welcomeMessage,
+  };
+}
+
+export async function resetWidgetSession(agentId: string): Promise<void> {
+  clearSession(agentId);
+}

package/src/runtime/messages.ts

@@ -0,0 +1,12 @@
+import type { WidgetMessage } from "../types";
+
+export function sortByCreatedAt(messages: WidgetMessage[]): WidgetMessage[] {
+  return [...messages].sort(
+    (a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime()
+  );
+}
+
+export function messageRoleLabel(role: WidgetMessage["role"]): string {
+  return role === "user" ? "You" : "Assistant";
+}
+

package/src/runtime/session-storage.ts

@@ -0,0 +1,32 @@
+import type { WidgetSessionState } from "../types";
+
+function key(agentId: string): string {
+  return `usereq-widget:${agentId}`;
+}
+
+export function loadSession(agentId: string): WidgetSessionState | null {
+  try {
+    const raw = sessionStorage.getItem(key(agentId));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as WidgetSessionState;
+    if (
+      !parsed?.sessionToken ||
+      !parsed?.expiresAt ||
+      !parsed?.widgetConfig?.agentId ||
+      !parsed?.widgetConfig?.name
+    ) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function saveSession(agentId: string, value: WidgetSessionState): void {
+  sessionStorage.setItem(key(agentId), JSON.stringify(value));
+}
+
+export function clearSession(agentId: string): void {
+  sessionStorage.removeItem(key(agentId));
+}

package/src/runtime/token-renewal.ts

@@ -0,0 +1,13 @@
+export function scheduleRenewal(
+  expiresAt: string,
+  onRenew: () => Promise<void> | void
+): () => void {
+  const expiryMs = new Date(expiresAt).getTime();
+  const delay = Math.max(5_000, expiryMs - Date.now() - 60_000);
+  const timer = window.setTimeout(() => {
+    void onRenew();
+  }, delay);
+
+  return () => window.clearTimeout(timer);
+}
+

package/src/runtime/trigger-rule.ts

@@ -0,0 +1,182 @@
+import { useEffect, useLayoutEffect, useState } from "react";
+import type { WidgetTriggerRule } from "../types";
+
+type Cleanup = () => void;
+
+function isValidDelay(value: unknown): value is number {
+  return typeof value === "number" && !Number.isNaN(value) && value >= 0;
+}
+
+function waitForElementById(
+  id: string,
+  callback: (element: HTMLElement) => void,
+): Cleanup {
+  const immediate = document.getElementById(id);
+  if (immediate instanceof HTMLElement) {
+    callback(immediate);
+    return () => undefined;
+  }
+
+  const observedRoot = document.body ?? document.documentElement;
+  if (!observedRoot) {
+    return () => undefined;
+  }
+
+  let settled = false;
+  const observer = new MutationObserver(() => {
+    if (settled) return;
+    const node = document.getElementById(id);
+    if (node instanceof HTMLElement) {
+      settled = true;
+      observer.disconnect();
+      callback(node);
+    }
+  });
+
+  observer.observe(observedRoot, { childList: true, subtree: true });
+
+  return () => {
+    settled = true;
+    observer.disconnect();
+  };
+}
+
+export function useWidgetTriggerGate(triggerRule?: WidgetTriggerRule | null) {
+  const [ready, setReady] = useState(triggerRule == null);
+  const useReadyEffect =
+    typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+  useReadyEffect(() => {
+    let canceled = false;
+
+    const markReady = () => {
+      if (!canceled) {
+        setReady(true);
+      }
+    };
+
+    if (!triggerRule) {
+      setReady(true);
+      return () => {
+        canceled = true;
+      };
+    }
+
+    setReady(false);
+
+    let cleanup: Cleanup = () => undefined;
+
+    switch (triggerRule.triggerRuleType) {
+      case "time_delay": {
+        if (!isValidDelay(triggerRule.timeDelay)) {
+          markReady();
+          return () => {
+            canceled = true;
+          };
+        }
+
+        const timeout = window.setTimeout(
+          markReady,
+          triggerRule.timeDelay * 1000,
+        );
+        cleanup = () => {
+          window.clearTimeout(timeout);
+        };
+        break;
+      }
+
+      case "scroll_to_bottom": {
+        if (!triggerRule.scrollToBottom) {
+          markReady();
+          return () => {
+            canceled = true;
+          };
+        }
+
+        const checkBottom = () => {
+          const scrollTop = window.scrollY;
+          const viewportHeight = window.innerHeight;
+          const scrollHeight = document.documentElement.scrollHeight;
+          if (scrollTop + viewportHeight >= scrollHeight - 1) {
+            markReady();
+          }
+        };
+
+        checkBottom();
+        window.addEventListener("scroll", checkBottom, { passive: true });
+        window.addEventListener("resize", checkBottom);
+        cleanup = () => {
+          window.removeEventListener("scroll", checkBottom);
+          window.removeEventListener("resize", checkBottom);
+        };
+        break;
+      }
+
+      case "element_displayed": {
+        if (!triggerRule.elementDisplayed) {
+          markReady();
+          return () => {
+            canceled = true;
+          };
+        }
+
+        let observer: IntersectionObserver | null = null;
+        const stopWaiting = waitForElementById(
+          triggerRule.elementDisplayed,
+          (node) => {
+            observer = new IntersectionObserver((entries) => {
+              if (entries.some((entry) => entry.isIntersecting)) {
+                markReady();
+              }
+            });
+            observer.observe(node);
+          },
+        );
+
+        cleanup = () => {
+          observer?.disconnect();
+          stopWaiting();
+        };
+        break;
+      }
+
+      case "element_clicked": {
+        if (!triggerRule.elementClicked) {
+          markReady();
+          return () => {
+            canceled = true;
+          };
+        }
+
+        const selector = `#${CSS.escape(triggerRule.elementClicked)}`;
+        const handler = (event: MouseEvent) => {
+          const target = event.target;
+          if (!(target instanceof Element)) return;
+          if (target.closest(selector)) {
+            markReady();
+          }
+        };
+
+        document.addEventListener("click", handler, true);
+        cleanup = () => {
+          document.removeEventListener("click", handler, true);
+        };
+        break;
+      }
+
+      default: {
+        markReady();
+        return () => {
+          canceled = true;
+        };
+      }
+    }
+
+    return () => {
+      canceled = true;
+      cleanup();
+    };
+  }, [triggerRule]);
+
+  return { ready: ready || triggerRule == null };
+}

package/src/shared/analytics.ts

@@ -0,0 +1,54 @@
+export const WIDGET_ANALYTICS_EVENT_TYPES = [
+  "SCRIPT_LOADED",
+  "UNIQUE_SCRIPT_LOADED",
+  "VIEW",
+  "CLICK",
+  "SESSION_START",
+  "DISPLAY_AFTER_ELEMENT_SHOWED",
+  "WIDGET_DISPLAY_AFTER_VSL_SHOWED",
+  "LINK_CLICKED",
+] as const;
+
+export type WidgetAnalyticsEventType =
+  (typeof WIDGET_ANALYTICS_EVENT_TYPES)[number];
+
+export const WIDGET_CLIENT_ANALYTICS_EVENT_TYPES = [
+  "SCRIPT_LOADED",
+  "UNIQUE_SCRIPT_LOADED",
+  "VIEW",
+  "CLICK",
+  "DISPLAY_AFTER_ELEMENT_SHOWED",
+  "LINK_CLICKED",
+] as const;
+
+export type WidgetClientAnalyticsEventType =
+  (typeof WIDGET_CLIENT_ANALYTICS_EVENT_TYPES)[number];
+
+export const WIDGET_TRIGGER_RULE_TYPES = [
+  "time_delay",
+  "scroll_to_bottom",
+  "element_clicked",
+  "element_displayed",
+] as const;
+
+export type WidgetTriggerRuleType = (typeof WIDGET_TRIGGER_RULE_TYPES)[number];
+
+export type WidgetAnalyticsBatchEvent = {
+  eventType: WidgetClientAnalyticsEventType;
+  occurredAt?: string;
+  conversationId?: string | null;
+  triggerRuleType?: WidgetTriggerRuleType | null;
+  linkUrl?: string | null;
+};
+
+export type WidgetAnalyticsBatchRequest = {
+  events: WidgetAnalyticsBatchEvent[];
+  pageUrl?: string;
+  referrer?: string;
+  sessionToken?: string;
+};
+
+export type WidgetAnalyticsBatchResponse = {
+  accepted: number;
+};
+

package/src/shared/shadow-css.ts

@@ -0,0 +1,15 @@
+type WidgetShadowCssGlobal = typeof globalThis & {
+  __USEREQ_WIDGET_SHADOW_CSS__?: string;
+};
+
+export const WIDGET_SHADOW_CSS_GLOBAL = "__USEREQ_WIDGET_SHADOW_CSS__";
+
+export function setWidgetShadowCss(css: string | null | undefined) {
+  const global = globalThis as WidgetShadowCssGlobal;
+  global[WIDGET_SHADOW_CSS_GLOBAL] = css?.trim() ? css : undefined;
+}
+
+export function getWidgetShadowCss(): string | null {
+  const global = globalThis as WidgetShadowCssGlobal;
+  return global[WIDGET_SHADOW_CSS_GLOBAL]?.trim() || null;
+}

package/src/shared/shadow-theme.ts

@@ -0,0 +1,85 @@
+export const WIDGET_SHADOW_THEME_CSS = `
+:host {
+  color-scheme: light;
+  --tw-border-style: solid;
+  --radius: 0.625rem;
+  --font-geist-sans: Geist, sans-serif;
+  --font-geist-mono: Geist_Mono, monospace;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --brand: oklch(0.55 0.22 263);
+  --brand-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-brand: var(--brand);
+  --color-brand-foreground: var(--brand-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) + 8px);
+  --radius-3xl: calc(var(--radius) + 12px);
+  --radius-4xl: calc(var(--radius) + 16px);
+  --spacing-header: 3rem;
+}
+`;