@possibl/rcrt-sdk 0.1.1 → 0.1.3

package/src/authn.ts

@@ -1,159 +0,0 @@
-/**
- * Identity module — `/v1/auth/*` endpoints.
- *
- * Distinct from the TokenProvider abstraction: this is the server-side
- * identity surface that runs _after_ you've presented a bearer token.
- * See `packages/docs/guides/02-auth.md`.
- */
-
-import type { FetchContext } from './internal/fetch.js';
-import { request } from './internal/fetch.js';
-
-export interface MeResponse {
-  user: {
-    id: string;
-    email: string;
-    name?: string;
-    picture?: string;
-  };
-  is_platform_admin: boolean;
-  organizations: Array<{ id: string; name: string; role: string }>;
-  tenants: Array<{ id: string; name: string; role: string }>;
-  active_tenant?: { id: string; name: string; role: string };
-  permissions?: string[];
-  grants?: unknown[];
-}
-
-export interface Tenant {
-  id: string;
-  name: string;
-  org_id?: string;
-  role?: string;
-}
-
-export interface PendingInvitation {
-  id: string;
-  org_id?: string | null;
-  tenant_id?: string | null;
-  email: string;
-  role: string;
-  status: 'pending' | 'accepted' | 'declined' | 'expired' | 'cancelled';
-  expires_at: string;
-  invited_by?: { id: string; name?: string };
-}
-
-export class IdentityModule {
-  constructor(private readonly ctx: FetchContext) {}
-
-  /**
-   * `GET /v1/auth/me` — returns identity + all accessible workspaces.
-   *
-   * Creates the user row on first sign-in. Call this before any other
-   * RCRT endpoint for brand-new Firebase users.
-   */
-  async me(): Promise<MeResponse> {
-    return request<MeResponse>(this.ctx, '/v1/auth/me', { skipTenant: true });
-  }
-
-  /** List workspaces the current user is a member of. */
-  async listTenants(): Promise<Tenant[]> {
-    const res = await request<Tenant[] | { tenants: Tenant[] }>(this.ctx, '/v1/auth/tenants', {
-      skipTenant: true,
-    });
-    return Array.isArray(res) ? res : (res.tenants ?? []);
-  }
-
-  /** Confirm workspace membership. Client code is still responsible for setting X-Tenant-ID. */
-  async selectTenant(tenantId: string): Promise<void> {
-    await request<void>(this.ctx, `/v1/auth/tenants/${tenantId}/select`, {
-      method: 'POST',
-      skipTenant: true,
-    });
-  }
-
-  /** `POST /v1/auth/logout` — server-side no-op; included for symmetry + audit. */
-  async logout(): Promise<void> {
-    await request<void>(this.ctx, '/v1/auth/logout', {
-      method: 'POST',
-      skipTenant: true,
-    });
-  }
-
-  /**
-   * `POST /v1/auth/delete-account` — cascading account deletion.
-   *
-   * **NOT YET ON `development`** at publish time — pending a follow-up
-   * PR. The SDK method exists so consumer code can compile against the
-   * intended shape; invoking it against a gateway that lacks the
-   * handler returns 404.
-   */
-  async deleteAccount(): Promise<void> {
-    await request<void>(this.ctx, '/v1/auth/delete-account', {
-      method: 'POST',
-      skipTenant: true,
-    });
-  }
-
-  /** Pending invitations keyed by the caller's email. */
-  async listPendingInvitations(): Promise<PendingInvitation[]> {
-    const res = await request<
-      PendingInvitation[] | { invitations: PendingInvitation[]; total?: number }
-    >(this.ctx, '/v1/invitations/pending');
-    return Array.isArray(res) ? res : (res.invitations ?? []);
-  }
-
-  async acceptInvitation(token: string): Promise<void> {
-    await request<void>(this.ctx, '/v1/invitations/accept', {
-      method: 'POST',
-      body: { token },
-    });
-  }
-
-  async declineInvitation(invitationId: string): Promise<void> {
-    await request<void>(this.ctx, `/v1/invitations/${invitationId}/decline`, {
-      method: 'POST',
-    });
-  }
-
-  /**
-   * `GET /v1/user/profile` — workspace-scoped user profile breadcrumb.
-   *
-   * Distinct from `me()` — this is the user's editable profile content
-   * (name, timezone, preferences) rather than their identity envelope.
-   * Returns `null` when no profile has been written yet (404 swallowed).
-   */
-  async getUserProfile(): Promise<UserProfileBreadcrumb | null> {
-    try {
-      return await request<UserProfileBreadcrumb>(this.ctx, '/v1/user/profile');
-    } catch (err) {
-      // 404 is the no-profile-yet case — caller renders the onboarding flow.
-      if (err && typeof err === 'object' && 'status' in err && (err as { status: number }).status === 404) {
-        return null;
-      }
-      throw err;
-    }
-  }
-
-  /**
-   * `PUT /v1/user/profile` — upsert. Body fields land on the
-   * underlying breadcrumb's `content` payload.
-   */
-  async updateUserProfile(
-    patch: Record<string, unknown>,
-  ): Promise<UserProfileBreadcrumb> {
-    return request<UserProfileBreadcrumb>(this.ctx, '/v1/user/profile', {
-      method: 'PUT',
-      body: patch,
-    });
-  }
-}
-
-export interface UserProfileBreadcrumb {
-  id: string;
-  title?: string;
-  content: Record<string, unknown>;
-  tags: string[];
-  version: number;
-  created_at?: string;
-  updated_at?: string;
-}

