@nitrostack/core 1.0.0

package/dist/core/oauth-module.js

@@ -0,0 +1,324 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var OAuthModule_1;
+import 'reflect-metadata';
+/**
+ * OAuth Module - Enable OAuth 2.1 authentication in your MCP server
+ *
+ * This module provides:
+ * - Protected Resource Metadata (RFC 9728)
+ * - Token validation with audience binding (RFC 8707)
+ * - Token introspection (RFC 7662)
+ * - PKCE support (RFC 7636)
+ *
+ * Compatible with OpenAI Apps SDK and MCP specification.
+ *
+ * @example
+ * ```typescript
+ * import { McpApplicationFactory, OAuthModule } from 'nitrostack';
+ * import { AppModule } from './app.module.js';
+ *
+ * @McpApp({
+ *   module: AppModule,
+ *   server: {
+ *     name: 'OAuth MCP Server',
+ *     version: '1.0.0',
+ *   },
+ * })
+ * @Module({
+ *   name: 'app',
+ *   imports: [
+ *     // Enable OAuth 2.1 authentication
+ *     OAuthModule.forRoot({
+ *       resourceUri: process.env.RESOURCE_URI!,
+ *       authorizationServers: [process.env.AUTH_SERVER_URL!],
+ *       scopesSupported: ['mcp:read', 'mcp:write', 'tools:execute'],
+ *       tokenIntrospectionEndpoint: process.env.INTROSPECTION_ENDPOINT,
+ *       tokenIntrospectionClientId: process.env.INTROSPECTION_CLIENT_ID,
+ *       tokenIntrospectionClientSecret: process.env.INTROSPECTION_CLIENT_SECRET,
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+import { Injectable, Inject } from './di/injectable.decorator.js';
+import { NitroStackServer } from './server.js';
+import { DiscoveryHttpServer } from './transports/discovery-http-server.js';
+let OAuthModule = class OAuthModule {
+    static { OAuthModule_1 = this; }
+    config;
+    server;
+    logger;
+    static config = null;
+    discoveryServer = null;
+    wellKnownHandler = (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            issuer: this.config.issuer,
+            token_endpoint: `${this.config.authorizationServers[0]}/oauth/token`,
+            // Add other metadata as needed
+        }));
+    };
+    resourceMetadataHandler = (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        // RFC 9728 - Protected Resource Metadata format
+        const metadata = {
+            resource: this.config.resourceUri,
+            authorization_servers: this.config.authorizationServers,
+        };
+        // Add optional fields
+        if (this.config.scopesSupported && this.config.scopesSupported.length > 0) {
+            metadata.scopes_supported = this.config.scopesSupported;
+        }
+        res.end(JSON.stringify(metadata));
+    };
+    constructor(config, server, logger) {
+        this.config = config;
+        this.server = server;
+        this.logger = logger;
+        OAuthModule_1.config = config;
+    }
+    onModuleInit() {
+        // Register the discovery endpoints
+        // Handlers are now arrow functions, so no need to bind
+    }
+    async start() {
+        this.logger.info('OAuthModule: start method called');
+        const transportType = this.server._transportType;
+        // Get port from environment or config, fallback to 3005
+        // Check MCP_SERVER_PORT first (set by dev command), then PORT, then config
+        const port = process.env.MCP_SERVER_PORT
+            ? parseInt(process.env.MCP_SERVER_PORT)
+            : process.env.PORT
+                ? parseInt(process.env.PORT)
+                : (this.config.http?.port || 3005);
+        if (transportType === 'stdio') {
+            this.logger.info(`OAuthModule: Running in STDIO mode, starting DiscoveryHttpServer on port ${port}`);
+            // In stdio mode, start a separate discovery server for OAuth endpoints
+            this.discoveryServer = new DiscoveryHttpServer(port, this.logger);
+            this.registerDiscoveryHandlers(this.discoveryServer);
+            await this.discoveryServer.start();
+        }
+        else {
+            this.logger.info(`OAuthModule: Running in ${transportType} mode, registering handlers with main server`);
+            // In http or dual mode, register the handlers with the main server
+            const httpTransport = this.server._httpTransport;
+            if (httpTransport) {
+                this.registerDiscoveryHandlers(httpTransport);
+            }
+            else {
+                // Fallback: if httpTransport is not available, start a discovery server anyway
+                // This handles edge cases where the transport setup fails or is delayed
+                this.logger.warn(`OAuthModule: httpTransport not found for ${transportType} mode. Starting fallback DiscoveryHttpServer on port ${port}`);
+                this.discoveryServer = new DiscoveryHttpServer(port, this.logger);
+                this.registerDiscoveryHandlers(this.discoveryServer);
+                await this.discoveryServer.start();
+            }
+        }
+    }
+    async stop() {
+        if (this.discoveryServer) {
+            await this.discoveryServer.stop();
+            this.discoveryServer = null;
+        }
+    }
+    registerDiscoveryHandlers(server) {
+        server.on('/.well-known/oauth-authorization-server', this.wellKnownHandler);
+        server.on('/.well-known/oauth-protected-resource', this.resourceMetadataHandler);
+    }
+    /**
+     * Configure OAuth module for the application
+     */
+    static forRoot(config) {
+        // Validate required fields
+        if (!config.resourceUri) {
+            throw new Error('OAuthModule: resourceUri is required');
+        }
+        if (!config.authorizationServers || config.authorizationServers.length === 0) {
+            throw new Error('OAuthModule: at least one authorizationServer is required');
+        }
+        // Set default audience to resourceUri if not provided
+        if (!config.audience) {
+            config.audience = config.resourceUri;
+        }
+        this.config = config;
+        return {
+            module: OAuthModule_1,
+            providers: [
+                { provide: 'OAUTH_CONFIG', useValue: config }
+            ],
+        };
+    }
+    /**
+     * Get current OAuth configuration
+     */
+    static getConfig() {
+        return this.config;
+    }
+    /**
+     * Validate an access token
+     *
+     * Performs:
+     * 1. Token introspection (if endpoint configured)
+     * 2. Audience validation (RFC 8807)
+     * 3. Issuer validation (if configured)
+     * 4. Custom validation (if configured)
+     */
+    static async validateToken(token) {
+        if (!this.config) {
+            return { valid: false, error: 'OAuth module not configured' };
+        }
+        try {
+            // Decode the header to check token type and provide helpful error message
+            try {
+                const headerPart = token.split('.')[0];
+                const decodedHeader = JSON.parse(Buffer.from(headerPart, 'base64').toString());
+                // Check if we received a JWE (encrypted) token instead of JWT
+                if (decodedHeader.alg === 'dir' || decodedHeader.enc) {
+                    return {
+                        valid: false,
+                        error: 'Received encrypted JWE token. MCP servers require unencrypted JWT access tokens. Check your OAuth provider application settings to ensure ID Token Encryption is disabled and that the "audience" parameter is being sent in authorization requests.'
+                    };
+                }
+            }
+            catch (headerError) {
+                // If header decode fails, continue with normal validation
+            }
+            // If introspection endpoint is configured, use it
+            if (this.config.tokenIntrospectionEndpoint) {
+                return await this.introspectToken(token);
+            }
+            // For JWT tokens without introspection, decode and validate
+            // Note: In production, you should validate JWT signature
+            const payload = this.decodeToken(token);
+            if (!payload) {
+                return { valid: false, error: 'Invalid token format' };
+            }
+            // Validate audience (RFC 8707 - critical for security)
+            if (payload.aud) {
+                const audiences = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+                if (!audiences.includes(this.config.audience)) {
+                    return {
+                        valid: false,
+                        error: `Token audience mismatch. Expected: ${this.config.audience}, Got: ${audiences.join(', ')}`,
+                    };
+                }
+            }
+            // Validate issuer
+            if (this.config.issuer && payload.iss !== this.config.issuer) {
+                return {
+                    valid: false,
+                    error: `Token issuer mismatch. Expected: ${this.config.issuer}, Got: ${payload.iss}`,
+                };
+            }
+            // Check expiration
+            const expiration = payload.exp;
+            if (expiration && expiration < Date.now() / 1000) {
+                return { valid: false, error: 'Token expired' };
+            }
+            // Custom validation
+            if (this.config.customValidation) {
+                const customValid = await this.config.customValidation(payload);
+                if (!customValid) {
+                    return { valid: false, error: 'Custom validation failed' };
+                }
+            }
+            return { valid: true, payload };
+        }
+        catch (error) {
+            return { valid: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    /**
+     * Introspect token using RFC 7662
+     * @private
+     */
+    static async introspectToken(token) {
+        if (!this.config?.tokenIntrospectionEndpoint) {
+            return { valid: false, error: 'Introspection endpoint not configured' };
+        }
+        try {
+            const auth = Buffer.from(`${this.config.tokenIntrospectionClientId}:${this.config.tokenIntrospectionClientSecret}`).toString('base64');
+            const response = await fetch(this.config.tokenIntrospectionEndpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    'Authorization': `Basic ${auth}`,
+                },
+                body: new URLSearchParams({
+                    token: token,
+                    token_type_hint: 'access_token',
+                }),
+            });
+            if (!response.ok) {
+                return {
+                    valid: false,
+                    error: `Introspection failed: ${response.status} ${response.statusText}`,
+                };
+            }
+            const result = await response.json();
+            if (!result.active) {
+                return { valid: false, error: 'Token is not active' };
+            }
+            // Validate audience from introspection response
+            if (result.aud) {
+                const audiences = Array.isArray(result.aud) ? result.aud : [result.aud];
+                if (!audiences.includes(this.config.audience)) {
+                    return {
+                        valid: false,
+                        error: `Token audience mismatch. Expected: ${this.config.audience}`,
+                    };
+                }
+            }
+            return { valid: true, payload: result };
+        }
+        catch (error) {
+            return { valid: false, error: `Introspection error: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    /**
+     * Decode JWT token (without validation)
+     * @private
+     */
+    static decodeToken(token) {
+        try {
+            const parts = token.split('.');
+            if (parts.length !== 3)
+                return null;
+            // Convert base64url to base64 by replacing URL-safe characters
+            let base64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+            // Add padding if necessary
+            const padding = base64.length % 4;
+            if (padding === 2) {
+                base64 += '==';
+            }
+            else if (padding === 3) {
+                base64 += '=';
+            }
+            const payload = JSON.parse(Buffer.from(base64, 'base64').toString('utf8'));
+            return payload;
+        }
+        catch {
+            return null;
+        }
+    }
+};
+OAuthModule = OAuthModule_1 = __decorate([
+    Injectable(),
+    __param(0, Inject('OAUTH_CONFIG')),
+    __param(2, Inject('Logger')),
+    __metadata("design:paramtypes", [Object, NitroStackServer, Object])
+], OAuthModule);
+export { OAuthModule };
+//# sourceMappingURL=oauth-module.js.map

package/dist/core/oauth-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-module.js","sourceRoot":"","sources":["../../src/core/oauth-module.ts"],"names":[],"mappings":"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"}

package/dist/core/pipes/pipe.decorator.d.ts

@@ -0,0 +1,64 @@
+import 'reflect-metadata';
+import { PipeConstructor } from './pipe.interface.js';
+import type { ClassConstructor } from '../types.js';
+/**
+ * Marks a class as a pipe
+ *
+ * @example
+ * ```typescript
+ * @Pipe()
+ * export class ValidationPipe implements PipeInterface {
+ *   transform(value: unknown, metadata: ArgumentMetadata) {
+ *     // Validate and transform
+ *     return value;
+ *   }
+ * }
+ * ```
+ */
+export declare function Pipe(): ClassDecorator;
+/**
+ * Apply pipes to tool input (entire input object)
+ *
+ * @example
+ * ```typescript
+ * @Tool({ name: 'create_user', ... })
+ * @UsePipes(ValidationPipe, TransformPipe)
+ * async createUser(input: unknown) { }
+ * ```
+ */
+export declare function UsePipes(...pipes: PipeConstructor[]): MethodDecorator;
+/**
+ * Parameter decorator to apply pipes to specific parameters
+ *
+ * @example
+ * ```typescript
+ * @Tool({ name: 'create_user', ... })
+ * async createUser(@Body(ValidationPipe) input: CreateUserDto) { }
+ * ```
+ */
+export declare function Body(...pipes: PipeConstructor[]): ParameterDecorator;
+/**
+ * Shorthand for validation pipe
+ */
+export declare function Validated(): ParameterDecorator;
+/**
+ * Parameter pipes metadata
+ */
+interface ParamPipeMetadata {
+    type: string;
+    pipes: PipeConstructor[];
+}
+/**
+ * Get pipes for a method
+ */
+export declare function getPipeMetadata(target: object, propertyKey: string | symbol): PipeConstructor[];
+/**
+ * Get parameter pipes for a method
+ */
+export declare function getParamPipesMetadata(target: object, propertyKey: string | symbol): Record<number, ParamPipeMetadata>;
+/**
+ * Check if a class is marked as a pipe
+ */
+export declare function isPipe(target: ClassConstructor): boolean;
+export {};
+//# sourceMappingURL=pipe.decorator.d.ts.map

package/dist/core/pipes/pipe.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipe.decorator.d.ts","sourceRoot":"","sources":["../../../src/core/pipes/pipe.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAMpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,IAAI,cAAc,CAIrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,GAAG,KAAK,EAAE,eAAe,EAAE,GAAG,eAAe,CAUrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,GAAG,KAAK,EAAE,eAAe,EAAE,GAAG,kBAAkB,CAWpE;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,kBAAkB,CAE9C;AAED;;GAEG;AACH,UAAU,iBAAiB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,eAAe,EAAE,CAE/F;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAErH;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAExD"}

package/dist/core/pipes/pipe.decorator.js

@@ -0,0 +1,85 @@
+import 'reflect-metadata';
+const PIPE_KEY = 'nitrostack:pipe';
+const IS_PIPE_KEY = 'nitrostack:is_pipe';
+const PARAM_PIPES_KEY = 'nitrostack:param_pipes';
+/**
+ * Marks a class as a pipe
+ *
+ * @example
+ * ```typescript
+ * @Pipe()
+ * export class ValidationPipe implements PipeInterface {
+ *   transform(value: unknown, metadata: ArgumentMetadata) {
+ *     // Validate and transform
+ *     return value;
+ *   }
+ * }
+ * ```
+ */
+export function Pipe() {
+    return (target) => {
+        Reflect.defineMetadata(IS_PIPE_KEY, true, target);
+    };
+}
+/**
+ * Apply pipes to tool input (entire input object)
+ *
+ * @example
+ * ```typescript
+ * @Tool({ name: 'create_user', ... })
+ * @UsePipes(ValidationPipe, TransformPipe)
+ * async createUser(input: unknown) { }
+ * ```
+ */
+export function UsePipes(...pipes) {
+    return (target, propertyKey, descriptor) => {
+        const existingPipes = Reflect.getMetadata(PIPE_KEY, target, propertyKey) || [];
+        Reflect.defineMetadata(PIPE_KEY, [...existingPipes, ...pipes], target, propertyKey);
+    };
+}
+/**
+ * Parameter decorator to apply pipes to specific parameters
+ *
+ * @example
+ * ```typescript
+ * @Tool({ name: 'create_user', ... })
+ * async createUser(@Body(ValidationPipe) input: CreateUserDto) { }
+ * ```
+ */
+export function Body(...pipes) {
+    return (target, propertyKey, parameterIndex) => {
+        if (!propertyKey)
+            return;
+        const existingParams = Reflect.getMetadata(PARAM_PIPES_KEY, target, propertyKey) || {};
+        existingParams[parameterIndex] = {
+            type: 'body',
+            pipes,
+        };
+        Reflect.defineMetadata(PARAM_PIPES_KEY, existingParams, target, propertyKey);
+    };
+}
+/**
+ * Shorthand for validation pipe
+ */
+export function Validated() {
+    return Body(); // Can be enhanced with default validation pipe
+}
+/**
+ * Get pipes for a method
+ */
+export function getPipeMetadata(target, propertyKey) {
+    return Reflect.getMetadata(PIPE_KEY, target, propertyKey) || [];
+}
+/**
+ * Get parameter pipes for a method
+ */
+export function getParamPipesMetadata(target, propertyKey) {
+    return Reflect.getMetadata(PARAM_PIPES_KEY, target, propertyKey) || {};
+}
+/**
+ * Check if a class is marked as a pipe
+ */
+export function isPipe(target) {
+    return Reflect.getMetadata(IS_PIPE_KEY, target) === true;
+}
+//# sourceMappingURL=pipe.decorator.js.map

package/dist/core/pipes/pipe.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipe.decorator.js","sourceRoot":"","sources":["../../../src/core/pipes/pipe.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAI1B,MAAM,QAAQ,GAAG,iBAAiB,CAAC;AACnC,MAAM,WAAW,GAAG,oBAAoB,CAAC;AACzC,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,IAAI;IAClB,OAAO,CAAC,MAAc,EAAE,EAAE;QACxB,OAAO,CAAC,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACpD,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAG,KAAwB;IAClD,OAAO,CAAC,MAAc,EAAE,WAA4B,EAAE,UAA8B,EAAE,EAAE;QACtF,MAAM,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;QAC/E,OAAO,CAAC,cAAc,CACpB,QAAQ,EACR,CAAC,GAAG,aAAa,EAAE,GAAG,KAAK,CAAC,EAC5B,MAAM,EACN,WAAW,CACZ,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,IAAI,CAAC,GAAG,KAAwB;IAC9C,OAAO,CAAC,MAAc,EAAE,WAAwC,EAAE,cAAsB,EAAE,EAAE;QAC1F,IAAI,CAAC,WAAW;YAAE,OAAO;QAEzB,MAAM,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;QACvF,cAAc,CAAC,cAAc,CAAC,GAAG;YAC/B,IAAI,EAAE,MAAM;YACZ,KAAK;SACN,CAAC;QACF,OAAO,CAAC,cAAc,CAAC,eAAe,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/E,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,IAAI,EAAE,CAAC,CAAC,+CAA+C;AAChE,CAAC;AAUD;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,WAA4B;IAC1E,OAAO,OAAO,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;AAClE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,WAA4B;IAChF,OAAO,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,MAAM,CAAC,MAAwB;IAC7C,OAAO,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;AAC3D,CAAC"}

package/dist/core/pipes/pipe.interface.d.ts

@@ -0,0 +1,41 @@
+import 'reflect-metadata';
+/**
+ * Constructor type for metatype
+ */
+type MetaType = new (...args: unknown[]) => unknown;
+/**
+ * Argument metadata for pipe transformation
+ */
+export interface ArgumentMetadata {
+    type: 'body' | 'param' | 'query' | 'custom';
+    metatype?: MetaType;
+    data?: string | undefined;
+}
+/**
+ * Pipe Interface
+ *
+ * Pipes are used to transform and validate input data before it reaches the tool handler.
+ * Similar to NestJS pipes.
+ *
+ * @example
+ * ```typescript
+ * @Pipe()
+ * export class ValidationPipe implements PipeInterface {
+ *   transform(value: unknown, metadata: ArgumentMetadata) {
+ *     if (!this.isValid(value)) {
+ *       throw new Error('Validation failed');
+ *     }
+ *     return value;
+ *   }
+ * }
+ * ```
+ */
+export interface PipeInterface<T = unknown, R = unknown> {
+    transform(value: T, metadata: ArgumentMetadata): R | Promise<R>;
+}
+/**
+ * Pipe constructor type
+ */
+export type PipeConstructor = new (...args: unknown[]) => PipeInterface;
+export {};
+//# sourceMappingURL=pipe.interface.d.ts.map

package/dist/core/pipes/pipe.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipe.interface.d.ts","sourceRoot":"","sources":["../../../src/core/pipes/pipe.interface.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAE1B;;GAEG;AACH,KAAK,QAAQ,GAAG,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;IACrD,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACjE;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,aAAa,CAAC"}

package/dist/core/pipes/pipe.interface.js

@@ -0,0 +1,2 @@
+import 'reflect-metadata';
+//# sourceMappingURL=pipe.interface.js.map

package/dist/core/pipes/pipe.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipe.interface.js","sourceRoot":"","sources":["../../../src/core/pipes/pipe.interface.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC"}

package/dist/core/prompt.d.ts

@@ -0,0 +1,46 @@
+import { PromptDefinition, ExecutionContext, PromptMessage, PromptArgument, PromptArgumentValue } from './types.js';
+/**
+ * MCP Prompt metadata structure
+ */
+interface McpPrompt {
+    name: string;
+    description: string;
+    arguments: PromptArgument[];
+}
+/**
+ * Prompt class provides a clean abstraction for defining and executing prompts
+ */
+export declare class Prompt {
+    private definition;
+    constructor(definition: PromptDefinition);
+    /**
+     * Get prompt name
+     */
+    get name(): string;
+    /**
+     * Get prompt description
+     */
+    get description(): string;
+    /**
+     * Get prompt arguments
+     */
+    get arguments(): PromptArgument[];
+    /**
+     * Execute the prompt with provided arguments
+     */
+    execute(args: Record<string, PromptArgumentValue>, context: ExecutionContext): Promise<PromptMessage[]>;
+    /**
+     * Validate prompt arguments
+     */
+    private validateArguments;
+    /**
+     * Create prompt metadata for MCP protocol
+     */
+    toMcpPrompt(): McpPrompt;
+}
+/**
+ * Helper function to create a prompt
+ */
+export declare function createPrompt(definition: PromptDefinition): Prompt;
+export {};
+//# sourceMappingURL=prompt.d.ts.map

package/dist/core/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/core/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,mBAAmB,EAAc,MAAM,YAAY,CAAC;AAGhI;;GAEG;AACH,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,cAAc,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,UAAU,CAAmB;gBAEzB,UAAU,EAAE,gBAAgB;IAIxC;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,cAAc,EAAE,CAEhC;IAED;;OAEG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAoB7G;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAYzB;;OAEG;IACH,WAAW,IAAI,SAAS;CAOzB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,CAEjE"}