@mastra/client-js 1.0.0-beta.8 → 1.0.0

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

@@ -0,0 +1,256 @@
+> 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/v1/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@beta
+    ```
+
+  
+  **pnpm:**
+
+    ```bash
+    pnpm add @mastra/client-js@beta
+    ```
+
+  
+  **yarn:**
+
+    ```bash
+    yarn add @mastra/client-js@beta
+    ```
+
+  
+  **bun:**
+
+    ```bash
+    bun add @mastra/client-js@beta
+    ```
+
+  
+
+### 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"
+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/v1/client-js/agents)**: Generate responses and stream conversations.
+- **[Memory](https://mastra.ai/reference/v1/client-js/memory)**: Manage conversation threads and message history.
+- **[Tools](https://mastra.ai/reference/v1/client-js/tools)**: Executed and managed tools.
+- **[Workflows](https://mastra.ai/reference/v1/client-js/workflows)**: Trigger workflows and track their execution.
+- **[Vectors](https://mastra.ai/reference/v1/client-js/vectors)**: Use vector embeddings for semantic search.
+- **[Logs](https://mastra.ai/reference/v1/client-js/logs)**: View logs and debug system behavior.
+- **[Telemetry](https://mastra.ai/reference/v1/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";
+  }
+};
+```
+
+> **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/v1/client-js/agents#generate) 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";
+  }
+};
+```
+
+> **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/v1/client-js/agents#stream) 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"
+import { MastraClient } from "@mastra/client-js";
+
+export const mastraClient = new MastraClient({
+  retries: 3,
+  backoffMs: 300,
+  maxBackoffMs: 5000,
+  headers: {
+    "X-Development": "true",
+  },
+});
+```
+
+> **Note:**
+
+Visit [MastraClient](https://mastra.ai/reference/v1/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 {3,7} title="lib/mastra-client.ts"
+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 {4}
+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 {27}
+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](../agents/overview#setting-up-agents) configured to return hex color codes, intended to work with the browser-based client tool defined above.
+
+```typescript title="src/mastra/agents/color-agent"
+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 {8}
+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/v1/client-js/error-handling) for development scenarios.
+2. **Environment Variables**: Use environment variables for configuration.
+3. **Debugging**: Enable detailed [logging](https://mastra.ai/reference/v1/client-js/logs) when needed.
+4. **Performance**: Monitor application performance, [telemetry](https://mastra.ai/reference/v1/client-js/telemetry) and traces.

package/dist/docs/server/02-jwt.md

@@ -0,0 +1,99 @@
+> Documentation for the MastraJwtAuth class, which authenticates Mastra applications using JSON Web Tokens.
+
+# 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.
+
+```bash
+npm install @mastra/auth@beta
+```
+
+## Usage example
+
+```typescript {2,6-8} title="src/mastra/index.ts"
+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,
+    }),
+  },
+});
+```
+
+> **Note:**
+
+Visit [MastraJwtAuth](https://mastra.ai/reference/v1/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 {6} title="lib/mastra/mastra-client.ts"
+import { MastraClient } from "@mastra/client-js";
+
+export const mastraClient = new MastraClient({
+  baseUrl: "https://<mastra-api-url>",
+  headers: {
+    Authorization: `Bearer ${process.env.MASTRA_JWT_TOKEN}`,
+  },
+});
+```
+
+> **Note:**
+
+Visit [Mastra Client SDK](https://mastra.ai/docs/v1/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 title="src/components/test-agent.tsx" copy
+    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/server/03-clerk.md

@@ -0,0 +1,143 @@
+> Documentation for the MastraAuthClerk class, which authenticates Mastra applications using Clerk authentication.
+
+# MastraAuthClerk Class
+
+The `MastraAuthClerk` class provides authentication for Mastra using Clerk. It verifies incoming requests using Clerk's authentication system and integrates with the Mastra server using the `auth` option.
+
+## Prerequisites
+
+This example uses Clerk authentication. Make sure to add your Clerk credentials to your `.env` file and ensure your Clerk project is properly configured.
+
+```env title=".env"
+CLERK_PUBLISHABLE_KEY=pk_test_...
+CLERK_SECRET_KEY=sk_test_...
+CLERK_JWKS_URI=https://your-clerk-domain.clerk.accounts.dev/.well-known/jwks.json
+```
+
+> **Note:**
+
+You can find these keys in your Clerk Dashboard under "API Keys".
+
+## Installation
+
+Before you can use the `MastraAuthClerk` class you have to install the `@mastra/auth-clerk` package.
+
+```bash
+npm install @mastra/auth-clerk@beta
+```
+
+## Usage example
+
+```typescript {2,6-10} title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { MastraAuthClerk } from "@mastra/auth-clerk";
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthClerk({
+      publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+      secretKey: process.env.CLERK_SECRET_KEY,
+      jwksUri: process.env.CLERK_JWKS_URI,
+    }),
+  },
+});
+```
+
+> **Note:**
+
+The default `authorizeUser` method allows all authenticated users. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+
+Visit [MastraAuthClerk](https://mastra.ai/reference/v1/auth/clerk) for all available configuration options.
+
+## Client-side setup
+
+When using Clerk auth, you'll need to retrieve the access token from Clerk on the client side and pass it to your Mastra requests.
+
+### Retrieving the access token
+
+Use the Clerk React hooks to authenticate users and retrieve their access token:
+
+```typescript title="lib/auth.ts"
+import { useAuth } from "@clerk/nextjs";
+
+export const useClerkAuth = () => {
+  const { getToken } = useAuth();
+
+  const getAccessToken = async () => {
+    const token = await getToken();
+    return token;
+  };
+
+  return { getAccessToken };
+};
+```
+
+> **Note:**
+
+Refer to the [Clerk documentation](https://clerk.com/docs) for more information.
+
+## Configuring `MastraClient`
+
+When `auth` is enabled, all requests made with `MastraClient` must include a valid Clerk access token in the `Authorization` header:
+
+```typescript {6} title="lib/mastra/mastra-client.ts"
+import { MastraClient } from "@mastra/client-js";
+
+export const mastraClient = new MastraClient({
+  baseUrl: "https://<mastra-api-url>",
+  headers: {
+    Authorization: `Bearer ${accessToken}`,
+  },
+});
+```
+
+> **Note:**
+
+The access token must be prefixed with `Bearer` in the Authorization header.
+
+Visit [Mastra Client SDK](https://mastra.ai/docs/v1/server/mastra-client) for more configuration options.
+
+### Making authenticated requests
+
+Once `MastraClient` is configured with the Clerk access token, you can send authenticated requests:
+
+  **react:**
+
+    ```tsx title="src/components/test-agent.tsx" copy
+    "use client";
+
+    import { useAuth } from "@clerk/nextjs";
+    import { MastraClient } from "@mastra/client-js";
+
+    export const TestAgent = () => {
+      const { getToken } = useAuth();
+
+      async function handleClick() {
+        const token = await getToken();
+
+        const client = new MastraClient({
+          baseUrl: "http://localhost:4111",
+          headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+        });
+
+        const weatherAgent = client.getAgent("weatherAgent");
+        const response = await weatherAgent.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-clerk-access-token>" \
+      -d '{
+        "messages": "Weather in London"
+      }'
+    ```

package/dist/docs/server/04-supabase.md

@@ -0,0 +1,128 @@
+> Documentation for the MastraAuthSupabase class, which authenticates Mastra applications using Supabase Auth.
+
+# 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 title=".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@beta
+```
+
+## Usage example
+
+```typescript {2,6-9} title="src/mastra/index.ts"
+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,
+    }),
+  },
+});
+```
+
+> **Note:**
+
+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/v1/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 title="lib/auth.ts"
+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 {6} title="lib/mastra/mastra-client.ts"
+import { MastraClient } from "@mastra/client-js";
+
+export const mastraClient = new MastraClient({
+  baseUrl: "https://<mastra-api-url>",
+  headers: {
+    Authorization: `Bearer ${accessToken}`,
+  },
+});
+```
+
+> **Note:**
+
+The access token must be prefixed with `Bearer` in the Authorization header.
+
+Visit [Mastra Client SDK](https://mastra.ai/docs/v1/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 title="src/components/test-agent.tsx" copy
+      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"
+      }'
+    ```