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

package/dist/docs/{server/06-workos.md → references/docs-server-auth-workos.md}

@@ -1,5 +1,3 @@
-> Documentation for the MastraAuthWorkos class, which authenticates Mastra applications using WorkOS authentication.
-
 # MastraAuthWorkos Class
 
 The `MastraAuthWorkos` class provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the `auth` option.
@@ -13,16 +11,14 @@ This example uses WorkOS authentication. Make sure to:
 3. Configure your redirect URIs and allowed origins
 4. Set up Organizations and configure user roles as needed
 
-```env title=".env"
+```env
 WORKOS_API_KEY=sk_live_...
 WORKOS_CLIENT_ID=client_...
 ```
 
-> **Note:**
-
-You can find your API key and Client ID in the WorkOS Dashboard under API Keys and Applications respectively.
-
-For detailed setup instructions, refer to the [WorkOS documentation](https://workos.com/docs) for your specific platform.
+> **Note:** You can find your API key and Client ID in the WorkOS Dashboard under API Keys and Applications respectively.
+>
+> For detailed setup instructions, refer to the [WorkOS documentation](https://workos.com/docs) for your specific platform.
 
 ## Installation
 
@@ -36,7 +32,7 @@ npm install @mastra/auth-workos@latest
 
 ### Basic usage with environment variables
 
-```typescript {2,6} title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { MastraAuthWorkos } from "@mastra/auth-workos";
 
