@possibl/rcrt-sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,103 @@
+/**
+ * @possibl/rcrt-sdk — TypeScript SDK for RCRT.
+ *
+ * Public surface. Anything not re-exported here is internal.
+ */
+
+// Primary entry
+export { RcrtClient } from './client.js';
+export type { RcrtClientConfig } from './client.js';
+
+// Auth
+export { staticTokenProvider } from './auth.js';
+export type { TokenProvider } from './auth.js';
+
+// Errors
+export { ApiError, SdkError } from './errors.js';
+export type { ApiErrorDetail, KnownErrorCode } from './errors.js';
+
+// Modules (handy if consumers want the types directly)
+export { BreadcrumbsModule } from './breadcrumbs.js';
+export { ChatModule } from './chat.js';
+export { CardsModule } from './cards.js';
+export { GrantsModule } from './grants.js';
+export { IdentityModule } from './authn.js';
+export { FilesModule } from './files.js';
+export { SessionsModule } from './sessions.js';
+export { CapabilitiesModule } from './capabilities.js';
+export type {
+  MeResponse,
+  Tenant,
+  PendingInvitation,
+  UserProfileBreadcrumb,
+} from './authn.js';
+export type { SendChatRequest, SendChatResponse, SseStreamOptions } from './chat.js';
+export type {
+  ServiceGrantSummary,
+  InitiateAuthRequest,
+  InitiateAuthResponse,
+  GrantType,
+  GrantStatus,
+} from './grants.js';
+export type { FileScope, UploadFileOptions, ListFilesOptions } from './files.js';
+export type {
+  SessionParticipant,
+  ConstellationData,
+  ConstellationNode,
+  ConstellationEdge,
+} from './sessions.js';
+export type { CapabilityType, ChattableAgent } from './capabilities.js';
+
+// Types — breadcrumbs
+export type {
+  Actor,
+  ActorType,
+  Breadcrumb,
+  BreadcrumbResponse,
+  CreateBreadcrumbRequest,
+  UpdateBreadcrumbRequest,
+  QueryByTagsOptions,
+  SemanticSearchOptions,
+} from './types/breadcrumb.js';
+
+// Types — JIT UI cards
+export type {
+  Card,
+  CardLayout,
+  CardHeader,
+  CardBody,
+  CardFooter,
+  CardAction,
+  ActionStyle,
+  Row,
+  TextRow,
+  FlexibleTextRow,
+  ClaimRow,
+  MetricRow,
+  EventRow,
+  PersonRow,
+  PlaceRow,
+  ToggleRow,
+  DraftPreviewRow,
+  ChartRow,
+  ChartSpec,
+  TrendDirection,
+  DraftPreview,
+  InputSpec,
+  RatingSpec,
+  ProgressState,
+  ConnectDetails,
+  CompareColumn,
+  ResolveRequest,
+  CanonicalStatus,
+} from './types/card.js';
+
+// SSE primitives (useful for custom consumers)
+export type {
+  SseConnection,
+  SseHandlers,
+  SseDelta,
+  SseThought,
+  SseAction,
+  SseError,
+} from './internal/sse.js';

package/src/internal/fetch.ts

