@voyant-travel/cruises

Opt-in cruises module for OTA, tour-operator, and DMC deployments. Provides the canonical schema, services, and admin/storefront/booking integration for cruise inventory - both self-managed (a tour operator or DMC publishes its own small-scale or specialized cruises) and external (sourced from a registered adapter package).

Cruises are an inventory and operations capability inside the target scenarios, not a separate cruise-line implementation scenario.

See docs/architecture/cruises-module.md for the full design and docs/architecture/cruise-adapter-contract.md for external adapter implementation requirements.

External Adapter Contract

@voyant-travel/cruises exports the provider-neutral CruiseAdapter contract from @voyant-travel/cruises/adapters. Adapter packages register at application startup and keep upstream clients, credentials, and provider-specific mappings outside the framework package.

Install @voyant-travel/cruises-contracts when an external adapter or validation package only needs the cruises/v1 rich content schema, schema version, Zod validator, and inferred content types. Use @voyant-travel/cruises when you also need Drizzle schema, routes, services, booking integration, adapter registry helpers, or runtime content resolution.

Adapter packages can run assertCruiseAdapterCompatibility(...) against a sandbox fixture to verify full SourceRef round-tripping, multi-connection identity, detail lookup, pricing lookup, and booking commit payload handling.

Status

Early development. Phase 1 (canonical schema + core service for self-managed cruises) is in progress.

Domain Events

@voyant-travel/cruises exports stable cruise lifecycle event constants for catalog and search subscribers:

• CRUISE_CREATED_EVENT = cruise.created
• CRUISE_UPDATED_EVENT = cruise.updated
• CRUISE_DELETED_EVENT = cruise.deleted

Each event carries { id }, where id is the local cruise id. Treat the payload as an invalidation trigger and re-read current cruise state before updating downstream indexes.

Agent Tools

Selecting the module contributes provider-neutral Tools for indexed cruise search, cruise/sailing/ship detail, cabin quotes, and the core cruise, sailing, and ship lifecycle. The Tools call the module's services and selected CruiseAdapter implementations; provider-specific calls, search projection maintenance, price-row replacement, and cabin/deck/itinerary mechanics are not exposed.

Read and quote Tools require cruises:read and are available to staff and customer actors. Local lifecycle writes require cruises:write, are staff only, and are ledgered. create_cruise is a handler-owned created-target command: its canonical row, required local search projection, deterministic cruise.created outbox envelope, command ledger, and immutable result reference commit in one transaction. Exact idempotency replays return that reference; reuse with different input conflicts. Booking creation is intentionally absent until the cruise vertical owns a durable admitted command. Archive/delete and party booking operations remain outside the Tool surface.