@vertesia/client 0.24.0-dev.202601221707

package/src/store/EmailApi.ts

@@ -0,0 +1,211 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import { EmailRouteData } from "@vertesia/common";
+
+/**
+ * Request payload for sending an email via the agent.
+ * Resend configuration is fetched from project settings.
+ * From address is constructed as: {project_namespace}+{agent_name}@{email_domain}
+ */
+export interface SendEmailRequest {
+    /** Email address to send to */
+    to_email: string;
+    /** Email subject */
+    subject: string;
+    /** Email body in markdown format */
+    body: string;
+    /** Agent/interaction endpoint name (used in from address) */
+    agent_name: string;
+    /** Display name for the sender (overrides project default) */
+    from_name?: string;
+    /** Workflow run ID for routing replies */
+    run_id: string;
+    /** Existing route key (for subsequent emails in same conversation) */
+    route_key?: string;
+    /** Message ID for In-Reply-To header (email threading) */
+    in_reply_to?: string;
+    /** Chain of message IDs for References header */
+    references?: string[];
+}
+
+/**
+ * Response from sending an email.
+ */
+export interface SendEmailResponse {
+    success: boolean;
+    /** Resend email ID */
+    email_id?: string;
+    /** Message-ID header for threading */
+    message_id?: string;
+    /** Short route key for reply routing */
+    route_key?: string;
+    /** Error message if failed */
+    error?: string;
+}
+
+/**
+ * Response from creating an email route.
+ */
+export interface CreateRouteResponse {
+    /** The generated route key (8-char alphanumeric) */
+    route_key: string;
+    /** Full reply-to address: r+{route_key}@{email_domain} */
+    reply_to: string;
+    /** The email domain for sending and receiving */
+    email_domain: string;
+}
+
+/**
+ * Request to forward an email to a workflow.
+ * Used by external services that handle email reception themselves.
+ */
+export interface ForwardEmailRequest {
+    /** Email content received by the external service */
+    email: {
+        /** Sender email address */
+        from: string;
+        /** Email subject */
+        subject?: string;
+        /** Plain text body */
+        text: string;
+        /** HTML body (optional) */
+        html?: string;
+        /** Message-ID header for threading */
+        message_id?: string;
+    };
+    /** Custom context data from the external service (e.g., auth tokens, user IDs) */
+    context?: Record<string, unknown>;
+    /** Attachments with download URLs */
+    attachments?: Array<{
+        filename: string;
+        content_type: string;
+        size: number;
+        download_url: string;
+    }>;
+}
+
+/**
+ * Response from forwarding an email.
+ */
+export interface ForwardEmailResponse {
+    success: boolean;
+    run_id: string;
+    workflow_id: string;
+    route_key: string;
+}
+
+/**
+ * Request to create an email route.
+ */
+export interface CreateRouteRequest {
+    /** Workflow run ID for routing replies */
+    run_id: string;
+    /** Email address of the user (for context) */
+    user_email: string;
+    /** Subject of the email thread (optional) */
+    thread_subject?: string;
+}
+
+/**
+ * Email API for sending emails from workflows.
+ */
+export class EmailApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/email");
+    }
+
+    /**
+     * Send an email from an agent/workflow.
+     * Creates a route key if not provided, sends via Resend, and returns routing info.
+     */
+    send(request: SendEmailRequest): Promise<SendEmailResponse> {
+        return this.post("/send", { payload: request });
+    }
+
+    /**
+     * Resolve a route key to get email context.
+     * Used by webhook handler to look up workflow info from reply email.
+     * @deprecated Use getRoute() instead
+     */
+    resolveRoute(routeKey: string): Promise<EmailRouteData> {
+        return this.post("/resolve-route", { payload: { route_key: routeKey } });
+    }
+
+    // ============================================================================
+    // Routes API - for external service integration
+    // ============================================================================
+
+    /**
+     * Create a new email route without sending an email.
+     * Useful for external services that want to handle email sending themselves
+     * but need reply routing back to Vertesia workflows.
+     *
+     * @example
+     * ```ts
+     * const { route_key, reply_to } = await client.store.email.createRoute({
+     *     run_id: workflowRunId,
+     *     user_email: "user@example.com",
+     *     thread_subject: "Contract Review"
+     * });
+     * // Use reply_to as the Reply-To header when sending your own email
+     * // Replies will be routed back to the workflow
+     * ```
+     */
+    createRoute(request: CreateRouteRequest): Promise<CreateRouteResponse> {
+        return this.post("/routes", { payload: request });
+    }
+
+    /**
+     * Get an email route by key.
+     */
+    getRoute(routeKey: string): Promise<EmailRouteData & { route_key: string }> {
+        return this.get(`/routes/${routeKey}`);
+    }
+
+    /**
+     * Update an email route (e.g., to update threading info).
+     */
+    updateRoute(routeKey: string, updates: Partial<EmailRouteData>): Promise<{ success: boolean; route_key: string }> {
+        return this.put(`/routes/${routeKey}`, { payload: updates });
+    }
+
+    /**
+     * Forward an email to a workflow via route key.
+     *
+     * Use this when your service receives an email reply and needs to forward
+     * it to the Vertesia workflow. You can add custom context data (like auth
+     * tokens or user IDs) that will be merged into `payload.vars.data`.
+     *
+     * **Important**: Use camelCase keys in context to match the agent start
+     * pattern. This ensures tools work identically whether the agent was
+     * started directly or received an email reply.
+     *
+     * @example
+     * ```ts
+     * // In your email webhook handler:
+     * const result = await client.store.email.forwardEmail(routeKey, {
+     *     email: {
+     *         from: inboundEmail.from,
+     *         subject: inboundEmail.subject,
+     *         text: inboundEmail.text,
+     *         message_id: inboundEmail.messageId,
+     *     },
+     *     context: {
+     *         // Use camelCase - merged into payload.vars.data
+     *         apiKey: generateServiceToken(),
+     *         tenantId: resolvedUser.tenantId,
+     *         userId: resolvedUser.id,
+     *         userEmail: resolvedUser.email,
+     *     },
+     *     attachments: inboundEmail.attachments?.map(att => ({
+     *         filename: att.filename,
+     *         content_type: att.contentType,
+     *         size: att.size,
+     *         download_url: att.url,
+     *     })),
+     * });
+     * ```
+     */
+    forwardEmail(routeKey: string, request: ForwardEmailRequest): Promise<ForwardEmailResponse> {
+        return this.post(`/routes/${routeKey}/forward`, { payload: request });
+    }
+}

