Proposals

The proposals module (@voyant-travel/proposals) owns the pre-commitment sales plane. A bespoke travel sale starts as a tracked pursuit with a Person or Organization, moves through a series of stages, and produces one or more priced proposals. Proposals is where that pursuit, those proposals, and their decisions live, right up to the moment a client accepts a proposal and the reserve workflow takes over. It sits at the top of the bespoke travel sales chain:

Proposal -> accepted Proposal Version -> Booking Session -> Quote + optional Hold
  -> Commit -> Booking / Component Booking -> Fulfillment

Each step hardens the commitment, and proposals owns the first two. Accepting a Proposal Version is a sales decision, not supplier confirmation: it marks the version accepted, closes the Proposal won, and seeds reservation. It does not by itself confirm suppliers or create a Booking.

“Quote” does not mean a sales pursuit. A Quote is an immutable, expiring, server-produced price and terms result for an exact Booking Session revision. It is a pricing artifact, and it is distinct from a Proposal Version. The sales pursuit is a Proposal. This module was previously called Quotes, and the older meaning still shows up in some code and conversation — the vocabulary above is the current one.

People and organizations are referenced by plain id. This module does not import relationships schema or own any identity lifecycle state.

Key concepts

tracked sales pursuit

A tracked travel sales pursuit with a Person and/or Organization. It moves through stages, owns value, participants, activities, and one or more proposal versions, and may close won or lost. This is the canonical sales pursuit; avoid “opportunity” or “deal”. See Proposal.

immutable proposal revision

An immutable proposal revision or alternative sent to the client. It freezes a Trip Envelope snapshot, pricing, validity, and decision state. Editing a sent version creates another version rather than mutating the one already in the client’s hands. See Proposal Version.

ordered stage set

An ordered set of stages a Proposal moves through. An operator can run several pipelines (for example one for FIT, one for groups). See Pipeline.

pipeline step

A step within a pipeline (for example Qualified, then Proposal, then Negotiation), carrying win and lost flags so the pipeline knows which stages close a proposal. See Stage.

role on the pursuit

A Participant on a proposal: the booker, the decision-maker, the finance contact, or a traveler. Each participant points at a Person by id and carries the role they play on this pursuit.

logged interaction

A logged interaction (call, email, meeting, task, follow-up) recorded against a proposal. Activities give a proposal its history and drive follow-up. See Activity.

proposal contents

Proposal products attach catalog references to the pursuit, and proposal version lines freeze the priced contents of a specific version. Both belong to the proposal side, not to a booking, until a version is accepted.

The proposal lifecycle

A proposal version moves through an explicit status: draft to sent to a decision. A version can only be accepted after it has been sent, and a proposal can hold exactly one accepted version. Sending freezes the proposal; accepting records the decision and closes the pursuit. The proposal itself closes alongside the version decision: accepting a version closes the proposal won, and a proposal can otherwise end lost or archived.

Draft

A version is created in draft and can be revised freely. It carries a frozen Trip Envelope snapshot, pricing, and validity.

Sent

Sending the version (sendProposalVersion) hands it to the client. Once sent, edits create a new version rather than mutating this one.

Accepted

Accepting the version (acceptProposalVersion) marks it accepted, stamps the proposal’s acceptedVersionId, closes the proposal won, and declines the sibling versions on the same proposal. A second accept on a proposal that already has a different accepted version raises a conflict.

Accepting a proposal version is a sales decision, not supplier confirmation. It seeds the reserve workflow but does not by itself guarantee that every live or manual component is confirmed by its supplier. The hardening happens downstream in bookings.

What it owns

Proposals owns the sales pipeline and the proposal artifacts.

Pipelines and stages (./schema), including win and lost flags on stages.
Proposals, their value, owner, status, source, and stage tracking (a stage change stamps stageChangedAt, and closing stamps the close).
Proposal versions, their immutable snapshots, validity, and decision state, plus the accept-and-decline-siblings transaction.
Proposal participants and activities scoped to a proposal.
Proposal products and proposal version lines that hold the proposal contents.
Custom fields on proposals, validated on write against the deployment custom-field registry.
The booking proposal-details extension (./booking-extension): a small booking_crm_details table that links a created Booking back to the proposal and version it came from, so the bookings side can carry provenance without coupling to proposal schema.

It does not own identities, commitments, inventory holds, or money collection. Those belong to relationships, bookings, and the finance module.

Working with it

Standard modules are not registered by hand. @voyant-travel/proposals is part of the standard product graph, so its routes, services, subscribers, and jobs are resolved into the application at build time. See Configuration. Create a pursuit against an existing Person, build a proposal, send it, and accept it.

import { proposalsService } from "@voyant-travel/proposals";

const proposal = await proposalsService.createProposal(db, {
  title: "Henderson family, two weeks in Egypt",
  personId: "pers_01h...",
  pipelineId: "pipe_default",
  stageId: "stage_qualified",
});

const version = await proposalsService.createProposalVersion(db, {
  proposalId: proposal.id,
  // freezes a Trip Envelope snapshot, pricing, and validity
});

await proposalsService.sendProposalVersion(db, version.id);

// The client says yes. Accept closes the proposal won and declines siblings.
const result = await proposalsService.acceptProposalVersion(db, version.id);
// result.proposalVersion.status === "accepted"
// result.proposal is closed won; result.closedProposalVersions lists declined siblings

Record the touches that move a deal, and add the people who matter on it.

await proposalsService.createProposalParticipant(db, proposal.id, {
  personId: "pers_01h...",
  role: "decision_maker",
});

A proposal can hold only one accepted version. Calling acceptProposalVersion on a version that has not been sent, or on a proposal that already accepted a different version, raises a ProposalVersionConflictError rather than silently overwriting the decision.

Links to other modules

relationships owns the People and Organizations a proposal points at by id. Proposal panels surface on person and organization detail pages.
bookings consumes the accepted proposal version: its Booking Origin records accepted_proposal_version and the version id, and the booking_crm_details extension links the booking back to its proposal.
trips is the shape a proposal version’s Trip Envelope snapshot mirrors when the proposal composes several components.
The finance and legal modules attach invoices, contracts, and policy acceptances against a proposal version once it is accepted.

React package

@voyant-travel/proposals-react provides hooks (useProposals, useStages, and the version and participant equivalents), query keys, the VoyantProvider, and reusable UI including ProposalsBoard for a stage-by-stage pipeline view. Proposals are represented by ids on proposal records, so person and organization UI comes from @voyant-travel/relationships-react. Styled components require the optional @voyant-travel/ui peer.

Next steps

Relationships

The CRM core that owns the People and Organizations a proposal pursues.

Bookings

Where an accepted proposal version becomes a durable commitment through reserve.

Trips

The Trip Envelope shape a multi-component proposal composes and freezes.

Glossary

The shared vocabulary: Proposal, Proposal Version, Pipeline, Stage, and the commitment chain.

Overview

Domain modules

Surfaces

Key concepts

The proposal lifecycle

What it owns

Working with it

Links to other modules

React package

Next steps

Relationships

Bookings

Trips

Glossary

​Key concepts

​The proposal lifecycle

​What it owns

​Working with it

​Links to other modules

​React package

​Next steps

Relationships

Bookings

Trips

Glossary

Key concepts

The proposal lifecycle

What it owns

Working with it

Links to other modules

React package

Next steps