nitrostack 1.0.74 → 1.0.76

package/templates/typescript-oauth/README.md

@@ -1,18 +1,30 @@
-# NitroStack Starter Template
-
-**The simple starter template** - Learn NitroStack v3.0 fundamentals with a clean calculator example.
-
-## 🎯 What's Inside
-
-This template demonstrates core NitroStack v3.0 features:
-
-- **One Module** - Calculator module with all features
-- **One Tool** - `calculate` - Perform arithmetic operations
-- **One Resource** - `calculator://operations` - List of operations
-- **One Prompt** - `calculator_help` - Get usage help
-- **Two Widgets** - Beautiful UI for results and operations list
-- **No Authentication** - Focus on learning the basics
-- **No Database** - Pure computation example
+# ✈️ NitroStack Flight Booking
+
+A production-ready NitroStack template showcasing real-time flight search and booking with **Duffel API** integration. Search flights, view details, select seats, and book - all through beautiful interactive widgets.
+
+## ✨ Features
+
+### 🔌 **Duffel API Integration**
+- Real-time flight search across 300+ airlines
+- Live pricing and availability
+- Seat selection with cabin maps
+- Booking and order management
+
+### 🎨 **Interactive Widgets**
+- **Airport Search** - Autocomplete airport selection
+- **Flight Search Results** - Compare flights with prices
+- **Flight Details** - Comprehensive flight information
+- **Seat Selection** - Visual cabin map with seat picker
+- **Order Summary** - Complete booking overview
+- **Payment Confirmation** - Secure payment flow
+
+### 🛠️ **MCP Tools**
+- `search_airports` - Find airports by name/code
+- `search_flights` - Search available flights
+- `show_flight_details` - Detailed flight information
+- `select_seats` - Interactive seat selection
+- `create_booking` - Book flights
+- `get_order` - Retrieve booking details
 
 ## 🚀 Quick Start
 
@@ -26,289 +38,226 @@ npm install -g nitrostack
 npx nitrostack --version
 ```
 
-### Setup Your Project
+### 1. Create Your Project
 
 ```bash
-nitrostack init my-calculator --template typescript-starter
-cd my-calculator
-```
+# Create a new project
+nitrostack init my-flight-app --template typescript-oauth
+cd my-flight-app
 
-That's it! The CLI automatically:
-- ✅ Installs all dependencies  
-- ✅ Installs widget dependencies
-- ✅ Builds the widgets
-- ✅ Sets up the project structure
+# Install all dependencies (root + widgets)
+nitrostack install
+```
 
-### Run the Project
+### 2. Get Your Duffel API Key (Free)
 
