nitrostack 1.0.0 → 1.0.2

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

@@ -0,0 +1,281 @@
+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';
+
+/**
+ * Orders Tools
+ * Handles order creation and management (requires authentication)
+ */
+export class OrdersTools {
+  /**
+   * Create order from cart - Requires authentication
+   */
+  @Tool({
+    name: 'create_order',
+    description: 'Create an order from the current shopping cart. Requires authentication and at least one item in cart.',
+    inputSchema: z.object({
+      payment_method: z.enum(['credit_card', 'paypal', 'apple_pay']).describe('Payment method'),
+      shipping_address_id: z.string().optional().describe('Address ID for shipping. Uses default if not provided.'),
+    }),
+    examples: {
+      request: {
+        payment_method: 'credit_card',
+        shipping_address_id: 'addr-1'
+      },
+      response: {
+        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'
+            }
+          ]
+        }
+      }
+    }
+  })
+  @Widget('order-confirmation')
+  @UseGuards(JWTGuard)
+  async createOrder(input: any, context: ExecutionContext) {
+    const db = getDatabase();
+    const userId = context.auth?.subject;
+    
+    // Get cart items
+    const cartItems: any[] = db.prepare(`
+      SELECT c.*, p.name, p.price, p.stock, p.image_url
+      FROM carts c
+      JOIN products p ON c.product_id = p.id
+      WHERE c.user_id = ?
+    `).all(userId);
+    
+    if (cartItems.length === 0) {
+      throw new Error('Cart is empty. Add items to cart before creating an order.');
+    }
+    
+    // Check stock availability
+    for (const item of cartItems) {
+      if (item.stock < item.quantity) {
+        throw new Error(`Insufficient stock for ${item.name}. Only ${item.stock} available.`);
+      }
+    }
+    
+    // Get shipping address
+    let addressId = input.shipping_address_id;
+    if (!addressId) {
+      const defaultAddress: any = db.prepare(`
+        SELECT id FROM addresses WHERE user_id = ? AND is_default = 1
+      `).get(userId);
+      
+      if (!defaultAddress) {
+        throw new Error('No shipping address found. Please add an address first.');
+      }
+      
+      addressId = defaultAddress.id;
+    }
+    
+    // Calculate total
+    const total = cartItems.reduce((sum, item) => sum + (item.price * item.quantity), 0);
+    
+    // Create order
+    const orderId = uuidv4();
+    const now = new Date().toISOString();
+    
+    db.prepare(`
+      INSERT INTO orders (id, user_id, total, status, payment_method, shipping_address_id, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(orderId, userId, total, 'pending', input.payment_method, addressId, now);
+    
+    // Create order items
+    for (const item of cartItems) {
+      const orderItemId = uuidv4();
+      db.prepare(`
+        INSERT INTO order_items (id, order_id, product_id, quantity, price)
+        VALUES (?, ?, ?, ?, ?)
+      `).run(orderItemId, orderId, item.product_id, item.quantity, item.price);
+      
+      // Update product stock
+      db.prepare(`
+        UPDATE products SET stock = stock - ? WHERE id = ?
+      `).run(item.quantity, item.product_id);
+    }
+    
+    // Clear cart
+    db.prepare(`
+      DELETE FROM carts WHERE user_id = ?
+    `).run(userId);
+    
+    context.logger.info(`Order created: ${orderId}, total=$${total.toFixed(2)}`);
+    
+    return {
+      message: 'Order created successfully!',
+      order: {
+        id: orderId,
+        total,
+        status: 'pending',
+        payment_method: input.payment_method,
+        created_at: now,
+        items: cartItems.map(item => ({
+          id: item.product_id,
+          name: item.name,
+          quantity: item.quantity,
+          price: item.price,
+          image_url: item.image_url,
+        })),
+      },
+    };
+  }
+
+  /**
+   * Get order history - Requires authentication
+   */
+  @Tool({
+    name: 'get_order_history',
+    description: 'Get the order history for the authenticated user. Requires authentication.',
+    inputSchema: z.object({}),
+    examples: {
+      request: {},
+      response: {
+        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
+        }
+      }
+    }
+  })
+  @Widget('order-history')
+  @UseGuards(JWTGuard)
+  async getOrderHistory(input: any, context: ExecutionContext) {
+    const db = getDatabase();
+    const userId = context.auth?.subject;
+    
+    const orders: any[] = db.prepare(`
+      SELECT o.*, COUNT(oi.id) as itemCount
+      FROM orders o
+      LEFT JOIN order_items oi ON o.id = oi.order_id
+      WHERE o.user_id = ?
+      GROUP BY o.id
+      ORDER BY o.created_at DESC
+    `).all(userId);
+    
+    context.logger.info(`Retrieved order history: ${orders.length} orders`);
+    
+    return {
+      orders,
+      totalOrders: orders.length,
+    };
+  }
+
+  /**
+   * Get order details - Requires authentication
+   */
+  @Tool({
+    name: 'get_order_details',
+    description: 'Get detailed information about a specific order. Requires authentication.',
+    examples: {
+      request: {
+        order_id: 'order-12345'
+      },
+      response: {
+        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'
+          }
+        ]
+      }
+    },
+    inputSchema: z.object({
+      order_id: z.string().describe('The ID of the order to retrieve'),
+    }),
+  })
+  @Widget('order-details')
+  @UseGuards(JWTGuard)
+  async getOrderDetails(input: any, context: ExecutionContext) {
+    const db = getDatabase();
+    const userId = context.auth?.subject;
+    
+    // Get order
+    const order: any = db.prepare(`
+      SELECT * FROM orders WHERE id = ? AND user_id = ?
+    `).get(input.order_id, userId);
+    
+    if (!order) {
+      throw new Error(`Order with ID ${input.order_id} not found or you don't have access to it.`);
+    }
+    
+    // Get order items
+    const items: any[] = db.prepare(`
+      SELECT oi.*, p.name, p.image_url
+      FROM order_items oi
+      JOIN products p ON oi.product_id = p.id
+      WHERE oi.order_id = ?
+    `).all(input.order_id);
+    
+    context.logger.info(`Retrieved order details: ${input.order_id}`);
+    
+    return {
+      order: {
+        ...order,
+        items,
+      },
+    };
+  }
+}
+

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

