nitrostack 1.0.0 → 1.0.1

package/templates/typescript-auth/src/db/setup.ts

@@ -0,0 +1,87 @@
+import * as dotenv from 'dotenv';
+import { initializeSchema, clearAllData } from './database.js';
+import { seedAll } from './seed.js';
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Database setup script
+ * Run with: npm run setup-db
+ */
+
+// Load environment variables
+dotenv.config();
+
+console.log('╔══════════════════════════════════════════════════════════════╗');
+console.log('║                                                              ║');
+console.log('║           E-COMMERCE MCP SERVER - DATABASE SETUP             ║');
+console.log('║                                                              ║');
+console.log('╚══════════════════════════════════════════════════════════════╝\n');
+
+try {
+  // 1. Initialize schema
+  console.log('📦 Initializing database schema...');
+  initializeSchema();
+  console.log('✅ Schema initialized\n');
+  
+  // 2. Clear existing data (optional)
+  console.log('🗑️  Clearing existing data...');
+  clearAllData();
+  console.log('✅ Data cleared\n');
+  
+  // 3. Seed data
+  seedAll();
+  console.log('');
+  
+  // 4. Generate JWT secret if not exists
+  const envPath = path.join(process.cwd(), '.env');
+  const envExamplePath = path.join(process.cwd(), '.env.example');
+  
+  if (!fs.existsSync(envPath) && fs.existsSync(envExamplePath)) {
+    console.log('📝 Creating .env file...');
+    let envContent = fs.readFileSync(envExamplePath, 'utf-8');
+    
+    // Generate JWT secret (64 random bytes encoded as base64url)
+    const jwtSecret = 'jwt_secret_' + crypto.randomBytes(32).toString('base64url');
+    envContent = envContent.replace('your-jwt-secret-here-change-this', jwtSecret);
+    
+    fs.writeFileSync(envPath, envContent);
+    console.log('✅ .env file created with JWT secret\n');
+  }
+  
+  // 5. Print test credentials
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log('                     TEST CREDENTIALS                         ');
+  console.log('═══════════════════════════════════════════════════════════════\n');
+  
+  console.log('🧪 Test Users (use these in the inspector):');
+  console.log('');
+  console.log('  👤 Alice Johnson');
+  console.log('     Email: alice@example.com');
+  console.log('     Password: password123');
+  console.log('');
+  console.log('  👤 Bob Smith');
+  console.log('     Email: bob@example.com');
+  console.log('     Password: password123');
+  console.log('');
+  console.log('  👤 Charlie Brown');
+  console.log('     Email: charlie@example.com');
+  console.log('     Password: password123');
+  console.log('');
+  
+  console.log('═══════════════════════════════════════════════════════════════\n');
+  
+  console.log('🎉 Database setup complete!\n');
+  console.log('Next steps:');
+  console.log('  1. npm install');
+  console.log('  2. npm run build');
+  console.log('  3. npm run dev');
+  console.log('  4. Test in inspector with the credentials above\n');
+  
+  process.exit(0);
+} catch (error) {
+  console.error('❌ Setup failed:', error);
+  process.exit(1);
+}
+

package/templates/typescript-auth/src/events/analytics.service.ts

@@ -0,0 +1,52 @@
+import { Injectable, OnEvent } from 'nitrostack';
+
+/**
+ * Analytics Service
+ * 
+ * Tracks events for analytics
+ */
+@Injectable()
+export class AnalyticsService {
+  private events: any[] = [];
+
+  /**
+   * Track order creation
+   */
+  @OnEvent('order.created')
+  async trackOrderCreated(order: any): Promise<void> {
+    this.events.push({
+      type: 'order_created',
+      timestamp: new Date().toISOString(),
+      data: {
+        order_id: order.id,
+        total: order.total,
+        item_count: order.items?.length || 0,
+      },
+    });
+    console.log(`📊 Tracked: Order Created #${order.id}`);
+  }
+
+  /**
+   * Track product viewed
+   */
+  @OnEvent('product.viewed')
+  async trackProductViewed(product: any): Promise<void> {
+    this.events.push({
+      type: 'product_viewed',
+      timestamp: new Date().toISOString(),
+      data: {
+        product_id: product.id,
+        product_name: product.name,
+      },
+    });
+    console.log(`📊 Tracked: Product Viewed - ${product.name}`);
+  }
+
+  /**
+   * Get analytics data
+   */
+  getAnalytics(): any[] {
+    return this.events;
+  }
+}
+

