primitive-admin 1.0.63 → 1.0.64

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

@@ -1,4 +1,5 @@
 import { type ListEnvelope } from "./paginate.js";
+import { type GlobalAppRef, type WorkflowUsageReport } from "./workflow-usage.js";
 /**
  * Metadata for a single bucket blob, as returned by the metadata endpoint
  * `GET blob-buckets/:bucketId/blobs/:blobId/metadata`. Mirrors the published
@@ -41,6 +42,20 @@ export declare class ConflictError extends ApiError {
     expectedModifiedAt: string;
     constructor(message: string, serverModifiedAt: string, expectedModifiedAt: string, details?: Record<string, any>);
 }
+/**
+ * The `ApiError` for a non-OK response read by a raw `fetch` call (#3403).
+ *
+ * The blob methods and the two document-artifact transfers build their own
+ * `fetch` call, so they never reached `parseErrorResponse` and never carried a
+ * `code` — a download refusal surfaced as `response.statusText` and an upload
+ * refusal as the raw JSON body shown to the operator as the message. This
+ * routes them through the same parser every other call site uses while keeping
+ * their human prefixes.
+ *
+ * Named for the blob paths it was written for; every raw-`fetch` path in this
+ * file answers through it now.
+ */
+export declare function blobFailure(response: Response, prefix: string): Promise<ApiError>;
 /**
  * Parsed shape of a non-OK HTTP response body.
  *
@@ -211,17 +226,40 @@ interface AnalyticsUserSummary {
     firstSeen: string;
     lastSeen: string;
     eventCount: number;
+    /**
+     * When the user joined this app (#3127) — an ISO timestamp, or `null` when
+     * no event of theirs carries a server-stamped join time yet.
+     */
+    signedUpAt?: string | null;
+    /** The same instant as a `YYYY-MM-DD` UTC day, or `null`. */
+    signupDay?: string | null;
+}
+/**
+ * A `users.top` row. `firstSeen` is the user's first event ever, invariant
+ * under `windowDays`; `firstSeenInWindow` is the window-relative one (#3126).
+ * `users.search` rows carry no `firstSeenInWindow`: it queries the full
+ * retained range, so its `firstSeen` is already the all-time value.
+ */
+interface AnalyticsTopUserRow extends AnalyticsUserSummary {
+    firstSeenInWindow: string;
 }
 interface AnalyticsTopUsersResponse {
     windowDays: number;
     limit: number;
-    results: AnalyticsUserSummary[];
+    results: AnalyticsTopUserRow[];
     _timing: AnalyticsTiming;
 }
 interface AnalyticsUserSearchResponse {
     query: string;
     limit: number;
     results: AnalyticsUserSummary[];
+    /** #3127 — the signup window this answer was filtered to, `null` when none. */
+    signupStartDay?: string | null;
+    signupEndDay?: string | null;
+    /** The row offset this page started at. */
+    offset?: number;
+    /** True when more rows match than this page returned; page with `offset`. */
+    truncated?: boolean;
 }
 interface AnalyticsUserDetailResponse {
     user: {
@@ -257,6 +295,9 @@ interface AnalyticsUserSnapshotResponse {
 interface AnalyticsEventRow {
     timestamp: string;
     user_ulid: string;
+    /** Display name for `user_ulid` — the system principal's `System`, else
+     *  null. The id itself is unchanged (#3168). */
+    user_name: string | null;
     action: string;
     feature: string;
     route: string;
@@ -391,6 +432,15 @@ interface PromptAnalyticsSummary {
     medianDurationMs: number;
     p95DurationMs: number;
     totalTokens: number;
+    /**
+     * #3787 — how many of the window's executions reported a cost, and what they
+     * spent. `totalCost` / `avgCost` are `null` (never `0`) when none did, and
+     * `executionsWithCost < executions` means the figures cover part of the
+     * window.
+     */
+    executionsWithCost?: number;
+    totalCost?: number | null;
+    avgCost?: number | null;
 }
 interface TopPromptsResponse {
     windowDays: number;
@@ -451,8 +501,24 @@ export interface DatabaseBatchOperation {
  */
 export declare function normalizeDatabaseOperationResult(raw: unknown): unknown;
 export declare class ApiClient {
+    /**
+     * Loaded on first use (`ensureAuthenticated`), never in a constructor.
+     *
+     * There used to be an `apiClient` singleton constructed at MODULE scope, so
+     * a constructor body ran while `bin/primitive.ts` was still being imported —
+     * before its first `try`, and before any command had said whether it needed
+     * the project at all. `loadCredentials()` resolves the environment, so on a
+     * project still holding the pre-#3153 layout that read threw the stale-layout
+     * refusal out of module evaluation, where not even the `uncaughtException`
+     * handler can reach it: the user got Node's raw stack trace, and `guides
+     * get` — which reads nothing from the project — died with it (#3273). The
+     * singleton is gone (#3154, it had no callers) and the read stays lazy,
+     * which is what keeps that shape from coming back.
+     *
+     * Nothing is lost by waiting, and one thing is gained: a `login` earlier in
+     * the same process is visible to a later request.
+     */
     private credentials;
-    constructor();
     private ensureAuthenticated;
     private refreshToken;
     request<T = any>(path: string, options?: RequestInit): Promise<T>;
@@ -461,6 +527,34 @@ export declare class ApiClient {
     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>;
+    /**
+     * One page of the apps the caller can reach.
+     *
+     * The route paginates cursor-style (default pageSize=25, cap=100). This
+     * method used to walk the whole chain so `primitive apps list` could not
+     * truncate at 25 (#436); since #3646 the page boundary belongs to the
+     * caller instead — `apps list` declares `--limit`/`--cursor` and prints the
+     * `hasMore`/`nextCursor` the server reported, and the aggregate readers that
+     * really do mean "every app" call `listAllApps()`.
+     */
+    listAppsPage(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: Array<{
+            id: string;
+            name: string;
+            role?: string;
+        }>;
+        hasMore?: boolean;
+        nextCursor?: string | null;
+    }>;
+    /**
+     * Every app the caller can reach, cursor chain walked (#436).
+     *
+     * For readers that genuinely need the whole set — an app picker, a sweep —
+     * rather than the one page `apps list` prints.
+     */
     listApps(): Promise<{
         apps: Array<{
             id: string;
@@ -468,6 +562,22 @@ export declare class ApiClient {
             role?: string;
         }>;
     }>;
+    /**
+     * Every app on the server, not just the caller's own.
+     *
+     * Deliberately separate from `listApps()`, whose contract is "apps assigned
+     * to me" (`GET /admin/api/admins/me/apps`, backed by `admin.queryApps()`) —
+     * the contract every other command depends on. `analytics workflow-usage
+     * --all-apps` has to reach apps nobody is assigned to, which is the global
+     * route `GET /admin/api/apps` (`App.iterateAll()`), and that route
+     * identifies an app as `appId` rather than `id` (D3130-001).
+     *
+     * One drain of that route is lossy — its cursor re-scans `App.iterateAll()`
+     * from the start of each page, so a list that changes under it both repeats
+     * and drops rows — so the walk is the union of repeated drains
+     * (`drainAppsUntilConverged`, which carries the measurement).
+     */
+    listAllAppsGlobal(): Promise<GlobalAppRef[]>;
     createApp(data: {
         name: string;
         initialAdminEmail?: string;
@@ -495,8 +605,13 @@ export declare class ApiClient {
         cursor?: string;
     }): Promise<{
         items: any[];
+        hasMore?: boolean;
         nextCursor?: string | null;
     }>;
+    /**
+     * @deprecated Use {@link setUserAvailability} with `"disable"`
+     * (`PUT /admin/api/apps/:appId/users/:userId/disable`) instead (#518).
+     */
     removeUser(appId: string, userId: string): Promise<void>;
     /**
      * #2803 — take a user's access away, or give it back. Distinct from
@@ -569,6 +684,8 @@ export declare class ApiClient {
         limit?: number;
         cursor?: string;
     }): Promise<{
+        items: any[];
+        /** @deprecated Read `items`; `grants` is a legacy alias of it (#1982). */
         grants: any[];
         nextCursor?: string | null;
         hasMore?: boolean;
@@ -580,6 +697,7 @@ export declare class ApiClient {
         limit?: number;
     }): Promise<{
         items: any[];
+        hasMore?: boolean;
         nextCursor?: string | null;
     }>;
     /** Integration detail (#2631: `accessRule` is on the detail, not the list summary). */
@@ -609,7 +727,9 @@ export declare class ApiClient {
         status?: string;
         from?: string;
         to?: string;
-        source?: "user" | "admin" | "test" | "workflow";
+        source?: "user" | "admin" | "test" | "workflow" | "function";
+        /** #3691 — only the calls this run made, workflow run or function run. */
+        runId?: string;
     }): Promise<any[]>;
     listWorkflowRunIntegrationLogs(appId: string, runId: string, params?: {
         limit?: number;
@@ -643,6 +763,7 @@ export declare class ApiClient {
         limit?: number;
     }): Promise<{
         items: any[];
+        hasMore?: boolean;
         nextCursor?: string | null;
     }>;
     getWebhook(appId: string, webhookId: string): Promise<any>;
@@ -663,6 +784,176 @@ export declare class ApiClient {
      * and refused on every configuration write path.
      */
     setWebhookAvailability(appId: string, webhookId: string, action: "enable" | "disable"): Promise<any>;
+    listFunctions(appId: string): Promise<{
+        items: any[];
+    }>;
+    getFunction(appId: string, functionId: string): Promise<any>;
+    createFunction(appId: string, payload: any): Promise<any>;
+    updateFunction(appId: string, functionId: string, payload: any): Promise<any>;
+    /**
+     * Archive a function, or destroy it with `hard`. Archiving KEEPS the key
+     * reserved in the app's single key namespace; the hard delete is what
+     * releases it, destroys every config version and removes the R2 objects.
+     */
+    deleteFunction(appId: string, functionId: string, options?: {
+        hard?: boolean;
+    }): Promise<ArchiveEnvelope>;
+    /** #2803 — the operational verb pair for a server function. */
+    setFunctionAvailability(appId: string, functionId: string, action: "enable" | "disable"): Promise<any>;
+    /** Every config version of a function, oldest first. */
+    /**
+     * A function's runs, newest first (#3181).
+     *
+     * A function run has no `workflowId`, so no workflow runs listing can see
+     * it — this is the only surface that lists one. Cursor-paginated like the
+     * other admin listings.
+     */
+    listFunctionRuns(appId: string, functionId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string | null;
+    }>;
+    /**
+     * A function run's step trace — #3348.
+     *
+     * The function-scoped twin of `getWorkflowStepRuns`, and it answers with the
+     * same rows in the same shape: `workflows/:idOrKey/runs/...` resolves its
+     * first argument to a workflow DEFINITION, which a function id and a function
+     * key alike miss, so a durable run's steps needed a route that addresses the
+     * run by the function that owns it.
+     */
+    getFunctionStepRuns(appId: string, functionId: string, runId: string): Promise<{
+        items: any[];
+    }>;
+    /**
+     * End a function run that will not settle — #3348.
+     *
+     * `terminated: false` means the run had already settled and the route
+     * reported its outcome instead of overwriting it.
+     */
+    terminateFunctionRun(appId: string, functionId: string, runId: string): Promise<{
+        runId: string;
+        status: string;
+        terminated: boolean;
+        endedAt?: string | null;
+        instanceTerminated?: boolean;
+    }>;
+    /**
+     * A function's invocation records, newest first — #3287.
+     *
+     * The ADMIN route, beside the runs listing above and for the same reason:
+     * the CLI acts as an operator, not as a member of the app. The app-API twin
+     * (`functions.logs`) is what a FUNCTION reads through the SDK profile.
+     */
+    listFunctionLogs(appId: string, functionId: string, params?: {
+        limit?: number;
+        cursor?: string;
+        runId?: string;
+    }): Promise<{
+        items: any[];
+        nextCursor?: string | null;
+    }>;
+    /**
+     * One invocation record by its id — #3448, behind `functions logs
+     * --invocation <id>`.
+     *
+     * The id the invoke envelope answered with. A record that never existed,
+     * one of ANOTHER function, and one the seven-day TTL has expired all answer
+     * the same 404, which is what the listing's own filter promises.
+     */
+    getFunctionLog(appId: string, functionId: string, invocationId: string): Promise<any>;
+    /**
+     * One function run, RECONCILED against the engine — #3448, what
+     * `functions runs wait` polls.
+     *
+     * NOT the runs listing: that reports the STORED status, and a durable run's
+     * row stays `running` until something asks the engine, so a wait built on it
+     * would never settle.
+     */
+    getFunctionRun(appId: string, functionId: string, runId: string): Promise<{
+        status: any;
+        run: any;
+        slice?: any;
+    }>;
+    /**
+     * The operator's own APP user — #3448 D3448-009.
+     *
+     * `getMe()` reads the ADMIN profile (`/admin/api/me`); this is the
+     * app-scoped route, which answers the app user `requireAppPermission`
+     * provisions for an admin and the `appRole` it gave them. That is the
+     * identity a `functions invoke` runs under by default, and printing it is
+     * how an operator knows their call bypassed the function's `access` gate.
+     */
+    getAppProfile(appId: string): Promise<{
+        userId: string;
+        email: string | null;
+        name?: string | null;
+        appRole: string;
+        appId: string;
+    }>;
+    /**
+     * Invoke a function and hand back the ANSWER, whatever its HTTP status —
+     * #3448 D3448-010.
+     *
+     * `request` throws an `ApiError` on any non-2xx, which is right for every
+     * other verb and wrong for this one: a 429 carries a `Retry-After` an
+     * operator needs to see, and a 409 mode mismatch carries the version's real
+     * mode. Rendering those from an exception means re-deriving what the server
+     * already said. So this returns the envelope with its status and its retry
+     * hint, and throws only when the request did not complete at all.
+     *
+     * `bearer` is the `--user` path's minted token; absent, the CLI's own
+     * credentials. `mode` is ALWAYS sent (D3448-012): it is what makes the
+     * server, not the CLI, the authority on a wrong verb.
+     */
+    invokeFunction(appId: string, functionKey: string, body: Record<string, unknown>, options?: {
+        bearer?: string;
+        asSystem?: boolean;
+        /**
+         * Which runtime this call means — #3482. The ROUTE is the selector:
+         * `POST functions/{key}` runs the function inside the request and
+         * `POST functions/{key}/start` runs it as a task. The admin-only system
+         * door is ONE route for both, so `--as system` keeps naming its runtime
+         * in the body (F-3482-007); phase 7's rename may fold it.
+         */
+        runtime?: "request" | "task";
+    }): Promise<{
+        httpStatus: number;
+        retryAfterSeconds: number | null;
+        body: any;
+    }>;
+    /**
+     * A function's versions, newest first (#3462).
+     *
+     * Paging is opt-in on the server: with no `limit` and no `cursor` every
+     * version comes back, which is what this method did before paging existed and
+     * what an already-installed CLI still asks for. A caller that passes either
+     * gets the shared `{ items, hasMore, nextCursor }` page.
+     */
+    listFunctionConfigs(appId: string, functionId: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        hasMore: boolean;
+        nextCursor?: string | null;
+    }>;
+    /**
+     * Point the function at one of its OWN existing versions (#3462). Creates no
+     * version; the activated version's capabilities, limits and triggers apply
+     * from the next call.
+     */
+    activateFunctionConfig(appId: string, functionId: string, configId: string): Promise<any>;
+    getFunctionConfig(appId: string, functionId: string, configId: string): Promise<any>;
+    /**
+     * The stored envelope: the authored TOML bytes, every source file and the
+     * built bundle, all base64. This is what `config pull` writes back verbatim.
+     */
+    getFunctionConfigEnvelope(appId: string, functionId: string, configId: string): Promise<any>;
+    /** Push a config version. The server verifies `contentHash` itself. */
+    pushFunctionConfig(appId: string, functionId: string, payload: any): 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). */
@@ -696,6 +987,7 @@ export declare class ApiClient {
         cursor?: string;
     }): Promise<{
         items: unknown[];
+        hasMore?: boolean;
         nextCursor?: string | null;
     }>;
     listSessions(appId: string, userId: string, params?: {
@@ -703,8 +995,27 @@ export declare class ApiClient {
         cursor?: string;
     }): Promise<{
         items: unknown[];
+        hasMore?: boolean;
         nextCursor?: string | null;
     }>;
+    /**
+     * One page of admin sessions (#3885): the caller's own, or — for a
+     * super-admin — the admin `adminId` names.
+     */
+    listAdminSessions(params?: {
+        adminId?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: unknown[];
+        hasMore?: boolean;
+        nextCursor?: string | null;
+    }>;
+    /** Revoke an admin session (idempotent). */
+    revokeAdminSession(sessionId: string): Promise<{
+        sessionId: string;
+        revokedAt: string;
+    }>;
     testWebhook(appId: string, webhookId: string, payload?: any): Promise<any>;
     /**
      * Run a webhook's configured verifier over headers and a body captured from
@@ -723,7 +1034,11 @@ export declare class ApiClient {
         locks: any[];
     }>;
     getLockStatus(appId: string, key: string): Promise<any>;
-    acquireLock(appId: string, key: string, ttlMs: number): Promise<any>;
+    /**
+     * #3562 — `owner` is sent only when one was given, so a call that names none
+     * composes byte for byte the body it always did.
+     */
+    acquireLock(appId: string, key: string, ttlMs: number, owner?: string): Promise<any>;
     releaseLock(appId: string, key: string, handleId: string): Promise<any>;
     listCronTriggers(appId: string): Promise<{
         items: any[];
@@ -798,6 +1113,7 @@ export declare class ApiClient {
         cursor?: string;
     }): Promise<{
         items: any[];
+        hasMore?: boolean;
         nextCursor?: string | null;
     }>;
     getPrompt(appId: string, promptId: string): Promise<any>;
@@ -897,6 +1213,7 @@ export declare class ApiClient {
         cursor?: string;
     }): Promise<{
         items: any[];
+        hasMore?: boolean;
         nextCursor?: string;
     }>;
     getTestCase(appId: string, blockType: "prompt" | "integration" | "workflow" | "script", blockId: string, testCaseId: string): Promise<any>;
@@ -975,9 +1292,20 @@ export declare class ApiClient {
         cursor?: string;
     }): Promise<{
         items: any[];
+        hasMore?: boolean;
         nextCursor?: string | null;
     }>;
     getWorkflow(appId: string, workflowId: string): Promise<any>;
+    /**
+     * One app's workflow step usage report (#3132).
+     *
+     * `windowDays` is omitted from the query when the caller did not ask for a
+     * window, so the server applies its own default rather than the CLI
+     * restating it on the wire.
+     */
+    getWorkflowUsage(appId: string, params?: {
+        windowDays?: number;
+    }): Promise<WorkflowUsageReport>;
     createWorkflow(appId: string, payload: any): Promise<any>;
     updateWorkflow(appId: string, workflowId: string, payload: any, expectedModifiedAt?: string): Promise<any>;
     /**
@@ -1108,8 +1436,15 @@ export declare class ApiClient {
     }): Promise<AnalyticsDailyActiveResponse>;
     getAnalyticsCohortRetention(appId: string): Promise<AnalyticsCohortResponse>;
     getAnalyticsUserSearch(appId: string, params: {
-        q: string;
+        q?: string;
         limit?: number;
+        /** #3127 — one UTC calendar day, `YYYY-MM-DD`. */
+        signupDay?: string;
+        /** #3127 — an inclusive range of at most 90 UTC calendar days. */
+        signupStartDay?: string;
+        signupEndDay?: string;
+        /** #3127 — row offset, accepted only with a signup filter. */
+        offset?: number;
     }): Promise<AnalyticsUserSearchResponse>;
     getAnalyticsUserDetail(appId: string, userUlid: string): Promise<AnalyticsUserDetailResponse>;
     getAnalyticsUserSnapshot(appId: string, userUlid: string): Promise<AnalyticsUserSnapshotResponse>;
@@ -1136,10 +1471,32 @@ export declare class ApiClient {
         windowDays?: number;
         limit?: number;
     }): Promise<TopPromptsResponse>;
+    /**
+     * The signed-in admin's own profile, `role` included.
+     *
+     * The role is read from the server rather than from the cached credentials
+     * file: a role changed after login would otherwise let a stale local record
+     * decide an authorization question.
+     */
+    getMe(): Promise<{
+        adminId: string;
+        email: string;
+        name: string;
+        role: string;
+        createdAt?: string;
+    }>;
     listAllAdmins(params?: {
         limit?: number;
         cursor?: string;
-    }): Promise<any>;
+    }): Promise<{
+        items: any[];
+        /** @deprecated Read `items`; `admins` is a legacy alias of it (#1982). */
+        admins: any[];
+        hasMore?: boolean;
+        nextCursor: string | null;
+        /** @deprecated Read `nextCursor`; `cursor` is a legacy alias of it (#1316, #1982). */
+        cursor: string | null;
+    }>;
     searchAdminByEmail(email: string): Promise<any>;
     getAdminApps(email: string): Promise<any>;
     updateAdminSettings(adminId: string, data: {
@@ -1288,9 +1645,22 @@ export declare class ApiClient {
      * `options.owner` narrows the result to the databases that user created; the
      * server resolves it through the `databasesByCreator` index (#1965).
      */
+    /**
+     * One page of an app's databases (#3646).
+     *
+     * `databases list` used to walk the chain here. The route pages, so the page
+     * boundary belongs to the caller: the verb declares `--limit`/`--cursor` and
+     * prints what came back.
+     */
     listDatabases(appId: string, options?: {
         owner?: string;
-    }): Promise<any[]>;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        hasMore?: boolean;
+        nextCursor?: string | null;
+    }>;
     createDatabase(appId: string, data: {
         title: string;
         databaseType?: string;
@@ -1305,13 +1675,29 @@ export declare class ApiClient {
      *
      * The HTTP path stays `/metadata` because the wire field name is still
      * `metadata`; only the client/CLI-facing helper names were reframed.
+     *
+     * @deprecated Use resource metadata categories instead (`primitive metadata
+     * get database <id> <category>`, #1420, #1815).
      */
     getDatabaseCelContext(appId: string, databaseId: string): Promise<any>;
-    /** Update a database's CEL context dict (merge with existing). */
+    /**
+     * Update a database's CEL context dict (merge with existing).
+     *
+     * @deprecated Use resource metadata categories instead (`primitive metadata
+     * set database <id> <category>`, #1420, #1815).
+     */
     updateDatabaseCelContext(appId: string, databaseId: string, celContext: Record<string, any>): Promise<any>;
-    /** @deprecated Use {@link getDatabaseCelContext} instead. */
+    /**
+     * @deprecated Database CEL context is deprecated; use resource metadata
+     * categories instead (`primitive metadata get database <id> <category>`,
+     * #1420, #1815).
+     */
     getDatabaseMetadata(appId: string, databaseId: string): Promise<any>;
-    /** @deprecated Use {@link updateDatabaseCelContext} instead. */
+    /**
+     * @deprecated Database CEL context is deprecated; use resource metadata
+     * categories instead (`primitive metadata set database <id> <category>`,
+     * #1420, #1815).
+     */
     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>;
@@ -1445,6 +1831,10 @@ export declare class ApiClient {
         databaseType: string;
         ruleSetId?: string | null;
         triggers?: Record<string, any> | null;
+        /**
+         * @deprecated The TOML `type.celContextAccess` expression. Use resource
+         * metadata categories instead (#1420, #1815).
+         */
         metadataAccess?: string | null;
         defaultAccess?: string | null;
         autoPopulatedFields?: Record<string, any> | null;
@@ -1457,6 +1847,10 @@ export declare class ApiClient {
     updateDatabaseTypeConfig(appId: string, databaseType: string, data: {
         ruleSetId?: string | null;
         triggers?: Record<string, any> | null;
+        /**
+         * @deprecated The TOML `type.celContextAccess` expression. Use resource
+         * metadata categories instead (#1420, #1815).
+         */
         metadataAccess?: string | null;
         defaultAccess?: string | null;
         autoPopulatedFields?: Record<string, any> | null;
@@ -1545,8 +1939,18 @@ export declare class ApiClient {
         description?: string;
     }): Promise<any>;
     deleteGroup(appId: string, groupType: string, groupId: string): Promise<any>;
+    /**
+     * One page of a group's members.
+     *
+     * The route paginates cursor-style (no default limit, cap 200) and reports
+     * the boundary, so `groups members list` carries `--limit`/`--cursor` and
+     * forwards them (#3646) rather than printing a first page that claims to be
+     * the whole membership.
+     */
     listGroupMembers(appId: string, groupType: string, groupId: string, options?: {
         include?: "profiles";
+        limit?: number;
+        cursor?: string;
     }): Promise<{
         items: any[];
         nextCursor?: string;
@@ -1572,6 +1976,7 @@ export declare class ApiClient {
         cursor?: string;
     }): Promise<{
         items: any[];
+        hasMore?: boolean;
         nextCursor?: string | null;
     }>;
     listAllCollections(appId: string, params?: {
@@ -1579,12 +1984,26 @@ export declare class ApiClient {
         cursor?: string;
     }): Promise<{
         items: any[];
+        hasMore?: boolean;
         nextCursor?: string | null;
     }>;
     createCollection(appId: string, data: {
         name: string;
         description?: string;
+        /**
+         * Which rule set governs the collection, and which context it belongs
+         * to. Both are immutable after creation, so a migration has to send them
+         * with the create or never (#3643).
+         */
+        collectionType?: string;
+        contextId?: string;
         initialMetadata?: Record<string, Record<string, unknown>>;
+        /**
+         * The app user to create the collection FOR (#3641). Honored only for
+         * admin-token callers; an app-user token has it ignored and creates as
+         * itself, exactly as `createDocument`'s does.
+         */
+        createdBy?: string;
     }): Promise<any>;
     getCollection(appId: string, collectionId: string): Promise<any>;
     updateCollection(appId: string, collectionId: string, data: {
@@ -1597,6 +2016,7 @@ export declare class ApiClient {
         cursor?: string;
     }): Promise<{
         items: any[];
+        hasMore?: boolean;
         nextCursor?: string | null;
     }>;
     addCollectionDocument(appId: string, collectionId: string, data: {
@@ -1710,7 +2130,45 @@ export declare class ApiClient {
         byteLength: number;
         documentId: string;
     }>;
+    /**
+     * The export chain of a large document (#2816, behavior 20): the latest
+     * completed snapshot, the sealed overlays after its epoch, and the open
+     * epoch's overlay inline. Every other artifact arrives as an expiring
+     * signature, read through {@link downloadDocumentArtifact}.
+     */
+    exportDocumentChain(appId: string, documentId: string): Promise<any>;
+    /**
+     * Read one granted artifact of a large document.
+     *
+     * The path comes from the chain and is origin-relative — the room is a
+     * Durable Object and has no reliable idea which host the caller reached it
+     * through — and the signature in it is the whole authorization, so no key is
+     * ever composed here.
+     */
+    downloadDocumentArtifact(_appId: string, grantedPath: string): Promise<Buffer>;
     importDocumentState(appId: string, documentId: string, stateBase64: string): Promise<any>;
+    /**
+     * Upload one artifact of a large document's import chain (#2816,
+     * behavior 20).
+     *
+     * The bytes travel raw and unmodified: the manifest's digest is over the
+     * STORED bytes, so re-encoding a chunk here would fail its own verification
+     * on install. The query says which artifact it is — the server derives the
+     * key from the document it belongs to, so nothing here composes one.
+     */
+    uploadDocumentChainArtifact(appId: string, documentId: string, query: Record<string, string | number>, body: Buffer): Promise<any>;
+    /** Start installing an uploaded chain (#2816, behavior 20). */
+    installDocumentChain(appId: string, documentId: string, plan: {
+        installId?: string;
+        base: {
+            epoch: number;
+            buildId: string;
+        } | null;
+        overlays: number[];
+        currentEpoch: number;
+    }): Promise<any>;
+    /** How far a document's chain install has got (#2816, behavior 20). */
+    getDocumentChainInstall(appId: string, documentId: string): Promise<any>;
     getDocument(appId: string, documentId: string): Promise<any>;
     /**
      * Delete a document and everything hanging off it (#2756). The server route
@@ -1726,6 +2184,16 @@ export declare class ApiClient {
      * describe`. Reuses the existing `GET documents/:id/schema` endpoint.
      */
     getDocumentSchema(appId: string, documentId: string): Promise<any>;
+    /**
+     * The `documentFormat` a records call states, as a query string to APPEND to
+     * a path (#3764).
+     *
+     * `post`, `patch` and `delete` take no params object — only `get` does — so
+     * for every verb but the reads the parameter rides the path. Empty when the
+     * caller states nothing, so an unparameterised call's URL is byte-identical
+     * to what it was.
+     */
+    private documentFormatQuery;
     /**
      * Query records in a document model (issue #1964 Phase 3). Reuses the
      * server-side `GET documents/:id/records/:model` endpoint, which runs
@@ -1740,12 +2208,15 @@ export declare class ApiClient {
         filter?: Record<string, any>;
         limit?: number;
         cursor?: string;
+        /** #3764 — the format the caller believes this document has. */
+        documentFormat?: 1 | 2;
     }): 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>;
+        documentFormat?: 1 | 2;
     }): Promise<{
         count: number;
     }>;
@@ -1766,6 +2237,8 @@ export declare class ApiClient {
         }[];
         groupBy?: string[];
         filter?: Record<string, any>;
+    }, extra?: {
+        documentFormat?: 1 | 2;
     }): Promise<{
         result: unknown;
     }>;
@@ -1774,6 +2247,70 @@ export declare class ApiClient {
      * record/model/blob counts, approximate size, and last-modified timestamp.
      */
     getDocumentStats(appId: string, documentId: string): Promise<any>;
+    /**
+     * A large document's snapshot builds, newest first, one page (#3432).
+     * `GET documents/:id/snapshots` → `{ items, hasMore, nextCursor? }`.
+     */
+    listDocumentSnapshots(appId: string, documentId: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
+    /**
+     * A large document's bulk-load sessions, newest first (#3434, criterion 9).
+     *
+     * Read-only, through the document read helper's app-admin arm — the same
+     * door the snapshot readers use. The action verb `documents ingest` is
+     * #3435's; these two are the operator's window onto what a session did.
+     */
+    listDocumentIngests(appId: string, documentId: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
+    /** One bulk-load session's status (#3434). */
+    getDocumentIngest(appId: string, documentId: string, sessionId: string): Promise<any>;
+    /** Open a bulk-load session on a large document (#3435, criterion 9). */
+    createDocumentIngest(appId: string, documentId: string): Promise<any>;
+    /**
+     * Upload one chunk of a bulk-load session's artifact (#3435).
+     *
+     * `multipart/form-data`: the eight descriptor fields as text parts and the
+     * gzipped bytes as one file part named `chunk`. No `Content-Type` is set on
+     * the request — fetch supplies the boundary, and a header written by hand
+     * would name one the body does not use.
+     */
+    uploadDocumentIngestChunk(appId: string, documentId: string, sessionId: string, chunk: {
+        model: string;
+        index: number;
+        rows: number;
+        bytes: number;
+        rawBytes: number;
+        sha256: string;
+        firstId: string;
+        lastId: string;
+        body: Buffer;
+    }): Promise<any>;
+    /** Freeze a session's manifest and hand it to the pipeline (#3435). */
+    commitDocumentIngest(appId: string, documentId: string, sessionId: string): Promise<any>;
+    /** Give a session up; allowed until the swap (#3435). */
+    abortDocumentIngest(appId: string, documentId: string, sessionId: string): Promise<any>;
+    /** One snapshot build with its verification result (#3432). */
+    getDocumentSnapshot(appId: string, documentId: string, buildId: string): Promise<any>;
+    /**
+     * Snapshot a large document now (#3666): seal the open epoch and start the
+     * base build that seal arms.
+     *
+     * Answers either the epoch that was sealed with the build it armed, or
+     * `{ sealed: false, reason: "empty" }` for an epoch that carried nothing.
+     */
+    requestDocumentSnapshot(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? }` —
@@ -1785,6 +2322,8 @@ export declare class ApiClient {
         id: string;
         data: Record<string, unknown>;
         options?: Record<string, unknown>;
+    }, extra?: {
+        documentFormat?: 1 | 2;
     }): Promise<{
         record: unknown;
     }>;
@@ -1796,6 +2335,8 @@ export declare class ApiClient {
     patchDocumentRecord(appId: string, documentId: string, modelName: string, recordId: string, body: {
         data: Record<string, unknown>;
         options?: Record<string, unknown>;
+    }, extra?: {
+        documentFormat?: 1 | 2;
     }): Promise<{
         record: unknown;
     }>;
@@ -1804,7 +2345,9 @@ export declare class ApiClient {
      * `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<{
+    deleteDocumentRecord(appId: string, documentId: string, modelName: string, recordId: string, extra?: {
+        documentFormat?: 1 | 2;
+    }): Promise<{
         deleted: boolean;
     }>;
     /**
@@ -1813,7 +2356,9 @@ export declare class ApiClient {
      * a validation failure commits nothing. Returns the facade's
      * `{ applied, added, updated, deleted }`.
      */
-    bulkDocumentRecords(appId: string, documentId: string, operations: Array<Record<string, unknown>>): Promise<{
+    bulkDocumentRecords(appId: string, documentId: string, operations: Array<Record<string, unknown>>, extra?: {
+        documentFormat?: 1 | 2;
+    }): Promise<{
         applied: number;
         added: Array<{
             model: string;
@@ -1830,6 +2375,7 @@ export declare class ApiClient {
         documentId?: string;
         tags?: string[];
         createdBy?: string;
+        documentFormat?: 1 | 2;
     }): Promise<any>;
     listDocumentPermissions(appId: string, documentId: string): Promise<any[]>;
     grantDocumentPermission(appId: string, documentId: string, permissions: Array<{
@@ -1849,10 +2395,24 @@ export declare class ApiClient {
         userId?: string;
         email?: string;
     }): Promise<any>;
+    /**
+     * Resolve a NAMED user's effective access to a document (#3658).
+     *
+     * The admin token is admitted to name a subject (it can already read every
+     * grant, group permission and membership the answer derives from), which is
+     * what makes this an operator read rather than a per-user one.
+     */
+    validateDocumentAccessForUser(appId: string, documentId: string, userId: 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[]>;
+    /**
+     * Pending deferred grants for a document (#2951 — replaces the removed
+     * legacy `GET /documents/:id/invitations`). Returns the `{ items }`
+     * envelope; rows are already filtered server-side to unresolved, unexpired
+     * grants whose app invitation is still outstanding.
+     */
+    listDocumentPendingInvitations(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: {
@@ -1878,7 +2438,62 @@ export declare class ApiClient {
             email?: string;
         };
     }>;
+    /**
+     * The admin inventory of one user's documents, followed to the end (#3399).
+     *
+     * The endpoint speaks the standard list contract (`{ items, hasMore,
+     * nextCursor }`) and caps a page, so one request reads one page: reading it
+     * would truncate a heavy user's inventory at the page size, which is the
+     * bug this issue is about with a smaller number on it. `documents list
+     * --user-id` and `documents export-all` both read this, and both mean "all
+     * of them". `paginateAll` carries the repeat-cursor and max-page guards, so
+     * a server handing out a non-advancing cursor fails loudly instead of
+     * looping forever.
+     *
+     * Tolerant of a pre-contract server, which answers with a bare
+     * `{ documents }` array and no cursor: that reads as a single page.
+     */
     listAdminDocuments(appId: string, userId: string): Promise<any[]>;
+    /**
+     * One page of the admin inventory of a user's documents (#3646).
+     *
+     * `documents list --user-id` prints exactly this — the page the caller's
+     * `--limit`/`--cursor` asked for, with the server's own page boundary
+     * beside it. `documents export-all`, which really does mean every document,
+     * keeps the walking `listAdminDocuments()` above.
+     *
+     * Tolerant of a pre-contract server, which answers with a bare
+     * `{ documents }` array and no cursor: that reads as a single page.
+     */
+    listAdminDocumentsPage(appId: string, userId: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: any[];
+        hasMore?: boolean;
+        nextCursor?: string | null;
+    }>;
+    /**
+     * The document `AppUser.rootDocId` points at, or null when the user has none
+     * yet (#3135). A user who is not a member of the app is a 404, which
+     * `documents import` reads as "this export has no target here" — distinct
+     * from "this user has no root document yet".
+     */
+    getUserRootDocument(appId: string, userId: string): Promise<{
+        rootDocId: string | null;
+    }>;
+    /**
+     * Get or create the user's root document (#3135).
+     *
+     * The server runs the same idempotent get-or-create sign-in uses, so this
+     * never mints a second root. `created` is true only when this call's claim
+     * won — an import must not report "created", or merge without `--overwrite`,
+     * for a root a concurrent sign-in minted first.
+     */
+    ensureUserRootDocument(appId: string, userId: string): Promise<{
+        rootDocId: string;
+        created: boolean;
+    }>;
     /**
      * Apply an ordered batch of record operations via `records/batch`.
      *
@@ -1932,5 +2547,4 @@ export declare class ApiClient {
     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 {};