hci-atrium 0.1.0

package/dist/atrium.js

@@ -0,0 +1,806 @@
+/** The ``Atrium`` client — the entry point that owns auth, an authenticated transport, and the
+ * phase-1 namespaces (``library`` / ``assets`` / ``sources`` / ``sessions`` / ``rooms``) plus the
+ * ``chat`` and ``embed`` methods. */
+import { Auth } from "./auth.js";
+import { seedAssetId, toOperand } from "./by.js";
+import { DEFAULT_BASE_URL, readEnv } from "./env.js";
+import { AuthError, InvalidArgumentError, raiseForStatus } from "./errors.js";
+import { httpFetch } from "./http.js";
+import { parseAsset, parseAssetPage, parseAssetVector, parseChatReply, parseCompareResult, parseEmbedding, parseIndexEntry, parseRoom, parseSearchByExamplesHit, parseSearchHit, parseSegment, parseSession, parseSessionEvent, parseSessionEventRow, parseSessionInfo, parseSourceInfo, parseSourceSearchResult, parseSpace, parseTagDefinition, parseTranscript, } from "./models.js";
+import { Room } from "./rooms/index.js";
+import { buildAssetGet, buildAssetIndex, buildAssetList, buildAssetSegments, buildAssetVectors, buildBulkVectors, buildChat, buildCompare, buildEmbed, buildEnrich, buildRoomOpen, buildSearch, buildSearchByExamples, buildSessionEvent, buildSessionEvents, buildSessionExport, buildSessionExportBundle, buildSessionStart, buildSessionsList, buildSourceImport, buildSourcesSearch, buildTagGet, buildTagsList, buildTranscribe, buildUpload, chatBody, distinctExportIds, isZodSchema, JSON_OBJECT, repairMessages, resolveImportTarget, responseFormatParam, structuredError, tryParse, } from "./shaping/index.js";
+import { buildRoomResolve } from "./shaping/rooms.js";
+import { PkceStore, TokenStore } from "./storage.js";
+import { transcribeEngine } from "./transcribe.js";
+export { DEFAULT_BASE_URL };
+// Emitted at most once per page load: an API key in a browser is readable by anyone on the page.
+let browserKeyWarned = false;
+/**
+ * Combine two abort signals into one that fires when either does. Returns the linked signal plus a
+ * ``dispose`` the caller runs once the request settles — so the listeners on a long-lived signal
+ * (the client lifecycle) don't accumulate across every request. Uses ``AbortSignal.any`` where
+ * available (no listeners to clean up); the fallback removes both listeners on ``dispose``.
+ */
+function linkSignals(a, b) {
+    const noop = () => { };
+    if (!a)
+        return { signal: b, dispose: noop };
+    if (!b)
+        return { signal: a, dispose: noop };
+    const anyOf = AbortSignal.any;
+    if (anyOf)
+        return { signal: anyOf([a, b]), dispose: noop };
+    const ctrl = new AbortController();
+    if (a.aborted || b.aborted) {
+        ctrl.abort();
+        return { signal: ctrl.signal, dispose: noop };
+    }
+    const onAbort = () => ctrl.abort();
+    a.addEventListener("abort", onAbort);
+    b.addEventListener("abort", onAbort);
+    return {
+        signal: ctrl.signal,
+        dispose: () => {
+            a.removeEventListener("abort", onAbort);
+            b.removeEventListener("abort", onAbort);
+        },
+    };
+}
+/** Resolve a {@link FileSource} to a Blob (fetching a URL string) for a multipart upload. */
+async function toBlob(source) {
+    if (typeof source === "string") {
+        const res = await httpFetch(source);
+        const blob = await res.blob();
+        return { blob, filename: source.split("/").pop() || "upload" };
+    }
+    const filename = source.name ?? "upload";
+    return { blob: source, filename };
+}
+function bytesToBase64(bytes) {
+    const g = globalThis;
+    if (g.Buffer) {
+        return g.Buffer.from(bytes).toString("base64");
+    }
+    let binary = "";
+    for (const b of bytes) {
+        binary += String.fromCharCode(b);
+    }
+    return btoa(binary);
+}
+/**
+ * A client bound to one Atrium instance and one credential (an OAuth ``clientId`` or an ``apiKey``).
+ *
+ * Construction is import-safe and side-effect-light. Namespaces (``library`` / ``assets`` /
+ * ``sources`` / ``sessions`` / ``rooms``) and the ``chat`` / ``embed`` methods each shape a request,
+ * send it over the authenticated transport, and parse the response. ``close()`` (or
+ * ``await using``) aborts any in-flight calls.
+ */
+export class Atrium {
+    /** The auth module: ``signIn``, ``signOut``, ``user``, ``onChange`` (OAuth path). */
+    auth;
+    baseUrl;
+    clientId;
+    library;
+    assets;
+    sources;
+    sessions;
+    rooms;
+    apiKey;
+    defaultProject;
+    defaultCollection;
+    lifecycle = new AbortController();
+    spacesPromise = null;
+    constructor(opts = {}) {
+        const baseUrl = (opts.baseUrl ?? readEnv("ATRIUM_BASE_URL") ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.baseUrl = baseUrl;
+        this.clientId = opts.clientId ?? readEnv("ATRIUM_CLIENT_ID");
+        this.apiKey = opts.apiKey ?? readEnv("ATRIUM_API_KEY");
+        this.defaultProject = opts.project;
+        this.defaultCollection = opts.collection;
+        if (this.apiKey && typeof window !== "undefined" && !browserKeyWarned) {
+            browserKeyWarned = true;
+            console.info("Atrium: this page carries an API key — fine for local research setups; " +
+                "use Sign in with Atrium for anything hosted.");
+        }
+        const namespaceId = this.clientId ?? "";
+        this.auth = new Auth(baseUrl, this.clientId, new TokenStore(baseUrl, namespaceId), new PkceStore(baseUrl, namespaceId));
+        this.library = new Library(this);
+        this.assets = new Assets(this);
+        this.sources = new Sources(this);
+        this.sessions = new Sessions(this);
+        this.rooms = new Rooms(this);
+    }
+    /**
+     * ``fetch`` against this instance with the signed-in user's bearer token attached, silent refresh,
+     * and a one-shot retry on 401. Relative paths resolve against ``baseUrl``.
+     */
+    fetch(path, init) {
+        return this.auth.apiFetch(path, init);
+    }
+    /** Resolves once initial auth (callback handling / session resume) has settled. */
+    ready() {
+        return this.auth.ready();
+    }
+    /** Abort any in-flight requests. Idempotent; called automatically by ``await using``. */
+    async close() {
+        this.lifecycle.abort();
+    }
+    async chat(messages, opts = {}) {
+        const { model, responseFormat, strictParams, signal, ...params } = opts;
+        if (isZodSchema(responseFormat)) {
+            return this.chatParse(messages, model, responseFormat, params, signal, strictParams);
+        }
+        const p = { ...params };
+        if (responseFormat !== undefined) {
+            p.response_format = responseFormat;
+        }
+        if (strictParams) {
+            p.strict_params = true;
+        }
+        const data = await this.request(buildChat(chatBody(messages, model, p)), signal);
+        return parseChatReply(data);
+    }
+    async chatParse(messages, model, schema, params, signal, strictParams) {
+        const msgs = typeof messages === "string" ? [{ role: "user", content: messages }] : [...messages];
+        const rf = await responseFormatParam(schema);
+        const jsonSchema = rf.json_schema.schema;
+        const first = (await this.chat(msgs, {
+            model,
+            responseFormat: rf,
+            strictParams,
+            signal,
+            ...params,
+        }));
+        let [value, detail] = tryParse(schema, first.content);
+        if (value !== null) {
+            return value;
+        }
+        const repaired = repairMessages(msgs, first.content, detail, jsonSchema);
+        const second = (await this.chat(repaired, {
+            model,
+            responseFormat: JSON_OBJECT,
+            strictParams,
+            signal,
+            ...params,
+        }));
+        [value, detail] = tryParse(schema, second.content);
+        if (value !== null) {
+            return value;
+        }
+        throw structuredError(schema.constructor.name, second.content, detail);
+    }
+    /**
+     * Embed text or a media file into a vector (``POST /v1/embeddings``). Pass exactly one of
+     * ``text`` / ``image`` / ``audio`` / ``video``. ``model`` is required — an embedding's model is
+     * part of your data contract.
+     */
+    async embed(opts) {
+        const { text, model, image, audio, video, format, signal } = opts;
+        const medias = [
+            ["image", image],
+            ["audio", audio],
+            ["video", video],
+        ].filter(([, src]) => src !== undefined);
+        let media;
+        if (medias.length === 1) {
+            const [kind, src] = medias[0];
+            media = await this.encodeMedia(kind, src, format);
+        }
+        const data = await this.request(buildEmbed(model, text, media), signal);
+        return parseEmbedding(data);
+    }
+    /**
+     * Transcribe speech to text (``POST /v1/audio/transcriptions``). ``opts.verbose`` fills
+     * ``.language`` / ``.duration`` / ``.segments`` on the result; ``opts.format`` names the media
+     * type for nameless bytes.
+     */
+    async transcribe(audio, opts = {}) {
+        const req = buildTranscribe({
+            audio,
+            model: opts.model,
+            language: opts.language,
+            prompt: opts.prompt,
+            verbose: opts.verbose,
+            format: opts.format,
+        });
+        return parseTranscript(await this.request(req, opts.signal));
+    }
+    /**
+     * Transcribe a live audio stream, yielding a {@link Transcript} per finalized sentence.
+     *
+     * **True streaming when the backend offers it, with a silent fallback.** The primary path opens the
+     * live transcription route (``WS /v1/audio/transcriptions/stream``) and pumps ``chunks`` up while
+     * reading transcript events down. If that route can't be reached — an old deploy, a proxy that
+     * strips the WebSocket upgrade, a refused connection — it degrades to the batch ``transcribe`` route
+     * (each chunk POSTed, finals only). A **rejected credential** (close 4401) is *not* a fallback case
+     * — it throws {@link AuthError}, since retrying won't heal it. The fallback is **connect-time only**:
+     * once live, a mid-session drop throws rather than silently degrading.
+     *
+     * By default (``partials`` off) it yields **finals only** — each a settled sentence with
+     * ``.final === true`` and ``.raw`` carrying ``start`` / ``end`` timings. ``partials`` additionally
+     * yields the live partial hypothesis (``.final === false``), a revisable guess at the current tail —
+     * render the latest, don't append.
+     *
+     * Input comes in two shapes: **container clips** (``format`` = ``"webm"`` / ``"wav"`` / … — each
+     * chunk a self-contained clip, the browser ``MediaRecorder`` shape) or **raw PCM**
+     * (``format="pcm16"``, a continuous PCM16LE-mono stream, which **requires** ``sampleRate`` because
+     * raw PCM is headerless). Passing ``sampleRate`` with a container format is an error.
+     */
+    async *transcribeLive(chunks, opts = {}) {
+        const format = opts.format ?? "wav";
+        if (format === "pcm16") {
+            if (opts.sampleRate === undefined) {
+                throw new InvalidArgumentError("transcribeLive({ format: 'pcm16' }) requires sampleRate: raw PCM is headerless — unlike a " +
+                    "WAV/WebM clip it carries no embedded sample rate to sniff, so the SDK can't infer the rate " +
+                    "your mic captured at. Pass it explicitly (e.g. sampleRate: 16000).");
+            }
+        }
+        else if (opts.sampleRate !== undefined) {
+            throw new InvalidArgumentError(`sampleRate is only valid with format: 'pcm16' (raw headerless PCM); '${format}' clips are ` +
+                "self-describing containers that carry their own rate — drop sampleRate.");
+        }
+        yield* this.transcribeStream(chunks, {
+            model: opts.model,
+            language: opts.language,
+            format,
+            sampleRate: opts.sampleRate,
+            partials: opts.partials ?? false,
+            skipEmpty: opts.skipEmpty ?? true,
+            webSocketCtor: opts.webSocketCtor,
+        });
+    }
+    transcribeStream(clips, opts) {
+        return transcribeEngine({
+            baseUrl: this.baseUrl,
+            token: () => this.streamToken(),
+            transcribe: (audio, o) => this.transcribe(audio, o),
+            webSocketCtor: opts.webSocketCtor,
+        }, clips, opts);
+    }
+    // A valid credential for the live-transcription WS (its `?api_key=` query — browsers can't set a WS
+    // header). An API key is used as-is; otherwise a valid OAuth access token, refreshed if near expiry.
+    async streamToken() {
+        if (this.apiKey)
+            return this.apiKey;
+        const token = await this.auth.token();
+        if (!token) {
+            throw new AuthError(401, "no credential for the transcription stream — sign in or construct with an apiKey");
+        }
+        return token;
+    }
+    async encodeMedia(kind, source, format) {
+        const { blob } = await toBlob(source);
+        const bytes = new Uint8Array(await blob.arrayBuffer());
+        const inferred = blob.type ? blob.type.split("/")[1] : undefined;
+        return { kind, data: bytesToBase64(bytes), format: format ?? inferred };
+    }
+    // --- ClientInternal ----------------------------------------------------------------------------
+    scope(project, collection) {
+        return {
+            project: project ?? this.defaultProject,
+            collection: collection ?? this.defaultCollection,
+        };
+    }
+    /** Resolve a space name-or-id to its id via the client-cached space list (mirror of Python's
+     * ``_resolve_space``): an id passes through; a case-insensitive name maps to its id; an unknown
+     * value is returned as-is for the server to report. The list is fetched once and cached. */
+    async resolveSpace(nameOrId) {
+        const spaces = await this.cachedSpaces();
+        if (spaces.some((s) => s.id === nameOrId)) {
+            return nameOrId;
+        }
+        const lower = nameOrId.toLowerCase();
+        const named = spaces.find((s) => s.name.toLowerCase() === lower);
+        return named ? named.id : nameOrId;
+    }
+    /** The full space list, fetched once and cached per client (shared with {@link resolveSpace}). */
+    cachedSpaces() {
+        if (!this.spacesPromise) {
+            this.spacesPromise = this.library.spaces();
+        }
+        return this.spacesPromise;
+    }
+    /** The client's ``assets`` namespace — the binder threaded into every parsed asset so a bound
+     * ``asset.vectors()`` / ``.segments()`` / ``.index()`` resolves through this client. */
+    get assetBinder() {
+        return this.assets;
+    }
+    async send(req, signal) {
+        const url = this.resolveUrl(req.path, req.query);
+        const { init, dispose } = await this.buildInit(req, signal);
+        try {
+            const res = this.apiKey
+                ? await this.keyedFetch(url, init)
+                : await this.auth.apiFetch(url, init);
+            if (!res.ok) {
+                await raiseForStatus(res);
+            }
+            return res;
+        }
+        finally {
+            dispose();
+        }
+    }
+    async request(req, signal) {
+        const res = await this.send(req, signal);
+        if (res.status === 204) {
+            return undefined;
+        }
+        return await res.json();
+    }
+    async requestBytes(req, signal) {
+        const res = await this.send(req, signal);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    keyedFetch(url, init) {
+        const headers = new Headers(init.headers);
+        headers.set("Authorization", `Bearer ${this.apiKey}`);
+        return httpFetch(url, { ...init, headers });
+    }
+    resolveUrl(path, query) {
+        const base = /^https?:\/\//i.test(path)
+            ? path
+            : `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+        if (!query) {
+            return base;
+        }
+        const usp = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    usp.append(key, String(item));
+                }
+            }
+            else {
+                usp.append(key, String(value));
+            }
+        }
+        const qs = usp.toString();
+        return qs ? `${base}${base.includes("?") ? "&" : "?"}${qs}` : base;
+    }
+    async buildInit(req, signal) {
+        const init = { method: req.method };
+        const { signal: linked, dispose } = linkSignals(signal, this.lifecycle.signal);
+        if (linked) {
+            init.signal = linked;
+        }
+        if (req.json !== undefined) {
+            init.headers = { "Content-Type": "application/json" };
+            init.body = JSON.stringify(req.json);
+        }
+        else if (req.form) {
+            // ``fetch`` sets ``application/x-www-form-urlencoded`` for a URLSearchParams body.
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(req.form)) {
+                params.append(key, value);
+            }
+            init.body = params;
+        }
+        else if (req.multipart) {
+            const form = new FormData();
+            for (const [key, value] of Object.entries(req.multipart.fields)) {
+                form.append(key, value);
+            }
+            for (const [field, part] of Object.entries(req.multipart.files)) {
+                const { blob, filename } = await toBlob(part.source);
+                form.append(field, blob, part.filename ?? filename);
+            }
+            init.body = form;
+        }
+        else if (req.content !== undefined) {
+            init.headers = { "Content-Type": req.contentType ?? "application/octet-stream" };
+            init.body = req.content;
+        }
+        return { init, dispose };
+    }
+}
+if (typeof Symbol.asyncDispose === "symbol") {
+    Atrium.prototype[Symbol.asyncDispose] = async function () {
+        await this.close();
+    };
+}
+// --- namespaces ----------------------------------------------------------------------------------
+function likeSourceId(like) {
+    if (typeof like === "string") {
+        return like;
+    }
+    return "asset" in like ? like.asset.id : like.id;
+}
+/** Semantic library search and mood-board (search-by-examples) queries. */
+export class Library {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** List the searchable embedding spaces (``GET /v1/library/spaces``). */
+    async spaces(opts = {}) {
+        const data = await this.c.request({ method: "GET", path: "/v1/library/spaces" }, opts.signal);
+        return (Array.isArray(data) ? data : []).map(parseSpace);
+    }
+    /**
+     * Resolve ``modality`` to the deployment's default space (or ``undefined``).
+     *
+     * So an app never has to hardcode a deployment's space ids — those leak deployment config into
+     * caller code. The deployment declares its defaults (``defaultModalities``); the app just asks.
+     * Returns the first space whose ``defaultModalities`` include ``modality``, else the first whose
+     * ``modalities`` include it, else ``undefined`` — reading the client's cached space list (no
+     * per-call refetch). The returned space's ``id`` is what search/scoring take as ``space``.
+     */
+    async defaultSpace(modality) {
+        const spaces = await this.c.cachedSpaces();
+        return (spaces.find((s) => s.defaultModalities.includes(modality)) ??
+            spaces.find((s) => s.modalities.includes(modality)));
+    }
+    /** Semantic search — by text, an example asset (``like``), a media file, or a raw ``vector``. */
+    async search(query = "", opts = {}) {
+        const { project, collection } = this.c.scope(opts.project, opts.collection);
+        const media = opts.image ?? opts.audio ?? opts.video;
+        const space = opts.space !== undefined ? await this.c.resolveSpace(opts.space) : undefined;
+        const includeVectors = typeof opts.includeVectors === "string"
+            ? await this.c.resolveSpace(opts.includeVectors)
+            : opts.includeVectors;
+        const req = buildSearch({
+            query,
+            like: opts.like !== undefined ? likeSourceId(opts.like) : undefined,
+            likeBy: opts.likeBy,
+            modality: opts.modality,
+            space,
+            limit: opts.limit ?? 20,
+            tags: opts.tags,
+            anyTags: opts.anyTags,
+            excludeTags: opts.excludeTags,
+            provider: opts.provider,
+            filters: opts.filters,
+            media,
+            vector: opts.vector,
+            includeVectors,
+            project,
+            collection,
+        });
+        const data = await this.c.request(req, opts.signal);
+        return (Array.isArray(data) ? data : []).map((d) => parseSearchHit(d, this.c.baseUrl, this.c.assetBinder));
+    }
+    /** Find assets similar to a *set* of example assets (a mood board). */
+    async searchByExamples(positives, opts = {}) {
+        const { project, collection } = this.c.scope(opts.project, opts.collection);
+        const spaces = opts.spaces !== undefined
+            ? await Promise.all(opts.spaces.map((s) => this.c.resolveSpace(s)))
+            : undefined;
+        const req = buildSearchByExamples({
+            positives: positives.map(seedAssetId),
+            negatives: opts.negatives?.map(seedAssetId),
+            method: opts.method ?? "cav",
+            spaces,
+            limit: opts.limit ?? 20,
+            contrastSamples: opts.contrastSamples,
+            features: opts.features,
+            matchBy: opts.matchBy,
+            filters: opts.filters,
+            project,
+            collection,
+        });
+        const data = await this.c.request(req, opts.signal);
+        return (Array.isArray(data) ? data : []).map((d) => parseSearchByExamplesHit(d, this.c.baseUrl, this.c.assetBinder));
+    }
+    /**
+     * Compare two operands and return their similarity (raw + calibrated when available). Each operand
+     * is an ``Asset``, a bare text string, or a ``by.*`` marker — ``by.asset(id)`` for a bare id,
+     * ``by.vector([…])`` for a raw vector, ``by.file(…)`` for a file, ``by.concept(name)`` for a tag's
+     * concept. ``space`` forces the embedding space (required for a raw vector or cross-modal pair).
+     */
+    async compare(a, b, opts = {}) {
+        const space = opts.space !== undefined ? await this.c.resolveSpace(opts.space) : undefined;
+        const req = buildCompare(toOperand(a), toOperand(b), space, opts.breakdown);
+        return parseCompareResult(await this.c.request(req, opts.signal));
+    }
+    /**
+     * Pull external candidates (Freesound / Openverse / …) for a query into the library. ``preview``
+     * is a dry-run that returns the candidates that *would* be pulled. The response is the raw payload
+     * (a deliberately unwrapped long tail — preview steps, or the staged/enqueued result).
+     */
+    async enrich(query, opts) {
+        const req = buildEnrich({
+            query,
+            modality: opts.modality,
+            tags: opts.tags,
+            total: opts.total,
+            preview: opts.preview,
+            wait: opts.wait,
+        });
+        return (await this.c.request(req, opts.signal));
+    }
+    /**
+     * Fetch stored embedding vectors for many assets at once (``POST /v1/library/vectors``,
+     * member-gated). ``ids`` elements are ``Asset`` objects, ``SearchHit`` results, or bare id strings.
+     * ``space`` (id or human name, one or a list) selects the space(s); ``matchBy`` picks an exact
+     * stored signal. **With ``matchBy`` omitted the signal is resolved per asset**, so one call can
+     * return mixed ``matchedBy`` values across assets — read {@link AssetVector.matchedBy}. Ids that
+     * don't exist or aren't visible land in the server's ``missing`` list: default silently omits them;
+     * ``strict: true`` throws, listing them.
+     */
+    async vectors(ids, opts) {
+        const space = await this.resolveSpaceArg(opts.space);
+        const req = buildBulkVectors(ids.map(likeSourceId), { space, matchBy: opts.matchBy });
+        const data = (await this.c.request(req, opts.signal));
+        const missing = Array.isArray(data.missing) ? data.missing : [];
+        if (opts.strict && missing.length) {
+            throw new InvalidArgumentError(`library.vectors(strict): ${missing.length} id(s) missing: ${missing.join(", ")}`);
+        }
+        return (Array.isArray(data.vectors) ? data.vectors : []).map((row) => parseAssetVector(row));
+    }
+    resolveSpaceArg(space) {
+        return typeof space === "string"
+            ? this.c.resolveSpace(space)
+            : Promise.all(space.map((s) => this.c.resolveSpace(s)));
+    }
+    /** List the tag definitions in scope (``GET /v1/library/tags``) — read-only. Inherits the
+     * client's collection scoping (own + inherited tags, else the root Library's vocabulary). Tag
+     * create/update/delete stay platform-only. */
+    async tags(opts = {}) {
+        const { collection } = this.c.scope(undefined, undefined);
+        const data = await this.c.request(buildTagsList({ collection }), opts.signal);
+        return (Array.isArray(data) ? data : []).map(parseTagDefinition);
+    }
+    /** Fetch one tag definition by name or id (``GET /v1/library/tags/{ref}``) — read-only. The name
+     * is resolved within the client's collection scope. ``includeSnapshot: true`` also fetches the
+     * materialized concept boundary onto ``tag.snapshot``. */
+    async tag(nameOrId, opts = {}) {
+        const { collection } = this.c.scope(undefined, undefined);
+        const req = buildTagGet(nameOrId, { includeSnapshot: opts.includeSnapshot, collection });
+        return parseTagDefinition(await this.c.request(req, opts.signal));
+    }
+}
+/** Browse and fetch asset metadata. */
+export class Assets {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** List assets in scope, newest first (``GET /v1/assets``). */
+    async list(opts = {}) {
+        const { project, collection } = this.c.scope(opts.project, opts.collection);
+        const req = buildAssetList({
+            modality: opts.modality,
+            contentKind: opts.contentKind,
+            limit: opts.limit ?? 48,
+            cursor: opts.cursor,
+            project,
+            collection,
+        });
+        const data = await this.c.request(req, opts.signal);
+        return parseAssetPage(data, this.c.baseUrl, this.c.assetBinder);
+    }
+    /** Fetch a single asset's metadata (``GET /v1/assets/{id}``). */
+    async get(assetId, opts = {}) {
+        const { collection } = this.c.scope(undefined, opts.collection);
+        const data = await this.c.request(buildAssetGet(assetId, { collection }), opts.signal);
+        return parseAsset(data, this.c.baseUrl, this.c.assetBinder);
+    }
+    /**
+     * Fetch one asset's stored embedding vectors (``GET /v1/assets/{id}/vectors``, public by-id).
+     * ``assetOrId`` is an ``Asset``, a ``SearchHit``, or a bare id. No ``space``/``matchBy`` returns
+     * every stored vector; ``space`` (id or human name, one or a list) and ``matchBy`` (a coarse class
+     * like ``native``/``manual``, or an exact value like ``bridge:text``/``seg:<id>``) narrow them.
+     * Also available as the bound ``asset.vectors(...)``.
+     */
+    async vectors(assetOrId, opts = {}) {
+        const assetId = likeSourceId(assetOrId);
+        let space;
+        if (opts.space === undefined) {
+            space = undefined;
+        }
+        else if (typeof opts.space === "string") {
+            space = await this.c.resolveSpace(opts.space);
+        }
+        else {
+            space = await Promise.all(opts.space.map((s) => this.c.resolveSpace(s)));
+        }
+        const req = buildAssetVectors(assetId, { space, matchBy: opts.matchBy });
+        const data = await this.c.request(req, opts.signal);
+        return (Array.isArray(data) ? data : []).map((row) => parseAssetVector(row, assetId));
+    }
+    /** Fetch one asset's sound-event segments (``GET /v1/assets/{id}/segments``, public by-id). Each
+     * {@link SegmentRef} carries a ``contentUrl`` for just that slice's pre-cut bytes. Also available
+     * as the bound ``asset.segments()``. */
+    async segments(assetOrId) {
+        const assetId = likeSourceId(assetOrId);
+        const data = await this.c.request(buildAssetSegments(assetId));
+        return (Array.isArray(data) ? data : []).map((row) => parseSegment(row, assetId, this.c.baseUrl));
+    }
+    /** Fetch one asset's per-signal index map (``GET /v1/assets/{id}/index``, authenticated). Each
+     * {@link IndexEntry} is one stored signal's processing state; the server's internal ``via``
+     * surfaces as ``matchedBy``. Also available as the bound ``asset.index()``. */
+    async index(assetOrId) {
+        const data = await this.c.request(buildAssetIndex(likeSourceId(assetOrId)));
+        return (Array.isArray(data) ? data : []).map(parseIndexEntry);
+    }
+    /** Upload a file to the library (``POST /v1/assets``); it indexes in the background. */
+    async upload(file, opts = {}) {
+        const { collection } = this.c.scope(undefined, opts.collection);
+        const req = buildUpload({
+            file,
+            modality: opts.modality,
+            description: opts.description,
+            collection,
+        });
+        const data = await this.c.request(req, opts.signal);
+        return parseAsset(data, this.c.baseUrl, this.c.assetBinder);
+    }
+}
+/** External sources — search several providers at once, then import what you pick. */
+export class Sources {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** List the registered external sources (``GET /v1/library/sources``). */
+    async list(opts = {}) {
+        const data = await this.c.request({ method: "GET", path: "/v1/library/sources" }, opts.signal);
+        return (Array.isArray(data) ? data : []).map(parseSourceInfo);
+    }
+    /** Search external sources for a query (``POST /v1/library/sources/search``) — read-only. */
+    async search(query, opts = {}) {
+        const req = buildSourcesSearch({
+            query,
+            providers: opts.providers,
+            k: opts.k ?? 12,
+            mode: opts.mode,
+            modality: opts.modality,
+        });
+        const data = await this.c.request(req, opts.signal);
+        return parseSourceSearchResult(data);
+    }
+    /** Import one candidate into the shared library (``POST …/{source}/import``). */
+    async import(opts) {
+        const [sourceId, externalId] = resolveImportTarget(opts.candidate, opts.sourceId, opts.externalId);
+        const req = buildSourceImport({
+            sourceId,
+            externalId,
+            modality: opts.modality,
+            description: opts.description,
+        });
+        const data = await this.c.request(req, opts.signal);
+        return parseAsset(data, this.c.baseUrl, this.c.assetBinder);
+    }
+}
+/** Start / resume sessions and append to their durable log. */
+export class Sessions {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** Start a new session — a standalone durable record (``POST /v1/sessions``). */
+    async start(opts = {}) {
+        const { project } = this.c.scope(opts.project, undefined);
+        const req = buildSessionStart({
+            project,
+            name: opts.name,
+            participantRef: opts.participantRef,
+            condition: opts.condition,
+            meta: opts.meta,
+        });
+        return parseSession(await this.c.request(req, opts.signal));
+    }
+    /** Resume an existing session by id (``GET /v1/sessions/{id}``) — the live {@link Session} handle
+     * for continued logging. For a read-only analysis view use {@link get}, which GETs the same route
+     * but returns a {@link SessionInfo} read model. */
+    async resume(sessionId, opts = {}) {
+        const data = await this.c.request({ method: "GET", path: `/v1/sessions/${sessionId}` }, opts.signal);
+        return parseSession(data);
+    }
+    /** List a project's sessions, newest first (``GET /v1/sessions``) — the read model. No ``project``
+     * → the client's default project. ``phase`` (a string or list) filters by study phase; the empty
+     * string ``""`` matches sessions with no phase set. Each row is a {@link SessionInfo};
+     * ``hasTranscript`` is ``null`` in list results (only {@link get} populates it). There is no
+     * participant filter server-side — filter the returned rows on ``participantRef`` yourself. */
+    async list(opts = {}) {
+        const { project } = this.c.scope(opts.project, undefined);
+        const req = buildSessionsList({ project, phase: opts.phase });
+        const data = await this.c.request(req, opts.signal);
+        return (Array.isArray(data) ? data : []).map(parseSessionInfo);
+    }
+    /** Fetch a session's read model for analysis (``GET /v1/sessions/{id}``) — a {@link SessionInfo}
+     * with ``hasTranscript`` populated. This is the **read model**; to keep *writing* to the log use
+     * {@link resume}, which GETs the same route but returns the live {@link Session} handle. */
+    async get(sessionId, opts = {}) {
+        const data = await this.c.request({ method: "GET", path: `/v1/sessions/${sessionId}` }, opts.signal);
+        return parseSessionInfo(data);
+    }
+    /** A session's durable event log as flat rows (``GET /v1/sessions/{id}/events/history``). ``after``
+     * returns only events with ``seq`` greater than it (a sequence number, not a timestamp); ``limit``
+     * caps the page (1..500, server default 100). Each row is a {@link ReadSessionEvent}. */
+    async events(sessionId, opts = {}) {
+        const req = buildSessionEvents(sessionId, { after: opts.after, limit: opts.limit });
+        const data = await this.c.request(req, opts.signal);
+        return (Array.isArray(data) ? data : []).map(parseSessionEventRow);
+    }
+    /**
+     * Export one session's data as raw bytes, dispatching ``format`` to its fixed export route.
+     * ``"jsonl"`` / ``"csv"`` are the event log; ``"transcript"`` is the plain-text transcript (404s
+     * when the session has none); ``"bundle"`` is a zip of everything. There is no ``?format=`` param
+     * server-side — each is a distinct path.
+     *
+     * Returns a ``Uint8Array``: the SDK is browser + Node, and the core never touches the filesystem
+     * (``files.ts``), so there is no ``path=`` file-writing (a Node caller writes the bytes itself).
+     */
+    async export(sessionId, format = "jsonl", opts = {}) {
+        return this.c.requestBytes(buildSessionExport(sessionId, format), opts.signal);
+    }
+    /** Export several sessions as one zip (``GET /v1/sessions/export/bundle``), returned as raw bytes.
+     * ``ids`` is required; the server caps a call at 100 **distinct** ids — more (or an empty list)
+     * throws (never silently truncated or chunked). Data access is required on every id. */
+    async exportBundle(ids, opts = {}) {
+        const req = buildSessionExportBundle(distinctExportIds(ids));
+        return this.c.requestBytes(req, opts.signal);
+    }
+    /** Append a durable event to a session's log (``POST /v1/sessions/{id}/events``). */
+    async event(sessionId, type, opts = {}) {
+        const req = buildSessionEvent(sessionId, {
+            type,
+            payload: opts.payload,
+            source: opts.source,
+            via: opts.via,
+        });
+        return parseSessionEvent(await this.c.request(req, opts.signal));
+    }
+}
+/** Open / fetch / join rooms — each returns a live {@link Room} handle (connect, send, on, request,
+ * player controls, audio signals). ``connect()`` (called for you by any wire method) opens the socket. */
+export class Rooms {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    wrap(info, live, participant) {
+        return new Room({
+            id: info.id,
+            connectCode: info.connectCode,
+            name: info.name,
+            projectId: info.projectId,
+            baseUrl: this.c.baseUrl,
+            // A participant (join-by-code) can't manage the room, nor embed (no credentials of its own);
+            // omit the REST caller and the embedding client for it.
+            rest: participant ? undefined : (req) => this.c.request(req),
+            client: participant
+                ? undefined
+                : {
+                    embed: (opts) => this.c.embed(opts),
+                    chat: (messages, o) => this.c.chat(messages, o),
+                    library: this.c.library,
+                    request: (req) => this.c.request(req),
+                    transcribeStream: (clips, o) => this.c.transcribeStream(clips, o),
+                },
+            identity: live.identity,
+            announce: live.announce,
+            requestTimeout: live.requestTimeout,
+            reconnect: live.reconnect,
+            transport: live.transport,
+            WebSocketCtor: live.WebSocketCtor,
+            fetchImpl: live.fetchImpl,
+            signal: live.signal,
+        });
+    }
+    /** Open a room (``POST /v1/rooms``) and return a live handle. */
+    async open(opts = {}) {
+        const { project } = this.c.scope(opts.project, undefined);
+        const req = buildRoomOpen({ name: opts.name, project, embeddingSpace: opts.embeddingSpace });
+        return this.wrap(parseRoom(await this.c.request(req, opts.signal)), opts, false);
+    }
+    /** Fetch a room by id (``GET /v1/rooms/{id}``) and return a live handle. */
+    async get(roomId, opts = {}) {
+        const data = await this.c.request({ method: "GET", path: `/v1/rooms/${roomId}` }, opts.signal);
+        return this.wrap(parseRoom(data), opts, false);
+    }
+    /** List the rooms you can see (``GET /v1/rooms``) as live handles. */
+    async list(opts = {}) {
+        const data = await this.c.request({ method: "GET", path: "/v1/rooms" }, opts.signal);
+        return (Array.isArray(data) ? data : []).map((d) => this.wrap(parseRoom(d), {}, false));
+    }
+    /** Join a room by its connect code (``GET /v1/rooms/resolve``) — a participant handle that can
+     * ``send`` / ``on`` / ``request`` / play / consume audio, but not manage the room. */
+    async join(code, opts = {}) {
+        const data = await this.c.request(buildRoomResolve(code), opts.signal);
+        return this.wrap(parseRoom(data), opts, true);
+    }
+}
+//# sourceMappingURL=atrium.js.map