@vertesia/client 1.0.0-dev.20260305.083323Z → 1.0.0-dev.20260331.091034Z

package/src/MCPOAuthApi.ts

@@ -47,21 +47,28 @@ export default class MCPOAuthApi extends ApiTopic {
     }
 
     /**
-     * Disconnect OAuth authentication for an MCP server
-     * @param mcpServerUrl - The MCP server URL
+     * Disconnect OAuth authentication for a specific collection
+     * @param appInstallId - The app installation ID
+     * @param collectionName - The collection name
      */
-    disconnect(mcpServerUrl: string): Promise<void> {
-        return this.del(`/disconnect/${encodeURIComponent(mcpServerUrl)}`);
+    disconnect(appInstallId: string, collectionName: string): Promise<void> {
+        return this.del(`/disconnect/${appInstallId}/${collectionName}`);
     }
 
     /**
-     * Get or refresh OAuth token for an MCP server (internal use by workflows)
+     * Get or refresh OAuth token (internal use by workflows).
+     * When oauthAppName is provided, uses the generic OAuth Application flow
+     * (resolves by name in the caller's project).
+     * Otherwise falls back to legacy MCP server URL-based token retrieval.
      * @param mcpServerUrl - The MCP server URL
+     * @param oauthAppName - Optional OAuth Application name (from collection's oauth_app field)
      * @returns Access token
      */
-    getToken(mcpServerUrl: string): Promise<{ access_token: string }> {
+    getToken(mcpServerUrl: string, oauthAppName?: string): Promise<{ access_token: string }> {
         return this.post('/token', {
-            payload: { mcp_server_url: mcpServerUrl }
+            payload: oauthAppName
+                ? { oauth_app_name: oauthAppName }
+                : { mcp_server_url: mcpServerUrl }
         });
     }
 }

package/src/OAuthAppsApi.ts

@@ -0,0 +1,87 @@
+import { ApiTopic, ClientBase } from '@vertesia/api-fetch-client';
+import type {
+    CreateOAuthApplicationPayload,
+    OAuthAppAuthStatus,
+    OAuthAppAuthorizeResponse,
+    OAuthApplication,
+    UpdateOAuthApplicationPayload,
+} from '@vertesia/common';
+
+export default class OAuthAppsApi extends ApiTopic {
+
+    constructor(parent: ClientBase) {
+        super(parent, '/api/v1/oauth-apps');
+    }
+
+    /**
+     * List all OAuth applications in the current project.
+     */
+    list(): Promise<OAuthApplication[]> {
+        return this.get('/');
+    }
+
+    /**
+     * Get a single OAuth application by ID (secret redacted).
+     */
+    retrieve(id: string): Promise<OAuthApplication> {
+        return this.get(`/${id}`);
+    }
+
+    /**
+     * Create a new OAuth application.
+     */
+    create(payload: CreateOAuthApplicationPayload): Promise<OAuthApplication> {
+        return this.post('/', { payload });
+    }
+
+    /**
+     * Update an OAuth application.
+     */
+    update(id: string, payload: UpdateOAuthApplicationPayload): Promise<OAuthApplication> {
+        return this.put(`/${id}`, { payload });
+    }
+
+    /**
+     * Delete an OAuth application.
+     */
+    remove(id: string): Promise<void> {
+        return this.del(`/${id}`);
+    }
+
+    /**
+     * Initiate OAuth 2.0 authorization flow for the current user.
+     * Returns an authorization URL to open in a popup/browser.
+     */
+    authorize(id: string): Promise<OAuthAppAuthorizeResponse> {
+        return this.get(`/${id}/authorize`);
+    }
+
+    /**
+     * Exchange an authorization code for tokens (called by UI callback).
+     */
+    exchange(code: string, state: string): Promise<{ success: boolean }> {
+        return this.post('/exchange', { payload: { code, state } });
+    }
+
+    /**
+     * Check the current user's authentication status for an OAuth application.
+     */
+    getStatus(id: string): Promise<OAuthAppAuthStatus> {
+        return this.get(`/${id}/status`);
+    }
+
+    /**
+     * Get a valid access token for an OAuth application (auto-refreshes).
+     * Primarily used by workflows/activities.
+     */
+    getToken(id: string): Promise<{ access_token: string }> {
+        return this.post(`/${id}/token`, { payload: {} });
+    }
+
+    /**
+     * Delete the current user's tokens for an OAuth application.
+     */
+    disconnect(id: string): Promise<void> {
+        return this.del(`/${id}/disconnect`);
+    }
+}

package/src/PromptsApi.ts

@@ -97,6 +97,7 @@ export default class PromptsApi extends ApiTopic {
         });
     }
 
