@hexclave/js 1.0.2 → 1.0.5

package/src/lib/hexclave-app/apps/implementations/session-refresh-subscription.test.ts

@@ -0,0 +1,106 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { describe, expect, it, vi } from "vitest";
+import { subscribeSessionRefresh } from "./session-refresh-subscription";
+
+type Listener = () => void;
+
+function createTokenStoreTestDouble() {
+  const listeners = new Set<Listener>();
+  const unsubscribe = vi.fn((listener: Listener) => {
+    listeners.delete(listener);
+  });
+
+  return {
+    tokenStore: {
+      onChange: vi.fn((listener: Listener) => {
+        listeners.add(listener);
+        return {
+          unsubscribe: () => unsubscribe(listener),
+        };
+      }),
+    },
+    emitChange: () => {
+      for (const listener of [...listeners]) {
+        listener();
+      }
+    },
+    unsubscribe,
+  };
+}
+
+function createSessionTestDouble(sessionKey: string) {
+  const refreshUnsubscribe = vi.fn();
+  return {
+    session: {
+      sessionKey,
+      startRefreshingAccessToken: vi.fn(() => ({
+        unsubscribe: refreshUnsubscribe,
+      })),
+    },
+    refreshUnsubscribe,
+  };
+}
+
+describe("subscribeSessionRefresh", () => {
+  it("starts token refresh while subscribed and stops it on unsubscribe", () => {
+    const tokenStore = createTokenStoreTestDouble();
+    const firstSession = createSessionTestDouble("refresh-token-1");
+    const onTokenStoreChange = vi.fn();
+
+    const unsubscribe = subscribeSessionRefresh({
+      tokenStore: tokenStore.tokenStore,
+      getSession: () => firstSession.session,
+      onTokenStoreChange,
+    });
+
+    expect(firstSession.session.startRefreshingAccessToken).toHaveBeenCalledWith(30_000, 60_000);
+    expect(tokenStore.tokenStore.onChange).toHaveBeenCalledOnce();
+
+    unsubscribe();
+
+    expect(tokenStore.unsubscribe).toHaveBeenCalledOnce();
+    expect(firstSession.refreshUnsubscribe).toHaveBeenCalledOnce();
+  });
+
+  it("keeps the existing refresh loop when the token store changes within the same session", () => {
+    const tokenStore = createTokenStoreTestDouble();
+    const firstSession = createSessionTestDouble("refresh-token-1");
+    const onTokenStoreChange = vi.fn();
+
+    subscribeSessionRefresh({
+      tokenStore: tokenStore.tokenStore,
+      getSession: () => firstSession.session,
+      onTokenStoreChange,
+    });
+
+    tokenStore.emitChange();
+
+    expect(onTokenStoreChange).toHaveBeenCalledOnce();
+    expect(firstSession.session.startRefreshingAccessToken).toHaveBeenCalledOnce();
+    expect(firstSession.refreshUnsubscribe).not.toHaveBeenCalled();
+  });
+
+  it("moves the refresh loop when the token store changes to a different session", () => {
+    const tokenStore = createTokenStoreTestDouble();
+    const firstSession = createSessionTestDouble("refresh-token-1");
+    const secondSession = createSessionTestDouble("refresh-token-2");
+    const sessions = [firstSession.session, secondSession.session];
+    const onTokenStoreChange = vi.fn();
+
+    subscribeSessionRefresh({
+      tokenStore: tokenStore.tokenStore,
+      getSession: () => sessions[0] ?? secondSession.session,
+      onTokenStoreChange,
+    });
+
+    sessions.shift();
+    tokenStore.emitChange();
+
+    expect(onTokenStoreChange).toHaveBeenCalledOnce();
+    expect(firstSession.refreshUnsubscribe).toHaveBeenCalledOnce();
+    expect(secondSession.session.startRefreshingAccessToken).toHaveBeenCalledWith(30_000, 60_000);
+  });
+});

package/src/lib/hexclave-app/apps/implementations/session-refresh-subscription.ts

