@possibl/rcrt-sdk 0.1.0

package/src/cards.ts

@@ -0,0 +1,110 @@
+/**
+ * Cards module — resolve an `interpret:pending-action` breadcrumb.
+ *
+ * The card's footer action ids correspond to values the SDK writes
+ * to `content.status`. See
+ * `packages/docs/guides/06-rendering-cards.md`.
+ */
+
+import type { FetchContext } from './internal/fetch.js';
+import { request } from './internal/fetch.js';
+import type { Breadcrumb } from './types/breadcrumb.js';
+import type { Card, ResolveRequest } from './types/card.js';
+import { ApiError } from './errors.js';
+
+export class CardsModule {
+  constructor(private readonly ctx: FetchContext) {}
+
+  /**
+   * PATCH the card breadcrumb with a resolution. Handles optimistic
+   * locking transparently — refetches + retries on 409.
+   */
+  async resolve(breadcrumbId: string, resolution: ResolveRequest): Promise<Breadcrumb> {
+    const current = await request<Breadcrumb>(this.ctx, `/v1/breadcrumbs/${breadcrumbId}`);
+    const nextContent = {
+      ...(current.content ?? {}),
+      status: resolution.status,
+      user_response: resolution.user_response,
+      resolved_at: new Date().toISOString(),
+    };
+    const nextTags = ensureStatusTag(current.tags, resolution.status);
+    return request<Breadcrumb>(this.ctx, `/v1/breadcrumbs/${breadcrumbId}`, {
+      method: 'PATCH',
+      body: {
+        version: current.version,
+        content: nextContent,
+        tags: nextTags,
+      },
+      maxConflictRetries: 2,
+      refetchBeforeRetry: async () => {
+        const fresh = await request<Breadcrumb>(this.ctx, `/v1/breadcrumbs/${breadcrumbId}`);
+        return {
+          body: {
+            version: fresh.version,
+            content: {
+              ...(fresh.content ?? {}),
+              status: resolution.status,
+              user_response: resolution.user_response,
+              resolved_at: new Date().toISOString(),
+            },
+            tags: ensureStatusTag(fresh.tags, resolution.status),
+          },
+        };
+      },
+    });
+  }
+
+  /** Pending cards for the current user's current workspace. */
+  async listPending(limit = 50): Promise<Breadcrumb[]> {
+    const list = await request<Breadcrumb[] | { breadcrumbs: Breadcrumb[] }>(this.ctx, '/v1/breadcrumbs', {
+      query: { tags: 'interpret:pending-action,status:pending', limit },
+    });
+    return Array.isArray(list) ? list : (list.breadcrumbs ?? []);
+  }
+
+  /**
+   * Extract the Card object from a breadcrumb's content, normalising
+   * over legacy shapes (old breadcrumbs stored `card.type` + flat
+   * fields instead of `card.layout` + structured body).
+   */
+  static extractCard(bc: Breadcrumb): Card | undefined {
+    const content = (bc.content ?? {}) as Record<string, unknown>;
+    const raw = (content.card as Record<string, unknown> | undefined) ?? undefined;
+    if (!raw) return undefined;
+    if (typeof raw.layout === 'string') return raw as unknown as Card;
+    // Legacy — fall back to a minimal info card.
+    if (typeof raw.type === 'string') {
+      const card: Card = {
+        layout: legacyTypeToLayout(raw.type as string),
+        header: { title: typeof content.title === 'string' ? content.title : bc.title },
+      };
+      if (typeof content.summary === 'string') {
+        card.body = { text: content.summary };
+      }
+      return card;
+    }
+    return undefined;
+  }
+}
+
+function ensureStatusTag(existing: string[], status: string): string[] {
+  const withoutStatus = existing.filter((t) => !t.startsWith('status:'));
+  withoutStatus.push(`status:${status}`);
+  return withoutStatus;
+}
+
+function legacyTypeToLayout(type: string): Card['layout'] {
+  switch (type) {
+    case 'connect':
+      return 'connect';
+    case 'confirm':
+    case 'choice':
+    case 'multi-choice':
+    case 'approval':
+      return 'decision';
+    case 'text-input':
+      return 'input';
+    default:
+      return 'info';
+  }
+}

