primitive-admin 1.0.63 → 1.0.64

package/dist/src/lib/api-client.js

@@ -1,7 +1,16 @@
 import { loadCredentials, saveCredentials, isTokenExpiringSoon, } from "./config.js";
+import { getCurrentEnvNameSafe } from "./env-resolver.js";
 import { fetchWithTLS } from "./fetch.js";
 import { paginateAll, normalizeCliListEnvelope } from "./paginate.js";
 import { RefreshError, refreshAdminCredentials, } from "./refresh-admin-credentials.js";
+import { drainAppsUntilConverged, } from "./workflow-usage.js";
+/**
+ * Page size the admin per-user inventories are asked for (#3399).
+ *
+ * `MAX_LIST_LIMIT` on the server, so a heavy user's inventory is walked in the
+ * fewest round trips the contract allows; a larger value is clamped there.
+ */
+const ADMIN_INVENTORY_PAGE_SIZE = 100;
 export class ApiError extends Error {
     statusCode;
     code;
@@ -40,6 +49,24 @@ export class ConflictError extends ApiError {
         this.name = "ConflictError";
     }
 }
+/**
+ * The `ApiError` for a non-OK response read by a raw `fetch` call (#3403).
+ *
+ * The blob methods and the two document-artifact transfers build their own
+ * `fetch` call, so they never reached `parseErrorResponse` and never carried a
+ * `code` — a download refusal surfaced as `response.statusText` and an upload
+ * refusal as the raw JSON body shown to the operator as the message. This
+ * routes them through the same parser every other call site uses while keeping
+ * their human prefixes.
+ *
+ * Named for the blob paths it was written for; every raw-`fetch` path in this
+ * file answers through it now.
+ */
+export async function blobFailure(response, prefix) {
+    const text = await response.text().catch(() => "");
+    const parsed = parseErrorResponse(response, text);
+    return new ApiError(`${prefix}${parsed.message}`, response.status, parsed.code, parsed.details);
+}
 /**
  * Extract a human-readable error message + structured fields from a non-OK
  * HTTP response body. Single source of truth used by every error-handler call
@@ -202,16 +229,38 @@ export function normalizeDatabaseOperationResult(raw) {
     return envelope;
 }
 export class ApiClient {
+    /**
+     * Loaded on first use (`ensureAuthenticated`), never in a constructor.
+     *
+     * There used to be an `apiClient` singleton constructed at MODULE scope, so
+     * a constructor body ran while `bin/primitive.ts` was still being imported —
+     * before its first `try`, and before any command had said whether it needed
+     * the project at all. `loadCredentials()` resolves the environment, so on a
+     * project still holding the pre-#3153 layout that read threw the stale-layout
+     * refusal out of module evaluation, where not even the `uncaughtException`
+     * handler can reach it: the user got Node's raw stack trace, and `guides
+     * get` — which reads nothing from the project — died with it (#3273). The
+     * singleton is gone (#3154, it had no callers) and the read stays lazy,
+     * which is what keeps that shape from coming back.
+     *
+     * Nothing is lost by waiting, and one thing is gained: a `login` earlier in
+     * the same process is visible to a later request.
+     */
     credentials = null;
