@blario/react-native 0.0.0-stage → 0.1.0

package/src/backend/presence.ts

@@ -0,0 +1,95 @@
+import { AppState, type NativeEventSubscription } from 'react-native';
+
+import type { ApiClient } from './api-client.ts';
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const IDLE_TIMEOUT_MS = 3 * 60_000;
+
+export class PresenceManager {
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  private subscription: NativeEventSubscription | null = null;
+
+  private lastInteraction = 0;
+
+  private inFlight = false;
+
+  private started = false;
+
+  constructor(
+    private readonly api: ApiClient,
+    private readonly onPendingNudge: () => void = () => undefined,
+    private readonly log: (message: string) => void = () => undefined,
+    private readonly now: () => number = () => Date.now(),
+  ) {}
+
+  start(): void {
+    if (this.started) {
+      return;
+    }
+    this.started = true;
+    this.lastInteraction = this.now();
+    this.subscription = AppState.addEventListener('change', (state) => {
+      if (state === 'active') {
+        this.lastInteraction = this.now();
+        this.fireNow();
+      }
+    });
+    this.fireNow();
+  }
+
+  stop(): void {
+    this.started = false;
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    this.subscription?.remove();
+    this.subscription = null;
+  }
+
+  noteInteraction(): void {
+    const wasIdle = !this.isPresent();
+    this.lastInteraction = this.now();
+    if (wasIdle && this.started) {
+      this.fireNow();
+    }
+  }
+
+  isPresent(): boolean {
+    return AppState.currentState === 'active' && this.now() - this.lastInteraction <= IDLE_TIMEOUT_MS;
+  }
+
+  private fireNow(): void {
+    if (this.isPresent()) {
+      void this.send();
+    }
+    this.scheduleNext();
+  }
+
+  private scheduleNext(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+    }
+    this.timer = setTimeout(() => this.fireNow(), HEARTBEAT_INTERVAL_MS);
+  }
+
+  private async send(): Promise<void> {
+    if (this.inFlight || this.api.getSourceId() === null || !this.started) {
+      return;
+    }
+    this.inFlight = true;
+    try {
+      const response = await this.api.heartbeat();
+      this.log(`heartbeat ok pending_nudge=${response.hasPendingNudge}`);
+      if (response.hasPendingNudge) {
+        this.onPendingNudge();
+      }
+    } catch (error) {
+      this.log(`heartbeat failed: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    } finally {
+      this.inFlight = false;
+    }
+  }
+}

package/src/backend/response-cache.ts

@@ -0,0 +1,45 @@
+const CACHE_LIMIT = 50;
+const CACHE_TTL_MS = 60_000;
+
+interface CachedFrame {
+  payload: string;
+  storedAt: number;
+}
+
+export class ResponseCache {
+  private readonly frames = new Map<string, CachedFrame>();
+
+  constructor(private readonly now: () => number = () => Date.now()) {}
+
+  store(commandId: string, payload: string): void {
+    this.sweep();
+    this.frames.set(commandId, { payload, storedAt: this.now() });
+    while (this.frames.size > CACHE_LIMIT) {
+      const oldest = this.frames.keys().next().value;
+      if (oldest === undefined) {
+        break;
+      }
+      this.frames.delete(oldest);
+    }
+  }
+
+  clear(): void {
+    this.frames.clear();
+  }
+
+  drain(): string[] {
+    this.sweep();
+    const payloads = [...this.frames.values()].map((frame) => frame.payload);
+    this.frames.clear();
+    return payloads;
+  }
+
+  private sweep(): void {
+    const expiry = this.now() - CACHE_TTL_MS;
+    for (const [commandId, frame] of this.frames) {
+      if (frame.storedAt < expiry) {
+        this.frames.delete(commandId);
+      }
+    }
+  }
+}

package/src/backend/session-change.ts

@@ -0,0 +1,14 @@
+import type { SessionState } from './session.ts';
+
+export function watchSessionChanges(subscribe: (listener: (state: SessionState) => void) => () => void, onChanged: () => void): () => void {
+  let known: number | null = null;
+  return subscribe(({ sessionId }) => {
+    if (sessionId === null) {
+      return;
+    }
+    if (known !== null && sessionId !== known) {
+      onChanged();
+    }
+    known = sessionId;
+  });
+}

package/src/backend/session-socket.ts

@@ -0,0 +1,292 @@
+import { isRecord } from '../fiber/narrow.ts';
+import { backoffDelay, isExhausted, SOCKET_BACKOFF } from './backoff.ts';
+import type { IdentityProof } from './identity.ts';
+import { ResponseCache } from './response-cache.ts';
+import { buildSocketUrl } from './socket-url.ts';
+
+export type SocketState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'failed';
+
+export interface SessionSocketOptions {
+  apiBaseUrl: string;
+  publishableKey: string;
+  tabId: string;
+  getSourceId: () => string | null;
+  getProof: () => Promise<IdentityProof | null> | null;
+  refreshProof: () => Promise<IdentityProof | null>;
+  getLastSeenSeq: () => number;
+  onMessage: (raw: string, frame: Record<string, unknown> | null) => void;
+  onState: (state: SocketState) => void;
+  onIdentityRejected: () => void;
+  watchForeground: (onActive: () => void) => () => void;
+}
+
+const IDENTITY_REJECTED_CLOSE_CODE = 4001;
+const STALE_CLOSE_CODE = 1006;
+const STALE_AFTER_MS = 45_000;
+const LIVENESS_CHECK_MS = 5_000;
+const EXHAUSTED_RETRY_MS = 60_000;
+
+function parseFrame(raw: string): Record<string, unknown> | null {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export class SessionSocket {
+  private socket: WebSocket | null = null;
+
+  private sessionId: number | null = null;
+
+  private epoch = 0;
+
+  private attempts = 0;
+
+  private intentionallyClosed = true;
+
+  private identityRefreshUsed = false;
+
+  private exhausted = false;
+
+  private lastFrameAt = 0;
+
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  private livenessTimer: ReturnType<typeof setInterval> | null = null;
+
+  private stopWatchingForeground: (() => void) | null = null;
+
+  private readonly cache = new ResponseCache();
+
+  private cacheScope: string | null = null;
+
+  constructor(private readonly options: SessionSocketOptions) {}
+
+  connect(sessionId: number): void {
+    const scope = `${sessionId}:${this.options.getSourceId() ?? ''}`;
+    if (scope !== this.cacheScope) {
+      this.cache.clear();
+      this.cacheScope = scope;
+    }
+    this.sessionId = sessionId;
+    this.intentionallyClosed = false;
+    this.epoch += 1;
+    this.clearTimers();
+    this.discardSocket();
+    this.watchForeground();
+    this.options.onState(this.attempts === 0 ? 'connecting' : 'reconnecting');
+    const epoch = this.epoch;
+    const pending = this.options.getProof();
+    if (pending === null) {
+      this.open(epoch, null);
+      return;
+    }
+    void pending
+      .catch(() => null)
+      .then((proof) => {
+        if (this.epoch === epoch && !this.intentionallyClosed) {
+          this.open(epoch, proof);
+        }
+      });
+  }
+
+  disconnect(): void {
+    this.intentionallyClosed = true;
+    this.epoch += 1;
+    this.clearTimers();
+    this.stopWatchingForeground?.();
+    this.stopWatchingForeground = null;
+    this.discardSocket();
+    this.attempts = 0;
+    this.options.onState('disconnected');
+  }
+
+  isOpen(): boolean {
+    return this.socket !== null && this.socket.readyState === WebSocket.OPEN;
+  }
+
+  send(payload: string): boolean {
+    if (!this.isOpen()) {
+      return false;
+    }
+    this.socket?.send(payload);
+    return true;
+  }
+
+  sendOrCache(commandId: string, payload: string): void {
+    if (!this.send(payload)) {
+      this.cache.store(commandId, payload);
+    }
+  }
+
+  private open(epoch: number, proof: IdentityProof | null): void {
+    const sourceId = this.options.getSourceId();
+    if (this.sessionId === null || sourceId === null) {
+      this.options.onState('failed');
+      return;
+    }
+    let socket: WebSocket;
+    try {
+      const url = buildSocketUrl({
+        apiBaseUrl: this.options.apiBaseUrl,
+        sessionId: this.sessionId,
+        publishableKey: this.options.publishableKey,
+        sourceId,
+        tabId: this.options.tabId,
+        lastSeenSeq: this.options.getLastSeenSeq(),
+      });
+      if (url === null || (proof !== null && (proof.protocol !== proof.protocol.trim() || !/^[!#$%&'*+.^_`|~a-z0-9-]+$/i.test(proof.protocol)))) {
+        this.disconnect();
+        this.options.onState('failed');
+        return;
+      }
+      socket = proof === null ? new WebSocket(url) : new WebSocket(url, [proof.protocol]);
+    } catch {
+      this.disconnect();
+      this.options.onState('failed');
+      return;
+    }
+    this.socket = socket;
+    socket.onopen = () => {
+      if (this.epoch !== epoch) {
+        return;
+      }
+      this.attempts = 0;
+      this.exhausted = false;
+      this.startLiveness();
+      this.options.onState('connected');
+      socket.send(JSON.stringify({ type: 'joined' }));
+      this.cache.drain().forEach((payload) => socket.send(payload));
+    };
+    socket.onmessage = (event) => {
+      if (this.epoch !== epoch || typeof event.data !== 'string') {
+        return;
+      }
+      this.lastFrameAt = Date.now();
+      const frame = parseFrame(event.data);
+      if (frame?.type === 'history') {
+        this.identityRefreshUsed = false;
+      }
+      this.options.onMessage(event.data, frame);
+    };
+    socket.onerror = () => undefined;
+    socket.onclose = (event) => {
+      if (this.epoch === epoch) {
+        this.handleClose(epoch, event.code ?? STALE_CLOSE_CODE);
+      }
+    };
+  }
+
+  private handleClose(epoch: number, code: number): void {
+    this.stopLiveness();
+    this.options.onState('disconnected');
+    if (this.intentionallyClosed) {
+      return;
+    }
+    if (code === IDENTITY_REJECTED_CLOSE_CODE) {
+      this.handleIdentityRejection(epoch);
+      return;
+    }
+    this.scheduleReconnect();
+  }
+
+  private handleIdentityRejection(epoch: number): void {
+    if (this.identityRefreshUsed) {
+      this.options.onState('failed');
+      this.options.onIdentityRejected();
+      return;
+    }
+    this.identityRefreshUsed = true;
+    void this.options.refreshProof().finally(() => {
+      if (this.epoch === epoch && !this.intentionallyClosed) {
+        this.scheduleReconnect();
+      }
+    });
+  }
+
+  private scheduleReconnect(): void {
+    if (isExhausted(SOCKET_BACKOFF, this.attempts)) {
+      this.options.onState('failed');
+      this.exhausted = true;
+      this.reconnectTimer = setTimeout(() => this.recover(), EXHAUSTED_RETRY_MS);
+      return;
+    }
+    const delay = backoffDelay(SOCKET_BACKOFF, this.attempts);
+    this.options.onState('reconnecting');
+    this.reconnectTimer = setTimeout(() => {
+      this.attempts += 1;
+      if (this.sessionId !== null) {
+        this.connect(this.sessionId);
+      }
+    }, delay);
+  }
+
+  private recover(): void {
+    if (!this.exhausted || this.intentionallyClosed || this.sessionId === null) {
+      return;
+    }
+    this.attempts = 0;
+    this.connect(this.sessionId);
+  }
+
+  private watchForeground(): void {
+    if (this.stopWatchingForeground === null) {
+      this.stopWatchingForeground = this.options.watchForeground(() => this.recover());
+    }
+  }
+
+  private startLiveness(): void {
+    this.stopLiveness();
+    this.lastFrameAt = Date.now();
+    this.livenessTimer = setInterval(() => {
+      if (Date.now() - this.lastFrameAt >= STALE_AFTER_MS) {
+        this.dropStaleSocket();
+      }
+    }, LIVENESS_CHECK_MS);
+  }
+
+  private stopLiveness(): void {
+    if (this.livenessTimer !== null) {
+      clearInterval(this.livenessTimer);
+      this.livenessTimer = null;
+    }
+  }
+
+  private dropStaleSocket(): void {
+    const socket = this.socket;
+    if (socket === null || this.intentionallyClosed) {
+      return;
+    }
+    this.detach(socket);
+    socket.close();
+    this.socket = null;
+    this.handleClose(this.epoch, STALE_CLOSE_CODE);
+  }
+
+  private discardSocket(): void {
+    const socket = this.socket;
+    this.detach(socket);
+    socket?.close(1000, 'Client disconnected');
+    this.socket = null;
+  }
+
+  private detach(socket: WebSocket | null): void {
+    if (socket === null) {
+      return;
+    }
+    socket.onopen = null;
+    socket.onmessage = null;
+    socket.onerror = null;
+    socket.onclose = null;
+  }
+
+  private clearTimers(): void {
+    this.stopLiveness();
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+}

