skills/plugins/document-navigator/docs/commerce/booking/booking/README.md

@suaveplan/booking - Universal JSON-configurable booking engine: pluggable availability resolution, conflict detection, pricing pipeline, rule evaluation, configurable status state machine, typed event bus, in-package data-transform Hooks pipeline, six domain presets (seats, accommodation, appointments, resources, activities, transport), Zod validation schemas, and typed BookingError hierarchy with stable BOOKING.* code registry.

Universal, JSON-configurable booking engine with pluggable strategies for availability resolution, conflict detection, pricing calculation, and rule evaluation. Ships six built-in domain presets (seats, accommodation, appointments, resources, activities, transport), a configurable status state machine, a typed lifecycle event bus, an in-package Hooks<TMap> data-transform pipeline, Zod validation schemas, and a typed BookingError hierarchy.

Documentation tree

• resolver — Pluggable availability-resolver registry. The booking engine asks "is this window available?" by delegating to a strate…
  • resolver — Pluggable availability-resolver registry. The booking engine asks "is this window available?" by delegating to a strate…
• strategies — Three built-in AvailabilityStrategyFn implementations covering the three most common booking semantics: `exactMatchSt…
  • strategies — Three built-in AvailabilityStrategyFn implementations covering the three most common booking semantics: `exactMatchSt…
• detector — Provides the pluggable conflict-detection registry used by the booking engine to decide whether a proposed window colli…
  • detector — Provides the pluggable conflict-detection registry used by the booking engine to decide whether a proposed window colli…
• exact-match — Conflict-detection strategy for seat-style bookings where two reservations conflict only when their start AND end times…
  • exact-match — Conflict-detection strategy for seat-style bookings where two reservations conflict only when their start AND end times…
• provider-overlap — Conflict-detection strategy for appointment-style bookings where the constraint is "this provider's calendar." Used for…
  • provider-overlap — Conflict-detection strategy for appointment-style bookings where the constraint is "this provider's calendar." Used for…
• range-overlap — Conflict-detection strategy for accommodation-style bookings where any temporal overlap counts as a conflict. Models ho…
  • range-overlap — Conflict-detection strategy for accommodation-style bookings where any temporal overlap counts as a conflict. Models ho…
• slot-capacity — Conflict-detection strategy for group bookings — meeting rooms, tour groups, activity classes, anything where multiple…
  • slot-capacity — Conflict-detection strategy for group bookings — meeting rooms, tour groups, activity classes, anything where multiple…
• engine — BookingEngine is the booking system's pipeline orchestrator. It composes the registry of bookables, the persistent ma…
  • engine — BookingEngine is the booking system's pipeline orchestrator. It composes the registry of bookables, the persistent ma…
• event-bus — Typed publish/subscribe event bus for booking lifecycle events. The engine emits the 15 standard BookingEventType eve…
  • event-bus — Typed publish/subscribe event bus for booking lifecycle events. The engine emits the 15 standard BookingEventType eve…