-    constructor() {
-        this.credentials = loadCredentials();
-    }
     async ensureAuthenticated() {
         if (!this.credentials) {
             this.credentials = loadCredentials();
         }
         if (!this.credentials) {
-            throw new ApiError("Not logged in. Run 'bao-admin login' first.", 401);
+            // Name the environment when there is one (#1293). Before #3152 this case
+            // surfaced from `resolveAppId`, because an unauthenticated environment
+            // resolved no app at all; now the environment always names its app, so
+            // "not logged in" is only ever an auth failure, and it is reported here,
+            // once, for every command.
+            const envName = getCurrentEnvNameSafe();
+            throw new ApiError(envName
+                ? `Not logged in to environment "${envName}". Run 'primitive -e ${envName} login'.`
+                : "Not logged in. Run 'primitive login' first.", 401);
         }
         // Check if token needs refresh
         if (isTokenExpiringSoon(this.credentials)) {
@@ -235,7 +284,10 @@ export class ApiClient {
                 // error or a server-side rejection. Callers that need a finer
                 // distinction (e.g. `primitive token`) consume RefreshError directly
                 // from refresh-admin-credentials.ts instead of going through here.
-                throw new ApiError("Token refresh failed. Please login again.", 401);
+                // A revoked session (#3885) says so.
+                throw new ApiError(err.code === "SESSION_REVOKED"
+                    ? err.message
+                    : "Token refresh failed. Please login again.", 401, err.code);
             }
             throw err;
         }
@@ -342,26 +394,79 @@ export class ApiClient {
     // ============================================
     // APPS
     // ============================================
+    /**
+     * One page of the apps the caller can reach.
+     *
+     * The route paginates cursor-style (default pageSize=25, cap=100). This
+     * method used to walk the whole chain so `primitive apps list` could not
+     * truncate at 25 (#436); since #3646 the page boundary belongs to the
+     * caller instead — `apps list` declares `--limit`/`--cursor` and prints the
+     * `hasMore`/`nextCursor` the server reported, and the aggregate readers that
+     * really do mean "every app" call `listAllApps()`.
+     */
+    async listAppsPage(params) {
+        const qs = new URLSearchParams();
+        if (params?.limit !== undefined)
+            qs.set("limit", String(params.limit));
+        if (params?.cursor)
+            qs.set("cursor", params.cursor);
+        const q = qs.toString();
+        const resp = await this.get(`/admin/api/admins/me/apps${q ? `?${q}` : ""}`);
+        // The server now emits `items` with `apps` as a deprecation-window alias
+        // (#1316). Read `items` first so listings keep working once the alias is
+        // removed; fall back to the legacy `apps` key meanwhile.
+        return {
+            items: resp?.items ?? (Array.isArray(resp?.apps) ? resp.apps : []),
+            hasMore: resp?.hasMore,
+            nextCursor: resp?.nextCursor ?? resp?.cursor ?? null,
+        };
+    }
+    /**
+     * Every app the caller can reach, cursor chain walked (#436).
+     *
+     * For readers that genuinely need the whole set — an app picker, a sweep —
+     * rather than the one page `apps list` prints.
+     */
     async listApps() {
-        // The server paginates cursor-style (default pageSize=25, cap=100). Historically
-        // this method issued a single un-paginated GET and silently truncated to the
-        // first page, which broke `primitive use <app-id>` and `primitive apps list`
-        // for admins with more than 25 apps (see #436). Iterate every page.
         const apps = await paginateAll(async (cursor) => {
+            const page = await this.listAppsPage({ limit: 100, cursor });
+            return { items: page.items, nextCursor: page.nextCursor };
+        });
+        return { apps };
+    }
+    /**
+     * Every app on the server, not just the caller's own.
+     *
+     * Deliberately separate from `listApps()`, whose contract is "apps assigned
+     * to me" (`GET /admin/api/admins/me/apps`, backed by `admin.queryApps()`) —
+     * the contract every other command depends on. `analytics workflow-usage
+     * --all-apps` has to reach apps nobody is assigned to, which is the global
+     * route `GET /admin/api/apps` (`App.iterateAll()`), and that route
+     * identifies an app as `appId` rather than `id` (D3130-001).
+     *
+     * One drain of that route is lossy — its cursor re-scans `App.iterateAll()`
+     * from the start of each page, so a list that changes under it both repeats
+     * and drops rows — so the walk is the union of repeated drains
+     * (`drainAppsUntilConverged`, which carries the measurement).
+     */
+    async listAllAppsGlobal() {
+        const drainOnce = () => paginateAll(async (cursor) => {
             const qs = new URLSearchParams({ limit: "100" });
             if (cursor)
                 qs.set("cursor", cursor);
-            const resp = await this.get(`/admin/api/admins/me/apps?${qs.toString()}`);
-            // The server now emits `items` with `apps` as a deprecation-window
-            // alias (#1316). Read `items` first so listings keep working once the
-            // alias is removed; fall back to the legacy `apps` key meanwhile.
+            const resp = await this.get(`/admin/api/apps?${qs.toString()}`);
+            // `items` first, with the `apps` alias (#1316) as the fallback,
+            // exactly as `listApps()` reads its own envelope.
+            const rows = resp.items ?? (Array.isArray(resp.apps) ? resp.apps : []);
             return {
-                items: resp.items ??
-                    (Array.isArray(resp.apps) ? resp.apps : []),
+                items: rows.map((row) => ({
+                    appId: String(row.appId ?? row.id ?? ""),
+                    name: String(row.name ?? ""),
+                })),
                 nextCursor: resp.nextCursor ?? resp.cursor,
             };
         });
-        return { apps };
+        return drainAppsUntilConverged(drainOnce);
     }
     async createApp(data) {
         return this.post("/admin/api/apps", data);
@@ -411,9 +516,16 @@ export class ApiClient {
         const result = await this.get(path);
         return {
             items: result?.items ?? (Array.isArray(result) ? result : []),
+            // `hasMore` travels with the page so the caller prints the server's own
+            // page boundary rather than inferring one from the cursor (#3646).
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? null,
         };
     }
+    /**
+     * @deprecated Use {@link setUserAvailability} with `"disable"`
+     * (`PUT /admin/api/apps/:appId/users/:userId/disable`) instead (#518).
+     */
     async removeUser(appId, userId) {
         return this.delete(`/app/${appId}/api/users/${userId}`);
     }
@@ -521,8 +633,12 @@ export class ApiClient {
     // ============================================
     async listDeferredGrants(appId, params) {
         const result = await this.get(`/app/${appId}/api/deferred-grants`, params);
+        // `items` is the key every list envelope is built from (#3646, #1982);
+        // `grants` is the deprecated legacy name, read only as a fallback.
+        const items = result?.items ?? result?.grants ?? [];
         return {
-            grants: result?.grants ?? result?.items ?? [],
+            items,
+            grants: items,
             nextCursor: result?.nextCursor ?? null,
             hasMore: result?.hasMore,
         };
@@ -537,6 +653,7 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/integrations`, params);
         return {
             items: result?.items ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? null,
         };
     }
@@ -647,6 +764,7 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/webhooks`, params);
         return {
             items: result?.items ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? null,
         };
     }
@@ -678,6 +796,217 @@ export class ApiClient {
     async setWebhookAvailability(appId, webhookId, action) {
         return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/${action}`, {});
     }
+    // ── Server functions (#3179) ─────────────────────────────────────────
+    //
+    // The `functions` family mirrors workflows and scripts: a header with the
+    // gate and the entry, and append-only immutable config versions carrying the
+    // authored TOML bytes, the sources and the built bundle. The listing drains
+    // server-side, so it has no cursor.
+    async listFunctions(appId) {
+        const result = await this.get(`/admin/api/apps/${appId}/functions`);
+        return { items: result?.items ?? [] };
+    }
+    async getFunction(appId, functionId) {
+        return this.get(`/admin/api/apps/${appId}/functions/${functionId}`);
+    }
+    async createFunction(appId, payload) {
+        return this.post(`/admin/api/apps/${appId}/functions`, payload);
+    }
+    async updateFunction(appId, functionId, payload) {
+        return this.patch(`/admin/api/apps/${appId}/functions/${functionId}`, payload);
+    }
+    /**
+     * Archive a function, or destroy it with `hard`. Archiving KEEPS the key
+     * reserved in the app's single key namespace; the hard delete is what
+     * releases it, destroys every config version and removes the R2 objects.
+     */
+    async deleteFunction(appId, functionId, options) {
+        const query = options?.hard ? "?hard=true" : "";
+        return this.delete(`/admin/api/apps/${appId}/functions/${functionId}${query}`);
+    }
+    /** #2803 — the operational verb pair for a server function. */
+    async setFunctionAvailability(appId, functionId, action) {
+        return this.post(`/admin/api/apps/${appId}/functions/${functionId}/${action}`, {});
+    }
+    /** Every config version of a function, oldest first. */
+    /**
+     * A function's runs, newest first (#3181).
+     *
+     * A function run has no `workflowId`, so no workflow runs listing can see
+     * it — this is the only surface that lists one. Cursor-paginated like the
+     * other admin listings.
+     */
+    async listFunctionRuns(appId, functionId, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs`, params);
+        return { items: result?.items ?? [], nextCursor: result?.nextCursor ?? null };
+    }
+    /**
+     * A function run's step trace — #3348.
+     *
+     * The function-scoped twin of `getWorkflowStepRuns`, and it answers with the
+     * same rows in the same shape: `workflows/:idOrKey/runs/...` resolves its
+     * first argument to a workflow DEFINITION, which a function id and a function
+     * key alike miss, so a durable run's steps needed a route that addresses the
+     * run by the function that owns it.
+     */
+    async getFunctionStepRuns(appId, functionId, runId) {
+        const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs/${runId}/steps`);
+        return { items: result?.items ?? [] };
+    }
+    /**
+     * End a function run that will not settle — #3348.
+     *
+     * `terminated: false` means the run had already settled and the route
+     * reported its outcome instead of overwriting it.
+     */
+    async terminateFunctionRun(appId, functionId, runId) {
+        return this.post(`/admin/api/apps/${appId}/functions/${functionId}/runs/${runId}/terminate`, {});
+    }
+    /**
+     * A function's invocation records, newest first — #3287.
+     *
+     * The ADMIN route, beside the runs listing above and for the same reason:
+     * the CLI acts as an operator, not as a member of the app. The app-API twin
+     * (`functions.logs`) is what a FUNCTION reads through the SDK profile.
+     */
+    async listFunctionLogs(appId, functionId, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/logs`, params);
+        return { items: result?.items ?? [], nextCursor: result?.nextCursor ?? null };
+    }
+    /**
+     * One invocation record by its id — #3448, behind `functions logs
+     * --invocation <id>`.
+     *
+     * The id the invoke envelope answered with. A record that never existed,
+     * one of ANOTHER function, and one the seven-day TTL has expired all answer
+     * the same 404, which is what the listing's own filter promises.
+     */
+    async getFunctionLog(appId, functionId, invocationId) {
+        return this.get(`/admin/api/apps/${appId}/functions/${functionId}/logs/${invocationId}`);
+    }
+    /**
+     * One function run, RECONCILED against the engine — #3448, what
+     * `functions runs wait` polls.
+     *
+     * NOT the runs listing: that reports the STORED status, and a durable run's
+     * row stays `running` until something asks the engine, so a wait built on it
+     * would never settle.
+     */
+    async getFunctionRun(appId, functionId, runId) {
+        return this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs/${runId}`);
+    }
+    /**
+     * The operator's own APP user — #3448 D3448-009.
+     *
+     * `getMe()` reads the ADMIN profile (`/admin/api/me`); this is the
+     * app-scoped route, which answers the app user `requireAppPermission`
+     * provisions for an admin and the `appRole` it gave them. That is the
+     * identity a `functions invoke` runs under by default, and printing it is
+     * how an operator knows their call bypassed the function's `access` gate.
+     */
+    async getAppProfile(appId) {
+        return this.get(`/app/${appId}/api/me`);
+    }
+    /**
+     * Invoke a function and hand back the ANSWER, whatever its HTTP status —
+     * #3448 D3448-010.
+     *
+     * `request` throws an `ApiError` on any non-2xx, which is right for every
+     * other verb and wrong for this one: a 429 carries a `Retry-After` an
+     * operator needs to see, and a 409 mode mismatch carries the version's real
+     * mode. Rendering those from an exception means re-deriving what the server
+     * already said. So this returns the envelope with its status and its retry
+     * hint, and throws only when the request did not complete at all.
+     *
+     * `bearer` is the `--user` path's minted token; absent, the CLI's own
+     * credentials. `mode` is ALWAYS sent (D3448-012): it is what makes the
+     * server, not the CLI, the authority on a wrong verb.
+     */
+    async invokeFunction(appId, functionKey, body, options) {
+        const credentials = await this.ensureAuthenticated();
+        const base = `/app/${appId}/api/functions/${encodeURIComponent(functionKey)}`;
+        const path = options?.asSystem
+            ? `${base}/invoke-as-system`
+            : options?.runtime === "task"
+                ? `${base}/start`
+                : base;
+        const headers = {
+            Authorization: `Bearer ${options?.bearer ?? credentials.accessToken}`,
+            "Content-Type": "application/json",
+        };
+        // The CLI's own credentials reach an app-scoped route through the
+        // global-admin header; a minted user token does not need it and must not
+        // carry it.
+        if (!options?.bearer && credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const response = await fetchWithTLS(`${credentials.serverUrl}${path}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        const text = await response.text();
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // A body that is not JSON is still an answer; keep it readable.
+            parsed = { error: text };
+        }
+        const retryAfter = response.headers.get("retry-after");
+        const retryAfterSeconds = retryAfter && Number.isFinite(Number(retryAfter)) ? Number(retryAfter) : null;
+        return {
+            httpStatus: response.status,
+            retryAfterSeconds: retryAfterSeconds ??
+                (typeof parsed?.retryAfter === "number" ? parsed.retryAfter : null),
+            body: parsed,
+        };
+    }
+    /**
+     * A function's versions, newest first (#3462).
+     *
+     * Paging is opt-in on the server: with no `limit` and no `cursor` every
+     * version comes back, which is what this method did before paging existed and
+     * what an already-installed CLI still asks for. A caller that passes either
+     * gets the shared `{ items, hasMore, nextCursor }` page.
+     */
+    async listFunctionConfigs(appId, functionId, options = {}) {
+        const query = new URLSearchParams();
+        if (options.limit !== undefined)
+            query.set("limit", String(options.limit));
+        if (options.cursor)
+            query.set("cursor", options.cursor);
+        const suffix = query.toString() ? `?${query.toString()}` : "";
+        const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/configs${suffix}`);
+        return {
+            items: result?.items ?? [],
+            hasMore: result?.hasMore === true,
+            nextCursor: result?.nextCursor ?? null,
+        };
+    }
+    /**
+     * Point the function at one of its OWN existing versions (#3462). Creates no
+     * version; the activated version's capabilities, limits and triggers apply
+     * from the next call.
+     */
+    async activateFunctionConfig(appId, functionId, configId) {
+        return this.post(`/admin/api/apps/${appId}/functions/${functionId}/configs/${configId}/activate`, {});
+    }
+    async getFunctionConfig(appId, functionId, configId) {
+        return this.get(`/admin/api/apps/${appId}/functions/${functionId}/configs/${configId}`);
+    }
+    /**
+     * The stored envelope: the authored TOML bytes, every source file and the
+     * built bundle, all base64. This is what `config pull` writes back verbatim.
+     */
+    async getFunctionConfigEnvelope(appId, functionId, configId) {
+        return this.get(`/admin/api/apps/${appId}/functions/${functionId}/configs/${configId}/envelope`);
+    }
+    /** Push a config version. The server verifies `contentHash` itself. */
+    async pushFunctionConfig(appId, functionId, payload) {
+        return this.post(`/admin/api/apps/${appId}/functions/${functionId}/configs`, payload);
+    }
     /** #2803 — the operational verb pair for a prompt (admin API). */
     async setPromptAvailability(appId, promptId, action) {
         return this.post(`/admin/api/apps/${appId}/prompts/${promptId}/${action}`, {});
@@ -717,6 +1046,7 @@ export class ApiClient {
         });
         return {
             items: result?.items ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? null,
         };
     }
@@ -727,9 +1057,26 @@ export class ApiClient {
         });
         return {
             items: result?.items ?? [],
+            hasMore: result?.hasMore,
+            nextCursor: result?.nextCursor ?? null,
+        };
+    }
+    /**
+     * One page of admin sessions (#3885): the caller's own, or — for a
+     * super-admin — the admin `adminId` names.
+     */
+    async listAdminSessions(params) {
+        const result = await this.get("/admin/api/auth/sessions", params);
+        return {
+            items: result?.items ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? null,
         };
     }
+    /** Revoke an admin session (idempotent). */
+    async revokeAdminSession(sessionId) {
+        return this.delete(`/admin/api/auth/sessions/${encodeURIComponent(sessionId)}`);
+    }
     async testWebhook(appId, webhookId, payload) {
         return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/test`, payload || {});
     }
