primitive-admin 1.1.0-alpha.9 → 1.1.0

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

@@ -1,36 +1,266 @@
 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;
-    constructor(message, statusCode, code) {
+    /**
+     * Structured `details` payload from `corsErrorResponse`.
+     *
+     * The server's error envelope can emit `details` as either:
+     *   - an array of validation issues (e.g. `[{ path, message }, ...]`) —
+     *     this is what most legacy endpoints produce, and what sync.ts walks
+     *     via `Array.isArray(err.details)` / `for (const detail of ...)`.
+     *   - a record of structured offender fields (e.g. `{ refs, operations,
+     *     opCount, line, column, ... }`) — emitted by the issue #666 schema
+     *     gate and consumed by the typed exception subclasses below.
+     *
+     * Callers must narrow before use: `Array.isArray(err.details)` for the
+     * legacy shape, otherwise treat as `Record<string, any>`.
+     */
+    details;
+    constructor(message, statusCode, code, details) {
         super(message);
         this.statusCode = statusCode;
         this.code = code;
         this.name = "ApiError";
+        if (details !== undefined) {
+            this.details = details;
+        }
     }
 }
 export class ConflictError extends ApiError {
     serverModifiedAt;
     expectedModifiedAt;
-    constructor(message, serverModifiedAt, expectedModifiedAt) {
-        super(message, 409, "CONFLICT");
+    constructor(message, serverModifiedAt, expectedModifiedAt, details) {
+        super(message, 409, "CONFLICT", details);
         this.serverModifiedAt = serverModifiedAt;
         this.expectedModifiedAt = expectedModifiedAt;
         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
+ * site in this file (see issue #684).
+ */
+export function parseErrorResponse(response, text, path) {
+    // Empty body → fall back to status code.
+    if (!text) {
+        return { message: `HTTP ${response.status}` };
+    }
+    let errorData;
+    try {
+        errorData = JSON.parse(text);
+    }
+    catch {
+        // Non-JSON body. Surface the existing `<!DOCTYPE` special-case (an HTML
+        // 404 page from hitting the wrong path) so we don't regress the helpful
+        // "API endpoint not found" message at api-client.ts:343.
+        if (text.includes("<!DOCTYPE")) {
+            const where = path ? `: ${path}` : "";
+            return {
+                message: `API endpoint not found${where}. Make sure the server is running.`,
+                htmlNotFound: true,
+            };
+        }
+        // Other non-JSON bodies (e.g. plain-text 502 from a proxy) — surface the
+        // raw text so the operator at least sees what the server returned.
+        return { message: text };
+    }
+    // Server's standard envelope uses `error`; ConflictError + integrations
+    // proxy use `message`. Prefer `error` (more common), fall back to `message`.
+    const message = (typeof errorData?.error === "string" && errorData.error) ||
+        (typeof errorData?.message === "string" && errorData.message) ||
+        `HTTP ${response.status}`;
+    // Per issue #666 addendum A1, `code` may be at the top level or nested
+    // under `details.code` when the server's bespoke envelope didn't flatten.
+    const code = (typeof errorData?.code === "string" ? errorData.code : undefined) ??
+        (typeof errorData?.details?.code === "string"
+            ? errorData.details.code
+            : undefined);
+    // Accept either an array (legacy) or a plain object (#666 schema gate).
+    const details = Array.isArray(errorData?.details)
+        ? errorData.details
+        : errorData?.details && typeof errorData.details === "object"
+            ? errorData.details
+            : undefined;
+    return { message, code, details, raw: errorData };
+}
+/**
+ * Typed exception classes for the database-schema feature (issue #666).
+ * Each maps 1:1 to a server `code` value emitted from the op-edit or
+ * schema-edit gate. They all extend ApiError so existing catch-all paths
+ * continue to work; specialized catch blocks can branch on `instanceof`.
+ *
+ * Per round-2 addendum A1, `details` is always preserved so callers can
+ * extract structured offender lists (refs[], operations[], etc.).
+ */
+export class SchemaRequiredError extends ApiError {
+    constructor(message, details) {
+        super(message, 422, "SCHEMA_REQUIRED", details);
+        this.name = "SchemaRequiredError";
+    }
+}
+function detailsRecord(details) {
+    return details && !Array.isArray(details) && typeof details === "object"
+        ? details
+        : undefined;
+}
+export class OperationRefError extends ApiError {
+    constructor(message, details) {
+        super(message, 422, "OPERATION_REFERENCES_UNDEFINED", details);
+        this.name = "OperationRefError";
+    }
+    get refs() {
+        const d = detailsRecord(this.details);
+        return Array.isArray(d?.refs) ? d.refs : [];
+    }
+}
+export class SchemaBreaksOpsError extends ApiError {
+    constructor(message, details) {
+        super(message, 422, "SCHEMA_BREAKS_OPERATIONS", details);
+        this.name = "SchemaBreaksOpsError";
+    }
+    get operations() {
+        const d = detailsRecord(this.details);
+        return Array.isArray(d?.operations) ? d.operations : [];
+    }
+}
+export class SchemaHasUncheckableOpsError extends ApiError {
+    constructor(message, details) {
+        super(message, 422, "SCHEMA_HAS_UNCHECKABLE_OPS", details);
+        this.name = "SchemaHasUncheckableOpsError";
+    }
+    get operations() {
+        const d = detailsRecord(this.details);
+        return Array.isArray(d?.operations) ? d.operations : [];
+    }
+}
+export class TomlParseError extends ApiError {
+    constructor(message, details) {
+        super(message, 400, "TOML_PARSE_ERROR", details);
+        this.name = "TomlParseError";
+    }
+    get line() {
+        const d = detailsRecord(this.details);
+        return typeof d?.line === "number" ? d.line : undefined;
+    }
+    get column() {
+        const d = detailsRecord(this.details);
+        return typeof d?.column === "number" ? d.column : undefined;
+    }
+}
+export class OpsExistError extends ApiError {
+    constructor(message, details) {
+        super(message, 409, "OPS_EXIST", details);
+        this.name = "OpsExistError";
+    }
+    get opCount() {
+        const d = detailsRecord(this.details);
+        return typeof d?.opCount === "number" ? d.opCount : 0;
+    }
+}
+/**
+ * Normalize a `databases operations execute` result to the CLI's one list
+ * envelope — but only when the result is a Durable Object query page
+ * (issue #2440).
+ *
+ * A registered operation is a list only sometimes. Of the shapes the server's
+ * operation dispatch can return, exactly two carry a top-level `data` array: a
+ * bare `query` and a `pipeline` whose `returnField` names a query step. A
+ * `count` (`{ count }`), an `aggregate` (`{ result }`), a mutation
+ * (`{ results }`), an `applyToQuery` (`{ matched, affected, failed, … }`) and a
+ * `returnField: "all"` pipeline (`{ steps: { … } }`) do not, so blanket
+ * normalization would corrupt them. This helper therefore tests the shape
+ * first and passes everything else through byte-for-byte — including the
+ * nested steps of a `returnField: "all"` pipeline, which are operation-defined
+ * objects the CLI must not reach into.
+ *
+ * Deliberately narrow, not a general-purpose predicate: the contract is
+ * specifically "an operations-execute result may be a DO query page".
+ * `executeDatabaseOperation()` is the only caller.
+ *
+ * The conversion itself is delegated to `normalizeCliListEnvelope()` so cursor
+ * handling, `prevCursor` dropping and `hasMore` derivation have exactly one
+ * implementation. That helper throws on an unrecognized shape — correct when
+ * the payload is supposed to be a list, wrong here, where the payload is the
+ * caller's own result — which is why the shape test has to run first. `_timing`
+ * (`--timing`) is re-attached afterwards, since it rides alongside the envelope
+ * rather than inside it.
+ */
+export function normalizeDatabaseOperationResult(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return raw;
+    const page = raw;
+    if (!Array.isArray(page.data))
+        return raw;
+    const envelope = normalizeCliListEnvelope(page);
+    if (page._timing !== undefined)
+        envelope._timing = page._timing;
+    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)) {
@@ -39,39 +269,27 @@ export class ApiClient {
         return this.credentials;
     }
     async refreshToken() {
-        if (!this.credentials?.refreshToken) {
-            throw new ApiError("No refresh token available. Please login again.", 401);
+        if (!this.credentials) {
+            throw new ApiError("Not logged in. Run 'primitive login' first.", 401);
         }
-        const url = `${this.credentials.serverUrl}/admin/api/auth/refresh`;
         try {
-            const headers = {
-                "Content-Type": "application/json",
-            };
-            if (this.credentials.globalAdminAppId) {
-                headers["X-Global-Admin-App-Id"] = this.credentials.globalAdminAppId;
-            }
-            const response = await fetchWithTLS(url, {
-                method: "POST",
-                headers,
-                body: JSON.stringify({ refreshToken: this.credentials.refreshToken }),
-            });
-            if (!response.ok) {
-                throw new ApiError("Token refresh failed. Please login again.", 401);
-            }
-            const data = await response.json();
-            // Update credentials with new tokens
-            this.credentials = {
-                ...this.credentials,
-                accessToken: data.accessToken || data.token,
-                refreshToken: data.refreshToken || this.credentials.refreshToken,
-                expiresAt: data.expiresAt,
-            };
+            const updated = await refreshAdminCredentials(this.credentials);
+            this.credentials = updated;
             saveCredentials(this.credentials);
         }
-        catch (error) {
-            if (error instanceof ApiError)
-                throw error;
-            throw new ApiError("Token refresh failed. Please login again.", 401);
+        catch (err) {
+            if (err instanceof RefreshError) {
+                // Preserve historical behavior: ApiClient surfaces refresh failures
+                // as 401s regardless of whether the underlying cause was a network
+                // 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.
+                // 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;
         }
     }
     async request(path, options = {}) {
@@ -92,20 +310,42 @@ export class ApiClient {
         });
         const text = await response.text();
         if (!response.ok) {
-            let errorData;
-            try {
-                errorData = JSON.parse(text);
+            const parsed = parseErrorResponse(response, text, path);
+            // Preserve the `<!DOCTYPE` → 404 ApiError shape (status forced to 404).
+            if (parsed.htmlNotFound) {
+                throw new ApiError(parsed.message, 404);
             }
-            catch {
-                if (text.includes("<!DOCTYPE")) {
-                    throw new ApiError(`API endpoint not found: ${path}. Make sure the server is running.`, 404);
-                }
-                errorData = { message: text || `HTTP ${response.status}` };
+            // Narrow details to the record shape for the issue #666 typed-exception
+            // dispatch below. Conflict metadata may live under `details.*` (canonical
+            // location per A1) or on the top-level envelope (legacy).
+            const detailsRecord = parsed.details && !Array.isArray(parsed.details)
+                ? parsed.details
+                : undefined;
+            const serverModifiedAt = detailsRecord?.serverModifiedAt ?? parsed.raw?.serverModifiedAt;
+            const expectedModifiedAt = detailsRecord?.expectedModifiedAt ?? parsed.raw?.expectedModifiedAt;
+            // Typed exceptions for the schema-feature (issue #666).
+            if (response.status === 409 && parsed.code === "CONFLICT") {
+                throw new ConflictError(parsed.message, serverModifiedAt, expectedModifiedAt, detailsRecord);
+            }
+            if (response.status === 409 && parsed.code === "OPS_EXIST") {
+                throw new OpsExistError(parsed.message, detailsRecord);
+            }
+            if (response.status === 400 && parsed.code === "TOML_PARSE_ERROR") {
+                throw new TomlParseError(parsed.message, detailsRecord);
             }
-            if (response.status === 409 && errorData?.code === "CONFLICT") {
-                throw new ConflictError(errorData.message || "Resource conflict", errorData.serverModifiedAt, errorData.expectedModifiedAt);
+            if (response.status === 422 && parsed.code === "SCHEMA_REQUIRED") {
+                throw new SchemaRequiredError(parsed.message, detailsRecord);
             }
-            throw new ApiError(errorData.message || `HTTP ${response.status}`, response.status, errorData.code);
+            if (response.status === 422 && parsed.code === "OPERATION_REFERENCES_UNDEFINED") {
+                throw new OperationRefError(parsed.message, detailsRecord);
+            }
+            if (response.status === 422 && parsed.code === "SCHEMA_BREAKS_OPERATIONS") {
+                throw new SchemaBreaksOpsError(parsed.message, detailsRecord);
+            }
+            if (response.status === 422 && parsed.code === "SCHEMA_HAS_UNCHECKABLE_OPS") {
+                throw new SchemaHasUncheckableOpsError(parsed.message, detailsRecord);
+            }
+            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
         }
         return text ? JSON.parse(text) : null;
     }
@@ -154,8 +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() {
-        return this.get("/admin/api/admins/me/apps");
+        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/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: rows.map((row) => ({
+                    appId: String(row.appId ?? row.id ?? ""),
+                    name: String(row.name ?? ""),
+                })),
+                nextCursor: resp.nextCursor ?? resp.cursor,
+            };
+        });
+        return drainAppsUntilConverged(drainOnce);
     }
     async createApp(data) {
         return this.post("/admin/api/apps", data);
@@ -181,12 +492,77 @@ export class ApiClient {
     async addUserByEmail(appId, data) {
         return this.post(`/admin/api/apps/${appId}/users/add-by-email`, data);
     }
-    async listUsers(appId) {
-        return this.get(`/app/${appId}/api/users`);
+    async mintTestJwt(appId, userId, role) {
+        return this.post(`/admin/api/apps/${appId}/users/${userId}/mint-test-jwt`, role ? { role } : {});
+    }
+    async rebuildUserSearchText(appId) {
+        return this.post(`/admin/api/apps/${appId}/users/rebuild-search-text`, {});
+    }
+    async listUsers(appId, params) {
+        const query = new URLSearchParams();
+        if (params?.name)
+            query.set("name", params.name);
+        if (params?.email)
+            query.set("email", params.email);
+        if (params?.userId)
+            query.set("userId", params.userId);
+        if (params?.limit)
+            query.set("limit", String(params.limit));
+        if (params?.cursor)
+            query.set("cursor", params.cursor);
+        const path = query.toString()
+            ? `/app/${appId}/api/users?${query.toString()}`
+            : `/app/${appId}/api/users`;
+        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}`);
     }
+    /**
+     * #2803 — take a user's access away, or give it back. Distinct from
+     * `removeUser`, which detaches the membership: this blocks the person's auth
+     * in the app, revokes their sessions and tokens, and is reversible. Both
+     * routes already existed; nothing on the CLI reached them.
+     */
+    async setUserAvailability(appId, userId, action) {
+        return this.put(`/admin/api/apps/${appId}/users/${userId}/${action}`, {});
+    }
+    // ============================================
+    // FEATURE FLAGS (super-admin)
+    // ============================================
+    /**
+     * #2803 — the platform's feature flags. A server-owned admin toggle with a
+     * console but, until now, no CLI: the same "one control, both surfaces" rule
+     * the carrying types get.
+     */
+    async listFeatureFlags() {
+        return this.get(`/admin/api/flags`);
+    }
+    /**
+     * The flag itself, not the `{ flag }` envelope the route answers with —
+     * `feature-flags get` prints the key, the enabled state and the per-app
+     * overrides, and reading them off the envelope printed a blank row.
+     */
+    async getFeatureFlag(flagKey) {
+        const result = await this.get(`/admin/api/flags/${flagKey}`);
+        return result?.flag ?? result;
+    }
+    /** Same envelope, same unwrap: `enable`/`disable` print the updated flag. */
+    async setFeatureFlagEnabled(flagKey, enabled) {
+        const result = await this.put(`/admin/api/flags/${flagKey}`, { enabled });
+        return result?.flag ?? result;
+    }
     async updateUserRole(appId, userId, role) {
         return this.put(`/app/${appId}/api/users/${userId}/role`, { role });
     }
@@ -196,14 +572,39 @@ export class ApiClient {
     async transferAdminOwnership(appId, adminId) {
         return this.post(`/admin/api/apps/${appId}/admins/transfer-ownership`, { adminId });
     }
+    // App-level console admin management
+    async listAppAdmins(appId) {
+        return this.get(`/admin/api/apps/${appId}/admins`);
+    }
+    async addAppAdmin(appId, data) {
+        return this.post(`/admin/api/apps/${appId}/admins`, data);
+    }
+    async removeAppAdmin(appId, adminId) {
+        return this.delete(`/admin/api/apps/${appId}/admins/${adminId}`);
+    }
+    async listAppAdminInvitations(appId) {
+        return this.get(`/admin/api/apps/${appId}/admin-invitations`);
+    }
+    async deleteAppAdminInvitation(appId, invitationId) {
+        return this.delete(`/admin/api/apps/${appId}/admin-invitations/${invitationId}`);
+    }
     async transferDocumentOwnership(appId, documentId, newOwnerId) {
         return this.post(`/app/${appId}/api/documents/${documentId}/permissions/transfer`, { newOwnerId });
     }
     // ============================================
     // INVITATIONS
     // ============================================
-    async listInvitations(appId) {
-        return this.get(`/app/${appId}/api/invitations`);
+    async listInvitations(appId, params) {
+        const result = await this.get(`/app/${appId}/api/invitations`, params);
+        // #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;
+        return {
+            items: result?.items ?? [],
+            nextCursor,
+            hasMore: result?.hasMore ?? nextCursor != null,
+            cursor: nextCursor,
+        };
     }
     async createInvitation(appId, data) {
         return this.post(`/app/${appId}/api/invitations`, data);
@@ -228,18 +629,47 @@ export class ApiClient {
         return this.delete(`/app/${appId}/api/waitlist/${waitlistId}`);
     }
     // ============================================
+    // DEFERRED GRANTS
+    // ============================================
+    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 {
+            items,
+            grants: items,
+            nextCursor: result?.nextCursor ?? null,
+            hasMore: result?.hasMore,
+        };
+    }
+    async revokeDeferredGrant(appId, deferredId, type) {
+        return this.delete(`/app/${appId}/api/deferred-grants/${deferredId}?type=${type}`);
+    }
+    // ============================================
     // INTEGRATIONS
     // ============================================
     async listIntegrations(appId, params) {
         const result = await this.get(`/admin/api/apps/${appId}/integrations`, params);
         return {
             items: result?.items ?? [],
+            hasMore: result?.hasMore,
             nextCursor: result?.nextCursor ?? null,
         };
     }
+    /** Integration detail (#2631: `accessRule` is on the detail, not the list summary). */
     async getIntegration(appId, integrationId) {
         return this.get(`/admin/api/apps/${appId}/integrations/${integrationId}`);
     }
+    /**
+     * An integration's named configs. Test cases pin a config by NAME so the
+     * sidecar is portable across apps (#2769); this is the map pull and push
+     * resolve that name through, the same way prompts/workflows/scripts do.
+     */
+    async listIntegrationConfigs(appId, integrationId) {
+        const result = await this.get(`/admin/api/apps/${appId}/integrations/${integrationId}/configs`);
+        return { items: result?.items ?? result ?? [] };
+    }
     async createIntegration(appId, payload) {
         return this.post(`/admin/api/apps/${appId}/integrations`, payload);
     }
@@ -247,8 +677,15 @@ export class ApiClient {
         const body = expectedModifiedAt ? { ...payload, expectedModifiedAt } : payload;
         return this.patch(`/admin/api/apps/${appId}/integrations/${integrationId}`, body);
     }
+    /**
+     * Delete an integration. Archives it by default; `{ hard: true }` destroys
+     * the row instead, which is what `config push --prune` passes (#2803) so a
+     * pruned integration stops holding its key. The positional boolean is still
+     * accepted for the existing callers.
+     */
     async deleteIntegration(appId, integrationId, hard) {
-        const path = hard
+        const isHard = typeof hard === "object" ? hard?.hard === true : hard === true;
+        const path = isHard
             ? `/admin/api/apps/${appId}/integrations/${integrationId}?hard=true`
             : `/admin/api/apps/${appId}/integrations/${integrationId}`;
         return this.delete(path);
@@ -260,17 +697,517 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/integrations/${integrationId}/logs`, params);
         return result?.items ?? [];
     }
-    async listIntegrationSecrets(appId, integrationId, params) {
-        const result = await this.get(`/admin/api/apps/${appId}/integrations/${integrationId}/secrets`, params);
+    async listWorkflowRunIntegrationLogs(appId, runId, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/workflows/runs/${runId}/integration-logs`, params);
         return result?.items ?? [];
     }
-    async addIntegrationSecret(appId, integrationId, payload) {
-        const result = await this.post(`/admin/api/apps/${appId}/integrations/${integrationId}/secrets`, payload);
-        return result?.secret ?? null;
+    // ============================================
+    // APP SECRETS
+    // ============================================
+    async listAppSecrets(appId) {
+        const result = await this.get(`/admin/api/apps/${appId}/secrets`);
+        return result?.items ?? [];
+    }
+    async createAppSecret(appId, payload) {
+        return this.post(`/admin/api/apps/${appId}/secrets`, payload);
+    }
+    async updateAppSecret(appId, secretId, payload) {
+        return this.put(`/admin/api/apps/${appId}/secrets/${secretId}`, payload);
+    }
+    async upsertAppSecret(appId, key, payload) {
+        return this.put(`/admin/api/apps/${appId}/secrets/by-key/${key}`, payload);
+    }
+    async deleteAppSecret(appId, secretId) {
+        return this.delete(`/admin/api/apps/${appId}/secrets/${secretId}`);
+    }
+    // ============================================
+    // APP CONFIG VARS (issue #1364 — non-secret twin of secrets)
+    // ============================================
+    async listAppConfigVars(appId) {
+        const result = await this.get(`/admin/api/apps/${appId}/vars`);
+        return result?.items ?? [];
+    }
+    async upsertAppConfigVar(appId, key, payload, expectedModifiedAt, options = {}) {
+        // Encode the key so a malformed one (e.g. containing "/") reaches the
+        // server's key validation (400) instead of producing a routing 404.
+        // `expectedModifiedAt` (issue #1423 review r-2 P1) is the optimistic-
+        // concurrency precondition for an UPDATE — the server rejects the write
+        // with a 409 CONFLICT (surfaced as `ConflictError`) if the var changed
+        // since it.
+        //
+        // `expectNotExists` (issue #1423 review r-3 P1a) is the create-only
+        // precondition. A create has no baseline timestamp to send, but without
+        // any precondition the by-key upsert silently overwrites a var created
+        // remotely since our snapshot. Setting `expectNotExists` makes the server
+        // 409 CONFLICT if the key already exists instead of overwriting it.
+        const body = { ...payload };
+        if (expectedModifiedAt !== undefined)
+            body.expectedModifiedAt = expectedModifiedAt;
+        if (options.expectNotExists)
+            body.expectNotExists = true;
+        return this.put(`/admin/api/apps/${appId}/vars/by-key/${encodeURIComponent(key)}`, body);
+    }
+    async deleteAppConfigVar(appId, key, expectedModifiedAt) {
+        // The DELETE carries the optimistic-concurrency precondition (issue #1423
+        // review r-2 P1) as a query param since it has no body; the server 409s
+        // (ConflictError) if the var was edited remotely since `expectedModifiedAt`.
+        let path = `/admin/api/apps/${appId}/vars/by-key/${encodeURIComponent(key)}`;
+        if (expectedModifiedAt !== undefined) {
+            path += `?expectedModifiedAt=${encodeURIComponent(expectedModifiedAt)}`;
+        }
+        return this.delete(path);
+    }
+    // ============================================
+    // WEBHOOKS
+    // ============================================
+    async listWebhooks(appId, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/webhooks`, params);
+        return {
+            items: result?.items ?? [],
+            hasMore: result?.hasMore,
+            nextCursor: result?.nextCursor ?? null,
+        };
+    }
+    async getWebhook(appId, webhookId) {
+        return this.get(`/admin/api/apps/${appId}/webhooks/${webhookId}`);
+    }
+    async createWebhook(appId, payload) {
+        return this.post(`/admin/api/apps/${appId}/webhooks`, payload);
+    }
+    async updateWebhook(appId, webhookId, payload, expectedModifiedAt) {
+        const body = expectedModifiedAt ? { ...payload, expectedModifiedAt } : payload;
+        return this.patch(`/admin/api/apps/${appId}/webhooks/${webhookId}`, body);
+    }
+    /**
+     * Delete a webhook. Archives it by default; `hard` hard-deletes the row
+     * instead (#2232), which is what frees a slot under the per-app webhook cap
+     * and releases the webhook key for reuse. Same `?hard=true` verb the admin
+     * integrations delete uses.
+     */
+    async deleteWebhook(appId, webhookId, options) {
+        const query = options?.hard ? "?hard=true" : "";
+        return this.delete(`/admin/api/apps/${appId}/webhooks/${webhookId}${query}`);
+    }
+    /**
+     * #2803 — the operational verb pair for a webhook. It posts to the
+     * enable/disable route rather than PATCHing `status`, which is server-owned
+     * and refused on every configuration write path.
+     */
+    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}`, {});
+    }
+    /** #2803 — the operational verb pair for an integration (admin API). */
+    async setIntegrationAvailability(appId, integrationId, action) {
+        return this.post(`/admin/api/apps/${appId}/integrations/${integrationId}/${action}`, {});
+    }
+    async rotateWebhookSecret(appId, webhookId, payload) {
+        return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/rotate-secret`, payload);
+    }
+    async listWebhookEvents(appId, webhookId, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/webhooks/${webhookId}/events`, params);
+        // #1316: prefer `nextCursor`; fall back to the deprecated `cursor` alias.
+        const nextCursor = result?.nextCursor ?? result?.cursor ?? null;
+        return {
+            items: result?.items ?? [],
+            hasMore: result?.hasMore ?? !!nextCursor,
+            nextCursor,
+            cursor: nextCursor,
+        };
+    }
+    // ============================================
+    // CONNECTIONS INSPECTION (#1968)
+    // ============================================
+    /**
+     * List the live connections the server believes exist for exactly one of a
+     * document, user, or database. Read-only inspection over admin-api. Rows are
+     * per-connection-×-subscription bindings, so `connectionId` is not unique
+     * across rows. `params` on a database-subscription row is caller-defined
+     * bound CEL input — typed `unknown`.
+     */
+    async listConnections(appId, selector, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/connections`, {
+            ...selector,
+            ...params,
+        });
+        return {
+            items: result?.items ?? [],
+            hasMore: result?.hasMore,
+            nextCursor: result?.nextCursor ?? null,
+        };
+    }
+    async listSessions(appId, userId, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/sessions`, {
+            userId,
+            ...params,
+        });
+        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 || {});
+    }
+    /**
+     * Run a webhook's configured verifier over headers and a body captured from
+     * a real delivery, and report whether that signature checks out (#2445).
+     *
+     * `headers` is sent as ordered `[name, value]` pairs so a capture carrying a
+     * field name on more than one line survives the round trip. Nothing is
+     * delivered: no delivery record, no workflow run.
+     */
+    async verifyWebhook(appId, webhookId, payload) {
+        return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/verify`, payload);
+    }
+    // ============================================
+    // NAMED LOCKS (#1518)
+    // ============================================
+    async listLocks(appId) {
+        const result = await this.get(`/app/${appId}/api/locks`);
+        return { locks: result?.locks ?? [] };
+    }
+    async getLockStatus(appId, key) {
+        return this.post(`/app/${appId}/api/locks/status`, { key });
+    }
+    /**
+     * #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`, {
+            key,
+            handle: { handleId },
+        });
+    }
+    // ============================================
+    // CRON TRIGGERS
+    // ============================================
+    async listCronTriggers(appId) {
+        const result = await this.get(`/app/${appId}/api/cron-triggers`);
+        return { items: result?.items ?? [] };
+    }
+    async getCronTrigger(appId, triggerId) {
+        return this.get(`/app/${appId}/api/cron-triggers/${triggerId}`);
+    }
+    async createCronTrigger(appId, payload) {
+        return this.post(`/app/${appId}/api/cron-triggers`, payload);
+    }
+    async updateCronTrigger(appId, triggerId, payload) {
+        return this.put(`/app/${appId}/api/cron-triggers/${triggerId}`, payload);
+    }
+    /**
+     * Retire a cron trigger. The default soft-deletes (writes the `archived`
+     * tombstone); `{ hard: true }` destroys the row, which is what
+     * `config push --prune` passes (#2803) so a pruned trigger stops consuming
+     * the per-app cap and holding its key.
+     */
+    async deleteCronTrigger(appId, triggerId, options = {}) {
+        const query = options.hard ? "?hard=true" : "";
+        return this.delete(`/app/${appId}/api/cron-triggers/${triggerId}${query}`);
+    }
+    async disableCronTrigger(appId, triggerId) {
+        return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/disable`, {});
+    }
+    async enableCronTrigger(appId, triggerId) {
+        return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/enable`, {});
+    }
+    async testCronTrigger(appId, triggerId) {
+        return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/test`, {});
+    }
+    // ============================================
+    // ITERATIONS (iterate-users introspection / reset — #1209)
+    // ============================================
+    async listIterations(appId) {
+        const result = await this.get(`/app/${appId}/api/iterations`);
+        return { items: result?.items ?? [] };
+    }
+    async getIteration(appId, iterationName) {
+        return this.get(`/app/${appId}/api/iterations/${encodeURIComponent(iterationName)}`);
+    }
+    async resetIteration(appId, iterationName) {
+        return this.post(`/app/${appId}/api/iterations/${encodeURIComponent(iterationName)}/reset`, {});
+    }
+    // ============================================
+    // RESOURCE METADATA (values — issue #1352)
+    // ============================================
+    async readResourceMetadata(appId, resourceType, resourceId, category) {
+        return this.get(`/app/${appId}/api/resources/${encodeURIComponent(resourceType)}/${encodeURIComponent(resourceId)}/metadata/${encodeURIComponent(category)}`);
+    }
+    async writeResourceMetadata(appId, resourceType, resourceId, category, data) {
+        return this.put(`/app/${appId}/api/resources/${encodeURIComponent(resourceType)}/${encodeURIComponent(resourceId)}/metadata/${encodeURIComponent(category)}`, { data });
+    }
+    async batchReadResourceMetadata(appId, requests) {
+        return this.post(`/app/${appId}/api/resources/metadata/batch`, {
+            requests,
+        });
     }
-    async archiveIntegrationSecret(appId, integrationId, secretId) {
-        return this.patch(`/admin/api/apps/${appId}/integrations/${integrationId}/secrets/${secretId}`, {
-            status: "inactive",
+    /**
+     * List every stored metadata category on one resource (issue #1402 — debug
+     * tooling). The CLI authenticates as a console admin, so the app-level
+     * owner/admin bypass returns every category regardless of its readRule.
+     */
+    async listResourceMetadata(appId, resourceType, resourceId) {
+        return this.get(`/app/${appId}/api/resources/${encodeURIComponent(resourceType)}/${encodeURIComponent(resourceId)}/metadata`);
+    }
+    /**
+     * Delete one resource's metadata for one category (issue #1402 — debug
+     * tooling). Idempotent: deleting an absent item succeeds with
+     * `deleted: false` rather than a 404.
+     */
+    async deleteResourceMetadata(appId, resourceType, resourceId, category) {
+        return this.delete(`/app/${appId}/api/resources/${encodeURIComponent(resourceType)}/${encodeURIComponent(resourceId)}/metadata/${encodeURIComponent(category)}`);
+    }
+    /**
+     * Reverse-resolve a resource by a category's unique metadata value (issue
+     * #2137). A miss is a success with `resourceId: null`, never an error. The
+     * CLI authenticates as a console admin, so the app-level owner/admin bypass
+     * skips readRule evaluation.
+     */
+    async resolveResourceMetadata(appId, resourceType, category, key, value) {
+        return this.post(`/app/${appId}/api/metadata/resolve`, {
+            resourceType,
+            category,
+            key,
+            value,
         });
     }
     // ============================================
@@ -280,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,
         };
     }
@@ -293,6 +1231,12 @@ export class ApiClient {
         const body = expectedModifiedAt ? { ...payload, expectedModifiedAt } : payload;
         return this.patch(`/admin/api/apps/${appId}/prompts/${promptId}`, body);
     }
+    /**
+     * Retire a prompt, or destroy it.
+     *
+     * `hard` was always sent by both first-party clients and always ignored by
+     * the server; #2887 made it mean something — the plain call now archives.
+     */
     async deletePrompt(appId, promptId, hard) {
         const path = hard
             ? `/admin/api/apps/${appId}/prompts/${promptId}?hard=true`
@@ -325,36 +1269,136 @@ export class ApiClient {
     async duplicatePromptConfig(appId, promptId, configId, payload) {
         return this.post(`/admin/api/apps/${appId}/prompts/${promptId}/configs/${configId}/duplicate`, payload || {});
     }
+    // ============================================
+    // SCRIPTS (Rhai transforms) — #1000 (prompt-model convergence)
+    // ============================================
+    //
+    // The `Script` model is the authoring surface for `script` workflow
+    // steps. A `Script` is a HEADER (name/description/activeConfigId); the
+    // Rhai body lives on versioned `ScriptConfig` rows resolved LIVE at run
+    // time. CLI `config push` reads `transforms/*.rhai` files and reconciles
+    // them: a new file → create script (mints a default config); a changed
+    // file → create a new config + activate it (zero fan-out — referencing
+    // workflows pick up the new body on their next run).
+    async listScripts(appId) {
+        const result = await this.get(`/admin/api/apps/${appId}/scripts`);
+        return { items: result?.items ?? [] };
+    }
+    async getScript(appId, scriptId) {
+        return this.get(`/admin/api/apps/${appId}/scripts/${scriptId}`);
+    }
+    /**
+     * List a script's versioned configs (the `ScriptConfig` rows). Each config
+     * is a distinct block version: `configId` is the stable version selector,
+     * `contentHash` is its content identity, and `status` reports whether it is
+     * `active`/`draft`/`archived`. The script header's `activeConfigId` names
+     * the live version. Used by `scripts configs list` and by the script test
+     * commands to run against a specific pinned version.
+     */
+    async listScriptConfigs(appId, scriptId) {
+        const result = await this.get(`/admin/api/apps/${appId}/scripts/${scriptId}/configs`);
+        return { items: result?.items ?? [] };
+    }
+    async createScript(appId, payload) {
+        // Mints the script header + a default `active` config carrying the body.
+        return this.post(`/admin/api/apps/${appId}/scripts`, payload);
+    }
+    /**
+     * Push a new body for an existing script by creating a new `ScriptConfig`
+     * and activating it (the prompt-model "edit → activate" flow). Referencing
+     * workflows pick up the new body on their next run with no fan-out. The
+     * config name is unique per script, so we mint a timestamped name.
+     */
+    async pushScriptBody(appId, scriptId, body, 
+    /**
+     * The active state the caller believes holds right now (#2731 B10).
+     * Creating an inactive config races nothing, so the guard sits on the
+     * ACTIVATION step: if the active config has moved since the caller read it,
+     * the server rejects with a 409 instead of overwriting a concurrent script
+     * change. It takes BOTH halves of "what is active", because a config's body
+     * can be edited in place without the active id changing — the id alone
+     * would let such an edit through. Omitted (e.g. `--force`) means activate
+     * unconditionally.
+     */
+    expectedActive) {
+        const configName = `sync-${Date.now()}`;
+        const config = await this.post(`/admin/api/apps/${appId}/scripts/${scriptId}/configs`, { configName, body });
+        const activateBody = {};
+        if (expectedActive?.configId) {
+            activateBody.expectedActiveConfigId = expectedActive.configId;
+        }
+        if (expectedActive?.modifiedAt) {
+            activateBody.expectedActiveModifiedAt = expectedActive.modifiedAt;
+        }
+        await this.post(`/admin/api/apps/${appId}/scripts/${scriptId}/configs/${config.configId}/activate`, activateBody);
+        return config;
+    }
+    /**
+     * Delete a script header (cascades its configs). `force` overrides the
+     * server's guard against deleting a script that an active workflow still
+     * references by name — without it the server answers 409.
+     */
+    async deleteScript(appId, scriptId, force) {
+        const path = force
+            ? `/admin/api/apps/${appId}/scripts/${scriptId}?force=true`
+            : `/admin/api/apps/${appId}/scripts/${scriptId}`;
+        return this.delete(path);
+    }
     async getPromptSchema(appId, promptId) {
         return this.get(`/admin/api/apps/${appId}/prompts/${promptId}/schema`);
     }
     // ============================================
     // BLOCK TEST CASES (Prompts, Integrations, Workflows)
     // ============================================
-    async listTestCases(appId, blockType, blockId) {
-        const result = await this.get(`/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/test-cases`);
-        return { items: result?.items ?? result ?? [] };
+    /**
+     * One page of a block's test cases. The endpoint paginates (default 50, cap
+     * 100) and reports `nextCursor`; callers that reconcile the sync tree must
+     * drain every page before deleting or classifying anything (#2769).
+     */
+    async listTestCases(appId, blockType, blockId, params = {}) {
+        const query = new URLSearchParams();
+        if (params.limit !== undefined)
+            query.set("limit", String(params.limit));
+        if (params.cursor)
+            query.set("cursor", params.cursor);
+        const suffix = query.toString() ? `?${query.toString()}` : "";
+        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,
+        };
     }
     async getTestCase(appId, blockType, blockId, testCaseId) {
         return this.get(`/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/test-cases/${testCaseId}`);
     }
     async createTestCase(appId, blockType, blockId, payload) {
-        // Server expects JSON strings for these fields
+        // #2769 — the JSON fields travel PARSED. The handler stringifies them for
+        // storage (`createBlockTestCase`) and `serializeBlockTestCase` parses them
+        // on the way back out, so a client that stringifies first stores a JSON
+        // string of a JSON string and reads back a quoted blob.
         const serverPayload = {
             name: payload.name,
-            inputVariables: JSON.stringify(payload.inputVariables),
+            inputVariables: payload.inputVariables,
             configId: payload.configId,
             evaluatorPromptId: payload.evaluatorPromptId,
             evaluatorConfigId: payload.evaluatorConfigId,
         };
+        // #2896 — only when the caller has one: an older server rejects the key
+        // outright, and push reads that 400 to learn what it is talking to.
+        if (payload.key !== undefined)
+            serverPayload.key = payload.key;
+        if (payload.description !== undefined) {
+            serverPayload.description = payload.description;
+        }
         if (payload.expectedOutputPattern) {
             serverPayload.expectedOutputPattern = payload.expectedOutputPattern;
         }
         if (payload.expectedOutputContains) {
-            serverPayload.expectedOutputContains = JSON.stringify(payload.expectedOutputContains);
+            serverPayload.expectedOutputContains = payload.expectedOutputContains;
         }
         if (payload.expectedJsonSubset) {
-            serverPayload.expectedJsonSubset = JSON.stringify(payload.expectedJsonSubset);
+            serverPayload.expectedJsonSubset = payload.expectedJsonSubset;
         }
         return this.post(`/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/test-cases`, serverPayload);
     }
@@ -362,21 +1406,23 @@ export class ApiClient {
         const serverPayload = {};
         if (payload.name !== undefined)
             serverPayload.name = payload.name;
+        if (payload.description !== undefined) {
+            serverPayload.description = payload.description;
+        }
+        // #2769 — parsed on the wire (see `createTestCase`), and an explicit `null`
+        // is how the authored file clears a field: the handler only touches keys
+        // that are present, so an omitted key retains the previous value.
         if (payload.inputVariables !== undefined) {
-            serverPayload.inputVariables = JSON.stringify(payload.inputVariables);
+            serverPayload.inputVariables = payload.inputVariables;
         }
         if (payload.expectedOutputPattern !== undefined) {
             serverPayload.expectedOutputPattern = payload.expectedOutputPattern;
         }
         if (payload.expectedOutputContains !== undefined) {
-            serverPayload.expectedOutputContains = payload.expectedOutputContains
-                ? JSON.stringify(payload.expectedOutputContains)
-                : null;
+            serverPayload.expectedOutputContains = payload.expectedOutputContains;
         }
         if (payload.expectedJsonSubset !== undefined) {
-            serverPayload.expectedJsonSubset = payload.expectedJsonSubset
-                ? JSON.stringify(payload.expectedJsonSubset)
-                : null;
+            serverPayload.expectedJsonSubset = payload.expectedJsonSubset;
         }
         if (payload.configId !== undefined)
             serverPayload.configId = payload.configId;
@@ -386,6 +1432,8 @@ export class ApiClient {
         if (payload.evaluatorConfigId !== undefined) {
             serverPayload.evaluatorConfigId = payload.evaluatorConfigId;
         }
+        if (payload.key !== undefined)
+            serverPayload.key = payload.key;
         return this.patch(`/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/test-cases/${testCaseId}`, serverPayload);
     }
     async deleteTestCase(appId, blockType, blockId, testCaseId) {
@@ -415,14 +1463,8 @@ export class ApiClient {
         });
         const text = await response.text();
         if (!response.ok) {
-            let errorData;
-            try {
-                errorData = JSON.parse(text);
-            }
-            catch {
-                errorData = { message: text || `HTTP ${response.status}` };
-            }
-            throw new ApiError(errorData.message || `HTTP ${response.status}`, response.status, errorData.code);
+            const parsed = parseErrorResponse(response, text, url);
+            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
         }
         return text ? JSON.parse(text) : null;
     }
@@ -442,14 +1484,8 @@ export class ApiClient {
         });
         if (!response.ok) {
             const text = await response.text();
-            let errorData;
-            try {
-                errorData = JSON.parse(text);
-            }
-            catch {
-                errorData = { message: text || `HTTP ${response.status}` };
-            }
-            throw new ApiError(errorData.message || `HTTP ${response.status}`, response.status, errorData.code);
+            const parsed = parseErrorResponse(response, text, url);
+            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
         }
         const arrayBuffer = await response.arrayBuffer();
         return {
@@ -481,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);
     }
