@lumavox/server 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -5,8 +5,9 @@
  * 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 { AuthenticationError, ConflictError, ConnectionError, InsufficientCreditsError, NotFoundError, PermissionError, PlatformError, type PlatformErrorCode, type PlatformErrorInit, RateLimitError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
 export type * from "./gen/index.js";
+export type { Page } from "./paging.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";

package/dist/paging.d.ts

@@ -1,34 +1,24 @@
 /**
- * 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.
+ * Paging as the API pages: every list answers one shape, `{data,
+ * next_cursor}`, asked for with `limit` and `cursor`, and `next_cursor` is
+ * `null` on the last page (`docs/history/wire.md`). So one iterator serves
+ * every list: each resource's `list()` is every item, page after page by
+ * cursor, and `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.
+ * - **Nothing is seen twice, nothing is counted**: the cursor is the
+ *   store's own position, opaque, and no list says its total.
+ * - **A list bounded by nature** — agents, voices, templates, a folder's
+ *   level — answers the same page with `next_cursor` always `null`, so its
+ *   `list()` reads once; the day the route pages, it reads on without a
+ *   change here.
+ * - **A list inside a resource** — a session's messages, which
+ *   `endUsers.export` reads back to the start — pages by its own field's
+ *   `next_cursor` (`resources/end-users.ts`).
  */
-/** 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;
+/** One page of any list: its items, and where the next starts — `null` on the last. */
+export interface Page<T> {
+    data: T[];
+    next_cursor: 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>;
+export declare function pages<T>(read: (cursor: string | undefined) => Promise<Page<T>>): AsyncGenerator<T, void, undefined>;

package/dist/paging.js

@@ -1,41 +1,26 @@
 /**
- * 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.
+ * Paging as the API pages: every list answers one shape, `{data,
+ * next_cursor}`, asked for with `limit` and `cursor`, and `next_cursor` is
+ * `null` on the last page (`docs/history/wire.md`). So one iterator serves
+ * every list: each resource's `list()` is every item, page after page by
+ * cursor, and `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.
+ * - **Nothing is seen twice, nothing is counted**: the cursor is the
+ *   store's own position, opaque, and no list says its total.
+ * - **A list bounded by nature** — agents, voices, templates, a folder's
+ *   level — answers the same page with `next_cursor` always `null`, so its
+ *   `list()` reads once; the day the route pages, it reads on without a
+ *   change here.
+ * - **A list inside a resource** — a session's messages, which
+ *   `endUsers.export` reads back to the start — pages by its own field's
+ *   `next_cursor` (`resources/end-users.ts`).
  */
-/** 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) {
+export async function* pages(read) {
     let cursor;
     do {
         const page = await read(cursor);
-        yield* page.items;
-        cursor = page.next ?? undefined;
+        yield* page.data;
+        cursor = page.next_cursor ?? undefined;
     } while (cursor);
 }

package/dist/resources/agents.d.ts

@@ -8,9 +8,11 @@
  * - **`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.
+ *   `true`, and `false` for one already gone.
+ * - **`list()` reads one page**: an organisation's agents are few, and the
+ *   route answers them all with `next_cursor` `null` (`paging.ts`).
  */
-import type { AgentCreateRequest, AgentInfo, AgentList, AgentSettingsInfo, AgentSettingsUpdate, AgentUpdate, KnowledgeAssigned, KnowledgeAssignment, KnowledgeList } from "../gen/index.js";
+import type { AgentCreateRequest, AgentInfo, AgentKnowledgeUpdate, AgentPage, AgentSettingsInfo, AgentSettingsUpdate, AgentSummary, AgentUpdate, KnowledgeAssigned, KnowledgeInfo } from "../gen/index.js";
 import type { RequestOptions, Transport } from "../transport.js";
 import { Editable } from "./resource.js";
 /** `agents.settings`: the organisation's, for every agent. */
@@ -20,15 +22,18 @@ export interface AgentSettings {
 }
 /** `agents.knowledge`: the entries one agent may look up. */
 export interface AgentKnowledge {
-    list(agentId: string, options?: RequestOptions): Promise<KnowledgeList>;
+    /** Every entry it may look up. */
+    list(agentId: string, options?: RequestOptions): AsyncGenerator<KnowledgeInfo, void, undefined>;
     /** Replaces them all with these. */
-    set(agentId: string, body: KnowledgeAssignment, options?: RequestOptions): Promise<KnowledgeAssigned>;
+    set(agentId: string, body: AgentKnowledgeUpdate, options?: RequestOptions): Promise<KnowledgeAssigned>;
 }
 export declare class Agents extends Editable<AgentInfo, AgentUpdate> {
     readonly settings: AgentSettings;
     readonly knowledge: AgentKnowledge;
     constructor(api: Transport, base: string);
+    /** The page of agents, as the route answers it. */
+    page(options?: RequestOptions): Promise<AgentPage>;
     /** Every agent. */
-    list(options?: RequestOptions): Promise<AgentList>;
+    list(options?: RequestOptions): AsyncGenerator<AgentSummary, void, undefined>;
     create(body: AgentCreateRequest, options?: RequestOptions): Promise<AgentInfo>;
 }

package/dist/resources/agents.js

@@ -8,7 +8,9 @@
  * - **`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.
+ *   `true`, and `false` for one already gone.
+ * - **`list()` reads one page**: an organisation's agents are few, and the
+ *   route answers them all with `next_cursor` `null` (`paging.ts`).
  */
 import { Editable } from "./resource.js";
 export class Agents extends Editable {
@@ -19,13 +21,17 @@ export class Agents extends Editable {
             update: (body, options) => this.send("PUT", "/settings", options, body),
         };
         this.knowledge = {
-            list: (id, options) => this.send("GET", this.at(id, "/knowledge"), options),
+            list: (id, options) => this.each(this.at(id, "/knowledge"), {}, options),
             set: (id, body, options) => this.send("PUT", this.at(id, "/knowledge"), options, body),
         };
     }
+    /** The page of agents, as the route answers it. */
+    page(options) {
+        return this.send("GET", "", options);
+    }
     /** Every agent. */
     list(options) {
-        return this.send("GET", "", options);
+        return this.each("", {}, options);
     }
     create(body, options) {
         return this.send("POST", "", options, body);

package/dist/resources/assets.d.ts

@@ -9,17 +9,18 @@
  *   `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.
+ * - **`delete` answers `true`**, and `false` for one already gone: done.
+ *   `deleteMany` and `move` answer how many they touched; a folder's
+ *   `delete` how many it moved up a level, and `null` for one gone.
  * - **`list()` pages by cursor**, 200 a page; a folder's `list()` is one
- *   level, as the route answers it.
+ *   level, which the route answers in one page.
  */
-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 { AssetBulkRequest, AssetDetail, AssetMoveRequest, AssetPage, AssetSummary, AssetsAffected, AssetUpdate, FolderCreate, FolderDeleted, FolderDetail, FolderPage, FolderSummary, FolderUpdate, ListAssetFoldersData, ListAssetsData, 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"]>;
+export type FolderListParams = NonNullable<ListAssetFoldersData["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. */
@@ -30,16 +31,20 @@ export type AssetUploadFields = Omit<UploadConfirm, "asset_id" | "content_type">
  * 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>;
+export declare class Folders extends Editable<FolderDetail, FolderUpdate, FolderSummary, FolderDeleted | null> {
+    /** One level — the top, or `parent_id`'s children — as the route answers it. */
+    page(params?: FolderListParams, options?: RequestOptions): Promise<FolderPage>;
+    /** Every folder of one level: the top, or `parent_id`'s children. */
+    list(params?: FolderListParams, options?: RequestOptions): AsyncGenerator<FolderSummary, void, undefined>;
+    /** Deletes it, moving what it held up a level: how many moved, or `null` when there is none. */
+    delete(id: string, options?: RequestOptions): Promise<FolderDeleted | null>;
     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> {
+export declare class Assets extends Waitable<AssetDetail, AssetUpdate> {
     readonly folders: Folders;
     constructor(api: Transport, base: string);
     /** One page, with the `next_cursor` of the next. */

package/dist/resources/assets.js

@@ -9,15 +9,15 @@
  *   `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.
+ * - **`delete` answers `true`**, and `false` for one already gone: done.
+ *   `deleteMany` and `move` answer how many they touched; a folder's
+ *   `delete` how many it moved up a level, and `null` for one gone.
  * - **`list()` pages by cursor**, 200 a page; a folder's `list()` is one
- *   level, as the route answers it.
+ *   level, which the route answers in one page.
  */
-import { byCursor } from "../paging.js";
 import { needType, put, } from "../upload.js";
 import { Editable, Waitable } from "./resource.js";
-/** The route's own page bound. */
+/** The route's largest page. */
 const PAGE = 200;
 /**
  * `assets.folders`: the library's tree. `get` answers a folder with its
@@ -25,10 +25,18 @@ const PAGE = 200;
  * `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) {
+    /** One level — the top, or `parent_id`'s children — as the route answers it. */
+    page(params = {}, options) {
         return this.send("GET", "", options, params);
     }
+    /** Every folder of one level: the top, or `parent_id`'s children. */
+    list(params = {}, options) {
+        return this.each("", params, options);
+    }
+    /** Deletes it, moving what it held up a level: how many moved, or `null` when there is none. */
+    delete(id, options) {
+        return this.drop(id, options);
+    }
     create(body, options) {
         return this.send("POST", "", options, body);
     }
@@ -48,10 +56,7 @@ export class Assets extends Waitable {
     }
     /** 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 };
-        });
+        return this.each("", params, options, PAGE);
     }
     /** A signed URL to `PUT` a file to, with exactly this type. */
     uploadUrl(body, options) {

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

@@ -20,19 +20,21 @@
  * 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).
+ * page), reads each transcript back to its start by `messages.next_cursor`
+ * (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 newest 100 in one page until it pages (left-overs
+ * #109) — read here by its cursor, so the day it does, the export has
+ * them all.
  */
-import type { EndUserCreateRequest, EndUserDeleted, EndUserInfo, EndUserList, EndUserUpdateRequest, FactInfo, ListEndUsersData, SessionDetail } from "../gen/index.js";
+import type { EndUserCreateRequest, EndUserDeleted, EndUserInfo, EndUserPage, 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";
@@ -50,12 +52,15 @@ export type EndUserCreated = EndUserInfo & {
 export interface EndUserExport {
     /** Their `eu_…` id. */
     end_user_id: string;
-    /** Every conversation, newest first, each with every message, oldest first. */
+    /**
+     * Every conversation, most recent first, each with every message,
+     * oldest first, in its one page of `messages` (`next_cursor` `null`).
+     */
     sessions: SessionDetail[];
-    /** What is remembered about them, oldest first — the first 100 for now. */
+    /** What is remembered about them, oldest first — the newest 100 for now. */
     facts: FactInfo[];
 }
-export declare class EndUsers extends Editable<EndUserInfo, EndUserUpdateRequest, EndUserInfo, EndUserDeleted> {
+export declare class EndUsers extends Editable<EndUserInfo, EndUserUpdateRequest, EndUserInfo, EndUserDeleted | null> {
     private readonly keys;
     constructor(api: Transport, base: string, keys: EphemeralKeys);
     /**
@@ -64,10 +69,12 @@ export declare class EndUsers extends Editable<EndUserInfo, EndUserUpdateRequest
      * 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>;
+    /** One page, newest first, with the `next_cursor` of the next. */
+    page(params?: EndUserListParams, options?: RequestOptions): Promise<EndUserPage>;
     /** Every person, newest first, page after page (`limit` a page, 200 by default). */
-    list(params?: Omit<EndUserListParams, "offset">, options?: RequestOptions): AsyncGenerator<EndUserInfo, void, undefined>;
+    list(params?: Omit<EndUserListParams, "cursor">, options?: RequestOptions): AsyncGenerator<EndUserInfo, void, undefined>;
+    /** Deletes them and all they had: the counts, or `null` when there is no such person. */
+    delete(id: string, options?: RequestOptions): Promise<EndUserDeleted | null>;
     /** 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

@@ -20,28 +20,37 @@
  * 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).
+ * page), reads each transcript back to its start by `messages.next_cursor`
+ * (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 newest 100 in one page until it pages (left-overs
+ * #109) — read here by its cursor, so the day it does, the export has
+ * them all.
  */
-import { byOffset } from "../paging.js";
+import { pages } 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. */
+/** The routes' largest page, 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";
+const EXPORT_CREDIT_MICROS = 1;
 /** Transcripts read at once. */
 const EXPORT_PARALLEL = 4;
+/** Every item of `items`, in an array. */
+async function all(items) {
+    const out = [];
+    for await (const item of items)
+        out.push(item);
+    return out;
+}
 /** `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);
@@ -75,22 +84,23 @@ export class EndUsers extends Editable {
         }, options);
         return { ...answer.data, created: answer.status === 201 };
     }
-    /** One page, newest first, with the `total` the filter matches. */
+    /** One page, newest first, with the `next_cursor` of the next. */
     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);
+        return this.each("", params, options, PAGE);
+    }
+    /** Deletes them and all they had: the counts, or `null` when there is no such person. */
+    delete(id, options) {
+        return this.drop(id, options);
     }
     /** 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,
+            credit_limit_micros: EXPORT_CREDIT_MICROS,
             expires_in_seconds: EXPORT_TTL_S,
             label: "export",
         }, options);
@@ -99,33 +109,27 @@ export class EndUsers extends Editable {
             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 listed = await all(pages((cursor) => read("/v1/agent/sessions", { limit: PAGE, cursor })));
             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 page = (cursor) => read(`/v1/agent/sessions/${segment(s.id)}`, {
+                    limit: PAGE,
+                    cursor,
+                });
+                // The newest messages first; each older page goes before them.
                 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;
+                const held = [newest.messages.data];
+                for (let cursor = newest.messages.next_cursor; cursor;) {
+                    const older = (await page(cursor)).messages;
+                    held.unshift(older.data);
+                    cursor = older.next_cursor;
                 }
-                return { ...newest, messages: pages.flat(), next_before: null };
+                return {
+                    ...newest,
+                    messages: { data: held.flat(), next_cursor: null },
+                };
             });
-            const facts = await read("/v1/agent/facts");
-            return {
-                end_user_id: key.end_user_id ?? facts.end_user_id,
-                sessions,
-                facts: facts.facts,
-            };
+            const facts = await all(pages((cursor) => read("/v1/agent/facts", { cursor })));
+            return { end_user_id: key.end_user_id ?? id, sessions, facts };
         }
         finally {
             // Without the caller's signal: an aborted export still revokes.

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

@@ -2,8 +2,8 @@
  * `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
+ * - **A key is prepaid**: its `credit_limit_micros` 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
@@ -17,10 +17,10 @@
  *   (`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
+ *   Its `credits_spent_micros` 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 { EphemeralKeyCreateRequest, EphemeralKeyCreateResponse, EphemeralKeyInfo, EphemeralKeyLimits, EphemeralKeyPage, EphemeralTokenSelf, ListEphemeralKeysData } from "../gen/index.js";
 import { type RequestOptions } from "../transport.js";
 import { Resource } from "./resource.js";
 export type EphemeralKeyListParams = NonNullable<ListEphemeralKeysData["query"]>;
@@ -43,7 +43,7 @@ export declare class EphemeralKeys extends Resource {
     /**
      * 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
+     * `credit_limit_micros` 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>;
@@ -58,8 +58,8 @@ export declare class EphemeralKeys extends Resource {
      * 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>;
+    /** One page of this organisation's keys, newest first: live ones unless `live_only` is `false`. */
+    page(params?: EphemeralKeyListParams, options?: RequestOptions): Promise<EphemeralKeyPage>;
+    /** Every key, page after page (`limit` a page, 200 by default). */
+    list(params?: Omit<EphemeralKeyListParams, "cursor">, options?: RequestOptions): AsyncGenerator<EphemeralKeyInfo, void, undefined>;
 }

package/dist/resources/ephemeral-keys.js

@@ -2,8 +2,8 @@
  * `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
+ * - **A key is prepaid**: its `credit_limit_micros` 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
@@ -17,16 +17,15 @@
  *   (`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
+ *   Its `credits_spent_micros` moves only when the key settles — at the end, or
  *   daily — so a live key reads as unspent (left-overs #105).
  */
 import { AuthenticationError } from "../errors.js";
-import { byOffset } from "../paging.js";
 import { orNull } from "../transport.js";
 import { Resource } from "./resource.js";
 const LIMITS_TTL_MS = 5 * 60_000;
-/** The route's own page bound. */
-const PAGE = 500;
+/** The route's largest page. */
+const PAGE = 200;
 /** `promise`, or the signal's reason when it aborts first. */
 function until(promise, signal) {
     if (!signal)
@@ -72,7 +71,7 @@ export class EphemeralKeys extends Resource {
     /**
      * 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
+     * `credit_limit_micros` aside, 422 past a cap, 429 past the plan's mints a
      * minute (retried after its `Retry-After`).
      */
     async create(body, options = {}) {
@@ -116,14 +115,12 @@ export class EphemeralKeys extends Resource {
         }
         return self;
     }
-    /** One page of this organisation's keys: live ones unless `live_only` is `false`. */
+    /** One page of this organisation's keys, newest first: live ones unless `live_only` is `false`. */
     page(params = {}, options) {
         return this.send("GET", "", options, params);
     }
-    /** Every key, page after page (`limit` a page, 500 by default). */
+    /** Every key, page after page (`limit` a page, 200 by default). */
     list(params = {}, options) {
-        return byOffset(async (offset, limit) => ({
-            items: await this.page({ ...params, offset, limit }, options),
-        }), params.limit ?? PAGE);
+        return this.each("", params, options, PAGE);
     }
 }