@@ -49,7 +45,7 @@ export const mastra = new Mastra({
 
 ### Custom configuration
 
-```typescript {2,6-9} title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { MastraAuthWorkos } from "@mastra/auth-workos";
 
@@ -76,7 +72,7 @@ By default, `MastraAuthWorkos` checks whether the authenticated user has an 'adm
 
 To customize user authorization, provide a custom `authorizeUser` function:
 
-```typescript title="src/mastra/auth.ts"
+```typescript
 import { MastraAuthWorkos } from "@mastra/auth-workos";
 
 const workosAuth = new MastraAuthWorkos({
@@ -88,9 +84,7 @@ const workosAuth = new MastraAuthWorkos({
 });
 ```
 
-> **Note:**
-
-Visit [MastraAuthWorkos](https://mastra.ai/reference/auth/workos) for all available configuration options.
+> **Info:** Visit [MastraAuthWorkos](https://mastra.ai/reference/auth/workos) for all available configuration options.
 
 ## Client-side setup
 
@@ -108,7 +102,7 @@ npm install @workos-inc/node
 
 After users complete the WorkOS authentication flow and return with an authorization code, exchange it for an access token:
 
-```typescript title="lib/auth.ts"
+```typescript
 import { WorkOS } from "@workos-inc/node";
 
 const workos = new WorkOS(process.env.WORKOS_API_KEY);
@@ -127,15 +121,13 @@ export const authenticateWithWorkos = async (
 };
 ```
 
-> **Note:**
-
-Refer to the [WorkOS User Management documentation](https://workos.com/docs/authkit/vanilla/nodejs) for more authentication methods and configuration options.
+> **Note:** Refer to the [WorkOS User Management documentation](https://workos.com/docs/authkit/vanilla/nodejs) for more authentication methods and configuration options.
 
 ## Configuring `MastraClient`
 
 When `auth` is enabled, all requests made with `MastraClient` must include a valid WorkOS access token in the `Authorization` header:
 
-```typescript title="lib/mastra/mastra-client.ts"
+```typescript
 import { MastraClient } from "@mastra/client-js";
 
 export const createMastraClient = (accessToken: string) => {
@@ -148,54 +140,51 @@ export const createMastraClient = (accessToken: string) => {
 };
 ```
 
-> **Note:**
-
-The access token must be prefixed with `Bearer` in the Authorization header.
-
-Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
+> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+>
+> Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 
 ### Making authenticated requests
 
 Once `MastraClient` is configured with the WorkOS access token, you can send authenticated requests:
 
-  **react:**
+**React**:
 
-    ```typescript title="src/api/agents.ts"
-    import { WorkOS } from '@workos-inc/node';
-    import { MastraClient } from '@mastra/client-js';
+```typescript
+import { WorkOS } from '@workos-inc/node';
+import { MastraClient } from '@mastra/client-js';
 
-    const workos = new WorkOS(process.env.WORKOS_API_KEY);
+const workos = new WorkOS(process.env.WORKOS_API_KEY);
 
-    export const callMastraWithWorkos = async (code: string, clientId: string) => {
-      const authenticationResponse = await workos.userManagement.authenticateWithCode({
-        code,
-        clientId,
-      });
+export const callMastraWithWorkos = async (code: string, clientId: string) => {
+  const authenticationResponse = await workos.userManagement.authenticateWithCode({
+    code,
+    clientId,
+  });
 
-      const token = authenticationResponse.accessToken;
+  const token = authenticationResponse.accessToken;
 
-      const mastra = new MastraClient({
-        baseUrl: "http://localhost:4111",
-        headers: {
-          Authorization: `Bearer ${token}`,
-        },
-      });
+  const mastra = new MastraClient({
+    baseUrl: "http://localhost:4111",
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+  });
 
-      const weatherAgent = mastra.getAgent("weatherAgent");
-      const response = await weatherAgent.generate("What's the weather like in Nairobi");
+  const weatherAgent = mastra.getAgent("weatherAgent");
+  const response = await weatherAgent.generate("What's the weather like in Nairobi");
 
-      return response.text;
-    };
-    ```
+  return response.text;
+};
+```
 
-  
-  **curl:**
+**cURL**:
 
-    ```bash
-    curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
-      -H "Content-Type: application/json" \
-      -H "Authorization: Bearer <your-workos-access-token>" \
-      -d '{
-        "messages": "Weather in London"
-      }'
-    ```
+```bash
+curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-workos-access-token>" \
+  -d '{
+    "messages": "Weather in London"
+  }'
+```

package/dist/docs/{server/01-mastra-client.md → references/docs-server-mastra-client.md}

@@ -1,5 +1,3 @@
-> Learn how to set up and use the Mastra Client SDK
-
 # Mastra Client SDK
 
 The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](https://mastra.ai/docs/server/mastra-server) from your client environment.
@@ -20,15 +18,35 @@ The Mastra Client SDK is designed for browser environments and uses the native `
 
 To use the Mastra Client SDK, install the required dependencies:
 
-```bash npm2yarn
+**npm**:
+
+```bash
 npm install @mastra/client-js@latest
 ```
 
+**pnpm**:
+
+```bash
+pnpm add @mastra/client-js@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/client-js@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/client-js@latest
+```
+
 ### Initialize the `MastraClient`
 
 Once initialized with a `baseUrl`, `MastraClient` exposes a type-safe interface for calling agents, tools, and workflows.
 
-```typescript title="lib/mastra-client.ts"
+```typescript
 import { MastraClient } from "@mastra/client-js";
 
 export const mastraClient = new MastraClient({
@@ -68,9 +86,7 @@ const testAgent = async () => {
 };
 ```
 
-> **Note:**
-
-You can also call `.generate()` with an array of message objects that include `role` and `content`. Visit the [.generate() reference](https://mastra.ai/reference/client-js/agents#generate) for more information.
+> **Info:** You can also call `.generate()` with an array of message objects that include `role` and `content`. Visit the [.generate() reference](https://mastra.ai/reference/client-js/agents) for more information.
 
 ## Streaming responses
 
@@ -96,15 +112,13 @@ const testAgent = async () => {
 };
 ```
 
-> **Note:**
-
-You can also call `.stream()` with an array of message objects that include `role` and `content`. Visit the [.stream() reference](https://mastra.ai/reference/client-js/agents#stream) for more information.
+> **Info:** You can also call `.stream()` with an array of message objects that include `role` and `content`. Visit the [.stream() reference](https://mastra.ai/reference/client-js/agents) for more information.
 
 ## Configuration options
 
 `MastraClient` accepts optional parameters like `retries`, `backoffMs`, and `headers` to control request behavior. These parameters are useful for controlling retry behavior and including diagnostic metadata.
 
-```typescript title="lib/mastra-client.ts"
+```typescript
 import { MastraClient } from "@mastra/client-js";
 
 export const mastraClient = new MastraClient({
@@ -117,9 +131,7 @@ export const mastraClient = new MastraClient({
 });
 ```
 
-> **Note:**
-
-Visit [MastraClient](https://mastra.ai/reference/client-js/mastra-client) for more configuration options.
+> **Info:** Visit [MastraClient](https://mastra.ai/reference/client-js/mastra-client) for more configuration options.
 
 ## Adding request cancelling
 
@@ -127,7 +139,7 @@ Visit [MastraClient](https://mastra.ai/reference/client-js/mastra-client) for mo
 
 Pass an `AbortSignal` to the client constructor to enable cancellation across all requests.
 
-```typescript {3,7} title="lib/mastra-client.ts"
+```typescript
 import { MastraClient } from "@mastra/client-js";
 
 export const controller = new AbortController();
@@ -142,7 +154,7 @@ export const mastraClient = new MastraClient({
 
 Calling `.abort()` will cancel any ongoing requests tied to that signal.
 
-```typescript {4}
+```typescript
 import { mastraClient, controller } from "lib/mastra-client";
 
 const handleAbort = () => {
@@ -156,7 +168,7 @@ Define tools directly in client-side applications using the `createTool()` funct
 
 This lets agents trigger browser-side functionality such as DOM manipulation, local storage access, or other Web APIs, enabling tool execution in the user's environment rather than on the server.
 
-```typescript {27}
+```typescript
 import { createTool } from "@mastra/client-js";
 import { z } from "zod";
 
@@ -194,9 +206,9 @@ const handleClientTool = async () => {
 
 ### Client tool's agent
 
-This is a standard Mastra [agent](../agents/overview#setting-up-agents) configured to return hex color codes, intended to work with the browser-based client tool defined above.
+This is a standard Mastra [agent](https://mastra.ai/docs/agents/overview) configured to return hex color codes, intended to work with the browser-based client tool defined above.
 
-```typescript title="src/mastra/agents/color-agent"
+```typescript
 import { Agent } from "@mastra/core/agent";
 
 export const colorAgent = new Agent({
@@ -213,7 +225,7 @@ export const colorAgent = new Agent({
 
 You can also use `MastraClient` in server-side environments such as API routes, serverless functions or actions. The usage will broadly remain the same but you may need to recreate the response to your client:
 
-```typescript {8}
+```typescript
 export async function action() {
   const agent = mastraClient.getAgent("testAgent");
 

package/dist/docs/{ai-sdk/01-reference.md → references/reference-ai-sdk-to-ai-sdk-stream.md}

@@ -1,13 +1,4 @@
-# Ai sdk API Reference
-
-> API reference for ai sdk - 3 entries
-
-
----
-
-## Reference: toAISdkStream()
-
-> API reference for toAISdkStream(), a function to convert Mastra streams to AI SDK-compatible streams.
+# toAISdkStream()
 
 Converts Mastra streams (agent, network, or workflow) to AI SDK-compatible streams. Use this function when you need to manually transform Mastra streams for use with AI SDK's `createUIMessageStream()` and `createUIMessageStreamResponse()`.
 
@@ -17,7 +8,7 @@ This is useful when building custom streaming endpoints outside Mastra's provide
 
 Next.js App Router example:
 
-```typescript title="app/api/chat/route.ts"
+```typescript
 import { mastra } from "../../mastra";
 import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
@@ -42,24 +33,41 @@ export async function POST(req: Request) {
 }
 ```
 
-> **Note:**
-
-Pass `messages` to `originalMessages` in `createUIMessageStream()` to avoid duplicated assistant messages in the UI. See [Troubleshooting: Repeated Assistant Messages](https://ai-sdk.dev/docs/troubleshooting/repeated-assistant-messages) for details.
+> **Tip:** Pass `messages` to `originalMessages` in `createUIMessageStream()` to avoid duplicated assistant messages in the UI. See [Troubleshooting: Repeated Assistant Messages](https://ai-sdk.dev/docs/troubleshooting/repeated-assistant-messages) for details.
 
 ## Parameters
 
 The first parameter is the Mastra stream to convert. It can be one of:
+
 - `MastraModelOutput` - An agent stream from `agent.stream()`
 - `MastraAgentNetworkStream` - A network stream from `agent.network()`
 - `MastraWorkflowStream` or `WorkflowRunOutput` - A workflow stream
 
 The second parameter is an options object:
 
+**from:** (`'agent' | 'network' | 'workflow'`): The type of Mastra stream being converted. (Default: `'agent'`)
+
+**lastMessageId?:** (`string`): (Agent only) The ID of the last message in the conversation.
+
+**sendStart?:** (`boolean`): (Agent only) Whether to send start events in the stream. (Default: `true`)
+
+**sendFinish?:** (`boolean`): (Agent only) Whether to send finish events in the stream. (Default: `true`)
+
+**sendReasoning?:** (`boolean`): (Agent only) Whether to include reasoning-delta chunks in the stream. Set to true to stream reasoning content from models that support extended thinking. (Default: `false`)
+
+**sendSources?:** (`boolean`): (Agent only) Whether to include source citations in the output. (Default: `false`)
+
+**includeTextStreamParts?:** (`boolean`): (Workflow only) Whether to include text stream parts in the output. (Default: `true`)
+
+**messageMetadata?:** (`(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined`): (Agent only) A function that receives the current stream part and returns metadata to attach to start and finish chunks.
+
+**onError?:** (`(error: unknown) => string`): (Agent only) A function to handle errors during stream conversion. Receives the error and should return a string representation.
+
 ## Examples
 
 ### Converting a workflow stream
 
-```typescript title="app/api/workflow/route.ts" {13}
+```typescript
 import { mastra } from "../../mastra";
 import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
@@ -86,7 +94,7 @@ export async function POST(req: Request) {
 
 ### Converting a network stream
 
-```typescript title="app/api/network/route.ts" {12}
+```typescript
 import { mastra } from "../../mastra";
 import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
@@ -112,7 +120,7 @@ export async function POST(req: Request) {
 
 ### Converting an agent stream with reasoning enabled
 
-```typescript title="app/api/reasoning/route.ts" {8-12,17-20}
+```typescript
 import { mastra } from "../../mastra";
 import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
@@ -146,7 +154,7 @@ export async function POST(req: Request) {
 
 ### Using messageMetadata
 
-```typescript title="app/api/chat-with-metadata/route.ts" {13-19}
+```typescript
 import { mastra } from "../../mastra";
 import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
@@ -181,7 +189,7 @@ export async function POST(req: Request) {
 
 If you're using the Mastra client SDK (`@mastra/client-js`) on the client side and want to convert streams to AI SDK format:
 
-```typescript title="client-stream-to-ai-sdk.ts" {14-23,25-35}
+```typescript
 import { MastraClient } from "@mastra/client-js";
 import { createUIMessageStream } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
@@ -221,138 +229,4 @@ const uiMessageStream = createUIMessageStream({
 for await (const part of uiMessageStream) {
   console.log(part);
 }
-```
-
----
-
-## Reference: toAISdkV4Messages()
-
-> API reference for toAISdkV4Messages(), a function to convert Mastra messages to AI SDK v4 UI messages.
-
-Converts messages from various input formats to AI SDK V4 UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V4 `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
-
-## Usage example
-
-```typescript title="app/chat/page.tsx"
-import { toAISdkV4Messages } from "@mastra/ai-sdk";
-import { useChat } from "ai/react"; // AI SDK V4
-
-// Stored messages from your database, memory or API
-const storedMessages = [
-  { id: "1", role: "user", parts: [{ type: "text", text: "Hello" }] },
-  { id: "2", role: "assistant", parts: [{ type: "text", text: "Hi there!" }] }
-];
-
-export default function Chat() {
-  const { messages } = useChat({
-    initialMessages: toAISdkV4Messages(storedMessages)
-  });
-
-  return (
-    <div>
-      {messages.map((message) => (
-        <div key={message.id}>
-          {message.role}: {message.content}
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-## Parameters
-
-## Returns
-
-Returns an array of AI SDK V4 `UIMessage` objects with the following structure:
-
-## Examples
-
-### Converting simple text messages
-
-```typescript
-import { toAISdkV4Messages } from "@mastra/ai-sdk";
-
-const messages = toAISdkV4Messages(["Hello", "How can I help you today?"]);
-// Returns array of UIMessage objects with user role and content string
-```
-
-### Loading messages with Mastra client
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-import { toAISdkV4Messages } from "@mastra/ai-sdk";
-
-const client = new MastraClient();
-
-const { messages } = await client.listThreadMessages("thread-id", { agentId: "myAgent" });
-const uiMessages = toAISdkV4Messages(messages);
-```
-
----
-
-## Reference: toAISdkV5Messages()
-
-> API reference for toAISdkV5Messages(), a function to convert Mastra messages to AI SDK v5 UI messages.
-
-Converts messages from various input formats to AI SDK V5 (and later) UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V5+ `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
-
-## Usage example
-
-```typescript title="app/chat/page.tsx"
-import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
-import { useChat } from "ai/react";
-
-// Stored messages from your database, memory or API
-const storedMessages = [
-  { id: "1", role: "user", content: "Hello", parts: [{ type: "text", text: "Hello" }] },
-  { id: "2", role: "assistant", content: "Hi there!", parts: [{ type: "text", text: "Hi there!" }] }
-];
-
-export default function Chat() {
-  const { messages } = useChat({
-    initialMessages: toAISdkV5Messages(storedMessages)
-  });
-
-  return (
-    <div>
-      {messages.map((message) => (
-        <div key={message.id}>
-          {message.role}: {message.parts.map(part => 
-            part.type === "text" ? part.text : null
-          )}
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-## Parameters
-
-## Returns
-
-Returns an array of AI SDK V5+ `UIMessage` objects with the following structure:
-
-## Examples
-
-### Converting simple text messages
-
-```typescript
-import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
-
-const messages = toAISdkV5Messages(["Hello", "How can I help you today?"]);
-// Returns array of UIMessage objects with user role
-```
-
-### Loading messages with Mastra client
-
-```typescript
-import { MastraClient } from "@mastra/client-js";
-import { toAISdkV5Messages } from "@mastra/ai-sdk/ui";
-
-const client = new MastraClient();
-
-const { messages } = await client.listThreadMessages("thread-id", { agentId: "myAgent" });
-const uiMessages = toAISdkV5Messages(messages);
 ```

package/dist/docs/references/reference-ai-sdk-to-ai-sdk-v4-messages.md

@@ -0,0 +1,79 @@
+# toAISdkV4Messages()
+
+Converts messages from various input formats to AI SDK V4 UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V4 `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
+
+## Usage example
+
+```typescript
+import { toAISdkV4Messages } from "@mastra/ai-sdk";
+import { useChat } from "ai/react"; // AI SDK V4
+
+// Stored messages from your database, memory or API
+const storedMessages = [
+  { id: "1", role: "user", parts: [{ type: "text", text: "Hello" }] },
+  { id: "2", role: "assistant", parts: [{ type: "text", text: "Hi there!" }] }
+];
+
+export default function Chat() {
+  const { messages } = useChat({
+    initialMessages: toAISdkV4Messages(storedMessages)
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.role}: {message.content}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Parameters
+
+**messages:** (`MessageListInput`): Messages to convert. Can be a string, array of strings, a single message object, or an array of message objects in any supported format.
+
+## Returns
+
+Returns an array of AI SDK V4 `UIMessage` objects with the following structure:
+
+**id:** (`string`): Unique message identifier.
+
+**role:** (`'user' | 'assistant' | 'system'`): The role of the message sender.
+
+**content:** (`string`): Text content of the message.
+
+**parts:** (`UIMessagePart[]`): Array of UI parts including text, tool-invocation, file, reasoning, source, and step markers.
+
+**createdAt:** (`Date`): Message creation timestamp.
+
+**toolInvocations?:** (`ToolInvocation[]`): Array of tool invocations for assistant messages.
+
+**experimental\_attachments?:** (`Attachment[]`): File attachments on the message.
+
+**metadata?:** (`Record<string, unknown>`): Custom metadata attached to the message.
+
+## Examples
+
+### Converting simple text messages
+
+```typescript
+import { toAISdkV4Messages } from "@mastra/ai-sdk";
+
+const messages = toAISdkV4Messages(["Hello", "How can I help you today?"]);
+// Returns array of UIMessage objects with user role and content string
+```
+
+### Loading messages with Mastra client
+
+```typescript
+import { MastraClient } from "@mastra/client-js";
+import { toAISdkV4Messages } from "@mastra/ai-sdk";
+
+const client = new MastraClient();
+
+const { messages } = await client.listThreadMessages("thread-id", { agentId: "myAgent" });
+const uiMessages = toAISdkV4Messages(messages);
+```