nitrostack 1.0.55 → 1.0.56

package/templates/typescript-oauth/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "typescript-oauth",
+  "name": "nitrostack-typescript-oauth",
   "version": "1.0.0",
   "private": true,
   "type": "module",
@@ -11,11 +11,16 @@
     "widget": "npm --prefix src/widgets"
   },
   "dependencies": {
-    "dotenv": "^16.4.5",
     "nitrostack": "^1",
-    "zod": "^3.23.8"
+    "zod": "^3.22.4",
+    "dotenv": "^16.3.1",
+    "@duffel/api": "^4.21.0",
+    "axios": "^1.7.9",
+    "date-fns": "^4.1.0"
   },
   "devDependencies": {
     "typescript": "^5.3.3"
-  }
-}
+  },
+  "description": "NitroStack OAuth 2.1 template with flight booking - demonstrates authentication, API integration, and modern widget development",
+  "author": ""
+}

package/templates/typescript-oauth/src/app.module.ts

@@ -1,49 +1,52 @@
-import { McpApp, Module, OAuthModule } from 'nitrostack';
-import { DemoModule } from './modules/demo/demo.module.js';
+import { McpApp, Module, ConfigModule, OAuthModule } from 'nitrostack';
+import { FlightsModule } from './modules/flights/flights.module.js';
+import { SystemHealthCheck } from './health/system.health.js';
 
 /**
- * App Module - Root module for the OAuth 2.1 MCP Server
+ * Root Application Module
  * 
- * This module demonstrates OAuth 2.1 authentication according to:
- * - MCP Specification: https://modelcontextprotocol.io/specification/draft/basic/authorization
- * - OpenAI Apps SDK Requirements: https://developers.openai.com/apps-sdk/build/auth
+ * This is the main module that bootstraps the MCP server.
+ * It registers all feature modules and health checks.
  * 
- * OAuth 2.1 Standards Compliance:
- * - OAuth 2.1 (draft-ietf-oauth-v2-1-13)
- * - RFC 9728 - Protected Resource Metadata
- * - RFC 8414 - Authorization Server Metadata
- * - RFC 7591 - Dynamic Client Registration
- * - RFC 8707 - Resource Indicators (Token Audience Binding)
- * - RFC 7636 - PKCE
- * - RFC 7662 - Token Introspection
+ * OAuth 2.1 Authentication:
+ * - Configured with Auth0 as the authorization server
+ * - Supports read, write, and admin scopes
+ * - Validates tokens with audience binding (RFC 8707)
+ * 
+ * Flight Booking System:
+ * - Powered by Duffel API
+ * - Professional flight search and booking capabilities
+ * - Comprehensive widgets for search results and flight details
  */
 @McpApp({
   module: AppModule,
   server: {
-    name: 'OAuth 2.1 MCP Server',
-    version: '1.0.0',
+    name: 'airline-ticketing-server',
+    version: '1.0.0'
   },
   logging: {
-    level: 'info',
-  },
+    level: 'info'
+  }
 })
 @Module({
   name: 'app',
-  description: 'Root application module with OAuth 2.1 authentication',
+  description: 'Airline ticketing MCP server with OAuth 2.1 authentication and Duffel integration',
   imports: [
+    ConfigModule.forRoot(),
+
     // Enable OAuth 2.1 authentication
     OAuthModule.forRoot({
       // Resource URI - YOUR MCP server's public URL
       // This is used for token audience binding (RFC 8707)
       // CRITICAL: Tokens must be issued specifically for this URI
-      resourceUri: process.env.RESOURCE_URI || 'https://mcp.example.com',
-      
+      resourceUri: process.env.RESOURCE_URI || 'https://mcplocal',
+
       // Authorization Server(s) - The OAuth provider URL(s)
       // Supports multiple auth servers for federation scenarios
       authorizationServers: [
-        process.env.AUTH_SERVER_URL || 'https://auth.example.com',
+        process.env.AUTH_SERVER_URL || 'https://dev-5dt0utuk31h13tjm.us.auth0.com',
       ],
-      
+
       // Supported scopes for this MCP server
       // Define what permissions your server supports
       scopesSupported: [
@@ -51,39 +54,39 @@ import { DemoModule } from './modules/demo/demo.module.js';
         'write',       // Write/modify resources
         'admin',       // Administrative operations
       ],
-      
+
       // Token Introspection (RFC 7662) - For opaque tokens
       // If your OAuth provider issues opaque tokens (not JWTs),
       // you MUST configure introspection to validate them
       tokenIntrospectionEndpoint: process.env.INTROSPECTION_ENDPOINT,
       tokenIntrospectionClientId: process.env.INTROSPECTION_CLIENT_ID,
       tokenIntrospectionClientSecret: process.env.INTROSPECTION_CLIENT_SECRET,
-      
+
       // Expected audience (defaults to resourceUri if not provided)
       // MUST match the audience claim in tokens (RFC 8707)
       audience: process.env.TOKEN_AUDIENCE,
-      
+
       // Expected issuer (optional but recommended)
       // If provided, tokens must be from this issuer
       issuer: process.env.TOKEN_ISSUER,
-      
+
       // Custom validation (optional)
       // Add any additional validation logic beyond spec requirements
       customValidation: async (tokenPayload) => {
         // Example: Check if user is active in your database
         // const user = await db.users.findOne({ id: tokenPayload.sub });
         // return user?.active === true;
-        
-        // For demo, accept all valid tokens
+
+        // For now, accept all valid tokens
         return true;
       },
     }),
-    
-    // Feature modules
-    DemoModule,
+
+    FlightsModule
   ],
-  controllers: [],
-  providers: [],
+  providers: [
+    // Health Checks
+    SystemHealthCheck,
+  ]
 })
