@vertesia/client 0.81.1 → 1.0.0-dev.20260203.130115Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/client",
-  "version": "0.81.1",
+  "version": "1.0.0-dev.20260203.130115Z",
   "type": "module",
   "types": "./lib/types/index.d.ts",
   "files": [
@@ -13,18 +13,18 @@
     "@rollup/plugin-commonjs": "^28.0.3",
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-typescript": "^12.1.2",
-    "@types/node": "^22.13.5",
+    "@types/node": "^22.19.2",
     "rollup": "^4.40.2",
     "rollup-plugin-terser": "^7.0.2",
     "ts-dual-module": "^0.6.3",
-    "typescript": "^5.0.2",
-    "vitest": "^3.0.9"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
   },
   "dependencies": {
     "eventsource": "^3.0.6",
-    "@llumiverse/common": "0.24.0",
-    "@vertesia/api-fetch-client": "0.81.1",
-    "@vertesia/common": "0.81.1"
+    "@vertesia/api-fetch-client": "1.0.0-dev.20260203.130115Z",
+    "@llumiverse/common": "1.0.0-dev.20260202.145450Z",
+    "@vertesia/common": "1.0.0-dev.20260203.130115Z"
   },
   "ts_dual_module": {
     "outDir": "lib"

package/src/InteractionsApi.ts

@@ -6,7 +6,7 @@ import {
     InteractionExecutionPayload, InteractionForkPayload,
     InteractionPublishPayload, InteractionRef, InteractionRefWithSchema, InteractionSearchPayload, InteractionSearchQuery,
     InteractionsExportPayload, InteractionTags, InteractionUpdatePayload,
-    RateLimitRequestPayload, RateLimitRequestResponse
+    RateLimitRequestPayload, RateLimitRequestResponse, ResolvedInteractionExecutionInfo
 } from "@vertesia/common";
 import { VertesiaClient } from "./client.js";
 import { checkRateLimit, executeInteraction, executeInteractionAsync, executeInteractionByName } from "./execute.js";
@@ -285,4 +285,24 @@ export default class InteractionsApi extends ApiTopic {
         return checkRateLimit(this.client as VertesiaClient, payload);
     }
 
+    /**
+     * Resolve an interaction by ID or name and return the resolved execution info.
+     * This includes the interaction ID, name, version, tags, and the resolved
+     * environment/model that would be used at execution time.
+     *
+     * The nameOrId parameter can be:
+     * - A MongoDB ObjectId (e.g., "66b9149c26dc74d6b5187d27")
+     * - An endpoint name (e.g., "ReviewContract")
+     * - An endpoint name with version/tag (e.g., "ReviewContract@1", "ReviewContract@draft")
+     *
+     * @param nameOrId The interaction ID or name (with optional @version/@tag)
+     * @param options Optional environment and/or model to resolve with
+     * @returns ResolvedInteractionExecutionInfo with the resolved environment and model
+     */
+    resolve(nameOrId: string, options?: { environment?: string; model?: string }): Promise<ResolvedInteractionExecutionInfo> {
+        return this.get(`/resolve/${encodeURIComponent(nameOrId)}`, {
+            query: options
+        });
+    }
+
 }

package/src/MCPOAuthApi.ts

@@ -0,0 +1,67 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import type { OAuthAuthStatus, OAuthAuthorizeResponse, OAuthMetadataResponse } from "@vertesia/common";
+
+export default class MCPOAuthApi extends ApiTopic {
+
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/mcp/oauth")
+    }
+
+    /**
+     * Get OAuth authentication status for all collections in an app installation
+     * @param appInstallId - The app installation ID
+     * @returns Array of OAuth authentication statuses
+     */
+    getStatus(appInstallId: string): Promise<OAuthAuthStatus[]> {
+        return this.get(`/status/${appInstallId}`);
+    }
+
+    /**
+     * Get OAuth authentication status for a specific collection
+     * @param appInstallId - The app installation ID
+     * @param collectionName - The collection name
+     * @returns OAuth authentication status for the collection
+     */
+    getCollectionStatus(appInstallId: string, collectionName: string): Promise<OAuthAuthStatus> {
+        return this.get(`/status/${appInstallId}/${collectionName}`);
+    }
+
+    /**
+     * Get OAuth metadata for a specific collection
+     * @param appInstallId - The app installation ID
+     * @param collectionName - The collection name
+     * @returns OAuth metadata
+     */
+    getMetadata(appInstallId: string, collectionName: string): Promise<OAuthMetadataResponse> {
+        return this.get(`/metadata/${appInstallId}/${collectionName}`);
+    }
+
+    /**
+     * Initiate OAuth authorization flow for a specific collection
+     * @param appInstallId - The app installation ID
+     * @param collectionName - The collection name
+     * @returns Authorization URL to open for user authentication
+     */
+    authorize(appInstallId: string, collectionName: string): Promise<OAuthAuthorizeResponse> {
+        return this.get(`/authorize/${appInstallId}/${collectionName}`);
+    }
+
+    /**
+     * Disconnect OAuth authentication for an MCP server
+     * @param mcpServerUrl - The MCP server URL
+     */
+    disconnect(mcpServerUrl: string): Promise<void> {
+        return this.del(`/disconnect/${encodeURIComponent(mcpServerUrl)}`);
+    }
+
+    /**
+     * Get or refresh OAuth token for an MCP server (internal use by workflows)
+     * @param mcpServerUrl - The MCP server URL
+     * @returns Access token
+     */
+    getToken(mcpServerUrl: string): Promise<{ access_token: string }> {
+        return this.post('/token', {
+            payload: { mcp_server_url: mcpServerUrl }
+        });
+    }
+}

