@vertesia/client 0.24.0-dev.202601221707

package/src/store/ObjectsApi.ts

@@ -0,0 +1,432 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    canGenerateRendition,
+    ContentObjectApiHeaders,
+    ComplexSearchPayload,
+    ComputeObjectFacetPayload,
+    ContentObject,
+    ContentObjectItem,
+    ContentObjectProcessingPriority,
+    ContentSource,
+    CreateContentObjectPayload,
+    Embedding,
+    ExportPropertiesPayload,
+    ExportPropertiesResponse,
+    FindPayload,
+    GetFileUrlPayload,
+    GetFileUrlResponse,
+    GetRenditionParams,
+    GetRenditionResponse,
+    getSupportedRenditionFormats,
+    GetUploadUrlPayload,
+    ListWorkflowRunsResponse,
+    ObjectSearchPayload,
+    ObjectSearchQuery,
+    SupportedEmbeddingTypes,
+    supportsVisualRendition,
+} from "@vertesia/common";
+
+// Re-export rendition utilities for consumers
+export { canGenerateRendition, getSupportedRenditionFormats, supportsVisualRendition };
+
+import { StreamSource } from "../StreamSource.js";
+import { AnalyzeDocApi } from "./AnalyzeDocApi.js";
+import { ZenoClient } from "./client.js";
+
+export interface ComputeFacetsResponse {
+    type?: { _id: string; count: number }[];
+    location?: { _id: string; count: number }[];
+    status?: { _id: string; count: number }[];
+    total?: number;
+}
+
+export interface SearchResponse {
+    results: ContentObjectItem[];
+    facets: ComputeFacetsResponse;
+}
+
+export class ObjectsApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/objects");
+    }
+
+    analyze(objectId: string) {
+        return new AnalyzeDocApi(this, objectId);
+    }
+
+    getUploadUrl(payload: GetUploadUrlPayload): Promise<GetFileUrlResponse> {
+        return this.post("/upload-url", {
+            payload,
+        });
+    }
+
+    getDownloadUrl(fileUri: string, name?: string, disposition?: "inline" | "attachment"): Promise<{ url: string }> {
+        return this.post("/download-url", {
+            payload: { file: fileUri, name, disposition } satisfies GetFileUrlPayload,
+        });
+    }
+
+    getDownloadUrlWithOptions(payload: GetFileUrlPayload): Promise<{ url: string }> {
+        return this.post("/download-url", { payload });
+    }
+
+    getContentSource(objectId: string): Promise<ContentSource> {
+        return this.get(`/${objectId}/content-source`);
+    }
+
+    /**
+     * 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);
+
+        return this.get("/", {
+            query: {
+                limit,
+                offset,
+                ...query,
+                all_revisions: payload.all_revisions,
+                from_root: payload.from_root || undefined,
+            },
+        });
+    }
+
+    computeFacets(
+        query: ComputeObjectFacetPayload,
+    ): Promise<ComputeFacetsResponse> {
+        return this.post("/facets", {
+            payload: query,
+        });
+    }
+
+    listFolders(path: string = "/") {
+        path; //TODO
+    }
+
+    /** Find object based on query */
+    find(payload: FindPayload): Promise<ContentObject[]> {
+        return this.post("/find", {
+            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<SearchResponse> {
+        return this.post("/search", {
+            payload,
+        });
+    }
+
+    retrieve(id: string, select?: string): Promise<ContentObject> {
+        return this.get(`/${id}`, {
+            query: {
+                select,
+            },
+        });
+    }
+
+    getObjectText(id: string): Promise<{ text: string }> {
+        return this.get(`/${id}/text`);
+    }
+
+    async upload(source: StreamSource | File) {
+        const isStream = source instanceof StreamSource;
+        // get a signed URL to upload the file a computed mimeType and the file object id.
+        const { url, id, mime_type } = await this.getUploadUrl({
+            id: isStream ? source.id : undefined,
+            name: source.name,
+            mime_type: source.type,
+        });
+
+        // upload the file content to the signed URL
+        /*const res = await this.fetch(url, {
+            method: 'PUT',
+            //@ts-ignore: duplex is not in the types. See https://github.com/node-fetch/node-fetch/issues/1769
+            duplex: isStream ? "half" : undefined,
+            body: isStream ? source.stream : source,
+            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}`);
+            }
+        });*/
+
+        const res = await fetch(url, {
+            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;
+            });
+
+        //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,
+        };
+    }
+
+    async create(
+        payload: CreateContentObjectPayload,
+        options?: {
+            collection_id?: string;
+            processing_priority?: ContentObjectProcessingPriority;
+        },
+    ): Promise<ContentObject> {
+        const createPayload: CreateContentObjectPayload = {
+            ...payload,
+        };
+        if (
+            payload.content instanceof StreamSource ||
+            payload.content instanceof File
+        ) {
+            createPayload.content = await this.upload(payload.content);
+        }
+
+        const headers: Record<string, string> = {};
+        if (options?.processing_priority) {
+            headers[ContentObjectApiHeaders.PROCESSING_PRIORITY] = options.processing_priority;
+        } 
+        if (options?.collection_id) {
+            headers[ContentObjectApiHeaders.COLLECTION_ID] = options.collection_id;
+        }
+
+        return await this.post("/", {
+            payload: createPayload,
+            headers: headers,
+        });
+    }
+
+    /**
+     * Create an object which holds a reference to an external blob (i.e. not in the project bucket)
+     * The uri should starts either with gs:// or s3://. Not other protocols are supported yet.
+     * For the s3 blobs you must use a hash with the blob #region. Ex: s3://bucket/path/to/file#us-east-1
+     * @param uri
+     * @param payload
+     * @param options
+     * @returns
+     */
+    async createFromExternalSource(
+        uri: string,
+        payload: CreateContentObjectPayload = {},
+        options?: {
+            collection_id?: string;
+            processing_priority?: ContentObjectProcessingPriority;
+        },
+    ): Promise<ContentObject> {
+        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,
+            },
+        };
+
+        const headers: Record<string, string> = {};
+        if (options?.processing_priority) {
+            headers[ContentObjectApiHeaders.PROCESSING_PRIORITY] = options.processing_priority;
+        } 
+        if (options?.collection_id) {
+            headers[ContentObjectApiHeaders.COLLECTION_ID] = options.collection_id;
+        }
+
+        return await this.post("/", {
+            payload: createPayload,
+            headers: headers,
+        });
+    }
+
+    /**
+     * 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")
+     * @param options.suppressWorkflows When true, prevents this update from triggering workflow rules
+     * @returns The updated object or newly created revision
+     */
+    async update(
+        id: string,
+        payload: Partial<CreateContentObjectPayload>,
+        options?: {
+            createRevision?: boolean;
+            revisionLabel?: string;
+            processing_priority?: ContentObjectProcessingPriority;
+            suppressWorkflows?: boolean;
+        },
+    ): 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);
+        }
+
+        const headers: Record<string, string> = {};
+        if (options?.processing_priority) {
+            headers[ContentObjectApiHeaders.PROCESSING_PRIORITY] = options.processing_priority;
+        }
+        if (options?.createRevision) {
+            headers[ContentObjectApiHeaders.CREATE_REVISION] = "true";
+            if (options.revisionLabel) {
+                headers[ContentObjectApiHeaders.REVISION_LABEL] = options.revisionLabel;
+            }
+        }
+        if (options?.suppressWorkflows) {
+            headers[ContentObjectApiHeaders.SUPPRESS_WORKFLOWS] = "true";
+        }
+
+        return this.put(`/${id}`, {
+            payload: updatePayload,
+            headers,
+        });
+    }
+
+    /**
+     * 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`);
+    }
+
+    /**
+     * Retrieves all collections that contain a specific object
+     *
+     * @param id The ID of the object
+     * @returns Array of collections containing this object (both static and dynamic)
+     */
+    getCollections(id: string): Promise<any[]> {
+        return this.get(`/${id}/collections`);
+    }
+
+    delete(id: string): Promise<{ id: string }> {
+        return this.del(`/${id}`);
+    }
+
+    listWorkflowRuns(documentId: string): Promise<ListWorkflowRunsResponse> {
+        return this.get(`/${documentId}/workflow-runs`);
+    }
+
+    listRenditions(documentId: string): Promise<ContentObjectItem[]> {
+        return this.get(`/${documentId}/renditions`);
+    }
+
+    getRendition(
+        documentId: string,
+        options: GetRenditionParams,
+    ): Promise<GetRenditionResponse> {
+        const query = {
+            max_hw: options.max_hw,
+            generate_if_missing: options.generate_if_missing,
+            sign_url: options.sign_url,
+            block_on_generation: options.block_on_generation,
+        };
+
+        return this.get(`/${documentId}/renditions/${options.format}`, {
+            query,
+        });
+    }
+
+    /**
+     * Get rendition with pre-validation of content type compatibility.
+     * Returns null instead of throwing if the format is not supported for the content type.
+     *
+     * @param documentId - The document ID
+     * @param contentType - The content type of the document (e.g., 'image/png', 'text/markdown')
+     * @param options - Rendition options including format
+     * @returns The rendition response, or null if format is not supported for the content type
+     *
+     * @example
+     * const rendition = await client.objects.getRenditionSafe(docId, doc.content?.type, {
+     *     format: ImageRenditionFormat.jpeg,
+     *     generate_if_missing: true
+     * });
+     * if (!rendition) {
+     *     console.log('Document does not support JPEG renditions');
+     * }
+     */
+    getRenditionSafe(
+        documentId: string,
+        contentType: string | undefined,
+        options: GetRenditionParams,
+    ): Promise<GetRenditionResponse | null> {
+        if (!canGenerateRendition(contentType, options.format)) {
+            return Promise.resolve(null);
+        }
+        return this.getRendition(documentId, options);
+    }
+
+    exportProperties(
+        payload: ExportPropertiesPayload,
+    ): Promise<ExportPropertiesResponse> {
+        return this.post("/export", {
+            payload,
+        });
+    }
+
+    setEmbedding(
+        id: string,
+        type: SupportedEmbeddingTypes,
+        payload: Embedding,
+    ): Promise<Record<SupportedEmbeddingTypes, Embedding>> {
+        return this.put(`/${id}/embeddings/${type}`, {
+            payload,
+        });
+    }
+}

