@vertesia/client 0.24.0-dev.202601221707

package/src/client.ts

@@ -0,0 +1,419 @@
+import { AbstractFetchClient } from "@vertesia/api-fetch-client";
+import { AuthTokenPayload, AuthTokenResponse } from "@vertesia/common";
+import AccountApi from "./AccountApi.js";
+import AccountsApi from "./AccountsApi.js";
+import AnalyticsApi from "./AnalyticsApi.js";
+import { ApiKeysApi } from "./ApiKeysApi.js";
+import AppsApi from "./AppsApi.js";
+import CommandsApi from "./CommandsApi.js";
+import EnvironmentsApi from "./EnvironmentsApi.js";
+import { IamApi } from "./IamApi.js";
+import InteractionsApi from "./InteractionsApi.js";
+import MCPOAuthApi from "./MCPOAuthApi.js";
+import ProjectsApi from "./ProjectsApi.js";
+import SkillsApi from "./SkillsApi.js";
+import PromptsApi from "./PromptsApi.js";
+import { RefsApi } from "./RefsApi.js";
+import { RunsApi } from "./RunsApi.js";
+import { ZenoClient } from "./store/client.js";
+import TrainingApi from "./TrainingApi.js";
+import UsersApi from "./UsersApi.js";
+import { VERSION, VERSION_HEADER } from "./store/version.js";
+
+
+/**
+ * 1 min threshold constant in ms
+ */
+const EXPIRATION_THRESHOLD = 60000;
+
+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;
+    tokenServerUrl?: string;
+    apikey?: string;
+    projectId?: string;
+    sessionTags?: string | string[];
+    onRequest?: (request: Request) => void;
+    onResponse?: (response: Response) => void;
+};
+
+export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
+    /**
+     * The JWT token linked to the API KEY (sk or pk)
+     */
+    _jwt: string | null = null;
+
+    /**
+     * The store client
+     */
+    store: ZenoClient;
+
+    /**
+     * The session name will be sent when executing an interaction as a tag
+     */
+    sessionTags?: string | string[];
+
+    /**
+     * tokenServerUrl
+     */
+    tokenServerUrl: string;
+
+    /**
+     * Create a client from the given token.
+     * If you already have the decoded token you can pass it as the second argument to avoid decodinf it again.
+     *
+     * @param token the raw JWT token
+     * @param payload the decoded JWT token as an AuthTokenPayload - optional
+     * @param endpoints optional endpoints to override those in the payload
+     */
+    static async fromAuthToken(
+        token: string,
+        payload?: AuthTokenPayload,
+        endpoints?: { studio: string; store: string; token?: string }
+    ) {
+        if (!payload) {
+            payload = decodeJWT(token);
+        }
+
+        const resolvedEndpoints = endpoints || decodeEndpoints(payload.endpoints);
+        return await new VertesiaClient({
+            serverUrl: resolvedEndpoints.studio,
+            storeUrl: resolvedEndpoints.store,
+            tokenServerUrl: resolvedEndpoints.token || payload.iss,
+        }).withApiKey(token);
+    }
+
+    static decodeEndpoints() {}
+
+    constructor(
+        opts: VertesiaClientProps = {
+            site: "api.vertesia.io",
+        },
+    ) {
+        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) {
+            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);
+
+        if (opts.tokenServerUrl) {
+            this.tokenServerUrl = opts.tokenServerUrl;
+        } else if (opts.site) {
+            // Preview uses production STS, staging uses its own STS
+            if (opts.site === "api-preview.vertesia.io" || opts.site === "api.vertesia.io") {
+                this.tokenServerUrl = "https://sts.vertesia.io";
+            } else {
+                this.tokenServerUrl = `https://${opts.site.replace(/^api/, "sts")}`;
+            }
+        } else if (opts.serverUrl || opts.storeUrl) {
+            // Determine STS URL based on environment in serverUrl or storeUrl
+            const urlToCheck = opts.serverUrl || opts.storeUrl || "";
+            try {
+                const url = new URL(urlToCheck);
+                // Check for environment patterns
+                if (url.hostname.includes("-production.")) {
+                    // zeno-server-production.api.vertesia.io -> sts.vertesia.io
+                    this.tokenServerUrl = "https://sts.vertesia.io";
+                } else if (url.hostname.includes("-preview.")) {
+                    // zeno-server-preview.api.vertesia.io -> sts.vertesia.io
+                    this.tokenServerUrl = "https://sts.vertesia.io";
+                } else if (url.hostname === "api.vertesia.io") {
+                    this.tokenServerUrl = "https://sts.vertesia.io";
+                } else if (url.hostname === "api-preview.vertesia.io") {
+                    this.tokenServerUrl = "https://sts.vertesia.io";
+                } else if (url.hostname === "api-staging.vertesia.io") {
+                    this.tokenServerUrl = "https://sts-staging.vertesia.io";
+                } else if (url.hostname.startsWith("api")) {
+                    // Generic api.* pattern replacement
+                    url.hostname = url.hostname.replace(/^api/, "sts");
+                    this.tokenServerUrl = url.toString();
+                } else {
+                    // Default to staging for everything else
+                    this.tokenServerUrl = "https://sts-staging.vertesia.io";
+                }
+            } catch (e) {
+                // Default to staging if URL parsing fails
+                this.tokenServerUrl = "https://sts-staging.vertesia.io";
+            }
+        } else {
+            // Default to staging if no URL provided
+            this.tokenServerUrl = "https://sts-staging.vertesia.io";
+        }
+
+        this.store = new ZenoClient({
+            serverUrl: zenoServerUrl,
+            tokenServerUrl: this.tokenServerUrl,
+            apikey: opts.apikey,
+            onRequest: opts.onRequest,
+            onResponse: opts.onResponse,
+        });
+
+        if (opts.apikey) {
+            this.withApiKey(opts.apikey);
+        }
+
+        this.onRequest = opts.onRequest;
+        this.onResponse = opts.onResponse;
+        this.sessionTags = opts.sessionTags;
+    }
+
+    withApiVersion(version: string | number | null) {
+        if (!version) {
+            delete this.headers[VERSION_HEADER];
+        } else {
+            this.headers[VERSION_HEADER] = String(version);
+        }
+        return this;
+    }
+
+    /**
+     * Overwrite to keep store and composable clients synchronized on the auth callback
+     * @param authCb
+     * @returns
+     */
+    withAuthCallback(authCb?: (() => Promise<string>) | null) {
+        this.store.withAuthCallback(authCb);
+        return super.withAuthCallback(authCb);
+    }
+
+    async withApiKey(apiKey: string | null) {
+        return this.withAuthCallback(
+            apiKey
+                ? async () => {
+                      if (!isApiKey(apiKey)) {
+                          return `Bearer ${apiKey}`;
+                      }
+
+                      if (isTokenExpired(this._jwt)) {
+                          const jwt = await this.getAuthToken(apiKey);
+                          this._jwt = jwt.token;
+                      }
+                      return `Bearer ${this._jwt}`;
+                  }
+                : undefined,
+        );
+    }
+
+    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(): Promise<AuthTokenPayload | null> {
+        const jwt = await this.getRawJWT();
+        return jwt ? decodeJWT(jwt) : null;
+    }
+
+    async getProject() {
+        const jwt = await this.getDecodedJWT();
+        return jwt?.project || null;
+    }
+
+    async getAccount() {
+        const jwt = await this.getDecodedJWT();
+        return jwt?.account || null;
+    }
+
+    /**
+     * Alias for store.workflows
+     */
+    get workflows() {
+        return this.store.workflows;
+    }
+
+    /**
+     * Alias for store.objects
+     */
+    get objects() {
+        return this.store.objects;
+    }
+
+    get files() {
+        return this.store.files;
+    }
+
+    /**
+     * Alias for store.types
+     */
+    get types() {
+        return this.store.types;
+    }
+
+    /**
+     * Alias for store.data
+     */
+    get data() {
+        return this.store.data;
+    }
+
+    get storeUrl() {
+        return this.store.baseUrl;
+    }
+
+    /**
+     *
+     * Generate a token for use with other Vertesia's services
+     *
+     * @returns AuthTokenResponse
+     */
+    async getAuthToken(token?: string): Promise<AuthTokenResponse> {
+        return fetch(`${this.tokenServerUrl}/token/issue`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${token}`,
+            },
+        })
+            .then((response) => response.json())
+            .then((data) => data as AuthTokenResponse)
+            .catch((error) => {
+                console.error(
+                    `Error fetching token from ${this.tokenServerUrl}:`,
+                    { error },
+                );
+                throw error;
+            });
+    }
+
+    get initialHeaders() {
+        return {
+            ...super.initialHeaders,
+            [VERSION_HEADER]: VERSION
+        }
+    }
+
+    projects = new ProjectsApi(this);
+    environments = new EnvironmentsApi(this);
+    interactions = new InteractionsApi(this);
+    skills = new SkillsApi(this);
+    prompts = new PromptsApi(this);
+    runs = new RunsApi(this);
+    account = new AccountApi(this);
+    accounts = new AccountsApi(this);
+    apikeys = new ApiKeysApi(this);
+    analytics = new AnalyticsApi(this);
+    training = new TrainingApi(this);
+    users = new UsersApi(this);
+    iam = new IamApi(this);
+    refs = new RefsApi(this);
+    commands = new CommandsApi(this);
+    apps = new AppsApi(this);
+    mcpOAuth = new MCPOAuthApi(this);
+}
+
+function isApiKey(apiKey: string) {
+    return apiKey.startsWith("pk-") || apiKey.startsWith("sk-");
+}
+
+function isTokenExpired(token: string | null) {
+    if (!token) {
+        return true;
+    }
+
+    const decoded = decodeJWT(token);
+    const exp = decoded.exp;
+    const currentTime = Date.now();
+    return currentTime <= exp * 1000 - EXPIRATION_THRESHOLD;
+}
+
+export function decodeJWT(jwt: string): AuthTokenPayload {
+    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");
+    }
+}
+
+export function decodeEndpoints(
+    endpoints: string | Record<string, string> | undefined,
+): Record<string, string> {
+    if (!endpoints) {
+        return getEndpointsFromDomain("api.vertesia.io");
+    }
+    if (typeof endpoints === "string") {
+        return getEndpointsFromDomain(endpoints);
+    } else {
+        return endpoints;
+    }
+}
+
+function getEndpointsFromDomain(domain: string) {
+    if (domain === "local") {
+        return {
+            studio: `http://localhost:8091`,
+            store: `http://localhost:8092`,
+            token: process.env.STS_URL ?? "https://sts-staging.vertesia.io",
+        };
+    } else {
+        const url = `https://${domain}`;
+        return {
+            studio: url,
+            store: url,
+            token: url.replace("api", "sts"),
+        };
+    }
+}

