@blario/react-native 0.0.0 → 0.1.0

package/src/backend/backend-transport.ts

@@ -0,0 +1,338 @@
+import type { OutboundFrame } from '../agent/frames.ts';
+import { type RunMemory, StoredRunMemory } from '../agent-mode/run-memory.ts';
+import { isRecord } from '../fiber/narrow.ts';
+import { reportSdkError, setReportIdentityProvider, setReportPublishableKey } from '../telemetry/sdk-reporter.ts';
+import type { AgentTransport } from '../transport/transport.ts';
+import { ApiClient } from './api-client.ts';
+import { watchForeground } from './foreground.ts';
+import { ClientHealthProbe } from './health.ts';
+import type { BlarIdentity } from './identity.ts';
+import { PresenceManager } from './presence.ts';
+import { type SessionState, BackendSession } from './session.ts';
+import { watchSessionChanges } from './session-change.ts';
+import { SessionSocket, type SocketState } from './session-socket.ts';
+import { createDefaultStorage, type KeyValueStorage, MemoryStorage } from './storage.ts';
+import { getTabId } from './tab-id.ts';
+
+export interface BackendTransportOptions {
+  publishableKey: string;
+  apiBaseUrl: string;
+  user: BlarIdentity | null;
+  storage?: KeyValueStorage;
+  onSocketState?: (state: SocketState) => void;
+  onConnecting?: (sessionId: number) => void;
+  onSessionChanged?: () => void;
+  log?: (message: string) => void;
+}
+
+export interface WidgetProof {
+  identityToken?: string;
+  identitySignature?: string;
+}
+
+type FrameListener = (frame: Record<string, unknown>) => void;
+
+export class BackendTransport implements AgentTransport {
+  private readonly api: ApiClient;
+
+  private readonly session: BackendSession;
+
+  private readonly runMemory: StoredRunMemory;
+
+  private readonly health = new ClientHealthProbe();
+
+  private readonly presence: PresenceManager;
+
+  private readonly socket: SessionSocket;
+
+  private readonly tabId = getTabId();
+
+  private readonly frameListeners = new Set<FrameListener>();
+
+  private readonly identityListeners = new Set<() => void>();
+
+  private agentListener: ((raw: string) => void) | null = null;
+
+  private lastSeenSeq = 0;
+
+  private connectedKey: string | null = null;
+
+  private stopped = true;
+
+  private refreshing = false;
+
+  private initialUser: BlarIdentity | null;
+
+  private readonly log: (message: string) => void;
+
+  private readonly onConnecting: (sessionId: number) => void;
+
+  private booted: Promise<void> = Promise.resolve();
+
+  constructor(options: BackendTransportOptions) {
+    this.initialUser = options.user;
+    this.log = options.log ?? (() => undefined);
+    this.api = new ApiClient({ apiBaseUrl: options.apiBaseUrl, publishableKey: options.publishableKey });
+    const storage = options.storage ?? createDefaultStorage();
+    this.log(`storage ${storage instanceof MemoryStorage ? 'memory' : 'async-storage'}`);
+    this.session = new BackendSession(this.api, storage);
+    setReportPublishableKey(options.publishableKey);
+    setReportIdentityProvider(() => ({
+      sourceId: this.session.getState().sourceId,
+      sessionId: this.session.getState().sessionId,
+      userExternalId: this.getIdentity()?.externalId ?? null,
+    }));
+    this.runMemory = new StoredRunMemory(storage, `blar_agent_run_${options.publishableKey.slice(-8)}`, () => this.session.getState().sessionId);
+    this.onConnecting = options.onConnecting ?? (() => undefined);
+    watchSessionChanges((listener) => this.session.subscribe(listener), () => options.onSessionChanged?.());
+    this.presence = new PresenceManager(
+      this.api,
+      () => void this.refreshSession(),
+      (message) => this.log(message),
+    );
+    this.socket = new SessionSocket({
+      apiBaseUrl: options.apiBaseUrl,
+      publishableKey: options.publishableKey,
+      tabId: this.tabId,
+      getSourceId: () => this.api.getSourceId(),
+      getProof: () => this.api.getIdentityProof(),
+      refreshProof: () => this.api.refreshIdentityProof(),
+      getLastSeenSeq: () => this.lastSeenSeq,
+      onMessage: (raw, frame) => this.receive(raw, frame),
+      onState: (state) => {
+        this.log(`socket ${state}`);
+        options.onSocketState?.(state);
+      },
+      onIdentityRejected: () => void this.session.logout().then(() => this.connect()),
+      watchForeground,
+    });
+  }
+
+  onMessage(listener: (raw: string) => void): void {
+    this.agentListener = listener;
+  }
+
+  getRunMemory(): RunMemory {
+    return this.runMemory;
+  }
+
+  onFrame(listener: FrameListener): () => void {
+    this.frameListeners.add(listener);
+    return () => this.frameListeners.delete(listener);
+  }
+
+  onIdentityChange(listener: () => void): () => void {
+    this.identityListeners.add(listener);
+    return () => this.identityListeners.delete(listener);
+  }
+
+  start(): void {
+    this.stopped = false;
+    this.health.start();
+    this.booted = this.boot();
+  }
+
+  stop(): void {
+    this.stopped = true;
+    this.presence.stop();
+    this.health.stop();
+    this.socket.disconnect();
+    this.connectedKey = null;
+  }
+
+  async setUser(identity: BlarIdentity): Promise<void> {
+    await this.booted;
+    await this.session.setUser(identity);
+    await this.connect();
+    this.identityListeners.forEach((listener) => listener());
+  }
+
+  async logout(): Promise<void> {
+    await this.booted;
+    await this.session.logout();
+    await this.connect();
+    this.identityListeners.forEach((listener) => listener());
+  }
+
+  isConnected(): boolean {
+    return this.socket.isOpen();
+  }
+
+  async refreshSession(): Promise<void> {
+    if (this.stopped || this.refreshing) {
+      return;
+    }
+    this.refreshing = true;
+    try {
+      const previous = this.session.getState().sessionId;
+      const state = await this.session.refresh();
+      this.log(`refreshed session=${state.sessionId} (was ${previous})`);
+      if (state.sessionId !== null && state.sessionId !== previous) {
+        await this.connect();
+      }
+    } catch (error) {
+      this.log(`refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+      reportSdkError('BackendTransport.refreshSession', error);
+    } finally {
+      this.refreshing = false;
+    }
+  }
+
+  async switchSession(sessionId: number): Promise<void> {
+    this.session.adoptSession(sessionId);
+    await this.connect();
+  }
+
+  leaveSession(): void {
+    this.session.leaveSession();
+    this.socket.disconnect();
+    this.connectedKey = null;
+  }
+
+  async openNudge(): Promise<number | null> {
+    const sessionId = await this.api.openNudge(this.tabId);
+    this.log(`nudge open -> session=${sessionId}`);
+    return sessionId;
+  }
+
+  async dismissNudge(milestoneMessageId: number): Promise<void> {
+    await this.api.dismissNudge(milestoneMessageId);
+    this.log(`nudge dismissed milestone=${milestoneMessageId}`);
+  }
+
+  async snoozeNudge(milestoneMessageId: number): Promise<void> {
+    await this.api.snoozeNudge(milestoneMessageId);
+    this.log(`nudge snoozed milestone=${milestoneMessageId}`);
+  }
+
+  getState(): SessionState {
+    return this.session.getState();
+  }
+
+  getTabId(): string {
+    return this.tabId;
+  }
+
+  getIdentity(): BlarIdentity | null {
+    return this.api.getIdentity();
+  }
+
+  async readWidgetProof(): Promise<WidgetProof | null> {
+    const proof = await this.api.refreshIdentityProof();
+    if (proof === null) {
+      return null;
+    }
+    return proof.header === 'X-Identity-Token' ? { identityToken: proof.value } : { identitySignature: proof.value };
+  }
+
+  noteInteraction(): void {
+    this.presence.noteInteraction();
+  }
+
+  send(frame: OutboundFrame): void {
+    if (frame.type === 'pong') {
+      this.socket.send(JSON.stringify({ type: 'pong', client: this.health.take() }));
+      return;
+    }
+    if (frame.type === 'command_ack') {
+      this.socket.send(JSON.stringify(frame));
+      return;
+    }
+    if (frame.type === 'agent_cancel') {
+      this.log(`-> agent_cancel ${frame.reason}`);
+      this.socket.send(JSON.stringify(frame));
+      return;
+    }
+    this.log(`-> ${frame.type === 'sdk_response' ? frame.response_type : frame.type} ${frame.command_id}`);
+    if (frame.type === 'sdk_response' && frame.response_type === 'agent_command_response') {
+      this.log(`   ${JSON.stringify(frame.data)}`);
+    }
+    if (frame.type === 'sdk_response' && frame.response_type === 'dom_state_response') {
+      this.log(`\n${frame.data.html_snapshot}`);
+    }
+    this.socket.sendOrCache(frame.command_id, JSON.stringify({ ...frame, document_id: this.tabId }));
+  }
+
+  private async boot(): Promise<void> {
+    try {
+      await Promise.all([this.session.boot(this.initialUser), this.runMemory.load()]);
+    } catch (error) {
+      this.log(`boot failed: ${error instanceof Error ? error.message : String(error)}`);
+      reportSdkError('BackendTransport.boot', error);
+      return;
+    }
+    if (this.stopped) {
+      return;
+    }
+    const state = this.session.getState();
+    this.log(`booted source=${state.sourceId} session=${state.sessionId} identified=${state.identified}`);
+    this.presence.start();
+    await this.connect().catch((error: unknown) => {
+      this.log(`connect failed: ${error instanceof Error ? error.message : String(error)}`);
+      reportSdkError('BackendTransport.connect', error);
+    });
+  }
+
+  private async connect(): Promise<void> {
+    if (this.stopped) {
+      return;
+    }
+    const sessionId = await this.session.ensureSessionId();
+    if (this.stopped) {
+      return;
+    }
+    const sourceId = this.api.getSourceId();
+    if (sessionId === null || sourceId === null) {
+      return;
+    }
+    const key = `${sessionId}:${sourceId}`;
+    if (key === this.connectedKey && this.socket.isOpen()) {
+      return;
+    }
+    this.connectedKey = key;
+    this.lastSeenSeq = 0;
+    this.log(`connecting session=${sessionId} source=${sourceId}`);
+    this.onConnecting(sessionId);
+    this.socket.connect(sessionId);
+  }
+
+  private receive(raw: string, frame: Record<string, unknown> | null): void {
+    if (frame === null) {
+      this.agentListener?.(raw);
+      return;
+    }
+    if (frame.type === 'ping') {
+      this.send({ type: 'pong' });
+      return;
+    }
+    this.trackSequence(frame);
+    if (typeof frame.event === 'string') {
+      this.log(`<- ${frame.event} ${this.describeCommand(frame)}`);
+      this.agentListener?.(raw);
+      return;
+    }
+    this.frameListeners.forEach((listener) => listener(frame));
+  }
+
+  private describeCommand(frame: Record<string, unknown>): string {
+    const data = isRecord(frame.data) ? frame.data : {};
+    const action = isRecord(data.action) ? JSON.stringify(data.action) : '';
+    const target = isRecord(data.target) && typeof data.target.agent_id === 'string' ? data.target.agent_id : '';
+    const risk = typeof data.risk_level === 'string' ? `risk=${data.risk_level}` : '';
+    return `${action} ${target} ${risk}`.trim();
+  }
+
+  private trackSequence(frame: Record<string, unknown>): void {
+    const message = isRecord(frame.message) ? frame.message : null;
+    if (frame.type === 'message' && message !== null && typeof message.seq === 'number') {
+      this.lastSeenSeq = Math.max(this.lastSeenSeq, message.seq);
+    }
+    if (frame.type === 'history' && Array.isArray(frame.messages)) {
+      for (const entry of frame.messages) {
+        if (isRecord(entry) && typeof entry.seq === 'number') {
+          this.lastSeenSeq = Math.max(this.lastSeenSeq, entry.seq);
+        }
+      }
+    }
+  }
+}

package/src/backend/backoff.ts

@@ -0,0 +1,16 @@
+export interface BackoffPolicy {
+  baseMs: number;
+  decay: number;
+  maxMs: number;
+  maxAttempts: number;
+}
+
+export const SOCKET_BACKOFF: BackoffPolicy = { baseMs: 1000, decay: 1.5, maxMs: 30_000, maxAttempts: 10 };
+
+export function backoffDelay(policy: BackoffPolicy, attempt: number): number {
+  return Math.min(policy.baseMs * Math.pow(policy.decay, attempt), policy.maxMs);
+}
+
+export function isExhausted(policy: BackoffPolicy, attempt: number): boolean {
+  return attempt >= policy.maxAttempts;
+}

package/src/backend/base64.ts

@@ -0,0 +1,25 @@
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+export function decodeBase64Url(input: string): string | null {
+  const normalized = input.replace(/-/g, '+').replace(/_/g, '/').replace(/=+$/, '');
+  let buffer = 0;
+  let bits = 0;
+  const bytes: number[] = [];
+  for (const char of normalized) {
+    const value = ALPHABET.indexOf(char);
+    if (value < 0) {
+      return null;
+    }
+    buffer = (buffer << 6) | value;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push((buffer >> bits) & 0xff);
+    }
+  }
+  try {
+    return decodeURIComponent(bytes.map((byte) => `%${byte.toString(16).padStart(2, '0')}`).join(''));
+  } catch {
+    return String.fromCharCode(...bytes);
+  }
+}

package/src/backend/errors.ts

@@ -0,0 +1,32 @@
+export type ApiErrorKind = 'http' | 'network' | 'timeout';
+
+export class ApiRequestError extends Error {
+  readonly kind: ApiErrorKind;
+
+  readonly status: number;
+
+  readonly code: string | null;
+
+  readonly endpoint: string;
+
+  constructor(options: { kind: ApiErrorKind; endpoint: string; status?: number; code?: string | null; message: string }) {
+    super(options.message);
+    this.name = 'ApiRequestError';
+    this.kind = options.kind;
+    this.endpoint = options.endpoint;
+    this.status = options.status ?? 0;
+    this.code = options.code ?? null;
+  }
+
+  static http(endpoint: string, status: number, statusText: string, code: string | null): ApiRequestError {
+    return new ApiRequestError({ kind: 'http', endpoint, status, code, message: `${endpoint} responded ${status} ${statusText}` });
+  }
+
+  static transport(endpoint: string, kind: 'network' | 'timeout'): ApiRequestError {
+    return new ApiRequestError({ kind, endpoint, message: `${endpoint} failed: ${kind}` });
+  }
+}
+
+export function isIdentityRejection(error: unknown): error is ApiRequestError {
+  return error instanceof ApiRequestError && error.kind === 'http' && (error.status === 401 || error.status === 403);
+}

package/src/backend/foreground.ts

@@ -0,0 +1,10 @@
+import { AppState } from 'react-native';
+
+export function watchForeground(onActive: () => void): () => void {
+  const subscription = AppState.addEventListener('change', (state) => {
+    if (state === 'active') {
+      onActive();
+    }
+  });
+  return () => subscription.remove();
+}

package/src/backend/health.ts

@@ -0,0 +1,64 @@
+import { AppState, type AppStateStatus, type NativeEventSubscription } from 'react-native';
+
+import { SDK_VERSION } from '../version.ts';
+
+export interface ClientHealth {
+  visibility: 'visible' | 'hidden';
+  hidden_ms: number;
+  lag_ms: number;
+  sdk_version: string;
+}
+
+const PROBE_INTERVAL_MS = 1000;
+
+export class ClientHealthProbe {
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  private subscription: NativeEventSubscription | null = null;
+
+  private expectedTickAt = 0;
+
+  private worstLagMs = 0;
+
+  private hiddenSince: number | null = null;
+
+  start(): void {
+    if (this.timer !== null) {
+      return;
+    }
+    this.hiddenSince = AppState.currentState === 'active' ? null : Date.now();
+    this.subscription = AppState.addEventListener('change', (state) => this.onStateChange(state));
+    this.expectedTickAt = Date.now() + PROBE_INTERVAL_MS;
+    this.timer = setInterval(() => {
+      const now = Date.now();
+      this.worstLagMs = Math.max(this.worstLagMs, now - this.expectedTickAt);
+      this.expectedTickAt = now + PROBE_INTERVAL_MS;
+    }, PROBE_INTERVAL_MS);
+  }
+
+  stop(): void {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.subscription?.remove();
+    this.subscription = null;
+    this.worstLagMs = 0;
+    this.hiddenSince = null;
+  }
+
+  take(): ClientHealth {
+    const lag = this.worstLagMs;
+    this.worstLagMs = 0;
+    return {
+      visibility: this.hiddenSince === null ? 'visible' : 'hidden',
+      hidden_ms: this.hiddenSince === null ? 0 : Date.now() - this.hiddenSince,
+      lag_ms: Math.max(0, Math.round(lag)),
+      sdk_version: SDK_VERSION,
+    };
+  }
+
+  private onStateChange(state: AppStateStatus): void {
+    this.hiddenSince = state === 'active' ? null : (this.hiddenSince ?? Date.now());
+  }
+}

package/src/backend/identity-proof.ts

@@ -0,0 +1,151 @@
+import { isRecord } from '../fiber/narrow.ts';
+import { decodeBase64Url } from './base64.ts';
+import type { BlarIdentity, IdentityProof, IdentityRefusalReason } from './identity.ts';
+
+const REFRESH_MARGIN_MS = 60_000;
+
+type MintFailure = 'provider_failed' | 'subject_mismatch';
+
+function tokenProof(value: string): IdentityProof {
+  if (typeof value !== 'string' || value !== value.trim() || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(value)) {
+    throw new Error('invalid identity token');
+  }
+  return { header: 'X-Identity-Token', value, protocol: `blar-identity-token.${value}` };
+}
+
+function signatureProof(value: string): IdentityProof {
+  if (typeof value !== 'string' || value !== value.trim() || !/^[A-Fa-f0-9]+$/.test(value)) {
+    throw new Error('invalid identity signature');
+  }
+  return { header: 'X-Identity-Signature', value, protocol: `blar-identity-signature.${value}` };
+}
+
+export function readJwtExpiry(token: string): number | null {
+  const payload = token.split('.')[1];
+  if (payload === undefined) {
+    return null;
+  }
+  try {
+    const decoded = decodeBase64Url(payload);
+    const claims: unknown = decoded === null ? null : JSON.parse(decoded);
+    return isRecord(claims) && typeof claims.exp === 'number' ? claims.exp * 1000 : null;
+  } catch {
+    return null;
+  }
+}
+
+export class IdentityProofStore {
+  private identity: BlarIdentity | null = null;
+
+  private cached: IdentityProof | null = null;
+
+  private expiresAt: number | null = null;
+
+  private inFlight: Promise<IdentityProof | null> | null = null;
+
+  private mintFailure: MintFailure | null = null;
+
+  constructor(private readonly now: () => number = () => Date.now()) {}
+
+  setIdentity(identity: BlarIdentity | null): void {
+    this.identity = identity;
+    this.cached = null;
+    this.expiresAt = null;
+    this.inFlight = null;
+    this.mintFailure = null;
+  }
+
+  getIdentity(): BlarIdentity | null {
+    return this.identity;
+  }
+
+  hasIdentity(): boolean {
+    return this.identity !== null;
+  }
+
+  canRefresh(): boolean {
+    const identity = this.identity;
+    return identity !== null && Boolean(identity.getProof ?? identity.getIdentityToken ?? identity.getIdentitySignature);
+  }
+
+  refusalReason(): IdentityRefusalReason {
+    if (this.mintFailure !== null) {
+      return this.mintFailure;
+    }
+    if (this.cached === null && this.canRefresh()) {
+      return 'provider_failed';
+    }
+    if (!this.canRefresh() && this.expiresAt !== null && this.expiresAt <= this.now()) {
+      return 'static_token_expired';
+    }
+    return 'identify_refused';
+  }
+
+  get(options?: { refresh?: boolean }): Promise<IdentityProof | null> {
+    if (this.identity === null) {
+      return Promise.resolve(null);
+    }
+    const expiring = this.expiresAt !== null && this.expiresAt - this.now() <= REFRESH_MARGIN_MS;
+    if (this.cached !== null && options?.refresh !== true && !expiring) {
+      return Promise.resolve(this.cached);
+    }
+    if (this.cached !== null && !this.canRefresh()) {
+      return Promise.resolve(this.cached);
+    }
+    if (this.inFlight === null) {
+      this.inFlight = this.mint().finally(() => {
+        this.inFlight = null;
+      });
+    }
+    return this.inFlight;
+  }
+
+  private async mint(): Promise<IdentityProof | null> {
+    const identity = this.identity;
+    if (identity === null) {
+      return null;
+    }
+    this.mintFailure = null;
+    try {
+      if (identity.getProof !== undefined) {
+        return this.fromProviderProof(identity, await identity.getProof());
+      }
+      const token = identity.getIdentityToken !== undefined ? await identity.getIdentityToken() : identity.identityToken;
+      if (token !== undefined && token !== '') {
+        return this.storeToken(token);
+      }
+      const signature = identity.getIdentitySignature !== undefined ? await identity.getIdentitySignature() : identity.identitySignature;
+      return this.storeSignature(signature);
+    } catch {
+      this.mintFailure = this.mintFailure ?? 'provider_failed';
+      this.cached = null;
+      return null;
+    }
+  }
+
+  private fromProviderProof(
+    identity: BlarIdentity,
+    proof: { externalId?: string; identityToken?: string; identitySignature?: string },
+  ): IdentityProof | null {
+    if (proof.externalId !== undefined && proof.externalId !== identity.externalId) {
+      this.mintFailure = 'subject_mismatch';
+      throw new Error('identity proof subject mismatch');
+    }
+    if (proof.identityToken !== undefined && proof.identityToken !== '') {
+      return this.storeToken(proof.identityToken);
+    }
+    return this.storeSignature(proof.identitySignature);
+  }
+
+  private storeToken(token: string): IdentityProof {
+    this.cached = tokenProof(token);
+    this.expiresAt = readJwtExpiry(token);
+    return this.cached;
+  }
+
+  private storeSignature(signature: string | undefined): IdentityProof | null {
+    this.cached = signature !== undefined && signature !== '' ? signatureProof(signature) : null;
+    this.expiresAt = null;
+    return this.cached;
+  }
+}

package/src/backend/identity.ts

@@ -0,0 +1,31 @@
+export interface BlarIdentityProofInput {
+  externalId?: string;
+  identityToken?: string;
+  identitySignature?: string;
+}
+
+export type CustomFields = Record<string, string | number | boolean>;
+
+export interface BlarIdentity {
+  externalId: string;
+  email?: string;
+  name?: string;
+  phone?: string;
+  contactCompany?: string;
+  contactCompanyExternalId?: string;
+  country?: string;
+  identityToken?: string;
+  identitySignature?: string;
+  getProof?: () => Promise<BlarIdentityProofInput>;
+  getIdentityToken?: () => Promise<string>;
+  getIdentitySignature?: () => Promise<string>;
+  customFields?: CustomFields;
+}
+
+export interface IdentityProof {
+  header: 'X-Identity-Token' | 'X-Identity-Signature';
+  value: string;
+  protocol: string;
+}
+
+export type IdentityRefusalReason = 'provider_failed' | 'static_token_expired' | 'identify_refused' | 'subject_mismatch';

package/src/backend/message-metadata.ts

@@ -0,0 +1,28 @@
+import type { TextDomResponseData } from '../agent/frames.ts';
+import type { Size } from '../host/rect.ts';
+import type { AppInfo } from './app-info.ts';
+
+export interface MessageMetadata extends AppInfo {
+  url: string;
+  tab_id: string;
+  debug_context: { viewport: Size };
+  text_dom?: TextDomResponseData;
+}
+
+export interface MessageMetadataInput {
+  screen: string;
+  tabId: string;
+  viewport: Size;
+  appInfo: AppInfo;
+  textDom: TextDomResponseData | null;
+}
+
+export function buildMessageMetadata(input: MessageMetadataInput): MessageMetadata {
+  return {
+    ...input.appInfo,
+    url: input.screen,
+    tab_id: input.tabId,
+    debug_context: { viewport: input.viewport },
+    ...(input.textDom === null ? {} : { text_dom: input.textDom }),
+  };
+}