@usereq/widget 0.1.2 → 0.1.4

package/src/runtime/analytics.ts

@@ -10,14 +10,54 @@ import { getWidgetApiBase } from "./api-origin";
 const ANALYTICS_ENDPOINT = "/api/widget/events/batch";
 const DEFAULT_BATCH_SIZE = 10;
 const DEFAULT_FLUSH_INTERVAL_MS = 2500;
+const MAX_FLUSH_INTERVAL_MS = 120_000;
+const MAX_QUEUE_SIZE = 200;
+const MAX_EVENT_ATTEMPTS = 5;
+const MAX_EVENT_AGE_MS = 10 * 60 * 1000;
 const UNIQUE_SCRIPT_LOADED_KEY_PREFIX =
   "usereq-widget:unique-script-loaded:";
 
 type QueuedAnalyticsEvent = {
   event: WidgetAnalyticsBatchEvent;
   sessionToken: string;
+  attempts: number;
+  enqueuedAt: number;
 };
 
+type SendOutcome =
+  | { outcome: "ok" }
+  | { outcome: "drop" }
+  | { outcome: "retry"; retryAfterMs?: number };
+
+function parseRetryAfter(headerValue: string | null): number | undefined {
+  if (!headerValue) return undefined;
+  const trimmed = headerValue.trim();
+  if (!trimmed) return undefined;
+  const seconds = Number(trimmed);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.min(MAX_FLUSH_INTERVAL_MS, seconds * 1000);
+  }
+  const dateMs = Date.parse(trimmed);
+  if (!Number.isNaN(dateMs)) {
+    const delta = dateMs - Date.now();
+    if (delta > 0) return Math.min(MAX_FLUSH_INTERVAL_MS, delta);
+  }
+  return undefined;
+}
+
+function classifyResponse(response: Response): SendOutcome {
+  if (response.ok) return { outcome: "ok" };
+  const status = response.status;
+  if (status === 408 || status === 425 || status === 429 || status >= 500) {
+    return {
+      outcome: "retry",
+      retryAfterMs: parseRetryAfter(response.headers.get("retry-after")),
+    };
+  }
+  if (status >= 400 && status < 500) return { outcome: "drop" };
+  return { outcome: "retry" };
+}
+
 export type WidgetAnalyticsTrackerOptions = {
   mode: "embed" | "preview";
   agentId: string;
@@ -38,6 +78,8 @@ export class WidgetAnalyticsTracker {
   private flushTimer: number | null = null;
   private queue: QueuedAnalyticsEvent[] = [];
   private disposed = false;
+  private consecutiveFailures = 0;
+  private nextAllowedFlushAt = 0;
 
   constructor(options: WidgetAnalyticsTrackerOptions) {
     this.mode = options.mode;
@@ -134,9 +176,11 @@ export class WidgetAnalyticsTracker {
       ...(linkUrl ? { linkUrl } : {}),
     };
 
-    this.queue.push({
+    this.enqueue({
       event: queuedEvent,
       sessionToken,
+      attempts: 0,
+      enqueuedAt: Date.now(),
     });
 
     if (this.queue.length >= this.batchSize) {
@@ -147,55 +191,108 @@ export class WidgetAnalyticsTracker {
     this.scheduleFlush();
   }
 
+  private enqueue(entry: QueuedAnalyticsEvent) {
+    this.queue.push(entry);
+    if (this.queue.length > MAX_QUEUE_SIZE) {
+      this.queue.splice(0, this.queue.length - MAX_QUEUE_SIZE);
+    }
+  }
+
+  private pruneStale(now: number) {
+    if (this.queue.length === 0) return;
+    this.queue = this.queue.filter(
+      (entry) => now - entry.enqueuedAt < MAX_EVENT_AGE_MS,
+    );
+  }
+
   async flush(options?: {
     transport?: "default" | "beacon";
   }): Promise<void> {
     if (this.disposed) return;
-    if (this.queue.length === 0) return;
+
+    const now = Date.now();
+    this.pruneStale(now);
+    if (this.queue.length === 0) {
+      this.clearFlushTimer();
+      return;
+    }
 
     this.clearFlushTimer();
     const transport = options?.transport ?? "default";
     const snapshot = this.queue;
     this.queue = [];
 
-    const grouped = new Map<string, WidgetAnalyticsBatchEvent[]>();
+    const grouped = new Map<string, QueuedAnalyticsEvent[]>();
     for (const entry of snapshot) {
       const group = grouped.get(entry.sessionToken);
       if (group) {
-        group.push(entry.event);
+        group.push(entry);
       } else {
-        grouped.set(entry.sessionToken, [entry.event]);
+        grouped.set(entry.sessionToken, [entry]);
       }
     }
 
     const failed: QueuedAnalyticsEvent[] = [];
+    let maxRetryAfterMs = 0;
+    let anyRetry = false;
+    let anySuccess = false;
 
-    for (const [sessionToken, events] of grouped.entries()) {
-      const sent = await this.sendBatch({
-        events,
+    for (const [sessionToken, entries] of grouped.entries()) {
+      const result = await this.sendBatch({
+        events: entries.map((entry) => entry.event),
         sessionToken,
         transport,
       });
 
-      if (!sent) {
-        for (const event of events) {
-          failed.push({ event, sessionToken });
-        }
+      if (result.outcome === "ok") {
+        anySuccess = true;
+        continue;
+      }
+      if (result.outcome === "drop") {
+        continue;
+      }
+      anyRetry = true;
+      if (result.retryAfterMs && result.retryAfterMs > maxRetryAfterMs) {
+        maxRetryAfterMs = result.retryAfterMs;
       }
+      for (const entry of entries) {
+        const attempts = entry.attempts + 1;
+        if (attempts >= MAX_EVENT_ATTEMPTS) continue;
+        failed.push({ ...entry, attempts });
+      }
+    }
+
+    if (anySuccess && !anyRetry) {
+      this.consecutiveFailures = 0;
+      this.nextAllowedFlushAt = 0;
+    } else if (anyRetry) {
+      this.consecutiveFailures += 1;
     }
 
     if (failed.length > 0) {
-      this.queue = [...failed, ...this.queue];
-      this.scheduleFlush();
+      for (const entry of failed) {
+        this.enqueue(entry);
+      }
+      const backoff = this.computeBackoffDelay();
+      const delay = Math.max(backoff, maxRetryAfterMs);
+      this.nextAllowedFlushAt = Date.now() + delay;
+      this.scheduleFlush(delay);
     }
   }
 
+  private computeBackoffDelay(): number {
+    const exponent = Math.max(0, this.consecutiveFailures - 1);
+    const base = this.flushIntervalMs * Math.pow(2, exponent);
+    const jitter = base * 0.2 * Math.random();
+    return Math.min(MAX_FLUSH_INTERVAL_MS, base + jitter);
+  }
+
   private async sendBatch(input: {
     events: WidgetAnalyticsBatchEvent[];
     sessionToken: string;
     transport: "default" | "beacon";
-  }): Promise<boolean> {
-    if (input.events.length === 0) return true;
+  }): Promise<SendOutcome> {
+    if (input.events.length === 0) return { outcome: "ok" };
 
     const url = new URL(ANALYTICS_ENDPOINT, `${getWidgetApiBase()}/`).toString();
     const sanitizedEvents = input.events.map((event) => {
@@ -220,7 +317,7 @@ export class WidgetAnalyticsTracker {
         type: "application/json",
       });
       if (navigator.sendBeacon(url, body)) {
-        return true;
+        return { outcome: "ok" };
       }
     }
 
@@ -235,18 +332,19 @@ export class WidgetAnalyticsTracker {
         credentials: "omit",
         keepalive: input.transport === "beacon",
       });
-      return response.ok;
+      return classifyResponse(response);
     } catch {
-      return false;
+      return { outcome: "retry" };
     }
   }
 
-  private scheduleFlush() {
+  private scheduleFlush(delayMs?: number) {
     if (this.flushTimer != null) return;
+    const delay = Math.max(0, delayMs ?? this.flushIntervalMs);
     this.flushTimer = window.setTimeout(() => {
       this.flushTimer = null;
       void this.flush();
-    }, this.flushIntervalMs);
+    }, delay);
   }
 
   private clearFlushTimer() {

package/src/shared/widget-config.ts

@@ -14,6 +14,10 @@ export type WidgetPlacement =
 
 export type WidgetVariant = "default" | "chatbar" | "box";
 
+export type WidgetPreset = "default" | "facebook_messenger";
+
+export const DEFAULT_WIDGET_PRESET: WidgetPreset = "default";
+
 export type WidgetAppearance = ResolvedChatWidgetAppearance;
 
 export const DEFAULT_WIDGET_APPEARANCE: WidgetAppearance =
@@ -64,6 +68,20 @@ export function widgetAppearanceToAttributes(
   ];
 }
 
+export function normalizeWidgetPreset(
+  value: string | null | undefined,
+): WidgetPreset {
+  switch (value) {
+    case "facebook_messenger":
+    case "facebook-messenger":
+      return "facebook_messenger";
+    case "default":
+      return "default";
+    default:
+      return DEFAULT_WIDGET_PRESET;
+  }
+}
+
 export function normalizeWidgetVariant(
   value: string | null | undefined,
 ): WidgetVariant {

package/src/types.ts

@@ -1,17 +1,21 @@
 import type {
   WidgetAppearance,
   WidgetPlacement,
+  WidgetPreset,
   WidgetVariant,
   WidgetTriggerRule,
 } from "./shared/widget-config";
 
 export {
   DEFAULT_WIDGET_APPEARANCE,
+  DEFAULT_WIDGET_PRESET,
   type WidgetAppearance,
   type WidgetPlacement,
+  type WidgetPreset,
   type WidgetVariant,
   normalizeWidgetAppearance,
   normalizeWidgetPlacement,
+  normalizeWidgetPreset,
   normalizeWidgetVariant,
   splitWidgetPlacement,
   widgetAppearanceToAttributes,
@@ -37,6 +41,7 @@ export type WidgetSessionConfig = {
     spotlightMessages: string[];
     widgetAppearance: WidgetAppearance;
     widgetVariant: WidgetVariant;
+    widgetPreset: WidgetPreset;
     widgetPlacement: WidgetPlacement;
     allowedDomains: string[];
     triggerRule: WidgetTriggerRule | null;