primitive-admin 1.2.0-alpha.0 → 1.2.0-alpha.2

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

@@ -85,6 +85,15 @@ export function parseErrorResponse(response, text, path) {
         // Non-JSON body. Surface the existing `<!DOCTYPE` special-case (an HTML
         // 404 page from hitting the wrong path) so we don't regress the helpful
         // "API endpoint not found" message at api-client.ts:343.
+        //
+        // An HTML page with any other status is not a wrong path: it keeps its
+        // status, so a gateway's 502 is retried and a 403 is not read as absence
+        // (#4148).
+        if (text.includes("<!DOCTYPE") && response.status !== 404) {
+            return {
+                message: `HTTP ${response.status}: the server answered with an HTML error page`,
+            };
+        }
         if (text.includes("<!DOCTYPE")) {
             const where = path ? `: ${path}` : "";
             return {
@@ -295,60 +304,113 @@ export class ApiClient {
     async request(path, options = {}) {
         const credentials = await this.ensureAuthenticated();
         const url = `${credentials.serverUrl}${path}`;
-        const headers = {
-            Authorization: `Bearer ${credentials.accessToken}`,
-            "Content-Type": "application/json",
-            ...(options.headers || {}),
-        };
-        // Include globalAdminAppId if available (required for admin API calls)
-        if (credentials.globalAdminAppId) {
-            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
-        }
-        const response = await fetchWithTLS(url, {
-            ...options,
-            headers,
-        });
-        const text = await response.text();
-        if (!response.ok) {
-            const parsed = parseErrorResponse(response, text, path);
-            // Preserve the `<!DOCTYPE` → 404 ApiError shape (status forced to 404).
-            if (parsed.htmlNotFound) {
-                throw new ApiError(parsed.message, 404);
-            }
-            // Narrow details to the record shape for the issue #666 typed-exception
-            // dispatch below. Conflict metadata may live under `details.*` (canonical
-            // location per A1) or on the top-level envelope (legacy).
-            const detailsRecord = parsed.details && !Array.isArray(parsed.details)
-                ? parsed.details
-                : undefined;
-            const serverModifiedAt = detailsRecord?.serverModifiedAt ?? parsed.raw?.serverModifiedAt;
-            const expectedModifiedAt = detailsRecord?.expectedModifiedAt ?? parsed.raw?.expectedModifiedAt;
-            // Typed exceptions for the schema-feature (issue #666).
-            if (response.status === 409 && parsed.code === "CONFLICT") {
-                throw new ConflictError(parsed.message, serverModifiedAt, expectedModifiedAt, detailsRecord);
-            }
-            if (response.status === 409 && parsed.code === "OPS_EXIST") {
-                throw new OpsExistError(parsed.message, detailsRecord);
-            }
-            if (response.status === 400 && parsed.code === "TOML_PARSE_ERROR") {
-                throw new TomlParseError(parsed.message, detailsRecord);
-            }
-            if (response.status === 422 && parsed.code === "SCHEMA_REQUIRED") {
-                throw new SchemaRequiredError(parsed.message, detailsRecord);
+        const send = async (accessToken) => {
+            const headers = {
+                Authorization: `Bearer ${accessToken}`,
+                "Content-Type": "application/json",
+                ...(options.headers || {}),
+            };
+            // Include globalAdminAppId if available (required for admin API calls)
+            if (credentials.globalAdminAppId) {
+                headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
             }
-            if (response.status === 422 && parsed.code === "OPERATION_REFERENCES_UNDEFINED") {
-                throw new OperationRefError(parsed.message, detailsRecord);
+            const response = await fetchWithTLS(url, {
+                ...options,
+                headers,
+            });
+            return { response, text: await response.text() };
+        };
+        let { response, text } = await send(credentials.accessToken);
+        // #3889 — a 403 naming `admin` is retried once with a stored, unexpired
+        // step-up. A retry refused 401 means the step-up is gone (revoked or
+        // expired early): drop it and show the original refusal. The retry's own
+        // refusal (say, an unpinned step-up on an app route) is shown as it is.
+        if (response.status === 403 && this.stepUpApplies(response, text, path)) {
+            const retried = await send(credentials.stepUp.accessToken);
+            if (retried.response.ok) {
+                return retried.text ? JSON.parse(retried.text) : null;
             }
-            if (response.status === 422 && parsed.code === "SCHEMA_BREAKS_OPERATIONS") {
-                throw new SchemaBreaksOpsError(parsed.message, detailsRecord);
+            if (retried.response.status === 401) {
+                this.dropStepUp();
             }
-            if (response.status === 422 && parsed.code === "SCHEMA_HAS_UNCHECKABLE_OPS") {
-                throw new SchemaHasUncheckableOpsError(parsed.message, detailsRecord);
+            else {
+                ({ response, text } = retried);
             }
-            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
+        }
+        if (!response.ok) {
+            throw this.responseError(response, text, path);
         }
         return text ? JSON.parse(text) : null;
     }
+    /**
+     * Whether a 403 should be retried with the stored step-up: it names
+     * `admin` among the missing scopes, and an unexpired step-up is stored.
+     */
+    stepUpApplies(response, text, path) {
+        const stepUp = this.credentials?.stepUp;
+        if (!stepUp?.accessToken)
+            return false;
+        if (new Date(stepUp.expiresAt).getTime() <= Date.now())
+            return false;
+        const details = parseErrorResponse(response, text, path).details;
+        const missing = details && !Array.isArray(details) ? details.missing : undefined;
+        return Array.isArray(missing) && missing.includes("admin");
+    }
+    /** Forget a step-up the server no longer accepts. */
+    dropStepUp() {
+        if (!this.credentials?.stepUp)
+            return;
+        const { stepUp: _dropped, ...rest } = this.credentials;
+        this.credentials = rest;
+        saveCredentials(rest);
+    }
+    /** The typed error a failed response throws. */
+    responseError(response, text, path) {
+        const parsed = parseErrorResponse(response, text, path);
+        // Preserve the `<!DOCTYPE` → 404 ApiError shape.
+        if (parsed.htmlNotFound) {
+            return new ApiError(parsed.message, 404);
+        }
+        // Narrow details to the record shape for the issue #666 typed-exception
+        // dispatch below. Conflict metadata may live under `details.*` (canonical
+        // location per A1) or on the top-level envelope (legacy).
+        const detailsRecord = parsed.details && !Array.isArray(parsed.details)
+            ? parsed.details
+            : undefined;
+        const serverModifiedAt = detailsRecord?.serverModifiedAt ?? parsed.raw?.serverModifiedAt;
+        const expectedModifiedAt = detailsRecord?.expectedModifiedAt ?? parsed.raw?.expectedModifiedAt;
+        // Typed exceptions for the schema-feature (issue #666).
+        if (response.status === 409 && parsed.code === "CONFLICT") {
+            return new ConflictError(parsed.message, serverModifiedAt, expectedModifiedAt, detailsRecord);
+        }
+        if (response.status === 409 && parsed.code === "OPS_EXIST") {
+            return new OpsExistError(parsed.message, detailsRecord);
+        }
+        if (response.status === 400 && parsed.code === "TOML_PARSE_ERROR") {
+            return new TomlParseError(parsed.message, detailsRecord);
+        }
+        if (response.status === 422 && parsed.code === "SCHEMA_REQUIRED") {
+            return new SchemaRequiredError(parsed.message, detailsRecord);
+        }
+        if (response.status === 422 && parsed.code === "OPERATION_REFERENCES_UNDEFINED") {
+            return new OperationRefError(parsed.message, detailsRecord);
+        }
+        if (response.status === 422 && parsed.code === "SCHEMA_BREAKS_OPERATIONS") {
+            return new SchemaBreaksOpsError(parsed.message, detailsRecord);
+        }
+        if (response.status === 422 && parsed.code === "SCHEMA_HAS_UNCHECKABLE_OPS") {
+            return new SchemaHasUncheckableOpsError(parsed.message, detailsRecord);
+        }
+        return new ApiError(parsed.message, response.status, parsed.code, parsed.details);
+    }
+    /**
+     * `POST /admin/api/auth/token` — derive a token no wider than the stored
+     * one (`primitive token --scope`, #3889). A wider request is refused with
+     * `TOKEN_WIDER_THAN_PRESENTED`.
+     */
+    async exchangeToken(body) {
+        return this.post("/admin/api/auth/token", body);
+    }
     // Helper for GET requests with query params
     async get(path, params) {
         let fullPath = path;
@@ -410,6 +472,10 @@ export class ApiClient {
             qs.set("limit", String(params.limit));
         if (params?.cursor)
             qs.set("cursor", params.cursor);
+        // `kind` filters by lineage: `parent` is apps with no parent, `child`
+        // child apps. Omitted lists every app the caller is assigned to.
+        if (params?.kind)
+            qs.set("kind", params.kind);
         const q = qs.toString();
         const resp = await this.get(`/admin/api/admins/me/apps${q ? `?${q}` : ""}`);
         return {
@@ -463,9 +529,54 @@ export class ApiClient {
         });
         return drainAppsUntilConverged(drainOnce);
     }
+    /**
+     * Create an app. An ordinary app takes `name` (and, for a super-admin,
+     * `initialAdminEmail`). A child app takes `parentAppId` and `childSlug`
+     * instead, plus the optional `branch`, `idleDays` (7-30, default 30) and
+     * `copySecrets` (default true); the server names it `<parent name> /
+     * <slug>` and copies the parent's settings.
+     */
     async createApp(data) {
         return this.post("/admin/api/apps", data);
     }
+    /**
+     * One page of an app's child apps, in creation order
+     * (`GET /admin/api/apps/{appId}/children`).
+     */
+    async listAppChildren(parentAppId, params) {
+        const qs = new URLSearchParams();
+        if (params?.limit !== undefined)
+            qs.set("limit", String(params.limit));
+        if (params?.cursor)
+            qs.set("cursor", params.cursor);
+        const q = qs.toString();
+        const resp = await this.get(`/admin/api/apps/${encodeURIComponent(parentAppId)}/children${q ? `?${q}` : ""}`);
+        return {
+            items: resp?.items ?? [],
+            hasMore: resp?.hasMore ?? false,
+            nextCursor: resp?.nextCursor ?? null,
+        };
+    }
+    /**
+     * Add one origin to a child's preview origins
+     * (`POST /admin/api/apps/{parentAppId}/children/{slug}/preview-origins`).
+     */
+    async addChildPreviewOrigin(parentAppId, slug, origin) {
+        return this.post(this.childPreviewOriginsPath(parentAppId, slug), { origin });
+    }
+    /**
+     * Remove one origin from a child's preview origins
+     * (`DELETE /admin/api/apps/{parentAppId}/children/{slug}/preview-origins`).
+     */
+    async removeChildPreviewOrigin(parentAppId, slug, origin) {
+        return this.request(this.childPreviewOriginsPath(parentAppId, slug), {
+            method: "DELETE",
+            body: JSON.stringify({ origin }),
+        });
+    }
+    childPreviewOriginsPath(parentAppId, slug) {
+        return `/admin/api/apps/${encodeURIComponent(parentAppId)}/children/${encodeURIComponent(slug)}/preview-origins`;
+    }
     async getApp(appId) {
         return this.get(`/admin/api/apps/${appId}`);
     }
@@ -487,6 +598,14 @@ export class ApiClient {
     async addUserByEmail(appId, data) {
         return this.post(`/admin/api/apps/${appId}/users/add-by-email`, data);
     }
+    /**
+     * Set a member's display name and/or avatar URL
+     * (`PATCH /admin/api/apps/:appId/users/:userId/profile`). An omitted field
+     * is left alone; `avatarUrl: null` or `""` clears the avatar.
+     */
+    async setUserProfile(appId, userId, data) {
+        return this.patch(`/admin/api/apps/${appId}/users/${userId}/profile`, data);
+    }
     async mintTestJwt(appId, userId, role) {
         return this.post(`/admin/api/apps/${appId}/users/${userId}/mint-test-jwt`, role ? { role } : {});
     }
@@ -1037,6 +1156,29 @@ export class ApiClient {
             nextCursor: result?.nextCursor ?? null,
         };
     }
+    /**
+     * One page of one user's agent sessions (#3809): the app API's sessions
+     * list, which an app owner or admin may read for any user.
+     */
+    async listAgentSessions(appId, params) {
+        const result = await this.get(`/app/${appId}/api/agent-sessions`, params);
+        return {
+            items: result?.items ?? [],
+            hasMore: result?.hasMore,
+            nextCursor: result?.nextCursor ?? null,
+        };
+    }
+    /**
+     * One agent session (#3809): its binding, status, members and active turn,
+     * and for an app owner or admin the session object's state. Never its rows.
+     */
+    async getAgentSession(appId, sessionId) {
+        return this.get(`/app/${appId}/api/agent-sessions/${encodeURIComponent(sessionId)}`);
+    }
+    /** Delete an agent session and its document (#3809); a repeat succeeds again. */
+    async deleteAgentSession(appId, sessionId) {
+        return this.delete(`/app/${appId}/api/agent-sessions/${encodeURIComponent(sessionId)}`);
+    }
     async listSessions(appId, userId, params) {
         const result = await this.get(`/admin/api/apps/${appId}/sessions`, {
             userId,
@@ -1890,43 +2032,6 @@ export class ApiClient {
     async deleteDatabase(appId, databaseId) {
         return this.delete(`/app/${appId}/api/databases/${databaseId}`);
     }
-    /**
-     * Read a database's CEL context dict.
-     *
-     * The HTTP path stays `/metadata` because the wire field name is still
-     * `metadata`; only the client/CLI-facing helper names were reframed.
-     *
-     * @deprecated Use resource metadata categories instead (`primitive metadata
-     * get database <id> <category>`, #1420, #1815).
-     */
-    async getDatabaseCelContext(appId, databaseId) {
-        return this.get(`/app/${appId}/api/databases/${databaseId}/metadata`);
-    }
-    /**
-     * Update a database's CEL context dict (merge with existing).
-     *
-     * @deprecated Use resource metadata categories instead (`primitive metadata
-     * set database <id> <category>`, #1420, #1815).
-     */
-    async updateDatabaseCelContext(appId, databaseId, celContext) {
-        return this.patch(`/app/${appId}/api/databases/${databaseId}/metadata`, celContext);
-    }
-    /**
-     * @deprecated Database CEL context is deprecated; use resource metadata
-     * categories instead (`primitive metadata get database <id> <category>`,
-     * #1420, #1815).
-     */
-    async getDatabaseMetadata(appId, databaseId) {
-        return this.getDatabaseCelContext(appId, databaseId);
-    }
-    /**
-     * @deprecated Database CEL context is deprecated; use resource metadata
-     * categories instead (`primitive metadata set database <id> <category>`,
-     * #1420, #1815).
-     */
-    async updateDatabaseMetadata(appId, databaseId, metadata) {
-        return this.updateDatabaseCelContext(appId, databaseId, metadata);
-    }
     // ============================================
     // DATABASE PERMISSIONS
     // ============================================
@@ -2890,8 +2995,13 @@ export class ApiClient {
     async listDocumentPendingInvitations(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/pending-invitations`);
     }
-    async listDocumentBlobs(appId, documentId) {
-        return this.get(`/app/${appId}/api/documents/${documentId}/blobs`);
+    /**
+     * One page of a document's uploaded blobs (the `{ items, hasMore,
+     * nextCursor? }` envelope); pass the previous page's `nextCursor` for the
+     * next.
+     */
+    async listDocumentBlobs(appId, documentId, params) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/blobs`, params);
     }
     async downloadBlob(appId, documentId, blobId) {
         const credentials = await this.ensureAuthenticated();
@@ -2935,6 +3045,20 @@ export class ApiClient {
     async listDocumentAliases(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/aliases`);
     }
+    /**
+     * The document a user's alias points at, or null when the user holds no
+     * alias under that key (#4148).
+     */
+    async getDocumentAlias(appId, aliasScope, aliasKey, userId) {
+        try {
+            return await this.get(`/app/${appId}/api/document-aliases/${aliasScope}/${encodeURIComponent(aliasKey)}`, { userId });
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.statusCode === 404)
+                return null;
+            throw error;
+        }
+    }
     async setDocumentAlias(appId, aliasScope, aliasKey, documentId, ownerUserId, mustNotExist) {
         return this.put(`/app/${appId}/api/document-aliases/${aliasScope}/${encodeURIComponent(aliasKey)}`, {
             documentId,