package/src/breadcrumbs.ts

@@ -1,111 +0,0 @@
-/**
- * Breadcrumbs module — CRUD + tag query + semantic search.
- *
- * See `packages/docs/guides/04-breadcrumbs.md` for the narrative
- * description of each operation.
- */
-
-import type { FetchContext } from './internal/fetch.js';
-import { request } from './internal/fetch.js';
-import type {
-  Breadcrumb,
-  BreadcrumbResponse,
-  CreateBreadcrumbRequest,
-  UpdateBreadcrumbRequest,
-  QueryByTagsOptions,
-  SemanticSearchOptions,
-} from './types/breadcrumb.js';
-import { ApiError, SdkError } from './errors.js';
-
-export class BreadcrumbsModule {
-  constructor(private readonly ctx: FetchContext) {}
-
-  /** `POST /v1/breadcrumbs` */
-  async create(req: CreateBreadcrumbRequest): Promise<Breadcrumb> {
-    const res = await request<BreadcrumbResponse | Breadcrumb>(this.ctx, '/v1/breadcrumbs', {
-      method: 'POST',
-      body: req,
-    });
-    return 'breadcrumb' in (res as BreadcrumbResponse)
-      ? (res as BreadcrumbResponse).breadcrumb
-      : (res as Breadcrumb);
-  }
-
-  /** `GET /v1/breadcrumbs?tags=...` — AND semantics. */
-  async queryByTags(tags: string[], options: QueryByTagsOptions = {}): Promise<Breadcrumb[]> {
-    if (tags.length === 0) {
-      throw new SdkError('EMPTY_TAGS', 'queryByTags requires at least one tag');
-    }
-    const res = await request<Breadcrumb[] | { breadcrumbs: Breadcrumb[] }>(this.ctx, '/v1/breadcrumbs', {
-      query: {
-        tags: tags.join(','),
-        limit: options.limit,
-        offset: options.offset,
-        name: options.name,
-        order: options.order,
-      },
-    });
-    return Array.isArray(res) ? res : (res.breadcrumbs ?? []);
-  }
-
-  /** `GET /v1/breadcrumbs/search?q=...` — cosine-similarity semantic search. */
-  async search(q: string, options: SemanticSearchOptions = {}): Promise<Breadcrumb[]> {
-    const query: Record<string, string | number | undefined> = {
-      q,
-      limit: options.limit,
-    };
-    if (options.tags?.length) query.tags = options.tags.join(',');
-    const res = await request<Breadcrumb[] | { breadcrumbs: Breadcrumb[] }>(this.ctx, '/v1/breadcrumbs/search', { query });
-    return Array.isArray(res) ? res : (res.breadcrumbs ?? []);
-  }
-
-  /** `GET /v1/breadcrumbs/{id}` */
-  async get(id: string): Promise<Breadcrumb> {
-    return request<Breadcrumb>(this.ctx, `/v1/breadcrumbs/${id}`);
-  }
-
-  /**
-   * `PATCH /v1/breadcrumbs/{id}` — optimistic-locking update.
-   *
-   * If `req.version` is wrong, the server returns 409. Pass
-   * `autoRetryConflict: true` to have the SDK refetch + retry once.
-   */
-  async update(
-    id: string,
-    req: UpdateBreadcrumbRequest,
-    opts: { autoRetryConflict?: boolean } = {},
-  ): Promise<Breadcrumb> {
-    const refetchBeforeRetry = opts.autoRetryConflict
-      ? async () => {
-          const fresh = await this.get(id);
-          return {
-            body: {
-              ...req,
-              version: fresh.version,
-            } satisfies UpdateBreadcrumbRequest,
-          };
-        }
-      : undefined;
-
-    const res = await request<BreadcrumbResponse | Breadcrumb>(this.ctx, `/v1/breadcrumbs/${id}`, {
-      method: 'PATCH',
-      body: req,
-      ...(refetchBeforeRetry
-        ? { maxConflictRetries: 2, refetchBeforeRetry }
-        : {}),
-    });
-    return 'breadcrumb' in (res as BreadcrumbResponse)
-      ? (res as BreadcrumbResponse).breadcrumb
-      : (res as Breadcrumb);
-  }
-
-  /** `DELETE /v1/breadcrumbs/{id}` — soft delete. */
-  async delete(id: string): Promise<void> {
-    try {
-      await request<void>(this.ctx, `/v1/breadcrumbs/${id}`, { method: 'DELETE' });
-    } catch (err) {
-      if (err instanceof ApiError && err.status === 404) return; // idempotent
-      throw err;
-    }
-  }
-}