@@ -0,0 +1,133 @@
+/**
+ * Internal HTTP helper. Handles:
+ *   - auth + tenant headers
+ *   - JSON encoding + parsing
+ *   - error envelope normalisation
+ *   - 409 retry for optimistic-locking PATCHes
+ *   - 401 one-shot retry after TokenProvider.onUnauthorized
+ *   - 429 honouring Retry-After
+ *
+ * Not exported from the public surface — use the RcrtClient methods.
+ */
+
+import { ApiError, parseErrorBody, SdkError } from '../errors.js';
+import type { TokenProvider } from '../auth.js';
+
+export interface FetchContext {
+  apiUrl: string;
+  tenantId: string | null;
+  tokenProvider: TokenProvider;
+  fetchImpl?: typeof fetch;
+}
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  /** JSON body; will be serialised. */
+  body?: unknown;
+  /** Extra query params. */
+  query?: Record<string, string | number | boolean | undefined | null>;
+  /** Extra headers. */
+  headers?: Record<string, string>;
+  /** Skip tenant header (identity routes). */
+  skipTenant?: boolean;
+  /** Abort signal. */
+  signal?: AbortSignal;
+  /**
+   * Retries for 409 Conflict. Each retry re-fetches first if the
+   * caller provides a `refetchBeforeRetry` hook.
+   */
+  maxConflictRetries?: number;
+  refetchBeforeRetry?: () => Promise<Partial<{ body: unknown }>>;
+}
+
+export async function request<T = unknown>(
+  ctx: FetchContext,
+  path: string,
+  options: RequestOptions = {},
+): Promise<T> {
+  const method = options.method ?? 'GET';
+  const fetchImpl = ctx.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new SdkError('NO_FETCH', 'fetch() is not available — pass `fetchImpl` in client config');
+  }
+
+  const url = buildUrl(ctx.apiUrl, path, options.query);
+  const maxRetries = options.maxConflictRetries ?? 2;
+  let attempt = 0;
+  let body = options.body;
+  let didRefreshAuth = false;
+
+  while (true) {
+    const idToken = await ctx.tokenProvider.getIdToken();
+    const headers: Record<string, string> = {
+      'Authorization': `Bearer ${idToken}`,
+      ...(options.headers ?? {}),
+    };
+    if (!options.skipTenant && ctx.tenantId) {
+      headers['X-Tenant-ID'] = ctx.tenantId;
+    }
+    if (body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    const init: RequestInit = { method, headers };
+    if (body !== undefined) init.body = JSON.stringify(body);
+    if (options.signal) init.signal = options.signal;
+    const res = await fetchImpl(url, init);
+
+    if (res.status >= 200 && res.status < 300) {
+      if (res.status === 204) return undefined as T;
+      const text = await res.text();
+      if (!text) return undefined as T;
+      try {
+        return JSON.parse(text) as T;
+      } catch {
+        // Some endpoints return non-JSON (e.g. raw bytes); surface as a string.
+        return text as unknown as T;
+      }
+    }
+
+    // Retry 401 once after the token provider has a chance to refresh.
+    if (res.status === 401 && !didRefreshAuth && ctx.tokenProvider.onUnauthorized) {
+      didRefreshAuth = true;
+      await ctx.tokenProvider.onUnauthorized();
+      continue;
+    }
+
+    // Retry 409 with a fresh body if the caller supports optimistic refetch.
+    if (res.status === 409 && attempt < maxRetries && options.refetchBeforeRetry) {
+      attempt += 1;
+      const fresh = await options.refetchBeforeRetry();
+      if (fresh.body !== undefined) body = fresh.body;
+      continue;
+    }
+
+    // Retry 429 honouring Retry-After, one time.
+    if (res.status === 429 && attempt < 1) {
+      attempt += 1;
+      const ra = parseInt(res.headers.get('Retry-After') ?? '1', 10);
+      await sleep((isNaN(ra) ? 1 : ra) * 1000);
+      continue;
+    }
+
+    const raw = await res.text().catch(() => '');
+    throw new ApiError(res.status, parseErrorBody(res.status, raw), raw);
+  }
+}
+
+function buildUrl(apiUrl: string, path: string, query?: RequestOptions['query']): string {
+  const base = apiUrl.replace(/\/$/, '');
+  const fullPath = path.startsWith('/') ? path : `/${path}`;
+  const u = new URL(base + fullPath);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v === undefined || v === null) continue;
+      u.searchParams.set(k, String(v));
+    }
+  }
+  return u.toString();
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/internal/sse.ts

