@openseat/booking

HTTP status, when there was a response.

For SEATS_UNAVAILABLE: which of the requested seats were taken.

For AREA_SOLD_OUT: inventory IDs of the areas that could not be held.

Whether retrying the same request (with the same idempotency key) can succeed.

What the buyer calls it: "Gold", "Section 102", "Booth B8", "Table T3".

"seated" or "standing" for zones; null for booths and tables.

Availability in words: "12 left", "sold out", "unavailable", or null when unknown.

Full sentence for screen readers: "Gold, Gold tier, ₹1,500, seated, 12 left".

Whole number of units, at least 1.

Units that can still be held: 0 when sold out or not for sale.

Total units for this event, when the host reports it.

Monotonic version, with the same meaning as on seat records.

Layout object ID of the area, zone section, booth or table.

Host inventory key: the GA area's or booth's inventoryId, the table's object ID, or a zone section's own ID.

"ga" for every zone (GA areas and zone sections): sold by quantity.

"section" for a zone section; absent for every other area.

True for a seated zone (a GA area with seating: "seated" and every zone section): the buyer picks a quantity and is seated at the venue. Absent for standing zones, booths and tables.

GA capacity; a zone section's capacity, else its seat count; 1 for a booth; the number of seats for a table (its capacity when it has none).

The object's category; for a table, the most common category of its seats; for a zone section, its own, else its seats' most common one.

Area quantities in the booking. Optional, since adapters written before areas existed leave it out.

Holds all seats and area quantities, or none. Rejects with SEATS_UNAVAILABLE (listing the seats in unavailableSeatIds) when any seat is taken, AREA_SOLD_OUT (listing unavailableAreaIds) when an area has too few places left, and LIMIT_EXCEEDED when the request is over the per-buyer ticket limit.

Converts a hold into a booking after the host's payment flow succeeds. paymentReference is whatever your payment provider returns; the server must verify it. The SDK never handles card data.

Optional: current hold state, for recovering after a reload.

Optional real-time updates. Return an unsubscribe function. Updates are hints that make the map fresher; they do not make it authoritative.

Optional: availability of GA areas, booths and whole tables (remaining capacity and status). Adapters without it simply do not report areas.

Optional real-time area updates (remaining capacity), like subscribe for seats.

Tickets in the cart: the sum of line quantities.

Sum of line amounts, rounded to 2 decimal places; null when any price is unknown. 0 for an empty cart.

Seats and areas left out because they are not in the layout (or are hidden), or had an invalid quantity.

Selected seats, by public seat ID. All seats of a bookAsWhole table make one table line.

GA places, booths and whole tables, by inventory ID.

Price of one ticket in a category, or undefined when it is not known.

Event statuses, so event-level categories in status records win over the layout's.

When seat lines start with the section. Default "auto": when the layout has more than one section.

What the buyer sees: "Stalls, Row D, Seats 1–4", "Table T3 (8 seats)", "4 × Fan Pit", "Booth B8". Never contains IDs.

Tickets on this line: seats, GA places, 1 for a booth, the seats of a table.

The category's display name, for example "VIP".

Price of one ticket on this line; null when unknown or, for a table, when its seats differ in price.

Price of the whole line; null when any of its prices is unknown.

For the host's code (removing a line, holding): the seats this line covers. Not for display.

For the host's code: the inventory ID of a GA, booth or whole-table line. Not for display.

Area quantities in the hold. Optional, since adapters written before areas existed leave it out.

Server-authoritative expiry (ISO 8601).

Server clock at response time (ISO 8601), used to correct for client clock skew.

Requests a hold of seats and, optionally, area quantities (GA places, booths, whole tables), all or nothing. Either may be empty, not both. Retrying after a retryable failure reuses the same idempotency key. Can be called again after confirmed, released or expired to start the next booking.

Confirms the current hold after the host's payment flow succeeded.

Returns to idle after a booking finished (confirmed), a release, an expiry or a failed hold request, so the UI shows its start state for a new booking. Throws CONFLICT while a request is in flight or a hold is still active: release that first.

