nitrostack 1.0.0 → 1.0.2

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

@@ -0,0 +1,147 @@
+import { PromptDecorator as Prompt, ExecutionContext } from 'nitrostack';
+
+/**
+ * Authentication Prompts
+ * Provides helpful prompts for authentication-related tasks
+ */
+export class AuthPrompts {
+  /**
+   * Authentication help prompt
+   */
+  @Prompt({
+    name: 'auth-help',
+    description: 'Get help with authentication and login process',
+    arguments: [
+      {
+        name: 'issue',
+        description: 'The authentication issue you are facing',
+        required: false,
+      },
+    ],
+  })
+  async authHelp(args: Record<string, any>, context: ExecutionContext) {
+    const issue = args.issue || 'general';
+    
+    const baseMessages = [
+      {
+        role: 'user' as const,
+        content: `I need help with authentication in the e-commerce system. My issue: ${issue}`,
+      },
+      {
+        role: 'assistant' as const,
+        content: `I'll help you with authentication. Here's what you need to know:
+
+**Login Process:**
+1. Use the \`login\` tool with email and password
+2. You'll receive a JWT token valid for 24 hours
+3. Include this token in subsequent requests
+
+**Test Accounts:**
+- alice@example.com / password123
+- bob@example.com / password123
+- charlie@example.com / password123
+
+**Including Token:**
+- In Inspector: Paste token in "JWT Token" field
+- Or use: Authorization: Bearer <your-token>
+
+**Protected Tools:**
+The following tools require authentication:
+- whoami - Get your profile
+- add_to_cart - Add items to cart
+- view_cart - View your cart
+- create_order - Place orders
+- get_order_history - View order history
+- add_address - Manage addresses
+
+**Common Issues:**
+${issue === 'invalid-token' ? '- Token expired: Login again to get a new token\n- Invalid format: Ensure you copied the complete token' : ''}
+${issue === 'unauthorized' ? '- Missing token: Make sure to login first\n- Wrong credentials: Check your email and password' : ''}
+${issue === 'general' ? '- Token expired? Login again\n- Forgot which email? Use test accounts above\n- Need to test? All test users have password: password123' : ''}
+
+**Security Notes:**
+- Tokens expire after 24 hours for security
+- Passwords are hashed with bcrypt
+- Never share your token with others`,
+      },
+    ];
+    
+    return baseMessages;
+  }
+
+  /**
+   * JWT token explanation prompt
+   */
+  @Prompt({
+    name: 'jwt-explained',
+    description: 'Understand how JWT authentication works in this system',
+  })
+  async jwtExplained(args: Record<string, any>, context: ExecutionContext) {
+    return [
+      {
+        role: 'user' as const,
+        content: 'Explain how JWT authentication works in this e-commerce system',
+      },
+      {
+        role: 'assistant' as const,
+        content: `**JWT Authentication in E-commerce MCP Server**
+
+**What is JWT?**
+JWT (JSON Web Token) is a secure way to transmit information between parties. It's a token that contains:
+- User identity (subject)
+- User information (email, name)
+- Expiration time
+- Digital signature
+
+**How It Works Here:**
+
+1. **Login** (Public)
+   - User provides email + password
+   - Server verifies with bcrypt
+   - Server generates JWT token
+   - Token valid for 24 hours
+
+2. **Using Protected Tools**
+   - Client includes token in request
+   - Server automatically validates token
+   - If valid: grants access
+   - If invalid/missing: denies access
+
+3. **Token Contents**
+   \`\`\`json
+   {
+     "sub": "user-id",
+     "email": "alice@example.com",
+     "name": "Alice Johnson",
+     "iat": 1234567890,
+     "exp": 1234654290
+   }
+   \`\`\`
+
+**Security Features:**
+- ✅ Tokens are signed (can't be tampered)
+- ✅ Passwords hashed with bcrypt
+- ✅ Tokens expire after 24 hours
+- ✅ No password storage in tokens
+
+**Developer Experience:**
+With V3 decorators, authentication is automatic:
+\`\`\`typescript
+@UseGuards(JWTGuard)
+async myProtectedTool(input, context) {
+  // context.auth is already populated!
+  const userId = context.auth.subject;
+}
+\`\`\`
+
+**No Manual Checking Needed!**
+The \`@UseGuards(JWTGuard)\` decorator handles:
+- Token extraction
+- Signature validation
+- Expiry checking
+- Context population`,
+      },
+    ];
+  }
+}
+

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