+    //TODO - Does this exist?
     /**
      * Render a prompt template
      * @param id of the prompt template to render
@@ -107,12 +108,13 @@ export default class PromptsApi extends ApiTopic {
      * @throws 400 if payload is invalid
      * @throws 500 if render fails
      **/
-    render(id: string, payload: {}): Promise<PromptTemplate> {
+    render(id: string, payload: object): Promise<PromptTemplate> {
         return this.post(`/${id}/render`, {
             payload
         });
     }
 
+    //TODO - Does this exist?
     /**
      * Get options for a field
      * @param field name to get options for

package/src/RunsApi.ts

@@ -7,6 +7,8 @@ import {
     FindPayload,
     PopulatedExecutionRun,
     RunCreatePayload,
+    ExecutionRunDocRef,
+    RunClonePayload,
     RunListingFilters,
     RunListingQueryOptions,
     RunSearchPayload,
@@ -141,4 +143,12 @@ export class RunsApi extends ApiTopic {
             payload,
         });
     }
+
+    /**
+     * Clone an existing ExecutionRun for fork workflows.
+     * Creates a new run with the same interaction/config but fresh status.
+     */
+    clone(payload: RunClonePayload): Promise<ExecutionRunDocRef> {
+        return this.post('/clone', { payload });
+    }
 }

package/src/client.test.ts

@@ -62,15 +62,51 @@ describe('Test Vertesia Client', () => {
         expect(client.tokenServerUrl).toBe('https://sts.vertesia.io');
     });
 