@@ -754,8 +1101,16 @@ export class ApiClient {
     async getLockStatus(appId, key) {
         return this.post(`/app/${appId}/api/locks/status`, { key });
     }
-    async acquireLock(appId, key, ttlMs) {
-        return this.post(`/app/${appId}/api/locks/acquire`, { key, ttlMs });
+    /**
+     * #3562 — `owner` is sent only when one was given, so a call that names none
+     * composes byte for byte the body it always did.
+     */
+    async acquireLock(appId, key, ttlMs, owner) {
+        return this.post(`/app/${appId}/api/locks/acquire`, {
+            key,
+            ttlMs,
+            ...(owner !== undefined ? { owner } : {}),
+        });
     }
     async releaseLock(appId, key, handleId) {
         return this.post(`/app/${appId}/api/locks/release`, {
@@ -862,6 +1217,7 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/prompts`, params);
         return {
             items: result?.items ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? null,
         };
     }
@@ -1009,6 +1365,7 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/test-cases${suffix}`);
         return {
             items: result?.items ?? result ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? undefined,
         };
     }
@@ -1160,12 +1517,23 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/workflows`, params);
         return {
             items: result?.items ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? null,
         };
     }
     async getWorkflow(appId, workflowId) {
         return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}`);
     }
+    /**
+     * One app's workflow step usage report (#3132).
+     *
+     * `windowDays` is omitted from the query when the caller did not ask for a
+     * window, so the server applies its own default rather than the CLI
+     * restating it on the wire.
+     */
+    async getWorkflowUsage(appId, params) {
+        return this.get(`/admin/api/apps/${appId}/workflows/usage`, params);
+    }
     async createWorkflow(appId, payload) {
         return this.post(`/admin/api/apps/${appId}/workflows`, payload);
     }
@@ -1327,12 +1695,27 @@ export class ApiClient {
     // ============================================
     // SUPER ADMIN: ADMINS
     // ============================================
+    /**
+     * The signed-in admin's own profile, `role` included.
+     *
+     * The role is read from the server rather than from the cached credentials
+     * file: a role changed after login would otherwise let a stale local record
+     * decide an authorization question.
+     */
+    async getMe() {
+        return this.get("/admin/api/me");
+    }
     async listAllAdmins(params) {
         const result = await this.get("/admin/api/admins", params);
         // #1316: prefer `nextCursor`; fall back to the deprecated `cursor` alias.
         const nextCursor = result?.nextCursor ?? result?.cursor ?? null;
+        const items = result?.items ?? result?.admins ?? [];
         return {
-            admins: result?.admins ?? result?.items ?? [],
+            // `items` is the key every list envelope is built from (#3646, #1982);
+            // `admins` is the deprecated legacy name, read only as a fallback.
+            items,
+            admins: items,
+            hasMore: result?.hasMore,
             nextCursor,
             cursor: nextCursor,
         };
@@ -1367,6 +1750,7 @@ export class ApiClient {
         const result = await this.get("/admin/api/catalog/prompts", params);
         return {
             items: result?.items ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? null,
         };
     }
@@ -1386,6 +1770,7 @@ export class ApiClient {
         const result = await this.get("/admin/api/catalog/integrations", params);
         return {
             items: result?.items ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? null,
         };
     }
@@ -1477,30 +1862,42 @@ export class ApiClient {
      * `options.owner` narrows the result to the databases that user created; the
      * server resolves it through the `databasesByCreator` index (#1965).
      */
+    /**
+     * One page of an app's databases (#3646).
+     *
+     * `databases list` used to walk the chain here. The route pages, so the page
+     * boundary belongs to the caller: the verb declares `--limit`/`--cursor` and
+     * prints what came back.
+     */
     async listDatabases(appId, options) {
-        return paginateAll(async (cursor) => {
-            const params = new URLSearchParams();
-            if (options?.owner)
-                params.set("owner", options.owner);
-            if (cursor)
-                params.set("cursor", cursor);
-            const qs = params.toString() ? `?${params.toString()}` : "";
-            const resp = await this.get(`/app/${appId}/api/databases${qs}`);
-            // Tolerant read: a server older than #1958 answers with a bare array.
-            // Without this a published CLI pointed at a not-yet-upgraded server
-            // would print nothing at all. Such a server also predates the `owner`
-            // filter (#1965) and ignores the unknown query parameter, so apply the
-            // filter here — the legacy rows carry `createdBy`, so this reproduces
-            // the server's own post-join filter (#2245).
-            if (Array.isArray(resp)) {
-                return {
-                    items: options?.owner
-                        ? resp.filter((db) => db?.createdBy === options.owner)
-                        : resp,
-                };
-            }
-            return { items: resp?.items ?? [], nextCursor: resp?.nextCursor };
-        });
+        const params = new URLSearchParams();
+        if (options?.owner)
+            params.set("owner", options.owner);
+        if (options?.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options?.cursor)
+            params.set("cursor", options.cursor);
+        const qs = params.toString() ? `?${params.toString()}` : "";
+        const resp = await this.get(`/app/${appId}/api/databases${qs}`);
+        // Tolerant read: a server older than #1958 answers with a bare array.
+        // Without this a published CLI pointed at a not-yet-upgraded server would
+        // print nothing at all. Such a server also predates the `owner` filter
+        // (#1965) and ignores the unknown query parameter, so apply the filter
+        // here — the legacy rows carry `createdBy`, so this reproduces the
+        // server's own post-join filter (#2245). It has no pages either.
+        if (Array.isArray(resp)) {
+            return {
+                items: options?.owner
+                    ? resp.filter((db) => db?.createdBy === options.owner)
+                    : resp,
+                hasMore: false,
+            };
+        }
+        return {
+            items: resp?.items ?? [],
+            hasMore: resp?.hasMore,
+            nextCursor: resp?.nextCursor ?? null,
+        };
     }
     async createDatabase(appId, data) {
         return this.post(`/app/${appId}/api/databases`, data);
@@ -1519,19 +1916,35 @@ export class ApiClient {
      *
      * The HTTP path stays `/metadata` because the wire field name is still
      * `metadata`; only the client/CLI-facing helper names were reframed.
+     *
+     * @deprecated Use resource metadata categories instead (`primitive metadata
+     * get database <id> <category>`, #1420, #1815).
      */
     async getDatabaseCelContext(appId, databaseId) {
         return this.get(`/app/${appId}/api/databases/${databaseId}/metadata`);
     }
-    /** Update a database's CEL context dict (merge with existing). */
+    /**
+     * Update a database's CEL context dict (merge with existing).
+     *
+     * @deprecated Use resource metadata categories instead (`primitive metadata
+     * set database <id> <category>`, #1420, #1815).
+     */
     async updateDatabaseCelContext(appId, databaseId, celContext) {
         return this.patch(`/app/${appId}/api/databases/${databaseId}/metadata`, celContext);
     }
-    /** @deprecated Use {@link getDatabaseCelContext} instead. */
+    /**
+     * @deprecated Database CEL context is deprecated; use resource metadata
+     * categories instead (`primitive metadata get database <id> <category>`,
+     * #1420, #1815).
+     */
     async getDatabaseMetadata(appId, databaseId) {
         return this.getDatabaseCelContext(appId, databaseId);
     }
-    /** @deprecated Use {@link updateDatabaseCelContext} instead. */
+    /**
+     * @deprecated Database CEL context is deprecated; use resource metadata
+     * categories instead (`primitive metadata set database <id> <category>`,
+     * #1420, #1815).
+     */
     async updateDatabaseMetadata(appId, databaseId, metadata) {
         return this.updateDatabaseCelContext(appId, databaseId, metadata);
     }
@@ -1884,9 +2297,20 @@ export class ApiClient {
     // ============================================
     // GROUP MEMBERS
     // ============================================
+    /**
+     * One page of a group's members.
+     *
+     * The route paginates cursor-style (no default limit, cap 200) and reports
+     * the boundary, so `groups members list` carries `--limit`/`--cursor` and
+     * forwards them (#3646) rather than printing a first page that claims to be
+     * the whole membership.
+     */
     async listGroupMembers(appId, groupType, groupId, options) {
-        const qs = options?.include ? `?include=${options.include}` : "";
-        const result = await this.get(`/app/${appId}/api/groups/${groupType}/${groupId}/members${qs}`);
+        const result = await this.get(`/app/${appId}/api/groups/${groupType}/${groupId}/members`, {
+            ...(options?.include ? { include: options.include } : {}),
+            ...(options?.limit !== undefined ? { limit: options.limit } : {}),
+            ...(options?.cursor ? { cursor: options.cursor } : {}),
+        });
         // #1316: prefer `nextCursor`; fall back to the deprecated `cursor` alias
         // so the CLI keeps paginating against pre-#1316 servers.
         const nextCursor = result?.nextCursor ?? result?.cursor;
@@ -1940,6 +2364,7 @@ export class ApiClient {
         const result = await this.get(`/app/${appId}/api/collections${q ? `?${q}` : ""}`);
         return {
             items: result?.items ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? result?.cursor ?? null,
         };
     }
@@ -1953,6 +2378,7 @@ export class ApiClient {
         const result = await this.get(`/app/${appId}/api/admin/collections${q ? `?${q}` : ""}`);
         return {
             items: result?.items ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? result?.cursor ?? null,
         };
     }
@@ -1981,6 +2407,7 @@ export class ApiClient {
         const result = await this.get(`/app/${appId}/api/collections/${collectionId}/documents${q ? `?${q}` : ""}`);
         return {
             items: result?.items ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? result?.cursor ?? null,
         };
     }
@@ -2133,9 +2560,82 @@ export class ApiClient {
     async exportDocumentState(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/export/state`);
     }
+    /**
+     * The export chain of a large document (#2816, behavior 20): the latest
+     * completed snapshot, the sealed overlays after its epoch, and the open
+     * epoch's overlay inline. Every other artifact arrives as an expiring
+     * signature, read through {@link downloadDocumentArtifact}.
+     */
+    async exportDocumentChain(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/export/chain`);
+    }
+    /**
+     * Read one granted artifact of a large document.
+     *
+     * The path comes from the chain and is origin-relative — the room is a
+     * Durable Object and has no reliable idea which host the caller reached it
+     * through — and the signature in it is the whole authorization, so no key is
+     * ever composed here.
+     */
+    async downloadDocumentArtifact(_appId, grantedPath) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}${grantedPath}`;
+        const response = await fetchWithTLS(url);
+        if (!response.ok) {
+            // #3403 — through the shared parser: the refusal this reads is the app
+            // API's coded envelope, and `statusText` carried none of it.
+            throw await blobFailure(response, "Failed to download document artifact: ");
+        }
+        return Buffer.from(await response.arrayBuffer());
+    }
     async importDocumentState(appId, documentId, stateBase64) {
         return this.post(`/app/${appId}/api/documents/${documentId}/import/state`, { state: stateBase64 });
     }
+    /**
+     * Upload one artifact of a large document's import chain (#2816,
+     * behavior 20).
+     *
+     * The bytes travel raw and unmodified: the manifest's digest is over the
+     * STORED bytes, so re-encoding a chunk here would fail its own verification
+     * on install. The query says which artifact it is — the server derives the
+     * key from the document it belongs to, so nothing here composes one.
+     */
+    async uploadDocumentChainArtifact(appId, documentId, query, body) {
+        const credentials = await this.ensureAuthenticated();
+        const search = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            search.set(key, String(value));
+        }
+        const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}` +
+            `/import/chain/artifact?${search.toString()}`;
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+            "Content-Type": "application/octet-stream",
+        };
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const response = await fetchWithTLS(url, {
+            method: "POST",
+            headers,
+            body: body,
+        });
+        if (!response.ok) {
+            // #3403 — through the shared parser: reading `error` alone dropped the
+            // envelope's `code` and `details`, so the refusal reached the operator
+            // (and `primitive documents import`) with nothing to branch on.
+            throw await blobFailure(response, "Failed to upload import artifact: ");
+        }
+        return await response.json().catch(() => ({}));
+    }
+    /** Start installing an uploaded chain (#2816, behavior 20). */
+    async installDocumentChain(appId, documentId, plan) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/import/chain`, plan);
+    }
+    /** How far a document's chain install has got (#2816, behavior 20). */
+    async getDocumentChainInstall(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/import/chain`);
+    }
     async getDocument(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}`);
     }
@@ -2157,6 +2657,18 @@ export class ApiClient {
     async getDocumentSchema(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/schema`);
     }
+    /**
+     * The `documentFormat` a records call states, as a query string to APPEND to
+     * a path (#3764).
+     *
+     * `post`, `patch` and `delete` take no params object — only `get` does — so
+     * for every verb but the reads the parameter rides the path. Empty when the
+     * caller states nothing, so an unparameterised call's URL is byte-identical
+     * to what it was.
+     */
+    documentFormatQuery(documentFormat) {
+        return documentFormat === undefined ? "" : `?documentFormat=${documentFormat}`;
+    }
     /**
      * Query records in a document model (issue #1964 Phase 3). Reuses the
      * server-side `GET documents/:id/records/:model` endpoint, which runs
@@ -2171,6 +2683,9 @@ export class ApiClient {
         const query = {};
         if (queryOptions?.filter)
             query.filter = JSON.stringify(queryOptions.filter);
+        if (queryOptions?.documentFormat !== undefined) {
+            query.documentFormat = queryOptions.documentFormat;
+        }
         // Forward `limit` whenever the caller supplied one (including an invalid
         // 0/negative) so the server validates and returns a clean 400 rather than
         // silently applying the default.
@@ -2188,6 +2703,9 @@ export class ApiClient {
         const query = {};
         if (queryOptions?.filter)
             query.filter = JSON.stringify(queryOptions.filter);
+        if (queryOptions?.documentFormat !== undefined) {
+            query.documentFormat = queryOptions.documentFormat;
+        }
         return this.get(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/count`, query);
     }
     /**
@@ -2200,8 +2718,9 @@ export class ApiClient {
      * `{ field, contains }` membership grouping are database-only, which is why
      * this signature is narrower than the databases one.
      */
-    async aggregateDocumentRecords(appId, documentId, modelName, options) {
-        return this.post(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/aggregate`, { options });
+    async aggregateDocumentRecords(appId, documentId, modelName, options, extra) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/aggregate` +
+            this.documentFormatQuery(extra?.documentFormat), { options });
     }
     /**
      * Fetch platform-vocabulary document statistics (issue #1964 Phase 3):
@@ -2210,6 +2729,111 @@ export class ApiClient {
     async getDocumentStats(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/stats`);
     }
+    /**
+     * A large document's snapshot builds, newest first, one page (#3432).
+     * `GET documents/:id/snapshots` → `{ items, hasMore, nextCursor? }`.
+     */
+    async listDocumentSnapshots(appId, documentId, options = {}) {
+        const params = new URLSearchParams();
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options.cursor)
+            params.set("cursor", options.cursor);
+        const query = params.toString();
+        return this.get(`/app/${appId}/api/documents/${documentId}/snapshots${query ? `?${query}` : ""}`);
+    }
+    /**
+     * A large document's bulk-load sessions, newest first (#3434, criterion 9).
+     *
+     * Read-only, through the document read helper's app-admin arm — the same
+     * door the snapshot readers use. The action verb `documents ingest` is
+     * #3435's; these two are the operator's window onto what a session did.
+     */
+    async listDocumentIngests(appId, documentId, options = {}) {
+        const params = new URLSearchParams();
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options.cursor)
+            params.set("cursor", options.cursor);
+        const query = params.toString();
+        return this.get(`/app/${appId}/api/documents/${documentId}/ingest${query ? `?${query}` : ""}`);
+    }
+    /** One bulk-load session's status (#3434). */
+    async getDocumentIngest(appId, documentId, sessionId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/ingest/${encodeURIComponent(sessionId)}`);
+    }
+    /** Open a bulk-load session on a large document (#3435, criterion 9). */
+    async createDocumentIngest(appId, documentId) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/ingest`, {});
+    }
+    /**
+     * Upload one chunk of a bulk-load session's artifact (#3435).
+     *
+     * `multipart/form-data`: the eight descriptor fields as text parts and the
+     * gzipped bytes as one file part named `chunk`. No `Content-Type` is set on
+     * the request — fetch supplies the boundary, and a header written by hand
+     * would name one the body does not use.
+     */
+    async uploadDocumentIngestChunk(appId, documentId, sessionId, chunk) {
+        const credentials = await this.ensureAuthenticated();
+        const form = new FormData();
+        form.set("model", chunk.model);
+        form.set("index", String(chunk.index));
+        form.set("rows", String(chunk.rows));
+        form.set("bytes", String(chunk.bytes));
+        form.set("rawBytes", String(chunk.rawBytes));
+        form.set("sha256", chunk.sha256);
+        form.set("firstId", chunk.firstId);
+        form.set("lastId", chunk.lastId);
+        form.set("chunk", new Blob([chunk.body]), `${chunk.index}.ndjson.gz`);
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+        };
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}` +
+            `/ingest/${encodeURIComponent(sessionId)}/chunks`;
+        const response = await fetchWithTLS(url, {
+            method: "POST",
+            headers,
+            body: form,
+        });
+        const text = await response.text();
+        let result = {};
+        try {
+            result = text ? JSON.parse(text) : {};
+        }
+        catch {
+            result = { error: text };
+        }
+        if (!response.ok) {
+            throw new ApiError(result?.error || `Failed to upload chunk: ${response.statusText}`, response.status, result?.code, result?.details);
+        }
+        return result;
+    }
+    /** Freeze a session's manifest and hand it to the pipeline (#3435). */
+    async commitDocumentIngest(appId, documentId, sessionId) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/ingest/${encodeURIComponent(sessionId)}/commit`, {});
+    }
+    /** Give a session up; allowed until the swap (#3435). */
+    async abortDocumentIngest(appId, documentId, sessionId) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/ingest/${encodeURIComponent(sessionId)}/abort`, {});
+    }
+    /** One snapshot build with its verification result (#3432). */
+    async getDocumentSnapshot(appId, documentId, buildId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/snapshots/${encodeURIComponent(buildId)}`);
+    }
+    /**
+     * Snapshot a large document now (#3666): seal the open epoch and start the
+     * base build that seal arms.
+     *
+     * Answers either the epoch that was sealed with the build it armed, or
+     * `{ sealed: false, reason: "empty" }` for an epoch that carried nothing.
+     */
+    async requestDocumentSnapshot(appId, documentId) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/snapshots`, {});
+    }
     /**
      * Create or replace a record in a document model (issue #1964 Phase 4).
      * `POST documents/:id/records/:model` with `{ id, data, options? }` —
@@ -2217,24 +2841,27 @@ export class ApiClient {
      * broadcasts to connected clients). Requires read-write+ on the document
      * or the app-admin arm. Returns `{ record }`.
      */
-    async saveDocumentRecord(appId, documentId, modelName, body) {
-        return this.post(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}`, body);
+    async saveDocumentRecord(appId, documentId, modelName, body, extra) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}` +
+            this.documentFormatQuery(extra?.documentFormat), body);
     }
     /**
      * Merge fields into an existing record (issue #1964 Phase 4).
      * `PATCH documents/:id/records/:model/:recordId` with `{ data, options? }`.
      * Returns `{ record }`.
      */
-    async patchDocumentRecord(appId, documentId, modelName, recordId, body) {
-        return this.patch(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}`, body);
+    async patchDocumentRecord(appId, documentId, modelName, recordId, body, extra) {
+        return this.patch(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}` +
+            this.documentFormatQuery(extra?.documentFormat), body);
     }
     /**
      * Delete a record from a document model (issue #1964 Phase 4).
      * `DELETE documents/:id/records/:model/:recordId`. A missing record id is
      * a silent no-op per the facade contract. Returns `{ deleted: true }`.
      */
-    async deleteDocumentRecord(appId, documentId, modelName, recordId) {
-        return this.delete(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}`);
+    async deleteDocumentRecord(appId, documentId, modelName, recordId, extra) {
+        return this.delete(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}` +
+            this.documentFormatQuery(extra?.documentFormat));
     }
     /**
      * Apply an ordered multi-model create/patch/delete blob atomically (issue
@@ -2242,8 +2869,9 @@ export class ApiClient {
      * a validation failure commits nothing. Returns the facade's
      * `{ applied, added, updated, deleted }`.
      */
-    async bulkDocumentRecords(appId, documentId, operations) {
-        return this.post(`/app/${appId}/api/documents/${documentId}/records/bulk`, { operations });
+    async bulkDocumentRecords(appId, documentId, operations, extra) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/records/bulk` +
+            this.documentFormatQuery(extra?.documentFormat), { operations });
     }
     async createDocument(appId, data) {
         return this.post(`/app/${appId}/api/documents`, data);
@@ -2272,6 +2900,16 @@ export class ApiClient {
         }
         return this.delete(`/app/${appId}/api/documents/${documentId}/permissions/${target.userId}`);
     }
