primitive-admin 1.1.0-alpha.4 → 1.1.0-alpha.41

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

@@ -1,25 +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() {
@@ -39,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 = {}) {
@@ -92,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 && 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);
+            }
+            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 === 409 && errorData?.code === "CONFLICT") {
-                throw new ConflictError(errorData.message || "Resource conflict", errorData.serverModifiedAt, errorData.expectedModifiedAt);
+            if (response.status === 422 && parsed.code === "SCHEMA_HAS_UNCHECKABLE_OPS") {
+                throw new SchemaHasUncheckableOpsError(parsed.message, detailsRecord);
             }
-            throw new ApiError(errorData.message || `HTTP ${response.status}`, response.status, errorData.code);
+            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
         }
         return text ? JSON.parse(text) : null;
     }
@@ -155,7 +304,18 @@ export class ApiClient {
     // APPS
     // ============================================
     async listApps() {
-        return this.get("/admin/api/admins/me/apps");
+        // 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.
+        const apps = await paginateAll(async (cursor) => {
+            const qs = new URLSearchParams({ limit: "100" });
+            if (cursor)
+                qs.set("cursor", cursor);
+            const resp = await this.get(`/admin/api/admins/me/apps?${qs.toString()}`);
+            return { items: Array.isArray(resp.apps) ? resp.apps : [], nextCursor: resp.nextCursor };
+        });
+        return { apps };
     }
     async createApp(data) {
         return this.post("/admin/api/apps", data);
@@ -181,8 +341,32 @@ export class ApiClient {
     async addUserByEmail(appId, data) {
         return this.post(`/admin/api/apps/${appId}/users/add-by-email`, data);
     }
-    async listUsers(appId) {
-        return this.get(`/app/${appId}/api/users`);
+    async mintTestJwt(appId, userId, role) {
+        return this.post(`/admin/api/apps/${appId}/users/${userId}/mint-test-jwt`, role ? { role } : {});
+    }
+    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}`);
@@ -196,14 +380,30 @@ export class ApiClient {
     async transferAdminOwnership(appId, adminId) {
         return this.post(`/admin/api/apps/${appId}/admins/transfer-ownership`, { adminId });
     }
+    // App-level console admin management
+    async listAppAdmins(appId) {
+        return this.get(`/admin/api/apps/${appId}/admins`);
+    }
+    async addAppAdmin(appId, data) {
+        return this.post(`/admin/api/apps/${appId}/admins`, data);
+    }
+    async removeAppAdmin(appId, adminId) {
+        return this.delete(`/admin/api/apps/${appId}/admins/${adminId}`);
+    }
+    async listAppAdminInvitations(appId) {
+        return this.get(`/admin/api/apps/${appId}/admin-invitations`);
+    }
+    async deleteAppAdminInvitation(appId, invitationId) {
+        return this.delete(`/admin/api/apps/${appId}/admin-invitations/${invitationId}`);
+    }
     async transferDocumentOwnership(appId, documentId, newOwnerId) {
         return this.post(`/app/${appId}/api/documents/${documentId}/permissions/transfer`, { newOwnerId });
     }
     // ============================================
     // INVITATIONS
     // ============================================
-    async listInvitations(appId) {
-        return this.get(`/app/${appId}/api/invitations`);
+    async listInvitations(appId, params) {
+        return this.get(`/app/${appId}/api/invitations`, params);
     }
     async createInvitation(appId, data) {
         return this.post(`/app/${appId}/api/invitations`, data);
@@ -228,6 +428,19 @@ export class ApiClient {
         return this.delete(`/app/${appId}/api/waitlist/${waitlistId}`);
     }
     // ============================================
+    // DEFERRED GRANTS
+    // ============================================
+    async listDeferredGrants(appId, params) {
+        const result = await this.get(`/app/${appId}/api/deferred-grants`, params);
+        return {
+            grants: result?.grants ?? [],
+            nextCursor: result?.nextCursor ?? null,
+        };
+    }
+    async revokeDeferredGrant(appId, deferredId, type) {
+        return this.delete(`/app/${appId}/api/deferred-grants/${deferredId}?type=${type}`);
+    }
+    // ============================================
     // INTEGRATIONS
     // ============================================
     async listIntegrations(appId, params) {
@@ -260,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 ?? [];
@@ -274,6 +491,113 @@ export class ApiClient {
         });
     }
     // ============================================
+    // APP SECRETS
+    // ============================================
+    async listAppSecrets(appId) {
+        const result = await this.get(`/admin/api/apps/${appId}/secrets`);
+        return result?.items ?? [];
+    }
+    async createAppSecret(appId, payload) {
+        return this.post(`/admin/api/apps/${appId}/secrets`, payload);
+    }
+    async updateAppSecret(appId, secretId, payload) {
+        return this.put(`/admin/api/apps/${appId}/secrets/${secretId}`, payload);
+    }
+    async upsertAppSecret(appId, key, payload) {
+        return this.put(`/admin/api/apps/${appId}/secrets/by-key/${key}`, payload);
+    }
+    async deleteAppSecret(appId, secretId) {
+        return this.delete(`/admin/api/apps/${appId}/secrets/${secretId}`);
+    }
+    // ============================================
+    // WEBHOOKS
+    // ============================================
+    async listWebhooks(appId, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/webhooks`, params);
+        return {
+            items: result?.items ?? [],
+            nextCursor: result?.nextCursor ?? null,
+        };
+    }
+    async getWebhook(appId, webhookId) {
+        return this.get(`/admin/api/apps/${appId}/webhooks/${webhookId}`);
+    }
+    async createWebhook(appId, payload) {
+        return this.post(`/admin/api/apps/${appId}/webhooks`, payload);
+    }
+    async updateWebhook(appId, webhookId, payload, expectedModifiedAt) {
+        const body = expectedModifiedAt ? { ...payload, expectedModifiedAt } : payload;
+        return this.patch(`/admin/api/apps/${appId}/webhooks/${webhookId}`, body);
+    }
+    async deleteWebhook(appId, webhookId) {
+        return this.delete(`/admin/api/apps/${appId}/webhooks/${webhookId}`);
+    }
+    async rotateWebhookSecret(appId, webhookId, payload) {
+        return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/rotate-secret`, payload);
+    }
+    async listWebhookEvents(appId, webhookId, params) {
+        const result = await this.get(`/admin/api/apps/${appId}/webhooks/${webhookId}/events`, params);
+        return result;
+    }
+    async testWebhook(appId, webhookId, payload) {
+        return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/test`, payload || {});
+    }
+    // ============================================
+    // CRON TRIGGERS
+    // ============================================
+    async listCronTriggers(appId) {
+        const result = await this.get(`/app/${appId}/api/cron-triggers`);
+        return { items: result?.items ?? [] };
+    }
+    async getCronTrigger(appId, triggerId) {
+        return this.get(`/app/${appId}/api/cron-triggers/${triggerId}`);
+    }
+    async createCronTrigger(appId, payload) {
+        return this.post(`/app/${appId}/api/cron-triggers`, payload);
+    }
+    async updateCronTrigger(appId, triggerId, payload) {
+        return this.put(`/app/${appId}/api/cron-triggers/${triggerId}`, payload);
+    }
+    async deleteCronTrigger(appId, triggerId) {
+        return this.delete(`/app/${appId}/api/cron-triggers/${triggerId}`);
+    }
+    async pauseCronTrigger(appId, triggerId) {
+        return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/pause`, {});
+    }
+    async resumeCronTrigger(appId, triggerId) {
+        return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/resume`, {});
+    }
+    async testCronTrigger(appId, triggerId) {
+        return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/test`, {});
+    }
+    // ============================================
+    // ITERATIONS (iterate-users introspection / reset — #1209)
+    // ============================================
+    async listIterations(appId) {
+        const result = await this.get(`/app/${appId}/api/iterations`);
+        return { items: result?.items ?? [] };
+    }
+    async getIteration(appId, iterationName) {
+        return this.get(`/app/${appId}/api/iterations/${encodeURIComponent(iterationName)}`);
+    }
+    async resetIteration(appId, iterationName) {
+        return this.post(`/app/${appId}/api/iterations/${encodeURIComponent(iterationName)}/reset`, {});
+    }
+    // ============================================
+    // RESOURCE METADATA (values — issue #1352)
+    // ============================================
+    async readResourceMetadata(appId, resourceType, resourceId, category) {
+        return this.get(`/app/${appId}/api/resources/${encodeURIComponent(resourceType)}/${encodeURIComponent(resourceId)}/metadata/${encodeURIComponent(category)}`);
+    }
+    async writeResourceMetadata(appId, resourceType, resourceId, category, data) {
+        return this.put(`/app/${appId}/api/resources/${encodeURIComponent(resourceType)}/${encodeURIComponent(resourceId)}/metadata/${encodeURIComponent(category)}`, { data });
+    }
+    async batchReadResourceMetadata(appId, requests) {
+        return this.post(`/app/${appId}/api/resources/metadata/batch`, {
+            requests,
+        });
+    }
+    // ============================================
     // PROMPTS
     // ============================================
     async listPrompts(appId, params) {
@@ -325,6 +649,55 @@ export class ApiClient {
     async duplicatePromptConfig(appId, promptId, configId, payload) {
         return this.post(`/admin/api/apps/${appId}/prompts/${promptId}/configs/${configId}/duplicate`, payload || {});
     }
+    // ============================================
+    // SCRIPTS (Rhai transforms) — #1000 (prompt-model convergence)
+    // ============================================
+    //
+    // The `Script` model is the authoring surface for `script` workflow
+    // steps. A `Script` is a HEADER (name/description/activeConfigId); the
+    // Rhai body lives on versioned `ScriptConfig` rows resolved LIVE at run
+    // time. CLI `sync push` reads `transforms/*.rhai` files and reconciles
+    // them: a new file → create script (mints a default config); a changed
+    // file → create a new config + activate it (zero fan-out — referencing
+    // workflows pick up the new body on their next run).
+    async listScripts(appId) {
+        const result = await this.get(`/admin/api/apps/${appId}/scripts`);
+        return { items: result?.items ?? [] };
+    }
+    async getScript(appId, scriptId) {
+        return this.get(`/admin/api/apps/${appId}/scripts/${scriptId}`);
+    }
+    /**
+     * List a script's versioned configs (the `ScriptConfig` rows). Each config
+     * is a distinct block version: `configId` is the stable version selector,
+     * `contentHash` is its content identity, and `status` reports whether it is
+     * `active`/`draft`/`archived`. The script header's `activeConfigId` names
+     * the live version. Used by `scripts configs list` and by the script test
+     * commands to run against a specific pinned version.
+     */
+    async listScriptConfigs(appId, scriptId) {
+        const result = await this.get(`/admin/api/apps/${appId}/scripts/${scriptId}/configs`);
+        return { items: result?.items ?? [] };
+    }
+    async createScript(appId, payload) {
+        // Mints the script header + a default `active` config carrying the body.
+        return this.post(`/admin/api/apps/${appId}/scripts`, payload);
+    }
+    /**
+     * Push a new body for an existing script by creating a new `ScriptConfig`
+     * and activating it (the prompt-model "edit → activate" flow). Referencing
+     * workflows pick up the new body on their next run with no fan-out. The
+     * config name is unique per script, so we mint a timestamped name.
+     */
+    async pushScriptBody(appId, scriptId, body) {
+        const configName = `sync-${Date.now()}`;
+        const config = await this.post(`/admin/api/apps/${appId}/scripts/${scriptId}/configs`, { configName, body });
+        await this.post(`/admin/api/apps/${appId}/scripts/${scriptId}/configs/${config.configId}/activate`, {});
+        return config;
+    }
+    async deleteScript(appId, scriptId) {
+        return this.delete(`/admin/api/apps/${appId}/scripts/${scriptId}`);
+    }
     async getPromptSchema(appId, promptId) {
         return this.get(`/admin/api/apps/${appId}/prompts/${promptId}/schema`);
     }
@@ -415,14 +788,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;
     }
