nitrostack 1.0.0 → 1.0.1

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

package/templates/typescript-auth/src/modules/cart/cart.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';
+
+/**
+ * Cart Tools
+ * Handles shopping cart operations (requires authentication)
+ */
+export class CartTools {
+  /**
+   * Add product to cart - Requires authentication
+   */
+  @Tool({
+    name: 'add_to_cart',
+    description: 'Add a product to the shopping cart. Requires authentication.',
+    inputSchema: z.object({
+      product_id: z.string().describe('The ID of the product to add'),
+      quantity: z.number().min(1).default(1).describe('Quantity to add'),
+    }),
+    examples: {
+      request: {
+        product_id: 'prod-1',
+        quantity: 2
+      },
+      response: {
+        message: 'Added to cart!',
+        product_id: 'prod-1',
+        product_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
+      }
+    }
+  })
+  @Widget('add-to-cart')
+  @UseGuards(JWTGuard)
+  async addToCart(input: any, context: ExecutionContext) {
+    const db = getDatabase();
+    const userId = context.auth?.subject;
+    
+    // Check if product exists and has stock
+    const product: any = db.prepare('SELECT * FROM products WHERE id = ?').get(input.product_id);
+    
+    if (!product) {
+      throw new Error(`Product with ID ${input.product_id} not found`);
+    }
+    
+    if (product.stock < (input.quantity || 1)) {
+      throw new Error(`Insufficient stock. Only ${product.stock} units available.`);
+    }
+    
+    // Check if item already in cart
+    const existing: any = db.prepare(`
+      SELECT * FROM carts WHERE user_id = ? AND product_id = ?
+    `).get(userId, input.product_id);
+    
+    if (existing) {
+      // Update quantity
+      const newQuantity = existing.quantity + input.quantity;
+      
+      if (product.stock < newQuantity) {
+        throw new Error(`Cannot add ${input.quantity} more units. Only ${product.stock - existing.quantity} additional units available.`);
+      }
+      
+      db.prepare(`
+        UPDATE carts SET quantity = ? WHERE id = ?
+      `).run(newQuantity, existing.id);
+      
+      context.logger.info(`Updated cart: product=${product.name}, quantity=${newQuantity}`);
+      
+      // Get total cart count
+      const cartCount: any = db.prepare(`
+        SELECT SUM(quantity) as total FROM carts WHERE user_id = ?
+      `).get(userId);
+      
+      return {
+        message: `Added to cart!`,
+        item: {
+          id: input.product_id,
+          name: product.name,
+          price: product.price,
+          quantity: input.quantity,
+          image_url: product.image_url,
+        },
+        cartItemCount: cartCount.total || 0,
+      };
+    } else {
+      // Add new item
+      const cartId = uuidv4();
+      
+      db.prepare(`
+        INSERT INTO carts (id, user_id, product_id, quantity)
+        VALUES (?, ?, ?, ?)
+      `).run(cartId, userId, input.product_id, input.quantity);
+      
+      context.logger.info(`Added to cart: product=${product.name}, quantity=${input.quantity}`);
+      
+      // Get total cart count
+      const cartCount: any = db.prepare(`
+        SELECT SUM(quantity) as total FROM carts WHERE user_id = ?
+      `).get(userId);
+      
+      return {
+        message: `Added to cart!`,
+        item: {
+          id: input.product_id,
+          name: product.name,
+          price: product.price,
+          quantity: input.quantity,
+          image_url: product.image_url,
+        },
+        cartItemCount: cartCount.total || 0,
+      };
+    }
+  }
+
+  /**
+   * View shopping cart - Requires authentication
+   */
+  @Tool({
+    name: 'view_cart',
+    description: 'View the current shopping cart with all items and total price. Requires authentication.',
+    inputSchema: z.object({}),
+    examples: {
+      request: {},
+      response: {
+        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
+      }
+    }
+  })
+  @Widget('shopping-cart')
+  @UseGuards(JWTGuard)
+  async viewCart(input: any, context: ExecutionContext) {
+    const db = getDatabase();
+    const userId = context.auth?.subject;
+    
+    const items: any[] = db.prepare(`
+      SELECT c.id, c.quantity, p.id as product_id, p.name, p.price, p.image_url
+      FROM carts c
+      JOIN products p ON c.product_id = p.id
+      WHERE c.user_id = ?
+    `).all(userId);
+    
+    const total = items.reduce((sum, item) => sum + (item.price * item.quantity), 0);
+    
+    context.logger.info(`Viewed cart: ${items.length} items, total=$${total.toFixed(2)}`);
+    
+    return {
+      items,
+      total,
+      itemCount: items.length,
+    };
+  }
+
+  /**
+   * Update cart item quantity - Requires authentication
+   */
+  @Tool({
+    name: 'update_cart_item',
+    description: 'Update the quantity of a product in the cart. Set to 0 to remove. Requires authentication.',
+    inputSchema: z.object({
+      product_id: z.string().describe('The ID of the product to update'),
+      quantity: z.number().min(0).describe('New quantity (0 to remove)'),
+    }),
+    examples: {
+      request: {
+        product_id: 'prod-1',
+        quantity: 3
+      },
+      response: {
+        message: 'Cart updated successfully',
+        product: 'Essence Mascara Lash Princess',
+        quantity: 3
+      }
+    }
+  })
+  @Widget('cart-updated')
+  @UseGuards(JWTGuard)
+  async updateCartItem(input: any, context: ExecutionContext) {
+    const db = getDatabase();
+    const userId = context.auth?.subject;
+    
+    if (input.quantity === 0) {
+      // Remove item
+      db.prepare(`
+        DELETE FROM carts WHERE user_id = ? AND product_id = ?
+      `).run(userId, input.product_id);
+      
+      context.logger.info(`Removed from cart: product_id=${input.product_id}`);
+      
+      return {
+        message: 'Item removed from cart',
+        product: input.product_id,
+      };
+    } else {
+      // Check stock
+      const product: any = db.prepare('SELECT * FROM products WHERE id = ?').get(input.product_id);
+      
+      if (!product) {
+        throw new Error(`Product with ID ${input.product_id} not found`);
+      }
+      
+      if (product.stock < input.quantity) {
+        throw new Error(`Insufficient stock. Only ${product.stock} units available.`);
+      }
+      
+      // Update quantity
+      db.prepare(`
+        UPDATE carts SET quantity = ? WHERE user_id = ? AND product_id = ?
+      `).run(input.quantity, userId, input.product_id);
+      
+      context.logger.info(`Updated cart item: product=${product.name}, quantity=${input.quantity}`);
+      
+      return {
+        message: 'Cart updated successfully',
+        product: product.name,
+        quantity: input.quantity,
+      };
+    }
+  }
+
+  /**
+   * Clear shopping cart - Requires authentication
+   */
+  @Tool({
+    name: 'clear_cart',
+    description: 'Remove all items from the shopping cart. Requires authentication.',
+    inputSchema: z.object({}),
+    examples: {
+      request: {},
+      response: {
+        message: 'Shopping cart cleared',
+        itemsRemoved: 2
+      }
+    }
+  })
+  @Widget('cart-cleared')
+  @UseGuards(JWTGuard)
+  async clearCart(input: any, context: ExecutionContext) {
+    const db = getDatabase();
+    const userId = context.auth?.subject;
+    
+    // Get count before clearing
+    const count: any = db.prepare(`
+      SELECT COUNT(*) as count FROM carts WHERE user_id = ?
+    `).get(userId);
+    
+    db.prepare(`
+      DELETE FROM carts WHERE user_id = ?
+    `).run(userId);
+    
+    context.logger.info(`Cleared cart: removed ${count.count} items`);
+    
+    return {
+      message: 'Shopping cart cleared',
+      itemsRemoved: count.count,
+    };
+  }
+}
+

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

