@mastra/server 1.6.0 → 1.7.0

package/dist/docs/references/reference-server-create-route.md

@@ -1,260 +0,0 @@
-# createRoute()
-
-The `createRoute()` function creates type-safe routes with Zod validation. When an `openapiPath` is configured on the server adapter, it generates OpenAPI schema entries from the supplied Zod schemas.
-
-## Import
-
-```typescript
-import { createRoute } from '@mastra/server/server-adapter';
-```
-
-## Signature
-
-```typescript
-function createRoute<TPath, TQuery, TBody, TResponse, TResponseType>(
-  config: RouteConfig<TPath, TQuery, TBody, TResponse, TResponseType>
-): ServerRoute
-```
-
-## Parameters
-
-**method:** (`'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'`): HTTP method
-
-**path:** (`string`): Route path with optional params (e.g., \`/api/items/:id\`)
-
-**responseType:** (`'json' | 'stream'`): Response format. Internal routes may use additional types (\`datastream-response\`, \`mcp-http\`, \`mcp-sse\`).
-
-**handler:** (`ServerRouteHandler`): Route handler function
-
-**pathParamSchema?:** (`ZodSchema`): Validates URL path parameters
-
-**queryParamSchema?:** (`ZodSchema`): Validates query string parameters
-
-**bodySchema?:** (`ZodSchema`): Validates request body
-
-**responseSchema?:** (`ZodSchema`): Documents response shape for OpenAPI
-
-**streamFormat?:** (`'sse' | 'stream'`): Stream format (when responseType is 'stream')
-
-**maxBodySize?:** (`number`): Override default body size limit in bytes
-
-**summary?:** (`string`): OpenAPI summary
-
-**description?:** (`string`): OpenAPI description
-
-**tags?:** (`string[]`): OpenAPI tags
-
-**deprecated?:** (`boolean`): Mark route as deprecated
-
-## Handler parameters
-
-The handler receives validated parameters plus runtime context:
-
-```typescript
-handler: async (params) => {
-  // From schemas (typed from Zod)
-  params.id;              // From pathParamSchema
-  params.filter;          // From queryParamSchema
-  params.name;            // From bodySchema
-
-  // Runtime context (always available)
-  params.mastra;          // Mastra instance
-  params.requestContext;  // Request-scoped context
-  params.tools;           // Available tools
-  params.abortSignal;     // Request cancellation signal
-  params.taskStore;       // A2A task storage
-}
-```
-
-## Return value
-
-Returns a `ServerRoute` object that can be registered with an adapter.
-
-## Examples
-
-### GET route with path params
-
-```typescript
-import { createRoute } from '@mastra/server/server-adapter';
-import { z } from 'zod';
-
-const getAgent = createRoute({
-  method: 'GET',
-  path: '/api/agents/:agentId',
-  responseType: 'json',
-  pathParamSchema: z.object({
-    agentId: z.string(),
-  }),
-  responseSchema: z.object({
-    name: z.string(),
-    description: z.string().optional(),
-  }),
-  summary: 'Get agent by ID',
-  tags: ['Agents'],
-  handler: async ({ agentId, mastra }) => {
-    return mastra.getAgent(agentId);
-  },
-});
-```
-
-### POST route with body
-
-```typescript
-const createItem = createRoute({
-  method: 'POST',
-  path: '/api/items',
-  responseType: 'json',
-  bodySchema: z.object({
-    name: z.string(),
-    value: z.number(),
-  }),
-  responseSchema: z.object({
-    id: z.string(),
-    name: z.string(),
-    value: z.number(),
-  }),
-  handler: async ({ name, value, mastra }) => {
-    // name and value are typed from bodySchema
-    return { id: 'new-id', name, value };
-  },
-});
-```
-
-### Query params with coercion
-
-```typescript
-const listItems = createRoute({
-  method: 'GET',
-  path: '/api/items',
-  responseType: 'json',
-  queryParamSchema: z.object({
-    page: z.coerce.number().default(0),
-    limit: z.coerce.number().default(50),
-    enabled: z.coerce.boolean().optional(),
-  }),
-  handler: async ({ page, limit, enabled, mastra }) => {
-    // page, limit, enabled are typed and coerced
-    return { items: [], page, limit };
-  },
-});
-```
-
-### Streaming route
-
-```typescript
-const streamAgent = createRoute({
-  method: 'POST',
-  path: '/api/agents/:agentId/stream',
-  responseType: 'stream',
-  streamFormat: 'sse',
-  pathParamSchema: z.object({
-    agentId: z.string(),
-  }),
-  bodySchema: z.object({
-    messages: z.array(z.any()),
-  }),
-  handler: async ({ agentId, messages, mastra, abortSignal }) => {
-    const agent = mastra.getAgent(agentId);
-    return agent.stream(messages, { abortSignal });
-  },
-});
-```
-
-### Custom body size limit
-
-```typescript
-const uploadRoute = createRoute({
-  method: 'POST',
-  path: '/api/upload',
-  responseType: 'json',
-  maxBodySize: 50 * 1024 * 1024, // 50MB
-  bodySchema: z.object({
-    file: z.string(),
-  }),
-  handler: async ({ file }) => {
-    return { uploaded: true };
-  },
-});
-```
-
-## Schema patterns
-
-### Passthrough for extensibility
-
-```typescript
-const bodySchema = z.object({
-  required: z.string(),
-}).passthrough(); // Allow unknown fields
-```
-
-### Date coercion
-
-```typescript
-const querySchema = z.object({
-  fromDate: z.coerce.date().optional(),
-  toDate: z.coerce.date().optional(),
-});
-```
-
-### Union types
-
-```typescript
-const bodySchema = z.object({
-  messages: z.union([
-    z.array(z.any()),
-    z.string(),
-  ]),
-});
-```
-
-## Error handling
-
-Throw an error with a `status` property to return specific HTTP status codes from handlers. If using Hono, you can use `HTTPException` from `hono/http-exception`:
-
-```typescript
-import { createRoute } from '@mastra/server/server-adapter';
-import { HTTPException } from 'hono/http-exception';
-
-const getAgent = createRoute({
-  method: 'GET',
-  path: '/api/agents/:agentId',
-  responseType: 'json',
-  pathParamSchema: z.object({ agentId: z.string() }),
-  handler: async ({ agentId, mastra }) => {
-    const agent = mastra.getAgent(agentId);
-    if (!agent) {
-      throw new HTTPException(404, { message: `Agent '${agentId}' not found` });
-    }
-    return agent;
-  },
-});
-```
-
-For Express or framework-agnostic code, throw an error with a `status` property:
-
-```typescript
-class HttpError extends Error {
-  constructor(public status: number, message: string) {
-    super(message);
-  }
-}
-
-// In handler:
-throw new HttpError(404, `Agent '${agentId}' not found`);
-```
-
-Common status codes:
-
-| Code | Meaning               |
-| ---- | --------------------- |
-| 400  | Bad Request           |
-| 401  | Unauthorized          |
-| 403  | Forbidden             |
-| 404  | Not Found             |
-| 500  | Internal Server Error |
-
-## Related
-
-- [Server Routes](https://mastra.ai/reference/server/routes) - Default Mastra routes
-- [MastraServer](https://mastra.ai/reference/server/mastra-server) - Server adapter class
-- [Server Adapters](https://mastra.ai/docs/server/server-adapters) - Using adapters

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

@@ -1,298 +0,0 @@
-# MastraServer
-
-The `MastraServer` abstract class is the base for all server adapters. Extend this class to create adapters for frameworks other than Hono or Express.
-
-## Import
-
-```typescript
-import { MastraServer } from '@mastra/server/server-adapter';
-```
-
-## Type parameters
-
-```typescript
-MastraServer<TApp, TRequest, TResponse>
-```
-
-| Parameter   | Description                                      |
-| ----------- | ------------------------------------------------ |
-| `TApp`      | Framework app type (e.g., `Hono`, `Application`) |
-| `TRequest`  | Framework request type                           |
-| `TResponse` | Framework response/context type                  |
-
-## Constructor
-
-```typescript
-constructor(options: MastraServerOptions<TApp>)
-```
-
-### Options
-
-**app:** (`TApp`): Framework app instance
-
-**mastra:** (`Mastra`): Mastra instance
-
-**prefix?:** (`string`): Route path prefix (e.g., \`/api/v2\`) (Default: `''`)
-
-**openapiPath?:** (`string`): Path to serve OpenAPI spec (Default: `''`)
-
-**bodyLimitOptions?:** (`BodyLimitOptions`): Request body size limits
-
-**streamOptions?:** (`StreamOptions`): Stream redaction config (Default: `{ redact: true }`)
-
-**customRouteAuthConfig?:** (`Map<string, boolean>`): Per-route auth overrides
-
-**tools?:** (`Record<string, Tool>`): Available tools for the server
-
-**taskStore?:** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
-
-**mcpOptions?:** (`MCPOptions`): MCP transport options for serverless environments
-
-## Abstract methods
-
-These methods must be implemented by adapters:
-
-### registerContextMiddleware()
-
-Attach Mastra context to every request.
-
-```typescript
-abstract registerContextMiddleware(): void
-```
-
-**Context to attach:**
-
-- `mastra` - Mastra instance
-- `requestContext` - Request-scoped context
-- `tools` - Available tools
-- `abortSignal` - Request cancellation signal
-
-### registerAuthMiddleware()
-
-Register authentication and authorization middleware.
-
-```typescript
-abstract registerAuthMiddleware(): void
-```
-
-### registerRoute()
-
-Register a single route with the framework.
-
-```typescript
-abstract registerRoute(
-  app: TApp,
-  route: ServerRoute,
-  options: { prefix?: string }
-): Promise<void>
-```
-
-### getParams()
-
-Extract parameters from the request.
-
-```typescript
-abstract getParams(
-  route: ServerRoute,
-  request: TRequest
-): Promise<{
-  urlParams: Record<string, string>;
-  queryParams: Record<string, string>;
-  body: unknown;
-}>
-```
-
-### sendResponse()
-
-Send response based on route type.
-
-```typescript
-abstract sendResponse(
-  route: ServerRoute,
-  response: TResponse,
-  result: unknown
-): Promise<unknown>
-```
-
-### stream()
-
-Handle streaming responses.
-
-```typescript
-abstract stream(
-  route: ServerRoute,
-  response: TResponse,
-  result: unknown
-): Promise<unknown>
-```
-
-## Instance methods
-
-### init()
-
-Initialize the server by registering all middleware and routes.
-
-```typescript
-async init(): Promise<void>
-```
-
-Calls in order:
-
-1. `registerContextMiddleware()`
-2. `registerAuthMiddleware()`
-3. `registerRoutes()`
-
-### registerRoutes()
-
-Register all Mastra routes.
-
-```typescript
-async registerRoutes(): Promise<void>
-```
-
-### getApp()
-
-Get the framework app instance.
-
-```typescript
-getApp<T = TApp>(): T
-```
-
-### parsePathParams()
-
-Validate path parameters with the route's Zod schema.
-
-```typescript
-async parsePathParams(
-  route: ServerRoute,
-  params: Record<string, string>
-): Promise<Record<string, unknown>>
-```
-
-### parseQueryParams()
-
-Validate query parameters with the route's Zod schema.
-
-```typescript
-async parseQueryParams(
-  route: ServerRoute,
-  params: Record<string, string>
-): Promise<Record<string, unknown>>
-```
-
-### parseBody()
-
-Validate request body with the route's Zod schema.
-
-```typescript
-async parseBody(
-  route: ServerRoute,
-  body: unknown
-): Promise<unknown>
-```
-
-### registerOpenAPIRoute()
-
-Register an endpoint that serves the OpenAPI specification.
-
-```typescript
-async registerOpenAPIRoute(
-  app: TApp,
-  config: OpenAPIConfig,
-  options: { prefix?: string }
-): Promise<void>
-```
-
-## Protected methods
-
-### mergeRequestContext()
-
-Merge request context from multiple sources (query params and body).
-
-```typescript
-protected mergeRequestContext(options: {
-  paramsRequestContext?: Record<string, any>;
-  bodyRequestContext?: Record<string, any>;
-}): RequestContext
-```
-
-## Types
-
-### BodyLimitOptions
-
-```typescript
-interface BodyLimitOptions {
-  maxSize: number;
-  onError: (error: unknown) => unknown;
-}
-```
-
-### StreamOptions
-
-```typescript
-interface StreamOptions {
-  redact?: boolean;
-}
-```
-
-### MCPOptions
-
-```typescript
-interface MCPOptions {
-  serverless?: boolean;
-  sessionIdGenerator?: () => string;
-}
-```
-
-| Property             | Description                                                                                                                                 |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `serverless`         | When `true`, runs MCP in stateless mode without session management. Use for serverless environments like Cloudflare Workers or Vercel Edge. |
-| `sessionIdGenerator` | Custom function to generate session IDs.                                                                                                    |
-
-## Example
-
-```typescript
-import { MastraServer, ServerRoute } from '@mastra/server/server-adapter';
-import type { Mastra } from '@mastra/core';
-
-export class MyServer extends MastraServer<MyApp, MyRequest, MyResponse> {
-  registerContextMiddleware(): void {
-    this.app.use('*', (req, res, next) => {
-      res.locals.mastra = this.mastra;
-      next();
-    });
-  }
-
-  registerAuthMiddleware(): void {
-    const auth = this.mastra.getServer()?.auth;
-    if (!auth) return;
-    // Implement auth
-  }
-
-  async registerRoute(app, route, { prefix }) {
-    // Implement route registration
-  }
-
-  async getParams(route, request) {
-    return {
-      urlParams: request.params,
-      queryParams: request.query,
-      body: request.body,
-    };
-  }
-
-  async sendResponse(route, response, result) {
-    return response.json(result);
-  }
-
-  async stream(route, response, result) {
-    // Implement streaming
-  }
-}
-```
-
-## Related
-
-- [Server Adapters](https://mastra.ai/docs/server/server-adapters) - Using adapters
-- [Custom Adapters](https://mastra.ai/docs/server/custom-adapters) - Creating custom adapters
-- [createRoute()](https://mastra.ai/reference/server/create-route) - Creating custom routes