@@ -494,15 +1541,33 @@ export class ApiClient {
         const body = expectedModifiedAt ? { ...payload, expectedModifiedAt } : payload;
         return this.patch(`/admin/api/apps/${appId}/workflows/${workflowId}`, body);
     }
-    async deleteWorkflow(appId, workflowId) {
-        return this.delete(`/admin/api/apps/${appId}/workflows/${workflowId}`);
+    /**
+     * Retire a workflow, or destroy it (#2887).
+     *
+     * The plain call ARCHIVES: the definition row stays, so its runs, revisions
+     * and test cases keep resolving. `{ hard: true }` performs the full cascade
+     * and is what releases the `workflowKey` — the flag `config push --prune`
+     * sends, for the same reason it sends it for webhooks and integrations.
+     */
+    async deleteWorkflow(appId, workflowId, options) {
+        const path = `/admin/api/apps/${appId}/workflows/${workflowId}`;
+        return this.delete(options?.hard ? `${path}?hard=true` : path);
+    }
+    /**
+     * #2645 criterion 9 — the operational toggle. Deliberately NOT the config
+     * PATCH: `config push` owns every configuration field, and taking a workflow
+     * out of service must not touch one, or an operator's action would show up as
+     * drift against the repo. Same route shape as `cron-triggers pause|resume`.
+     */
+    async disableWorkflow(appId, workflowId) {
+        return this.post(`/app/${appId}/api/workflows/${workflowId}/disable`, {});
+    }
+    async enableWorkflow(appId, workflowId) {
+        return this.post(`/app/${appId}/api/workflows/${workflowId}/enable`, {});
     }
     async updateWorkflowDraft(appId, workflowId, payload) {
         return this.put(`/admin/api/apps/${appId}/workflows/${workflowId}/draft`, payload);
     }
-    async publishWorkflow(appId, workflowId) {
-        return this.post(`/admin/api/apps/${appId}/workflows/${workflowId}/publish`, {});
-    }
     async previewWorkflow(appId, workflowId, payload) {
         return this.post(`/admin/api/apps/${appId}/workflows/${workflowId}/preview`, payload);
     }
@@ -511,14 +1576,43 @@ export class ApiClient {
     }
     async listWorkflowRuns(appId, workflowId, params) {
         const result = await this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/runs`, params);
+        // #1316: prefer `nextCursor`; fall back to the deprecated `cursor` alias.
+        const nextCursor = result?.nextCursor ?? result?.cursor ?? null;
         return {
             items: result?.items ?? [],
-            cursor: result?.cursor ?? null,
+            hasMore: result?.hasMore,
+            nextCursor,
+            cursor: nextCursor,
+            resumeAfter: result?.resumeAfter,
+            scanned: typeof result?.scanned === "number" ? result.scanned : undefined,
+        };
+    }
+    /**
+     * Workflow runs started by one app user, across every workflow (#1967).
+     * Backed by `GET /admin/api/apps/{appId}/users/{userId}/workflow-runs`,
+     * which resolves the app user before querying the `runsByUser` index.
+     */
+    async listUserWorkflowRuns(appId, userId, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/users/${encodeURIComponent(userId)}/workflow-runs`, params);
+        const nextCursor = result?.nextCursor ?? result?.cursor ?? null;
+        return {
+            items: result?.items ?? [],
+            hasMore: result?.hasMore,
+            nextCursor,
+            cursor: nextCursor,
+            scanned: typeof result?.scanned === "number" ? result.scanned : undefined,
         };
     }
     async getWorkflowRunStatus(appId, workflowId, runId) {
         return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/runs/${runId}/status`);
     }
+    async getWorkflowStepRuns(appId, workflowId, runId) {
+        const result = await this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/runs/${runId}/steps`);
+        return { items: result?.items ?? [] };
+    }
+    // Workflow analytics have one client path, `getAnalyticsTopWorkflows`
+    // (issue #2766): `getTopWorkflows` was a second name for the same endpoint,
+    // and `getWorkflowAnalytics` called a route the server never registered.
     // ============================================
     // WORKFLOW CONFIGURATIONS
     // ============================================
