@vertesia/client 1.6.0-dev.20260923.085325Z → 1.6.0-dev.20261004.085740Z

package/src/client.test.ts

@@ -1,332 +0,0 @@
-import { APP_VERSION_HEADER } from '@vertesia/common';
-import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
-import { decodeJWT, isTokenExpired, VertesiaClient, type VertesiaClientProps } from './client.js';
-import { ZenoClient, type ZenoClientProps } from './store/client.js';
-import { resetUnknownOptionWarnings } from './unknown-options.js';
-
-describe('Test Vertesia Client', () => {
-    test('Initialization with studio and zeno URLs', () => {
-        const client = new VertesiaClient({
-            serverUrl: 'https://api.vertesia.io',
-            storeUrl: 'https://api.vertesia.io',
-            tokenServerUrl: 'https://sts.vertesia.io',
-            apikey: '1234',
-        });
-        expect(client).toBeDefined();
-    });
-
-    test('Initialization with studio URL only', () => {
-        expect(() => {
-            new VertesiaClient({
-                serverUrl: 'https://api.vertesia.io',
-                storeUrl: '',
-            });
-        }).toThrowError("Parameter 'site' or 'storeUrl' is required for VertesiaClient");
-    });
-
-    test('Initialization with zeno URL only', () => {
-        expect(() => {
-            new VertesiaClient({
-                serverUrl: '',
-                storeUrl: 'https://api.vertesia.io',
-            });
-        }).toThrowError("Parameter 'site' or 'serverUrl' is required for VertesiaClient");
-    });
-
-    test('Initialization with same site', () => {
-        const client = new VertesiaClient({
-            serverUrl: 'https://api.vertesia.io',
-            storeUrl: 'https://api.vertesia.io',
-            site: 'api.vertesia.io',
-        });
-
-        expect(client).toBeDefined();
-        expect(client.baseUrl).toBe('https://api.vertesia.io');
-        expect(client.storeUrl).toBe('https://api.vertesia.io');
-    });
-
-    test('Initialization with default parameters', () => {
-        const client = new VertesiaClient();
-
-        expect(client).toBeDefined();
-        expect(client.baseUrl).toBe('https://api.vertesia.io');
-        expect(client.storeUrl).toBe('https://api.vertesia.io');
-        expect(client.tokenServerUrl).toBe('https://sts.vertesia.io');
-    });
-
-    test('Initialization with site api-preview.vertesia.io', () => {
-        const client = new VertesiaClient({
-            site: 'api-preview.vertesia.io',
-        });
-
-        expect(client).toBeDefined();
-        expect(client.baseUrl).toBe('https://api-preview.vertesia.io');
-        expect(client.storeUrl).toBe('https://api-preview.vertesia.io');
-        // preview keeps its env segment: api-preview → sts-preview (its own STS)
-        expect(client.tokenServerUrl).toBe('https://sts-preview.vertesia.io');
-    });
-
-    test('Initialization with site api.dev1.vertesia.io', () => {
-        const client = new VertesiaClient({
-            site: 'api.dev1.vertesia.io',
-        });
-
-        expect(client).toBeDefined();
-        expect(client.baseUrl).toBe('https://api.dev1.vertesia.io');
-        expect(client.storeUrl).toBe('https://api.dev1.vertesia.io');
-        expect(client.tokenServerUrl).toBe('https://sts.dev1.vertesia.io');
-    });
-
-    test('Initialization with site api-preview.dev1.vertesia.io', () => {
-        const client = new VertesiaClient({
-            site: 'api-preview.dev1.vertesia.io',
-        });
-
-        expect(client).toBeDefined();
-        expect(client.baseUrl).toBe('https://api-preview.dev1.vertesia.io');
-        expect(client.storeUrl).toBe('https://api-preview.dev1.vertesia.io');
-        // preview keeps its env segment: api-preview → sts-preview (its own STS)
-        expect(client.tokenServerUrl).toBe('https://sts-preview.dev1.vertesia.io');
-    });
-
-    test('Initialization with regional serverUrl (api.us1)', () => {
-        const client = new VertesiaClient({
-            serverUrl: 'https://api.us1.vertesia.io',
-            storeUrl: 'https://api.us1.vertesia.io',
-        });
-
-        expect(client).toBeDefined();
-        expect(client.baseUrl).toBe('https://api.us1.vertesia.io');
-        expect(client.storeUrl).toBe('https://api.us1.vertesia.io');
-        expect(client.tokenServerUrl).toBe('https://sts.us1.vertesia.io');
-    });
-
-    test('Initialization with regional serverUrl (api.eu1)', () => {
-        const client = new VertesiaClient({
-            serverUrl: 'https://api.eu1.vertesia.io',
-            storeUrl: 'https://api.eu1.vertesia.io',
-        });
-
-        expect(client).toBeDefined();
-        expect(client.baseUrl).toBe('https://api.eu1.vertesia.io');
-        expect(client.storeUrl).toBe('https://api.eu1.vertesia.io');
-        expect(client.tokenServerUrl).toBe('https://sts.eu1.vertesia.io');
-    });
-
-    test('Initialization with regional preview serverUrl (api-preview.us1)', () => {
-        const client = new VertesiaClient({
-            serverUrl: 'https://api-preview.us1.vertesia.io',
-            storeUrl: 'https://api-preview.us1.vertesia.io',
-        });
-
-        expect(client).toBeDefined();
-        expect(client.baseUrl).toBe('https://api-preview.us1.vertesia.io');
-        // preview keeps its env segment: api-preview → sts-preview (its own versioned STS)
-        expect(client.tokenServerUrl).toBe('https://sts-preview.us1.vertesia.io');
-    });
-
-    test('Initialization with site localhost', () => {
-        const client = new VertesiaClient({
-            serverUrl: 'http://localhost:8091',
-            storeUrl: 'http://localhost:8092',
-            tokenServerUrl: 'http://localhost:8093',
-        });
-
-        expect(client).toBeDefined();
-        expect(client.baseUrl).toBe('http://localhost:8091');
-        expect(client.storeUrl).toBe('http://localhost:8092');
-    });
-
-    test('Initialization with overrides', () => {
-        const client = new VertesiaClient({
-            serverUrl: 'https://studio-server-production.api.becomposable.com',
-            storeUrl: 'https://zeno-server-production.api.becomposable.com',
-            site: 'api.vertesia.io',
-        });
-
-        expect(client).toBeDefined();
-        expect(client.baseUrl).toBe('https://studio-server-production.api.becomposable.com');
-        expect(client.storeUrl).toBe('https://zeno-server-production.api.becomposable.com');
-    });
-
-    test('withAppVersion keeps Studio and Store requests pinned together', () => {
-        const client = new VertesiaClient({
-            serverUrl: 'https://studio-server-production.api.becomposable.com',
-            storeUrl: 'https://zeno-server-production.api.becomposable.com',
-        });
-
-        expect(client.withAppVersion('candidate-v1')).toBe(client);
-        expect(client.headers[APP_VERSION_HEADER]).toBe('candidate-v1');
-        expect(client.store.headers[APP_VERSION_HEADER]).toBe('candidate-v1');
-
-        client.withAppVersion(null);
-        expect(client.headers[APP_VERSION_HEADER]).toBeUndefined();
-        expect(client.store.headers[APP_VERSION_HEADER]).toBeUndefined();
-    });
-});
-
-describe('isTokenExpired', () => {
-    // EXPIRATION_THRESHOLD inside client.ts is 60000ms (60s). Tokens with `exp`
-    // less than 60s in the future are treated as expired so the caller refreshes
-    // proactively.
-    const REFRESH_WINDOW_MS = 60_000;
-    const NOW_MS = 1_700_000_000_000;
-
-    function base64UrlEncode(s: string): string {
-        return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-    }
-
-    function makeToken(exp: number): string {
-        const header = base64UrlEncode(JSON.stringify({ alg: 'none', typ: 'JWT' }));
-        const payload = base64UrlEncode(JSON.stringify({ exp }));
-        return `${header}.${payload}.signature`;
-    }
-
-    beforeEach(() => {
-        vi.useFakeTimers();
-        vi.setSystemTime(new Date(NOW_MS));
-    });
-
-    afterEach(() => {
-        vi.useRealTimers();
-    });
-
-    test('returns true for a null token', () => {
-        expect(isTokenExpired(null)).toBe(true);
-    });
-
-    test('returns false for a fresh token comfortably inside its lifetime', () => {
-        // 1 hour in the future
-        const exp = Math.floor(NOW_MS / 1000) + 3600;
-        expect(isTokenExpired(makeToken(exp))).toBe(false);
-    });
-
-    test('returns true when the token is within the refresh threshold of expiry', () => {
-        // 30s in the future — inside the 60s refresh window
-        const exp = Math.floor((NOW_MS + 30_000) / 1000);
-        expect(isTokenExpired(makeToken(exp))).toBe(true);
-    });
-
-    test('returns true for a token whose exp is already in the past', () => {
-        // expired 100s ago
-        const exp = Math.floor((NOW_MS - 100_000) / 1000);
-        expect(isTokenExpired(makeToken(exp))).toBe(true);
-    });
-
-    test('returns true exactly at the refresh-window boundary', () => {
-        // exp is exactly REFRESH_WINDOW_MS in the future — should already trigger refresh
-        const exp = Math.floor((NOW_MS + REFRESH_WINDOW_MS) / 1000);
-        expect(isTokenExpired(makeToken(exp))).toBe(true);
-    });
-});
-
-describe('unknown constructor options', () => {
-    // Model the real escape hatch rather than a cast: TypeScript's excess-property check only fires
-    // on an object literal, so a spread of a wider config object reaches the constructor unchecked.
-    function optionsWith(extra: Record<string, unknown>): VertesiaClientProps {
-        return {
-            serverUrl: 'https://api.vertesia.io',
-            storeUrl: 'https://api.vertesia.io',
-            ...extra,
-        } as VertesiaClientProps;
-    }
-
-    beforeEach(() => {
-        resetUnknownOptionWarnings();
-    });
-
-    afterEach(() => {
-        vi.restoreAllMocks();
-    });
-
-    // The option names below are deliberately spelled the way the SDK does NOT accept them. Passing
-    // them used to produce a client that looked fine and then failed every request with
-    // `401 Unauthorized: Authorization token is required`, with nothing pointing at the constructor.
-    test('names the option and what the caller meant', () => {
-        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-
-        new VertesiaClient(optionsWith({ token: 'jwt' }));
-
-        expect(warn).toHaveBeenCalledTimes(1);
-        const message = warn.mock.calls[0][0] as string;
-        expect(message).toContain('[VertesiaClient]');
-        expect(message).toContain('token');
-        expect(message).toContain('`apikey`');
-    });
-
-    test('reports each unknown option once, not once per client', () => {
-        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-        const opts = optionsWith({ appVersion: 'v1' });
-
-        new VertesiaClient(opts);
-        new VertesiaClient(opts);
-
-        expect(warn).toHaveBeenCalledTimes(1);
-        expect(warn.mock.calls[0][0]).toContain('withAppVersion');
-    });
-
-    test('stays silent for a fully valid options object', () => {
-        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-
-        new VertesiaClient({
-            serverUrl: 'https://api.vertesia.io',
-            storeUrl: 'https://api.vertesia.io',
-            tokenServerUrl: 'https://sts.vertesia.io',
-            apikey: 'sk-1234',
-            sessionTags: 'test',
-            timeout: 1000,
-        });
-
-        expect(warn).not.toHaveBeenCalled();
-    });
-
-    // `key in known` would treat these as known options, because every object inherits them.
-    test.each(['toString', 'constructor', 'valueOf', 'hasOwnProperty'])(
-        'reports %s, which is inherited from Object.prototype',
-        (key) => {
-            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-
-            new VertesiaClient(optionsWith({ [key]: 'whatever' }));
-
-            expect(warn).toHaveBeenCalledTimes(1);
-            expect(warn.mock.calls[0][0]).toContain(key);
-        },
-    );
-
-    test('covers the store client too', () => {
-        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-
-        new ZenoClient({
-            serverUrl: 'https://api.vertesia.io',
-            ...{ apiKey: 'sk-1234' },
-        } as ZenoClientProps);
-
-        expect(warn).toHaveBeenCalledTimes(1);
-        expect(warn.mock.calls[0][0]).toContain('[ZenoClient]');
-        expect(warn.mock.calls[0][0]).toContain('apikey');
-    });
-});
-
-describe('decodeJWT', () => {
-    // An empty or non-JWT credential used to reach `''.split('.')[1]` and die inside the base64
-    // decoder with a TypeError naming neither the token nor the caller.
-    test.each([
-        ['an empty string', ''],
-        ['an API key', 'sk-abcdef'],
-        ['a two-segment string', 'header.payload'],
-    ])('names the failure for %s', (_label, value) => {
-        expect(() => decodeJWT(value)).toThrowError(/Invalid auth token: expected a JWT/);
-    });
-
-    test('names a payload that is not JSON', () => {
-        expect(() => decodeJWT('aGVhZGVy.bm90LWpzb24.sig')).toThrowError(
-            'Invalid auth token: payload segment is not JSON',
-        );
-    });
-
-    test('rejects an empty token before decoding it', async () => {
-        await expect(VertesiaClient.fromAuthToken('   ')).rejects.toThrowError(
-            'VertesiaClient.fromAuthToken requires a non-empty auth token',
-        );
-    });
-});

