@vertesia/client 0.24.0-dev.202601221707

package/src/InteractionResult.example.ts

@@ -0,0 +1,72 @@
+/**
+ * Example usage of InteractionOutput
+ * This file demonstrates the Proxy-based approach where the result acts as both
+ * an array and has convenience methods.
+ */
+
+import { CompletionResult } from '@llumiverse/common';
+import { InteractionOutput } from './InteractionOutput.js';
+
+// Sample data
+const sampleResults: CompletionResult[] = [
+    { type: 'text', value: 'Hello, ' },
+    { type: 'text', value: 'World!' },
+    { type: 'json', value: { name: 'Alice', age: 30 } },
+    { type: 'json', value: { title: 'Engineer', level: 'Senior' } },
+    { type: 'image', value: 'data:image/png;base64,iVBORw0K...' }
+];
+
+// Example 1: Using InteractionOutput.from() (Proxy approach - RECOMMENDED)
+console.log('=== Example 1: Proxy Approach ===');
+interface Person { name: string; age: number; }
+const output = InteractionOutput.from<Person>(sampleResults);
+
+// Works as an array
+console.log('Array length:', output.length);           // 5
+console.log('First item:', output[0]);                 // { type: 'text', value: 'Hello, ' }
+console.log('Types:', output.map(r => r.type));        // ['text', 'text', 'json', 'json', 'image']
+
+// Has convenience methods
+console.log('All text:', output.text);                 // 'Hello, World!'
+console.log('First object:', output.object());         // { name: 'Alice', age: 30 } (typed as Person)
+console.log('All objects:', output.objects());         // [{ name: 'Alice', age: 30 }, { title: 'Engineer', level: 'Senior' }]
+console.log('First image:', output.image);             // 'data:image/png;base64,iVBORw0K...'
+
+// Override type for specific objects
+interface Job { title: string; level: string; }
+console.log('Second object:', output.objectAt<Job>(1)); // { title: 'Engineer', level: 'Senior' } (typed as Job)
+
+// Example 2: Using InteractionOutput class directly
+console.log('\n=== Example 2: Class Approach ===');
+const wrapper = new InteractionOutput<Person>(sampleResults);
+
+// Access through wrapper properties (no array access)
+console.log('All text:', wrapper.text);
+console.log('Raw results:', wrapper.results);          // Original array
+console.log('First object:', wrapper.object());
+
+// Example 3: Type safety demonstration
+console.log('\n=== Example 3: Type Safety ===');
+
+interface Contract { title: string; parties: string[]; }
+const contractResults: CompletionResult[] = [
+    { type: 'json', value: { title: 'Sales Agreement', parties: ['Alice', 'Bob'] } }
+];
+
+const contractOutput = InteractionOutput.from<Contract>(contractResults);
+const contract = contractOutput.object(); // TypeScript knows this is Contract
+console.log('Contract title:', contract.title);
+console.log('Parties:', contract.parties.join(', '));
+
+// Example 4: Mixed content
+console.log('\n=== Example 4: Mixed Content ===');
+const mixedResults: CompletionResult[] = [
+    { type: 'text', value: 'Analysis complete. Results: ' },
+    { type: 'json', value: { score: 0.95, confidence: 'high' } },
+    { type: 'text', value: '\nThank you!' }
+];
+
+const mixed = InteractionOutput.from(mixedResults);
+console.log('Full text:', mixed.text);                 // 'Analysis complete. Results: \nThank you!'
+console.log('Analysis:', mixed.object());              // { score: 0.95, confidence: 'high' }
+console.log('Text parts:', mixed.texts);               // ['Analysis complete. Results: ', '\nThank you!']

package/src/InteractionsApi.ts

