primitive-admin 1.0.43 → 1.0.45

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

@@ -1,26 +1,167 @@
 import { loadCredentials, saveCredentials, isTokenExpiringSoon, } from "./config.js";
 import { fetchWithTLS } from "./fetch.js";
 import { paginateAll } from "./paginate.js";
+import { RefreshError, refreshAdminCredentials, } from "./refresh-admin-credentials.js";
 export class ApiError extends Error {
     statusCode;
     code;
-    constructor(message, statusCode, code) {
+    /**
+     * Structured `details` payload from `corsErrorResponse`.
+     *
+     * The server's error envelope can emit `details` as either:
+     *   - an array of validation issues (e.g. `[{ path, message }, ...]`) —
+     *     this is what most legacy endpoints produce, and what sync.ts walks
+     *     via `Array.isArray(err.details)` / `for (const detail of ...)`.
+     *   - a record of structured offender fields (e.g. `{ refs, operations,
+     *     opCount, line, column, ... }`) — emitted by the issue #666 schema
+     *     gate and consumed by the typed exception subclasses below.
+     *
+     * Callers must narrow before use: `Array.isArray(err.details)` for the
+     * legacy shape, otherwise treat as `Record<string, any>`.
+     */
+    details;
+    constructor(message, statusCode, code, details) {
         super(message);
         this.statusCode = statusCode;
         this.code = code;
         this.name = "ApiError";
+        if (details !== undefined) {
+            this.details = details;
+        }
     }
 }
 export class ConflictError extends ApiError {
     serverModifiedAt;
     expectedModifiedAt;
-    constructor(message, serverModifiedAt, expectedModifiedAt) {
-        super(message, 409, "CONFLICT");
+    constructor(message, serverModifiedAt, expectedModifiedAt, details) {
+        super(message, 409, "CONFLICT", details);
         this.serverModifiedAt = serverModifiedAt;
         this.expectedModifiedAt = expectedModifiedAt;
         this.name = "ConflictError";
     }
 }
+/**
+ * Extract a human-readable error message + structured fields from a non-OK
+ * HTTP response body. Single source of truth used by every error-handler call
+ * site in this file (see issue #684).
+ */
+export function parseErrorResponse(response, text, path) {
+    // Empty body → fall back to status code.
+    if (!text) {
+        return { message: `HTTP ${response.status}` };
+    }
+    let errorData;
+    try {
+        errorData = JSON.parse(text);
+    }
+    catch {
+        // 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.
+        if (text.includes("<!DOCTYPE")) {
+            const where = path ? `: ${path}` : "";
+            return {
+                message: `API endpoint not found${where}. Make sure the server is running.`,
+                htmlNotFound: true,
+            };
+        }
+        // Other non-JSON bodies (e.g. plain-text 502 from a proxy) — surface the
+        // raw text so the operator at least sees what the server returned.
+        return { message: text };
+    }
+    // Server's standard envelope uses `error`; ConflictError + integrations
+    // proxy use `message`. Prefer `error` (more common), fall back to `message`.
+    const message = (typeof errorData?.error === "string" && errorData.error) ||
+        (typeof errorData?.message === "string" && errorData.message) ||
+        `HTTP ${response.status}`;
+    // Per issue #666 addendum A1, `code` may be at the top level or nested
+    // under `details.code` when the server's bespoke envelope didn't flatten.
+    const code = (typeof errorData?.code === "string" ? errorData.code : undefined) ??
+        (typeof errorData?.details?.code === "string"
+            ? errorData.details.code
+            : undefined);
+    // Accept either an array (legacy) or a plain object (#666 schema gate).
+    const details = Array.isArray(errorData?.details)
+        ? errorData.details
+        : errorData?.details && typeof errorData.details === "object"
+            ? errorData.details
+            : undefined;
+    return { message, code, details, raw: errorData };
+}
+/**
+ * Typed exception classes for the database-schema feature (issue #666).
+ * Each maps 1:1 to a server `code` value emitted from the op-edit or
+ * schema-edit gate. They all extend ApiError so existing catch-all paths
+ * continue to work; specialized catch blocks can branch on `instanceof`.
+ *
+ * Per round-2 addendum A1, `details` is always preserved so callers can
+ * extract structured offender lists (refs[], operations[], etc.).
+ */
+export class SchemaRequiredError extends ApiError {
+    constructor(message, details) {
+        super(message, 422, "SCHEMA_REQUIRED", details);
+        this.name = "SchemaRequiredError";
+    }
+}
+function detailsRecord(details) {
+    return details && !Array.isArray(details) && typeof details === "object"
+        ? details
+        : undefined;
+}
+export class OperationRefError extends ApiError {
+    constructor(message, details) {
+        super(message, 422, "OPERATION_REFERENCES_UNDEFINED", details);
+        this.name = "OperationRefError";
+    }
+    get refs() {
+        const d = detailsRecord(this.details);
+        return Array.isArray(d?.refs) ? d.refs : [];
+    }
+}
+export class SchemaBreaksOpsError extends ApiError {
+    constructor(message, details) {
+        super(message, 422, "SCHEMA_BREAKS_OPERATIONS", details);
+        this.name = "SchemaBreaksOpsError";
+    }
+    get operations() {
+        const d = detailsRecord(this.details);
+        return Array.isArray(d?.operations) ? d.operations : [];
+    }
+}
+export class SchemaHasUncheckableOpsError extends ApiError {
+    constructor(message, details) {
+        super(message, 422, "SCHEMA_HAS_UNCHECKABLE_OPS", details);
+        this.name = "SchemaHasUncheckableOpsError";
+    }
+    get operations() {
+        const d = detailsRecord(this.details);
+        return Array.isArray(d?.operations) ? d.operations : [];
+    }
+}
+export class TomlParseError extends ApiError {
+    constructor(message, details) {
+        super(message, 400, "TOML_PARSE_ERROR", details);
+        this.name = "TomlParseError";
+    }
+    get line() {
+        const d = detailsRecord(this.details);
+        return typeof d?.line === "number" ? d.line : undefined;
+    }
+    get column() {
+        const d = detailsRecord(this.details);
+        return typeof d?.column === "number" ? d.column : undefined;
+    }
+}
+export class OpsExistError extends ApiError {
+    constructor(message, details) {
+        super(message, 409, "OPS_EXIST", details);
+        this.name = "OpsExistError";
+    }
+    get opCount() {
+        const d = detailsRecord(this.details);
+        return typeof d?.opCount === "number" ? d.opCount : 0;
+    }
+}
 export class ApiClient {
     credentials = null;
     constructor() {
@@ -40,39 +181,24 @@ export class ApiClient {
         return this.credentials;
     }
     async refreshToken() {
-        if (!this.credentials?.refreshToken) {
-            throw new ApiError("No refresh token available. Please login again.", 401);
+        if (!this.credentials) {
+            throw new ApiError("Not logged in. Run 'primitive login' first.", 401);
         }
-        const url = `${this.credentials.serverUrl}/admin/api/auth/refresh`;
         try {
-            const headers = {
-                "Content-Type": "application/json",
-            };
-            if (this.credentials.globalAdminAppId) {
-                headers["X-Global-Admin-App-Id"] = this.credentials.globalAdminAppId;
-            }
-            const response = await fetchWithTLS(url, {
-                method: "POST",
-                headers,
-                body: JSON.stringify({ refreshToken: this.credentials.refreshToken }),
-            });
-            if (!response.ok) {
-                throw new ApiError("Token refresh failed. Please login again.", 401);
-            }
-            const data = await response.json();
-            // Update credentials with new tokens
-            this.credentials = {
-                ...this.credentials,
-                accessToken: data.accessToken || data.token,
-                refreshToken: data.refreshToken || this.credentials.refreshToken,
-                expiresAt: data.expiresAt,
-            };
+            const updated = await refreshAdminCredentials(this.credentials);
+            this.credentials = updated;
             saveCredentials(this.credentials);
         }
-        catch (error) {
-            if (error instanceof ApiError)
-                throw error;
-            throw new ApiError("Token refresh failed. Please login again.", 401);
+        catch (err) {
+            if (err instanceof RefreshError) {
+                // Preserve historical behavior: ApiClient surfaces refresh failures
+                // as 401s regardless of whether the underlying cause was a network
+                // error or a server-side rejection. Callers that need a finer
+                // distinction (e.g. `primitive token`) consume RefreshError directly
+                // from refresh-admin-credentials.ts instead of going through here.
+                throw new ApiError("Token refresh failed. Please login again.", 401);
+            }
+            throw err;
         }
     }
     async request(path, options = {}) {
@@ -93,20 +219,42 @@ export class ApiClient {
         });
         const text = await response.text();
         if (!response.ok) {
-            let errorData;
-            try {
-                errorData = JSON.parse(text);
+            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);
             }
-            catch {
-                if (text.includes("<!DOCTYPE")) {
-                    throw new ApiError(`API endpoint not found: ${path}. Make sure the server is running.`, 404);
-                }
-                errorData = { message: text || `HTTP ${response.status}` };
+            // 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 && errorData?.code === "CONFLICT") {
-                throw new ConflictError(errorData.message || "Resource conflict", errorData.serverModifiedAt, errorData.expectedModifiedAt);
+            if (response.status === 409 && parsed.code === "OPS_EXIST") {
+                throw new OpsExistError(parsed.message, detailsRecord);
             }
-            throw new ApiError(errorData.message || `HTTP ${response.status}`, response.status, errorData.code);
+            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);
+            }
+            if (response.status === 422 && parsed.code === "OPERATION_REFERENCES_UNDEFINED") {
+                throw new OperationRefError(parsed.message, detailsRecord);
+            }
+            if (response.status === 422 && parsed.code === "SCHEMA_BREAKS_OPERATIONS") {
+                throw new SchemaBreaksOpsError(parsed.message, detailsRecord);
+            }
+            if (response.status === 422 && parsed.code === "SCHEMA_HAS_UNCHECKABLE_OPS") {
+                throw new SchemaHasUncheckableOpsError(parsed.message, detailsRecord);
+            }
+            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
         }
         return text ? JSON.parse(text) : null;
     }
@@ -196,9 +344,29 @@ export class ApiClient {
     async mintTestJwt(appId, userId, role) {
         return this.post(`/admin/api/apps/${appId}/users/${userId}/mint-test-jwt`, role ? { role } : {});
     }
-    async listUsers(appId) {
-        const result = await this.get(`/app/${appId}/api/users`);
-        return result?.items ?? result ?? [];
+    async rebuildUserSearchText(appId) {
+        return this.post(`/admin/api/apps/${appId}/users/rebuild-search-text`, {});
+    }
+    async listUsers(appId, params) {
+        const query = new URLSearchParams();
+        if (params?.name)
+            query.set("name", params.name);
+        if (params?.email)
+            query.set("email", params.email);
+        if (params?.userId)
+            query.set("userId", params.userId);
+        if (params?.limit)
+            query.set("limit", String(params.limit));
+        if (params?.cursor)
+            query.set("cursor", params.cursor);
+        const path = query.toString()
+            ? `/app/${appId}/api/users?${query.toString()}`
+            : `/app/${appId}/api/users`;
+        const result = await this.get(path);
+        return {
+            items: result?.items ?? (Array.isArray(result) ? result : []),
+            nextCursor: result?.nextCursor ?? null,
+        };
     }
     async removeUser(appId, userId) {
         return this.delete(`/app/${appId}/api/users/${userId}`);
@@ -305,6 +473,10 @@ export class ApiClient {
         const result = await this.get(`/admin/api/apps/${appId}/integrations/${integrationId}/logs`, params);
         return result?.items ?? [];
     }
+    async listWorkflowRunIntegrationLogs(appId, runId, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/workflows/runs/${runId}/integration-logs`, params);
+        return result?.items ?? [];
+    }
     async listIntegrationSecrets(appId, integrationId, params) {
         const result = await this.get(`/admin/api/apps/${appId}/integrations/${integrationId}/secrets`, params);
         return result?.items ?? [];
@@ -540,14 +712,8 @@ export class ApiClient {
         });
         const text = await response.text();
         if (!response.ok) {
-            let errorData;
-            try {
-                errorData = JSON.parse(text);
-            }
-            catch {
-                errorData = { message: text || `HTTP ${response.status}` };
-            }
-            throw new ApiError(errorData.message || `HTTP ${response.status}`, response.status, errorData.code);
+            const parsed = parseErrorResponse(response, text, url);
+            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
         }
         return text ? JSON.parse(text) : null;
     }
@@ -567,14 +733,8 @@ export class ApiClient {
         });
         if (!response.ok) {
             const text = await response.text();
-            let errorData;
-            try {
-                errorData = JSON.parse(text);
-            }
-            catch {
-                errorData = { message: text || `HTTP ${response.status}` };
-            }
-            throw new ApiError(errorData.message || `HTTP ${response.status}`, response.status, errorData.code);
+            const parsed = parseErrorResponse(response, text, url);
+            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
         }
         const arrayBuffer = await response.arrayBuffer();
         return {
@@ -995,14 +1155,8 @@ export class ApiClient {
         const response = await fetchWithTLS(url, { ...options, headers });
         const text = await response.text();
         if (!response.ok) {
-            let errorData;
-            try {
-                errorData = JSON.parse(text);
-            }
-            catch {
-                errorData = { message: text || `HTTP ${response.status}` };
-            }
-            throw new ApiError(errorData.message || `HTTP ${response.status}`, response.status, errorData.code);
+            const parsed = parseErrorResponse(response, text, path);
+            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
         }
         return text ? JSON.parse(text) : null;
     }
@@ -1030,13 +1184,27 @@ export class ApiClient {
     async createDatabaseTypeConfig(appId, data) {
         return this.post(`/app/${appId}/api/databases/types`, data);
     }
-    async updateDatabaseTypeConfig(appId, databaseType, data, expectedModifiedAt) {
+    async updateDatabaseTypeConfig(appId, databaseType, data, expectedModifiedAt, options) {
         const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
-        return this.patch(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}`, body);
+        const qs = new URLSearchParams();
+        if (options?.dryRun)
+            qs.set("dryRun", "true");
+        if (options?.acceptWarnings)
+            qs.set("acceptWarnings", "true");
+        const query = qs.toString();
+        const path = `/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}${query ? `?${query}` : ""}`;
+        return this.patch(path, body);
     }
     async deleteDatabaseTypeConfig(appId, databaseType) {
         return this.delete(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}`);
     }
+    /**
+     * Issue #666 Phase 3: ask the server to scaffold a TOML schema from
+     * existing ops + DO field introspection. Read-only — does NOT persist.
+     */
+    async scaffoldDatabaseTypeSchema(appId, databaseType) {
+        return this.post(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/schema:scaffold`, {});
+    }
     // ============================================
     // DATABASE TYPE OPERATIONS
     // ============================================