@mastra/client-js 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/dist/docs/references/docs-server-auth-jwt.md

@@ -0,0 +1,110 @@
+# MastraJwtAuth Class
+
+The `MastraJwtAuth` class provides a lightweight authentication mechanism for Mastra using JSON Web Tokens (JWTs). It verifies incoming requests based on a shared secret and integrates with the Mastra server using the `auth` option.
+
+## Installation
+
+Before you can use the `MastraJwtAuth` class you have to install the `@mastra/auth` package.
+
+**npm**:
+
+```bash
+npm install @mastra/auth@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/auth@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/auth@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/auth@latest
+```
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraJwtAuth } from '@mastra/auth'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraJwtAuth({
+      secret: process.env.MASTRA_JWT_SECRET,
+    }),
+  },
+})
+```
+
+> **Info:** Visit [MastraJwtAuth](https://mastra.ai/reference/auth/jwt) for all available configuration options.
+
+## Configuring `MastraClient`
+
+When `auth` is enabled, all requests made with `MastraClient` must include a valid JWT in the `Authorization` header:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+export const mastraClient = new MastraClient({
+  baseUrl: 'https://<mastra-api-url>',
+  headers: {
+    Authorization: `Bearer ${process.env.MASTRA_JWT_TOKEN}`,
+  },
+})
+```
+
+> **Info:** Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
+
+### Making authenticated requests
+
+Once `MastraClient` is configured, you can send authenticated requests from your frontend application, or use `curl` for quick local testing:
+
+**React**:
+
+```tsx
+import { mastraClient } from '../../lib/mastra-client'
+
+export const TestAgent = () => {
+  async function handleClick() {
+    const agent = mastraClient.getAgent('weatherAgent')
+
+    const response = await agent.generate('Weather in London')
+
+    console.log(response)
+  }
+
+  return <button onClick={handleClick}>Test Agent</button>
+}
+```
+
+**cURL**:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-jwt>" \
+  -d '{
+    "messages": "Weather in London"
+  }'
+```
+
+## Creating a JWT
+
+To authenticate requests to your Mastra server, you'll need a valid JSON Web Token (JWT) signed with your `MASTRA_JWT_SECRET`.
+
+The easiest way to generate one is using [jwt.io](https://www.jwt.io/):
+
+1. Select **JWT Encoder**.
+2. Scroll down to the **Sign JWT: Secret** section.
+3. Enter your secret (for example: `supersecretdevkeythatishs256safe!`).
+4. Click **Generate example** to create a valid JWT.
+5. Copy the generated token and set it as `MASTRA_JWT_TOKEN` in your `.env` file.

package/dist/docs/references/docs-server-auth-supabase.md

@@ -0,0 +1,117 @@
+# MastraAuthSupabase Class
+
+The `MastraAuthSupabase` class provides authentication for Mastra using Supabase Auth. It verifies incoming requests using Supabase's authentication system and integrates with the Mastra server using the `auth` option.
+
+## Prerequisites
+
+This example uses Supabase Auth. Make sure to add your Supabase credentials to your `.env` file and ensure your Supabase project is properly configured.
+
+```env
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_KEY=your-anon-key
+```
+
+> **Note:** Review your Supabase Row Level Security (RLS) settings to ensure proper data access controls.
+
+## Installation
+
+Before you can use the `MastraAuthSupabase` class you have to install the `@mastra/auth-supabase` package.
+
+```bash
+npm install @mastra/auth-supabase@latest
+```
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthSupabase } from '@mastra/auth-supabase'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthSupabase({
+      url: process.env.SUPABASE_URL,
+      anonKey: process.env.SUPABASE_ANON_KEY,
+    }),
+  },
+})
+```
+
+> **Info:** The default `authorizeUser` method checks the `isAdmin` column in the `users` table in the `public` schema. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+>
+> Visit [MastraAuthSupabase](https://mastra.ai/reference/auth/supabase) for all available configuration options.
+
+## Client-side setup
+
+When using Supabase auth, you'll need to retrieve the access token from Supabase on the client side and pass it to your Mastra requests.
+
+### Retrieving the access token
+
+Use the Supabase client to authenticate users and retrieve their access token:
+
+```typescript
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient('<supabase-url>', '<supabase-key>')
+
+const authTokenResponse = await supabase.auth.signInWithPassword({
+  email: "<user's email>",
+  password: "<user's password>",
+})
+
+const accessToken = authTokenResponse.data?.session?.access_token
+```
+
+> **Note:** Refer to the [Supabase documentation](https://supabase.com/docs/guides/auth) for other authentication methods like OAuth, magic links, and more.
+
+## Configuring `MastraClient`
+
+When `auth` is enabled, all requests made with `MastraClient` must include a valid Supabase access token in the `Authorization` header:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+export const mastraClient = new MastraClient({
+  baseUrl: 'https://<mastra-api-url>',
+  headers: {
+    Authorization: `Bearer ${accessToken}`,
+  },
+})
+```
+
+> **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 Supabase access token, you can send authenticated requests:
+
+**React**:
+
+```tsx
+import { mastraClient } from '../../lib/mastra-client'
+
+export const TestAgent = () => {
+  async function handleClick() {
+    const agent = mastraClient.getAgent('weatherAgent')
+
+    const response = await agent.generate("What's the weather like in New York")
+
+    console.log(response)
+  }
+
+  return <button onClick={handleClick}>Test Agent</button>
+}
+```
+
+**cURL**:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-supabase-access-token>" \
+  -d '{
+    "messages": "Weather in London"
+  }'
+```

package/dist/docs/references/docs-server-auth-workos.md

@@ -0,0 +1,186 @@
+# 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.
+
+## Prerequisites
+
+This example uses WorkOS authentication. Make sure to:
+
+1. Create a WorkOS account at [workos.com](https://workos.com/)
+2. Set up an Application in your WorkOS Dashboard
+3. Configure your redirect URIs and allowed origins
+4. Set up Organizations and configure user roles as needed
+
+```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.
+
+## Installation
+
+Before you can use the `MastraAuthWorkos` class you have to install the `@mastra/auth-workos` package.
+
+```bash
+npm install @mastra/auth-workos@latest
+```
+
+## Usage examples
+
+### Basic usage with environment variables
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthWorkos } from '@mastra/auth-workos'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthWorkos(),
+  },
+})
+```
+
+### Custom configuration
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthWorkos } from '@mastra/auth-workos'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthWorkos({
+      apiKey: process.env.WORKOS_API_KEY,
+      clientId: process.env.WORKOS_CLIENT_ID,
+    }),
+  },
+})
+```
+
+## Configuration
+
+### User Authorization
+
+By default, `MastraAuthWorkos` checks whether the authenticated user has an 'admin' role in any of their organization memberships. The authorization process:
+
+1. Retrieves the user's organization memberships using their user ID
+2. Extracts all roles from their memberships
+3. Checks if any role has the slug 'admin'
+4. Grants access only if the user has admin role in at least one organization
+
+To customize user authorization, provide a custom `authorizeUser` function:
+
+```typescript
+import { MastraAuthWorkos } from '@mastra/auth-workos'
+
+const workosAuth = new MastraAuthWorkos({
+  apiKey: process.env.WORKOS_API_KEY,
+  clientId: process.env.WORKOS_CLIENT_ID,
+  authorizeUser: async user => {
+    return !!user
+  },
+})
+```
+
+> **Info:** Visit [MastraAuthWorkos](https://mastra.ai/reference/auth/workos) for all available configuration options.
+
+## Client-side setup
+
+When using WorkOS auth, you'll need to implement the WorkOS authentication flow to exchange an authorization code for an access token, then use that token with your Mastra requests.
+
+### Installing WorkOS SDK
+
+First, install the WorkOS SDK in your application:
+
+```bash
+npm install @workos-inc/node
+```
+
+### Exchanging code for access token
+
+After users complete the WorkOS authentication flow and return with an authorization code, exchange it for an access token:
+
+```typescript
+import { WorkOS } from '@workos-inc/node'
+
+const workos = new WorkOS(process.env.WORKOS_API_KEY)
+
+export const authenticateWithWorkos = async (code: string, clientId: string) => {
+  const authenticationResponse = await workos.userManagement.authenticateWithCode({
+    code,
+    clientId,
+  })
+
+  return authenticationResponse.accessToken
+}
+```
+
+> **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
+import { MastraClient } from '@mastra/client-js'
+
+export const createMastraClient = (accessToken: string) => {
+  return new MastraClient({
+    baseUrl: 'https://<mastra-api-url>',
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+    },
+  })
+}
+```
+
+> **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**:
+
+```typescript
+import { WorkOS } from '@workos-inc/node'
+import { MastraClient } from '@mastra/client-js'
+
+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,
+  })
+
+  const token = authenticationResponse.accessToken
+
+  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")
+
+  return response.text
+}
+```
+
+**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"
+  }'
+```

package/dist/docs/references/docs-server-mastra-client.md

@@ -0,0 +1,243 @@
+# 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.
+
+## Prerequisites
+
+To ensure smooth local development, make sure you have:
+
+- Node.js `v22.13.0` or later
+- TypeScript `v4.7` or higher (if using TypeScript)
+- Your local Mastra server running (typically on port `4111`)
+
+## Usage
+
+The Mastra Client SDK is designed for browser environments and uses the native `fetch` API for making HTTP requests to your Mastra server.
+
+## Installation
+
+To use the Mastra Client SDK, install the required dependencies:
+
+**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
+import { MastraClient } from '@mastra/client-js'
+
+export const mastraClient = new MastraClient({
+  baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
+})
+```
+
+## Core APIs
+
+The Mastra Client SDK exposes all resources served by the Mastra Server
+
+- **[Agents](https://mastra.ai/reference/client-js/agents)**: Generate responses and stream conversations.
+- **[Memory](https://mastra.ai/reference/client-js/memory)**: Manage conversation threads and message history.
+- **[Tools](https://mastra.ai/reference/client-js/tools)**: Executed and managed tools.
+- **[Workflows](https://mastra.ai/reference/client-js/workflows)**: Trigger workflows and track their execution.
+- **[Vectors](https://mastra.ai/reference/client-js/vectors)**: Use vector embeddings for semantic search.
+- **[Logs](https://mastra.ai/reference/client-js/logs)**: View logs and debug system behavior.
+- **[Telemetry](https://mastra.ai/reference/client-js/telemetry)**: Monitor app performance and trace activity.
+
+## Generating responses
+
+Call `.generate()` with a string prompt:
+
+```typescript
+import { mastraClient } from 'lib/mastra-client'
+
+const testAgent = async () => {
+  try {
+    const agent = mastraClient.getAgent('testAgent')
+
+    const response = await agent.generate('Hello')
+
+    console.log(response.text)
+  } catch (error) {
+    return 'Error occurred while generating response'
+  }
+}
+```
+
+> **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
+
+Use `.stream()` for real-time responses with a string prompt:
+
+```typescript
+import { mastraClient } from 'lib/mastra-client'
+
+const testAgent = async () => {
+  try {
+    const agent = mastraClient.getAgent('testAgent')
+
+    const stream = await agent.stream('Hello')
+
+    stream.processDataStream({
+      onTextPart: text => {
+        console.log(text)
+      },
+    })
+  } catch (error) {
+    return 'Error occurred while generating response'
+  }
+}
+```
+
+> **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
+import { MastraClient } from '@mastra/client-js'
+
+export const mastraClient = new MastraClient({
+  retries: 3,
+  backoffMs: 300,
+  maxBackoffMs: 5000,
+  headers: {
+    'X-Development': 'true',
+  },
+})
+```
+
+> **Info:** Visit [MastraClient](https://mastra.ai/reference/client-js/mastra-client) for more configuration options.
+
+## Adding request cancelling
+
+`MastraClient` supports request cancellation using the standard Node.js `AbortSignal` API. Useful for canceling in-flight requests, such as when users abort an operation or to clean up stale network calls.
+
+Pass an `AbortSignal` to the client constructor to enable cancellation across all requests.
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+export const controller = new AbortController()
+
+export const mastraClient = new MastraClient({
+  baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
+  abortSignal: controller.signal,
+})
+```
+
+### Using the `AbortController`
+
+Calling `.abort()` will cancel any ongoing requests tied to that signal.
+
+```typescript
+import { mastraClient, controller } from 'lib/mastra-client'
+
+const handleAbort = () => {
+  controller.abort()
+}
+```
+
+## Client tools
+
+Define tools directly in client-side applications using the `createTool()` function. Pass them to agents via the `clientTools` parameter in `.generate()` or `.stream()` calls.
+
+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
+import { createTool } from '@mastra/client-js'
+import { z } from 'zod'
+
+const handleClientTool = async () => {
+  try {
+    const agent = mastraClient.getAgent('colorAgent')
+
+    const colorChangeTool = createTool({
+      id: 'color-change-tool',
+      description: 'Changes the HTML background color',
+      inputSchema: z.object({
+        color: z.string(),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+      }),
+      execute: async inputData => {
+        const { color } = inputData
+
+        document.body.style.backgroundColor = color
+        return { success: true }
+      },
+    })
+
+    const response = await agent.generate('Change the background to blue', {
+      clientTools: { colorChangeTool },
+    })
+
+    console.log(response)
+  } catch (error) {
+    console.error(error)
+  }
+}
+```
+
+### Client tool's agent
+
+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
+import { Agent } from '@mastra/core/agent'
+
+export const colorAgent = new Agent({
+  id: 'color-agent',
+  name: 'Color Agent',
+  instructions: `You are a helpful CSS assistant.
+  You can change the background color of web pages.
+  Respond with a hex reference for the color requested by the user`,
+  model: 'openai/gpt-5.1',
+})
+```
+
+## Server-side environments
+
+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
+export async function action() {
+  const agent = mastraClient.getAgent('testAgent')
+
+  const stream = await agent.stream('Hello')
+
+  return new Response(stream.body)
+}
+```
+
+## Best practices
+
+1. **Error Handling**: Implement proper [error handling](https://mastra.ai/reference/client-js/error-handling) for development scenarios.
+2. **Environment Variables**: Use environment variables for configuration.
+3. **Debugging**: Enable detailed [logging](https://mastra.ai/reference/client-js/logs) when needed.
+4. **Performance**: Monitor application performance, [telemetry](https://mastra.ai/reference/client-js/telemetry) and traces.