package/src/store/EmbeddingsApi.ts

@@ -0,0 +1,39 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    EmbeddingsStatusResponse,
+    GenericCommandResponse,
+    ProjectConfigurationEmbeddings,
+    SupportedEmbeddingTypes,
+} from "@vertesia/common";
+
+/**
+ * @since 0.52.0
+ */
+export class EmbeddingsApi extends ApiTopic {
+
+    constructor(parent: ClientBase, basePath: string = "/api/v1/embeddings") {
+        super(parent, basePath);
+    }
+
+    async status(type: SupportedEmbeddingTypes): Promise<EmbeddingsStatusResponse> {
+        return this.get(type + "/status");
+    }
+
+    async activate(type: SupportedEmbeddingTypes, config: Partial<ProjectConfigurationEmbeddings>): Promise<GenericCommandResponse> {
+
+        if (!config.environment) {
+            throw new Error("Invalid configuration: select environment");
+        }
+
+        return this.post(type + "/enable", { payload: config });
+    }
+
+    async disable(type: SupportedEmbeddingTypes): Promise<GenericCommandResponse> {
+        return this.post(type + "/disable");
+    }
+
+    async recalculate(type: SupportedEmbeddingTypes): Promise<GenericCommandResponse> {
+        return this.post(type + "/recalculate");
+    }
+
+}

package/src/store/FilesApi.ts

