@redplanethq/sdk 0.1.17 → 1.2.1

package/LICENSE.md

@@ -0,0 +1,30 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,228 +1,204 @@
-# Core SDK
+# @mastra/ai-sdk
 
-The Core SDK provides tools and utilities for building integrations with the Core platform.
+The recommended way of using Mastra and AI SDK together is by installing the `@mastra/ai-sdk` package. `@mastra/ai-sdk` provides custom API routes and utilities for streaming Mastra agents in AI SDK-compatible formats. Including chat, workflow, and network route handlers, along with utilities and exported types for UI integrations.
 
-## Integration System
-
-The Core integration system uses a CLI-based approach where each integration is a command-line tool that responds to specific events. This makes integrations portable, testable, and easy to debug.
-
-### Integration Event Types
-
-Each integration CLI handles 5 core event types:
-
-#### 1. `spec`
-
-Returns the integration's metadata and configuration.
-
-**Usage:**
+## Installation
 
 ```bash
-my-integration spec
+npm install @mastra/ai-sdk
 ```
 
-**Returns:** Integration specification including name, description, auth config, etc.
+## Usage
 
-#### 2. `setup`
+If you want to use dynamic agents you can use a path with `:agentId`.
 
-Processes authentication data and returns tokens/credentials to be saved.
-
-**Usage:**
-
-```bash
-my-integration setup --event-body '{"code":"oauth_code","state":"state"}' --integration-definition '{}'
+```typescript
+import { chatRoute } from '@mastra/ai-sdk';
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      chatRoute({
+        path: '/chat/:agentId',
+      }),
+    ],
+  },
+});
 ```
 
-**Returns:** Configuration data (tokens, credentials) to be stored for the account.
-
-#### 3. `identify`
+Or you can create a fixed route (i.e. `/chat`):
 
-Extracts accountId from webhook data to route webhooks to the correct account.
-
-**Usage:**
-
-```bash
-my-integration identify --webhook-data '{"team_id":"T123","event":{}}'
+```typescript
+import { chatRoute } from '@mastra/ai-sdk';
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      chatRoute({
+        path: '/chat',
+        agent: 'weatherAgent',
+      }),
+    ],
+  },
+});
 ```
 
-**Returns:** Account identifier for webhook routing.
-
-#### 4. `process`
-
-Handles webhook events and returns activity data.
+After defining a dynamic route with `:agentId` you can use the `useChat()` hook like so:
 
-**Usage:**
+```typescript
+type MyMessage = {};
 
-```bash
-my-integration process --event-data '{"type":"reaction_added","reaction":"=M"}' --config '{"access_token":"token"}'
+const { error, status, sendMessage, messages, regenerate, stop } = useChat<MyMessage>({
+  transport: new DefaultChatTransport({
+    api: 'http://localhost:4111/chat/weatherAgent',
+  }),
+});
 ```
 
-**Returns:** Activity messages representing user actions.
-
-#### 5. `sync`
+`chatRoute()` forwards the incoming request `AbortSignal` to `agent.stream()`. If the client disconnects, Mastra aborts the in-flight generation. If you need generation to continue and persist server-side after disconnect, build a custom route around `agent.stream()`, avoid passing the request signal, and call `consumeStream()` on the returned `MastraModelOutput`.
 
-Performs scheduled data synchronization for integrations that don't support webhooks.
+### Workflow route
 
-**Usage:**
+Stream a workflow in AI SDK-compatible format.
 
-```bash
-my-integration sync --config '{"access_token":"token","last_sync":"2023-01-01T00:00:00Z"}'
+```typescript
+import { workflowRoute } from '@mastra/ai-sdk';
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      workflowRoute({
+        path: '/workflow',
+        agent: 'weatherAgent',
+      }),
+    ],
+  },
+});
 ```
 
-**Returns:** Activity messages and updated state for next sync.
+### Network route
 
-### Message Types
+Stream agent networks (routing + nested agent/workflow/tool executions) in AI SDK-compatible format.
 
-All integration responses are wrapped in a `Message` object with a `type` field:
-
-- **`spec`** - Integration metadata and configuration
-- **`activity`** - User actions/events from the integration
-- **`state`** - Sync state for polling integrations
-- **`identifier`** - Account identification for webhook routing
-
-### Building an Integration
+```typescript
+import { networkRoute } from '@mastra/ai-sdk';
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      networkRoute({
+        path: '/network',
+        agent: 'weatherAgent',
+      }),
+    ],
+  },
+});
+```
 
-1. **Install the SDK:**
+## Framework-agnostic handlers
 
-```bash
-npm install @Core/core-sdk
-```
+For use outside the Mastra server (e.g., Next.js App Router, Express), you can use the standalone handler functions directly. These handlers return a compatibility `ReadableStream` that can be passed to AI SDK response helpers like `createUIMessageStreamResponse` and `pipeUIMessageStreamToResponse`:
 