-    test('Initialization with site api-staging.vertesia.io', () => {
+    test('Initialization with site api.dev1.vertesia.io', () => {
         const client = new VertesiaClient({
-            site: 'api-staging.vertesia.io',
+            site: 'api.dev1.vertesia.io',
         });
 
         expect(client).toBeDefined();
-        expect(client.baseUrl).toBe('https://api-staging.vertesia.io');
-        expect(client.storeUrl).toBe('https://api-staging.vertesia.io');
-        expect(client.tokenServerUrl).toBe('https://sts-staging.vertesia.io');
+        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 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 strips -preview., then api → sts: sts.us1.vertesia.io
+        expect(client.tokenServerUrl).toBe('https://sts.us1.vertesia.io');
     });
 
     test('Initialization with site localhost', () => {

package/src/client.ts

@@ -11,6 +11,7 @@ import EnvironmentsApi from "./EnvironmentsApi.js";
 import { IamApi } from "./IamApi.js";
 import InteractionsApi from "./InteractionsApi.js";
 import MCPOAuthApi from "./MCPOAuthApi.js";
+import OAuthAppsApi from "./OAuthAppsApi.js";
 import ProjectsApi from "./ProjectsApi.js";
 import SkillsApi from "./SkillsApi.js";
 import PromptsApi from "./PromptsApi.js";
@@ -35,15 +36,21 @@ export type VertesiaClientProps = {
      * advanced configurations, use `serverUrl` and `storeUrl` instead.
      *
      * @example api.vertesia.io
-     * @example api-preview.vertesia.io
-     * @example api-staging.vertesia.io
+     * @example api.us1.vertesia.io
+     * @example api-preview.eu1.vertesia.io
      * @default api.vertesia.io
      * @since 0.52.0
      */
     site?:
         | "api.vertesia.io"
         | "api-preview.vertesia.io"
-        | "api-staging.vertesia.io";
+        | "api.us1.vertesia.io"
+        | "api-preview.us1.vertesia.io"
+        | "api.eu1.vertesia.io"
+        | "api-preview.eu1.vertesia.io"
+        | "api.jp1.vertesia.io"
+        | "api-preview.jp1.vertesia.io"
+        | "api.dev1.vertesia.io";
     serverUrl?: string;
     storeUrl?: string;
     tokenServerUrl?: string;
@@ -135,45 +142,35 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         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")}`;
-            }
+            // Strip -preview (preview uses the same STS as production for the same region),
+            // then replace api prefix with sts.
+            // Examples:
+            //   api.vertesia.io          -> sts.vertesia.io
+            //   api-preview.vertesia.io  -> sts.vertesia.io
+            //   api.us1.vertesia.io      -> sts.us1.vertesia.io
+            //   api-preview.eu1.vertesia.io -> sts.eu1.vertesia.io
+            const stsHost = opts.site.replace('api-preview.', 'api.').replace(/^api/, 'sts');
+            this.tokenServerUrl = `https://${stsHost}`;
         } 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();
+                if (url.hostname.startsWith("api")) {
+                    // Strip -preview and replace api with sts.
+                    // api.us1.vertesia.io         -> sts.us1.vertesia.io
+                    // api-preview.us1.vertesia.io -> sts.us1.vertesia.io
+                    // api.vertesia.io             -> sts.vertesia.io
+                    const stsHost = url.hostname.replace('api-preview.', 'api.').replace(/^api/, 'sts');
+                    this.tokenServerUrl = `https://${stsHost}`;
                 } else {
-                    // Default to staging for everything else
-                    this.tokenServerUrl = "https://sts-staging.vertesia.io";
+                    this.tokenServerUrl = "https://sts.dev1.vertesia.io";
                 }
             } catch (e) {
-                // Default to staging if URL parsing fails
-                this.tokenServerUrl = "https://sts-staging.vertesia.io";
+                this.tokenServerUrl = "https://sts.dev1.vertesia.io";
             }
         } else {
-            // Default to staging if no URL provided
-            this.tokenServerUrl = "https://sts-staging.vertesia.io";
+            this.tokenServerUrl = "https://sts.dev1.vertesia.io";
         }
 
         this.store = new ZenoClient({
@@ -256,6 +253,13 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         return jwt?.account || null;
     }
 
+    /**
+     * Alias for store.agents
+     */
+    get agents() {
+        return this.store.agents;
+    }
+
     /**
      * Alias for store.workflows
      */
@@ -342,6 +346,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     commands = new CommandsApi(this);
     apps = new AppsApi(this);
     mcpOAuth = new MCPOAuthApi(this);
+    oauthApps = new OAuthAppsApi(this);
 }
 
 function isApiKey(apiKey: string) {
@@ -412,6 +417,8 @@ function getEndpointsFromDomain(domain: string) {
         };
     } else {
         const url = `https://${domain}`;
+        // Supports both dot-separated (api.us1.vertesia.io → sts.us1.vertesia.io)
+        // and legacy (api.vertesia.io → sts.vertesia.io)
         return {
             studio: url,
             store: url,

package/src/execute.ts

@@ -1,5 +1,6 @@
 import { AsyncExecutionPayload, ExecutionRunStatus, InteractionExecutionPayload, InteractionExecutionResult, NamedInteractionExecutionPayload, RateLimitRequestPayload, RateLimitRequestResponse } from '@vertesia/common';
 import { VertesiaClient } from './client.js';
+import type { AsyncExecutionResult } from './InteractionsApi.js';
 
 export async function EventSourceProvider(): Promise<typeof EventSource> {
     if (typeof globalThis.EventSource === 'function') {
@@ -74,46 +75,48 @@ export async function executeInteractionByName<P = any>(client: VertesiaClient,
 }
 
 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;
+    return new Promise((resolve, reject) => {
+        (async () => {
+            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');
-            }
+                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);
+                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);
                     }
-                } 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);
-        }
+                });
+                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 }> {
+export async function executeInteractionAsync(client: VertesiaClient, payload: AsyncExecutionPayload): Promise<AsyncExecutionResult> {
     return await client.post('/api/v1/execute/async', {
         payload,
     });