@mastra/core 1.2.0 → 1.2.1-alpha.0

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

@@ -0,0 +1,298 @@
+# 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

@@ -0,0 +1,249 @@
+# 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