@lumavox/server 0.0.0-stage → 0.2.2

package/dist/gen/types.gen.js

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@lumavox/server`: the API from a customer's server, with an org API key.
+ * Bodies and answers are the wire's, snake_case, typed from the published
+ * OpenAPI document (`src/gen/`, generated); methods are camelCase, and the
+ * SDK's own options (`RequestOptions`) go in a last argument.
+ */
+export { type Client, type ClientOptions, createClient, DEFAULT_BASE_URL, } from "./client.js";
+export { AuthenticationError, ConflictError, ConnectionError, InsufficientCreditsError, NotFoundError, PermissionError, PlatformError, type PlatformErrorInit, RateLimitError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
+export type * from "./gen/index.js";
+export type { AgentKnowledge, AgentSettings, Agents, } from "./resources/agents.js";
+export type { AssetListParams, Assets, AssetUploadFields, FolderListParams, Folders, } from "./resources/assets.js";
+export type { EndUserCreated, EndUserExport, EndUserListParams, EndUsers, } from "./resources/end-users.js";
+export type { EphemeralKeyCreateOptions, EphemeralKeyListParams, EphemeralKeys, } from "./resources/ephemeral-keys.js";
+export type { GenerationListParams, Generations, Jobs, Skybox, } from "./resources/generations.js";
+export type { Knowledge, KnowledgeInsightsParams, KnowledgeListParams, KnowledgeUploadFields, } from "./resources/knowledge.js";
+export type { Resource, Waitable } from "./resources/resource.js";
+export type { Speech, Stt, SttEvent, SttParams, Transcript, Tts, } from "./resources/speech.js";
+export type { TemplateFile, Templates } from "./resources/templates.js";
+export type { Usage, UsageParams } from "./resources/usage.js";
+export type { Voices, VoiceUploadFields } from "./resources/voices.js";
+export type { Fetch, RequestOptions } from "./transport.js";
+export type { UploadData, UploadOptions } from "./upload.js";
+export type { Job } from "./wait.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * `@lumavox/server`: the API from a customer's server, with an org API key.
+ * Bodies and answers are the wire's, snake_case, typed from the published
+ * OpenAPI document (`src/gen/`, generated); methods are camelCase, and the
+ * SDK's own options (`RequestOptions`) go in a last argument.
+ */
+export { createClient, DEFAULT_BASE_URL, } from "./client.js";
+export { AuthenticationError, ConflictError, ConnectionError, InsufficientCreditsError, NotFoundError, PermissionError, PlatformError, RateLimitError, ServerError, TimeoutError, ValidationError, } from "./errors.js";

package/dist/paging.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Paging as the API pages: every `list()` is an async iterator over every
+ * item, page after page; `page()` beside it is one page, as the route
+ * answers it.
+ *
+ * The API has three styles:
+ * - **Offset** (end users, ephemeral keys, knowledge, and an end user's
+ *   sessions inside the export): the next page starts where this one
+ *   ended, and a page shorter than the limit, or the `total` reached, is
+ *   the last. Newest first, so a row made while iterating shifts the rest
+ *   by one and one item is seen twice — the cost of offsets, which the
+ *   API chose.
+ * - **`next_cursor`** (generations, assets): the page says where the next
+ *   starts, and the last has none. Nothing is seen twice.
+ * - **The backwards `next_before`** of a transcript, which only the
+ *   export reads, by hand (`resources/end-users.ts`).
+ *
+ * A route that does not page (voices, agents, templates, a folder's
+ * level) has no iterator: its `list()` answers what the route does.
+ */
+/** One page of an offset-paged list: its items, and the total when the route says. */
+export interface OffsetPage<T> {
+    items: T[];
+    total?: number;
+}
+/** Every item, `limit` at a time from `offset`, until a short page or the total. */
+export declare function byOffset<T>(read: (offset: number, limit: number) => Promise<OffsetPage<T>>, limit: number, offset?: number): AsyncGenerator<T, void, undefined>;
+/** One page of a cursor-paged list: its items, and where the next one starts. */
+export interface CursorPage<T> {
+    items: T[];
+    next?: string | null;
+}
+/** Every item, page after page, until a page names no next one. */
+export declare function byCursor<T>(read: (cursor: string | undefined) => Promise<CursorPage<T>>): AsyncGenerator<T, void, undefined>;

package/dist/paging.js

@@ -0,0 +1,41 @@
+/**
+ * Paging as the API pages: every `list()` is an async iterator over every
+ * item, page after page; `page()` beside it is one page, as the route
+ * answers it.
+ *
+ * The API has three styles:
+ * - **Offset** (end users, ephemeral keys, knowledge, and an end user's
+ *   sessions inside the export): the next page starts where this one
+ *   ended, and a page shorter than the limit, or the `total` reached, is
+ *   the last. Newest first, so a row made while iterating shifts the rest
+ *   by one and one item is seen twice — the cost of offsets, which the
+ *   API chose.
+ * - **`next_cursor`** (generations, assets): the page says where the next
+ *   starts, and the last has none. Nothing is seen twice.
+ * - **The backwards `next_before`** of a transcript, which only the
+ *   export reads, by hand (`resources/end-users.ts`).
+ *
+ * A route that does not page (voices, agents, templates, a folder's
+ * level) has no iterator: its `list()` answers what the route does.
+ */
+/** Every item, `limit` at a time from `offset`, until a short page or the total. */
+export async function* byOffset(read, limit, offset = 0) {
+    for (;;) {
+        const page = await read(offset, limit);
+        yield* page.items;
+        offset += page.items.length;
+        const last = page.items.length < limit ||
+            (page.total !== undefined && offset >= page.total);
+        if (last)
+            return;
+    }
+}
+/** Every item, page after page, until a page names no next one. */
+export async function* byCursor(read) {
+    let cursor;
+    do {
+        const page = await read(cursor);
+        yield* page.items;
+        cursor = page.next ?? undefined;
+    } while (cursor);
+}

package/dist/refuse.d.ts

@@ -0,0 +1,11 @@
+/**
+ * What `@lumavox/server` resolves to under the `browser` and
+ * `react-native` export conditions (`package.json`; `runtime.ts` says
+ * why). It exports the refusal and nothing else, so a bundler that checks
+ * imports — esbuild, Rollup and so Vite — fails the build on
+ * `createClient` (esbuild only warns about a file with no exports at
+ * all); and it throws when it is loaded, for one that does not check
+ * (Metro). `package.json`'s `sideEffects` keeps it from being shaken out.
+ */
+import { REFUSAL } from "./runtime.js";
+export { REFUSAL };

package/dist/refuse.js

@@ -0,0 +1,12 @@
+/**
+ * What `@lumavox/server` resolves to under the `browser` and
+ * `react-native` export conditions (`package.json`; `runtime.ts` says
+ * why). It exports the refusal and nothing else, so a bundler that checks
+ * imports — esbuild, Rollup and so Vite — fails the build on
+ * `createClient` (esbuild only warns about a file with no exports at
+ * all); and it throws when it is loaded, for one that does not check
+ * (Metro). `package.json`'s `sideEffects` keeps it from being shaken out.
+ */
+import { REFUSAL } from "./runtime.js";
+export { REFUSAL };
+throw new Error(REFUSAL);

package/dist/resources/agents.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `client.agents`: the agents end users talk to — `/v1/agents*`. What one
+ * says, its voice, its hearing and the knowledge it may look up; the
+ * conversations themselves are the end users' (`endUsers.export`).
+ *
+ * - **A save reaches running sessions within a minute**, not at once: an
+ *   agent's version travels through the platform's `STANDING` copy.
+ * - **`settings`** are the organisation's, for every agent;
+ *   **`knowledge.set`** replaces the entries one agent may look up.
+ * - **`create` is a 409 at the plan's maximum agents**; `delete` answers
+ *   the agent as it was, and `null` for one already gone.
+ */
+import type { AgentCreateRequest, AgentInfo, AgentList, AgentSettingsInfo, AgentSettingsUpdate, AgentUpdate, KnowledgeAssigned, KnowledgeAssignment, KnowledgeList } from "../gen/index.js";
+import type { RequestOptions, Transport } from "../transport.js";
+import { Editable } from "./resource.js";
+/** `agents.settings`: the organisation's, for every agent. */
+export interface AgentSettings {
+    get(options?: RequestOptions): Promise<AgentSettingsInfo>;
+    update(body: AgentSettingsUpdate, options?: RequestOptions): Promise<AgentSettingsInfo>;
+}
+/** `agents.knowledge`: the entries one agent may look up. */
+export interface AgentKnowledge {
+    list(agentId: string, options?: RequestOptions): Promise<KnowledgeList>;
+    /** Replaces them all with these. */
+    set(agentId: string, body: KnowledgeAssignment, options?: RequestOptions): Promise<KnowledgeAssigned>;
+}
+export declare class Agents extends Editable<AgentInfo, AgentUpdate> {
+    readonly settings: AgentSettings;
+    readonly knowledge: AgentKnowledge;
+    constructor(api: Transport, base: string);
+    /** Every agent. */
+    list(options?: RequestOptions): Promise<AgentList>;
+    create(body: AgentCreateRequest, options?: RequestOptions): Promise<AgentInfo>;
+}

package/dist/resources/agents.js

@@ -0,0 +1,33 @@
+/**
+ * `client.agents`: the agents end users talk to — `/v1/agents*`. What one
+ * says, its voice, its hearing and the knowledge it may look up; the
+ * conversations themselves are the end users' (`endUsers.export`).
+ *
+ * - **A save reaches running sessions within a minute**, not at once: an
+ *   agent's version travels through the platform's `STANDING` copy.
+ * - **`settings`** are the organisation's, for every agent;
+ *   **`knowledge.set`** replaces the entries one agent may look up.
+ * - **`create` is a 409 at the plan's maximum agents**; `delete` answers
+ *   the agent as it was, and `null` for one already gone.
+ */
+import { Editable } from "./resource.js";
+export class Agents extends Editable {
+    constructor(api, base) {
+        super(api, base);
+        this.settings = {
+            get: (options) => this.send("GET", "/settings", options),
+            update: (body, options) => this.send("PUT", "/settings", options, body),
+        };
+        this.knowledge = {
+            list: (id, options) => this.send("GET", this.at(id, "/knowledge"), options),
+            set: (id, body, options) => this.send("PUT", this.at(id, "/knowledge"), options, body),
+        };
+    }
+    /** Every agent. */
+    list(options) {
+        return this.send("GET", "", options);
+    }
+    create(body, options) {
+        return this.send("POST", "", options, body);
+    }
+}

package/dist/resources/assets.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `client.assets`: this organisation's library — `/v1/assets*`, and its
+ * folders, `/v1/asset-folders*`, as `assets.folders`. Every generation's
+ * file lands here; uploads go here before a transcription or a video's
+ * frames can name them.
+ *
+ * - **An upload is converted after it arrives**: `confirm` and `upload`
+ *   answer it `pending`, and `wait(id)` reads it until `ready` or
+ *   `failed`. A transcription of one still `pending` is a 409.
+ * - **`upload(data, fields)`** is the ticket, the `PUT` and the confirm
+ *   in one (`upload.ts`).
+ * - **`delete` of one already gone is done**: `null`. `deleteMany` and
+ *   `move` answer how many they touched.
+ * - **`list()` pages by cursor**, 200 a page; a folder's `list()` is one
+ *   level, as the route answers it.
+ */
+import type { AssetBulkRequest, AssetDeleted, AssetDetail, AssetMoveRequest, AssetPage, AssetSummary, AssetsAffected, AssetUpdate, FolderCreate, FolderDeleted, FolderDetail, FolderLevel, FolderSummary, FolderUpdate, ListAssetsData, ListFoldersData, UploadConfirm, UploadTicket, UploadTicketRequest } from "../gen/index.js";
+import type { RequestOptions, Transport } from "../transport.js";
+import { type UploadData, type UploadOptions } from "../upload.js";
+import { Editable, Waitable } from "./resource.js";
+export type AssetListParams = NonNullable<ListAssetsData["query"]>;
+export type FolderListParams = NonNullable<ListFoldersData["query"]>;
+/** A file's place in the library: the confirm's fields, and its type. */
+export type AssetUploadFields = Omit<UploadConfirm, "asset_id" | "content_type"> & {
+    /** A Blob's own type by default. */
+    content_type?: string;
+};
+/**
+ * `assets.folders`: the library's tree. `get` answers a folder with its
+ * counts and ancestors; `update` renames it or moves it under another;
+ * `delete` moves what it held up a level.
+ */
+export declare class Folders extends Editable<FolderDetail, FolderUpdate, FolderSummary, FolderDeleted> {
+    /** One level: the top, or `parent_id`'s children. */
+    list(params?: FolderListParams, options?: RequestOptions): Promise<FolderLevel>;
+    create(body: FolderCreate, options?: RequestOptions): Promise<FolderSummary>;
+}
+/**
+ * `update` renames an asset or files it in a folder; `delete` deletes it
+ * and its files.
+ */
+export declare class Assets extends Waitable<AssetDetail, AssetUpdate, AssetDetail, AssetDeleted> {
+    readonly folders: Folders;
+    constructor(api: Transport, base: string);
+    /** One page, with the `next_cursor` of the next. */
+    page(params?: AssetListParams, options?: RequestOptions): Promise<AssetPage>;
+    /** Every asset the filter matches, page after page (200 a page by default). */
+    list(params?: Omit<AssetListParams, "cursor">, options?: RequestOptions): AsyncGenerator<AssetSummary, void, undefined>;
+    /** A signed URL to `PUT` a file to, with exactly this type. */
+    uploadUrl(body: UploadTicketRequest, options?: RequestOptions): Promise<UploadTicket>;
+    /** Says the `PUT` is done: the asset, `pending` while it converts. */
+    confirm(body: UploadConfirm, options?: RequestOptions): Promise<AssetDetail>;
+    /** Uploads a file: `uploadUrl`, the `PUT`, `confirm`. */
+    upload(data: UploadData, fields?: AssetUploadFields, options?: UploadOptions): Promise<AssetDetail>;
+    /** Deletes several: how many were. */
+    deleteMany(body: AssetBulkRequest, options?: RequestOptions): Promise<AssetsAffected>;
+    /** Files several in one folder, `null` for the top: how many moved. */
+    move(body: AssetMoveRequest, options?: RequestOptions): Promise<AssetsAffected>;
+}

package/dist/resources/assets.js

@@ -0,0 +1,80 @@
+/**
+ * `client.assets`: this organisation's library — `/v1/assets*`, and its
+ * folders, `/v1/asset-folders*`, as `assets.folders`. Every generation's
+ * file lands here; uploads go here before a transcription or a video's
+ * frames can name them.
+ *
+ * - **An upload is converted after it arrives**: `confirm` and `upload`
+ *   answer it `pending`, and `wait(id)` reads it until `ready` or
+ *   `failed`. A transcription of one still `pending` is a 409.
+ * - **`upload(data, fields)`** is the ticket, the `PUT` and the confirm
+ *   in one (`upload.ts`).
+ * - **`delete` of one already gone is done**: `null`. `deleteMany` and
+ *   `move` answer how many they touched.
+ * - **`list()` pages by cursor**, 200 a page; a folder's `list()` is one
+ *   level, as the route answers it.
+ */
+import { byCursor } from "../paging.js";
+import { needType, put, } from "../upload.js";
+import { Editable, Waitable } from "./resource.js";
+/** The route's own page bound. */
+const PAGE = 200;
+/**
+ * `assets.folders`: the library's tree. `get` answers a folder with its
+ * counts and ancestors; `update` renames it or moves it under another;
+ * `delete` moves what it held up a level.
+ */
+export class Folders extends Editable {
+    /** One level: the top, or `parent_id`'s children. */
+    list(params = {}, options) {
+        return this.send("GET", "", options, params);
+    }
+    create(body, options) {
+        return this.send("POST", "", options, body);
+    }
+}
+/**
+ * `update` renames an asset or files it in a folder; `delete` deletes it
+ * and its files.
+ */
+export class Assets extends Waitable {
+    constructor(api, base) {
+        super(api, base);
+        this.folders = new Folders(api, "/v1/asset-folders");
+    }
+    /** One page, with the `next_cursor` of the next. */
+    page(params = {}, options) {
+        return this.send("GET", "", options, params);
+    }
+    /** Every asset the filter matches, page after page (200 a page by default). */
+    list(params = {}, options) {
+        return byCursor(async (cursor) => {
+            const page = await this.page({ limit: PAGE, ...params, cursor }, options);
+            return { items: page.assets, next: page.next_cursor };
+        });
+    }
+    /** A signed URL to `PUT` a file to, with exactly this type. */
+    uploadUrl(body, options) {
+        return this.send("POST", "/upload-url", options, body);
+    }
+    /** Says the `PUT` is done: the asset, `pending` while it converts. */
+    confirm(body, options) {
+        return this.send("POST", "/uploaded", options, body);
+    }
+    /** Uploads a file: `uploadUrl`, the `PUT`, `confirm`. */
+    async upload(data, fields = {}, options = {}) {
+        const { content_type, ...rest } = fields;
+        const type = needType(data, content_type);
+        const ticket = await this.uploadUrl({ content_type: type }, options);
+        await put(this.api, ticket, data, type, options);
+        return this.settled(await this.confirm({ ...rest, asset_id: ticket.asset_id, content_type: type }, options), options);
+    }
+    /** Deletes several: how many were. */
+    deleteMany(body, options) {
+        return this.send("POST", "/delete", options, body);
+    }
+    /** Files several in one folder, `null` for the top: how many moved. */
+    move(body, options) {
+        return this.send("POST", "/move", options, body);
+    }
+}

package/dist/resources/end-users.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `client.endUsers`: the people your agents talk to — `/v1/end-users*`,
+ * and everything about one of them in `export`.
+ *
+ * - **`create` with your own `external_id` is idempotent**: the same value
+ *   is always the same person, made only the first time (200 found, 201
+ *   made). So it is retried like a GET; without an `external_id` every call
+ *   makes someone new, and only a 429 is retried.
+ * - **Either id works everywhere**: the `eu_…` the API made, or your
+ *   `external_id`. Path parameters are encoded, so an id may hold `/`.
+ * - **`update` renames them, or changes your id for them**: absent fields
+ *   are untouched, `null` clears one; 409 when another person has that
+ *   `external_id`.
+ * - **`delete` is what to call when someone asks to be forgotten**: it
+ *   deletes them, every conversation they had and everything remembered
+ *   about them, and answers the counts. Someone already gone is done, not
+ *   an error: `null`.
+ *
+ * **`export`** reads what the API holds about one person with a key of
+ * their own, since their conversations and facts are their end user DO's
+ * and an API key cannot read them (`/v1/agent/*` takes only an ephemeral
+ * key): it mints a five-minute key for them, lists their sessions (200 a
+ * page), reads each transcript backwards (200 messages a page, four
+ * sessions at a time), reads their facts, and revokes the key in
+ * `finally` — after an abort or a failure too. The cost: one mint (and
+ * `limits()` when cold) + ⌈S/200⌉ lists + Σ⌈M/200⌉ transcript pages + one
+ * facts read + one revoke. **Its ceilings**: the key is ordinary, so at
+ * the person's live-key cap or the plan's mint rate the export fails as
+ * the mint does (422, 429) and can be retried once a key lapses; it lives
+ * five minutes, so a history that takes longer to read fails with a 401;
+ * its one micro-credit is set aside like any key's, so an organisation
+ * with no balance cannot export (402); and the facts route answers the
+ * first 100 until it pages (left-overs #109).
+ */
+import type { EndUserCreateRequest, EndUserDeleted, EndUserInfo, EndUserList, EndUserUpdateRequest, FactInfo, ListEndUsersData, SessionDetail } from "../gen/index.js";
+import { type RequestOptions, type Transport } from "../transport.js";
+import type { EphemeralKeys } from "./ephemeral-keys.js";
+import { Editable } from "./resource.js";
+export type EndUserListParams = NonNullable<ListEndUsersData["query"]>;
+/** An end user `create` answered, and whether this call made them. */
+export type EndUserCreated = EndUserInfo & {
+    /**
+     * `true` on a 201, `false` when the `external_id` already named them.
+     * The last attempt's: after a retried connection failure, a person
+     * the first attempt made reads as found.
+     */
+    created: boolean;
+};
+/** Everything the API holds about one person. */
+export interface EndUserExport {
+    /** Their `eu_…` id. */
+    end_user_id: string;
+    /** Every conversation, newest first, each with every message, oldest first. */
+    sessions: SessionDetail[];
+    /** What is remembered about them, oldest first — the first 100 for now. */
+    facts: FactInfo[];
+}
+export declare class EndUsers extends Editable<EndUserInfo, EndUserUpdateRequest, EndUserInfo, EndUserDeleted> {
+    private readonly keys;
+    constructor(api: Transport, base: string, keys: EphemeralKeys);
+    /**
+     * Makes a person, or finds the one your `external_id` already names.
+     * 409 when the plan's maximum end users is reached (a repeat of an
+     * existing `external_id` is answered as ever).
+     */
+    create(body?: EndUserCreateRequest, options?: RequestOptions): Promise<EndUserCreated>;
+    /** One page, newest first, with the `total` the filter matches. */
+    page(params?: EndUserListParams, options?: RequestOptions): Promise<EndUserList>;
+    /** Every person, newest first, page after page (`limit` a page, 200 by default). */
+    list(params?: Omit<EndUserListParams, "offset">, options?: RequestOptions): AsyncGenerator<EndUserInfo, void, undefined>;
+    /** Everything about one person, read with a key of their own (see the header). */
+    export(id: string, options?: RequestOptions): Promise<EndUserExport>;
+}