package/src/chat.ts

@@ -0,0 +1,83 @@
+/**
+ * Chat module — `POST /v1/chat` + per-session / global SSE streams.
+ *
+ * See `packages/docs/guides/03-chat-and-sse.md`.
+ */
+
+import type { FetchContext } from './internal/fetch.js';
+import { request } from './internal/fetch.js';
+import type { SseConnection, SseConnectConfig, SseHandlers } from './internal/sse.js';
+import { connect as sseConnect } from './internal/sse.js';
+
+export interface SendChatRequest {
+  message: string;
+  /** The agent to route this turn to. `life-coordinator` by default in the Ritual bundle. */
+  target_agent: string;
+  /** Resume an existing session; omit to start a new one. */
+  session_id?: string;
+  /** Extra tags stamped on the user's message breadcrumb. */
+  extra_tags?: string[];
+}
+
+export interface SendChatResponse {
+  id: string;
+  session_id: string;
+}
+
+export interface SseStreamOptions {
+  /** Override the EventSource constructor (required in React Native). */
+  eventSource?: SseConnectConfig['eventSource'];
+  useHeaderAuth?: boolean;
+  maxBackoffMs?: number;
+  /** Supply a Last-Event-ID-style resume token if your server supports it. */
+  last_event_id?: string;
+}
+
+export class ChatModule {
+  constructor(private readonly ctx: FetchContext) {}
+
+  /**
+   * Send a user message to an agent. Returns immediately with the
+   * breadcrumb id + session id. The agent reply arrives via the SSE
+   * stream — call `stream(session_id)` before posting, not after.
+   */
+  async send(req: SendChatRequest): Promise<SendChatResponse> {
+    return request<SendChatResponse>(this.ctx, '/v1/chat', {
+      method: 'POST',
+      body: req,
+    });
+  }
+
+  /** Per-session SSE — just this session's events. Recommended for chat views. */
+  sessionStream(sessionId: string, handlers: SseHandlers, options: SseStreamOptions = {}): SseConnection {
+    return sseConnect(this.buildConfig(`/v1/sessions/${sessionId}/stream`, options), handlers);
+  }
+
+  /** Global SSE — everything the user can see. Useful for home feeds / awaiting-you. */
+  globalStream(handlers: SseHandlers, options: SseStreamOptions = {}): SseConnection {
+    return sseConnect(this.buildConfig('/v1/events', options), handlers);
+  }
+
+  private buildConfig(path: string, options: SseStreamOptions): SseConnectConfig {
+    const config: SseConnectConfig = {
+      apiUrl: this.ctx.apiUrl,
+      path,
+      tenantId: this.ctx.tenantId,
+      getToken: () => this.ctx.tokenProvider.getIdToken(),
+    };
+    if (options.eventSource) config.eventSource = options.eventSource;
+    if (options.useHeaderAuth !== undefined) config.useHeaderAuth = options.useHeaderAuth;
+    if (options.maxBackoffMs !== undefined) config.maxBackoffMs = options.maxBackoffMs;
+    if (options.last_event_id) config.query = { last_event_id: options.last_event_id };
+    return config;
+  }
+
+  /**
+   * Clear a session's suspend flag after the loop detector fired.
+   *
+   * @see `packages/docs/operations/loop-detector.md`
+   */
+  async resumeSession(sessionId: string): Promise<void> {
+    await request<void>(this.ctx, `/v1/sessions/${sessionId}/resume`, { method: 'POST' });
+  }
+}

package/src/client.ts