@@ -442,14 +809,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 {
@@ -519,6 +880,16 @@ export class ApiClient {
     async getWorkflowRunStatus(appId, workflowId, runId) {
         return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/runs/${runId}/status`);
     }
+    async getWorkflowStepRuns(appId, workflowId, runId) {
+        const result = await this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/runs/${runId}/steps`);
+        return { items: result?.items ?? [] };
+    }
+    async getWorkflowAnalytics(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/workflows/overview`, params);
+    }
+    async getTopWorkflows(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/workflows/top`, params);
+    }
     // ============================================
     // WORKFLOW CONFIGURATIONS
     // ============================================
@@ -547,21 +918,54 @@ export class ApiClient {
     // ============================================
     // ANALYTICS
     // ============================================
-    async getAnalyticsOverview(appId, params) {
-        return this.get(`/app/${appId}/api/analytics/overview`, params);
-    }
     async getAnalyticsTopUsers(appId, params) {
         return this.get(`/app/${appId}/api/analytics/users/top`, params);
     }
-    async getAnalyticsUserTimeline(appId, userUlid, params) {
-        return this.get(`/app/${appId}/api/analytics/users/${userUlid}/timeline`, params);
-    }
-    async getAnalyticsUserEvents(appId, userUlid, params) {
-        return this.get(`/app/${appId}/api/analytics/users/${userUlid}/events`, params);
-    }
     async getAnalyticsIntegrationMetrics(appId, params) {
         return this.get(`/app/${appId}/api/analytics/integrations`, params);
     }
+    async getAnalyticsOverviewDau(appId) {
+        return this.get(`/app/${appId}/api/analytics/overview/dau`);
+    }
+    async getAnalyticsOverviewWau(appId) {
+        return this.get(`/app/${appId}/api/analytics/overview/wau`);
+    }
+    async getAnalyticsOverviewMau(appId) {
+        return this.get(`/app/${appId}/api/analytics/overview/mau`);
+    }
+    async getAnalyticsOverviewGrowth(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/overview/growth`, params);
+    }
+    async getAnalyticsDailyActive(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/daily-active`, params);
+    }
+    async getAnalyticsRollingActive(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/rolling-active`, params);
+    }
+    async getAnalyticsCohortRetention(appId) {
+        return this.get(`/app/${appId}/api/analytics/cohort-retention`);
+    }
+    async getAnalyticsUserSearch(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/users/search`, params);
+    }
+    async getAnalyticsUserDetail(appId, userUlid) {
+        return this.get(`/app/${appId}/api/analytics/users/${userUlid}/detail`);
+    }
+    async getAnalyticsUserSnapshot(appId, userUlid) {
+        return this.get(`/app/${appId}/api/analytics/users/${userUlid}/snapshot`);
+    }
+    async getAnalyticsEvents(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/events`, params);
+    }
+    async getAnalyticsEventsGrouped(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/events/grouped`, params);
+    }
+    async getAnalyticsTopWorkflows(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/workflows/top`, params);
+    }
+    async getAnalyticsTopPrompts(appId, params) {
+        return this.get(`/app/${appId}/api/analytics/prompts/top`, params);
+    }
     // ============================================
     // SUPER ADMIN: ADMINS
     // ============================================
@@ -670,6 +1074,24 @@ export class ApiClient {
         return this.get(`/admin/api/apps/${appId}/comparisons/${group}`);
     }
     // ============================================
+    // EMAIL TEMPLATES
+    // ============================================
+    async listEmailTemplates(appId) {
+        return this.get(`/admin/api/apps/${appId}/email-templates`);
+    }
+    async getEmailTemplate(appId, emailType) {
+        return this.get(`/admin/api/apps/${appId}/email-templates/${emailType}`);
+    }
+    async upsertEmailTemplate(appId, emailType, payload) {
+        return this.put(`/admin/api/apps/${appId}/email-templates/${emailType}`, payload);
+    }
+    async deleteEmailTemplate(appId, emailType) {
+        return this.delete(`/admin/api/apps/${appId}/email-templates/${emailType}`);
+    }
+    async testEmailTemplate(appId, emailType, payload) {
+        return this.post(`/admin/api/apps/${appId}/email-templates/${emailType}/test`, payload || {});
+    }
+    // ============================================
     // ACCESS TOKENS
     // ============================================
     async createToken(appId, data) {
@@ -697,32 +1119,268 @@ export class ApiClient {
     async getDatabase(appId, databaseId) {
         return this.get(`/app/${appId}/api/databases/${databaseId}`);
     }
+    async updateDatabase(appId, databaseId, data) {
+        return this.patch(`/app/${appId}/api/databases/${databaseId}`, data);
+    }
     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.
+     */
+    async getDatabaseCelContext(appId, databaseId) {
+        return this.get(`/app/${appId}/api/databases/${databaseId}/metadata`);
+    }
+    /** Update a database's CEL context dict (merge with existing). */
+    async updateDatabaseCelContext(appId, databaseId, celContext) {
+        return this.patch(`/app/${appId}/api/databases/${databaseId}/metadata`, celContext);
+    }
+    /** @deprecated Use {@link getDatabaseCelContext} instead. */
+    async getDatabaseMetadata(appId, databaseId) {
+        return this.getDatabaseCelContext(appId, databaseId);
+    }
+    /** @deprecated Use {@link updateDatabaseCelContext} instead. */
+    async updateDatabaseMetadata(appId, databaseId, metadata) {
+        return this.updateDatabaseCelContext(appId, databaseId, metadata);
+    }
     // ============================================
     // DATABASE PERMISSIONS
     // ============================================
     async listDatabasePermissions(appId, databaseId) {
         return this.get(`/app/${appId}/api/databases/${databaseId}/permissions`);
     }
+    async addDatabaseManager(appId, databaseId, userId) {
+        return this.put(`/app/${appId}/api/databases/${databaseId}/permissions`, {
+            userId,
+            permission: "manager",
+        });
+    }
+    async removeDatabaseManager(appId, databaseId, userId) {
+        return this.delete(`/app/${appId}/api/databases/${databaseId}/permissions/${userId}`);
+    }
+    /** @deprecated Use {@link addDatabaseManager} instead. */
     async grantDatabasePermission(appId, databaseId, data) {
-        return this.put(`/app/${appId}/api/databases/${databaseId}/permissions`, data);
+        return this.addDatabaseManager(appId, databaseId, data.userId);
     }
+    /** @deprecated Use {@link removeDatabaseManager} instead. */
     async revokeDatabasePermission(appId, databaseId, userId) {
         return this.delete(`/app/${appId}/api/databases/${databaseId}/permissions/${userId}`);
     }
     // ============================================
-    // DATABASE GROUP PERMISSIONS
+    // DATABASE RECORDS & SCHEMA
+    // ============================================
+    async listDatabaseModels(appId, databaseId) {
+        return this.get(`/app/${appId}/api/databases/${databaseId}/records/models`);
+    }
+    async describeDatabaseModel(appId, databaseId, modelName) {
+        return this.get(`/app/${appId}/api/databases/${databaseId}/records/describe`, { modelName });
+    }
+    async queryDatabaseRecords(appId, databaseId, modelName, queryOptions) {
+        const body = { modelName };
+        if (queryOptions?.filter)
+            body.filter = queryOptions.filter;
+        const options = {};
+        if (queryOptions?.limit)
+            options.limit = queryOptions.limit;
+        if (queryOptions?.cursor)
+            options.uniqueStartKey = queryOptions.cursor;
+        if (Object.keys(options).length > 0)
+            body.options = options;
+        return this.post(`/app/${appId}/api/databases/${databaseId}/admin-data/query`, body);
+    }
+    // ============================================
+    // DATABASE OPERATIONS (registered operations)
+    // ============================================
+    async listDatabaseOperations(appId, databaseId) {
+        return this.get(`/app/${appId}/api/databases/${databaseId}/operations`);
+    }
+    async executeDatabaseOperation(appId, databaseId, operationName, data, token, options) {
+        const path = `/app/${appId}/api/databases/${databaseId}/operations/${encodeURIComponent(operationName)}/execute`;
+        const extraHeaders = {};
+        if (options?.timing) {
+            extraHeaders["X-Timing"] = "true";
+        }
+        if (token) {
+            return this.requestWithToken(path, token, {
+                method: "POST",
+                body: JSON.stringify(data || {}),
+                headers: extraHeaders,
+            });
+        }
+        return this.request(path, {
+            method: "POST",
+            body: JSON.stringify(data || {}),
+            headers: extraHeaders,
+        });
+    }
+    /**
+     * Execute a registered batch (bulk) database operation. Posts a chunk of
+     * items to the canonical `operations/:name/batch` endpoint (the same one the
+     * client library's `executeBatch` uses — NOT the deprecated `import-bulk`
+     * alias). Used by `databases import-csv`.
+     *
+     * @returns `{ imported, failed }` — DO-level write outcome counts. Per-item
+     *   validation/access failures abort the whole chunk with a 4xx (thrown).
+     */
+    async executeBatch(appId, databaseId, operationName, batch) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/operations/${encodeURIComponent(operationName)}/batch`, { batch });
+    }
+    /**
+     * Make a request using a specific JWT token instead of the CLI's credentials.
+     * Used for executing operations as a different user.
+     */
+    async requestWithToken(path, token, options = {}) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}${path}`;
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            ...(options.headers || {}),
+        };
+        const response = await fetchWithTLS(url, { ...options, headers });
+        const text = await response.text();
+        if (!response.ok) {
+            const parsed = parseErrorResponse(response, text, path);
+            throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
+        }
+        return text ? JSON.parse(text) : null;
+    }
+    // ============================================
+    // DATABASE INDEXES
     // ============================================
-    async listDatabaseGroupPermissions(appId, databaseId) {
-        return this.get(`/app/${appId}/api/databases/${databaseId}/group-permissions`);
+    async listDatabaseIndexes(appId, databaseId, modelName) {
+        return this.get(`/app/${appId}/api/databases/${databaseId}/records/indexes`, modelName ? { modelName } : undefined);
     }
-    async grantDatabaseGroupPermission(appId, databaseId, data) {
-        return this.post(`/app/${appId}/api/databases/${databaseId}/group-permissions`, data);
+    async registerDatabaseIndex(appId, databaseId, data) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/records/index/register`, data);
     }