package/src/backend/session.ts

@@ -0,0 +1,188 @@
+import type { ApiClient } from './api-client.ts';
+import type { BootstrapResponse, IdentifyRequest } from './api-types.ts';
+import type { BlarIdentity, IdentityRefusalReason } from './identity.ts';
+import type { KeyValueStorage } from './storage.ts';
+
+export interface SessionState {
+  sourceId: string | null;
+  sessionId: number | null;
+  conversationId: number | null;
+  aiActive: boolean;
+  identified: boolean;
+  isIdentityVerified: boolean;
+}
+
+type Listener = (state: SessionState) => void;
+
+const EMPTY_STATE: SessionState = {
+  sourceId: null,
+  sessionId: null,
+  conversationId: null,
+  aiActive: true,
+  identified: false,
+  isIdentityVerified: false,
+};
+
+function storageKeyFor(publishableKey: string): string {
+  return `blar_source_id_${publishableKey.slice(-8)}`;
+}
+
+function buildIdentifyRequest(identity: BlarIdentity): IdentifyRequest {
+  return {
+    external_id: identity.externalId,
+    ...(identity.email === undefined ? {} : { email: identity.email }),
+    ...(identity.name === undefined ? {} : { name: identity.name }),
+    ...(identity.phone === undefined ? {} : { phone: identity.phone }),
+    ...(identity.contactCompany === undefined ? {} : { contact_company: identity.contactCompany }),
+    ...(identity.contactCompanyExternalId === undefined ? {} : { contact_company_external_id: identity.contactCompanyExternalId }),
+    ...(identity.country === undefined ? {} : { country: identity.country }),
+    ...(identity.customFields === undefined ? {} : { custom_fields: identity.customFields }),
+  };
+}
+
+export class BackendSession {
+  private state: SessionState = EMPTY_STATE;
+
+  private readonly listeners = new Set<Listener>();
+
+  private restoring: Promise<string | null> | null = null;
+
+  private readonly storageKey: string;
+
+  constructor(
+    private readonly api: ApiClient,
+    private readonly storage: KeyValueStorage,
+  ) {
+    this.storageKey = storageKeyFor(api.getPublishableKey());
+    api.setHooks({
+      restoreSource: () => this.restoreSession(),
+      onIdentityRefused: (reason) => void this.fallBackToAnonymous(reason),
+    });
+  }
+
+  getState(): SessionState {
+    return this.state;
+  }
+
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  async boot(identity: BlarIdentity | null): Promise<void> {
+    this.api.setIdentity(identity);
+    const stored = await this.storage.getItem(this.storageKey);
+    this.api.setSourceId(stored);
+    if (identity === null || stored === null) {
+      await this.loadAnonymous();
+    }
+    if (identity !== null) {
+      await this.identify(identity).catch(() => this.api.setIdentity(null));
+    }
+  }
+
+  async setUser(identity: BlarIdentity): Promise<void> {
+    this.api.setIdentity(identity);
+    if (this.api.getSourceId() === null) {
+      await this.loadAnonymous();
+    }
+    await this.identify(identity);
+  }
+
+  private async identify(identity: BlarIdentity): Promise<void> {
+    try {
+      this.apply(await this.api.identifyUser(buildIdentifyRequest(identity)), true);
+    } catch (error) {
+      this.api.setIdentity(null);
+      if (this.api.getSourceId() === null) {
+        await this.restoreSession();
+      }
+      throw error;
+    }
+  }
+
+  async logout(): Promise<void> {
+    this.api.setIdentity(null);
+    await this.dropSource();
+    await this.loadAnonymous();
+  }
+
+  async refresh(): Promise<SessionState> {
+    await this.loadAnonymous();
+    const identity = this.api.getIdentity();
+    if (identity !== null) {
+      await this.identify(identity).catch(() => undefined);
+    }
+    return this.state;
+  }
+
+  adoptSession(sessionId: number): void {
+    this.update({ ...this.state, sessionId });
+  }
+
+  leaveSession(): void {
+    this.update({ ...this.state, sessionId: null });
+  }
+
+  async ensureSessionId(): Promise<number | null> {
+    if (this.state.sessionId !== null) {
+      return this.state.sessionId;
+    }
+    const sessionId = await this.api.createSession();
+    this.update({ ...this.state, sessionId });
+    return sessionId;
+  }
+
+  private async loadAnonymous(): Promise<void> {
+    this.apply(await this.api.loadSession(this.api.getSourceId()), false);
+  }
+
+  private restoreSession(): Promise<string | null> {
+    this.restoring = this.restoring ?? this.restore().finally(() => {
+      this.restoring = null;
+    });
+    return this.restoring;
+  }
+
+  private async restore(): Promise<string | null> {
+    const identity = this.api.getIdentity();
+    try {
+      await this.loadAnonymous();
+      if (identity !== null) {
+        await this.setUser(identity).catch(() => undefined);
+      }
+      return this.api.getSourceId();
+    } catch {
+      return null;
+    }
+  }
+
+  private async fallBackToAnonymous(_reason: IdentityRefusalReason): Promise<void> {
+    this.api.setIdentity(null);
+    await this.dropSource();
+  }
+
+  private async dropSource(): Promise<void> {
+    this.api.setSourceId(null);
+    await this.storage.removeItem(this.storageKey);
+    this.update(EMPTY_STATE);
+  }
+
+  private apply(bootstrap: BootstrapResponse, identified: boolean): void {
+    this.api.setSourceId(bootstrap.sourceId);
+    void this.storage.setItem(this.storageKey, bootstrap.sourceId);
+    this.update({
+      sourceId: bootstrap.sourceId,
+      sessionId: bootstrap.sessionId,
+      conversationId: bootstrap.conversationId,
+      aiActive: bootstrap.aiActive,
+      identified,
+      isIdentityVerified: bootstrap.isIdentityVerified,
+    });
+  }
+
+  private update(next: SessionState): void {
+    this.state = next;
+    this.listeners.forEach((listener) => listener(next));
+  }
+}