@@ -0,0 +1,84 @@
+import { ResourceDecorator as Resource, ExecutionContext } from 'nitrostack';
+import { getDatabase } from '../../db/database.js';
+
+/**
+ * Authentication Resources
+ * Provides auth-related resource endpoints
+ */
+export class AuthResources {
+  /**
+   * User schema resource
+   */
+  @Resource({
+    uri: 'auth://schema/user',
+    name: 'User Schema',
+    description: 'Schema definition for user objects in the authentication system',
+    mimeType: 'application/json',
+  })
+  async getUserSchema(context: ExecutionContext) {
+    return {
+      type: 'json' as const,
+      data: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', format: 'uuid', description: 'Unique user identifier' },
+          email: { type: 'string', format: 'email', description: 'User email address' },
+          name: { type: 'string', description: 'Full name' },
+          profile_picture: { type: 'string', format: 'uri', nullable: true, description: 'Profile picture URL' },
+          created_at: { type: 'string', format: 'date-time', description: 'Account creation timestamp' },
+        },
+        required: ['id', 'email', 'name'],
+      },
+    };
+  }
+
+  /**
+   * Available test users resource
+   */
+  @Resource({
+    uri: 'auth://test-users',
+    name: 'Test Users',
+    description: 'List of available test users for the demo',
+    mimeType: 'application/json',
+  })
+  async getTestUsers(context: ExecutionContext) {
+    return {
+      type: 'json' as const,
+      data: {
+        users: [
+          { email: 'alice@example.com', password: 'password123', name: 'Alice Johnson' },
+          { email: 'bob@example.com', password: 'password123', name: 'Bob Smith' },
+          { email: 'charlie@example.com', password: 'password123', name: 'Charlie Brown' },
+        ],
+        note: 'All test users have the same password: password123',
+      },
+    };
+  }
+
+  /**
+   * Authentication statistics
+   */
+  @Resource({
+    uri: 'auth://stats',
+    name: 'Auth Statistics',
+    description: 'Authentication system statistics',
+    mimeType: 'application/json',
+  })
+  async getAuthStats(context: ExecutionContext) {
+    const db = getDatabase();
+    
+    const totalUsers: any = db.prepare('SELECT COUNT(*) as count FROM users').get();
+    const recentLogins: any[] = db.prepare('SELECT email, created_at FROM users ORDER BY created_at DESC LIMIT 5').all();
+    
+    return {
+      type: 'json' as const,
+      data: {
+        totalUsers: totalUsers.count,
+        recentUsers: recentLogins,
+        authMethod: 'JWT with bcrypt password hashing',
+        tokenExpiry: '24 hours',
+      },
+    };
+  }
+}
+

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

