@mastra/nestjs 0.0.0-observe-20260504181920

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# @mastra/nestjs
+
+## 0.0.0-observe-20260504181920
+
+### Patch Changes
+
+- Updated dependencies [[`6dcd65f`](https://github.com/mastra-ai/mastra/commit/6dcd65f2a34069e6dc43ba35f1d11119b9b40bef), [`86c0298`](https://github.com/mastra-ai/mastra/commit/86c0298e647306423c842f9d5ac827bd616bd13d), [`fb0719a`](https://github.com/mastra-ai/mastra/commit/fb0719aef8072132efbcdca740e265f5f2b98a99), [`c05c9a1`](https://github.com/mastra-ai/mastra/commit/c05c9a13230988cef6d438a62f37760f31927bc7), [`ca28c23`](https://github.com/mastra-ai/mastra/commit/ca28c232a2f18801a6cf20fe053479237b4d4fb0), [`e24aacb`](https://github.com/mastra-ai/mastra/commit/e24aacba07bd66f5d95b636dc24016fca26b52cf), [`7fce309`](https://github.com/mastra-ai/mastra/commit/7fce30912b14170bfc41f0ac736cca0f39fe0cd4), [`cd96779`](https://github.com/mastra-ai/mastra/commit/cd9677937f113b2856dc8b9f3d4bdabcee58bb2e), [`1c2dda8`](https://github.com/mastra-ai/mastra/commit/1c2dda805fbfccc0abf55d4cb20cc34402dc3f0c), [`c721164`](https://github.com/mastra-ai/mastra/commit/c7211643f7ac861f83b19a3757cc921487fc9d75), [`1b55954`](https://github.com/mastra-ai/mastra/commit/1b559541c1e08a10e49d01ffc51a634dfc37a286), [`7997c2e`](https://github.com/mastra-ai/mastra/commit/7997c2e55ddd121562a4098cd8d2b89c68433bf1), [`5adc55e`](https://github.com/mastra-ai/mastra/commit/5adc55e63407be8ee977914957d68bcc2a075ceb), [`5adc55e`](https://github.com/mastra-ai/mastra/commit/5adc55e63407be8ee977914957d68bcc2a075ceb), [`39162cb`](https://github.com/mastra-ai/mastra/commit/39162cb952c0053fdd4ed7217ec7802a2027b19d), [`e97ccb9`](https://github.com/mastra-ai/mastra/commit/e97ccb900f8b7a390ce82c9f8eb8d6eb2c5e3777), [`f5afe62`](https://github.com/mastra-ai/mastra/commit/f5afe62beff3ae69148a35e55fe5375168897829), [`c5daf48`](https://github.com/mastra-ai/mastra/commit/c5daf48556e98c46ae06caf00f92c249912007e9), [`70017d7`](https://github.com/mastra-ai/mastra/commit/70017d72ab741b5d7040e2a15c251a317782e39e), [`cd96779`](https://github.com/mastra-ai/mastra/commit/cd9677937f113b2856dc8b9f3d4bdabcee58bb2e), [`e4942bc`](https://github.com/mastra-ai/mastra/commit/e4942bc7fdc903572f7d84f26d5e15f9d39c763d), [`86c0298`](https://github.com/mastra-ai/mastra/commit/86c0298e647306423c842f9d5ac827bd616bd13d)]:
+  - @mastra/core@0.0.0-observe-20260504181920
+  - @mastra/server@0.0.0-observe-20260504181920
+
+## 0.1.1-alpha.3
+
+### Patch Changes
+
+- Updated dependencies [[`fb0719a`](https://github.com/mastra-ai/mastra/commit/fb0719aef8072132efbcdca740e265f5f2b98a99), [`ca28c23`](https://github.com/mastra-ai/mastra/commit/ca28c232a2f18801a6cf20fe053479237b4d4fb0), [`39162cb`](https://github.com/mastra-ai/mastra/commit/39162cb952c0053fdd4ed7217ec7802a2027b19d)]:
+  - @mastra/server@1.32.0-alpha.3
+  - @mastra/core@1.32.0-alpha.3
+
+## 0.1.1-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`86c0298`](https://github.com/mastra-ai/mastra/commit/86c0298e647306423c842f9d5ac827bd616bd13d), [`7fce309`](https://github.com/mastra-ai/mastra/commit/7fce30912b14170bfc41f0ac736cca0f39fe0cd4), [`cd96779`](https://github.com/mastra-ai/mastra/commit/cd9677937f113b2856dc8b9f3d4bdabcee58bb2e), [`7997c2e`](https://github.com/mastra-ai/mastra/commit/7997c2e55ddd121562a4098cd8d2b89c68433bf1), [`e97ccb9`](https://github.com/mastra-ai/mastra/commit/e97ccb900f8b7a390ce82c9f8eb8d6eb2c5e3777), [`f5afe62`](https://github.com/mastra-ai/mastra/commit/f5afe62beff3ae69148a35e55fe5375168897829), [`c5daf48`](https://github.com/mastra-ai/mastra/commit/c5daf48556e98c46ae06caf00f92c249912007e9), [`cd96779`](https://github.com/mastra-ai/mastra/commit/cd9677937f113b2856dc8b9f3d4bdabcee58bb2e), [`86c0298`](https://github.com/mastra-ai/mastra/commit/86c0298e647306423c842f9d5ac827bd616bd13d)]:
+  - @mastra/core@1.32.0-alpha.2
+  - @mastra/server@1.32.0-alpha.2
+
+## 0.1.1-alpha.1
+
+### Patch Changes
+
+- Updated dependencies [[`c05c9a1`](https://github.com/mastra-ai/mastra/commit/c05c9a13230988cef6d438a62f37760f31927bc7), [`e24aacb`](https://github.com/mastra-ai/mastra/commit/e24aacba07bd66f5d95b636dc24016fca26b52cf), [`c721164`](https://github.com/mastra-ai/mastra/commit/c7211643f7ac861f83b19a3757cc921487fc9d75), [`1b55954`](https://github.com/mastra-ai/mastra/commit/1b559541c1e08a10e49d01ffc51a634dfc37a286), [`5adc55e`](https://github.com/mastra-ai/mastra/commit/5adc55e63407be8ee977914957d68bcc2a075ceb), [`5adc55e`](https://github.com/mastra-ai/mastra/commit/5adc55e63407be8ee977914957d68bcc2a075ceb), [`70017d7`](https://github.com/mastra-ai/mastra/commit/70017d72ab741b5d7040e2a15c251a317782e39e), [`e4942bc`](https://github.com/mastra-ai/mastra/commit/e4942bc7fdc903572f7d84f26d5e15f9d39c763d)]:
+  - @mastra/core@1.32.0-alpha.1
+  - @mastra/server@1.32.0-alpha.1
+
+## 0.1.1-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`6dcd65f`](https://github.com/mastra-ai/mastra/commit/6dcd65f2a34069e6dc43ba35f1d11119b9b40bef), [`1c2dda8`](https://github.com/mastra-ai/mastra/commit/1c2dda805fbfccc0abf55d4cb20cc34402dc3f0c)]:
+  - @mastra/core@1.31.1-alpha.0
+  - @mastra/server@1.31.1-alpha.0
+
+## 0.1.0
+
+### Minor Changes
+
+- Add NestJS server adapter (`@mastra/nestjs`) for running Mastra with NestJS Express applications. Provides native module registration, DI-based service injection, rate limiting, graceful shutdown, streaming, and MCP transport support. ([#12751](https://github.com/mastra-ai/mastra/pull/12751))
+
+  ```typescript
+  import { Module } from '@nestjs/common';
+  import { MastraModule } from '@mastra/nestjs';
+  import { mastra } from './mastra';
+
+  @Module({
+    imports: [MastraModule.register({ mastra })],
+  })
+  export class AppModule {}
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`1723e09`](https://github.com/mastra-ai/mastra/commit/1723e099829892419ddbfe49287acfeac2522724), [`629f9e9`](https://github.com/mastra-ai/mastra/commit/629f9e9a7e56aa8f129515a3923c5813298790c7), [`25168fb`](https://github.com/mastra-ai/mastra/commit/25168fb9c1de9db7f8171df4f58ceb842c53aa29), [`ab34b5a`](https://github.com/mastra-ai/mastra/commit/ab34b5a2191b8e4353df1dbf7b9155e7d6628d79), [`5fb6c2a`](https://github.com/mastra-ai/mastra/commit/5fb6c2a95c1843cc231704b91354311fc1f34a71), [`2b0f355`](https://github.com/mastra-ai/mastra/commit/2b0f3553be3e9e5524da539a66e5cf82668440a4), [`f0d3c1a`](https://github.com/mastra-ai/mastra/commit/f0d3c1a9a2b283abc322d363f4f87e04e16837cf), [`394f0cf`](https://github.com/mastra-ai/mastra/commit/394f0cfc31e6b4d801219fdef2e9cc69e5bc8682), [`b2deb29`](https://github.com/mastra-ai/mastra/commit/b2deb29412b300c868655b5840463614fbb7962d), [`66644be`](https://github.com/mastra-ai/mastra/commit/66644beac1aa560f0e417956ff007c89341dc382), [`7dfea5e`](https://github.com/mastra-ai/mastra/commit/7dfea5eff7774eeeccd55ceb655392d70886206b), [`e109607`](https://github.com/mastra-ai/mastra/commit/e10960749251e34d46b480a20648c490fd30381b), [`310b953`](https://github.com/mastra-ai/mastra/commit/310b95345f302dcd5ba3ed862bdc96f059d44122), [`c600d54`](https://github.com/mastra-ai/mastra/commit/c600d5427277f44bc246b4daf70f77605ff1265c), [`3d7f709`](https://github.com/mastra-ai/mastra/commit/3d7f709b615e588050bb6283c4ee5cfe2978cbde), [`48a42f1`](https://github.com/mastra-ai/mastra/commit/48a42f114a4006a95e0b7a1b5ad1a24815a175c2), [`8091c7c`](https://github.com/mastra-ai/mastra/commit/8091c7c944d15e13fef6d61b6cfd903f158d4006), [`2c83efc`](https://github.com/mastra-ai/mastra/commit/2c83efc4482b3efe50830e3b8b4ba9a8d219edff), [`43f0e1d`](https://github.com/mastra-ai/mastra/commit/43f0e1d5d5a74ba6fc746f2ad89ebe0c64777a7d), [`da0b9e2`](https://github.com/mastra-ai/mastra/commit/da0b9e2ba7ecc560213b426d6c097fe63946086e), [`282a10c`](https://github.com/mastra-ai/mastra/commit/282a10c9446e9922afe80e10e3770481c8ac8a28), [`04151c7`](https://github.com/mastra-ai/mastra/commit/04151c7dcea934b4fe9076708a23fac161195414), [`8091c7c`](https://github.com/mastra-ai/mastra/commit/8091c7c944d15e13fef6d61b6cfd903f158d4006)]:
+  - @mastra/core@1.31.0
+  - @mastra/server@1.31.0
+
+## 0.1.0-alpha.1
+
+### Patch Changes
+
+- Updated dependencies [[`f0d3c1a`](https://github.com/mastra-ai/mastra/commit/f0d3c1a9a2b283abc322d363f4f87e04e16837cf)]:
+  - @mastra/server@1.31.0-alpha.5
+  - @mastra/core@1.31.0-alpha.5
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Add NestJS server adapter (`@mastra/nestjs`) for running Mastra with NestJS Express applications. Provides native module registration, DI-based service injection, rate limiting, graceful shutdown, streaming, and MCP transport support. ([#12751](https://github.com/mastra-ai/mastra/pull/12751))
+
+  ```typescript
+  import { Module } from '@nestjs/common';
+  import { MastraModule } from '@mastra/nestjs';
+  import { mastra } from './mastra';
+
+  @Module({
+    imports: [MastraModule.register({ mastra })],
+  })
+  export class AppModule {}
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`c600d54`](https://github.com/mastra-ai/mastra/commit/c600d5427277f44bc246b4daf70f77605ff1265c), [`8091c7c`](https://github.com/mastra-ai/mastra/commit/8091c7c944d15e13fef6d61b6cfd903f158d4006), [`04151c7`](https://github.com/mastra-ai/mastra/commit/04151c7dcea934b4fe9076708a23fac161195414), [`8091c7c`](https://github.com/mastra-ai/mastra/commit/8091c7c944d15e13fef6d61b6cfd903f158d4006)]:
+  - @mastra/server@1.31.0-alpha.4
+  - @mastra/core@1.31.0-alpha.4

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

@@ -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"}