# @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.

<!-- begin:auto-docs -->
## Documentation tree

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

## Install

```bash
bun add @suaveplan/booking
```

## Quick start

```ts
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

```text
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](src/error-codes/error-codes.md) |
| Hooks (in-package `Hooks<TMap>` pipeline) | [src/hooks/hooks.md](src/hooks/hooks.md) |
| Utils (`parseDurationMs`, …) | [src/utils/utils.md](src/utils/utils.md) |

### Types

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

### Temporal

| Module | Documentation |
|---|---|
| Windows | [src/temporal/windows/windows.md](src/temporal/windows/windows.md) |
| Recurrence | [src/temporal/recurrence/recurrence.md](src/temporal/recurrence/recurrence.md) |
| Slots | [src/temporal/slots/slots.md](src/temporal/slots/slots.md) |

### Conflict detection

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

### Pricing

| Module | Documentation |
|---|---|
| Calculator | [src/pricing/calculator/calculator.md](src/pricing/calculator/calculator.md) |
| Seasonal | [src/pricing/seasonal/seasonal.md](src/pricing/seasonal/seasonal.md) |
| Dynamic | [src/pricing/dynamic/dynamic.md](src/pricing/dynamic/dynamic.md) |

### Rules

| Module | Documentation |
|---|---|
| Evaluator | [src/rules/evaluator/evaluator.md](src/rules/evaluator/evaluator.md) |
| Conditions | [src/rules/conditions/conditions.md](src/rules/conditions/conditions.md) |

### Availability

| Module | Documentation |
|---|---|
| Resolver registry | [src/availability/resolver/resolver.md](src/availability/resolver/resolver.md) |
| Built-in strategies | [src/availability/strategies/strategies.md](src/availability/strategies/strategies.md) |

### Domains

| Module | Documentation |
|---|---|
| Shared base | [src/domains/shared.md](src/domains/shared.md) |
| Seats | [src/domains/seats/seats.md](src/domains/seats/seats.md) |
| Accommodation | [src/domains/accommodation/accommodation.md](src/domains/accommodation/accommodation.md) |
| Appointments | [src/domains/appointments/appointments.md](src/domains/appointments/appointments.md) |
| Resources | [src/domains/resources/resources.md](src/domains/resources/resources.md) |
| Activities | [src/domains/activities/activities.md](src/domains/activities/activities.md) |
| Transport | [src/domains/transport/transport.md](src/domains/transport/transport.md) |

### Schemas

| Module | Documentation |
|---|---|
| Booking schema | [src/schemas/booking.schema.md](src/schemas/booking.schema.md) |
| Config schema | [src/schemas/config.schema.md](src/schemas/config.schema.md) |

### Core

| Module | Documentation |
|---|---|
| Booking engine | [src/core/engine/engine.md](src/core/engine/engine.md) |
| State machine | [src/core/state-machine/state-machine.md](src/core/state-machine/state-machine.md) |
| Event bus | [src/core/event-bus/event-bus.md](src/core/event-bus/event-bus.md) |

## Tree-shaking

Every feature module ships at its own subpath export:

```ts
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