@vertesia/client 1.6.0-dev.20260918.090710Z → 1.6.0-dev.20260923.085325Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.6.0-dev.20260918.090710Z",
+  "version": "1.6.0-dev.20260923.085325Z",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -11,16 +11,16 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
-    "@types/node": "^24.13.3",
+    "@types/node": "^24.13.5",
     "@vertesia/tsconfig": "0.1.0",
     "rolldown": "1.2.8",
     "typescript": "7.0.2",
-    "vitest": "5.0.0"
+    "vitest": "5.0.1"
   },
   "dependencies": {
-    "@llumiverse/common": "1.6.0-dev.20260918.055633Z",
-    "@vertesia/api-fetch-client": "1.6.0-dev.20260918.090710Z",
-    "@vertesia/common": "1.6.0-dev.20260918.090710Z",
+    "@llumiverse/common": "1.6.0-dev.20260923.085100Z",
+    "@vertesia/api-fetch-client": "1.6.0-dev.20260923.085325Z",
+    "@vertesia/common": "1.6.0-dev.20260923.085325Z",
     "eventsource": "^5.1.1"
   },
   "exports": {
@@ -48,7 +48,7 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "10f35da1a210e1950f9c8b1368fea89328a23ea0",
+  "gitHead": "8732631fd8099bdcab4f5375da2309f3cff34e19",
   "scripts": {
     "lint": "biome lint src",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",

package/src/AppsApi.ts

@@ -39,6 +39,7 @@ import type {
     StartAppDevelopmentTaskRequest,
     StartAppScaffoldRequest,
     StartAppScaffoldResponse,
+    UpdateAppInstallationOAuthApprovalPayload,
     UpdateAppInstallationToolAllowlistPayload,
     UpdateAppPayload,
     UpsertAppVersionRequest,
@@ -429,6 +430,16 @@ export default class AppsApi extends ApiTopic {
         });
     }
 
+    /**
+     * Set project-admin approval for an installation's OAuth scopes.
+     * Pass an empty list to revoke approval.
+     */
+    updateOAuthApproval(installId: string, approved_scopes: string[]): Promise<AppInstallationWithManifest> {
+        return this.put(`/installations/${installId}/oauth-approval`, {
+            payload: { approved_scopes } satisfies UpdateAppInstallationOAuthApprovalPayload,
+        });
+    }
+
     /**
      * Update the tool allowlist for an app installation.
      * Pass null to remove all restrictions (all tools permitted).

package/src/EnvironmentsApi.ts

@@ -1,6 +1,11 @@
 import type { AIModel, ModelSearchPayload } from '@llumiverse/common';
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
 import type {
+    EmbeddingBatchCapabilityRequest,
+    EmbeddingBatchCapabilityResponse,
+    EmbeddingBatchCreateRequest,
+    EmbeddingBatchJobRequest,
+    EmbeddingBatchJobResponse,
     EmbeddingsApiRequest,
     EmbeddingsApiResult,
     EnableEnvironmentModelPayload,
@@ -84,6 +89,29 @@ export default class EnvironmentsApi extends ApiTopic {
         });
     }
 
+    embeddingBatchCapability(
+        id: string,
+        payload: EmbeddingBatchCapabilityRequest,
+    ): Promise<EmbeddingBatchCapabilityResponse> {
+        return this.post(`/${id}/embedding-batches/capability`, { payload });
+    }
+
+    createEmbeddingBatch(id: string, payload: EmbeddingBatchCreateRequest): Promise<EmbeddingBatchJobResponse> {
+        return this.post(`/${id}/embedding-batches`, { payload });
+    }
+
+    getEmbeddingBatch(id: string, payload: EmbeddingBatchJobRequest): Promise<EmbeddingBatchJobResponse> {
+        return this.post(`/${id}/embedding-batches/get`, { payload });
+    }
+
+    cancelEmbeddingBatch(id: string, payload: EmbeddingBatchJobRequest): Promise<EmbeddingBatchJobResponse> {
+        return this.post(`/${id}/embedding-batches/cancel`, { payload });
+    }
+
+    deleteEmbeddingBatch(id: string, payload: EmbeddingBatchJobRequest): Promise<EmbeddingBatchJobResponse> {
+        return this.post(`/${id}/embedding-batches/delete`, { payload });
+    }
+
     /**
      * Batch update the LLM Environment for multiple Interactions, including the model used and the
      * Environment that they belong to.

package/src/InteractionOutput.test.ts

@@ -3,6 +3,20 @@ import { describe, expect, it } from 'vitest';
 import { InteractionOutput, IS_INTERACTION_OUTPUT } from './InteractionOutput.js';
 
 describe('InteractionOutput', () => {
+    it('exposes audio metadata and URI without treating it as text or JSON', () => {
+        const audio = {
+            type: 'audio' as const,
+            value: 'gs://bucket/speech.mp3',
+            mime_type: 'audio/mpeg',
+            container: 'mp3',
+        };
+        const output = InteractionOutput.from([audio]);
+        expect(output.hasAudio()).toBe(true);
+        expect(output.audio()).toEqual(audio);
+        expect(output.audios()).toEqual([audio]);
+        expect(output.text()).toBe('');
+    });
+
     const sampleResults: CompletionResult[] = [
         { type: 'text', value: 'Hello, ' },
         { type: 'text', value: 'World!' },

package/src/InteractionOutput.ts

@@ -217,6 +217,21 @@ export class InteractionOutput<T = unknown> {
         return this.results.filter((r) => r.type === 'image').map((r) => r.value);
     }
 
+    hasAudio(): boolean {
+        return this.results.some((r) => r.type === 'audio');
+    }
+
+    /** Get complete audio metadata and its durable file reference. */
+    audios() {
+        return this.results.filter((r) => r.type === 'audio');
+    }
+
+    audio() {
+        const result = this.audios()[0];
+        if (!result) throw new Error('No audio result found');
+        return result;
+    }
+
     /** Get the first video result URI. */
     video(): string {
         const videoResult = this.results.find((r) => r.type === 'video');

package/src/InternalAccountsApi.ts

@@ -0,0 +1,12 @@
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type { AccountApiVersionPolicy } from '@vertesia/common';
+
+export default class InternalAccountsApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, '/internal/accounts');
+    }
+
+    getApiVersionPolicy(accountId: string): Promise<AccountApiVersionPolicy> {
+        return this.get(`/${encodeURIComponent(accountId)}/api-version-policy`);
+    }
+}