-2. **Create your integration class:**
+### handleChatStream
 
 ```typescript
-import { IntegrationCLI } from '@Core/core-sdk';
-
-class MyIntegration extends IntegrationCLI {
-  constructor() {
-    super('my-integration', '1.0.0');
-  }
-
-  protected async handleEvent(
-    eventPayload: IntegrationEventPayload,
-  ): Promise<any> {
-    switch (eventPayload.event) {
-      case 'SETUP':
-        return this.handleSetup(eventPayload);
-      case 'PROCESS':
-        return this.handleProcess(eventPayload);
-      case 'IDENTIFY':
-        return this.handleIdentify(eventPayload);
-      case 'SYNC':
-        return this.handleSync(eventPayload);
-      default:
-        throw new Error(`Unknown event type: ${eventPayload.event}`);
-    }
-  }
-
-  protected async getSpec(): Promise<Spec> {
-    return {
-      name: 'My Integration',
-      key: 'my-integration',
-      description: 'Integration with My Service',
-      icon: 'https://example.com/icon.png',
-      auth: {
-        OAuth2: {
-          token_url: 'https://api.example.com/oauth/token',
-          authorization_url: 'https://api.example.com/oauth/authorize',
-          scopes: ['read', 'write'],
-        },
-      },
-    };
-  }
-
-  private async handleSetup(
-    eventPayload: IntegrationEventPayload,
-  ): Promise<any> {
-    // Process OAuth response and return tokens to save
-    const { code } = eventPayload.eventBody;
-    // Exchange code for tokens...
-    return {
-      access_token: 'token',
-      refresh_token: 'refresh_token',
-      expires_at: Date.now() + 3600000,
-    };
-  }
-
-  private async handleProcess(
-    eventPayload: IntegrationEventPayload,
-  ): Promise<any> {
-    // Handle webhook events
-    const { eventData } = eventPayload.eventBody;
-    // Process event and return activity...
-    return {
-      type: 'message',
-      user: 'user123',
-      content: 'Hello world',
-      timestamp: new Date(),
-    };
-  }
-
-  private async handleIdentify(
-    eventPayload: IntegrationEventPayload,
-  ): Promise<any> {
-    // Extract account ID from webhook
-    const { team_id } = eventPayload.eventBody;
-    return { id: team_id };
-  }
-
-  private async handleSync(
-    eventPayload: IntegrationEventPayload,
-  ): Promise<any> {
-    // Perform scheduled sync
-    const { config } = eventPayload;
-    // Fetch data since last sync...
-    return {
-      activities: [
-        /* activity data */
-      ],
-      state: { last_sync: new Date().toISOString() },
-    };
-  }
+import { handleChatStream } from '@mastra/ai-sdk';
+import { createUIMessageStreamResponse } from 'ai';
+import { mastra } from '@/src/mastra';
+
+export async function POST(req: Request) {
+  const params = await req.json();
+  const stream = await handleChatStream({
+    mastra,
+    agentId: 'weatherAgent',
+    params,
+  });
+  return createUIMessageStreamResponse({ stream });
 }
-
-// CLI entry point
-const integration = new MyIntegration();
-integration.parse();
 ```
 
-3. **Build and package your integration:**
+### handleWorkflowStream
 
-```bash
-npm run build
-npm pack
+```typescript
+import { handleWorkflowStream } from '@mastra/ai-sdk';
+import { createUIMessageStreamResponse } from 'ai';
+import { mastra } from '@/src/mastra';
+
+export async function POST(req: Request) {
+  const params = await req.json();
+  const stream = await handleWorkflowStream({
+    mastra,
+    workflowId: 'myWorkflow',
+    params,
+  });
+  return createUIMessageStreamResponse({ stream });
+}
 ```
 
-### Integration Development
+### handleNetworkStream
 
-The `IntegrationCLI` base class provides:
+Pass AI SDK `UIMessage[]` from your installed `ai` version so TypeScript can infer the correct stream overload.
 
-- **Automatic CLI setup** with all required commands
-- **JSON input/output handling** for all event types
-- **Error handling** with proper exit codes
-- **Consistent message formatting** for all responses
+Handlers keep the existing v5/default behavior. If your app is typed against `ai@6`, pass `version: 'v6'`.
 
-### Testing
+```typescript
+import { handleNetworkStream } from '@mastra/ai-sdk';
+import { createUIMessageStreamResponse, type UIMessage } from 'ai';
+import { mastra } from '@/src/mastra';
+
+export async function POST(req: Request) {
+  const params = (await req.json()) as { messages: UIMessage[] };
+  const stream = await handleNetworkStream({
+    mastra,
+    agentId: 'routingAgent',
+    version: 'v6',
+    params,
+  });
+  return createUIMessageStreamResponse({ stream });
+}
+```
 
-Test your integration by running commands directly:
+## Manual transformation
 
-```bash
-# Test spec
-node dist/index.js spec
+If you have a raw Mastra `stream`, you can manually transform it to AI SDK UI message parts:
 
-# Test setup
-node dist/index.js setup --event-body '{"code":"test"}' --integration-definition '{}'
+Use `toAISdkStream` for both versions. If your app is typed against `ai@6`, pass `version: 'v6'`.
 
-# Test webhook processing
-node dist/index.js process --event-data '{"type":"test"}' --config '{"token":"test"}'
+```typescript
+import { toAISdkStream } from '@mastra/ai-sdk';
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const agent = mastra.getAgent('weatherAgent');
+  const stream = await agent.stream(messages);
+
+  // deduplicate messages https://ai-sdk.dev/docs/troubleshooting/repeated-assistant-messages
+  const uiMessageStream = createUIMessageStream({
+    originalMessages: messages,
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, { from: 'agent' })) {
+        writer.write(part);
+      }
+    },
+  });
+
+  return createUIMessageStreamResponse({ stream: uiMessageStream });
+}
 ```
 
-### Best Practices
-
-1. **Always validate input data** before processing
-2. **Handle errors gracefully** with meaningful error messages
-3. **Use consistent data structures** for activities
-4. **Include proper timestamps** in all activity data
-5. **Store minimal state** for sync operations
-6. **Test all event types** thoroughly
+For AI SDK v6, select the v6 stream contract explicitly:
 
-For more examples, see the integrations in the `integrations/` directory.
+```typescript
+const uiMessageStream = createUIMessageStream({
+  originalMessages: messages,
+  execute: async ({ writer }) => {
+    for await (const part of toAISdkStream(stream, {
+      from: 'agent',
+      version: 'v6',
+    })) {
+      writer.write(part);
+    }
+  },
+});
+```