+    /**
+     * Resolve a NAMED user's effective access to a document (#3658).
+     *
+     * The admin token is admitted to name a subject (it can already read every
+     * grant, group permission and membership the answer derives from), which is
+     * what makes this an operator read rather than a per-user one.
+     */
+    async validateDocumentAccessForUser(appId, documentId, userId) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/validate-access`, { userId });
+    }
     async getDocumentLinkAccess(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/link-access`);
     }
@@ -2281,8 +2919,14 @@ export class ApiClient {
     async clearDocumentLinkAccess(appId, documentId) {
         return this.delete(`/app/${appId}/api/documents/${documentId}/link-access`);
     }
-    async listDocumentInvitations(appId, documentId) {
-        return this.get(`/app/${appId}/api/documents/${documentId}/invitations`);
+    /**
+     * Pending deferred grants for a document (#2951 — replaces the removed
+     * legacy `GET /documents/:id/invitations`). Returns the `{ items }`
+     * envelope; rows are already filtered server-side to unresolved, unexpired
+     * grants whose app invitation is still outstanding.
+     */
+    async listDocumentPendingInvitations(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/pending-invitations`);
     }
     async listDocumentBlobs(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/blobs`);
@@ -2298,7 +2942,7 @@ export class ApiClient {
         }
         const response = await fetchWithTLS(url, { headers });
         if (!response.ok) {
-            throw new ApiError(`Failed to download blob: ${response.statusText}`, response.status);
+            throw await blobFailure(response, "Failed to download blob: ");
         }
         const arrayBuffer = await response.arrayBuffer();
         return Buffer.from(arrayBuffer);
@@ -2322,8 +2966,7 @@ export class ApiClient {
             body: data,
         });
         if (!response.ok) {
-            const text = await response.text();
-            throw new ApiError(`Failed to upload blob: ${text}`, response.status);
+            throw await blobFailure(response, "Failed to upload blob: ");
         }
         return response.json();
     }
