@mastra/client-js 1.7.0 → 1.7.1

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

@@ -0,0 +1,272 @@
+# MastraAuthFirebase Class
+
+The `MastraAuthFirebase` class provides authentication for Mastra using Firebase Authentication. It verifies incoming requests using Firebase ID tokens and integrates with the Mastra server using the `auth` option.
+
+## Prerequisites
+
+This example uses Firebase Authentication. Make sure to:
+
+1. Create a Firebase project in the [Firebase Console](https://console.firebase.google.com/)
+2. Enable Authentication and configure your preferred sign-in methods (Google, Email/Password, etc.)
+3. Generate a service account key from Project Settings > Service Accounts
+4. Download the service account JSON file
+
+```env
+FIREBASE_SERVICE_ACCOUNT=/path/to/your/service-account-key.json
+FIRESTORE_DATABASE_ID=(default)
+# Alternative environment variable names:
+# FIREBASE_DATABASE_ID=(default)
+```
+
+> **Note:** Store your service account JSON file securely and never commit it to version control.
+
+## Installation
+
+Before you can use the `MastraAuthFirebase` class you have to install the `@mastra/auth-firebase` package.
+
+```bash
+npm install @mastra/auth-firebase@latest
+```
+
+## Usage examples
+
+### Basic usage with environment variables
+
+If you set the required environment variables (`FIREBASE_SERVICE_ACCOUNT` and `FIRESTORE_DATABASE_ID`), you can initialize `MastraAuthFirebase` without any constructor arguments. The class will automatically read these environment variables as configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthFirebase } from '@mastra/auth-firebase'
+
+// Automatically uses FIREBASE_SERVICE_ACCOUNT and FIRESTORE_DATABASE_ID env vars
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthFirebase(),
+  },
+})
+```
+
+### Custom configuration
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthFirebase } from '@mastra/auth-firebase'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthFirebase({
+      serviceAccount: '/path/to/service-account.json',
+      databaseId: 'your-database-id',
+    }),
+  },
+})
+```
+
+## Configuration
+
+The `MastraAuthFirebase` class can be configured through constructor options or environment variables.
+
+### Environment Variables
+
+- `FIREBASE_SERVICE_ACCOUNT`: Path to Firebase service account JSON file
+- `FIRESTORE_DATABASE_ID` or `FIREBASE_DATABASE_ID`: Firestore database ID
+
+> **Note:** When constructor options are not provided, the class automatically reads these environment variables. This means you can simply call `new MastraAuthFirebase()` without any arguments if your environment variables are properly configured.
+
+### User Authorization
+
+By default, `MastraAuthFirebase` uses Firestore to manage user access. It expects a collection named `user_access` with documents keyed by user UIDs. The presence of a document in this collection determines whether a user is authorized.
+
+```text
+user_access/
+  {user_uid_1}/     // Document exists = user authorized
+  {user_uid_2}/     // Document exists = user authorized
+```
+
+To customize user authorization, provide a custom `authorizeUser` function:
+
+```typescript
+import { MastraAuthFirebase } from '@mastra/auth-firebase'
+
+const firebaseAuth = new MastraAuthFirebase({
+  authorizeUser: async user => {
+    // Custom authorization logic
+    return user.email?.endsWith('@yourcompany.com') || false
+  },
+})
+```
+
+> **Info:** Visit [MastraAuthFirebase](https://mastra.ai/reference/auth/firebase) for all available configuration options.
+
+## Client-side setup
+
+When using Firebase auth, you'll need to initialize Firebase on the client side, authenticate users, and retrieve their ID tokens to pass to your Mastra requests.
+
+### Setting up Firebase on the client
+
+First, initialize Firebase in your client application:
+
+```typescript
+import { initializeApp } from 'firebase/app'
+import { getAuth, GoogleAuthProvider } from 'firebase/auth'
+
+const firebaseConfig = {
+  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
+  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
+  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
+}
+
+const app = initializeApp(firebaseConfig)
+export const auth = getAuth(app)
+export const googleProvider = new GoogleAuthProvider()
+```
+
+### Authenticating users and retrieving tokens
+
+Use Firebase authentication to sign in users and retrieve their ID tokens:
+
+```typescript
+import { signInWithPopup, signOut, User } from 'firebase/auth'
+import { auth, googleProvider } from './firebase'
+
+export const signInWithGoogle = async () => {
+  try {
+    const result = await signInWithPopup(auth, googleProvider)
+    return result.user
+  } catch (error) {
+    console.error('Error signing in:', error)
+    throw error
+  }
+}
+
+export const getIdToken = async (user: User) => {
+  try {
+    const idToken = await user.getIdToken()
+    return idToken
+  } catch (error) {
+    console.error('Error getting ID token:', error)
+    throw error
+  }
+}
+
+export const signOutUser = async () => {
+  try {
+    await signOut(auth)
+  } catch (error) {
+    console.error('Error signing out:', error)
+    throw error
+  }
+}
+```
+
+> **Note:** Refer to the [Firebase documentation](https://firebase.google.com/docs/auth) for other authentication methods like email/password, phone authentication, and more.
+
+## Configuring `MastraClient`
+
+When `auth` is enabled, all requests made with `MastraClient` must include a valid Firebase ID token in the `Authorization` header:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+export const createMastraClient = (idToken: string) => {
+  return new MastraClient({
+    baseUrl: 'https://<mastra-api-url>',
+    headers: {
+      Authorization: `Bearer ${idToken}`,
+    },
+  })
+}
+```
+
+> **Info:** The ID 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 Firebase ID token, you can send authenticated requests:
+
+**React**:
+
+```tsx
+'use client'
+
+import { useAuthState } from 'react-firebase-hooks/auth'
+import { MastraClient } from '@mastra/client-js'
+import { auth } from '../lib/firebase'
+import { getIdToken } from '../lib/auth'
+
+export const TestAgent = () => {
+  const [user] = useAuthState(auth)
+
+  async function handleClick() {
+    if (!user) return
+
+    const token = await getIdToken(user)
+    const client = createMastraClient(token)
+
+    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} disabled={!user}>
+      Test Agent
+    </button>
+  )
+}
+```
+
+**Node.js**:
+
+```typescript
+const express = require('express')
+const admin = require('firebase-admin')
+const { MastraClient } = require('@mastra/client-js')
+
+// Initialize Firebase Admin
+admin.initializeApp({
+  credential: admin.credential.cert({
+    // Your service account credentials
+  }),
+})
+
+const app = express()
+app.use(express.json())
+
+app.post('/generate', async (req, res) => {
+  try {
+    const { idToken } = req.body
+
+    // Verify the token
+    await admin.auth().verifyIdToken(idToken)
+
+    const mastra = new MastraClient({
+      baseUrl: 'http://localhost:4111',
+      headers: {
+        Authorization: `Bearer ${idToken}`,
+      },
+    })
+
+    const weatherAgent = mastra.getAgent('weatherAgent')
+    const response = await weatherAgent.generate("What's the weather like in Nairobi")
+
+    res.json({ response: response.text })
+  } catch (error) {
+    res.status(401).json({ error: 'Unauthorized' })
+  }
+})
+```
+
+**cURL**:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-firebase-id-token>" \
+  -d '{
+    "messages": "Weather in London"
+  }'
+```

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"
+  }'
+```