package/src/store/PendingAsksApi.ts

@@ -0,0 +1,98 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import { ListPendingAsksResponse, PendingAskData, UserChannel } from "@vertesia/common";
+
+/**
+ * Request to register a pending ask.
+ */
+export interface RegisterPendingAskRequest {
+    /** Temporal workflow run ID */
+    runId: string;
+    /** Temporal workflow ID */
+    workflowId: string;
+    /** Name of the agent/interaction */
+    agentName: string;
+    /** Questions asked by the agent */
+    questions: string[];
+    /** Timeout in hours (default 48) */
+    timeoutHours?: number;
+    /** User communication channels */
+    userChannels: UserChannel[];
+}
+
+/**
+ * Response from registering a pending ask.
+ */
+export interface RegisterPendingAskResponse {
+    /** Whether registration succeeded */
+    success: boolean;
+    /** Generated ask ID */
+    askId?: string;
+    /** Whether webhook was sent */
+    webhookSent?: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+
+/**
+ * Request to resolve a pending ask.
+ */
+export interface ResolvePendingAskRequest {
+    /** User's response */
+    response: string;
+}
+
+/**
+ * Response from resolving a pending ask.
+ */
+export interface ResolvePendingAskResponse {
+    /** Whether resolution succeeded */
+    success: boolean;
+    /** Whether webhook was sent */
+    webhookSent?: boolean;
+    /** How long the user took to respond (ms) */
+    waitDurationMs?: number;
+    /** Error message if failed */
+    error?: string;
+}
+
+/**
+ * Pending Asks API for tracking ask_user requests.
+ * Handles registration, resolution, and listing of pending asks.
+ */
+export class PendingAsksApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/pending-asks");
+    }
+
+    /**
+     * Register a new pending ask.
+     * Called when an agent calls ask_user.
+     * Stores in Redis and sends webhook if configured.
+     */
+    register(request: RegisterPendingAskRequest): Promise<RegisterPendingAskResponse> {
+        return this.post("/", { payload: request });
+    }
+
+    /**
+     * Resolve a pending ask with the user's response.
+     * Called when a user responds to an ask.
+     * Updates Redis and sends webhook if configured.
+     */
+    resolve(askId: string, request: ResolvePendingAskRequest): Promise<ResolvePendingAskResponse> {
+        return this.post(`/${askId}/resolve`, { payload: request });
+    }
+
+    /**
+     * List all pending asks for the current project.
+     */
+    list(): Promise<ListPendingAsksResponse> {
+        return this.get("/");
+    }
+
+    /**
+     * Get a specific pending ask by ID.
+     */
+    retrieve(askId: string): Promise<PendingAskData> {
+        return this.get(`/${askId}`);
+    }
+}

