feat(booking-engine): add request-first booking workflow

CONTEXT.md

@@ -0,0 +1,44 @@
+# Domain glossary
+
+## Booking Request
+
+A guest's request for the property to review a sellable stay before deciding
+whether to create a reservation. A Booking Request does not reserve inventory.
+
+## Request Mode
+
+A direct-booking mode in which submitting the guest form creates a Booking
+Request instead of a reservation.
+
+## Waitlist Entry
+
+Non-deducting demand recorded when the requested stay is not currently
+available. A Waitlist Entry is not a Booking Request.
+
+## Quote Snapshot
+
+The immutable record of the offer shown when a Booking Request was submitted.
+Later prices and accepted prices do not rewrite this record.
+
+## Accepted Price
+
+The stay price chosen by staff when accepting a Booking Request. It can match
+the Quote Snapshot, the current authoritative quote, or a justified custom
+price.
+
+## Payment Plan
+
+A staff-managed set of expected partial payments. A Payment Plan can express
+amounts or percentages and due milestones, but never initiates a payment by
+itself.
+
+## Payment Movement
+
+An attempted or completed movement of money, either through the configured
+card gateway or recorded after taking place outside HAIP.
+
+## Stay Amendment
+
+An audited change to an accepted reservation, such as extending its departure
+date. A Stay Amendment does not rewrite the original Booking Request or its
+Accepted Price.

README.md

@@ -14,7 +14,7 @@
   <img src="https://img.shields.io/badge/NestJS-framework-E0234E?logo=nestjs&logoColor=white" alt="NestJS" />
   <img src="https://img.shields.io/badge/PostgreSQL-database-4169E1?logo=postgresql&logoColor=white" alt="PostgreSQL" />
   <img src="https://img.shields.io/badge/License-Apache%202.0-blue" alt="Apache 2.0 License" />
-<img src="https://img.shields.io/badge/Tests-1568%20passing-brightgreen" alt="1568 Tests Passing" />  <img src="https://img.shields.io/badge/AI%20Agents-12%20built--in-blueviolet" alt="12 AI Agents" />
+<img src="https://img.shields.io/badge/Tests-2235%20passing-brightgreen" alt="2235 Tests Passing" />  <img src="https://img.shields.io/badge/AI%20Agents-12%20built--in-blueviolet" alt="12 AI Agents" />
 </p>
 
 <p align="center">
@@ -510,7 +510,7 @@ Operator notes for activating existing adapters, metasearch landings on the dire
 | OTA Channels | Booking.com + Expedia (EQC) + SiteMinder + DerbySoft | Direct + aggregated OTA connectivity (ARI + content) |
 | XML Processing | fast-xml-parser | Booking.com OTA XML protocol |
 | Package Manager | pnpm workspaces | Monorepo management |
-| Testing | Vitest (1568 tests across 218 test files) | Unit and integration tests || Build | tsup (packages) + Vite (dashboard) + nest build (API) | Fast builds |
+| Testing | Vitest (2235 passing tests across 259 files with passing tests) | Unit and integration tests || Build | tsup (packages) + Vite (dashboard) + nest build (API) | Fast builds |
 | Containers | Docker + docker-compose | Local dev and production deployment |
 | CI/CD | GitHub Actions | Automated testing, builds, and releases |
 
@@ -642,7 +642,7 @@ Before going live, verify the items in [`docs/deployment.md`](./docs/deployment.
 ### Run tests
 
 ```bash
-# All tests (1568 tests across 218 test files)
+# Passing-test count: 2235 test cases across 259 files (skipped excluded)
 
 # API tests only
 pnpm --filter @telivityhaip/api test
@@ -1190,7 +1190,7 @@ HAIP is built in public and contributions are welcome.
 pnpm install          # Install dependencies
 pnpm build            # Build all workspace packages
 pnpm dev              # Start API in dev mode (hot reload)
-pnpm test             # Run all tests (1568 tests, 218 files)
+pnpm test             # Run all tests (2235 passing, 259 files with passes; skipped excluded)
 pnpm lint             # ESLint
 ```
 

apps/api/package.json

@@ -42,6 +42,7 @@
     "fast-xml-parser": "^5.5.10",
     "jsonwebtoken": "^9.0.3",
     "jwks-rsa": "^4.0.1",
+    "nodemailer": "^9.0.5",
     "passport": "^0.7.0",
     "passport-jwt": "^4.0.1",
     "postgres": "^3.4.5",

apps/api/src/app.module.ts

@@ -35,6 +35,7 @@ import { PolicyModule } from './modules/policy/policy.module';
 import { GroupsModule } from './modules/groups/groups.module';
 import { AdminModule } from './modules/admin/admin.module';
 import { BookingEngineModule } from './modules/booking-engine/booking-engine.module';
+import { BookingRequestModule } from './modules/booking-request/booking-request.module';
 import { ImportModule } from './modules/import/import.module';
 import { MigrationModule } from './modules/migration/migration.module';
 import { AccountingExportModule } from './modules/accounting-export/accounting-export.module';
@@ -59,7 +60,7 @@ const imports: any[] = [
     isGlobal: true,
     envFilePath: ['.env.local', '.env'],
   }),
