primitive-admin 1.1.0-alpha.73 → 1.1.0-alpha.74

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
@@ -212,10 +213,19 @@ interface AnalyticsUserSummary {
     lastSeen: string;
     eventCount: number;
 }
+/**
+ * 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 {
@@ -257,6 +267,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;
@@ -468,6 +481,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;
@@ -663,6 +692,48 @@ 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;
+    }>;
+    listFunctionConfigs(appId: string, functionId: string): Promise<{
+        items: 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). */
@@ -978,6 +1049,16 @@ export declare class ApiClient {
         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>;
     /**
@@ -1136,6 +1217,20 @@ 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;
@@ -1710,7 +1805,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
@@ -1830,6 +1963,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<{
@@ -1879,6 +2013,27 @@ export declare class ApiClient {
         };
     }>;
     listAdminDocuments(appId: string, userId: string): Promise<any[]>;
+    /**
+     * 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`.
      *

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

@@ -1,7 +1,9 @@
 import { loadCredentials, saveCredentials, isTokenExpiringSoon, } from "./config.js";
+import { getCurrentEnvNameSafe } from "./env-resolver.js";
 import { fetchWithTLS } from "./fetch.js";
 import { paginateAll, normalizeCliListEnvelope } from "./paginate.js";
 import { RefreshError, refreshAdminCredentials, } from "./refresh-admin-credentials.js";
+import { drainAppsUntilConverged, } from "./workflow-usage.js";
 export class ApiError extends Error {
     statusCode;
     code;
@@ -211,7 +213,15 @@ export class ApiClient {
             this.credentials = loadCredentials();
         }
         if (!this.credentials) {
-            throw new ApiError("Not logged in. Run 'bao-admin login' first.", 401);
+            // Name the environment when there is one (#1293). Before #3152 this case
+            // surfaced from `resolveAppId`, because an unauthenticated environment
+            // resolved no app at all; now the environment always names its app, so
+            // "not logged in" is only ever an auth failure, and it is reported here,
+            // once, for every command.
+            const envName = getCurrentEnvNameSafe();
+            throw new ApiError(envName
+                ? `Not logged in to environment "${envName}". Run 'primitive -e ${envName} login'.`
+                : "Not logged in. Run 'primitive login' first.", 401);
         }
         // Check if token needs refresh
         if (isTokenExpiringSoon(this.credentials)) {
@@ -345,8 +355,8 @@ export class ApiClient {
     async listApps() {
         // The server paginates cursor-style (default pageSize=25, cap=100). Historically
         // this method issued a single un-paginated GET and silently truncated to the
-        // first page, which broke `primitive use <app-id>` and `primitive apps list`
-        // for admins with more than 25 apps (see #436). Iterate every page.
+        // first page, which broke `primitive apps list` for admins with more than
+        // 25 apps (see #436). Iterate every page.
         const apps = await paginateAll(async (cursor) => {
             const qs = new URLSearchParams({ limit: "100" });
             if (cursor)
@@ -363,6 +373,40 @@ export class ApiClient {
         });
         return { apps };
     }
+    /**
+     * Every app on the server, not just the caller's own.
+     *
+     * Deliberately separate from `listApps()`, whose contract is "apps assigned
+     * to me" (`GET /admin/api/admins/me/apps`, backed by `admin.queryApps()`) —
+     * the contract every other command depends on. `analytics workflow-usage
+     * --all-apps` has to reach apps nobody is assigned to, which is the global
+     * route `GET /admin/api/apps` (`App.iterateAll()`), and that route
+     * identifies an app as `appId` rather than `id` (D3130-001).
+     *
+     * One drain of that route is lossy — its cursor re-scans `App.iterateAll()`
+     * from the start of each page, so a list that changes under it both repeats
+     * and drops rows — so the walk is the union of repeated drains
+     * (`drainAppsUntilConverged`, which carries the measurement).
+     */
+    async listAllAppsGlobal() {
+        const drainOnce = () => paginateAll(async (cursor) => {
+            const qs = new URLSearchParams({ limit: "100" });
+            if (cursor)
+                qs.set("cursor", cursor);
+            const resp = await this.get(`/admin/api/apps?${qs.toString()}`);
+            // `items` first, with the `apps` alias (#1316) as the fallback,
+            // exactly as `listApps()` reads its own envelope.
+            const rows = resp.items ?? (Array.isArray(resp.apps) ? resp.apps : []);
+            return {
+                items: rows.map((row) => ({
+                    appId: String(row.appId ?? row.id ?? ""),
+                    name: String(row.name ?? ""),
+                })),
+                nextCursor: resp.nextCursor ?? resp.cursor,
+            };
+        });
+        return drainAppsUntilConverged(drainOnce);
+    }
     async createApp(data) {
         return this.post("/admin/api/apps", data);
     }
@@ -678,6 +722,68 @@ export class ApiClient {
     async setWebhookAvailability(appId, webhookId, action) {
         return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/${action}`, {});
     }
+    // ── Server functions (#3179) ─────────────────────────────────────────
+    //
+    // The `functions` family mirrors workflows and scripts: a header with the
+    // gate and the entry, and append-only immutable config versions carrying the
+    // authored TOML bytes, the sources and the built bundle. The listing drains
+    // server-side, so it has no cursor.
+    async listFunctions(appId) {
+        const result = await this.get(`/admin/api/apps/${appId}/functions`);
+        return { items: result?.items ?? [] };
+    }
+    async getFunction(appId, functionId) {
+        return this.get(`/admin/api/apps/${appId}/functions/${functionId}`);
+    }
+    async createFunction(appId, payload) {
+        return this.post(`/admin/api/apps/${appId}/functions`, payload);
+    }
+    async updateFunction(appId, functionId, payload) {
+        return this.patch(`/admin/api/apps/${appId}/functions/${functionId}`, payload);
+    }
+    /**
+     * Archive a function, or destroy it with `hard`. Archiving KEEPS the key
+     * reserved in the app's single key namespace; the hard delete is what
+     * releases it, destroys every config version and removes the R2 objects.
+     */
+    async deleteFunction(appId, functionId, options) {
+        const query = options?.hard ? "?hard=true" : "";
+        return this.delete(`/admin/api/apps/${appId}/functions/${functionId}${query}`);
+    }
+    /** #2803 — the operational verb pair for a server function. */
+    async setFunctionAvailability(appId, functionId, action) {
+        return this.post(`/admin/api/apps/${appId}/functions/${functionId}/${action}`, {});
+    }
+    /** Every config version of a function, oldest first. */
+    /**
+     * A function's runs, newest first (#3181).
+     *
+     * A function run has no `workflowId`, so no workflow runs listing can see
+     * it — this is the only surface that lists one. Cursor-paginated like the
+     * other admin listings.
+     */
+    async listFunctionRuns(appId, functionId, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs`, params);
+        return { items: result?.items ?? [], nextCursor: result?.nextCursor ?? null };
+    }
+    async listFunctionConfigs(appId, functionId) {
+        const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/configs`);
+        return { items: result?.items ?? [] };
+    }
+    async getFunctionConfig(appId, functionId, configId) {
+        return this.get(`/admin/api/apps/${appId}/functions/${functionId}/configs/${configId}`);
+    }
+    /**
+     * The stored envelope: the authored TOML bytes, every source file and the
+     * built bundle, all base64. This is what `config pull` writes back verbatim.
+     */
+    async getFunctionConfigEnvelope(appId, functionId, configId) {
+        return this.get(`/admin/api/apps/${appId}/functions/${functionId}/configs/${configId}/envelope`);
+    }
+    /** Push a config version. The server verifies `contentHash` itself. */
+    async pushFunctionConfig(appId, functionId, payload) {
+        return this.post(`/admin/api/apps/${appId}/functions/${functionId}/configs`, payload);
+    }
     /** #2803 — the operational verb pair for a prompt (admin API). */
     async setPromptAvailability(appId, promptId, action) {
         return this.post(`/admin/api/apps/${appId}/prompts/${promptId}/${action}`, {});
@@ -1166,6 +1272,16 @@ export class ApiClient {
     async getWorkflow(appId, workflowId) {
         return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}`);
     }