Takes over a hold the server already has, for example after a page reload (from adapter.getHold or the host's own "my bookings" answer): the state becomes held with its countdown, or expired when its time is up. Throws CONFLICT while a request is in flight.

Milliseconds until the server releases the hold, by the server's clock. 0 when not held.

Clears timers. Does not release the hold on the server; call release() for that.

Clock, for tests.

Timer functions, for tests.

Idempotency key factory. Defaults to crypto.randomUUID.

Per-buyer ticket limit, checked before asking the adapter: a request over it fails with LIMIT_EXCEEDED ("You can buy up to 10 tickets.") and nothing is sent. Seats, GA places and booths count one each.

The layout, so a whole table counts its seats towards maxTickets instead of 1.

GA places, booths and whole tables to hold together with the seats, all or nothing. Omitted (or empty) for a seats-only hold, which is all that adapters written before areas existed understand.

Same key for retries of the same attempt. The server must return the original result for a repeated key instead of creating a second hold.

Kept as given; generated when left out.

Starting statuses. Records for area keys (a GA area's or booth's inventoryId, or a whole table's ID) set the area instead: "blocked" makes it not for sale, so it can never be held; "held" or "booked" sell out what is left.

The layout, so zones (GA areas and zone sections, capacity from the layout), booths (capacity 1) and bookAsWhole tables (one unit backed by their seats) can be held. The seats of zone sections cannot be held on their own: the zone is sold instead.

Capacity per area inventory ID, overriding the layout's or adding areas without a layout.

Confirmed bookings to seed, so a host ledger can restore them after a reload or re-save.

Per-buyer limit for one hold, counting seats, GA places and booths, and a whole table as its number of seats. Over it, holds fail with LIMIT_EXCEEDED. Default unlimited.

Called after every confirmed booking, for example to append it to a host ledger.

How long holds last. Default 10 minutes.

Simulated latency per call. Default 0.

Optional real-time updates. Return an unsubscribe function. Updates are hints that make the map fresher; they do not make it authoritative.

Optional: availability of GA areas, booths and whole tables (remaining capacity and status). Adapters without it simply do not report areas.

Optional real-time area updates (remaining capacity), like subscribe for seats.

Current records by seat ID. A new Map after every change, so it can be used as a React dependency.

Applies records. With replace, the given records become the whole picture (seats not listed are available), as after a full refresh. Records whose version is older than the one already held are ignored. Returns the seat IDs that actually changed.

Abort the request, for example when the component unmounts.

Short label for lists: "Seat 5".

Where the seat is: "Row A, Stalls".

Full sentence for screen readers: "Seat 5, row A, Stalls, VIP, £45, available, wheelchair space".

Seat IDs in reading order: by section, row, then seat order. Seats of zone sections are left out.

Row ID → segments of seat IDs.

Category from the layout. Event statuses may override it.

True when the seat is hidden itself or through a hidden row, table or section, or is in a zone section (see zoneSectionId). Hidden seats are not drawn, focused, listed or selectable.

The zone section (showSeats: false) the seat is in. Such a seat is not sold on its own (the section is sold by quantity), so it is also hidden.

When to start with the section: "auto" (the default) when the layout has more than one section, so "Row A" alone would be ambiguous; "always" whenever the seat is in a section; "never".

Public seat ID from the layout.

Event-level category, overriding the layout's. Pricing tiers often vary by event.

Display-only price text, for example "£45". The SDK never computes prices.

For held seats: when the server will release the hold (ISO 8601).

Monotonic version from the server. When present, an update with a lower version than the one already applied is ignored, so out-of-order real-time messages cannot resurrect stale states.

Optional area availability by inventory ID, to check GA and booth quantities against what is left.

Minimum seats for a valid selection (checked at checkout, not while clicking). Default 1.

Maximum seats. Clicking beyond it is refused. Default unlimited. When area quantities are passed and maxTickets is not set, it limits the total number of tickets instead.

One per-buyer limit across seats, GA places, booths and whole tables (a table counts its seats). When absent, maxSeats applies to the total.

Allow seats from different categories in one selection. Default true.

Only these categories can be selected.

Refuse selections that leave a single available seat stranded between taken or selected seats (or a row end), which is usually unsellable. Checked at checkout, since an orphan is often fixed by the next click.

Seats the violation is about: the unavailable seats, or the stranded seat.

Areas the violation is about, by inventory ID. Only on area violations.

True when the toggle was accepted.

The selection after the toggle (unchanged when refused).