primitive-admin 1.1.0-alpha.7 → 1.1.0-alpha.71

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

@@ -0,0 +1,1936 @@
+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
+ * JS client's `BlobInfo` shape.
+ */
+export interface BlobInfo {
+    blobId: string;
+    bucketId: string;
+    filename: string | null;
+    contentType: string | null;
+    numBytes: number;
+    sha256: string | null;
+    tags: string[];
+    createdBy: string | null;
+    uploaded?: string | null;
+    etag?: string | null;
+}
+export declare class ApiError extends Error {
+    statusCode: number;
+    code?: string;
+    /**
+     * Structured `details` payload from `corsErrorResponse`.
+     *
+     * The server's error envelope can emit `details` as either:
+     *   - an array of validation issues (e.g. `[{ path, message }, ...]`) —
+     *     this is what most legacy endpoints produce, and what sync.ts walks
+     *     via `Array.isArray(err.details)` / `for (const detail of ...)`.
+     *   - a record of structured offender fields (e.g. `{ refs, operations,
+     *     opCount, line, column, ... }`) — emitted by the issue #666 schema
+     *     gate and consumed by the typed exception subclasses below.
+     *
+     * Callers must narrow before use: `Array.isArray(err.details)` for the
+     * legacy shape, otherwise treat as `Record<string, any>`.
+     */
+    details?: unknown[] | Record<string, any>;
+    constructor(message: string, statusCode: number, code?: string, details?: unknown[] | Record<string, any>);
+}
+export declare class ConflictError extends ApiError {
+    serverModifiedAt: string;
+    expectedModifiedAt: string;
+    constructor(message: string, serverModifiedAt: string, expectedModifiedAt: string, details?: Record<string, any>);
+}
+/**
+ * Parsed shape of a non-OK HTTP response body.
+ *
+ * The server's standard error envelope (corsErrorResponse, `src/utils.ts:348`)
+ * writes the message to `error`. A handful of bespoke endpoints (ConflictError,
+ * integrations proxy) use `message`. This helper reads both fields so all CLI
+ * call sites surface the real server message instead of `HTTP <status>`.
+ *
+ * `htmlNotFound` is set when the body looks like an HTML 404 page (typically
+ * served when an API path is wrong); callers can use it to throw a clearer
+ * "API endpoint not found" message regardless of the original status code.
+ *
+ * `details` can be either an array (legacy validation-issue list) or a
+ * structured record (issue #666 schema gate); the schema-feature errors
+ * below need the record shape, while the legacy `for (const detail of ...)`
+ * walkers in sync.ts assume the array shape.
+ */
+export interface ParsedErrorResponse {
+    message: string;
+    code?: string;
+    details?: unknown[] | Record<string, any>;
+    /** True when the response body is an HTML error page (e.g. wrong API path). */
+    htmlNotFound?: boolean;
+    /** Raw parsed JSON envelope (or `undefined` for non-JSON bodies). */
+    raw?: any;
+}
+/**
+ * Extract a human-readable error message + structured fields from a non-OK
+ * HTTP response body. Single source of truth used by every error-handler call
+ * site in this file (see issue #684).
+ */
+export declare function parseErrorResponse(response: {
+    status: number;
+}, text: string, path?: string): ParsedErrorResponse;
+/**
+ * Typed exception classes for the database-schema feature (issue #666).
+ * Each maps 1:1 to a server `code` value emitted from the op-edit or
+ * schema-edit gate. They all extend ApiError so existing catch-all paths
+ * continue to work; specialized catch blocks can branch on `instanceof`.
+ *
+ * Per round-2 addendum A1, `details` is always preserved so callers can
+ * extract structured offender lists (refs[], operations[], etc.).
+ */
+export declare class SchemaRequiredError extends ApiError {
+    constructor(message: string, details?: Record<string, any>);
+}
+export declare class OperationRefError extends ApiError {
+    constructor(message: string, details?: Record<string, any>);
+    get refs(): Array<{
+        ref: string;
+        location: string;
+    }>;
+}
+export declare class SchemaBreaksOpsError extends ApiError {
+    constructor(message: string, details?: Record<string, any>);
+    get operations(): Array<{
+        operation: string;
+        refs: Array<{
+            ref: string;
+            location: string;
+        }>;
+    }>;
+}
+export declare class SchemaHasUncheckableOpsError extends ApiError {
+    constructor(message: string, details?: Record<string, any>);
+    get operations(): Array<{
+        operation: string;
+        locations: string[];
+    }>;
+}
+export declare class TomlParseError extends ApiError {
+    constructor(message: string, details?: Record<string, any>);
+    get line(): number | undefined;
+    get column(): number | undefined;
+}
+export declare class OpsExistError extends ApiError {
+    constructor(message: string, details?: Record<string, any>);
+    get opCount(): number;
+}
+interface EmailTemplateSummary {
+    emailType: string;
+    label: string;
+    description: string;
+    hasOverride: boolean;
+    modifiedAt: string | null;
+}
+interface EmailTemplateDetail {
+    emailType: string;
+    label: string;
+    description: string;
+    hasOverride: boolean;
+    override: {
+        templateId: string;
+        subject: string;
+        htmlBody: string;
+        textBody: string;
+        createdAt: string;
+        modifiedAt: string;
+    } | null;
+    default: {
+        subject: string;
+        htmlBody: string;
+        textBody: string;
+    };
+    variables: {
+        name: string;
+        required: boolean;
+        description: string;
+    }[];
+}
+interface EmailTemplateUpsertResult {
+    emailType: string;
+    templateId: string;
+    subject: string;
+    htmlBody: string;
+    textBody: string;
+    createdAt: string;
+    modifiedAt: string;
+    warnings: string[];
+}
+interface AnalyticsTiming {
+    total_ms: number;
+    wae_queries: number[];
+}
+interface AnalyticsMetricResponse {
+    value: number;
+    previous: number;
+    deltaPct: number;
+    _timing: AnalyticsTiming;
+}
+interface AnalyticsGrowthResponse {
+    window_days: number;
+    retained_users: number;
+    new_users: number;
+    reactivated_users: number;
+    churned_users: number;
+    current_active: number;
+    previous_active: number;
+    deltaPct: number;
+    _timing: AnalyticsTiming;
+}
+interface AnalyticsDailyActivePoint {
+    day_ts: number;
+    day_label: string;
+    active_users: number;
+}
+interface AnalyticsDailyActiveResponse {
+    window_days: number;
+    rows: AnalyticsDailyActivePoint[];
+    _timing: AnalyticsTiming;
+}
+interface AnalyticsCohortRow {
+    signup_week: number;
+    signup_week_label: string;
+    cohort_size: number;
+    retention: (number | null)[];
+}
+interface AnalyticsCohortResponse {
+    weeks: number[];
+    rows: AnalyticsCohortRow[];
+    averages: (number | null)[];
+    _timing: AnalyticsTiming;
+}
+interface AnalyticsUserSummary {
+    userUlid: string;
+    email: string | null;
+    name: string | null;
+    firstSeen: string;
+    lastSeen: string;
+    eventCount: number;
+}
+interface AnalyticsTopUsersResponse {
+    windowDays: number;
+    limit: number;
+    results: AnalyticsUserSummary[];
+    _timing: AnalyticsTiming;
+}
+interface AnalyticsUserSearchResponse {
+    query: string;
+    limit: number;
+    results: AnalyticsUserSummary[];
+}
+interface AnalyticsUserDetailResponse {
+    user: {
+        user_ulid: string;
+        email: string | null;
+        name: string | null;
+    };
+    stats: {
+        first_seen: string | null;
+        last_active: string | null;
+        total_events: number;
+        days_active: number;
+    };
+    events_by_action: Array<{
+        action: string;
+        event_count: number;
+        last_occurred: string;
+    }>;
+    events_by_feature: Array<{
+        feature: string;
+        event_count: number;
+        pct: number;
+    }>;
+    _timing: AnalyticsTiming;
+}
+interface AnalyticsUserSnapshotResponse {
+    snapshot: {
+        timestamp: string;
+        values: unknown;
+    } | null;
+    _timing: AnalyticsTiming;
+}
+interface AnalyticsEventRow {
+    timestamp: string;
+    user_ulid: string;
+    action: string;
+    feature: string;
+    route: string;
+    country: string;
+}
+interface AnalyticsEventsResponse {
+    page: number;
+    page_size: number;
+    total_rows: number;
+    rows: AnalyticsEventRow[];
+    _timing: AnalyticsTiming;
+}
+interface AnalyticsGroupedRow {
+    group_value: string;
+    raw_group_value: string;
+    events: number;
+    unique_users: number;
+}
+interface AnalyticsEventsGroupedResponse {
+    group_by: string;
+    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;
+    source: string;
+    status_class: string;
+    total: number;
+    daily: Array<{
+        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;
+    errorRate: number;
+    medianDurationMs: number;
+    p95DurationMs: number;
+}
+interface AnalyticsIntegrationMetricsResponse {
+    windowDays: number;
+    integrations: AnalyticsIntegrationMetric[];
+    _timing: AnalyticsTiming;
+}
+interface WorkflowAnalyticsSummary {
+    workflowKey: string;
+    runs: number;
+    successRate: number;
+    medianDurationMs: number;
+    p95: number;
+    totalTokens: number;
+}
+interface TopWorkflowsResponse {
+    windowDays: number;
+    limit: number;
+    workflows: WorkflowAnalyticsSummary[];
+    _timing: AnalyticsTiming;
+}
+interface PromptAnalyticsSummary {
+    promptKey: string;
+    executions: number;
+    medianDurationMs: number;
+    p95DurationMs: number;
+    totalTokens: number;
+}
+interface TopPromptsResponse {
+    windowDays: number;
+    limit: number;
+    prompts: PromptAnalyticsSummary[];
+    _timing: AnalyticsTiming;
+}
+/**
+ * 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`.
+ */
+export interface DatabaseBatchOperation {
+    op: "save" | "patch" | "delete";
+    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();
+    private ensureAuthenticated;
+    private refreshToken;
+    request<T = any>(path: string, options?: RequestInit): Promise<T>;
+    get<T = any>(path: string, params?: Record<string, any>): Promise<T>;
+    post<T = any>(path: string, body?: any): Promise<T>;
+    put<T = any>(path: string, body?: any): Promise<T>;
+    patch<T = any>(path: string, body?: any): Promise<T>;
+    delete<T = any>(path: string): Promise<T>;
+    listApps(): Promise<{
+        apps: Array<{
+            id: string;
+            name: string;
+            role?: string;
+        }>;
+    }>;
+    createApp(data: {
+        name: string;
+        initialAdminEmail?: string;
+    }): Promise<any>;
+    getApp(appId: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    deleteApp(appId: string): Promise<void>;
+    getAppSettings(appId: string): Promise<any>;
+    updateAppSettings(appId: string, settings: any): Promise<any>;
+    addUserByEmail(appId: string, data: {
+        email: string;
+        role?: string;
+    }): Promise<any>;
+    mintTestJwt(appId: string, userId: string, role?: string): Promise<any>;
+    rebuildUserSearchText(appId: string): Promise<{
+        count: number;
+    }>;
+    listUsers(appId: string, params?: {
+        name?: string;
+        email?: string;
+        userId?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        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>;
+    listAppAdmins(appId: string): Promise<any[]>;
+    addAppAdmin(appId: string, data: {
+        adminEmail: string;
+        role?: string;
+        sendEmail?: boolean;
+        loginUrl?: string;
+    }): Promise<any>;
+    removeAppAdmin(appId: string, adminId: string): Promise<any>;
+    listAppAdminInvitations(appId: string): Promise<any[]>;
+    deleteAppAdminInvitation(appId: string, invitationId: string): Promise<any>;
+    transferDocumentOwnership(appId: string, documentId: string, newOwnerId: string): Promise<void>;
+    listInvitations(appId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string;
+        hasMore?: boolean;
+        /** @deprecated Alias of `nextCursor` (#1316). */
+        cursor?: string;
+    }>;
+    createInvitation(appId: string, data: {
+        email: string;
+        role: "admin" | "member";
+        expiresInDays?: number;
+        sendEmail?: boolean;
+        note?: string;
+    }): Promise<any>;
+    deleteInvitation(appId: string, invitationId: string): Promise<void>;
+    listWaitlist(appId: string): Promise<any[]>;
+    inviteWaitlistEntry(appId: string, waitlistId: string, options?: {
+        sendEmail?: boolean;
+        signupUrl?: string;
+    }): Promise<any>;
+    bulkInviteWaitlist(appId: string, payload: {
+        waitlistIds?: string[];
+        count?: number;
+        sendEmail?: boolean;
+        signupUrl?: string;
+    }): Promise<any>;
+    removeWaitlistEntry(appId: string, waitlistId: string): Promise<void>;
+    listDeferredGrants(appId: string, params?: {
+        type?: string;
+        email?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        grants: any[];
+        nextCursor?: string | null;
+        hasMore?: boolean;
+    }>;
+    revokeDeferredGrant(appId: string, deferredId: string, type: string): Promise<any>;
+    listIntegrations(appId: string, params?: {
+        status?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string | null;
+    }>;
+    /** 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;
+        status?: string;
+        from?: string;
+        to?: string;
+        source?: "user" | "admin" | "test" | "workflow";
+    }): Promise<any[]>;
+    listWorkflowRunIntegrationLogs(appId: string, runId: string, params?: {
+        limit?: number;
+    }): Promise<any[]>;
+    listAppSecrets(appId: string): Promise<any[]>;
+    createAppSecret(appId: string, payload: {
+        key: string;
+        value: string;
+        summary?: string;
+    }): Promise<any>;
+    updateAppSecret(appId: string, secretId: string, payload: {
+        value?: string;
+        summary?: string;
+    }): Promise<any>;
+    upsertAppSecret(appId: string, key: string, payload: {
+        value: string;
+        summary?: string;
+    }): Promise<any>;
+    deleteAppSecret(appId: string, secretId: string): Promise<any>;
+    listAppConfigVars(appId: string): Promise<any[]>;
+    upsertAppConfigVar(appId: string, key: string, payload: {
+        value: string;
+        summary?: string;
+    }, expectedModifiedAt?: string, options?: {
+        expectNotExists?: boolean;
+    }): Promise<any>;
+    deleteAppConfigVar(appId: string, key: string, expectedModifiedAt?: string): Promise<any>;
+    listWebhooks(appId: string, params?: {
+        status?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string | null;
+    }>;
+    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>;
+    /**
+     * 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;
+        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
+     * 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`.
+     */
+    listConnections(appId: string, selector: {
+        documentId?: string;
+        userId?: string;
+        databaseId?: string;
+    }, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: unknown[];
+        nextCursor?: string | null;
+    }>;
+    listSessions(appId: string, userId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: unknown[];
+        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[];
+    }>;
+    getLockStatus(appId: string, key: string): Promise<any>;
+    acquireLock(appId: string, key: string, ttlMs: number): Promise<any>;
+    releaseLock(appId: string, key: string, handleId: string): Promise<any>;
+    listCronTriggers(appId: string): Promise<{
+        items: any[];
+    }>;
+    getCronTrigger(appId: string, triggerId: string): Promise<any>;
+    createCronTrigger(appId: string, payload: any): Promise<any>;
+    updateCronTrigger(appId: string, triggerId: string, payload: any): 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[];
+    }>;
+    getIteration(appId: string, iterationName: string): Promise<any>;
+    resetIteration(appId: string, iterationName: string): Promise<any>;
+    readResourceMetadata(appId: string, resourceType: string, resourceId: string, category: string): Promise<any>;
+    writeResourceMetadata(appId: string, resourceType: string, resourceId: string, category: string, data: Record<string, any>): Promise<any>;
+    batchReadResourceMetadata(appId: string, requests: Array<{
+        resourceType: string;
+        resourceId: string;
+        categories: string[];
+    }>): Promise<{
+        results: any[];
+    }>;
+    /**
+     * List every stored metadata category on one resource (issue #1402 — debug
+     * tooling). The CLI authenticates as a console admin, so the app-level
+     * owner/admin bypass returns every category regardless of its readRule.
+     */
+    listResourceMetadata(appId: string, resourceType: string, resourceId: string): Promise<{
+        resourceType: string;
+        resourceId: string;
+        categories: Array<{
+            category: string;
+            data: Record<string, any>;
+            schemaVersion: number | null;
+        }>;
+    }>;
+    /**
+     * Delete one resource's metadata for one category (issue #1402 — debug
+     * tooling). Idempotent: deleting an absent item succeeds with
+     * `deleted: false` rather than a 404.
+     */
+    deleteResourceMetadata(appId: string, resourceType: string, resourceId: string, category: string): Promise<{
+        resourceType: string;
+        resourceId: string;
+        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;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string | null;
+    }>;
+    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>;
+    /**
+     * 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;
+        configId?: string;
+    }): Promise<any>;
+    previewPrompt(appId: string, promptId: string, payload: {
+        variables: Record<string, any>;
+        configId?: string;
+    }): Promise<any>;
+    listPromptConfigs(appId: string, promptId: string): Promise<{
+        items: any[];
+    }>;
+    getPromptConfig(appId: string, promptId: string, configId: string): Promise<any>;
+    createPromptConfig(appId: string, promptId: string, payload: any): Promise<any>;
+    updatePromptConfig(appId: string, promptId: string, configId: string, payload: any): Promise<any>;
+    activatePromptConfig(appId: string, promptId: string, configId: string): Promise<any>;
+    duplicatePromptConfig(appId: string, promptId: string, configId: string, payload?: {
+        configName?: string;
+        description?: string;
+    }): Promise<any>;
+    listScripts(appId: string): Promise<{
+        items: any[];
+    }>;
+    getScript(appId: string, scriptId: string): Promise<any>;
+    /**
+     * List a script's versioned configs (the `ScriptConfig` rows). Each config
+     * is a distinct block version: `configId` is the stable version selector,
+     * `contentHash` is its content identity, and `status` reports whether it is
+     * `active`/`draft`/`archived`. The script header's `activeConfigId` names
+     * the live version. Used by `scripts configs list` and by the script test
+     * commands to run against a specific pinned version.
+     */
+    listScriptConfigs(appId: string, scriptId: string): Promise<{
+        items: any[];
+    }>;
+    createScript(appId: string, payload: {
+        name: string;
+        body: string;
+        description?: string;
+    }): Promise<any>;
+    /**
+     * Push a new body for an existing script by creating a new `ScriptConfig`
+     * and activating it (the prompt-model "edit → activate" flow). Referencing
+     * workflows pick up the new body on their next run with no fan-out. The
+     * config name is unique per script, so we mint a timestamped name.
+     */
+    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
+     * references by name — without it the server answers 409.
+     */
+    deleteScript(appId: string, scriptId: string, force?: boolean): Promise<void>;
+    getPromptSchema(appId: string, promptId: string): Promise<{
+        promptId: string;
+        promptKey: string;
+        displayName: string;
+        inputSchema: any;
+        inputVariables: string[];
+        outputSchema: any;
+        activeConfigId: string | null;
+        activeConfigName: string | null;
+    }>;
+    /**
+     * 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[];
+        expectedJsonSubset?: Record<string, any>;
+        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;
+        expectedJsonSubset?: Record<string, any> | null;
+        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<{
+        attachments: Array<{
+            filename: string;
+            contentType: string;
+            size: number;
+            r2Key: string;
+        }>;
+    }>;
+    uploadTestCaseAttachment(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string, filename: string, data: Buffer, contentType: string): Promise<{
+        success: boolean;
+        attachment: {
+            filename: string;
+            contentType: string;
+            size: number;
+            r2Key: string;
+        };
+    }>;
+    downloadTestCaseAttachment(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string, filename: string): Promise<{
+        data: Buffer;
+        contentType: string;
+    }>;
+    deleteTestCaseAttachment(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string, filename: string): Promise<{
+        success: boolean;
+        deleted: boolean;
+    }>;
+    executeBlockTest(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, payload: {
+        variables?: Record<string, any>;
+        testCaseId?: string;
+        configId?: string;
+        comparisonGroup?: string;
+    }): Promise<any>;
+    runAllTestCases(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, payload?: {
+        overrideConfigId?: string;
+        comparisonGroup?: string;
+        testCaseIds?: string[];
+    }): Promise<any>;
+    listTestRuns(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, params?: {
+        limit?: number;
+        comparisonGroup?: string;
+    }): Promise<{
+        items: any[];
+    }>;
+    listWorkflows(appId: string, params?: {
+        status?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string | null;
+    }>;
+    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>;
+    /**
+     * 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>;
+    previewWorkflow(appId: string, workflowId: string, payload: {
+        rootInput?: object;
+        meta?: object;
+        configId?: string;
+        useDraft?: boolean;
+        preferActive?: boolean;
+    }): Promise<{
+        instanceId: string;
+        usingDraft?: boolean;
+        source?: "config" | "active" | "draft" | null;
+        configName?: string | null;
+        configId?: string | null;
+        warning?: string;
+    }>;
+    getPreviewStatus(appId: string, workflowId: string, instanceId: string): Promise<any>;
+    listWorkflowRuns(appId: string, workflowId: string, params?: {
+        status?: string;
+        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[];
+    }>;
+    listWorkflowConfigs(appId: string, workflowId: string): Promise<{
+        items: any[];
+    }>;
+    getWorkflowConfig(appId: string, workflowId: string, configId: string): Promise<any>;
+    createWorkflowConfig(appId: string, workflowId: string, payload: {
+        configName: string;
+        description?: string;
+        steps: any[];
+        expressions?: {
+            cel?: Record<string, string>;
+        };
+    }): Promise<any>;
+    updateWorkflowConfig(appId: string, workflowId: string, configId: string, payload: {
+        configName?: string;
+        description?: string;
+        steps?: any[];
+        status?: string;
+        expressions?: {
+            cel?: Record<string, string>;
+        };
+    }): Promise<any>;
+    archiveWorkflowConfig(appId: string, workflowId: string, configId: string): Promise<any>;
+    activateWorkflowConfig(appId: string, workflowId: string, configId: string): Promise<any>;
+    duplicateWorkflowConfig(appId: string, workflowId: string, configId: string, payload?: {
+        configName?: string;
+    }): Promise<any>;
+    getAnalyticsTopUsers(appId: string, params?: {
+        windowDays?: number;
+        limit?: number;
+    }): Promise<AnalyticsTopUsersResponse>;
+    getAnalyticsIntegrationMetrics(appId: string, params?: {
+        windowDays?: number;
+    }): Promise<AnalyticsIntegrationMetricsResponse>;
+    getAnalyticsOverviewDau(appId: string): Promise<AnalyticsMetricResponse>;
+    getAnalyticsOverviewWau(appId: string): Promise<AnalyticsMetricResponse>;
+    getAnalyticsOverviewMau(appId: string): Promise<AnalyticsMetricResponse>;
+    getAnalyticsOverviewGrowth(appId: string, params?: {
+        windowDays?: number;
+    }): Promise<AnalyticsGrowthResponse>;
+    getAnalyticsDailyActive(appId: string, params?: {
+        windowDays?: number;
+    }): Promise<AnalyticsDailyActiveResponse>;
+    getAnalyticsRollingActive(appId: string, params?: {
+        windowDays?: number;
+    }): Promise<AnalyticsDailyActiveResponse>;
+    getAnalyticsCohortRetention(appId: string): Promise<AnalyticsCohortResponse>;
+    getAnalyticsUserSearch(appId: string, params: {
+        q: string;
+        limit?: number;
+    }): Promise<AnalyticsUserSearchResponse>;
+    getAnalyticsUserDetail(appId: string, userUlid: string): Promise<AnalyticsUserDetailResponse>;
+    getAnalyticsUserSnapshot(appId: string, userUlid: string): Promise<AnalyticsUserSnapshotResponse>;
+    getAnalyticsEvents(appId: string, params?: {
+        windowDays?: number;
+        page?: number;
+        [key: string]: any;
+    }): Promise<AnalyticsEventsResponse>;
+    getAnalyticsEventsGrouped(appId: string, params?: {
+        groupBy?: string;
+        windowDays?: number;
+        [key: string]: any;
+    }): Promise<AnalyticsEventsGroupedResponse>;
+    getAnalyticsErrorsGroups(appId: string, params?: {
+        windowDays?: number;
+        limit?: number;
+        [key: string]: any;
+    }): Promise<AnalyticsErrorsGroupsResponse>;
+    getAnalyticsTopWorkflows(appId: string, params?: {
+        windowDays?: number;
+        limit?: number;
+    }): Promise<TopWorkflowsResponse>;
+    getAnalyticsTopPrompts(appId: string, params?: {
+        windowDays?: number;
+        limit?: number;
+    }): Promise<TopPromptsResponse>;
+    listAllAdmins(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    searchAdminByEmail(email: string): Promise<any>;
+    getAdminApps(email: string): Promise<any>;
+    updateAdminSettings(adminId: string, data: {
+        appCreationLimit?: number;
+        disabled?: boolean;
+        role?: "admin" | "super-admin";
+    }): Promise<any>;
+    reindexAdmin(adminId: string): Promise<void>;
+    listAllAdminInvitations(): Promise<any[]>;
+    createGlobalAdminInvitation(data: {
+        email: string;
+        appCreationLimit?: number;
+        expiresInDays?: number;
+    }): Promise<any>;
+    deleteGlobalAdminInvitation(invitationId: string): Promise<void>;
+    listPromptCatalog(params?: {
+        status?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    getPromptCatalogItem(catalogId: string): Promise<any>;
+    createPromptCatalogItem(payload: any): Promise<any>;
+    updatePromptCatalogItem(catalogId: string, payload: any): Promise<any>;
+    deletePromptCatalogItem(catalogId: string): Promise<void>;
+    listIntegrationCatalog(params?: {
+        status?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<any>;
+    getIntegrationCatalogItem(catalogId: string): Promise<any>;
+    createIntegrationCatalogItem(payload: any): Promise<any>;
+    updateIntegrationCatalogItem(catalogId: string, payload: any): Promise<any>;
+    deleteIntegrationCatalogItem(catalogId: string): Promise<void>;
+    startBatchTests(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, payload?: {
+        comparisonGroup?: string;
+        overrideConfigId?: string;
+        testCaseIds?: string[];
+    }): Promise<{
+        batchId: string;
+        totalTests: number;
+        instanceIds: string[];
+        errors?: any[];
+    }>;
+    getBatchTestStatus(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, batchId: string): Promise<{
+        status: string;
+        batchId: string;
+        completed: number;
+        passed: number;
+        failed: number;
+        results: Array<{
+            testCaseId: string;
+            runId: string;
+            status: string;
+            verificationPassed: boolean;
+            durationMs?: number;
+            verificationDetails?: any;
+            startedAt?: string;
+            endedAt?: string;
+        }>;
+    }>;
+    cancelBatchTests(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, batchId: string, instanceIds: string[]): Promise<{
+        batchId: string;
+        terminated: string[];
+        errors?: any[];
+    }>;
+    getComparisonGroup(appId: string, group: string): Promise<{
+        comparisonGroup: string;
+        runs: any[];
+    }>;
+    listEmailTemplates(appId: string): Promise<{
+        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;
+    }, expectedModifiedAt?: string): Promise<EmailTemplateUpsertResult>;
+    deleteEmailTemplate(appId: string, emailType: string): Promise<{
+        success: boolean;
+    }>;
+    testEmailTemplate(appId: string, emailType: string, payload?: {
+        subject: string;
+        htmlBody: string;
+        textBody: string;
+    }): Promise<{
+        success: boolean;
+        sentTo: string;
+        error?: string;
+    }>;
+    createToken(appId: string, data: {
+        name: string;
+        ttl?: string;
+        userId?: string;
+    }): Promise<{
+        token: string;
+        tokenId: string;
+        name: string;
+        expiresAt: string | null;
+        createdAt: string;
+        warning: string;
+    }>;
+    listTokens(appId: string, params?: {
+        userId?: string;
+    }): Promise<Array<{
+        tokenId: string;
+        name: string;
+        userId: string;
+        expiresAt: string | null;
+        lastUsedAt: string | null;
+        createdAt: string;
+        createdBy: string;
+    }>>;
+    getToken(appId: string, tokenId: string): Promise<{
+        tokenId: string;
+        name: string;
+        userId: string;
+        expiresAt: string | null;
+        lastUsedAt: string | null;
+        createdAt: string;
+        createdBy: string;
+        revokedAt: string | null;
+    }>;
+    revokeToken(appId: string, tokenId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * 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;
+        metadata?: Record<string, any> | string;
+        initialMetadata?: Record<string, Record<string, unknown>>;
+    }): Promise<any>;
+    getDatabase(appId: string, databaseId: string): Promise<any>;
+    updateDatabase(appId: string, databaseId: string, data: Record<string, any>): Promise<any>;
+    deleteDatabase(appId: string, databaseId: string): Promise<void>;
+    /**
+     * Read a database's CEL context dict.
+     *
+     * The HTTP path stays `/metadata` because the wire field name is still
+     * `metadata`; only the client/CLI-facing helper names were reframed.
+     */
+    getDatabaseCelContext(appId: string, databaseId: string): Promise<any>;
+    /** Update a database's CEL context dict (merge with existing). */
+    updateDatabaseCelContext(appId: string, databaseId: string, celContext: Record<string, any>): Promise<any>;
+    /** @deprecated Use {@link getDatabaseCelContext} instead. */
+    getDatabaseMetadata(appId: string, databaseId: string): Promise<any>;
+    /** @deprecated Use {@link updateDatabaseCelContext} instead. */
+    updateDatabaseMetadata(appId: string, databaseId: string, metadata: Record<string, any>): Promise<any>;
+    listDatabasePermissions(appId: string, databaseId: string): Promise<any[]>;
+    addDatabaseManager(appId: string, databaseId: string, userId: string): Promise<any>;
+    removeDatabaseManager(appId: string, databaseId: string, userId: string): Promise<any>;
+    /** @deprecated Use {@link addDatabaseManager} instead. */
+    grantDatabasePermission(appId: string, databaseId: string, data: {
+        userId: string;
+        permission: "manager";
+    }): Promise<any>;
+    /** @deprecated Use {@link removeDatabaseManager} instead. */
+    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<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;
+        cursor?: string;
+        direction?: number;
+    }, token?: string, options?: {
+        timing?: boolean;
+    }): Promise<any>;
+    /**
+     * Execute a registered batch (bulk) database operation. Posts a chunk of
+     * items to the canonical `operations/:name/batch` endpoint (the same one the
+     * client library's `executeBatch` uses — NOT the deprecated `import-bulk`
+     * alias). Used by `databases import-csv`.
+     *
+     * @returns `{ imported, failed }` — DO-level write outcome counts. Per-item
+     *   validation/access failures abort the whole chunk with a 4xx (thrown).
+     */
+    executeBatch(appId: string, databaseId: string, operationName: string, batch: Array<{
+        params: Record<string, any>;
+    }>): Promise<{
+        imported: number;
+        failed: number;
+    }>;
+    /**
+     * Make a request using a specific JWT token instead of the CLI's credentials.
+     * Used for executing operations as a different user.
+     */
+    requestWithToken<T = any>(path: string, token: string, options?: RequestInit): Promise<T>;
+    listDatabaseIndexes(appId: string, databaseId: string, modelName?: string): Promise<any>;
+    registerDatabaseIndex(appId: string, databaseId: string, data: {
+        modelName: string;
+        fieldName: string;
+        fieldType: string;
+        unique?: boolean;
+    }): Promise<any>;
+    dropDatabaseIndex(appId: string, databaseId: string, data: {
+        modelName: string;
+        fieldName: string;
+    }): Promise<any>;
+    /**
+     * Issue #974: back-provision an existing database instance's schema-declared
+     * unique indexes by reading its type schema and registering any declared-but-
+     * missing unique index. Idempotent.
+     */
+    reindexDatabaseFromSchema(appId: string, databaseId: string): Promise<{
+        ok: boolean;
+        registered: number;
+        skipped?: boolean;
+        reason?: string;
+        databaseType?: string;
+    }>;
+    listDatabaseTypeConfigs(appId: string): Promise<any[]>;
+    getDatabaseTypeConfig(appId: string, databaseType: string): Promise<any>;
+    createDatabaseTypeConfig(appId: string, data: {
+        databaseType: string;
+        ruleSetId?: string | null;
+        triggers?: Record<string, any> | null;
+        metadataAccess?: string | null;
+        defaultAccess?: string | null;
+        autoPopulatedFields?: Record<string, any> | null;
+        timestamps?: Record<string, any> | null;
+        schema?: string | null;
+        metadataManifest?: any;
+    }, options?: {
+        dryRun?: boolean;
+    }): Promise<any>;
+    updateDatabaseTypeConfig(appId: string, databaseType: string, data: {
+        ruleSetId?: string | null;
+        triggers?: Record<string, any> | null;
+        metadataAccess?: string | null;
+        defaultAccess?: string | null;
+        autoPopulatedFields?: Record<string, any> | null;
+        timestamps?: Record<string, any> | null;
+        schema?: string | null;
+        pendingOpDeletes?: string[];
+        finalOpNames?: string[];
+        metadataManifest?: any;
+        pendingOpUpdates?: Array<{
+            name: string;
+            access?: string | null;
+            params?: Record<string, any> | null;
+        }>;
+        pendingOpUpserts?: Array<Record<string, any>>;
+    }, expectedModifiedAt?: string, options?: {
+        dryRun?: boolean;
+        acceptWarnings?: boolean;
+    }): Promise<any>;
+    deleteDatabaseTypeConfig(appId: string, databaseType: string, options?: {
+        force?: boolean;
+    }): Promise<any>;
+    /**
+     * Issue #666 Phase 3: ask the server to scaffold a TOML schema from
+     * existing ops + DO field introspection. Read-only — does NOT persist.
+     */
+    scaffoldDatabaseTypeSchema(appId: string, databaseType: string): Promise<{
+        schema: string;
+    }>;
+    listDatabaseTypeOperations(appId: string, databaseType: string): Promise<any[]>;
+    getDatabaseTypeOperation(appId: string, databaseType: string, name: string): Promise<any>;
+    createDatabaseTypeOperation(appId: string, databaseType: string, data: {
+        name: string;
+        type: string;
+        modelName: string;
+        access?: string | null;
+        definition: Record<string, any>;
+        params?: Record<string, any> | null;
+    }, options?: {
+        dryRun?: boolean;
+        schemaOverride?: string | null;
+        defaultAccess?: string | null;
+        metadataManifestOverride?: Record<string, any> | null;
+    }): Promise<any>;
+    updateDatabaseTypeOperation(appId: string, databaseType: string, name: string, data: Record<string, any>, expectedModifiedAt?: string, options?: {
+        dryRun?: boolean;
+        schemaOverride?: string | null;
+        metadataManifestOverride?: Record<string, any> | null;
+    }): Promise<any>;
+    deleteDatabaseTypeOperation(appId: string, databaseType: string, name: string): Promise<any>;
+    listDatabaseTypeSubscriptions(appId: string, databaseType: string): Promise<any[]>;
+    getDatabaseTypeSubscription(appId: string, databaseType: string, subscriptionKey: string): Promise<any>;
+    createDatabaseTypeSubscription(appId: string, databaseType: string, data: {
+        subscriptionKey: string;
+        displayName: string;
+        modelName: string;
+        filter: string;
+        access: string;
+        description?: string | null;
+        select?: string[] | null;
+        emit?: string[] | null;
+        params?: Record<string, any> | null;
+        status?: string;
+    }): 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;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string;
+        hasMore?: boolean;
+        /** @deprecated Alias of `nextCursor` (#1316). */
+        cursor?: string;
+    }>;
+    createGroup(appId: string, data: {
+        groupType: string;
+        groupId?: string;
+        name: string;
+        description?: string;
+    }): Promise<any>;
+    getGroup(appId: string, groupType: string, groupId: string): Promise<any>;
+    updateGroup(appId: string, groupType: string, groupId: string, data: {
+        name?: string;
+        description?: string;
+    }): Promise<any>;
+    deleteGroup(appId: string, groupType: string, groupId: string): Promise<any>;
+    listGroupMembers(appId: string, groupType: string, groupId: string, options?: {
+        include?: "profiles";
+    }): Promise<{
+        items: any[];
+        nextCursor?: string;
+        hasMore?: boolean;
+        /** @deprecated Alias of `nextCursor` (#1316). */
+        cursor?: string;
+    }>;
+    addGroupMember(appId: string, groupType: string, groupId: string, data: {
+        userId: string;
+    }): Promise<any>;
+    removeGroupMember(appId: string, groupType: string, groupId: string, userId: string): Promise<any>;
+    listGroupDocuments(appId: string, groupType: string, groupId: string): Promise<any[]>;
+    listUserMemberships(appId: string, userId: string): Promise<any[]>;
+    listDocumentGroupPermissions(appId: string, documentId: string): Promise<any[]>;
+    grantDocumentGroupPermission(appId: string, documentId: string, data: {
+        groupType: string;
+        groupId: string;
+        permission: string;
+    }): Promise<any>;
+    revokeDocumentGroupPermission(appId: string, documentId: string, groupType: string, groupId: string): Promise<any>;
+    listCollections(appId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string | null;
+    }>;
+    listAllCollections(appId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string | null;
+    }>;
+    createCollection(appId: string, data: {
+        name: string;
+        description?: string;
+        initialMetadata?: Record<string, Record<string, unknown>>;
+    }): Promise<any>;
+    getCollection(appId: string, collectionId: string): Promise<any>;
+    updateCollection(appId: string, collectionId: string, data: {
+        name?: string;
+        description?: string;
+    }): Promise<any>;
+    deleteCollection(appId: string, collectionId: string): Promise<any>;
+    listCollectionDocuments(appId: string, collectionId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string | null;
+    }>;
+    addCollectionDocument(appId: string, collectionId: string, data: {
+        documentId: string;
+    }): Promise<any>;
+    removeCollectionDocument(appId: string, collectionId: string, documentId: string): Promise<any>;
+    listCollectionsForDocument(appId: string, documentId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string | null;
+    }>;
+    getCollectionAccess(appId: string, collectionId: string): Promise<any>;
+    grantCollectionGroupPermission(appId: string, collectionId: string, data: {
+        groupType: string;
+        groupId: string;
+        permission: string;
+    }): Promise<any>;
+    revokeCollectionGroupPermission(appId: string, collectionId: string, groupType: string, groupId: string): Promise<any>;
+    addCollectionMember(appId: string, collectionId: string, data: {
+        userId: string;
+        permission: string;
+    }): Promise<any>;
+    removeCollectionMember(appId: string, collectionId: string, userId: string): Promise<any>;
+    listCollectionTypeConfigs(appId: string): Promise<any[]>;
+    getCollectionTypeConfig(appId: string, collectionType: string): Promise<any>;
+    createCollectionTypeConfig(appId: string, data: {
+        collectionType: string;
+        ruleSetId?: string;
+        metadataManifest?: any;
+    }): Promise<any>;
+    updateCollectionTypeConfig(appId: string, collectionType: string, data: {
+        ruleSetId?: string | null;
+        metadataManifest?: any;
+    }, expectedModifiedAt?: string): Promise<any>;
+    deleteCollectionTypeConfig(appId: string, collectionType: string): Promise<any>;
+    /**
+     * List all metadata category configs for an app. The route returns
+     * `{ configs: [...] }`; unwrap to a bare array to match the other
+     * `list*Configs` helpers.
+     */
+    listMetadataCategoryConfigs(appId: string): Promise<any[]>;
+    getMetadataCategoryConfig(appId: string, resourceType: string, category: string): Promise<any>;
+    /**
+     * Create or replace a metadata category config (idempotent upsert via the
+     * path-addressed PUT route). `resourceType` / `category` identify the config;
+     * the body carries `schema` / `readRule` / `writeRule` / `description`.
+     */
+    upsertMetadataCategoryConfig(appId: string, resourceType: string, category: string, data: {
+        schema: unknown;
+        readRule?: string | null;
+        writeRule?: string | null;
+        description?: string | null;
+        metadataManifest?: unknown;
+    }, 
+    /** 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
+     * `ResourceMetadata` value rows for the category are left behind and become
+     * unreachable (no query path from a category to its values). Delete the
+     * values first if you need them gone — an orphaned value row can't be
+     * removed through any surface once its config is gone. Returns
+     * `{ resourceType, category, deleted }`; a missing config is a 404.
+     */
+    deleteMetadataCategoryConfig(appId: string, resourceType: string, category: string): Promise<{
+        resourceType: string;
+        category: string;
+        deleted: boolean;
+    }>;
+    listRuleSets(appId: string, params?: {
+        resourceType?: string;
+    }): Promise<any[]>;
+    createRuleSet(appId: string, data: {
+        name: string;
+        resourceType: string;
+        rules: Record<string, any>;
+        description?: string;
+    }): Promise<any>;
+    getRuleSet(appId: string, ruleSetId: string): Promise<any>;
+    updateRuleSet(appId: string, ruleSetId: string, data: {
+        name?: string;
+        description?: string;
+        rules?: Record<string, any>;
+    }, expectedModifiedAt?: string): Promise<any>;
+    deleteRuleSet(appId: string, ruleSetId: string): Promise<any>;
+    getRuleSetSchema(appId: string): Promise<any>;
+    getRuleSetResourceTypes(appId: string): Promise<{
+        resourceTypes: string[];
+    }>;
+    testRuleSet(appId: string, ruleSetId: string, data: any): Promise<any>;
+    debugRuleSet(appId: string, data: any): Promise<any>;
+    listGroupTypeConfigs(appId: string): Promise<any[]>;
+    getGroupTypeConfig(appId: string, groupType: string): Promise<any>;
+    createGroupTypeConfig(appId: string, data: {
+        groupType: string;
+        ruleSetId?: string;
+        autoAddCreator?: boolean;
+        metadataManifest?: any;
+    }): Promise<any>;
+    updateGroupTypeConfig(appId: string, groupType: string, data: {
+        ruleSetId?: string | null;
+        autoAddCreator?: boolean;
+        metadataManifest?: any;
+    }, expectedModifiedAt?: string): Promise<any>;
+    deleteGroupTypeConfig(appId: string, groupType: string): Promise<any>;
+    exportDocumentState(appId: string, documentId: string): Promise<{
+        state: string;
+        byteLength: number;
+        documentId: string;
+    }>;
+    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;
+        tags?: string[];
+        createdBy?: string;
+    }): Promise<any>;
+    listDocumentPermissions(appId: string, documentId: string): Promise<any[]>;
+    grantDocumentPermission(appId: string, documentId: string, permissions: Array<{
+        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>;
+    listDocumentInvitations(appId: string, documentId: string): Promise<any[]>;
+    listDocumentBlobs(appId: string, documentId: string): Promise<any[]>;
+    downloadBlob(appId: string, documentId: string, blobId: string): Promise<Buffer>;
+    uploadBlob(appId: string, documentId: string, blobId: string, data: Buffer, meta: {
+        filename: string;
+        contentType: string;
+        sha256: string;
+    }): Promise<any>;
+    listDocumentAliases(appId: string, documentId: string): Promise<any[]>;
+    setDocumentAlias(appId: string, aliasScope: string, aliasKey: string, documentId: string, ownerUserId?: string, mustNotExist?: boolean): Promise<any>;
+    /**
+     * 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[]>;
+    /**
+     * 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";
+        modelName: string;
+        id: string;
+    }[]): Promise<any>;
+    listDatabaseUniqueConstraints(appId: string, databaseId: string): Promise<any[]>;
+    registerDatabaseUniqueConstraint(appId: string, databaseId: string, constraint: {
+        modelName: string;
+        constraintName: string;
+        fields: string[];
+    }): Promise<any>;
+    listBlobBuckets(appId: string): Promise<{
+        items: any[];
+    }>;
+    createBlobBucket(appId: string, payload: any): Promise<any>;
+    getBlobBucket(appId: string, bucketIdOrKey: string): Promise<any>;
+    updateBlobBucket(appId: string, bucketIdOrKey: string, payload: any): Promise<any>;
+    deleteBlobBucket(appId: string, bucketIdOrKey: string): Promise<any>;
+    listBucketBlobs(appId: string, bucketIdOrKey: string, params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string;
+        hasMore?: boolean;
+        /** @deprecated Alias of `nextCursor` (#1316). */
+        cursor?: string;
+    }>;
+    uploadBucketBlob(appId: string, bucketIdOrKey: string, data: Buffer, meta: {
+        filename: string;
+        contentType: string;
+        tags?: string[];
+    }): Promise<any>;
+    downloadBucketBlob(appId: string, bucketIdOrKey: string, blobId: string): Promise<Buffer>;
+    deleteBucketBlob(appId: string, bucketIdOrKey: string, blobId: string): Promise<any>;
+    deleteBucketBlobs(appId: string, bucketIdOrKey: string, blobIds: string[]): Promise<any>;
+    getBucketBlobSignedUrl(appId: string, bucketIdOrKey: string, blobId: string, expiresInSeconds?: number): Promise<any>;
+    getBucketBlobMetadata(appId: string, bucketIdOrKey: string, blobId: string): Promise<BlobInfo>;
+}
+export declare const apiClient: ApiClient;
+export {};