@@ -0,0 +1,308 @@
+import { ApiTopic, ClientBase, ServerError } from "@vertesia/api-fetch-client";
+import {
+    AsyncExecutionPayload, ComputeInteractionFacetPayload, GenerateInteractionPayload, GenerateTestDataPayload, ImprovePromptPayload,
+    ImprovePromptPayloadConfig,
+    Interaction, InteractionCreatePayload, InteractionEndpoint, InteractionEndpointQuery,
+    InteractionExecutionPayload, InteractionForkPayload,
+    InteractionPublishPayload, InteractionRef, InteractionRefWithSchema, InteractionSearchPayload, InteractionSearchQuery,
+    InteractionsExportPayload, InteractionTags, InteractionUpdatePayload,
+    RateLimitRequestPayload, RateLimitRequestResponse, ResolvedInteractionExecutionInfo
+} from "@vertesia/common";
+import { VertesiaClient } from "./client.js";
+import { checkRateLimit, executeInteraction, executeInteractionAsync, executeInteractionByName } from "./execute.js";
+import { InteractionCatalogApi } from "./InteractionCatalogApi.js";
+import { EnhancedExecutionRun, EnhancedInteractionExecutionResult, enhanceExecutionRun, enhanceInteractionExecutionResult } from "./InteractionOutput.js";
+
+export interface ComputeInteractionFacetsResponse {
+    tags?: { _id: string, count: number }[];
+    status?: { _id: string, count: number }[];
+    total?: { count: number }[];
+}
+
+export interface AsyncExecutionResult {
+    runId: string, workflowId: string
+}
+
+export default class InteractionsApi extends ApiTopic {
+    catalog: InteractionCatalogApi;
+
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/interactions");
+        this.catalog = new InteractionCatalogApi(parent);
+    }
+
+    /**
+     * Get the list of all interactions in the current project
+     * @returns InteractionRef[]
+     **/
+    list(payload: InteractionSearchPayload = {}): Promise<InteractionRef[]> {
+        const query = payload.query || {} as InteractionSearchQuery;
+
+        return this.get("/", {
+            query: {
+                ...query
+            }
+        });
+    }
+    /**
+     * Find interactions given a mongo match query.
+     * You can also specify if prompts schemas are included in the result
+     */
+    listEndpoints(payload: InteractionEndpointQuery): Promise<InteractionEndpoint[]> {
+        return this.post("/endpoints", {
+            payload
+        });
+    }
+
+    /**
+     * List all interaction versions in the project having the given endpoint name.
+     * This is useful to list orphaned versions
+     * @param name
+     */
+    listVersionsByName(name: string): Promise<InteractionRef[]> {
+        return this.get(`/versions/${name}`);
+    }
+
+    /**
+     * Get the list of all interaction tags in the current project
+     * @param query optional query parameters to filter the tags
+     * @returns InteractionTags[]
+     **/
+    listTags(query?: InteractionSearchQuery): Promise<InteractionTags[]> {
+        return this.get("/tags", {
+            query: {
+                ...query
+            }
+        });
+    }
+
+    /**
+     * Get the list of all interactions facets
+     * @param payload query payload to filter facet search
+     * @returns ComputeInteractionFacetsResponse[]
+     **/
+    computeFacets(query: ComputeInteractionFacetPayload): Promise<ComputeInteractionFacetsResponse> {
+        return this.post("/facets", {
+            payload: query
+        });
+    }
+
+    /**
+     * List interaction names in the current project
+     * @returns
+     */
+    listNames(): Promise<{ id: string, name: string }[]> {
+        return this.get('/names');
+    }
+
+    /**
+     * Get the list of all interactions in the current project. Schemas will be returned too.
+     * @returns InteractionRefWithSchema[]
+     **/
+    export(payload: InteractionsExportPayload): Promise<InteractionRefWithSchema[]> {
+        return this.post('/export', { payload });
+    }
+
+    /**
+     * Create a new interaction
+     * @param payload InteractionCreatePayload
+     * @returns Interaction
+     * @throws ApiError
+     * @throws 400 if payload is invalid
+     * @throws 500 if interaction creation fails
+     **/
+    create(payload: InteractionCreatePayload): Promise<Interaction> {
+        return this.post('/', {
+            payload
+        });
+    }
+
+    /**
+     * Retrieve an existing interaction definition
+     * @param id of the interaction to retrieve
+     * @returns Interaction
+     **/
+    retrieve(id: string): Promise<Interaction> {
+        return this.get(`/${id}`);
+    }
+
+    /**
+     * Update an existing interaction definition
+     * @param id of the interaction to update
+     * @param payload InteractionUpdatePayload
+     * @returns Interaction
+     * @throws ApiError
+     * @throws 400 if payload is invalid
+     * @throws 500 if interaction update fails
+     * @throws 404 if interaction not found
+     **/
+    update(id: string, payload: InteractionUpdatePayload): Promise<Interaction> {
+        return this.put(`/${id}`, {
+            payload
+        });
+    }
+
+    /**
+     * 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
+     * @returns Promise<ExecutionRun>
+     * @throws ApiError
+     * @throws 404 if interaction not found
+     * @throws 400 if payload is invalid
+     * @throws 500 if interaction execution fails
+     * @throws 500 if interaction execution times out
+     **/
+    async execute<ResultT = any, ParamsT = any>(id: string, payload: InteractionExecutionPayload = {},
+        onChunk?: (chunk: string) => void): Promise<EnhancedInteractionExecutionResult<ResultT, ParamsT>> {
+        const r = await executeInteraction<ParamsT>(this.client as VertesiaClient, id, payload, onChunk).catch(err => {
+            if (err instanceof ServerError && err.payload?.id) {
+                throw err.updateDetails({ run_id: err.payload.id });
+            } else {
+                throw err;
+            }
+        });
+        return enhanceInteractionExecutionResult<ResultT, ParamsT>(r);
+    }
+
+    /**
+     * Same as execute 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 nameWithTag
+     * @param payload
+     * @param onChunk
+     * @returns
+     */
+    async executeByName<ResultT = any, ParamsT = any>(nameWithTag: string, payload: InteractionExecutionPayload = {},
+        onChunk?: (chunk: string) => void): Promise<EnhancedInteractionExecutionResult<ResultT, ParamsT>> {
+        const r = await executeInteractionByName<ParamsT>(this.client as VertesiaClient, nameWithTag, payload, onChunk).catch(err => {
+            if (err instanceof ServerError && err.payload?.id) {
+                throw err.updateDetails({ run_id: err.payload.id });
+            } else {
+                throw err;
+            }
+        });
+        return enhanceInteractionExecutionResult<ResultT, ParamsT>(r);
+    }
+
+    /**
+     * Execute an interaction in an workflow
+     * @param payload
+     * @returns
+     */
+    executeAsync(payload: AsyncExecutionPayload): Promise<AsyncExecutionResult> {
+        return executeInteractionAsync(this.client as VertesiaClient, payload);
+    }
+
+    publish(id: string, payload: InteractionPublishPayload): Promise<Interaction> {
+        return this.post(`/${id}/publish`, {
+            payload
+        });
+    }
+
+    fork(id: string, payload: InteractionForkPayload): Promise<Interaction> {
+        return this.post(`/${id}/fork`, {
+            payload
+        });
+    }
+
+    /**
+     * Generate Composable definition of an interaction
+     **/
+    generateInteraction(id: string, payload: GenerateInteractionPayload): Promise<any[]> {
+
+        return this.post(`${id}/generate-interaction`, {
+            payload
+        });
+
+    }
+
+    /**
+     * Generate Test Data for an interaction
+     **/
+    generateTestData(id: string, payload: GenerateTestDataPayload): Promise<any[]> {
+
+        return this.post(`${id}/generate-test-data`, {
+            payload
+        });
+    }
+
+    /**
+     * Suggest Improvement for a prompt
+     * @deprecated use suggestPromptImprovements instead
+     */
+    async suggestImprovements<ResultT = any, ParamsT = any>(id: string, payload: ImprovePromptPayloadConfig): Promise<EnhancedExecutionRun<ResultT, ParamsT>> {
+        const r = await this.post(`${id}/suggest-prompt-improvements`, {
+            payload
+        });
+        return enhanceExecutionRun<ResultT, ParamsT>(r);
+    }
+
+    async suggestPromptImprovements<ResultT = any, ParamsT = any>(payload: ImprovePromptPayload): Promise<EnhancedInteractionExecutionResult<ResultT, ParamsT>> {
+        const r = await this.post(`/improve`, {
+            payload
+        });
+        return enhanceInteractionExecutionResult<ResultT, ParamsT>(r);
+    }
+
+
+    /**
+     * List the versions of the interaction. Returns an empty array if no versions are found
+     * @param id
+     * @returns the versions list or an empty array if no versions are found
+     */
+    listVersions(id: string): Promise<InteractionRef[]> {
+        return this.get(`/${id}/versions`);
+    }
+
+    /**
+     * List the forks of the interaction. Returns an empty array if no forks are found
+     * @param id
+     * @returns the versions list or an empty array if no forks are found
+     */
+    listForks(id: string): Promise<InteractionRef[]> {
+        return this.get(`/${id}/forks`);
+    }
+
+    /**
+     * Request a time slot to execute an interaction with a given environment / model
+     * @param payload RateLimitRequestPayload
+     * @returns RateLimitRequestResponse with delay_ms
+     */
+    requestSlot(payload: RateLimitRequestPayload): Promise<RateLimitRequestResponse> {
+        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

@@ -0,0 +1,85 @@
+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) {
+        super(parent, "/api/v1/projects");
+    }
+
+    list(account?: string[]): Promise<ProjectRef[]> {
+        return this.get('/', { query: { account } });
+    }
+
+    retrieve(projectId: string): Promise<Project> {
+        return this.get(`/${projectId}`);
+    }
+
+    create(payload: ICreateProjectPayload): Promise<Project> {
+        return this.post('/', {
+            payload
+        });
+    }
+
+    update(projectId: string, payload: Partial<Project>): Promise<Project> {
+        return this.put(`/${projectId}`, {
+            payload
+        });
+    }
+
+    updateConfiguration(projectId: string, payload: Partial<ProjectConfiguration>): Promise<ProjectConfiguration> {
+        return this.put(`/${projectId}/configuration`, {
+            payload
+        });
+    }
+
+    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 {
+
+    constructor(parent: ClientBase) {
+        super(parent, "/");
+    }
+
+    list(projectId: string): Promise<ProjectIntegrationListEntry[]> {
+        return this.get(`/${projectId}/integrations`).then(res => res.integrations);
+    }
+
+    retrieve(projectId: string, integrationId: SupportedIntegrations): Promise<GladiaConfiguration | GithubConfiguration | AwsConfiguration | MagicPdfConfiguration | undefined> {
+        return this.get(`/${projectId}/integrations/${integrationId}`).catch(err => {
+            if (err.status === 404) {
+                return undefined;
+            }
+            throw err;
+        });
+    }
+
+    update(projectId: string, integrationId: string, payload: any): Promise<GladiaConfiguration | GithubConfiguration> {
+        return this.put(`/${projectId}/integrations/${integrationId}`, {
+            payload
+        });
+    }
+
+}

