@usereq/widget 0.2.25 → 1.0.0-experimental.0

package/src/runtime/bootstrap.ts

@@ -1,366 +0,0 @@
-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";
-import { widgetDebug, widgetWarn } from "./debug";
-
-export type WidgetBootstrapState = {
-  session: WidgetSessionState;
-  conversationId?: string;
-  messages: WidgetMessage[];
-};
-
-/**
- * Compact, JSON-safe error shape for the verbose logs. Strips noisy
- * stack lines but keeps message + name + (if present) `code` so AppError
- * responses surface their server-side code in the customer's console.
- */
-function serializeError(error: unknown): {
-  name: string;
-  message: string;
-  code?: string;
-  status?: number;
-} {
-  if (error instanceof Error) {
-    const err = error as Error & { code?: unknown; status?: unknown };
-    return {
-      name: err.name,
-      message: err.message,
-      code: typeof err.code === "string" ? err.code : undefined,
-      status: typeof err.status === "number" ? err.status : undefined,
-    };
-  }
-  return { name: "Unknown", message: String(error) };
-}
-
-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 (error) {
-      // Network blip during the refresh is recoverable — the cached
-      // session is still valid, so we fall back to it. But log so the
-      // customer's DevTools shows the underlying API failure (origin
-      // not allowed, agent archived, server 5xx, etc.).
-      widgetWarn(
-        "bootstrap.refreshSession",
-        "config refresh failed, using cached session",
-        { agentId: input.agentId, error: serializeError(error) },
-      );
-      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 (error) {
-      // Stored conversation id was orphaned (deleted server-side,
-      // expired session, etc.). Drop it and act as if we're a fresh
-      // visitor. Surface the underlying failure — silent-drop here is
-      // exactly what makes "no welcome message + no send" so hard to
-      // debug from the outside.
-      widgetWarn(
-        "bootstrap.listMessages",
-        "transcript fetch failed, resetting conversation",
-        {
-          agentId: input.agentId,
-          conversationId,
-          error: serializeError(error),
-        },
-      );
-      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 (error) {
-      // The `current conversation` lookup failed (most commonly a 401
-      // because the session token is stale, or a 403 because the host
-      // origin isn't in the agent's allow-list). Without surfacing
-      // this, the panel renders empty + `sendDisabled=true` and the
-      // visitor has no way to recover or signal something's wrong.
-      widgetWarn(
-        "bootstrap.currentConversation",
-        "no conversation could be resolved, starting fresh",
-        { agentId: input.agentId, error: serializeError(error) },
-      );
-      conversationId = undefined;
-      messages = [];
-    }
-  }
-
-  const sessionState: WidgetSessionState = {
-    ...session,
-    conversationId,
-  };
-  deps.saveSession(input.agentId, sessionState);
-
-  widgetDebug("bootstrap.ready", "session resolved", {
-    agentId: input.agentId,
-    hasConversation: Boolean(conversationId),
-    messageCount: messages.length,
-    autoStart: Boolean(sessionState.widgetConfig.widgetBehavior?.autoStart),
-    defaultOpen: Boolean(sessionState.widgetConfig.widgetBehavior?.defaultOpen),
-    alwaysOpen: Boolean(sessionState.widgetConfig.widgetBehavior?.alwaysOpen),
-  });
-
-  return {
-    session: sessionState,
-    conversationId,
-    messages,
-  };
-}
-
-export async function bootstrapWidget(input: {
-  agentId: string;
-  pageUrl?: string;
-  referrer?: string;
-}): Promise<WidgetBootstrapState> {
-  return bootstrapWidgetWithDeps(input, defaultBootstrapDeps);
-}
-
-/**
- * Send a user message. Lazy-starts the conversation on the first send —
- * `startPublicChat` is called transparently when no `conversationId` is
- * stored yet, so visitors never create empty conversations by opening
- * the panel and walking away. When a start happens as part of this call
- * the server-inserted welcome message rides back on `welcomeMessage`
- * so the caller can reconcile the client-side placeholder bubble with
- * the real DB row.
- */
-export async function submitWidgetMessage(input: {
-  agentId: string;
-  content: string;
-}): Promise<{
-  session: WidgetSessionState;
-  conversationId: string;
-  messages: WidgetMessage[];
-  userMessage: WidgetMessage;
-  assistantMessages: WidgetMessage[];
-  welcomeMessage?: WidgetMessage;
-}> {
-  let stored = await ensureWidgetSession({
-    agentId: input.agentId,
-    pageUrl: window.location.href,
-    referrer: document.referrer || undefined,
-  });
-
-  let welcomeMessage: WidgetMessage | undefined;
-  let conversationId: string;
-  if (stored.conversationId) {
-    conversationId = stored.conversationId;
-  } else {
-    const started = await startPublicChat({
-      agentId: input.agentId,
-      sessionToken: stored.sessionToken,
-    });
-    conversationId = started.conversation.id;
-    stored = { ...stored, conversationId };
-    saveSession(input.agentId, stored);
-    welcomeMessage = started.welcomeMessage;
-  }
-
-  const response = await sendPublicChatMessage({
-    conversationId,
-    sessionToken: stored.sessionToken,
-    content: input.content,
-  });
-
-  const nextSession: WidgetSessionState = {
-    ...stored,
-    conversationId,
-  };
-  saveSession(input.agentId, nextSession);
-
-  return {
-    session: nextSession,
-    conversationId,
-    messages: sortByCreatedAt([
-      ...(welcomeMessage ? [welcomeMessage] : []),
-      response.userMessage,
-      ...response.assistantMessages,
-    ]),
-    userMessage: response.userMessage,
-    assistantMessages: response.assistantMessages,
-    welcomeMessage,
-  };
-}
-
-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 resetWidgetSession(agentId: string): Promise<void> {
-  clearSession(agentId);
-}