package/src/OAuthServerApi.ts

@@ -7,6 +7,8 @@ import type {
     OAuthDeviceAuthorizationRequest,
     OAuthDeviceAuthorizationResponse,
     OAuthGrantableScopesResponse,
+    OAuthLoginDecisionResponse,
+    OAuthLoginPayload,
 } from '@vertesia/common';
 
 export default class OAuthServerApi extends ClientBase {
@@ -20,6 +22,10 @@ export default class OAuthServerApi extends ClientBase {
         this.verboseErrors = parent.verboseErrors;
     }
 
+    login(requestId: string, payload: OAuthLoginPayload): Promise<OAuthLoginDecisionResponse> {
+        return this.post(`/requests/${encodeURIComponent(requestId)}/login`, { payload });
+    }
+
     get headers() {
         return this.parent.headers;
     }

package/src/app-session.test.ts

@@ -0,0 +1,23 @@
+import { expect, it, vi } from 'vitest';
+import { VertesiaClient } from './client.js';
+
+it('mints an app session through STS with the caller authorization and declared scopes', async () => {
+    const transport = vi.fn<typeof fetch>(async () =>
+        Response.json({ token: 'scoped', token_type: 'Bearer', expires_in: 900 }),
+    );
+    const client = new VertesiaClient({
+        serverUrl: 'https://api.example',
+        storeUrl: 'https://store.example',
+        tokenServerUrl: 'https://sts.example',
+        apikey: 'caller',
+        fetch: transport,
+    });
+    const result = await client.mintAppSessionToken({ app_name: 'analytics', scopes: ['content:read'] });
+    expect(result.token).toBe('scoped');
+    const [url, options] = transport.mock.calls[0];
+    const request = new Request(url, options);
+    expect(request.url).toBe('https://sts.example/token/app-session');
+    expect(request.method).toBe('POST');
+    expect(request.headers.get('authorization')).toBe('Bearer caller');
+    expect(await request.json()).toEqual({ app_name: 'analytics', scopes: ['content:read'] });
+});

package/src/client.ts

@@ -1,4 +1,5 @@
 import { AbstractFetchClient, type FETCH_FN, type IRequestRetryPolicy } from '@vertesia/api-fetch-client';
+import type { AppSessionTokenRequest, AppSessionTokenResponse } from '@vertesia/common';
 import { APP_VERSION_HEADER, type AuthTokenPayload, type AuthTokenResponse } from '@vertesia/common';
 import AccountApi from './AccountApi.js';
 import AccountsApi from './AccountsApi.js';
@@ -412,6 +413,10 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
      *
      * @returns AuthTokenResponse
      */
+    async mintAppSessionToken(request: AppSessionTokenRequest): Promise<AppSessionTokenResponse> {
+        return this.post<AppSessionTokenResponse>(`${this.tokenServerUrl}/token/app-session`, { payload: request });
+    }
+
     async getAuthToken(token?: string): Promise<AuthTokenResponse> {
         // Route through the base client (absolute URL) so the call benefits from the
         // retry policy. The default retry methods exclude POST as non-idempotent, but

package/src/index.ts

@@ -7,6 +7,7 @@ export { default as DelegationGrantsApi } from './DelegationGrantsApi.js';
 export type { GroupsQueryOptions } from './GroupsApi.js';
 export * from './InteractionBase.js';
 export * from './InteractionOutput.js';
+export { default as InternalAccountsApi } from './InternalAccountsApi.js';
 export { default as InternalSecretsApi } from './InternalSecretsApi.js';
 export * from './managed-sse.js';
 export { default as OAuthClientsApi } from './OAuthClientsApi.js';

package/src/store/AgentsApi.stream.test.ts

@@ -72,7 +72,16 @@ function createHarness(): Harness {
             }
             const since = Number(url.searchParams.get('since') ?? 0);
             pollSince.push(since);
-            return Response.json({ messages: pollResponse(since) });
+            try {
+                return Response.json({ messages: pollResponse(since) });
+            } catch (err) {
+                // A thrown error carrying `status` models an HTTP error response (e.g. 404).
+                const status = (err as { status?: unknown }).status;
+                if (typeof status === 'number') {
+                    return Response.json({ error: (err as Error).message }, { status });
+                }
+                throw err;
+            }
         }
         if (url.pathname.endsWith(`/${AGENT_RUN_ID}`)) {
             return Response.json({ id: AGENT_RUN_ID, status: runStatus });
@@ -337,6 +346,29 @@ describe('AgentsApi.streamMessages reconnection', () => {
         await settle();
     });
 
+    it('stops the polling fallback when the run no longer exists (404)', async () => {
+        const harness = createHarness();
+        harness.setHistory([{ t: AgentMessageType.UPDATE, m: 'history', ts: 1000 }]);
+        harness.setPollResponse(() => {
+            throw Object.assign(new Error('Not Found: Agent run not found'), { status: 404 });
+        });
+
+        const abort = new AbortController();
+        const done = harness.client.agents.streamMessages(AGENT_RUN_ID, undefined, undefined, abort.signal);
+        await settle();
+
+        for (let i = 0; i < 11; i++) {
+            await failCurrentConnection();
+        }
+        await settle(6000);
+
+        await expect(done).resolves.toBeNull();
+        expect(warnings.some((line) => line.includes('the run no longer exists (404)'))).toBe(true);
+        // A single 404 ends the loop: no retry warning, no further poll after the exit.
+        expect(warnings.filter((line) => line.includes('GET /updates failed while polling'))).toEqual([]);
+        expect(harness.pollSince).toHaveLength(1);
+    });
+
     it('closes the stream when polling observes a terminal run status', async () => {
         const harness = createHarness();
         const abort = new AbortController();

package/src/store/AgentsApi.ts

@@ -435,6 +435,15 @@ export class AgentsApi extends ApiTopic {
             );
         };
 
+        // A 404 while polling means the run itself is gone (deleted, or never persisted): nothing
+        // will ever arrive, so stop instead of polling the missing resource every 5s forever.
+        const isRunGone = (error: unknown): boolean =>
+            typeof error === 'object' && error !== null && (error as { status?: unknown }).status === 404;
+        const exitBecauseRunGone = () => {
+            console.warn(`Agent stream ${id}: the run no longer exists (404); stopping the polling fallback.`);
+            exit(null);
+        };
+
         const pollTick = async () => {
             if (isClosed || !isPolling) return;
             let polledMessages = false;
@@ -456,6 +465,10 @@ export class AgentsApi extends ApiTopic {
                     }
                 }
             } catch (err) {
+                if (isRunGone(err)) {
+                    exitBecauseRunGone();
+                    return;
+                }
                 warnPollFailure('GET /updates', err);
             }
             if (isClosed || !isPolling) return;
@@ -468,6 +481,10 @@ export class AgentsApi extends ApiTopic {
                 }
                 if (polledMessages) consecutivePollFailures = 0;
             } catch (err) {
+                if (isRunGone(err)) {
+                    exitBecauseRunGone();
+                    return;
+                }
                 warnPollFailure('run status check', err);
             }
             if (isClosed || !isPolling) return;

package/src/store/EmbeddingsApi.test.ts

@@ -0,0 +1,31 @@
+import { SupportedEmbeddingTypes } from '@vertesia/common';
+import { describe, expect, it, vi } from 'vitest';
+import { ZenoClient } from './client.js';
+
+describe('EmbeddingsApi', () => {
+    it('omits the mode by default and sends the explicit sync override when requested', async () => {
+        const requests: Request[] = [];
+        const client = new ZenoClient({
+            serverUrl: 'https://store.example.com',
+            apikey: 'token',
+            fetch: vi.fn(
+                async () =>
+                    new Response(JSON.stringify({ status: 'success', message: 'started' }), {
+                        status: 200,
+                        headers: { 'content-type': 'application/json' },
+                    }),
+            ),
+            onRequest: (request) => requests.push(request),
+        });
+
+        await client.embeddings.recalculate(SupportedEmbeddingTypes.text);
+        await client.embeddings.recalculate(SupportedEmbeddingTypes.text, { mode: 'sync' });
+        await client.embeddings.recalculate(SupportedEmbeddingTypes.image, { force: true });
+
+        expect(requests.map(({ url }) => url)).toEqual([
+            'https://store.example.com/api/v1/embeddings/text/recalculate',
+            'https://store.example.com/api/v1/embeddings/text/recalculate?mode=sync',
+            'https://store.example.com/api/v1/embeddings/image/recalculate?force=true',
+        ]);
+    });
+});

package/src/store/EmbeddingsApi.ts

@@ -1,8 +1,16 @@
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
 import type {
+    EmbeddingBatchApplyRequest,
+    EmbeddingBatchApplyResponse,
+    EmbeddingBatchPrepareRequest,
+    EmbeddingBatchPrepareResponse,
+    EmbeddingBatchRenditionPageRequest,
+    EmbeddingBatchRenditionPageResponse,
+    EmbeddingBatchUpdateRequest,
     EmbeddingsStatusResponse,
     GenericCommandResponse,
     ProjectConfigurationEmbeddingEnablePayload,
+    RecalculateEmbeddingsQuery,
     SupportedEmbeddingTypes,
 } from '@vertesia/common';
 
@@ -33,7 +41,44 @@ export class EmbeddingsApi extends ApiTopic {
         return this.post(`${type}/disable`);
     }
 
-    async recalculate(type: SupportedEmbeddingTypes): Promise<GenericCommandResponse> {
-        return this.post(`${type}/recalculate`);
+    async recalculate(
+        type: SupportedEmbeddingTypes,
+        query: RecalculateEmbeddingsQuery = {},
+    ): Promise<GenericCommandResponse> {
+        return this.post(`${type}/recalculate`, Object.keys(query).length ? { query } : undefined);
+    }
+
+    async prepareBatch(
+        payload: EmbeddingBatchPrepareRequest,
+        timeoutMs: number | false | null = false,
+    ): Promise<EmbeddingBatchPrepareResponse> {
+        return this.post('/batch/prepare', { payload, timeoutMs });
+    }
+
+    async updateBatch(payload: EmbeddingBatchUpdateRequest): Promise<GenericCommandResponse> {
+        return this.post('/batch/update', { payload });
+    }
+
+    async prepareBatchRenditionPage(
+        payload: EmbeddingBatchRenditionPageRequest,
+    ): Promise<EmbeddingBatchRenditionPageResponse> {
+        return this.post('/batch/renditions/prepare', { payload });
+    }
+
+    async pollBatchRenditionPage(
+        payload: EmbeddingBatchRenditionPageRequest,
+    ): Promise<EmbeddingBatchRenditionPageResponse> {
+        return this.post('/batch/renditions/status', { payload });
+    }
+
+    async cancelBatchRenditionPage(payload: EmbeddingBatchRenditionPageRequest): Promise<GenericCommandResponse> {
+        return this.post('/batch/renditions/cancel', { payload });
+    }
+
+    async applyBatch(
+        payload: EmbeddingBatchApplyRequest,
+        timeoutMs: number | false | null = false,
+    ): Promise<EmbeddingBatchApplyResponse> {
+        return this.post('/batch/apply', { payload, timeoutMs });
     }
 }

package/src/store/FilesApi.test.ts

@@ -2,6 +2,19 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { ZenoClient } from './client.js';
 
 describe('FilesApi', () => {
+    it('retrieves a durable audio result through the authenticated file API', async () => {
+        const bytes = new Uint8Array([82, 73, 70, 70, 1, 2, 3]);
+        const sign = vi.fn(async () => Response.json({ url: 'https://signed.example/speech.wav' }));
+        vi.stubGlobal(
+            'fetch',
+            vi.fn(async () => new Response(bytes, { headers: { 'content-type': 'audio/wav' } })),
+        );
+        const client = new ZenoClient({ serverUrl: 'https://store.test', apikey: 'test-token', fetch: sign });
+        const stream = await client.files.downloadFile('gs://bucket/runs/run-1/media/speech.wav');
+        expect(new Uint8Array(await new Response(stream).arrayBuffer())).toEqual(bytes);
+        expect(sign).toHaveBeenCalledOnce();
+    });
+
     afterEach(() => {
         vi.restoreAllMocks();
         vi.unstubAllGlobals();