package/src/PromptsApi.ts

@@ -0,0 +1,160 @@
+import { ComputePromptFacetPayload, PromptSearchPayload, PromptSearchQuery, PromptTemplate, PromptTemplateForkPayload, PromptTemplateCreatePayload, PromptTemplateRef, PromptTemplateUpdatePayload } from "@vertesia/common";
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+
+export interface ComputePromptFacetsResponse {
+    role?: { _id: string, count: number }[];
+    total?: { count: number }[];
+}
+
+export default class PromptsApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/prompts")
+    }
+
+    /**
+     * Get the list of all prompt templates
+     * @param payload query payload to filter search
+     * @returns PromptTemplateRef[]
+     **/
+    list(payload: PromptSearchPayload = {}): Promise<PromptTemplateRef[]> {
+        const query = payload.query || {} as PromptSearchQuery;
+
+        return this.get("/", {
+            query: {
+                ...query
+            }
+        });
+    }
+
+    /**
+     * Get the list of all prompt facets
+     * @param payload query payload to filter facet search
+     * @returns ComputePromptFacetsResponse[]
+     **/
+    computeFacets(query: ComputePromptFacetPayload): Promise<ComputePromptFacetsResponse> {
+        return this.post("/facets", {
+            payload: query
+        });
+    }
+
+    /**
+     * Create a new prompt template
+     * @param payload PromptTemplateCreatePayload
+     * @returns PromptTemplate
+     * @throws ApiError
+     * @throws 400 if payload is invalid
+     * @throws 500 if creation fails
+     **/
+    create(payload: PromptTemplateCreatePayload): Promise<PromptTemplate> {
+        return this.post('/', {
+            payload
+        });
+    }
+
+    /**
+     * Retrieve an existing prompt template
+     * @param id of the prompt template to retrieve
+     * @returns PromptTemplate
+     **/
+    retrieve(id: string): Promise<PromptTemplate> {
+        return this.get(`/${id}`);
+    }
+
+    /**
+     * Update an existing prompt template
+     * @param id of the prompt template to update
+     * @param payload PromptTemplateCreatePayload
+     * @returns PromptTemplate
+     * @throws ApiError
+     * @throws 400 if payload is invalid
+     * @throws 500 if update fails
+     * @throws 404 if not found
+     **/
+    update(id: string, payload: PromptTemplateUpdatePayload): Promise<PromptTemplate> {
+        return this.put(`/${id}`, {
+            payload
+        });
+    }
+
+    /**
+     * Delete an existing prompt template
+     * @param id of the prompt template to delete
+     * @returns void
+     */
+    delete(id: string): Promise<void> {
+        return this.del(`/${id}`);
+    }
+
+    /**
+     * Fork an existing prompt template
+     * @param id of the prompt template to fork
+     * @param payload PromptTemplateForkPayload
+     * @returns Forked PromptTemplate
+     */
+    fork(id: string, payload: PromptTemplateForkPayload): Promise<PromptTemplate> {
+        return this.post(`/${id}/fork`, {
+            payload
+        });
+    }
+
+    /**
+     * Render a prompt template
+     * @param id of the prompt template to render
+     * @param payload that will be passed to the prompt template to generate the prompts
+     * @returns PromptTemplate
+     * @throws ApiError
+     * @throws 404 if not found
+     * @throws 400 if payload is invalid
+     * @throws 500 if render fails
+     **/
+    render(id: string, payload: {}): Promise<PromptTemplate> {
+        return this.post(`/${id}/render`, {
+            payload
+        });
+    }
+
+    /**
+     * Get options for a field
+     * @param field name to get options for
+     * @returns string[]
+     */
+    options(field: string): Promise<string[]> {
+        return this.get(`/options/${field}`);
+    }
+
+    /**
+     * List the versions of the prompt template. Returns an empty array if no versions are found
+     * @param id
+     * @returns the versions list or an empty array if no versions are found
+     */
+    listVersions(id: string): Promise<PromptTemplateRef[]> {
+        return this.get(`/${id}/versions`);
+    }
+
+
+    /**
+     * Retrieve list of interactions that use the prompt template
+     */
+    listInteractions(id: string): Promise<ListInteractionsResponse> {
+        return this.get(`/${id}/interactions`);
+    }
+
+    /**
+     * List the forks of the prompt. Returns an empty array if no forks are found
+     * @param id of the prompt to search forks
+     * @returns the versions list or an empty array if no forks are found
+     */
+    listForks(id: string): Promise<PromptTemplateRef[]> {
+        return this.get(`/${id}/forks`);
+    }
+
+}
+
+export interface ListInteractionsResponse {
+    prompt: string,
+    interactions: {
+        id: string,
+        name: string,
+        versions: string[],
+    }[]
+}