package/src/ProjectsApi.ts

@@ -1,5 +1,5 @@
-import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
-import { AwsConfiguration, GithubConfiguration, GladiaConfiguration, ICreateProjectPayload, MagicPdfConfiguration, Project, ProjectConfiguration, ProjectIntegrationListEntry, ProjectRef, SupportedIntegrations } from "@vertesia/common";
+import { ApiTopic, ClientBase, ServerError } from "@vertesia/api-fetch-client";
+import { AwsConfiguration, GithubConfiguration, GladiaConfiguration, ICreateProjectPayload, MagicPdfConfiguration, Project, ProjectConfiguration, ProjectIntegrationListEntry, ProjectRef, ProjectToolInfo, SupportedIntegrations } from "@vertesia/common";
 
 export default class ProjectsApi extends ApiTopic {
     constructor(parent: ClientBase) {
@@ -34,6 +34,27 @@ export default class ProjectsApi extends ApiTopic {
 
     integrations: IntegrationsConfigurationApi = new IntegrationsConfigurationApi(this);
 
+    /**
+     * List all tools available in the project with their app installation info.
+     * Settings are only included for agent tokens (security: may contain API keys).
+     */
+    getTools(projectId: string): Promise<ProjectToolInfo[]> {
+        return this.get(`/${projectId}/tools`);
+    }
+
+    /**
+     * Get a specific tool by name with its app installation info.
+     * Returns null if the tool is not found.
+     */
+    getToolByName(projectId: string, toolName: string): Promise<ProjectToolInfo | null> {
+        return this.get(`/${projectId}/tools/${toolName}`).catch((err: ServerError) => {
+            if (err.status === 404) {
+                return null;
+            }
+            throw err;
+        });
+    }
+
 }
 
 class IntegrationsConfigurationApi extends ApiTopic {

package/src/client.ts

@@ -9,6 +9,7 @@ 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";
@@ -79,17 +80,22 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
      *
      * @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) {
+    static async fromAuthToken(
+        token: string,
+        payload?: AuthTokenPayload,
+        endpoints?: { studio: string; store: string; token?: string }
+    ) {
         if (!payload) {
             payload = decodeJWT(token);
         }
 
-        const endpoints = decodeEndpoints(payload.endpoints);
+        const resolvedEndpoints = endpoints || decodeEndpoints(payload.endpoints);
         return await new VertesiaClient({
-            serverUrl: endpoints.studio,
-            storeUrl: endpoints.store,
-            tokenServerUrl: payload.iss,
+            serverUrl: resolvedEndpoints.studio,
+            storeUrl: resolvedEndpoints.store,
+            tokenServerUrl: resolvedEndpoints.token || payload.iss,
         }).withApiKey(token);
     }
 
@@ -274,6 +280,13 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         return this.store.types;
     }
 
+    /**
+     * Alias for store.data
+     */
+    get data() {
+        return this.store.data;
+    }
+
     get storeUrl() {
         return this.store.baseUrl;
     }
@@ -326,6 +339,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     refs = new RefsApi(this);
     commands = new CommandsApi(this);
     apps = new AppsApi(this);
+    mcpOAuth = new MCPOAuthApi(this);
 }
 
 function isApiKey(apiKey: string) {

package/src/index.ts

@@ -1,10 +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 type { GroupsQueryOptions } from './GroupsApi.js';
 export * from "./store/index.js";
 export * from "./StreamSource.js";
-export type { OrphanedAppInstallation } from "./AppsApi.js";

package/src/store/CollectionsApi.ts

@@ -1,5 +1,5 @@
 import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
-import { Collection, CollectionItem, ComplexCollectionSearchQuery, ComplexSearchPayload, ComputeCollectionFacetPayload, ComputeObjectFacetPayload, ContentObjectItem, ContentObjectStatus, CreateCollectionPayload, DynamicCollection } from "@vertesia/common";
+import { Collection, ComplexCollectionSearchQuery, ComplexSearchPayload, ComputeCollectionFacetPayload, ComputeObjectFacetPayload, ContentObjectItem, ContentObjectStatus, CreateCollectionPayload, DynamicCollection } from "@vertesia/common";
 import { ComputeFacetsResponse, SearchResponse } from "./ObjectsApi.js";
 
 
@@ -12,9 +12,9 @@ export class CollectionsApi extends ApiTopic {
     /**
      * List collections
      * @param payload: CollectionSearchPayload
-     * @returns CollectionItem[] list of collections
+     * @returns Collection[] list of collections
     **/
-    search(payload: ComplexCollectionSearchQuery): Promise<CollectionItem[]> {
+    search(payload: ComplexCollectionSearchQuery): Promise<Collection[]> {
         return this.post("/search", { payload });
     }
 
@@ -109,7 +109,7 @@ export class CollectionsApi extends ApiTopic {
         });
     }
 
-    searchChildren(collectionId: string, query: ComplexCollectionSearchQuery = {}): Promise<CollectionItem[]> {
+    searchChildren(collectionId: string, query: ComplexCollectionSearchQuery = {}): Promise<Collection[]> {
         return this.post(`/${collectionId}/children/search`, {
             payload: query
         });

package/src/store/DashboardApi.ts

@@ -0,0 +1,216 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    CreateDashboardPayload,
+    CreateDashboardSnapshotPayload,
+    Dashboard,
+    DashboardItem,
+    DashboardStatus,
+    DashboardVersion,
+    DashboardVersionItem,
+    DataStoreApiHeaders,
+    PromoteDashboardVersionPayload,
+    UpdateDashboardPayload,
+} from "@vertesia/common";
+
+/**
+ * Client API for managing Vega-based dashboards linked to data stores.
+ *
+ * Dashboards provide:
+ * - Multi-panel Vega/Vega-Lite visualizations
+ * - SQL-backed data sources via named queries
+ *
+ * Note: Rendering is handled by the tools (data_preview_dashboard, data_render_dashboard).
+ */
+export class DashboardApi extends ApiTopic {
+    private readonly storeId: string;
+
+    constructor(parent: ClientBase, storeId: string) {
+        super(parent, `/api/v1/data/${storeId}/dashboards`);
+        this.storeId = storeId;
+    }
+
+    /**
+     * Create headers with data store ID for Cloud Run session affinity.
+     */
+    private storeHeaders(): Record<string, string> {
+        return { [DataStoreApiHeaders.DATA_STORE_ID]: this.storeId };
+    }
+
+    // ============================================================
+    // Dashboard Operations
+    // ============================================================
+
+    /**
+     * List all dashboards for the data store.
+     *
+     * @param status - Filter by status (default: 'active')
+     * @returns List of dashboards
+     */
+    list(status?: DashboardStatus): Promise<DashboardItem[]> {
+        const query = status ? `?status=${status}` : '';
+        return this.get(`/${query}`, { headers: this.storeHeaders() });
+    }
+
+    /**
+     * Create a new dashboard.
+     *
+     * @param payload - Dashboard configuration with queries and panels
+     * @returns The created dashboard
+     *
+     * @example
+     * ```typescript
+     * const dashboard = await client.data.dashboards(storeId).create({
+     *   name: 'Sales Overview',
+     *   queries: [
+     *     { name: 'revenue', sql: 'SELECT month, SUM(amount) FROM sales GROUP BY month' }
+     *   ],
+     *   panels: [
+     *     {
+     *       title: 'Monthly Revenue',
+     *       dataSources: ['revenue'],
+     *       position: { row: 0, col: 0 },
+     *       spec: {
+     *         mark: 'bar',
+     *         encoding: {
+     *           x: { field: 'month', type: 'ordinal' },
+     *           y: { field: 'sum_amount', type: 'quantitative' }
+     *         }
+     *       }
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    create(payload: CreateDashboardPayload): Promise<Dashboard> {
+        return this.post("/", { payload, headers: this.storeHeaders() });
+    }
+
+    /**
+     * Get a dashboard by ID.
+     *
+     * @param id - Dashboard ID
+     * @returns The dashboard with all details
+     */
+    retrieve(id: string): Promise<Dashboard> {
+        return this.get(`/${id}`, { headers: this.storeHeaders() });
+    }
+
+    /**
+     * Update an existing dashboard.
+     *
+     * @param id - Dashboard ID
+     * @param payload - Fields to update
+     * @returns The updated dashboard
+     */
+    update(id: string, payload: UpdateDashboardPayload): Promise<Dashboard> {
+        return this.put(`/${id}`, { payload, headers: this.storeHeaders() });
+    }
+
+    /**
+     * Archive (soft delete) a dashboard.
+     *
+     * @param id - Dashboard ID
+     * @returns Object with the archived dashboard ID
+     */
+    delete(id: string): Promise<{ id: string; status: DashboardStatus }> {
+        return this.del(`/${id}`, { headers: this.storeHeaders() });
+    }
+
+    /**
+     * Archive (soft delete) multiple dashboards.
+     *
+     * @param ids - Array of dashboard IDs
+     * @returns Object with counts of archived and failed dashboards
+     */
+    bulkArchive(ids: string[]): Promise<{ archived: number; failed: number }> {
+        return this.post('/bulk/archive', { payload: { ids }, headers: this.storeHeaders() });
+    }
+
+    /**
+     * Permanently delete multiple dashboards.
+     *
+     * @param ids - Array of dashboard IDs
+     * @returns Object with counts of deleted and failed dashboards
+     */
+    bulkDelete(ids: string[]): Promise<{ deleted: number; failed: number }> {
+        return this.post('/bulk/delete', { payload: { ids }, headers: this.storeHeaders() });
+    }
+
+    // ============================================================
+    // Version Operations
+    // ============================================================
+
+    /**
+     * List versions for a dashboard.
+     *
+     * @param dashboardId - Dashboard ID
+     * @param options - Filter options
+     * @returns List of version summaries
+     */
+    listVersions(
+        dashboardId: string,
+        options?: { snapshotsOnly?: boolean; limit?: number }
+    ): Promise<DashboardVersionItem[]> {
+        const params = new URLSearchParams();
+        if (options?.snapshotsOnly) params.set('snapshots_only', 'true');
+        if (options?.limit) params.set('limit', String(options.limit));
+        const query = params.toString() ? `?${params}` : '';
+        return this.get(`/${dashboardId}/versions${query}`, { headers: this.storeHeaders() });
+    }
+
+    /**
+     * Get a specific version with full content.
+     *
+     * @param dashboardId - Dashboard ID
+     * @param versionId - Version ID
+     * @returns The version with full content
+     */
+    getVersion(dashboardId: string, versionId: string): Promise<DashboardVersion> {
+        return this.get(`/${dashboardId}/versions/${versionId}`, { headers: this.storeHeaders() });
+    }
+
+    /**
+     * Create a named snapshot from current dashboard state.
+     *
+     * @param dashboardId - Dashboard ID
+     * @param payload - Snapshot name and message
+     * @returns The created snapshot version
+     */
+    createSnapshot(
+        dashboardId: string,
+        payload: CreateDashboardSnapshotPayload
+    ): Promise<DashboardVersionItem> {
+        return this.post(`/${dashboardId}/versions`, { payload, headers: this.storeHeaders() });
+    }
+
+    /**
+     * Promote a version to be the current/active one.
+     * This restores the version's content to the dashboard.
+     *
+     * @param dashboardId - Dashboard ID
+     * @param versionId - Version ID to promote
+     * @param payload - Optional promotion message
+     * @returns The updated dashboard
+     */
+    promoteVersion(
+        dashboardId: string,
+        versionId: string,
+        payload?: PromoteDashboardVersionPayload
+    ): Promise<Dashboard> {
+        return this.post(`/${dashboardId}/versions/${versionId}/promote`, { payload: payload || {}, headers: this.storeHeaders() });
+    }
+
+    /**
+     * Enable or disable versioning for a dashboard.
+     *
+     * @param dashboardId - Dashboard ID
+     * @param enabled - Whether versioning should be enabled
+     * @returns The updated versioning state
+     */
+    setVersioningEnabled(
+        dashboardId: string,
+        enabled: boolean
+    ): Promise<{ versioning_enabled: boolean }> {
+        return this.put(`/${dashboardId}/versioning`, { payload: { enabled }, headers: this.storeHeaders() });
+    }
+}