@ema.co/mcp-toolkit 2026.2.27 → 2026.2.28

package/dist/sdk/ema-client.js

@@ -304,6 +304,56 @@ export class EmaClientV2 {
     async getPersonaTemplates() {
         return this.listPersonaTemplates();
     }
+    /**
+     * Get a single persona template by ID
+     *
+     * Returns null for non-existent or invalid template IDs.
+     */
+    async getPersonaTemplateById(templateId) {
+        try {
+            const result = await api.getPersonaTemplateById({
+                client: this.restClient,
+                path: { template_id: templateId },
+            });
+            return result.data ?? null;
+        }
+        catch (e) {
+            if (e instanceof EmaApiError && (e.statusCode === 404 || e.statusCode === 422)) {
+                return null;
+            }
+            throw e;
+        }
+    }
+    /**
+     * Create a new persona template
+     */
+    async createPersonaTemplate(data) {
+        const result = await api.createPersonaTemplate({
+            client: this.restClient,
+            body: data,
+        });
+        return result.data;
+    }
+    /**
+     * Update an existing persona template
+     */
+    async updatePersonaTemplate(data) {
+        const result = await api.updatePersonaTemplate({
+            client: this.restClient,
+            body: data,
+        });
+        return result.data;
+    }
+    /**
+     * Delete a persona template by ID
+     */
+    async deletePersonaTemplate(templateId) {
+        const result = await api.deletePersonaTemplate({
+            client: this.restClient,
+            path: { template_id: templateId },
+        });
+        return result.data;
+    }
     // ─────────────────────────────────────────────────────────────────────────────
     // Actions - gRPC API
     // ─────────────────────────────────────────────────────────────────────────────
@@ -356,6 +406,50 @@ export class EmaClientV2 {
     async getDataSourceAggregates(personaId, widgetName) {
         return this.grpcClient.getContentNodeAggregates(personaId, widgetName);
     }
+    /**
+     * Download a file's content by its UploadedFile.Id.
+     * Uses GetSignedUrl gRPC → HTTP fetch on the signed URL.
+     *
+     * @param fileId - The UploadedFile.Id (from ContentNodeResponse.id)
+     * @returns Raw file content as Buffer
+     * @throws If file is deleted or signed URL fetch fails
+     */
+    async downloadFile(fileId, personaId) {
+        const signedUrlResponse = await this.grpcClient.getSignedUrl(fileId, personaId);
+        if (signedUrlResponse.isDeleted) {
+            throw new EmaApiError({
+                statusCode: 410,
+                body: `File ${fileId} has been deleted`,
+                message: `downloadFile: file is deleted (${this.env.name})`,
+            });
+        }
+        if (!signedUrlResponse.signedUrl) {
+            throw new EmaApiError({
+                statusCode: 404,
+                body: `No signed URL returned for file ${fileId}`,
+                message: `downloadFile: no signed URL (${this.env.name})`,
+            });
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const resp = await fetch(signedUrlResponse.signedUrl, {
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                throw new EmaApiError({
+                    statusCode: resp.status,
+                    body: await resp.text(),
+                    message: `downloadFile: fetch failed (${this.env.name})`,
+                });
+            }
+            const arrayBuffer = await resp.arrayBuffer();
+            return Buffer.from(arrayBuffer);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
     /**
      * Replicate data between personas
      */
@@ -442,6 +536,52 @@ export class EmaClientV2 {
         });
         return resp;
     }
+    /**
+     * Continue a paused (HITL) workflow for a dashboard row.
+     * Builds the ContinuationMessage proto JSON from convenience params.
+     *
+     * @param rowId - The dashboard row ID
+     * @param continuation - One of text, buttons, or form
+     */
+    async continueDashboardRow(rowId, continuation) {
+        // Raw pass-through: used for form HITL where the full formMessage must be echoed back
+        if (continuation.raw) {
+            await this.grpcClient.continueWorkflowForRow(rowId, continuation.raw);
+            return;
+        }
+        // Build ContinuationMessage JSON matching the proto oneof structure
+        let continuationMessage;
+        if (continuation.text) {
+            continuationMessage = {
+                textMessage: { contents: [continuation.text] },
+            };
+        }
+        else if (continuation.buttons) {
+            // Accept both chat-style {selected_button:{label:...}} and flat {label:...}
+            const btn = continuation.buttons;
+            const selectedButton = btn.selected_button ?? btn.selectedButton ?? btn;
+            continuationMessage = {
+                buttonsMessage: {
+                    selectedButton,
+                },
+            };
+        }
+        else if (continuation.form) {
+            // Accept chat-style {fields:[...], is_cancelled:bool} and pass through
+            const frm = continuation.form;
+            continuationMessage = {
+                formMessage: {
+                    fields: frm.fields,
+                    isCancelled: frm.is_cancelled ?? frm.isCancelled ?? false,
+                    ...(frm.content !== undefined && { content: frm.content }),
+                },
+            };
+        }
+        else {
+            throw new Error("continueDashboardRow requires one of: text, buttons, form, or raw");
+        }
+        await this.grpcClient.continueWorkflowForRow(rowId, continuationMessage);
+    }
     // ─────────────────────────────────────────────────────────────────────────────
     // Document Generation - REST API (OpenAPI generated)
     // ─────────────────────────────────────────────────────────────────────────────
@@ -624,34 +764,16 @@ export class EmaClientV2 {
         }
     }
     /**
-     * Delete a data source file from an AI Employee's knowledge base.
-     * API endpoint: DELETE /api/v2/upload/files/{file_id}
+     * Delete data source file(s) from an AI Employee's knowledge base.
+     * Uses gRPC DeleteFilesForGroup — the ONLY deletion method DIS exposes.
+     *
+     * @param personaId - The persona owning the files
+     * @param fileId - Single file ID to delete
+     * @param opts - Optional widget name scope
      */
-    async deleteDataSource(personaId, fileId) {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), 30_000);
-        try {
-            const resp = await fetch(`${this.env.baseUrl.replace(/\/$/, "")}/api/v2/upload/files/${fileId}?persona_id=${personaId}`, {
-                method: "DELETE",
-                headers: {
-                    Authorization: `Bearer ${this.env.bearerToken}`,
-                    "X-Persona-Id": personaId,
-                },
-                signal: controller.signal,
-            });
-            if (!resp.ok && resp.status !== 404) {
-                const errorBody = await resp.text();
-                throw new EmaApiError({
-                    statusCode: resp.status,
-                    body: errorBody,
-                    message: `deleteDataSource failed (${this.env.name})`,
-                });
-            }
-            return { success: true, fileId };
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
+    async deleteDataSource(personaId, fileId, opts) {
+        await this.grpcClient.deleteFilesForGroup(personaId, [fileId], opts?.widgetName);
+        return { success: true, fileId };
     }
     /**
      * Delete a persona
@@ -705,6 +827,99 @@ export class EmaClientV2 {
         return { status: "timeout" };
     }
     // ─────────────────────────────────────────────────────────────────────────────
+    // Chat / Conversation API
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Create a new chat conversation for a persona.
+     * Uses the legacy /api/chat/ route (no tenant_id needed -- JWT identifies tenant).
+     */
+    async createConversation(personaId, opts) {
+        const result = await this.fetchWithAuth("POST", "/api/chat/", {
+            persona_id: personaId,
+            ...(opts?.userContext && { user_context: opts.userContext }),
+            ...(opts?.caller && { caller: opts.caller }),
+        });
+        return {
+            conversationId: result.conversation_id,
+            message: result.message,
+        };
+    }
+    /**
+     * Send a message in a chat conversation.
+     * The message should be a ChatbotMessage proto dict.
+     */
+    async sendMessage(conversationId, message, opts) {
+        const result = await this.fetchWithAuth("POST", `/api/chat/${conversationId}`, {
+            message,
+            ...(opts?.userContext && { user_context: opts.userContext }),
+            ...(opts?.originalMessageId && { original_message_id: opts.originalMessageId }),
+        });
+        return {
+            conversationId: result.conversation_id,
+            message: result.message,
+            snippets: result.snippets ?? [],
+        };
+    }
+    /**
+     * Get conversation message history.
+     */
+    async getConversationHistory(conversationId) {
+        const result = await this.fetchWithAuth("GET", `/api/chat/${conversationId}`);
+        return { messages: result.messages ?? [] };
+    }
+    /**
+     * List all conversations for the current user.
+     */
+    async listConversations() {
+        const result = await api.listConversations({ client: this.restClient });
+        return (result.data ?? []);
+    }
+    /**
+     * List conversations for a specific persona (paginated).
+     */
+    async listConversationsForPersona(personaId, opts) {
+        const result = await api.listConversationsForPersona({
+            client: this.restClient,
+            path: { persona_id: personaId },
+            query: {
+                num_conversations: opts?.limit,
+                pagination_token: opts?.paginationToken,
+            },
+        });
+        return (result.data ?? {});
+    }
+    /**
+     * Get all messages in a conversation.
+     */
+    async getConversationMessages(conversationId) {
+        const result = await api.getConversationMessages({
+            client: this.restClient,
+            path: { conversation_id: conversationId },
+        });
+        return (result.data ?? []);
+    }
+    /**
+     * Delete a conversation by ID.
+     */
+    async deleteConversation(conversationId) {
+        const result = await api.deleteConversation({
+            client: this.restClient,
+            path: { conversation_id: conversationId },
+        });
+        return (result.data ?? {});
+    }
+    /**
+     * Update the display name for a conversation.
+     */
+    async updateConversationDisplayName(conversationId, displayName) {
+        const result = await api.updateConversationDisplayName({
+            client: this.restClient,
+            path: { conversation_id: conversationId },
+            query: { display_name: displayName },
+        });
+        return (result.data ?? {});
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
     // Private Helpers
     // ─────────────────────────────────────────────────────────────────────────────
     /**