primitive-admin 1.2.0-alpha.7 → 1.2.0-alpha.9

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

@@ -51,6 +51,8 @@ export interface AppChildSummary {
     expiresAt: string | null;
     /** Exact origins the child's CORS and email-redirect checks accept beside its authored lists. */
     previewOrigins?: string[];
+    /** The child's protection level: always `internal` (#4564); absent from an older server. */
+    protection?: string;
 }
 /** A child's preview origins after a write to them. */
 export interface ChildPreviewOrigins {
@@ -499,9 +501,18 @@ export declare class ApiClient {
     request<T = any>(path: string, options?: RequestInit): Promise<T>;
     /**
      * 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.
+     * `admin` among the missing scopes, or it is a protected app's refusal of
+     * a token that is no step-up, and an unexpired step-up is stored.
      */
     private stepUpApplies;
+    /**
+     * #4564 — a request outside `request` (an upload, a function invocation)
+     * sent with the CLI's own credentials, retried once with the stored step-up
+     * exactly as `request` retries. `init` builds the request for a bearer. The
+     * answer is the retry's, unless the retry was refused 401: the step-up is
+     * dropped and the original refusal comes back, still readable.
+     */
+    private fetchWithStepUp;
     /** Forget a step-up the server no longer accepts. */
     private dropStepUp;
     /** The typed error a failed response throws. */
@@ -2104,10 +2115,14 @@ export declare class ApiClient {
      * through the caller's document permission (reader+) or the app-admin arm.
      * Returns the unified `{ items, hasMore, nextCursor? }` envelope. The cursor
      * is an opaque token — feed `nextCursor` back as `cursor` for the next page.
+     * `limit` is 100 records when omitted and at most 10000; it is forwarded
+     * unparsed (a string from the command line) so the server validates it.
      */
     queryDocumentRecords(appId: string, documentId: string, modelName: string, queryOptions?: {
         filter?: Record<string, any>;
-        limit?: number;
+        /** `{ field: 1 | -1 }`, key order as precedence; the route validates it. */
+        sort?: unknown;
+        limit?: number | string;
         cursor?: string;
         /** #3764 — the format the caller believes this document has. */
         documentFormat?: 1 | 3;
@@ -2127,16 +2142,20 @@ export declare class ApiClient {
      * with `{ options: { operations, groupBy?, filter? } }`, answering `{ result }`
      * in the same shape as the database endpoint.
      *
-     * `groupBy` takes plain field names only: StringSet facet grouping and
-     * `{ field, contains }` membership grouping are database-only, which is why
-     * this signature is narrower than the databases one.
+     * `groupBy` takes plain field names and period levels `{ field, period }`
+     * (keyed `<field>_<period>` in a row's `group`): StringSet facet grouping
+     * and `{ field, contains }` membership grouping are database-only, which is
+     * why this signature is narrower than the databases one.
      */
     aggregateDocumentRecords(appId: string, documentId: string, modelName: string, options: {
         operations: {
             type: string;
             field?: string;
         }[];
-        groupBy?: string[];
+        groupBy?: Array<string | {
+            field: string;
+            period: "month" | "quarter" | "year";
+        }>;
         filter?: Record<string, any>;
     }, extra?: {
         documentFormat?: 1 | 3;
@@ -2354,6 +2373,27 @@ export declare class ApiClient {
         contentType: string;
         sha256: string;
     }): Promise<any>;
+    /**
+     * Upload a file to an agent session by `sessionId` (#4585): the document
+     * blob upload's headers and body, on the session's attachment route.
+     */
+    uploadAgentSessionAttachment(appId: string, sessionId: string, blobId: string, data: Buffer, meta: {
+        filename: string;
+        contentType: string;
+        sha256: string;
+    }): Promise<any>;
+    /** Download an agent session's file by `sessionId` (#4585). */
+    downloadAgentSessionAttachment(appId: string, sessionId: string, blobId: string): Promise<Buffer>;
+    /**
+     * An agent session file's download headers (lower-cased names) by
+     * `sessionId` (#4585). A refusal has no body, so it fails with the status
+     * alone and no code.
+     */
+    headAgentSessionAttachment(appId: string, sessionId: string, blobId: string): Promise<{
+        status: number;
+        headers: Record<string, string>;
+    }>;
+    private agentSessionAttachmentRead;
     listDocumentAliases(appId: string, documentId: string): Promise<any[]>;
     /**
      * The document a user's alias points at, or null when the user holds no

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

@@ -243,9 +243,10 @@ export class ApiClient {
         };
         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.
+        // step-up, and (#4564) so is a write a protected app refused for want of
+        // one. 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, a step-up without the scope this command needs) 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) {
@@ -265,7 +266,8 @@ export class ApiClient {
     }
     /**
      * 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.
+     * `admin` among the missing scopes, or it is a protected app's refusal of
+     * a token that is no step-up, and an unexpired step-up is stored.
      */
     stepUpApplies(response, text, path) {
         const stepUp = this.credentials?.stepUp;
@@ -273,10 +275,41 @@ export class ApiClient {
             return false;
         if (new Date(stepUp.expiresAt).getTime() <= Date.now())
             return false;
-        const details = parseErrorResponse(response, text, path).details;
+        const parsed = parseErrorResponse(response, text, path);
+        if (parsed.code === "PROTECTED_APP_STEP_UP_REQUIRED")
+            return true;
+        const details = parsed.details;
         const missing = details && !Array.isArray(details) ? details.missing : undefined;
         return Array.isArray(missing) && missing.includes("admin");
     }
+    /**
+     * #4564 — a request outside `request` (an upload, a function invocation)
+     * sent with the CLI's own credentials, retried once with the stored step-up
+     * exactly as `request` retries. `init` builds the request for a bearer. The
+     * answer is the retry's, unless the retry was refused 401: the step-up is
+     * dropped and the original refusal comes back, still readable.
+     */
+    async fetchWithStepUp(url, path, accessToken, init) {
+        const response = await fetchWithTLS(url, init(accessToken));
+        if (response.status !== 403)
+            return response;
+        // Read once to decide; hand the caller a response it can still read.
+        const text = await response.text();
+        const original = new Response(text, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+        if (!this.stepUpApplies(response, text, path))
+            return original;
+        const retried = await fetchWithTLS(url, init(this.credentials.stepUp.accessToken));
+        if (retried.status === 401) {
+            await retried.text().catch(() => "");
+            this.dropStepUp();
+            return original;
+        }
+        return retried;
+    }
     /** Forget a step-up the server no longer accepts. */
     dropStepUp() {
         if (!this.credentials?.stepUp)
@@ -944,21 +977,25 @@ export class ApiClient {
             : options?.runtime === "task"
                 ? `${base}/start`
                 : base;
-        const headers = {
-            Authorization: `Bearer ${options?.bearer ?? credentials.accessToken}`,
-            "Content-Type": "application/json",
+        const init = (bearer) => {
+            const headers = {
+                Authorization: `Bearer ${bearer}`,
+                "Content-Type": "application/json",
+            };
+            // The CLI's own credentials reach an app-scoped route through the
+            // global-admin header; a minted user token does not need it and must
+            // not carry it.
+            if (!options?.bearer && credentials.globalAdminAppId) {
+                headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+            }
+            return { method: "POST", headers, body: JSON.stringify(body) };
         };
-        // The CLI's own credentials reach an app-scoped route through the
-        // global-admin header; a minted user token does not need it and must not
-        // carry it.
-        if (!options?.bearer && credentials.globalAdminAppId) {
-            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
-        }
-        const response = await fetchWithTLS(`${credentials.serverUrl}${path}`, {
-            method: "POST",
-            headers,
-            body: JSON.stringify(body),
-        });
+        const url = `${credentials.serverUrl}${path}`;
+        // A minted user token is sent as it is; the CLI's own credentials get the
+        // step-up retry a protected app's refusal asks for (#4564).
+        const response = options?.bearer
+            ? await fetchWithTLS(url, init(options.bearer))
+            : await this.fetchWithStepUp(url, path, credentials.accessToken, init);
         const text = await response.text();
         let parsed = null;
         try {
@@ -1495,17 +1532,15 @@ export class ApiClient {
         const credentials = await this.ensureAuthenticated();
         const encodedFilename = encodeURIComponent(filename);
         const url = `${credentials.serverUrl}/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/test-cases/${testCaseId}/attachments/${encodedFilename}`;
-        const headers = {
-            Authorization: `Bearer ${credentials.accessToken}`,
-            "Content-Type": contentType,
-        };
-        if (credentials.globalAdminAppId) {
-            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
-        }
-        const response = await fetchWithTLS(url, {
-            method: "PUT",
-            headers,
-            body: data,
+        const response = await this.fetchWithStepUp(url, url, credentials.accessToken, (bearer) => {
+            const headers = {
+                Authorization: `Bearer ${bearer}`,
+                "Content-Type": contentType,
+            };
+            if (credentials.globalAdminAppId) {
+                headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+            }
+            return { method: "PUT", headers, body: data };
         });
         const text = await response.text();
         if (!response.ok) {
@@ -2460,11 +2495,15 @@ export class ApiClient {
      * through the caller's document permission (reader+) or the app-admin arm.
      * Returns the unified `{ items, hasMore, nextCursor? }` envelope. The cursor
      * is an opaque token — feed `nextCursor` back as `cursor` for the next page.
+     * `limit` is 100 records when omitted and at most 10000; it is forwarded
+     * unparsed (a string from the command line) so the server validates it.
      */
     async queryDocumentRecords(appId, documentId, modelName, queryOptions) {
         const query = {};
         if (queryOptions?.filter)
             query.filter = JSON.stringify(queryOptions.filter);
+        if (queryOptions?.sort !== undefined)
+            query.sort = JSON.stringify(queryOptions.sort);
         if (queryOptions?.documentFormat !== undefined) {
             query.documentFormat = queryOptions.documentFormat;
         }
@@ -2496,9 +2535,10 @@ export class ApiClient {
      * with `{ options: { operations, groupBy?, filter? } }`, answering `{ result }`
      * in the same shape as the database endpoint.
      *
-     * `groupBy` takes plain field names only: StringSet facet grouping and
-     * `{ field, contains }` membership grouping are database-only, which is why
-     * this signature is narrower than the databases one.
+     * `groupBy` takes plain field names and period levels `{ field, period }`
+     * (keyed `<field>_<period>` in a row's `group`): StringSet facet grouping
+     * and `{ field, contains }` membership grouping are database-only, which is
+     * why this signature is narrower than the databases one.
      */
     async aggregateDocumentRecords(appId, documentId, modelName, options, extra) {
         return this.post(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/aggregate` +
@@ -2589,18 +2629,16 @@ export class ApiClient {
         form.set("firstId", chunk.firstId);
         form.set("lastId", chunk.lastId);
         form.set("chunk", new Blob([chunk.body]), `${chunk.index}.ndjson.gz`);
-        const headers = {
-            Authorization: `Bearer ${credentials.accessToken}`,
-        };
-        if (credentials.globalAdminAppId) {
-            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
-        }
         const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}` +
             `/ingest/${encodeURIComponent(sessionId)}/chunks`;
-        const response = await fetchWithTLS(url, {
-            method: "POST",
-            headers,
-            body: form,
+        const response = await this.fetchWithStepUp(url, url, credentials.accessToken, (bearer) => {
+            const headers = {
+                Authorization: `Bearer ${bearer}`,
+            };
+            if (credentials.globalAdminAppId) {
+                headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+            }
+            return { method: "POST", headers, body: form };
         });
         const text = await response.text();
         let result = {};
@@ -2758,6 +2796,31 @@ export class ApiClient {
     async uploadBlob(appId, documentId, blobId, data, meta) {
         const credentials = await this.ensureAuthenticated();
         const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}/blobs/${blobId}`;
+        const response = await this.fetchWithStepUp(url, url, credentials.accessToken, (bearer) => {
+            const headers = {
+                Authorization: `Bearer ${bearer}`,
+                "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;
+            }
+            return { method: "PUT", headers, body: data };
+        });
+        if (!response.ok) {
+            throw await blobFailure(response, "Failed to upload blob: ");
+        }
+        return response.json();
+    }
+    /**
+     * Upload a file to an agent session by `sessionId` (#4585): the document
+     * blob upload's headers and body, on the session's attachment route.
+     */
+    async uploadAgentSessionAttachment(appId, sessionId, blobId, data, meta) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}/app/${appId}/api/agent-sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(blobId)}`;
         const headers = {
             Authorization: `Bearer ${credentials.accessToken}`,
             "Content-Type": meta.contentType,
@@ -2768,16 +2831,47 @@ export class ApiClient {
         if (credentials.globalAdminAppId) {
             headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
         }
-        const response = await fetchWithTLS(url, {
-            method: "PUT",
-            headers,
-            body: data,
-        });
+        const response = await fetchWithTLS(url, { method: "PUT", headers, body: data });
         if (!response.ok) {
-            throw await blobFailure(response, "Failed to upload blob: ");
+            throw await blobFailure(response, "Failed to upload attachment: ");
         }
         return response.json();
     }
+    /** Download an agent session's file by `sessionId` (#4585). */
+    async downloadAgentSessionAttachment(appId, sessionId, blobId) {
+        const response = await this.agentSessionAttachmentRead("GET", appId, sessionId, blobId);
+        if (!response.ok) {
+            throw await blobFailure(response, "Failed to download attachment: ");
+        }
+        return Buffer.from(await response.arrayBuffer());
+    }
+    /**
+     * An agent session file's download headers (lower-cased names) by
+     * `sessionId` (#4585). A refusal has no body, so it fails with the status
+     * alone and no code.
+     */
+    async headAgentSessionAttachment(appId, sessionId, blobId) {
+        const response = await this.agentSessionAttachmentRead("HEAD", appId, sessionId, blobId);
+        if (!response.ok && response.status !== 304) {
+            throw new ApiError(`Failed to read attachment headers: HTTP ${response.status}`, response.status);
+        }
+        const headers = {};
+        response.headers.forEach((value, name) => {
+            headers[name.toLowerCase()] = value;
+        });
+        return { status: response.status, headers };
+    }
+    async agentSessionAttachmentRead(method, appId, sessionId, blobId) {
+        const credentials = await this.ensureAuthenticated();
+        const url = `${credentials.serverUrl}/app/${appId}/api/agent-sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(blobId)}/download`;
+        const headers = {
+            Authorization: `Bearer ${credentials.accessToken}`,
+        };
+        if (credentials.globalAdminAppId) {
+            headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
+        }
+        return fetchWithTLS(url, { method, headers });
+    }
     async listDocumentAliases(appId, documentId) {
         return this.get(`/app/${appId}/api/documents/${documentId}/aliases`);
     }
@@ -2939,21 +3033,19 @@ export class ApiClient {
     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,
+        const response = await this.fetchWithStepUp(url, url, credentials.accessToken, (bearer) => {
+            const headers = {
+                Authorization: `Bearer ${bearer}`,
+                "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;
+            }
+            return { method: "POST", headers, body: data };
         });
         if (!response.ok) {
             throw await blobFailure(response, "Failed to upload blob: ");