package/src/store/SchedulesApi.ts

@@ -0,0 +1,114 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    AgentSchedule,
+    AgentScheduleWithTemporalInfo,
+    CreateSchedulePayload,
+    ScheduleListItem,
+    UpdateSchedulePayload,
+} from "@vertesia/common";
+
+/**
+ * Client API for managing agent schedules.
+ *
+ * Schedules allow agents to run on a recurring basis using cron expressions.
+ */
+export class SchedulesApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/schedules");
+    }
+
+    /**
+     * List all schedules in the project.
+     */
+    list(): Promise<ScheduleListItem[]> {
+        return this.get("/");
+    }
+
+    /**
+     * Retrieve a schedule by ID.
+     * Includes Temporal execution info if available.
+     */
+    retrieve(id: string): Promise<AgentScheduleWithTemporalInfo> {
+        return this.get(`/${id}`);
+    }
+
+    /**
+     * Create a new schedule.
+     *
+     * @param payload - Schedule configuration including name, interaction, and cron expression
+     * @returns The created schedule
+     *
+     * @example
+     * ```typescript
+     * const schedule = await client.schedules.create({
+     *   name: 'Weekly Report',
+     *   interaction: 'WeeklyReportAgent',
+     *   cron_expression: '0 9 * * MON', // Every Monday at 9am
+     *   timezone: 'America/New_York',
+     *   vars: { reportType: 'summary' }
+     * });
+     * ```
+     */
+    create(payload: CreateSchedulePayload): Promise<AgentSchedule> {
+        return this.post("/", { payload });
+    }
+
+    /**
+     * Update an existing schedule.
+     *
+     * @param id - Schedule ID
+     * @param payload - Fields to update
+     * @returns The updated schedule
+     */
+    update(id: string, payload: UpdateSchedulePayload): Promise<AgentSchedule> {
+        return this.put(`/${id}`, { payload });
+    }
+
+    /**
+     * Delete a schedule.
+     *
+     * This also removes the corresponding Temporal schedule.
+     *
+     * @param id - Schedule ID
+     * @returns Object with the deleted schedule ID
+     */
+    delete(id: string): Promise<{ id: string }> {
+        return this.del(`/${id}`);
+    }
+
+    /**
+     * Trigger an immediate execution of the scheduled agent.
+     *
+     * This runs the agent immediately without waiting for the next scheduled time.
+     *
+     * @param id - Schedule ID
+     * @returns Success message
+     */
+    trigger(id: string): Promise<{ message: string }> {
+        return this.post(`/${id}/trigger`, {});
+    }
+
+    /**
+     * Pause a schedule.
+     *
+     * The schedule will not run until resumed.
+     *
+     * @param id - Schedule ID
+     * @param note - Optional note explaining why the schedule was paused
+     * @returns Success message
+     */
+    pause(id: string, note?: string): Promise<{ message: string }> {
+        return this.post(`/${id}/pause`, { payload: { note } });
+    }
+
+    /**
+     * Resume a paused schedule.
+     *
+     * @param id - Schedule ID
+     * @param note - Optional note explaining why the schedule was resumed
+     * @returns Success message
+     */
+    resume(id: string, note?: string): Promise<{ message: string }> {
+        return this.post(`/${id}/resume`, { payload: { note } });
+    }
+}

package/src/store/ToolsApi.ts

@@ -0,0 +1,19 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import type { BuiltinToolsCatalogResponse } from "@vertesia/common";
+
+/**
+ * API for accessing the builtin tools catalog
+ */
+export class ToolsApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/tools");
+    }
+
+    /**
+     * Get the builtin tools catalog
+     * @returns List of all available builtin tools with their descriptions and parameter schemas
+     */
+    getBuiltinCatalog(): Promise<BuiltinToolsCatalogResponse> {
+        return this.get('/');
+    }
+}