@@ -0,0 +1,16 @@
+import { Module } from 'nitrostack';
+import { ProductsTools } from './products.tools.js';
+import { ProductsResources } from './products.resources.js';
+import { ProductsPrompts } from './products.prompts.js';
+
+/**
+ * Products Module
+ * Provides product browsing, search, resources, and prompts
+ */
+@Module({
+  name: 'products',
+  description: 'Product browsing, search, and details',
+  controllers: [ProductsTools, ProductsResources, ProductsPrompts],
+})
+export class ProductsModule {}
+

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

@@ -0,0 +1,146 @@
+import { PromptDecorator as Prompt, ExecutionContext } from 'nitrostack';
+
+/**
+ * Products Prompts
+ * Provides helpful prompts for product browsing and shopping
+ */
+export class ProductsPrompts {
+  /**
+   * Product search help prompt
+   */
+  @Prompt({
+    name: 'product-search-help',
+    description: 'Get help with searching and browsing products',
+    arguments: [
+      {
+        name: 'looking_for',
+        description: 'What type of product you are looking for',
+        required: false,
+      },
+    ],
+  })
+  async productSearchHelp(args: Record<string, any>, context: ExecutionContext) {
+    const lookingFor = args.looking_for || 'general browsing';
+    
+    return [
+      {
+        role: 'user' as const,
+        content: `I want to find products. I'm looking for: ${lookingFor}`,
+      },
+      {
+        role: 'assistant' as const,
+        content: `I'll help you find what you're looking for! Here's how to browse products:
+
+**Available Tools:**
+1. \`browse_products\` - Browse all products with filters
+2. \`get_product_details\` - Get detailed info about a specific product
+3. \`get_categories\` - See all available categories
+
+**Browsing Products:**
+\`\`\`
+tool: browse_products
+parameters:
+  category: "All" | "Electronics" | "Clothing" | "Home" | "Books" | "Sports"
+  search: "optional search term"
+  page: 1
+  limit: 10
+\`\`\`
+
+**Filter by Category:**
+- Electronics - Gadgets, devices, tech
+- Clothing - Apparel and fashion
+- Home - Furniture and home goods
+- Books - Reading materials
+- Sports - Athletic equipment
+
+**Search by Name:**
+Add a \`search\` parameter to find specific products:
+\`\`\`
+browse_products({ search: "laptop", category: "Electronics" })
+\`\`\`
+
+**Pagination:**
+- \`page\`: Page number (starts at 1)
+- \`limit\`: Items per page (1-50, default 10)
+
+**Get Product Details:**
+Once you find a product, use its ID to get full details:
+\`\`\`
+get_product_details({ product_id: "abc-123" })
+\`\`\`
+
+**Tips:**
+${lookingFor.toLowerCase().includes('electronic') ? '- Check the Electronics category\n- Look for items with high stock\n- Compare prices across products' : ''}
+${lookingFor.toLowerCase().includes('cloth') ? '- Browse the Clothing category\n- Check size availability in stock\n- Look for seasonal items' : ''}
+- Use search to narrow down results
+- Check stock levels before adding to cart
+- View full details for complete specifications`,
+      },
+    ];
+  }
+
+  /**
+   * Shopping recommendations prompt
+   */
+  @Prompt({
+    name: 'shopping-recommendations',
+    description: 'Get personalized shopping recommendations and tips',
+  })
+  async shoppingRecommendations(args: Record<string, any>, context: ExecutionContext) {
+    return [
+      {
+        role: 'user' as const,
+        content: 'Give me shopping tips and recommendations for this e-commerce store',
+      },
+      {
+        role: 'assistant' as const,
+        content: `**Shopping Tips & Recommendations**
+
+**Best Practices:**
+1. **Check Stock First**
+   - Use \`browse_products\` to see available items
+   - Look for "stock" field in product details
+   - Low stock items go fast!
+
+2. **Compare Products**
+   - Browse by category to see options
+   - Check prices across similar items
+   - Read full descriptions with \`get_product_details\`
+
+3. **Smart Shopping Flow**
+   \`\`\`
+   Step 1: Browse → browse_products
+   Step 2: View Details → get_product_details
+   Step 3: Add to Cart → add_to_cart (requires login)
+   Step 4: Review Cart → view_cart
+   Step 5: Place Order → create_order
+   \`\`\`
+
+**Categories Overview:**
+📱 **Electronics** - Latest gadgets and tech
+👕 **Clothing** - Fashion and apparel
+🏠 **Home** - Furniture and decor
+📚 **Books** - Reading materials
+⚽ **Sports** - Athletic gear
+
+**Money-Saving Tips:**
+- Check all categories for deals
+- Look for bundle opportunities
+- Review cart before checkout
+- Items in high stock are usually popular
+
+**Before You Buy:**
+✓ Verify stock availability
+✓ Review product description
+✓ Check your cart total
+✓ Ensure shipping address is set
+
+**Need Help?**
+- Authentication issues? Use \`auth-help\` prompt
+- Cart problems? Use \`cart-management-help\` prompt
+- Order questions? Use \`order-help\` prompt`,
+      },
+    ];
+  }
+}
+

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

