@possibl/rcrt-sdk 0.1.2 → 0.5.0

package/src/client.ts

@@ -1,97 +0,0 @@
-/**
- * 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

@@ -1,101 +0,0 @@
-/**
- * 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

@@ -1,135 +0,0 @@
-/**
- * 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

@@ -1,99 +0,0 @@
-/**
- * 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`,
-    );
-  }
-}

package/src/index.ts

@@ -1,103 +0,0 @@
-/**
- * @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

@@ -1,133 +0,0 @@
-/**
- * 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));
-}