+    /**
+     * One app's workflow step usage report (#3132).
+     *
+     * `windowDays` is omitted from the query when the caller did not ask for a
+     * window, so the server applies its own default rather than the CLI
+     * restating it on the wire.
+     */
+    async getWorkflowUsage(appId, params) {
+        return this.get(`/admin/api/apps/${appId}/workflows/usage`, params);
+    }
     async createWorkflow(appId, payload) {
         return this.post(`/admin/api/apps/${appId}/workflows`, payload);
     }
@@ -1327,6 +1443,16 @@ export class ApiClient {
     // ============================================
     // SUPER ADMIN: ADMINS
     // ============================================
+    /**
+     * The signed-in admin's own profile, `role` included.
+     *
+     * The role is read from the server rather than from the cached credentials
+     * file: a role changed after login would otherwise let a stale local record
+     * decide an authorization question.
+     */
+    async getMe() {
+        return this.get("/admin/api/me");
+    }
     async listAllAdmins(params) {
         const result = await this.get("/admin/api/admins", params);
         // #1316: prefer `nextCursor`; fall back to the deprecated `cursor` alias.
@@ -2133,9 +2259,79 @@ export class ApiClient {
     async exportDocumentState(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/export/state`);
     }
+    /**
+     * The export chain of a large document (#2816, behavior 20): the latest
+     * completed snapshot, the sealed overlays after its epoch, and the open
+     * epoch's overlay inline. Every other artifact arrives as an expiring
+     * signature, read through {@link downloadDocumentArtifact}.
+     */
+    async exportDocumentChain(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/export/chain`);
+    }
+    /**
+     * Read one granted artifact of a large document.
+     *
+     * The path comes from the chain and is origin-relative — the room is a
+     * Durable Object and has no reliable idea which host the caller reached it
+     * through — and the signature in it is the whole authorization, so no key is
+     * ever composed here.
+     */
+    async downloadDocumentArtifact(_appId, grantedPath) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}${grantedPath}`;
+        const response = await fetchWithTLS(url);
+        if (!response.ok) {
+            throw new ApiError(`Failed to download document artifact: ${response.statusText}`, response.status);
+        }
+        return Buffer.from(await response.arrayBuffer());
+    }
     async importDocumentState(appId, documentId, stateBase64) {
         return this.post(`/app/${appId}/api/documents/${documentId}/import/state`, { state: stateBase64 });
     }
+    /**
+     * Upload one artifact of a large document's import chain (#2816,
+     * behavior 20).
+     *
+     * The bytes travel raw and unmodified: the manifest's digest is over the
+     * STORED bytes, so re-encoding a chunk here would fail its own verification
+     * on install. The query says which artifact it is — the server derives the
+     * key from the document it belongs to, so nothing here composes one.
+     */
+    async uploadDocumentChainArtifact(appId, documentId, query, body) {
+        const credentials = await this.ensureAuthenticated();
+        const search = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            search.set(key, String(value));
+        }
+        const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}` +
+            `/import/chain/artifact?${search.toString()}`;
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+            "Content-Type": "application/octet-stream",
+        };
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const response = await fetchWithTLS(url, {
+            method: "POST",
+            headers,
+            body: body,
+        });
+        const result = await response.json().catch(() => ({}));
+        if (!response.ok) {
+            throw new ApiError(result?.error ||
+                `Failed to upload import artifact: ${response.statusText}`, response.status);
+        }
+        return result;
+    }
+    /** Start installing an uploaded chain (#2816, behavior 20). */
+    async installDocumentChain(appId, documentId, plan) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/import/chain`, plan);
+    }
+    /** How far a document's chain install has got (#2816, behavior 20). */
+    async getDocumentChainInstall(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/import/chain`);
+    }
     async getDocument(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}`);
     }
@@ -2352,6 +2548,26 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/documents`, { userId });
         return result?.documents || result || [];
     }
+    /**
+     * The document `AppUser.rootDocId` points at, or null when the user has none
+     * yet (#3135). A user who is not a member of the app is a 404, which
+     * `documents import` reads as "this export has no target here" — distinct
+     * from "this user has no root document yet".
+     */
+    async getUserRootDocument(appId, userId) {
+        return this.get(`/admin/api/apps/${appId}/users/${userId}/root-document`);
+    }
+    /**
+     * Get or create the user's root document (#3135).
+     *
+     * The server runs the same idempotent get-or-create sign-in uses, so this
+     * never mints a second root. `created` is true only when this call's claim
+     * won — an import must not report "created", or merge without `--overwrite`,
+     * for a root a concurrent sign-in minted first.
+     */
+    async ensureUserRootDocument(appId, userId) {
+        return this.post(`/admin/api/apps/${appId}/users/${userId}/root-document`, {});
+    }
     // ============================================
     // DATABASE EXPORT / IMPORT
     // ============================================