@mastra/nestjs 0.0.0

package/README.md

@@ -0,0 +1,324 @@
+# @mastra/nestjs
+
+NestJS server adapter for [Mastra](https://mastra.ai). Use it to expose agents, workflows, tools, MCP, and streaming endpoints through NestJS with native guards, interceptors, and DI.
+
+This package supports NestJS running on the Express adapter only. If your app uses Fastify, `MastraModule` now fails fast during bootstrap with a clear error instead of partially initializing.
+
+## Features
+
+- **NestJS-native integration** via modules, DI, guards, interceptors, and filters
+- **Rate limiting** enabled by default (opt-out)
+- **Graceful shutdown** with in-flight request tracking and optional SSE notifications
+- **Streaming** for AI responses with optional redaction and SSE heartbeats
+- **MCP transport** (HTTP + SSE) exposed under the API prefix
+
+## Installation
+
+```bash
+npm install @mastra/nestjs @mastra/core
+# or
+pnpm add @mastra/nestjs @mastra/core
+# or
+yarn add @mastra/nestjs @mastra/core
+```
+
+## Quick Start
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { MastraModule } from '@mastra/nestjs';
+import { Mastra } from '@mastra/core/mastra';
+import { z } from 'zod';
+import { createTool } from '@mastra/core/tools';
+
+/** Simple tool used by the demo agent. */
+const pingTool = createTool({
+  id: 'ping',
+  description: 'Returns a pong response',
+  inputSchema: z.object({ message: z.string() }),
+  execute: async ({ message }) => ({ ok: true, message }),
+});
+
+/** Minimal Mastra instance for NestJS integration. */
+const mastra = new Mastra({
+  tools: { ping: pingTool },
+  agents: {
+    greeter: {
+      name: 'greeter',
+      description: 'Greets the user and can call tools.',
+      model: 'openai/gpt-4o-mini',
+      tools: ['ping'],
+    },
+  },
+});
+
+@Module({
+  imports: [MastraModule.register({ mastra })],
+})
+export class AppModule {}
+```
+
+```typescript
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+
+bootstrap();
+```
+
+With the default prefix (`/api`), Mastra routes mount under `http://localhost:3000/api`.
+
+## Async Module Registration
+
+Use async registration when the Mastra config depends on runtime services (e.g., `ConfigService`).
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { MastraModule } from '@mastra/nestjs';
+import { Mastra } from '@mastra/core/mastra';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot(),
+    MastraModule.registerAsync({
+      imports: [ConfigModule],
+      useFactory: (config: ConfigService) => ({
+        mastra: new Mastra({
+          agents: {
+            greeter: {
+              name: 'greeter',
+              description: 'Greets users with a short response.',
+              model: config.get('MASTRA_MODEL', 'openai/gpt-4o-mini'),
+            },
+          },
+        }),
+        prefix: config.get('MASTRA_PREFIX', '/api'),
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Injecting Mastra in Services
+
+Use `MASTRA` for direct access or `MastraService` for helper methods.
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common';
+import { MASTRA, MastraService } from '@mastra/nestjs';
+import type { Mastra } from '@mastra/core/mastra';
+
+@Injectable()
+export class AgentService {
+  constructor(@Inject(MASTRA) private readonly mastra: Mastra) {}
+
+  async greet() {
+    const agent = this.mastra.getAgent('greeter');
+    return agent.generate({
+      messages: [{ role: 'user', content: 'Hello from NestJS' }],
+    });
+  }
+}
+
+@Injectable()
+export class WorkflowService {
+  constructor(private readonly mastraService: MastraService) {}
+
+  async runWorkflow(workflowId: string, inputData: Record<string, unknown>) {
+    const workflow = this.mastraService.getWorkflow(workflowId);
+    return workflow.start({ inputData });
+  }
+}
+```
+
+## Request Context (GET + POST)
+
+Pass request context via query string or JSON body. The adapter accepts JSON or base64-encoded JSON.
+
+```bash
+curl "http://localhost:3000/api/agents/greeter/generate?requestContext=%7B%22userId%22%3A%22123%22%7D"
+```
+
+```bash
+curl -X POST "http://localhost:3000/api/agents/greeter/generate" \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"hi"}],"requestContext":{"userId":"123"}}'
+```
+
+## Rate Limiting
+
+Rate limiting is on by default. Disable it or customize limits:
+
+```typescript
+MastraModule.register({
+  mastra,
+  rateLimitOptions: {
+    enabled: true,
+    defaultLimit: 200,
+    generateLimit: 20,
+    windowMs: 60_000,
+  },
+});
+```
+
+## Mastra Auth Compatibility
+
+Mastra's built-in token auth is disabled by default because most NestJS apps already have their own auth layer. When enabled, bearer tokens from the `Authorization` header are the default credential source.
+
+Query-string `?apiKey=` auth is available only as an explicit backward-compatibility option:
+
+```typescript
+MastraModule.register({
+  mastra,
+  auth: {
+    enabled: true,
+    allowQueryApiKey: true,
+  },
+});
+```
+
+## Streaming Options
+
+```typescript
+MastraModule.register({
+  mastra,
+  streamOptions: {
+    redact: true,
+    heartbeatMs: 20_000,
+  },
+});
+```
+
+## MCP Transport (HTTP + SSE)
+
+MCP endpoints are exposed under the API prefix:
+
+- `POST /api/mcp/:serverId/mcp`
+- `GET /api/mcp/:serverId/sse`
+- `POST /api/mcp/:serverId/messages`
+
+## Health Endpoints
+
+These are always at the root (not under the prefix):
+
+- `GET /health`
+- `GET /ready`
+- `GET /info`
+
+## Decorators
+
+Skip auth or rate limiting on specific controller routes:
+
+```typescript
+import { Controller, Get, Post } from '@nestjs/common';
+import { Public, SkipThrottle, MastraThrottle } from '@mastra/nestjs';
+
+@Controller('custom')
+export class CustomController {
+  @Get('public')
+  @Public()
+  publicRoute() {}
+
+  @Get('unlimited')
+  @SkipThrottle()
+  unlimitedRoute() {}
+
+  @Post('custom-limit')
+  @MastraThrottle({ limit: 5, windowMs: 60_000 })
+  customLimitRoute() {}
+}
+```
+
+## Configuration Options
+
+| Option                              | Type                                                | Default              | Description                                 |
+| ----------------------------------- | --------------------------------------------------- | -------------------- | ------------------------------------------- |
+| `mastra`                            | `Mastra`                                            | required             | The Mastra instance                         |
+| `prefix`                            | `string`                                            | `/api`               | Route prefix                                |
+| `rateLimitOptions`                  | `object`                                            | enabled              | Rate limiting configuration                 |
+| `rateLimitOptions.enabled`          | `boolean`                                           | `true`               | Enable/disable rate limiting                |
+| `rateLimitOptions.defaultLimit`     | `number`                                            | `100`                | Requests per window                         |
+| `rateLimitOptions.generateLimit`    | `number`                                            | `10`                 | Stricter limit for `/generate`              |
+| `rateLimitOptions.windowMs`         | `number`                                            | `60000`              | Window size in ms                           |
+| `shutdownOptions`                   | `object`                                            | -                    | Graceful shutdown configuration             |
+| `shutdownOptions.timeoutMs`         | `number`                                            | `30000`              | Max wait time for in-flight requests        |
+| `shutdownOptions.notifyClients`     | `boolean`                                           | `true`               | Send shutdown event to SSE clients          |
+| `bodyLimitOptions`                  | `object`                                            | -                    | Request body size limits                    |
+| `bodyLimitOptions.maxSize`          | `number`                                            | `10MB`               | Max JSON body size                          |
+| `bodyLimitOptions.maxFileSize`      | `number`                                            | -                    | Max multipart file size (no limit if unset) |
+| `bodyLimitOptions.allowedMimeTypes` | `string[]`                                          | -                    | Allowed upload MIME types                   |
+| `streamOptions`                     | `{ redact?: boolean; heartbeatMs?: number }`        | -                    | Streaming config                            |
+| `tracingOptions`                    | `{ enabled?: boolean; serviceName?: string }`       | -                    | OpenTelemetry tracing                       |
+| `customRouteAuthConfig`             | `Map<string, boolean>`                              | -                    | Per-route auth overrides                    |
+| `mcpOptions`                        | `object`                                            | -                    | MCP transport options                       |
+| `mcpOptions.serverless`             | `boolean`                                           | `false`              | Stateless MCP HTTP mode                     |
+| `mcpOptions.sessionIdGenerator`     | `() => string`                                      | -                    | Custom MCP session IDs                      |
+| `auth`                              | `{ enabled?: boolean; allowQueryApiKey?: boolean }` | `{ enabled: false }` | Enable Mastra's built-in token auth         |
+
+## Requirements
+
+- Node.js >= 22.13.0
+- NestJS with Express adapter (`@nestjs/platform-express`)
+- Express 4.x or 5.x
+
+**Note:** This adapter supports NestJS with Express only. Fastify is not supported in v1, and `MastraModule` throws during bootstrap if another Nest HTTP adapter is in use.
+
+## API Reference
+
+### `MastraModule.register(options)`
+
+Register Mastra with NestJS DI.
+
+### `MastraModule.registerAsync(options)`
+
+Async registration supporting `useFactory`, `useClass`, and `useExisting`.
+
+### `MastraService`
+
+```typescript
+class MastraService {
+  getMastra(): Mastra;
+  getOptions(): MastraModuleOptions;
+  getAgent(agentId: string): Agent;
+  getWorkflow(workflowId: string): Workflow;
+  isShuttingDown: boolean;
+}
+```
+
+### `MASTRA`
+
+Injection token for the Mastra instance.
+
+## Exported Components
+
+```typescript
+import {
+  MastraAuthGuard,
+  MastraThrottleGuard,
+  StreamingInterceptor,
+  RequestTrackingInterceptor,
+  MastraExceptionFilter,
+  RouteHandlerService,
+  RequestContextService,
+  ShutdownService,
+} from '@mastra/nestjs';
+```
+
+## Related Packages
+
+- [@mastra/core](https://www.npmjs.com/package/@mastra/core)
+- [@mastra/express](https://www.npmjs.com/package/@mastra/express)
+- [@mastra/hono](https://www.npmjs.com/package/@mastra/hono)
+
+## License
+
+Apache-2.0

package/dist/__tests__/test-helpers.d.ts

@@ -0,0 +1,17 @@
+import type { Readable } from 'node:stream';
+import type { Application } from 'express';
+export type MockHttpRequest = {
+    method: string;
+    path: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    rawBody?: string | Buffer;
+};
+export type MockHttpResponse = {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+    stream?: Readable;
+};
+export declare function executeExpressRequest(app: Application, req: MockHttpRequest): Promise<MockHttpResponse>;
+//# sourceMappingURL=test-helpers.d.ts.map

package/dist/__tests__/test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../../src/__tests__/test-helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB,CAAC;AAWF,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqI7G"}

package/dist/constants.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Injection token for the Mastra instance.
+ * Use with @Inject(MASTRA) to inject the Mastra instance.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class MyService {
+ *   constructor(@Inject(MASTRA) private readonly mastra: Mastra) {}
+ * }
+ * ```
+ */
+export declare const MASTRA: unique symbol;
+/**
+ * Injection token for the Mastra module options.
+ * Used internally by MastraService.
+ */
+export declare const MASTRA_OPTIONS: unique symbol;
+/**
+ * Metadata key for @Public() decorator.
+ * Routes marked as public skip authentication.
+ */
+export declare const IS_PUBLIC_KEY = "isPublic";
+/**
+ * Metadata key for @MastraThrottle() decorator.
+ * Custom rate limits per route.
+ */
+export declare const THROTTLE_KEY = "mastraThrottle";
+/**
+ * Metadata key for route information.
+ * Stores the Mastra route definition for the handler.
+ */
+export declare const MASTRA_ROUTE_KEY = "mastraRoute";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,MAAM,eAAmB,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,cAAc,eAA2B,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,aAAa,aAAa,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,gBAAgB,gBAAgB,CAAC"}

package/dist/controllers/index.d.ts

@@ -0,0 +1,3 @@
+export { MastraController } from './mastra.controller.js';
+export { SystemController } from './system.controller.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/controllers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/controllers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/controllers/mastra.controller.d.ts

@@ -0,0 +1,54 @@
+import type { Request, Response } from 'express';
+import type { MastraModuleOptions } from '../mastra.module.js';
+import { RequestContextService } from '../services/request-context.service.js';
+import { RouteHandlerService } from '../services/route-handler.service.js';
+/**
+ * Main Mastra controller that handles all routes dynamically.
+ * Routes are matched against SERVER_ROUTES from @mastra/server.
+ *
+ * Auth and rate limiting are handled via MastraRouteGuard so they only apply
+ * to matched Mastra routes and do not affect the rest of the user's app.
+ */
+export declare class MastraController {
+    private readonly options;
+    private readonly routeHandler;
+    private readonly requestContext;
+    constructor(options: MastraModuleOptions, routeHandler: RouteHandlerService, requestContext: RequestContextService);
+    /**
+     * Catch-all handler that matches incoming requests to Mastra routes.
+     */
+    handleRequest(req: Request, _res: Response): Promise<unknown>;
+    /**
+     * Parse and normalize query parameters.
+     * Handles type coercion for numbers, booleans, arrays, and JSON strings.
+     */
+    private parseQueryParams;
+    /**
+     * Coerce a query parameter value to its appropriate type.
+     *
+     * Type coercion rules:
+     * - "true"/"false" → boolean
+     * - "null" → null
+     * - Numeric strings → number (except IDs with leading zeros like "007")
+     * - JSON objects/arrays → parsed object/array
+     *
+     * @example
+     * // Numbers
+     * coerceQueryValue("42")      // → 42
+     * coerceQueryValue("3.14")    // → 3.14
+     * coerceQueryValue("007")     // → "007" (preserved as string)
+     *
+     * // Booleans
+     * coerceQueryValue("true")    // → true
+     * coerceQueryValue("false")   // → false
+     *
+     * // JSON
+     * coerceQueryValue('{"a":1}') // → { a: 1 }
+     */
+    private coerceQueryValue;
+    /**
+     * Parse request body, handling multipart/form-data and JSON.
+     */
+    private parseBody;
+}
+//# sourceMappingURL=mastra.controller.d.ts.map

package/dist/controllers/mastra.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mastra.controller.d.ts","sourceRoot":"","sources":["../../src/controllers/mastra.controller.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAQjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAIxE;;;;;;GAMG;AACH,qBAIa,gBAAgB;IAED,OAAO,CAAC,QAAQ,CAAC,OAAO;IACnB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC3B,OAAO,CAAC,QAAQ,CAAC,cAAc;gBAFrB,OAAO,EAAE,mBAAmB,EACvB,YAAY,EAAE,mBAAmB,EAC/B,cAAc,EAAE,qBAAqB;IAGvF;;OAEG;IAEG,aAAa,CAAQ,GAAG,EAAE,OAAO,EAA8B,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IA+BtG;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,gBAAgB;IAoCxB;;OAEG;YACW,SAAS;CAsBxB"}

package/dist/controllers/system.controller.d.ts

@@ -0,0 +1,45 @@
+import type { Mastra } from '@mastra/core/mastra';
+import type { Response } from 'express';
+import type { MastraModuleOptions } from '../mastra.module.js';
+import { ShutdownService } from '../services/shutdown.service.js';
+/**
+ * System controller for health checks and diagnostics.
+ *
+ * Routes are at the root level (not under the Mastra prefix) for compatibility
+ * with Kubernetes, Docker, and container orchestration systems that typically
+ * expect /health at root level.
+ *
+ * These routes are public (@Public) and skip rate limiting (@SkipThrottle).
+ */
+export declare class SystemController {
+    private readonly mastra;
+    private readonly options;
+    private readonly shutdownService;
+    constructor(mastra: Mastra, options: MastraModuleOptions, shutdownService: ShutdownService);
+    /**
+     * Health check endpoint.
+     * Returns 200 if healthy, 503 if shutting down.
+     */
+    health(res: Response): {
+        status: 'ok' | 'shutting_down';
+        timestamp: string;
+    };
+    /**
+     * Readiness check endpoint.
+     * Returns 200 if ready to accept traffic, 503 if not.
+     */
+    ready(res: Response): {
+        ready: boolean;
+        activeRequests: number;
+        timestamp: string;
+    };
+    /**
+     * Version and info endpoint.
+     */
+    info(): {
+        version: string;
+        prefix: string;
+        timestamp: string;
+    };
+}
+//# sourceMappingURL=system.controller.d.ts.map

package/dist/controllers/system.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.controller.d.ts","sourceRoot":"","sources":["../../src/controllers/system.controller.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAKxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAgB/D;;;;;;;;GAQG;AACH,qBACa,gBAAgB;IAET,OAAO,CAAC,QAAQ,CAAC,MAAM;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO;IACvB,OAAO,CAAC,QAAQ,CAAC,eAAe;gBAFxB,MAAM,EAAE,MAAM,EACN,OAAO,EAAE,mBAAmB,EAC3B,eAAe,EAAE,eAAe;IAG5E;;;OAGG;IAIH,MAAM,CAA6B,GAAG,EAAE,QAAQ,GAAG;QAAE,MAAM,EAAE,IAAI,GAAG,eAAe,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAYxG;;;OAGG;IAIH,KAAK,CAA6B,GAAG,EAAE,QAAQ,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAa/G;;OAEG;IAIH,IAAI,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;CAO/D"}

package/dist/decorators/index.d.ts

@@ -0,0 +1,3 @@
+export { Public } from './public.decorator.js';
+export { MastraThrottle, SkipThrottle, type ThrottleOptions } from './throttle.decorator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/decorators/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/decorators/public.decorator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Decorator to mark a route as public (no authentication required).
+ *
+ * @example
+ * ```typescript
+ * @Controller('health')
+ * export class HealthController {
+ *   @Get()
+ *   @Public()
+ *   check() {
+ *     return { status: 'ok' };
+ *   }
+ * }
+ * ```
+ */
+export declare const Public: () => import("@nestjs/common").CustomDecorator<string>;
+//# sourceMappingURL=public.decorator.d.ts.map

package/dist/decorators/public.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/public.decorator.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,wDAAyC,CAAC"}

package/dist/decorators/throttle.decorator.d.ts

@@ -0,0 +1,34 @@
+export interface ThrottleOptions {
+    /** Maximum number of requests in the window */
+    limit: number;
+    /** Time window in milliseconds */
+    windowMs: number;
+}
+/**
+ * Decorator to set custom rate limits for a route.
+ * Overrides the default rate limits from MastraModuleOptions.
+ *
+ * @example
+ * ```typescript
+ * @Post('generate')
+ * @MastraThrottle({ limit: 5, windowMs: 60000 }) // 5 requests per minute
+ * async generate(@Body() body: GenerateDto) {
+ *   // ...
+ * }
+ * ```
+ */
+export declare const MastraThrottle: (options: ThrottleOptions) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * Decorator to skip rate limiting for a route.
+ *
+ * @example
+ * ```typescript
+ * @Get('health')
+ * @SkipThrottle()
+ * check() {
+ *   return { status: 'ok' };
+ * }
+ * ```
+ */
+export declare const SkipThrottle: () => import("@nestjs/common").CustomDecorator<string>;
+//# sourceMappingURL=throttle.decorator.d.ts.map

package/dist/decorators/throttle.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/throttle.decorator.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,eAAe,qDAAuC,CAAC;AAE/F;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,wDAAkD,CAAC"}

package/dist/filters/index.d.ts

@@ -0,0 +1,2 @@
+export { MastraExceptionFilter } from './mastra-exception.filter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/filters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/filters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/filters/mastra-exception.filter.d.ts

@@ -0,0 +1,28 @@
+import type { ArgumentsHost, ExceptionFilter } from '@nestjs/common';
+/**
+ * Global exception filter that normalizes all errors to a consistent format.
+ *
+ * Response format:
+ * ```json
+ * {
+ *   "error": "Error message",
+ *   "code": "ERROR_CODE",
+ *   "issues": [{ "field": "fieldName", "message": "..." }],
+ *   "requestId": "...",
+ *   "timestamp": "..."
+ * }
+ * ```
+ */
+export declare class MastraExceptionFilter implements ExceptionFilter {
+    private readonly logger;
+    catch(exception: unknown, host: ArgumentsHost): void;
+    /**
+     * Normalize any error type to a consistent format.
+     */
+    private normalizeError;
+    /**
+     * Get error code from HTTP status.
+     */
+    private getErrorCode;
+}
+//# sourceMappingURL=mastra-exception.filter.d.ts.map

package/dist/filters/mastra-exception.filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mastra-exception.filter.d.ts","sourceRoot":"","sources":["../../src/filters/mastra-exception.filter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAyBrE;;;;;;;;;;;;;GAaG;AACH,qBACa,qBAAsB,YAAW,eAAe;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IAEjE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI;IAkCpD;;OAEG;IACH,OAAO,CAAC,cAAc;IAgHtB;;OAEG;IACH,OAAO,CAAC,YAAY;CAkCrB"}

package/dist/guards/index.d.ts

@@ -0,0 +1,3 @@
+export { MastraAuthGuard } from './mastra-auth.guard.js';
+export { MastraThrottleGuard } from './mastra-throttle.guard.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/guards/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guards/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/guards/mastra-auth.guard.d.ts

@@ -0,0 +1,42 @@
+import type { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { AuthService } from '../services/auth.service.js';
+/**
+ * Guard that bridges to Mastra's authentication system.
+ * Checks for @Public() decorator to skip auth.
+ *
+ * **IMPORTANT: This guard is for custom user routes, NOT for Mastra API routes.**
+ *
+ * Mastra routes (agents, workflows, etc.) use AuthService internally which has
+ * access to route-specific auth configuration (customRouteAuthConfig, isProtectedPath,
+ * canAccessPublicly). This guard is a simplified version for when you want to
+ * protect your own NestJS routes with Mastra's auth config.
+ *
+ * Differences from AuthService (used internally for Mastra routes):
+ * - Does NOT check `customRouteAuthConfig`
+ * - Does NOT check `isProtectedPath` / `canAccessPublicly` from @mastra/server/auth
+ * - Has simpler dev playground detection (just checks header + config)
+ *
+ * @example
+ * ```typescript
+ * // Protect a custom route with Mastra auth
+ * @Controller('my-custom')
+ * @UseGuards(MastraAuthGuard)
+ * export class MyController {
+ *   @Get('protected')
+ *   protectedRoute() { ... }
+ *
+ *   @Get('open')
+ *   @Public() // Skip auth for this route
+ *   openRoute() { ... }
+ * }
+ * ```
+ */
+export declare class MastraAuthGuard implements CanActivate {
+    private readonly reflector;
+    private readonly authService;
+    private readonly logger;
+    constructor(reflector: Reflector, authService: AuthService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+//# sourceMappingURL=mastra-auth.guard.d.ts.map

package/dist/guards/mastra-auth.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mastra-auth.guard.d.ts","sourceRoot":"","sources":["../../src/guards/mastra-auth.guard.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBACa,eAAgB,YAAW,WAAW;IAI5B,OAAO,CAAC,QAAQ,CAAC,SAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAJnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;gBAGrB,SAAS,EAAE,SAAS,EAClB,WAAW,EAAE,WAAW;IAG1D,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CAoB/D"}