@@ -547,29 +1641,83 @@ export class ApiClient {
     // ============================================
     // ANALYTICS
     // ============================================
-    async getAnalyticsOverview(appId, params) {
-        return this.get(`/app/${appId}/api/analytics/overview`, params);
-    }
     async getAnalyticsTopUsers(appId, params) {
         return this.get(`/app/${appId}/api/analytics/users/top`, params);
     }
-    async getAnalyticsUserTimeline(appId, userUlid, params) {
-        return this.get(`/app/${appId}/api/analytics/users/${userUlid}/timeline`, params);
-    }
-    async getAnalyticsUserEvents(appId, userUlid, params) {
-        return this.get(`/app/${appId}/api/analytics/users/${userUlid}/events`, params);
-    }
     async getAnalyticsIntegrationMetrics(appId, params) {
         return this.get(`/app/${appId}/api/analytics/integrations`, params);
     }
+    async getAnalyticsOverviewDau(appId) {
+        return this.get(`/app/${appId}/api/analytics/overview/dau`);
+    }
+    async getAnalyticsOverviewWau(appId) {
+        return this.get(`/app/${appId}/api/analytics/overview/wau`);
+    }
+    async getAnalyticsOverviewMau(appId) {
+        return this.get(`/app/${appId}/api/analytics/overview/mau`);
+    }
+    async getAnalyticsOverviewGrowth(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/overview/growth`, params);
+    }
+    async getAnalyticsDailyActive(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/daily-active`, params);
+    }
+    async getAnalyticsRollingActive(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/rolling-active`, params);
+    }
+    async getAnalyticsCohortRetention(appId) {
+        return this.get(`/app/${appId}/api/analytics/cohort-retention`);
+    }
+    async getAnalyticsUserSearch(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/users/search`, params);
+    }
+    async getAnalyticsUserDetail(appId, userUlid) {
+        return this.get(`/app/${appId}/api/analytics/users/${userUlid}/detail`);
+    }
+    async getAnalyticsUserSnapshot(appId, userUlid) {
+        return this.get(`/app/${appId}/api/analytics/users/${userUlid}/snapshot`);
+    }
+    async getAnalyticsEvents(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/events`, params);
+    }
+    async getAnalyticsEventsGrouped(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/events/grouped`, params);
+    }
+    async getAnalyticsErrorsGroups(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/errors/groups`, params);
+    }
+    async getAnalyticsTopWorkflows(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/workflows/top`, params);
+    }
+    async getAnalyticsTopPrompts(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/prompts/top`, params);
+    }
     // ============================================
     // 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 ?? [],
-            cursor: result?.cursor ?? null,
+            // `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,
         };
     }
     async searchAdminByEmail(email) {
@@ -602,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,
         };
     }
