hci-atrium 0.1.0

package/dist/shaping/rooms.d.ts

@@ -0,0 +1,128 @@
+/** Sessions + rooms REST request shaping (mirror of ``_shaping`` room/session helpers). */
+import type { ShapedRequest } from "./request.js";
+export interface BuildRoomOpenInput {
+    name?: string;
+    project?: string;
+    embeddingSpace?: string;
+}
+/** Build the ``POST /v1/rooms`` body. ``project`` is already resolved. */
+export declare function buildRoomOpen(input: BuildRoomOpenInput): ShapedRequest;
+/** Build a ``POST /v1/rooms/{id}/rotate-code`` request (mint a fresh join code; no body). */
+export declare function buildRoomRotateCode(roomId: string): ShapedRequest;
+/** Build a ``GET /v1/rooms/resolve?code=…`` request (join-by-code lookup). */
+export declare function buildRoomResolve(code: string): ShapedRequest;
+export interface BuildRoomSignalInput {
+    type: string;
+    payload?: Record<string, unknown>;
+    source?: string | null;
+    ephemeral?: boolean;
+    connectionId?: string | null;
+    to?: string | string[] | null;
+    includeSelf?: boolean;
+    ackId?: string | null;
+    replyTo?: string | null;
+}
+/**
+ * Build the ``POST /v1/rooms/{id}/signal`` envelope — the REST signal wire (the cross-SDK contract
+ * pinned by the fixture corpus, and the Python SDK's send path). The live TS Room sends over its
+ * WebSocket instead, but the wire body is identical field-for-field, so this is the canonical shape.
+ */
+export declare function buildRoomSignal(roomId: string, input: BuildRoomSignalInput): ShapedRequest;
+export interface BuildPlayInput {
+    source: unknown;
+    layer?: string;
+    mode?: string;
+    transition?: string;
+    repeat?: boolean;
+    shuffle?: boolean;
+}
+/** Build a ``play`` signal body — one sound or an array, each coerced to a track dict. */
+export declare function buildPlayBody(input: BuildPlayInput): Record<string, unknown>;
+/** Build a ``layer.clear`` body (``layer`` omitted → ``"default"``; ``"*"`` → every layer). */
+export declare function buildLayerClearBody(layer?: string, fadeOutMs?: number): Record<string, unknown>;
+/**
+ * Build a ``layer.effects`` body, e.g. ``{ lowpass: { hz: 700 } }`` for a backroom muffle. The
+ * ``effects`` state is passed through as-is — ``lowpass`` / ``highpass`` / ``reverb`` / ``echo`` are
+ * all live keys (an absent implemented key ramps back to neutral). ``layer`` may be ``"*"`` to apply
+ * to every existing layer (mirrors ``layer.clear``'s wildcard).
+ */
+export declare function buildLayerEffectsBody(layer: string, effects: Record<string, unknown>, fadeMs?: number): Record<string, unknown>;
+export interface BuildLayerPositionInput {
+    layer: string;
+    x: number;
+    y: number;
+    z?: number;
+    fadeMs?: number;
+    distance?: Record<string, unknown>;
+}
+/**
+ * Build a ``layer.position`` body — ramped whole-layer HRTF placement. ``z`` defaults to 0; the
+ * optional ``distance`` attenuation config (``{ model, ref, max, rolloff }``) and ``fadeMs`` are
+ * omitted when absent (``distance`` absent → direction-only, today's behaviour). No ``"*"`` wildcard.
+ */
+export declare function buildLayerPositionBody(input: BuildLayerPositionInput): Record<string, unknown>;
+export interface BuildShowInput {
+    assetId?: string;
+    url?: string;
+    caption?: string;
+    projection?: string;
+}
+/**
+ * Build a ``show`` signal body. Exactly one of ``assetId`` / ``url`` must be given (both or neither
+ * throws); ``projection`` (when present) must be ``"flat"`` or ``"360"``. Absent keys are omitted —
+ * no nulls on the wire. camelCase API in, snake_case wire out.
+ */
+export declare function buildShowBody(input: BuildShowInput): Record<string, unknown>;
+export interface BuildSessionStartInput {
+    project?: string;
+    name?: string;
+    participantRef?: string;
+    condition?: string;
+    meta?: Record<string, unknown>;
+}
+/** Build the ``POST /v1/sessions`` body. ``project`` is already resolved. */
+export declare function buildSessionStart(input: BuildSessionStartInput): ShapedRequest;
+/** Build ``POST /v1/sessions/{id}/recordings`` — open a room-capture recording in a session (the
+ * offer-capture chunked wire; mirror of Python's inline ``_open_recording`` call). */
+export declare function buildRecordingCreate(sessionId: string, input: {
+    sourceName: string | null;
+    contentType: string;
+}): ShapedRequest;
+/** Build ``PUT /v1/sessions/{id}/recordings/{rid}/chunks`` — append one raw clip to an open
+ * recording (the clip's bytes as the body, its mime as the Content-Type). */
+export declare function buildRecordingChunk(sessionId: string, recordingId: string, data: ArrayBuffer, contentType: string): ShapedRequest;
+/** Build ``POST /v1/sessions/{id}/recordings/{rid}/finalize`` — close an open recording (no body). */
+export declare function buildRecordingFinalize(sessionId: string, recordingId: string): ShapedRequest;
+export interface BuildSessionEventInput {
+    type: string;
+    payload?: Record<string, unknown>;
+    source?: string;
+    via?: Record<string, unknown>;
+}
+/** Build a ``POST /v1/sessions/{id}/events`` body. */
+export declare function buildSessionEvent(sessionId: string, input: BuildSessionEventInput): ShapedRequest;
+/** Build a ``GET /v1/sessions`` list request. ``project`` (already resolved) filters by project;
+ * ``phase`` (a string or list) rides as repeated ``phase=`` query params — the empty string ``""``
+ * matches sessions with no phase set. */
+export declare function buildSessionsList(input: {
+    project?: string;
+    phase?: string | string[];
+}): ShapedRequest;
+/** Build a ``GET /v1/sessions/{id}/events/history`` request (durable log, ``seq > after``). */
+export declare function buildSessionEvents(sessionId: string, input?: {
+    after?: number;
+    limit?: number;
+}): ShapedRequest;
+/** The fixed export formats — each maps to a distinct ``/export/`` route segment (there is no
+ * ``?format=`` param server-side). */
+export type SessionExportFormat = "jsonl" | "csv" | "transcript" | "bundle";
+/** The multi-session bundle endpoint's per-call distinct-id cap (sessions/router.py). */
+export declare const SESSION_EXPORT_IDS_MAX = 100;
+/** Build a single-session export ``GET`` request, dispatching ``format`` to its fixed route. */
+export declare function buildSessionExport(sessionId: string, format: SessionExportFormat): ShapedRequest;
+/** Dedup export ids (order-preserving) and enforce the server's per-call cap — throw (never
+ * truncate / chunk) when exceeded or empty, naming the cap. */
+export declare function distinctExportIds(ids: string[]): string[];
+/** Build the multi-session ``GET /v1/sessions/export/bundle`` request (``ids`` already deduped). */
+export declare function buildSessionExportBundle(ids: string[]): ShapedRequest;
+//# sourceMappingURL=rooms.d.ts.map

