@nitrostack/cli 1.0.0

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 { }

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

@@ -0,0 +1,228 @@
+import { PromptDecorator as Prompt, ExecutionContext, Injectable } from 'nitrostack';
+import { DuffelService } from '../../services/duffel.service.js';
+
+@Injectable()
+export class FlightPrompts {
+    constructor(private duffelService: DuffelService) { }
+
+    @Prompt({
+        name: 'flight_search_assistant',
+        description: 'An AI assistant specialized in helping users search for flights, understand flight options, and make booking decisions.',
+        arguments: [
+            {
+                name: 'userQuery',
+                description: 'The user\'s flight search query or question',
+                required: true
+            },
+            {
+                name: 'context',
+                description: 'Optional context including previous searches and selected offers',
+                required: false
+            }
+        ]
+    })
+    async flightSearchAssistant(input: any, ctx: ExecutionContext) {
+        const systemPrompt = `You are a professional flight booking assistant with expertise in helping travelers find flight information.
+
+⚠️ CRITICAL: Only do what the user specifically asks. Do NOT assume additional steps.
+
+Your capabilities:
+- Search for airports using search_airports tool
+- Search for flights using the search_flights tool
+- Get detailed flight information using get_flight_details tool
+- Help book flights when explicitly requested
+
+**IMPORTANT RULES:**
+1. If user asks about airports, ONLY search airports - do NOT search for flights
+2. If user asks about flights, ONLY search flights - do NOT automatically book
+3. If user asks to book, ONLY then proceed with booking workflow
+4. NEVER chain operations unless user explicitly requests it
+
+**EXAMPLES:**
+- "show me airports in London" → search_airports("London") → show results → STOP
+- "find flights from NYC to LAX" → search_flights → show results → STOP
+- "book this flight" → THEN start booking workflow
+
+BOOKING WORKFLOW (only when user explicitly wants to book):
+1. FIRST, collect ALL passenger information (name, title, gender, date of birth, email, phone)
+2. THEN, call create_order tool with complete passenger details
+⚠️ NEVER call create_order without collecting passenger information first!
+⚠️ All bookings are automatically held - no payment is required at booking time
+
+Current user query: ${input.userQuery}
+
+${input.context?.previousSearches?.length ? `Previous searches in this conversation:\n${JSON.stringify(input.context.previousSearches, null, 2)}` : ''}
+
+Respond to EXACTLY what the user asked - nothing more.`;
+
+        return {
+            role: 'assistant',
+            content: systemPrompt
+        };
+    }
+
+    @Prompt({
+        name: 'flight_comparison',
+        description: 'Compare multiple flight offers and provide recommendations based on various factors.',
+        arguments: [
+            {
+                name: 'offerIds',
+                description: 'Flight offer IDs to compare (2-5 offers)',
+                required: true
+            },
+            {
+                name: 'priorities',
+                description: 'User priorities for comparison (price, duration, stops, airline, departure_time, flexibility)',
+                required: false
+            }
+        ]
+    })
+    async flightComparison(input: any, ctx: ExecutionContext) {
+        const offers = await Promise.all(
+            input.offerIds.map((id: string) => this.duffelService.getOffer(id))
+        );
+
+        const comparisonData = offers.map((offer: any) => {
+            const outbound = offer.slices[0];
+            return {
+                offerId: offer.id,
+                price: `${offer.total_amount} ${offer.total_currency}`,
+                airline: outbound.segments[0].marketing_carrier.name,
+                duration: outbound.duration,
+                stops: outbound.segments.length - 1,
+                departureTime: outbound.segments[0].departing_at,
+                arrivalTime: outbound.segments[outbound.segments.length - 1].arriving_at,
+                refundable: offer.conditions?.refund_before_departure?.allowed || false,
+                changeable: offer.conditions?.change_before_departure?.allowed || false
+            };
+        });
+
+        const priorities = input.priorities || ['price', 'duration', 'stops'];
+
+        const prompt = `Compare these flight options and provide a recommendation:
+
+${JSON.stringify(comparisonData, null, 2)}
+
+User priorities: ${priorities.join(', ')}
+
+Provide:
+1. A clear comparison of the key differences
+2. Pros and cons of each option
+3. Your recommendation based on the user's priorities
+4. Any important considerations (layover times, airline reputation, flexibility, etc.)`;
+
+        return {
+            role: 'assistant',
+            content: prompt
+        };
+    }
+
+    @Prompt({
+        name: 'travel_tips',
+        description: 'Provide travel tips and advice for a specific route and travel dates.',
+        arguments: [
+            {
+                name: 'origin',
+                description: 'Origin airport code',
+                required: true
+            },
+            {
+                name: 'destination',
+                description: 'Destination airport code',
+                required: true
+            },
+            {
+                name: 'departureDate',
+                description: 'Departure date',
+                required: true
+            },
+            {
+                name: 'tripType',
+                description: 'Type of trip: business, leisure, or family',
+                required: false
+            }
+        ]
+    })
+    async travelTips(input: any, ctx: ExecutionContext) {
+        const prompt = `Provide helpful travel tips for a trip from ${input.origin} to ${input.destination} departing on ${input.departureDate}.
+
+Include advice on:
+1. Best time to book for this route
+2. Typical weather at destination during this time
+3. Airport tips (check-in, security, lounges)
+4. Baggage recommendations
+5. Connection considerations if applicable
+6. Time zone differences and jet lag tips
+${input.tripType ? `7. Specific tips for ${input.tripType} travel` : ''}
+
+Be concise but informative.`;
+
+        return {
+            role: 'assistant',
+            content: prompt
+        };
+    }
+
+    @Prompt({
+        name: 'booking_assistant',
+        description: 'Guide users through the flight booking process, collecting all necessary passenger information before creating an order.',
+        arguments: [
+            {
+                name: 'offerId',
+                description: 'The flight offer ID the user wants to book',
+                required: true
+            },
+            {
+                name: 'passengerCount',
+                description: 'Number of passengers (default: 1)',
+                required: false
+            }
+        ]
+    })
+    async bookingAssistant(input: any, ctx: ExecutionContext) {
+        const passengerCount = input.passengerCount || 1;
+
+        const prompt = `You are helping the user book flight offer: ${input.offerId}
+
+IMPORTANT BOOKING WORKFLOW:
+Before you can create the order, you MUST collect the following information for ${passengerCount} passenger(s):
+
+For EACH passenger, ask for:
+1. **Title**: Mr, Ms, Mrs, Miss, or Dr
+2. **Full Name**: First name and last name (as it appears on their passport/ID)
+3. **Gender**: Male (M) or Female (F)
+4. **Date of Birth**: In YYYY-MM-DD format (e.g., 1990-01-15)
+5. **Email Address**: For booking confirmation
+6. **Phone Number**: With country code (e.g., +1234567890)
+
+COLLECTION STRATEGY:
+- Ask for all information in a friendly, conversational way
+- You can ask for multiple fields at once to make it efficient
+- Validate the format (especially date of birth and email)
+- Confirm all details with the user before proceeding
+
+EXAMPLE QUESTIONS:
+"Great! To complete your booking, I'll need some passenger details. Could you please provide:
+- Full name (first and last)
+- Title (Mr/Ms/Mrs/Miss/Dr)
+- Date of birth (YYYY-MM-DD)
+- Gender (M/F)
+- Email address
+- Phone number with country code"
+
+BOOKING PROCESS:
+Once you have ALL passenger information:
+- Call create_order with the offer ID and passenger details
+- The booking will be automatically held (no payment required)
+- The user will receive booking confirmation with expiration details
+- Payment can be completed later before the hold expires
+
+DO NOT ask for payment details - all bookings are held by default.
+ALWAYS inform the user that their booking is held and they have time to complete payment.`;
+
+        return {
+            role: 'assistant',
+            content: prompt
+        };
+    }
+}