package/src/execute.test.ts

@@ -1,22 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import type { VertesiaClient } from './client.js';
-import { executeInteractionByName } from './execute.js';
-
-describe('executeInteractionByName', () => {
-    it('forwards private per-request headers without placing them in the execution payload', async () => {
-        const post = vi.fn().mockResolvedValue({ id: 'run-1', status: 'completed' });
-        const client = { post } as unknown as VertesiaClient;
-
-        await executeInteractionByName(client, 'sys:test', { data: { message: 'hello' } }, undefined, {
-            headers: { 'x-vertesia-required-tool-name': 'app_workspace_init' },
-        });
-
-        expect(post).toHaveBeenCalledWith(
-            '/api/v1/execute',
-            expect.objectContaining({
-                headers: { 'x-vertesia-required-tool-name': 'app_workspace_init' },
-                payload: expect.not.objectContaining({ required_tool_name: expect.anything() }),
-            }),
-        );
-    });
-});

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

@@ -1,119 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { escapeArtifactPathDelimiters } from './AgentsApi.js';
-import { ZenoClient } from './client.js';
-
-const SERVER_URL = 'https://store.test';
-const RUN_ID = 'run-1';
-
-/**
- * A client whose injected fetch records the URL of every request it is handed. The URL is read off
- * the Request object, so the assertions see the path after WHATWG URL parsing — which is where an
- * unescaped `#` was being dropped.
- */
-function clientRecordingUrls(body: unknown = { url: 'https://signed', path: 'p' }) {
-    const urls: string[] = [];
-    const client = new ZenoClient({
-        serverUrl: SERVER_URL,
-        apikey: 'token',
-        fetch: async (input: RequestInfo) => {
-            urls.push(input instanceof Request ? input.url : String(input));
-            return new Response(JSON.stringify(body), {
-                status: 200,
-                headers: { 'content-type': 'application/json' },
-            });
-        },
-    });
-    return { client, urls };
-}
-
-/** The artifact path the server reconstructs: the URL path after the route prefix, decoded per segment. */
-function serverPath(url: string, prefix: string): string {
-    const tail = new URL(url).pathname.split(`/${prefix}/`)[1] ?? '';
-    return tail.split('/').map(decodeURIComponent).join('/');
-}
-
-describe('escapeArtifactPathDelimiters', () => {
-    it('escapes the two characters that truncate a path', () => {
-        expect(escapeArtifactPathDelimiters('files/tpl (YYYY-0#).docx')).toBe('files/tpl (YYYY-0%23).docx');
-        expect(escapeArtifactPathDelimiters('files/report?v2.docx')).toBe('files/report%3Fv2.docx');
-    });
-
-    // Scope guard. Anything this helper touches changes the bytes on the wire for filenames that
-    // work today, so it must leave everything except `#` and `?` exactly as it found it.
-    it.each([
-        ['percent', 'files/100% done.docx'],
-        ['spaces', 'files/MHA - Client IQ FSD.docx'],
-        ['non-ascii and accents', 'files/café résumé.docx'],
-        ['backslash', 'files/back\\slash.docx'],
-        ['segment separators', 'files/nested/a b.txt'],
-        ['already-encoded sequence', 'files/report%23.md'],
-    ])('leaves %s untouched', (_label, path) => {
-        expect(escapeArtifactPathDelimiters(path)).toBe(path);
-    });
-});
-
-describe('AgentsApi artifact paths', () => {
-    afterEach(() => {
-        vi.restoreAllMocks();
-        vi.unstubAllGlobals();
-    });
-
-    // A `#` in an uploaded filename used to be parsed as the URL fragment, so the server saw a
-    // truncated path and stored the object under a key nothing could read back.
-    it('uploadArtifact preserves a path containing #', async () => {
-        vi.stubGlobal(
-            'fetch',
-            vi.fn(async () => new Response(null, { status: 200 })),
-        );
-        const { client, urls } = clientRecordingUrls();
-        const path = 'files/Design Template (YYYY-0#).docx';
-
-        await client.agents.uploadArtifact(RUN_ID, path, 'content');
-
-        expect(urls).toHaveLength(1);
-        expect(urls[0]).not.toContain('#');
-        expect(serverPath(urls[0], 'artifacts')).toBe(path);
-    });
-
-    // The query is concatenated onto the path, so an unescaped delimiter took it down too.
-    it.each([
-        ['hash', 'files/Design (YYYY-0#).docx'],
-        ['question mark', 'files/report?v2.docx'],
-    ])('getArtifactUrl round-trips %s and keeps the query intact', async (_label, path) => {
-        const { client, urls } = clientRecordingUrls();
-
-        await client.agents.getArtifactUrl(RUN_ID, path, 'attachment', 'download-name.docx');
-
-        const url = new URL(urls[0]);
-        expect(serverPath(urls[0], 'artifacts')).toBe(path);
-        expect(url.hash).toBe('');
-        expect(url.searchParams.get('url')).toBe('1');
-        expect(url.searchParams.get('disposition')).toBe('attachment');
-        expect(url.searchParams.get('filename')).toBe('download-name.docx');
-    });
-
-    // Pins the scope boundary: `%` must go on the wire exactly as it does with no escaping at all.
-    it('sends a path containing % exactly as it did before, unescaped', async () => {
-        const { client, urls } = clientRecordingUrls();
-        const path = 'files/100% done.docx';
-
-        await client.agents.getArtifactUrl(RUN_ID, path);
-
-        const unescaped = new URL(`${SERVER_URL}/api/v1/agents/${RUN_ID}/artifacts/${path}?url=1`);
-        expect(new URL(urls[0]).pathname).toBe(unescaped.pathname);
-        expect(new URL(urls[0]).pathname).toContain('100%%20done.docx');
-    });
-
-    it('getArtifactContent and updateArtifactContent preserve a path containing #', async () => {
-        const { client, urls } = clientRecordingUrls({ content: '', generation: '1' });
-        const path = 'files/notes (v0#1).md';
-
-        await client.agents.getArtifactContent(RUN_ID, path);
-        await client.agents.updateArtifactContent(RUN_ID, path, { content: 'x', generation: '1' });
-
-        expect(urls).toHaveLength(2);
-        for (const url of urls) {
-            expect(serverPath(url, 'artifact-content')).toBe(path);
-        }
-    });
-});

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