package/dist/shaping/rooms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rooms.d.ts","sourceRoot":"","sources":["../../src/shaping/rooms.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAI3F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAYtE;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAEjE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAE5D;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAA;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,aAAa,CAa1F;AAkFD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoB5E;AAED,+FAA+F;AAC/F,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAK/F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzB;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAU9F;AAOD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAe5E;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,aAAa,CAkB9E;AAED;sFACsF;AACtF,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACxD,aAAa,CAMf;AAED;6EAC6E;AAC7E,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,WAAW,EACjB,WAAW,EAAE,MAAM,GAClB,aAAa,CAOf;AAED,sGAAsG;AACtG,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,CAK5F;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC9B;AAED,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,GAAG,aAAa,CAUjG;AAID;;yCAEyC;AACzC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAC1B,GAAG,aAAa,CAahB;AAED,+FAA+F;AAC/F,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,aAAa,CAaf;AAED;sCACsC;AACtC,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,QAAQ,CAAA;AAS3E,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAEzC,gGAAgG;AAChG,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,GAAG,aAAa,CAUhG;AAED;+DAC+D;AAC/D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAYzD;AAED,oGAAoG;AACpG,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,aAAa,CAErE"}

package/dist/shaping/rooms.js

@@ -0,0 +1,330 @@
+/** Sessions + rooms REST request shaping (mirror of ``_shaping`` room/session helpers). */
+import { InvalidArgumentError } from "../errors.js";
+import { assetPlayback } from "../models.js";
+/** Build the ``POST /v1/rooms`` body. ``project`` is already resolved. */
+export function buildRoomOpen(input) {
+    const body = {};
+    if (input.name !== undefined) {
+        body.name = input.name;
+    }
+    if (input.project !== undefined) {
+        body.project_id = input.project;
+    }
+    if (input.embeddingSpace !== undefined) {
+        body.embedding_space = input.embeddingSpace;
+    }
+    return { method: "POST", path: "/v1/rooms", json: body };
+}
+/** Build a ``POST /v1/rooms/{id}/rotate-code`` request (mint a fresh join code; no body). */
+export function buildRoomRotateCode(roomId) {
+    return { method: "POST", path: `/v1/rooms/${roomId}/rotate-code` };
+}
+/** Build a ``GET /v1/rooms/resolve?code=…`` request (join-by-code lookup). */
+export function buildRoomResolve(code) {
+    return { method: "GET", path: "/v1/rooms/resolve", query: { code } };
+}
+/**
+ * Build the ``POST /v1/rooms/{id}/signal`` envelope — the REST signal wire (the cross-SDK contract
+ * pinned by the fixture corpus, and the Python SDK's send path). The live TS Room sends over its
+ * WebSocket instead, but the wire body is identical field-for-field, so this is the canonical shape.
+ */
+export function buildRoomSignal(roomId, input) {
+    const body = {
+        type: input.type,
+        payload: input.payload ?? {},
+        source: input.source ?? null,
+        ephemeral: input.ephemeral ?? false,
+        connection_id: input.connectionId ?? null,
+        to: input.to ?? null,
+        include_self: input.includeSelf ?? false,
+        ack_id: input.ackId ?? null,
+        reply_to: input.replyTo ?? null,
+    };
+    return { method: "POST", path: `/v1/rooms/${roomId}/signal`, json: body };
+}
+// --- audio-layers dialect: `play` / `layer.*` body builders ------------------------------------
+// Port of ``hci_atrium._shaping``'s play/layer builders; the normative contract is
+// ``docs/reference/audio-layers-dialect.md``.
+const PLAY_MODES = new Set(["oneshot", "queue"]);
+const LAYER_TRANSITIONS = new Set(["now", "after_current", "queued"]);
+/**
+ * A parsed {@link ../models.Asset} always carries these computed URLs; a hand-rolled track dict
+ * won't. Used to tell an Asset object apart from a plain track dict — the deliberate TS stand-in
+ * for Python's ``isinstance(item, dict)`` split (below).
+ */
+function isAssetLike(obj) {
+    return (typeof obj.id === "string" && (obj.contentUrl !== undefined || obj.thumbnailUrl !== undefined));
+}
+/** Normalise one ``play`` source to a track dict (mirror of ``_shaping._coerce_track``). */
+function coerceTrack(item) {
+    if (typeof item === "string") {
+        return /^https?:\/\//.test(item) ? { content_url: item } : { asset_id: item };
+    }
+    if (item && typeof item === "object") {
+        const obj = item;
+        // Python passes any ``dict`` through untouched (``isinstance(item, dict)``); TypeScript has no
+        // dict/object split, so we pass an object through UNLESS it's recognizably a SearchHit (``.asset``
+        // present) or a parsed Asset (``isAssetLike`` — an id plus the computed content/thumbnail URLs a
+        // hand-rolled track dict won't carry). Deliberate deviation from Python's isinstance(dict) rule:
+        // it lets a hand-rolled track dict with an ``id`` key pass through rather than be read as an asset.
+        const wrapped = obj.asset; // a SearchHit wraps the asset it matched
+        if (wrapped && typeof wrapped === "object") {
+            return trackFromAsset(wrapped);
+        }
+        if (isAssetLike(obj)) {
+            return trackFromAsset(obj);
+        }
+        return obj;
+    }
+    throw new Error(`cannot play ${JSON.stringify(item)}: expected an asset, a URL/id string, or a track`);
+}
+/**
+ * Build a track dict from an {@link ../models.Asset}. A link-only asset (no stored bytes, but a
+ * provider link like Spotify) resolves through its typed ``playback`` intent — a target the Player
+ * can't reach from an asset id alone. A bytes-backed asset keeps the compact ``{ asset_id }`` form
+ * (the Player resolves the content from the id). Deviation from Python's ``_coerce_track``, which
+ * emits ``playback`` for every asset — the TS wire keeps ``asset_id`` for byte-backed content.
+ */
+function trackFromAsset(asset) {
+    if (!asset.sha256 && asset.sourceUrl) {
+        const track = { playback: assetPlayback(asset) };
+        const name = asset.title || asset.filename;
+        if (name)
+            track.name = name;
+        attachLoudness(track, asset);
+        return track;
+    }
+    const id = asset.id;
+    if (id) {
+        const track = { asset_id: String(id) };
+        attachLoudness(track, asset);
+        return track;
+    }
+    throw new Error(`cannot play ${JSON.stringify(asset)}: expected an asset, a URL/id string, or a track`);
+}
+/** Copy an asset's measured loudness facts onto a track so the Player can normalize without a fetch. */
+function attachLoudness(track, asset) {
+    const facts = asset.facts;
+    if (!facts || typeof facts !== "object")
+        return;
+    for (const key of ["loudness_lufs", "true_peak_db"]) {
+        const value = facts[key];
+        if (typeof value === "number")
+            track[key] = value;
+    }
+}
+/** Build a ``play`` signal body — one sound or an array, each coerced to a track dict. */
+export function buildPlayBody(input) {
+    const mode = input.mode ?? "oneshot";
+    if (!PLAY_MODES.has(mode)) {
+        throw new Error(`mode must be one of oneshot, queue, got ${JSON.stringify(mode)}`);
+    }
+    const items = Array.isArray(input.source) ? input.source : [input.source];
+    const body = { mode, tracks: items.map(coerceTrack) };
+    if (input.layer !== undefined)
+        body.layer = input.layer;
+    if (mode === "queue") {
+        const transition = input.transition ?? "now";
+        if (!LAYER_TRANSITIONS.has(transition)) {
+            throw new Error(`transition must be one of now, after_current, queued, got ${JSON.stringify(transition)}`);
+        }
+        body.transition = transition;
+        if (input.repeat)
+            body.repeat = true;
+        if (input.shuffle)
+            body.shuffle = true;
+    }
+    return body;
+}
+/** Build a ``layer.clear`` body (``layer`` omitted → ``"default"``; ``"*"`` → every layer). */
+export function buildLayerClearBody(layer, fadeOutMs) {
+    const body = {};
+    if (layer !== undefined)
+        body.layer = layer;
+    if (fadeOutMs !== undefined)
+        body.fade_out_ms = fadeOutMs;
+    return body;
+}
+/**
+ * Build a ``layer.effects`` body, e.g. ``{ lowpass: { hz: 700 } }`` for a backroom muffle. The
+ * ``effects`` state is passed through as-is — ``lowpass`` / ``highpass`` / ``reverb`` / ``echo`` are
+ * all live keys (an absent implemented key ramps back to neutral). ``layer`` may be ``"*"`` to apply
+ * to every existing layer (mirrors ``layer.clear``'s wildcard).
+ */
+export function buildLayerEffectsBody(layer, effects, fadeMs) {
+    const body = { layer, effects };
+    if (fadeMs !== undefined)
+        body.fade_ms = fadeMs;
+    return body;
+}
+/**
+ * Build a ``layer.position`` body — ramped whole-layer HRTF placement. ``z`` defaults to 0; the
+ * optional ``distance`` attenuation config (``{ model, ref, max, rolloff }``) and ``fadeMs`` are
+ * omitted when absent (``distance`` absent → direction-only, today's behaviour). No ``"*"`` wildcard.
+ */
+export function buildLayerPositionBody(input) {
+    const body = {
+        layer: input.layer,
+        x: input.x,
+        y: input.y,
+        z: input.z ?? 0,
+    };
+    if (input.fadeMs !== undefined)
+        body.fade_ms = input.fadeMs;
+    if (input.distance !== undefined)
+        body.distance = input.distance;
+    return body;
+}
+// --- viewer dialect: `show` / `show.clear` body builders --------------------------------------
+// The normative contract is ``docs/reference/viewer-dialect.md``.
+const VIEWER_PROJECTIONS = new Set(["flat", "360"]);
+/**
+ * Build a ``show`` signal body. Exactly one of ``assetId`` / ``url`` must be given (both or neither
+ * throws); ``projection`` (when present) must be ``"flat"`` or ``"360"``. Absent keys are omitted —
+ * no nulls on the wire. camelCase API in, snake_case wire out.
+ */
+export function buildShowBody(input) {
+    const hasAsset = input.assetId !== undefined;
+    const hasUrl = input.url !== undefined;
+    if (hasAsset === hasUrl) {
+        throw new Error("show() needs exactly one of assetId or url");
+    }
+    if (input.projection !== undefined && !VIEWER_PROJECTIONS.has(input.projection)) {
+        throw new Error(`projection must be one of flat, 360, got ${JSON.stringify(input.projection)}`);
+    }
+    const body = {};
+    if (input.assetId !== undefined)
+        body.asset_id = input.assetId;
+    if (input.url !== undefined)
+        body.url = input.url;
+    if (input.caption !== undefined)
+        body.caption = input.caption;
+    if (input.projection !== undefined)
+        body.projection = input.projection;
+    return body;
+}
+/** Build the ``POST /v1/sessions`` body. ``project`` is already resolved. */
+export function buildSessionStart(input) {
+    const body = {};
+    if (input.project !== undefined) {
+        body.project_id = input.project;
+    }
+    if (input.name !== undefined) {
+        body.name = input.name;
+    }
+    if (input.participantRef !== undefined) {
+        body.participant_ref = input.participantRef;
+    }
+    if (input.condition !== undefined) {
+        body.condition = input.condition;
+    }
+    if (input.meta !== undefined) {
+        body.meta = input.meta;
+    }
+    return { method: "POST", path: "/v1/sessions", json: body };
+}
+/** Build ``POST /v1/sessions/{id}/recordings`` — open a room-capture recording in a session (the
+ * offer-capture chunked wire; mirror of Python's inline ``_open_recording`` call). */
+export function buildRecordingCreate(sessionId, input) {
+    return {
+        method: "POST",
+        path: `/v1/sessions/${sessionId}/recordings`,
+        json: { source_name: input.sourceName, content_type: input.contentType },
+    };
+}
+/** Build ``PUT /v1/sessions/{id}/recordings/{rid}/chunks`` — append one raw clip to an open
+ * recording (the clip's bytes as the body, its mime as the Content-Type). */
+export function buildRecordingChunk(sessionId, recordingId, data, contentType) {
+    return {
+        method: "PUT",
+        path: `/v1/sessions/${sessionId}/recordings/${recordingId}/chunks`,
+        content: data,
+        contentType,
+    };
+}
+/** Build ``POST /v1/sessions/{id}/recordings/{rid}/finalize`` — close an open recording (no body). */
+export function buildRecordingFinalize(sessionId, recordingId) {
+    return {
+        method: "POST",
+        path: `/v1/sessions/${sessionId}/recordings/${recordingId}/finalize`,
+    };
+}
+/** Build a ``POST /v1/sessions/{id}/events`` body. */
+export function buildSessionEvent(sessionId, input) {
+    const body = {
+        type: input.type,
+        payload: input.payload ?? {},
+        source: input.source ?? null,
+    };
+    if (input.via !== undefined) {
+        body.via = input.via;
+    }
+    return { method: "POST", path: `/v1/sessions/${sessionId}/events`, json: body };
+}
+// --- sessions read-back + export ---------------------------------------------------------------
+/** Build a ``GET /v1/sessions`` list request. ``project`` (already resolved) filters by project;
+ * ``phase`` (a string or list) rides as repeated ``phase=`` query params — the empty string ``""``
+ * matches sessions with no phase set. */
+export function buildSessionsList(input) {
+    const query = {};
+    if (input.project !== undefined) {
+        query.project_id = input.project;
+    }
+    if (input.phase !== undefined) {
+        query.phase = typeof input.phase === "string" ? [input.phase] : [...input.phase];
+    }
+    const req = { method: "GET", path: "/v1/sessions" };
+    if (Object.keys(query).length) {
+        req.query = query;
+    }
+    return req;
+}
+/** Build a ``GET /v1/sessions/{id}/events/history`` request (durable log, ``seq > after``). */
+export function buildSessionEvents(sessionId, input = {}) {
+    const query = {};
+    if (input.after !== undefined) {
+        query.after = input.after;
+    }
+    if (input.limit !== undefined) {
+        query.limit = input.limit;
+    }
+    const req = { method: "GET", path: `/v1/sessions/${sessionId}/events/history` };
+    if (Object.keys(query).length) {
+        req.query = query;
+    }
+    return req;
+}
+const SESSION_EXPORT_ROUTES = {
+    jsonl: "events.jsonl",
+    csv: "events.csv",
+    transcript: "transcript.txt",
+    bundle: "bundle",
+};
+/** The multi-session bundle endpoint's per-call distinct-id cap (sessions/router.py). */
+export const SESSION_EXPORT_IDS_MAX = 100;
+/** Build a single-session export ``GET`` request, dispatching ``format`` to its fixed route. */
+export function buildSessionExport(sessionId, format) {
+    const segment = SESSION_EXPORT_ROUTES[format];
+    if (segment === undefined) {
+        throw new Error(`unknown export format ${JSON.stringify(format)}; expected one of ${Object.keys(SESSION_EXPORT_ROUTES).join(", ")}`);
+    }
+    return { method: "GET", path: `/v1/sessions/${sessionId}/export/${segment}` };
+}
+/** Dedup export ids (order-preserving) and enforce the server's per-call cap — throw (never
+ * truncate / chunk) when exceeded or empty, naming the cap. */
+export function distinctExportIds(ids) {
+    const distinct = [...new Set(ids)];
+    if (distinct.length === 0) {
+        throw new InvalidArgumentError("exportBundle: ids is required — pass at least one session id");
+    }
+    if (distinct.length > SESSION_EXPORT_IDS_MAX) {
+        throw new InvalidArgumentError(`exportBundle: ${distinct.length} distinct ids exceeds the server cap of ` +
+            `${SESSION_EXPORT_IDS_MAX} — split into batches of ${SESSION_EXPORT_IDS_MAX} or fewer`);
+    }
+    return distinct;
+}
+/** Build the multi-session ``GET /v1/sessions/export/bundle`` request (``ids`` already deduped). */
+export function buildSessionExportBundle(ids) {
+    return { method: "GET", path: "/v1/sessions/export/bundle", query: { ids } };
+}
+//# sourceMappingURL=rooms.js.map

