@vertesia/client 1.1.1-dev.20260505.163000Z → 1.3.0-dev.20260620.061059Z

package/src/store/client.ts

@@ -1,26 +1,31 @@
-import { AbstractFetchClient, RequestError } from "@vertesia/api-fetch-client";
-import { BulkOperationPayload, BulkOperationResponse } from "@vertesia/common";
-import { AgentsApi } from "./AgentsApi.js";
-import { CollectionsApi } from "./CollectionsApi.js";
-import { CostApi } from "./CostApi.js";
-import { CommandsApi } from "./CommandsApi.js";
-import { DataApi } from "./DataApi.js";
-import { EmailApi } from "./EmailApi.js";
-import { IndexingApi } from "./IndexingApi.js";
-import { EmbeddingsApi } from "./EmbeddingsApi.js";
-import { ZenoClientNotFoundError } from "./errors.js";
-import { FilesApi } from "./FilesApi.js";
-import { HiveMemoryApi } from "./HiveMemoryApi.js";
-import { ObjectsApi } from "./ObjectsApi.js";
-import { PendingAsksApi } from "./PendingAsksApi.js";
-import { QueryApi } from "./QueryApi.js";
-import { RenderingApi } from "./RenderingApi.js";
-import { SchedulesApi } from "./SchedulesApi.js";
-import { ToolsApi } from "./ToolsApi.js";
-import { TypesApi } from "./TypesApi.js";
-import { VERSION, VERSION_HEADER } from "./version.js";
-import { WorkersApi } from "./WorkersApi.js";
-import { WorkflowsApi } from "./WorkflowsApi.js";
+import {
+    AbstractFetchClient,
+    type FETCH_FN,
+    type IRequestRetryPolicy,
+    type RequestError,
+} from '@vertesia/api-fetch-client';
+import { APP_VERSION_HEADER, type BulkOperationPayload, type BulkOperationResponse } from '@vertesia/common';
+import { AgentsApi } from './AgentsApi.js';
+import { CollectionsApi } from './CollectionsApi.js';
+import { CostApi } from './CostApi.js';
+import { DataApi } from './DataApi.js';
+import { EmailApi } from './EmailApi.js';
+import { EmbeddingsApi } from './EmbeddingsApi.js';
+import { ZenoClientNotFoundError } from './errors.js';
+import { FilesApi } from './FilesApi.js';
+import { HiveMemoryApi } from './HiveMemoryApi.js';
+import { IndexingApi } from './IndexingApi.js';
+import { ObjectsApi } from './ObjectsApi.js';
+import { PendingAsksApi } from './PendingAsksApi.js';
+import { ProcessApi } from './ProcessApi.js';
+import { QueryApi } from './QueryApi.js';
+import { RenderingApi } from './RenderingApi.js';
+import { SchedulesApi } from './SchedulesApi.js';
+import { TaskApi } from './TaskApi.js';
+import { ToolsApi } from './ToolsApi.js';
+import { TypesApi } from './TypesApi.js';
+import { VERSION, VERSION_HEADER } from './version.js';
+import { WorkflowsApi } from './WorkflowsApi.js';
 
 export interface ZenoClientProps {
     serverUrl?: string;
@@ -28,24 +33,30 @@ export interface ZenoClientProps {
     apikey?: string;
     onRequest?: (request: Request) => void;
     onResponse?: (response: Response) => void;
+    retryPolicy?: IRequestRetryPolicy;
+    timeout?: number | false | null;
+    fetch?: FETCH_FN | Promise<FETCH_FN>;
 }
 
 function ensureDefined(serverUrl: string | undefined) {
     if (!serverUrl) {
-        throw new Error("zeno client serverUrl is required");
+        throw new Error('zeno client serverUrl is required');
     }
     return serverUrl;
 }
 
 export class ZenoClient extends AbstractFetchClient<ZenoClient> {
-
-    constructor(
-        opts: ZenoClientProps = {}
-    ) {
-        super(ensureDefined(opts.serverUrl));
+    constructor(opts: ZenoClientProps = {}) {
+        super(ensureDefined(opts.serverUrl), opts.fetch);
         if (opts.apikey) {
             this.withApiKey(opts.apikey);
         }
+        if (opts.retryPolicy) {
+            this.withRetryPolicy(opts.retryPolicy);
+        }
+        if (opts.timeout !== undefined) {
+            this.withTimeout(opts.timeout);
+        }
         this.onRequest = opts.onRequest;
         this.onResponse = opts.onResponse;
         this.errorFactory = (err: RequestError) => {
@@ -54,7 +65,7 @@ export class ZenoClient extends AbstractFetchClient<ZenoClient> {
             } else {
                 return err;
             }
-        }
+        };
     }
 
     withApiVersion(version: string | number | null) {
@@ -66,23 +77,31 @@ export class ZenoClient extends AbstractFetchClient<ZenoClient> {
         return this;
     }
 
+    /** Pin the app version this client's requests resolve against (see VertesiaClient.withAppVersion). */
+    withAppVersion(version: string | null | undefined) {
+        if (!version) {
+            delete this.headers[APP_VERSION_HEADER];
+        } else {
+            this.headers[APP_VERSION_HEADER] = String(version);
+        }
+        return this;
+    }
+
     withApiKey(apiKey: string | null) {
-        return this.withAuthCallback(
-            apiKey ? () => Promise.resolve(`Bearer ${apiKey}`) : undefined
-        );
+        return this.withAuthCallback(apiKey ? () => Promise.resolve(`Bearer ${apiKey}`) : undefined);
     }
 
     runOperation(payload: BulkOperationPayload): Promise<BulkOperationResponse> {
-        return this.post("/api/v1/operations", {
-            payload
+        return this.post('/api/v1/operations', {
+            payload,
         });
     }
 
     get initialHeaders() {
         return {
             ...super.initialHeaders,
-            [VERSION_HEADER]: VERSION
-        }
+            [VERSION_HEADER]: VERSION,
+        };
     }
 
     agents = new AgentsApi(this);
@@ -91,9 +110,9 @@ export class ZenoClient extends AbstractFetchClient<ZenoClient> {
     types = new TypesApi(this);
     workflows = new WorkflowsApi(this);
     schedules = new SchedulesApi(this);
+    processes = new ProcessApi(this);
+    tasks = new TaskApi(this);
     files = new FilesApi(this);
-    commands = new CommandsApi(this);
-    workers = new WorkersApi(this);
     collections = new CollectionsApi(this);
     embeddings = new EmbeddingsApi(this);
     email = new EmailApi(this);

package/src/store/errors.ts

@@ -1,7 +1,7 @@
-import { RequestError } from "@vertesia/api-fetch-client";
+import { RequestError } from '@vertesia/api-fetch-client';
 
 export class ZenoClientNotFoundError extends RequestError {
     constructor(req: Request, error: RequestError) {
-        super("Resource not found: " + error.message, req, 404, error.payload);
+        super(`Resource not found: ${error.message}`, req, 404, error.payload);
     }
-}
+}

package/src/store/index.ts

@@ -1,18 +1,20 @@
-export * from "./AgentsApi.js";
-export * from "./client.js";
-export * from "./CommandsApi.js";
-export * from "./DataApi.js";
-export * from "./EmailApi.js";
-export * from "./errors.js";
-export * from "./FilesApi.js";
-export * from "./HiveMemoryApi.js";
-export * from "./IndexingApi.js";
-export * from "./ObjectsApi.js";
-export * from "./PendingAsksApi.js";
-export * from "./QueryApi.js";
-export * from "./RenderingApi.js";
-export * from "./SchedulesApi.js";
-export * from "./TypeCatalogApi.js";
-export * from "./TypesApi.js";
-export * from "./WorkflowsApi.js";
-
+export * from './AgentsApi.js';
+export * from './client.js';
+export * from './DataApi.js';
+export * from './EmailApi.js';
+export * from './errors.js';
+export * from './FilesApi.js';
+export * from './HiveMemoryApi.js';
+export * from './IndexingApi.js';
+export * from './ObjectsApi.js';
+export * from './PendingAsksApi.js';
+export * from './ProcessApi.js';
+export * from './QueryApi.js';
+export * from './RenderingApi.js';
+export * from './SchedulesApi.js';
+export * from './signed-url.js';
+export * from './TaskApi.js';
+export * from './TypeCatalogApi.js';
+export * from './TypesApi.js';
+export { APP_VERSION_HEADER } from './version.js';
+export * from './WorkflowsApi.js';

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

@@ -0,0 +1,182 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { fetchSignedUrl } from './signed-url.js';
+
+function streamOf(chunk: Uint8Array): ReadableStream {
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(chunk);
+            controller.close();
+        },
+    });
+}
+
+function response(status: number, body = '', headers?: Record<string, string>): Response {
+    return new Response(status === 204 ? null : body, { status, headers });
+}
+
+describe('fetchSignedUrl', () => {
+    let fetchMock: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+        fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        // Make backoff instantaneous so the tests don't actually wait.
+        vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.unstubAllGlobals();
+        vi.restoreAllMocks();
+    });
+
+    async function runAllTimers<T>(promise: Promise<T>): Promise<T> {
+        await vi.runAllTimersAsync();
+        return promise;
+    }
+
+    it('returns immediately on a successful response', async () => {
+        fetchMock.mockResolvedValueOnce(response(200, 'ok'));
+        const res = await runAllTimers(fetchSignedUrl('https://storage/x'));
+        expect(res.status).toBe(200);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('retries on a 503 and succeeds', async () => {
+        fetchMock
+            .mockResolvedValueOnce(response(503, 'try later'))
+            .mockResolvedValueOnce(response(503, 'try later'))
+            .mockResolvedValueOnce(response(200, 'ok'));
+        const res = await runAllTimers(fetchSignedUrl('https://storage/x', { method: 'PUT', body: 'data' }));
+        expect(res.status).toBe(200);
+        expect(fetchMock).toHaveBeenCalledTimes(3);
+    });
+
+    it('retries on connection errors and succeeds', async () => {
+        fetchMock.mockRejectedValueOnce(new TypeError('network error')).mockResolvedValueOnce(response(200, 'ok'));
+        const res = await runAllTimers(fetchSignedUrl('https://storage/x'));
+        expect(res.status).toBe(200);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not retry non-retryable statuses (404)', async () => {
+        fetchMock.mockResolvedValueOnce(response(404, 'missing'));
+        const res = await runAllTimers(fetchSignedUrl('https://storage/x'));
+        expect(res.status).toBe(404);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('returns the last retryable response after exhausting attempts', async () => {
+        fetchMock.mockResolvedValue(response(503, 'down'));
+        const res = await runAllTimers(fetchSignedUrl('https://storage/x', { attempts: 3 }));
+        expect(res.status).toBe(503);
+        expect(fetchMock).toHaveBeenCalledTimes(3);
+    });
+
+    it('throws the connection error after exhausting attempts', async () => {
+        const err = new TypeError('network down');
+        fetchMock.mockRejectedValue(err);
+        // Attach the rejection expectation before advancing timers to avoid an
+        // unhandled rejection while the backoff timer is pending.
+        const assertion = expect(fetchSignedUrl('https://storage/x', { attempts: 2 })).rejects.toThrow('network down');
+        await vi.runAllTimersAsync();
+        await assertion;
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('buffers a ReadableStream body so it can be replayed across retries', async () => {
+        const bodies: unknown[] = [];
+        fetchMock.mockImplementation((_url: string, init: RequestInit) => {
+            bodies.push(init.body);
+            return Promise.resolve(bodies.length < 2 ? response(503, 'retry') : response(200, 'ok'));
+        });
+
+        const stream = streamOf(new TextEncoder().encode('hello'));
+        const res = await runAllTimers(
+            fetchSignedUrl('https://storage/x', { method: 'PUT', body: stream as unknown as BodyInit }),
+        );
+
+        expect(res.status).toBe(200);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        // The stream was buffered into a replayable Blob, and the same instance was reused on retry.
+        expect(bodies[0]).toBeInstanceOf(Blob);
+        expect(bodies[0]).toBe(bodies[1]);
+    });
+
+    it('buffers a string-chunk ReadableStream body without throwing (regression: non-Uint8Array chunk)', async () => {
+        const bodies: unknown[] = [];
+        fetchMock.mockImplementation((_url: string, init: RequestInit) => {
+            bodies.push(init.body);
+            return Promise.resolve(response(200, 'ok'));
+        });
+
+        // A web stream that yields *string* chunks — what `Readable.toWeb(Readable.from(text))`
+        // produces (NodeStreamSource wraps text bodies this way). `new Response(stream).blob()`
+        // rejects these under undici with "Received non-Uint8Array chunk"; the helper must
+        // encode them to bytes instead.
+        const stream = new ReadableStream<string>({
+            start(controller) {
+                controller.enqueue('hello ');
+                controller.enqueue('world');
+                controller.close();
+            },
+        });
+
+        const res = await runAllTimers(
+            fetchSignedUrl('https://storage/x', { method: 'PUT', body: stream as unknown as BodyInit }),
+        );
+
+        expect(res.status).toBe(200);
+        expect(bodies[0]).toBeInstanceOf(Blob);
+        expect(await (bodies[0] as Blob).text()).toBe('hello world');
+    });
+
+    it('buffers a mixed-chunk ReadableStream body, encoding strings and keeping bytes', async () => {
+        const bodies: unknown[] = [];
+        fetchMock.mockImplementation((_url: string, init: RequestInit) => {
+            bodies.push(init.body);
+            return Promise.resolve(response(200, 'ok'));
+        });
+
+        const stream = new ReadableStream<string | Uint8Array>({
+            start(controller) {
+                controller.enqueue('a');
+                controller.enqueue(new TextEncoder().encode('b'));
+                controller.close();
+            },
+        });
+
+        const res = await runAllTimers(
+            fetchSignedUrl('https://storage/x', { method: 'PUT', body: stream as unknown as BodyInit }),
+        );
+
+        expect(res.status).toBe(200);
+        expect(bodies[0]).toBeInstanceOf(Blob);
+        expect(await (bodies[0] as Blob).text()).toBe('ab');
+    });
+
+    it('throws on an object-mode stream chunk instead of silently corrupting the upload', async () => {
+        const stream = new ReadableStream<unknown>({
+            start(controller) {
+                controller.enqueue({ not: 'bytes' });
+                controller.close();
+            },
+        });
+
+        await expect(
+            fetchSignedUrl('https://storage/x', { method: 'PUT', body: stream as unknown as BodyInit }),
+        ).rejects.toThrow(TypeError);
+        // The bad body is rejected before any network call is attempted.
+        expect(fetchMock).not.toHaveBeenCalled();
+        expect(stream.locked).toBe(false);
+    });
+
+    it('honors a numeric Retry-After header when scheduling the retry', async () => {
+        fetchMock
+            .mockResolvedValueOnce(response(503, 'slow down', { 'retry-after': '2' }))
+            .mockResolvedValueOnce(response(200, 'ok'));
+        const res = await runAllTimers(fetchSignedUrl('https://storage/x'));
+        expect(res.status).toBe(200);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+});

package/src/store/signed-url.ts

@@ -0,0 +1,184 @@
+/**
+ * Helpers for transferring file content to/from cloud-storage signed URLs
+ * (GCS, S3, Azure Blob) with retry + backoff on transient failures.
+ *
+ * Signed-URL transfers go straight to the storage backend and therefore bypass
+ * the Vertesia API client (`AbstractFetchClient`), which means they normally get
+ * none of its retry policy. A single transient `503 Service Unavailable` from the
+ * storage backend would otherwise fail the whole upload/download. This helper
+ * restores retry behaviour for those storage hops.
+ *
+ * Note on streamed bodies: a `ReadableStream` body cannot be replayed once it has
+ * been consumed, so it is buffered into memory before the first attempt to make
+ * retries safe. Callers transferring very large streams should be aware of this
+ * memory cost.
+ */
+
+/** HTTP statuses that storage backends return for transient, retryable conditions. */
+const DEFAULT_RETRYABLE_STATUSES: ReadonlySet<number> = new Set([429, 500, 502, 503, 504]);
+
+const DEFAULT_ATTEMPTS = 4;
+const DEFAULT_BASE_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 8_000;
+
+export interface SignedUrlFetchOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: BodyInit | null;
+    /** Total number of attempts, including the first. Defaults to 4. */
+    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. */
+    maxDelayMs?: number;
+    /** HTTP statuses to retry on. Defaults to 429, 500, 502, 503, 504. */
+    retryableStatuses?: ReadonlySet<number>;
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function retryAfterMs(res: Response): number | undefined {
+    const header = res.headers.get('retry-after');
+    if (!header) {
+        return undefined;
+    }
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds * 1000;
+    }
+    const date = Date.parse(header);
+    if (!Number.isNaN(date)) {
+        return Math.max(0, date - Date.now());
+    }
+    return 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);
+    }
+    // Exponential backoff with full jitter.
+    const capped = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+    return Math.floor(Math.random() * capped);
+}
+
+const textEncoder = new TextEncoder();
+
+/**
+ * Normalize one `ReadableStream` chunk to a byte-backed `BlobPart`.
+ *
+ * A web stream produced from a Node `Readable.from(<string>)` (e.g. via
+ * `Readable.toWeb`, which `NodeStreamSource` uses) yields *string* chunks. Buffering
+ * such a stream with `new Response(stream).blob()` throws under undici with
+ * "TypeError: Received non-Uint8Array chunk", which breaks every signed-URL upload of
+ * a text/JSON body (extracted text previews, agent artifacts, tool storage). Encoding
+ * chunks ourselves keeps both string and binary bodies uploadable.
+ */
+function chunkToBlobPart(chunk: unknown): BlobPart {
+    if (typeof chunk === 'string') {
+        return textEncoder.encode(chunk);
+    }
+    if (chunk instanceof Blob) {
+        return chunk;
+    }
+    if (chunk instanceof ArrayBuffer) {
+        return new Uint8Array(chunk);
+    }
+    // Covers Uint8Array and every other typed-array / DataView view.
+    if (ArrayBuffer.isView(chunk)) {
+        return new Uint8Array(chunk.buffer as ArrayBuffer, chunk.byteOffset, chunk.byteLength);
+    }
+    // Fail loud rather than uploading e.g. "[object Object]" from an accidental
+    // object-mode stream — silently corrupting the stored content is worse than a clear error.
+    throw new TypeError(
+        `Unsupported signed-URL upload chunk of type "${typeof chunk}"; ` +
+            `body streams must yield string or binary (Uint8Array/ArrayBuffer/DataView/Blob) chunks.`,
+    );
+}
+
+/**
+ * Buffer a `ReadableStream` body into a `Blob` so the request can be safely
+ * replayed across retries. Other body types (`Blob`/`File`, `ArrayBuffer`,
+ * typed arrays, strings, `URLSearchParams`) are already replayable and pass
+ * through unchanged.
+ *
+ * The stream is drained manually (rather than `new Response(stream).blob()`) so that
+ * string chunks are encoded to bytes — see {@link chunkToBlobPart}.
+ */
+async function toReplayableBody(body: BodyInit | null | undefined): Promise<BodyInit | undefined> {
+    if (body == null) {
+        return undefined;
+    }
+    if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream) {
+        const reader = (body as ReadableStream<unknown>).getReader();
+        const parts: BlobPart[] = [];
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                // Normalize every chunk (a stray null/undefined is rejected by
+                // chunkToBlobPart) so a malformed stream fails loudly instead of
+                // silently uploading a truncated body.
+                parts.push(chunkToBlobPart(value));
+            }
+        } catch (err) {
+            // Signal the producer to stop and release its resources before propagating.
+            await reader.cancel(err).catch(() => undefined);
+            throw err;
+        } finally {
+            reader.releaseLock();
+        }
+        return new Blob(parts);
+    }
+    return 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.
+ *
+ * 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
+ * as-is for the caller to handle.
+ */
+export async function fetchSignedUrl(url: string, options: SignedUrlFetchOptions = {}): Promise<Response> {
+    const {
+        method = 'GET',
+        headers,
+        attempts = DEFAULT_ATTEMPTS,
+        baseDelayMs = DEFAULT_BASE_DELAY_MS,
+        maxDelayMs = DEFAULT_MAX_DELAY_MS,
+        retryableStatuses = DEFAULT_RETRYABLE_STATUSES,
+    } = options;
+
+    const body = await toReplayableBody(options.body);
+
+    let lastError: unknown;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        const isLastAttempt = attempt === attempts - 1;
+        try {
+            const res = await fetch(url, { method, headers, body });
+            if (res.ok || !retryableStatuses.has(res.status) || isLastAttempt) {
+                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));
+        } catch (err) {
+            lastError = err;
+            if (isLastAttempt) {
+                throw err;
+            }
+            await sleep(backoffMs(attempt, baseDelayMs, maxDelayMs));
+        }
+    }
+
+    // Unreachable: the loop always returns a Response or throws on the last attempt.
+    throw lastError instanceof Error ? lastError : new Error(`Failed to fetch signed URL: ${url}`);
+}