@vertesia/client 0.53.0 → 0.54.0

package/LICENSE

@@ -1,13 +1,13 @@
-Copyright 2024 Composable
+Copyright 2024 Composable Prompts
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
 
-    http://www.apache.org/licenses/LICENSE-2.0
+http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
-limitations under the License.
+limitations under the License.

package/package.json

@@ -1,24 +1,24 @@
 {
   "name": "@vertesia/client",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "type": "module",
   "types": "./lib/types/index.d.ts",
   "files": [
     "lib",
     "src"
   ],
+  "license": "Apache-2.0",
   "devDependencies": {
-    "@types/eventsource": "^1.1.14",
     "@types/node": "^22.13.5",
     "ts-dual-module": "^0.6.3",
     "typescript": "^5.0.2",
     "vitest": "^3.0.9"
   },
   "dependencies": {
-    "eventsource": "^2.0.2",
-    "@vertesia/api-fetch-client": "0.52.0",
+    "eventsource": "^3.0.6",
+    "@vertesia/common": "0.54.0",
     "@llumiverse/core": "0.17.0",
-    "@vertesia/common": "0.52.0"
+    "@vertesia/api-fetch-client": "0.54.0"
   },
   "ts_dual_module": {
     "outDir": "lib"

package/src/ApiKeysApi.ts

@@ -50,7 +50,7 @@ export class ApiKeysApi extends ApiTopic {
     }
 
     /**
-     * get or create a temporary public key which can be used from browser to browse and execute itneractions.
+     * get or create a temporary public key which can be used from browser to browse and execute interactions.
      * If a public key already exists for the given project (or for the current organization) then it is returned, otherwise a new one is created.
      * The payload object can contain the following properties:
      * - name: the name of the public key. If not specified a random name is generated.

package/src/EnvironmentsApi.ts

@@ -34,8 +34,8 @@ export default class EnvironmentsApi extends ApiTopic {
     }
 
     /**
-     * udpate enabled models and / or config. If enabled_models is not provided, the existing enabled models will not change.
-     * Same, if config is not provioded the exiting config is not changed.
+     * Update enabled models and / or config. If enabled_models is not provided, the existing enabled models will not change.
+     * Same, if config is not provided the exiting config is not changed.
      * If the config is provided then it will be updated without removing fields that are not provided.
      *
      * @param id

package/src/InteractionBase.ts

@@ -31,7 +31,7 @@ export class InteractionBase<P = any, R = any> {
      * 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 fucntion will return the resolved promise
+     * 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

package/src/InteractionsApi.ts

@@ -32,7 +32,7 @@ export default class InteractionsApi extends ApiTopic {
         });
     }
     /**
-     * Find interractions given a mongo match query.
+     * Find interactions given a mongo match query.
      * You can also specify if prompts schemas are included in the result
      */
     listEndpoints(payload: InteractionEndpointQuery): Promise<InteractionRef[]> {
@@ -92,7 +92,7 @@ export default class InteractionsApi extends ApiTopic {
     }
 
     /**
-     * Retrieve an existing interaction definiton
+     * Retrieve an existing interaction definition
      * @param id of the interaction to retrieve
      * @returns Interaction
      **/
@@ -101,7 +101,7 @@ export default class InteractionsApi extends ApiTopic {
     }
 
     /**
-     * Update an existing interaction definiton
+     * Update an existing interaction definition
      * @param id of the interaction to update
      * @param payload InteractionUpdatePayload
      * @returns Interaction
@@ -121,7 +121,7 @@ export default class InteractionsApi extends ApiTopic {
      * 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 fucntion will return the resolved promise
+     * 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
@@ -146,7 +146,7 @@ export default class InteractionsApi extends ApiTopic {
     /**
      * Same as execute but uses the interaction name selector instead of the id.
      *
-     * A name selector is the interaction endpoint name suffuxed with an optional tag or version wich is starting with a `@` character.
+     * 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

package/src/PluginsApi.ts

@@ -0,0 +1,28 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import type { PluginManifest } from "@vertesia/common";
+
+export default class PluginsApi extends ApiTopic {
+
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/plugins")
+    }
+
+    create(manifest: Omit<PluginManifest, 'id'>): Promise<PluginManifest> {
+        return this.post('/', { payload: manifest });
+    }
+
+    update(manifest: PluginManifest) {
+        return this.put(`/${manifest.id}`, { payload: manifest });
+    }
+
+    /**
+     * If a project ID is specified through the project query param
+     * then only the plugins that are enabled on the project are returned.
+     * @param query
+     * @returns
+     */
+    list(): Promise<PluginManifest[]> {
+        return this.get('/');
+    }
+
+}

package/src/ProjectsApi.ts

@@ -1,5 +1,5 @@
 import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
-import { AwsConfiguration, GithubConfiguration, GladiaConfiguration, ICreateProjectPayload, MacgicPdfConfiguration, Project, ProjectIntegrationListEntry, ProjectRef, SupportedIntegrations } from "@vertesia/common";
+import { AwsConfiguration, GithubConfiguration, GladiaConfiguration, ICreateProjectPayload, MagicPdfConfiguration, PluginManifest, Project, ProjectIntegrationListEntry, ProjectRef, SupportedIntegrations } from "@vertesia/common";
 
 export default class ProjectsApi extends ApiTopic {
     constructor(parent: ClientBase) {
@@ -26,6 +26,14 @@ export default class ProjectsApi extends ApiTopic {
         });
     }
 
+    listPlugins(projectId: string): Promise<PluginManifest[]> {
+        return this.get(`/${projectId}/plugins`);
+    }
+
+    setPlugins(projectId: string, pluginIds: string[]): Promise<{ count: number }> {
+        return this.post(`/${projectId}/plugins`, { payload: { plugins: pluginIds } });
+    }
+
     integrations: IntegrationsConfigurationApi = new IntegrationsConfigurationApi(this);
 
 }
@@ -40,7 +48,7 @@ class IntegrationsConfigurationApi extends ApiTopic {
         return this.get(`/${projectId}/integrations`).then(res => res.integrations);
     }
 
-    retrieve(projectId: string, integrationId: SupportedIntegrations): Promise<GladiaConfiguration | GithubConfiguration | AwsConfiguration | MacgicPdfConfiguration | undefined> {
+    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;

package/src/PromptsApi.ts

@@ -123,7 +123,7 @@ export default class PromptsApi extends ApiTopic {
     }
 
     /**
-     * List the versions of the prompt template. Returens an empty array if no versions are found
+     * 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
      */

package/src/client.ts

@@ -15,6 +15,7 @@ import { RunsApi } from "./RunsApi.js";
 import { ZenoClient } from "./store/client.js";
 import TrainingApi from "./TrainingApi.js";
 import UsersApi from "./UsersApi.js";
+import PluginsApi from "./PluginsApi.js";
 
 /**
  * 1 min threshold constant in ms
@@ -218,6 +219,7 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
     iam = new IamApi(this);
     refs = new RefsApi(this);
     commands = new CommandsApi(this);
+    plugins = new PluginsApi(this);
 }
 
 function isApiKey(apiKey: string) {

package/src/execute.ts

@@ -1,11 +1,11 @@
 import { AsyncExecutionPayload, ExecutionRunStatus, InteractionExecutionPayload, InteractionExecutionResult, NamedInteractionExecutionPayload } from '@vertesia/common';
 import { VertesiaClient } from './client.js';
 
-export function EventSourceProvider(): Promise<typeof EventSource> {
+export async function EventSourceProvider(): Promise<typeof EventSource> {
     if (typeof globalThis.EventSource === 'function') {
-        return Promise.resolve(globalThis.EventSource)
+        return globalThis.EventSource;
     } else {
-        return import('eventsource').then(module => module.default as unknown as typeof EventSource);
+        return (await import('eventsource')).EventSource;
     }
 }
 /**
@@ -14,7 +14,7 @@ export function EventSourceProvider(): Promise<typeof EventSource> {
  * 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 fucntion will return the resolved promise
+ * 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
@@ -38,7 +38,7 @@ export async function executeInteraction<P = any, R = any>(client: VertesiaClien
 
 /**
  * Same as executeInteraction but uses the interaction name selector instead of the id.
- * A name selector is the interaction endpoint name suffuxed with an optional tag or version wich is starting with a `@` character.
+ * 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

package/src/store/ObjectsApi.ts

@@ -1,35 +1,54 @@
-import { ApiTopic, ClientBase } from '@vertesia/api-fetch-client';
-import { ComplexSearchPayload, ComputeObjectFacetPayload, ContentObject, ContentObjectItem, ContentSource, CreateContentObjectPayload, Embedding, ExportPropertiesPayload, ExportPropertiesResponse, FindPayload, GetFileUrlPayload, GetFileUrlResponse, GetRenditionResponse, GetUploadUrlPayload, ListWorkflowRunsResponse, ObjectSearchPayload, ObjectSearchQuery, SupportedEmbeddingTypes } from '@vertesia/common';
-
-import { StreamSource } from '../StreamSource.js';
-import { ZenoClient } from './client.js';
-import { AnalyzeDocApi } from './AnalyzeDocApi.js';
-
-export interface UploadContentObjectPayload extends Omit<CreateContentObjectPayload, 'content'> {
-    content?: StreamSource | File | {
-
-        // the source URI
-        source: string,
-        // the original name of the input file if any
-        name?: string,
-        // the mime type of the content source.
-        type?: string
-
-        // the target id in the content store
-        id?: string
-
-    }
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    ComplexSearchPayload,
+    ComputeObjectFacetPayload,
+    ContentObject,
+    ContentObjectItem,
+    ContentSource,
+    CreateContentObjectPayload,
+    Embedding,
+    ExportPropertiesPayload,
+    ExportPropertiesResponse,
+    FindPayload,
+    GetFileUrlPayload,
+    GetFileUrlResponse,
+    GetRenditionResponse,
+    GetUploadUrlPayload,
+    ListWorkflowRunsResponse,
+    ObjectSearchPayload,
+    ObjectSearchQuery,
+    SupportedEmbeddingTypes,
+} from "@vertesia/common";
+
+import { StreamSource } from "../StreamSource.js";
+import { ZenoClient } from "./client.js";
+import { AnalyzeDocApi } from "./AnalyzeDocApi.js";
+
+export interface UploadContentObjectPayload extends Omit<CreateContentObjectPayload, "content"> {
+    content?:
+        | StreamSource
+        | File
+        | {
+              // the source URI
+              source: string;
+              // the original name of the input file if any
+              name?: string;
+              // the mime type of the content source.
+              type?: string;
+
+              // the target id in the content store
+              id?: string;
+          };
 }
 
 export interface ComputeFacetsResponse {
-    type?: { _id: string, count: number }[];
-    location?: { _id: string, count: number }[];
-    status?: { _id: string, count: number }[];
+    type?: { _id: string; count: number }[];
+    location?: { _id: string; count: number }[];
+    status?: { _id: string; count: number }[];
     total?: { count: number }[];
 }
 
 export class ObjectsApi extends ApiTopic {
-
     constructor(parent: ClientBase) {
         super(parent, "/api/v1/objects");
     }
@@ -39,64 +58,85 @@ export class ObjectsApi extends ApiTopic {
     }
 
     getUploadUrl(payload: GetUploadUrlPayload): Promise<GetFileUrlResponse> {
-        return this.post('/upload-url', {
-            payload
-        })
+        return this.post("/upload-url", {
+            payload,
+        });
     }
 
     getDownloadUrl(fileUri: string): Promise<{ url: string }> {
-        return this.post('/download-url', {
+        return this.post("/download-url", {
             payload: {
-                file: fileUri
-            } satisfies GetFileUrlPayload
-        })
+                file: fileUri,
+            } satisfies GetFileUrlPayload,
+        });
     }
 
     getContentSource(objectId: string): Promise<ContentSource> {
         return this.get(`/${objectId}/content-source`);
     }
 
-    list(payload: ObjectSearchPayload = {}): Promise<ContentObjectItem[]> {
+    /**
+     * List objects with revision filtering options
+     *
+     * @param payload Search/filter parameters
+     * @returns Matching content objects
+     */
+    list<T = any>(payload: ObjectSearchPayload = {}): Promise<ContentObjectItem<T>[]> {
         const limit = payload.limit || 100;
         const offset = payload.offset || 0;
-        const query = payload.query || {} as ObjectSearchQuery;
+        const query = payload.query || ({} as ObjectSearchQuery);
+
+        // Add revision filtering options
+        const showAllRevisions = payload.show_all_revisions === true;
+        const revisionRoot = payload.from_root;
 
         return this.get("/", {
             query: {
                 limit,
                 offset,
-                ...query
-            }
+                ...query,
+                show_all_revisions: showAllRevisions ? "true" : undefined,
+                from_root: revisionRoot,
+            },
         });
     }
 
     computeFacets(query: ComputeObjectFacetPayload): Promise<ComputeFacetsResponse> {
         return this.post("/facets", {
-            payload: query
+            payload: query,
         });
     }
 
-    listFolders(path: string = '/') {
-        path;//TODO
+    listFolders(path: string = "/") {
+        path; //TODO
     }
 
+    /** Find object based on query */
     find(payload: FindPayload): Promise<ContentObject[]> {
         return this.post("/find", {
-            payload
+            payload,
         });
     }
 
+    /** Count number of objects matching this query */
+    count(payload: FindPayload): Promise<{ count: number }> {
+        return this.post("/count", {
+            payload,
+        });
+    }
+
+    /** Search object — different from find because allow full text search */
     search(payload: ComplexSearchPayload): Promise<ContentObjectItem[]> {
         return this.post("/search", {
-            payload
+            payload,
         });
     }
 
     retrieve(id: string, select?: string): Promise<ContentObject> {
         return this.get(`/${id}`, {
             query: {
-                select
-            }
+                select,
+            },
         });
     }
 
@@ -110,10 +150,10 @@ export class ObjectsApi extends ApiTopic {
         const { url, id, mime_type } = await this.getUploadUrl({
             id: isStream ? source.id : undefined,
             name: source.name,
-            mime_type: source.type
+            mime_type: source.type,
         });
 
-        console.log(`Uploading file to ${url}`, { id, mime_type, isStream, source })
+        console.log(`Uploading content to ${url}`, { id, mime_type, isStream, source });
 
         // upload the file content to the signed URL
         /*const res = await this.fetch(url, {
@@ -134,44 +174,50 @@ export class ObjectsApi extends ApiTopic {
         });*/
 
         const res = await fetch(url, {
-            method: 'PUT',
+            method: "PUT",
             body: isStream ? source.stream : source,
             //@ts-ignore: duplex is not in the types. See https://github.com/node-fetch/node-fetch/issues/1769
             duplex: isStream ? "half" : undefined,
             headers: {
-                'Content-Type': mime_type || 'application/octet-stream'
-            }
-        }).then((res: Response) => {
-            if (res.ok) {
-                return res;
-            } else {
-                console.log(res);
-                throw new Error(`Failed to upload file: ${res.statusText}`);
-            }
-        }).catch(err => {
-            console.error('Failed to upload file', err);
-            throw err;
-        });
-
+                "Content-Type": mime_type || "application/octet-stream",
+            },
+        })
+            .then((res: Response) => {
+                if (res.ok) {
+                    return res;
+                } else {
+                    console.log(res);
+                    throw new Error(`Failed to upload file: ${res.statusText}`);
+                }
+            })
+            .catch((err) => {
+                console.error("Failed to upload file", err);
+                throw err;
+            });
+
+        //Etag need to be unquoted
+        //When a server returns an ETag header, it includes the quotes around the actual hash value.
+        //This is part of the HTTP specification (RFC 7232), which states that ETags should be
+        //enclosed in double quotes.
+        const etag = res.headers.get("etag")?.replace(/^"(.*)"$/, "$1");
 
         return {
             source: id,
             name: source.name,
             type: mime_type,
-            etag: res.headers.get('etag') ?? undefined
-        }
+            etag,
+        };
     }
 
     async create(payload: UploadContentObjectPayload): Promise<ContentObject> {
-
         const createPayload: CreateContentObjectPayload = {
-            ...payload
+            ...payload,
         };
         if (payload.content instanceof StreamSource || payload.content instanceof File) {
             createPayload.content = await this.upload(payload.content);
         }
-        return await this.post('/', {
-            payload: createPayload
+        return await this.post("/", {
+            payload: createPayload,
         });
     }
 
@@ -184,25 +230,72 @@ export class ObjectsApi extends ApiTopic {
      * @returns
      */
     async createFromExternalSource(uri: string, payload: CreateContentObjectPayload = {}): Promise<ContentObject> {
-        const metadata = await ((this.client as ZenoClient).files.getMetadata(uri));
+        const metadata = await (this.client as ZenoClient).files.getMetadata(uri);
         const createPayload: CreateContentObjectPayload = {
             ...payload,
             content: {
                 source: uri,
                 name: metadata.name,
                 type: metadata.contentType,
-                etag: metadata.etag
-            }
+                etag: metadata.etag,
+            },
         };
-        return await this.post('/', {
-            payload: createPayload
+        return await this.post("/", {
+            payload: createPayload,
         });
     }
 
-    update(id: string, payload: Partial<CreateContentObjectPayload>): Promise<ContentObject> {
-        return this.put(`/${id}`, {
-            payload
-        });
+    /**
+     * Updates an existing object or creates a new revision
+     * Handles file uploads similar to the create method
+     *
+     * @param id The ID of the object to update
+     * @param payload The changes to apply
+     * @param options Additional options
+     * @param options.createRevision Whether to create a new revision instead of updating in place
+     * @param options.revisionLabel Optional label for the revision (e.g., "v1.2")
+     * @returns The updated object or newly created revision
+     */
+    async update(
+        id: string,
+        payload: Partial<CreateContentObjectPayload>,
+        options?: {
+            createRevision?: boolean;
+            revisionLabel?: string;
+        },
+    ): Promise<ContentObject> {
+        const updatePayload: Partial<CreateContentObjectPayload> = {
+            ...payload,
+        };
+
+        // Handle file upload if content is provided as File or StreamSource
+        if (payload.content instanceof StreamSource || payload.content instanceof File) {
+            updatePayload.content = await this.upload(payload.content);
+        }
+
+        if (options?.createRevision) {
+            return this.put(`/${id}`, {
+                payload: updatePayload,
+                headers: {
+                    "x-create-revision": "true",
+                    "x-revision-label": options.revisionLabel || "",
+                },
+            });
+        } else {
+            return this.put(`/${id}`, {
+                payload: updatePayload,
+            });
+        }
+    }
+
+    /**
+     * Retrieves all revisions of a content object
+     *
+     * @param id The ID of any revision in the object's history
+     * @returns Array of all revisions sharing the same root
+     */
+    getRevisions(id: string): Promise<ContentObjectItem[]> {
+        return this.get(`/${id}/revisions`);
     }
 
     delete(id: string): Promise<{ id: string }> {
@@ -210,9 +303,7 @@ export class ObjectsApi extends ApiTopic {
     }
 
     listWorkflowRuns(documentId: string): Promise<ListWorkflowRunsResponse> {
-
-        return this.get(`/${documentId}/workflow-runs`)
-
+        return this.get(`/${documentId}/workflow-runs`);
     }
 
     listRenditions(documentId: string): Promise<ContentObjectItem[]> {
@@ -220,31 +311,33 @@ export class ObjectsApi extends ApiTopic {
     }
 
     getRendition(documentId: string, options: GetRenditionParams): Promise<GetRenditionResponse> {
-
         const query = {
             max_hw: options.max_hw,
-            generate_if_missing: options.generate_if_missing
-        }
+            generate_if_missing: options.generate_if_missing,
+        };
 
         return this.get(`/${documentId}/renditions/${options.format}`, { query });
     }
 
     exportProperties(payload: ExportPropertiesPayload): Promise<ExportPropertiesResponse> {
         return this.post("/export", {
-            payload
+            payload,
         });
     }
 
-    setEmbedding(id: string, type: SupportedEmbeddingTypes, payload: Embedding): Promise<Record<SupportedEmbeddingTypes, Embedding>> {
+    setEmbedding(
+        id: string,
+        type: SupportedEmbeddingTypes,
+        payload: Embedding,
+    ): Promise<Record<SupportedEmbeddingTypes, Embedding>> {
         return this.put(`/${id}/embeddings/${type}`, {
-            payload
+            payload,
         });
     }
-
 }
 
 interface GetRenditionParams {
     format: string;
     max_hw?: number;
     generate_if_missing?: boolean;
-}
+}