@@ -0,0 +1,52 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+type TokenStoreSubscription = {
+  unsubscribe: () => void,
+};
+
+type TokenStoreLike = {
+  onChange: (callback: () => void) => TokenStoreSubscription,
+};
+
+type SessionRefreshLike = {
+  sessionKey: string,
+  startRefreshingAccessToken: (minMillisUntilExpiration: number, maxMillisSinceIssued: number | null) => TokenStoreSubscription,
+};
+
+/**
+ * Keeps the currently mounted React session fresh while `useSyncExternalStore`
+ * has an active subscriber. The token store owns which session is current; when
+ * it changes to a different session key, we stop refreshing the old session and
+ * start refreshing the new one. The caller still receives every token-store
+ * change through `onTokenStoreChange` so React can re-read the session snapshot.
+ */
+export function subscribeSessionRefresh(options: {
+  tokenStore: TokenStoreLike,
+  getSession: () => SessionRefreshLike,
+  onTokenStoreChange: () => void,
+  minMillisUntilExpiration?: number,
+  maxMillisSinceIssued?: number | null,
+}): () => void {
+  const minMillisUntilExpiration = options.minMillisUntilExpiration ?? 30_000;
+  const maxMillisSinceIssued = options.maxMillisSinceIssued ?? 60_000;
+
+  let refreshedSession = options.getSession();
+  let refreshSubscription = refreshedSession.startRefreshingAccessToken(minMillisUntilExpiration, maxMillisSinceIssued);
+
+  const tokenStoreSubscription = options.tokenStore.onChange(() => {
+    const nextSession = options.getSession();
+    if (nextSession.sessionKey !== refreshedSession.sessionKey) {
+      refreshSubscription.unsubscribe();
+      refreshedSession = nextSession;
+      refreshSubscription = refreshedSession.startRefreshingAccessToken(minMillisUntilExpiration, maxMillisSinceIssued);
+    }
+    options.onTokenStoreChange();
+  });
+
+  return () => {
+    tokenStoreSubscription.unsubscribe();
+    refreshSubscription.unsubscribe();
+  };
+}

package/src/lib/hexclave-app/apps/implementations/session-replay.test.ts

@@ -0,0 +1,33 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { describe, expect, it } from "vitest";
+import { analyticsOptionsFromJson, analyticsOptionsToJson } from "./session-replay";
+
+describe("analytics option JSON conversion", () => {
+  it("preserves top-level analytics options when serializing replay block classes", () => {
+    const json = analyticsOptionsToJson({
+      enabled: false,
+      replays: {
+        enabled: true,
+        blockClass: /stack-sensitive/u,
+      },
+    });
+
+    expect(json?.enabled).toBe(false);
+    expect(json?.replays?.enabled).toBe(true);
+  });
+
+  it("preserves top-level analytics options when deserializing replay block classes", () => {
+    const roundTripped = analyticsOptionsFromJson(analyticsOptionsToJson({
+      enabled: false,
+      replays: {
+        blockClass: /stack-sensitive/u,
+      },
+    }));
+
+    expect(roundTripped?.enabled).toBe(false);
+    expect(roundTripped?.replays?.blockClass).toEqual(/stack-sensitive/u);
+  });
+});

package/src/lib/hexclave-app/apps/implementations/session-replay.ts