package/dist/shaping/rooms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rooms.js","sourceRoot":"","sources":["../../src/shaping/rooms.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAE3F,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAc,aAAa,EAAE,MAAM,cAAc,CAAA;AASxD,0EAA0E;AAC1E,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,MAAM,IAAI,GAA4B,EAAE,CAAA;IACxC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;IACxB,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,OAAO,CAAA;IACjC,CAAC;IACD,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACvC,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,cAAc,CAAA;IAC7C,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AAC1D,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,MAAM,cAAc,EAAE,CAAA;AACpE,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,CAAA;AACtE,CAAC;AAcD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,KAA2B;IACzE,MAAM,IAAI,GAA4B;QACpC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;QAC5B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,KAAK;QACnC,aAAa,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;QACzC,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,IAAI;QACpB,YAAY,EAAE,KAAK,CAAC,WAAW,IAAI,KAAK;QACxC,MAAM,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI;QAC3B,QAAQ,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;KAChC,CAAA;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,MAAM,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AAC3E,CAAC;AAED,kGAAkG;AAClG,mFAAmF;AACnF,8CAA8C;AAE9C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAA;AAChD,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAA;AAErE;;;;GAIG;AACH,SAAS,WAAW,CAAC,GAA4B;IAC/C,OAAO,CACL,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAC/F,CAAA;AACH,CAAC;AAED,4FAA4F;AAC5F,SAAS,WAAW,CAAC,IAAa;IAChC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;IAC/E,CAAC;IACD,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAA+B,CAAA;QAC3C,+FAA+F;QAC/F,mGAAmG;QACnG,iGAAiG;QACjG,iGAAiG;QACjG,oGAAoG;QACpG,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAA,CAAC,yCAAyC;QACnE,IAAI,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC3C,OAAO,cAAc,CAAC,OAAgB,CAAC,CAAA;QACzC,CAAC;QACD,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO,cAAc,CAAC,GAAuB,CAAC,CAAA;QAChD,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,MAAM,IAAI,KAAK,CACb,eAAe,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,kDAAkD,CACtF,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,KAAY;IAClC,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACrC,MAAM,KAAK,GAA4B,EAAE,QAAQ,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,CAAA;QACzE,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAA;QAC1C,IAAI,IAAI;YAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAA;QAC3B,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;QAC5B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,EAAE,GAAG,KAAK,CAAC,EAAE,CAAA;IACnB,IAAI,EAAE,EAAE,CAAC;QACP,MAAM,KAAK,GAA4B,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;QAC/D,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;QAC5B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,IAAI,KAAK,CACb,eAAe,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,kDAAkD,CACvF,CAAA;AACH,CAAC;AAED,wGAAwG;AACxG,SAAS,cAAc,CAAC,KAA8B,EAAE,KAA0B;IAChF,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;IACzB,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAM;IAC/C,KAAK,MAAM,GAAG,IAAI,CAAC,eAAe,EAAE,cAAc,CAAC,EAAE,CAAC;QACpD,MAAM,KAAK,GAAI,KAAiC,CAAC,GAAG,CAAC,CAAA;QACrD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;IACnD,CAAC;AACH,CAAC;AAWD,0FAA0F;AAC1F,MAAM,UAAU,aAAa,CAAC,KAAqB;IACjD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,SAAS,CAAA;IACpC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,2CAA2C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACpF,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IACzE,MAAM,IAAI,GAA4B,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAA;IAC9E,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;IACvD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,KAAK,CAAA;QAC5C,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACb,6DAA6D,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAC1F,CAAA;QACH,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;QAC5B,IAAI,KAAK,CAAC,MAAM;YAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QACpC,IAAI,KAAK,CAAC,OAAO;YAAE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;IACxC,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,mBAAmB,CAAC,KAAc,EAAE,SAAkB;IACpE,MAAM,IAAI,GAA4B,EAAE,CAAA;IACxC,IAAI,KAAK,KAAK,SAAS;QAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IAC3C,IAAI,SAAS,KAAK,SAAS;QAAE,IAAI,CAAC,WAAW,GAAG,SAAS,CAAA;IACzD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAa,EACb,OAAgC,EAChC,MAAe;IAEf,MAAM,IAAI,GAA4B,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;IACxD,IAAI,MAAM,KAAK,SAAS;QAAE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IAC/C,OAAO,IAAI,CAAA;AACb,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAA8B;IACnE,MAAM,IAAI,GAA4B;QACpC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,CAAC,EAAE,KAAK,CAAC,CAAC;QACV,CAAC,EAAE,KAAK,CAAC,CAAC;QACV,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC;KAChB,CAAA;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAA;IAC3D,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;IAChE,OAAO,IAAI,CAAA;AACb,CAAC;AAED,iGAAiG;AACjG,kEAAkE;AAElE,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;AASnD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAqB;IACjD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,KAAK,SAAS,CAAA;IAC5C,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,KAAK,SAAS,CAAA;IACtC,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAA;IAC/D,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QAChF,MAAM,IAAI,KAAK,CAAC,4CAA4C,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IACjG,CAAC;IACD,MAAM,IAAI,GAA4B,EAAE,CAAA;IACxC,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAA;IAC9D,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;QAAE,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAA;IACjD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAA;IAC7D,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAA;IACtE,OAAO,IAAI,CAAA;AACb,CAAC;AAUD,6EAA6E;AAC7E,MAAM,UAAU,iBAAiB,CAAC,KAA6B;IAC7D,MAAM,IAAI,GAA4B,EAAE,CAAA;IACxC,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,OAAO,CAAA;IACjC,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;IACxB,CAAC;IACD,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACvC,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,cAAc,CAAA;IAC7C,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAA;IAClC,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;IACxB,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AAC7D,CAAC;AAED;sFACsF;AACtF,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,KAAyD;IAEzD,OAAO;QACL,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,gBAAgB,SAAS,aAAa;QAC5C,IAAI,EAAE,EAAE,WAAW,EAAE,KAAK,CAAC,UAAU,EAAE,YAAY,EAAE,KAAK,CAAC,WAAW,EAAE;KACzE,CAAA;AACH,CAAC;AAED;6EAC6E;AAC7E,MAAM,UAAU,mBAAmB,CACjC,SAAiB,EACjB,WAAmB,EACnB,IAAiB,EACjB,WAAmB;IAEnB,OAAO;QACL,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,gBAAgB,SAAS,eAAe,WAAW,SAAS;QAClE,OAAO,EAAE,IAAI;QACb,WAAW;KACZ,CAAA;AACH,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,sBAAsB,CAAC,SAAiB,EAAE,WAAmB;IAC3E,OAAO;QACL,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,gBAAgB,SAAS,eAAe,WAAW,WAAW;KACrE,CAAA;AACH,CAAC;AASD,sDAAsD;AACtD,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,KAA6B;IAChF,MAAM,IAAI,GAA4B;QACpC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;QAC5B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;KAC7B,CAAA;IACD,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAA;IACtB,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,SAAS,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AACjF,CAAC;AAED,kGAAkG;AAElG;;yCAEyC;AACzC,MAAM,UAAU,iBAAiB,CAAC,KAGjC;IACC,MAAM,KAAK,GAA6D,EAAE,CAAA;IAC1E,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,OAAO,CAAA;IAClC,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,KAAK,GAAG,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAA;IAClF,CAAC;IACD,MAAM,GAAG,GAAkB,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,CAAA;IAClE,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC9B,GAAG,CAAC,KAAK,GAAG,KAAK,CAAA;IACnB,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,kBAAkB,CAChC,SAAiB,EACjB,QAA4C,EAAE;IAE9C,MAAM,KAAK,GAA6D,EAAE,CAAA;IAC1E,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;IAC3B,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;IAC3B,CAAC;IACD,MAAM,GAAG,GAAkB,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,SAAS,iBAAiB,EAAE,CAAA;IAC9F,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC9B,GAAG,CAAC,KAAK,GAAG,KAAK,CAAA;IACnB,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAMD,MAAM,qBAAqB,GAAwC;IACjE,KAAK,EAAE,cAAc;IACrB,GAAG,EAAE,YAAY;IACjB,UAAU,EAAE,gBAAgB;IAC5B,MAAM,EAAE,QAAQ;CACjB,CAAA;AAED,yFAAyF;AACzF,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAA;AAEzC,gGAAgG;AAChG,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,MAA2B;IAC/E,MAAM,OAAO,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAA;IAC7C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,qBAAqB,MAAM,CAAC,IAAI,CAC7E,qBAAqB,CACtB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACf,CAAA;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,SAAS,WAAW,OAAO,EAAE,EAAE,CAAA;AAC/E,CAAC;AAED;+DAC+D;AAC/D,MAAM,UAAU,iBAAiB,CAAC,GAAa;IAC7C,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;IAClC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,oBAAoB,CAAC,8DAA8D,CAAC,CAAA;IAChG,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,GAAG,sBAAsB,EAAE,CAAC;QAC7C,MAAM,IAAI,oBAAoB,CAC5B,iBAAiB,QAAQ,CAAC,MAAM,0CAA0C;YACxE,GAAG,sBAAsB,4BAA4B,sBAAsB,WAAW,CACzF,CAAA;IACH,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,wBAAwB,CAAC,GAAa;IACpD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,4BAA4B,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE,CAAA;AAC9E,CAAC"}

