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

package/src/client.ts

@@ -1,5 +1,5 @@
 import { AbstractFetchClient, type FETCH_FN, type IRequestRetryPolicy } from '@vertesia/api-fetch-client';
-import type { AuthTokenPayload, AuthTokenResponse } from '@vertesia/common';
+import { APP_VERSION_HEADER, type AuthTokenPayload, type AuthTokenResponse } from '@vertesia/common';
 import AccountApi from './AccountApi.js';
 import AccountsApi from './AccountsApi.js';
 import AnalyticsApi from './AnalyticsApi.js';
@@ -28,6 +28,7 @@ import { VERSION, VERSION_HEADER } from './store/version.js';
 import ToolsApi from './ToolsApi.js';
 import TrainingApi from './TrainingApi.js';
 import UsersApi from './UsersApi.js';
+import ViewsApi from './ViewsApi.js';
 
 /**
  * 1 min threshold constant in ms
@@ -116,7 +117,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     static async fromAuthToken(
         token: string,
         payload?: AuthTokenPayload,
-        endpoints?: { studio: string; store: string; token?: string },
+        endpoints?: { studio: string; store: string; token?: string; git?: string },
     ) {
         if (!payload) {
             payload = decodeJWT(token);
@@ -206,6 +207,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
             timeout: opts.timeout,
             fetch: opts.fetch,
         });
+        this.views = new ViewsApi(this, this.store.views);
 
         if (opts.retryPolicy) {
             this.withRetryPolicy(opts.retryPolicy);
@@ -240,6 +242,20 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         return this;
     }
 
+    /**
+     * Pin the app version this client's requests resolve against. A generated app's UI sets this from
+     * its build-time `VITE_APP_VERSION` so studio/zeno resolve its `app:<app>:…` refs against that
+     * exact built version instead of the promoted version. Pass null/empty to clear (→ promoted).
+     */
+    withAppVersion(version: string | null | undefined) {
+        if (!version) {
+            delete this.headers[APP_VERSION_HEADER];
+        } else {
+            this.headers[APP_VERSION_HEADER] = String(version);
+        }
+        return this;
+    }
+
     /**
      * Overwrite to keep store and composable clients synchronized on the auth callback
      * @param authCb
@@ -411,6 +427,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     apps = new AppsApi(this);
     tools = new ToolsApi(this);
     quota = new QuotaApi(this);
+    views: ViewsApi;
 }
 
 function isApiKey(apiKey: string) {
@@ -500,6 +517,7 @@ function getEndpointsFromDomain(domain: string) {
             studio: `http://localhost:8091`,
             store: `http://localhost:8092`,
             token: getRuntimeStsUrl() ?? 'https://sts.dev1.vertesia.io',
+            git: 'https://git.dev1.vertesia.io',
         };
     } else {
         const url = `https://${domain}`;
@@ -509,6 +527,7 @@ function getEndpointsFromDomain(domain: string) {
             studio: url,
             store: url,
             token: url.replace('api', 'sts'),
+            git: url.replace('api', 'git'),
         };
     }
 }

package/src/index.ts

@@ -7,6 +7,7 @@ export type { GroupsQueryOptions } from './GroupsApi.js';
 export * from './InteractionBase.js';
 export * from './InteractionOutput.js';
 export { default as InternalSecretsApi } from './InternalSecretsApi.js';
+export * from './managed-sse.js';
 export { default as OAuthClientsApi } from './OAuthClientsApi.js';
 export { default as OAuthGrantsApi } from './OAuthGrantsApi.js';
 export { default as OAuthProvidersApi } from './OAuthProvidersApi.js';
@@ -17,4 +18,5 @@ export type { ComputeRunFacetsResponse, FilterOption } from './RunsApi.js';
 export { default as SecretsApi } from './SecretsApi.js';
 export * from './StreamSource.js';
 export * from './store/index.js';
+export { default as ViewsApi } from './ViewsApi.js';
 export type { AsyncExecutionResult };

package/src/managed-sse.ts

@@ -0,0 +1,205 @@
+import { EventSourceProvider } from './execute.js';
+
+export type ManagedEventSourceStatus = 'connecting' | 'open' | 'reconnecting' | 'closed';
+
+export interface ManagedEventSourceEvent<T> {
+    data: T;
+    event_type: string;
+    event_id?: string;
+}
+
+export interface ManagedEventSourceConnection {
+    readonly closed: boolean;
+    close(): void;
+}
+
+export interface ManagedEventSourceOptions<T> {
+    url: URL | string | (() => URL | string | Promise<URL | string>);
+    event_types?: string[];
+    signal?: AbortSignal;
+    max_reconnect_attempts?: number;
+    base_reconnect_delay_ms?: number;
+    max_reconnect_delay_ms?: number;
+    last_event_id_query_param?: string;
+    get_access_token?: () => Promise<string | undefined>;
+    parse?: (data: string, eventType: string) => T;
+    get_cursor?: (data: T) => string | undefined;
+    on_event: (event: ManagedEventSourceEvent<T>) => void;
+    on_error?: (error: unknown) => void;
+    on_status?: (status: ManagedEventSourceStatus) => void;
+}
+
+function defaultParse<T>(data: string): T {
+    return JSON.parse(data) as T;
+}
+
+function calculateBackoffDelay(attempts: number, baseDelayMs: number, maxDelayMs: number): number {
+    const exponentialDelay = Math.min(baseDelayMs * 2 ** attempts, maxDelayMs);
+    const jitter = Math.random() * 0.1 * exponentialDelay;
+    return exponentialDelay + jitter;
+}
+
+function withAccessToken(url: URL, bearerToken: string | undefined): void {
+    if (!bearerToken) {
+        return;
+    }
+    const token = bearerToken.startsWith('Bearer ') ? bearerToken.slice('Bearer '.length) : bearerToken;
+    url.searchParams.set('access_token', token);
+}
+
+async function resolveUrl(value: ManagedEventSourceOptions<unknown>['url']): Promise<URL> {
+    const resolved = typeof value === 'function' ? await value() : value;
+    return resolved instanceof URL ? new URL(resolved.href) : new URL(resolved);
+}
+
+export function openManagedEventSource<T>(options: ManagedEventSourceOptions<T>): ManagedEventSourceConnection {
+    const eventTypes = options.event_types?.length ? options.event_types : ['message'];
+    const maxReconnectAttempts = options.max_reconnect_attempts ?? 10;
+    const baseDelayMs = options.base_reconnect_delay_ms ?? 1000;
+    const maxDelayMs = options.max_reconnect_delay_ms ?? 30_000;
+    const parse = options.parse ?? defaultParse<T>;
+
+    let closed = false;
+    let reconnectAttempts = 0;
+    let currentSse: EventSource | null = null;
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+    let abortHandler: (() => void) | null = null;
+    let connectionOpenedAt = 0;
+    let lastEventId: string | undefined;
+
+    const emitStatus = (status: ManagedEventSourceStatus) => {
+        options.on_status?.(status);
+    };
+
+    const cleanupCurrentSource = () => {
+        if (currentSse) {
+            currentSse.close();
+            currentSse = null;
+        }
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+    };
+
+    const close = () => {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        cleanupCurrentSource();
+        if (options.signal && abortHandler) {
+            options.signal.removeEventListener('abort', abortHandler);
+            abortHandler = null;
+        }
+        emitStatus('closed');
+    };
+
+    const scheduleReconnect = (error: unknown) => {
+        if (closed) {
+            return;
+        }
+        cleanupCurrentSource();
+        const connectionDuration = connectionOpenedAt ? Date.now() - connectionOpenedAt : 0;
+        if (connectionDuration > 5000) {
+            reconnectAttempts = 0;
+        }
+        if (reconnectAttempts >= maxReconnectAttempts) {
+            close();
+            options.on_error?.(error);
+            return;
+        }
+        const delay = calculateBackoffDelay(reconnectAttempts, baseDelayMs, maxDelayMs);
+        reconnectAttempts += 1;
+        emitStatus('reconnecting');
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = null;
+            void connect(true);
+        }, delay);
+    };
+
+    const handleMessage = (eventType: string, ev: MessageEvent) => {
+        if (closed || !ev.data || String(ev.data).startsWith(':')) {
+            return;
+        }
+        try {
+            const data = parse(String(ev.data), eventType);
+            const cursor = options.get_cursor?.(data);
+            lastEventId = ev.lastEventId || cursor || lastEventId;
+            options.on_event({
+                data,
+                event_type: eventType,
+                event_id: ev.lastEventId || cursor,
+            });
+        } catch (err) {
+            options.on_error?.(err);
+        }
+    };
+
+    const connect = async (isReconnect: boolean) => {
+        if (closed) {
+            return;
+        }
+        try {
+            emitStatus(isReconnect ? 'reconnecting' : 'connecting');
+            const EventSourceImpl = await EventSourceProvider();
+            if (closed) {
+                return;
+            }
+            const url = await resolveUrl(options.url);
+            if (
+                lastEventId &&
+                options.last_event_id_query_param &&
+                !url.searchParams.has(options.last_event_id_query_param)
+            ) {
+                url.searchParams.set(options.last_event_id_query_param, lastEventId);
+            }
+            withAccessToken(url, await options.get_access_token?.());
+            if (closed) {
+                return;
+            }
+            const sse = new EventSourceImpl(url.href);
+            currentSse = sse;
+            connectionOpenedAt = 0;
+
+            sse.onopen = () => {
+                connectionOpenedAt = Date.now();
+                emitStatus('open');
+            };
+
+            for (const eventType of eventTypes) {
+                sse.addEventListener(eventType, (ev) => handleMessage(eventType, ev as MessageEvent));
+            }
+
+            sse.onerror = (err: unknown) => {
+                scheduleReconnect(err);
+            };
+        } catch (err) {
+            scheduleReconnect(err);
+        }
+    };
+
+    if (options.signal) {
+        if (options.signal.aborted) {
+            closed = true;
+            emitStatus('closed');
+            return {
+                get closed() {
+                    return closed;
+                },
+                close,
+            };
+        }
+        abortHandler = close;
+        options.signal.addEventListener('abort', abortHandler, { once: true });
+    }
+
+    void connect(false);
+
+    return {
+        get closed() {
+            return closed;
+        },
+        close,
+    };
+}

package/src/store/AgentsApi.ts

@@ -362,6 +362,61 @@ export class AgentsApi extends ApiTopic {
             }
         };
 
+        // SSE reconnection exhausted. The run is durable and still executing
+        // server-side — only the live view dropped. Failing fatally here aborts
+        // headless consumers (CLI `agents stream`, agent test harnesses) before
+        // they can read the result. Instead degrade gracefully: poll GET /updates
+        // for any messages we missed and exit cleanly once the run is terminal,
+        // even if the terminal message never streamed.
+        const POLL_INTERVAL_MS = 5000;
+        const isTerminalStatus = (status: unknown): boolean =>
+            typeof status === 'string' && ['completed', 'failed', 'cancelled'].includes(status);
+        const degradeToPolling = (reason: unknown) => {
+            if (isClosed) return;
+            cleanup();
+            console.warn(
+                `Agent stream ${id}: SSE unavailable after ${maxReconnectAttempts} attempts; falling back to /updates polling.`,
+                reason instanceof Error ? reason.message : reason,
+            );
+            const tick = async () => {
+                if (isClosed) return;
+                try {
+                    const recent = await this.retrieveMessages(id, lastMessageTimestamp || undefined);
+                    for (const msg of recent) {
+                        if (isClosed) return;
+                        if ((msg.timestamp || 0) <= lastMessageTimestamp) continue;
+                        lastMessageTimestamp = msg.timestamp || lastMessageTimestamp;
+                        if (onMessage) onMessage(msg, exit);
+                        if (isClosed) return;
+                        if (shouldCloseAgentRunStream(msg, id)) {
+                            exit(null);
+                            return;
+                        }
+                    }
+                } catch {
+                    // transient poll error — retry next tick
+                }
+                if (isClosed) return;
+                // Exit even when no terminal message ever streams, by reading the run record.
+                try {
+                    const run = (await this.get(`/${id}`)) as { status?: unknown };
+                    if (isTerminalStatus(run?.status)) {
+                        exit(null);
+                        return;
+                    }
+                } catch {
+                    // ignore — retry next tick
+                }
+                if (!isClosed) {
+                    reconnectTimer = setTimeout(() => {
+                        reconnectTimer = null;
+                        void tick();
+                    }, POLL_INTERVAL_MS);
+                }
+            };
+            void tick();
+        };
+
         if (signal) {
             if (signal.aborted) {
                 isClosed = true;
@@ -499,9 +554,7 @@ export class AgentsApi extends ApiTopic {
                             if (!isClosed) void setupStream(true);
                         }, delay);
                     } else {
-                        isClosed = true;
-                        cleanup();
-                        rejectFn(
+                        degradeToPolling(
                             new Error(`SSE connection failed after ${maxReconnectAttempts} reconnection attempts`),
                         );
                     }
@@ -516,9 +569,7 @@ export class AgentsApi extends ApiTopic {
                         if (!isClosed) void setupStream(true);
                     }, delay);
                 } else {
-                    isClosed = true;
-                    cleanup();
-                    rejectFn(err);
+                    degradeToPolling(err);
                 }
             }
         };

package/src/store/AnalyzeDocApi.ts

@@ -1,16 +1,10 @@
-import { ApiTopic, type ClientBase, type IRequestParams } from '@vertesia/api-fetch-client';
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
 import type {
-    AdaptedTable,
-    AdaptTablesRequest,
     DocAnalyzeRunStatusResponse,
-    DocAnalyzerResultResponse,
-    DocImage,
-    DocTableCsv,
-    DocTableJson,
-    ExportTableFormats,
-    GetAdaptedTablesRequestQuery,
-    PdfToRichtextOptions,
-    WorkflowRunStatus,
+    DocumentPrepOptions,
+    GroundedAssistantResponse,
+    GroundedExtractionRequest,
+    GroundedExtractionResultResponse,
 } from '@vertesia/common';
 
 export class AnalyzeDocApi extends ApiTopic {
@@ -21,7 +15,7 @@ export class AnalyzeDocApi extends ApiTopic {
         super(parent, `/${objectId}/analyze`);
     }
 
-    async start(payload: PdfToRichtextOptions): Promise<DocAnalyzeRunStatusResponse> {
+    async start(payload: DocumentPrepOptions): Promise<DocAnalyzeRunStatusResponse> {
         return this.post('/', { payload });
     }
 
@@ -29,51 +23,19 @@ export class AnalyzeDocApi extends ApiTopic {
         return this.get('/status');
     }
 
-    async getResults(): Promise<DocAnalyzerResultResponse> {
-        return this.get('/results');
+    async startGroundedExtraction(payload?: GroundedExtractionRequest): Promise<DocAnalyzeRunStatusResponse> {
+        return this.post('/grounded', { payload: payload ?? {} });
     }
 
-    async adaptTables(payload: AdaptTablesRequest): Promise<WorkflowRunStatus> {
-        return this.post('/adapt_tables', { payload });
+    async getGroundedExtractionResult(): Promise<GroundedExtractionResultResponse> {
+        return this.get('/grounded/result');
     }
 
-    async getAdaptedTables(
-        runId?: string,
-        query?: GetAdaptedTablesRequestQuery,
-    ): Promise<Record<number, AdaptedTable>> {
-        const path = runId ? `/adapt_tables/${runId}` : '/adapt_tables';
-
-        // Build query parameters
-        const queryParams: NonNullable<IRequestParams['query']> = {};
-        if (query?.format) queryParams.format = query.format;
-        if (query?.raw !== undefined) queryParams.raw = query.raw;
-
-        // If format is CSV, set response type to text to avoid automatic JSON parsing
-        const options: IRequestParams & { responseType?: 'text' } = { query: queryParams };
-        if (query?.format === 'csv') {
-            options.responseType = 'text';
-        }
-
-        return this.get(path, options);
-    }
-
-    async getXml(): Promise<string> {
-        return this.get('/xml');
-    }
-
-    async getTables(format?: ExportTableFormats): Promise<DocTableCsv[] | DocTableJson[]> {
-        const options: IRequestParams = {};
-        if (format) {
-            options.query = { format: format };
-        }
-        return this.get('/tables', options);
-    }
-
-    async getImages(): Promise<DocImage[]> {
-        return this.get('/images');
-    }
-
-    async getAnnotated(): Promise<{ url: string }> {
-        return this.get('/annotated');
+    /**
+     * Launch the interactive grounded extraction assistant for this document.
+     * Returns the agent_run_id used to stream/render the conversation.
+     */
+    async startGroundedAssistant(payload?: GroundedExtractionRequest): Promise<GroundedAssistantResponse> {
+        return this.post('/grounded/assistant', { payload: payload ?? {} });
     }
 }

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();
+    });
+});