package/templates/typescript-auth/src/events/notification.service.ts

@@ -0,0 +1,40 @@
+import { Injectable, OnEvent } from 'nitrostack';
+
+/**
+ * Notification Service
+ * 
+ * Listens to events and sends notifications
+ */
+@Injectable()
+export class NotificationService {
+  /**
+   * Handle order created event
+   */
+  @OnEvent('order.created')
+  async handleOrderCreated(order: any): Promise<void> {
+    console.log(`📧 Sending order confirmation email for order #${order.id}`);
+    // TODO: Implement actual email sending
+    console.log(`  To: ${order.user_email}`);
+    console.log(`  Subject: Order Confirmation #${order.id}`);
+    console.log(`  Total: $${order.total}`);
+  }
+
+  /**
+   * Handle order shipped event
+   */
+  @OnEvent('order.shipped')
+  async handleOrderShipped(order: any): Promise<void> {
+    console.log(`📦 Sending shipping notification for order #${order.id}`);
+    // TODO: Implement actual notification
+  }
+
+  /**
+   * Handle user registered event
+   */
+  @OnEvent('user.registered')
+  async handleUserRegistered(user: any): Promise<void> {
+    console.log(`👋 Sending welcome email to ${user.email}`);
+    // TODO: Implement actual welcome email
+  }
+}
+

package/templates/typescript-auth/src/filters/global-exception.filter.ts

@@ -0,0 +1,28 @@
+import { ExceptionFilter, ExceptionFilterInterface, ExecutionContext } from 'nitrostack';
+
+/**
+ * Global Exception Filter
+ * 
+ * Handles all unhandled exceptions and formats error responses
+ */
+@ExceptionFilter()
+export class GlobalExceptionFilter implements ExceptionFilterInterface {
+  catch(exception: any, context: ExecutionContext) {
+    context.logger.error('Unhandled exception', {
+      tool: context.toolName || 'unknown',
+      error: exception.message,
+      stack: exception.stack,
+    });
+    
+    // Format error response
+    return {
+      error: true,
+      message: exception.message || 'Internal server error',
+      code: exception.code || 'INTERNAL_ERROR',
+      timestamp: new Date().toISOString(),
+      requestId: context.requestId,
+      tool: context.toolName || 'unknown',
+    };
+  }
+}
+

package/templates/typescript-auth/src/guards/README.md

