@mastra/client-js 0.1.0-alpha.2 → 0.1.0-alpha.3

package/src/client.ts

@@ -0,0 +1,201 @@
+import type { ClientOptions, CreateMemoryThreadParams, CreateMemoryThreadResponse, GetAgentResponse, GetLogParams, GetLogsParams, GetLogsResponse, GetMemoryThreadParams, GetMemoryThreadResponse, GetToolResponse, GetWorkflowResponse, RequestOptions, SaveMessageToMemoryParams, SaveMessageToMemoryResponse } from './types';
+import { Agent, MemoryThread, Tool, Workflow, Vector } from './resources';
+
+export class MastraClient {
+    readonly baseUrl: string;
+    private readonly retries: number;
+    private readonly backoffMs: number;
+    private readonly maxBackoffMs: number;
+    private readonly headers: Record<string, string>;
+
+    constructor(options: ClientOptions) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.retries = options.retries ?? 3;
+        this.backoffMs = options.backoffMs ?? 300;
+        this.maxBackoffMs = options.maxBackoffMs ?? 5000;
+        this.headers = {
+            'Content-Type': 'application/json',
+            ...options.headers,
+        };
+    }
+
+    /**
+     * Makes an HTTP request to the Mastra API
+     * @param path - API endpoint path
+     * @param options - Request options including method, headers, and body
+     * @returns Promise containing the API response
+     * @throws Error if the request fails after all retries
+     */
+    async request(path: string, options: RequestOptions = {}): Promise<any> {
+        const url = `${this.baseUrl}${path}`;
+        let lastError: Error | null = null;
+        let currentBackoff = this.backoffMs;
+
+        for (let attempt = 0; attempt <= this.retries; attempt++) {
+            try {
+                const response = await fetch(url, {
+                    method: options.method ?? 'GET',
+                    headers: {
+                        ...this.headers,
+                        ...options.headers,
+                    },
+                    body: options.body ? JSON.stringify(options.body) : undefined,
+                });
+
+                if (!response.ok) {
+                    throw new Error(`HTTP error! status: ${response.status}`);
+                }
+
+                return await response.json();
+            } catch (error) {
+                lastError = error as Error;
+                if (attempt === this.retries) break;
+
+                await new Promise(resolve => setTimeout(resolve, currentBackoff));
+                currentBackoff = Math.min(currentBackoff * 2, this.maxBackoffMs);
+            }
+        }
+
+        throw lastError;
+    }
+
+    /**
+     * Retrieves all available agents
+     * @returns Promise containing map of agent IDs to agent details
+     */
+    public getAgents(): Promise<Record<string, GetAgentResponse>> {
+        return this.request('/api/agents');
+    }
+
+    /**
+     * Gets an agent instance by ID
+     * @param agentId - ID of the agent to retrieve
+     * @returns Agent instance
+     */
+    public getAgent(agentId: string) {
+        return new Agent(
+            (path: string, options?: RequestOptions) => this.request(path, options),
+            agentId
+        );
+    }
+
+    /**
+     * Retrieves memory threads for a resource
+     * @param params - Parameters containing the resource ID
+     * @returns Promise containing array of memory threads
+     */
+    public getMemoryThreads(params: GetMemoryThreadParams): Promise<GetMemoryThreadResponse> {
+        return this.request(`/api/memory/threads?resourceid=${params.resourceId}`);
+    }
+
+    /**
+     * Creates a new memory thread
+     * @param params - Parameters for creating the memory thread
+     * @returns Promise containing the created memory thread
+     */
+    public createMemoryThread(params: CreateMemoryThreadParams): Promise<CreateMemoryThreadResponse> {
+        return this.request('/api/memory/threads', { method: 'POST', body: params });
+    }
+
+    /**
+     * Gets a memory thread instance by ID
+     * @param threadId - ID of the memory thread to retrieve
+     * @returns MemoryThread instance
+     */
+    public getMemoryThread(threadId: string) {
+        return new MemoryThread(
+            (path: string, options?: RequestOptions) => this.request(path, options),
+            threadId
+        );
+    }
+
+    /**
+     * Saves messages to memory
+     * @param params - Parameters containing messages to save
+     * @returns Promise containing the saved messages
+     */
+    public saveMessageToMemory(params: SaveMessageToMemoryParams): Promise<SaveMessageToMemoryResponse> {
+        return this.request('/api/memory/save-messages', {
+            method: 'POST',
+            body: params,
+        });
+    }
+
+    /**
+     * Gets the status of the memory system
+     * @returns Promise containing memory system status
+     */
+    public getMemoryStatus(): Promise<{ result: boolean }> {
+        return this.request('/api/memory/status');
+    }
+
+    /**
+     * Retrieves all available tools
+     * @returns Promise containing map of tool IDs to tool details
+     */
+    public getTools(): Promise<Record<string, GetToolResponse>> {
+        return this.request('/api/tools');
+    }
+
+    /**
+     * Gets a tool instance by ID
+     * @param toolId - ID of the tool to retrieve
+     * @returns Tool instance
+     */
+    public getTool(toolId: string) {
+        return new Tool(
+            (path: string, options?: RequestOptions) => this.request(path, options),
+            toolId
+        );
+    }
+
+    /**
+     * Retrieves all available workflows
+     * @returns Promise containing map of workflow IDs to workflow details
+     */
+    public getWorkflows(): Promise<Record<string, GetWorkflowResponse>> {
+        return this.request('/api/workflows');
+    }
+
+    /**
+     * Gets a workflow instance by ID
+     * @param workflowId - ID of the workflow to retrieve
+     * @returns Workflow instance
+     */
+    public getWorkflow(workflowId: string) {
+        return new Workflow(
+            (path: string, options?: RequestOptions) => this.request(path, options),
+            workflowId
+        );
+    }
+
+    /**
+     * Gets a vector instance by name
+     * @param vectorName - Name of the vector to retrieve
+     * @returns Vector instance
+     */
+    public getVector(vectorName: string) {
+        return new Vector(
+            (path: string, options?: RequestOptions) => this.request(path, options),
+            vectorName
+        );
+    }
+
+    /**
+     * Retrieves logs
+     * @param params - Parameters for filtering logs
+     * @returns Promise containing array of log messages
+     */
+    public getLogs(params: GetLogsParams): Promise<GetLogsResponse> {
+        return this.request(`/api/logs?transportId=${params.transportId}`);
+    }
+
+    /**
+     * Gets logs for a specific run
+     * @param params - Parameters containing run ID to retrieve
+     * @returns Promise containing array of log messages
+     */
+    public getLogForRun(params: GetLogParams): Promise<GetLogsResponse> {
+        return this.request(`/api/logs/${params.runId}?transportId=${params.transportId}`);
+    }
+} 

