@vertesia/client 1.5.0-dev.20260804.124748Z → 1.5.0-dev.20260807.073259Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.5.0-dev.20260804.124748Z",
+  "version": "1.5.0-dev.20260807.073259Z",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,15 +13,15 @@
   "devDependencies": {
     "@types/node": "^24.13.3",
     "rolldown": "1.2.0",
-    "typescript": "^6.0.3",
+    "typescript": "7.0.2",
     "vitest": "^4.1.10",
     "@vertesia/tsconfig": "0.1.0"
   },
   "dependencies": {
     "eventsource": "^4.1.0",
-    "@llumiverse/common": "1.5.0-dev.20260804.122431Z",
-    "@vertesia/common": "1.5.0-dev.20260804.124748Z",
-    "@vertesia/api-fetch-client": "1.5.0-dev.20260804.124748Z"
+    "@vertesia/api-fetch-client": "1.5.0-dev.20260807.073259Z",
+    "@vertesia/common": "1.5.0-dev.20260807.073259Z",
+    "@llumiverse/common": "1.5.0-dev.20260807.072147Z"
   },
   "exports": {
     ".": {
@@ -48,7 +48,7 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "87ac9166db2b38bd1be6e37adf0414ea83e402ee",
+  "gitHead": "e6ebc1482ad6c4df965d74c79f82eb25fc6e2ce3",
   "scripts": {
     "lint": "biome lint src",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",

package/src/AppsApi.ts

@@ -1,5 +1,6 @@
 import { ApiTopic, type ClientBase, type ServerError } from '@vertesia/api-fetch-client';
 import type {
+    AppApiKeyCollectionParams,
     AppBuildProgress,
     AppDeleteSummary,
     AppDevelopmentTaskDetails,
@@ -26,9 +27,11 @@ import type {
     CountResult,
     CreateAppRepoBranchRequest,
     DeleteAppVersionResponse,
+    McpApiKeyStatus,
     ProjectRef,
     PromoteAppVersionResponse,
     RequireAtLeastOne,
+    SetMcpApiKeyRequest,
     StartAppBuildRequest,
     StartAppBuildResponse,
     StartAppScaffoldRequest,
@@ -64,6 +67,27 @@ export default class AppsApi extends ApiTopic {
         return this.del(`/${id}`);
     }
 
+    /**
+     * Store the API key of an MCP tool collection declared with `auth: 'api_key'`.
+     * The key is write-only: it is encrypted server-side and never returned by any endpoint,
+     * so the response carries only the configured flag and a masked hint.
+     */
+    setMcpCollectionApiKey(appId: string, collectionId: string, apiKey: string): Promise<McpApiKeyStatus> {
+        return this.put(`/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collectionId)}/api-key`, {
+            payload: { api_key: apiKey } satisfies SetMcpApiKeyRequest,
+        });
+    }
+
+    /** Whether an MCP tool collection has an API key stored, with a masked hint for display. */
+    getMcpCollectionApiKeyStatus(appId: string, collectionId: string): Promise<McpApiKeyStatus> {
+        return this.get(`/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collectionId)}/api-key`);
+    }
+
+    /** Remove the stored API key of an MCP tool collection. */
+    deleteMcpCollectionApiKey(appId: string, collectionId: string): Promise<McpApiKeyStatus> {
+        return this.del(`/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collectionId)}/api-key`);
+    }
+
     /**
      * Cascade-delete an app and everything attached to it (versions,
      * installations + ACEs, git repo on the app-git server). Pass through
@@ -288,6 +312,7 @@ export default class AppsApi extends ApiTopic {
         settings?: Record<string, unknown>,
         oauthParams?: Record<string, { client_id?: string; client_secret?: string; scopes?: string[] }>,
         oauthProviderParams?: Record<string, { client_id?: string; client_secret?: string; scopes?: string[] }>,
+        apiKeyParams?: AppApiKeyCollectionParams,
     ): Promise<AppInstallation> {
         return this.post(`/install`, {
             payload: {
@@ -295,6 +320,7 @@ export default class AppsApi extends ApiTopic {
                 settings,
                 oauth_params: oauthParams,
                 oauth_provider_params: oauthProviderParams,
+                api_key_params: apiKeyParams,
             } satisfies AppInstallationPayload,
         });
     }

package/src/client.test.ts

@@ -1,3 +1,4 @@
+import { APP_VERSION_HEADER } from '@vertesia/common';
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 import { isTokenExpired, VertesiaClient } from './client.js';
 
@@ -145,6 +146,21 @@ describe('Test Vertesia Client', () => {
         expect(client.baseUrl).toBe('https://studio-server-production.api.becomposable.com');
         expect(client.storeUrl).toBe('https://zeno-server-production.api.becomposable.com');
     });
+
+    test('withAppVersion keeps Studio and Store requests pinned together', () => {
+        const client = new VertesiaClient({
+            serverUrl: 'https://studio-server-production.api.becomposable.com',
+            storeUrl: 'https://zeno-server-production.api.becomposable.com',
+        });
+
+        expect(client.withAppVersion('candidate-v1')).toBe(client);
+        expect(client.headers[APP_VERSION_HEADER]).toBe('candidate-v1');
+        expect(client.store.headers[APP_VERSION_HEADER]).toBe('candidate-v1');
+
+        client.withAppVersion(null);
+        expect(client.headers[APP_VERSION_HEADER]).toBeUndefined();
+        expect(client.store.headers[APP_VERSION_HEADER]).toBeUndefined();
+    });
 });
 
 describe('isTokenExpired', () => {

package/src/client.ts

@@ -248,6 +248,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
      * exact built version instead of the promoted version. Pass null/empty to clear (→ promoted).
      */
     withAppVersion(version: string | null | undefined) {
+        this.store.withAppVersion(version);
         if (!version) {
             delete this.headers[APP_VERSION_HEADER];
         } else {

package/src/store/EventsApi.ts

@@ -1,5 +1,7 @@
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
 import type {
+    CancelEventDeliveryIntentsPayload,
+    CancelEventDeliveryIntentsResponse,
     EventDeliveryQueueSummaryPayload,
     EventDeliveryQueueSummaryResponse,
     EventDeliveryStreamEnvelope,
@@ -46,6 +48,12 @@ export class EventsApi extends ApiTopic {
         return this.post('/deliveries/queue-summary', { payload });
     }
 
+    cancelQueuedDeliveries(
+        payload: CancelEventDeliveryIntentsPayload = {},
+    ): Promise<CancelEventDeliveryIntentsResponse> {
+        return this.post('/deliveries/cancel', { payload });
+    }
+
     subscribeDeliveries(options: SubscribeEventDeliveriesOptions): ManagedEventSourceConnection {
         const { signal, max_reconnect_attempts, on_snapshot, on_delivery, on_envelope, on_error, on_status, ...query } =
             options;

package/src/store/FilesApi.test.ts

@@ -1,7 +1,12 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { ZenoClient } from './client.js';
 
 describe('FilesApi', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.unstubAllGlobals();
+    });
+
     it('retries signed upload URL creation after a transient connection failure', async () => {
         let attempts = 0;
         const fetchSignedUploadUrl = async (): Promise<Response> => {
@@ -66,4 +71,35 @@ describe('FilesApi', () => {
         expect(result).toEqual({ id: 'file-1', path: 'agents/run/conversation.json', url: 'https://signed' });
         expect(attempts).toBe(2);
     });
+
+    it('does not expose a signed URL when a file download returns 404', async () => {
+        const signedUrl =
+            'https://storage.googleapis.com/test-bucket/agents/run/files/missing.png?X-Goog-Credential=secret&X-Goog-Signature=do-not-log';
+        const fetchDownloadUrl = (): Promise<Response> =>
+            Promise.resolve(
+                new Response(JSON.stringify({ url: signedUrl }), {
+                    status: 200,
+                    headers: { 'content-type': 'application/json' },
+                }),
+            );
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(null, { status: 404, statusText: 'Not Found' })));
+        const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        const client = new ZenoClient({
+            serverUrl: 'https://store.test',
+            apikey: 'token',
+            fetch: fetchDownloadUrl,
+        });
+
+        const error = await client.files.downloadFile('agents/run/files/missing.png').catch((cause: unknown) => cause);
+
+        expect(error).toMatchObject({
+            name: 'FileDownloadError',
+            status: 404,
+            message: 'File download not found: agents/run/files/missing.png',
+        });
+        expect(String(error)).not.toContain('X-Goog-Credential');
+        expect(String(error)).not.toContain('X-Goog-Signature');
+        expect(String(error)).not.toContain('do-not-log');
+        expect(consoleError).not.toHaveBeenCalled();
+    });
 });

package/src/store/FilesApi.ts

@@ -28,6 +28,44 @@ const FILE_SIGNING_RETRY_POLICY: IRequestRetryPolicy = {
     statuses: [502, 503, 504],
 };
 
+function fileLocationForError(location: string): string {
+    try {
+        const url = new URL(location);
+        return `${url.protocol}//${url.host}${url.pathname}`;
+    } catch {
+        return location.split(/[?#]/, 1)[0] || 'unknown file';
+    }
+}
+
+function sanitizedErrorCause(error: unknown): Error | undefined {
+    if (!(error instanceof Error)) {
+        return undefined;
+    }
+    const message = error.message.replace(/https?:\/\/[^\s)\]}>"']+/g, (url) => fileLocationForError(url));
+    const cause = new Error(message);
+    cause.name = error.name;
+    return cause;
+}
+
+function fileDownloadFailureReason(status?: number, statusText?: string): string {
+    if (status === 404) return 'not found';
+    if (status === 403) return 'forbidden';
+    if (status) return `failed with status ${status}${statusText ? ` ${statusText}` : ''}`;
+    return 'failed';
+}
+
+export class FileDownloadError extends Error {
+    readonly status?: number;
+
+    constructor(location: string, status?: number, statusText?: string, cause?: unknown) {
+        const safeLocation = fileLocationForError(location);
+        const reason = fileDownloadFailureReason(status, statusText);
+        super(`File download ${reason}: ${safeLocation}`, { cause: sanitizedErrorCause(cause) });
+        this.name = 'FileDownloadError';
+        this.status = status;
+    }
+}
+
 export function getMemoryFilePath(name: string) {
     const nameWithExt = name.endsWith('.tar.gz') ? name : `${name}.tar.gz`;
     return `${MEMORIES_PREFIX}/${nameWithExt}`;
@@ -229,28 +267,19 @@ export class FilesApi extends ApiTopic {
         const needSign = !location.startsWith('https:');
         const { url } = needSign ? await this.getDownloadUrl(location) : { url: location };
 
-        const res = await fetchSignedUrl(url, {
-            method: 'GET',
-        })
-            .then((res: Response) => {
-                if (res.ok) {
-                    return res;
-                } else if (res.status === 404) {
-                    throw new Error(`File at ${url} not found`); //TODO: type fetch error better with a fetch error class
-                } else if (res.status === 403) {
-                    throw new Error(`File at ${url} is forbidden`);
-                } else {
-                    console.log(res);
-                    throw new Error(`Failed to download file ${location}: ${res.statusText}`);
-                }
-            })
-            .catch((err) => {
-                console.error(`Failed to download file ${location}.`, err);
-                throw err;
-            });
+        let res: Response;
+        try {
+            res = await fetchSignedUrl(url, { method: 'GET' });
+        } catch (error: unknown) {
+            throw new FileDownloadError(location, undefined, undefined, error);
+        }
+
+        if (!res.ok) {
+            throw new FileDownloadError(location, res.status, res.statusText);
+        }
 
         if (!res.body) {
-            throw new Error(`No body in response while downloading file ${location}`);
+            throw new FileDownloadError(location);
         }
 
         return res.body;

package/src/store/version.ts

@@ -1,4 +1,7 @@
-export const VERSION = '20260319'; // YYYYMMDD, client versioning for API endpoints. Increment manually for breaking changes
-// Re-exported, not redeclared: the servers read the same constant when deciding how strictly to
-// hold a request to its schema, so a name only this side knew could not stay a negotiation.
-export { APP_VERSION_HEADER, VERSION_HEADER } from '@vertesia/common';
+// Preserve the public client export while sourcing its value from the same module as the servers
+// and OpenAPI generator.
+export {
+    APP_VERSION_HEADER,
+    CURRENT_API_VERSION_HEADER_VALUE as VERSION,
+    VERSION_HEADER,
+} from '@vertesia/common';