@@ -0,0 +1,139 @@
+import { ToolDecorator as Tool, Widget, UseGuards, z, ExecutionContext } from 'nitrostack';
+import bcrypt from 'bcryptjs';
+import { getDatabase } from '../../db/database.js';
+import { generateJWT } from 'nitrostack';
+import { JWTGuard } from '../../guards/jwt.guard.js';
+
+/**
+ * Authentication Tools
+ * Handles user authentication and profile management
+ */
+export class AuthTools {
+  /**
+   * Login tool - Authenticate user and return JWT token
+   * No authentication required (public endpoint)
+   */
+  @Tool({
+    name: 'login',
+    description: 'Login with email and password to get a JWT token. Use this token in the Authorization header for authenticated requests.',
+    inputSchema: z.object({
+      email: z.string().email().describe('User email address'),
+      password: z.string().describe('User password'),
+    }),
+    examples: {
+      request: {
+        email: 'emily.johnson@x.dummyjson.com',
+        password: 'password123'
+      },
+      response: {
+        message: 'Login successful!',
+        token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+        user: {
+          id: 'user-emily',
+          email: 'emily.johnson@x.dummyjson.com',
+          name: 'Emily Johnson'
+        }
+      }
+    }
+  })
+  @Widget('login-result')
+  async login(input: any, context: ExecutionContext) {
+    const db = getDatabase();
+    
+    // Find user
+    const user: any = db.prepare('SELECT * FROM users WHERE email = ?').get(input.email);
+    
+    if (!user) {
+      throw new Error('Invalid email or password');
+    }
+    
+    // Verify password
+    const valid = bcrypt.compareSync(input.password, user.password_hash);
+    
+    if (!valid) {
+      throw new Error('Invalid email or password');
+    }
+    
+    // Generate JWT token
+    const token = generateJWT({
+      secret: process.env.JWT_SECRET!,
+      payload: {
+        sub: user.id,
+        email: user.email,
+        name: user.name,
+      },
+      expiresIn: '24h',
+      audience: process.env.JWT_AUDIENCE || 'ecommerce-mcp-server',
+      issuer: process.env.JWT_ISSUER || 'ecommerce-app',
+    });
+    
+    context.logger.info(`User logged in: ${user.email}`);
+    
+    return {
+      message: 'Login successful!',
+      token,
+      user: {
+        id: user.id,
+        email: user.email,
+        name: user.name,
+      },
+      instructions: {
+        step1: 'Copy the token above',
+        step2: 'In the inspector, go to Chat tab',
+        step3: 'Paste the token in the "JWT Token" field (if available)',
+        step4: 'Or use: Authorization: Bearer <token>',
+        expiresIn: '24 hours',
+      },
+    };
+  }
+
+  /**
+   * Get current user information
+   * Requires JWT authentication
+   */
+  @Tool({
+    name: 'whoami',
+    description: 'Get information about the currently authenticated user. Requires authentication.',
+    inputSchema: z.object({}),
+    examples: {
+      request: {},
+      response: {
+        user: {
+          id: 'user-emily',
+          email: 'emily.johnson@x.dummyjson.com',
+          name: 'Emily Johnson',
+          profile_picture: 'https://dummyjson.com/icon/emilys/128',
+          memberSince: '2024-01-01T00:00:00Z'
+        },
+        authenticated: true
+      }
+    }
+  })
+  @Widget('whoami')
+  @UseGuards(JWTGuard)
+  async whoami(input: any, context: ExecutionContext) {
+    // User is already authenticated by JWTGuard
+    const userId = context.auth?.subject;
+    
+    const db = getDatabase();
+    const user: any = db.prepare(`
+      SELECT id, email, name, profile_picture, created_at FROM users WHERE id = ?
+    `).get(userId);
+    
+    if (!user) {
+      throw new Error('User not found');
+    }
+    
+    return {
+      user: {
+        id: user.id,
+        email: user.email,
+        name: user.name,
+        profile_picture: user.profile_picture,
+        memberSince: user.created_at,
+      },
+      authenticated: true,
+    };
+  }
+}
+

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

@@ -0,0 +1,16 @@
+import { Module } from 'nitrostack';
+import { CartTools } from './cart.tools.js';
+import { CartResources } from './cart.resources.js';
+import { CartPrompts } from './cart.prompts.js';
+
+/**
+ * Cart Module
+ * Provides shopping cart management, resources, and prompts
+ */
+@Module({
+  name: 'cart',
+  description: 'Shopping cart management',
+  controllers: [CartTools, CartResources, CartPrompts],
+})
+export class CartModule {}
+

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