-export class AppModule {}
-
+export class AppModule { }

package/templates/typescript-oauth/src/guards/oauth.guard.ts

@@ -124,4 +124,3 @@ export function createScopeGuard(requiredScopes: string[]): new () => Guard {
   };
 }
 
-

package/templates/typescript-oauth/src/index.ts

@@ -1,71 +1,63 @@
 #!/usr/bin/env node
-import 'dotenv/config';
-import { McpApplicationFactory } from 'nitrostack';
-import { AppModule } from './app.module.js';
-
 /**
- * OAuth 2.1 MCP Server
+ * Calculator MCP Server with OAuth 2.1 Authentication
  * 
- * Demonstrates OAuth 2.1 authentication for Model Context Protocol servers.
+ * Main entry point for the MCP server.
+ * Uses the @McpApp decorator pattern for clean, NestJS-style architecture.
  * 
- * Compliant with:
+ * OAuth 2.1 Compliance:
  * - MCP Specification: https://modelcontextprotocol.io/specification/draft/basic/authorization
  * - OpenAI Apps SDK: https://developers.openai.com/apps-sdk/build/auth
- * 
- * Standards:
- * - OAuth 2.1 (draft-ietf-oauth-v2-1-13)
  * - RFC 9728 - Protected Resource Metadata
- * - RFC 8414 - Authorization Server Metadata
- * - RFC 7591 - Dynamic Client Registration
  * - RFC 8707 - Resource Indicators (Token Audience Binding)
- * - RFC 7636 - PKCE
- * - RFC 7662 - Token Introspection
- * 
- * Compatible with:
- * - Auth0
- * - Okta
- * - Keycloak
- * - Any RFC-compliant OAuth 2.1 provider
  * 
  * Transport Configuration:
  * - Development (NODE_ENV=development): STDIO only
  * - Production (NODE_ENV=production): Dual transport (STDIO + HTTP SSE)
+ * - With OAuth: Dual mode (STDIO + HTTP for metadata endpoints)
  */
 
+import 'dotenv/config';
+import { McpApplicationFactory } from 'nitrostack';
+import { AppModule } from './app.module.js';
+
+/**
+ * Bootstrap the application
+ */
 async function bootstrap() {
   try {
-    console.error('🔐 Starting OAuth 2.1 MCP Server...\n');
+    console.error('🔐 Starting Calculator MCP Server with OAuth 2.1...\\n');
 
-    // Validate required environment variables
+    // Validate required environment variables for OAuth
     const requiredEnvVars = ['RESOURCE_URI', 'AUTH_SERVER_URL'];
     const missing = requiredEnvVars.filter(v => !process.env[v]);
 
     if (missing.length > 0) {
-      console.error('❌ Missing required environment variables:');
+      console.error('❌ Missing required OAuth environment variables:');
       missing.forEach(v => console.error(`   - ${v}`));
-      console.error('\n💡 Copy .env.example to .env and configure your OAuth provider');
-      console.error('   See OAUTH_SETUP.md for provider-specific setup guides\n');
+      console.error('\\n💡 Copy .env.example to .env and configure your OAuth provider');
+      console.error('   Or check the test-oauth/.env for reference\\n');
       process.exit(1);
     }
 
     // Create the MCP application
-    const app = await McpApplicationFactory.create(AppModule);
+    const server = await McpApplicationFactory.create(AppModule);
 
     console.error('✅ OAuth 2.1 Module configured');
     console.error(`   Resource URI: ${process.env.RESOURCE_URI}`);
     console.error(`   Auth Server: ${process.env.AUTH_SERVER_URL}`);
     console.error(`   Scopes: read, write, admin`);
-    console.error(`   Audience: ${process.env.TOKEN_AUDIENCE || process.env.RESOURCE_URI}\n`);
+    console.error(`   Audience: ${process.env.TOKEN_AUDIENCE || process.env.RESOURCE_URI}\\n`);
 
     // Start the server
-    await app.start();
+    await server.start();
 
   } catch (error) {
     console.error('❌ Failed to start server:', error);
-    console.error('\n💡 Check your OAuth configuration in .env');
-    console.error('   See OAUTH_SETUP.md for troubleshooting\n');
+    console.error('\\n💡 Check your OAuth configuration in .env\\n');
     process.exit(1);
   }
 }
 
