nitrostack 1.0.0 → 1.0.1

package/templates/typescript-auth/src/widgets/widget-manifest.json

@@ -0,0 +1,464 @@
+{
+  "version": "1.0.0",
+  "widgets": [
+    {
+      "uri": "/login-result",
+      "name": "Login Result",
+      "description": "Displays login success with user information and JWT token",
+      "examples": [
+        {
+          "name": "Successful Login - Emily",
+          "description": "Login result for Emily Johnson",
+          "data": {
+            "message": "Login successful!",
+            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+            "user": {
+              "id": "user-emily",
+              "email": "emily.johnson@x.dummyjson.com",
+              "name": "Emily Johnson"
+            },
+            "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"
+            }
+          }
+        }
+      ],
+      "tags": ["auth", "login", "jwt"]
+    },
+    {
+      "uri": "/whoami",
+      "name": "User Profile",
+      "description": "Shows current authenticated user's profile information",
+      "examples": [
+        {
+          "name": "Emily's Profile",
+          "description": "Profile for Emily Johnson",
+          "data": {
+            "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
+          }
+        }
+      ],
+      "tags": ["auth", "profile", "user"]
+    },
+    {
+      "uri": "/products-grid",
+      "name": "Products Grid",
+      "description": "Displays a grid of products with filtering and pagination",
+      "examples": [
+        {
+          "name": "Beauty Products - Page 1",
+          "description": "First page of beauty products",
+          "data": {
+            "products": [
+              {
+                "id": "prod-1",
+                "name": "Essence Mascara Lash Princess",
+                "description": "The Essence Mascara Lash Princess is a popular mascara known for its volumizing and lengthening effects.",
+                "price": 9.99,
+                "category": "Beauty",
+                "stock": 99,
+                "image_url": "https://cdn.dummyjson.com/product-images/beauty/essence-mascara-lash-princess/thumbnail.webp"
+              },
+              {
+                "id": "prod-2",
+                "name": "Eyeshadow Palette with Mirror",
+                "description": "The Eyeshadow Palette offers a versatile range of eyeshadow shades for creating stunning eye looks.",
+                "price": 19.99,
+                "category": "Beauty",
+                "stock": 34,
+                "image_url": "https://cdn.dummyjson.com/product-images/beauty/eyeshadow-palette-with-mirror/thumbnail.webp"
+              },
+              {
+                "id": "prod-3",
+                "name": "Powder Canister",
+                "description": "The Powder Canister is a finely milled setting powder designed to set makeup and control shine.",
+                "price": 14.99,
+                "category": "Beauty",
+                "stock": 89,
+                "image_url": "https://cdn.dummyjson.com/product-images/beauty/powder-canister/thumbnail.webp"
+              },
+              {
+                "id": "prod-4",
+                "name": "Red Lipstick",
+                "description": "The Red Lipstick is a classic and bold choice for adding a pop of color to your lips.",
+                "price": 12.99,
+                "category": "Beauty",
+                "stock": 91,
+                "image_url": "https://cdn.dummyjson.com/product-images/beauty/red-lipstick/thumbnail.webp"
+              }
+            ],
+            "pagination": {
+              "page": 1,
+              "limit": 4,
+              "total": 5,
+              "totalPages": 2,
+              "hasMore": true
+            }
+          }
+        }
+      ],
+      "tags": ["products", "ecommerce", "shopping", "grid"]
+    },
+    {
+      "uri": "/product-card",
+      "name": "Product Card",
+      "description": "Displays detailed information for a single product",
+      "examples": [
+        {
+          "name": "Essence Mascara Details",
+          "description": "Details for Essence Mascara product",
+          "data": {
+            "product": {
+              "id": "prod-1",
+              "name": "Essence Mascara Lash Princess",
+              "description": "The Essence Mascara Lash Princess is a popular mascara known for its volumizing and lengthening effects.",
+              "price": 9.99,
+              "category": "Beauty",
+              "stock": 99,
+              "image_url": "https://cdn.dummyjson.com/product-images/beauty/essence-mascara-lash-princess/thumbnail.webp"
+            },
+            "availability": "In Stock",
+            "stockMessage": "Available"
+          }
+        }
+      ],
+      "tags": ["products", "details", "ecommerce"]
+    },
+    {
+      "uri": "/categories",
+      "name": "Product Categories",
+      "description": "Shows all available product categories with counts",
+      "examples": [
+        {
+          "name": "All Categories",
+          "description": "List of all product categories",
+          "data": {
+            "categories": [
+              { "name": "Beauty", "productCount": 5 },
+              { "name": "Fragrances", "productCount": 5 },
+              { "name": "Furniture", "productCount": 5 },
+              { "name": "Groceries", "productCount": 5 }
+            ]
+          }
+        }
+      ],
+      "tags": ["products", "categories", "navigation"]
+    },
+    {
+      "uri": "/add-to-cart",
+      "name": "Add to Cart Confirmation",
+      "description": "Confirms a product was added to the shopping cart",
+      "examples": [
+        {
+          "name": "Added Mascara",
+          "description": "Confirmation for adding 2 mascaras",
+          "data": {
+            "message": "Added to cart!",
+            "item": {
+              "id": "prod-1",
+              "name": "Essence Mascara Lash Princess",
+              "price": 9.99,
+              "quantity": 2,
+              "image_url": "https://cdn.dummyjson.com/product-images/beauty/essence-mascara-lash-princess/thumbnail.webp"
+            },
+            "cartItemCount": 2
+          }
+        }
+      ],
+      "tags": ["cart", "ecommerce", "confirmation"]
+    },
+    {
+      "uri": "/shopping-cart",
+      "name": "Shopping Cart",
+      "description": "Displays all items in the shopping cart with total",
+      "examples": [
+        {
+          "name": "Cart with 2 Items",
+          "description": "Shopping cart with mascara and eyeshadow",
+          "data": {
+            "items": [
+              {
+                "id": "cart-item-1",
+                "quantity": 2,
+                "product_id": "prod-1",
+                "name": "Essence Mascara Lash Princess",
+                "price": 9.99,
+                "image_url": "https://cdn.dummyjson.com/product-images/beauty/essence-mascara-lash-princess/thumbnail.webp"
+              },
+              {
+                "id": "cart-item-2",
+                "quantity": 1,
+                "product_id": "prod-2",
+                "name": "Eyeshadow Palette with Mirror",
+                "price": 19.99,
+                "image_url": "https://cdn.dummyjson.com/product-images/beauty/eyeshadow-palette-with-mirror/thumbnail.webp"
+              }
+            ],
+            "total": 39.97,
+            "itemCount": 2
+          }
+        }
+      ],
+      "tags": ["cart", "ecommerce", "shopping"]
+    },
+    {
+      "uri": "/cart-updated",
+      "name": "Cart Updated",
+      "description": "Confirms cart item quantity was updated",
+      "examples": [
+        {
+          "name": "Updated Quantity",
+          "description": "Updated mascara quantity to 3",
+          "data": {
+            "message": "Cart updated successfully",
+            "product": "Essence Mascara Lash Princess",
+            "quantity": 3
+          }
+        }
+      ],
+      "tags": ["cart", "update", "confirmation"]
+    },
+    {
+      "uri": "/cart-cleared",
+      "name": "Cart Cleared",
+      "description": "Confirms all items were removed from cart",
+      "examples": [
+        {
+          "name": "Cleared Cart",
+          "description": "Cart cleared with 2 items removed",
+          "data": {
+            "message": "Shopping cart cleared",
+            "itemsRemoved": 2
+          }
+        }
+      ],
+      "tags": ["cart", "clear", "confirmation"]
+    },
+    {
+      "uri": "/order-confirmation",
+      "name": "Order Confirmation",
+      "description": "Displays order confirmation with items and total",
+      "examples": [
+        {
+          "name": "Order Placed",
+          "description": "Confirmation for order with 2 items",
+          "data": {
+            "message": "Order created successfully!",
+            "order": {
+              "id": "order-12345",
+              "total": 39.97,
+              "status": "pending",
+              "estimated_delivery": "3-5 business days",
+              "payment_method": "credit_card",
+              "created_at": "2024-01-15T10:30:00Z",
+              "items": [
+                {
+                  "id": "prod-1",
+                  "product_id": "prod-1",
+                  "name": "Essence Mascara Lash Princess",
+                  "quantity": 2,
+                  "price": 9.99,
+                  "image_url": "https://cdn.dummyjson.com/product-images/beauty/essence-mascara-lash-princess/thumbnail.webp"
+                },
+                {
+                  "id": "prod-2",
+                  "product_id": "prod-2",
+                  "name": "Eyeshadow Palette with Mirror",
+                  "quantity": 1,
+                  "price": 19.99,
+                  "image_url": "https://cdn.dummyjson.com/product-images/beauty/eyeshadow-palette-with-mirror/thumbnail.webp"
+                }
+              ]
+            }
+          }
+        }
+      ],
+      "tags": ["orders", "checkout", "confirmation"]
+    },
+    {
+      "uri": "/order-history",
+      "name": "Order History",
+      "description": "Shows a list of all user orders",
+      "examples": [
+        {
+          "name": "Past Orders",
+          "description": "List of 2 orders",
+          "data": {
+            "orders": [
+              {
+                "id": "order-12345",
+                "total": 39.97,
+                "status": "pending",
+                "created_at": "2024-01-15T10:30:00Z",
+                "itemCount": 2
+              },
+              {
+                "id": "order-12344",
+                "total": 89.96,
+                "status": "delivered",
+                "created_at": "2024-01-10T14:20:00Z",
+                "itemCount": 3
+              }
+            ],
+            "totalOrders": 2,
+            "pagination": {
+              "page": 1,
+              "totalPages": 1,
+              "totalResults": 2
+            }
+          }
+        }
+      ],
+      "tags": ["orders", "history", "ecommerce"]
+    },
+    {
+      "uri": "/order-details",
+      "name": "Order Details",
+      "description": "Shows detailed information for a specific order",
+      "examples": [
+        {
+          "name": "Order #12345",
+          "description": "Details for order with 2 items",
+          "data": {
+            "order": {
+              "id": "order-12345",
+              "total": 39.97,
+              "status": "pending",
+              "payment_method": "credit_card",
+              "created_at": "2024-01-15T10:30:00Z",
+              "items": [
+                {
+                  "id": "prod-1",
+                  "product_id": "prod-1",
+                  "name": "Essence Mascara Lash Princess",
+                  "quantity": 2,
+                  "price": 9.99,
+                  "image_url": "https://cdn.dummyjson.com/product-images/beauty/essence-mascara-lash-princess/thumbnail.webp"
+                },
+                {
+                  "id": "prod-2",
+                  "product_id": "prod-2",
+                  "name": "Eyeshadow Palette with Mirror",
+                  "quantity": 1,
+                  "price": 19.99,
+                  "image_url": "https://cdn.dummyjson.com/product-images/beauty/eyeshadow-palette-with-mirror/thumbnail.webp"
+                }
+              ]
+            }
+          }
+        }
+      ],
+      "tags": ["orders", "details", "ecommerce"]
+    },
+    {
+      "uri": "/address-added",
+      "name": "Address Added",
+      "description": "Confirms a new shipping address was added",
+      "examples": [
+        {
+          "name": "New Address",
+          "description": "Confirmation for adding address",
+          "data": {
+            "message": "Address added successfully!",
+            "addressId": "addr-1",
+            "isDefault": true
+          }
+        }
+      ],
+      "tags": ["address", "shipping", "confirmation"]
+    },
+    {
+      "uri": "/address-list",
+      "name": "Address List",
+      "description": "Shows all saved shipping addresses",
+      "examples": [
+        {
+          "name": "All Addresses",
+          "description": "List of 2 saved addresses",
+          "data": {
+            "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
+              }
+            ]
+          }
+        }
+      ],
+      "tags": ["address", "shipping", "list"]
+    },
+    {
+      "uri": "/address-updated",
+      "name": "Address Updated",
+      "description": "Confirms an address was set as default",
+      "examples": [
+        {
+          "name": "Default Address Set",
+          "description": "Confirmation for setting default address",
+          "data": {
+            "message": "Default address updated!",
+            "address": {
+              "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": true
+            }
+          }
+        }
+      ],
+      "tags": ["address", "update", "confirmation"]
+    },
+    {
+      "uri": "/address-deleted",
+      "name": "Address Deleted",
+      "description": "Confirms an address was deleted",
+      "examples": [
+        {
+          "name": "Address Removed",
+          "description": "Confirmation for deleting address",
+          "data": {
+            "message": "Address deleted successfully!",
+            "addressId": "addr-2"
+          }
+        }
+      ],
+      "tags": ["address", "delete", "confirmation"]
+    }
+  ],
+  "generatedAt": "2025-01-24T00:00:00.000Z"
+}
+

