primitive-admin 1.1.0-alpha.81 → 1.1.0-alpha.83

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

@@ -753,6 +753,31 @@ export declare class ApiClient {
         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.
      *
@@ -763,13 +788,102 @@ export declare class ApiClient {
     listFunctionLogs(appId: string, functionId: string, params?: {
         limit?: number;
         cursor?: string;
+        runId?: string;
     }): Promise<{
         items: any[];
         nextCursor?: string | null;
     }>;
-    listFunctionConfigs(appId: string, functionId: string): Promise<{
+    /**
+     * 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
@@ -838,7 +952,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[];
@@ -1958,6 +2076,62 @@ 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>;
     /**
      * Create or replace a record in a document model (issue #1964 Phase 4).
      * `POST documents/:id/records/:model` with `{ id, data, options? }` —
@@ -2069,6 +2243,21 @@ 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[]>;
     /**
      * The document `AppUser.rootDocId` points at, or null when the user has none

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;
@@ -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,9 +820,125 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/logs`, 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 ?? [] };
+    /**
+     * 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 base = `/app/${appId}/api/functions/${encodeURIComponent(functionKey)}`;
+        const path = options?.asSystem
+            ? `${base}/invoke-as-system`
+            : options?.runtime === "task"
+                ? `${base}/start`
+                : base;
+        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,
+        };
+    }
+    /**
+     * 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.
+     */
+    async listFunctionConfigs(appId, functionId, options = {}) {
+        const query = new URLSearchParams();
+        if (options.limit !== undefined)
+            query.set("limit", String(options.limit));
+        if (options.cursor)
+            query.set("cursor", options.cursor);
+        const suffix = query.toString() ? `?${query.toString()}` : "";
+        const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/configs${suffix}`);
+        return {
+            items: result?.items ?? [],
+            hasMore: result?.hasMore === true,
+            nextCursor: result?.nextCursor ?? 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.
+     */
+    async activateFunctionConfig(appId, functionId, configId) {
+        return this.post(`/admin/api/apps/${appId}/functions/${functionId}/configs/${configId}/activate`, {});
     }
     async getFunctionConfig(appId, functionId, configId) {
         return this.get(`/admin/api/apps/${appId}/functions/${functionId}/configs/${configId}`);
@@ -885,8 +1030,16 @@ export class ApiClient {
     async getLockStatus(appId, key) {
         return this.post(`/app/${appId}/api/locks/status`, { key });
     }
-    async acquireLock(appId, key, ttlMs) {
-        return this.post(`/app/${appId}/api/locks/acquire`, { key, ttlMs });
+    /**
+     * #3562 — `owner` is sent only when one was given, so a call that names none
+     * composes byte for byte the body it always did.
+     */
+    async acquireLock(appId, key, ttlMs, owner) {
+        return this.post(`/app/${appId}/api/locks/acquire`, {
+            key,
+            ttlMs,
+            ...(owner !== undefined ? { owner } : {}),
+        });
     }
     async releaseLock(appId, key, handleId) {
         return this.post(`/app/${appId}/api/locks/release`, {
@@ -2431,6 +2584,101 @@ 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}` : ""}`);
+    }
+    /**
+     * 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.
+     */
+    async listDocumentIngests(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}/ingest${query ? `?${query}` : ""}`);
+    }
+    /** One bulk-load session's status (#3434). */
+    async getDocumentIngest(appId, documentId, sessionId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/ingest/${encodeURIComponent(sessionId)}`);
+    }
+    /** Open a bulk-load session on a large document (#3435, criterion 9). */
+    async createDocumentIngest(appId, documentId) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/ingest`, {});
+    }
+    /**
+     * 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.
+     */
+    async uploadDocumentIngestChunk(appId, documentId, sessionId, chunk) {
+        const credentials = await this.ensureAuthenticated();
+        const form = new FormData();
+        form.set("model", chunk.model);
+        form.set("index", String(chunk.index));
+        form.set("rows", String(chunk.rows));
+        form.set("bytes", String(chunk.bytes));
+        form.set("rawBytes", String(chunk.rawBytes));
+        form.set("sha256", chunk.sha256);
+        form.set("firstId", chunk.firstId);
+        form.set("lastId", chunk.lastId);
+        form.set("chunk", new Blob([chunk.body]), `${chunk.index}.ndjson.gz`);
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+        };
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}` +
+            `/ingest/${encodeURIComponent(sessionId)}/chunks`;
+        const response = await fetchWithTLS(url, {
+            method: "POST",
+            headers,
+            body: form,
+        });
+        const text = await response.text();
+        let result = {};
+        try {
+            result = text ? JSON.parse(text) : {};
+        }
+        catch {
+            result = { error: text };
+        }
+        if (!response.ok) {
+            throw new ApiError(result?.error || `Failed to upload chunk: ${response.statusText}`, response.status, result?.code, result?.details);
+        }
+        return result;
+    }
+    /** Freeze a session's manifest and hand it to the pipeline (#3435). */
+    async commitDocumentIngest(appId, documentId, sessionId) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/ingest/${encodeURIComponent(sessionId)}/commit`, {});
+    }
+    /** Give a session up; allowed until the swap (#3435). */
+    async abortDocumentIngest(appId, documentId, sessionId) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/ingest/${encodeURIComponent(sessionId)}/abort`, {});
+    }
+    /** 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 +2823,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