package/src/capabilities.ts

@@ -1,93 +0,0 @@
-/**
- * Capabilities module — discover what the current workspace can do.
- *
- * In RCRT, capabilities are breadcrumbs tagged with `interpret:*`:
- *   - `interpret:executable` — tools (functions an agent can call)
- *   - `interpret:promptable` — agents (entities the user / other
- *     agents can `chat.send()` to)
- *   - `interpret:service-def` — connectable services (Gmail, Notion,
- *     etc.) with their OAuth metadata
- *   - `interpret:knowledge` — static knowledge bases attached to the
- *     workspace
- *
- * This module is a thin convenience layer over `breadcrumbs.queryByTags`
- * that maps the `type` argument to the right tag.
- */
-
-import type { FetchContext } from './internal/fetch.js';
-import { request } from './internal/fetch.js';
-import type { Breadcrumb } from './types/breadcrumb.js';
-
-export type CapabilityType = 'tools' | 'agents' | 'services' | 'knowledge';
-
-const TAG_BY_TYPE: Record<CapabilityType, string> = {
-  tools: 'interpret:executable',
-  agents: 'interpret:promptable',
-  services: 'interpret:service-def',
-  knowledge: 'interpret:knowledge',
-};
-
-export interface ChattableAgent {
-  /** The id you pass to `chat.send({ target_agent: ... })`. */
-  id: string;
-  name: string;
-  description: string;
-  /** True when this agent has the `interface:chat-default` tag. */
-  isDefault: boolean;
-}
-
-export class CapabilitiesModule {
-  constructor(private readonly ctx: FetchContext) {}
-
-  /**
-   * List every capability of every type. Useful when surfacing the
-   * full toolbelt + agent roster to a debug / admin view.
-   */
-  async listAll(limit: number = 200): Promise<Breadcrumb[]> {
-    const res = await request<Breadcrumb[] | { breadcrumbs: Breadcrumb[] }>(
-      this.ctx,
-      '/v1/breadcrumbs',
-      { query: { tags: TAG_BY_TYPE.tools, limit } },
-    );
-    return Array.isArray(res) ? res : (res.breadcrumbs ?? []);
-  }
-
-  /** List capabilities of one specific type. */
-  async list(type: CapabilityType, limit: number = 200): Promise<Breadcrumb[]> {
-    const tag = TAG_BY_TYPE[type];
-    const res = await request<Breadcrumb[] | { breadcrumbs: Breadcrumb[] }>(
-      this.ctx,
-      '/v1/breadcrumbs',
-      { query: { tags: tag, limit } },
-    );
-    return Array.isArray(res) ? res : (res.breadcrumbs ?? []);
-  }
-
-  /**
-   * Convenience: agents the user can chat with directly.
-   *
-   * Filters `interpret:promptable` to those tagged `interface:chat`
-   * or `interface:chat-default`. Falls back to all promptables when
-   * no agents have a chat interface tag (older deploys).
-   */
-  async getChattableAgents(limit: number = 50): Promise<ChattableAgent[]> {
-    const promptables = await this.list('agents', limit);
-    const chatAgents = promptables.filter((bc) =>
-      bc.tags?.some(
-        (t) => t === 'interface:chat' || t === 'interface:chat-default',
-      ),
-    );
-    const source = chatAgents.length > 0 ? chatAgents : promptables;
-    return source.map<ChattableAgent>((bc) => {
-      const content = (bc.content ?? {}) as Record<string, unknown>;
-      const id = (bc as { name?: string }).name ?? bc.id;
-      const name =
-        (content.name as string | undefined) ??
-        (bc as { title?: string }).title ??
-        id;
-      const description = (content.description as string | undefined) ?? '';
-      const isDefault = !!bc.tags?.includes('interface:chat-default');
-      return { id, name, description, isDefault };
-    });
-  }
-}

package/src/cards.ts

@@ -1,109 +0,0 @@
-/**
- * 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';
-
-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

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

@@ -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;
-  }
-}