primitive-admin 1.0.61 → 1.0.63

package/dist/src/lib/api-client.d.ts

@@ -1,3 +1,4 @@
+import { type ListEnvelope } from "./paginate.js";
 /**
  * Metadata for a single bucket blob, as returned by the metadata endpoint
  * `GET blob-buckets/:bucketId/blobs/:blobId/metadata`. Mirrors the published
@@ -279,6 +280,14 @@ interface AnalyticsEventsGroupedResponse {
     rows: AnalyticsGroupedRow[];
     _timing: AnalyticsTiming;
 }
+interface AnalyticsErrorGroupExemplar {
+    message: string;
+    action: string;
+    scope_key: string;
+    step_id: string | null;
+    run_id: string | null;
+    at: string;
+}
 interface AnalyticsErrorGroupRow {
     fingerprint: string;
     normalized_title: string;
@@ -289,12 +298,67 @@ interface AnalyticsErrorGroupRow {
         day: string;
         count: number;
     }>;
+    /** First/last occurrence in the window (ISO-8601). */
+    first_seen: string | null;
+    last_seen: string | null;
+    /** A raw sample of the failure, or null when no sampled row carried one
+     *  (events written before the exemplar shipped, or a starved group). */
+    exemplar: AnalyticsErrorGroupExemplar | null;
 }
 interface AnalyticsErrorsGroupsResponse {
     window_days: number;
     rows: AnalyticsErrorGroupRow[];
     _timing: AnalyticsTiming;
 }
