@usereq/widget 0.2.2 → 0.2.4

package/src/runtime/analytics.ts

@@ -1,431 +0,0 @@
-import type { WidgetSessionState } from "../types";
-import type {
-  WidgetAnalyticsBatchEvent,
-  WidgetAnalyticsBatchRequest,
-  WidgetClientAnalyticsEventType,
-  WidgetTriggerRuleType,
-} from "../shared/analytics";
-import { getWidgetApiBase } from "./api-origin";
-
-const ANALYTICS_ENABLED = false;
-
-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;
-  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;
-  private consecutiveFailures = 0;
-  private nextAllowedFlushAt = 0;
-
-  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 (ANALYTICS_ENABLED && 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();
-    if (!ANALYTICS_ENABLED) return;
-    window.removeEventListener("pagehide", this.handlePageHide, true);
-    document.removeEventListener(
-      "visibilitychange",
-      this.handleVisibilityChange,
-      true,
-    );
-    void this.flush({ transport: "beacon" });
-  }
-
-  trackScriptLoaded() {
-    this.track({ eventType: "SCRIPT_LOADED" });
-  }
-
-  trackUniqueScriptLoaded() {
-    if (!ANALYTICS_ENABLED) return;
-    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 (!ANALYTICS_ENABLED) return;
-    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.enqueue({
-      event: queuedEvent,
-      sessionToken,
-      attempts: 0,
-      enqueuedAt: Date.now(),
-    });
-
-    if (this.queue.length >= this.batchSize) {
-      void this.flush();
-      return;
-    }
-
-    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 (!ANALYTICS_ENABLED) return;
-    if (this.disposed) 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, QueuedAnalyticsEvent[]>();
-    for (const entry of snapshot) {
-      const group = grouped.get(entry.sessionToken);
-      if (group) {
-        group.push(entry);
-      } else {
-        grouped.set(entry.sessionToken, [entry]);
-      }
-    }
-
-    const failed: QueuedAnalyticsEvent[] = [];
-    let maxRetryAfterMs = 0;
-    let anyRetry = false;
-    let anySuccess = false;
-
-    for (const [sessionToken, entries] of grouped.entries()) {
-      const result = await this.sendBatch({
-        events: entries.map((entry) => entry.event),
-        sessionToken,
-        transport,
-      });
-
-      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) {
-      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<SendOutcome> {
-    if (input.events.length === 0) return { outcome: "ok" };
-
-    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 { outcome: "ok" };
-      }
-    }
-
-    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 classifyResponse(response);
-    } catch {
-      return { outcome: "retry" };
-    }
-  }
-
-  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();
-    }, delay);
-  }
-
-  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/token-renewal.ts

@@ -1,13 +0,0 @@
-export function scheduleRenewal(
-  expiresAt: string,
-  onRenew: () => Promise<void> | void
-): () => void {
-  const expiryMs = new Date(expiresAt).getTime();
-  const delay = Math.max(5_000, expiryMs - Date.now() - 60_000);
-  const timer = window.setTimeout(() => {
-    void onRenew();
-  }, delay);
-
-  return () => window.clearTimeout(timer);
-}
-

package/src/shared/analytics.ts

@@ -1,54 +0,0 @@
-export const WIDGET_ANALYTICS_EVENT_TYPES = [
-  "SCRIPT_LOADED",
-  "UNIQUE_SCRIPT_LOADED",
-  "VIEW",
-  "CLICK",
-  "SESSION_START",
-  "DISPLAY_AFTER_ELEMENT_SHOWED",
-  "WIDGET_DISPLAY_AFTER_VSL_SHOWED",
-  "LINK_CLICKED",
-] as const;
-
-export type WidgetAnalyticsEventType =
-  (typeof WIDGET_ANALYTICS_EVENT_TYPES)[number];
-
-export const WIDGET_CLIENT_ANALYTICS_EVENT_TYPES = [
-  "SCRIPT_LOADED",
-  "UNIQUE_SCRIPT_LOADED",
-  "VIEW",
-  "CLICK",
-  "DISPLAY_AFTER_ELEMENT_SHOWED",
-  "LINK_CLICKED",
-] as const;
-
-export type WidgetClientAnalyticsEventType =
-  (typeof WIDGET_CLIENT_ANALYTICS_EVENT_TYPES)[number];
-
-export const WIDGET_TRIGGER_RULE_TYPES = [
-  "time_delay",
-  "scroll_to_bottom",
-  "element_clicked",
-  "element_displayed",
-] as const;
-
-export type WidgetTriggerRuleType = (typeof WIDGET_TRIGGER_RULE_TYPES)[number];
-
-export type WidgetAnalyticsBatchEvent = {
-  eventType: WidgetClientAnalyticsEventType;
-  occurredAt?: string;
-  conversationId?: string | null;
-  triggerRuleType?: WidgetTriggerRuleType | null;
-  linkUrl?: string | null;
-};
-
-export type WidgetAnalyticsBatchRequest = {
-  events: WidgetAnalyticsBatchEvent[];
-  pageUrl?: string;
-  referrer?: string;
-  sessionToken?: string;
-};
-
-export type WidgetAnalyticsBatchResponse = {
-  accepted: number;
-};
-