@vertesia/client 1.2.0 → 1.4.0-dev.20260614.160504Z

package/src/store/FilesApi.ts

@@ -1,8 +1,11 @@
-import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
-import {
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type {
+    BucketReadAccessStatusResponse,
     BulkUploadUrlsPayload,
     BulkUploadUrlsResponse,
     DeleteFileResult,
+    EnsureBucketReadAccessPayload,
+    EnsureBucketReadAccessResponse,
     FileBucketResponse,
     FileListResponse,
     FileMetadataResponse,
@@ -11,14 +14,15 @@ import {
     GetFileUrlResponse,
     GetUploadUrlPayload,
     SetFileMetadataPayload,
-} from "@vertesia/common";
-import { StreamSource } from "../StreamSource.js";
+} from '@vertesia/common';
+import { StreamSource } from '../StreamSource.js';
+import { fetchSignedUrl } from './signed-url.js';
 
-export const MEMORIES_PREFIX = "memories";
-export const ARTIFACTS_PREFIX = "agents";
+export const MEMORIES_PREFIX = 'memories';
+export const ARTIFACTS_PREFIX = 'agents';
 
 export function getMemoryFilePath(name: string) {
-    const nameWithExt = name.endsWith(".tar.gz") ? name : name + ".tar.gz";
+    const nameWithExt = name.endsWith('.tar.gz') ? name : `${name}.tar.gz`;
     return `${MEMORIES_PREFIX}/${nameWithExt}`;
 }
 
@@ -33,11 +37,11 @@ export function getAgentArtifactPath(runId: string, name: string): string {
 
 export class FilesApi extends ApiTopic {
     constructor(parent: ClientBase) {
-        super(parent, "/api/v1/files");
+        super(parent, '/api/v1/files');
     }
 
     async deleteFile(path: string, prefix?: boolean): Promise<DeleteFileResult> {
-        return this.delete(`/${path}`, { query: { prefix } });
+        return this.del(`/${path}`, { query: { prefix } });
     }
 
     /**
@@ -48,7 +52,7 @@ export class FilesApi extends ApiTopic {
      * @returns
      */
     getMetadata(uri: string): Promise<FileMetadataResponse> {
-        return this.get("/metadata", {
+        return this.get('/metadata', {
             query: {
                 file: uri,
             },
@@ -63,7 +67,7 @@ export class FilesApi extends ApiTopic {
      */
     setFileMetadata(file: string, metadata: Record<string, string>): Promise<FileMetadataUpdateResult> {
         const payload: SetFileMetadataPayload = { file, metadata };
-        return this.put("/metadata", { payload });
+        return this.put('/metadata', { payload });
     }
 
     /**
@@ -72,7 +76,16 @@ export class FilesApi extends ApiTopic {
      * @returns
      */
     getOrCreateBucket(): Promise<FileBucketResponse> {
-        return this.post("/bucket");
+        return this.post('/bucket');
+    }
+
+    ensureBucketReadAccess(principal: string): Promise<EnsureBucketReadAccessResponse> {
+        const payload: EnsureBucketReadAccessPayload = { principal };
+        return this.post('/bucket/read-access', { payload });
+    }
+
+    getBucketReadAccessStatus(principal: string): Promise<BucketReadAccessStatusResponse> {
+        return this.get('/bucket/read-access', { query: { principal } });
     }
 
     list(prefix: string): Promise<FileListResponse> {
@@ -80,19 +93,19 @@ export class FilesApi extends ApiTopic {
     }
 
     getUploadUrl(payload: GetUploadUrlPayload): Promise<GetFileUrlResponse> {
-        return this.post("/upload-url", {
+        return this.post('/upload-url', {
             payload,
         });
     }
 
     // Strictly typed: provide either simple args or a full payload via a separate method
-    getDownloadUrl(file: string, name?: string, disposition?: "inline" | "attachment"): Promise<GetFileUrlResponse> {
+    getDownloadUrl(file: string, name?: string, disposition?: 'inline' | 'attachment'): Promise<GetFileUrlResponse> {
         const payload: GetFileUrlPayload = { file, name, disposition };
-        return this.post("/download-url", { payload });
+        return this.post('/download-url', { payload });
     }
 
     getDownloadUrlWithOptions(payload: GetFileUrlPayload): Promise<GetFileUrlResponse> {
-        return this.post("/download-url", { payload });
+        return this.post('/download-url', { payload });
     }
 
     /**
@@ -102,7 +115,7 @@ export class FilesApi extends ApiTopic {
      * @returns Array of upload URL responses
      */
     bulkGetUploadUrls(payload: BulkUploadUrlsPayload): Promise<BulkUploadUrlsResponse> {
-        return this.post("/bulk-upload-urls", { payload });
+        return this.post('/bulk-upload-urls', { payload });
     }
 
     /**
@@ -111,8 +124,11 @@ export class FilesApi extends ApiTopic {
      * @param concurrency - Maximum number of concurrent uploads (default: 10)
      * @returns Array of upload results with source URI, name, type, and etag
      */
-    async bulkUpload(sources: (StreamSource | File)[], concurrency = 10): Promise<{ source: string; name: string; type?: string; etag?: string }[]> {
-        const fileDescriptors = sources.map(s => ({
+    async bulkUpload(
+        sources: (StreamSource | File)[],
+        concurrency = 10,
+    ): Promise<{ source: string; name: string; type?: string; etag?: string }[]> {
+        const fileDescriptors = sources.map((s) => ({
             name: s.name,
             mime_type: s.type,
             id: s instanceof StreamSource ? s.id : undefined,
@@ -132,11 +148,9 @@ export class FilesApi extends ApiTopic {
                     const isStream = source instanceof StreamSource;
                     const sourceMimeType = source.type || mime_type;
 
-                    const res = await fetch(url, {
+                    const res = await fetchSignedUrl(url, {
                         method: 'PUT',
                         body: isStream ? source.stream : source,
-                        //@ts-expect-error: duplex is not in the types
-                        duplex: isStream ? 'half' : undefined,
                         headers: sourceMimeType ? { 'Content-Type': sourceMimeType } : undefined,
                     });
 
@@ -146,7 +160,7 @@ export class FilesApi extends ApiTopic {
 
                     const etag = res.headers.get('etag')?.replace(/^"(.*)"$/, '$1');
                     results[idx] = { source: id, name: source.name, type: sourceMimeType, etag };
-                })
+                }),
             );
         }
 
@@ -154,37 +168,42 @@ export class FilesApi extends ApiTopic {
     }
 
     /**
-     * Upload content to a file and return the full path (including bucket name) of the uploaded file
+     * Upload content to a file and return the file id.
      * @param source
-     * @returns
+     * @returns the uploaded file id
      */
     async uploadFile(source: StreamSource | File): Promise<string> {
+        return (await this.uploadFileWithPath(source)).id;
+    }
+
+    /**
+     * Upload content to a file and return both the file id and its storage path
+     * (e.g. "bucket-name/path/to/file"). Prefer this over {@link uploadFile} when the
+     * caller needs an importable reference (the path can be turned into a "gs://…" URL),
+     * not just the opaque id.
+     * @param source
+     * @returns the uploaded file id and storage path
+     */
+    async uploadFileWithPath(source: StreamSource | File): Promise<{ id: string; path: string }> {
         const isStream = source instanceof StreamSource;
         const { url, id, path } = await this.getUploadUrl(source);
 
-        await fetch(url, {
-            method: "PUT",
+        const res = await fetchSignedUrl(url, {
+            method: 'PUT',
             body: isStream ? source.stream : source,
-            //@ts-expect-error: duplex is not in the types. See https://github.com/node-fetch/node-fetch/issues/1769
-            duplex: isStream ? "half" : undefined,
             headers: {
-                "Content-Type": source.type || "application/gzip",
+                'Content-Type': source.type || 'application/gzip',
             },
-        })
-            .then((res: Response) => {
-                if (res.ok) {
-                    return res;
-                } else {
-                    console.log(res);
-                    throw new Error(`Failed to upload file: ${res.statusText}`);
-                }
-            })
-            .catch((err) => {
-                console.error("Failed to upload file", { err, url, id, path });
-                throw err;
-            });
+        }).catch((err) => {
+            console.error('Failed to upload file', { err, url, id, path });
+            throw err;
+        });
+        if (!res.ok) {
+            console.log(res);
+            throw new Error(`Failed to upload file: ${res.statusText}`);
+        }
 
-        return id;
+        return { id, path };
     }
 
     /**
@@ -194,13 +213,11 @@ export class FilesApi extends ApiTopic {
      */
     async downloadFile(location: string): Promise<ReadableStream<Uint8Array<ArrayBuffer>>> {
         //if start with HTTPS, no download url needed - assume it's signed already
-        const needSign = !location.startsWith("https:");
-        const { url } = needSign
-            ? await this.getDownloadUrl(location)
-            : { url: location };
+        const needSign = !location.startsWith('https:');
+        const { url } = needSign ? await this.getDownloadUrl(location) : { url: location };
 
-        const res = await fetch(url, {
-            method: "GET",
+        const res = await fetchSignedUrl(url, {
+            method: 'GET',
         })
             .then((res: Response) => {
                 if (res.ok) {
@@ -211,9 +228,7 @@ export class FilesApi extends ApiTopic {
                     throw new Error(`File at ${url} is forbidden`);
                 } else {
                     console.log(res);
-                    throw new Error(
-                        `Failed to download file ${location}: ${res.statusText}`,
-                    );
+                    throw new Error(`Failed to download file ${location}: ${res.statusText}`);
                 }
             })
             .catch((err) => {
@@ -222,9 +237,7 @@ export class FilesApi extends ApiTopic {
             });
 
         if (!res.body) {
-            throw new Error(
-                `No body in response while downloading file ${location}`,
-            );
+            throw new Error(`No body in response while downloading file ${location}`);
         }
 
         return res.body;
@@ -237,41 +250,27 @@ export class FilesApi extends ApiTopic {
      * @returns The destination file URI
      */
     async copyFile(source: string, dest: string): Promise<string> {
-        const response = await this.post("/copy", {
+        const response = (await this.post('/copy', {
             payload: { source, dest },
-        }) as { success: boolean; source: string; dest: string };
+        })) as { success: boolean; source: string; dest: string };
         return response.dest;
     }
 
     async uploadMemoryPack(source: StreamSource | File): Promise<string> {
         const fileId = getMemoryFilePath(source.name);
-        const nameWithExt = source.name.endsWith(".tar.gz")
-            ? source.name
-            : source.name + ".tar.gz";
+        const nameWithExt = source.name.endsWith('.tar.gz') ? source.name : `${source.name}.tar.gz`;
         if (source instanceof File) {
             const file = source as File;
-            return this.uploadFile(
-                new StreamSource(file.stream(), nameWithExt, file.type, fileId),
-            );
+            return this.uploadFile(new StreamSource(file.stream(), nameWithExt, file.type, fileId));
         } else {
-            return this.uploadFile(
-                new StreamSource(
-                    source.stream,
-                    nameWithExt,
-                    source.type,
-                    fileId,
-                ),
-            );
+            return this.uploadFile(new StreamSource(source.stream, nameWithExt, source.type, fileId));
         }
     }
 
-    async downloadMemoryPack(
-        name: string,
-        gunzip: boolean = false,
-    ): Promise<ReadableStream<Uint8Array>> {
+    async downloadMemoryPack(name: string, gunzip: boolean = false): Promise<ReadableStream<Uint8Array>> {
         let stream = await this.downloadFile(getMemoryFilePath(name));
         if (gunzip) {
-            const ds = new DecompressionStream("gzip");
+            const ds = new DecompressionStream('gzip');
             stream = stream.pipeThrough(ds);
         }
         return stream;
@@ -285,7 +284,7 @@ export class FilesApi extends ApiTopic {
      * @returns Array of file paths matching the prefix
      */
     listByPrefix(prefix: string): Promise<{ files: string[] }> {
-        return this.get("/list", { query: { prefix } });
+        return this.get('/list', { query: { prefix } });
     }
 
     /**
@@ -299,13 +298,9 @@ export class FilesApi extends ApiTopic {
         const artifactPath = getAgentArtifactPath(runId, name);
         if (source instanceof File) {
             const file = source as File;
-            return this.uploadFile(
-                new StreamSource(file.stream(), name, file.type, artifactPath)
-            );
+            return this.uploadFile(new StreamSource(file.stream(), name, file.type, artifactPath));
         } else {
-            return this.uploadFile(
-                new StreamSource(source.stream, name, source.type, artifactPath)
-            );
+            return this.uploadFile(new StreamSource(source.stream, name, source.type, artifactPath));
         }
     }
 
@@ -330,7 +325,7 @@ export class FilesApi extends ApiTopic {
     getArtifactDownloadUrl(
         runId: string,
         name: string,
-        disposition?: "inline" | "attachment"
+        disposition?: 'inline' | 'attachment',
     ): Promise<GetFileUrlResponse> {
         const artifactPath = getAgentArtifactPath(runId, name);
         return this.getDownloadUrl(artifactPath, name, disposition);

package/src/store/HiveMemoryApi.ts

@@ -1,12 +1,12 @@
-import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
-import {
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type {
     CreateHiveMemoryPayload,
     FormattedMemoryForAgent,
     HiveMemory,
     HiveMemorySearchParams,
     HiveMemorySearchResult,
     UpdateHiveMemoryPayload,
-} from "@vertesia/common";
+} from '@vertesia/common';
 
 /**
  * Statistics about hive memories in the project
@@ -42,7 +42,7 @@ export interface RecallResult {
  */
 export class HiveMemoryApi extends ApiTopic {
     constructor(parent: ClientBase) {
-        super(parent, "/api/v1/hive-memory");
+        super(parent, '/api/v1/hive-memory');
     }
 
     /**
@@ -50,12 +50,7 @@ export class HiveMemoryApi extends ApiTopic {
      *
      * @param options - Optional filters and pagination
      */
-    list(options?: {
-        category?: string;
-        scope?: string;
-        limit?: number;
-        offset?: number;
-    }): Promise<HiveMemory[]> {
+    list(options?: { category?: string; scope?: string; limit?: number; offset?: number }): Promise<HiveMemory[]> {
         const params = new URLSearchParams();
         if (options?.category) params.set('category', options.category);
         if (options?.scope) params.set('scope', options.scope);
@@ -79,7 +74,7 @@ export class HiveMemoryApi extends ApiTopic {
      * @param payload - Memory content including category, summary, and learnings
      */
     create(payload: CreateHiveMemoryPayload): Promise<HiveMemory> {
-        return this.post("/", { payload });
+        return this.post('/', { payload });
     }
 
     /**
@@ -109,7 +104,7 @@ export class HiveMemoryApi extends ApiTopic {
      * @param params - Search parameters including query, filters, and pagination
      */
     search(params: HiveMemorySearchParams): Promise<HiveMemorySearchResult> {
-        return this.post("/search", { payload: params });
+        return this.post('/search', { payload: params });
     }
 
     /**
@@ -139,15 +134,15 @@ export class HiveMemoryApi extends ApiTopic {
             tools?: string[];
             category?: string;
             maxResults?: number;
-        }
+        },
     ): Promise<RecallResult> {
-        return this.post("/recall", {
+        return this.post('/recall', {
             payload: {
                 task_description: taskDescription,
                 tools: options?.tools,
                 category: options?.category,
                 max_results: options?.maxResults,
-            }
+            },
         });
     }
 
@@ -177,10 +172,7 @@ export class HiveMemoryApi extends ApiTopic {
      * @param category - Task category (e.g., "document-analysis", "data-extraction")
      * @param options - Pagination options
      */
-    getByCategory(
-        category: string,
-        options?: { limit?: number; offset?: number }
-    ): Promise<HiveMemory[]> {
+    getByCategory(category: string, options?: { limit?: number; offset?: number }): Promise<HiveMemory[]> {
         const params = new URLSearchParams();
         if (options?.limit) params.set('limit', String(options.limit));
         if (options?.offset) params.set('offset', String(options.offset));
@@ -193,7 +185,7 @@ export class HiveMemoryApi extends ApiTopic {
      * Get memory statistics for the project.
      */
     getStats(): Promise<HiveMemoryStats> {
-        return this.get("/stats");
+        return this.get('/stats');
     }
 
     /**
@@ -204,15 +196,12 @@ export class HiveMemoryApi extends ApiTopic {
      *
      * @param options - Decay parameters
      */
-    applyDecay(options?: {
-        daysThreshold?: number;
-        decayRate?: number;
-    }): Promise<{ modified_count: number }> {
-        return this.post("/admin/decay", {
+    applyDecay(options?: { daysThreshold?: number; decayRate?: number }): Promise<{ modified_count: number }> {
+        return this.post('/admin/decay', {
             payload: {
                 days_threshold: options?.daysThreshold,
                 decay_rate: options?.decayRate,
-            }
+            },
         });
     }
 
@@ -224,8 +213,8 @@ export class HiveMemoryApi extends ApiTopic {
      * @param threshold - Confidence threshold (0-1), default 0.2
      */
     archiveLowConfidence(threshold?: number): Promise<{ archived_count: number }> {
-        return this.post("/admin/archive", {
-            payload: { threshold }
+        return this.post('/admin/archive', {
+            payload: { threshold },
         });
     }
 }