-```bash
-npm run dev
-```
+[Duffel](https://duffel.com/) provides a free API for flight search and booking:
 
-This starts:
-- **MCP Server** (dual transport: STDIO + HTTP on port 3002) - Hot reloads on code changes
-- **Studio** on http://localhost:3000 - Visual testing environment
-- **Widget Dev Server** on http://localhost:3001 - Hot module replacement
+1. **Sign up** at [duffel.com](https://duffel.com/) (click "Start now" - it's free!)
+2. Create a free account (no credit card required)
+3. Go to your **Dashboard** → **Developers** → **Access tokens**
+4. Click **"Create token"** to generate your API key
+5. Copy the token (starts with `duffel_test_` for sandbox)
 
-> 💡 **Dual Transport**: Your server exposes tools via both STDIO (for direct connections) and HTTP (for remote access on port 3002). Switch between transports in Studio → Settings.
+> 💡 **Tip**: The test mode (`duffel_test_*` tokens) gives you access to realistic mock data for development. Production tokens (`duffel_live_*`) connect to real airlines.
 
-The `nitrostack dev` command handles everything automatically:
-- ✅ Auto-detects widget directory
-- ✅ Installs dependencies (if needed)
-- ✅ Builds widgets (on first run)
-- ✅ Starts all services concurrently
-- ✅ Hot reload for TypeScript and widgets
+### 3. Configure Environment
 
-## 📁 Project Structure
+Copy the example environment file and add your Duffel API key:
 
-```
-src/
-├── modules/
-│   └── calculator/
-│       ├── calculator.module.ts       # @Module definition
-│       ├── calculator.tools.ts        # @Tool with examples
-│       ├── calculator.resources.ts    # @Resource
-│       └── calculator.prompts.ts      # @Prompt
-├── widgets/                           # Next.js UI widgets
-│   └── app/
-│       ├── calculator-result/         # Tool result widget
-│       └── calculator-operations/     # Resource widget
-├── app.module.ts                      # Root @McpApp module
-└── index.ts                           # Application bootstrap
+```bash
+cp .env.example .env
 ```
 
-## 🛠️ Available Features
+Edit `.env` and update:
 
-### Health Check: `system`
+```env
+# Duffel API Configuration
+DUFFEL_API_KEY=duffel_test_your_api_key_here
+```
 
-Monitors server health and resources:
+### 4. Run Development Server
 
-- **Uptime**: Server running time
-- **Memory Usage**: Heap memory consumption
-- **Process Info**: PID and Node.js version
-- **Status**: `up`, `degraded`, or `down`
+```bash
+npm run dev
+```
 
-Check health status in Studio's Health Checks tab!
+This starts:
+- **MCP Server** - Hot reloads on code changes
+- **Studio** on http://localhost:3000 - Visual testing environment  
+- **Widget Dev Server** on http://localhost:3001 - Hot module replacement
 
-### Tool: `calculate`
+### 5. Test in Studio
 
-Perform basic arithmetic operations:
+Try these prompts in Studio chat:
+- "Search flights from London to New York for next week"
+- "Show me flight details"
+- "I want to select seats"
+- "Show me flights from JFK to LAX"
 
-```typescript
-@Tool({
-  name: 'calculate',
-  description: 'Perform basic arithmetic calculations',
-  inputSchema: z.object({
-    operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
-    a: z.number(),
-    b: z.number()
-  }),
-  examples: {
-    request: { operation: 'add', a: 5, b: 3 },
-    response: { result: 8, expression: '5 + 3 = 8' }
-  }
-})
-```
+## 📁 Project Structure
 
-**Usage:**
 ```
-User: "Calculate 5 + 3"
-AI: [Calls calculate tool]
-Result: Beautiful widget showing "5 + 3 = 8"
+typescript-oauth/
+├── src/
+│   ├── index.ts                 # Main server entry
+│   ├── app.module.ts            # App module
+│   ├── services/
+│   │   └── duffel.service.ts    # Duffel API client
+│   └── modules/
+│       └── flights/
+│           ├── flights.module.ts    # Module definition
+│           ├── flights.tools.ts     # Search & display tools
+│           ├── flights.prompts.ts   # AI prompts
+│           ├── flights.resources.ts # Static resources
+│           └── booking.tools.ts     # Booking tools
+│   └── widgets/
+│       ├── app/
+│       │   ├── airport-search/      # Airport autocomplete
+│       │   ├── flight-search-results/ # Results list
+│       │   ├── flight-details/      # Flight info
+│       │   ├── seat-selection/      # Seat picker
+│       │   ├── order-summary/       # Booking summary
+│       │   └── payment-confirmation/ # Payment widget
+├── .env.example                 # Environment template
+├── OAUTH_SETUP.md              # OAuth configuration guide
+├── package.json
+└── README.md
 ```
 
-### Resource: `calculator://operations`
-
-Lists all available operations with examples.
-
-### Prompt: `calculator_help`
-
-Get help on how to use the calculator.
-
-## 🎨 Widgets
-
-### Calculator Result Widget
-- Gradient background
-- Operation icon
-- Breakdown of numbers
-- Beautiful animations
-
-### Calculator Operations Widget
-- Grid of all operations
-- Color-coded by type
-- Examples for each operation
-
-## 💡 Learning Path
-
-This template is perfect for learning:
-
-1. **Module Organization** - How to structure a feature module
-2. **Tools** - How to create a tool with `@Tool` decorator
-3. **Resources** - How to expose data with `@Resource`
-4. **Prompts** - How to create conversation templates
-5. **Widgets** - How to build UI components
-6. **Examples** - How to include request/response examples
-7. **Validation** - How to use Zod schemas
-
 ## 🔧 Commands
 
 ```bash
+# Installation
+npm install              # Install all dependencies (root + widgets)
+nitrostack install       # Same as above
+
 # Development
-npm run dev              # Start dev server with Studio (auto-builds everything)
+npm run dev              # Start dev server with Studio
 npm run build            # Build TypeScript and widgets for production
 npm start                # Run production server
 
+# Upgrade
+npm run upgrade          # Upgrade nitrostack to latest version
+
 # Widget Management
 npm run widget <command> # Run npm command in widgets directory
-npm run widget add <pkg> # Add a widget dependency (e.g., @mui/material)
+npm run widget add <pkg> # Add a widget dependency
 ```
 
-**Note:** The NitroStack CLI automatically handles building, installing dependencies, and hot reload. You don't need separate commands for widgets anymore!
+## 🔐 OAuth Setup (Optional)
 
-## 📝 Example Interactions
+This template includes OAuth 2.1 authentication support. If you want to protect your MCP server with authentication:
 
-### Basic Calculation
-```
-User: "What's 12 times 8?"
-AI: Calls calculate(operation="multiply", a=12, b=8)
-Result: Widget showing "12 × 8 = 96"
-```
+1. Read the detailed guide: **[OAUTH_SETUP.md](./OAUTH_SETUP.md)**
+2. Configure Auth0 (or your OAuth provider)
+3. Update your `.env` with OAuth credentials
 
-### Get Help
-```
-User: "How do I use the calculator?"
-AI: Uses calculator_help prompt
-Result: Complete usage instructions
-```
+> **Note**: OAuth is optional for local development. The template works without it using Duffel's test API.
 
-### List Operations
-```
-User: "What operations are available?"
-AI: Fetches calculator://operations resource
-Result: Widget showing all 4 operations with examples
-```
+## 📊 Duffel API Features
 
-## 🎓 Code Walkthrough
-
-### 1. Tool Definition
-
-```typescript
-@Tool({
-  name: 'calculate',
-  description: 'Perform basic arithmetic calculations',
-  inputSchema: z.object({...}),
-  examples: {...}
-})
-@Widget('calculator-result')  // Link UI widget
-async calculate(input: any, ctx: ExecutionContext) {
-  // Your logic here
-  return { result, expression };
-}
-```
+### Test Mode vs Live Mode
 
-**Key Points:**
-- `@Tool` decorator defines the tool
-- `inputSchema` validates input with Zod
-- `examples` help AI understand usage
-- `@Widget` links the UI component
-- `ExecutionContext` provides logger, metadata
-
-### 2. Resource Definition
-
-```typescript
-@Resource({
-  uri: 'calculator://operations',
-  name: 'Calculator Operations',
-  mimeType: 'application/json',
-  examples: {...}
-})
-@Widget('calculator-operations')
-async getOperations(uri: string, ctx: ExecutionContext) {
-  return { contents: [{...}] };
-}
-```
+| Feature | Test Mode (`duffel_test_*`) | Live Mode (`duffel_live_*`) |
+|---------|----------------------------|----------------------------|
+| API Access | ✅ Full access | ✅ Full access |
+| Pricing | Mock data | Real prices |
+| Bookings | Simulated | Real bookings |
+| Credit Card | Not charged | Charged |
+| Rate Limits | Generous | Production limits |
 
-### 3. Prompt Definition
+### Supported Airlines
 
-```typescript
-@Prompt({
-  name: 'calculator_help',
-  arguments: [...]
-})
-async getHelp(args: any, ctx: ExecutionContext) {
-  return { messages: [...] };
-}
-```
+Duffel provides access to 300+ airlines including:
+- Major carriers (British Airways, Lufthansa, Emirates, etc.)
+- Low-cost carriers (Ryanair, EasyJet, Spirit, etc.)
+- Regional airlines
 
-### 4. Module Definition
+### API Capabilities
 
-```typescript
-@Module({
-  name: 'calculator',
-  controllers: [CalculatorTools, CalculatorResources, CalculatorPrompts]
-})
-export class CalculatorModule {}
-```
+- **Search**: Real-time availability and pricing
+- **Ancillaries**: Seats, bags, meals
+- **Booking**: Create and manage orders
+- **Changes**: Modify existing bookings
+- **Cancellations**: Cancel and refund
 
-### 5. Root Module
+## 🎨 Widget Features
 
-```typescript
-@McpApp({
-  server: { name: 'calculator-server', version: '1.0.0' }
-})
-@Module({
-  imports: [ConfigModule.forRoot(), CalculatorModule]
-})
-export class AppModule {}
-```
+### Airport Search Widget
+- Autocomplete with IATA codes
+- City and airport name search
+- Recent searches
 
-## 🚀 Extend This Template
+### Flight Search Results Widget
+- Compare multiple flights
+- Filter by stops, price, time
+- Sort options
+- Airline logos
 
-### Add More Operations
+### Flight Details Widget
+- Complete itinerary
+- Fare breakdown
+- Baggage allowance
+- Flight duration and stops
 
-Edit `calculator.tools.ts` and add new operations to the enum and switch statement.
+### Seat Selection Widget
+- Visual cabin map
+- Seat categories (standard, extra legroom, etc.)
+- Price per seat
+- Real-time availability
 
-### Add History Feature
+## 🛠️ Customization
 
-1. Create a service to store calculations
-2. Add a `get_history` tool
-3. Create a history widget
+### Adding New Airlines
 
-### Add More Modules
+Duffel handles airline integrations automatically. You don't need to configure individual airlines.
 
-```bash
-nitrostack generate module converter
-```
+### Modifying Search Parameters
 
-## 📚 Next Steps
+Edit `src/modules/flights/flights.tools.ts` to customize:
+- Default passenger counts
+- Cabin class options
+- Date ranges
+- Result limits
 
-Once you understand this template:
+### Styling Widgets
 
-1. Try the [E-commerce Template](/templates/ecommerce) - Advanced features with auth
-2. Read [Server Concepts](/sdk/typescript/server) - Deep dive into modules
-3. Read [Tools Guide](/sdk/typescript/tools) - Advanced tool patterns
-4. Read [Widgets Guide](/sdk/typescript/ui/widgets) - Build better UIs
+Each widget in `src/widgets/app/` can be customized:
+- Edit page.tsx for layout
+- Add custom CSS
+- Modify component styles
+
+## 📚 Resources
+
+### Duffel Documentation
+- [Duffel API Docs](https://duffel.com/docs/api)
+- [Duffel SDK (Node.js)](https://github.com/duffel/duffel-api-javascript)
+- [Duffel Postman Collection](https://duffel.com/docs/postman)
+
+### NitroStack Documentation
+- [NitroStack Docs](https://nitrostack.ai/docs)
+- [Widget Development Guide](https://nitrostack.ai/docs/widgets)
 
 ## 💡 Tips
 
-- **Keep it Simple** - This template shows the minimum needed
-- **Study the Code** - Each file has clear examples
-- **Test in Studio** - Use the chat to test your tools
-- **Check Examples** - The `examples` field helps AI understand your tools
+- **Use Test Mode**: Start with `duffel_test_*` tokens for development
+- **Check Rate Limits**: Duffel has rate limits - cache searches when possible
+- **Error Handling**: The template includes comprehensive error handling
+- **Responsive Design**: Widgets are mobile-friendly out of the box
 
-## 🎉 What to Build
+## 📚 Next Steps
 
-Use this as a starting point for:
+- Try the **Starter Template** - Learn NitroStack basics
+- Try the **Pizza Shop Template** - Interactive maps with Mapbox
+- Read the [Duffel Getting Started Guide](https://duffel.com/docs/guides/getting-started)
 
-- **Unit Converters** - Temperature, currency, etc.
-- **Text Tools** - String manipulation, formatting
-- **Data Processors** - JSON, CSV, XML parsing
-- **Simple APIs** - Weather, jokes, facts
-- **Utilities** - Date/time, UUID generation
+## License
 
----
+MIT
 
-**Happy Learning! 📖**
+---
 
-Start simple, learn the patterns, then build something amazing!
+**Built with ❤️ using NitroStack + Duffel API**
 
+Need help? Check [Duffel Support](https://duffel.com/docs) or [NitroStack Docs](https://nitrostack.ai/docs)

package/templates/typescript-oauth/package.json

@@ -1,13 +1,15 @@
 {
-  "name": "nitrostack-typescript-oauth",
+  "name": "nitrostack-flight-booking",
   "version": "1.0.0",
   "private": true,
   "type": "module",
+  "description": "NitroStack Flight Booking - Real-time flight search and booking with Duffel API integration",
   "scripts": {
     "dev": "nitrostack dev",
     "build": "nitrostack build",
     "start": "npm run build && nitrostack start",
     "start:prod": "nitrostack start",
+    "upgrade": "nitrostack upgrade",
     "widget": "npm --prefix src/widgets"
   },
   "dependencies": {
@@ -21,6 +23,5 @@
   "devDependencies": {
     "typescript": "^5.3.3"
   },
-  "description": "NitroStack OAuth 2.1 template with flight booking - demonstrates authentication, API integration, and modern widget development",
   "author": ""
-}
+}