@mastra/client-js 1.2.0 → 1.2.1-alpha.0

package/dist/docs/references/reference-client-js-memory.md

@@ -0,0 +1,225 @@
+# Memory API
+
+The Memory API provides methods to manage conversation threads and message history in Mastra.
+
+### Get All Threads
+
+Retrieve all memory threads for a specific resource:
+
+```typescript
+const threads = await mastraClient.getMemoryThreads({
+  resourceId: "resource-1",
+  agentId: "agent-1", // Optional - can be omitted if storage is configured
+});
+```
+
+When `agentId` is omitted and storage is configured on the server, threads will be retrieved using storage directly. This is useful when multiple agents share the same threads (e.g., in workflows with multiple agent steps).
+
+### Create a New Thread
+
+Create a new memory thread:
+
+```typescript
+const thread = await mastraClient.createMemoryThread({
+  title: "New Conversation",
+  metadata: { category: "support" },
+  resourceId: "resource-1",
+  agentId: "agent-1",
+});
+```
+
+### Working with a Specific Thread
+
+Get an instance of a specific memory thread:
+
+```typescript
+const thread = mastraClient.getMemoryThread({ threadId: "thread-id", agentId: "agent-id" });
+```
+
+## Thread Methods
+
+### Get Thread Details
+
+Retrieve details about a specific thread:
+
+```typescript
+const details = await thread.get();
+```
+
+### Update Thread
+
+Update thread properties:
+
+```typescript
+const updated = await thread.update({
+  title: "Updated Title",
+  metadata: { status: "resolved" },
+  resourceId: "resource-1",
+});
+```
+
+### Delete Thread
+
+Delete a thread and its messages:
+
+```typescript
+await thread.delete();
+```
+
+### Clone Thread
+
+Create a copy of a thread with all its messages:
+
+```typescript
+const { thread: clonedThread, clonedMessages } = await thread.clone();
+```
+
+Clone with options:
+
+```typescript
+const { thread: clonedThread, clonedMessages } = await thread.clone({
+  newThreadId: "custom-clone-id",
+  title: "Cloned Conversation",
+  metadata: { branch: "experiment-1" },
+  options: {
+    messageLimit: 10, // Only clone last 10 messages
+  },
+});
+```
+
+Clone with message filtering:
+
+```typescript
+const { thread: clonedThread } = await thread.clone({
+  options: {
+    messageFilter: {
+      startDate: new Date("2024-01-01"),
+      endDate: new Date("2024-01-31"),
+    },
+  },
+});
+```
+
+The clone response includes:
+
+- `thread`: The newly created cloned thread with clone metadata
+- `clonedMessages`: Array of the cloned messages with new IDs
+
+## Message Operations
+
+### Save Messages
+
+Save messages to memory:
+
+```typescript
+const result = await mastraClient.saveMessageToMemory({
+  messages: [
+    {
+      role: "user",
+      content: "Hello!",
+      id: "1",
+      threadId: "thread-1",
+      resourceId: "resource-1",
+      createdAt: new Date(),
+      format: 2,
+    },
+  ],
+  agentId: "agent-1",
+});
+
+// result.messages contains the saved messages
+console.log(result.messages);
+```
+
+### Retrieve Thread Messages
+
+Get messages associated with a memory thread:
+
+```typescript
+// Get all messages in the thread (paginated)
+const result = await thread.listMessages();
+console.log(result.messages); // Array of messages
+console.log(result.total); // Total count
+console.log(result.hasMore); // Whether more pages exist
+
+// Get messages with pagination
+const result = await thread.listMessages({
+  page: 0,
+  perPage: 20
+});
+
+// Get messages with ordering
+const result = await thread.listMessages({
+  orderBy: { field: 'createdAt', direction: 'ASC' }
+});
+```
+
+### Delete Messages
+
+Delete one or more messages from a thread:
+
+```typescript
+// Delete a single message
+const result = await thread.deleteMessages("message-id");
+
+// Delete multiple messages
+const result = await thread.deleteMessages([
+  "message-1",
+  "message-2",
+  "message-3",
+]);
+
+// Returns: { success: true, message: "Message deleted successfully" }
+```
+
+## Working Memory
+
+Working memory allows agents to maintain persistent information about users across interactions. It can be scoped to either a specific thread or across all threads for a resource (user).
+
+### Get Working Memory
+
+Retrieve the current working memory for a thread:
+
+```typescript
+const workingMemory = await mastraClient.getWorkingMemory({
+  agentId: "agent-1",
+  threadId: "thread-1",
+  resourceId: "user-123", // Optional, required for resource-scoped memory
+});
+```
+
+The response includes:
+
+- `workingMemory`: The current working memory content (string or null)
+- `source`: Whether the memory is from `"thread"` or `"resource"` scope
+- `workingMemoryTemplate`: The template used for working memory (if configured)
+- `threadExists`: Whether the thread exists
+
+### Update Working Memory
+
+Update the working memory content for a thread:
+
+```typescript
+await mastraClient.updateWorkingMemory({
+  agentId: "agent-1",
+  threadId: "thread-1",
+  workingMemory: `# User Profile
+- Name: John Doe
+- Location: New York
+- Preferences: Prefers formal communication
+`,
+  resourceId: "user-123", // Optional, required for resource-scoped memory
+});
+
+// Returns: { success: true }
+```
+
+**Note:** For resource-scoped working memory, you must provide the `resourceId` parameter. This allows the memory to persist across all conversation threads for that user.
+
+### Get Memory Status
+
+Check the status of the memory system:
+
+```typescript
+const status = await mastraClient.getMemoryStatus("agent-id");
+```