package/src/backend/socket-url.ts

@@ -0,0 +1,25 @@
+import { normalizeApiBaseUrl } from '../transport/connection-options.ts';
+
+export interface SocketUrlParts {
+  apiBaseUrl: string;
+  sessionId: number;
+  publishableKey: string;
+  sourceId: string;
+  tabId: string;
+  lastSeenSeq: number;
+}
+
+export function buildSocketUrl(parts: SocketUrlParts): string | null {
+  const normalized = normalizeApiBaseUrl(parts.apiBaseUrl);
+  if (normalized === null) {
+    return null;
+  }
+  const base = normalized.replace(/^http/, 'ws');
+  const query = [
+    `publishable_key=${encodeURIComponent(parts.publishableKey)}`,
+    `source_id=${encodeURIComponent(parts.sourceId)}`,
+    `tab_id=${encodeURIComponent(parts.tabId)}`,
+    ...(parts.lastSeenSeq > 0 ? [`last_seen_seq=${parts.lastSeenSeq}`] : []),
+  ];
+  return `${base}/sessions/chat/${parts.sessionId}/?${query.join('&')}`;
+}

package/src/backend/storage.ts

@@ -0,0 +1,49 @@
+import { isFunction, isRecord } from '../fiber/narrow.ts';
+
+export interface KeyValueStorage {
+  getItem: (key: string) => Promise<string | null>;
+  setItem: (key: string, value: string) => Promise<void>;
+  removeItem: (key: string) => Promise<void>;
+}
+
+declare const require: (moduleName: string) => unknown;
+
+class MemoryStorage implements KeyValueStorage {
+  private readonly values = new Map<string, string>();
+
+  getItem(key: string): Promise<string | null> {
+    return Promise.resolve(this.values.get(key) ?? null);
+  }
+
+  setItem(key: string, value: string): Promise<void> {
+    this.values.set(key, value);
+    return Promise.resolve();
+  }
+
+  removeItem(key: string): Promise<void> {
+    this.values.delete(key);
+    return Promise.resolve();
+  }
+}
+
+function isKeyValueStorage(value: unknown): value is KeyValueStorage {
+  return isRecord(value) && isFunction(value.getItem) && isFunction(value.setItem) && isFunction(value.removeItem);
+}
+
+function loadAsyncStorage(): KeyValueStorage | null {
+  try {
+    const loaded = require('@react-native-async-storage/async-storage');
+    const candidate = isRecord(loaded) && 'default' in loaded ? loaded.default : loaded;
+    return isKeyValueStorage(candidate) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+const ASYNC_STORAGE = loadAsyncStorage();
+
+export function createDefaultStorage(): KeyValueStorage {
+  return ASYNC_STORAGE ?? new MemoryStorage();
+}
+
+export { MemoryStorage };