package/src/index.test.ts

@@ -0,0 +1,507 @@
+import { describe, expect, beforeEach, it, vi } from 'vitest';
+import { MastraClient } from "./client";
+import type { MessageType } from '@mastra/core';
+
+// Mock fetch globally
+global.fetch = vi.fn();
+
+describe('MastraClient Resources', () => {
+    let client: MastraClient;
+
+    // Helper to mock successful API responses
+    const mockFetchResponse = (data: any) => {
+        (global.fetch as any).mockResolvedValueOnce({
+            ok: true,
+            json: async () => data
+        });
+    };
+
+    beforeEach(() => {
+        // Reset mocks
+        vi.clearAllMocks();
+
+        // Create fresh client for each test
+        client = new MastraClient({
+            baseUrl: 'http://localhost:4111',
+            headers: {
+                'Authorization': 'Bearer test-key'
+            }
+        });
+    });
+
+    describe('Vector Resource', () => {
+        const vectorName = 'test-vector';
+        let vector: ReturnType<typeof client.getVector>;
+
+        beforeEach(() => {
+            vector = client.getVector(vectorName);
+        });
+
+        it('should get vector index details', async () => {
+            const mockResponse = {
+                dimension: 128,
+                metric: 'cosine',
+                count: 1000
+            };
+            mockFetchResponse(mockResponse);
+
+            const result = await vector.details('test-index');
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/vector/test-vector/indexes/test-index`,
+                expect.any(Object)
+            );
+        });
+
+        it('should delete vector index', async () => {
+            mockFetchResponse({ success: true });
+            const result = await vector.delete('test-index');
+            expect(result).toEqual({ success: true });
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/vector/test-vector/indexes/test-index`,
+                expect.objectContaining({ method: 'DELETE' })
+            );
+        });
+
+        it('should get all indexes', async () => {
+            const mockResponse = { indexes: ['index1', 'index2'] };
+            mockFetchResponse(mockResponse);
+            const result = await vector.getIndexes();
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/vector/test-vector/indexes`,
+                expect.any(Object)
+            );
+        });
+
+        it('should create vector index with all parameters', async () => {
+            mockFetchResponse({ success: true });
+            const result = await vector.createIndex({
+                indexName: 'test-index',
+                dimension: 128,
+                metric: 'cosine'
+            });
+            expect(result).toEqual({ success: true });
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/vector/test-vector/create-index`,
+                expect.objectContaining({
+                    method: 'POST',
+                    body: JSON.stringify({
+                        indexName: 'test-index',
+                        dimension: 128,
+                        metric: 'cosine'
+                    })
+                })
+            );
+        });
+
+        it('should upsert vectors with metadata and ids', async () => {
+            const mockResponse = ['id1', 'id2'];
+            mockFetchResponse(mockResponse);
+            const result = await vector.upsert({
+                indexName: 'test-index',
+                vectors: [[1, 2], [3, 4]],
+                metadata: [{ label: 'a' }, { label: 'b' }],
+                ids: ['id1', 'id2']
+            });
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/vector/test-vector/upsert`,
+                expect.objectContaining({
+                    method: 'POST',
+                    body: JSON.stringify({
+                        indexName: 'test-index',
+                        vectors: [[1, 2], [3, 4]],
+                        metadata: [{ label: 'a' }, { label: 'b' }],
+                        ids: ['id1', 'id2']
+                    })
+                })
+            );
+        });
+
+        it('should query vectors with all parameters', async () => {
+            const mockResponse = {
+                results: [{
+                    id: 'id1',
+                    score: 0.9,
+                    metadata: { label: 'a' },
+                    vector: [1, 2]
+                }]
+            };
+            mockFetchResponse(mockResponse);
+            const result = await vector.query({
+                indexName: 'test-index',
+                queryVector: [1, 2],
+                topK: 10,
+                filter: { label: 'a' },
+                includeVector: true
+            });
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/vector/test-vector/query`,
+                expect.objectContaining({
+                    method: 'POST',
+                    body: JSON.stringify({
+                        indexName: 'test-index',
+                        queryVector: [1, 2],
+                        topK: 10,
+                        filter: { label: 'a' },
+                        includeVector: true
+                    })
+                })
+            );
+        });
+    });
+
+    describe('Agent Resource', () => {
+        const agentId = 'test-agent';
+        let agent: ReturnType<typeof client.getAgent>;
+
+        beforeEach(() => {
+            agent = client.getAgent(agentId);
+        });
+
+        it('should get all agents', async () => {
+            const mockResponse = {
+                'agent1': { name: 'Agent 1', model: 'gpt-4' },
+                'agent2': { name: 'Agent 2', model: 'gpt-3.5' }
+            };
+            mockFetchResponse(mockResponse);
+            const result = await client.getAgents();
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/agents`,
+                expect.any(Object)
+            );
+        });
+
+        it('should get agent details', async () => {
+            const mockResponse = {
+                name: 'Test Agent',
+                model: 'gpt-4',
+                instructions: 'Test instructions',
+                tools: {}
+            };
+            mockFetchResponse(mockResponse);
+
+            const result = await agent.details();
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/agents/test-agent`,
+                expect.any(Object)
+            );
+        });
+
+        it('should generate response', async () => {
+            const mockResponse = {
+                response: 'Generated response'
+            };
+            mockFetchResponse(mockResponse);
+
+            const result = await agent.generate({ prompt: 'Test prompt' });
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/agents/test-agent/generate`,
+                expect.objectContaining({
+                    method: 'POST',
+                    body: JSON.stringify({ prompt: 'Test prompt' })
+                })
+            );
+        });
+
+        it('should stream responses', async () => {
+            const mockResponse = {
+                stream: true,
+                chunks: ['chunk1', 'chunk2']
+            };
+            mockFetchResponse(mockResponse);
+            const result = await agent.stream({ prompt: 'Test prompt' });
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/agents/test-agent/generate`,
+                expect.objectContaining({
+                    method: 'POST',
+                    body: JSON.stringify({ prompt: 'Test prompt', stream: true })
+                })
+            );
+        });
+
+        it('should get agent tool', async () => {
+            const mockResponse = {
+                id: 'tool1',
+                description: 'Test Tool'
+            };
+            mockFetchResponse(mockResponse);
+            const result = await agent.getTool('tool1');
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/agents/test-agent/tools/tool1`,
+                expect.any(Object)
+            );
+        });
+
+        it('should get agent evals', async () => {
+            const mockResponse = {
+                name: 'Test Agent',
+                evals: [{ id: 'eval1' }]
+            };
+            mockFetchResponse(mockResponse);
+            const result = await agent.evals();
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/agents/test-agent/evals`,
+                expect.any(Object)
+            );
+        });
+
+        it('should get live evals', async () => {
+            const mockResponse = {
+                name: 'Test Agent',
+                evals: [{ id: 'eval1', live: true }]
+            };
+            mockFetchResponse(mockResponse);
+            const result = await agent.liveEvals();
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/agents/test-agent/evals/live`,
+                expect.any(Object)
+            );
+        });
+    });
+
+    describe('Memory Thread Resource', () => {
+        const threadId = 'test-thread';
+        let memoryThread: ReturnType<typeof client.getMemoryThread>;
+
+        beforeEach(() => {
+            memoryThread = client.getMemoryThread(threadId);
+        });
+
+        it('should get thread details', async () => {
+            const mockResponse = {
+                id: threadId,
+                title: 'Test Thread',
+                metadata: {}
+            };
+            mockFetchResponse(mockResponse);
+
+            const result = await memoryThread.get();
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/memory/threads/test-thread`,
+                expect.any(Object)
+            );
+        });
+
+        it('should update thread', async () => {
+            const mockResponse = {
+                id: threadId,
+                title: 'Updated Thread',
+                metadata: { updated: true }
+            };
+            mockFetchResponse(mockResponse);
+
+            const result = await memoryThread.update({
+                title: 'Updated Thread',
+                metadata: { updated: true },
+                resourceid: 'test-resource'
+            });
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/memory/threads/test-thread`,
+                expect.objectContaining({
+                    method: 'PATCH'
+                })
+            );
+        });
+
+        it('should delete thread', async () => {
+            const mockResponse = { result: 'deleted' };
+            mockFetchResponse(mockResponse);
+            const result = await memoryThread.delete();
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/memory/threads/test-thread`,
+                expect.objectContaining({ method: 'DELETE' })
+            );
+        });
+
+        it('should get memory status', async () => {
+            const mockResponse = { result: true };
+            mockFetchResponse(mockResponse);
+            const result = await client.getMemoryStatus();
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/memory/status`,
+                expect.any(Object)
+            );
+        });
+
+        it('should save messages to memory', async () => {
+            const messages: MessageType[] = [{
+                id: '1',
+                type: 'text',
+                content: 'test',
+                role: 'user',
+                threadId: 'test-thread',
+                createdAt: new Date()
+            }];
+            mockFetchResponse(messages);
+            const result = await client.saveMessageToMemory({ messages });
+            expect(result).toEqual(messages);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/memory/save-messages`,
+                expect.objectContaining({
+                    method: 'POST',
+                    body: JSON.stringify({ messages })
+                })
+            );
+        });
+    });
+
+    describe('Tool Resource', () => {
+        const toolId = 'test-tool';
+        let tool: ReturnType<typeof client.getTool>;
+
+        beforeEach(() => {
+            tool = client.getTool(toolId);
+        });
+
+        it('should get tool details', async () => {
+            const mockResponse = {
+                id: toolId,
+                description: 'Test Tool',
+                inputSchema: '{}',
+                outputSchema: '{}'
+            };
+            mockFetchResponse(mockResponse);
+
+            const result = await tool.details();
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/tools/test-tool`,
+                expect.any(Object)
+            );
+        });
+
+        it('should execute tool', async () => {
+            const mockResponse = {
+                result: 'Tool execution result'
+            };
+            mockFetchResponse(mockResponse);
+
+            const result = await tool.execute({ input: 'test' });
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/tools/test-tool/execute`,
+                expect.objectContaining({
+                    method: 'POST',
+                    body: JSON.stringify({ input: 'test' })
+                })
+            );
+        });
+    });
+
+    describe('Workflow Resource', () => {
+        const workflowId = 'test-workflow';
+        let workflow: ReturnType<typeof client.getWorkflow>;
+
+        beforeEach(() => {
+            workflow = client.getWorkflow(workflowId);
+        });
+
+        it('should get workflow details', async () => {
+            const mockResponse = {
+                name: 'Test Workflow',
+                triggerSchema: '{}',
+                steps: {},
+                stepGraph: {},
+                stepSubscriberGraph: {}
+            };
+            mockFetchResponse(mockResponse);
+
+            const result = await workflow.details();
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/workflows/test-workflow`,
+                expect.any(Object)
+            );
+        });
+
+        it('should execute workflow', async () => {
+            const mockResponse = {
+                result: 'Workflow execution result'
+            };
+            mockFetchResponse(mockResponse);
+
+            const result = await workflow.execute({ trigger: 'test' });
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                `${client.baseUrl}/api/workflows/test-workflow/execute`,
+                expect.objectContaining({
+                    method: 'POST',
+                    body: JSON.stringify({ trigger: 'test' })
+                })
+            );
+        });
+    });
+
+    describe('Client Error Handling', () => {
+        it('should retry failed requests', async () => {
+            // Mock first two calls to fail, third to succeed
+            (global.fetch as any)
+                .mockRejectedValueOnce(new Error('Network error'))
+                .mockRejectedValueOnce(new Error('Network error'))
+                .mockResolvedValueOnce({
+                    ok: true,
+                    json: async () => ({ success: true })
+                });
+
+            const result = await client.request('/test-endpoint');
+            expect(result).toEqual({ success: true });
+            expect(global.fetch).toHaveBeenCalledTimes(3);
+        });
+
+        it('should throw error after max retries', async () => {
+            (global.fetch as any).mockRejectedValue(new Error('Network error'));
+
+            await expect(client.request('/test-endpoint'))
+                .rejects
+                .toThrow('Network error');
+
+            expect(global.fetch).toHaveBeenCalledTimes(4);
+        });
+    });
+
+    describe('Client Configuration', () => {
+        it('should handle custom retry configuration', async () => {
+            const customClient = new MastraClient({
+                baseUrl: 'http://localhost:4111',
+                retries: 2,
+                backoffMs: 100,
+                maxBackoffMs: 1000,
+                headers: { 'Custom-Header': 'value' }
+            });
+
+            (global.fetch as any)
+                .mockRejectedValueOnce(new Error('Network error'))
+                .mockRejectedValueOnce(new Error('Network error'))
+                .mockResolvedValueOnce({
+                    ok: true,
+                    json: async () => ({ success: true })
+                });
+
+            const result = await customClient.request('/test');
+            expect(result).toEqual({ success: true });
+            expect(global.fetch).toHaveBeenCalledTimes(3);
+            expect(global.fetch).toHaveBeenCalledWith(
+                'http://localhost:4111/test',
+                expect.objectContaining({
+                    headers: expect.objectContaining({
+                        'Custom-Header': 'value'
+                    })
+                })
+            );
+        });
+    });
+});