package/dist/shaping/sources.d.ts

@@ -0,0 +1,29 @@
+/** External-sources request shaping (mirror of ``_shaping`` source helpers). */
+import type { Candidate } from "../models.js";
+import type { ShapedRequest } from "./request.js";
+export interface BuildSourcesSearchInput {
+    query: string;
+    providers?: string | string[];
+    k: number;
+    mode?: string;
+    modality?: string;
+}
+/**
+ * Build the multi-provider fan-out request (``POST /v1/library/sources/search``). A single
+ * ``providers`` string is normalised to a one-item list; ``k`` is clamped server-side.
+ */
+export declare function buildSourcesSearch(input: BuildSourcesSearchInput): ShapedRequest;
+/**
+ * Resolve an import to its ``[sourceId, externalId]`` — from a {@link Candidate} (its provider +
+ * externalId), or the explicit pair. Exactly one form must be given.
+ */
+export declare function resolveImportTarget(candidate: Candidate | undefined, sourceId: string | undefined, externalId: string | undefined): [string, string];
+export interface BuildSourceImportInput {
+    sourceId: string;
+    externalId: string;
+    modality?: string;
+    description?: string;
+}
+/** Build the import request (``POST /v1/library/sources/{id}/import``). */
+export declare function buildSourceImport(input: BuildSourceImportInput): ShapedRequest;
+//# sourceMappingURL=sources.d.ts.map