-  EventEmitterModule.forRoot(),
+  EventEmitterModule.forRoot({ wildcard: true }),
   DatabaseModule,
   HealthModule,
   PropertyModule,
@@ -90,6 +91,7 @@ const imports: any[] = [
   GroupsModule,
   AdminModule,
   BookingEngineModule,
+  BookingRequestModule,
   ImportModule,
   MigrationModule,
   AccountingExportModule,

apps/api/src/common/accepted-pricing/accepted-reservation-service.ts

@@ -0,0 +1,49 @@
+import type { AcceptedPricingSnapshot } from '@telivityhaip/database';
+
+export type AcceptedReservationServiceCandidate = {
+  id: string;
+  serviceId: string;
+  status?: string | null;
+  sourceChannel?: string | null;
+  createdAt?: Date | string | null;
+};
+
+function createdAtValue(value: Date | string | null | undefined): number {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === 'string') {
+    const parsed = Date.parse(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return Number.MAX_SAFE_INTEGER;
+}
+
+/**
+ * Match each snapshot service to exactly one operational row. Booking Request
+ * acceptance creates `booking_engine` rows; later front-desk duplicates are
+ * legal extras and must never duplicate or resurrect that accepted component.
+ * The time/id fallback makes legacy rows deterministic when provenance is absent.
+ */
+export function matchAcceptedReservationServiceRows<
+  T extends AcceptedReservationServiceCandidate,
+>(
+  pricing: Pick<AcceptedPricingSnapshot, 'services'> | null | undefined,
+  rows: readonly T[],
+): Map<string, T> {
+  const matched = new Map<string, T>();
+  if (!pricing) return matched;
+
+  for (const service of pricing.services) {
+    const candidates = rows
+      .filter((row) => row.serviceId === service.serviceId)
+      .sort((left, right) => {
+        const provenance = Number(right.sourceChannel === 'booking_engine')
+          - Number(left.sourceChannel === 'booking_engine');
+        if (provenance !== 0) return provenance;
+        const created = createdAtValue(left.createdAt) - createdAtValue(right.createdAt);
+        return created !== 0 ? created : left.id.localeCompare(right.id);
+      });
+    if (candidates[0]) matched.set(service.serviceId, candidates[0]);
+  }
+
+  return matched;
+}

apps/api/src/common/crypto/confirmation-number.spec.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it, vi } from 'vitest';
+import { generateConfirmationNumber } from './confirmation-number';
+
+describe('generateConfirmationNumber', () => {
+  it('uses a 128-bit cryptographic entropy seam and a non-enumerable shape', () => {
+    const entropy = vi.fn((bytes: number) => Buffer.alloc(bytes, 0xa5));
+
+    const confirmation = generateConfirmationNumber(entropy);
+
+    expect(entropy).toHaveBeenCalledWith(16);
+    expect(confirmation).toMatch(/^HAIP-[0-9A-HJKMNP-TV-Z]{32}$/);
+  });
+});

apps/api/src/common/crypto/confirmation-number.ts

@@ -0,0 +1,21 @@
+import { randomBytes } from 'node:crypto';
+
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+export type ConfirmationEntropy = (bytes: number) => Uint8Array;
+
+/** A guest-facing bearer credential backed by exactly 128 bits of entropy. */
+export function generateConfirmationNumber(
+  entropy: ConfirmationEntropy = randomBytes,
+): string {
+  const bytes = entropy(16);
+  if (bytes.length !== 16) {
+    throw new Error('Confirmation entropy source must return 16 bytes');
+  }
+  let token = '';
+  for (const byte of bytes) {
+    token += CROCKFORD[byte & 0x1f];
+    token += CROCKFORD[(byte >> 5) & 0x1f];
+  }
+  return `HAIP-${token}`;
+}