@@ -0,0 +1,288 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    GetFileUrlPayload,
+    GetFileUrlResponse,
+    GetUploadUrlPayload,
+    SetFileMetadataPayload,
+} from "@vertesia/common";
+import { StreamSource } from "../StreamSource.js";
+
+export const MEMORIES_PREFIX = "memories";
+export const ARTIFACTS_PREFIX = "agents";
+
+export function getMemoryFilePath(name: string) {
+    const nameWithExt = name.endsWith(".tar.gz") ? name : name + ".tar.gz";
+    return `${MEMORIES_PREFIX}/${nameWithExt}`;
+}
+
+/**
+ * Build the storage path for an agent artifact
+ * @param runId - The workflow run ID
+ * @param name - The artifact filename
+ */
+export function getAgentArtifactPath(runId: string, name: string): string {
+    return `${ARTIFACTS_PREFIX}/${runId}/${name}`;
+}
+
+export class FilesApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/files");
+    }
+
+    async deleteFile(path: string, prefix?: boolean): Promise<void | number> {
+        const res = await this.delete(`/${path}`, { query: { prefix } });
+        return res.count;
+    }
+
+    /**
+     * get the metadata of a blob given its URI. Supported URI are:
+     * starting with s3:// and gs://.
+     * For s3 blobs use #region to specify the region. Ex: s3://bucket/key#us-west-2
+     * @param uri
+     * @returns
+     */
+    getMetadata(uri: string): Promise<{
+        name: string;
+        size: number;
+        contentType: string;
+        contentDisposition?: string;
+        etag?: string;
+        customMetadata?: Record<string, string>;
+    }> {
+        return this.get("/metadata", {
+            query: {
+                file: uri,
+            },
+        });
+    }
+
+    /**
+     * Set custom metadata on a file
+     * @param file - The file path or URI
+     * @param metadata - Custom metadata key-value pairs
+     * @returns Success status
+     */
+    setFileMetadata(file: string, metadata: Record<string, string>): Promise<{ success: boolean; file: string }> {
+        const payload: SetFileMetadataPayload = { file, metadata };
+        return this.put("/metadata", { payload });
+    }
+
+    /**
+     * Get or create a bucket for the project. If the bucket already exists, it does nothing.
+     * The bucket URI is returned.
+     * @returns
+     */
+    getOrCreateBucket(): Promise<{ bucket: string }> {
+        return this.post("/bucket");
+    }
+
+    getUploadUrl(payload: GetUploadUrlPayload): Promise<GetFileUrlResponse> {
+        return this.post("/upload-url", {
+            payload,
+        });
+    }
+
+    // Strictly typed: provide either simple args or a full payload via a separate method
+    getDownloadUrl(file: string, name?: string, disposition?: "inline" | "attachment"): Promise<GetFileUrlResponse> {
+        const payload: GetFileUrlPayload = { file, name, disposition };
+        return this.post("/download-url", { payload });
+    }
+
+    getDownloadUrlWithOptions(payload: GetFileUrlPayload): Promise<GetFileUrlResponse> {
+        return this.post("/download-url", { payload });
+    }
+
+    /**
+     * Upload content to a file and return the full path (including bucket name) of the uploaded file
+     * @param source
+     * @returns
+     */
+    async uploadFile(source: StreamSource | File): Promise<string> {
+        const isStream = source instanceof StreamSource;
+        const { url, id, path } = await this.getUploadUrl(source);
+
+        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": source.type || "application/gzip",
+            },
+        })
+            .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, url, id, path });
+                throw err;
+            });
+
+        return id;
+    }
+
+    /**
+     *
+     * @param location can be a relative path in the project, a reference to a cloud storage, or a accessible HTTPS URL (typically signed URL)
+     * @returns ReadableStream
+     */
+    async downloadFile(location: string): Promise<ReadableStream<Uint8Array<ArrayBuffer>>> {
+        //if start with HTTPS, no download url needed - assume it's signed already
+        const needSign = !location.startsWith("https:");
+        const { url } = needSign
+            ? await this.getDownloadUrl(location)
+            : { url: location };
+
+        const res = await fetch(url, {
+            method: "GET",
+        })
+            .then((res: Response) => {
+                if (res.ok) {
+                    return res;
+                } else if (res.status === 404) {
+                    throw new Error(`File at ${url} not found`); //TODO: type fetch error better with a fetch error class
+                } else if (res.status === 403) {
+                    throw new Error(`File at ${url} is forbidden`);
+                } else {
+                    console.log(res);
+                    throw new Error(
+                        `Failed to download file ${location}: ${res.statusText}`,
+                    );
+                }
+            })
+            .catch((err) => {
+                console.error(`Failed to download file ${location}.`, err);
+                throw err;
+            });
+
+        if (!res.body) {
+            throw new Error(
+                `No body in response while downloading file ${location}`,
+            );
+        }
+
+        return res.body;
+    }
+
+    /**
+     * Copy a file to a new destination within the same bucket.
+     * @param source - Source file path (relative to project bucket)
+     * @param dest - Destination file path (relative to project bucket)
+     * @returns The destination file URI
+     */
+    async copyFile(source: string, dest: string): Promise<string> {
+        const response = await this.post("/copy", {
+            payload: { source, dest },
+        }) as { success: boolean; source: string; dest: string };
+        return response.dest;
+    }
+
+    async uploadMemoryPack(source: StreamSource | File): Promise<string> {
+        const fileId = getMemoryFilePath(source.name);
+        const nameWithExt = source.name.endsWith(".tar.gz")
+            ? source.name
+            : source.name + ".tar.gz";
+        if (source instanceof File) {
+            let file = source as File;
+            return this.uploadFile(
+                new StreamSource(file.stream(), nameWithExt, file.type, fileId),
+            );
+        } else {
+            return this.uploadFile(
+                new StreamSource(
+                    source.stream,
+                    nameWithExt,
+                    source.type,
+                    fileId,
+                ),
+            );
+        }
+    }
+
+    async downloadMemoryPack(
+        name: string,
+        gunzip: boolean = false,
+    ): Promise<ReadableStream<Uint8Array>> {
+        let stream = await this.downloadFile(getMemoryFilePath(name));
+        if (gunzip) {
+            const ds = new DecompressionStream("gzip");
+            stream = stream.pipeThrough(ds);
+        }
+        return stream;
+    }
+
+    // ==================== Agent Artifact Methods ====================
+
+    /**
+     * List files by prefix
+     * @param prefix - Path prefix to filter files
+     * @returns Array of file paths matching the prefix
+     */
+    listByPrefix(prefix: string): Promise<{ files: string[] }> {
+        return this.get("/list", { query: { prefix } });
+    }
+
+    /**
+     * Upload an artifact for an agent run
+     * @param runId - The workflow run ID
+     * @param name - Artifact name (e.g., "output.json")
+     * @param source - File content source
+     * @returns The full path of the uploaded artifact
+     */
+    async uploadArtifact(runId: string, name: string, source: StreamSource | File): Promise<string> {
+        const artifactPath = getAgentArtifactPath(runId, name);
+        if (source instanceof File) {
+            const file = source as File;
+            return this.uploadFile(
+                new StreamSource(file.stream(), name, file.type, artifactPath)
+            );
+        } else {
+            return this.uploadFile(
+                new StreamSource(source.stream, name, source.type, artifactPath)
+            );
+        }
+    }
+
+    /**
+     * Download an artifact from an agent run
+     * @param runId - The workflow run ID
+     * @param name - Artifact name
+     * @returns ReadableStream of the artifact content
+     */
+    async downloadArtifact(runId: string, name: string): Promise<ReadableStream<Uint8Array>> {
+        const artifactPath = getAgentArtifactPath(runId, name);
+        return this.downloadFile(artifactPath);
+    }
+
+    /**
+     * Get download URL for an artifact
+     * @param runId - The workflow run ID
+     * @param name - Artifact name
+     * @param disposition - Content disposition (inline or attachment)
+     * @returns Signed URL response
+     */
+    getArtifactDownloadUrl(
+        runId: string,
+        name: string,
+        disposition?: "inline" | "attachment"
+    ): Promise<GetFileUrlResponse> {
+        const artifactPath = getAgentArtifactPath(runId, name);
+        return this.getDownloadUrl(artifactPath, name, disposition);
+    }
+
+    /**
+     * List artifacts for an agent run
+     * @param runId - The workflow run ID
+     * @returns Array of artifact file paths
+     */
+    async listArtifacts(runId: string): Promise<string[]> {
+        const prefix = `${ARTIFACTS_PREFIX}/${runId}/`;
+        const result = await this.listByPrefix(prefix);
+        return result.files;
+    }
+}