@@ -0,0 +1,236 @@
+/**
+ * SSE client with automatic reconnection + typed event dispatch.
+ *
+ * Works in three environments:
+ *   - Browsers: uses the built-in `EventSource`. Auth goes via query
+ *     params because `EventSource` can't set custom headers.
+ *   - Node 18+: uses the built-in `EventSource` (Node 22+) or a
+ *     pluggable polyfill (see `config.eventSource`).
+ *   - React Native: install `react-native-sse` and pass its
+ *     constructor as `config.eventSource`. Custom headers work there.
+ *
+ * Subscribers get typed events. Streams auto-reconnect with
+ * exponential backoff unless `close()` was called explicitly.
+ */
+
+import type { Breadcrumb } from '../types/breadcrumb.js';
+
+export interface SseConnectConfig {
+  apiUrl: string;
+  path: string;
+  tenantId: string | null;
+  getToken: () => Promise<string>;
+  /** Override the EventSource implementation. Required in React Native. */
+  eventSource?: EventSourceConstructor;
+  /** Max reconnect delay in ms. Default 30000. */
+  maxBackoffMs?: number;
+  /** Extra query params (e.g. `?last_event_id=...`). */
+  query?: Record<string, string>;
+  /** Disable the query-param token fallback; requires a custom EventSource impl. */
+  useHeaderAuth?: boolean;
+}
+
+export interface SseDelta {
+  delta: string;
+  agent_id: string;
+  is_final: boolean;
+}
+
+export interface SseThought {
+  steps: string[];
+  agent_id?: string;
+}
+
+export interface SseAction {
+  tool_name: string;
+  status: 'running' | 'completed' | 'failed';
+  request_id?: string;
+}
+
+export interface SseError {
+  code?: string;
+  message?: string;
+  fatal?: boolean;
+}
+
+export interface SseHandlers {
+  onConnected?: (payload: { session_id?: string; user_id?: string }) => void;
+  onDelta?: (data: SseDelta) => void;
+  onMessage?: (data: Breadcrumb) => void;
+  onThought?: (data: SseThought) => void;
+  onAction?: (data: SseAction) => void;
+  onError?: (data: SseError, isFatal: boolean) => void;
+  /** Fires any time the underlying SSE connection opens. */
+  onOpen?: () => void;
+  /** Fires any time the underlying SSE connection closes (before a reconnect attempt). */
+  onClose?: () => void;
+}
+
+type EventSourceConstructor = new (url: string, init?: EventSourceInit & { headers?: Record<string, string> }) => EventSourceLike;
+
+interface EventSourceLike {
+  readonly readyState: 0 | 1 | 2;
+  close(): void;
+  addEventListener(type: string, listener: (ev: MessageEvent | Event) => void): void;
+  onerror: ((ev: Event) => void) | null;
+  onopen: ((ev: Event) => void) | null;
+}
+
+export interface SseConnection {
+  /** Close the stream. No more reconnects. */
+  close(): void;
+  /** Current state — for UI reconnection indicators. */
+  readonly state: 'connecting' | 'open' | 'closed';
+}
+
+export function connect(config: SseConnectConfig, handlers: SseHandlers): SseConnection {
+  const maxBackoff = config.maxBackoffMs ?? 30_000;
+  let backoff = 1_000;
+  let closed = false;
+  let es: EventSourceLike | null = null;
+  let state: 'connecting' | 'open' | 'closed' = 'connecting';
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  async function open(): Promise<void> {
+    if (closed) return;
+
+    const token = await config.getToken();
+    const u = new URL(config.apiUrl.replace(/\/$/, '') + config.path);
+    if (config.query) {
+      for (const [k, v] of Object.entries(config.query)) {
+        u.searchParams.set(k, v);
+      }
+    }
+
+    const EventSourceCtor: EventSourceConstructor = (config.eventSource
+      ?? (globalThis as unknown as { EventSource?: EventSourceConstructor }).EventSource) as EventSourceConstructor;
+    if (!EventSourceCtor) {
+      handlers.onError?.({ message: 'No EventSource implementation available. Pass config.eventSource for React Native.', fatal: true }, true);
+      closed = true;
+      state = 'closed';
+      return;
+    }
+
+    // Prefer header auth when the EventSource impl supports it (React
+    // Native with `react-native-sse`, Node 22+, any custom
+    // `config.eventSource` that accepts a `headers` init). The browser's
+    // built-in EventSource constructor has NO support for custom
+    // headers — there's no proposal in the WHATWG spec to change that —
+    // so when we're stuck with it we fall back to passing the bearer
+    // token and tenant ID as query params.
+    //
+    // Security note (Sonar hotspot review): tokens in URLs are a
+    // documented smell — they can leak via proxy logs, HTTP Referer
+    // headers, and browser history. We mitigate:
+    //   * TLS is assumed (RCRT's api-gateway rejects plaintext HTTP).
+    //   * Firebase ID tokens are short-lived (60 min) and auto-rotated.
+    //     A leaked token in a server log expires fast; it can't be used
+    //     to escalate outside the scope Firebase already granted.
+    //   * `tk_*` workspace API keys are long-lived and should NEVER be
+    //     passed through this path. Callers holding a tk_ key are
+    //     server-side and must set `useHeaderAuth: true`. The SDK docs
+    //     and the TokenProvider interface make this explicit.
+    //   * This fallback only triggers for SSE subscriptions. The regular
+    //     fetch-based surface (`src/internal/fetch.ts`) always uses the
+    //     Authorization header.
+    // Without this fallback the SDK cannot open SSE connections from a
+    // browser at all, which would break every chat UI built on RCRT.
+    const init: EventSourceInit & { headers?: Record<string, string> } = {};
+    if (config.useHeaderAuth) {
+      init.headers = {
+        Authorization: `Bearer ${token}`,
+        ...(config.tenantId ? { 'X-Tenant-ID': config.tenantId } : {}),
+      };
+    } else {
+      u.searchParams.set('token', token); // NOSONAR - required for browser EventSource; see block comment above
+      if (config.tenantId) u.searchParams.set('tenant_id', config.tenantId);
+    }
+
+    try {
+      es = new EventSourceCtor(u.toString(), init);
+    } catch (err) {
+      handlers.onError?.({ message: (err as Error).message, fatal: true }, true);
+      scheduleReconnect();
+      return;
+    }
+
+    es.onopen = () => {
+      backoff = 1_000;
+      state = 'open';
+      handlers.onOpen?.();
+    };
+
+    es.addEventListener('connected', (e) => {
+      const data = tryJson((e as MessageEvent).data);
+      handlers.onConnected?.(data as { session_id?: string; user_id?: string });
+    });
+
+    es.addEventListener('delta', (e) => {
+      const data = tryJson<SseDelta>((e as MessageEvent).data);
+      if (data) handlers.onDelta?.(data);
+    });
+
+    es.addEventListener('message', (e) => {
+      const data = tryJson<Breadcrumb>((e as MessageEvent).data);
+      if (data) handlers.onMessage?.(data);
+    });
+
+    es.addEventListener('thought', (e) => {
+      const data = tryJson<SseThought>((e as MessageEvent).data);
+      if (data) handlers.onThought?.(data);
+    });
+
+    es.addEventListener('action', (e) => {
+      const data = tryJson<SseAction>((e as MessageEvent).data);
+      if (data) handlers.onAction?.(data);
+    });
+
+    es.addEventListener('error', (e) => {
+      const data = tryJson<SseError>((e as MessageEvent | undefined)?.data ?? '');
+      handlers.onError?.(data ?? { message: 'stream error' }, false);
+    });
+
+    es.onerror = () => {
+      state = 'closed';
+      handlers.onClose?.();
+      es?.close();
+      es = null;
+      scheduleReconnect();
+    };
+  }
+
+  function scheduleReconnect() {
+    if (closed) return;
+    state = 'connecting';
+    const delay = backoff + Math.floor(Math.random() * 500);
+    backoff = Math.min(maxBackoff, backoff * 2);
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      void open();
+    }, delay);
+  }
+
+  void open();
+
+  return {
+    close() {
+      closed = true;
+      state = 'closed';
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      es?.close();
+      es = null;
+    },
+    get state() {
+      return state;
+    },
+  };
+}
+
+function tryJson<T = unknown>(raw: unknown): T | undefined {
+  if (typeof raw !== 'string' || !raw) return undefined;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return undefined;
+  }
+}