• state-machine — Configurable booking-status state machine. Consumers pass an array of StatusTransition rows (from `BookingSystemConfi…
  • state-machine — Configurable booking-status state machine. Consumers pass an array of StatusTransition rows (from `BookingSystemConfi…
• domains — Provides createBaseConfig(tenantId, tenantName) — the canonical default BookingSystemConfig factory that every doma…
  • accommodation — Factory for the accommodation booking domain — hotels, vacation rentals, hostels. Each bookable represents one bookable…
    • accommodation — Factory for the accommodation booking domain — hotels, vacation rentals, hostels. Each bookable represents one bookable…
  • activities — Factory for the activity/tour booking domain — group tours, classes, workshops, group events. Each bookable represents…
    • activities — Factory for the activity/tour booking domain — group tours, classes, workshops, group events. Each bookable represents…
  • appointments — Factory for the appointment booking domain — medical, dental, salon, consulting. Each bookable represents an appointmen…
    • appointments — Factory for the appointment booking domain — medical, dental, salon, consulting. Each bookable represents an appointmen…
  • resources — Factory for the resource booking domain — meeting rooms, equipment, shared vehicles. Each bookable represents a resourc…
    • resources — Factory for the resource booking domain — meeting rooms, equipment, shared vehicles. Each bookable represents a resourc…
  • seats — Factory for the seat-based booking domain — stadiums, theatres, cinemas, flights. Each bookable represents one physical…
    • seats — Factory for the seat-based booking domain — stadiums, theatres, cinemas, flights. Each bookable represents one physical…
  • transport — Factory for the transport booking domain — flights, trains, buses. Each bookable represents a single transport-seat on…
    • transport — Factory for the transport booking domain — flights, trains, buses. Each bookable represents a single transport-seat on…
  • shared — Provides createBaseConfig(tenantId, tenantName) — the canonical default BookingSystemConfig factory that every doma…
• error-codes — Defines the stable error-code registry and typed BookingError class for @suaveplan/booking. Every failure path the…
  • error-codes — Defines the stable error-code registry and typed BookingError class for @suaveplan/booking. Every failure path the…
• hooks — In-package data-transform pipeline used by BookingEngine to give consumers a hook into the create-booking and cancel-…
  • hooks — In-package data-transform pipeline used by BookingEngine to give consumers a hook into the create-booking and cancel-…
• calculator — Implements the booking engine's price-calculation pipeline. calculatePrice is the canonical entry point: it runs base…
  • calculator — Implements the booking engine's price-calculation pipeline. calculatePrice is the canonical entry point: it runs base…
• dynamic — Implements dynamic-pricing rule evaluation. Three trigger types are supported — occupancy_threshold, advance_days,…
  • dynamic — Implements dynamic-pricing rule evaluation. Three trigger types are supported — occupancy_threshold, advance_days,…
• seasonal — Applies seasonal-rate multipliers to a base price based on month/day windows. Supports wrap-around-year intervals (e.g.…
  • seasonal — Applies seasonal-rate multipliers to a base price based on month/day windows. Supports wrap-around-year intervals (e.g.…
• conditions — Pre-built RuleCondition factories for the most common booking constraints — minimum/maximum duration, advance-booking…
  • conditions — Pre-built RuleCondition factories for the most common booking constraints — minimum/maximum duration, advance-booking…
• evaluator — The rules-engine evaluator walks a list of BookingRule[] against an EvaluationContext (booking + bookable + window…
  • evaluator — The rules-engine evaluator walks a list of BookingRule[] against an EvaluationContext (booking + bookable + window…
• booking.schema — Zod validation schemas covering every entity at the booking engine's input boundary — Bookable, Booking, `BookingRe…
• config.schema — Validates the full BookingSystemConfig JSON tree at runtime. The schema mirrors the config.types.ts shape and is th…
• recurrence — Expands RecurrenceRule definitions into concrete TimeWindow[] occurrences across a date range. Supports daily, week…
  • recurrence — Expands RecurrenceRule definitions into concrete TimeWindow[] occurrences across a date range. Supports daily, week…
• slots — Generates and manipulates TimeSlot lists. generateTimeSlots produces fixed-interval slots covering a single `TimeWi…
  • slots — Generates and manipulates TimeSlot lists. generateTimeSlots produces fixed-interval slots covering a single `TimeWi…
• windows — Defines pure functions for reasoning about TimeWindow intervals — overlap, merge, split, containment, adjacency, vali…
  • windows — Defines pure functions for reasoning about TimeWindow intervals — overlap, merge, split, containment, adjacency, vali…
• utils — Shared, dependency-free helpers used across @suaveplan/booking. Every export here is pure, side-effect-free, and runs…
  • utils — Shared, dependency-free helpers used across @suaveplan/booking. Every export here is pure, side-effect-free, and runs…

Install

bun add @suaveplan/booking

Quick start

import { createBookingEngine, createSeatConfig } from "@suaveplan/booking";

const engine = createBookingEngine();
engine.configure(createSeatConfig("arena-1", "Main Arena"));

engine.registerBookable({
 identifierRef: { id: "seat-A12", tenantId: "arena-1", categoryId: "vip" },
 name: "Seat A12",
 description: "Aisle seat",
 bookableType: "seat",
 status: "active",
 layoutNodeRef: null,
 capacityRef: "cap-A12",
 priceRuleRefs: [],
 timeSlotRefs: [],
 attributes: {},
});

const result = engine.checkAvailability({
 bookableRef: "seat-A12",
 windowRef: {
  startTime: "2026-06-01T19:00:00Z",
  endTime: "2026-06-01T22:00:00Z",
  timezone: "UTC",
 },
 quantity: 1,
});
console.log(result.available);

Architecture

Availability → Conflict detection → Pricing → Rules → State machine → Events

Every stage is pluggable via registries (registerDetector, registerAvailabilityStrategy) and the Hooks<BookingHookMap> accessor exposes pre-persistence transform points (booking:creating, booking:cancelling).

Modules

Foundation

Module	Documentation
Error codes (BOOKING_CODES, BookingError)	src/error-codes/error-codes.md
Hooks (in-package Hooks<TMap> pipeline)	src/hooks/hooks.md
Utils (parseDurationMs, …)	src/utils/utils.md

Types

Module	Documentation
Bookable	src/types/bookable.types.md
Booking	src/types/booking.types.md
Booking hooks	src/types/booking-hooks.types.md
Capacity	src/types/capacity.types.md
Config	src/types/config.types.md
Events	src/types/events.types.md
Layout	src/types/layout.types.md
Pricing	src/types/pricing.types.md
Rules	src/types/rules.types.md
Temporal	src/types/temporal.types.md

Temporal

Module	Documentation
Windows	src/temporal/windows/windows.md
Recurrence	src/temporal/recurrence/recurrence.md
Slots	src/temporal/slots/slots.md

Conflict detection

Module	Documentation
Detector registry	src/conflict/detector/detector.md
Exact match	src/conflict/exact-match/exact-match.md
Range overlap	src/conflict/range-overlap/range-overlap.md
Slot capacity	src/conflict/slot-capacity/slot-capacity.md
Provider overlap	src/conflict/provider-overlap/provider-overlap.md

Pricing

Module	Documentation
Calculator	src/pricing/calculator/calculator.md
Seasonal	src/pricing/seasonal/seasonal.md
Dynamic	src/pricing/dynamic/dynamic.md

Rules

Module	Documentation
Evaluator	src/rules/evaluator/evaluator.md
Conditions	src/rules/conditions/conditions.md

Availability

Module	Documentation
Resolver registry	src/availability/resolver/resolver.md
Built-in strategies	src/availability/strategies/strategies.md

Domains

Module	Documentation
Shared base	src/domains/shared.md
Seats	src/domains/seats/seats.md
Accommodation	src/domains/accommodation/accommodation.md
Appointments	src/domains/appointments/appointments.md
Resources	src/domains/resources/resources.md
Activities	src/domains/activities/activities.md
Transport	src/domains/transport/transport.md

Schemas

Module	Documentation
Booking schema	src/schemas/booking.schema.md
Config schema	src/schemas/config.schema.md

Core

Module	Documentation
Booking engine	src/core/engine/engine.md
State machine	src/core/state-machine/state-machine.md
Event bus	src/core/event-bus/event-bus.md

Tree-shaking

Every feature module ships at its own subpath export:

import { windowsOverlap } from "@suaveplan/booking/temporal/windows/windows";
import { calculatePrice } from "@suaveplan/booking/pricing/calculator/calculator";
import { createSeatConfig } from "@suaveplan/booking/domains/seats/seats";

License

MIT — © Suaveplan Team