1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

/**
 * DailyInventory - tracks room availability for a single date
 * One record per hotel + room type + date combination
 */
class DailyInventory {
    private readonly id: DailyInventoryId;
    private readonly hotelId: HotelId;
    private readonly roomTypeId: RoomTypeId;
    private readonly date: LocalDate;
    
    // Physical inventory
    private readonly physicalRooms: number;     // Total rooms of this type
    private outOfOrderRooms: number;             // Blocked for maintenance
    
    // Calculated availability
    private confirmedReservations: number;       // Confirmed bookings
    private pendingReservations: number;         // Unconfirmed bookings (held)
    
    // Overbooking management
    private overbookingAllowance: number;        // Extra rooms allowed to sell
    private sellLimit: number;                   // Manually set sales cap (can be < physical)
    
    // Channel allocation (optional advanced feature)
    private channelAllocations: Map<BookingChannel, number>;
    
    // Computed properties
    get totalInventory(): number {
        return this.physicalRooms - this.outOfOrderRooms;
    }
    
    get effectiveSellLimit(): number {
        // Sell limit including overbooking allowance, capped by total
        return Math.min(
            this.sellLimit + this.overbookingAllowance,
            this.physicalRooms + this.overbookingAllowance
        );
    }
    
    get totalBooked(): number {
        return this.confirmedReservations + this.pendingReservations;
    }
    
    get availableToSell(): number {
        return Math.max(0, this.effectiveSellLimit - this.totalBooked);
    }
    
    get isSoldOut(): boolean {
        return this.availableToSell === 0;
    }
    
    get isOverbooked(): boolean {
        return this.confirmedReservations > this.totalInventory;
    }
    
    get overbookingLevel(): number {
        // Positive if overbooked, negative if under-booked
        return this.confirmedReservations - this.totalInventory;
    }
    
    // ============ Modification Methods ============
    
    /**
     * Reserve inventory for a new booking
     * @throws InsufficientInventoryError if no availability
     */
    reserve(count: number = 1, status: 'CONFIRMED' | 'PENDING' = 'CONFIRMED'): void {
        if (count > this.availableToSell) {
            throw new InsufficientInventoryError(
                `Cannot reserve ${count} rooms on ${this.date}. Available: ${this.availableToSell}`
            );
        }
        
        if (status === 'CONFIRMED') {
            this.confirmedReservations += count;
        } else {
            this.pendingReservations += count;
        }
    }
    
    /**
     * Release inventory when booking is cancelled or modified
     */
    release(count: number = 1, status: 'CONFIRMED' | 'PENDING' = 'CONFIRMED'): void {
        if (status === 'CONFIRMED') {
            this.confirmedReservations = Math.max(0, this.confirmedReservations - count);
        } else {
            this.pendingReservations = Math.max(0, this.pendingReservations - count);
        }
    }
    
    /**
     * Convert pending to confirmed (on payment)
     */
    confirmPending(count: number = 1): void {
        if (count > this.pendingReservations) {
            throw new InvalidInventoryOperationError(
                `Cannot confirm ${count} pending. Only ${this.pendingReservations} pending.`
            );
        }
        
        this.pendingReservations -= count;
        this.confirmedReservations += count;
    }
    
    /**
     * Block rooms for maintenance/out-of-order
     */
    blockRooms(count: number, reason: string): void {
        const newOutOfOrder = this.outOfOrderRooms + count;
        if (newOutOfOrder > this.physicalRooms) {
            throw new InvalidInventoryOperationError(
                `Cannot block ${count} rooms. Would exceed physical inventory.`
            );
        }
        
        this.outOfOrderRooms = newOutOfOrder;
        // Might need to adjust sell limit if blocking reduces available
    }
    
    /**
     * Update overbooking allowance (revenue management)
     */
    setOverbookingAllowance(allowance: number): void {
        if (allowance < 0) {
            throw new InvalidInventoryOperationError(
                'Overbooking allowance cannot be negative'
            );
        }
        
        // Cap at a percentage of physical inventory (e.g., max 10%)
        const maxAllowance = Math.floor(this.physicalRooms * 0.10);
        this.overbookingAllowance = Math.min(allowance, maxAllowance);
    }
    