@@ -0,0 +1,95 @@
+import { PromptDecorator as Prompt, ExecutionContext } from 'nitrostack';
+
+/**
+ * Cart Prompts
+ * Provides helpful prompts for cart management
+ */
+export class CartPrompts {
+  /**
+   * Cart management help prompt
+   */
+  @Prompt({
+    name: 'cart-management-help',
+    description: 'Get help managing your shopping cart',
+  })
+  async cartHelp(args: Record<string, any>, context: ExecutionContext) {
+    return [
+      {
+        role: 'user' as const,
+        content: 'I need help managing my shopping cart',
+      },
+      {
+        role: 'assistant' as const,
+        content: `**Shopping Cart Management Guide**
+
+**Available Tools (Requires Authentication):**
+1. \`add_to_cart\` - Add products to cart
+2. \`view_cart\` - View cart contents and total
+3. \`update_cart_item\` - Change quantity or remove items
+4. \`clear_cart\` - Empty entire cart
+
+**Adding Items:**
+\`\`\`
+add_to_cart({
+  product_id: "product-uuid",
+  quantity: 2
+})
+\`\`\`
+- Make sure to login first
+- Check product stock availability
+- Quantity must be > 0
+
+**Viewing Cart:**
+\`\`\`
+view_cart({})
+\`\`\`
+- Shows all items with images
+- Displays individual and total prices
+- Item count included
+
+**Updating Items:**
+\`\`\`
+update_cart_item({
+  product_id: "product-uuid",
+  quantity: 5  // or 0 to remove
+})
+\`\`\`
+- Set quantity to 0 to remove item
+- Must have sufficient stock
+
+**Clearing Cart:**
+\`\`\`
+clear_cart({})
+\`\`\`
+- Removes ALL items
+- Cannot be undone
+
+**Common Operations:**
+📦 **Add Multiple Items:**
+Call \`add_to_cart\` multiple times with different product_ids
+
+🔄 **Update Quantity:**
+Use \`update_cart_item\` with new quantity
+
+🗑️ **Remove Single Item:**
+Use \`update_cart_item\` with quantity: 0
+
+💰 **Check Total:**
+Call \`view_cart\` to see current total
+
+**Best Practices:**
+✓ Login before adding to cart
+✓ Check stock before adding large quantities
+✓ Review cart before checkout
+✓ Use \`view_cart\` to verify changes
+
+**Tips:**
+- Cart persists between sessions
+- Items added increment existing quantities
+- Checkout with \`create_order\` when ready
+- Cart clears automatically after order`,
+      },
+    ];
+  }
+}
+

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

@@ -0,0 +1,44 @@
+import { ResourceDecorator as Resource, ExecutionContext } from 'nitrostack';
+
+/**
+ * Cart Resources
+ * Provides cart-related resource endpoints
+ */
+export class CartResources {
+  /**
+   * Cart schema resource
+   */
+  @Resource({
+    uri: 'cart://schema',
+    name: 'Cart Schema',
+    description: 'Schema definition for shopping cart objects',
+    mimeType: 'application/json',
+  })
+  async getCartSchema(context: ExecutionContext) {
+    return {
+      type: 'json' as const,
+      data: {
+        type: 'object',
+        properties: {
+          items: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                id: { type: 'string', description: 'Cart item ID' },
+                product_id: { type: 'string', description: 'Product ID' },
+                name: { type: 'string', description: 'Product name' },
+                price: { type: 'number', description: 'Product price' },
+                quantity: { type: 'integer', minimum: 1, description: 'Quantity in cart' },
+                image_url: { type: 'string', nullable: true, description: 'Product image' },
+              },
+            },
+          },
+          total: { type: 'number', description: 'Total cart value' },
+          itemCount: { type: 'integer', description: 'Number of items in cart' },
+        },
+      },
+    };
+  }
+}
+