Trips

​

Key concepts

​

How independent commitments group into one itinerary

• Independent commitments become sibling component bookings. A customer-composed addition with its own supplier, its own cancellation rules, and its own fulfillment state is a sibling Component Booking under the same Trip Envelope. Cancelling it previews and executes against that component alone.
• Dependent parts stay nested. Product-internal bundles and dependent Extras stay inside their component booking. They share that component’s lifecycle and are cancelled, fulfilled, taxed, and supported with it.
• A Cruise Extension is decided by the same rule. Its catalog definition may be reused across cruises, but the selected extension is an Extra when cruise-owned and lifecycle-dependent, or a sibling component when independently supplied and confirmed.

​

The envelope lifecycle

​

What it owns

• The durable schema (./schema): trip envelopes, trip components, component events, trip snapshots, and trip reservation plans.
• The deterministic trip service (./service): create, get, list, add and update and reorder components, and update component refs.
• Price aggregation (priceTrip) that rolls component prices into one envelope total, and applyQuoteToComponent.
• The reserve workflow (reserveTrip) that runs across components and produces a reservation plan.
• Checkout handoff (startCheckout, completeTripCheckout), dependency-injected so the runtime owns payment, bank transfer, and storefront URL policy.
• Component-level cancellation (previewCancellation, cancelComponents), so support can preview and cancel one component without touching siblings.
• Cruise Extension helpers (./cruise-extension) and a catalog component adapter (./catalog-component-adapter) that maps catalog entities into trip components.
• MCP tools (./mcp-tools): AI-safe trip planning, revision, pricing, and reserve operations.

​

Dynamic assembly: requirements and candidates

• A Trip Requirement (tripRequirements) is an unresolved need: a vertical plus criteria. Its status walks open to sourcing to candidates_ready to selected, or no_availability.
• Trip Candidates (tripCandidates) are persisted, ranked AvailabilityCandidate rows under a requirement, each with a TTL; status is ranked, selected, expired, or discarded.
• sourceRequirementCandidates runs the catalog availability fan-out (injected through deps.search, so trips never imports a catalog adapter) and persists the ranked candidates. selectCandidate pins one into a draft component, enforcing selected-uniqueness. reshopRequirement and reshopTrip re-source when supply goes stale, and expireStaleTripCandidates is a TTL reaper for a deployment cron.
• The candidate’s candidateRef is not replay-safe: priceTrip re-resolves the selection and reserveTrip re-validates before any supplier dispatch, gated by assertEnvelopeRequirementsSatisfied.

​

Working with it

import { createTrip, addComponent, priceTrip, reserveTrip } from "@voyant-travel/trips";

const trip = await createTrip(db, {
  personId: "pers_01h...",
});

// Each component is an independent commitment under the one envelope.
await addComponent(db, trip.id, {
  kind: "stay",
  // catalog reference and dates
});
await addComponent(db, trip.id, {
  kind: "flight",
});

// Aggregate the component prices into one envelope total.
const priced = await priceTrip(db, trip.id);

// Reserve runs across components and produces a reservation plan.
const plan = await reserveTrip(db, trip.id /* ...injected policy */);

import { previewCancellation, cancelComponents } from "@voyant-travel/trips";

const preview = await previewCancellation(db, trip.id, {
  componentIds: ["trcp_01h..."],
});

// Execute only the previewed components; siblings are untouched.
await cancelComponents(db, trip.id, {
  componentIds: ["trcp_01h..."],
});

​

Links to other modules

• bookings owns each Component Booking’s commitment truth. A booking’s origin can point at the trip snapshot the envelope froze.
• proposals produces proposal versions whose Trip Envelope snapshot mirrors a composed itinerary; reserve crosses from accepted version into component reservation.
• catalog is the source the catalog component adapter maps into trip components, so owned and sourced inventory compose into one envelope.
• The cruises vertical pairs with the Cruise Extension helpers to decide whether an extension nests as an Extra or splits into a sibling component.
• The finance module collects against the envelope’s checkout while each component keeps its own tax treatment.

​

React package

​

Next steps