package/dist/shaping/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../src/shaping/sources.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAGhF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC7B,CAAC,EAAE,MAAM,CAAA;IACT,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,aAAa,CAYhF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,CAAC,MAAM,EAAE,MAAM,CAAC,CAWlB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,aAAa,CAa9E"}

package/dist/shaping/sources.js

@@ -0,0 +1,51 @@
+/** External-sources request shaping (mirror of ``_shaping`` source helpers). */
+import { InvalidArgumentError } from "../errors.js";
+/**
+ * Build the multi-provider fan-out request (``POST /v1/library/sources/search``). A single
+ * ``providers`` string is normalised to a one-item list; ``k`` is clamped server-side.
+ */
+export function buildSourcesSearch(input) {
+    const body = { query: input.query, k: input.k };
+    if (input.providers !== undefined) {
+        body.providers = typeof input.providers === "string" ? [input.providers] : [...input.providers];
+    }
+    if (input.mode !== undefined) {
+        body.mode = input.mode;
+    }
+    if (input.modality !== undefined) {
+        body.modality = input.modality;
+    }
+    return { method: "POST", path: "/v1/library/sources/search", json: body };
+}
+/**
+ * Resolve an import to its ``[sourceId, externalId]`` — from a {@link Candidate} (its provider +
+ * externalId), or the explicit pair. Exactly one form must be given.
+ */
+export function resolveImportTarget(candidate, sourceId, externalId) {
+    if (candidate !== undefined) {
+        if (sourceId !== undefined || externalId !== undefined) {
+            throw new InvalidArgumentError("pass either a candidate or sourceId + externalId, not both");
+        }
+        return [candidate.provider, candidate.externalId];
+    }
+    if (sourceId === undefined || externalId === undefined) {
+        throw new InvalidArgumentError("pass a candidate, or both sourceId and externalId");
+    }
+    return [sourceId, externalId];
+}
+/** Build the import request (``POST /v1/library/sources/{id}/import``). */
+export function buildSourceImport(input) {
+    const body = { external_id: input.externalId };
+    if (input.modality !== undefined) {
+        body.modality = input.modality;
+    }
+    if (input.description !== undefined) {
+        body.description = input.description;
+    }
+    return {
+        method: "POST",
+        path: `/v1/library/sources/${input.sourceId}/import`,
+        json: body,
+    };
+}
+//# sourceMappingURL=sources.js.map

