@usereq/widget 0.1.0

package/src/renderer/widget-runtime.tsx

@@ -0,0 +1,205 @@
+import React from "react";
+import {
+  ChatWidgetBubble,
+  ChatWidgetBox,
+  ChatWidgetChatBar,
+} from "../chat-widget";
+import type { WidgetMessage } from "../types";
+import {
+  splitWidgetPlacement,
+  type WidgetAppearance,
+  type WidgetPlacement,
+  type WidgetVariant,
+} from "../shared/widget-config";
+import type { WidgetTriggerRule } from "../shared/widget-config";
+import { getPendingStopConfirmationId } from "../shared/stop-confirmation";
+import { widgetCss } from "../styles/widget.css";
+import { useWidgetTriggerGate } from "../runtime/trigger-rule";
+import type { WidgetTriggerRuleType } from "../shared/analytics";
+
+export type WidgetRuntimeMode = "embed" | "preview";
+
+export type WidgetRuntimeStatus = "idle" | "booting" | "ready" | "sending" | "error";
+
+export type WidgetRuntimeProps = {
+  mode: WidgetRuntimeMode;
+  agentId: string;
+  variant: WidgetVariant;
+  placement: WidgetPlacement;
+  appearance: WidgetAppearance;
+  agentAvatarUrl: string | null;
+  widgetTitle: string;
+  welcomeMessage: string | null;
+  spotlights: string[];
+  open: boolean;
+  status: WidgetRuntimeStatus;
+  messages: WidgetMessage[];
+  errorMessage: string | null;
+  triggerRule?: WidgetTriggerRule | null;
+  emptyAction?: { label: string; onClick: () => void; disabled?: boolean };
+  sendDisabled?: boolean;
+  onOpenChange: (open: boolean) => void;
+  onSendMessage: (content: string) => void;
+  onStopConversation?: () => void;
+  onConfirmationDecision?: (
+    confirmationId: string,
+    accepted: boolean,
+  ) => void | Promise<void>;
+  portalContainer?: HTMLElement | DocumentFragment | null;
+  onWidgetVisible?: (triggerRuleType: WidgetTriggerRuleType | null) => void;
+  onLinkClick?: (linkUrl: string) => void;
+  onLauncherClick?: () => void;
+};
+
+const VARIANT_COMPONENTS = {
+  default: ChatWidgetBubble,
+  box: ChatWidgetBox,
+  chatbar: ChatWidgetChatBar,
+} as const;
+
+export function WidgetRuntime({
+  mode,
+  agentId,
+  variant,
+  placement,
+  appearance,
+  agentAvatarUrl,
+  widgetTitle,
+  spotlights,
+  open,
+  status,
+  messages,
+  errorMessage,
+  triggerRule,
+  emptyAction,
+  sendDisabled = false,
+  onOpenChange,
+  onSendMessage,
+  onStopConversation,
+  onConfirmationDecision,
+  portalContainer,
+  onWidgetVisible,
+  onLinkClick,
+  onLauncherClick,
+}: WidgetRuntimeProps) {
+  const { ready } = useWidgetTriggerGate(triggerRule);
+  const { horizontal, vertical } = splitWidgetPlacement(placement);
+  const Component = VARIANT_COMPONENTS[variant] ?? ChatWidgetBubble;
+  const shellStyle = getWidgetShellStyle(mode, placement);
+  const resolvedAvatarUrl = agentAvatarUrl?.trim() || undefined;
+  const pendingConfirmationId = getPendingStopConfirmationId(messages);
+  const confirmationPending = pendingConfirmationId != null;
+  const stopDisabledResolved = confirmationPending || status === "booting" || status === "sending";
+  const sendDisabledResolved =
+    sendDisabled || confirmationPending || status === "booting";
+  const viewTrackedRef = React.useRef(false);
+
+  React.useEffect(() => {
+    if (mode !== "embed" || !ready || viewTrackedRef.current) {
+      return;
+    }
+    viewTrackedRef.current = true;
+    onWidgetVisible?.(triggerRule?.triggerRuleType ?? null);
+  }, [mode, onWidgetVisible, ready, triggerRule]);
+
+  if (!ready) {
+    return null;
+  }
+
+  return (
+    <>
+      <style>{widgetCss}</style>
+      <div
+        data-agent-id={agentId}
+        data-mode={mode}
+        data-horizontal={horizontal}
+        data-vertical={vertical}
+        data-variant={variant}
+        data-open={String(open)}
+        data-status={status}
+        style={shellStyle}
+        className="widget-shell"
+      >
+        <div style={{ pointerEvents: "auto" }}>
+          <Component
+            agentName={widgetTitle}
+            agentAvatarUrl={resolvedAvatarUrl}
+            appearance={appearance}
+            spotlightMessages={spotlights}
+            messages={messages}
+            status={status}
+            errorMessage={errorMessage}
+            emptyAction={emptyAction}
+            sendDisabled={sendDisabledResolved}
+            onSendMessage={onSendMessage}
+            open={open}
+            onOpenChange={onOpenChange}
+            onStopConversation={onStopConversation}
+            stopDisabled={stopDisabledResolved}
+            onConfirmationDecision={onConfirmationDecision}
+            onLauncherClick={onLauncherClick}
+            onLinkClick={onLinkClick}
+            portalContainer={portalContainer}
+          />
+        </div>
+      </div>
+    </>
+  );
+}
+
+function getWidgetShellStyle(
+  mode: WidgetRuntimeMode,
+  placement: WidgetPlacement,
+): React.CSSProperties {
+  const style: React.CSSProperties = {
+    pointerEvents: "none",
+  };
+
+  if (mode === "preview") {
+    const { horizontal, vertical } = splitWidgetPlacement(placement);
+    Object.assign(style, {
+      position: "relative",
+      display: "flex",
+      width: "100%",
+      minHeight: "720px",
+      padding: "24px",
+      overflow: "hidden",
+      alignItems: vertical === "top" ? "flex-start" : "flex-end",
+      justifyContent:
+        horizontal === "left"
+          ? "flex-start"
+          : horizontal === "center"
+            ? "center"
+            : "flex-end",
+    });
+    return style;
+  }
+
+  Object.assign(style, {
+    position: "fixed",
+    zIndex: 2147483646,
+  });
+
+  switch (placement) {
+    case "top-left":
+      Object.assign(style, { left: "24px", top: "24px" });
+      break;
+    case "top-center":
+      Object.assign(style, { left: "50%", top: "24px", transform: "translateX(-50%)" });
+      break;
+    case "top-right":
+      Object.assign(style, { right: "24px", top: "24px" });
+      break;
+    case "bottom-left":
+      Object.assign(style, { left: "24px", bottom: "24px" });
+      break;
+    case "bottom-center":
+      Object.assign(style, { left: "50%", bottom: "24px", transform: "translateX(-50%)" });
+      break;
+    default:
+      Object.assign(style, { right: "24px", bottom: "24px" });
+      break;
+  }
+
+  return style;
+}