@@ -0,0 +1,356 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { isBrowserLike } from "@hexclave/shared/dist/utils/env";
+import { captureWarning } from "@hexclave/shared/dist/utils/errors";
+import { runAsynchronously } from "@hexclave/shared/dist/utils/promises";
+import { Result } from "@hexclave/shared/dist/utils/results";
+
+export type AnalyticsReplayOptions = {
+  /**
+   * Whether session replays are enabled.
+   *
+   * @default false
+   */
+  enabled?: boolean,
+  /**
+   * Whether to mask the content of all `<input>` elements.
+   *
+   * @default true
+   */
+  maskAllInputs?: boolean,
+  /**
+   * A CSS class name or RegExp. Elements with a matching class will be blocked
+   * (replaced with a placeholder in the recording).
+   *
+   * @default undefined
+   */
+  blockClass?: string | RegExp,
+  /**
+   * A CSS selector string. Elements matching this selector will be blocked
+   * (replaced with a placeholder in the recording).
+   *
+   * @default undefined
+   */
+  blockSelector?: string,
+};
+
+export type AnalyticsOptions = {
+  /**
+   * Whether SDK-managed analytics capture is enabled.
+   *
+   * @default true
+   */
+  enabled?: boolean,
+  /**
+   * Options for session replay recording. Replays are disabled by default;
+   * set `enabled: true` to opt in.
+   */
+  replays?: AnalyticsReplayOptions,
+};
+
+/**
+ * Converts AnalyticsOptions to a JSON-safe representation.
+ * RegExp blockClass values are serialized as `{ __regexp, __flags }` objects.
+ * The return type is AnalyticsOptions to keep StackClientAppJson simple;
+ * the actual runtime value is JSON-safe.
+ */
+export function analyticsOptionsToJson(options: AnalyticsOptions | undefined): AnalyticsOptions | undefined {
+  if (!options?.replays?.blockClass) return options;
+  const { blockClass, ...rest } = options.replays;
+  if (!(blockClass instanceof RegExp)) return options;
+  return {
+    ...options,
+    replays: {
+      ...rest,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      blockClass: { __regexp: blockClass.source, __flags: blockClass.flags } as any,
+    },
+  };
+}
+
+/**
+ * Reconstructs AnalyticsOptions from a JSON-deserialized value.
+ * Converts `{ __regexp, __flags }` objects back to RegExp instances.
+ */
+export function analyticsOptionsFromJson(json: AnalyticsOptions | undefined): AnalyticsOptions | undefined {
+  if (!json?.replays?.blockClass) return json;
+  const { blockClass, ...rest } = json.replays;
+  if (typeof blockClass === 'object' && '__regexp' in blockClass) {
+    const bc = blockClass as unknown as { __regexp: string, __flags: string };
+    return {
+      ...json,
+      replays: {
+        ...rest,
+        blockClass: new RegExp(bc.__regexp, bc.__flags),
+      },
+    };
+  }
+  return json;
+}
+
+// ---------- Recording internals ----------
+
+// Hexclave rebrand: canonical localStorage prefix (colon delimiters preserved).
+const LOCAL_STORAGE_PREFIX = "hexclave:session-replay:v1";
+// Hexclave rebrand: legacy prefix — dual-read only, so a recording session active
+// across an SDK upgrade is not orphaned. Never written.
+const LEGACY_LOCAL_STORAGE_PREFIX = "stack:session-replay:v1";
+const IDLE_TTL_MS = 3 * 60 * 1000;
+
+const FLUSH_INTERVAL_MS = 5_000;
+const MAX_EVENTS_PER_BATCH = 200;
+const MAX_APPROX_BYTES_PER_BATCH = 512_000;
+
+export type StoredSession = {
+  session_id: string,
+  created_at_ms: number,
+  last_activity_ms: number,
+};
+
+export function safeParseStoredSession(raw: string | null): StoredSession | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    if (typeof parsed.session_id !== "string") return null;
+    if (typeof parsed.created_at_ms !== "number") return null;
+    if (typeof parsed.last_activity_ms !== "number") return null;
+    return parsed as StoredSession;
+  } catch {
+    return null;
+  }
+}
+
+export function makeStorageKey(projectId: string) {
+  return `${LOCAL_STORAGE_PREFIX}:${projectId}`;
+}
+
+// Hexclave rebrand: legacy key, dual-read only (never written).
+export function makeLegacyStorageKey(projectId: string) {
+  return `${LEGACY_LOCAL_STORAGE_PREFIX}:${projectId}`;
+}
+
+export function generateUuid() {
+  return crypto.randomUUID();
+}
+
+export function getOrRotateSession(options: { key: string, legacyKey?: string, nowMs: number }): StoredSession {
+  // Hexclave rebrand: prefer the new key; fall back to the legacy key so a
+  // recording session active across an SDK upgrade is not orphaned.
+  const existing = safeParseStoredSession(localStorage.getItem(options.key))
+    ?? (options.legacyKey ? safeParseStoredSession(localStorage.getItem(options.legacyKey)) : null);
+  if (existing && options.nowMs - existing.last_activity_ms <= IDLE_TTL_MS) {
+    return existing;
+  }
+  const next: StoredSession = {
+    session_id: generateUuid(),
+    created_at_ms: options.nowMs,
+    last_activity_ms: options.nowMs,
+  };
+  localStorage.setItem(options.key, JSON.stringify(next));
+  return next;
+}
+
+export type SessionRecorderDeps = {
+  projectId: string,
+  sendBatch: (body: string, options: { keepalive: boolean }) => Promise<Result<Response, Error>>,
+};
+
+export class SessionRecorder {
+  private _started = false;
+  private _cancelled = false;
+  private _stopRecording: (() => void) | null = null;
+  private _detachListeners: (() => void) | null = null;
+  private _flushTimer: ReturnType<typeof setInterval> | null = null;
+  private _events: unknown[] = [];
+  private _approxBytes = 0;
+  private _lastPersistActivity = 0;
+  private _recording = false;
+  private _rrwebModule: typeof import("rrweb") | null = null;
+  private _lastBrowserSessionId: string | null = null;
+  private _takingSnapshot = false;
+  private _flushInProgress = false;
+  private readonly _sessionReplaySegmentId: string;
+  private readonly _storageKey: string;
+  // Hexclave rebrand: legacy key used for dual-read fallback only.
+  private readonly _legacyStorageKey: string;
+  private readonly _deps: SessionRecorderDeps;
+  private readonly _replayOptions: AnalyticsReplayOptions;
+
+  constructor(deps: SessionRecorderDeps, replayOptions: AnalyticsReplayOptions) {
+    this._deps = deps;
+    this._replayOptions = replayOptions;
+    this._sessionReplaySegmentId = generateUuid();
+    this._storageKey = makeStorageKey(deps.projectId);
+    this._legacyStorageKey = makeLegacyStorageKey(deps.projectId);
+  }
+
+  /**
+   * Starts recording. Idempotent — calling multiple times is safe.
+   */
+  start() {
+    if (this._started) return;
+    if (!isBrowserLike()) return;
+    this._started = true;
+
+    // Kick off rrweb recording
+    runAsynchronously(() => this._startRecording(), { noErrorLogging: true });
+
+    // Periodic flush
+    this._flushTimer = setInterval(() => this._tick(), FLUSH_INTERVAL_MS);
+  }
+
+  stop() {
+    this._cancelled = true;
+    if (this._flushTimer !== null) {
+      clearInterval(this._flushTimer);
+      this._flushTimer = null;
+    }
+    // Flush remaining events before cleanup
+    runAsynchronously(() => this._flush({ keepalive: true }));
+    this._stopCurrentRecording();
+  }
+
+  clearBuffer() {
+    this._events = [];
+    this._approxBytes = 0;
+  }
+
+  private _persistActivity(nowMs: number): StoredSession {
+    const stored = getOrRotateSession({ key: this._storageKey, legacyKey: this._legacyStorageKey, nowMs });
+    if (nowMs - this._lastPersistActivity < 5_000) return stored;
+    this._lastPersistActivity = nowMs;
+    const updated: StoredSession = { ...stored, last_activity_ms: nowMs };
+    localStorage.setItem(this._storageKey, JSON.stringify(updated));
+    return stored;
+  }
+
+  private async _flush(options: { keepalive: boolean }) {
+    if (this._events.length === 0) return;
+    // Prevent concurrent in-flight HTTP requests. When a flush is already
+    // in-flight, a second batch could race on the server (both call
+    // findRecentSessionReplay before either upsert commits) and create
+    // duplicate SessionReplay records. Events stay in _events and will be
+    // picked up by the next tick or batch-size check.
+    if (this._flushInProgress) return;
+
+    const nowMs = Date.now();
+    const stored = getOrRotateSession({ key: this._storageKey, legacyKey: this._legacyStorageKey, nowMs });
+
+    const batchId = generateUuid();
+    const payload = {
+      browser_session_id: stored.session_id,
+      session_replay_segment_id: this._sessionReplaySegmentId,
+      batch_id: batchId,
+      started_at_ms: stored.created_at_ms,
+      sent_at_ms: nowMs,
+      events: this._events,
+    };
+
+    this._events = [];
+    this._approxBytes = 0;
+
+    this._flushInProgress = true;
+    try {
+      const res = await this._deps.sendBatch(
+        JSON.stringify(payload),
+        { keepalive: options.keepalive },
+      );
+
+      if (res.status === "error") {
+        captureWarning("SessionRecorder.flush", res.error);
+        return;
+      }
+
+      if (!res.data.ok) {
+        captureWarning("SessionRecorder.flush", new Error(`SessionRecorder flush failed: ${res.data.status} ${await res.data.text()}`));
+      }
+    } finally {
+      this._flushInProgress = false;
+    }
+  }
+
+  private async _startRecording() {
+    if (this._recording || this._cancelled) return;
+
+    if (!this._rrwebModule) {
+      const rrwebImport = await Result.fromPromise(import("rrweb"));
+      if (rrwebImport.status === "error") {
+        console.warn("SessionRecorder: rrweb import failed. Is rrweb installed?", rrwebImport.error);
+        return;
+      }
+      this._rrwebModule = rrwebImport.data;
+    }
+
+    // cancelled may change during the await above
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (this._cancelled) return;
+
+    this._stopRecording = this._rrwebModule.record({
+      emit: (event) => {
+        const nowMs = Date.now();
+        const stored = this._persistActivity(nowMs);
+
+        // Detect session rotation: after 3+ minutes idle, getOrRotateSession
+        // creates a new session ID. We need to inject a FullSnapshot so the
+        // new server-side SessionReplay record is playable.
+        if (this._lastBrowserSessionId === null) {
+          this._lastBrowserSessionId = stored.session_id;
+        } else if (stored.session_id !== this._lastBrowserSessionId && !this._takingSnapshot) {
+          this._lastBrowserSessionId = stored.session_id;
+          // Inject a FullSnapshot for the new session (calls emit synchronously)
+          this._takingSnapshot = true;
+          try {
+            this._rrwebModule!.record.takeFullSnapshot();
+          } finally {
+            this._takingSnapshot = false;
+          }
+        }
+
+        this._events.push(event);
+        this._approxBytes += JSON.stringify(event).length;
+        if (this._events.length >= MAX_EVENTS_PER_BATCH || this._approxBytes >= MAX_APPROX_BYTES_PER_BATCH) {
+          runAsynchronously(() => this._flush({ keepalive: false }));
+        }
+      },
+      maskAllInputs: this._replayOptions.maskAllInputs ?? true,
+      ...(this._replayOptions.blockClass !== undefined ? { blockClass: this._replayOptions.blockClass } : {}),
+      ...(this._replayOptions.blockSelector !== undefined ? { blockSelector: this._replayOptions.blockSelector } : {}),
+    }) ?? null;
+
+    this._recording = true;
+
+    const onPageHide = () => {
+      runAsynchronously(() => this._flush({ keepalive: true }));
+    };
+    window.addEventListener("pagehide", onPageHide);
+    document.addEventListener("visibilitychange", onPageHide);
+    this._detachListeners = () => {
+      window.removeEventListener("pagehide", onPageHide);
+      document.removeEventListener("visibilitychange", onPageHide);
+    };
+  }
+
+  private _stopCurrentRecording() {
+    if (this._detachListeners) {
+      this._detachListeners();
+      this._detachListeners = null;
+    }
+    if (this._stopRecording) {
+      this._stopRecording();
+      this._stopRecording = null;
+    }
+    this._events = [];
+    this._approxBytes = 0;
+    this._recording = false;
+  }
+
+  private _tick() {
+    if (this._cancelled) return;
+    if (this._events.length > 0) {
+      runAsynchronously(() => this._flush({ keepalive: false }));
+    }
+  }
+}

