@possibl/rcrt-sdk 0.1.2 → 0.5.0

package/dist/client.js

@@ -0,0 +1,133 @@
+/**
+ * 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.
+ *
+ * For fleet fan-out across workspaces, prefer `forTenant()` over
+ * mutating one client with `setTenantId()`:
+ *
+ *     await Promise.all(workspaces.map((ws) =>
+ *       rcrt.forTenant(ws.id).breadcrumbs.queryByTags(['interpret:alert']),
+ *     ));
+ */
+import { request } 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 { MarketplaceModule } from './marketplace.js';
+import { OrgModule } from './org.js';
+import { FilesModule } from './files.js';
+import { MembersModule } from './members.js';
+import { SdkError } from './errors.js';
+export class RcrtClient {
+    ctx;
+    config;
+    tenantClients = new Map();
+    auth;
+    breadcrumbs;
+    chat;
+    cards;
+    grants;
+    marketplace;
+    org;
+    files;
+    members;
+    constructor(config) {
+        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`');
+        }
+        this.config = config;
+        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({}, {
+            get: (_target, prop) => ctxInternal[prop],
+            set: (_target, prop, value) => {
+                ctxInternal[prop] = 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.marketplace = new MarketplaceModule(this.ctx);
+        this.org = new OrgModule(this.ctx);
+        this.files = new FilesModule(this.ctx);
+        this.members = new MembersModule(this.ctx);
+    }
+    /** Switch workspaces. Subsequent requests carry the new `X-Tenant-ID`. */
+    setTenantId(tenantId) {
+        this.ctx.tenantId = tenantId;
+    }
+    /** Read the workspace id this client is currently scoped to. */
+    getTenantId() {
+        return this.ctx.tenantId;
+    }
+    /**
+     * A client permanently bound to `tenantId` — same apiUrl, token
+     * provider and fetch impl, its own tenant header. Instances are
+     * cached per tenant and are just thin header wrappers, so parallel
+     * fleet fan-out is safe and cheap (no shared-client races, no
+     * serialisation through `setTenantId`).
+     */
+    forTenant(tenantId) {
+        if (!tenantId) {
+            throw new SdkError('MISSING_TENANT_ID', 'forTenant requires a tenant id');
+        }
+        let c = this.tenantClients.get(tenantId);
+        if (!c) {
+            const cfg = {
+                apiUrl: this.config.apiUrl,
+                tokenProvider: this.config.tokenProvider,
+                tenantId,
+            };
+            if (this.config.fetchImpl)
+                cfg.fetchImpl = this.config.fetchImpl;
+            c = new RcrtClient(cfg);
+            this.tenantClients.set(tenantId, c);
+        }
+        return c;
+    }
+    /**
+     * Typed escape hatch — call any gateway endpoint with the client's
+     * auth + tenant + retry handling. Apps are never blocked on an SDK
+     * release for a new endpoint:
+     *
+     *     const res = await rcrt.request<{ items: Item[] }>('/v1/some/new/endpoint', {
+     *       method: 'POST',
+     *       body: { hello: 'world' },   // plain object — the SDK serialises
+     *     });
+     *
+     * `options.body` is JSON-serialised; use `options.rawBody` for
+     * FormData / binary payloads; `options.query` appends search params.
+     */
+    async request(path, options = {}) {
+        return request(this.ctx, path, options);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare class ApiError extends Error {
+    readonly status: number;
+    readonly detail: ApiErrorDetail;
+    readonly rawBody: string | undefined;
+    constructor(status: number, detail: ApiErrorDetail, rawBody?: string);
+    static fromResponse(status: number, rawBody: string): ApiError;
+}
+/** Errors thrown by the SDK before we even reach the server. */
+export declare class SdkError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function parseErrorBody(status: number, rawBody: string): ApiErrorDetail;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iEAAiE;AACjE,MAAM,MAAM,cAAc,GACtB,cAAc,GACd,WAAW,GACX,WAAW,GACX,UAAU,GACV,iBAAiB,GACjB,mBAAmB,GACnB,UAAU,GACV,qBAAqB,GACrB,SAAS,CAAC;AAEd,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,IAAI,EAAE,cAAc,GAAG,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,MAAM,EAAE,cAAc,CAAC;IACvC,SAAgB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEhC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,MAAM;IAQpE,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ;CAG/D;AAED,gEAAgE;AAChE,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEjB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAeD,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CA4B9E"}

package/dist/errors.js

@@ -0,0 +1,76 @@
+/**
+ * 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`.
+ */
+export class ApiError extends Error {
+    status;
+    detail;
+    rawBody;
+    constructor(status, detail, rawBody) {
+        super(detail.message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.detail = detail;
+        this.rawBody = rawBody;
+    }
+    static fromResponse(status, rawBody) {
+        return new ApiError(status, parseErrorBody(status, rawBody), rawBody);
+    }
+}
+/** Errors thrown by the SDK before we even reach the server. */
+export class SdkError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SdkError';
+        this.code = code;
+    }
+}
+// ── Internal helpers ─────────────────────────────────────────────
+const STATUS_TO_CODE = {
+    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, rawBody) {
+    const fallbackCode = STATUS_TO_CODE[status] ?? 'UNKNOWN';
+    if (!rawBody.trim()) {
+        return { code: fallbackCode, message: `HTTP ${status}` };
+    }
+    try {
+        const parsed = JSON.parse(rawBody);
+        if (parsed && typeof parsed === 'object' && 'error' in parsed) {
+            const err = parsed.error;
+            if (typeof err === 'string') {
+                return { code: fallbackCode, message: err };
+            }
+            if (err && typeof err === 'object') {
+                const e = err;
+                const detail = {
+                    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;
+                }
+                return detail;
+            }
+        }
+        return { code: fallbackCode, message: rawBody.slice(0, 200) };
+    }
+    catch {
+        return { code: fallbackCode, message: rawBody.slice(0, 200) };
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/files.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Files module — `/v1/files` upload + retrieval.
+ *
+ * Uploads use multipart `FormData`, which is global in browsers,
+ * Node 18+ and React Native — no extra dependency needed. Every file
+ * lands as a breadcrumb, so downstream reads are normal breadcrumb
+ * reads too.
+ */
+import type { FetchContext } from './internal/fetch.js';
+import type { Breadcrumb } from './types/breadcrumb.js';
+export type FileScope = 'tenant' | 'org' | 'user';
+export interface UploadFileOptions {
+    /** Who can see the file. Default `'tenant'`. */
+    scope?: FileScope;
+    /** Override the filename recorded server-side (useful for raw Blobs). */
+    filename?: string;
+}
+export declare class FilesModule {
+    private readonly ctx;
+    constructor(ctx: FetchContext);
+    /**
+     * `POST /v1/files` — multipart upload. Returns the file's breadcrumb.
+     *
+     * Accepts a `File` (browser), `Blob`, or anything FormData takes.
+     */
+    upload(file: Blob, opts?: UploadFileOptions): Promise<Breadcrumb>;
+    /** `GET /v1/files` — file breadcrumbs visible at the given scope. */
+    list(opts?: {
+        scope?: FileScope;
+        limit?: number;
+    }): Promise<Breadcrumb[]>;
+    /** `GET /v1/files/{id}` */
+    get(fileId: string): Promise<Breadcrumb>;
+    /** `GET /v1/files/{id}/content` — short-lived signed download URL. */
+    downloadUrl(fileId: string, expiry?: string): Promise<string>;
+    /** `GET /v1/files/{id}/text` — extracted text content (PDFs, docs, …). */
+    getText(fileId: string): Promise<string>;
+    /** `DELETE /v1/files/{id}` */
+    delete(fileId: string): Promise<void>;
+}
+//# sourceMappingURL=files.d.ts.map

package/dist/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AAElD,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,YAAY;IAE9C;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC;IAe3E,qEAAqE;IAC/D,IAAI,CAAC,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,SAAS,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAOnF,2BAA2B;IACrB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAK9C,sEAAsE;IAChE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,SAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAOjE,0EAA0E;IACpE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK9C,8BAA8B;IACxB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG5C"}

package/dist/files.js

@@ -0,0 +1,64 @@
+/**
+ * Files module — `/v1/files` upload + retrieval.
+ *
+ * Uploads use multipart `FormData`, which is global in browsers,
+ * Node 18+ and React Native — no extra dependency needed. Every file
+ * lands as a breadcrumb, so downstream reads are normal breadcrumb
+ * reads too.
+ */
+import { request } from './internal/fetch.js';
+export class FilesModule {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * `POST /v1/files` — multipart upload. Returns the file's breadcrumb.
+     *
+     * Accepts a `File` (browser), `Blob`, or anything FormData takes.
+     */
+    async upload(file, opts = {}) {
+        const form = new FormData();
+        if (opts.filename)
+            form.append('file', file, opts.filename);
+        else
+            form.append('file', file);
+        form.append('scope', opts.scope ?? 'tenant');
+        const res = await request(this.ctx, '/v1/files', {
+            method: 'POST',
+            rawBody: form,
+        });
+        return 'breadcrumb' in res && res.breadcrumb
+            ? res.breadcrumb
+            : res;
+    }
+    /** `GET /v1/files` — file breadcrumbs visible at the given scope. */
+    async list(opts = {}) {
+        const res = await request(this.ctx, '/v1/files', {
+            query: { scope: opts.scope, limit: opts.limit ?? 50 },
+        });
+        return Array.isArray(res) ? res : (res?.files ?? []);
+    }
+    /** `GET /v1/files/{id}` */
+    async get(fileId) {
+        const res = await request(this.ctx, `/v1/files/${fileId}`);
+        return res.file ?? res;
+    }
+    /** `GET /v1/files/{id}/content` — short-lived signed download URL. */
+    async downloadUrl(fileId, expiry = '1h') {
+        const res = await request(this.ctx, `/v1/files/${fileId}/content`, {
+            query: { expiry },
+        });
+        return res.download_url;
+    }
+    /** `GET /v1/files/{id}/text` — extracted text content (PDFs, docs, …). */
+    async getText(fileId) {
+        const res = await request(this.ctx, `/v1/files/${fileId}/text`);
+        return res.text;
+    }
+    /** `DELETE /v1/files/{id}` */
+    async delete(fileId) {
+        await request(this.ctx, `/v1/files/${fileId}`, { method: 'DELETE' });
+    }
+}
+//# sourceMappingURL=files.js.map

package/dist/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAY9C,MAAM,OAAO,WAAW;IACO;IAA7B,YAA6B,GAAiB;QAAjB,QAAG,GAAH,GAAG,CAAc;IAAG,CAAC;IAElD;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,IAAU,EAAE,OAA0B,EAAE;QACnD,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;;YACvD,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC,CAAC;QAE7C,MAAM,GAAG,GAAG,MAAM,OAAO,CAA2C,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE;YACzF,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,IAAI;SACd,CAAC,CAAC;QACH,OAAO,YAAY,IAAK,GAAmC,IAAK,GAAmC,CAAC,UAAU;YAC5G,CAAC,CAAE,GAAkC,CAAC,UAAU;YAChD,CAAC,CAAE,GAAkB,CAAC;IAC1B,CAAC;IAED,qEAAqE;IACrE,KAAK,CAAC,IAAI,CAAC,OAA8C,EAAE;QACzD,MAAM,GAAG,GAAG,MAAM,OAAO,CAA0C,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE;YACxF,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE;SACtD,CAAC,CAAC;QACH,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,2BAA2B;IAC3B,KAAK,CAAC,GAAG,CAAC,MAAc;QACtB,MAAM,GAAG,GAAG,MAAM,OAAO,CAAqC,IAAI,CAAC,GAAG,EAAE,aAAa,MAAM,EAAE,CAAC,CAAC;QAC/F,OAAQ,GAA6B,CAAC,IAAI,IAAK,GAAkB,CAAC;IACpE,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,WAAW,CAAC,MAAc,EAAE,MAAM,GAAG,IAAI;QAC7C,MAAM,GAAG,GAAG,MAAM,OAAO,CAA2B,IAAI,CAAC,GAAG,EAAE,aAAa,MAAM,UAAU,EAAE;YAC3F,KAAK,EAAE,EAAE,MAAM,EAAE;SAClB,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,YAAY,CAAC;IAC1B,CAAC;IAED,0EAA0E;IAC1E,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAmB,IAAI,CAAC,GAAG,EAAE,aAAa,MAAM,OAAO,CAAC,CAAC;QAClF,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED,8BAA8B;IAC9B,KAAK,CAAC,MAAM,CAAC,MAAc;QACzB,MAAM,OAAO,CAAO,IAAI,CAAC,GAAG,EAAE,aAAa,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC7E,CAAC;CACF"}

package/dist/generated/conformance.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Contract conformance guardrail.
+ *
+ * Asserts at compile time that the hand-written domain types in
+ * `@possibl/rcrt-sdk/types` are structurally compatible with the
+ * OpenAPI spec. If the spec drifts (new required field, renamed prop,
+ * changed enum) without a matching hand-written update, `tsc` fails
+ * here and the PR is blocked until the two are re-aligned.
+ *
+ * The asserts are one-directional. They check that our domain shape
+ * ⊇ the wire shape (we accept everything the server sends). We do
+ * NOT check the reverse — by design, hand-written types can be richer
+ * (flexible rows, normalised error envelope, etc.).
+ *
+ * If this file fails to compile:
+ * - Read the error message carefully — it points at the specific
+ *   property that diverged.
+ * - Either update the hand-written type to accept the new shape, or
+ *   update the OpenAPI spec if the code changed first (more common).
+ * - Re-run `pnpm run codegen` and commit the regenerated
+ *   `src/generated/openapi.ts` in the same PR.
+ */
+import type { components } from './openapi.js';
+import type { Card, Breadcrumb } from '../types/index.js';
+/**
+ * Compile-time assertion that `Got` extends `Expected`.
+ * Produces a type error at the `_check_*` declaration if not.
+ */
+type AssertExtends<Got, Expected> = Got extends Expected ? true : never;
+/**
+ * Our hand-written `Card` must accept every property required by the
+ * spec's `components.schemas.Card`. If you see an error here, the spec
+ * gained a required field that our type doesn't model. Update the type
+ * (preferred) or relax the spec.
+ *
+ * We use Pick<…, X> so the assertion only covers the fields we've
+ * explicitly opted into. Ignoring fields we don't surface (e.g. legacy
+ * spec-level extras) is intentional.
+ */
+type _check_card_layout = AssertExtends<Pick<Card, 'layout' | 'header'>, Pick<components['schemas']['Card'], 'layout' | 'header'>>;
+/**
+ * Breadcrumb.content is an open `Record<string, unknown>` — intentional.
+ * Only check the metadata fields that are load-bearing for the SDK.
+ */
+type _check_breadcrumb_core = AssertExtends<Pick<Breadcrumb, 'id' | 'tags' | 'content'>, Pick<components['schemas']['Breadcrumb'], 'id' | 'tags' | 'content'>>;
+export type __conformanceGuards = [_check_card_layout, _check_breadcrumb_core];
+export {};
+//# sourceMappingURL=conformance.d.ts.map

package/dist/generated/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../src/generated/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI1D;;;GAGG;AACH,KAAK,aAAa,CAAC,GAAG,EAAE,QAAQ,IAAI,GAAG,SAAS,QAAQ,GAAG,IAAI,GAAG,KAAK,CAAC;AAIxE;;;;;;;;;GASG;AACH,KAAK,kBAAkB,GAAG,aAAa,CACrC,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC,EAC/B,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC,CACzD,CAAC;AAEF;;;GAGG;AACH,KAAK,sBAAsB,GAAG,aAAa,CACzC,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC,EAC3C,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC,CACrE,CAAC;AAGF,MAAM,MAAM,mBAAmB,GAAG,CAAC,kBAAkB,EAAE,sBAAsB,CAAC,CAAC"}

package/dist/generated/conformance.js

@@ -0,0 +1,24 @@
+/**
+ * Contract conformance guardrail.
+ *
+ * Asserts at compile time that the hand-written domain types in
+ * `@possibl/rcrt-sdk/types` are structurally compatible with the
+ * OpenAPI spec. If the spec drifts (new required field, renamed prop,
+ * changed enum) without a matching hand-written update, `tsc` fails
+ * here and the PR is blocked until the two are re-aligned.
+ *
+ * The asserts are one-directional. They check that our domain shape
+ * ⊇ the wire shape (we accept everything the server sends). We do
+ * NOT check the reverse — by design, hand-written types can be richer
+ * (flexible rows, normalised error envelope, etc.).
+ *
+ * If this file fails to compile:
+ * - Read the error message carefully — it points at the specific
+ *   property that diverged.
+ * - Either update the hand-written type to accept the new shape, or
+ *   update the OpenAPI spec if the code changed first (more common).
+ * - Re-run `pnpm run codegen` and commit the regenerated
+ *   `src/generated/openapi.ts` in the same PR.
+ */
+export {};
+//# sourceMappingURL=conformance.js.map

package/dist/generated/conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.js","sourceRoot":"","sources":["../../src/generated/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG"}

package/dist/generated/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Generated OpenAPI types.
+ *
+ * This module is produced by `pnpm run codegen` against
+ * `packages/docs/openapi/v1.yaml` — the hand-maintained API contract.
+ * Do NOT edit the generated file by hand. Edit the spec, then regenerate.
+ *
+ * ## When to use these types
+ *
+ * - **Raw fetch-level type safety** — e.g. you're bypassing the `RcrtClient`
+ *   and calling the HTTP endpoints directly. Use `paths`, `operations`, or
+ *   `components` to type request bodies + response shapes.
+ * - **Contract conformance checks** — asserting at compile time that a
+ *   hand-written type is a structural subset of the wire shape.
+ *
+ * ## When NOT to use these types
+ *
+ * - **Domain modelling in app code.** Prefer the hand-written types in
+ *   `@possibl/rcrt-sdk/types` (`Card`, `Breadcrumb`, `Row`, `ChartSpec`).
+ *   They are richer: documented flexibly (e.g. `FlexibleTextRow`),
+ *   discriminated-union-friendly, and wear the `ApiErrorDetail` shape
+ *   normalised across both the canonical and legacy error envelopes.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import type { components, operations } from '@possibl/rcrt-sdk/generated';
+ *
+ * type RawCard = components['schemas']['Card'];
+ * type ChatRequest = operations['post_v1_chat']['requestBody']['content']['application/json'];
+ * ```
+ */
+export type { paths, components, operations, webhooks } from './openapi.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/generated/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generated/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC"}

package/dist/generated/index.js

@@ -0,0 +1,34 @@
+/**
+ * Generated OpenAPI types.
+ *
+ * This module is produced by `pnpm run codegen` against
+ * `packages/docs/openapi/v1.yaml` — the hand-maintained API contract.
+ * Do NOT edit the generated file by hand. Edit the spec, then regenerate.
+ *
+ * ## When to use these types
+ *
+ * - **Raw fetch-level type safety** — e.g. you're bypassing the `RcrtClient`
+ *   and calling the HTTP endpoints directly. Use `paths`, `operations`, or
+ *   `components` to type request bodies + response shapes.
+ * - **Contract conformance checks** — asserting at compile time that a
+ *   hand-written type is a structural subset of the wire shape.
+ *
+ * ## When NOT to use these types
+ *
+ * - **Domain modelling in app code.** Prefer the hand-written types in
+ *   `@possibl/rcrt-sdk/types` (`Card`, `Breadcrumb`, `Row`, `ChartSpec`).
+ *   They are richer: documented flexibly (e.g. `FlexibleTextRow`),
+ *   discriminated-union-friendly, and wear the `ApiErrorDetail` shape
+ *   normalised across both the canonical and legacy error envelopes.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import type { components, operations } from '@possibl/rcrt-sdk/generated';
+ *
+ * type RawCard = components['schemas']['Card'];
+ * type ChatRequest = operations['post_v1_chat']['requestBody']['content']['application/json'];
+ * ```
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/generated/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/generated/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG"}