@vertesia/client 0.51.0 → 0.53.0

package/src/RunsApi.ts

@@ -1,26 +1,38 @@
 import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
-import { ComputeRunFacetPayload, ExecutionRun, ExecutionRunRef, FindPayload, RunCreatePayload, RunListingFilters, RunListingQueryOptions, RunSearchPayload } from "@vertesia/common";
+import {
+    CheckpointConversationPayload,
+    ComputeRunFacetPayload,
+    ExecutionRun,
+    ExecutionRunRef,
+    FindPayload,
+    RunCreatePayload,
+    RunListingFilters,
+    RunListingQueryOptions,
+    RunSearchPayload,
+    ToolResultsPayload,
+    UserMessagePayload,
+} from "@vertesia/common";
 import { VertesiaClient } from "./client.js";
+import { ExecutionResponse } from "@llumiverse/core";
 
 export interface FilterOption {
-    id: string,
-    name: string,
-    count: number
+    id: string;
+    name: string;
+    count: number;
 }
 
 export interface ComputeRunFacetsResponse {
-    environments?: { _id: string, count: number }[];
-    interactions?: { _id: string, count: number }[];
-    models?: { _id: string, count: number }[];
-    tags?: { _id: string, count: number }[];
-    status?: { _id: string, count: number }[];
+    environments?: { _id: string; count: number }[];
+    interactions?: { _id: string; count: number }[];
+    models?: { _id: string; count: number }[];
+    tags?: { _id: string; count: number }[];
+    status?: { _id: string; count: number }[];
     total?: { count: number }[];
 }
 
 export class RunsApi extends ApiTopic {
-
     constructor(parent: ClientBase) {
-        super(parent, "/api/v1/runs")
+        super(parent, "/api/v1/runs");
     }
 
     /**
@@ -30,30 +42,29 @@ export class RunsApi extends ApiTopic {
      * @returns InteractionResult[]
      **/
     list({ limit, offset, filters }: RunListingQueryOptions): Promise<ExecutionRunRef[]> {
-
         const query = {
             limit,
             offset,
-            ...filters
-        }
+            ...filters,
+        };
 
-        return this.get('/', { query: query });
+        return this.get("/", { query: query });
     }
 
     find(payload: FindPayload): Promise<ExecutionRun[]> {
         return this.post("/find", {
-            payload
+            payload,
         });
     }
 
     /**
      * Get a run by id
-     * 
+     *
      * @param id
      * @returns InteractionResult
      **/
-    retrieve<P=any, R=any>(id: string): Promise<ExecutionRun<P, R>> {
-        return this.get('/' + id);
+    retrieve<P = any, R = any>(id: string): Promise<ExecutionRun<P, R>> {
+        return this.get("/" + id);
     }
 
     /**
@@ -62,10 +73,9 @@ export class RunsApi extends ApiTopic {
      */
     filterOptions(field: string, filters: RunListingFilters): Promise<FilterOption[]> {
         const query = {
-            ...filters
-        }
+            ...filters,
+        };
         return this.get(`/filter-options/${field}`, { query });
-
     }
 
     create(payload: RunCreatePayload): Promise<ExecutionRun> {
@@ -73,14 +83,42 @@ export class RunsApi extends ApiTopic {
         if (sessionTags) {
             let tags = Array.isArray(sessionTags) ? sessionTags : [sessionTags];
             if (Array.isArray(payload.tags)) {
-                tags = tags.concat(payload.tags)
+                tags = tags.concat(payload.tags);
             } else if (payload.tags) {
-                tags = tags.concat([payload.tags])
+                tags = tags.concat([payload.tags]);
             }
-            payload = { ...payload, tags }
+            payload = { ...payload, tags };
         }
         return this.post("/", {
-            payload
+            payload,
+        });
+    }
+
+    /**
+     * Send tool results and continues the conversation
+     * @param payload
+     * @returns
+     */
+    sendToolResults(payload: ToolResultsPayload): Promise<ExecutionResponse> {
+        return this.post(`/tool-results`, {
+            payload,
+        });
+    }
+
+    /**
+     *
+     * @param payload
+     * @returns
+     */
+    sendUserMessage(payload: UserMessagePayload): Promise<ExecutionResponse> {
+        return this.post(`/user-message`, {
+            payload,
+        });
+    }
+
+    createCheckpoint(payload: CheckpointConversationPayload): Promise<ExecutionResponse> {
+        return this.post(`/checkpoint`, {
+            payload,
         });
     }
 
@@ -91,14 +129,13 @@ export class RunsApi extends ApiTopic {
      **/
     computeFacets(query: ComputeRunFacetPayload): Promise<ComputeRunFacetsResponse> {
         return this.post("/facets", {
-            payload: query
+            payload: query,
         });
     }
 
     search(payload: RunSearchPayload): Promise<ExecutionRunRef[]> {
         return this.post("/search", {
-            payload
+            payload,
         });
     }
-
-}
+}