@@ -2348,9 +2991,75 @@ export class ApiClient {
     async lookupUserByEmail(appId, email) {
         return this.get(`/app/${appId}/api/users/lookup`, { email });
     }
+    /**
+     * The admin inventory of one user's documents, followed to the end (#3399).
+     *
+     * The endpoint speaks the standard list contract (`{ items, hasMore,
+     * nextCursor }`) and caps a page, so one request reads one page: reading it
+     * would truncate a heavy user's inventory at the page size, which is the
+     * bug this issue is about with a smaller number on it. `documents list
+     * --user-id` and `documents export-all` both read this, and both mean "all
+     * of them". `paginateAll` carries the repeat-cursor and max-page guards, so
+     * a server handing out a non-advancing cursor fails loudly instead of
+     * looping forever.
+     *
+     * Tolerant of a pre-contract server, which answers with a bare
+     * `{ documents }` array and no cursor: that reads as a single page.
+     */
     async listAdminDocuments(appId, userId) {
-        const result = await this.get(`/admin/api/apps/${appId}/documents`, { userId });
-        return result?.documents || result || [];
+        return paginateAll(async (cursor) => {
+            const page = await this.listAdminDocumentsPage(appId, userId, {
+                limit: ADMIN_INVENTORY_PAGE_SIZE,
+                cursor,
+            });
+            return { items: page.items, nextCursor: page.nextCursor };
+        });
+    }
+    /**
+     * One page of the admin inventory of a user's documents (#3646).
+     *
+     * `documents list --user-id` prints exactly this — the page the caller's
+     * `--limit`/`--cursor` asked for, with the server's own page boundary
+     * beside it. `documents export-all`, which really does mean every document,
+     * keeps the walking `listAdminDocuments()` above.
+     *
+     * Tolerant of a pre-contract server, which answers with a bare
+     * `{ documents }` array and no cursor: that reads as a single page.
+     */
+    async listAdminDocumentsPage(appId, userId, options = {}) {
+        const params = new URLSearchParams({ userId });
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options.cursor)
+            params.set("cursor", options.cursor);
+        const result = await this.get(`/admin/api/apps/${appId}/documents?${params.toString()}`);
+        return {
+            items: result?.items ?? result?.documents ?? [],
+            hasMore: result?.hasMore,
+            // #1316: prefer `nextCursor`; the deprecated `cursor` alias keeps a
+            // shipped CLI paginating against a server that still dual-emits.
+            nextCursor: result?.nextCursor ?? result?.cursor ?? null,
+        };
+    }
+    /**
+     * The document `AppUser.rootDocId` points at, or null when the user has none
+     * yet (#3135). A user who is not a member of the app is a 404, which
+     * `documents import` reads as "this export has no target here" — distinct
+     * from "this user has no root document yet".
+     */
+    async getUserRootDocument(appId, userId) {
+        return this.get(`/admin/api/apps/${appId}/users/${userId}/root-document`);
+    }
+    /**
+     * Get or create the user's root document (#3135).
+     *
+     * The server runs the same idempotent get-or-create sign-in uses, so this
+     * never mints a second root. `created` is true only when this call's claim
+     * won — an import must not report "created", or merge without `--overwrite`,
+     * for a root a concurrent sign-in minted first.
+     */
+    async ensureUserRootDocument(appId, userId) {
+        return this.post(`/admin/api/apps/${appId}/users/${userId}/root-document`, {});
     }
     // ============================================
     // DATABASE EXPORT / IMPORT
@@ -2436,8 +3145,7 @@ export class ApiClient {
             body: data,
         });
         if (!response.ok) {
-            const text = await response.text();
-            throw new ApiError(`Failed to upload blob: ${text}`, response.status);
+            throw await blobFailure(response, "Failed to upload blob: ");
         }
         return response.json();
     }
@@ -2452,7 +3160,7 @@ export class ApiClient {
         }
         const response = await fetchWithTLS(url, { headers });
         if (!response.ok) {
-            throw new ApiError(`Failed to download blob: ${response.statusText}`, response.status);
+            throw await blobFailure(response, "Failed to download blob: ");
         }
         const arrayBuffer = await response.arrayBuffer();
         return Buffer.from(arrayBuffer);
@@ -2476,6 +3184,4 @@ export class ApiClient {
         return this.get(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs/${blobId}/metadata`);
     }
 }
-// Export a singleton instance
-export const apiClient = new ApiClient();
 //# sourceMappingURL=api-client.js.map