@@ -0,0 +1,75 @@
+# Guards
+
+Guards are classes that implement the `Guard` interface and determine whether a tool can be executed.
+
+## What are Guards?
+
+Guards in NitroStack are similar to NestJS guards - they handle authorization logic before tool execution. Use the `@UseGuards()` decorator to apply guards to your tools.
+
+## Available Guards
+
+### JWTGuard
+
+Validates JWT tokens and populates `context.auth` with user information.
+
+**Usage:**
+```typescript
+import { JWTGuard } from '../guards/jwt.guard.js';
+
+@Tool({ name: 'get_profile', ... })
+@UseGuards(JWTGuard)
+async getProfile(input: any, context: ExecutionContext) {
+  const userId = context.auth?.subject;
+  // User is already authenticated!
+}
+```
+
+## Creating Custom Guards
+
+Create a class that implements the `Guard` interface:
+
+```typescript
+import { Guard, ExecutionContext } from 'nitrostack';
+
+export class RoleGuard implements Guard {
+  constructor(private requiredRole: string) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const userRole = context.auth?.role;
+    
+    if (userRole !== this.requiredRole) {
+      throw new Error(`Required role: ${this.requiredRole}`);
+    }
+    
+    return true;
+  }
+}
+```
+
+**Usage:**
+```typescript
+@UseGuards(JWTGuard, new RoleGuard('admin'))
+async deleteUser(input: any, context: ExecutionContext) {
+  // Only admins can execute this
+}
+```
+
+## Guard Execution Order
+
+Guards are executed in the order they are specified:
+```typescript
+@UseGuards(JWTGuard, RoleGuard, PermissionGuard)
+```
+1. JWTGuard validates token
+2. RoleGuard checks user role
+3. PermissionGuard checks specific permissions
+
+If any guard returns `false` or throws an error, execution stops.
+
+## Best Practices
+
+1. **Keep guards focused** - Each guard should have one responsibility
+2. **Reuse guards** - Create guards that can be used across multiple tools
+3. **Clear error messages** - Help users understand why access was denied
+4. **Log important events** - Use `context.logger` for debugging
+

package/templates/typescript-auth/src/guards/jwt.guard.ts

