@usereq/widget 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usereq/widget",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/custom-element/agent-widget-element.tsx

@@ -19,7 +19,6 @@ import { widgetTriggerRuleKey } from "../shared/widget-config";
 import { WidgetRuntime, type WidgetRuntimeStatus } from "../renderer/index";
 import { buildAssistantMessageRevealSteps } from "../chat-widget";
 import { DEFAULT_STOP_CONVERSATION_PROMPT } from "../shared/stop-confirmation";
-import type { WidgetTriggerRuleType } from "../shared/analytics";
 import {
   bootstrapWidget,
   resetWidgetSession,
@@ -27,10 +26,6 @@ import {
   startWidgetConversation,
   submitWidgetMessage,
 } from "../runtime/bootstrap";
-import {
-  createWidgetAnalyticsTracker,
-  type WidgetAnalyticsTracker,
-} from "../runtime/analytics";
 import { getWidgetShadowCss } from "../shared/shadow-css";
 import { WIDGET_SHADOW_THEME_CSS } from "../shared/shadow-theme";
 
@@ -72,8 +67,7 @@ export class AgentWidgetElement extends HTMLElement {
   private sendVersion = 0;
   private confirmationVersion = 0;
   private bootstrapPhase: "idle" | "booting" | "ready" | "blocked" = "idle";
-  private analyticsTrackerKey = "";
-  private analyticsTracker: WidgetAnalyticsTracker | null = null;
+  private autoStartTriggered = false;
 
   constructor() {
     super();
@@ -109,7 +103,6 @@ export class AgentWidgetElement extends HTMLElement {
 
   connectedCallback() {
     this.syncAttributes();
-    this.recreateAnalyticsTracker();
     this.renderWidget();
     if (this.agentId) {
       void this.ensureBootstrap();
@@ -118,9 +111,6 @@ export class AgentWidgetElement extends HTMLElement {
 
   disconnectedCallback() {
     this.bootstrapPromise = null;
-    this.analyticsTracker?.dispose();
-    this.analyticsTracker = null;
-    this.analyticsTrackerKey = "";
     this.root.unmount();
   }
 
@@ -130,7 +120,6 @@ export class AgentWidgetElement extends HTMLElement {
     newValue?: string | null,
   ) {
     this.syncAttributes();
-    this.recreateAnalyticsTracker();
     if (name === "agent-id" && oldValue !== newValue) {
       this.clearAgentState();
     }
@@ -216,22 +205,6 @@ export class AgentWidgetElement extends HTMLElement {
     this.status = "idle";
   }
 
-  private recreateAnalyticsTracker() {
-    const nextKey = `${this.mode}:${this.agentId}`;
-    if (nextKey === this.analyticsTrackerKey) {
-      return;
-    }
-
-    this.analyticsTracker?.dispose();
-    this.analyticsTracker = createWidgetAnalyticsTracker({
-      mode: this.mode,
-      agentId: this.agentId,
-      getSession: () => this.sessionState,
-      getConversationId: () => this.sessionState?.conversationId,
-    });
-    this.analyticsTrackerKey = nextKey;
-  }
-
   private renderWidget() {
     if (
       this.bootstrapPhase !== "ready" ||
@@ -246,14 +219,31 @@ export class AgentWidgetElement extends HTMLElement {
     const placement = this.getResolvedPlacement();
     const variant = this.getResolvedVariant();
     const preset = this.getResolvedPreset();
-    const emptyAction =
+    const autoStartEnabled =
+      this.sessionConfig?.widgetConfig.widgetBehavior?.autoStart === true;
+    const awaitingConversation =
       this.status === "booting" ||
-      (this.sessionState != null && !this.sessionState.conversationId)
+      (this.sessionState != null && !this.sessionState.conversationId);
+    // When auto-start is on we never render the manual CTA — except as a
+    // fallback if the auto-start attempt errored, so the visitor isn't
+    // stranded on a blank panel.
+    const showFallbackCta = autoStartEnabled && this.status === "error";
+    const emptyAction =
+      !autoStartEnabled && awaitingConversation
         ? {
             label: DEFAULT_START_CONVERSATION_LABEL,
             onClick: () => void this.handleStartConversation(),
             disabled: this.status !== "ready",
           }
+        : showFallbackCta
+        ? {
+            label: DEFAULT_START_CONVERSATION_LABEL,
+            onClick: () => {
+              this.autoStartTriggered = false;
+              void this.handleStartConversation();
+            },
+            disabled: false,
+          }
         : undefined;
 
     this.root.render(
@@ -287,10 +277,6 @@ export class AgentWidgetElement extends HTMLElement {
         onSendMessage: (content: string) => void this.sendMessage(content),
         onConfirmationDecision: (confirmationId: string, accepted: boolean) =>
           void this.handleConfirmationDecision(confirmationId, accepted),
-        onWidgetVisible: (triggerRuleType: WidgetTriggerRuleType | null) =>
-          this.analyticsTracker?.trackView(triggerRuleType),
-        onLinkClick: (linkUrl: string) =>
-          this.analyticsTracker?.trackLinkClicked(linkUrl),
         portalContainer: this.shadowRootRef,
       }),
     );
@@ -337,10 +323,6 @@ export class AgentWidgetElement extends HTMLElement {
         this.welcomeMessage = state.session.widgetConfig.welcomeMessage;
         this.status = "ready";
         this.bootstrapPhase = "ready";
-        if (this.mode === "embed") {
-          this.analyticsTracker?.trackScriptLoaded();
-          this.analyticsTracker?.trackUniqueScriptLoaded();
-        }
         this.renderWidget();
       } catch (error) {
         if (runVersion !== this.bootstrapVersion) {
@@ -443,16 +425,33 @@ export class AgentWidgetElement extends HTMLElement {
   }
 
   private async handleOpenChange(nextOpen: boolean) {
-    const wasOpen = this.open;
     this.open = nextOpen;
     this.renderWidget();
-    if (!wasOpen && nextOpen && this.mode === "embed") {
-      this.analyticsTracker?.trackClick();
-    }
 
     if (this.open && (this.status === "idle" || !this.sessionState)) {
       await this.ensureBootstrap();
     }
+
+    this.maybeAutoStartConversation();
+  }
+
+  /**
+   * Auto-start opt-in: when the agent has `widgetBehavior.autoStart`
+   * enabled, the first time the visitor opens the launcher we transparently
+   * call /conversations/public/start so they skip the empty state. Fires
+   * once per element lifetime; subsequent opens reuse the existing
+   * conversation via the standard sessionStorage rehydrate.
+   */
+  private maybeAutoStartConversation() {
+    if (this.autoStartTriggered) return;
+    if (!this.open) return;
+    if (this.status !== "ready") return;
+    if (!this.sessionConfig) return;
+    if (!this.sessionConfig.widgetConfig.widgetBehavior?.autoStart) return;
+    if (this.sessionState?.conversationId) return;
+
+    this.autoStartTriggered = true;
+    void this.handleStartConversation();
   }
 
   private async handleStartConversation() {

package/src/index.ts

@@ -1,5 +1,4 @@
 export * from "./shared/widget-config";
-export * from "./shared/analytics";
 export * from "./renderer/index";
 export * from "./types";
 export * from "./shared/shadow-css";

package/src/renderer/widget-runtime.tsx

@@ -27,7 +27,6 @@ import {
 } 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";
 
@@ -64,8 +63,6 @@ export type WidgetRuntimeProps = {
     accepted: boolean,
   ) => void | Promise<void>;
   portalContainer?: HTMLElement | DocumentFragment | null;
-  onWidgetVisible?: (triggerRuleType: WidgetTriggerRuleType | null) => void;
-  onLinkClick?: (linkUrl: string) => void;
   onLauncherClick?: () => void;
 };
 
@@ -100,21 +97,10 @@ export function WidgetRuntime({
   onStopConversation,
   onConfirmationDecision,
   portalContainer,
-  onWidgetVisible,
-  onLinkClick,
   onLauncherClick,
 }: WidgetRuntimeProps) {
   const { ready } = useWidgetTriggerGate(triggerRule);
   const { horizontal, vertical } = splitWidgetPlacement(placement);
-  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]);
 
   const { panelMessages, confirmation } = React.useMemo(
     () => splitConfirmationFromMessages(messages, onConfirmationDecision),
@@ -219,7 +205,6 @@ export function WidgetRuntime({
                 onStopConversation ? handleStop : undefined
               }
               onLauncherClick={onLauncherClick}
-              onLinkClick={onLinkClick}
               emptyAction={wrappedEmptyAction}
               confirmation={confirmation}
               portalContainer={portalEl}

package/src/runtime/api.ts

@@ -1,5 +1,4 @@
 import type {
-  WidgetAnalyticsBatchRequest,
   WidgetConversation,
   WidgetMessage,
   WidgetPublicChatSendChatResponse,
@@ -91,33 +90,6 @@ export async function sendPublicChatConfirmation(input: {
   );
 }
 
-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;
 }> {

package/src/shared/widget-config.ts

@@ -29,6 +29,22 @@ export type WidgetTriggerRule =
   | { triggerRuleType: "element_clicked"; elementClicked: string }
   | { triggerRuleType: "element_displayed"; elementDisplayed: string };
 
+export type WidgetBehavior = {
+  autoStart: boolean;
+};
+
+export const DEFAULT_WIDGET_BEHAVIOR: WidgetBehavior = {
+  autoStart: false,
+};
+
+export function normalizeWidgetBehavior(
+  behavior: Partial<WidgetBehavior> | null | undefined,
+): WidgetBehavior {
+  return {
+    autoStart: Boolean(behavior?.autoStart),
+  };
+}
+
 export function widgetTriggerRuleKey(
   rule: WidgetTriggerRule | null | undefined,
 ): string {

package/src/types.ts

@@ -1,5 +1,6 @@
 import type {
   WidgetAppearance,
+  WidgetBehavior,
   WidgetPlacement,
   WidgetPreset,
   WidgetVariant,
@@ -8,12 +9,15 @@ import type {
 
 export {
   DEFAULT_WIDGET_APPEARANCE,
+  DEFAULT_WIDGET_BEHAVIOR,
   DEFAULT_WIDGET_PRESET,
   type WidgetAppearance,
+  type WidgetBehavior,
   type WidgetPlacement,
   type WidgetPreset,
   type WidgetVariant,
   normalizeWidgetAppearance,
+  normalizeWidgetBehavior,
   normalizeWidgetPlacement,
   normalizeWidgetPreset,
   normalizeWidgetVariant,
@@ -21,14 +25,6 @@ export {
   widgetAppearanceToAttributes,
   type WidgetTriggerRule,
 } from "./shared/widget-config";
-export type {
-  WidgetAnalyticsBatchEvent,
-  WidgetAnalyticsBatchRequest,
-  WidgetAnalyticsBatchResponse,
-  WidgetAnalyticsEventType,
-  WidgetClientAnalyticsEventType,
-  WidgetTriggerRuleType,
-} from "./shared/analytics";
 
 export type WidgetSessionConfig = {
   sessionToken: string;
@@ -40,6 +36,7 @@ export type WidgetSessionConfig = {
     welcomeMessage: string | null;
     spotlightMessages: string[];
     widgetAppearance: WidgetAppearance;
+    widgetBehavior: WidgetBehavior;
     widgetVariant: WidgetVariant;
     widgetPreset: WidgetPreset;
     widgetPlacement: WidgetPlacement;