package/templates/typescript-auth/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/widgets"],
+  "ts-node": {
+    "esm": true,
+    "experimentalSpecifierResolution": "node"
+  }
+}
+

package/templates/typescript-auth-api-key/.env

@@ -0,0 +1,15 @@
+# API Key Authentication - Test Keys
+# ⚠️ These are demo keys for testing only - DO NOT use in production!
+
+# Test API Keys
+API_KEY_1=sk_test_public_demo_key_12345
+API_KEY_2=sk_test_admin_demo_key_67890
+
+# You can add more keys by incrementing the number
+# API_KEY_3=your_custom_key_here
+# API_KEY_4=another_key_here
+
+# Note: Keys are loaded automatically by ApiKeyModule
+# The module reads all environment variables matching the pattern API_KEY_*
+
+

package/templates/typescript-auth-api-key/.env.example

@@ -0,0 +1,4 @@
+# Server Configuration
+NODE_ENV=development
+PORT=3000
+

package/templates/typescript-auth-api-key/src/app.module.ts

@@ -0,0 +1,38 @@
+import { McpApp, Module, ApiKeyModule } from 'nitrostack';
+import { DemoModule } from './modules/demo/demo.module.js';
+
+/**
+ * App Module - Root module for the API Key Auth MCP Server
+ * 
+ * This module demonstrates how to build an MCP server with API key authentication.
+ */
+@McpApp({
+  module: AppModule,
+  server: {
+    name: 'API Key Auth MCP Server',
+    version: '1.0.0',
+  },
+  logging: {
+    level: 'info',
+  },
+})
+@Module({
+  name: 'app',
+  description: 'Root application module with API key authentication',
+  imports: [
+    // Enable API key authentication
+    ApiKeyModule.forRoot({
+      keysEnvPrefix: 'API_KEY',  // Reads API_KEY_1, API_KEY_2, etc.
+      headerName: 'x-api-key',
+      metadataField: 'apiKey',
+      hashed: false,  // Set to true in production
+    }),
+    
+    // Feature modules
+    DemoModule,
+  ],
+  controllers: [],
+  providers: [],
+})
+export class AppModule {}
+