@@ -0,0 +1,105 @@
+import jwt from 'jsonwebtoken';
+import { Guard, ExecutionContext, JWTPayload, JWTModule } from 'nitrostack';
+
+/**
+ * JWT Guard - Validates JWT tokens and populates context.auth
+ * 
+ * This is an example implementation. You can customize it for your needs.
+ * 
+ * @example
+ * ```typescript
+ * @Tool({ name: 'whoami', ... })
+ * @UseGuards(JWTGuard)
+ * async whoami(input: any, context: ExecutionContext) {
+ *   // context.auth is populated with JWT payload
+ *   return { user: context.auth };
+ * }
+ * ```
+ */
+export class JWTGuard implements Guard {
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    try {
+      // Get JWT secret from JWTModule configuration
+      const secret = JWTModule.getSecret();
+      if (!secret) {
+        context.logger.warn('[JWTGuard] JWT secret not configured');
+        throw new Error('JWT authentication not configured. Set JWT_SECRET environment variable.');
+      }
+
+      // Extract token from context
+      const token = this.extractToken(context);
+      if (!token) {
+        context.logger.info('[JWTGuard] No token found in request');
+        throw new Error('Authentication required. Please login first and include your JWT token.');
+      }
+
+      // Verify token
+      const payload = await this.verifyToken(token, secret);
+      if (!payload) {
+        context.logger.warn('[JWTGuard] Token verification failed');
+        throw new Error('Invalid or expired token. Please login again.');
+      }
+
+      // Populate context.auth
+      context.auth = {
+        subject: payload.sub,
+        scopes: [],
+        email: payload.email,
+        name: payload.name,
+        ...payload,
+      };
+
+      context.logger.info(`[JWTGuard] Authentication successful for user: ${payload.sub}`);
+      return true;
+    } catch (error) {
+      context.logger.error('[JWTGuard] Authentication failed', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Extract JWT token from execution context
+   * Supports multiple token locations for maximum compatibility
+   */
+  private extractToken(context: ExecutionContext): string | null {
+    // Priority 1: Check metadata for _jwt field (MCP protocol)
+    if (context.metadata?._jwt) {
+      return context.metadata._jwt as string;
+    }
+
+    // Priority 2: Check Authorization header format in metadata
+    if (context.metadata?.authorization) {
+      const auth = context.metadata.authorization as string;
+      if (auth.startsWith('Bearer ')) {
+        return auth.substring(7);
+      }
+      return auth;
+    }
+
+    // Priority 3: Check metadata.headers (if present)
+    const headers = context.metadata?.headers as any;
+    if (headers?.authorization) {
+      const auth = headers.authorization as string;
+      if (auth.startsWith('Bearer ')) {
+        return auth.substring(7);
+      }
+      return auth;
+    }
+
+    return null;
+  }
+
+  /**
+   * Verify JWT token
+   */
+  private async verifyToken(token: string, secret: string): Promise<JWTPayload | null> {
+    try {
+      const cleanSecret = secret.trim();
+      const decoded = jwt.verify(token, cleanSecret) as JWTPayload;
+      return decoded;
+    } catch (error) {
+      return null;
+    }
+  }
+}
+

package/templates/typescript-auth/src/health/database.health.ts

@@ -0,0 +1,41 @@
+import { HealthCheck, HealthCheckInterface, HealthCheckResult } from 'nitrostack';
+import { DatabaseService } from '../services/database.service.js';
+
+/**
+ * Database Health Check
+ * 
+ * Monitors database connectivity
+ */
+@HealthCheck({ 
+  name: 'database', 
+  description: 'Database connectivity check',
+  interval: 30 // Check every 30 seconds
+})
+export class DatabaseHealthCheck implements HealthCheckInterface {
+  constructor(private database: DatabaseService) {}
+
+  async check(): Promise<HealthCheckResult> {
+    try {
+      const isConnected = await this.database.ping();
+      
+      if (isConnected) {
+        return {
+          status: 'up',
+          message: 'Database is connected and responsive',
+        };
+      } else {
+        return {
+          status: 'down',
+          message: 'Database connection failed',
+        };
+      }
+    } catch (error: any) {
+      return {
+        status: 'down',
+        message: 'Database health check failed',
+        details: error.message,
+      };
+    }
+  }
+}
+

package/templates/typescript-auth/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * E-commerce MCP Server
+ * 
+ * Main entry point for the MCP server.
+ * Uses the new @McpApp decorator pattern for clean, NestJS-style architecture.
+ */
+
+import { McpApplicationFactory } from 'nitrostack';
+import { AppModule } from './app.module.js';
+
+/**
+ * Bootstrap the application
+ */
+async function bootstrap() {
+  // Create and start the MCP server from AppModule
+  const server = await McpApplicationFactory.create(AppModule);
+  
+  // Start the server
+  await server.start();
+}
+
+// Start the application
+bootstrap().catch((error) => {
+  console.error('❌ Failed to start server:', error);
+  process.exit(1);
+});

package/templates/typescript-auth/src/interceptors/transform.interceptor.ts

@@ -0,0 +1,24 @@
+import { Interceptor, InterceptorInterface, ExecutionContext } from 'nitrostack';
+
+/**
+ * Transform Interceptor
+ * 
+ * Wraps all responses in a standard format with metadata
+ */
+@Interceptor()
+export class TransformInterceptor implements InterceptorInterface {
+  async intercept(context: ExecutionContext, next: () => Promise<any>) {
+    const result = await next();
+    
+    return {
+      success: true,
+      data: result,
+      metadata: {
+        timestamp: new Date().toISOString(),
+        requestId: context.requestId,
+        tool: context.toolName || 'unknown',
+      },
+    };
+  }
+}
+

package/templates/typescript-auth/src/middleware/logging.middleware.ts

@@ -0,0 +1,42 @@
+import { Middleware, MiddlewareInterface, ExecutionContext } from 'nitrostack';
+
+/**
+ * Logging Middleware
+ * 
+ * Logs all tool executions with timing information
+ */
+@Middleware()
+export class LoggingMiddleware implements MiddlewareInterface {
+  async use(context: ExecutionContext, next: () => Promise<any>) {
+    const start = performance.now();
+    const toolName = context.toolName || 'unknown';
+    
+    context.logger.info(`[${toolName}] Started`, {
+      requestId: context.requestId,
+      user: context.auth?.subject || 'anonymous',
+    });
+    
+    try {
+      const result = await next();
+      const duration = performance.now() - start;
+      
+      context.logger.info(`[${toolName}] Completed in ${duration.toFixed(2)}ms`, {
+        requestId: context.requestId,
+        duration,
+      });
+      
+      return result;
+    } catch (error: any) {
+      const duration = performance.now() - start;
+      
+      context.logger.error(`[${toolName}] Failed after ${duration.toFixed(2)}ms`, {
+        requestId: context.requestId,
+        duration,
+        error: error.message,
+      });
+      
+      throw error;
+    }
+  }
+}
+

package/templates/typescript-auth/src/modules/addresses/addresses.module.ts

@@ -0,0 +1,16 @@
+import { Module } from 'nitrostack';
+import { AddressesTools } from './addresses.tools.js';
+import { AddressesResources } from './addresses.resources.js';
+import { AddressesPrompts } from './addresses.prompts.js';
+
+/**
+ * Addresses Module
+ * Provides shipping address management, resources, and prompts
+ */
+@Module({
+  name: 'addresses',
+  description: 'Shipping address management',
+  controllers: [AddressesTools, AddressesResources, AddressesPrompts],
+})
+export class AddressesModule {}
+

package/templates/typescript-auth/src/modules/addresses/addresses.prompts.ts

@@ -0,0 +1,114 @@
+import { PromptDecorator as Prompt, ExecutionContext } from 'nitrostack';
+
+/**
+ * Addresses Prompts
+ * Provides helpful prompts for address management
+ */
+export class AddressesPrompts {
+  /**
+   * Address management help prompt
+   */
+  @Prompt({
+    name: 'address-help',
+    description: 'Get help managing shipping addresses',
+  })
+  async addressHelp(args: Record<string, any>, context: ExecutionContext) {
+    return [
+      {
+        role: 'user' as const,
+        content: 'I need help managing shipping addresses',
+      },
+      {
+        role: 'assistant' as const,
+        content: `**Shipping Address Management Guide**
+
+**Available Tools (Requires Authentication):**
+1. \`add_address\` - Add new shipping address
+2. \`get_addresses\` - View all your addresses
+3. \`set_default_address\` - Set default for orders
+4. \`delete_address\` - Remove an address
+
+**Adding an Address:**
+\`\`\`
+add_address({
+  full_name: "John Doe",
+  street: "123 Main St",
+  city: "New York",
+  state: "NY",
+  zip_code: "10001",
+  country: "USA",
+  phone: "+1234567890",
+  is_default: true
+})
+\`\`\`
+
+**Required Fields:**
+- ✓ full_name
+- ✓ street
+- ✓ city
+- ✓ state
+- ✓ zip_code
+- ✓ phone
+
+**Optional Fields:**
+- country (defaults to "USA")
+- is_default (defaults to false)
+
+**Default Address:**
+- Used automatically for orders
+- Only one default address per user
+- Setting new default unsets old one
+
+**Viewing Addresses:**
+\`\`\`
+get_addresses({})
+\`\`\`
+Returns all addresses, sorted by:
+1. Default address first
+2. Then by creation date
+
+**Setting Default:**
+\`\`\`
+set_default_address({
+  address_id: "address-uuid"
+})
+\`\`\`
+
+**Deleting Address:**
+\`\`\`
+delete_address({
+  address_id: "address-uuid"
+})
+\`\`\`
+⚠️ Cannot be undone!
+
+**Address Format Tips:**
+📍 **Street:** Include apartment/unit if applicable
+📍 **State:** Use 2-letter code (NY, CA, TX)
+📍 **ZIP:** 5-digit or 9-digit format
+📍 **Phone:** Include country code for international
+
+**Common Operations:**
+1. **First Time Setup:**
+   - Add address with is_default: true
+   - Will be used for all orders
+
+2. **Multiple Addresses:**
+   - Add each address separately
+   - Set one as default
+   - Choose specific address when ordering
+
+3. **Update Address:**
+   - Delete old address
+   - Add new address with updated info
+
+**Tips:**
+✓ Add address before first order
+✓ Keep at least one address on file
+✓ Verify address details before saving
+✓ Use default for frequent shipping location`,
+      },
+    ];
+  }
+}
+