package/src/runtime/debug.ts

@@ -1,104 +0,0 @@
-/**
- * Widget debug logging.
- *
- * Two tiers:
- *
- *  1. ALWAYS-ON warnings  (`widgetWarn`) — fired on every silent failure
- *     path that would otherwise leave the visitor with a broken widget
- *     and no signal in the console. e.g. `/start` returns 403, the
- *     transcript fetch dies, the session token is stale. Surfaced via
- *     `console.warn` so a customer running our widget on their site can
- *     open DevTools and immediately see WHY the chat isn't working —
- *     no env vars, no rebuilds, no extra steps.
- *
- *  2. OPT-IN traces  (`widgetDebug`) — verbose state-transition logs
- *     ("bootstrap started", "session restored", "auto-start fired"). Off
- *     by default; turned on by either:
- *       - `localStorage.setItem("usereq_debug", "1")` (sticky)
- *       - `?usereq_debug=1` in the embed-host's URL (one-shot)
- *
- * Both routes are namespace-prefixed so customer's own console output
- * doesn't get tangled with ours.
- */
-
-const PREFIX = "[usereq-widget]";
-
-/** True when verbose-trace logging is enabled. Memoized per page load. */
-let debugEnabled: boolean | null = null;
-
-export function isWidgetDebugEnabled(): boolean {
-  if (debugEnabled !== null) return debugEnabled;
-  debugEnabled = computeDebugEnabled();
-  return debugEnabled;
-}
-
-function computeDebugEnabled(): boolean {
-  if (typeof window === "undefined") return false;
-  try {
-    // Query param is one-shot per page load — handy for "ask the
-    // customer to add `?usereq_debug=1` to their URL and reproduce."
-    const params = new URLSearchParams(window.location.search);
-    if (params.get("usereq_debug") === "1") return true;
-  } catch {
-    /* iframe with restricted location.search — ignore */
-  }
-  try {
-    if (window.localStorage?.getItem("usereq_debug") === "1") return true;
-  } catch {
-    /* incognito / disabled localStorage — ignore */
-  }
-  return false;
-}
-
-/**
- * Always-on warning. Use for silent-failure paths where we currently
- * swallow an error but the visitor's chat will visibly break.
- *
- * Output shape:
- *   [usereq-widget] bootstrap.listMessages failed { agentId, sessionToken, error }
- */
-export function widgetWarn(scope: string, message: string, context?: unknown): void {
-  if (context === undefined) {
-    console.warn(`${PREFIX} ${scope}: ${message}`);
-    return;
-  }
-  console.warn(`${PREFIX} ${scope}: ${message}`, sanitizeForLog(context));
-}
-
-/**
- * Opt-in trace. Logs state transitions / network calls when debug mode
- * is on. Production builds keep these as `console.debug` calls; modern
- * DevTools hide `debug` by default so the warning channel stays clean.
- */
-export function widgetDebug(scope: string, message: string, context?: unknown): void {
-  if (!isWidgetDebugEnabled()) return;
-  if (context === undefined) {
-    console.debug(`${PREFIX} ${scope}: ${message}`);
-    return;
-  }
-  console.debug(`${PREFIX} ${scope}: ${message}`, sanitizeForLog(context));
-}
-
-/**
- * Strip session tokens / PII from arbitrary context objects before
- * logging. Keeps prefixes long enough to recognize the session at a
- * glance ("eyJh…") without leaking the secret.
- */
-function sanitizeForLog(context: unknown): unknown {
-  if (context === null || typeof context !== "object") return context;
-  try {
-    const json = JSON.parse(
-      JSON.stringify(context, (_key, value) => {
-        if (typeof value === "string") {
-          if (value.length > 32 && /^[A-Za-z0-9_.\-+/=]+$/.test(value)) {
-            return `${value.slice(0, 8)}…(redacted, len=${value.length})`;
-          }
-        }
-        return value;
-      }),
-    );
-    return json;
-  } catch {
-    return context;
-  }
-}

package/src/runtime/messages.ts

@@ -1,12 +0,0 @@
-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

@@ -1,32 +0,0 @@
-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/trigger-rule.ts

@@ -1,182 +0,0 @@
-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/shadow-css.ts

@@ -1,15 +0,0 @@
-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;
-}