package/dist/resources/end-users.js

@@ -0,0 +1,139 @@
+/**
+ * `client.endUsers`: the people your agents talk to — `/v1/end-users*`,
+ * and everything about one of them in `export`.
+ *
+ * - **`create` with your own `external_id` is idempotent**: the same value
+ *   is always the same person, made only the first time (200 found, 201
+ *   made). So it is retried like a GET; without an `external_id` every call
+ *   makes someone new, and only a 429 is retried.
+ * - **Either id works everywhere**: the `eu_…` the API made, or your
+ *   `external_id`. Path parameters are encoded, so an id may hold `/`.
+ * - **`update` renames them, or changes your id for them**: absent fields
+ *   are untouched, `null` clears one; 409 when another person has that
+ *   `external_id`.
+ * - **`delete` is what to call when someone asks to be forgotten**: it
+ *   deletes them, every conversation they had and everything remembered
+ *   about them, and answers the counts. Someone already gone is done, not
+ *   an error: `null`.
+ *
+ * **`export`** reads what the API holds about one person with a key of
+ * their own, since their conversations and facts are their end user DO's
+ * and an API key cannot read them (`/v1/agent/*` takes only an ephemeral
+ * key): it mints a five-minute key for them, lists their sessions (200 a
+ * page), reads each transcript backwards (200 messages a page, four
+ * sessions at a time), reads their facts, and revokes the key in
+ * `finally` — after an abort or a failure too. The cost: one mint (and
+ * `limits()` when cold) + ⌈S/200⌉ lists + Σ⌈M/200⌉ transcript pages + one
+ * facts read + one revoke. **Its ceilings**: the key is ordinary, so at
+ * the person's live-key cap or the plan's mint rate the export fails as
+ * the mint does (422, 429) and can be retried once a key lapses; it lives
+ * five minutes, so a history that takes longer to read fails with a 401;
+ * its one micro-credit is set aside like any key's, so an organisation
+ * with no balance cannot export (402); and the facts route answers the
+ * first 100 until it pages (left-overs #109).
+ */
+import { byOffset } from "../paging.js";
+import { segment, } from "../transport.js";
+import { Editable } from "./resource.js";
+/** The routes' own page bound, for end users, sessions and transcripts alike. */
+const PAGE = 200;
+/** The export key's lifetime and limit: the shortest useful, the least set aside. */
+const EXPORT_TTL_S = 300;
+const EXPORT_CREDIT = "0.000001";
+/** Transcripts read at once. */
+const EXPORT_PARALLEL = 4;
+/** `work` over every item, `width` at a time, answers in the items' order. */
+async function inParallel(items, width, work) {
+    const out = new Array(items.length);
+    let next = 0;
+    const lane = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await work(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(width, items.length) }, lane));
+    return out;
+}
+export class EndUsers extends Editable {
+    constructor(api, base, keys) {
+        super(api, base);
+        this.keys = keys;
+    }
+    /**
+     * Makes a person, or finds the one your `external_id` already names.
+     * 409 when the plan's maximum end users is reached (a repeat of an
+     * existing `external_id` is answered as ever).
+     */
+    async create(body = {}, options) {
+        const answer = await this.api.request({
+            method: "POST",
+            path: this.base,
+            body,
+            // A string or nothing, by its type: so a non-empty one.
+            idempotent: !!body.external_id,
+        }, options);
+        return { ...answer.data, created: answer.status === 201 };
+    }
+    /** One page, newest first, with the `total` the filter matches. */
+    page(params = {}, options) {
+        return this.send("GET", "", options, params);
+    }
+    /** Every person, newest first, page after page (`limit` a page, 200 by default). */
+    list(params = {}, options) {
+        return byOffset(async (offset, limit) => {
+            const page = await this.page({ ...params, offset, limit }, options);
+            return { items: page.end_users, total: page.total };
+        }, params.limit ?? PAGE);
+    }
+    /** Everything about one person, read with a key of their own (see the header). */
+    async export(id, options = {}) {
+        const key = await this.keys.create({
+            end_user_id: id,
+            credit_limit: EXPORT_CREDIT,
+            expires_in_seconds: EXPORT_TTL_S,
+            label: "export",
+        }, options);
+        try {
+            // Every read as the person: the agent routes take nothing else.
+            const read = (path, query) => this.api
+                .request({ method: "GET", path, query, token: key.key }, options)
+                .then((answer) => answer.data);
+            const listed = [];
+            for await (const session of byOffset(async (offset, limit) => ({
+                items: await read("/v1/agent/sessions", {
+                    offset,
+                    limit,
+                }),
+            }), PAGE)) {
+                listed.push(session);
+            }
+            const sessions = await inParallel(listed, EXPORT_PARALLEL, async (s) => {
+                const path = `/v1/agent/sessions/${segment(s.id)}`;
+                const page = (before) => read(path, { limit: PAGE, before });
+                const newest = await page();
+                const pages = [newest.messages];
+                for (let before = newest.next_before; typeof before === "number";) {
+                    const older = await page(before);
+                    pages.unshift(older.messages);
+                    before = older.next_before;
+                }
+                return { ...newest, messages: pages.flat(), next_before: null };
+            });
+            const facts = await read("/v1/agent/facts");
+            return {
+                end_user_id: key.end_user_id ?? facts.end_user_id,
+                sessions,
+                facts: facts.facts,
+            };
+        }
+        finally {
+            // Without the caller's signal: an aborted export still revokes.
+            const { signal: _, ...revoking } = options;
+            await this.keys.revoke(key.id, revoking).catch(() => {
+                // swallowed: the key lapses by itself within its five minutes, and
+                // the export's own answer or error is the one the caller needs.
+            });
+        }
+    }
+}