    /**
     * Set manual sell limit (close out)
     */
    setSellLimit(limit: number): void {
        if (limit < 0) {
            throw new InvalidInventoryOperationError('Sell limit cannot be negative');
        }
        if (limit < this.confirmedReservations) {
            // Can't reduce below already sold
            throw new InvalidInventoryOperationError(
                `Cannot set limit to ${limit}. Already have ${this.confirmedReservations} confirmed.`
            );
        }
        
        this.sellLimit = limit;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238

/**
 * AvailabilityService - handles availability queries and reservations
 */
class AvailabilityService {
    private readonly inventoryRepository: DailyInventoryRepository;
    private readonly lockManager: DistributedLockManager;
    
    /**
     * Check availability for a stay
     * Returns the maximum number of rooms bookable for the entire stay
     */
    async checkAvailability(
        hotelId: HotelId,
        roomTypeId: RoomTypeId,
        checkIn: LocalDate,
        checkOut: LocalDate
    ): Promise<AvailabilityResult> {
        // Get inventory records for all nights
        const nights = this.getStayNights(checkIn, checkOut);
        const inventoryRecords = await this.inventoryRepository.findByDates(
            hotelId,
            roomTypeId,
            nights
        );
        
        // Validate we have records for all nights
        if (inventoryRecords.length !== nights.length) {
            const missingDates = this.findMissingDates(nights, inventoryRecords);
            throw new InventoryNotConfiguredError(
                `No inventory configured for dates: ${missingDates.join(', ')}`
            );
        }
        
        // Find minimum availability across all nights
        const minAvailable = Math.min(
            ...inventoryRecords.map(inv => inv.availableToSell)
        );
        
        // Find the constraining night (for diagnostics)
        const constrainingNight = inventoryRecords.find(
            inv => inv.availableToSell === minAvailable
        );
        
        return new AvailabilityResult({
            hotelId,
            roomTypeId,
            checkIn,
            checkOut,
            nights: nights.length,
            availableRooms: minAvailable,
            isSoldOut: minAvailable === 0,
            constrainingDate: constrainingNight?.date,
            dailyBreakdown: inventoryRecords.map(inv => ({
                date: inv.date,
                available: inv.availableToSell,
                totalInventory: inv.totalInventory,
            })),
        });
    }
    
    /**
     * Reserve inventory for a booking (atomic across all nights)
     */
    async reserveInventory(
        hotelId: HotelId,
        roomTypeId: RoomTypeId,
        checkIn: LocalDate,
        checkOut: LocalDate,
        roomCount: number,
        reservationId: ReservationId
    ): Promise<void> {
        const nights = this.getStayNights(checkIn, checkOut);
        const lockKey = `inventory:${hotelId}:${roomTypeId}`;
        
        // Acquire distributed lock to prevent race conditions
        await this.lockManager.withLock(lockKey, async () => {
            // Re-check availability with lock held
            const availability = await this.checkAvailability(
                hotelId, roomTypeId, checkIn, checkOut
            );
            
            if (availability.availableRooms < roomCount) {
                throw new InsufficientInventoryError(
                    `Requested ${roomCount} rooms, only ${availability.availableRooms} available`
                );
            }
            
            // Reserve on all nights atomically
            const inventoryRecords = await this.inventoryRepository.findByDates(
                hotelId, roomTypeId, nights
            );
            
            for (const inventory of inventoryRecords) {
                inventory.reserve(roomCount, 'CONFIRMED');
            }
            
            // Single transaction to update all
            await this.inventoryRepository.saveAll(inventoryRecords);
            
            // Log for reconciliation
            await this.logInventoryChange({
                operation: 'RESERVE',
                reservationId,
                hotelId,
                roomTypeId,
                dates: nights,
                roomCount,
                timestamp: Instant.now(),
            });
        });
    }
    
    /**
     * Release inventory when booking is cancelled
     */
    async releaseInventory(
        hotelId: HotelId,
        roomTypeId: RoomTypeId,
        checkIn: LocalDate,
        checkOut: LocalDate,
        roomCount: number,
        reservationId: ReservationId
    ): Promise<void> {
        const nights = this.getStayNights(checkIn, checkOut);
        
        // No lock needed for release - we're increasing availability
        // However, we do it in transaction for consistency
        const inventoryRecords = await this.inventoryRepository.findByDates(
            hotelId, roomTypeId, nights
        );
        
        for (const inventory of inventoryRecords) {
            inventory.release(roomCount, 'CONFIRMED');
        }
        
        await this.inventoryRepository.saveAll(inventoryRecords);
        
        await this.logInventoryChange({
            operation: 'RELEASE',
            reservationId,
            hotelId,
            roomTypeId,
            dates: nights,
            roomCount,
            timestamp: Instant.now(),
        });
    }
    
    /**
     * Handle modification - adjust inventory for date changes
     */
    async adjustInventoryForModification(
        reservationId: ReservationId,
        originalDates: DateRange,
        newDates: DateRange,
        hotelId: HotelId,
        roomTypeId: RoomTypeId,
        roomCount: number
    ): Promise<void> {
        // Calculate date differences
        const originalNights = new Set(
            this.getStayNights(originalDates.start, originalDates.end)
                .map(d => d.toString())
        );
        const newNights = new Set(
            this.getStayNights(newDates.start, newDates.end)
                .map(d => d.toString())
        );
        
        const toRelease: LocalDate[] = [];
        const toReserve: LocalDate[] = [];
        
        // Nights being released (in original but not in new)
        for (const night of originalNights) {
            if (!newNights.has(night)) {
                toRelease.push(LocalDate.parse(night));
            }
        }
        
        // Nights being added (in new but not in original)
        for (const night of newNights) {
            if (!originalNights.has(night)) {
                toReserve.push(LocalDate.parse(night));
            }
        }
        
        const lockKey = `inventory:${hotelId}:${roomTypeId}`;
        
        await this.lockManager.withLock(lockKey, async () => {
            // First check availability for new nights
            if (toReserve.length > 0) {
                const availability = await this.checkAvailabilityForNights(
                    hotelId, roomTypeId, toReserve
                );
                
                if (availability.minAvailable < roomCount) {
                    throw new InsufficientInventoryError(
                        `Cannot extend to new dates. Required: ${roomCount}, available: ${availability.minAvailable}`
                    );
                }
            }
            
            // Release old nights
            if (toRelease.length > 0) {
                const releaseRecords = await this.inventoryRepository.findByDates(
                    hotelId, roomTypeId, toRelease
                );
                for (const inv of releaseRecords) {
                    inv.release(roomCount, 'CONFIRMED');
                }
                await this.inventoryRepository.saveAll(releaseRecords);
            }
            
            // Reserve new nights
            if (toReserve.length > 0) {
                const reserveRecords = await this.inventoryRepository.findByDates(
                    hotelId, roomTypeId, toReserve
                );
                for (const inv of reserveRecords) {
                    inv.reserve(roomCount, 'CONFIRMED');
                }
                await this.inventoryRepository.saveAll(reserveRecords);
            }
        });
    }
    
    private getStayNights(checkIn: LocalDate, checkOut: LocalDate): LocalDate[] {
        const nights: LocalDate[] = [];
        let current = checkIn;
        
        while (current.isBefore(checkOut)) {
            nights.push(current);
            current = current.plusDays(1);
        }
        
        return nights;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178

/**
 * OverbookingEngine - calculates optimal overbooking levels
 */
class OverbookingEngine {
    private readonly historicalAnalyzer: HistoricalDataAnalyzer;
    private readonly costCalculator: WalkCostCalculator;
    
    /**
     * Calculate recommended overbooking allowance for a date
     */
    calculateRecommendedOverbooking(
        hotelId: HotelId,
        roomTypeId: RoomTypeId,
        date: LocalDate
    ): OverbookingRecommendation {
        // Get historical rates for similar periods
        const historicalRates = this.historicalAnalyzer.getRates(
            hotelId,
            roomTypeId,
            date
        );
        
        const expectedNoShows = historicalRates.noShowRate;
        const expectedCancellations = historicalRates.lateCancellationRate;
        const totalExpectedFreed = expectedNoShows + expectedCancellations;
        
        // Get inventory size
        const inventory = this.getInventorySize(hotelId, roomTypeId);
        
        // Calculate raw overbooking count
        const rawOverbooking = Math.floor(inventory * totalExpectedFreed);
        
        // Calculate walk risk at different levels
        const walkRisk = this.calculateWalkRisk(
            inventory,
            rawOverbooking,
            historicalRates.standardDeviation
        );
        
        // Calculate expected walk cost
        const expectedWalkCost = this.costCalculator.calculate(
            hotelId,
            date,
            walkRisk.expectedWalks
        );
        
        // Calculate revenue gain from overbooking
        const avgNightlyRate = this.getAverageRate(hotelId, roomTypeId, date);
        const expectedRevenueGain = avgNightlyRate.multiply(rawOverbooking)
            .multiply(1 - walkRisk.walkProbability);
        
        // Optimize: find overbooking level that maximizes (revenue gain - walk cost)
        const optimalLevel = this.optimizeOverbookingLevel(
            inventory,
            historicalRates,
            avgNightlyRate,
            this.costCalculator.getWalkCost(hotelId, date)
        );
        
        return new OverbookingRecommendation({
            date,
            roomTypeId,
            physicalInventory: inventory,
            historicalNoShowRate: expectedNoShows,
            historicalLateCancellationRate: expectedCancellations,
            recommendedOverbooking: optimalLevel.count,
            walkRiskPercentage: optimalLevel.walkRisk,
            expectedRevenueImpact: optimalLevel.netRevenueImpact,
            confidence: historicalRates.sampleSize > 100 ? 'HIGH' : 'MEDIUM',
        });
    }
    
    private optimizeOverbookingLevel(
        inventory: number,
        rates: HistoricalRates,
        avgRate: Money,
        walkCost: Money
    ): OptimalLevel {
        let bestLevel = 0;
        let bestNetRevenue = Money.zero();
        let bestWalkRisk = 0;
        
        // Try each level from 0 to max (e.g., 15% of inventory)
        const maxOverbooking = Math.floor(inventory * 0.15);
        
        for (let level = 0; level <= maxOverbooking; level++) {
            // Expected rooms freed based on historical rates
            const expectedFreed = inventory * (rates.noShowRate + rates.lateCancellationRate);
            
            // If we overbook by 'level', walks occur when freed < level
            // Use normal distribution to calculate probability
            const walkProbability = this.calculateWalkProbability(
                level,
                expectedFreed,
                rates.standardDeviation * inventory
            );
            
            const expectedWalks = level * walkProbability;
            const revenueGain = avgRate.multiply(level * (1 - walkProbability));
            const walkCosts = walkCost.multiply(expectedWalks);
            const netRevenue = revenueGain.subtract(walkCosts);
            
            if (netRevenue.isGreaterThan(bestNetRevenue)) {
                bestLevel = level;
                bestNetRevenue = netRevenue;
                bestWalkRisk = walkProbability;
            }
        }
        
        return {
            count: bestLevel,
            walkRisk: bestWalkRisk,
            netRevenueImpact: bestNetRevenue,
        };
    }
    
    private calculateWalkProbability(
        overbooking: number,
        expectedFreed: number,
        stdDev: number
    ): number {
        // Probability that actualFreed < overbooking
        // Using normal distribution CDF
        const z = (overbooking - expectedFreed) / stdDev;
        return this.normalCDF(z);
    }
    
    private normalCDF(z: number): number {
        // Approximation of standard normal CDF
        const a1 = 0.254829592;
        const a2 = -0.284496736;
        const a3 = 1.421413741;
        const a4 = -1.453152027;
        const a5 = 1.061405429;
        const p = 0.3275911;
        
        const sign = z < 0 ? -1 : 1;
        z = Math.abs(z) / Math.sqrt(2);
        
        const t = 1.0 / (1.0 + p * z);
        const y = 1.0 - (((((a5 * t + a4) * t) + a3) * t + a2) * t + a1) * t * Math.exp(-z * z);
        
        return 0.5 * (1.0 + sign * y);
    }
}
 
/**
 * WalkCostCalculator - determines cost of walking a guest
 */
class WalkCostCalculator {
    calculate(hotelId: HotelId, date: LocalDate, expectedWalks: number): Money {
        // Components of walk cost:
        // 1. Room at alternate hotel (often at premium)
        // 2. Transportation to alternate
        // 3. Compensation (points, future discount)
        // 4. Reputation damage (harder to quantify)
        
        const baseWalkCost = Money.of(300, 'USD'); // Varies by market
        
        // Higher cost during peak periods
        const seasonMultiplier = this.getSeasonMultiplier(date);
        
        return baseWalkCost.multiply(seasonMultiplier).multiply(expectedWalks);
    }
    
    getWalkCost(hotelId: HotelId, date: LocalDate): Money {
        return Money.of(300, 'USD'); // Simplified; would be configurable
    }
    
    private getSeasonMultiplier(date: LocalDate): number {
        // Higher multiplier during holidays, events
        const month = date.monthValue;
        if (month === 12 || month === 7 || month === 8) {
            return 2.0; // Peak seasons
        }
        return 1.0;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214

/**
 * Pattern 1: Optimistic Locking with Version Column
 */
class DailyInventoryWithVersion {
    private readonly id: DailyInventoryId;
    private version: number;  // Incremented on each update
    
    // ... other fields
    
    incrementVersion(): void {
        this.version += 1;
    }
}
 
// Repository with optimistic locking
class OptimisticInventoryRepository {
    async save(inventory: DailyInventoryWithVersion): Promise<void> {
        const originalVersion = inventory.version;
        inventory.incrementVersion();
        
        const result = await this.db.update(
            'daily_inventory',
            { 
                ...inventory.toDbRow(),
                version: inventory.version 
            },
            // WHERE clause includes version check
            { 
                id: inventory.id, 
                version: originalVersion  // Must match original
            }
        );
        
        if (result.rowsAffected === 0) {
            throw new ConcurrentModificationError(
                'Inventory was modified by another process. Please retry.'
            );
        }
    }
}
 
/**
 * Pattern 2: Distributed Locking (for multi-instance deployments)
 */
interface DistributedLockManager {
    acquireLock(key: string, ttlMs: number): Promise<LockHandle>;
    releaseLock(handle: LockHandle): Promise<void>;
    withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
}
 
// Redis-based implementation
class RedisLockManager implements DistributedLockManager {
    private readonly redis: Redis;
    
    async acquireLock(key: string, ttlMs: number): Promise<LockHandle> {
        const lockKey = `lock:${key}`;
        const lockValue = crypto.randomUUID();
        
        // SET NX (only if not exists) with expiration
        const acquired = await this.redis.set(
            lockKey,
            lockValue,
            'NX',
            'PX',
            ttlMs
        );
        
        if (!acquired) {
            throw new LockNotAcquiredError(`Could not acquire lock for ${key}`);
        }
        
        return { key: lockKey, value: lockValue };
    }
    
    async releaseLock(handle: LockHandle): Promise<void> {
        // Lua script for atomic check-and-delete
        const script = `
            if redis.call("get", KEYS[1]) == ARGV[1] then
                return redis.call("del", KEYS[1])
            else
                return 0
            end
        `;
        
        await this.redis.eval(script, 1, handle.key, handle.value);
    }
    
    async withLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
        const handle = await this.acquireLock(key, 10000);  // 10 second TTL
        
        try {
            return await fn();
        } finally {
            await this.releaseLock(handle);
        }
    }
}
 
/**
 * Pattern 3: Atomic Database Operations
 * Using database capabilities for atomic updates
 */
class AtomicInventoryRepository {
    /**
     * Reserve inventory atomically - single SQL statement
     * Returns true if reserved, false if insufficient
     */
    async atomicReserve(
        hotelId: HotelId,
        roomTypeId: RoomTypeId,
        dates: LocalDate[],
        count: number
    ): Promise<boolean> {
        // This uses a CTE to check all dates have availability
        // and updates them atomically
        const result = await this.db.execute(`
            WITH availability_check AS (
                SELECT date, 
                       (sell_limit + overbooking_allowance - confirmed - pending) as available
                FROM daily_inventory
                WHERE hotel_id = $1 
                  AND room_type_id = $2 
                  AND date = ANY($3)
            ),
            can_book AS (
                SELECT MIN(available) >= $4 as bookable
                FROM availability_check
            )
            UPDATE daily_inventory
            SET confirmed = confirmed + $4,
                updated_at = NOW()
            WHERE hotel_id = $1 
              AND room_type_id = $2 
              AND date = ANY($3)
              AND (SELECT bookable FROM can_book) = true
            RETURNING date
        `, [hotelId, roomTypeId, dates, count]);
        
        // If we updated all expected rows, booking succeeded
        return result.rowCount === dates.length;
    }
}
 
/**
 * Pattern 4: Reservation with Expiring Hold
 * Soft-lock inventory with auto-expiration
 */
class InventoryHoldService {
    private readonly redis: Redis;
    private readonly holdTtlSeconds: number = 900;  // 15 minutes
    
    /**
     * Place a temporary hold on inventory
     */
    async placeHold(
        reservationId: ReservationId,
        hotelId: HotelId,
        roomTypeId: RoomTypeId,
        dates: LocalDate[],
        count: number
    ): Promise<InventoryHold> {
        // Store hold in Redis with expiration
        const holdId = crypto.randomUUID();
        const holdData = {
            reservationId,
            hotelId,
            roomTypeId,
            dates: dates.map(d => d.toString()),
            count,
            createdAt: Date.now(),
        };
        
        await this.redis.setex(
            `hold:${holdId}`,
            this.holdTtlSeconds,
            JSON.stringify(holdData)
        );
        
        // Also update pending count in inventory
        // (pending will auto-decrement via background job when hold expires)
        await this.inventoryService.reservePending(
            hotelId, roomTypeId, dates, count
        );
        
        return new InventoryHold({
            holdId,
            expiresAt: Instant.now().plusSeconds(this.holdTtlSeconds),
            ...holdData,
        });
    }
    
    /**
     * Convert hold to confirmed reservation
     */
    async confirmHold(holdId: string): Promise<void> {
        const holdData = await this.redis.get(`hold:${holdId}`);
        if (!holdData) {
            throw new HoldExpiredError('Reservation hold has expired');
        }
        
        const hold = JSON.parse(holdData);
        
        // Convert pending to confirmed
        await this.inventoryService.confirmPending(
            hold.hotelId,
            hold.roomTypeId,
            hold.dates.map(d => LocalDate.parse(d)),
            hold.count
        );
        
        // Delete the hold
        await this.redis.del(`hold:${holdId}`);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166

/**
 * ChannelManager - coordinates inventory across distribution channels
 */
class ChannelManager {
    private readonly channelConnectors: Map<BookingChannel, ChannelConnector>;
    private readonly eventBus: EventBus;
    
    constructor(connectors: ChannelConnector[]) {
        this.channelConnectors = new Map(
            connectors.map(c => [c.channel, c])
        );
        
        // Subscribe to inventory changes
        this.eventBus.subscribe(
            InventoryChangedEvent,
            this.handleInventoryChange.bind(this)
        );
    }
    
    /**
     * Push availability update to all connected channels
     */
    async handleInventoryChange(event: InventoryChangedEvent): Promise<void> {
        const { hotelId, roomTypeId, dates, newAvailability } = event;
        
        // Build ARI (Availability, Rates, Inventory) update
        const ariUpdate = new ARIUpdate({
            hotelId,
            roomTypeId,
            updates: dates.map(date => ({
                date,
                availability: newAvailability.get(date.toString()),
                rateUpdate: null,  // Rates updated separately
            })),
        });
        
        // Fan out to all channels concurrently
        const updatePromises = Array.from(this.channelConnectors.values())
            .filter(c => c.isActive)
            .map(connector => this.pushUpdate(connector, ariUpdate));
        
        // Wait for all, but don't fail entire operation if one channel fails
        const results = await Promise.allSettled(updatePromises);
        
        // Log failures for alerting
        results.forEach((result, index) => {
            if (result.status === 'rejected') {
                this.logChannelFailure(
                    Array.from(this.channelConnectors.keys())[index],
                    result.reason
                );
            }
        });
    }
    
    private async pushUpdate(
        connector: ChannelConnector,
        update: ARIUpdate
    ): Promise<void> {
        try {
            await connector.pushARI(update);
        } catch (error) {
            // Implement retry logic with exponential backoff
            await this.retryWithBackoff(
                () => connector.pushARI(update),
                3,  // max retries
                1000  // initial delay ms
            );
        }
    }
    
    /**
     * Handle booking notification from an OTA
     */
    async handleOTABooking(
        channel: BookingChannel,
        otaReservation: OTAReservationData
    ): Promise<Reservation> {
        // Translate OTA format to our domain
        const reservationData = this.translateFromOTA(channel, otaReservation);
        
        // Create reservation in our system
        const reservation = await this.reservationService.createFromChannel(
            reservationData,
            channel
        );
        
        // Acknowledge to OTA
        const connector = this.channelConnectors.get(channel);
        await connector.acknowledgeBooking(
            otaReservation.otaConfirmationNumber,
            reservation.confirmationNumber
        );
        
        // Note: Inventory was already decremented when we created reservation
        // Channel updates will propagate via the event we raised
        
        return reservation;
    }
    
    /**
     * Handle cancellation notification from OTA
     */
    async handleOTACancellation(
        channel: BookingChannel,
        otaConfirmationNumber: string
    ): Promise<void> {
        // Find our reservation by external reference
        const reservation = await this.reservationRepository.findByExternalRef(
            channel,
            otaConfirmationNumber
        );
        
        if (!reservation) {
            throw new ReservationNotFoundError(
                `No reservation found for OTA ref: ${otaConfirmationNumber}`
            );
        }
        
        // Process cancellation
        await this.reservationService.cancelFromChannel(
            reservation.id,
            'Cancelled via OTA'
        );
        
        // Acknowledge
        const connector = this.channelConnectors.get(channel);
        await connector.acknowledgeCancellation(otaConfirmationNumber);
    }
}
 
/**
 * Interface for OTA/Channel API connectors
 */
interface ChannelConnector {
    channel: BookingChannel;
    isActive: boolean;
    
    // Push updates to channel
    pushARI(update: ARIUpdate): Promise<void>;
    
    // Fetch reservations from channel (for reconciliation)
    fetchReservations(since: Instant): Promise<OTAReservationData[]>;
    
    // Acknowledgments
    acknowledgeBooking(otaRef: string, ourRef: ConfirmationNumber): Promise<void>;
    acknowledgeCancellation(otaRef: string): Promise<void>;
}
 
/**
 * ARI Update structure (industry standard)
 */
interface ARIUpdate {
    hotelId: HotelId;
    roomTypeId: RoomTypeId;
    updates: DateUpdate[];
}
 
interface DateUpdate {
    date: LocalDate;
    availability: number | null;     // Rooms available to sell
    rate: Money | null;              // Price for this date
    minimumStay: number | null;      // LOS restrictions
    closedToArrival: boolean | null;
    closedToDeparture: boolean | null;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

/**
 * ReconciliationService - ensures inventory accuracy
 */
class ReconciliationService {
    private readonly inventoryRepository: DailyInventoryRepository;
    private readonly reservationRepository: ReservationRepository;
    private readonly alertService: AlertService;
    
    /**
     * Full reconciliation for a date range
     */
    async reconcile(
        hotelId: HotelId,
        startDate: LocalDate,
        endDate: LocalDate
    ): Promise<ReconciliationReport> {
        const discrepancies: Discrepancy[] = [];
        const autoFixed: AutoFix[] = [];
        
        // Get all room types for hotel
        const roomTypes = await this.getRoomTypes(hotelId);
        
        for (const roomType of roomTypes) {
            for (const date of this.eachDate(startDate, endDate)) {
                const discrepancy = await this.reconcileDay(
                    hotelId,
                    roomType.id,
                    date
                );
                
                if (discrepancy) {
                    discrepancies.push(discrepancy);
                    
                    // Auto-fix if within threshold
                    if (Math.abs(discrepancy.difference) <= 2) {
                        const fix = await this.autoFix(discrepancy);
                        autoFixed.push(fix);
                    } else {
                        // Alert for manual review
                        await this.alertService.sendReconciliationAlert(discrepancy);
                    }
                }
            }
        }
        
        return new ReconciliationReport({
            hotelId,
            startDate,
            endDate,
            totalDaysChecked: this.dayCount(startDate, endDate) * roomTypes.length,
            discrepanciesFound: discrepancies.length,
            autoFixed: autoFixed.length,
            pendingReview: discrepancies.length - autoFixed.length,
            details: discrepancies,
        });
    }
    
    /**
     * Reconcile a single day's inventory
     */
    private async reconcileDay(
        hotelId: HotelId,
        roomTypeId: RoomTypeId,
        date: LocalDate
    ): Promise<Discrepancy | null> {
        // Count reservations from source of truth
        const reservationCount = await this.reservationRepository.countForDate(
            hotelId,
            roomTypeId,
            date,
            ['CONFIRMED', 'CHECKED_IN']  // Active statuses only
        );
        
        // Get availability record
        const inventory = await this.inventoryRepository.findByDate(
            hotelId,
            roomTypeId,
            date
        );
        
        if (!inventory) {
            return new Discrepancy({
                type: 'MISSING_INVENTORY',
                hotelId,
                roomTypeId,
                date,
                expected: reservationCount,
                actual: 0,
                difference: reservationCount,
            });
        }
        
        // Compare
        if (inventory.confirmedReservations !== reservationCount) {
            return new Discrepancy({
                type: 'COUNT_MISMATCH',
                hotelId,
                roomTypeId,
                date,
                expected: reservationCount,
                actual: inventory.confirmedReservations,
                difference: reservationCount - inventory.confirmedReservations,
            });
        }
        
        return null;  // No discrepancy
    }
    
    /**
     * Auto-fix small discrepancies
     */
    private async autoFix(discrepancy: Discrepancy): Promise<AutoFix> {
        const inventory = await this.inventoryRepository.findByDate(
            discrepancy.hotelId,
            discrepancy.roomTypeId,
            discrepancy.date
        );
        
        const oldValue = inventory.confirmedReservations;
        inventory.confirmedReservations = discrepancy.expected;
        
        await this.inventoryRepository.save(inventory);
        
        // Log the fix for audit
        await this.logReconciliationFix({
            discrepancy,
            oldValue,
            newValue: discrepancy.expected,
            fixedAt: Instant.now(),
            fixedBy: 'SYSTEM_RECONCILIATION',
        });
        
        return new AutoFix({
            discrepancy,
            action: 'UPDATED_INVENTORY',
            oldValue,
            newValue: discrepancy.expected,
        });
    }
}
 
/**
 * Inventory change log for auditing
 * This table enables debugging and reconciliation
 */
interface InventoryChangeLog {
    id: string;
    hotelId: HotelId;
    roomTypeId: RoomTypeId;
    date: LocalDate;
    operation: 'RESERVE' | 'RELEASE' | 'ADJUST' | 'RECONCILE';
    previousValue: number;
    newValue: number;
    delta: number;
    reservationId: ReservationId | null;
    reason: string;
    performedBy: string;  // User ID or 'SYSTEM'
    timestamp: Instant;
}