@@ -1,29 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { VertesiaClient } from '../client.js';
-
-describe('agent history cursor transport', () => {
-    it('passes the cursor and response metadata through for main and child details', async () => {
-        const urls: URL[] = [];
-        const response = { history: { type: 'agent', mode: 'delta', next_from: 'next', agentTasks: [] } };
-        const client = new VertesiaClient({
-            serverUrl: 'https://studio.test',
-            storeUrl: 'https://store.test',
-            fetch: (async (input: Request | string) => {
-                urls.push(new URL(typeof input === 'string' ? input : input.url));
-                return Response.json(response);
-            }) as typeof fetch,
-        });
-        const options = { includeHistory: true, hydratePayloads: true, from: 'opaque/+=' };
-        expect(await client.agents.getRunDetails('agent', options)).toEqual(response);
-        expect(await client.agents.getChildDetails('agent', 'child', options)).toEqual(response);
-        expect(urls.map((url) => url.pathname)).toEqual([
-            '/api/v1/agents/agent/details',
-            '/api/v1/agents/agent/children/child/details',
-        ]);
-        for (const url of urls) {
-            expect(url.searchParams.get('from')).toBe(options.from);
-            expect(url.searchParams.get('include_history')).toBe('true');
-            expect(url.searchParams.get('hydrate_payloads')).toBe('true');
-        }
-    });
-});