@mastra/core 1.6.0 → 1.7.0

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

package/dist/docs/references/reference-server-register-api-route.md

@@ -1,249 +0,0 @@
-# registerApiRoute()
-
-The `registerApiRoute()` function creates custom HTTP routes that integrate with the Mastra server. Routes can include OpenAPI metadata to appear in the Swagger UI documentation.
-
-## Import
-
-```typescript
-import { registerApiRoute } from "@mastra/core/server";
-```
-
-## Parameters
-
-### path
-
-The URL path for the route. Supports path parameters using `:param` syntax.
-
-```typescript
-registerApiRoute("/items/:itemId", { ... })
-```
-
-**Note:** Paths cannot start with `/api/` as this prefix is reserved for Mastra server routes.
-
-### options
-
-**method:** (`'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'`): HTTP method for the route
-
-**handler?:** (`Handler`): Route handler function receiving Hono Context. Use either \`handler\` or \`createHandler\`, not both.
-
-**createHandler?:** (`(c: Context) => Promise<Handler>`): Async factory function to create the handler. Use either \`handler\` or \`createHandler\`, not both.
-
-**middleware?:** (`MiddlewareHandler | MiddlewareHandler[]`): Route-specific middleware functions
-
-**openapi?:** (`DescribeRouteOptions`): OpenAPI metadata for Swagger UI documentation
-
-## OpenAPI Options
-
-The `openapi` property accepts standard OpenAPI 3.1 operation fields from [hono-openapi](https://github.com/honojs/middleware/tree/main/packages/openapi). Routes without an `openapi` property are not included in Swagger UI.
-
-**summary?:** (`string`): Short summary of the operation
-
-**description?:** (`string`): Detailed description of the operation
-
-**tags?:** (`string[]`): Tags for grouping in Swagger UI. Defaults to \['custom'] if not specified.
-
-**deprecated?:** (`boolean`): Mark the operation as deprecated
-
-**parameters?:** (`ParameterObject[]`): Path, query, and header parameters
-
-**requestBody?:** (`RequestBodyObject`): Request body specification
-
-**responses?:** (`ResponsesObject`): Response specifications by status code
-
-**security?:** (`SecurityRequirementObject[]`): Security requirements for the operation
-
-## Return Value
-
-Returns an `ApiRoute` object to be passed to `server.apiRoutes` in the Mastra configuration.
-
-## Handler Context
-
-The handler receives a Hono `Context` object with access to:
-
-```typescript
-handler: async (c) => {
-  // Get the Mastra instance
-  const mastra = c.get("mastra");
-
-  // Get request context
-  const requestContext = c.get("requestContext");
-
-  // Access path parameters
-  const itemId = c.req.param("itemId");
-
-  // Access query parameters
-  const filter = c.req.query("filter");
-
-  // Access request body
-  const body = await c.req.json();
-
-  // Return JSON response
-  return c.json({ data: "value" });
-}
-```
-
-## Examples
-
-### Basic GET Route
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { registerApiRoute } from "@mastra/core/server";
-
-export const mastra = new Mastra({
-  server: {
-    apiRoutes: [
-      registerApiRoute("/health-check", {
-        method: "GET",
-        handler: async (c) => {
-          return c.json({ status: "ok" });
-        },
-      }),
-    ],
-  },
-});
-```
-
-### Route with Path Parameters
-
-```typescript
-registerApiRoute("/users/:userId/posts/:postId", {
-  method: "GET",
-  handler: async (c) => {
-    const userId = c.req.param("userId");
-    const postId = c.req.param("postId");
-
-    return c.json({ userId, postId });
-  },
-});
-```
-
-### POST Route with Body
-
-```typescript
-registerApiRoute("/items", {
-  method: "POST",
-  handler: async (c) => {
-    const body = await c.req.json();
-    const mastra = c.get("mastra");
-
-    // Process the request...
-
-    return c.json({ id: "new-id", ...body }, 201);
-  },
-});
-```
-
-### Route with Middleware
-
-```typescript
-registerApiRoute("/protected", {
-  method: "GET",
-  middleware: [
-    async (c, next) => {
-      const token = c.req.header("Authorization");
-      if (!token) {
-        return c.json({ error: "Unauthorized" }, 401);
-      }
-      await next();
-    },
-  ],
-  handler: async (c) => {
-    return c.json({ data: "protected content" });
-  },
-});
-```
-
-### Route with OpenAPI Documentation
-
-```typescript
-import { z } from "zod";
-
-const ItemSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  price: z.number(),
-});
-
-registerApiRoute("/items/:itemId", {
-  method: "GET",
-  openapi: {
-    summary: "Get item by ID",
-    description: "Retrieves a single item by its unique identifier",
-    tags: ["Items"],
-    parameters: [
-      {
-        name: "itemId",
-        in: "path",
-        required: true,
-        description: "The item ID",
-        schema: { type: "string" },
-      },
-    ],
-    responses: {
-      200: {
-        description: "Item found",
-        content: {
-          "application/json": {
-            schema: ItemSchema, // Zod schemas are converted to JSON Schema during OpenAPI generation
-          },
-        },
-      },
-      404: {
-        description: "Item not found",
-      },
-    },
-  },
-  handler: async (c) => {
-    const itemId = c.req.param("itemId");
-    return c.json({ id: itemId, name: "Example", price: 9.99 });
-  },
-});
-```
-
-### Using createHandler
-
-For routes that need async initialization:
-
-```typescript
-registerApiRoute("/dynamic", {
-  method: "GET",
-  createHandler: async (c) => {
-    // Perform async setup
-    const config = await loadConfig();
-
-    return async (c) => {
-      return c.json({ config });
-    };
-  },
-});
-```
-
-## Error Handling
-
-Throw errors with status codes using Hono's `HTTPException`:
-
-```typescript
-import { HTTPException } from "hono/http-exception";
-
-registerApiRoute("/items/:itemId", {
-  method: "GET",
-  handler: async (c) => {
-    const itemId = c.req.param("itemId");
-    const item = await findItem(itemId);
-
-    if (!item) {
-      throw new HTTPException(404, { message: "Item not found" });
-    }
-
-    return c.json(item);
-  },
-});
-```
-
-## Related
-
-- [Custom API Routes Guide](https://mastra.ai/docs/server/custom-api-routes) - Usage guide with examples
-- [Server Middleware](https://mastra.ai/docs/server/middleware) - Global middleware configuration
-- [createRoute()](https://mastra.ai/reference/server/create-route) - Type-safe route creation for server adapters
-- [Server Routes](https://mastra.ai/reference/server/routes) - Built-in Mastra server routes