@vertesia/client 1.5.0-dev.20260714.072725Z → 1.5.0-dev.20260717.131047Z

package/src/store/EventsApi.test.ts

@@ -0,0 +1,131 @@
+import type { EventDeliveryStreamSnapshot } from '@vertesia/common';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { VertesiaClient } from '../client.js';
+
+type Listener = (event: MessageEvent) => void;
+
+class FakeEventSource {
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSED = 2;
+
+    static instances: FakeEventSource[] = [];
+    static urls: string[] = [];
+
+    readonly url: string;
+    readonly withCredentials = false;
+    readyState = FakeEventSource.CONNECTING;
+    onopen: ((event: Event) => void) | null = null;
+    onmessage: ((event: MessageEvent) => void) | null = null;
+    onerror: ((event: Event) => void) | null = null;
+    private readonly listeners = new Map<string, Listener[]>();
+
+    constructor(url: string) {
+        this.url = url;
+        FakeEventSource.urls.push(url);
+        FakeEventSource.instances.push(this);
+    }
+
+    close() {
+        this.readyState = FakeEventSource.CLOSED;
+    }
+
+    addEventListener(type: string, listener: Listener) {
+        const listeners = this.listeners.get(type) ?? [];
+        listeners.push(listener);
+        this.listeners.set(type, listeners);
+    }
+
+    removeEventListener() {}
+
+    dispatchEvent() {
+        return true;
+    }
+
+    emit(type: string, data: unknown, lastEventId = '') {
+        const event = { data: JSON.stringify(data), lastEventId } as MessageEvent;
+        for (const listener of this.listeners.get(type) ?? []) {
+            listener(event);
+        }
+        if (type === 'message') {
+            this.onmessage?.(event);
+        }
+    }
+}
+
+function createClient(): VertesiaClient {
+    const client = new VertesiaClient({
+        serverUrl: 'https://studio.example.test',
+        storeUrl: 'https://store.example.test',
+    });
+    client.withAuthCallback(async () => 'Bearer test-token');
+    return client;
+}
+
+describe('EventsApi.subscribeDeliveries', () => {
+    beforeEach(() => {
+        FakeEventSource.instances = [];
+        FakeEventSource.urls = [];
+        vi.stubGlobal('EventSource', FakeEventSource);
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.restoreAllMocks();
+    });
+
+    it('serializes stream filters and auth token into the EventSource URL', async () => {
+        const client = createClient();
+        const subscription = client.events.subscribeDeliveries({
+            resource_id: 'agentic-coworker-platform',
+            resource_type: ['app', 'workflow_run'],
+            event_category: ['workflow', 'system'],
+            action: ['create', 'workflow_completed'],
+            outbox_status: ['failed'],
+            include_event: true,
+            poll_interval_ms: 1500,
+            on_envelope: () => {},
+        });
+
+        await vi.waitFor(() => expect(FakeEventSource.urls).toHaveLength(1));
+        const url = new URL(FakeEventSource.urls[0]);
+
+        expect(url.href).toContain('https://store.example.test/api/v1/events/stream');
+        expect(url.searchParams.get('access_token')).toBe('test-token');
+        expect(url.searchParams.get('resource_id')).toBe('agentic-coworker-platform');
+        expect(url.searchParams.get('resource_type')).toBe('app,workflow_run');
+        expect(url.searchParams.get('event_category')).toBe('workflow,system');
+        expect(url.searchParams.get('action')).toBe('create,workflow_completed');
+        expect(url.searchParams.get('outbox_status')).toBe('failed');
+        expect(url.searchParams.get('include_event')).toBe('true');
+        expect(url.searchParams.get('poll_interval_ms')).toBe('1500');
+
+        subscription.close();
+    });
+
+    it('dispatches typed snapshot envelopes to the snapshot callback', async () => {
+        const client = createClient();
+        const snapshots: EventDeliveryStreamSnapshot[] = [];
+        const subscription = client.events.subscribeDeliveries({
+            resource_id: 'demo-app',
+            on_snapshot: (_items, envelope) => snapshots.push(envelope),
+        });
+
+        await vi.waitFor(() => expect(FakeEventSource.instances).toHaveLength(1));
+        FakeEventSource.instances[0].emit(
+            'snapshot',
+            {
+                type: 'snapshot',
+                emitted_at: '2026-06-27T00:00:00.000Z',
+                cursor: 'evt_1',
+                deliveries: [],
+            } satisfies EventDeliveryStreamSnapshot,
+            'evt_1',
+        );
+
+        expect(snapshots).toHaveLength(1);
+        expect(snapshots[0].cursor).toBe('evt_1');
+
+        subscription.close();
+    });
+});