@@ -0,0 +1,16 @@
+import { Module } from 'nitrostack';
+import { OrdersTools } from './orders.tools.js';
+import { OrdersResources } from './orders.resources.js';
+import { OrdersPrompts } from './orders.prompts.js';
+
+/**
+ * Orders Module
+ * Provides order creation, history, resources, and prompts
+ */
+@Module({
+  name: 'orders',
+  description: 'Order creation and management',
+  controllers: [OrdersTools, OrdersResources, OrdersPrompts],
+})
+export class OrdersModule {}
+

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

@@ -0,0 +1,88 @@
+import { PromptDecorator as Prompt, ExecutionContext } from 'nitrostack';
+
+/**
+ * Orders Prompts
+ * Provides helpful prompts for order management
+ */
+export class OrdersPrompts {
+  /**
+   * Order help prompt
+   */
+  @Prompt({
+    name: 'order-help',
+    description: 'Get help with placing and managing orders',
+  })
+  async orderHelp(args: Record<string, any>, context: ExecutionContext) {
+    return [
+      {
+        role: 'user' as const,
+        content: 'I need help with orders',
+      },
+      {
+        role: 'assistant' as const,
+        content: `**Order Management Guide**
+
+**Available Tools (Requires Authentication):**
+1. \`create_order\` - Place order from cart
+2. \`get_order_history\` - View all your orders
+3. \`get_order_details\` - View specific order details
+
+**Creating an Order:**
+\`\`\`
+create_order({
+  payment_method: "credit_card" | "paypal" | "apple_pay",
+  shipping_address_id: "optional-address-id"
+})
+\`\`\`
+
+**Prerequisites:**
+✓ Must be logged in
+✓ Must have items in cart
+✓ Must have a shipping address (or set default)
+
+**Order Process:**
+1. **Add items to cart** → \`add_to_cart\`
+2. **Review cart** → \`view_cart\`
+3. **Set shipping address** → \`add_address\` or use default
+4. **Place order** → \`create_order\`
+5. **Get confirmation** → Order ID returned
+
+**Payment Methods:**
+- \`credit_card\` - Credit/Debit card
+- \`paypal\` - PayPal account
+- \`apple_pay\` - Apple Pay
+
+**After Order Created:**
+- Cart is automatically cleared
+- Product stock is updated
+- Order appears in history
+- Status starts as "pending"
+
+**Viewing Orders:**
+\`\`\`
+get_order_history({})  // All your orders
+get_order_details({ order_id: "order-uuid" })  // Specific order
+\`\`\`
+
+**Order Statuses:**
+- 🟡 **pending** - Order placed, awaiting processing
+- 🔵 **processing** - Being prepared
+- 📦 **shipped** - In transit
+- ✅ **delivered** - Completed
+- ❌ **cancelled** - Cancelled
+
+**Common Issues:**
+❌ "Cart is empty" → Add items first
+❌ "No shipping address" → Add address with \`add_address\`
+❌ "Insufficient stock" → Product sold out, update cart
+
+**Tips:**
+- Review cart before ordering
+- Ensure correct shipping address
+- Keep order ID for tracking
+- Check order history anytime`,
+      },
+    ];
+  }
+}
+

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