package/templates/typescript-auth-api-key/src/guards/apikey.guard.ts

@@ -0,0 +1,47 @@
+import { Guard, ExecutionContext, ApiKeyModule, ApiKeyMetadata } from 'nitrostack';
+
+/**
+ * API Key Guard
+ * 
+ * Validates API keys for tool access.
+ * Keys are extracted from context.metadata.apiKey or context.metadata['x-api-key']
+ * 
+ * Usage:
+ * ```typescript
+ * @Tool({
+ *   name: 'protected_tool',
+ *   description: 'A protected tool that requires API key'
+ * })
+ * @UseGuards(ApiKeyGuard)
+ * async protectedTool() {
+ *   // Only accessible with valid API key
+ * }
+ * ```
+ */
+export class ApiKeyGuard implements Guard {
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    // Extract API key from metadata (sent by Studio or client)
+    const apiKey = context.metadata?.apiKey || context.metadata?.['x-api-key'];
+    
+    if (!apiKey) {
+      throw new Error('API key required. Please set your API key in the Studio Auth tab (OAuth 2.1 page).');
+    }
+    
+    // Validate API key using ApiKeyModule
+    const isValid = await ApiKeyModule.validate(apiKey as string);
+    
+    if (!isValid) {
+      throw new Error('Invalid API key. Please check your API key in the Studio Auth tab.');
+    }
+    
+    // Populate context.auth with API key metadata
+    context.auth = {
+      subject: `apikey_${(apiKey as string).substring(0, 12)}`,
+      scopes: ['*'], // API keys typically have full access
+    };
+    
+    return true;
+  }
+}
+
+