+/**
+ * What a `DELETE` on a status-carrying object answers (#2887, #2907).
+ *
+ * The plain call archives and `?hard=true` destroys, and the envelope says
+ * which happened. Four of the five methods below were declared `Promise<void>`
+ * while returning this at runtime, so `primitive <noun> archive --json` printed
+ * a value TypeScript believed did not exist. The fields are optional because
+ * the cron route answers the shorter `{ archived: true }` — no `success`, and
+ * no key — which is why the archive commands identify the object by the id the
+ * operator passed rather than by anything the envelope carries.
+ */
+export interface ArchiveEnvelope {
+    success?: boolean;
+    hardDeleted?: boolean;
+    archived?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Body accepted by integration create and update (#2631).
+ *
+ * `accessRule` is the CEL expression gating who may invoke the integration
+ * through the proxy. The server REQUIRES it on create; on update, `null` or
+ * `""` clears it, and a cleared rule denies every non-admin call.
+ */
+export interface IntegrationWritePayload {
+    integrationKey?: string;
+    displayName?: string;
+    description?: string | null;
+    requestConfig?: any;
+    timeoutMs?: number;
+    status?: string;
+    accessRule?: string | null;
+}
+/**
+ * Integration detail response. `accessRule` is only on the detail — the list
+ * summary does not carry it (#2631).
+ */
+export interface IntegrationDetail {
+    integrationId: string;
+    integrationKey: string;
+    displayName?: string;
+    description?: string | null;
+    status?: string;
+    timeoutMs?: number;
+    requestConfig?: any;
+    accessRule?: string | null;
+    modifiedAt?: string;
+    [key: string]: any;
+}
 interface AnalyticsIntegrationMetric {
     integrationKey: string;
     invocations: number;
@@ -335,7 +399,7 @@ interface TopPromptsResponse {
     _timing: AnalyticsTiming;
 }
 /**
- * One operation in an `admin-data/batch` request. Mirrors the wire shape the
+ * One operation in a `records/batch` request. Mirrors the wire shape the
  * DatabaseDO expects (`databases-controller.ts`): `{ op, modelName, id, data }`.
  * `data` is required for `save`/`patch` and omitted for `delete`.
  */
@@ -344,7 +408,48 @@ export interface DatabaseBatchOperation {
     modelName: string;
     id: string;
     data?: any;
+    /**
+     * Strict create: the DatabaseDO fails the op with a 409 `ALREADY_EXISTS` when
+     * the id is already present, instead of `save`'s upsert merge. Checked inside
+     * the batch transaction, so under `atomic` it rolls the whole batch back.
+     */
+    ifNotExists?: boolean;
+    /**
+     * Per-op guard evaluated inside the batch transaction — a mismatch is a 409
+     * `CONDITION_NOT_MET`, and under `atomic` it rolls the whole batch back. This
+     * is what the documents surface calls a `precondition`.
+     */
+    condition?: Record<string, any>;
 }
+/**
+ * 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 declare function normalizeDatabaseOperationResult(raw: unknown): unknown;
 export declare class ApiClient {
     private credentials;
     constructor();
@@ -393,6 +498,27 @@ export declare class ApiClient {
         nextCursor?: string | null;
     }>;
     removeUser(appId: string, userId: string): Promise<void>;
+    /**
+     * #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.
+     */
+    setUserAvailability(appId: string, userId: string, action: "enable" | "disable"): Promise<void>;
+    /**
+     * #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.
+     */
+    listFeatureFlags(): Promise<any>;
+    /**
+     * 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.
+     */
+    getFeatureFlag(flagKey: string): Promise<any>;
+    /** Same envelope, same unwrap: `enable`/`disable` print the updated flag. */
+    setFeatureFlagEnabled(flagKey: string, enabled: boolean): Promise<any>;
     updateUserRole(appId: string, userId: string, role: "admin" | "member"): Promise<any>;
     transferOwnership(appId: string, newOwnerEmail: string): Promise<void>;
     transferAdminOwnership(appId: string, adminId: string): Promise<any>;
@@ -456,10 +582,27 @@ export declare class ApiClient {
         items: any[];
         nextCursor?: string | null;
     }>;
-    getIntegration(appId: string, integrationId: string): Promise<any>;
-    createIntegration(appId: string, payload: any): Promise<any>;
-    updateIntegration(appId: string, integrationId: string, payload: any, expectedModifiedAt?: string): Promise<any>;
-    deleteIntegration(appId: string, integrationId: string, hard?: boolean): Promise<void>;
+    /** Integration detail (#2631: `accessRule` is on the detail, not the list summary). */
+    getIntegration(appId: string, integrationId: string): Promise<IntegrationDetail>;
+    /**
+     * 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.
+     */
+    listIntegrationConfigs(appId: string, integrationId: string): Promise<{
+        items: any[];
+    }>;
+    createIntegration(appId: string, payload: IntegrationWritePayload): Promise<any>;
+    updateIntegration(appId: string, integrationId: string, payload: IntegrationWritePayload, expectedModifiedAt?: string): Promise<any>;
+    /**
+     * 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.
+     */
+    deleteIntegration(appId: string, integrationId: string, hard?: boolean | {
+        hard?: boolean;
+    }): Promise<ArchiveEnvelope>;
     testIntegration(appId: string, integrationId: string, payload: any): Promise<any>;
     listIntegrationLogs(appId: string, integrationId: string, params?: {
         limit?: number;
@@ -471,14 +614,6 @@ export declare class ApiClient {
     listWorkflowRunIntegrationLogs(appId: string, runId: string, params?: {
         limit?: number;
     }): Promise<any[]>;
-    listIntegrationSecrets(appId: string, integrationId: string, params?: {
-        limit?: number;
-    }): Promise<any[]>;
-    addIntegrationSecret(appId: string, integrationId: string, payload: {
-        secretData: any;
-        secretSummary?: string;
-    }): Promise<any>;
-    archiveIntegrationSecret(appId: string, integrationId: string, secretId: string): Promise<any>;
     listAppSecrets(appId: string): Promise<any[]>;
     createAppSecret(appId: string, payload: {
         key: string;
@@ -513,13 +648,38 @@ export declare class ApiClient {
     getWebhook(appId: string, webhookId: string): Promise<any>;
     createWebhook(appId: string, payload: any): Promise<any>;
     updateWebhook(appId: string, webhookId: string, payload: any, expectedModifiedAt?: string): Promise<any>;
-    deleteWebhook(appId: string, webhookId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    deleteWebhook(appId: string, webhookId: string, options?: {
+        hard?: boolean;
+    }): Promise<ArchiveEnvelope>;
+    /**
+     * #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.
+     */
+    setWebhookAvailability(appId: string, webhookId: string, action: "enable" | "disable"): Promise<any>;
+    /** #2803 — the operational verb pair for a prompt (admin API). */
+    setPromptAvailability(appId: string, promptId: string, action: "enable" | "disable"): Promise<any>;
+    /** #2803 — the operational verb pair for an integration (admin API). */
+    setIntegrationAvailability(appId: string, integrationId: string, action: "enable" | "disable"): Promise<any>;
     rotateWebhookSecret(appId: string, webhookId: string, payload: {
         signingSecret: string;
     }): Promise<any>;
     listWebhookEvents(appId: string, webhookId: string, params?: {
         limit?: number;
-    }): Promise<any>;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        hasMore?: boolean;
+        nextCursor?: string | null;
+        /** @deprecated Alias of `nextCursor` (#1316). */
+        cursor?: string | null;
+    }>;
     /**
      * 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
@@ -546,6 +706,19 @@ export declare class ApiClient {
         nextCursor?: string | null;
     }>;
     testWebhook(appId: string, webhookId: string, payload?: any): Promise<any>;
+    /**
+     * 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.
+     */
+    verifyWebhook(appId: string, webhookId: string, payload: {
+        headers: Array<[string, string]>;
+        rawBody?: string;
+        bodyBase64?: string;
+    }): Promise<any>;
     listLocks(appId: string): Promise<{
         locks: any[];
     }>;
@@ -558,9 +731,17 @@ export declare class ApiClient {
     getCronTrigger(appId: string, triggerId: string): Promise<any>;
     createCronTrigger(appId: string, payload: any): Promise<any>;
     updateCronTrigger(appId: string, triggerId: string, payload: any): Promise<any>;
-    deleteCronTrigger(appId: string, triggerId: string): Promise<any>;
-    pauseCronTrigger(appId: string, triggerId: string): Promise<any>;
-    resumeCronTrigger(appId: string, triggerId: string): Promise<any>;
+    /**
+     * 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.
+     */
+    deleteCronTrigger(appId: string, triggerId: string, options?: {
+        hard?: boolean;
+    }): Promise<ArchiveEnvelope>;
+    disableCronTrigger(appId: string, triggerId: string): Promise<any>;
+    enableCronTrigger(appId: string, triggerId: string): Promise<any>;
     testCronTrigger(appId: string, triggerId: string): Promise<any>;
     listIterations(appId: string): Promise<{
         items: any[];
@@ -601,6 +782,16 @@ export declare class ApiClient {
         category: string;
         deleted: boolean;
     }>;
+    /**
+     * 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.
+     */
+    resolveResourceMetadata(appId: string, resourceType: string, category: string, key: string, value: string): Promise<{
+        resourceId: string | null;
+        resourceType?: string;
+    }>;
     listPrompts(appId: string, params?: {
         status?: string;
         limit?: number;
@@ -612,7 +803,13 @@ export declare class ApiClient {
     getPrompt(appId: string, promptId: string): Promise<any>;
     createPrompt(appId: string, payload: any): Promise<any>;
     updatePrompt(appId: string, promptId: string, payload: any, expectedModifiedAt?: string): Promise<any>;
-    deletePrompt(appId: string, promptId: string, hard?: boolean): Promise<void>;
+    /**
+     * 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.
+     */
+    deletePrompt(appId: string, promptId: string, hard?: boolean): Promise<ArchiveEnvelope>;
     executePrompt(appId: string, promptId: string, payload: {
         variables: Record<string, any>;
         modelOverride?: string;
@@ -659,7 +856,21 @@ export declare 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.
      */
-    pushScriptBody(appId: string, scriptId: string, body: string): Promise<any>;
+    pushScriptBody(appId: string, scriptId: string, body: string, 
+    /**
+     * 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?: {
+        configId?: string;
+        modifiedAt?: string;
+    }): Promise<any>;
     /**
      * Delete a script header (cascades its configs). `force` overrides the
      * server's guard against deleting a script that an active workflow still
@@ -676,12 +887,22 @@ export declare class ApiClient {
         activeConfigId: string | null;
         activeConfigName: string | null;
     }>;
-    listTestCases(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string): Promise<{
+    /**
+     * 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).
+     */
+    listTestCases(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
         items: any[];
+        nextCursor?: string;
     }>;
     getTestCase(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string): Promise<any>;
     createTestCase(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, payload: {
         name: string;
+        description?: string | null;
         inputVariables: Record<string, any>;
         expectedOutputPattern?: string;
         expectedOutputContains?: string[];
@@ -689,9 +910,12 @@ export declare class ApiClient {
         configId?: string;
         evaluatorPromptId?: string;
         evaluatorConfigId?: string;
+        /** The sidecar's file name — the case's identity (#2896). */
+        key?: string;
     }): Promise<any>;
     updateTestCase(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string, payload: {
         name?: string;
+        description?: string | null;
         inputVariables?: Record<string, any>;
         expectedOutputPattern?: string | null;
         expectedOutputContains?: string[] | null;
@@ -699,6 +923,8 @@ export declare class ApiClient {
         configId?: string | null;
         evaluatorPromptId?: string | null;
         evaluatorConfigId?: string | null;
+        /** The sidecar's file name, on a create-or-rename backfill (#2896). */
+        key?: string;
     }): Promise<any>;
     deleteTestCase(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string): Promise<void>;
     listTestCaseAttachments(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string): Promise<{
@@ -754,9 +980,26 @@ export declare class ApiClient {
     getWorkflow(appId: string, workflowId: string): Promise<any>;
     createWorkflow(appId: string, payload: any): Promise<any>;
     updateWorkflow(appId: string, workflowId: string, payload: any, expectedModifiedAt?: string): Promise<any>;
-    deleteWorkflow(appId: string, workflowId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    deleteWorkflow(appId: string, workflowId: string, options?: {
+        hard?: boolean;
+    }): Promise<ArchiveEnvelope>;
+    /**
+     * #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`.
+     */
+    disableWorkflow(appId: string, workflowId: string): Promise<any>;
+    enableWorkflow(appId: string, workflowId: string): Promise<any>;
     updateWorkflowDraft(appId: string, workflowId: string, payload: any): Promise<any>;
-    publishWorkflow(appId: string, workflowId: string): Promise<any>;
     previewWorkflow(appId: string, workflowId: string, payload: {
         rootInput?: object;
         meta?: object;
@@ -777,23 +1020,47 @@ export declare class ApiClient {
         limit?: number;
         cursor?: string;
         forward?: boolean;
+        follow?: boolean;
+        after?: string;
+    }): Promise<{
+        items: any[];
+        hasMore?: boolean;
+        nextCursor?: string | null;
+        /** @deprecated Alias of `nextCursor` (#1316). */
+        cursor?: string | null;
+        /** #1969 — opaque follow checkpoint; present on `follow=true` responses. */
+        resumeAfter?: string;
+        /**
+         * #2237 — index rows the server examined for this request. Filtered reads
+         * only, and only on a server new enough to report it; `undefined`
+         * otherwise, which callers must treat as "unknown", not zero.
+         */
+        scanned?: number;
+    }>;
+    /**
+     * 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.
+     */
+    listUserWorkflowRuns(appId: string, userId: string, params?: {
+        status?: string;
+        limit?: number;
+        cursor?: string;
+        forward?: boolean;
+        workflowId?: string;
     }): Promise<{
         items: any[];
+        hasMore?: boolean;
         nextCursor?: string | null;
         /** @deprecated Alias of `nextCursor` (#1316). */
         cursor?: string | null;
+        /** #2237 — index rows examined; filtered reads only, `undefined` if unknown. */
+        scanned?: number;
     }>;
     getWorkflowRunStatus(appId: string, workflowId: string, runId: string): Promise<any>;
     getWorkflowStepRuns(appId: string, workflowId: string, runId: string): Promise<{
         items: any[];
     }>;
-    getWorkflowAnalytics(appId: string, params?: {
-        windowDays?: number;
-    }): Promise<any>;
-    getTopWorkflows(appId: string, params?: {
-        windowDays?: number;
-        limit?: number;
-    }): Promise<any>;
     listWorkflowConfigs(appId: string, workflowId: string): Promise<{
         items: any[];
     }>;
@@ -906,28 +1173,6 @@ export declare class ApiClient {
     createIntegrationCatalogItem(payload: any): Promise<any>;
     updateIntegrationCatalogItem(catalogId: string, payload: any): Promise<any>;
     deleteIntegrationCatalogItem(catalogId: string): Promise<void>;
-    listLlmModels(provider?: string): Promise<{
-        models: Array<{
-            id: string;
-            name: string;
-            context_length?: number;
-            pricing?: any;
-        }>;
-        defaultModel?: string;
-        cachedAt?: string;
-    }>;
-    generatePrompt(payload: {
-        description: string;
-        generateOutputSchema?: boolean;
-    }): Promise<any>;
-    generateEvaluator(payload: {
-        appId: string;
-        promptId: string;
-    }): Promise<any>;
-    generateWorkflowEvaluator(payload: {
-        appId: string;
-        workflowId: string;
-    }): Promise<any>;
     startBatchTests(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, payload?: {
         comparisonGroup?: string;
         overrideConfigId?: string;
@@ -968,11 +1213,20 @@ export declare class ApiClient {
         templates: EmailTemplateSummary[];
     }>;
     getEmailTemplate(appId: string, emailType: string): Promise<EmailTemplateDetail>;
+    /**
+     * 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.
+     */
     upsertEmailTemplate(appId: string, emailType: string, payload: {
         subject: string;
         htmlBody: string;
         textBody: string;
-    }): Promise<EmailTemplateUpsertResult>;
+    }, expectedModifiedAt?: string): Promise<EmailTemplateUpsertResult>;
     deleteEmailTemplate(appId: string, emailType: string): Promise<{
         success: boolean;
     }>;
@@ -1022,7 +1276,21 @@ export declare class ApiClient {
         success: boolean;
         message: string;
     }>;
-    listDatabases(appId: string): Promise<any[]>;
+    /**
+     * 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).
+     */
+    listDatabases(appId: string, options?: {
+        owner?: string;
+    }): Promise<any[]>;
     createDatabase(appId: string, data: {
         title: string;
         databaseType?: string;
@@ -1057,12 +1325,69 @@ export declare class ApiClient {
     revokeDatabasePermission(appId: string, databaseId: string, userId: string): Promise<any>;
     listDatabaseModels(appId: string, databaseId: string): Promise<any>;
     describeDatabaseModel(appId: string, databaseId: string, modelName: string): Promise<any>;
+    /**
+     * 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}.
+     */
     queryDatabaseRecords(appId: string, databaseId: string, modelName: string, queryOptions?: {
         filter?: Record<string, any>;
         limit?: number;
         cursor?: string;
-    }): Promise<any>;
+    }): Promise<ListEnvelope>;
+    countDatabaseRecords(appId: string, databaseId: string, modelName: string, filter?: Record<string, any>): Promise<{
+        count: number;
+    }>;
+    aggregateDatabaseRecords(appId: string, databaseId: string, modelName: string, options: {
+        operations: {
+            type: string;
+            field?: string;
+        }[];
+        groupBy: (string | {
+            field: string;
+            contains: string;
+        })[];
+        filter?: Record<string, any>;
+    }): Promise<{
+        result: unknown;
+    }>;
+    /**
+     * 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.
+     */
+    saveDatabaseRecord(appId: string, databaseId: string, modelName: string, id: string | undefined, data: any): Promise<any>;
+    /**
+     * 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 }`.
+     */
+    patchDatabaseRecord(appId: string, databaseId: string, modelName: string, id: string, data: any): Promise<any>;
     listDatabaseOperations(appId: string, databaseId: string): Promise<any[]>;
+    /**
+     * 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.
+     */
     executeDatabaseOperation(appId: string, databaseId: string, operationName: string, data?: {
         params?: Record<string, any>;
         limit?: number;
@@ -1145,6 +1470,7 @@ export declare class ApiClient {
             access?: string | null;
             params?: Record<string, any> | null;
         }>;
+        pendingOpUpserts?: Array<Record<string, any>>;
     }, expectedModifiedAt?: string, options?: {
         dryRun?: boolean;
         acceptWarnings?: boolean;
@@ -1194,7 +1520,7 @@ export declare class ApiClient {
         params?: Record<string, any> | null;
         status?: string;
     }): Promise<any>;
-    updateDatabaseTypeSubscription(appId: string, databaseType: string, subscriptionKey: string, data: Record<string, any>): Promise<any>;
+    updateDatabaseTypeSubscription(appId: string, databaseType: string, subscriptionKey: string, data: Record<string, any>, expectedModifiedAt?: string): Promise<any>;
     deleteDatabaseTypeSubscription(appId: string, databaseType: string, subscriptionKey: string): Promise<any>;
     listGroups(appId: string, params?: {
         type?: string;
@@ -1326,7 +1652,9 @@ export declare class ApiClient {
         writeRule?: string | null;
         description?: string | null;
         metadataManifest?: unknown;
-    }): Promise<any>;
+    }, 
+    /** Optimistic-concurrency token; see `upsertEmailTemplate` (#2731 B10). */
+    expectedModifiedAt?: string): Promise<any>;
     /**
      * Delete a metadata category config (issue #1426, admin-gated route shipped
      * in #1364). Orphan semantics: the config row is hard-deleted; any stored
@@ -1384,6 +1712,119 @@ export declare class ApiClient {
     }>;
     importDocumentState(appId: string, documentId: string, stateBase64: string): Promise<any>;
     getDocument(appId: string, documentId: string): Promise<any>;
+    /**
+     * 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`.
+     */
+    deleteDocument(appId: string, documentId: string): Promise<any>;
+    /**
+     * 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.
+     */
+    getDocumentSchema(appId: string, documentId: string): Promise<any>;
+    /**
+     * 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.
+     */
+    queryDocumentRecords(appId: string, documentId: string, modelName: string, queryOptions?: {
+        filter?: Record<string, any>;
+        limit?: number;
+        cursor?: string;
+    }): Promise<ListEnvelope>;
+    /**
+     * Count records in a document model (issue #1964 Phase 3). Returns `{ count }`.
+     */
+    countDocumentRecords(appId: string, documentId: string, modelName: string, queryOptions?: {
+        filter?: Record<string, any>;
+    }): Promise<{
+        count: number;
+    }>;
+    /**
+     * 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.
+     */
+    aggregateDocumentRecords(appId: string, documentId: string, modelName: string, options: {
+        operations: {
+            type: string;
+            field?: string;
+        }[];
+        groupBy?: string[];
+        filter?: Record<string, any>;
+    }): Promise<{
+        result: unknown;
+    }>;
+    /**
+     * Fetch platform-vocabulary document statistics (issue #1964 Phase 3):
+     * record/model/blob counts, approximate size, and last-modified timestamp.
+     */
+    getDocumentStats(appId: string, documentId: string): Promise<any>;
+    /**
+     * 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 }`.
+     */
+    saveDocumentRecord(appId: string, documentId: string, modelName: string, body: {
+        id: string;
+        data: Record<string, unknown>;
+        options?: Record<string, unknown>;
+    }): Promise<{
+        record: unknown;
+    }>;
+    /**
+     * Merge fields into an existing record (issue #1964 Phase 4).
+     * `PATCH documents/:id/records/:model/:recordId` with `{ data, options? }`.
+     * Returns `{ record }`.
+     */
+    patchDocumentRecord(appId: string, documentId: string, modelName: string, recordId: string, body: {
+        data: Record<string, unknown>;
+        options?: Record<string, unknown>;
+    }): Promise<{
+        record: unknown;
+    }>;
+    /**
+     * 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 }`.
+     */
+    deleteDocumentRecord(appId: string, documentId: string, modelName: string, recordId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * 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 }`.
+     */
+    bulkDocumentRecords(appId: string, documentId: string, operations: Array<Record<string, unknown>>): Promise<{
+        applied: number;
+        added: Array<{
+            model: string;
+            id: string;
+        }>;
+        updated: Array<{
+            model: string;
+            id: string;
+        }>;
+        deleted: number;
+    }>;
     createDocument(appId: string, data: {
         title: string;
         documentId?: string;
@@ -1392,9 +1833,22 @@ export declare class ApiClient {
     }): Promise<any>;
     listDocumentPermissions(appId: string, documentId: string): Promise<any[]>;
     grantDocumentPermission(appId: string, documentId: string, permissions: Array<{
-        userId: string;
+        userId?: string;
+        email?: string;
         permission: string;
     }>): Promise<any>;
+    /**
+     * 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).
+     */
+    revokeDocumentPermission(appId: string, documentId: string, target: {
+        userId?: string;
+        email?: string;
+    }): Promise<any>;
     getDocumentLinkAccess(appId: string, documentId: string): Promise<any>;
     setDocumentLinkAccess(appId: string, documentId: string, level: "reader" | "read-write"): Promise<any>;
     clearDocumentLinkAccess(appId: string, documentId: string): Promise<any>;
@@ -1408,10 +1862,36 @@ export declare class ApiClient {
     }): Promise<any>;
     listDocumentAliases(appId: string, documentId: string): Promise<any[]>;
     setDocumentAlias(appId: string, aliasScope: string, aliasKey: string, documentId: string, ownerUserId?: string, mustNotExist?: boolean): Promise<any>;
-    findUserByEmail(appId: string, email: string): Promise<any | 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.
+     */
+    lookupUserByEmail(appId: string, email: string): Promise<{
+        exists: boolean;
+        user?: {
+            userId: string;
+            name?: string;
+            email?: string;
+        };
+    }>;
     listAdminDocuments(appId: string, userId: string): Promise<any[]>;
-    saveDatabaseRecord(appId: string, databaseId: string, modelName: string, id: string, data: any): Promise<any>;
-    batchDatabaseRecords(appId: string, databaseId: string, operations: DatabaseBatchOperation[]): Promise<any>;
+    /**
+     * 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.
+     */
+    batchDatabaseRecords(appId: string, databaseId: string, operations: DatabaseBatchOperation[], options?: {
+        atomic?: boolean;
+    }): Promise<any>;
     deleteDatabaseRecord(appId: string, databaseId: string, modelName: string, id: string): Promise<any>;
     batchDeleteDatabaseRecords(appId: string, databaseId: string, operations: {
         op: "delete";