@@ -621,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,
         };
     }
@@ -637,21 +1787,6 @@ export class ApiClient {
         return this.delete(`/admin/api/catalog/integrations/${catalogId}`);
     }
     // ============================================
-    // LLM UTILITIES
-    // ============================================
-    async listLlmModels(provider = "openrouter") {
-        return this.get("/admin/api/llm/models", { provider });
-    }
-    async generatePrompt(payload) {
-        return this.post("/admin/api/llm/generate-prompt", payload);
-    }
-    async generateEvaluator(payload) {
-        return this.post("/admin/api/llm/generate-evaluator", payload);
-    }
-    async generateWorkflowEvaluator(payload) {
-        return this.post("/admin/api/llm/generate-evaluator-workflow", payload);
-    }
-    // ============================================
     // BATCH TEST EXECUTION
     // ============================================
     async startBatchTests(appId, blockType, blockId, payload) {
@@ -670,6 +1805,33 @@ export class ApiClient {
         return this.get(`/admin/api/apps/${appId}/comparisons/${group}`);
     }
     // ============================================
+    // EMAIL TEMPLATES
+    // ============================================
+    async listEmailTemplates(appId) {
+        return this.get(`/admin/api/apps/${appId}/email-templates`);
+    }
+    async getEmailTemplate(appId, emailType) {
+        return this.get(`/admin/api/apps/${appId}/email-templates/${emailType}`);
+    }
+    /**
+     * Create or replace an email-template override.
+     *
+     * `expectedModifiedAt` is the optimistic-concurrency token every sibling
+     * config endpoint already takes (#2731 B10). Optional and additive: when
+     * omitted the write is unconditional, which is how `--force` and every
+     * pre-existing caller keep working; when supplied and stale, the server
+     * answers 409 rather than silently overwriting a concurrent edit.
+     */
+    async upsertEmailTemplate(appId, emailType, payload, expectedModifiedAt) {
+        return this.put(`/admin/api/apps/${appId}/email-templates/${emailType}`, expectedModifiedAt ? { ...payload, expectedModifiedAt } : payload);
+    }
+    async deleteEmailTemplate(appId, emailType) {
+        return this.delete(`/admin/api/apps/${appId}/email-templates/${emailType}`);
+    }
+    async testEmailTemplate(appId, emailType, payload) {
+        return this.post(`/admin/api/apps/${appId}/email-templates/${emailType}/test`, payload || {});
+    }
+    // ============================================
     // ACCESS TOKENS
     // ============================================
     async createToken(appId, data) {
@@ -688,8 +1850,54 @@ export class ApiClient {
     // ============================================
     // DATABASES
     // ============================================
-    async listDatabases(appId) {
-        return this.get(`/app/${appId}/api/databases`);
+    /**
+     * List an app's databases, following the cursor to the end.
+     *
+     * The endpoint returns the `{ items, hasMore, nextCursor }` envelope and
+     * caps a page at 100 (#1958), so `databases list` needs the follow-up pages
+     * to show every database. `paginateAll` carries the repeat-cursor and
+     * max-page guards, so a server that hands out a non-advancing cursor fails
+     * loudly instead of looping forever.
+     *
+     * `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) {
+        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);
@@ -703,29 +1911,65 @@ export class ApiClient {
     async deleteDatabase(appId, databaseId) {
         return this.delete(`/app/${appId}/api/databases/${databaseId}`);
     }
+    /**
+     * Read a database's CEL context dict.
+     *
+     * 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).
+     *
+     * @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 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 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);
+    }
     // ============================================
     // DATABASE PERMISSIONS
     // ============================================
     async listDatabasePermissions(appId, databaseId) {
         return this.get(`/app/${appId}/api/databases/${databaseId}/permissions`);
     }
-    async grantDatabasePermission(appId, databaseId, data) {
-        return this.put(`/app/${appId}/api/databases/${databaseId}/permissions`, data);
+    async addDatabaseManager(appId, databaseId, userId) {
+        return this.put(`/app/${appId}/api/databases/${databaseId}/permissions`, {
+            userId,
+            permission: "manager",
+        });
     }
-    async revokeDatabasePermission(appId, databaseId, userId) {
+    async removeDatabaseManager(appId, databaseId, userId) {
         return this.delete(`/app/${appId}/api/databases/${databaseId}/permissions/${userId}`);
     }
-    // ============================================
-    // DATABASE GROUP PERMISSIONS
-    // ============================================
-    async listDatabaseGroupPermissions(appId, databaseId) {
-        return this.get(`/app/${appId}/api/databases/${databaseId}/group-permissions`);
-    }
-    async grantDatabaseGroupPermission(appId, databaseId, data) {
-        return this.post(`/app/${appId}/api/databases/${databaseId}/group-permissions`, data);
+    /** @deprecated Use {@link addDatabaseManager} instead. */
+    async grantDatabasePermission(appId, databaseId, data) {
+        return this.addDatabaseManager(appId, databaseId, data.userId);
     }
-    async revokeDatabaseGroupPermission(appId, databaseId, groupType, groupId) {
-        return this.delete(`/app/${appId}/api/databases/${databaseId}/group-permissions/${groupType}/${groupId}`);
+    /** @deprecated Use {@link removeDatabaseManager} instead. */
+    async revokeDatabasePermission(appId, databaseId, userId) {
+        return this.delete(`/app/${appId}/api/databases/${databaseId}/permissions/${userId}`);
     }
     // ============================================
     // DATABASE RECORDS & SCHEMA
@@ -736,17 +1980,140 @@ export class ApiClient {
     async describeDatabaseModel(appId, databaseId, modelName) {
         return this.get(`/app/${appId}/api/databases/${databaseId}/records/describe`, { modelName });
     }
-    async queryDatabaseRecords(appId, databaseId, data) {
-        return this.post(`/app/${appId}/api/databases/${databaseId}/records/query`, data);
-    }
-    async saveDatabaseRecord(appId, databaseId, data) {
-        return this.post(`/app/${appId}/api/databases/${databaseId}/records/save`, data);
+    /**
+     * Query records in a database model. The Durable Object answers with its own
+     * `{ data, hasMore, nextCursor?, prevCursor? }` envelope; that wire shape is
+     * shared with the JS client, the Swift client and web-admin, so the CLI
+     * normalizes it at its own boundary instead (issue #2357) and hands callers
+     * the same `{ items, hasMore, nextCursor? }` envelope as
+     * {@link queryDocumentRecords}.
+     */
+    async queryDatabaseRecords(appId, databaseId, modelName, queryOptions) {
+        const body = { modelName };
+        if (queryOptions?.filter)
+            body.filter = queryOptions.filter;
+        const options = {};
+        if (queryOptions?.limit)
+            options.limit = queryOptions.limit;
+        if (queryOptions?.cursor)
+            options.uniqueStartKey = queryOptions.cursor;
+        if (Object.keys(options).length > 0)
+            body.options = options;
+        const raw = await this.post(`/app/${appId}/api/databases/${databaseId}/records/query`, body);
+        return normalizeCliListEnvelope(raw);
+    }
+    async countDatabaseRecords(appId, databaseId, modelName, filter) {
+        const body = { modelName };
+        if (filter)
+            body.filter = filter;
+        return this.post(`/app/${appId}/api/databases/${databaseId}/records/count`, body);
+    }
+    async aggregateDatabaseRecords(appId, databaseId, modelName, options) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/records/aggregate`, {
+            modelName,
+            options,
+        });
     }
-    async deleteDatabaseRecord(appId, databaseId, data) {
-        return this.post(`/app/${appId}/api/databases/${databaseId}/records/delete`, data);
+    /**
+     * Upsert one record via `records/save`: creates the record when the id is
+     * new, and merges the supplied fields into it when it already exists (the DO
+     * writes with `ON CONFLICT … json_patch`, so fields you leave out survive).
+     * `patchDatabaseRecord` is the same merge but requires the record to exist.
+     *
+     * `id` is optional: when omitted the body carries no `id`, which the
+     * DatabaseDO only accepts alongside an `upsertOn` field — callers that want a
+     * plain create must supply an id themselves (`databases records save` mints a
+     * ULID, matching the CSV import path).
+     *
+     * Returns the endpoint's flat `{ success, id, appliedFields }` — not the
+     * saved record.
+     */
+    async saveDatabaseRecord(appId, databaseId, modelName, id, data) {
+        const body = { modelName, data };
+        if (id !== undefined)
+            body.id = id;
+        return this.post(`/app/${appId}/api/databases/${databaseId}/records/save`, body);
+    }
+    /**
+     * Merge the supplied fields into an existing record via `records/patch`.
+     *
+     * Fields absent from `data` are left as they are. Unlike `saveDatabaseRecord`
+     * the record must already exist — the DatabaseDO answers 404 for an unknown
+     * id rather than creating one. Returns the flat
+     * `{ success, id, appliedFields }`.
+     */
+    async patchDatabaseRecord(appId, databaseId, modelName, id, data) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/records/patch`, {
+            modelName,
+            id,
+            data,
+        });
     }
-    async countDatabaseRecords(appId, databaseId, data) {
-        return this.post(`/app/${appId}/api/databases/${databaseId}/records/count`, data);
+    // ============================================
+    // DATABASE OPERATIONS (registered operations)
+    // ============================================
+    async listDatabaseOperations(appId, databaseId) {
+        return this.get(`/app/${appId}/api/databases/${databaseId}/operations`);
+    }
+    /**
+     * Execute a registered operation and, when the result is a query page,
+     * normalize it to the CLI's one list envelope (issue #2440).
+     *
+     * The registered operation decides the response shape, so the normalization
+     * is conditional — see {@link normalizeDatabaseOperationResult}. Everything
+     * else (a `count`, an `aggregate`, a mutation, a `returnField: "all"`
+     * pipeline) is returned exactly as the server sent it.
+     */
+    async executeDatabaseOperation(appId, databaseId, operationName, data, token, options) {
+        const path = `/app/${appId}/api/databases/${databaseId}/operations/${encodeURIComponent(operationName)}/execute`;
+        const extraHeaders = {};
+        if (options?.timing) {
+            extraHeaders["X-Timing"] = "true";
+        }
+        if (token) {
+            return normalizeDatabaseOperationResult(await this.requestWithToken(path, token, {
+                method: "POST",
+                body: JSON.stringify(data || {}),
+                headers: extraHeaders,
+            }));
+        }
+        return normalizeDatabaseOperationResult(await this.request(path, {
+            method: "POST",
+            body: JSON.stringify(data || {}),
+            headers: extraHeaders,
+        }));
+    }
+    /**
+     * Execute a registered batch (bulk) database operation. Posts a chunk of
+     * items to the canonical `operations/:name/batch` endpoint (the same one the
+     * client library's `executeBatch` uses — NOT the deprecated `import-bulk`
+     * alias). Used by `databases import-csv`.
+     *
+     * @returns `{ imported, failed }` — DO-level write outcome counts. Per-item
+     *   validation/access failures abort the whole chunk with a 4xx (thrown).
+     */
+    async executeBatch(appId, databaseId, operationName, batch) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/operations/${encodeURIComponent(operationName)}/batch`, { batch });
+    }
+    /**
+     * Make a request using a specific JWT token instead of the CLI's credentials.
+     * Used for executing operations as a different user.
+     */
+    async requestWithToken(path, token, options = {}) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}${path}`;
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            ...(options.headers || {}),
+        };
+        const response = await fetchWithTLS(url, { ...options, headers });
+        const text = await response.text();
+        if (!response.ok) {
+            const parsed = parseErrorResponse(response, text, path);
+            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
+        }
+        return text ? JSON.parse(text) : null;
     }
     // ============================================
     // DATABASE INDEXES
@@ -760,11 +2127,160 @@ export class ApiClient {
     async dropDatabaseIndex(appId, databaseId, data) {
         return this.post(`/app/${appId}/api/databases/${databaseId}/records/index/drop`, data);
     }
+    /**
+     * Issue #974: back-provision an existing database instance's schema-declared
+     * unique indexes by reading its type schema and registering any declared-but-
+     * missing unique index. Idempotent.
+     */
+    async reindexDatabaseFromSchema(appId, databaseId) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/reindex`, {});
+    }
+    // ============================================
+    // DATABASE TYPE CONFIGS
+    // ============================================
+    async listDatabaseTypeConfigs(appId) {
+        return this.get(`/app/${appId}/api/databases/types`);
+    }
+    async getDatabaseTypeConfig(appId, databaseType) {
+        return this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}`);
+    }
+    async createDatabaseTypeConfig(appId, data, 
+    // Issue #1336 (codex round-1 P2): `dryRun` runs every create-time
+    // validation (inline CEL rule lint, manifest shape, schema TOML parse)
+    // WITHOUT persisting, so a fresh-type `config push --dry-run` surfaces a
+    // malformed `defaultAccess`/manifest the same way the real POST would.
+    options) {
+        const query = options?.dryRun ? "?dryRun=true" : "";
+        return this.post(`/app/${appId}/api/databases/types${query}`, data);
+    }
+    async updateDatabaseTypeConfig(appId, databaseType, data, expectedModifiedAt, options) {
+        const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
+        const qs = new URLSearchParams();
+        if (options?.dryRun)
+            qs.set("dryRun", "true");
+        if (options?.acceptWarnings)
+            qs.set("acceptWarnings", "true");
+        const query = qs.toString();
+        const path = `/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}${query ? `?${query}` : ""}`;
+        return this.patch(path, body);
+    }
+    async deleteDatabaseTypeConfig(appId, databaseType, options) {
+        const query = options?.force ? "?force=true" : "";
+        return this.delete(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}${query}`);
+    }
+    /**
+     * Issue #666 Phase 3: ask the server to scaffold a TOML schema from
+     * existing ops + DO field introspection. Read-only — does NOT persist.
+     */
+    async scaffoldDatabaseTypeSchema(appId, databaseType) {
+        return this.post(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/schema:scaffold`, {});
+    }
+    // ============================================
+    // DATABASE TYPE OPERATIONS
+    // ============================================
+    async listDatabaseTypeOperations(appId, databaseType) {
+        return this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations`);
+    }
+    async getDatabaseTypeOperation(appId, databaseType, name) {
+        return this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations/${encodeURIComponent(name)}`);
+    }
+    async createDatabaseTypeOperation(appId, databaseType, data, 
+    // Issue #813 (1A): when `dryRun` is set the server runs the op-edit gate
+    // without persisting — used by `config push --dry-run` to surface gate
+    // failures the real push would hit. `schemaOverride` lets the gate run
+    // against the schema the SAME push is about to land (so an op that depends
+    // on a new field isn't falsely rejected against the stale stored schema).
+    //
+    // Issue #915 (defect a, follow-up): for a FRESH db-type the parent config
+    // does not exist on the server yet, so the server's "access required"
+    // check has no `defaultAccess` to fall back on. Thread the TOML-declared
+    // type-level `defaultAccess` so an op that omits `access` (intending to
+    // inherit it after the type is created) isn't falsely rejected during the
+    // dry-run. Server only trusts this on the fresh-type dry-run path.
+    options) {
+        const query = options?.dryRun ? "?dryRun=true" : "";
+        let body = data;
+        if (options?.dryRun && options.schemaOverride !== undefined) {
+            body = { ...body, schemaOverride: options.schemaOverride };
+        }
+        if (options?.dryRun && options.defaultAccess !== undefined) {
+            body = { ...body, defaultAccess: options.defaultAccess };
+        }
+        if (options?.dryRun && options.metadataManifestOverride !== undefined) {
+            body = { ...body, metadataManifestOverride: options.metadataManifestOverride };
+        }
+        return this.post(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations${query}`, body);
+    }
+    async updateDatabaseTypeOperation(appId, databaseType, name, data, expectedModifiedAt, 
+    // Issue #813 (1A): dry-run runs the op-edit gate without persisting.
+    // `schemaOverride` gates against the schema the same push is landing.
+    // Issue #1336: `metadataManifestOverride` gates the op-access lint against
+    // the manifest the same push is landing (see `createDatabaseTypeOperation`).
+    options) {
+        let body = expectedModifiedAt ? { ...data, expectedModifiedAt } : { ...data };
+        if (options?.dryRun && options.schemaOverride !== undefined) {
+            body = { ...body, schemaOverride: options.schemaOverride };
+        }
+        if (options?.dryRun && options.metadataManifestOverride !== undefined) {
+            body = { ...body, metadataManifestOverride: options.metadataManifestOverride };
+        }
+        const query = options?.dryRun ? "?dryRun=true" : "";
+        return this.patch(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations/${encodeURIComponent(name)}${query}`, body);
+    }
+    async deleteDatabaseTypeOperation(appId, databaseType, name) {
+        return this.delete(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations/${encodeURIComponent(name)}`);
+    }
+    // ============================================
+    // DATABASE TYPE SUBSCRIPTIONS (#740 / #803)
+    // ============================================
+    //
+    // Transparent passthroughs against the server's type-scoped subscription
+    // routes (GET/POST/PUT/DELETE `/databases/types/:type/subscriptions[/:key]`).
+    // The wire format is authoritative in the controller
+    // (`database-type-subscriptions-controller.ts`): create requires
+    // `subscriptionKey`, `displayName`, `modelName`, `filter` (CEL), `access`
+    // (CEL); optional `description`, `select` (string[]), `emit`
+    // (enter/update/leave subset), `params` (object, ≤5 entries), `status`.
+    //
+    // The list endpoint wraps results in `{ items: [...] }` (unlike operations,
+    // which returns a bare array). We unwrap here so callers get an array,
+    // matching `listDatabaseTypeOperations`.
+    async listDatabaseTypeSubscriptions(appId, databaseType) {
+        const result = await this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions`);
+        if (Array.isArray(result))
+            return result;
+        return Array.isArray(result?.items) ? result.items : [];
+    }
+    async getDatabaseTypeSubscription(appId, databaseType, subscriptionKey) {
+        return this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions/${encodeURIComponent(subscriptionKey)}`);
+    }
+    async createDatabaseTypeSubscription(appId, databaseType, data) {
+        return this.post(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions`, data);
+    }
+    async updateDatabaseTypeSubscription(appId, databaseType, subscriptionKey, data, 
+    // #2731 B10 — optimistic concurrency, as the sibling operation update has
+    // had. Omitted (by `--force`, and by every caller predating it) means the
+    // write stays unconditional.
+    expectedModifiedAt) {
+        return this.put(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions/${encodeURIComponent(subscriptionKey)}`, expectedModifiedAt ? { ...data, expectedModifiedAt } : data);
+    }
+    async deleteDatabaseTypeSubscription(appId, databaseType, subscriptionKey) {
+        return this.delete(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions/${encodeURIComponent(subscriptionKey)}`);
+    }
     // ============================================
     // GROUPS
     // ============================================
     async listGroups(appId, params) {
-        return this.get(`/app/${appId}/api/groups`, params);
+        const result = await this.get(`/app/${appId}/api/groups`, params);
+        // #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;
+        return {
+            items: result?.items ?? [],
+            nextCursor,
+            hasMore: result?.hasMore ?? nextCursor != null,
+            cursor: nextCursor,
+        };
     }
     async createGroup(appId, data) {
         return this.post(`/app/${appId}/api/groups`, data);
@@ -781,8 +2297,29 @@ export class ApiClient {
     // ============================================
     // GROUP MEMBERS
     // ============================================
-    async listGroupMembers(appId, groupType, groupId) {
-        return this.get(`/app/${appId}/api/groups/${groupType}/${groupId}/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 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;
+        return {
+            items: result?.items ?? [],
+            nextCursor,
+            hasMore: result?.hasMore ?? nextCursor != null,
+            cursor: nextCursor,
+        };
     }
     async addGroupMember(appId, groupType, groupId, data) {
         return this.post(`/app/${appId}/api/groups/${groupType}/${groupId}/members`, data);
@@ -790,18 +2327,12 @@ export class ApiClient {
     async removeGroupMember(appId, groupType, groupId, userId) {
         return this.delete(`/app/${appId}/api/groups/${groupType}/${groupId}/members/${userId}`);
     }
-    async updateGroupMemberRole(appId, groupType, groupId, userId, data) {
-        return this.patch(`/app/${appId}/api/groups/${groupType}/${groupId}/members/${userId}`, data);
-    }
     // ============================================
     // GROUP RESOURCE LISTINGS
     // ============================================
     async listGroupDocuments(appId, groupType, groupId) {
         return this.get(`/app/${appId}/api/groups/${groupType}/${groupId}/documents`);
     }
-    async listGroupDatabases(appId, groupType, groupId) {
-        return this.get(`/app/${appId}/api/groups/${groupType}/${groupId}/databases`);
-    }
     // ============================================
     // USER MEMBERSHIPS
     // ============================================
@@ -821,6 +2352,159 @@ export class ApiClient {
         return this.delete(`/app/${appId}/api/documents/${documentId}/group-permissions/${groupType}/${groupId}`);
     }
     // ============================================
+    // COLLECTIONS
+    // ============================================
+    async listCollections(appId, params) {
+        const qs = new URLSearchParams();
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.cursor)
+            qs.set("cursor", params.cursor);
+        const q = qs.toString();
+        const result = await this.get(`/app/${appId}/api/collections${q ? `?${q}` : ""}`);
+        return {
+            items: result?.items ?? [],
+            hasMore: result?.hasMore,
+            nextCursor: result?.nextCursor ?? result?.cursor ?? null,
+        };
+    }
+    async listAllCollections(appId, params) {
+        const qs = new URLSearchParams();
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.cursor)
+            qs.set("cursor", params.cursor);
+        const q = qs.toString();
+        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,
+        };
+    }
+    async createCollection(appId, data) {
+        return this.post(`/app/${appId}/api/collections`, data);
+    }
+    async getCollection(appId, collectionId) {
+        return this.get(`/app/${appId}/api/collections/${collectionId}`);
+    }
+    async updateCollection(appId, collectionId, data) {
+        return this.patch(`/app/${appId}/api/collections/${collectionId}`, data);
+    }
+    async deleteCollection(appId, collectionId) {
+        return this.delete(`/app/${appId}/api/collections/${collectionId}`);
+    }
+    // ============================================
+    // COLLECTION DOCUMENTS
+    // ============================================
+    async listCollectionDocuments(appId, collectionId, params) {
+        const qs = new URLSearchParams();
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.cursor)
+            qs.set("cursor", params.cursor);
+        const q = qs.toString();
+        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,
+        };
+    }
+    async addCollectionDocument(appId, collectionId, data) {
+        return this.post(`/app/${appId}/api/collections/${collectionId}/documents`, data);
+    }
+    async removeCollectionDocument(appId, collectionId, documentId) {
+        return this.delete(`/app/${appId}/api/collections/${collectionId}/documents/${documentId}`);
+    }
+    async listCollectionsForDocument(appId, documentId, params) {
+        const qs = new URLSearchParams();
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.cursor)
+            qs.set("cursor", params.cursor);
+        const q = qs.toString();
+        const result = await this.get(`/app/${appId}/api/documents/${documentId}/collections${q ? `?${q}` : ""}`);
+        return {
+            items: result?.items ?? [],
+            nextCursor: result?.nextCursor ?? result?.cursor ?? null,
+        };
+    }
+    // ============================================
+    // COLLECTION ACCESS (GROUPS + MEMBERS)
+    // ============================================
+    async getCollectionAccess(appId, collectionId) {
+        return this.get(`/app/${appId}/api/collections/${collectionId}/access`);
+    }
+    async grantCollectionGroupPermission(appId, collectionId, data) {
+        return this.post(`/app/${appId}/api/collections/${collectionId}/group-permissions`, data);
+    }
+    async revokeCollectionGroupPermission(appId, collectionId, groupType, groupId) {
+        return this.delete(`/app/${appId}/api/collections/${collectionId}/group-permissions/${groupType}/${groupId}`);
+    }
+    async addCollectionMember(appId, collectionId, data) {
+        return this.post(`/app/${appId}/api/collections/${collectionId}/members`, data);
+    }
+    async removeCollectionMember(appId, collectionId, userId) {
+        return this.delete(`/app/${appId}/api/collections/${collectionId}/members/${userId}`);
+    }
+    // ============================================
+    // COLLECTION TYPE CONFIGS
+    // ============================================
+    async listCollectionTypeConfigs(appId) {
+        return this.get(`/app/${appId}/api/collection-type-configs`);
+    }
+    async getCollectionTypeConfig(appId, collectionType) {
+        return this.get(`/app/${appId}/api/collection-type-configs/${collectionType}`);
+    }
+    async createCollectionTypeConfig(appId, data) {
+        return this.post(`/app/${appId}/api/collection-type-configs`, data);
+    }
+    async updateCollectionTypeConfig(appId, collectionType, data, expectedModifiedAt) {
+        const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
+        return this.patch(`/app/${appId}/api/collection-type-configs/${collectionType}`, body);
+    }
+    async deleteCollectionTypeConfig(appId, collectionType) {
+        return this.delete(`/app/${appId}/api/collection-type-configs/${collectionType}`);
+    }
+    // ============================================
+    // METADATA CATEGORY CONFIGS (issue #1304, P-B)
+    // ============================================
+    /**
+     * List all metadata category configs for an app. The route returns
+     * `{ configs: [...] }`; unwrap to a bare array to match the other
+     * `list*Configs` helpers.
+     */
+    async listMetadataCategoryConfigs(appId) {
+        const res = await this.get(`/app/${appId}/api/metadata-categories`);
+        return Array.isArray(res?.configs) ? res.configs : [];
+    }
+    async getMetadataCategoryConfig(appId, resourceType, category) {
+        return this.get(`/app/${appId}/api/metadata-categories/${encodeURIComponent(resourceType)}/${encodeURIComponent(category)}`);
+    }
+    /**
+     * Create or replace a metadata category config (idempotent upsert via the
+     * path-addressed PUT route). `resourceType` / `category` identify the config;
+     * the body carries `schema` / `readRule` / `writeRule` / `description`.
+     */
+    async upsertMetadataCategoryConfig(appId, resourceType, category, data, 
+    /** Optimistic-concurrency token; see `upsertEmailTemplate` (#2731 B10). */
+    expectedModifiedAt) {
+        return this.put(`/app/${appId}/api/metadata-categories/${encodeURIComponent(resourceType)}/${encodeURIComponent(category)}`, expectedModifiedAt ? { ...data, expectedModifiedAt } : data);
+    }
+    /**
+     * Delete a metadata category config (issue #1426, admin-gated route shipped
+     * in #1364). Orphan semantics: the config row is hard-deleted; any stored
+     * `ResourceMetadata` value rows for the category are left behind and become
+     * unreachable (no query path from a category to its values). Delete the
+     * values first if you need them gone — an orphaned value row can't be
+     * removed through any surface once its config is gone. Returns
+     * `{ resourceType, category, deleted }`; a missing config is a 404.
+     */
+    async deleteMetadataCategoryConfig(appId, resourceType, category) {
+        return this.delete(`/app/${appId}/api/metadata-categories/${encodeURIComponent(resourceType)}/${encodeURIComponent(category)}`);
+    }
+    // ============================================
     // ACCESS RULE SETS
     // ============================================
     async listRuleSets(appId, params) {
@@ -832,13 +2516,672 @@ export class ApiClient {
     async getRuleSet(appId, ruleSetId) {
         return this.get(`/app/${appId}/api/rule-sets/${ruleSetId}`);
     }
-    async updateRuleSet(appId, ruleSetId, data) {
-        return this.patch(`/app/${appId}/api/rule-sets/${ruleSetId}`, data);
+    async updateRuleSet(appId, ruleSetId, data, expectedModifiedAt) {
+        const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
+        return this.patch(`/app/${appId}/api/rule-sets/${ruleSetId}`, body);
     }
     async deleteRuleSet(appId, ruleSetId) {
         return this.delete(`/app/${appId}/api/rule-sets/${ruleSetId}`);
     }
+    async getRuleSetSchema(appId) {
+        return this.get(`/app/${appId}/api/rule-sets/schema`);
+    }
+    async getRuleSetResourceTypes(appId) {
+        return this.get(`/app/${appId}/api/rule-sets/resource-types`);
+    }
+    async testRuleSet(appId, ruleSetId, data) {
+        return this.post(`/app/${appId}/api/rule-sets/${ruleSetId}/test`, data);
+    }
+    async debugRuleSet(appId, data) {
+        return this.post(`/app/${appId}/api/rule-sets/debug`, data);
+    }
+    // ============================================
+    // GROUP TYPE CONFIGS
+    // ============================================
+    async listGroupTypeConfigs(appId) {
+        return this.get(`/app/${appId}/api/group-type-configs`);
+    }
+    async getGroupTypeConfig(appId, groupType) {
+        return this.get(`/app/${appId}/api/group-type-configs/${groupType}`);
+    }
+    async createGroupTypeConfig(appId, data) {
+        return this.post(`/app/${appId}/api/group-type-configs`, data);
+    }
+    async updateGroupTypeConfig(appId, groupType, data, expectedModifiedAt) {
+        const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
+        return this.patch(`/app/${appId}/api/group-type-configs/${groupType}`, body);
+    }
+    async deleteGroupTypeConfig(appId, groupType) {
+        return this.delete(`/app/${appId}/api/group-type-configs/${groupType}`);
+    }
+    // ============================================
+    // DOCUMENT EXPORT / IMPORT
+    // ============================================
+    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}`);
+    }
+    /**
+     * Delete a document and everything hanging off it (#2756). The server route
+     * runs the same cascade the client SDK's `documents.delete()` triggers —
+     * Yjs state and update history, blob rows and objects, aliases, user/group
+     * permissions, invitations, collection memberships — and returns
+     * `{ success, message }`, which callers pass through under `--json`.
+     */
+    async deleteDocument(appId, documentId) {
+        return this.delete(`/app/${appId}/api/documents/${documentId}`);
+    }
+    /**
+     * Introspect a document's Yjs schema (model names, per-model fields and
+     * indexes). Backs `documents records models` and `documents records
+     * describe`. Reuses the existing `GET documents/:id/schema` endpoint.
+     */
+    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
+     * through the caller's document permission (reader+) or the app-admin arm.
+     * Returns the unified `{ items, hasMore, nextCursor? }` envelope. The cursor
+     * is an opaque token — feed `nextCursor` back as `cursor` for the next page.
+     * The server also dual-emits a deprecated `cursor` alias (#1316); the
+     * normalizer drops it so CLI output is already on `nextCursor` when #1982
+     * removes it.
+     */
+    async queryDocumentRecords(appId, documentId, modelName, queryOptions) {
+        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.
+        if (queryOptions?.limit !== undefined)
+            query.limit = queryOptions.limit;
+        if (queryOptions?.cursor)
+            query.cursor = queryOptions.cursor;
+        const raw = await this.get(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}`, query);
+        return normalizeCliListEnvelope(raw);
+    }
+    /**
+     * Count records in a document model (issue #1964 Phase 3). Returns `{ count }`.
+     */
+    async countDocumentRecords(appId, documentId, modelName, queryOptions) {
+        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);
+    }
+    /**
+     * Aggregate records in a document model (issue #2437) — the documents twin
+     * of {@link aggregateDatabaseRecords}. `POST documents/:id/records/:model/aggregate`
+     * with `{ options: { operations, groupBy?, filter? } }`, answering `{ result }`
+     * in the same shape as the database endpoint.
+     *
+     * `groupBy` takes plain field names only: StringSet facet grouping and
+     * `{ field, contains }` membership grouping are database-only, which is why
+     * this signature is narrower than the databases one.
+     */
+    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):
+     * record/model/blob counts, approximate size, and last-modified timestamp.
+     */
+    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? }` —
+     * server-side write through the document facade (Yjs-first, CRDT-safe,
+     * broadcasts to connected clients). Requires read-write+ on the document
+     * or the app-admin arm. Returns `{ record }`.
+     */
+    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, 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, 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
+     * #1964 Phase 4, wrapping the #1517 `bulkUpdate` facade). All-or-nothing:
+     * a validation failure commits nothing. Returns the facade's
+     * `{ applied, added, updated, deleted }`.
+     */
+    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);
+    }
+    async listDocumentPermissions(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/permissions`);
+    }
+    async grantDocumentPermission(appId, documentId, permissions) {
+        return this.put(`/app/${appId}/api/documents/${documentId}/permissions`, { permissions });
+    }
+    /**
+     * Revoke a user's permission on a document. Mirrors the published client's
+     * `documents.removePermission` wire behavior (`src/client/api/documentsApi.ts`):
+     * a userId targets the path route `DELETE .../permissions/:userId`, while an
+     * email targets the query-param route `DELETE .../permissions?email=...`
+     * (unified email removal, #452). This duplication of the client's wire shape
+     * is deliberate and parity-tested (issue #1964 amendment 8).
+     */
+    async revokeDocumentPermission(appId, documentId, target) {
+        if (target.email) {
+            const email = encodeURIComponent(target.email);
+            return this.delete(`/app/${appId}/api/documents/${documentId}/permissions?email=${email}`);
+        }
+        if (!target.userId) {
+            throw new Error("revokeDocumentPermission: userId or email is required");
+        }
+        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`);
+    }
+    async setDocumentLinkAccess(appId, documentId, level) {
+        return this.put(`/app/${appId}/api/documents/${documentId}/link-access`, { level });
+    }
+    async clearDocumentLinkAccess(appId, documentId) {
+        return this.delete(`/app/${appId}/api/documents/${documentId}/link-access`);
+    }
+    /**
+     * 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`);
+    }
+    async downloadBlob(appId, documentId, blobId) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}/blobs/${blobId}/download`;
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+        };
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const response = await fetchWithTLS(url, { headers });
+        if (!response.ok) {
+            throw await blobFailure(response, "Failed to download blob: ");
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    }
+    async uploadBlob(appId, documentId, blobId, data, meta) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}/blobs/${blobId}`;
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+            "Content-Type": meta.contentType,
+            "X-Blob-Filename": encodeURIComponent(meta.filename),
+            "X-Blob-Size": String(data.length),
+            "X-Blob-Sha256": meta.sha256,
+        };
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const response = await fetchWithTLS(url, {
+            method: "PUT",
+            headers,
+            body: data,
+        });
+        if (!response.ok) {
+            throw await blobFailure(response, "Failed to upload blob: ");
+        }
+        return response.json();
+    }
+    async listDocumentAliases(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/aliases`);
+    }
+    async setDocumentAlias(appId, aliasScope, aliasKey, documentId, ownerUserId, mustNotExist) {
+        return this.put(`/app/${appId}/api/document-aliases/${aliasScope}/${encodeURIComponent(aliasKey)}`, {
+            documentId,
+            userId: ownerUserId,
+            mustNotExist,
+        });
+    }
+    /**
+     * Resolve an app user by exact email — the single email → userId lookup in
+     * the CLI (issue #2763). It reads the member-accessible `users/lookup`
+     * endpoint rather than the admin-only `GET /users` list, and returns the
+     * server's `{ exists, user? }` envelope as-is: a 403 or a transport failure
+     * rejects instead of being flattened into "no such user", which is exactly
+     * how the deleted admin-list helper misreported permission problems.
+     */
+    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) {
+        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
+    // ============================================
+    // `saveDatabaseRecord` lives with the other record verbs under
+    // "DATABASE RECORDS & SCHEMA" above.
+    /**
+     * Apply an ordered batch of record operations via `records/batch`.
+     *
+     * `atomic` (default off, matching the DatabaseDO) makes the whole batch
+     * all-or-nothing: the DO rolls every write back at the first failed
+     * operation and answers with that operation's status. `databases records
+     * bulk` sends `atomic: true` so it matches the documents twin's
+     * all-or-nothing contract (#2437); the CSV/import paths keep the default
+     * partial-success behavior.
+     */
+    async batchDatabaseRecords(appId, databaseId, operations, options) {
+        const body = { operations };
+        if (options?.atomic)
+            body.atomic = true;
+        return this.post(`/app/${appId}/api/databases/${databaseId}/records/batch`, body);
+    }
+    async deleteDatabaseRecord(appId, databaseId, modelName, id) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/records/delete`, { modelName, id });
+    }
+    async batchDeleteDatabaseRecords(appId, databaseId, operations) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/records/batch`, { operations });
+    }
+    async listDatabaseUniqueConstraints(appId, databaseId) {
+        const result = await this.get(`/app/${appId}/api/databases/${databaseId}/records/unique-constraints`);
+        return result?.constraints || result || [];
+    }
+    async registerDatabaseUniqueConstraint(appId, databaseId, constraint) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/records/unique-constraint/register`, constraint);
+    }
+    // ============================================
+    // BLOB BUCKETS
+    // ============================================
+    async listBlobBuckets(appId) {
+        return this.get(`/app/${appId}/api/blob-buckets`);
+    }
+    async createBlobBucket(appId, payload) {
+        return this.post(`/app/${appId}/api/blob-buckets`, payload);
+    }
+    async getBlobBucket(appId, bucketIdOrKey) {
+        return this.get(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}`);
+    }
+    async updateBlobBucket(appId, bucketIdOrKey, payload) {
+        return this.patch(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}`, payload);
+    }
+    async deleteBlobBucket(appId, bucketIdOrKey) {
+        return this.delete(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}`);
+    }
+    async listBucketBlobs(appId, bucketIdOrKey, params) {
+        const result = await this.get(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs`, params);
+        // #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;
+        return {
+            items: result?.items ?? [],
+            nextCursor,
+            hasMore: result?.hasMore ?? nextCursor != null,
+            cursor: nextCursor,
+        };
+    }
+    async uploadBucketBlob(appId, bucketIdOrKey, data, meta) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs`;
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+            "Content-Type": meta.contentType,
+            "X-Blob-Filename": encodeURIComponent(meta.filename),
+        };
+        if (meta.tags && meta.tags.length > 0) {
+            headers["X-Blob-Tags"] = JSON.stringify(meta.tags);
+        }
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const response = await fetchWithTLS(url, {
+            method: "POST",
+            headers,
+            body: data,
+        });
+        if (!response.ok) {
+            throw await blobFailure(response, "Failed to upload blob: ");
+        }
+        return response.json();
+    }
+    async downloadBucketBlob(appId, bucketIdOrKey, blobId) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs/${blobId}`;
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+        };
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const response = await fetchWithTLS(url, { headers });
+        if (!response.ok) {
+            throw await blobFailure(response, "Failed to download blob: ");
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    }
+    async deleteBucketBlob(appId, bucketIdOrKey, blobId) {
+        return this.delete(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs/${blobId}`);
+    }
+    // Batch delete (#1455): one round-trip for N ids via POST .../blobs/delete.
+    async deleteBucketBlobs(appId, bucketIdOrKey, blobIds) {
+        return this.post(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs/delete`, { blobIds });
+    }
+    async getBucketBlobSignedUrl(appId, bucketIdOrKey, blobId, expiresInSeconds) {
+        return this.post(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs/${blobId}/signed-url`, {
+            expiresInSeconds: expiresInSeconds || 300,
+        });
+    }
+    // Blob metadata (#1966): head a single blob without downloading its bytes.
+    // Mirrors listBucketBlobs/downloadBucketBlob addressing; the server heads the
+    // R2 object and returns the serialized BlobInfo shape.
+    async getBucketBlobMetadata(appId, bucketIdOrKey, blobId) {
+        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