package/src/runtime/analytics.ts

@@ -0,0 +1,327 @@
+import type { WidgetSessionState } from "../types";
+import type {
+  WidgetAnalyticsBatchEvent,
+  WidgetAnalyticsBatchRequest,
+  WidgetClientAnalyticsEventType,
+  WidgetTriggerRuleType,
+} from "../shared/analytics";
+import { getWidgetApiBase } from "./api-origin";
+
+const ANALYTICS_ENDPOINT = "/api/widget/events/batch";
+const DEFAULT_BATCH_SIZE = 10;
+const DEFAULT_FLUSH_INTERVAL_MS = 2500;
+const UNIQUE_SCRIPT_LOADED_KEY_PREFIX =
+  "usereq-widget:unique-script-loaded:";
+
+type QueuedAnalyticsEvent = {
+  event: WidgetAnalyticsBatchEvent;
+  sessionToken: string;
+};
+
+export type WidgetAnalyticsTrackerOptions = {
+  mode: "embed" | "preview";
+  agentId: string;
+  getSession: () => WidgetSessionState | null;
+  getConversationId: () => string | undefined;
+  batchSize?: number;
+  flushIntervalMs?: number;
+};
+
+export class WidgetAnalyticsTracker {
+  private readonly mode: "embed" | "preview";
+  private readonly agentId: string;
+  private readonly getSession: () => WidgetSessionState | null;
+  private readonly getConversationId: () => string | undefined;
+  private readonly batchSize: number;
+  private readonly flushIntervalMs: number;
+  private readonly uniqueScriptSeen = new Set<string>();
+  private flushTimer: number | null = null;
+  private queue: QueuedAnalyticsEvent[] = [];
+  private disposed = false;
+
+  constructor(options: WidgetAnalyticsTrackerOptions) {
+    this.mode = options.mode;
+    this.agentId = options.agentId;
+    this.getSession = options.getSession;
+    this.getConversationId = options.getConversationId;
+    this.batchSize = Math.max(1, options.batchSize ?? DEFAULT_BATCH_SIZE);
+    this.flushIntervalMs = Math.max(
+      200,
+      options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS,
+    );
+
+    if (this.mode === "embed") {
+      window.addEventListener("pagehide", this.handlePageHide, {
+        capture: true,
+      });
+      document.addEventListener(
+        "visibilitychange",
+        this.handleVisibilityChange,
+        true,
+      );
+    }
+  }
+
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.clearFlushTimer();
+    window.removeEventListener("pagehide", this.handlePageHide, true);
+    document.removeEventListener(
+      "visibilitychange",
+      this.handleVisibilityChange,
+      true,
+    );
+    void this.flush({ transport: "beacon" });
+  }
+
+  trackScriptLoaded() {
+    this.track({ eventType: "SCRIPT_LOADED" });
+  }
+
+  trackUniqueScriptLoaded() {
+    const sessionToken = this.getSession()?.sessionToken?.trim();
+    if (!sessionToken) return;
+    const uniqueKey = `${this.agentId}:${sessionToken}`;
+
+    if (this.uniqueScriptSeen.has(uniqueKey)) return;
+    if (this.hasSessionUniqueScriptLoaded(uniqueKey)) {
+      this.uniqueScriptSeen.add(uniqueKey);
+      return;
+    }
+
+    this.uniqueScriptSeen.add(uniqueKey);
+    this.setSessionUniqueScriptLoaded(uniqueKey);
+    this.track({ eventType: "UNIQUE_SCRIPT_LOADED" });
+  }
+
+  trackView(triggerRuleType: WidgetTriggerRuleType | null) {
+    this.track({ eventType: "VIEW", triggerRuleType });
+    if (triggerRuleType === "element_displayed") {
+      this.track({
+        eventType: "DISPLAY_AFTER_ELEMENT_SHOWED",
+        triggerRuleType,
+      });
+    }
+  }
+
+  trackClick() {
+    this.track({ eventType: "CLICK" });
+  }
+
+  trackLinkClicked(linkUrl: string) {
+    const raw = linkUrl.trim();
+    if (!raw) return;
+    const resolvedUrl = this.normalizeLinkUrl(raw);
+    this.track({ eventType: "LINK_CLICKED", linkUrl: resolvedUrl });
+  }
+
+  track(event: Omit<WidgetAnalyticsBatchEvent, "occurredAt"> & {
+    occurredAt?: string;
+  }) {
+    if (this.disposed || this.mode !== "embed") return;
+
+    const sessionToken = this.getSession()?.sessionToken?.trim();
+    if (!sessionToken) return;
+
+    const { occurredAt, conversationId, triggerRuleType, linkUrl, ...rest } = event;
+    const resolvedConversationId = conversationId ?? this.getConversationId();
+    const queuedEvent: WidgetAnalyticsBatchEvent = {
+      ...rest,
+      occurredAt: occurredAt ?? new Date().toISOString(),
+      ...(resolvedConversationId ? { conversationId: resolvedConversationId } : {}),
+      ...(triggerRuleType ? { triggerRuleType } : {}),
+      ...(linkUrl ? { linkUrl } : {}),
+    };
+
+    this.queue.push({
+      event: queuedEvent,
+      sessionToken,
+    });
+
+    if (this.queue.length >= this.batchSize) {
+      void this.flush();
+      return;
+    }
+
+    this.scheduleFlush();
+  }
+
+  async flush(options?: {
+    transport?: "default" | "beacon";
+  }): Promise<void> {
+    if (this.disposed) return;
+    if (this.queue.length === 0) return;
+
+    this.clearFlushTimer();
+    const transport = options?.transport ?? "default";
+    const snapshot = this.queue;
+    this.queue = [];
+
+    const grouped = new Map<string, WidgetAnalyticsBatchEvent[]>();
+    for (const entry of snapshot) {
+      const group = grouped.get(entry.sessionToken);
+      if (group) {
+        group.push(entry.event);
+      } else {
+        grouped.set(entry.sessionToken, [entry.event]);
+      }
+    }
+
+    const failed: QueuedAnalyticsEvent[] = [];
+
+    for (const [sessionToken, events] of grouped.entries()) {
+      const sent = await this.sendBatch({
+        events,
+        sessionToken,
+        transport,
+      });
+
+      if (!sent) {
+        for (const event of events) {
+          failed.push({ event, sessionToken });
+        }
+      }
+    }
+
+    if (failed.length > 0) {
+      this.queue = [...failed, ...this.queue];
+      this.scheduleFlush();
+    }
+  }
+
+  private async sendBatch(input: {
+    events: WidgetAnalyticsBatchEvent[];
+    sessionToken: string;
+    transport: "default" | "beacon";
+  }): Promise<boolean> {
+    if (input.events.length === 0) return true;
+
+    const url = new URL(ANALYTICS_ENDPOINT, `${getWidgetApiBase()}/`).toString();
+    const sanitizedEvents = input.events.map((event) => {
+      const { conversationId, triggerRuleType, linkUrl, ...rest } = event;
+      return {
+        ...rest,
+        ...(conversationId ? { conversationId } : {}),
+        ...(triggerRuleType ? { triggerRuleType } : {}),
+        ...(linkUrl ? { linkUrl } : {}),
+      };
+    });
+    const payload: WidgetAnalyticsBatchRequest = {
+      events: sanitizedEvents,
+      pageUrl: window.location.href,
+      referrer: document.referrer || undefined,
+      // sendBeacon cannot set Authorization header, so include token in body as fallback.
+      sessionToken: input.sessionToken,
+    };
+
+    if (input.transport === "beacon" && typeof navigator.sendBeacon === "function") {
+      const body = new Blob([JSON.stringify(payload)], {
+        type: "application/json",
+      });
+      if (navigator.sendBeacon(url, body)) {
+        return true;
+      }
+    }
+
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${input.sessionToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+        credentials: "omit",
+        keepalive: input.transport === "beacon",
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  private scheduleFlush() {
+    if (this.flushTimer != null) return;
+    this.flushTimer = window.setTimeout(() => {
+      this.flushTimer = null;
+      void this.flush();
+    }, this.flushIntervalMs);
+  }
+
+  private clearFlushTimer() {
+    if (this.flushTimer == null) return;
+    window.clearTimeout(this.flushTimer);
+    this.flushTimer = null;
+  }
+
+  private hasSessionUniqueScriptLoaded(uniqueKey: string): boolean {
+    try {
+      return (
+        sessionStorage.getItem(`${UNIQUE_SCRIPT_LOADED_KEY_PREFIX}${uniqueKey}`) ===
+        "1"
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  private setSessionUniqueScriptLoaded(uniqueKey: string) {
+    try {
+      sessionStorage.setItem(
+        `${UNIQUE_SCRIPT_LOADED_KEY_PREFIX}${uniqueKey}`,
+        "1",
+      );
+    } catch {
+      // no-op
+    }
+  }
+
+  private readonly handlePageHide = () => {
+    void this.flush({ transport: "beacon" });
+  };
+
+  private readonly handleVisibilityChange = () => {
+    if (document.visibilityState === "hidden") {
+      void this.flush({ transport: "beacon" });
+    }
+  };
+
+  private normalizeLinkUrl(value: string): string {
+    try {
+      return new URL(value, window.location.href).toString();
+    } catch {
+      return value;
+    }
+  }
+}
+
+export function createWidgetAnalyticsTracker(
+  options: WidgetAnalyticsTrackerOptions,
+): WidgetAnalyticsTracker {
+  return new WidgetAnalyticsTracker(options);
+}
+
+export function isWidgetTriggerRuleType(
+  value: string | null | undefined,
+): value is WidgetTriggerRuleType {
+  return (
+    value === "time_delay" ||
+    value === "scroll_to_bottom" ||
+    value === "element_clicked" ||
+    value === "element_displayed"
+  );
+}
+
+export function isWidgetClientAnalyticsEventType(
+  value: string | null | undefined,
+): value is WidgetClientAnalyticsEventType {
+  return (
+    value === "SCRIPT_LOADED" ||
+    value === "UNIQUE_SCRIPT_LOADED" ||
+    value === "VIEW" ||
+    value === "CLICK" ||
+    value === "DISPLAY_AFTER_ELEMENT_SHOWED" ||
+    value === "LINK_CLICKED"
+  );
+}

package/src/runtime/api-origin.ts

@@ -0,0 +1,29 @@
+declare const __USEREQ_WIDGET_API_BASE__:
+  | string
+  | undefined;
+
+type WidgetRuntimeGlobal = typeof globalThis & {
+  __USEREQ_WIDGET_API_BASE__?: string;
+};
+
+function normalizeApiBase(value: string | undefined): string | null {
+  const trimmed = value?.trim();
+  if (!trimmed) return null;
+
+  return trimmed.replace(/\/+$/, "");
+}
+
+export function getWidgetApiBase(): string {
+  const compileTimeApiBase =
+    typeof __USEREQ_WIDGET_API_BASE__ !== "undefined"
+      ? __USEREQ_WIDGET_API_BASE__
+      : undefined;
+  const runtimeApiBase = (globalThis as WidgetRuntimeGlobal)
+    .__USEREQ_WIDGET_API_BASE__;
+
+  return (
+    normalizeApiBase(compileTimeApiBase) ??
+    normalizeApiBase(runtimeApiBase) ??
+    "http://localhost:4000"
+  );
+}

package/src/runtime/api.ts

@@ -0,0 +1,151 @@
+import type {
+  WidgetAnalyticsBatchRequest,
+  WidgetConversation,
+  WidgetMessage,
+  WidgetPublicChatSendChatResponse,
+  WidgetPublicChatSendStopConfirmationResponse,
+  WidgetSessionConfig,
+} from "../types";
+import { getWidgetApiBase } from "./api-origin";
+
+async function requestJson<T>(path: string, init: RequestInit): Promise<T> {
+  const response = await fetch(new URL(path, `${getWidgetApiBase()}/`).toString(), {
+    ...init,
+    headers: {
+      "Content-Type": "application/json",
+      ...(init.headers ?? {}),
+    },
+    credentials: "omit",
+  });
+
+  const text = await response.text();
+  const payload = text ? JSON.parse(text) : null;
+  if (!response.ok) {
+    throw new Error(
+      typeof payload === "object" && payload && "error" in payload
+        ? String((payload as { error?: string }).error ?? response.statusText)
+        : response.statusText
+    );
+  }
+
+  return payload as T;
+}
+
+export async function mintWidgetSession(input: {
+  agentId: string;
+  origin: string;
+  pageUrl?: string;
+  referrer?: string;
+}): Promise<WidgetSessionConfig> {
+  return requestJson<WidgetSessionConfig>("/api/widget/sessions", {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+export async function startPublicChat(input: {
+  agentId: string;
+  sessionToken: string;
+}): Promise<{
+  conversation: WidgetConversation;
+  welcomeMessage: WidgetMessage;
+}> {
+  return requestJson("/api/conversations/public/start", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${input.sessionToken}` },
+    body: JSON.stringify({ agentId: input.agentId }),
+  });
+}
+
+export async function sendPublicChatMessage(input: {
+  conversationId: string;
+  sessionToken: string;
+  content: string;
+}): Promise<WidgetPublicChatSendChatResponse> {
+  return requestJson(
+    `/api/conversations/public/${encodeURIComponent(input.conversationId)}/messages`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${input.sessionToken}` },
+      body: JSON.stringify({
+        content: input.content,
+      }),
+    }
+  );
+}
+
+export async function sendPublicChatConfirmation(input: {
+  conversationId: string;
+  sessionToken: string;
+  content: string;
+}): Promise<WidgetPublicChatSendStopConfirmationResponse> {
+  return requestJson(
+    `/api/conversations/public/${encodeURIComponent(input.conversationId)}/messages`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${input.sessionToken}` },
+      body: JSON.stringify({
+        content: input.content,
+      }),
+    }
+  );
+}
+
+export async function sendWidgetAnalyticsBatch(
+  input: WidgetAnalyticsBatchRequest,
+): Promise<void> {
+  const response = await fetch(
+    new URL("/api/widget/events/batch", `${getWidgetApiBase()}/`).toString(),
+    {
+      method: "POST",
+      headers: input.sessionToken
+        ? { Authorization: `Bearer ${input.sessionToken}` }
+        : undefined,
+      body: JSON.stringify(input),
+      credentials: "omit",
+      keepalive: true,
+    },
+  );
+
+  if (!response.ok) {
+    const text = await response.text();
+    const payload = text ? JSON.parse(text) : null;
+    throw new Error(
+      typeof payload === "object" && payload && "error" in payload
+        ? String((payload as { error?: string }).error ?? response.statusText)
+        : response.statusText,
+    );
+  }
+}
+
+export async function getCurrentConversation(sessionToken: string): Promise<{
+  conversation: WidgetConversation | null;
+}> {
+  return requestJson<{ conversation: WidgetConversation | null }>(
+    "/api/conversations/public/current",
+    {
+      method: "GET",
+      headers: { Authorization: `Bearer ${sessionToken}` },
+    }
+  );
+}
+
+export async function listConversationMessages(input: {
+  conversationId: string;
+  sessionToken: string;
+  cursor?: string | null;
+}): Promise<{
+  data: WidgetMessage[];
+  nextCursor: string | null;
+  hasMore: boolean;
+}> {
+  const params = new URLSearchParams();
+  if (input.cursor) params.set("cursor", input.cursor);
+  return requestJson(
+    `/api/conversations/public/${encodeURIComponent(input.conversationId)}/messages?${params.toString()}`,
+    {
+      method: "GET",
+      headers: { Authorization: `Bearer ${input.sessionToken}` },
+    }
+  );
+}