@tai42/studio-sdk 16.0.0 → 17.0.0

package/src/hooks/interactions-connection.ts

@@ -0,0 +1,227 @@
+/**
+ * The SSE reconnect driver behind `useInteractionsStream`: it owns the fetch +
+ * ReadableStream tail (via the api-client's `streamInteractions`, never
+ * EventSource), the capped-exponential-with-jitter reconnect backoff, the
+ * on-(re)connect resync, and the wiring that folds each frame through the pure
+ * overlay reducer and republishes the merged list. React state flows in as the
+ * dispatchers the hook passes; this file holds no React.
+ */
+import type { ApiClient, Interaction } from '@tai42/api-client';
+import type { Dispatch, RefObject, SetStateAction } from 'react';
+
+import { isFeatureDisabled } from '../feature-disabled';
+import {
+  emptyOverlay,
+  type LiveOverlay,
+  merge,
+  overlayApplyAdd,
+  overlayApplyAnswered,
+  overlayApplyRemoved,
+  parseAddFrame,
+  parseId,
+  type StreamInteraction,
+  sweepAnswered,
+} from './interactions-stream';
+
+// Reconnect backoff: capped exponential with full jitter. The delay for attempt
+// n is a random value in [0, min(CAP, BASE * 2**n)); the attempt counter resets
+// only when a connection PROVES HEALTHY — it stayed open at least
+// `HEALTHY_CONNECTION_MS` — not merely when it opens, so a server that accepts the
+// request then drops the body still backs off instead of tight-looping.
+const RECONNECT_BASE_MS = 1500;
+const RECONNECT_CAP_MS = 30000;
+const HEALTHY_CONNECTION_MS = RECONNECT_BASE_MS;
+
+/** The live connection status the hook renders from. */
+export interface ConnectionState {
+  readonly connected: boolean;
+  readonly error: Error | null;
+  /**
+   * The interactions store is not configured on this deployment: the stream
+   * answered with a terminal 501 `interactions-not-configured`. Reconnection is
+   * abandoned (retrying would replay the same refusal forever) and the consumer
+   * renders the muted OFF state instead of a red error or a floating badge.
+   */
+  readonly disabled: boolean;
+}
+
+/** Everything the driver reads or writes, supplied by the hook's render. */
+export interface InteractionsStreamDeps {
+  readonly api: ApiClient;
+  readonly overlayRef: RefObject<LiveOverlay>;
+  readonly epochRef: RefObject<number>;
+  readonly seedRef: RefObject<readonly Interaction[]>;
+  readonly onResyncRef: RefObject<() => boolean | Promise<boolean>>;
+  readonly onUnauthorized: () => void;
+  readonly setConnectionState: Dispatch<SetStateAction<ConnectionState>>;
+  readonly setInteractions: Dispatch<SetStateAction<StreamInteraction[]>>;
+  readonly setCountEpoch: Dispatch<SetStateAction<number>>;
+}
+
+/** The driver's per-connection context: the deps plus this run's abort source and overlay. */
+interface StreamContext extends InteractionsStreamDeps {
+  readonly controller: AbortController;
+  readonly overlay: LiveOverlay;
+}
+
+function aborted(ctx: StreamContext): boolean {
+  return ctx.controller.signal.aborted;
+}
+
+function surfaceMalformed(ctx: StreamContext, event: string): void {
+  ctx.setConnectionState((prev) => ({
+    ...prev,
+    error: new Error(`malformed interaction frame: ${event}`),
+  }));
+}
+
+/**
+ * A successful data frame sweeps aged answered cards, republishes the merged list,
+ * and clears any transient frame-parse error — one bad frame on a healthy stream
+ * must not stick. It does NOT refetch: the overlay already updated the list and the
+ * derived count, and the resync fires on (re)connect only.
+ */
+function commit(ctx: StreamContext): void {
+  if (aborted(ctx)) return;
+  sweepAnswered(ctx.overlay);
+  ctx.setConnectionState((prev) => (prev.error === null ? prev : { ...prev, error: null }));
+  ctx.setInteractions(merge(ctx.seedRef.current, ctx.overlay));
+}
+
+function applyFrame(ctx: StreamContext, event: string, data: string): void {
+  if (event === 'interaction.removed') {
+    const id = parseId(data);
+    if (id === null) {
+      surfaceMalformed(ctx, event);
+      return;
+    }
+    overlayApplyRemoved(ctx.overlay, id, ctx.epochRef.current);
+    commit(ctx);
+    return;
+  }
+  if (event === 'interaction.answered') {
+    const id = parseId(data);
+    if (id === null) {
+      surfaceMalformed(ctx, event);
+      return;
+    }
+    overlayApplyAnswered(ctx.overlay, id, ctx.epochRef.current, ctx.seedRef.current);
+    commit(ctx);
+    return;
+  }
+  // interaction.add — the full question.
+  const interaction = parseAddFrame(data);
+  if (interaction === null) {
+    surfaceMalformed(ctx, event);
+    return;
+  }
+  overlayApplyAdd(ctx.overlay, interaction, ctx.epochRef.current);
+  commit(ctx);
+}
+
+/** The resume cursor: the id of the last frame seen on this mount, sent as Last-Event-ID. */
+interface ResumeCursor {
+  lastEventId: string | undefined;
+}
+
+/**
+ * Open one connection and consume its frames until the tail ends. Refetches the
+ * paged base on connect under a fresh epoch (tail-only carries no backlog) and
+ * records that epoch as `countEpoch` only once the refetch LANDED, so the count
+ * applies only deltas not yet folded into the fresh `total`.
+ */
+async function connectAndConsume(ctx: StreamContext, cursor: ResumeCursor): Promise<void> {
+  const frames = await ctx.api.streamInteractions(ctx.controller.signal, cursor.lastEventId);
+  if (aborted(ctx)) return;
+  ctx.setConnectionState((prev) => ({ ...prev, connected: true, error: null, disabled: false }));
+  const epoch = (ctx.epochRef.current += 1);
+  const landed = await ctx.onResyncRef.current();
+  if (aborted(ctx)) return;
+  if (landed) ctx.setCountEpoch(epoch);
+  for await (const frame of frames) {
+    if (aborted(ctx)) return;
+    applyFrame(ctx, frame.event, frame.data);
+    // Advance the resume cursor to every id-bearing frame (even a malformed one)
+    // so a reconnect never re-requests a frame already delivered.
+    if (frame.id !== undefined) cursor.lastEventId = frame.id;
+  }
+}
+
+/** Classify a connection error into whether the driver should stop or reconnect. */
+function handleConnectionError(ctx: StreamContext, err: unknown): 'stop' | 'retry' {
+  const error = err instanceof Error ? err : new Error(String(err));
+  ctx.setConnectionState((prev) => ({ ...prev, connected: false, error }));
+  if (error.name === 'ApiUnauthorizedError') {
+    // A dead credential — reconnecting would replay the same bad key forever. Hand
+    // off to the app's 401→login handler, the same path every other call takes.
+    ctx.onUnauthorized();
+    return 'stop';
+  }
+  if (isFeatureDisabled(error)) {
+    // A terminal 501 `interactions-not-configured`: reconnecting would replay the
+    // same refusal on every backoff forever. Flag the OFF state and stop.
+    ctx.setConnectionState((prev) => ({ ...prev, connected: false, disabled: true }));
+    return 'stop';
+  }
+  return 'retry';
+}
+
+/** Wait out the backoff for `attempt`, resolving early if the signal aborts. */
+function waitBackoff(signal: AbortSignal, attempt: number): Promise<void> {
+  const ceiling = Math.min(RECONNECT_CAP_MS, RECONNECT_BASE_MS * 2 ** attempt);
+  const delay = Math.random() * ceiling;
+  return new Promise<void>((resolve) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      // Normal wake: drop the abort listener so it does not accumulate across
+      // reconnects ({ once: true } only self-removes on firing).
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, delay);
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/** The reconnect loop: connect, consume, back off, repeat until aborted or terminal. */
+async function runConnectionLoop(ctx: StreamContext): Promise<void> {
+  const cursor: ResumeCursor = { lastEventId: undefined };
+  let reconnectAttempt = 0;
+  while (!aborted(ctx)) {
+    const openedAt = Date.now();
+    try {
+      await connectAndConsume(ctx, cursor);
+      if (aborted(ctx)) return;
+    } catch (err) {
+      if (aborted(ctx)) return;
+      if (handleConnectionError(ctx, err) === 'stop') return;
+    }
+    // A connection open at least HEALTHY_CONNECTION_MS proved healthy — clear the
+    // backoff so the next drop reconnects promptly; an accept-then-drop flap does not.
+    if (Date.now() - openedAt >= HEALTHY_CONNECTION_MS) reconnectAttempt = 0;
+    if (aborted(ctx)) return;
+    ctx.setConnectionState((prev) => ({ ...prev, connected: false }));
+    await waitBackoff(ctx.controller.signal, reconnectAttempt);
+    reconnectAttempt += 1;
+  }
+}
+
+/**
+ * Start the tail-only interactions stream and return the effect cleanup. The
+ * abort signal is the single cancellation source of truth: cleanup aborts it, every
+ * loop guard reads it fresh, and a fresh mount starts from an empty overlay at epoch
+ * 0 so a re-run never inherits the prior run's tail or its epoch stamps.
+ */
+export function startInteractionsStream(deps: InteractionsStreamDeps): () => void {
+  const controller = new AbortController();
+  const ctx: StreamContext = { ...deps, controller, overlay: deps.overlayRef.current };
+  void runConnectionLoop(ctx);
+  return () => {
+    controller.abort();
+    deps.overlayRef.current = emptyOverlay();
+    deps.epochRef.current = 0;
+    deps.setCountEpoch(0);
+  };
+}

package/src/hooks/interactions-stream.ts

@@ -0,0 +1,274 @@
+/**
+ * The pure reducer behind the live interactions inbox: frame parsing, the live
+ * overlay accumulated over the paged base, and the two derived projections
+ * (`merge` → the published list, `pendingCount` → the live badge tally). No React,
+ * no I/O — the connection driver owns the SSE loop and feeds frames through here.
+ */
+import type { Interaction } from '@tai42/api-client';
+
+import { isRecord } from '../guards';
+
+/** A live interaction plus the client-maintained `answered` flag. */
+export type StreamInteraction = Interaction & { readonly answered: boolean };
+
+// The server emits no removal for an answered card — only `interaction.answered`,
+// never `interaction.removed` for it — and the paged base never carries answered
+// items, so answered cards would otherwise pile up unbounded in the always-mounted
+// badge/inbox. The client ages them out: drop an answered card
+// ANSWERED_RETENTION_MS after its answered frame, keeping at most ANSWERED_CAP as a
+// hard flood backstop. Swept lazily on frame/reconnect ticks (the stream carries no
+// idle heartbeat frame), never a per-item timer.
+const ANSWERED_RETENTION_MS = 10 * 60 * 1000;
+const ANSWERED_CAP = 200;
+
+// The wire `answer_format` values. Duplicated from the api-client enum by design:
+// the SDK is the leaf and must not import api-client at runtime. The `satisfies`
+// pin against `Interaction['answer_format']` fails to compile if a listed value
+// leaves the union, so this runtime guard cannot silently drift from the type.
+const ANSWER_FORMATS = new Set<string>([
+  'text',
+  'confirm',
+  'select',
+  'form',
+  'external',
+] as const satisfies readonly Interaction['answer_format'][]);
+
+/** Parse a frame's JSON to a plain object, or null when it is not one. */
+function parseJson(data: string): Record<string, unknown> | null {
+  if (!data) return null;
+  try {
+    const obj: unknown = JSON.parse(data);
+    return isRecord(obj) ? obj : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The strictly-required frame fields, narrowed once so the assembly needs no casts. */
+interface RequiredFrameFields {
+  interaction_id: string;
+  group_id: string;
+  created_at: string;
+  timeout_at: string;
+  answer_format: Interaction['answer_format'];
+}
+
+/**
+ * The strict-required fields: `interaction_id`, `group_id`, `created_at`,
+ * `timeout_at` must each be a string and `answer_format` a known enum value.
+ * `question` is `z.string().default('')` — a missing question is valid (normalized
+ * to `''` on assembly) but a present non-string is malformed; `format_payload` is
+ * nullish — absent/null is valid but a present non-object is malformed.
+ */
+function requiredFieldsValid(
+  obj: Record<string, unknown>,
+): obj is Record<string, unknown> & RequiredFrameFields {
+  if (typeof obj.interaction_id !== 'string') return false;
+  if (typeof obj.group_id !== 'string') return false;
+  if (obj.question !== undefined && typeof obj.question !== 'string') return false;
+  if (typeof obj.created_at !== 'string') return false;
+  if (typeof obj.timeout_at !== 'string') return false;
+  if (typeof obj.answer_format !== 'string' || !ANSWER_FORMATS.has(obj.answer_format)) return false;
+  if (obj.format_payload != null && !isRecord(obj.format_payload)) return false;
+  return true;
+}
+
+/**
+ * The optional fields, each rejected only when PRESENT with the wrong type: an
+ * absent value stays absent (or takes its schema default on assembly). `media`
+ * items stay unknown by design — each is validated per item by the renderer.
+ */
+function optionalFieldsValid(obj: Record<string, unknown>): boolean {
+  if (obj.sensitive !== undefined && typeof obj.sensitive !== 'boolean') return false;
+  if (obj.server_verified !== undefined && typeof obj.server_verified !== 'boolean') return false;
+  if (obj.channel !== undefined && typeof obj.channel !== 'string') return false;
+  if (obj.recipient !== undefined && typeof obj.recipient !== 'string') return false;
+  if (obj.origin !== undefined && typeof obj.origin !== 'string') return false;
+  if (obj.audience !== undefined && typeof obj.audience !== 'string') return false;
+  if (obj.media !== undefined && !Array.isArray(obj.media)) return false;
+  return true;
+}
+
+/** Assemble the validated frame into an `Interaction`, applying the schema defaults. */
+function buildInteraction(obj: Record<string, unknown> & RequiredFrameFields): Interaction {
+  return {
+    interaction_id: obj.interaction_id,
+    group_id: obj.group_id,
+    question: typeof obj.question === 'string' ? obj.question : '',
+    answer_format: obj.answer_format,
+    format_payload: isRecord(obj.format_payload) ? obj.format_payload : {},
+    created_at: obj.created_at,
+    timeout_at: obj.timeout_at,
+    sensitive: typeof obj.sensitive === 'boolean' ? obj.sensitive : false,
+    ...(typeof obj.server_verified === 'boolean' ? { server_verified: obj.server_verified } : {}),
+    ...(typeof obj.channel === 'string' ? { channel: obj.channel } : {}),
+    ...(typeof obj.recipient === 'string' ? { recipient: obj.recipient } : {}),
+    ...(typeof obj.origin === 'string' ? { origin: obj.origin } : {}),
+    ...(typeof obj.audience === 'string' ? { audience: obj.audience } : {}),
+    ...(Array.isArray(obj.media) ? { media: obj.media } : {}),
+  };
+}
+
+/**
+ * Validate an `interaction.add` frame into an `Interaction`, or null when it is
+ * malformed. This mirrors the api-client `interaction` zod schema exactly — it
+ * accepts what that schema accepts, no more, no less — so the caller surfaces a
+ * malformed frame as an error rather than rendering a blank card, and never
+ * silently coerces one.
+ */
+export function parseAddFrame(data: string): Interaction | null {
+  const obj = parseJson(data);
+  if (obj === null) return null;
+  if (!requiredFieldsValid(obj) || !optionalFieldsValid(obj)) return null;
+  return buildInteraction(obj);
+}
+
+/** The interaction id from an `answered` / `removed` frame, or null. */
+export function parseId(data: string): string | null {
+  const id = parseJson(data)?.interaction_id;
+  return typeof id === 'string' ? id : null;
+}
+
+/**
+ * The live overlay a connection accumulates over the paged base: the tail's own
+ * adds (kept whether or not the base already lists them, so a fresher add wins),
+ * the answered stamps (wall-clock ms, for the aging sweep), and the tombstones for
+ * ids removed on the tail OR aged out of the answered window (a tombstone stops a
+ * still-stale seed from re-showing a gone card; ids are never reused). `addEpoch`
+ * and `goneEpoch` carry the resync epoch current when an add / a first terminal frame
+ * arrived, so the count applies an add (or subtracts a terminal) only while it is not
+ * yet folded into the refetched `total`; the merge and the aging sweep ignore them.
+ */
+export interface LiveOverlay {
+  readonly adds: Map<string, Interaction>;
+  readonly addEpoch: Map<string, number>;
+  readonly answeredAt: Map<string, number>;
+  readonly removed: Set<string>;
+  readonly goneEpoch: Map<string, number>;
+}
+
+export function emptyOverlay(): LiveOverlay {
+  return {
+    adds: new Map(),
+    addEpoch: new Map(),
+    answeredAt: new Map(),
+    removed: new Set(),
+    goneEpoch: new Map(),
+  };
+}
+
+/** Record an `interaction.add`: a live add overwrites any prior copy in place. */
+export function overlayApplyAdd(
+  overlay: LiveOverlay,
+  interaction: Interaction,
+  epoch: number,
+): void {
+  overlay.adds.set(interaction.interaction_id, interaction);
+  overlay.addEpoch.set(interaction.interaction_id, epoch);
+}
+
+/**
+ * Record an `interaction.answered`. The answered time and terminal epoch are
+ * stamped on the FIRST answered frame only (a redelivery keeps the original stamp,
+ * so the retention window is not extended and a later terminal never re-dates it
+ * into a fresher resync). A seed-origin card is promoted into the overlay so it
+ * lingers uniformly with a live-add card, since the paged base never carries
+ * answered items and a refetch would otherwise drop it before its window elapses.
+ */
+export function overlayApplyAnswered(
+  overlay: LiveOverlay,
+  id: string,
+  epoch: number,
+  seed: readonly Interaction[],
+): void {
+  if (!overlay.answeredAt.has(id)) overlay.answeredAt.set(id, Date.now());
+  if (!overlay.goneEpoch.has(id)) overlay.goneEpoch.set(id, epoch);
+  if (!overlay.adds.has(id)) {
+    const seeded = seed.find((item) => item.interaction_id === id);
+    if (seeded !== undefined) {
+      overlay.adds.set(id, seeded);
+      overlay.addEpoch.set(id, epoch);
+    }
+  }
+}
+
+/** Record an `interaction.removed`: tombstone the id and stamp its first terminal epoch. */
+export function overlayApplyRemoved(overlay: LiveOverlay, id: string, epoch: number): void {
+  overlay.adds.delete(id);
+  overlay.addEpoch.delete(id);
+  overlay.answeredAt.delete(id);
+  overlay.removed.add(id);
+  if (!overlay.goneEpoch.has(id)) overlay.goneEpoch.set(id, epoch);
+}
+
+/**
+ * Age answered cards out (the server sends no removal for them): tombstone any past
+ * the retention window, then — as a flood backstop — the oldest beyond the count
+ * cap. A tombstone (not a bare delete) so a still-stale seed cannot resurrect a card
+ * the client has retired; the id keeps its original `goneEpoch` so moving
+ * answered→removed never re-dates it into a fresher resync.
+ */
+export function sweepAnswered(overlay: LiveOverlay): void {
+  const now = Date.now();
+  const retire = (id: string) => {
+    overlay.answeredAt.delete(id);
+    overlay.adds.delete(id);
+    overlay.addEpoch.delete(id);
+    overlay.removed.add(id);
+  };
+  for (const [id, at] of overlay.answeredAt) {
+    if (now - at >= ANSWERED_RETENTION_MS) retire(id);
+  }
+  if (overlay.answeredAt.size > ANSWERED_CAP) {
+    const oldest = [...overlay.answeredAt.entries()].sort((a, b) => a[1] - b[1]);
+    for (const [id] of oldest.slice(0, oldest.length - ANSWERED_CAP)) retire(id);
+  }
+}
+
+/** Fold the paged base and the live overlay into the published, ordered list. */
+export function merge(seed: readonly Interaction[], live: LiveOverlay): StreamInteraction[] {
+  const out = new Map<string, StreamInteraction>();
+  for (const item of seed) {
+    if (live.removed.has(item.interaction_id)) continue;
+    out.set(item.interaction_id, { ...item, answered: live.answeredAt.has(item.interaction_id) });
+  }
+  for (const [id, item] of live.adds) {
+    if (live.removed.has(id)) continue;
+    out.set(id, { ...item, answered: live.answeredAt.has(id) });
+  }
+  return Array.from(out.values());
+}
+
+/**
+ * The live pending tally: the door's `total` for the seed, plus live adds whose id
+ * is absent from the seed AND stamped at or after `countEpoch` (a new question not
+ * yet folded into `total`), minus one for every terminal id — answered OR removed —
+ * stamped at or after `countEpoch`, deduped per id so an id counts once however many
+ * terminal frames it drew. `countEpoch` is the epoch of the last resync whose refetch
+ * LANDED (a failed refetch never advances it): a delta stamped before it is already
+ * reflected in the fresh `total`, so it is NOT applied again — this is what stops a
+ * resync from re-subtracting a terminal it already dropped from `total`, while a
+ * failed refetch keeps the prior-epoch deltas applying against the prior total. One
+ * residual race remains: a frame arriving while a refetch is in flight may already be
+ * reflected in that refetch's `total`, so the raw tally can transiently dip below zero
+ * until the next resync reconciles. A pending tally below zero is meaningless, so the
+ * published count clamps at 0; the clamp covers only the negative symptom (a transient
+ * positive under-count reconciles on the next resync, not here).
+ */
+export function pendingCount(
+  seed: readonly Interaction[],
+  total: number,
+  live: LiveOverlay,
+  countEpoch: number,
+): number {
+  const seedIds = new Set(seed.map((item) => item.interaction_id));
+  let count = total;
+  for (const id of live.adds.keys()) {
+    if (!seedIds.has(id) && (live.addEpoch.get(id) ?? 0) >= countEpoch) count += 1;
+  }
+  const gone = new Set<string>([...live.answeredAt.keys(), ...live.removed]);
+  for (const id of gone) {
+    if ((live.goneEpoch.get(id) ?? 0) >= countEpoch) count -= 1;
+  }
+  return Math.max(count, 0);
+}

package/src/hooks/useApi.ts

@@ -9,8 +9,8 @@
  * runtime dependency on @tai42/api-client (the SDK imports nothing internal at
  * runtime).
  */
-import { createContext, useContext } from 'react';
 import type { ApiClient } from '@tai42/api-client';
+import { createContext, useContext } from 'react';
 
 const ApiContext = createContext<ApiClient | null>(null);
 

package/src/hooks/useAuth.ts

@@ -4,8 +4,8 @@
  * sessionStorage. localStorage is NEVER written: the README documents the
  * XSS trade-off and why localStorage persistence is not offered.
  */
-import { createContext, useCallback, useContext, useMemo, useState } from 'react';
 import type { ReactNode } from 'react';
+import { createContext, useCallback, useContext, useMemo, useState } from 'react';
 import { createElement } from 'react';
 
 const SESSION_KEY = 'tai-studio.apiKey';

package/src/hooks/useCapabilities.ts

@@ -14,6 +14,8 @@
  * `ErrorState` with `retry` in the nav region — never an optimistic full nav on
  * error. The UI fails closed exactly as the server would.
  */
+import type { MeProjection } from '@tai42/api-client';
+import type { ReactNode } from 'react';
 import {
   createContext,
   useCallback,
@@ -23,9 +25,7 @@ import {
   useRef,
   useState,
 } from 'react';
-import type { ReactNode } from 'react';
 import { createElement } from 'react';
-import type { MeProjection } from '@tai42/api-client';
 
 import { useApi } from './useApi';
 import { useAuth } from './useAuth';
@@ -116,7 +116,7 @@ export function useCapabilities(): CapabilityContextValue {
 
 /**
  * Whether the projection is the synthetic TOTAL projection — the admin session
- * (the condition-free ownerless `"*"` discriminator) and the gate-off local-dev
+ * (the condition-free `"*"` discriminator) and the gate-off local-dev
  * projection alike. This is `projection.admin === true` and NOTHING else: a
  * seeded editor/viewer carries `["*"]` scopes PLUS a jq fence, so keying on `"*"`
  * scopes would hand every editor/viewer the unfiltered nav and a wall of 403s on