nitrostack 1.0.0 → 1.0.2

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`,
+      },
+    ];
+  }
+}
+

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

@@ -0,0 +1,40 @@
+import { ResourceDecorator as Resource, ExecutionContext } from 'nitrostack';
+
+/**
+ * Addresses Resources
+ * Provides address-related resource endpoints
+ */
+export class AddressesResources {
+  /**
+   * Address schema resource
+   */
+  @Resource({
+    uri: 'addresses://schema',
+    name: 'Address Schema',
+    description: 'Schema definition for shipping address objects',
+    mimeType: 'application/json',
+  })
+  async getAddressSchema(context: ExecutionContext) {
+    return {
+      type: 'json' as const,
+      data: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', format: 'uuid', description: 'Address ID' },
+          user_id: { type: 'string', description: 'User ID' },
+          full_name: { type: 'string', description: 'Full name for delivery' },
+          street: { type: 'string', description: 'Street address' },
+          city: { type: 'string', description: 'City' },
+          state: { type: 'string', description: 'State/Province' },
+          zip_code: { type: 'string', description: 'ZIP/Postal code' },
+          country: { type: 'string', default: 'USA', description: 'Country' },
+          phone: { type: 'string', description: 'Contact phone number' },
+          is_default: { type: 'boolean', description: 'Is default shipping address' },
+          created_at: { type: 'string', format: 'date-time', description: 'Address creation time' },
+        },
+        required: ['full_name', 'street', 'city', 'state', 'zip_code', 'phone'],
+      },
+    };
+  }
+}
+

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

@@ -0,0 +1,241 @@
+import { ToolDecorator as Tool, Widget, UseGuards, z, ExecutionContext } from 'nitrostack';
+import { v4 as uuidv4 } from 'uuid';
+import { getDatabase } from '../../db/database.js';
+import { JWTGuard } from '../../guards/jwt.guard.js';
+
+/**
+ * Addresses Tools
+ * Handles user shipping addresses (requires authentication)
+ */
+export class AddressesTools {
+  /**
+   * Add new address - Requires authentication
+   */
+  @Tool({
+    name: 'add_address',
+    description: 'Add a new shipping address. Requires authentication.',
+    inputSchema: z.object({
+      full_name: z.string().describe('Full name for delivery'),
+      street: z.string().describe('Street address'),
+      city: z.string().describe('City'),
+      state: z.string().describe('State/Province'),
+      zip_code: z.string().describe('ZIP/Postal code'),
+      country: z.string().default('USA').describe('Country'),
+      phone: z.string().describe('Contact phone number'),
+      is_default: z.boolean().default(false).describe('Set as default address'),
+    }),
+    examples: {
+      request: {
+        full_name: 'Emily Johnson',
+        street: '123 Main Street',
+        city: 'San Francisco',
+        state: 'CA',
+        zip_code: '94102',
+        country: 'USA',
+        phone: '+1-555-0100',
+        is_default: true
+      },
+      response: {
+        message: 'Address added successfully!',
+        addressId: 'addr-1',
+        isDefault: true
+      }
+    }
+  })
+  @Widget('address-added')
+  @UseGuards(JWTGuard)
+  async addAddress(input: any, context: ExecutionContext) {
+    const db = getDatabase();
+    const userId = context.auth?.subject;
+    const addressId = uuidv4();
+    
+    // If this is set as default, unset other defaults
+    if (input.is_default) {
+      db.prepare(`
+        UPDATE addresses SET is_default = 0 WHERE user_id = ?
+      `).run(userId);
+    }
+    
+    db.prepare(`
+      INSERT INTO addresses (id, user_id, full_name, street, city, state, zip_code, country, phone, is_default)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      addressId,
+      userId,
+      input.full_name,
+      input.street,
+      input.city,
+      input.state,
+      input.zip_code,
+      input.country,
+      input.phone,
+      input.is_default ? 1 : 0
+    );
+    
+    context.logger.info(`Address added: ${input.city}, ${input.state}`);
+    
+    return {
+      message: 'Address added successfully!',
+      addressId,
+      isDefault: input.is_default,
+    };
+  }
+
+  /**
+   * Get all addresses - Requires authentication
+   */
+  @Tool({
+    name: 'get_addresses',
+    description: 'Get all saved shipping addresses. Requires authentication.',
+    inputSchema: z.object({}),
+    examples: {
+      request: {},
+      response: {
+        addresses: [
+          {
+            id: 'addr-1',
+            full_name: 'Emily Johnson',
+            street: '123 Main Street',
+            city: 'San Francisco',
+            state: 'CA',
+            zip_code: '94102',
+            country: 'USA',
+            phone: '+1-555-0100',
+            is_default: true
+          },
+          {
+            id: 'addr-2',
+            full_name: 'Emily Johnson',
+            street: '456 Office Blvd',
+            city: 'San Francisco',
+            state: 'CA',
+            zip_code: '94103',
+            country: 'USA',
+            phone: '+1-555-0100',
+            is_default: false
+          }
+        ]
+      }
+    }
+  })
+  @Widget('address-list')
+  @UseGuards(JWTGuard)
+  async getAddresses(input: any, context: ExecutionContext) {
+    const db = getDatabase();
+    const userId = context.auth?.subject;
+    
+    const addresses: any[] = db.prepare(`
+      SELECT * FROM addresses WHERE user_id = ? ORDER BY is_default DESC, created_at DESC
+    `).all(userId);
+    
+    context.logger.info(`Retrieved ${addresses.length} addresses`);
+    
+    return {
+      addresses: addresses.map(addr => ({
+        ...addr,
+        is_default: addr.is_default === 1,
+      })),
+    };
+  }
+
+  /**
+   * Set default address - Requires authentication
+   */
+  @Tool({
+    name: 'set_default_address',
+    description: 'Set an address as the default shipping address. Requires authentication.',
+    examples: {
+      request: {
+        address_id: 'addr-2'
+      },
+      response: {
+        message: 'Default address updated!',
+        addressId: 'addr-2'
+      }
+    },
+    inputSchema: z.object({
+      address_id: z.string().describe('The ID of the address to set as default'),
+    }),
+  })
+  @Widget('address-updated')
+  @UseGuards(JWTGuard)
+  async setDefaultAddress(input: any, context: ExecutionContext) {
+    const db = getDatabase();
+    const userId = context.auth?.subject;
+    
+    // Verify address belongs to user
+    const address: any = db.prepare(`
+      SELECT * FROM addresses WHERE id = ? AND user_id = ?
+    `).get(input.address_id, userId);
+    
+    if (!address) {
+      throw new Error('Address not found or you don\'t have access to it.');
+    }
+    
+    // Unset all defaults
+    db.prepare(`
+      UPDATE addresses SET is_default = 0 WHERE user_id = ?
+    `).run(userId);
+    
+    // Set new default
+    db.prepare(`
+      UPDATE addresses SET is_default = 1 WHERE id = ?
+    `).run(input.address_id);
+    
+    context.logger.info(`Set default address: ${address.city}, ${address.state}`);
+    
+    return {
+      message: 'Default address updated!',
+      address: {
+        ...address,
+        is_default: true,
+      },
+    };
+  }
+
+  /**
+   * Delete address - Requires authentication
+   */
+  @Tool({
+    name: 'delete_address',
+    description: 'Delete a shipping address. Requires authentication.',
+    inputSchema: z.object({
+      address_id: z.string().describe('The ID of the address to delete'),
+    }),
+    examples: {
+      request: {
+        address_id: 'addr-2'
+      },
+      response: {
+        message: 'Address deleted successfully!',
+        addressId: 'addr-2'
+      }
+    }
+  })
+  @Widget('address-deleted')
+  @UseGuards(JWTGuard)
+  async deleteAddress(input: any, context: ExecutionContext) {
+    const db = getDatabase();
+    const userId = context.auth?.subject;
+    
+    // Verify address belongs to user
+    const address: any = db.prepare(`
+      SELECT * FROM addresses WHERE id = ? AND user_id = ?
+    `).get(input.address_id, userId);
+    
+    if (!address) {
+      throw new Error('Address not found or you don\'t have access to it.');
+    }
+    
+    db.prepare(`
+      DELETE FROM addresses WHERE id = ?
+    `).run(input.address_id);
+    
+    context.logger.info(`Deleted address: ${address.city}, ${address.state}`);
+    
+    return {
+      message: 'Address deleted successfully!',
+    };
+  }
+}
+

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

@@ -0,0 +1,16 @@
+import { Module } from 'nitrostack';
+import { AuthTools } from './auth.tools.js';
+import { AuthResources } from './auth.resources.js';
+import { AuthPrompts } from './auth.prompts.js';
+
+/**
+ * Authentication Module
+ * Provides login, user profile tools, resources, and prompts
+ */
+@Module({
+  name: 'auth',
+  description: 'Authentication and user management',
+  controllers: [AuthTools, AuthResources, AuthPrompts],
+})
+export class AuthModule {}
+