package/dist/shaping/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../../src/shaping/sources.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAYnD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAA8B;IAC/D,MAAM,IAAI,GAA4B,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAA;IACxE,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,CAAA;IACjG,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;IACxB,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;IAChC,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,4BAA4B,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AAC3E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAgC,EAChC,QAA4B,EAC5B,UAA8B;IAE9B,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,QAAQ,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YACvD,MAAM,IAAI,oBAAoB,CAAC,4DAA4D,CAAC,CAAA;QAC9F,CAAC;QACD,OAAO,CAAC,SAAS,CAAC,QAAQ,EAAE,SAAS,CAAC,UAAU,CAAC,CAAA;IACnD,CAAC;IACD,IAAI,QAAQ,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QACvD,MAAM,IAAI,oBAAoB,CAAC,mDAAmD,CAAC,CAAA;IACrF,CAAC;IACD,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;AAC/B,CAAC;AASD,2EAA2E;AAC3E,MAAM,UAAU,iBAAiB,CAAC,KAA6B;IAC7D,MAAM,IAAI,GAA4B,EAAE,WAAW,EAAE,KAAK,CAAC,UAAU,EAAE,CAAA;IACvE,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;IAChC,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAA;IACtC,CAAC;IACD,OAAO;QACL,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,uBAAuB,KAAK,CAAC,QAAQ,SAAS;QACpD,IAAI,EAAE,IAAI;KACX,CAAA;AACH,CAAC"}