-    async revokeDatabaseGroupPermission(appId, databaseId, groupType, groupId) {
-        return this.delete(`/app/${appId}/api/databases/${databaseId}/group-permissions/${groupType}/${groupId}`);
+    async dropDatabaseIndex(appId, databaseId, data) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/records/index/drop`, data);
+    }
+    /**
+     * Issue #974: back-provision an existing database instance's schema-declared
+     * unique indexes by reading its type schema and registering any declared-but-
+     * missing unique index. Idempotent.
+     */
+    async reindexDatabaseFromSchema(appId, databaseId) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/reindex`, {});
+    }
+    // ============================================
+    // DATABASE TYPE CONFIGS
+    // ============================================
+    async listDatabaseTypeConfigs(appId) {
+        return this.get(`/app/${appId}/api/databases/types`);
+    }
+    async getDatabaseTypeConfig(appId, databaseType) {
+        return this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}`);
+    }
+    async createDatabaseTypeConfig(appId, data) {
+        return this.post(`/app/${appId}/api/databases/types`, data);
+    }
+    async updateDatabaseTypeConfig(appId, databaseType, data, expectedModifiedAt, options) {
+        const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
+        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, options) {
+        const query = options?.force ? "?force=true" : "";
+        return this.delete(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}${query}`);
+    }
+    /**
+     * 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
+    // ============================================
+    async listDatabaseTypeOperations(appId, databaseType) {
+        return this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations`);
+    }
+    async getDatabaseTypeOperation(appId, databaseType, name) {
+        return this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations/${encodeURIComponent(name)}`);
+    }
+    async createDatabaseTypeOperation(appId, databaseType, data, 
+    // Issue #813 (1A): when `dryRun` is set the server runs the op-edit gate
+    // without persisting — used by `sync push --dry-run` to surface gate
+    // failures the real push would hit. `schemaOverride` lets the gate run
+    // against the schema the SAME push is about to land (so an op that depends
+    // on a new field isn't falsely rejected against the stale stored schema).
+    //
+    // Issue #915 (defect a, follow-up): for a FRESH db-type the parent config
+    // does not exist on the server yet, so the server's "access required"
+    // check has no `defaultAccess` to fall back on. Thread the TOML-declared
+    // type-level `defaultAccess` so an op that omits `access` (intending to
+    // inherit it after the type is created) isn't falsely rejected during the
+    // dry-run. Server only trusts this on the fresh-type dry-run path.
+    options) {
+        const query = options?.dryRun ? "?dryRun=true" : "";
+        let body = data;
+        if (options?.dryRun && options.schemaOverride !== undefined) {
+            body = { ...body, schemaOverride: options.schemaOverride };
+        }
+        if (options?.dryRun && options.defaultAccess !== undefined) {
+            body = { ...body, defaultAccess: options.defaultAccess };
+        }
+        return this.post(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations${query}`, body);
+    }
+    async updateDatabaseTypeOperation(appId, databaseType, name, data, expectedModifiedAt, 
+    // Issue #813 (1A): dry-run runs the op-edit gate without persisting.
+    // `schemaOverride` gates against the schema the same push is landing.
+    options) {
+        let body = expectedModifiedAt ? { ...data, expectedModifiedAt } : { ...data };
+        if (options?.dryRun && options.schemaOverride !== undefined) {
+            body = { ...body, schemaOverride: options.schemaOverride };
+        }
+        const query = options?.dryRun ? "?dryRun=true" : "";
+        return this.patch(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations/${encodeURIComponent(name)}${query}`, body);
+    }
+    async deleteDatabaseTypeOperation(appId, databaseType, name) {
+        return this.delete(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/operations/${encodeURIComponent(name)}`);
+    }
+    // ============================================
+    // DATABASE TYPE SUBSCRIPTIONS (#740 / #803)
+    // ============================================
+    //
+    // Transparent passthroughs against the server's type-scoped subscription
+    // routes (GET/POST/PUT/DELETE `/databases/types/:type/subscriptions[/:key]`).
+    // The wire format is authoritative in the controller
+    // (`database-type-subscriptions-controller.ts`): create requires
+    // `subscriptionKey`, `displayName`, `modelName`, `filter` (CEL), `access`
+    // (CEL); optional `description`, `select` (string[]), `emit`
+    // (enter/update/leave subset), `params` (object, ≤5 entries), `status`.
+    //
+    // The list endpoint wraps results in `{ items: [...] }` (unlike operations,
+    // which returns a bare array). We unwrap here so callers get an array,
+    // matching `listDatabaseTypeOperations`.
+    async listDatabaseTypeSubscriptions(appId, databaseType) {
+        const result = await this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions`);
+        if (Array.isArray(result))
+            return result;
+        return Array.isArray(result?.items) ? result.items : [];
+    }
+    async getDatabaseTypeSubscription(appId, databaseType, subscriptionKey) {
+        return this.get(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions/${encodeURIComponent(subscriptionKey)}`);
+    }
+    async createDatabaseTypeSubscription(appId, databaseType, data) {
+        return this.post(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions`, data);
+    }
+    async updateDatabaseTypeSubscription(appId, databaseType, subscriptionKey, data) {
+        return this.put(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions/${encodeURIComponent(subscriptionKey)}`, data);
+    }
+    async deleteDatabaseTypeSubscription(appId, databaseType, subscriptionKey) {
+        return this.delete(`/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}/subscriptions/${encodeURIComponent(subscriptionKey)}`);
     }
     // ============================================
     // GROUPS
@@ -754,8 +1412,11 @@ export class ApiClient {
     async removeGroupMember(appId, groupType, groupId, userId) {
         return this.delete(`/app/${appId}/api/groups/${groupType}/${groupId}/members/${userId}`);
     }
-    async updateGroupMemberRole(appId, groupType, groupId, userId, data) {
-        return this.patch(`/app/${appId}/api/groups/${groupType}/${groupId}/members/${userId}`, data);
+    // ============================================
+    // GROUP RESOURCE LISTINGS
+    // ============================================
+    async listGroupDocuments(appId, groupType, groupId) {
+        return this.get(`/app/${appId}/api/groups/${groupType}/${groupId}/documents`);
     }
     // ============================================
     // USER MEMBERSHIPS
@@ -763,6 +1424,391 @@ export class ApiClient {
     async listUserMemberships(appId, userId) {
         return this.get(`/app/${appId}/api/users/${userId}/memberships`);
     }
+    // ============================================
+    // DOCUMENT GROUP PERMISSIONS
+    // ============================================
+    async listDocumentGroupPermissions(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/group-permissions`);
+    }
+    async grantDocumentGroupPermission(appId, documentId, data) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/group-permissions`, data);
+    }
+    async revokeDocumentGroupPermission(appId, documentId, groupType, groupId) {
+        return this.delete(`/app/${appId}/api/documents/${documentId}/group-permissions/${groupType}/${groupId}`);
+    }
+    // ============================================
+    // COLLECTIONS
+    // ============================================
+    async listCollections(appId, params) {
+        const qs = new URLSearchParams();
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.cursor)
+            qs.set("cursor", params.cursor);
+        const q = qs.toString();
+        const result = await this.get(`/app/${appId}/api/collections${q ? `?${q}` : ""}`);
+        return {
+            items: result?.items ?? [],
+            nextCursor: result?.cursor ?? null,
+        };
+    }
+    async listAllCollections(appId, params) {
+        const qs = new URLSearchParams();
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.cursor)
+            qs.set("cursor", params.cursor);
+        const q = qs.toString();
+        const result = await this.get(`/app/${appId}/api/admin/collections${q ? `?${q}` : ""}`);
+        return {
+            items: result?.items ?? [],
+            nextCursor: result?.cursor ?? null,
+        };
+    }
+    async createCollection(appId, data) {
+        return this.post(`/app/${appId}/api/collections`, data);
+    }
+    async getCollection(appId, collectionId) {
+        return this.get(`/app/${appId}/api/collections/${collectionId}`);
+    }
+    async updateCollection(appId, collectionId, data) {
+        return this.patch(`/app/${appId}/api/collections/${collectionId}`, data);
+    }
+    async deleteCollection(appId, collectionId) {
+        return this.delete(`/app/${appId}/api/collections/${collectionId}`);
+    }
+    // ============================================
+    // COLLECTION DOCUMENTS
+    // ============================================
+    async listCollectionDocuments(appId, collectionId, params) {
+        const qs = new URLSearchParams();
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.cursor)
+            qs.set("cursor", params.cursor);
+        const q = qs.toString();
+        const result = await this.get(`/app/${appId}/api/collections/${collectionId}/documents${q ? `?${q}` : ""}`);
+        return {
+            items: result?.items ?? [],
+            nextCursor: result?.cursor ?? null,
+        };
+    }
+    async addCollectionDocument(appId, collectionId, data) {
+        return this.post(`/app/${appId}/api/collections/${collectionId}/documents`, data);
+    }
+    async removeCollectionDocument(appId, collectionId, documentId) {
+        return this.delete(`/app/${appId}/api/collections/${collectionId}/documents/${documentId}`);
+    }
+    async listCollectionsForDocument(appId, documentId, params) {
+        const qs = new URLSearchParams();
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        if (params?.cursor)
+            qs.set("cursor", params.cursor);
+        const q = qs.toString();
+        const result = await this.get(`/app/${appId}/api/documents/${documentId}/collections${q ? `?${q}` : ""}`);
+        return {
+            items: result?.items ?? [],
+            nextCursor: result?.cursor ?? null,
+        };
+    }
+    // ============================================
+    // COLLECTION ACCESS (GROUPS + MEMBERS)
+    // ============================================
+    async getCollectionAccess(appId, collectionId) {
+        return this.get(`/app/${appId}/api/collections/${collectionId}/access`);
+    }
+    async grantCollectionGroupPermission(appId, collectionId, data) {
+        return this.post(`/app/${appId}/api/collections/${collectionId}/group-permissions`, data);
+    }
+    async revokeCollectionGroupPermission(appId, collectionId, groupType, groupId) {
+        return this.delete(`/app/${appId}/api/collections/${collectionId}/group-permissions/${groupType}/${groupId}`);
+    }
+    async addCollectionMember(appId, collectionId, data) {
+        return this.post(`/app/${appId}/api/collections/${collectionId}/members`, data);
+    }
+    async removeCollectionMember(appId, collectionId, userId) {
+        return this.delete(`/app/${appId}/api/collections/${collectionId}/members/${userId}`);
+    }
+    // ============================================
+    // COLLECTION TYPE CONFIGS
+    // ============================================
+    async listCollectionTypeConfigs(appId) {
+        return this.get(`/app/${appId}/api/collection-type-configs`);
+    }
+    async getCollectionTypeConfig(appId, collectionType) {
+        return this.get(`/app/${appId}/api/collection-type-configs/${collectionType}`);
+    }
+    async createCollectionTypeConfig(appId, data) {
+        return this.post(`/app/${appId}/api/collection-type-configs`, data);
+    }
+    async updateCollectionTypeConfig(appId, collectionType, data, expectedModifiedAt) {
+        const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
+        return this.patch(`/app/${appId}/api/collection-type-configs/${collectionType}`, body);
+    }
+    async deleteCollectionTypeConfig(appId, collectionType) {
+        return this.delete(`/app/${appId}/api/collection-type-configs/${collectionType}`);
+    }
+    // ============================================
+    // METADATA CATEGORY CONFIGS (issue #1304, P-B)
+    // ============================================
+    /**
+     * List all metadata category configs for an app. The route returns
+     * `{ configs: [...] }`; unwrap to a bare array to match the other
+     * `list*Configs` helpers.
+     */
+    async listMetadataCategoryConfigs(appId) {
+        const res = await this.get(`/app/${appId}/api/metadata-categories`);
+        return Array.isArray(res?.configs) ? res.configs : [];
+    }
+    async getMetadataCategoryConfig(appId, resourceType, category) {
+        return this.get(`/app/${appId}/api/metadata-categories/${encodeURIComponent(resourceType)}/${encodeURIComponent(category)}`);
+    }
+    /**
+     * Create or replace a metadata category config (idempotent upsert via the
+     * path-addressed PUT route). `resourceType` / `category` identify the config;
+     * the body carries `schema` / `readRule` / `writeRule` / `description`.
+     */
+    async upsertMetadataCategoryConfig(appId, resourceType, category, data) {
+        return this.put(`/app/${appId}/api/metadata-categories/${encodeURIComponent(resourceType)}/${encodeURIComponent(category)}`, data);
+    }
+    // ============================================
+    // ACCESS RULE SETS
+    // ============================================
+    async listRuleSets(appId, params) {
+        return this.get(`/app/${appId}/api/rule-sets`, params);
+    }
+    async createRuleSet(appId, data) {
+        return this.post(`/app/${appId}/api/rule-sets`, data);
+    }
+    async getRuleSet(appId, ruleSetId) {
+        return this.get(`/app/${appId}/api/rule-sets/${ruleSetId}`);
+    }
+    async updateRuleSet(appId, ruleSetId, data, expectedModifiedAt) {
+        const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
+        return this.patch(`/app/${appId}/api/rule-sets/${ruleSetId}`, body);
+    }
+    async deleteRuleSet(appId, ruleSetId) {
+        return this.delete(`/app/${appId}/api/rule-sets/${ruleSetId}`);
+    }
+    async getRuleSetSchema(appId) {
+        return this.get(`/app/${appId}/api/rule-sets/schema`);
+    }
+    async getRuleSetResourceTypes(appId) {
+        return this.get(`/app/${appId}/api/rule-sets/resource-types`);
+    }
+    async testRuleSet(appId, ruleSetId, data) {
+        return this.post(`/app/${appId}/api/rule-sets/${ruleSetId}/test`, data);
+    }
+    async debugRuleSet(appId, data) {
+        return this.post(`/app/${appId}/api/rule-sets/debug`, data);
+    }
+    // ============================================
+    // GROUP TYPE CONFIGS
+    // ============================================
+    async listGroupTypeConfigs(appId) {
+        return this.get(`/app/${appId}/api/group-type-configs`);
+    }
+    async getGroupTypeConfig(appId, groupType) {
+        return this.get(`/app/${appId}/api/group-type-configs/${groupType}`);
+    }
+    async createGroupTypeConfig(appId, data) {
+        return this.post(`/app/${appId}/api/group-type-configs`, data);
+    }
+    async updateGroupTypeConfig(appId, groupType, data, expectedModifiedAt) {
+        const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
+        return this.patch(`/app/${appId}/api/group-type-configs/${groupType}`, body);
+    }
+    async deleteGroupTypeConfig(appId, groupType) {
+        return this.delete(`/app/${appId}/api/group-type-configs/${groupType}`);
+    }
+    // ============================================
+    // DOCUMENT EXPORT / IMPORT
+    // ============================================
+    async exportDocumentState(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/export/state`);
+    }
+    async importDocumentState(appId, documentId, stateBase64) {
+        return this.post(`/app/${appId}/api/documents/${documentId}/import/state`, { state: stateBase64 });
+    }
+    async getDocument(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}`);
+    }
+    async createDocument(appId, data) {
+        return this.post(`/app/${appId}/api/documents`, data);
+    }
+    async listDocumentPermissions(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/permissions`);
+    }
+    async grantDocumentPermission(appId, documentId, permissions) {
+        return this.put(`/app/${appId}/api/documents/${documentId}/permissions`, { permissions });
+    }
+    async listDocumentInvitations(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/invitations`);
+    }
+    async listDocumentBlobs(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/blobs`);
+    }
+    async downloadBlob(appId, documentId, blobId) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}/blobs/${blobId}/download`;
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+        };
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const response = await fetchWithTLS(url, { headers });
+        if (!response.ok) {
+            throw new ApiError(`Failed to download blob: ${response.statusText}`, response.status);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    }
+    async uploadBlob(appId, documentId, blobId, data, meta) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}/blobs/${blobId}`;
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+            "Content-Type": meta.contentType,
+            "X-Blob-Filename": encodeURIComponent(meta.filename),
+            "X-Blob-Size": String(data.length),
+            "X-Blob-Sha256": meta.sha256,
+        };
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const response = await fetchWithTLS(url, {
+            method: "PUT",
+            headers,
+            body: data,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new ApiError(`Failed to upload blob: ${text}`, response.status);
+        }
+        return response.json();
+    }
+    async listDocumentAliases(appId, documentId) {
+        return this.get(`/app/${appId}/api/documents/${documentId}/aliases`);
+    }
+    async setDocumentAlias(appId, aliasScope, aliasKey, documentId, ownerUserId, mustNotExist) {
+        return this.put(`/app/${appId}/api/document-aliases/${aliasScope}/${encodeURIComponent(aliasKey)}`, {
+            documentId,
+            userId: ownerUserId,
+            mustNotExist,
+        });
+    }
+    async findUserByEmail(appId, email) {
+        try {
+            const result = await this.get(`/app/${appId}/api/users`, { email });
+            const items = result?.items || (Array.isArray(result) ? result : []);
+            return items[0] || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async listAdminDocuments(appId, userId) {
+        const result = await this.get(`/admin/api/apps/${appId}/documents`, { userId });
+        return result?.documents || result || [];
+    }
+    // ============================================
+    // DATABASE EXPORT / IMPORT
+    // ============================================
+    async saveDatabaseRecord(appId, databaseId, modelName, id, data) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/admin-data/save`, {
+            modelName,
+            id,
+            data,
+        });
+    }
+    async batchDatabaseRecords(appId, databaseId, operations) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/admin-data/batch`, { operations });
+    }
+    async deleteDatabaseRecord(appId, databaseId, modelName, id) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/admin-data/delete`, { modelName, id });
+    }
+    async batchDeleteDatabaseRecords(appId, databaseId, operations) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/admin-data/batch`, { operations });
+    }
+    async listDatabaseUniqueConstraints(appId, databaseId) {
+        const result = await this.get(`/app/${appId}/api/databases/${databaseId}/records/unique-constraints`);
+        return result?.constraints || result || [];
+    }
+    async registerDatabaseUniqueConstraint(appId, databaseId, constraint) {
+        return this.post(`/app/${appId}/api/databases/${databaseId}/records/unique-constraint/register`, constraint);
+    }
+    // ============================================
+    // BLOB BUCKETS
+    // ============================================
+    async listBlobBuckets(appId) {
+        return this.get(`/app/${appId}/api/blob-buckets`);
+    }
+    async createBlobBucket(appId, payload) {
+        return this.post(`/app/${appId}/api/blob-buckets`, payload);
+    }
+    async getBlobBucket(appId, bucketIdOrKey) {
+        return this.get(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}`);
+    }
+    async updateBlobBucket(appId, bucketIdOrKey, payload) {
+        return this.patch(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}`, payload);
+    }
+    async deleteBlobBucket(appId, bucketIdOrKey) {
+        return this.delete(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}`);
+    }
+    async listBucketBlobs(appId, bucketIdOrKey, params) {
+        return this.get(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs`, params);
+    }
+    async uploadBucketBlob(appId, bucketIdOrKey, data, meta) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs`;
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+            "Content-Type": meta.contentType,
+            "X-Blob-Filename": encodeURIComponent(meta.filename),
+        };
+        if (meta.tags && meta.tags.length > 0) {
+            headers["X-Blob-Tags"] = JSON.stringify(meta.tags);
+        }
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const response = await fetchWithTLS(url, {
+            method: "POST",
+            headers,
+            body: data,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new ApiError(`Failed to upload blob: ${text}`, response.status);
+        }
+        return response.json();
+    }
+    async downloadBucketBlob(appId, bucketIdOrKey, blobId) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs/${blobId}`;
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+        };
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        const response = await fetchWithTLS(url, { headers });
+        if (!response.ok) {
+            throw new ApiError(`Failed to download blob: ${response.statusText}`, response.status);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    }
+    async deleteBucketBlob(appId, bucketIdOrKey, blobId) {
+        return this.delete(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs/${blobId}`);
+    }
+    async getBucketBlobSignedUrl(appId, bucketIdOrKey, blobId, expiresInSeconds) {
+        return this.post(`/app/${appId}/api/blob-buckets/${encodeURIComponent(bucketIdOrKey)}/blobs/${blobId}/signed-url`, {
+            expiresInSeconds: expiresInSeconds || 300,
+        });
+    }
 }
 // Export a singleton instance
 export const apiClient = new ApiClient();