@repzo/widget-react-native 1.3.1 → 1.5.0

package/src/state/user-update-queue.ts

@@ -0,0 +1,178 @@
+/**
+ * Paces `updateUser()` the way Intercom paces its web `update` (20 calls per
+ * 30 minutes), so a host that calls it on a timer or on every GPS fix can't
+ * flood Workstation.
+ *
+ * - Values that match what Workstation already has are not sent again.
+ * - Up to `burst` sends go out straight away; after that one more is allowed
+ *   every `windowMs / burst` (90 s by default).
+ * - While a send is in flight, rate limited or out of budget, new values wait
+ *   and merge into one bag, newest value per key. Nothing is lost: the latest
+ *   of every key goes out on the next allowed send. Workstation merges the bag
+ *   into the saved attributes per key, so sending only what changed is enough.
+ * - A 429 holds sends until its `Retry-After`. A failed connection or a 5xx
+ *   keeps the values and tries again later.
+ */
+
+import { RepzoWidgetError } from '../api/client';
+import type { WidgetCustomAttributes } from '../types';
+
+export const USER_UPDATE_BURST = 20;
+export const USER_UPDATE_WINDOW_MS = 30 * 60 * 1000;
+/** Wait after a 429 without a usable `Retry-After`, or after a failed connection / 5xx. */
+const DEFAULT_HOLD_MS = 60 * 1000;
+
+type Attributes = WidgetCustomAttributes;
+
+export interface UserUpdateQueueOptions {
+  burst?: number;
+  windowMs?: number;
+  now?: () => number;
+}
+
+export class UserUpdateQueue {
+  private readonly burst: number;
+  private readonly refillMs: number;
+  private readonly now: () => number;
+
+  private tokens: number;
+  private refilledAt: number;
+  /** Values Workstation accepted for the current identity. */
+  private sent: Attributes = {};
+  /** Values waiting for the next allowed send. */
+  private pending: Attributes | null = null;
+  private inFlight = false;
+  private holdUntil = 0;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  /** Bumped by reset(): a send that settles after it writes nothing back. */
+  private generation = 0;
+
+  constructor(
+    private readonly send: (attributes: Attributes) => Promise<void>,
+    options: UserUpdateQueueOptions = {}
+  ) {
+    this.burst = Math.max(1, options.burst ?? USER_UPDATE_BURST);
+    this.refillMs = (options.windowMs ?? USER_UPDATE_WINDOW_MS) / this.burst;
+    this.now = options.now ?? Date.now;
+    this.tokens = this.burst;
+    this.refilledAt = this.now();
+  }
+
+  /**
+   * Resolves once the values are sent, or straight away when nothing changed
+   * or they were held for a later send. Rejects only when a send made right
+   * now fails with something other than a 429, as `updateUser()` always has.
+   */
+  update(attributes: Attributes): Promise<void> {
+    const changes: Attributes = {};
+    for (const [key, value] of Object.entries(attributes)) {
+      const known = this.pending && key in this.pending ? this.pending[key] : this.sent[key];
+      if (known !== value) changes[key] = value;
+    }
+    if (Object.keys(changes).length === 0) return Promise.resolve();
+
+    this.pending = { ...this.pending, ...changes };
+    if (this.inFlight || this.now() < this.holdUntil || !this.takeToken()) {
+      this.schedule();
+      return Promise.resolve();
+    }
+    return this.sendPending();
+  }
+
+  /** The visitor's identity changed (anonymous → signed in): Workstation may hold other values now. */
+  forgetSent(): void {
+    this.sent = {};
+  }
+
+  /** Sign-out or a different user: drop everything waiting so it can't reach the next visitor. */
+  reset(): void {
+    this.generation += 1;
+    this.clearTimer();
+    this.sent = {};
+    this.pending = null;
+    this.inFlight = false;
+    this.holdUntil = 0;
+  }
+
+  destroy(): void {
+    this.reset();
+  }
+
+  /** The send budget is per device, not per visitor, so reset() leaves it alone. */
+  private takeToken(): boolean {
+    this.refill();
+    if (this.tokens < 1) return false;
+    this.tokens -= 1;
+    return true;
+  }
+
+  private refill(): void {
+    const now = this.now();
+    if (this.tokens >= this.burst) {
+      this.refilledAt = now;
+      return;
+    }
+    const earned = Math.floor((now - this.refilledAt) / this.refillMs);
+    if (earned <= 0) return;
+    this.tokens = Math.min(this.burst, this.tokens + earned);
+    this.refilledAt = this.tokens === this.burst ? now : this.refilledAt + earned * this.refillMs;
+  }
+
+  private async sendPending(): Promise<void> {
+    const attributes = this.pending ?? {};
+    const generation = this.generation;
+    this.pending = null;
+    this.inFlight = true;
+    try {
+      await this.send(attributes);
+      if (generation !== this.generation) return;
+      this.sent = { ...this.sent, ...attributes };
+    } catch (error) {
+      if (generation !== this.generation) throw error;
+      const status = error instanceof RepzoWidgetError ? error.status : 0;
+      const retryable = status === 429 || status === 0 || status >= 500;
+      if (retryable) {
+        // Newer values that arrived meanwhile win over the ones that failed.
+        this.pending = { ...attributes, ...(this.pending ?? {}) };
+        const retryAfter = error instanceof RepzoWidgetError ? error.retryAfter : undefined;
+        const holdMs = status === 429 && retryAfter && retryAfter > 0 ? retryAfter * 1000 : DEFAULT_HOLD_MS;
+        this.holdUntil = Math.max(this.holdUntil, this.now() + holdMs);
+      }
+      // Rate limited: the values are kept and go out later, so the call succeeded.
+      if (status !== 429) throw error;
+    } finally {
+      if (generation === this.generation) {
+        this.inFlight = false;
+        if (this.pending) this.schedule();
+      }
+    }
+  }
+
+  private schedule(): void {
+    if (this.timer || this.inFlight || !this.pending) return;
+    this.refill();
+    const now = this.now();
+    const tokenAt = this.tokens >= 1 ? now : this.refilledAt + this.refillMs;
+    const delay = Math.max(0, this.holdUntil - now, tokenAt - now);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.flush();
+    }, delay);
+  }
+
+  private flush(): void {
+    if (this.inFlight || !this.pending) return;
+    if (this.now() < this.holdUntil || !this.takeToken()) {
+      this.schedule();
+      return;
+    }
+    this.sendPending().catch((error) => {
+      console.warn('[repzo-widget] updateUser failed', error);
+    });
+  }
+
+  private clearTimer(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+  }
+}