+// Start the application
 bootstrap();

package/templates/typescript-oauth/src/modules/flights/booking.tools.ts

@@ -0,0 +1,323 @@
+import { ToolDecorator as Tool, Widget, ExecutionContext, z, UseGuards, Injectable } from 'nitrostack';
+import { OAuthGuard } from '../../guards/oauth.guard.js';
+import { DuffelService } from '../../services/duffel.service.js';
+
+@Injectable()
+export class BookingTools {
+    constructor(private duffelService: DuffelService) { }
+
+    @Tool({
+        name: 'create_order',
+        description: 'Create a flight order with hold (no payment required). IMPORTANT: Before calling this tool, you MUST collect passenger information from the user. Ask for: full name (first and last), title (Mr/Ms/Mrs/Miss/Dr), gender (M/F), date of birth (YYYY-MM-DD), email, and phone number with country code. The order will be held for later payment.',
+        inputSchema: z.object({
+            offerId: z.string().describe('The offer ID to book'),
+            passengers: z.string().describe('JSON string containing array of passenger objects. Each passenger must have: title (mr/ms/mrs/miss/dr), givenName (first name), familyName (last name), gender (M/F), bornOn (YYYY-MM-DD), email, phoneNumber. Example: \'[{"title":"mr","givenName":"John","familyName":"Doe","gender":"M","bornOn":"1990-01-15","email":"john@example.com","phoneNumber":"+1234567890"}]\'')
+        }),
+        examples: {
+            request: {
+                offerId: 'off_123456',
+                passengers: '[{"title":"mr","givenName":"John","familyName":"Doe","gender":"M","bornOn":"1990-01-15","email":"john.doe@example.com","phoneNumber":"+1234567890"}]'
+            },
+            response: {
+                orderId: 'ord_123456',
+                status: 'held',
+                totalAmount: '450.00',
+                totalCurrency: 'USD',
+                expiresAt: '2024-03-01T12:00:00Z',
+                passengers: [],
+                slices: [],
+                message: 'Order created and held successfully.'
+            }
+        }
+    })
+    @UseGuards(OAuthGuard)
+    @Widget('order-summary')
+    async createOrder(input: any, ctx: ExecutionContext) {
+        ctx.logger.info('Creating flight order (hold)', {
+            user: ctx.auth?.subject,
+            offerId: input.offerId
+        });
+
+        // Validate and parse passengers
+        let passengersArray;
+        try {
+            if (typeof input.passengers === 'string') {
+                // Try to parse the JSON string
+                // Handle both regular JSON and double-encoded JSON
+                let passengerStr = input.passengers;
+
+                // If the string starts with escaped quotes, it might be double-encoded
+                if (passengerStr.startsWith('\\"') || passengerStr.includes('\\"')) {
+                    // Remove escape characters
+                    passengerStr = passengerStr.replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+                }
+
+                passengersArray = JSON.parse(passengerStr);
+            } else if (Array.isArray(input.passengers)) {
+                passengersArray = input.passengers;
+            } else {
+                throw new Error('Passengers must be a JSON string or array');
+            }
+        } catch (error: any) {
+            ctx.logger.error('Failed to parse passengers', {
+                input: input.passengers,
+                error: error.message
+            });
+            throw new Error(`Invalid passengers format: ${error.message}. Expected JSON string like '[{"title":"mr","givenName":"John","familyName":"Doe","gender":"M","bornOn":"1990-01-15","email":"john@example.com","phoneNumber":"+1234567890"}]'`);
+        }
+
+        if (!passengersArray || !Array.isArray(passengersArray) || passengersArray.length === 0) {
+            throw new Error('At least one passenger is required to create an order');
+        }
+
+        // Transform passengers to Duffel format
+        // Pass inline passenger data - Duffel will create passenger records automatically
+        const passengers = passengersArray.map((pax: any) => ({
+            title: pax.title,
+            given_name: pax.givenName,
+            family_name: pax.familyName,
+            gender: pax.gender,
+            born_on: pax.bornOn,
+            email: pax.email,
+            phone_number: pax.phoneNumber
+        }));
+
+        const orderParams: any = {
+            selectedOffers: [input.offerId],
+            passengers,
+            type: 'hold' // Always create hold orders
+        };
+
+        const order = await this.duffelService.createOrder(orderParams);
+
+        ctx.logger.info('Order created successfully', {
+            user: ctx.auth?.subject,
+            orderId: order.id,
+            status: 'held'
+        });
+
+        return {
+            orderId: order.id,
+            status: 'held',
+            totalAmount: order.total_amount,
+            totalCurrency: order.total_currency,
+            expiresAt: (order as any).expires_at,
+            bookingReference: order.booking_reference,
+            passengers: order.passengers.map((pax: any) => ({
+                id: pax.id,
+                name: `${pax.given_name} ${pax.family_name}`,
+                type: pax.type
+            })),
+            slices: order.slices.map((slice: any) => ({
+                origin: slice.origin.iata_code,
+                destination: slice.destination.iata_code,
+                departureTime: slice.segments[0].departing_at,
+                arrivalTime: slice.segments[slice.segments.length - 1].arriving_at
+            })),
+            message: 'Order created and held successfully.'
+        };
+    }
+
+
+
+    @Tool({
+        name: 'get_order_details',
+        description: 'Get detailed information about an order',
+        inputSchema: z.object({
+            orderId: z.string().describe('The order ID')
+        }),
+        examples: {
+            request: {
+                orderId: 'ord_123456'
+            },
+            response: {
+                orderId: 'ord_123456',
+                status: 'confirmed',
+                bookingReference: 'ABC123',
+                totalAmount: '450.00',
+                totalCurrency: 'USD',
+                passengers: [],
+                slices: []
+            }
+        }
+    })
+    @UseGuards(OAuthGuard)
+    @Widget('order-summary')
+    async getOrderDetails(input: any, ctx: ExecutionContext) {
+        ctx.logger.info('Getting order details', {
+            user: ctx.auth?.subject,
+            orderId: input.orderId
+        });
+
+        const order = await this.duffelService.getOrder(input.orderId);
+
+        return {
+            orderId: order.id,
+            status: (order as any).status || 'confirmed',
+            bookingReference: order.booking_reference,
+            totalAmount: order.total_amount,
+            totalCurrency: order.total_currency,
+            createdAt: order.created_at,
+            expiresAt: (order as any).expires_at,
+            passengers: order.passengers.map((pax: any) => ({
+                id: pax.id,
+                name: `${pax.given_name} ${pax.family_name}`,
+                type: pax.type,
+                email: pax.email,
+                phoneNumber: pax.phone_number
+            })),
+            slices: order.slices.map((slice: any) => ({
+                id: slice.id,
+                origin: {
+                    code: slice.origin.iata_code,
+                    name: slice.origin.name,
+                    city: slice.origin.city_name
+                },
+                destination: {
+                    code: slice.destination.iata_code,
+                    name: slice.destination.name,
+                    city: slice.destination.city_name
+                },
+                duration: slice.duration,
+                segments: slice.segments.map((seg: any) => ({
+                    id: seg.id,
+                    origin: seg.origin.iata_code,
+                    destination: seg.destination.iata_code,
+                    departingAt: seg.departing_at,
+                    arrivingAt: seg.arriving_at,
+                    airline: seg.marketing_carrier.name,
+                    flightNumber: seg.marketing_carrier_flight_number,
+                    aircraft: seg.aircraft?.name
+                }))
+            }))
+        };
+    }
+
+    @Tool({
+        name: 'get_seat_map',
+        description: 'Get available seats for a flight offer to allow seat selection',
+        inputSchema: z.object({
+            offerId: z.string().describe('The offer ID to get seats for')
+        }),
+        examples: {
+            request: {
+                offerId: 'off_123456'
+            },
+            response: {
+                offerId: 'off_123456',
+                cabins: [
+                    {
+                        cabinClass: 'economy',
+                        rows: [
+                            {
+                                rowNumber: 10,
+                                seats: [
+                                    {
+                                        id: 'seat_10a',
+                                        column: 'A',
+                                        available: true,
+                                        price: '25.00',
+                                        currency: 'USD',
+                                        type: 'window'
+                                    },
+                                    {
+                                        id: 'seat_10b',
+                                        column: 'B',
+                                        available: true,
+                                        price: '0',
+                                        currency: 'USD',
+                                        type: 'middle'
+                                    },
+                                    {
+                                        id: 'seat_10c',
+                                        column: 'C',
+                                        available: true,
+                                        price: '15.00',
+                                        currency: 'USD',
+                                        type: 'aisle'
+                                    }
+                                ]
+                            }
+                        ]
+                    }
+                ],
+                message: 'Select your preferred seats from the available options'
+            }
+        }
+    })
+    @UseGuards(OAuthGuard)
+    @Widget('seat-selection')
+    async getSeatMap(input: any, ctx: ExecutionContext) {
+        ctx.logger.info('Getting seat map', {
+            user: ctx.auth?.subject,
+            offerId: input.offerId
+        });
+
+        const seatMaps = await this.duffelService.getSeatsForOffer(input.offerId);
+
+        return {
+            offerId: input.offerId,
+            cabins: seatMaps.map((cabin: any) => ({
+                cabinClass: cabin.cabin_class,
+                rows: cabin.rows.map((row: any) => ({
+                    rowNumber: row.row_number,
+                    seats: row.sections.flatMap((section: any) =>
+                        section.elements.filter((el: any) => el.type === 'seat').map((seat: any) => ({
+                            id: seat.id,
+                            column: seat.designator,
+                            available: seat.available_services?.length > 0,
+                            price: seat.available_services?.[0]?.total_amount,
+                            currency: seat.available_services?.[0]?.total_currency,
+                            type: seat.disclosures?.join(', ') || 'standard'
+                        }))
+                    )
+                }))
+            })),
+            message: 'Select your preferred seats from the available options'
+        };
+    }
+
+    @Tool({
+        name: 'cancel_order',
+        description: 'Cancel a flight order and request refund if applicable',
+        inputSchema: z.object({
+            orderId: z.string().describe('The order ID to cancel')
+        }),
+        examples: {
+            request: {
+                orderId: 'ord_123456'
+            },
+            response: {
+                orderId: 'ord_123456',
+                cancellationId: 'ocr_123456',
+                status: 'cancelled',
+                refundAmount: '450.00',
+                refundCurrency: 'USD',
+                confirmedAt: '2024-03-01T12:00:00Z',
+                message: 'Order cancelled. Refund of USD 450.00 will be processed.'
+            }
+        }
+    })
+    @UseGuards(OAuthGuard)
+    @Widget('order-cancellation')
+    async cancelOrder(input: any, ctx: ExecutionContext) {
+        ctx.logger.info('Cancelling order', {
+            user: ctx.auth?.subject,
+            orderId: input.orderId
+        });
+
+        const cancellation = await this.duffelService.cancelOrder(input.orderId);
+
+        return {
+            orderId: input.orderId,
+            cancellationId: cancellation.id,
+            status: 'cancelled',
+            refundAmount: cancellation.refund_amount,
+            refundCurrency: cancellation.refund_currency,
+            confirmedAt: cancellation.confirmed_at,
+            message: cancellation.refund_amount
+                ? `Order cancelled. Refund of ${cancellation.refund_currency} ${cancellation.refund_amount} will be processed.`
+                : 'Order cancelled. No refund available for this booking.'
+        };
+    }
+}

package/templates/typescript-oauth/src/modules/flights/flights.module.ts

@@ -0,0 +1,14 @@
+import { Module } from 'nitrostack';
+import { FlightTools } from './flights.tools.js';
+import { BookingTools } from './booking.tools.js';
+import { FlightPrompts } from './flights.prompts.js';
+import { FlightResources } from './flights.resources.js';
+import { DuffelService } from '../../services/duffel.service.js';
+
+@Module({
+    name: 'flights',
+    description: 'Professional flight search and booking system powered by Duffel API',
+    controllers: [FlightTools, BookingTools, FlightPrompts, FlightResources],
+    providers: [DuffelService]
+})
+export class FlightsModule { }