package/src/client.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "vitest";
+import { VertesiaClient } from "./client";
+
+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',
+            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');
+    });
+
+    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');
+    });
+
+    test('Initialization with site api-staging.vertesia.io', () => {
+        const client = new VertesiaClient({
+            site: 'api-staging.vertesia.io',
+        });
+
+        expect(client).toBeDefined();
+        expect(client.baseUrl).toBe('https://api-staging.vertesia.io');
+        expect(client.storeUrl).toBe('https://api-staging.vertesia.io');
+    });
+
+    test('Initialization with site localhost', () => {
+        const client = new VertesiaClient({
+            serverUrl: 'http://localhost:8091',
+            storeUrl: 'http://localhost:8092',
+        });
+
+        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');
+    });
+});

package/src/client.ts

@@ -21,9 +21,22 @@ import UsersApi from "./UsersApi.js";
  */
 const EXPIRATION_THRESHOLD = 60000;
 
-export interface VertesiaClientProps {
-    serverUrl: string;
-    storeUrl: string;
+export type VertesiaClientProps = {
+    /**
+     * The site name of Vertesia.
+     *
+     * This is used to determine the API backend. It should not include the protocol. For more
+     * advanced configurations, use `serverUrl` and `storeUrl` instead.
+     *
+     * @example api.vertesia.io
+     * @example api-preview.vertesia.io
+     * @example api-staging.vertesia.io
+     * @default api.vertesia.io
+     * @since 0.52.0
+     */
+    site?: 'api.vertesia.io' | 'api-preview.vertesia.io' | 'api-staging.vertesia.io';
+    serverUrl?: string;
+    storeUrl?: string;
     apikey?: string;
     projectId?: string;
     sessionTags?: string | string[];
@@ -49,17 +62,33 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     sessionTags?: string | string[];
 
     constructor(
-        opts: VertesiaClientProps = {} as any
+        opts: VertesiaClientProps = {
+            site: 'api.vertesia.io',
+        }
     ) {
-        super(opts.serverUrl);
-        if (!opts.serverUrl) {
-            throw new Error("storeUrl is required for VertesiaClient");
+        let studioServerUrl: string;
+        let zenoServerUrl: string;
+
+        if (opts.serverUrl) {
+            studioServerUrl = opts.serverUrl;
+        } else if (opts.site) {
+            studioServerUrl = `https://${opts.site}`;
+        } else {
+            throw new Error("Parameter 'site' or 'serverUrl' is required for VertesiaClient");
         }
-        if (!opts.storeUrl) {
-            throw new Error("storeUrl is required for VertesiaClient");
+
+        if (opts.storeUrl) {
+            zenoServerUrl = opts.storeUrl;
+        } else if (opts.site) {
+            zenoServerUrl = `https://${opts.site}`;
+        } else {
+            throw new Error("Parameter 'site' or 'storeUrl' is required for VertesiaClient");
         }
+
+        super(studioServerUrl);
+
         this.store = new ZenoClient({
-            serverUrl: opts.storeUrl,
+            serverUrl: zenoServerUrl,
             apikey: opts.apikey,
             onRequest: opts.onRequest,
             onResponse: opts.onResponse
@@ -103,6 +132,21 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         );
     }
 
+    async getRawJWT() {
+        if (!this._jwt && this._auth) {
+            const auth = await this._auth();
+            if (!this._jwt) { // the _jwt may be set by the auth callback
+                this._jwt = auth.trim().split(' ')[1]; // remove Bearer prefix
+            }
+        }
+        return this._jwt || null;
+    }
+
+    async getDecodedJWT() {
+        const jwt = await this.getRawJWT();
+        return jwt ? decodeJWT(jwt) : null;
+    }
+
     /**
      * Alias for store.workflows
      */
@@ -128,6 +172,9 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         return this.store.types;
     }
 
+    get storeUrl() {
+        return this.store.baseUrl;
+    }
 
     set project(projectId: string | null) {
         if (projectId) {
@@ -182,10 +229,34 @@ function isTokenExpired(token: string | null) {
         return true;
     }
 
-    const payloadBase64 = token.split('.')[1];
-    const decodedJson = Buffer.from(payloadBase64, 'base64').toString();
-    const decoded = JSON.parse(decodedJson)
+    const decoded = decodeJWT(token);
     const exp = decoded.exp;
     const currentTime = Date.now();
     return (currentTime <= exp * 1000 - EXPIRATION_THRESHOLD);
 }
+
+function decodeJWT(jwt: string) {
+    const payloadBase64 = jwt.split('.')[1];
+    const decodedJson = base64UrlDecode(payloadBase64);
+    return JSON.parse(decodedJson)
+}
+
+function base64UrlDecode(input: string): string {
+    // Convert base64url to base64
+    const base64 = input.replace(/-/g, '+').replace(/_/g, '/')
+        // Pad with '=' to make length a multiple of 4
+        .padEnd(Math.ceil(input.length / 4) * 4, '=');
+
+    if (typeof Buffer !== 'undefined') {
+        // Node.js
+        return Buffer.from(base64, 'base64').toString('utf-8');
+    } else if (typeof atob !== 'undefined' && typeof TextDecoder !== 'undefined') {
+        // Browser
+        const binary = atob(base64);
+        const bytes = Uint8Array.from(binary, c => c.charCodeAt(0));
+        // decode to utf8
+        return new TextDecoder().decode(bytes);
+    } else {
+        throw new Error('No base64 decoder available');
+    }
+}

package/src/execute.ts

@@ -1,4 +1,4 @@
-import { ExecutionRun, ExecutionRunStatus, InteractionExecutionPayload, NamedInteractionExecutionPayload } from '@vertesia/common';
+import { AsyncExecutionPayload, ExecutionRunStatus, InteractionExecutionPayload, InteractionExecutionResult, NamedInteractionExecutionPayload } from '@vertesia/common';
 import { VertesiaClient } from './client.js';
 
 export function EventSourceProvider(): Promise<typeof EventSource> {
@@ -22,7 +22,7 @@ export function EventSourceProvider(): Promise<typeof EventSource> {
 export async function executeInteraction<P = any, R = any>(client: VertesiaClient,
     interactionId: string,
     payload: InteractionExecutionPayload = {},
-    onChunk?: (chunk: string) => void): Promise<ExecutionRun<P, R>> {
+    onChunk?: (chunk: string) => void): Promise<InteractionExecutionResult<P, R>> {
     const stream = !!onChunk;
     const response = await client.runs.create({
         ...payload, interaction: interactionId, stream
@@ -55,7 +55,7 @@ export async function executeInteraction<P = any, R = any>(client: VertesiaClien
 export async function executeInteractionByName<P = any, R = any>(client: VertesiaClient,
     interaction: string,
     payload: InteractionExecutionPayload = {},
-    onChunk?: (chunk: string) => void): Promise<ExecutionRun<P, R>> {
+    onChunk?: (chunk: string) => void): Promise<InteractionExecutionResult<P, R>> {
     const stream = !!onChunk;
     const response = await client.post('/api/v1/execute', {
         payload: {
@@ -111,4 +111,10 @@ function handleStreaming(client: VertesiaClient, runId: string, onChunk: (chunk:
             reject(err);
         }
     });
+}
+
+export async function executeInteractionAsync(client: VertesiaClient, payload: AsyncExecutionPayload): Promise<{ runId: string, workflowId: string }> {
+    return await client.post('/api/v1/execute/async', {
+        payload,
+    });
 }

package/src/index.ts

@@ -1,8 +1,7 @@
+export * from './client.js';
 export * from './InteractionBase.js';
+export type { AsyncExecutionResult, ComputeInteractionFacetsResponse } from './InteractionsApi.js';
 export type { ComputePromptFacetsResponse, ListInteractionsResponse } from './PromptsApi.js';
-export type { ComputeInteractionFacetsResponse } from './InteractionsApi.js';
 export type { ComputeRunFacetsResponse, FilterOption } from './RunsApi.js';
-export * from './client.js';
-export * from './InteractionBase.js';
 export * from "./store/index.js";
 export * from "./StreamSource.js";

package/src/nodejs/NodeStreamSource.ts

@@ -0,0 +1,43 @@
+import type { Readable } from "node:stream";
+import { ReadableStream as NodeReadableStream } from "node:stream/web";
+import { StreamSource } from "../StreamSource.js";
+
+
+/**
+ * A stream source that wraps a Node.js Readable stream.
+ * This class is only works in Node.js environments.
+ */
+export class NodeStreamSource extends StreamSource {
+    constructor(stream: Readable, name: string, type?: string, id?: string) {
+        super(readableToWebStream(stream) as ReadableStream, name, type, id);
+    }
+}
+
+function readableToWebStream<T = string | Buffer>(stream: Readable): ReadableStream<T> {
+    if (NodeReadableStream.from) {
+        return NodeReadableStream.from(stream) as ReadableStream<T>;
+    } else {
+        return readableToWebStream_BUN(stream);
+    }
+}
+
+/**
+ * Bun implementation since bun is not yet supporting NodeReadableStream.from
+ * @returns
+ */
+function readableToWebStream_BUN<T = string | Buffer>(stream: Readable): ReadableStream<T> {
+    const it = stream[Symbol.asyncIterator]();
+    return new ReadableStream<T>({
+        async pull(controller) {
+            const { value, done } = await it.next();
+            if (done) {
+                controller.close();
+            } else {
+                controller.enqueue(value);
+            }
+        },
+        cancel() {
+            it.return?.();
+        }
+    });
+}

package/src/nodejs/index.ts

@@ -0,0 +1 @@
+export * from "./NodeStreamSource.js";

package/src/store/AnalyzeDocApi.ts

@@ -1,5 +1,5 @@
 import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
-import { ContentObject, DocAnalyzerResultResponse, DocAnalyzeRunStatusResponse, DocImage, DocTableCsv, DocTableJson, PdfToRichtextOptions } from "@vertesia/common";
+import { AdaptedTable, AdaptTablesRequest, DocAnalyzerResultResponse, DocAnalyzeRunStatusResponse, DocImage, DocTableCsv, DocTableJson, ExportTableFormats, GetAdaptedTablesRequestQuery, PdfToRichtextOptions, WorkflowRunStatus } from "@vertesia/common";
 
 export class AnalyzeDocApi extends ApiTopic {
     constructor(parent: ClientBase, public objectId: string) {
@@ -18,24 +18,44 @@ export class AnalyzeDocApi extends ApiTopic {
         return this.get("/results");
     }
 
+    async adaptTables(payload: AdaptTablesRequest): Promise<WorkflowRunStatus> {
+        return this.post("/adapt_tables", { payload });
+    }
+
+    async getAdaptedTables(runId?: string, query?: GetAdaptedTablesRequestQuery): Promise<Record<number, AdaptedTable>> {
+        const path = runId ? `/adapt_tables/${runId}` : "/adapt_tables";
+        
+        // Build query parameters
+        const queryParams: any = {};
+        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: any = { query: queryParams };
+        if (query?.format === 'csv') {
+            options.responseType = 'text';
+        }
+        
+        return this.get(path, options);
+    }
+
     async getXml(): Promise<string> {
         return this.get("/xml");
     }
 
-    async getTables(): Promise<DocTableCsv[] | DocTableJson[]> {
-        return this.get("/tables");
+    async getTables(format?: ExportTableFormats): Promise<DocTableCsv[] | DocTableJson[]> {
+        const options: any = {};
+        if (format) {
+            options.query = {format: format}
+        }
+        return this.get("/tables", options);
     }
 
     async getImages(): Promise<DocImage[]> {
-        return this.get("/tables");
-    }
-
-    async getParts(): Promise<ContentObject[]> {
-        return this.get("/parts");
+        return this.get("/images");
     }
 
     async getAnnotated(): Promise<{ url: string }> {
         return this.get("/annotated");
     }
-
 }

package/src/store/CommandsApi.ts

@@ -1,42 +1,15 @@
 import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
-import { EmbeddingsStatusResponse, GenericCommandResponse, ProjectConfigurationEmbeddings, SupportedEmbeddingTypes } from "@vertesia/common";
-
+import { EmbeddingsApi } from "./EmbeddingsApi.js";
 
+/**
+ * @deprecated use EmbeddingsApi instead
+ * @see EmbeddingsApi
+ */
 export class CommandsApi extends ApiTopic {
 
     constructor(parent: ClientBase) {
         super(parent, "/api/v1/commands");
     }
 
-    embeddings = new EmbeddingsApi(this);
-
+    embeddings = new EmbeddingsApi(this, "/embeddings");
 }
-
-export class EmbeddingsApi extends ApiTopic {
-
-    constructor(parent: ClientBase) {
-        super(parent, "/embeddings");
-    }
-
-    async status(type: SupportedEmbeddingTypes): Promise<EmbeddingsStatusResponse> {
-        return this.get(type + "/status");
-    }
-
-    async activate(type: SupportedEmbeddingTypes, config: Partial<ProjectConfigurationEmbeddings>): Promise<GenericCommandResponse> {
-
-        if (!config.environment) {
-            throw new Error("Invalid configuration: select environment");
-        }
-
-        return this.post(type + "/enable", { payload: config });
-    }
-
-    async disable(type: SupportedEmbeddingTypes): Promise<GenericCommandResponse> {
-        return this.post(type + "/disable");
-    }
-
-    async recalculate(type: SupportedEmbeddingTypes): Promise<GenericCommandResponse> {
-        return this.post(type + "/recalculate");
-    }
-
-}

package/src/store/EmbeddingsApi.ts

@@ -0,0 +1,39 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    EmbeddingsStatusResponse,
+    GenericCommandResponse,
+    ProjectConfigurationEmbeddings,
+    SupportedEmbeddingTypes,
+} from "@vertesia/common";
+
+/**
+ * @since 0.52.0
+ */
+export class EmbeddingsApi extends ApiTopic {
+
+    constructor(parent: ClientBase, basePath: string = "/api/v1/embeddings") {
+        super(parent, basePath);
+    }
+
+    async status(type: SupportedEmbeddingTypes): Promise<EmbeddingsStatusResponse> {
+        return this.get(type + "/status");
+    }
+
+    async activate(type: SupportedEmbeddingTypes, config: Partial<ProjectConfigurationEmbeddings>): Promise<GenericCommandResponse> {
+
+        if (!config.environment) {
+            throw new Error("Invalid configuration: select environment");
+        }
+
+        return this.post(type + "/enable", { payload: config });
+    }
+
+    async disable(type: SupportedEmbeddingTypes): Promise<GenericCommandResponse> {
+        return this.post(type + "/disable");
+    }
+
+    async recalculate(type: SupportedEmbeddingTypes): Promise<GenericCommandResponse> {
+        return this.post(type + "/recalculate");
+    }
+
+}

package/src/store/FilesApi.ts

@@ -101,6 +101,10 @@ export class FilesApi extends ApiTopic {
         }).then((res: Response) => {
             if (res.ok) {
                 return res;
+            } else if (res.status === 404) {
+                throw new Error(`File ${name} not found`); //TODO: type fetch error better with a fetch error class
+            } else if (res.status === 403) {
+                throw new Error(`File ${name} is forbidden`);
             } else {
                 console.log(res);
                 throw new Error(`Failed to download file ${name}: ${res.statusText}`);

package/src/store/TypesApi.ts

@@ -16,7 +16,7 @@ export class TypesApi extends ApiTopic {
      * @param options
      * @returns
      */
-    list(payload: ObjectTypeSearchPayload = {}, options?: { layout: boolean }): Promise<ContentObjectTypeItem[]> {
+    list(payload: ObjectTypeSearchPayload = {}, options?: { layout?: boolean, schema?: boolean }): Promise<ContentObjectTypeItem[]> {
         const limit = payload.limit || 100;
         const offset = payload.offset || 0;
         const query = payload.query || {} as ObjectTypeSearchQuery;
@@ -26,6 +26,7 @@ export class TypesApi extends ApiTopic {
                 limit,
                 offset,
                 layout: options?.layout ? true : false,
+                schema: options?.schema ? true : false,
                 ...query
             }
         });