primitive-admin 1.0.60 → 1.0.62

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

@@ -1,6 +1,6 @@
 import { loadCredentials, saveCredentials, isTokenExpiringSoon, } from "./config.js";
 import { fetchWithTLS } from "./fetch.js";
-import { paginateAll } from "./paginate.js";
+import { paginateAll, normalizeCliListEnvelope } from "./paginate.js";
 import { RefreshError, refreshAdminCredentials, } from "./refresh-admin-credentials.js";
 export class ApiError extends Error {
     statusCode;
@@ -162,6 +162,45 @@ export class OpsExistError extends ApiError {
         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 {
     credentials = null;
     constructor() {
@@ -313,7 +352,14 @@ export class ApiClient {
             if (cursor)
                 qs.set("cursor", cursor);
             const resp = await this.get(`/admin/api/admins/me/apps?${qs.toString()}`);
-            return { items: Array.isArray(resp.apps) ? resp.apps : [], nextCursor: resp.nextCursor };
+            // 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 : []),
+                nextCursor: resp.nextCursor ?? resp.cursor,
+            };
         });
         return { apps };
     }
@@ -371,6 +417,40 @@ export class ApiClient {
     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 });
     }
@@ -403,7 +483,16 @@ export class ApiClient {
     // INVITATIONS
     // ============================================
     async listInvitations(appId, params) {
-        return this.get(`/app/${appId}/api/invitations`, 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);
@@ -433,8 +522,9 @@ export class ApiClient {
     async listDeferredGrants(appId, params) {
         const result = await this.get(`/app/${appId}/api/deferred-grants`, params);
         return {
-            grants: result?.grants ?? [],
+            grants: result?.grants ?? result?.items ?? [],
             nextCursor: result?.nextCursor ?? null,
+            hasMore: result?.hasMore,
         };
     }
     async revokeDeferredGrant(appId, deferredId, type) {
@@ -450,9 +540,19 @@ export class ApiClient {
             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);
     }
@@ -460,8 +560,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);
@@ -477,19 +584,6 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/workflows/runs/${runId}/integration-logs`, params);
         return result?.items ?? [];
     }
-    async listIntegrationSecrets(appId, integrationId, params) {
-        const result = await this.get(`/admin/api/apps/${appId}/integrations/${integrationId}/secrets`, 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;
-    }
-    async archiveIntegrationSecret(appId, integrationId, secretId) {
-        return this.patch(`/admin/api/apps/${appId}/integrations/${integrationId}/secrets/${secretId}`, {
-            status: "inactive",
-        });
-    }
     // ============================================
     // APP SECRETS
     // ============================================
@@ -566,19 +660,90 @@ export class ApiClient {
         const body = expectedModifiedAt ? { ...payload, expectedModifiedAt } : payload;
         return this.patch(`/admin/api/apps/${appId}/webhooks/${webhookId}`, body);
     }
-    async deleteWebhook(appId, webhookId) {
-        return this.delete(`/admin/api/apps/${appId}/webhooks/${webhookId}`);
+    /**
+     * 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}`, {});
+    }
+    /** #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);
-        return result;
+        // #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 ?? [],
+            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 ?? [],
+            nextCursor: result?.nextCursor ?? null,
+        };
     }
     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)
     // ============================================
@@ -614,14 +779,21 @@ export class ApiClient {
     async updateCronTrigger(appId, triggerId, payload) {
         return this.put(`/app/${appId}/api/cron-triggers/${triggerId}`, payload);
     }
-    async deleteCronTrigger(appId, triggerId) {
-        return this.delete(`/app/${appId}/api/cron-triggers/${triggerId}`);
+    /**
+     * 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 pauseCronTrigger(appId, triggerId) {
-        return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/pause`, {});
+    async disableCronTrigger(appId, triggerId) {
+        return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/disable`, {});
     }
-    async resumeCronTrigger(appId, triggerId) {
-        return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/resume`, {});
+    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`, {});
@@ -669,6 +841,20 @@ export class ApiClient {
     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,
+        });
+    }
     // ============================================
     // PROMPTS
     // ============================================
@@ -689,6 +875,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`
@@ -728,7 +920,7 @@ export class ApiClient {
     // 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 `sync push` reads `transforms/*.rhai` files and reconciles
+    // 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).
@@ -761,10 +953,28 @@ export class ApiClient {
      * 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) {
+    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 });
-        await this.post(`/admin/api/apps/${appId}/scripts/${scriptId}/configs/${config.configId}/activate`, {});
+        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;
     }
     /**
@@ -784,30 +994,54 @@ export class ApiClient {
     // ============================================
     // 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 ?? [],
+            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);
     }
@@ -815,21 +1049,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;
@@ -839,6 +1075,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) {
@@ -935,15 +1173,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);
     }
@@ -952,9 +1208,31 @@ 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) {
@@ -964,12 +1242,9 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/runs/${runId}/steps`);
         return { items: result?.items ?? [] };
     }
-    async getWorkflowAnalytics(appId, params) {
-        return this.get(`/app/${appId}/api/analytics/workflows/overview`, params);
-    }
-    async getTopWorkflows(appId, params) {
-        return this.get(`/app/${appId}/api/analytics/workflows/top`, params);
-    }
+    // 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
     // ============================================
@@ -1040,6 +1315,9 @@ export class ApiClient {
     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);
     }
@@ -1051,9 +1329,12 @@ export class ApiClient {
     // ============================================
     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;
         return {
-            admins: result?.admins ?? [],
-            cursor: result?.cursor ?? null,
+            admins: result?.admins ?? result?.items ?? [],
+            nextCursor,
+            cursor: nextCursor,
         };
     }
     async searchAdminByEmail(email) {
@@ -1121,21 +1402,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) {
@@ -1162,8 +1428,17 @@ export class ApiClient {
     async getEmailTemplate(appId, emailType) {
         return this.get(`/admin/api/apps/${appId}/email-templates/${emailType}`);
     }
-    async upsertEmailTemplate(appId, emailType, payload) {
-        return this.put(`/admin/api/apps/${appId}/email-templates/${emailType}`, payload);
+    /**
+     * 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}`);
@@ -1190,8 +1465,42 @@ 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).
+     */
+    async listDatabases(appId, options) {
+        return paginateAll(async (cursor) => {
+            const params = new URLSearchParams();
+            if (options?.owner)
+                params.set("owner", options.owner);
+            if (cursor)
+                params.set("cursor", cursor);
+            const qs = params.toString() ? `?${params.toString()}` : "";
+            const resp = await this.get(`/app/${appId}/api/databases${qs}`);
+            // Tolerant read: a server older than #1958 answers with a bare array.
+            // Without this a published CLI pointed at a not-yet-upgraded server
+            // would print nothing at all. Such a server also predates the `owner`
+            // filter (#1965) and ignores the unknown query parameter, so apply the
+            // filter here — the legacy rows carry `createdBy`, so this reproduces
+            // the server's own post-join filter (#2245).
+            if (Array.isArray(resp)) {
+                return {
+                    items: options?.owner
+                        ? resp.filter((db) => db?.createdBy === options.owner)
+                        : resp,
+                };
+            }
+            return { items: resp?.items ?? [], nextCursor: resp?.nextCursor };
+        });
     }
     async createDatabase(appId, data) {
         return this.post(`/app/${appId}/api/databases`, data);
@@ -1258,6 +1567,14 @@ export class ApiClient {
     async describeDatabaseModel(appId, databaseId, modelName) {
         return this.get(`/app/${appId}/api/databases/${databaseId}/records/describe`, { modelName });
     }
+    /**
+     * 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)
@@ -1269,7 +1586,55 @@ export class ApiClient {
             options.uniqueStartKey = queryOptions.cursor;
         if (Object.keys(options).length > 0)
             body.options = options;
-        return this.post(`/app/${appId}/api/databases/${databaseId}/admin-data/query`, body);
+        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,
+        });
+    }
+    /**
+     * 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,
+        });
     }
     // ============================================
     // DATABASE OPERATIONS (registered operations)
@@ -1277,6 +1642,15 @@ export class ApiClient {
     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 = {};
@@ -1284,17 +1658,17 @@ export class ApiClient {
             extraHeaders["X-Timing"] = "true";
         }
         if (token) {
-            return this.requestWithToken(path, token, {
+            return normalizeDatabaseOperationResult(await this.requestWithToken(path, token, {
                 method: "POST",
                 body: JSON.stringify(data || {}),
                 headers: extraHeaders,
-            });
+            }));
         }
-        return this.request(path, {
+        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
@@ -1357,8 +1731,14 @@ export class ApiClient {
     async getDatabaseTypeConfig(appId, databaseType) {
         return this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}`);
     }
-    async createDatabaseTypeConfig(appId, data) {
-        return this.post(`/app/${appId}/api/databases/types`, data);
+    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;
@@ -1393,7 +1773,7 @@ export class ApiClient {
     }
     async createDatabaseTypeOperation(appId, databaseType, data, 
     // Issue #813 (1A): when `dryRun` is set the server runs the op-edit gate
-    // without persisting — used by `sync push --dry-run` to surface 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).
@@ -1413,16 +1793,24 @@ export class ApiClient {
         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);
     }
@@ -1456,8 +1844,12 @@ export class ApiClient {
     async createDatabaseTypeSubscription(appId, databaseType, data) {
         return this.post(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions`, data);
     }
-    async updateDatabaseTypeSubscription(appId, databaseType, subscriptionKey, data) {
-        return this.put(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions/${encodeURIComponent(subscriptionKey)}`, 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)}`);
@@ -1466,7 +1858,16 @@ export class ApiClient {
     // 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);
@@ -1485,7 +1886,16 @@ export class ApiClient {
     // ============================================
     async listGroupMembers(appId, groupType, groupId, options) {
         const qs = options?.include ? `?include=${options.include}` : "";
-        return this.get(`/app/${appId}/api/groups/${groupType}/${groupId}/members${qs}`);
+        const result = await this.get(`/app/${appId}/api/groups/${groupType}/${groupId}/members${qs}`);
+        // #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);
@@ -1530,7 +1940,7 @@ export class ApiClient {
         const result = await this.get(`/app/${appId}/api/collections${q ? `?${q}` : ""}`);
         return {
             items: result?.items ?? [],
-            nextCursor: result?.cursor ?? null,
+            nextCursor: result?.nextCursor ?? result?.cursor ?? null,
         };
     }
     async listAllCollections(appId, params) {
@@ -1543,7 +1953,7 @@ export class ApiClient {
         const result = await this.get(`/app/${appId}/api/admin/collections${q ? `?${q}` : ""}`);
         return {
             items: result?.items ?? [],
-            nextCursor: result?.cursor ?? null,
+            nextCursor: result?.nextCursor ?? result?.cursor ?? null,
         };
     }
     async createCollection(appId, data) {
@@ -1571,7 +1981,7 @@ export class ApiClient {
         const result = await this.get(`/app/${appId}/api/collections/${collectionId}/documents${q ? `?${q}` : ""}`);
         return {
             items: result?.items ?? [],
-            nextCursor: result?.cursor ?? null,
+            nextCursor: result?.nextCursor ?? result?.cursor ?? null,
         };
     }
     async addCollectionDocument(appId, collectionId, data) {
@@ -1590,7 +2000,7 @@ export class ApiClient {
         const result = await this.get(`/app/${appId}/api/documents/${documentId}/collections${q ? `?${q}` : ""}`);
         return {
             items: result?.items ?? [],
-            nextCursor: result?.cursor ?? null,
+            nextCursor: result?.nextCursor ?? result?.cursor ?? null,
         };
     }
     // ============================================
@@ -1650,8 +2060,10 @@ export class ApiClient {
      * path-addressed PUT route). `resourceType` / `category` identify the config;
      * the body carries `schema` / `readRule` / `writeRule` / `description`.
      */
-    async upsertMetadataCategoryConfig(appId, resourceType, category, data) {
-        return this.put(`/app/${appId}/api/metadata-categories/${encodeURIComponent(resourceType)}/${encodeURIComponent(category)}`, data);
+    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
@@ -1727,6 +2139,112 @@ export class ApiClient {
     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`);
+    }
+    /**
+     * 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);
+        // 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);
+        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) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/aggregate`, { 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`);
+    }
+    /**
+     * 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) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}`, body);
+    }
+    /**
+     * Merge fields into an existing record (issue #1964 Phase 4).
+     * `PATCH documents/:id/records/:model/:recordId` with `{ data, options? }`.
+     * Returns `{ record }`.
+     */
+    async patchDocumentRecord(appId, documentId, modelName, recordId, body) {
+        return this.patch(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}`, body);
+    }
+    /**
+     * Delete a record from a document model (issue #1964 Phase 4).
+     * `DELETE documents/:id/records/:model/:recordId`. A missing record id is
+     * a silent no-op per the facade contract. Returns `{ deleted: true }`.
+     */
+    async deleteDocumentRecord(appId, documentId, modelName, recordId) {
+        return this.delete(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}`);
+    }
+    /**
+     * 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) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/records/bulk`, { operations });
+    }
     async createDocument(appId, data) {
         return this.post(`/app/${appId}/api/documents`, data);
     }
@@ -1736,6 +2254,24 @@ export class ApiClient {
     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}`);
+    }
     async getDocumentLinkAccess(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/link-access`);
     }
@@ -1801,15 +2337,16 @@ export class ApiClient {
             mustNotExist,
         });
     }
-    async findUserByEmail(appId, email) {
-        try {
-            const result = await this.get(`/app/${appId}/api/users`, { email });
-            const items = result?.items || (Array.isArray(result) ? result : []);
-            return items[0] || null;
-        }
-        catch {
-            return null;
-        }
+    /**
+     * 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 });
     }
     async listAdminDocuments(appId, userId) {
         const result = await this.get(`/admin/api/apps/${appId}/documents`, { userId });
@@ -1818,21 +2355,29 @@ export class ApiClient {
     // ============================================
     // DATABASE EXPORT / IMPORT
     // ============================================
-    async saveDatabaseRecord(appId, databaseId, modelName, id, data) {
-        return this.post(`/app/${appId}/api/databases/${databaseId}/admin-data/save`, {
-            modelName,
-            id,
-            data,
-        });
-    }
-    async batchDatabaseRecords(appId, databaseId, operations) {
-        return this.post(`/app/${appId}/api/databases/${databaseId}/admin-data/batch`, { operations });
+    // `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}/admin-data/delete`, { 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}/admin-data/batch`, { 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`);
@@ -1860,7 +2405,16 @@ export class ApiClient {
         return this.delete(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}`);
     }
     async listBucketBlobs(appId, bucketIdOrKey, params) {
-        return this.get(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs`, 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();
@@ -1915,6 +2469,12 @@ export class ApiClient {
             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();