package/dist/resources/ephemeral-keys.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `client.ephemeralKeys`: the keys an end user's device talks to agents
+ * with — `/v1/ephemeral-keys*` and `/v1/token`.
+ *
+ * - **A key is prepaid**: its `credit_limit` is set aside from the balance
+ *   when it is minted (402 when it cannot be), and what it does not spend
+ *   comes back when it settles.
+ * - **`create` clamps the lifetime by default** to the platform's maximum,
+ *   read from `limits()` — which the API never does: past a cap is a 422
+ *   (`apps/api/src/org/minting.ts`). The plan's own caps for one end
+ *   user's key are not reported yet (left-overs #107), so a key within the
+ *   platform's can still be refused.
+ * - **`limits()` is cached five minutes per client**, so a mint is two
+ *   requests cold and one warm. Concurrent cold callers share one read.
+ * - **`revoke` answers at once**, with the figures from before the key's
+ *   end user DO settles: revocation leaves through the org DO's outbox
+ *   (`apps/api/src/org/areas/keys.ts` `revokeEphemeral`). Waiting for the
+ *   final figures needs the key's read route (left-overs #106).
+ * - **`inspect` reads a key as itself** (`GET /v1/token` with that key).
+ *   Its `credits_spent` moves only when the key settles — at the end, or
+ *   daily — so a live key reads as unspent (left-overs #105).
+ */
+import type { EphemeralKeyCreateRequest, EphemeralKeyCreateResponse, EphemeralKeyInfo, EphemeralKeyLimits, EphemeralTokenSelf, ListEphemeralKeysData } from "../gen/index.js";
+import { type RequestOptions } from "../transport.js";
+import { Resource } from "./resource.js";
+export type EphemeralKeyListParams = NonNullable<ListEphemeralKeysData["query"]>;
+export interface EphemeralKeyCreateOptions extends RequestOptions {
+    /**
+     * Cut `expires_in_seconds` to the platform's maximum instead of being
+     * refused for it, and send the default when it is absent. On by default;
+     * `false` sends the body as written, in one request.
+     */
+    clampTtl?: boolean;
+}
+export declare class EphemeralKeys extends Resource {
+    private cached;
+    /**
+     * What a key may be minted with: the **platform's** longest lifetime and
+     * largest credit limit, and the scopes this API key may grant. Cached
+     * five minutes per client.
+     */
+    limits(options?: RequestOptions): Promise<EphemeralKeyLimits>;
+    /**
+     * Mints a key for one end user — returned **once**, as `key`. Scopes
+     * are exactly `["agent"]` (the default). 402 when the balance cannot set
+     * `credit_limit` aside, 422 past a cap, 429 past the plan's mints a
+     * minute (retried after its `Retry-After`).
+     */
+    create(body: EphemeralKeyCreateRequest, options?: EphemeralKeyCreateOptions): Promise<EphemeralKeyCreateResponse>;
+    /**
+     * Revokes a key: it is refused from now on, and what it did not spend
+     * comes back when it settles. `null` when there is no such key — a
+     * revoked, expired or unknown id answers as itself, a non-UUID as none.
+     */
+    revoke(id: string, options?: RequestOptions): Promise<EphemeralKeyInfo | null>;
+    /**
+     * A key as it reads itself: its scopes, limit, spend and expiry. `null`
+     * when the key is refused — expired, revoked, spent or not a key.
+     */
+    inspect(key: string, options?: RequestOptions): Promise<EphemeralTokenSelf | null>;
+    /** One page of this organisation's keys: live ones unless `live_only` is `false`. */
+    page(params?: EphemeralKeyListParams, options?: RequestOptions): Promise<EphemeralKeyInfo[]>;
+    /** Every key, page after page (`limit` a page, 500 by default). */
+    list(params?: Omit<EphemeralKeyListParams, "offset">, options?: RequestOptions): AsyncGenerator<EphemeralKeyInfo, void, undefined>;
+}