@@ -0,0 +1,97 @@
+/**
+ * RcrtClient — the single entry-point to the SDK.
+ *
+ *     import { RcrtClient, staticTokenProvider } from '@possibl/rcrt-sdk';
+ *
+ *     const rcrt = new RcrtClient({
+ *       apiUrl: 'https://rcrt-api-gateway-<hash>.run.app',
+ *       tokenProvider: firebaseTokenProvider(auth),
+ *     });
+ *
+ *     rcrt.setTenantId(workspaceId);
+ *     const me = await rcrt.auth.me();
+ *     const stream = rcrt.chat.sessionStream(sessionId, { ...handlers });
+ *
+ * Every module on the client shares the same fetch context — one
+ * bearer refresh path, one tenant header, one error envelope.
+ */
+
+import type { TokenProvider } from './auth.js';
+import type { FetchContext } from './internal/fetch.js';
+import { BreadcrumbsModule } from './breadcrumbs.js';
+import { ChatModule } from './chat.js';
+import { CardsModule } from './cards.js';
+import { GrantsModule } from './grants.js';
+import { IdentityModule } from './authn.js';
+import { FilesModule } from './files.js';
+import { SessionsModule } from './sessions.js';
+import { CapabilitiesModule } from './capabilities.js';
+import { SdkError } from './errors.js';
+
+export interface RcrtClientConfig {
+  apiUrl: string;
+  tokenProvider: TokenProvider;
+  /** Optional workspace UUID. Can be set later via `setTenantId()`. */
+  tenantId?: string;
+  /** Optional fetch override (SSR, custom retry, mock). */
+  fetchImpl?: typeof fetch;
+}
+
+export class RcrtClient {
+  private readonly ctx: FetchContext;
+
+  public readonly auth: IdentityModule;
+  public readonly breadcrumbs: BreadcrumbsModule;
+  public readonly chat: ChatModule;
+  public readonly cards: CardsModule;
+  public readonly grants: GrantsModule;
+  public readonly files: FilesModule;
+  public readonly sessions: SessionsModule;
+  public readonly capabilities: CapabilitiesModule;
+
+  constructor(config: RcrtClientConfig) {
+    if (!config.apiUrl) {
+      throw new SdkError('MISSING_API_URL', 'RcrtClient requires `apiUrl`');
+    }
+    if (!config.tokenProvider) {
+      throw new SdkError('MISSING_TOKEN_PROVIDER', 'RcrtClient requires a `tokenProvider`');
+    }
+
+    const ctxInternal = {
+      apiUrl: config.apiUrl,
+      tenantId: config.tenantId ?? null,
+      tokenProvider: config.tokenProvider,
+      fetchImpl: config.fetchImpl ?? undefined,
+    };
+
+    // Use a Proxy so module instances can read the current `tenantId`
+    // at request time without us having to rebuild them on every
+    // `setTenantId` call.
+    this.ctx = new Proxy({} as FetchContext, {
+      get: (_target, prop) => (ctxInternal as unknown as Record<string, unknown>)[prop as string],
+      set: (_target, prop, value) => {
+        (ctxInternal as unknown as Record<string, unknown>)[prop as string] = value;
+        return true;
+      },
+    });
+
+    this.auth = new IdentityModule(this.ctx);
+    this.breadcrumbs = new BreadcrumbsModule(this.ctx);
+    this.chat = new ChatModule(this.ctx);
+    this.cards = new CardsModule(this.ctx);
+    this.grants = new GrantsModule(this.ctx);
+    this.files = new FilesModule(this.ctx);
+    this.sessions = new SessionsModule(this.ctx);
+    this.capabilities = new CapabilitiesModule(this.ctx);
+  }
+
+  /** Switch workspaces. Subsequent requests carry the new `X-Tenant-ID`. */
+  setTenantId(tenantId: string | null): void {
+    (this.ctx as unknown as { tenantId: string | null }).tenantId = tenantId;
+  }
+
+  /** Read the workspace id this client is currently scoped to. */
+  getTenantId(): string | null {
+    return (this.ctx as unknown as { tenantId: string | null }).tenantId;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,101 @@
+/**
+ * Error taxonomy.
+ *
+ * The RCRT backend is mid-migration from a flat `{"error": "string"}`
+ * envelope to a typed `{"error": {"code", "message", "details"}}`
+ * shape. This module normalises both into one `ApiError` that app
+ * code can switch on.
+ *
+ * See `packages/docs/guides/07-error-handling.md`.
+ */
+
+/** Stable machine-readable error codes recognised by the SDK. */
+export type KnownErrorCode =
+  | 'UNAUTHORIZED'
+  | 'FORBIDDEN'
+  | 'NOT_FOUND'
+  | 'CONFLICT'
+  | 'INVALID_REQUEST'
+  | 'TOO_MANY_REQUESTS'
+  | 'INTERNAL'
+  | 'SERVICE_UNAVAILABLE'
+  | 'UNKNOWN';
+
+export interface ApiErrorDetail {
+  /** Machine-readable code if the server sent one. Otherwise derived from status. */
+  code: KnownErrorCode | string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export class ApiError extends Error {
+  public readonly status: number;
+  public readonly detail: ApiErrorDetail;
+  public readonly rawBody: string | undefined;
+
+  constructor(status: number, detail: ApiErrorDetail, rawBody?: string) {
+    super(detail.message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.detail = detail;
+    this.rawBody = rawBody;
+  }
+
+  static fromResponse(status: number, rawBody: string): ApiError {
+    return new ApiError(status, parseErrorBody(status, rawBody), rawBody);
+  }
+}
+
+/** Errors thrown by the SDK before we even reach the server. */
+export class SdkError extends Error {
+  public readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'SdkError';
+    this.code = code;
+  }
+}
+
+// ── Internal helpers ─────────────────────────────────────────────
+
+const STATUS_TO_CODE: Record<number, KnownErrorCode> = {
+  400: 'INVALID_REQUEST',
+  401: 'UNAUTHORIZED',
+  403: 'FORBIDDEN',
+  404: 'NOT_FOUND',
+  409: 'CONFLICT',
+  429: 'TOO_MANY_REQUESTS',
+  500: 'INTERNAL',
+  503: 'SERVICE_UNAVAILABLE',
+};
+
+export function parseErrorBody(status: number, rawBody: string): ApiErrorDetail {
+  const fallbackCode = STATUS_TO_CODE[status] ?? 'UNKNOWN';
+  if (!rawBody.trim()) {
+    return { code: fallbackCode, message: `HTTP ${status}` };
+  }
+  try {
+    const parsed = JSON.parse(rawBody) as unknown;
+    if (parsed && typeof parsed === 'object' && 'error' in parsed) {
+      const err = (parsed as { error: unknown }).error;
+      if (typeof err === 'string') {
+        return { code: fallbackCode, message: err };
+      }
+      if (err && typeof err === 'object') {
+        const e = err as Record<string, unknown>;
+        const detail: ApiErrorDetail = {
+          code: typeof e.code === 'string' ? e.code : fallbackCode,
+          message: typeof e.message === 'string' ? e.message : `HTTP ${status}`,
+        };
+        if (typeof e.details === 'object' && e.details !== null) {
+          detail.details = e.details as Record<string, unknown>;
+        }
+        return detail;
+      }
+    }
+    return { code: fallbackCode, message: rawBody.slice(0, 200) };
+  } catch {
+    return { code: fallbackCode, message: rawBody.slice(0, 200) };
+  }
+}

package/src/files.ts

@@ -0,0 +1,135 @@
+/**
+ * Files module — upload + download + read text + list + delete.
+ *
+ * Files are stored as breadcrumbs under `interpret:file` so they
+ * inherit the same tag / permissions / SSE lifecycle as everything
+ * else. The upload returns the file's breadcrumb so callers can
+ * round-trip into `breadcrumbs.update()` for renames or tagging.
+ *
+ * `getDownloadUrl` returns a short-lived signed URL suitable for
+ * `<a href>` or `fetch()`; the SDK does not cache it.
+ *
+ * See `packages/docs/guides/06-files.md` for the narrative.
+ */
+
+import type { FetchContext } from './internal/fetch.js';
+import { request } from './internal/fetch.js';
+import { ApiError, SdkError } from './errors.js';
+import type { Breadcrumb } from './types/breadcrumb.js';
+
+export type FileScope = 'tenant' | 'org' | 'user';
+
+export interface UploadFileOptions {
+  /** Default `'tenant'` — file is visible to all members of the active workspace. */
+  scope?: FileScope;
+  /** Override the filename written on the breadcrumb (defaults to `File.name`). */
+  filename?: string;
+  /** Extra tags to attach. `interpret:file` is always added by the server. */
+  tags?: string[];
+}
+
+export interface ListFilesOptions {
+  scope?: FileScope;
+  limit?: number;
+}
+
+export class FilesModule {
+  constructor(private readonly ctx: FetchContext) {}
+
+  /**
+   * `POST /v1/files` — multipart upload.
+   *
+   * Accepts a `Blob` (browser / RN) or `File` (browser only). Server
+   * returns the breadcrumb wrapping the stored file.
+   */
+  async upload(file: Blob | File, options: UploadFileOptions = {}): Promise<Breadcrumb> {
+    const fetchImpl = this.ctx.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+      throw new SdkError('NO_FETCH', 'fetch() is not available — pass `fetchImpl` in client config');
+    }
+    if (typeof FormData === 'undefined') {
+      throw new SdkError(
+        'NO_FORMDATA',
+        'FormData is not available in this environment — provide a polyfill (e.g. form-data on Node) before calling files.upload()',
+      );
+    }
+
+    const formData = new FormData();
+    const filename =
+      options.filename ?? ((file as File).name ? (file as File).name : 'upload');
+    formData.append('file', file as Blob, filename);
+    formData.append('scope', options.scope ?? 'tenant');
+    if (options.tags?.length) {
+      formData.append('tags', options.tags.join(','));
+    }
+
+    const url = `${this.ctx.apiUrl.replace(/\/$/, '')}/v1/files`;
+    const idToken = await this.ctx.tokenProvider.getIdToken();
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${idToken}`,
+    };
+    if (this.ctx.tenantId) headers['X-Tenant-ID'] = this.ctx.tenantId;
+
+    const res = await fetchImpl(url, { method: 'POST', headers, body: formData });
+    if (!res.ok) {
+      const raw = await res.text().catch(() => '');
+      throw ApiError.fromResponse(res.status, raw || 'upload failed');
+    }
+    const json = (await res.json()) as { breadcrumb?: Breadcrumb } & Breadcrumb;
+    return json.breadcrumb ?? json;
+  }
+
+  /** `GET /v1/files?scope=...&limit=...` */
+  async list(options: ListFilesOptions = {}): Promise<Breadcrumb[]> {
+    const res = await request<{ files: Breadcrumb[] } | Breadcrumb[]>(this.ctx, '/v1/files', {
+      query: {
+        scope: options.scope,
+        limit: options.limit,
+      },
+    });
+    return Array.isArray(res) ? res : (res.files ?? []);
+  }
+
+  /** `GET /v1/files/{id}` — wrapping breadcrumb for the file. */
+  async get(fileId: string): Promise<Breadcrumb> {
+    const res = await request<{ file: Breadcrumb } | Breadcrumb>(this.ctx, `/v1/files/${fileId}`);
+    return 'file' in (res as { file: Breadcrumb })
+      ? (res as { file: Breadcrumb }).file
+      : (res as Breadcrumb);
+  }
+
+  /**
+   * `GET /v1/files/{id}/content?expiry=...` — signed download URL.
+   *
+   * Default expiry `1h`. URL format goes through Cloud Storage's V4
+   * signed URL flow on the server side. Don't cache — re-fetch when
+   * you need a fresh one.
+   */
+  async getDownloadUrl(fileId: string, expiry: string = '1h'): Promise<string> {
+    const res = await request<{ download_url: string }>(this.ctx, `/v1/files/${fileId}/content`, {
+      query: { expiry },
+    });
+    return res.download_url;
+  }
+
+  /**
+   * `GET /v1/files/{id}/text` — server-side OCR / text extraction.
+   *
+   * Only works for content the document-parser knows about (PDF,
+   * common image formats, plain text). Returns `''` for unparseable.
+   */
+  async getText(fileId: string): Promise<string> {
+    const res = await request<{ text: string }>(this.ctx, `/v1/files/${fileId}/text`);
+    return res.text;
+  }
+
+  /** `DELETE /v1/files/{id}` — soft delete on the wrapping breadcrumb. */
+  async delete(fileId: string): Promise<void> {
+    try {
+      await request<void>(this.ctx, `/v1/files/${fileId}`, { method: 'DELETE' });
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 404) return; // idempotent
+      throw err;
+    }
+  }
+}

package/src/grants.ts

@@ -0,0 +1,99 @@
+/**
+ * Service grants module — OAuth connect flow + grant management.
+ *
+ * See `packages/docs/guides/05-connecting-services.md`.
+ */
+
+import type { FetchContext } from './internal/fetch.js';
+import { request } from './internal/fetch.js';
+
+export type GrantType = 'per_user' | 'service_account';
+export type GrantStatus = 'connected' | 'revoked' | 'error';
+
+export interface ServiceGrantSummary {
+  id: string;
+  service_id: string;
+  account_label?: string | null;
+  email?: string | null;
+  scopes: string[];
+  status: GrantStatus;
+  granted_at: string;
+}
+
+export interface InitiateAuthRequest {
+  grant_type?: GrantType;
+  scopes?: string[];
+  /** Where the browser lands after provider consent. */
+  redirect_uri?: string;
+  /** Label this grant as a specific account (e.g. `work`, `personal`). */
+  account_label?: string;
+}
+
+export interface InitiateAuthResponse {
+  auth_url: string;
+}
+
+export class GrantsModule {
+  constructor(private readonly ctx: FetchContext) {}
+
+  /** All grants the current workspace can see. */
+  async list(): Promise<ServiceGrantSummary[]> {
+    const res = await request<ServiceGrantSummary[] | { grants: ServiceGrantSummary[] }>(
+      this.ctx,
+      '/v1/service-grants',
+    );
+    return Array.isArray(res) ? res : (res.grants ?? []);
+  }
+
+  /** Grant for one specific service (optionally an account label). */
+  async get(serviceId: string, accountLabel?: string): Promise<ServiceGrantSummary | null> {
+    const query: Record<string, string | undefined> = {};
+    if (accountLabel) query.account = accountLabel;
+    const res = await request<ServiceGrantSummary | null>(this.ctx, `/v1/service-grants/${serviceId}`, {
+      query,
+    });
+    return res ?? null;
+  }
+
+  /** Kick off an OAuth flow. Returns the provider URL to open in a popup / in-app browser. */
+  async initiateAuth(serviceId: string, req: InitiateAuthRequest = {}): Promise<InitiateAuthResponse> {
+    return request<InitiateAuthResponse>(this.ctx, `/v1/service-grants/${serviceId}/auth/init`, {
+      method: 'POST',
+      body: {
+        grant_type: req.grant_type ?? 'per_user',
+        scopes: req.scopes,
+        redirect_uri: req.redirect_uri,
+        account_label: req.account_label,
+      },
+    });
+  }
+
+  /** Revoke a grant. Safe + idempotent — revoking a revoked grant is a no-op. */
+  async revoke(serviceId: string, accountLabel?: string): Promise<void> {
+    const query: Record<string, string | undefined> = {};
+    if (accountLabel) query.account = accountLabel;
+    await request<void>(this.ctx, `/v1/service-grants/${serviceId}`, {
+      method: 'DELETE',
+      query,
+    });
+  }
+
+  /**
+   * `GET /v1/services/{name}/resolve` — server-side credential resolution.
+   *
+   * Used by tools that need to call a third-party API on behalf of
+   * the workspace. The server hands back the live credentials for the
+   * requested service (Gmail, Notion etc.) keyed off the active grant.
+   *
+   * Returns `{ service, credentials }`. Treat the credentials as
+   * sensitive — don't log them.
+   */
+  async resolveService(
+    name: string,
+  ): Promise<{ service: string; credentials: Record<string, unknown> }> {
+    return request<{ service: string; credentials: Record<string, unknown> }>(
+      this.ctx,
+      `/v1/services/${name}/resolve`,
+    );
+  }
+}