package/src/sessions.ts

@@ -0,0 +1,110 @@
+/**
+ * Sessions module — multi-agent / multi-participant session metadata.
+ *
+ * The `chat.send()` + `chat.sessionStream()` flow gives you the
+ * per-turn read/write loop. This module is for everything around the
+ * session: who's in it (participants — agents AND users), and the
+ * cross-session graph view (constellation).
+ *
+ * See `packages/docs/guides/03-chat-and-sse.md` for how sessions
+ * relate to breadcrumbs.
+ */
+
+import type { FetchContext } from './internal/fetch.js';
+import { request } from './internal/fetch.js';
+import { ApiError } from './errors.js';
+
+export interface SessionParticipant {
+  /** Either `agent` (id is an agent name like `life-coordinator`) or `user` (id is a UUID). */
+  type: 'agent' | 'user';
+  id: string;
+  /** Human-friendly label. May be undefined for never-renamed participants. */
+  name?: string;
+  invited_by?: string;
+  joined_at?: string;
+}
+
+export interface ConstellationNode {
+  session_id: string;
+  title?: string;
+  topics?: string[];
+  message_count?: number;
+  last_active?: string;
+  primary_agent?: string;
+  participant_ids?: string[];
+}
+
+export interface ConstellationEdge {
+  /** Two session ids the constellation maps as related. */
+  a: string;
+  b: string;
+  /** Reason for the relationship — e.g. `shared_topic:health`, `shared_participant:life-coordinator`. */
+  reason: string;
+}
+
+export interface ConstellationData {
+  nodes: ConstellationNode[];
+  edges: ConstellationEdge[];
+}
+
+export class SessionsModule {
+  constructor(private readonly ctx: FetchContext) {}
+
+  /**
+   * `GET /v1/sessions/constellation` — graph view across all the
+   * caller's sessions, grouped by topic / shared participant.
+   *
+   * Returns `null` when the constellation endpoint is unavailable
+   * or the user has zero sessions to graph.
+   */
+  async getConstellation(limit: number = 50): Promise<ConstellationData | null> {
+    try {
+      return await request<ConstellationData>(this.ctx, '/v1/sessions/constellation', {
+        query: { limit },
+      });
+    } catch (err) {
+      if (err instanceof ApiError && (err.status === 404 || err.status === 204)) {
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  /** `GET /v1/sessions/{id}/participants` — agents + users currently in the session. */
+  async listParticipants(sessionId: string): Promise<SessionParticipant[]> {
+    const res = await request<{ participants: SessionParticipant[] } | SessionParticipant[]>(
+      this.ctx,
+      `/v1/sessions/${sessionId}/participants`,
+    );
+    return Array.isArray(res) ? res : (res.participants ?? []);
+  }
+
+  /**
+   * `POST /v1/sessions/{id}/participants` — invite an agent into the
+   * session. The agent will see subsequent turns and may respond.
+   */
+  async addParticipant(
+    sessionId: string,
+    agentId: string,
+    options: { invitedBy?: string } = {},
+  ): Promise<void> {
+    await request<void>(this.ctx, `/v1/sessions/${sessionId}/participants`, {
+      method: 'POST',
+      body: { agent_id: agentId, invited_by: options.invitedBy },
+    });
+  }
+
+  /** `DELETE /v1/sessions/{id}/participants/{agent_id}` — drop an agent from the session. */
+  async removeParticipant(sessionId: string, agentId: string): Promise<void> {
+    try {
+      await request<void>(
+        this.ctx,
+        `/v1/sessions/${sessionId}/participants/${agentId}`,
+        { method: 'DELETE' },
+      );
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 404) return; // idempotent
+      throw err;
+    }
+  }
+}

package/src/types/breadcrumb.ts

@@ -0,0 +1,77 @@
+/**
+ * Breadcrumb — the fundamental record of RCRT.
+ *
+ * Every meaningful state change in the system is a breadcrumb. See
+ * `packages/docs/concepts/02-primitives.md` for the mental model.
+ */
+
+export type ActorType = 'user' | 'agent' | 'tool' | 'system';
+
+export interface Actor {
+  type: ActorType;
+  /** For users: the user UUID. For agents: the agent id. For tools: the tool name. */
+  id: string;
+}
+
+export interface Breadcrumb {
+  id: string;
+  tenant_id: string;
+  name: string;
+  title: string;
+  content: Record<string, unknown>;
+  /** AND-semantics when queried. Prefix conventions: `interpret:*`, `service:*`, `session:*`, `user:*`, etc. */
+  tags: string[];
+  /** Breadcrumbs this derived from (SAPL provenance chain). */
+  parent_ids: string[];
+  /** Optimistic locking. PATCH must include the current value. */
+  version: number;
+  created_by: Actor;
+  created_at: string;
+  updated_at: string;
+  deleted_at: string | null;
+  /** Optional embedding for semantic search. */
+  embedding?: number[];
+  /** Relative TTL — e.g. "24h", "30d". */
+  ttl?: string;
+}
+
+export interface CreateBreadcrumbRequest {
+  name?: string;
+  title: string;
+  content: Record<string, unknown>;
+  tags?: string[];
+  parent_ids?: string[];
+  created_by?: Actor;
+  ttl?: string;
+  /** If a breadcrumb with the same name + tags exists, update it rather than inserting a new row. */
+  upsert?: boolean;
+}
+
+export interface UpdateBreadcrumbRequest {
+  /** Required. Optimistic locking fails with 409 Conflict otherwise. */
+  version: number;
+  title?: string;
+  content?: Record<string, unknown>;
+  tags?: string[];
+  parent_ids?: string[];
+  ttl?: string;
+}
+
+export interface BreadcrumbResponse {
+  breadcrumb: Breadcrumb;
+  action?: 'created' | 'updated';
+}
+
+export interface QueryByTagsOptions {
+  /** Max rows to return. Server max is 200. */
+  limit?: number;
+  offset?: number;
+  /** Exact name match. */
+  name?: string;
+  order?: 'newest' | 'oldest';
+}
+
+export interface SemanticSearchOptions {
+  limit?: number;
+  tags?: string[];
+}