@mastra/client-js 1.39.0-alpha.8 → 1.39.0

package/dist/docs/references/reference-migrations-upgrade-to-v1-client.md

@@ -0,0 +1,339 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Client SDK
+
+Client SDK changes align with server-side API updates, including utility renames, updated pagination, and type naming conventions.
+
+## Changed
+
+### `messages` is now identical to `@mastra/core/agent` syntax
+
+The `messages` argument is now the first argument of the `generate`, `stream` and `network` method calls, similar to the NodeJS version in `@mastra/core/agent`.
+
+To migrate, move `messages` to the first argument of the method call:
+
+**Using `@mastra/client-js`:**
+
+```diff
+const agent = client.getAgent('my-agent');
+
+-  await agent.generate({
+-    messages: [...]
++  await agent.generate([...], {
+  });
+
+-  await agent.stream({
+-    messages: [...]
++  await agent.stream([...], {
+  });
+
+-  await agent.network({
+-    messages: [...]
++  await agent.network([...], {
+  });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-msg-function-args .
+> ```
+
+### `threadId` and `resourceId` to `memory` option
+
+The `threadId` and `resourceId` options have been removed from agent method calls. Use the `memory` option instead, which provides a cleaner API for memory configuration. This applies to both `@mastra/client-js` and `@mastra/react` packages.
+
+To migrate, move `threadId` and `resourceId` into the `memory` option:
+
+**Using `@mastra/client-js`:**
+
+```diff
+const agent = client.getAgent('my-agent');
+
+  await agent.generate([...], {
+-   threadId: 'thread-123',
+-   resourceId: 'user-456',
++   memory: {
++     thread: 'thread-123',
++     resource: 'user-456',
++   },
+  });
+
++  await agent.stream([...], {
+-   threadId: 'thread-123',
+-   resourceId: 'user-456',
++   memory: {
++     thread: 'thread-123',
++     resource: 'user-456',
++   },
+  });
+```
+
+#### Using `@mastra/react` `useChat` hook
+
+The `useChat` hook internally passes the memory option when you provide a `threadId`. No changes are needed in your component code if you're using the hook's built-in memory handling. However, if you were manually passing options to `sendMessage`, update them accordingly:
+
+```diff
+const { sendMessage } = useChat({ agentId: 'my-agent' });
+
+  await sendMessage({
+    message: 'Hello',
+    mode: 'stream',
+-   threadId: 'thread-123',
++   threadId: 'thread-123', // Still works - internally converted to memory option
+  });
+```
+
+The `memory` option also supports passing thread metadata when creating new threads:
+
+```typescript
+await agent.generate([...], {
+  memory: {
+    thread: {
+      id: 'thread-123',
+      title: 'Support conversation',
+      metadata: { category: 'billing' },
+    },
+    resource: 'user-456',
+  },
+});
+```
+
+### Client SDK types from `Get*` to `List*`
+
+Client SDK types have been renamed from `Get*` to `List*` pattern. This change aligns type names with the method naming convention.
+
+To migrate, update type imports to use the new naming pattern.
+
+```diff
+- import type {
+-   GetWorkflowRunsParams,
+-   GetWorkflowRunsResponse,
+-   GetMemoryThreadParams,
+- } from '@mastra/client-js';
++ import type {
++   ListWorkflowRunsParams,
++   ListWorkflowRunsResponse,
++   ListMemoryThreadsParams,
++ } from '@mastra/client-js';
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-sdk-types .
+> ```
+
+### Pagination parameters from `offset/limit` to `page/perPage`
+
+All client SDK methods that used `offset/limit` now use `page/perPage`, matching page-based web pagination.
+
+To migrate, update pagination parameters in all client SDK method calls. Example:
+
+```diff
+client.memory.listMessages({
+    threadId: 'thread-123',
+-   offset: 0,
+-   limit: 20,
++   page: 0,
++   perPage: 20,
+  });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-offset-limit .
+> ```
+
+### `getMemoryThread` parameter structure
+
+The `getMemoryThread` method parameter structure has been updated. This change provides a more consistent API across memory methods.
+
+To migrate, update the method call with the new parameter structure. Check the updated API documentation for the specific changes.
+
+```diff
+- const thread = await client.getMemoryThread(threadId, agentId);
++ const thread = await client.getMemoryThread({ threadId, agentId });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-get-memory-thread .
+> ```
+
+### Unified `runById` API for workflow runs
+
+The `runById()` method now returns a unified `WorkflowState` object containing both metadata (runId, workflowName, resourceId, createdAt, updatedAt) and processed execution state (status, result, error, payload, steps). This unifies the previously separate `runById()` and `runExecutionResult()` methods.
+
+The method also accepts an options object with optional `fields` and `withNestedWorkflows` parameters for performance optimization.
+
+```diff
+const workflow = client.getWorkflow('my-workflow');
+
+- // Previously: runById returned raw WorkflowRun with snapshot
+- const run = await workflow.runById(runId, requestContext);
+- // Separately: runExecutionResult returned processed execution state
+- const result = await workflow.runExecutionResult(runId);
+
++ // Now: Single method returns unified WorkflowState
++ const run = await workflow.runById(runId, {
++   requestContext,  // Optional request context
++   fields: ['status', 'result'],  // Optional: request only specific fields
++   withNestedWorkflows: false,  // Optional: skip nested workflow data for performance
++ });
++ // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
+```
+
+## Removed
+
+### `runExecutionResult` method and `GetWorkflowRunExecutionResultResponse` type
+
+The `runExecutionResult()` method and `GetWorkflowRunExecutionResultResponse` type have been removed from `@mastra/client-js`. The `/execution-result` API endpoints have also been removed.
+
+To migrate, use `runById()` instead, which now returns the same unified `WorkflowState` with both metadata and processed execution state.
+
+```diff
+- import type { GetWorkflowRunExecutionResultResponse } from '@mastra/client-js';
+-
+- const workflow = client.getWorkflow('my-workflow');
+- const result = await workflow.runExecutionResult(runId);
+
++ const workflow = client.getWorkflow('my-workflow');
++ 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
++ });
+```
+
+### `toAISdkFormat` function
+
+The `toAISdkFormat()` function has been removed from `@mastra/ai-sdk`. Use the stream conversion utilities shown below instead.
+
+To migrate, use `toAISdkStream()` instead.
+
+```diff
+- import { toAISdkFormat } from '@mastra/ai-sdk';
+- const stream = toAISdkFormat(agentStream, { from: 'agent' });
++ import { toAISdkStream } from '@mastra/ai-sdk';
++ const stream = toAISdkStream(agentStream, { from: 'agent' });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-to-ai-sdk-format .
+> ```
+
+### Network memory methods
+
+Network memory methods have been removed from `@mastra/client-js`. The `NetworkMemoryThread` class and all network memory-related methods are no longer available. This change simplifies the memory API by removing specialized network memory functionality.
+
+To migrate, use regular memory APIs instead of network memory.
+
+```diff
+- import { MastraClient } from '@mastra/client-js';
+-
+- const client = new MastraClient({ baseUrl: '...' });
+- const networkThread = client.networkMemory.getThread('thread-id');
+- const networkThread = client.memory.networkThread('thread-id', 'network-id');
+- await networkThread.get();
+- await networkThread.getMessages();
+
++ // Use regular memory thread APIs instead
++ const client = new MastraClient({ baseUrl: '...' });
++ const thread = client.memory.getThread('thread-id');
++ await thread.get();
++ const messages = await thread.listMessages();
+```
+
+### Watch-related types
+
+Watch-related types have been removed from `@mastra/client-js`. This includes `WorkflowWatchResult`, `WatchEvent`, and related types. This change reflects the removal of the watch API in favor of streaming.
+
+To migrate, use workflow streaming APIs instead of watch.
+
+```diff
+- import type { WorkflowWatchResult, WatchEvent } from '@mastra/client-js';
+-
+- const workflow = client.getWorkflow('my-workflow');
+- const run = await workflow.createRun();
+- await run.watch((event: WatchEvent) => {
+-   console.log('Event:', event);
+- });
+
++ const workflow = client.getWorkflow('my-workflow');
++ const run = await workflow.createRun();
++ const stream = await run.stream({ inputData: { ... } });
++ for await (const chunk of stream) {
++   console.log('Event:', chunk);
++ }
+```
+
+### Run-related methods can't be called directly on workflow instance
+
+Run-related methods can't be called directly on workflow instance. You need to create a run instance first using `createRun()` method.
+
+```diff
+- const result = await workflow.start({ runId: '123', inputData: { ... } });
++ const run = await workflow.createRun({ runId: '123' });
++ const result = await run.start({ inputData: { ... } });
+```
+
+```diff
+- const result = await workflow.stream({ runId: '123', inputData: { ... } });
++ const run = await workflow.createRun({ runId: '123' });
++ const stream = await run.stream({ inputData: { ... } });
+```
+
+### `streamVNext`, `resumeStreamVNext`, and `observeStreamVNext` methods
+
+The experimental `streamVNext()`, `resumeStreamVNext()`, and `observeStreamVNext()` methods have been removed. These methods are now the standard implementation with updated event structures and return types.
+
+To migrate, use the standard `stream()`, `resumeStream()`, and `observeStream()` methods instead.
+
+```diff
++ const run = await workflow.createRun({ runId: '123' });
+- const stream = await run.streamVNext({ inputData: { ... } });
++ const stream = await run.stream({ inputData: { ... } });
+```
+
+### Deprecated stream endpoints
+
+Some stream endpoints are deprecated and will be removed. The `/api/agents/:agentId/stream/vnext` endpoint returns 410 Gone, and `/api/agents/:agentId/stream/ui` is deprecated. This change consolidates on standard streaming endpoints.
+
+To migrate, use the standard stream endpoint or `@mastra/ai-sdk` for UI message transformations.
+
+```diff
+- const response = await fetch('/api/agents/my-agent/stream/vnext', {
+-   method: 'POST',
+-   body: JSON.stringify({ messages: [...] }),
+- });
+
++ const response = await fetch('/api/agents/my-agent/stream', {
++   method: 'POST',
++   body: JSON.stringify({ messages: [...] }),
++ });
++
++ // Or use @mastra/ai-sdk for UI message transformations
+```
+
+### Network memory API endpoints
+
+Network memory API endpoints have been removed including `/api/memory/network/*`. This change simplifies the memory API surface.
+
+To migrate, use regular memory API endpoints.
+
+```diff
+- const networkThread = await fetch('/api/memory/network/threads/thread-123');
++ const thread = await fetch('/api/memory/threads/thread-123');
+```
+
+### Eval-related client SDK types
+
+Several eval-related types have been removed from the client SDK including `GetEvalsByAgentIdResponse`, `GetTelemetryResponse`, and `GetTelemetryParams`. This change reflects the removal of legacy evals functionality.
+
+To migrate, use the new scorers API instead of legacy evals.