package/src/lib/hexclave-app/apps/index.ts

@@ -0,0 +1,40 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+export {
+  HexclaveClientApp,
+  StackClientApp
+} from "./interfaces/client-app";
+// HexclaveClientApp / StackClientApp are exported above as classes (TS treats classes as
+// both value + type), so only the helper types need a separate type-only re-export here.
+export type {
+  HexclaveClientAppConstructor,
+  HexclaveClientAppConstructorOptions,
+  HexclaveClientAppJson,
+  StackClientAppConstructor,
+  StackClientAppConstructorOptions,
+  StackClientAppJson
+} from "./interfaces/client-app";
+
+export {
+  HexclaveServerApp,
+  StackServerApp
+} from "./interfaces/server-app";
+export type {
+  HexclaveServerAppConstructor,
+  HexclaveServerAppConstructorOptions,
+  StackServerAppConstructor,
+  StackServerAppConstructorOptions
+} from "./interfaces/server-app";
+
+export {
+  HexclaveAdminApp,
+  StackAdminApp
+} from "./interfaces/admin-app";
+export type {
+  HexclaveAdminAppConstructor,
+  HexclaveAdminAppConstructorOptions,
+  StackAdminAppConstructor,
+  StackAdminAppConstructorOptions,
+} from "./interfaces/admin-app";