primitive-admin 1.1.0-alpha.80 → 1.1.0-alpha.82

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

@@ -4,6 +4,13 @@ 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";
+/**
+ * Page size the admin per-user inventories are asked for (#3399).
+ *
+ * `MAX_LIST_LIMIT` on the server, so a heavy user's inventory is walked in the
+ * fewest round trips the contract allows; a larger value is clamped there.
+ */
+const ADMIN_INVENTORY_PAGE_SIZE = 100;
 export class ApiError extends Error {
     statusCode;
     code;
@@ -214,9 +221,9 @@ export class ApiClient {
      * 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` — the command that serves the very document the refusal names — 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.
+     * 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.
@@ -780,6 +787,28 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs`, params);
         return { items: result?.items ?? [], nextCursor: result?.nextCursor ?? 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.
+     */
+    async getFunctionStepRuns(appId, functionId, runId) {
+        const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs/${runId}/steps`);
+        return { items: result?.items ?? [] };
+    }
+    /**
+     * 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.
+     */
+    async terminateFunctionRun(appId, functionId, runId) {
+        return this.post(`/admin/api/apps/${appId}/functions/${functionId}/runs/${runId}/terminate`, {});
+    }
     /**
      * A function's invocation records, newest first — #3287.
      *
@@ -791,6 +820,93 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/logs`, params);
         return { items: result?.items ?? [], nextCursor: result?.nextCursor ?? 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.
+     */
+    async getFunctionLog(appId, functionId, invocationId) {
+        return this.get(`/admin/api/apps/${appId}/functions/${functionId}/logs/${invocationId}`);
+    }
+    /**
+     * 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.
+     */
+    async getFunctionRun(appId, functionId, runId) {
+        return this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs/${runId}`);
+    }
+    /**
+     * 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.
+     */
+    async getAppProfile(appId) {
+        return this.get(`/app/${appId}/api/me`);
+    }
+    /**
+     * 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.
+     */
+    async invokeFunction(appId, functionKey, body, options) {
+        const credentials = await this.ensureAuthenticated();
+        const path = options?.asSystem
+            ? `/app/${appId}/api/functions/${encodeURIComponent(functionKey)}/invoke-as-system`
+            : `/app/${appId}/api/functions/${encodeURIComponent(functionKey)}`;
+        const headers = {
+            Authorization: `Bearer ${options?.bearer ?? credentials.accessToken}`,
+            "Content-Type": "application/json",
+        };
+        // The CLI's own credentials reach an app-scoped route through the
+        // global-admin header; a minted user token does not need it and must not
+        // carry it.
+        if (!options?.bearer && credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const response = await fetchWithTLS(`${credentials.serverUrl}${path}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        const text = await response.text();
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // A body that is not JSON is still an answer; keep it readable.
+            parsed = { error: text };
+        }
+        const retryAfter = response.headers.get("retry-after");
+        const retryAfterSeconds = retryAfter && Number.isFinite(Number(retryAfter)) ? Number(retryAfter) : null;
+        return {
+            httpStatus: response.status,
+            retryAfterSeconds: retryAfterSeconds ??
+                (typeof parsed?.retryAfter === "number" ? parsed.retryAfter : null),
+            body: parsed,
+        };
+    }
     async listFunctionConfigs(appId, functionId) {
         const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/configs`);
         return { items: result?.items ?? [] };
@@ -2431,6 +2547,23 @@ export class ApiClient {
     async getDocumentStats(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/stats`);
     }
+    /**
+     * A large document's snapshot builds, newest first, one page (#3432).
+     * `GET documents/:id/snapshots` → `{ items, hasMore, nextCursor? }`.
+     */
+    async listDocumentSnapshots(appId, documentId, options = {}) {
+        const params = new URLSearchParams();
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options.cursor)
+            params.set("cursor", options.cursor);
+        const query = params.toString();
+        return this.get(`/app/${appId}/api/documents/${documentId}/snapshots${query ? `?${query}` : ""}`);
+    }
+    /** One snapshot build with its verification result (#3432). */
+    async getDocumentSnapshot(appId, documentId, buildId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/snapshots/${encodeURIComponent(buildId)}`);
+    }
     /**
      * Create or replace a record in a document model (issue #1964 Phase 4).
      * `POST documents/:id/records/:model` with `{ id, data, options? }` —
@@ -2575,9 +2708,37 @@ export class ApiClient {
     async lookupUserByEmail(appId, email) {
         return this.get(`/app/${appId}/api/users/lookup`, { email });
     }
+    /**
+     * 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.
+     */
     async listAdminDocuments(appId, userId) {
-        const result = await this.get(`/admin/api/apps/${appId}/documents`, { userId });
-        return result?.documents || result || [];
+        return paginateAll(async (cursor) => {
+            const params = new URLSearchParams({
+                userId,
+                limit: String(ADMIN_INVENTORY_PAGE_SIZE),
+            });
+            if (cursor)
+                params.set("cursor", cursor);
+            const result = await this.get(`/admin/api/apps/${appId}/documents?${params.toString()}`);
+            return {
+                items: result?.items ?? result?.documents ?? [],
+                // #1316: prefer `nextCursor`; the deprecated `cursor` alias keeps a
+                // shipped CLI paginating against a server that still dual-emits.
+                nextCursor: result?.nextCursor ?? result?.cursor,
+            };
+        });
     }
     /**
      * The document `AppUser.rootDocId` points at, or null when the user has none