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

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/FilesApi.ts

@@ -169,6 +169,19 @@ export class FilesApi extends ApiTopic {
         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")

package/src/store/HiveMemoryApi.ts

@@ -0,0 +1,231 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    CreateHiveMemoryPayload,
+    FormattedMemoryForAgent,
+    HiveMemory,
+    HiveMemorySearchParams,
+    HiveMemorySearchResult,
+    UpdateHiveMemoryPayload,
+} from "@vertesia/common";
+
+/**
+ * Statistics about hive memories in the project
+ */
+export interface HiveMemoryStats {
+    total_memories: number;
+    by_category: Array<{
+        category: string;
+        count: number;
+        avg_confidence: number;
+        total_usage: number;
+    }>;
+    overall: {
+        avgConfidence: number;
+        avgUsage: number;
+        totalContributions: number;
+    };
+}
+
+/**
+ * Result from recall endpoint
+ */
+export interface RecallResult {
+    memories: FormattedMemoryForAgent[];
+    count: number;
+}
+
+/**
+ * Client API for managing hive memories.
+ *
+ * Hive memory is a system for storing and retrieving agent learnings,
+ * enabling agents to learn from past runs and share knowledge.
+ */
+export class HiveMemoryApi extends ApiTopic {
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/hive-memory");
+    }
+
+    /**
+     * List memories in the project.
+     *
+     * @param options - Optional filters and pagination
+     */
+    list(options?: {
+        category?: string;
+        scope?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<HiveMemory[]> {
+        const params = new URLSearchParams();
+        if (options?.category) params.set('category', options.category);
+        if (options?.scope) params.set('scope', options.scope);
+        if (options?.limit) params.set('limit', String(options.limit));
+        if (options?.offset) params.set('offset', String(options.offset));
+
+        const queryString = params.toString();
+        return this.get(queryString ? `/?${queryString}` : '/');
+    }
+
+    /**
+     * Retrieve a memory by ID.
+     */
+    retrieve(id: string): Promise<HiveMemory> {
+        return this.get(`/${id}`);
+    }
+
+    /**
+     * Create a new hive memory.
+     *
+     * @param payload - Memory content including category, summary, and learnings
+     */
+    create(payload: CreateHiveMemoryPayload): Promise<HiveMemory> {
+        return this.post("/", { payload });
+    }
+
+    /**
+     * Update an existing memory with new learnings.
+     *
+     * This merges new learnings with existing ones rather than replacing them.
+     *
+     * @param id - Memory ID
+     * @param payload - Fields to update/merge
+     */
+    update(id: string, payload: UpdateHiveMemoryPayload): Promise<HiveMemory> {
+        return this.put(`/${id}`, { payload });
+    }
+
+    /**
+     * Delete a memory.
+     *
+     * @param id - Memory ID
+     */
+    delete(id: string): Promise<{ id: string; deleted: boolean }> {
+        return this.del(`/${id}`);
+    }
+
+    /**
+     * Search memories using semantic and keyword search.
+     *
+     * @param params - Search parameters including query, filters, and pagination
+     */
+    search(params: HiveMemorySearchParams): Promise<HiveMemorySearchResult> {
+        return this.post("/search", { payload: params });
+    }
+
+    /**
+     * Recall memories for an agent.
+     *
+     * This is the primary method for agents to retrieve relevant learnings.
+     * It searches for memories matching the task description and returns
+     * them formatted for agent consumption.
+     *
+     * @param taskDescription - Description of the current task
+     * @param options - Optional filters
+     *
+     * @example
+     * ```typescript
+     * const result = await client.hiveMemory.recall(
+     *   "Extract financial data from PDF documents",
+     *   {
+     *     tools: ["extract_text", "analyze_document"],
+     *     maxResults: 5
+     *   }
+     * );
+     * ```
+     */
+    recall(
+        taskDescription: string,
+        options?: {
+            tools?: string[];
+            category?: string;
+            maxResults?: number;
+        }
+    ): Promise<RecallResult> {
+        return this.post("/recall", {
+            payload: {
+                task_description: taskDescription,
+                tools: options?.tools,
+                category: options?.category,
+                max_results: options?.maxResults,
+            }
+        });
+    }
+
+    /**
+     * Get a memory formatted for agent consumption.
+     *
+     * @param id - Memory ID
+     */
+    getFormatted(id: string): Promise<FormattedMemoryForAgent> {
+        return this.get(`/${id}/formatted`);
+    }
+
+    /**
+     * Record that a memory was used.
+     *
+     * This increments the usage count and helps track memory effectiveness.
+     *
+     * @param id - Memory ID
+     */
+    recordUsage(id: string): Promise<{ success: boolean }> {
+        return this.post(`/${id}/usage`, {});
+    }
+
+    /**
+     * Get memories by category.
+     *
+     * @param category - Task category (e.g., "document-analysis", "data-extraction")
+     * @param options - Pagination options
+     */
+    getByCategory(
+        category: string,
+        options?: { limit?: number; offset?: number }
+    ): Promise<HiveMemory[]> {
+        const params = new URLSearchParams();
+        if (options?.limit) params.set('limit', String(options.limit));
+        if (options?.offset) params.set('offset', String(options.offset));
+
+        const queryString = params.toString();
+        return this.get(`/category/${category}${queryString ? `?${queryString}` : ''}`);
+    }
+
+    /**
+     * Get memory statistics for the project.
+     */
+    getStats(): Promise<HiveMemoryStats> {
+        return this.get("/stats");
+    }
+
+    /**
+     * Apply confidence decay to unused memories.
+     *
+     * Admin operation that reduces confidence scores for memories
+     * that haven't been used recently.
+     *
+     * @param options - Decay parameters
+     */
+    applyDecay(options?: {
+        daysThreshold?: number;
+        decayRate?: number;
+    }): Promise<{ modified_count: number }> {
+        return this.post("/admin/decay", {
+            payload: {
+                days_threshold: options?.daysThreshold,
+                decay_rate: options?.decayRate,
+            }
+        });
+    }
+
+    /**
+     * Archive memories with low confidence scores.
+     *
+     * Admin operation that removes memories below a confidence threshold.
+     *
+     * @param threshold - Confidence threshold (0-1), default 0.2
+     */
+    archiveLowConfidence(threshold?: number): Promise<{ archived_count: number }> {
+        return this.post("/admin/archive", {
+            payload: { threshold }
+        });
+    }
+}