@possibl/rcrt-sdk 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,82 +1,32 @@
-# Changelog
+# @possibl/rcrt-sdk — Changelog
 
-All notable changes to `@possibl/rcrt-sdk` are documented here. The
-format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
-this package follows [SemVer](https://semver.org/spec/v2.0.0.html) once
-published.
+All notable changes are documented here. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) + [semver](https://semver.org/).
 
-## [0.1.2] — 2026-04-30
+## 0.1.0-alpha.1 — 2026-04-23
 
-Docs-only patch. Removes a customer reference from the README that
-shouldn't have been published — content of the package itself is
-unchanged from 0.1.1.
+First publish. Breaking changes are expected during the `alpha` line — pin exact versions. Do not use in production until `0.1.0` stable.
 
-## [0.1.1] — 2026-04-30
+### Included
 
-Patch release. The SDK ships TypeScript source directly (`main:
-./src/index.ts`), which means consumer tsconfigs compile it. Stricter
-consumer settings (e.g. `noUnusedLocals: true` in
-`possibl-ai/ritual-app`) caught a stray unused import in `cards.ts`
-that the SDK's own tsconfig let pass.
+- `RcrtClient` with auth, chat (send + stream), breadcrumbs (CRUD + tag query + semantic search), service grants, cards, identity modules.
+- Pluggable `TokenProvider` interface — SDK never touches Firebase / Auth0 / Clerk directly.
+- Pluggable `EventSource` — React Native consumers inject `react-native-sse`; browser + Node 18+ use native.
+- Typed error envelope via `ApiError.detail.code` / `KnownErrorCode`. Accepts both the canonical `{error: {code, message, details}}` and legacy `{error: "string"}` shapes during the migration window.
+- Domain types (`Card`, `Breadcrumb`, `Row`, `ChartSpec`, ...) under the main export.
+- OpenAPI-generated types (`paths`, `operations`, `components`) under `@possibl/rcrt-sdk/generated` for raw fetch-level type safety.
 
-### Fixed
+### Known gaps
 
-- Removed unused `ApiError` import in `src/cards.ts`. Consumers with
-  `noUnusedLocals: true` no longer fail the type-check on the SDK's
-  source.
+- No integration test suite against a live backend yet. Smoke tests (9/9) cover the mock surface. Integration harness is queued.
+- The backend's error-envelope migration is in progress (tracked in `packages/docs/guides/07-error-handling.md`). Any handler still returning `{error: "string"}` is normalised by the SDK's `parseErrorBody`.
+- React hooks / a card renderer are deliberately out of scope. See `packages/docs/recipes/react.md` for copy-pasteable patterns.
 
-### Internal
+### Support matrix
 
-- Added `noUnusedLocals: true` + `noUnusedParameters: true` to the
-  SDK's own `tsconfig.json` so future bumps can't ship the same class
-  of issue. CI catches it before publish.
-
-## [0.1.0] — 2026-04-30
-
-First public release. Drops the `-alpha.1` suffix; signals the SDK is
-ready for frontend consumption (canonical RCRT mobile + web template
-imports it directly).
-
-### Added — modules
-
-- **`FilesModule`** (`client.files`) — multipart upload, list, get,
-  signed-URL download, server-side text extraction, soft delete.
-  Defaults to `tenant` scope; supports `org` / `user` for cross-
-  workspace assets.
-- **`SessionsModule`** (`client.sessions`) — `getConstellation()`
-  graph view of related sessions, `listParticipants` /
-  `addParticipant` / `removeParticipant` for multi-agent sessions.
-- **`CapabilitiesModule`** (`client.capabilities`) — `list(type)` for
-  tools / agents / services / knowledge, plus `getChattableAgents()`
-  helper that filters `interpret:promptable` to entries tagged
-  `interface:chat` / `interface:chat-default`.
-- **`IdentityModule.getUserProfile` / `updateUserProfile`** — workspace-
-  scoped editable profile breadcrumb. Returns `null` (instead of
-  throwing) when no profile has been written yet.
-- **`GrantsModule.resolveService(name)`** — server-side credential
-  resolution for tools that need to act on behalf of a workspace's
-  active service grant.
-
-### Notes
-
-- `IdentityModule.listPendingInvitations` / `acceptInvitation` /
-  `declineInvitation` were already shipped in the alpha — no change.
-- Global-events SSE (`/v1/events`) is exposed as `chat.globalStream`
-  rather than its own module — an extra module would have meant a
-  duplicate config builder.
-- Tenant admin endpoints (members, resource overrides) deliberately
-  out of scope for `0.1.0`. Will land in a `0.2.x` once a consumer
-  needs them.
-
-### Dependencies
-
-- No runtime deps. The SDK is fetch + EventSource + plain TS. Bring
-  your own `EventSource` polyfill on React Native (see README).
-
-### Compatibility
-
-- Node 18+ (native fetch + WHATWG URL).
-- Browsers with `fetch`, `URL`, `URLSearchParams`, `EventSource`.
-- React Native — pass an `eventSource` constructor in
-  `chat.sessionStream({ eventSource })` and bring a fetch polyfill if
-  using a runtime older than RN 0.74.
+| Runtime | Supported |
+| --- | --- |
+| Browser (Chrome 103+, Firefox 102+, Safari 16+) | Yes |
+| Node 18+ | Yes |
+| React Native + `react-native-sse` polyfill | Yes |
+| Deno 1.40+ | Untested, should work |
+| Bun 1.0+ | Untested, should work |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Possibl AI Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -99,21 +99,6 @@ const stream = rcrt.chat.sessionStream(sessionId, handlers, {
 
 Browse `src/index.ts` for the full re-export list.
 
-### Module surface on `RcrtClient`
-
-```ts
-const rcrt = new RcrtClient({ apiUrl, tokenProvider });
-
-rcrt.auth          // identity, tenants, invitations, user profile
-rcrt.breadcrumbs   // CRUD + tag query + semantic search
-rcrt.chat          // send + sessionStream (per-session SSE) + globalStream (/v1/events)
-rcrt.cards         // JIT-UI card resolve + helpers
-rcrt.grants        // OAuth grants + initiate + resolveService
-rcrt.files         // upload / list / get / signed download / text extract / delete
-rcrt.sessions      // constellation + participants
-rcrt.capabilities  // tools / agents / services / knowledge discovery
-```
-
 ## Design notes
 
 - **Isomorphic**: zero DOM or Node-only APIs in the core. The only
@@ -142,11 +127,9 @@ Full narrative + concepts + operations playbook in
 
 ## Status
 
-**0.1.0** — first public release. Used by `possibl-ai/rcrt-template-mobile`
-and downstream apps (e.g. `possibl-ai/ritual-app`) as their canonical
-RCRT client. Surface stable; minor adjustments possible before 1.0.
-
-See [`CHANGELOG.md`](./CHANGELOG.md) for what's new in this release.
+**0.1.0-alpha** — first published alongside the OpenAPI v1 draft.
+Shape is stable for the documented surface; minor adjustments
+possible before 1.0.
 
 ## Licence
 

package/dist/auth.d.ts

@@ -0,0 +1,45 @@
+/**
+ * TokenProvider — the seam between RCRT and your identity source.
+ *
+ * The SDK never talks to Firebase / Auth0 / Clerk directly. You wire
+ * up whichever IdP you use by implementing this interface once. On
+ * every request the SDK calls `getIdToken()` to get a fresh bearer.
+ *
+ * The provider owns refresh. If your IdP supports it (Firebase does),
+ * it should return a token that's valid for at least the next ~60s;
+ * the SDK doesn't track expiry itself.
+ *
+ * Example Firebase (web):
+ *
+ *     import { getAuth } from 'firebase/auth';
+ *     const auth = getAuth();
+ *     const tokenProvider: TokenProvider = {
+ *       async getIdToken() {
+ *         const u = auth.currentUser;
+ *         if (!u) throw new SdkError('NOT_SIGNED_IN', 'Sign in first');
+ *         return u.getIdToken(false);
+ *       },
+ *     };
+ *
+ * Example test stub:
+ *
+ *     const tokenProvider: TokenProvider = {
+ *       async getIdToken() { return 'tk_test_workspace_api_key'; },
+ *     };
+ */
+export interface TokenProvider {
+    /**
+     * Return a bearer token for the next request. Throws or rejects if
+     * the user isn't signed in / the key is missing.
+     *
+     * Implementations SHOULD refresh transparently if they know the
+     * token is close to expiry. The SDK calls this per-request and
+     * doesn't cache.
+     */
+    getIdToken(): Promise<string>;
+    /** Optional hook: called on 401. Implementations can force a refresh. */
+    onUnauthorized?(): Promise<void>;
+}
+/** Convenience: a provider that returns a static string. For workspace API keys or tests. */
+export declare function staticTokenProvider(token: string): TokenProvider;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9B,yEAAyE;IACzE,cAAc,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAOhE"}

package/{src/auth.ts → dist/auth.js}

@@ -27,30 +27,15 @@
  *       async getIdToken() { return 'tk_test_workspace_api_key'; },
  *     };
  */
-
 import { SdkError } from './errors.js';
-
-export interface TokenProvider {
-  /**
-   * Return a bearer token for the next request. Throws or rejects if
-   * the user isn't signed in / the key is missing.
-   *
-   * Implementations SHOULD refresh transparently if they know the
-   * token is close to expiry. The SDK calls this per-request and
-   * doesn't cache.
-   */
-  getIdToken(): Promise<string>;
-
-  /** Optional hook: called on 401. Implementations can force a refresh. */
-  onUnauthorized?(): Promise<void>;
-}
-
 /** Convenience: a provider that returns a static string. For workspace API keys or tests. */
-export function staticTokenProvider(token: string): TokenProvider {
-  if (!token) throw new SdkError('EMPTY_TOKEN', 'staticTokenProvider called with empty token');
-  return {
-    async getIdToken() {
-      return token;
-    },
-  };
+export function staticTokenProvider(token) {
+    if (!token)
+        throw new SdkError('EMPTY_TOKEN', 'staticTokenProvider called with empty token');
+    return {
+        async getIdToken() {
+            return token;
+        },
+    };
 }
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAiBvC,6FAA6F;AAC7F,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,QAAQ,CAAC,aAAa,EAAE,6CAA6C,CAAC,CAAC;IAC7F,OAAO;QACL,KAAK,CAAC,UAAU;YACd,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/authn.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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';
+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 declare class IdentityModule {
+    private readonly ctx;
+    constructor(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.
+     */
+    me(): Promise<MeResponse>;
+    /** List workspaces the current user is a member of. */
+    listTenants(): Promise<Tenant[]>;
+    /** Confirm workspace membership. Client code is still responsible for setting X-Tenant-ID. */
+    selectTenant(tenantId: string): Promise<void>;
+    /** `POST /v1/auth/logout` — server-side no-op; included for symmetry + audit. */
+    logout(): Promise<void>;
+    /**
+     * `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.
+     */
+    deleteAccount(): Promise<void>;
+    /** Pending invitations keyed by the caller's email. */
+    listPendingInvitations(): Promise<PendingInvitation[]>;
+    acceptInvitation(token: string): Promise<void>;
+    declineInvitation(invitationId: string): Promise<void>;
+}
+//# sourceMappingURL=authn.d.ts.map

package/dist/authn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authn.d.ts","sourceRoot":"","sources":["../src/authn.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,iBAAiB,EAAE,OAAO,CAAC;IAC3B,aAAa,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D,aAAa,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,YAAY;IAE9C;;;;;OAKG;IACG,EAAE,IAAI,OAAO,CAAC,UAAU,CAAC;IAI/B,uDAAuD;IACjD,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAOtC,8FAA8F;IACxF,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnD,iFAAiF;IAC3E,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAO7B;;;;;;;OAOG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAOpC,uDAAuD;IACjD,sBAAsB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAOtD,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAK7D"}

package/dist/authn.js

@@ -0,0 +1,75 @@
+/**
+ * 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 { request } from './internal/fetch.js';
+export class IdentityModule {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * `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() {
+        return request(this.ctx, '/v1/auth/me', { skipTenant: true });
+    }
+    /** List workspaces the current user is a member of. */
+    async listTenants() {
+        const res = await request(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) {
+        await request(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() {
+        await request(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() {
+        await request(this.ctx, '/v1/auth/delete-account', {
+            method: 'POST',
+            skipTenant: true,
+        });
+    }
+    /** Pending invitations keyed by the caller's email. */
+    async listPendingInvitations() {
+        const res = await request(this.ctx, '/v1/invitations/pending');
+        return Array.isArray(res) ? res : (res.invitations ?? []);
+    }
+    async acceptInvitation(token) {
+        await request(this.ctx, '/v1/invitations/accept', {
+            method: 'POST',
+            body: { token },
+        });
+    }
+    async declineInvitation(invitationId) {
+        await request(this.ctx, `/v1/invitations/${invitationId}/decline`, {
+            method: 'POST',
+        });
+    }
+}
+//# sourceMappingURL=authn.js.map

package/dist/authn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authn.js","sourceRoot":"","sources":["../src/authn.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAmC9C,MAAM,OAAO,cAAc;IACI;IAA7B,YAA6B,GAAiB;QAAjB,QAAG,GAAH,GAAG,CAAc;IAAG,CAAC;IAElD;;;;;OAKG;IACH,KAAK,CAAC,EAAE;QACN,OAAO,OAAO,CAAa,IAAI,CAAC,GAAG,EAAE,aAAa,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,uDAAuD;IACvD,KAAK,CAAC,WAAW;QACf,MAAM,GAAG,GAAG,MAAM,OAAO,CAAmC,IAAI,CAAC,GAAG,EAAE,kBAAkB,EAAE;YACxF,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;QACH,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,8FAA8F;IAC9F,KAAK,CAAC,YAAY,CAAC,QAAgB;QACjC,MAAM,OAAO,CAAO,IAAI,CAAC,GAAG,EAAE,oBAAoB,QAAQ,SAAS,EAAE;YACnE,MAAM,EAAE,MAAM;YACd,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;IACL,CAAC;IAED,iFAAiF;IACjF,KAAK,CAAC,MAAM;QACV,MAAM,OAAO,CAAO,IAAI,CAAC,GAAG,EAAE,iBAAiB,EAAE;YAC/C,MAAM,EAAE,MAAM;YACd,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,aAAa;QACjB,MAAM,OAAO,CAAO,IAAI,CAAC,GAAG,EAAE,yBAAyB,EAAE;YACvD,MAAM,EAAE,MAAM;YACd,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;IACL,CAAC;IAED,uDAAuD;IACvD,KAAK,CAAC,sBAAsB;QAC1B,MAAM,GAAG,GAAG,MAAM,OAAO,CAEvB,IAAI,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC;QACvC,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,KAAa;QAClC,MAAM,OAAO,CAAO,IAAI,CAAC,GAAG,EAAE,wBAAwB,EAAE;YACtD,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE,KAAK,EAAE;SAChB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,iBAAiB,CAAC,YAAoB;QAC1C,MAAM,OAAO,CAAO,IAAI,CAAC,GAAG,EAAE,mBAAmB,YAAY,UAAU,EAAE;YACvE,MAAM,EAAE,MAAM;SACf,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/breadcrumbs.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 type { Breadcrumb, CreateBreadcrumbRequest, UpdateBreadcrumbRequest, QueryByTagsOptions, SemanticSearchOptions } from './types/breadcrumb.js';
+export declare class BreadcrumbsModule {
+    private readonly ctx;
+    constructor(ctx: FetchContext);
+    /** `POST /v1/breadcrumbs` */
+    create(req: CreateBreadcrumbRequest): Promise<Breadcrumb>;
+    /** `GET /v1/breadcrumbs?tags=...` — AND semantics. */
+    queryByTags(tags: string[], options?: QueryByTagsOptions): Promise<Breadcrumb[]>;
+    /** `GET /v1/breadcrumbs/search?q=...` — cosine-similarity semantic search. */
+    search(q: string, options?: SemanticSearchOptions): Promise<Breadcrumb[]>;
+    /** `GET /v1/breadcrumbs/{id}` */
+    get(id: string): Promise<Breadcrumb>;
+    /**
+     * `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.
+     */
+    update(id: string, req: UpdateBreadcrumbRequest, opts?: {
+        autoRetryConflict?: boolean;
+    }): Promise<Breadcrumb>;
+    /** `DELETE /v1/breadcrumbs/{id}` — soft delete. */
+    delete(id: string): Promise<void>;
+}
+//# sourceMappingURL=breadcrumbs.d.ts.map

package/dist/breadcrumbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"breadcrumbs.d.ts","sourceRoot":"","sources":["../src/breadcrumbs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EACV,UAAU,EAEV,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAG/B,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,YAAY;IAE9C,6BAA6B;IACvB,MAAM,CAAC,GAAG,EAAE,uBAAuB,GAAG,OAAO,CAAC,UAAU,CAAC;IAU/D,sDAAsD;IAChD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAgB1F,8EAA8E;IACxE,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAUnF,iCAAiC;IAC3B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAI1C;;;;;OAKG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,uBAAuB,EAC5B,IAAI,GAAE;QAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;KAAO,GACzC,OAAO,CAAC,UAAU,CAAC;IAyBtB,mDAAmD;IAC7C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAQxC"}

package/dist/breadcrumbs.js

@@ -0,0 +1,96 @@
+/**
+ * Breadcrumbs module — CRUD + tag query + semantic search.
+ *
+ * See `packages/docs/guides/04-breadcrumbs.md` for the narrative
+ * description of each operation.
+ */
+import { request } from './internal/fetch.js';
+import { ApiError, SdkError } from './errors.js';
+export class BreadcrumbsModule {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** `POST /v1/breadcrumbs` */
+    async create(req) {
+        const res = await request(this.ctx, '/v1/breadcrumbs', {
+            method: 'POST',
+            body: req,
+        });
+        return 'breadcrumb' in res
+            ? res.breadcrumb
+            : res;
+    }
+    /** `GET /v1/breadcrumbs?tags=...` — AND semantics. */
+    async queryByTags(tags, options = {}) {
+        if (tags.length === 0) {
+            throw new SdkError('EMPTY_TAGS', 'queryByTags requires at least one tag');
+        }
+        const res = await request(this.ctx, '/v1/breadcrumbs', {
+            query: {
+                tags,
+                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, options = {}) {
+        const query = {
+            q,
+            limit: options.limit,
+        };
+        if (options.tags?.length)
+            query.tags = options.tags;
+        const res = await request(this.ctx, '/v1/breadcrumbs/search', { query });
+        return Array.isArray(res) ? res : (res.breadcrumbs ?? []);
+    }
+    /** `GET /v1/breadcrumbs/{id}` */
+    async get(id) {
+        return request(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, req, opts = {}) {
+        const refetchBeforeRetry = opts.autoRetryConflict
+            ? async () => {
+                const fresh = await this.get(id);
+                return {
+                    body: {
+                        ...req,
+                        version: fresh.version,
+                    },
+                };
+            }
+            : undefined;
+        const res = await request(this.ctx, `/v1/breadcrumbs/${id}`, {
+            method: 'PATCH',
+            body: req,
+            ...(refetchBeforeRetry
+                ? { maxConflictRetries: 2, refetchBeforeRetry }
+                : {}),
+        });
+        return 'breadcrumb' in res
+            ? res.breadcrumb
+            : res;
+    }
+    /** `DELETE /v1/breadcrumbs/{id}` — soft delete. */
+    async delete(id) {
+        try {
+            await request(this.ctx, `/v1/breadcrumbs/${id}`, { method: 'DELETE' });
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.status === 404)
+                return; // idempotent
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=breadcrumbs.js.map

package/dist/breadcrumbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breadcrumbs.js","sourceRoot":"","sources":["../src/breadcrumbs.ts"],"names":[],"mappings":"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"}

package/dist/cards.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 type { Breadcrumb } from './types/breadcrumb.js';
+import type { Card, ResolveRequest } from './types/card.js';
+export declare class CardsModule {
+    private readonly ctx;
+    constructor(ctx: FetchContext);
+    /**
+     * PATCH the card breadcrumb with a resolution. Handles optimistic
+     * locking transparently — refetches + retries on 409.
+     */
+    resolve(breadcrumbId: string, resolution: ResolveRequest): Promise<Breadcrumb>;
+    /** Pending cards for the current user's current workspace. */
+    listPending(limit?: number): Promise<Breadcrumb[]>;
+    /**
+     * 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;
+}
+//# sourceMappingURL=cards.d.ts.map

package/dist/cards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cards.d.ts","sourceRoot":"","sources":["../src/cards.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG5D,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,YAAY;IAE9C;;;OAGG;IACG,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IAmCpF,8DAA8D;IACxD,WAAW,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAOpD;;;;OAIG;IACH,MAAM,CAAC,WAAW,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS;CAkBrD"}