package/src/execute.ts

@@ -0,0 +1,126 @@
+import { AsyncExecutionPayload, ExecutionRunStatus, InteractionExecutionPayload, InteractionExecutionResult, NamedInteractionExecutionPayload, RateLimitRequestPayload, RateLimitRequestResponse } from '@vertesia/common';
+import { VertesiaClient } from './client.js';
+
+export async function EventSourceProvider(): Promise<typeof EventSource> {
+    if (typeof globalThis.EventSource === 'function') {
+        return globalThis.EventSource;
+    } else {
+        return (await import('eventsource')).EventSource;
+    }
+}
+/**
+ *
+ * Execute an interaction and return a promise which will be resolved with the executed run when
+ * the run completes or fails.
+ * If the onChunk callback is passed then the streaming of the result is enabled.
+ * The onChunk callback with be called with the next chunk of the result as soon as it is available.
+ * When all chunks are received the function will return the resolved promise
+ * @param id of the interaction to execute
+ * @param payload InteractionExecutionPayload
+ * @param onChunk callback to be called when the next chunk of the response is available
+ */
+export async function executeInteraction<P = any>(client: VertesiaClient,
+    interactionId: string,
+    payload: InteractionExecutionPayload = {},
+    onChunk?: (chunk: string) => void): Promise<InteractionExecutionResult<P>> {
+    const stream = !!onChunk;
+    const response = await client.runs.create({
+        ...payload, interaction: interactionId, stream
+    });
+    if (stream) {
+        if (response.status === ExecutionRunStatus.failed) {
+            return response;
+        }
+        await handleStreaming(client, response.id, onChunk);
+    }
+    return response;
+}
+
+/**
+ * Same as executeInteraction but uses the interaction name selector instead of the id.
+ * A name selector is the interaction endpoint name suffixed with an optional tag or version which is starting with a `@` character.
+ * The special `draft` tag is used to select the draft version of the interaction. If no tag or version is specified then the latest version is selected.
+ * Examples of selectors:
+ * - `ReviewContract` - select the latest version of the ReviewContract interaction
+ * - `ReviewContract@1` - select the version 1 of the ReviewContract interaction
+ * - `ReviewContract@draft` - select the draft version of the ReviewContract interaction
+ * - `ReviewContract@fixed` - select the ReviewContract interaction which is tagged with 'fixed' tag.
+ *
+ * @param client
+ * @param interaction
+ * @param payload
+ * @param onChunk
+ * @returns
+ */
+export async function executeInteractionByName<P = any>(client: VertesiaClient,
+    interaction: string,
+    payload: InteractionExecutionPayload = {},
+    onChunk?: (chunk: string) => void): Promise<InteractionExecutionResult<P>> {
+    const stream = !!onChunk;
+    const response = await client.post('/api/v1/execute', {
+        payload: {
+            ...payload,
+            interaction,
+            stream
+        } as NamedInteractionExecutionPayload,
+    });
+    if (stream) {
+        if (response.status === ExecutionRunStatus.failed) {
+            return response;
+        }
+        await handleStreaming(client, response.id, onChunk);
+    }
+    return response;
+}
+
+function handleStreaming(client: VertesiaClient, runId: string, onChunk: (chunk: string) => void) {
+    return new Promise(async (resolve, reject) => {
+        try {
+            const EventSourceImpl = await EventSourceProvider();
+            const streamUrl = new URL(client.runs.baseUrl + '/' + runId + '/stream');
+            const bearerToken = client._auth ? await client._auth() : undefined;
+
+            if (bearerToken) {
+                const token = bearerToken.split(' ')[1];
+                streamUrl.searchParams.set('access_token', token);
+            } else {
+                throw new Error('No auth token available');
+            }
+
+            const sse = new EventSourceImpl(streamUrl.href);
+            sse.addEventListener("message", ev => {
+                try {
+                    const data = JSON.parse(ev.data);
+                    if (data) {
+                        onChunk && onChunk(data);
+                    }
+                } catch (err) {
+                    reject(err);
+                }
+            });
+            sse.addEventListener("close", (ev) => {
+                try {
+                    sse.close();
+                    const msg = JSON.parse(ev.data)
+                    resolve(msg);
+                } catch (err) {
+                    reject(err);
+                }
+            });
+        } catch (err) {
+            reject(err);
+        }
+    });
+}
+
+export async function executeInteractionAsync(client: VertesiaClient, payload: AsyncExecutionPayload): Promise<{ runId: string, workflowId: string }> {
+    return await client.post('/api/v1/execute/async', {
+        payload,
+    });
+}
+
+export async function checkRateLimit(client: VertesiaClient, payload: RateLimitRequestPayload): Promise<RateLimitRequestResponse> {
+    return await client.post('/api/v1/execute/rate-limit/request', {
+        payload
+    });
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export type { OrphanedAppInstallation } from "./AppsApi.js";
+export * from './client.js';
+export type { GroupsQueryOptions } from './GroupsApi.js';
+export * from './InteractionBase.js';
+export * from './InteractionOutput.js';
+export type { AsyncExecutionResult, ComputeInteractionFacetsResponse } from './InteractionsApi.js';
+export type { ComputePromptFacetsResponse, ListInteractionsResponse } from './PromptsApi.js';
+export type { ComputeRunFacetsResponse, FilterOption } from './RunsApi.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

@@ -0,0 +1,61 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+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) {
+        super(parent, `/${objectId}/analyze`);
+    }
+
+    async start(payload: PdfToRichtextOptions): Promise<DocAnalyzeRunStatusResponse> {
+        return this.post("/", { payload });
+    }
+
+    async getStatus(): Promise<DocAnalyzeRunStatusResponse> {
+        return this.get("/status");
+    }
+
+    async getResults(): Promise<DocAnalyzerResultResponse> {
+        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(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("/images");
+    }
+
+    async getAnnotated(): Promise<{ url: string }> {
+        return this.get("/annotated");
+    }
+}