package/src/store/EventsApi.ts

@@ -2,12 +2,32 @@ import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
 import type {
     EventDeliveryQueueSummaryPayload,
     EventDeliveryQueueSummaryResponse,
+    EventDeliveryStreamEnvelope,
+    EventDeliveryStreamItem,
+    EventDeliveryStreamSnapshot,
+    EventDeliveryStreamUpdate,
     ListEventDeliveriesPayload,
     ListEventDeliveriesResponse,
+    StreamEventDeliveriesQuery,
 } from '@vertesia/common';
+import {
+    type ManagedEventSourceConnection,
+    type ManagedEventSourceStatus,
+    openManagedEventSource,
+} from '../managed-sse.js';
 import { EventIngestChannelsApi } from './EventIngestChannelsApi.js';
 import { EventSubscriptionsApi } from './EventSubscriptionsApi.js';
 
+export interface SubscribeEventDeliveriesOptions extends StreamEventDeliveriesQuery {
+    signal?: AbortSignal;
+    max_reconnect_attempts?: number;
+    on_snapshot?: (deliveries: EventDeliveryStreamItem[], envelope: EventDeliveryStreamSnapshot) => void;
+    on_delivery?: (delivery: EventDeliveryStreamItem, envelope: EventDeliveryStreamUpdate) => void;
+    on_envelope?: (envelope: EventDeliveryStreamEnvelope) => void;
+    on_error?: (error: unknown) => void;
+    on_status?: (status: ManagedEventSourceStatus) => void;
+}
+
 export class EventsApi extends ApiTopic {
     readonly subscriptions: EventSubscriptionsApi;
     readonly channels: EventIngestChannelsApi;
@@ -25,4 +45,64 @@ export class EventsApi extends ApiTopic {
     queueSummary(payload: EventDeliveryQueueSummaryPayload = {}): Promise<EventDeliveryQueueSummaryResponse> {
         return this.post('/deliveries/queue-summary', { payload });
     }
+
+    subscribeDeliveries(options: SubscribeEventDeliveriesOptions): ManagedEventSourceConnection {
+        const { signal, max_reconnect_attempts, on_snapshot, on_delivery, on_envelope, on_error, on_status, ...query } =
+            options;
+
+        return openManagedEventSource<EventDeliveryStreamEnvelope>({
+            url: () => this.buildStreamUrl(query),
+            event_types: ['snapshot', 'event', 'heartbeat', 'error'],
+            signal,
+            max_reconnect_attempts,
+            last_event_id_query_param: 'since_event_id',
+            get_access_token: async () => {
+                const client = this.client as ClientBase & { _auth?: () => Promise<string> };
+                return client._auth ? await client._auth() : undefined;
+            },
+            get_cursor: (envelope) => envelope.cursor,
+            on_status,
+            on_error,
+            on_event: ({ data }) => {
+                on_envelope?.(data);
+                if (data.type === 'snapshot') {
+                    on_snapshot?.(data.deliveries, data);
+                } else if (data.type === 'event') {
+                    on_delivery?.(data.item, data);
+                } else if (data.type === 'error') {
+                    on_error?.(new Error(data.error));
+                }
+            },
+        });
+    }
+
+    private buildStreamUrl(query: StreamEventDeliveriesQuery): URL {
+        const url = new URL(`${this.baseUrl}/stream`);
+        this.setStreamParam(url, 'limit', query.limit);
+        this.setStreamParam(url, 'event_id', query.event_id);
+        this.setStreamParam(url, 'resource_id', query.resource_id);
+        this.setStreamListParam(url, 'resource_type', query.resource_type);
+        this.setStreamListParam(url, 'event_category', query.event_category);
+        this.setStreamListParam(url, 'action', query.action);
+        this.setStreamListParam(url, 'outbox_status', query.outbox_status);
+        this.setStreamParam(url, 'since_event_id', query.since_event_id);
+        this.setStreamParam(url, 'since_created_at', query.since_created_at);
+        this.setStreamParam(url, 'include_event', query.include_event);
+        this.setStreamParam(url, 'poll_interval_ms', query.poll_interval_ms);
+        return url;
+    }
+
+    private setStreamParam(url: URL, key: string, value: string | number | boolean | undefined): void {
+        if (value === undefined || value === null || value === '') {
+            return;
+        }
+        url.searchParams.set(key, String(value));
+    }
+
+    private setStreamListParam(url: URL, key: string, value: string[] | undefined): void {
+        if (!value?.length) {
+            return;
+        }
+        url.searchParams.set(key, value.join(','));
+    }
 }

package/src/store/FilesApi.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { ZenoClient } from './client.js';
+
+describe('FilesApi', () => {
+    it('retries signed upload URL creation after a transient connection failure', async () => {
+        let attempts = 0;
+        const fetchSignedUploadUrl = async (): Promise<Response> => {
+            attempts++;
+            if (attempts === 1) {
+                throw new TypeError('fetch failed');
+            }
+            return new Response(
+                JSON.stringify({ id: 'file-1', path: 'agents/run/conversation.json', url: 'https://signed' }),
+                {
+                    status: 200,
+                    headers: { 'content-type': 'application/json' },
+                },
+            );
+        };
+
+        const client = new ZenoClient({
+            serverUrl: 'https://store.test',
+            apikey: 'token',
+            fetch: fetchSignedUploadUrl,
+        });
+
+        const result = await client.files.getUploadUrl({
+            name: 'conversation.json',
+            id: 'agents/run/conversation.json',
+        });
+
+        expect(result).toEqual({ id: 'file-1', path: 'agents/run/conversation.json', url: 'https://signed' });
+        expect(attempts).toBe(2);
+    });
+
+    it('retries signed upload URL creation after a transient 503', async () => {
+        let attempts = 0;
+        const fetchSignedUploadUrl = async (): Promise<Response> => {
+            attempts++;
+            if (attempts === 1) {
+                return new Response(JSON.stringify({ message: 'try again' }), {
+                    status: 503,
+                    headers: { 'content-type': 'application/json' },
+                });
+            }
+            return new Response(
+                JSON.stringify({ id: 'file-1', path: 'agents/run/conversation.json', url: 'https://signed' }),
+                {
+                    status: 200,
+                    headers: { 'content-type': 'application/json' },
+                },
+            );
+        };
+
+        const client = new ZenoClient({
+            serverUrl: 'https://store.test',
+            apikey: 'token',
+            fetch: fetchSignedUploadUrl,
+        });
+
+        const result = await client.files.getUploadUrl({
+            name: 'conversation.json',
+            id: 'agents/run/conversation.json',
+        });
+
+        expect(result).toEqual({ id: 'file-1', path: 'agents/run/conversation.json', url: 'https://signed' });
+        expect(attempts).toBe(2);
+    });
+});

package/src/store/FilesApi.ts

@@ -1,4 +1,4 @@
-import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import { ApiTopic, type ClientBase, type IRequestRetryPolicy } from '@vertesia/api-fetch-client';
 import type {
     BucketReadAccessStatusResponse,
     BulkUploadUrlsPayload,
@@ -21,6 +21,12 @@ import { fetchSignedUrl } from './signed-url.js';
 export const MEMORIES_PREFIX = 'memories';
 export const ARTIFACTS_PREFIX = 'agents';
 
+const FILE_SIGNING_RETRY_POLICY: IRequestRetryPolicy = {
+    attempts: 3,
+    methods: ['POST'],
+    statuses: [502, 503, 504],
+};
+
 export function getMemoryFilePath(name: string) {
     const nameWithExt = name.endsWith('.tar.gz') ? name : `${name}.tar.gz`;
     return `${MEMORIES_PREFIX}/${nameWithExt}`;
@@ -95,6 +101,7 @@ export class FilesApi extends ApiTopic {
     getUploadUrl(payload: GetUploadUrlPayload): Promise<GetFileUrlResponse> {
         return this.post('/upload-url', {
             payload,
+            retryPolicy: FILE_SIGNING_RETRY_POLICY,
         });
     }
 

package/src/store/client.ts

@@ -4,7 +4,7 @@ import {
     type IRequestRetryPolicy,
     type RequestError,
 } from '@vertesia/api-fetch-client';
-import type { BulkOperationPayload, BulkOperationResponse } from '@vertesia/common';
+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';
@@ -77,6 +77,16 @@ 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);
     }

package/src/store/index.ts

@@ -20,4 +20,5 @@ 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/version.ts

@@ -1,2 +1,3 @@
 export const VERSION = '20260319'; // YYYYMMDD, client versioning for API endpoints. Increment manually for breaking changes
 export const VERSION_HEADER = 'x-api-version';
+export { APP_VERSION_HEADER } from '@vertesia/common';