@usereq/widget 0.2.2 → 0.2.3

package/package.json

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

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

@@ -74,6 +74,7 @@ export class AgentWidgetElement extends HTMLElement {
   private bootstrapPhase: "idle" | "booting" | "ready" | "blocked" = "idle";
   private analyticsTrackerKey = "";
   private analyticsTracker: WidgetAnalyticsTracker | null = null;
+  private autoStartTriggered = false;
 
   constructor() {
     super();
@@ -246,14 +247,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(
@@ -453,6 +471,27 @@ export class AgentWidgetElement extends HTMLElement {
     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/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,
@@ -40,6 +44,7 @@ export type WidgetSessionConfig = {
     welcomeMessage: string | null;
     spotlightMessages: string[];
     widgetAppearance: WidgetAppearance;
+    widgetBehavior: WidgetBehavior;
     widgetVariant: WidgetVariant;
     widgetPreset: WidgetPreset;
     widgetPlacement: WidgetPlacement;