package/dist/shaping/structured.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Structured-output plumbing — the mirror of ``_structured.py``, using **Zod** as the OpenAI TS SDK
+ * does (decision 3). Zod is an *optional* peer dependency: nothing here imports it at module top;
+ * a schema is duck-typed at runtime and the module is loaded lazily only to derive its JSON Schema.
+ *
+ * The flow (client-orchestrated, like Python's): send the schema as OpenAI's ``json_schema``
+ * response_format, validate the reply, and on failure run ONE repair turn before throwing
+ * {@link StructuredOutputError}. The pure pieces (JSON extraction, validation, repair messages) live
+ * here; the client owns the two ``chat`` calls.
+ */
+import { StructuredOutputError } from "../errors.js";
+import type { ChatMessage } from "./chat.js";
+/** The slice of a Zod schema this module relies on (v3 and v4 both satisfy it). */
+export interface ZodLike<T = unknown> {
+    safeParse(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: unknown;
+    };
+}
+/** A safe, universally-supported response_format for the repair turn: plain JSON mode. */
+export declare const JSON_OBJECT: {
+    readonly type: "json_object";
+};
+/** True when ``value`` looks like a Zod schema (the structured-output path). */
+export declare function isZodSchema(value: unknown): value is ZodLike;
+/**
+ * Build the OpenAI ``json_schema`` response_format for a Zod schema. Async because it lazily loads
+ * Zod (v4's ``z.toJSONSchema``) — never imported at module top so the SDK installs without Zod.
+ * Throws {@link InvalidArgumentError} when Zod (v4+) isn't resolvable.
+ */
+export declare function responseFormatParam(schema: ZodLike, name?: string): Promise<Record<string, unknown>>;
+/**
+ * Validate ``text`` into ``schema``. Returns ``[value, ""]`` on success or ``[null, detail]`` with
+ * a human-readable reason on failure (never throws).
+ */
+export declare function tryParse<T>(schema: ZodLike<T>, text: string): [T | null, string];
+/**
+ * The message list for the single repair turn: the prior turns, the model's bad reply, and a
+ * correction quoting the error and the JSON schema to conform to.
+ */
+export declare function repairMessages(messages: ChatMessage[], badReply: string, detail: string, jsonSchema: unknown): ChatMessage[];
+/** Build the terminal error raised when the repair turn still didn't yield valid output. */
+export declare function structuredError(schemaName: string, raw: string, detail: string): StructuredOutputError;
+//# sourceMappingURL=structured.d.ts.map

package/dist/shaping/structured.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured.d.ts","sourceRoot":"","sources":["../../src/shaping/structured.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAwB,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAE5C,mFAAmF;AACnF,MAAM,WAAW,OAAO,CAAC,CAAC,GAAG,OAAO;IAClC,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAA;CAC1F;AAED,0FAA0F;AAC1F,eAAO,MAAM,WAAW;;CAAmC,CAAA;AAK3D,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAO5D;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,OAAO,EACf,IAAI,SAAa,GAChB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAkBlC;AAoCD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAUhF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,WAAW,EAAE,EACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,OAAO,GAClB,WAAW,EAAE,CAWf;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,qBAAqB,CAEvB"}