@mastra/client-js 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @mastra/client-js
 
+## 1.7.1
+
+### Patch Changes
+
+- Updated dependencies [[`df170fd`](https://github.com/mastra-ai/mastra/commit/df170fd139b55f845bfd2de8488b16435bd3d0da), [`ae55343`](https://github.com/mastra-ai/mastra/commit/ae5534397fc006fd6eef3e4f80c235bcdc9289ef), [`c290cec`](https://github.com/mastra-ai/mastra/commit/c290cec5bf9107225de42942b56b487107aa9dce), [`f03e794`](https://github.com/mastra-ai/mastra/commit/f03e794630f812b56e95aad54f7b1993dc003add), [`aa4a5ae`](https://github.com/mastra-ai/mastra/commit/aa4a5aedb80d8d6837bab8cbb2e301215d1ba3e9), [`de3f584`](https://github.com/mastra-ai/mastra/commit/de3f58408752a8d80a295275c7f23fc306cf7f4f), [`d3fb010`](https://github.com/mastra-ai/mastra/commit/d3fb010c98f575f1c0614452667396e2653815f6), [`702ee1c`](https://github.com/mastra-ai/mastra/commit/702ee1c41be67cc532b4dbe89bcb62143508f6f0), [`f495051`](https://github.com/mastra-ai/mastra/commit/f495051eb6496a720f637fc85b6d69941c12554c), [`e622f1d`](https://github.com/mastra-ai/mastra/commit/e622f1d3ab346a8e6aca6d1fe2eac99bd961e50b), [`8d14a59`](https://github.com/mastra-ai/mastra/commit/8d14a591d46fbbbe81baa33c9c267d596f790329), [`861f111`](https://github.com/mastra-ai/mastra/commit/861f11189211b20ddb70d8df81a6b901fc78d11e), [`00f43e8`](https://github.com/mastra-ai/mastra/commit/00f43e8e97a80c82b27d5bd30494f10a715a1df9), [`1b6f651`](https://github.com/mastra-ai/mastra/commit/1b6f65127d4a0d6c38d0a1055cb84527db529d6b), [`96a1702`](https://github.com/mastra-ai/mastra/commit/96a1702ce362c50dda20c8b4a228b4ad1a36a17a), [`cb9f921`](https://github.com/mastra-ai/mastra/commit/cb9f921320913975657abb1404855d8c510f7ac5), [`114e7c1`](https://github.com/mastra-ai/mastra/commit/114e7c146ac682925f0fb37376c1be70e5d6e6e5), [`1b6f651`](https://github.com/mastra-ai/mastra/commit/1b6f65127d4a0d6c38d0a1055cb84527db529d6b), [`72df4a8`](https://github.com/mastra-ai/mastra/commit/72df4a8f9bf1a20cfd3d9006a4fdb597ad56d10a)]:
+  - @mastra/core@1.8.0
+  - @mastra/schema-compat@1.1.3
+
+## 1.7.1-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`df170fd`](https://github.com/mastra-ai/mastra/commit/df170fd139b55f845bfd2de8488b16435bd3d0da), [`ae55343`](https://github.com/mastra-ai/mastra/commit/ae5534397fc006fd6eef3e4f80c235bcdc9289ef), [`c290cec`](https://github.com/mastra-ai/mastra/commit/c290cec5bf9107225de42942b56b487107aa9dce), [`f03e794`](https://github.com/mastra-ai/mastra/commit/f03e794630f812b56e95aad54f7b1993dc003add), [`aa4a5ae`](https://github.com/mastra-ai/mastra/commit/aa4a5aedb80d8d6837bab8cbb2e301215d1ba3e9), [`de3f584`](https://github.com/mastra-ai/mastra/commit/de3f58408752a8d80a295275c7f23fc306cf7f4f), [`d3fb010`](https://github.com/mastra-ai/mastra/commit/d3fb010c98f575f1c0614452667396e2653815f6), [`702ee1c`](https://github.com/mastra-ai/mastra/commit/702ee1c41be67cc532b4dbe89bcb62143508f6f0), [`f495051`](https://github.com/mastra-ai/mastra/commit/f495051eb6496a720f637fc85b6d69941c12554c), [`e622f1d`](https://github.com/mastra-ai/mastra/commit/e622f1d3ab346a8e6aca6d1fe2eac99bd961e50b), [`8d14a59`](https://github.com/mastra-ai/mastra/commit/8d14a591d46fbbbe81baa33c9c267d596f790329), [`861f111`](https://github.com/mastra-ai/mastra/commit/861f11189211b20ddb70d8df81a6b901fc78d11e), [`00f43e8`](https://github.com/mastra-ai/mastra/commit/00f43e8e97a80c82b27d5bd30494f10a715a1df9), [`1b6f651`](https://github.com/mastra-ai/mastra/commit/1b6f65127d4a0d6c38d0a1055cb84527db529d6b), [`96a1702`](https://github.com/mastra-ai/mastra/commit/96a1702ce362c50dda20c8b4a228b4ad1a36a17a), [`cb9f921`](https://github.com/mastra-ai/mastra/commit/cb9f921320913975657abb1404855d8c510f7ac5), [`114e7c1`](https://github.com/mastra-ai/mastra/commit/114e7c146ac682925f0fb37376c1be70e5d6e6e5), [`1b6f651`](https://github.com/mastra-ai/mastra/commit/1b6f65127d4a0d6c38d0a1055cb84527db529d6b), [`72df4a8`](https://github.com/mastra-ai/mastra/commit/72df4a8f9bf1a20cfd3d9006a4fdb597ad56d10a)]:
+  - @mastra/core@1.8.0-alpha.0
+  - @mastra/schema-compat@1.1.3-alpha.0
+
 ## 1.7.0
 
 ### Minor Changes

package/dist/docs/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: mastra-client-js
+description: Documentation for @mastra/client-js. Use when working with @mastra/client-js APIs, configuration, or implementation.
+metadata:
+  package: "@mastra/client-js"
+  version: "1.7.1"
+---
+
+## When to use
+
+Use this skill whenever you are working with @mastra/client-js to obtain the domain-specific knowledge.
+
+## How to use
+
+Read the individual reference documents for detailed explanations and code examples.
+
+### Docs
+
+- [MastraAuthAuth0 Class](references/docs-server-auth-auth0.md) - Documentation for the MastraAuthAuth0 class, which authenticates Mastra applications using Auth0 authentication.
+- [MastraAuthClerk Class](references/docs-server-auth-clerk.md) - Documentation for the MastraAuthClerk class, which authenticates Mastra applications using Clerk authentication.
+- [MastraAuthFirebase Class](references/docs-server-auth-firebase.md) - Documentation for the MastraAuthFirebase class, which authenticates Mastra applications using Firebase Authentication.
+- [MastraJwtAuth Class](references/docs-server-auth-jwt.md) - Documentation for the MastraJwtAuth class, which authenticates Mastra applications using JSON Web Tokens.
+- [MastraAuthSupabase Class](references/docs-server-auth-supabase.md) - Documentation for the MastraAuthSupabase class, which authenticates Mastra applications using Supabase Auth.
+- [MastraAuthWorkos Class](references/docs-server-auth-workos.md) - Documentation for the MastraAuthWorkos class, which authenticates Mastra applications using WorkOS authentication.
+- [Mastra Client SDK](references/docs-server-mastra-client.md) - Learn how to set up and use the Mastra Client SDK
+
+### Reference
+
+- [Reference: toAISdkStream()](references/reference-ai-sdk-to-ai-sdk-stream.md) - API reference for toAISdkStream(), a function to convert Mastra streams to AI SDK-compatible streams.
+- [Reference: toAISdkV4Messages()](references/reference-ai-sdk-to-ai-sdk-v4-messages.md) - API reference for toAISdkV4Messages(), a function to convert Mastra messages to AI SDK v4 UI messages.
+- [Reference: toAISdkV5Messages()](references/reference-ai-sdk-to-ai-sdk-v5-messages.md) - API reference for toAISdkV5Messages(), a function to convert Mastra messages to AI SDK v5 UI messages.
+- [Reference: Agents API](references/reference-client-js-agents.md) - Learn how to interact with Mastra AI agents, including generating responses, streaming interactions, and managing agent tools using the client-js SDK.
+- [Reference: Error Handling](references/reference-client-js-error-handling.md) - Learn about the built-in retry mechanism and error handling capabilities in the Mastra client-js SDK.
+- [Reference: Logs API](references/reference-client-js-logs.md) - Learn how to access and query system logs and debugging information in Mastra using the client-js SDK.
+- [Reference: Mastra Client SDK](references/reference-client-js-mastra-client.md) - Learn how to interact with Mastra using the client-js SDK.
+- [Reference: Memory API](references/reference-client-js-memory.md) - Learn how to manage conversation threads and message history in Mastra using the client-js SDK.
+- [Reference: Observability API](references/reference-client-js-observability.md) - Learn how to retrieve traces, monitor application performance, and score traces using the client-js SDK.
+- [Reference: Telemetry API](references/reference-client-js-telemetry.md) - Learn how to retrieve and analyze traces from your Mastra application for monitoring and debugging using the client-js SDK.
+- [Reference: Tools API](references/reference-client-js-tools.md) - Learn how to interact with and execute tools available in the Mastra platform using the client-js SDK.
+- [Reference: Vectors API](references/reference-client-js-vectors.md) - Learn how to work with vector embeddings for semantic search and similarity matching in Mastra using the client-js SDK.
+- [Reference: Workflows API](references/reference-client-js-workflows.md) - Learn how to interact with and execute automated workflows in Mastra using the client-js SDK.
+
+
+Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "1.7.1",
+  "package": "@mastra/client-js",
+  "exports": {},
+  "modules": {}
+}

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

@@ -0,0 +1,220 @@
+# MastraAuthAuth0 Class
+
+The `MastraAuthAuth0` class provides authentication for Mastra using Auth0. It verifies incoming requests using Auth0-issued JWT tokens and integrates with the Mastra server using the `auth` option.
+
+## Prerequisites
+
+This example uses Auth0 authentication. Make sure to:
+
+1. Create an Auth0 account at [auth0.com](https://auth0.com/)
+2. Set up an Application in your Auth0 Dashboard
+3. Configure an API in your Auth0 Dashboard with an identifier (audience)
+4. Configure your application's allowed callback URLs, web origins, and logout URLs
+
+```env
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_AUDIENCE=your-api-identifier
+```
+
+> **Note:** You can find your domain in the Auth0 Dashboard under Applications > Settings. The audience is the identifier of your API configured in Auth0 Dashboard > APIs.
+>
+> For detailed setup instructions, refer to the [Auth0 quickstarts](https://auth0.com/docs/quickstarts) for your specific platform.
+
+## Installation
+
+Before you can use the `MastraAuthAuth0` class you have to install the `@mastra/auth-auth0` package.
+
+```bash
+npm install @mastra/auth-auth0@latest
+```
+
+## Usage examples
+
+### Basic usage with environment variables
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthAuth0 } from '@mastra/auth-auth0'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthAuth0(),
+  },
+})
+```
+
+### Custom configuration
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthAuth0 } from '@mastra/auth-auth0'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthAuth0({
+      domain: process.env.AUTH0_DOMAIN,
+      audience: process.env.AUTH0_AUDIENCE,
+    }),
+  },
+})
+```
+
+## Configuration
+
+### User Authorization
+
+By default, `MastraAuthAuth0` allows all authenticated users who have valid Auth0 tokens for the specified audience. The token verification ensures that:
+
+1. The token is properly signed by Auth0
+2. The token is not expired
+3. The token audience matches your configured audience
+4. The token issuer matches your Auth0 domain
+
+To customize user authorization, provide a custom `authorizeUser` function:
+
+```typescript
+import { MastraAuthAuth0 } from '@mastra/auth-auth0'
+
+const auth0Provider = new MastraAuthAuth0({
+  authorizeUser: async user => {
+    // Custom authorization logic
+    return user.email?.endsWith('@yourcompany.com') || false
+  },
+})
+```
+
+> **Info:** Visit [MastraAuthAuth0](https://mastra.ai/reference/auth/auth0) for all available configuration options.
+
+## Client-side setup
+
+When using Auth0 auth, you'll need to set up the Auth0 React SDK, authenticate users, and retrieve their access tokens to pass to your Mastra requests.
+
+### Setting up Auth0 React SDK
+
+First, install and configure the Auth0 React SDK in your application:
+
+```bash
+npm install @auth0/auth0-react
+```
+
+```typescript
+import React from 'react'
+import { Auth0Provider } from '@auth0/auth0-react'
+
+const Auth0ProviderWithHistory = ({ children }) => {
+  return (
+    <Auth0Provider
+      domain={process.env.REACT_APP_AUTH0_DOMAIN}
+      clientId={process.env.REACT_APP_AUTH0_CLIENT_ID}
+      authorizationParams={{
+        redirect_uri: window.location.origin,
+        audience: process.env.REACT_APP_AUTH0_AUDIENCE,
+        scope: 'read:current_user update:current_user_metadata',
+      }}
+    >
+      {children}
+    </Auth0Provider>
+  )
+}
+
+export default Auth0ProviderWithHistory
+```
+
+### Retrieving access tokens
+
+Use the Auth0 React SDK to authenticate users and retrieve their access tokens:
+
+```typescript
+import { useAuth0 } from '@auth0/auth0-react'
+
+export const useAuth0Token = () => {
+  const { getAccessTokenSilently } = useAuth0()
+
+  const getAccessToken = async () => {
+    const token = await getAccessTokenSilently()
+    return token
+  }
+
+  return { getAccessToken }
+}
+```
+
+> **Note:** Refer to the [Auth0 React SDK documentation](https://auth0.com/docs/libraries/auth0-react) for more authentication methods and configuration options.
+
+## Configuring `MastraClient`
+
+When `auth` is enabled, all requests made with `MastraClient` must include a valid Auth0 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 Auth0 access token, you can send authenticated requests:
+
+**React**:
+
+```tsx
+import React, { useState } from 'react'
+import { useAuth0 } from '@auth0/auth0-react'
+import { MastraClient } from '@mastra/client-js'
+
+export const MastraApiTest = () => {
+  const { getAccessTokenSilently } = useAuth0()
+  const [result, setResult] = useState(null)
+
+  const callMastraApi = async () => {
+    const token = await getAccessTokenSilently()
+
+    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 New York")
+
+    setResult(response.text)
+  }
+
+  return (
+    <div>
+      <button onClick={callMastraApi}>Test Mastra API</button>
+
+      {result && (
+        <div className="result">
+          <h6>Result:</h6>
+          <pre>{result}</pre>
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+**cURL**:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-auth0-access-token>" \
+  -d '{
+    "messages": "Weather in London"
+  }'
+```

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

@@ -0,0 +1,132 @@
+# 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
+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@latest
+```
+
+## Usage example
+
+```typescript
+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,
+    }),
+  },
+})
+```
+
+> **Info:** 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/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
+import { useAuth } from '@clerk/nextjs'
+
+export const useClerkAuth = () => {
+  const { getToken } = useAuth()
+
+  const getAccessToken = async () => {
+    const token = await getToken()
+    return token
+  }
+
+  return { getAccessToken }
+}
+```
+
+> **Info:** 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
+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 Clerk access token, you can send authenticated requests:
+
+**React**:
+
+```tsx
+'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"
+  }'
+```