@vertesia/client 1.5.0-dev.20260725.083715Z → 1.5.0-dev.20260804.124748Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "1.5.0-dev.20260725.083715Z",
+  "version": "1.5.0-dev.20260804.124748Z",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -19,9 +19,9 @@
   },
   "dependencies": {
     "eventsource": "^4.1.0",
-    "@llumiverse/common": "1.5.0-dev.20260725.065646Z",
-    "@vertesia/api-fetch-client": "1.5.0-dev.20260725.083715Z",
-    "@vertesia/common": "1.5.0-dev.20260725.083715Z"
+    "@llumiverse/common": "1.5.0-dev.20260804.122431Z",
+    "@vertesia/common": "1.5.0-dev.20260804.124748Z",
+    "@vertesia/api-fetch-client": "1.5.0-dev.20260804.124748Z"
   },
   "exports": {
     ".": {
@@ -48,7 +48,7 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "57bcc2f27dd17b3387f27c18e89329c4c37f98ac",
+  "gitHead": "87ac9166db2b38bd1be6e37adf0414ea83e402ee",
   "scripts": {
     "lint": "biome lint src",
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",

package/src/AccountApi.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it, vi } from 'vitest';
+import { VertesiaClient } from './client.js';
+
+describe('AccountApi', () => {
+    it('returns onboarding.completed_at as the ISO string received over JSON', async () => {
+        const completedAt = '2026-07-29T10:00:00.000Z';
+        const fetchMock = vi.fn(async () => {
+            return new Response(
+                JSON.stringify({
+                    id: 'account-id',
+                    onboarding: { completed: true, completed_at: completedAt },
+                }),
+                {
+                    status: 200,
+                    headers: { 'content-type': 'application/json' },
+                },
+            );
+        });
+        const client = new VertesiaClient({
+            serverUrl: 'https://api.example.com',
+            storeUrl: 'https://api.example.com',
+            fetch: fetchMock,
+        });
+
+        const account = await client.account.info();
+
+        expect(account.onboarding.completed_at).toBe(completedAt);
+        expect(account.onboarding.completed_at).not.toBeInstanceOf(Date);
+    });
+});

package/src/AccountApi.ts

@@ -9,10 +9,9 @@ import type {
     OnboardingProgress,
     ProjectRef,
     StripeBillingStatusResponse,
-    TransientToken,
     UpdateAccountPayload,
     User,
-    UserInviteTokenData,
+    UserInviteToken,
 } from '@vertesia/common';
 
 export default class AccountApi extends ApiTopic {
@@ -56,17 +55,20 @@ export default class AccountApi extends ApiTopic {
 
     /**
      * Fetch Invites for Principal
-     * @returns UserInviteTokenData[]
-     * */
-    listInvites(): Promise<TransientToken<UserInviteTokenData>[]> {
+     *
+     * Returns `UserInviteToken[]`, not `TransientToken<UserInviteTokenData>[]`. The latter declared
+     * `Date` for `expires`, `created_at` and `updated_at`, which no HTTP response can carry — the
+     * client hands back whatever `JSON.parse` produced, so those three were always strings. It now
+     * says so.
+     */
+    listInvites(): Promise<UserInviteToken[]> {
         return this.get('/invites');
     }
     /**
      * Fetch Invites for specific account or project
      * @param type Filter for the type of invitation, either "project" or "account"
-     * @returns UserInviteTokenData[]
-     * */
-    listInvitation(type: 'project' | 'account' = 'project'): Promise<TransientToken<UserInviteTokenData>[]> {
+     */
+    listInvitation(type: 'project' | 'account' = 'project'): Promise<UserInviteToken[]> {
         return this.get(`/invites/${type}`);
     }
 

package/src/ApiKeysApi.ts

@@ -4,9 +4,10 @@ import type {
     ApiKeyReadResponse,
     ApiKeyWithValue,
     AuthTokenResponse,
-    CreateOrUpdateApiKeyPayload,
+    CreateApiKeyPayload,
     CreatePublicKeyPayload,
     DeleteOperationResult,
+    UpdateApiKeyPayload,
 } from '@vertesia/common';
 
 export class ApiKeysApi extends ApiTopic {
@@ -28,7 +29,7 @@ export class ApiKeysApi extends ApiTopic {
      * ALL REQUESTS ARE LOGGED IN SECURITY AUDIT LOG
      * @returns ApiKeyWithValue
      */
-    create(payload: CreateOrUpdateApiKeyPayload): Promise<ApiKeyWithValue> {
+    create(payload: CreateApiKeyPayload): Promise<ApiKeyWithValue> {
         return this.post('/', { payload });
     }
 
@@ -36,7 +37,7 @@ export class ApiKeysApi extends ApiTopic {
      * Update an existing ApiKey for account
      * @returns ApiKey
      */
-    update(id: string, payload: CreateOrUpdateApiKeyPayload): Promise<ApiKey> {
+    update(id: string, payload: UpdateApiKeyPayload): Promise<ApiKey> {
         return this.put(`/${id}`, { payload });
     }
 

package/src/EnvironmentsApi.ts

@@ -5,11 +5,9 @@ import type {
     EmbeddingsApiResult,
     EnableEnvironmentModelPayload,
     ExecutionEnvironment,
+    ExecutionEnvironmentConfigUpdatePayload,
     ExecutionEnvironmentCreatePayload,
-    ExecutionEnvironmentRef,
     ExecutionEnvironmentUpdatePayload,
-    LoadBalancingEnvConfig,
-    MediatorEnvConfig,
     MigrateInteractionsPayload,
     MigrateInteractionsResult,
 } from '@vertesia/common';
@@ -23,7 +21,7 @@ export default class EnvironmentsApi extends ApiTopic {
      * List all environments for the current project
      * @param all if true, list all environments, otherwise only the ones for the current project
      */
-    list(all: boolean = false): Promise<ExecutionEnvironmentRef[]> {
+    list(all: boolean = false): Promise<ExecutionEnvironment[]> {
         const query = all ? { all: true } : undefined;
 
         return this.get('/', { query });
@@ -54,13 +52,7 @@ export default class EnvironmentsApi extends ApiTopic {
      * @param payload
      * @returns
      */
-    updateConfig(
-        id: string,
-        payload: {
-            enabled_models?: AIModel[];
-            config?: MediatorEnvConfig | LoadBalancingEnvConfig;
-        },
-    ): Promise<ExecutionEnvironment> {
+    updateConfig(id: string, payload: ExecutionEnvironmentConfigUpdatePayload): Promise<ExecutionEnvironment> {
         return this.put(`/${id}/config`, {
             payload,
         });

package/src/GroupsApi.ts

@@ -12,6 +12,8 @@ export interface GroupsQueryOptions {
     tags?: string[];
     limit?: number;
     offset?: number;
+    /** Only return groups usable in this project (org-wide + restricted-to-this-project). */
+    project?: string;
     [key: string]: string | string[] | number | undefined;
 }
 

package/src/OAuthGrantsApi.ts

@@ -5,6 +5,7 @@ import type {
     OAuthGrant,
     OAuthGrantListResponse,
     OAuthGrantRevokeResponse,
+    RevokeOAuthGrantQuery,
 } from '@vertesia/common';
 
 function toQueryRecord(query?: ListOAuthGrantsQuery): Record<string, string> | undefined {
@@ -32,7 +33,7 @@ export default class OAuthGrantsApi extends ApiTopic {
         return this.get(`/${grantId}`);
     }
 
-    revoke(grantId: string, query?: { include_consent?: boolean }): Promise<OAuthGrantRevokeResponse> {
+    revoke(grantId: string, query?: RevokeOAuthGrantQuery): Promise<OAuthGrantRevokeResponse> {
         return this.del(`/${grantId}`, { query });
     }
 

package/src/OAuthProvidersApi.ts

@@ -30,7 +30,12 @@ export default class OAuthProvidersApi extends ApiTopic {
         return this.put(`/${id}`, { payload });
     }
 
-    remove(id: string): Promise<void> {
+    /**
+     * `SuccessResponse`, not `void`: the endpoint has always returned `{ success: true }` and the
+     * document has always published it. Typing it as `void` meant a caller could not read the one
+     * field it sends without casting.
+     */
+    remove(id: string): Promise<SuccessResponse> {
         return this.del(`/${id}`);
     }
 

package/src/PromptsApi.ts

@@ -1,29 +1,28 @@
-import type { PromptRole } from '@llumiverse/common';
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
 import type {
+    ComputedFacetResponse,
     ComputePromptFacetPayload,
     PromptSearchPayload,
     PromptSearchQuery,
     PromptTemplate,
     PromptTemplateCreatePayload,
     PromptTemplateForkPayload,
+    PromptTemplateInteractionsResponse,
     PromptTemplateRef,
     PromptTemplateUpdatePayload,
-    TemplateType,
+    RenderPromptPayload,
+    RenderPromptResponse,
 } from '@vertesia/common';
 
-export interface ComputePromptFacetsResponse {
-    role?: { _id: string; count: number }[];
-    total?: { count: number }[];
-}
+/**
+ * @deprecated Use `ComputedFacetResponse` from `@vertesia/common`, which is what the endpoint
+ * publishes. This restated the facet buckets in their pre-collapse shape: `total` is a number by
+ * the time the response is written, not a one-element array.
+ */
+export type ComputePromptFacetsResponse = ComputedFacetResponse;
 
-export interface PromptRenderResponse {
-    id: string;
-    name: string;
-    role: PromptRole;
-    content_type: TemplateType;
-    rendered: string;
-}
+/** @deprecated Use `RenderPromptResponse` from `@vertesia/common`. */
+export type PromptRenderResponse = RenderPromptResponse;
 
 export default class PromptsApi extends ApiTopic {
     constructor(parent: ClientBase) {
@@ -48,9 +47,9 @@ export default class PromptsApi extends ApiTopic {
     /**
      * Get the list of all prompt facets
      * @param payload query payload to filter facet search
-     * @returns ComputePromptFacetsResponse[]
+     * @returns ComputedFacetResponse
      **/
-    computeFacets(query: ComputePromptFacetPayload): Promise<ComputePromptFacetsResponse> {
+    computeFacets(query: ComputePromptFacetPayload): Promise<ComputedFacetResponse> {
         return this.post('/facets', {
             payload: query,
         });
@@ -125,7 +124,7 @@ export default class PromptsApi extends ApiTopic {
      * @throws 404 if not found
      * @throws 403 if the prompt is not in the current project
      */
-    render(id: string, payload: object): Promise<PromptRenderResponse> {
+    render(id: string, payload: RenderPromptPayload): Promise<RenderPromptResponse> {
         return this.post(`/${id}/render`, {
             payload,
         });
@@ -153,7 +152,7 @@ export default class PromptsApi extends ApiTopic {
     /**
      * Retrieve list of interactions that use the prompt template
      */
-    listInteractions(id: string): Promise<ListInteractionsResponse> {
+    listInteractions(id: string): Promise<PromptTemplateInteractionsResponse> {
         return this.get(`/${id}/interactions`);
     }
 
@@ -167,11 +166,9 @@ export default class PromptsApi extends ApiTopic {
     }
 }
 
-export interface ListInteractionsResponse {
-    prompt: string;
-    interactions: {
-        id: string;
-        name: string;
-        versions: string[];
-    }[];
-}
+/**
+ * @deprecated Use `PromptTemplateInteractionsResponse` from `@vertesia/common`, which is what the
+ * endpoint publishes. This declared `versions: string[]`; the endpoint has always sent
+ * `[{ version: number }]`.
+ */
+export type ListInteractionsResponse = PromptTemplateInteractionsResponse;

package/src/store/AgentsApi.stream.test.ts

@@ -0,0 +1,298 @@
+import { type AgentMessage, AgentMessageType, type CompactMessage } from '@vertesia/common';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { VertesiaClient } from '../client.js';
+
+const AGENT_RUN_ID = 'run-1';
+const STORE_URL = 'https://store.example.test';
+
+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;
+
+    constructor(url: string) {
+        this.url = url;
+        FakeEventSource.urls.push(url);
+        FakeEventSource.instances.push(this);
+    }
+
+    close() {
+        this.readyState = FakeEventSource.CLOSED;
+    }
+
+    addEventListener() {}
+    removeEventListener() {}
+    dispatchEvent() {
+        return true;
+    }
+
+    fail() {
+        this.onerror?.(new Event('error'));
+    }
+
+    emit(message: CompactMessage) {
+        this.onmessage?.({ data: JSON.stringify(message) } as MessageEvent);
+    }
+}
+
+interface Harness {
+    client: VertesiaClient;
+    /** `since` query value of every GET /updates call after the initial history fetch. */
+    pollSince: number[];
+    setHistory: (messages: CompactMessage[]) => void;
+    setPollResponse: (handler: (since: number) => CompactMessage[]) => void;
+    setRunStatus: (status: string) => void;
+    issuedTokens: string[];
+}
+
+function createHarness(): Harness {
+    let history: CompactMessage[] = [];
+    let pollResponse: (since: number) => CompactMessage[] = () => [];
+    let runStatus = 'running';
+    let historyServed = false;
+    const pollSince: number[] = [];
+    const issuedTokens: string[] = [];
+
+    const fetchMock = vi.fn(async (input: Request | string) => {
+        const url = new URL(typeof input === 'string' ? input : input.url);
+        if (url.pathname.endsWith('/updates')) {
+            if (!historyServed) {
+                historyServed = true;
+                return Response.json({ messages: history });
+            }
+            const since = Number(url.searchParams.get('since') ?? 0);
+            pollSince.push(since);
+            return Response.json({ messages: pollResponse(since) });
+        }
+        if (url.pathname.endsWith(`/${AGENT_RUN_ID}`)) {
+            return Response.json({ id: AGENT_RUN_ID, status: runStatus });
+        }
+        return Response.json({ error: 'not found' }, { status: 404 });
+    });
+
+    const client = new VertesiaClient({
+        serverUrl: 'https://studio.example.test',
+        storeUrl: STORE_URL,
+        fetch: fetchMock as unknown as typeof fetch,
+    });
+
+    // Mimics a refreshing credential provider: every call hands out a newer token.
+    client.withAuthCallback(async () => {
+        const token = `token-${issuedTokens.length + 1}`;
+        issuedTokens.push(token);
+        return `Bearer ${token}`;
+    });
+
+    return {
+        client,
+        pollSince,
+        issuedTokens,
+        setHistory: (messages) => {
+            history = messages;
+        },
+        setPollResponse: (handler) => {
+            pollResponse = handler;
+        },
+        setRunStatus: (status) => {
+            runStatus = status;
+        },
+    };
+}
+
+/** Advance fake timers and drain the microtask queue so awaited fetches settle. */
+async function settle(ms = 0) {
+    await vi.advanceTimersByTimeAsync(ms);
+    for (let i = 0; i < 20; i++) {
+        await Promise.resolve();
+    }
+}
+
+/** Longer than the capped backoff delay (30s + jitter). */
+const BACKOFF_CEILING_MS = 40000;
+
+async function failCurrentConnection() {
+    FakeEventSource.instances[FakeEventSource.instances.length - 1].fail();
+    await settle(BACKOFF_CEILING_MS);
+}
+
+describe('AgentsApi.streamMessages reconnection', () => {
+    let logs: string[];
+    let warnings: string[];
+
+    beforeEach(() => {
+        vi.useFakeTimers();
+        FakeEventSource.instances = [];
+        FakeEventSource.urls = [];
+        logs = [];
+        warnings = [];
+        vi.stubGlobal('EventSource', FakeEventSource);
+        vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => {
+            logs.push(args.map(String).join(' '));
+        });
+        vi.spyOn(console, 'warn').mockImplementation((...args: unknown[]) => {
+            warnings.push(args.map(String).join(' '));
+        });
+        vi.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+
+    it('resolves a fresh auth token for every reconnection attempt', async () => {
+        const harness = createHarness();
+        const abort = new AbortController();
+        void harness.client.agents.streamMessages(AGENT_RUN_ID, undefined, undefined, abort.signal);
+        await settle();
+
+        expect(FakeEventSource.instances).toHaveLength(1);
+        await failCurrentConnection();
+        await failCurrentConnection();
+        expect(FakeEventSource.instances).toHaveLength(3);
+
+        const tokens = FakeEventSource.urls.map((url) => new URL(url).searchParams.get('access_token'));
+        expect(tokens).toHaveLength(3);
+        expect(new Set(tokens).size).toBe(3);
+        expect(tokens.every((token) => token?.startsWith('token-'))).toBe(true);
+
+        abort.abort();
+        await settle();
+    });
+
+    it('never announces an attempt number above the stated maximum', async () => {
+        const harness = createHarness();
+        const abort = new AbortController();
+        void harness.client.agents.streamMessages(AGENT_RUN_ID, undefined, undefined, abort.signal);
+        await settle();
+
+        // 10 reconnects are allowed; the 11th failure must degrade instead of announcing 11/10.
+        for (let i = 0; i < 11; i++) {
+            await failCurrentConnection();
+        }
+
+        const announced = logs
+            .map((line) => /\(attempt (\d+)\/(\d+)\)/.exec(line))
+            .filter((match): match is RegExpExecArray => match !== null)
+            .map((match) => ({ attempt: Number(match[1]), max: Number(match[2]) }));
+
+        expect(announced).toHaveLength(10);
+        expect(announced.map((entry) => entry.attempt)).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+        expect(announced.every((entry) => entry.attempt <= entry.max)).toBe(true);
+        expect(FakeEventSource.instances).toHaveLength(11);
+        expect(warnings.some((line) => line.includes('SSE unavailable after 10 attempts'))).toBe(true);
+
+        abort.abort();
+        await settle();
+    });
+
+    it('polls GET /updates from the last received timestamp and emits the messages', async () => {
+        const harness = createHarness();
+        harness.setHistory([{ t: AgentMessageType.UPDATE, m: 'history', ts: 1000 }]);
+        harness.setPollResponse((since) =>
+            since < 2000 ? [{ t: AgentMessageType.UPDATE, m: 'polled', ts: 2000 }] : [],
+        );
+
+        const received: AgentMessage[] = [];
+        const abort = new AbortController();
+        void harness.client.agents.streamMessages(
+            AGENT_RUN_ID,
+            (message) => received.push(message),
+            undefined,
+            abort.signal,
+        );
+        await settle();
+
+        for (let i = 0; i < 11; i++) {
+            await failCurrentConnection();
+        }
+        await settle(6000);
+
+        // The first poll resumes at the history cursor, later polls at the last polled message.
+        expect(harness.pollSince[0]).toBe(1000);
+        expect(harness.pollSince[1]).toBe(2000);
+        expect(received.map((message) => message.message)).toEqual(['history', 'polled']);
+        // Polled messages reach the caller as fully-formed AgentMessages, like the SSE path.
+        expect(received[1]).toMatchObject({
+            type: AgentMessageType.UPDATE,
+            workflow_run_id: AGENT_RUN_ID,
+            workstream_id: 'main',
+            timestamp: 2000,
+        });
+
+        abort.abort();
+        await settle();
+    });
+
+    it('warns on every polling failure instead of failing silently', async () => {
+        const harness = createHarness();
+        harness.setHistory([{ t: AgentMessageType.UPDATE, m: 'history', ts: 1000 }]);
+        harness.setPollResponse(() => {
+            throw new Error('boom');
+        });
+
+        const abort = new AbortController();
+        void 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);
+
+        const pollWarnings = warnings.filter((line) => line.includes('GET /updates failed while polling'));
+        expect(pollWarnings.length).toBeGreaterThanOrEqual(2);
+        expect(pollWarnings[0]).toContain('consecutive failures: 1');
+        expect(pollWarnings[1]).toContain('consecutive failures: 2');
+
+        abort.abort();
+        await settle();
+    });
+
+    it('retries SSE after the polling fallback so an outage is not permanent', async () => {
+        const harness = createHarness();
+        const abort = new AbortController();
+        void harness.client.agents.streamMessages(AGENT_RUN_ID, undefined, undefined, abort.signal);
+        await settle();
+
+        for (let i = 0; i < 11; i++) {
+            await failCurrentConnection();
+        }
+        const connectionsBeforeRetry = FakeEventSource.instances.length;
+        expect(warnings.some((line) => line.includes('SSE retried every 60s'))).toBe(true);
+
+        await settle(61000);
+
+        expect(FakeEventSource.instances.length).toBe(connectionsBeforeRetry + 1);
+        expect(logs.some((line) => line.includes('retrying the SSE connection'))).toBe(true);
+
+        abort.abort();
+        await settle();
+    });
+
+    it('closes the stream when polling observes a terminal run status', async () => {
+        const harness = createHarness();
+        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();
+        }
+        harness.setRunStatus('completed');
+        await settle(6000);
+
+        await expect(done).resolves.toBeNull();
+    });
+});