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

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/ViewsApi.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ZenoClient } from './client.js';
+
+describe('StoreViewsApi', () => {
+    it('uses the View execution resource for persisted and draft execution', async () => {
+        const requests: Request[] = [];
+        const fetchMock = vi.fn(async () => {
+            return new Response(JSON.stringify({}), {
+                status: 200,
+                headers: { 'content-type': 'application/json' },
+            });
+        });
+        const client = new ZenoClient({
+            serverUrl: 'https://api.example.com',
+            fetch: fetchMock,
+            onRequest: (request) => requests.push(request),
+        });
+
+        await client.views.execute('app:content:document-library');
+        await client.views.preview({
+            configuration: {
+                name: 'Document library',
+                description: 'Browse documents.',
+                scope: {},
+            },
+        });
+
+        expect(requests.map((request) => request.url)).toEqual([
+            'https://api.example.com/api/v1/view-executions/app%3Acontent%3Adocument-library/execute',
+            'https://api.example.com/api/v1/view-executions/preview',
+        ]);
+    });
+});

package/src/store/ViewsApi.ts

@@ -0,0 +1,20 @@
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type { ExecuteViewRequest, PreviewViewExperienceRequest, ViewExecutionResult } from '@vertesia/common';
+
+export class StoreViewsApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, '/api/v1/view-executions');
+    }
+
+    execute(id: string, payload: ExecuteViewRequest = {}): Promise<ViewExecutionResult> {
+        return this.post(`/${encodeURIComponent(id)}/execute`, { payload });
+    }
+
+    /**
+     * Validate and execute an unsaved View configuration without persisting it.
+     * Returns the same normalized results as {@link execute}.
+     */
+    preview(payload: PreviewViewExperienceRequest): Promise<ViewExecutionResult> {
+        return this.post('/preview', { payload });
+    }
+}

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';
@@ -24,6 +24,7 @@ import { RenderingApi } from './RenderingApi.js';
 import { SchedulesApi } from './SchedulesApi.js';
 import { TaskApi } from './TaskApi.js';
 import { TypesApi } from './TypesApi.js';
+import { StoreViewsApi } from './ViewsApi.js';
 import { VERSION, VERSION_HEADER } from './version.js';
 import { WorkflowsApi } from './WorkflowsApi.js';
 
@@ -77,6 +78,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);
     }
@@ -115,4 +126,5 @@ export class ZenoClient extends AbstractFetchClient<ZenoClient> {
     query = new QueryApi(this);
     hiveMemory = new HiveMemoryApi(this);
     rendering = new RenderingApi(this);
+    views = new StoreViewsApi(this);
 }

package/src/store/index.ts

@@ -20,4 +20,6 @@ export * from './signed-url.js';
 export * from './TaskApi.js';
 export * from './TypeCatalogApi.js';
 export * from './TypesApi.js';
+export * from './ViewsApi.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';