@vertesia/client 1.5.0-dev.20260910.052912Z → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.5.0-dev.20260910.052912Z",
+  "version": "1.5.1",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -19,9 +19,9 @@
   },
   "dependencies": {
     "eventsource": "^5.0.0",
-    "@vertesia/api-fetch-client": "1.5.0-dev.20260910.052912Z",
-    "@vertesia/common": "1.5.0-dev.20260910.052912Z",
-    "@llumiverse/common": "1.5.0-dev.20260910.044936Z"
+    "@llumiverse/common": "1.5.1",
+    "@vertesia/api-fetch-client": "1.5.1",
+    "@vertesia/common": "1.5.1"
   },
   "exports": {
     ".": {
@@ -48,7 +48,7 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "95d481ca856012cd67b501b901dc365afeb7cf81",
+  "gitHead": "7ab3acd95af12b8c254e1b3852e67d5078790f98",
   "scripts": {
     "lint": "biome lint src",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",

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/InteractionsApi.ts

@@ -30,6 +30,7 @@ import type {
     RateLimitRequestPayload,
     RateLimitRequestResponse,
     ResolvedInteractionExecutionInfo,
+    ResolveInteractionQuery,
 } from '@vertesia/common';
 import type { VertesiaClient } from './client.js';
 import { checkRateLimit, executeInteraction, executeInteractionAsync, executeInteractionByName } from './execute.js';
@@ -339,15 +340,7 @@ export default class InteractionsApi extends ApiTopic {
      * @param options Optional environment and/or model to resolve with
      * @returns ResolvedInteractionExecutionInfo with the resolved environment and model
      */
-    resolve(
-        nameOrId: string,
-        options?: {
-            environment?: string;
-            model?: string;
-            hasImage?: boolean;
-            hasVideo?: boolean;
-        },
-    ): Promise<ResolvedInteractionExecutionInfo> {
+    resolve(nameOrId: string, options?: ResolveInteractionQuery): Promise<ResolvedInteractionExecutionInfo> {
         return this.get(`/resolve/${encodeURIComponent(nameOrId)}`, {
             query: options,
         });

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/index.ts

@@ -6,6 +6,7 @@ export * from './client.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

@@ -417,6 +417,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;
@@ -438,6 +447,10 @@ export class AgentsApi extends ApiTopic {
                     }
                 }
             } catch (err) {
+                if (isRunGone(err)) {
+                    exitBecauseRunGone();
+                    return;
+                }
                 warnPollFailure('GET /updates', err);
             }
             if (isClosed || !isPolling) return;
@@ -450,6 +463,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/ObjectsApi.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ZenoClient } from './client.js';
+
+describe('ObjectsApi revision labels', () => {
+    it.each(['v1.2', 'Review — 日本語', 'Révision – café', '100% complete & reviewed + approved'])(
+        'preserves the revision label %s through the query contract',
+        async (revisionLabel) => {
+            const requests: Request[] = [];
+            const client = new ZenoClient({
+                serverUrl: 'https://api.example.com',
+                fetch: vi.fn(async () => Response.json({ id: 'document-id' })),
+                onRequest: (request) => requests.push(request),
+            });
+
+            await client.objects.update(
+                'document-id',
+                { name: 'Updated document' },
+                {
+                    createRevision: true,
+                    revisionLabel,
+                    ifMatch: 'previous-etag',
+                },
+            );
+
+            expect(requests).toHaveLength(1);
+            const request = requests[0];
+            expect(request.method).toBe('PUT');
+            expect(new URL(request.url).searchParams.get('revision_label')).toBe(revisionLabel);
+            expect(request.headers.has('x-revision-label')).toBe(false);
+            expect(request.headers.get('x-create-revision')).toBe('true');
+            expect(request.headers.get('if-match')).toBe('previous-etag');
+            expect(await request.clone().json()).toEqual({ name: 'Updated document' });
+        },
+    );
+
+    it('does not send a label when updating in place', async () => {
+        const requests: Request[] = [];
+        const client = new ZenoClient({
+            serverUrl: 'https://api.example.com',
+            fetch: vi.fn(async () => Response.json({ id: 'document-id' })),
+            onRequest: (request) => requests.push(request),
+        });
+
+        await client.objects.update('document-id', {}, { revisionLabel: 'Unused — label' });
+
+        expect(new URL(requests[0].url).searchParams.has('revision_label')).toBe(false);
+        expect(requests[0].headers.has('x-create-revision')).toBe(false);
+        expect(requests[0].headers.has('x-revision-label')).toBe(false);
+    });
+});

package/src/store/ObjectsApi.ts

@@ -437,9 +437,6 @@ export class ObjectsApi extends ApiTopic {
         }
         if (options?.createRevision) {
             headers[ContentObjectApiHeaders.CREATE_REVISION] = 'true';
-            if (options.revisionLabel) {
-                headers[ContentObjectApiHeaders.REVISION_LABEL] = options.revisionLabel;
-            }
         }
         if (options?.suppressWorkflows) {
             headers[ContentObjectApiHeaders.SUPPRESS_WORKFLOWS] = 'true';
@@ -447,6 +444,11 @@ export class ObjectsApi extends ApiTopic {
 
         return this.put(`/${id}`, {
             payload: updatePayload,
+            // The existing query contract preserves Unicode labels; HTTP headers only accept ByteString values.
+            query:
+                options?.createRevision && options.revisionLabel
+                    ? { revision_label: options.revisionLabel }
+                    : undefined,
             headers,
         });
     }

package/src/store/signed-url.test.ts

@@ -173,10 +173,32 @@ describe('fetchSignedUrl', () => {
 
     it('honors a numeric Retry-After header when scheduling the retry', async () => {
         fetchMock
-            .mockResolvedValueOnce(response(503, 'slow down', { 'retry-after': '2' }))
+            .mockResolvedValueOnce(response(503, 'slow down', { 'retry-after': '30' }))
             .mockResolvedValueOnce(response(200, 'ok'));
-        const res = await runAllTimers(fetchSignedUrl('https://storage/x'));
+        const pending = fetchSignedUrl('https://storage/x');
+        await vi.advanceTimersByTimeAsync(29999);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        await vi.advanceTimersByTimeAsync(1);
+        const res = await pending;
         expect(res.status).toBe(200);
         expect(fetchMock).toHaveBeenCalledTimes(2);
     });
 });
+
+describe('Retry-After request budget', () => {
+    it.each(['3600', '2147484', '1e308', new Date(Date.now() + 3600000).toUTCString()])(
+        'returns the intact response without an early retry for %s',
+        async (retryAfter) => {
+            const res = new Response('retry later', { status: 503, headers: { 'Retry-After': retryAfter } });
+            const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(res);
+            try {
+                const result = await fetchSignedUrl('https://storage/x');
+                expect(result).toBe(res);
+                expect(await result.text()).toBe('retry later');
+                expect(fetch).toHaveBeenCalledTimes(1);
+            } finally {
+                fetch.mockRestore();
+            }
+        },
+    );
+});

package/src/store/signed-url.ts

@@ -20,6 +20,7 @@ const DEFAULT_RETRYABLE_STATUSES: ReadonlySet<number> = new Set([429, 500, 502,
 const DEFAULT_ATTEMPTS = 4;
 const DEFAULT_BASE_DELAY_MS = 500;
 const DEFAULT_MAX_DELAY_MS = 8_000;
+const MAX_RETRY_AFTER_MS = 60_000;
 
 export interface SignedUrlFetchOptions {
     method?: string;
@@ -29,7 +30,7 @@ export interface SignedUrlFetchOptions {
     attempts?: number;
     /** Base delay for exponential backoff, in milliseconds. Defaults to 500. */
     baseDelayMs?: number;
-    /** Upper bound for a single backoff delay, in milliseconds. Defaults to 8000. */
+    /** Upper bound for exponential backoff, in milliseconds. Defaults to 8000. Retry-After takes precedence. */
     maxDelayMs?: number;
     /** HTTP statuses to retry on. Defaults to 429, 500, 502, 503, 504. */
     retryableStatuses?: ReadonlySet<number>;
@@ -58,7 +59,7 @@ function retryAfterMs(res: Response): number | undefined {
 function backoffMs(attempt: number, baseDelayMs: number, maxDelayMs: number, res?: Response): number {
     const retryAfter = res ? retryAfterMs(res) : undefined;
     if (retryAfter !== undefined) {
-        return Math.min(maxDelayMs, retryAfter);
+        return retryAfter;
     }
     // Exponential backoff with full jitter.
     const capped = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
@@ -141,7 +142,8 @@ async function toReplayableBody(body: BodyInit | null | undefined): Promise<Body
 /**
  * `fetch()` a cloud-storage signed URL, retrying transient failures (connection
  * errors and retryable HTTP statuses) with exponential backoff. Honors a
- * `Retry-After` response header when present.
+ * `Retry-After` response header up to 60 seconds. Longer delays return the response
+ * without retrying so the caller can schedule recovery outside this request.
  *
  * The returned `Response` is only guaranteed to be retried while it carries a
  * retryable status; a non-retryable error response (e.g. 403, 404) is returned
@@ -167,6 +169,9 @@ export async function fetchSignedUrl(url: string, options: SignedUrlFetchOptions
             if (res.ok || !retryableStatuses.has(res.status) || isLastAttempt) {
                 return res;
             }
+            // Do not retry earlier than requested or park the caller beyond the retry budget.
+            // Returning the response also avoids overflowing JavaScript's timer range.
+            if ((retryAfterMs(res) ?? 0) > MAX_RETRY_AFTER_MS) return res;
             // Retryable status: drain the body so the connection can be reused, then back off.
             await res.body?.cancel().catch(() => undefined);
             await sleep(backoffMs(attempt, baseDelayMs, maxDelayMs, res));