nitrostack 1.0.0 → 1.0.1

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 {}
+

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 {}
+