package/dist/docs/references/reference-client-js-observability.md

@@ -0,0 +1,72 @@
+# Observability API
+
+The Observability API provides methods to retrieve traces, monitor your application's performance, and score traces for evaluation. This helps you understand how your AI agents and workflows are performing.
+
+## Getting a Specific Trace
+
+Retrieve a specific trace by its ID, including all its spans and details:
+
+```typescript
+const trace = await mastraClient.getTrace("trace-id-123");
+```
+
+## Getting Traces with Filtering
+
+Retrieve a paginated list of trace root spans with optional filtering:
+
+```typescript
+const traces = await mastraClient.getTraces({
+  pagination: {
+    page: 1,
+    perPage: 20,
+    dateRange: {
+      start: new Date("2024-01-01"),
+      end: new Date("2024-01-31"),
+    },
+  },
+  filters: {
+    name: "weather-agent", // Filter by trace name
+    spanType: "agent", // Filter by span type
+    entityId: "weather-agent-id", // Filter by entity ID
+    entityType: "agent", // Filter by entity type
+  },
+});
+
+console.log(`Found ${traces.spans.length} root spans`);
+console.log(`Total pages: ${traces.pagination.totalPages}`);
+
+// To get the complete trace with all spans, use getTrace
+const completeTrace = await mastraClient.getTrace(traces.spans[0].traceId);
+```
+
+## Scoring Traces
+
+Score specific traces using registered scorers for evaluation:
+
+```typescript
+const result = await mastraClient.score({
+  scorerName: "answer-relevancy",
+  targets: [
+    { traceId: "trace-1", spanId: "span-1" }, // Score specific span
+    { traceId: "trace-2" }, // Score specific span which defaults to the parent span
+  ],
+});
+```
+
+## Getting Scores by Span
+
+Retrieve scores for a specific span within a trace:
+
+```typescript
+const scores = await mastraClient.listScoresBySpan({
+  traceId: "trace-123",
+  spanId: "span-456",
+  page: 1,
+  perPage: 20,
+});
+```
+
+## Related
+
+- [Agents API](https://mastra.ai/reference/client-js/agents) - Learn about agent interactions that generate traces
+- [Workflows API](https://mastra.ai/reference/client-js/workflows) - Understand workflow execution monitoring

package/dist/docs/references/reference-client-js-telemetry.md

@@ -0,0 +1,20 @@
+# Telemetry API
+
+The Telemetry API provides methods to retrieve and analyze traces from your Mastra application. This helps you monitor and debug your application's behavior and performance.
+
+## Getting Traces
+
+Retrieve traces with optional filtering and pagination:
+
+```typescript
+const telemetry = await mastraClient.getTelemetry({
+  name: "trace-name", // Optional: Filter by trace name
+  scope: "scope-name", // Optional: Filter by scope
+  page: 1, // Optional: Page number for pagination
+  perPage: 10, // Optional: Number of items per page
+  attribute: {
+    // Optional: Filter by custom attributes
+    key: "value",
+  },
+});
+```

package/dist/docs/references/reference-client-js-tools.md

@@ -0,0 +1,44 @@
+# Tools API
+
+The Tools API provides methods to interact with and execute tools available in the Mastra platform.
+
+## Getting All Tools
+
+Retrieve a list of all available tools:
+
+```typescript
+const tools = await mastraClient.listTools();
+```
+
+## Working with a Specific Tool
+
+Get an instance of a specific tool:
+
+```typescript
+const tool = mastraClient.getTool("tool-id");
+```
+
+## Tool Methods
+
+### Get Tool Details
+
+Retrieve detailed information about a tool:
+
+```typescript
+const details = await tool.details();
+```
+
+### Execute Tool
+
+Execute a tool with specific arguments:
+
+```typescript
+const result = await tool.execute({
+  args: {
+    param1: "value1",
+    param2: "value2",
+  },
+  threadId: "thread-1", // Optional: Thread context
+  resourceId: "resource-1", // Optional: Resource identifier
+});
+```

package/dist/docs/references/reference-client-js-vectors.md

@@ -0,0 +1,79 @@
+# Vectors API
+
+The Vectors API provides methods to work with vector embeddings for semantic search and similarity matching in Mastra.
+
+## Working with Vectors
+
+Get an instance of a vector store:
+
+```typescript
+const vector = mastraClient.getVector("vector-name");
+```
+
+## Vector Methods
+
+### Get Vector Index Details
+
+Retrieve information about a specific vector index:
+
+```typescript
+const details = await vector.details("index-name");
+```
+
+### Create Vector Index
+
+Create a new vector index:
+
+```typescript
+const result = await vector.createIndex({
+  indexName: "new-index",
+  dimension: 128,
+  metric: "cosine", // 'cosine', 'euclidean', or 'dotproduct'
+});
+```
+
+### Upsert Vectors
+
+Add or update vectors in an index:
+
+```typescript
+const ids = await vector.upsert({
+  indexName: "my-index",
+  vectors: [
+    [0.1, 0.2, 0.3], // First vector
+    [0.4, 0.5, 0.6], // Second vector
+  ],
+  metadata: [{ label: "first" }, { label: "second" }],
+  ids: ["id1", "id2"], // Optional: Custom IDs
+});
+```
+
+### Query Vectors
+
+Search for similar vectors:
+
+```typescript
+const results = await vector.query({
+  indexName: "my-index",
+  queryVector: [0.1, 0.2, 0.3],
+  topK: 10,
+  filter: { label: "first" }, // Optional: Metadata filter
+  includeVector: true, // Optional: Include vectors in results
+});
+```
+
+### Get All Indexes
+
+List all available indexes:
+
+```typescript
+const indexes = await vector.getIndexes();
+```
+
+### Delete Index
+
+Delete a vector index:
+
+```typescript
+const result = await vector.delete("index-name");
+```

package/dist/docs/references/reference-client-js-workflows.md

@@ -0,0 +1,199 @@
+# Workflows API
+
+The Workflows API provides methods to interact with and execute automated workflows in Mastra.
+
+## Getting All Workflows
+
+Retrieve a list of all available workflows:
+
+```typescript
+const workflows = await mastraClient.listWorkflows();
+```
+
+## Working with a Specific Workflow
+
+Get an instance of a specific workflow by its ID:
+
+```typescript
+export const testWorkflow = createWorkflow({
+  id: "city-workflow",
+});
+```
+
+```typescript
+const workflow = mastraClient.getWorkflow("city-workflow");
+```
+
+## Workflow Methods
+
+### details()
+
+Retrieve detailed information about a workflow:
+
+```typescript
+const details = await workflow.details();
+```
+
+### createRun()
+
+Create a new workflow run instance:
+
+```typescript
+const run = await workflow.createRun();
+
+// Or with an existing runId
+const run = await workflow.createRun({ runId: "existing-run-id" });
+
+// Or with a resourceId to associate the run with a specific resource
+const run = await workflow.createRun({
+  runId: "my-run-id",
+  resourceId: "user-123"
+});
+```
+
+The `resourceId` parameter associates the workflow run with a specific resource (e.g., user ID, tenant ID). This value is persisted with the run and can be used for filtering and querying runs later.
+
+### startAsync()
+
+Start a workflow run and await the full result:
+
+```typescript
+const run = await workflow.createRun();
+
+const result = await run.startAsync({
+  inputData: {
+    city: "New York",
+  },
+});
+```
+
+You can also pass `initialState` to set the starting values for the workflow's state:
+
+```typescript
+const result = await run.startAsync({
+  inputData: {
+    city: "New York",
+  },
+  initialState: {
+    count: 0,
+    items: [],
+  },
+});
+```
+
+The `initialState` object should match the structure defined in the workflow's `stateSchema`. See [Workflow State](https://mastra.ai/docs/workflows/workflow-state) for more details.
+
+To associate a run with a specific resource, pass `resourceId` to `createRun()`:
+
+```typescript
+const run = await workflow.createRun({ resourceId: "user-123" });
+
+const result = await run.startAsync({
+  inputData: {
+    city: "New York",
+  },
+});
+```
+
+### start()
+
+Start a workflow run without waiting for completion:
+
+```typescript
+const run = await workflow.createRun();
+
+await run.start({
+  inputData: {
+    city: "New York",
+  },
+});
+
+// Poll for results later
+const result = await workflow.runById(run.runId);
+```
+
+This is useful for long-running workflows where you want to start execution and check results later.
+
+### resumeAsync()
+
+Resume a suspended workflow step and await the full result:
+
+```typescript
+const run = await workflow.createRun({ runId: prevRunId });
+
+const result = await run.resumeAsync({
+  step: "step-id",
+  resumeData: { key: "value" },
+});
+```
+
+### resume()
+
+Resume a suspended workflow step without waiting for completion:
+
+```typescript
+const run = await workflow.createRun({ runId: prevRunId });
+
+await run.resume({
+  step: "step-id",
+  resumeData: { key: "value" },
+});
+```
+
+### cancel()
+
+Cancel a running workflow:
+
+```typescript
+const run = await workflow.createRun({ runId: existingRunId });
+
+const result = await run.cancel();
+// Returns: { message: 'Workflow run canceled' }
+```
+
+This method stops any running steps and prevents subsequent steps from executing. Steps that check the `abortSignal` parameter can respond to cancellation by cleaning up resources (timeouts, network requests, etc.).
+
+See the [Run.cancel()](https://mastra.ai/reference/workflows/run-methods/cancel) reference for detailed information about how cancellation works and how to write steps that respond to cancellation.
+
+### stream()
+
+Stream workflow execution for real-time updates:
+
+```typescript
+const run = await workflow.createRun();
+
+const stream = await run.stream({
+  inputData: {
+    city: "New York",
+  },
+});
+
+for await (const chunk of stream) {
+  console.log(JSON.stringify(chunk, null, 2));
+}
+```
+
+### runById()
+
+Get the execution result for a workflow run:
+
+```typescript
+const result = await workflow.runById(runId);
+
+// Or with options for performance optimization:
+const result = await workflow.runById(runId, {
+  fields: ['status', 'result'],  // Only fetch specific fields
+  withNestedWorkflows: false,    // Skip expensive nested workflow data
+  requestContext: { userId: 'user-123' }, // Optional request context
+});
+```
+
+### Run result format
+
+A workflow run result yields the following:
+
+**runId:** (`string`): Unique identifier for this workflow run instance
+
+**eventTimestamp:** (`Date`): The timestamp of the event
+
+**payload:** (`object`): Contains currentStep (id, status, output, payload) and workflowState (status, steps record)

package/dist/index.cjs

@@ -354,7 +354,7 @@ function safeParseJSON({
   }
 }
 
-// ../../node_modules/.pnpm/zod-to-json-schema@3.24.6_zod@3.25.76/node_modules/zod-to-json-schema/dist/esm/parsers/string.js
+// ../../node_modules/.pnpm/zod-to-json-schema@3.25.1_zod@3.25.76/node_modules/zod-to-json-schema/dist/esm/parsers/string.js
 new Set("ABCDEFGHIJKLMNOPQRSTUVXYZabcdefghijklmnopqrstuvxyz0123456789");
 function fixJson(input) {
   const stack = ["ROOT"];
@@ -4953,6 +4953,23 @@ var MastraClient = class extends BaseResource {
   getWorkspace(workspaceId) {
     return new Workspace(this.options, workspaceId);
   }
+  // ============================================================================
+  // Vectors & Embedders
+  // ============================================================================
+  /**
+   * Lists all available vector stores
+   * @returns Promise containing list of available vector stores
+   */
+  listVectors() {
+    return this.request("/vectors");
+  }
+  /**
+   * Lists all available embedding models
+   * @returns Promise containing list of available embedders
+   */
+  listEmbedders() {
+    return this.request("/embedders");
+  }
 };
 
 // src/tools.ts