@@ -0,0 +1,98 @@
+import { ResourceDecorator as Resource, ExecutionContext } from 'nitrostack';
+import { getDatabase } from '../../db/database.js';
+
+/**
+ * Products Resources
+ * Provides product-related resource endpoints
+ */
+export class ProductsResources {
+  /**
+   * Product schema resource
+   */
+  @Resource({
+    uri: 'products://schema/product',
+    name: 'Product Schema',
+    description: 'Schema definition for product objects',
+    mimeType: 'application/json',
+  })
+  async getProductSchema(context: ExecutionContext) {
+    return {
+      type: 'json' as const,
+      data: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', format: 'uuid', description: 'Unique product identifier' },
+          name: { type: 'string', description: 'Product name' },
+          description: { type: 'string', description: 'Product description' },
+          price: { type: 'number', minimum: 0, description: 'Price in USD' },
+          category: { type: 'string', enum: ['Electronics', 'Clothing', 'Home', 'Books', 'Sports'], description: 'Product category' },
+          stock: { type: 'integer', minimum: 0, description: 'Available stock quantity' },
+          image_url: { type: 'string', format: 'uri', nullable: true, description: 'Product image URL' },
+          created_at: { type: 'string', format: 'date-time', description: 'Product creation timestamp' },
+        },
+        required: ['id', 'name', 'description', 'price', 'category', 'stock'],
+      },
+    };
+  }
+
+  /**
+   * Product categories resource
+   */
+  @Resource({
+    uri: 'products://categories',
+    name: 'Product Categories',
+    description: 'List of all available product categories',
+    mimeType: 'application/json',
+  })
+  async getCategories(context: ExecutionContext) {
+    const db = getDatabase();
+    
+    const categories: any[] = db.prepare(`
+      SELECT DISTINCT category, COUNT(*) as count
+      FROM products
+      GROUP BY category
+      ORDER BY category
+    `).all();
+    
+    return {
+      type: 'json' as const,
+      data: {
+        categories: categories.map(c => ({
+          name: c.category,
+          productCount: c.count,
+        })),
+        total: categories.length,
+      },
+    };
+  }
+
+  /**
+   * Product statistics resource
+   */
+  @Resource({
+    uri: 'products://stats',
+    name: 'Product Statistics',
+    description: 'Overall product catalog statistics',
+    mimeType: 'application/json',
+  })
+  async getProductStats(context: ExecutionContext) {
+    const db = getDatabase();
+    
+    const totalProducts: any = db.prepare('SELECT COUNT(*) as count FROM products').get();
+    const totalValue: any = db.prepare('SELECT SUM(price * stock) as value FROM products').get();
+    const outOfStock: any = db.prepare('SELECT COUNT(*) as count FROM products WHERE stock = 0').get();
+    const lowStock: any = db.prepare('SELECT COUNT(*) as count FROM products WHERE stock > 0 AND stock <= 5').get();
+    
+    return {
+      type: 'json' as const,
+      data: {
+        totalProducts: totalProducts.count,
+        totalInventoryValue: totalValue.value || 0,
+        outOfStock: outOfStock.count,
+        lowStock: lowStock.count,
+        categories: 5,
+      },
+    };
+  }
+}
+