@@ -0,0 +1,48 @@
+import { ResourceDecorator as Resource, ExecutionContext } from 'nitrostack';
+
+/**
+ * Orders Resources
+ * Provides order-related resource endpoints
+ */
+export class OrdersResources {
+  /**
+   * Order schema resource
+   */
+  @Resource({
+    uri: 'orders://schema',
+    name: 'Order Schema',
+    description: 'Schema definition for order objects',
+    mimeType: 'application/json',
+  })
+  async getOrderSchema(context: ExecutionContext) {
+    return {
+      type: 'json' as const,
+      data: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', format: 'uuid', description: 'Order ID' },
+          user_id: { type: 'string', description: 'User ID' },
+          total: { type: 'number', minimum: 0, description: 'Order total' },
+          status: { type: 'string', enum: ['pending', 'processing', 'shipped', 'delivered', 'cancelled'], description: 'Order status' },
+          payment_method: { type: 'string', enum: ['credit_card', 'paypal', 'apple_pay'], description: 'Payment method' },
+          shipping_address_id: { type: 'string', description: 'Shipping address ID' },
+          created_at: { type: 'string', format: 'date-time', description: 'Order creation time' },
+          items: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                id: { type: 'string', description: 'Order item ID' },
+                product_id: { type: 'string', description: 'Product ID' },
+                name: { type: 'string', description: 'Product name' },
+                quantity: { type: 'integer', minimum: 1, description: 'Quantity ordered' },
+                price: { type: 'number', description: 'Price at time of order' },
+              },
+            },
+          },
+        },
+      },
+    };
+  }
+}
+