@vertesia/client 1.2.0 → 1.3.0-dev.20260620.091720Z

package/src/SkillsApi.ts

@@ -1,9 +1,5 @@
-import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
-import {
-    FindRelevantSkillsPayload,
-    InjectedSkill,
-    SkillContext,
-} from "@vertesia/common";
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type { FindRelevantSkillsPayload, InjectedSkill, SkillContext } from '@vertesia/common';
 
 /**
  * API client for skill operations.
@@ -13,7 +9,7 @@ import {
  */
 export default class SkillsApi extends ApiTopic {
     constructor(parent: ClientBase) {
-        super(parent, "/api/v1/skills");
+        super(parent, '/api/v1/skills');
     }
 
     /**
@@ -25,7 +21,7 @@ export default class SkillsApi extends ApiTopic {
      */
     findRelevant(context: SkillContext, limit?: number): Promise<InjectedSkill[]> {
         const payload: FindRelevantSkillsPayload = { context, limit };
-        return this.post("/find-relevant", { payload });
+        return this.post('/find-relevant', { payload });
     }
 
     /**
@@ -34,10 +30,7 @@ export default class SkillsApi extends ApiTopic {
      * @param toolNames Optional list of tools being used
      * @returns Array of injected skills
      */
-    findRelevantForTask(
-        taskDescription: string,
-        toolNames?: string[]
-    ): Promise<InjectedSkill[]> {
+    findRelevantForTask(taskDescription: string, toolNames?: string[]): Promise<InjectedSkill[]> {
         return this.findRelevant({
             task_description: taskDescription,
             tool_names: toolNames,

package/src/StreamSource.ts

@@ -1,3 +1,8 @@
 export class StreamSource {
-    constructor(public stream: ReadableStream, public name: string, public type?: string, public id?: string) { }
+    constructor(
+        public stream: ReadableStream,
+        public name: string,
+        public type?: string,
+        public id?: string,
+    ) {}
 }

package/src/ToolsApi.ts

@@ -0,0 +1,52 @@
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type {
+    AggregatedTool,
+    ListProjectToolsQuery,
+    ValidateToolNamesPayload,
+    ValidateToolNamesResponse,
+} from '@vertesia/common';
+
+/**
+ * Project-scoped unified tool registry.
+ *
+ * Wraps:
+ *  - `GET  /api/v1/tools`         — list every tool visible to the current principal across all sources
+ *  - `POST /api/v1/tools/validate` — resolve a list of names against the same registry
+ *
+ * Note: this is distinct from `client.store.tools` (the static builtin catalog exposed by zeno-server)
+ * — that one is global and source-incomplete (no app/interaction tools). Use this client for anything
+ * project-aware.
+ */
+export default class ToolsApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, '/api/v1/tools');
+    }
+
+    /**
+     * List the project's unified tool registry as seen by the current principal.
+     * Use `sources` for an allowlist or `exclude` for a denylist. Excluded sources
+     * are not fetched, so denylisting `'app'` skips the per-installation HTTP calls.
+     *
+     * **Interactive UI consumers should prefer `{ exclude: ['app'] }`** and fetch
+     * app tools directly via `client.apps.getInstalledApps()` + per-app
+     * `client.apps.listAppInstallationTools(id)`. Reason: app tools require N
+     * per-installation HTTP fetches; doing them browser-side keeps studio-server's
+     * fetch budget free, lets one slow app fail in isolation, and exploits browser
+     * parallelism. Server-side aggregation of the `app` source is intended for
+     * one-shot consumers (validation, CLI, agent tools) — not hot UI paths.
+     */
+    list(query?: ListProjectToolsQuery): Promise<AggregatedTool[]> {
+        const params: Record<string, string> = {};
+        if (query?.sources?.length) params.sources = query.sources.join(',');
+        if (query?.exclude?.length) params.exclude = query.exclude.join(',');
+        return this.get('/', { query: Object.keys(params).length > 0 ? params : undefined });
+    }
+
+    /**
+     * Validate a list of tool names. Each result reports validity, source, app provenance,
+     * and (for invalid names) a closest-match suggestion.
+     */
+    validate(names: string[]): Promise<ValidateToolNamesResponse> {
+        return this.post('/validate', { payload: { names } satisfies ValidateToolNamesPayload });
+    }
+}

package/src/TrainingApi.ts

@@ -1,57 +1,60 @@
-import type { TrainingJob } from "@llumiverse/common";
-import { ExecutionRunRef, ListTrainingSessionsQuery, TrainingSession, TrainingSessionCreatePayload, TrainingSessionRef } from "@vertesia/common";
-import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
-
+import type { TrainingJob } from '@llumiverse/common';
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type {
+    ExecutionRunRef,
+    ListTrainingSessionsQuery,
+    TrainingSession,
+    TrainingSessionCreatePayload,
+    TrainingSessionRef,
+} from '@vertesia/common';
 
 export default class TrainingApi extends ApiTopic {
-
     constructor(parent: ClientBase) {
-        super(parent, "/api/v1/training")
+        super(parent, '/api/v1/training');
     }
 
     listSessions(query: ListTrainingSessionsQuery = {}): Promise<TrainingSessionRef[]> {
-        return this.get('/', { query: query as any });
+        return this.get('/', { query: { ...query } });
     }
 
-    listSessionNames(query: ListTrainingSessionsQuery = {}): Promise<{ id: string, name: string }[]> {
-        return this.get('/names', { query: query as any });
+    listSessionNames(query: ListTrainingSessionsQuery = {}): Promise<{ id: string; name: string }[]> {
+        return this.get('/names', { query: { ...query } });
     }
 
     createSession(payload: TrainingSessionCreatePayload): Promise<TrainingSession> {
-        return this.post('/', { payload })
+        return this.post('/', { payload });
     }
 
     getSession(sessionId: string): Promise<TrainingSession> {
-        return this.get('/' + sessionId)
+        return this.get(`/${sessionId}`);
     }
 
-    addToSession(sessionId: string, runs: string[]): Promise<any> {
-        return this.post('/' + sessionId + '/add', { payload: { runs } })
+    addToSession(sessionId: string, runs: string[]): Promise<unknown> {
+        return this.post(`/${sessionId}/add`, { payload: { runs } });
     }
 
     listSessionRuns(sessionId: string, limit = 100, offset = 0): Promise<ExecutionRunRef[]> {
-        return this.get('/' + sessionId + '/runs', { query: { limit, offset } });
+        return this.get(`/${sessionId}/runs`, { query: { limit, offset } });
     }
 
     buildSession(sessionId: string) {
-        return this.post('/' + sessionId + '/build');
+        return this.post(`/${sessionId}/build`);
     }
 
     getDataUrl(sessionId: string): Promise<{ url: string }> {
-        return this.get('/' + sessionId + '/url')
+        return this.get(`/${sessionId}/url`);
     }
 
     getDataUploadUrl(sessionId: string, isResumable = false): Promise<{ url: string }> {
-        return this.get('/' + sessionId + '/upload-url',
-            isResumable ? { query: { resumable: 'true' } } : {})
+        return this.get(`/${sessionId}/upload-url`, isResumable ? { query: { resumable: 'true' } } : {});
     }
 
     startTraining(sessionId: string): Promise<TrainingJob> {
-        return this.post('/' + sessionId + '/start');
+        return this.post(`/${sessionId}/start`);
     }
 
     cancelTraining(sessionId: string): Promise<TrainingJob> {
-        return this.post('/' + sessionId + '/cancel');
+        return this.post(`/${sessionId}/cancel`);
     }
 
     getTrainingJob(jobId: string): Promise<TrainingJob> {
@@ -60,12 +63,11 @@ export default class TrainingApi extends ApiTopic {
 
     getAndSyncTrainingJob(jobId: string): Promise<TrainingJob> {
         return this.get(`/job/${jobId}`, {
-            query: { sync: 'true' }
+            query: { sync: 'true' },
         });
     }
 
-    setDataset(sessionId: string, name: string = "default"): Promise<any> {
-        return this.post('/' + sessionId + '/dataset', { payload: { dataset: name } })
+    setDataset(sessionId: string, name: string = 'default'): Promise<unknown> {
+        return this.post(`/${sessionId}/dataset`, { payload: { dataset: name } });
     }
-
-}
+}

package/src/UsersApi.ts

@@ -1,22 +1,20 @@
-import { DeleteByIdResult, UpdateUserPayload, User } from '@vertesia/common';
-import { ApiTopic, ClientBase } from '@vertesia/api-fetch-client';
-
+import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
+import type { DeleteByIdResult, UpdateUserPayload, User } from '@vertesia/common';
 
 export default class UsersApi extends ApiTopic {
-
     constructor(parent: ClientBase) {
-        super(parent, '/api/v1/users')
+        super(parent, '/api/v1/users');
     }
 
     retrieve(userId: string): Promise<User> {
-        return this.get('/' + userId);
+        return this.get(`/${userId}`);
     }
 
     update(userId: string, payload: UpdateUserPayload): Promise<User> {
-        return this.put('/' + userId, { payload });
+        return this.put(`/${userId}`, { payload });
     }
 
     delete(userId: string): Promise<DeleteByIdResult> {
-        return this.del('/' + userId);
+        return this.del(`/${userId}`);
     }
 }

package/src/client.test.ts

@@ -1,5 +1,5 @@
-import { describe, expect, test } from "vitest";
-import { VertesiaClient } from "./client";
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { isTokenExpired, VertesiaClient } from './client.js';
 
 describe('Test Vertesia Client', () => {
     test('Initialization with studio and zeno URLs', () => {
@@ -73,6 +73,17 @@ describe('Test Vertesia Client', () => {
         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');
+        expect(client.tokenServerUrl).toBe('https://sts.dev1.vertesia.io');
+    });
+
     test('Initialization with regional serverUrl (api.us1)', () => {
         const client = new VertesiaClient({
             serverUrl: 'https://api.us1.vertesia.io',
@@ -133,3 +144,58 @@ describe('Test Vertesia Client', () => {
         expect(client.storeUrl).toBe('https://zeno-server-production.api.becomposable.com');
     });
 });
+
+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);
+    });
+});