seatlayer 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 841def7560b63781babf931924a29204c724ba5b4513eff1de283a370cb22699
-  data.tar.gz: 7027c38a8aeeee9aa5c339d90d04b33c4d708e47362687951d30dc280402bef4
+  metadata.gz: 2e7f487c6f37918712d5b9ad4967aefb979b5bbd85368cd1c669b3718837c19d
+  data.tar.gz: 1a350dcf149a427a410faf436a39ab8b4ada55a8a262956513316b7531a52b65
 SHA512:
-  metadata.gz: 2ef313b0db74c36aef5d0f512264586448d99330e1257c8a28b835da54a7b539fd3f9ab7183a91ae912cf1e55ec2c5dcede861260d80b77a4ed0eaaa6d1faaba
-  data.tar.gz: e85e01d772d6639a36d7fa7154a062d60564fbbe750258c1080fa4f7cc17eba25277ebc0e7e31ad0f04589b9d716402c486c6c325b3d202e7c7fd2ed9e96c903
+  metadata.gz: a1c8d7522480ed8f26c1858ad590fed53146a2d672fa698d4ac07009978f6cacb73ce63a9d8912ecbbae50439344f7b8117e25d72e307cf323f22d33fcaeafab
+  data.tar.gz: c909fa65b7a98c2e6d03ba1b69a79ee4074a33d4041647fbced2d15d923b40b7385ccabe8ff270fb5c4e90b8664ee0f89bf9adcb8ded0388489f9f1ef81c00ed

data/CHANGELOG.md

@@ -1,5 +1,114 @@
 # Changelog
 
+## 0.9.0 (2026-11-11)
+
+- Season seats: `set_aside_season_block` (`POST /v1/seasons/:key/block`), `retrieve_season_block`
+  and `release_season_block` (`POST /v1/seasons/:key/block/release`). Each write answers "job"
+  and "block"; follow the job with `retrieve_season_bulk_job` (kinds `season_block_set_aside` and
+  `season_block_release`, read by id, not listed). Both writes are retried safely with one
+  Idempotency-Key, generated when none is given.
+- `inventory_mode:` on season create and update (opt a season into season seats), read back on
+  every season (`"inventoryMode"`).
+- Webhook names `season.block.ready` and `season.block.released` (`Webhooks::EVENT_NAMES`, now 58).
+- A season-seats season's date cancel (`create_season_amendment`) or past date
+  (`mark_season_performance_past`) can answer `202` while the date leaves every season seat:
+  `Seasons.date_leave_pending?` recognises it.
+- New refusals come through `SeatLayer::APIError` and its subclasses with `code`:
+  `season_block_not_enabled`, `block_exists`, `block_not_ready`, `season_not_draft_or_active`,
+  `block_selection_empty`, `seat_not_in_block`, `season_block_set_aside`, `season_inventory_locked`,
+  `date_leave_in_progress`.
+  `inventory_mode:` can also answer `season_block_packages` (more than one package),
+  `season_block_on_sale`, `season_block_exists` and `invalid_inventory_mode`. The set-aside can
+  also answer `season_block_packages`, `season_block_one_package`, `plan_not_published`,
+  `season_block_undoing`, `chart_unavailable` and `dates_missing`, and the release
+  `release_mismatch`. On `503 season_busy` or `season_not_configured`, send the same request again.
+
+- A date its season cancelled never opens again: `transition_event_sales` to `testable` or
+  `live` and `reopen` answer `409 season_date_cancelled`, and `update_event_series` with
+  `sales: "on"` leaves it closed as a failed item of the job (`season_date_cancelled`; not in
+  `failedDates`).
+- `create_season_amendment` refuses to move (`reschedule`), postpone or replace a cancelled date,
+  and `mark_season_performance_past` refuses to mark one as taken place:
+  `409 performance_cancelled`.
+- `update_event_series` sends only the prices that change: each date keeps its own price for
+  every category (or tier) left out, so weekend and weekday prices keep their difference.
+- A season's `transferCutoffHours` / `returnCutoffHours` of `nil` means the club default
+  (Settings › Ticket site), or until the date starts when the club has none.
+- `create_holder_transfer` and `create_holder_return` are not stopped by the club's customer
+  switches in Settings › Ticket site; cut-offs still apply.
+- Cancelling a date (`create_season_amendment` with `kind: "cancel"`) voids its tickets as a
+  `date_cancel_void` job, named by `SeatLayer::Seasons.date_cancel_void_job_id(amendment_id)`
+  (`sbj_void_…`); follow it with `retrieve_season_bulk_job`. `season.ticket.voided` says
+  `date_cancelled` for each Season ticket it voids.
+- A Season package holds 2 to 50 dates. `SeatLayer::Seasons.holder_import_rows_per_call(dates)`
+  gives the most rows one `create_season_holder_import` call takes (100 up to 20 dates, 43 at
+  50); a call with more raises `ValidationError` `invalid_rows` with `"maxRows"` in its `body`.
+- `update_season`'s `singleTicketDates` may carry `jobRefused`, why a `season_singles` job could
+  not start; the change stands, and sending `single_tickets: true` again opens any date still
+  not open. An `update_season` retried with its first `idempotency_key:` and
+  `expected_revision:` is not applied twice.
+- An `event_series.create_event_series` given up for its key raises `ConflictError`
+  `create_abandoned` with a message to send it again with a new idempotency key.
+- Added the 39 remaining Fixed Renewable Season operations to `client.seasons` (87 in all):
+  performances, package edits and prices, publishing, checkout tests, occurrence returns and
+  reclaims, holders, Season order refunds and cancellations, hosted renewals, renewal quotes,
+  intents and checkouts, the sales,
+  seats and seat-count reports, and bulk refunds and lapsed-offer releases with their jobs.
+- Added three resources: `client.holders` (holders, customers, holder tickets and ticket
+  transfers), `client.orders` (account and event orders, refunds, cancellations and ticket
+  resends) and `client.event_series` (plan, read, extend and update an event series).
+- Added `holders.create_holder_return`: give back a holder's seat on one date, one per ticket.
+- Added the event sales settings to `client.events`: buyer checkout, payment gateway, sales
+  readiness, preflight and transition, booking fee, and discount codes.
+- `export_season_holders_csv`, `export_season_orders_csv` and `orders.export_event_orders_csv`
+  return the raw CSV text. `delete_season_plan` and `events.delete_event_discount_code` return
+  an empty Hash (the API answers 204).
+- 27 of the new operations use exact header replay (41 in the SDK now) and retry with one
+  `Idempotency-Key`; every other new mutation is single-attempt.
+- `Webhooks::EVENT_NAMES` adds `series.created`, `series.dates_added`, `order.paid`,
+  `order.refunded`, `order.cancelled`, `customer.created`, `customer.email_changed`,
+  `season.ticket.transfer_sent`, `season.ticket.transferred` and
+  `season.ticket.transfer_cancelled`.
+- Added `seasons.refund_season_performance` (refund every order of a cancelled date as a job,
+  with header replay), `seasons.list_season_bulk_jobs`, and `seasons.retrieve_season_bulk_job`.
+- `create_season_amendment` takes `refund:` and `reason:`, for the new `postpone` and `cancel`
+  kinds.
+- `update_season` takes `checkout_mode:`, `transfer_cutoff_hours:`, and `return_cutoff_hours:`
+  (`nil` sends an explicit null).
+- `replace_season_package_prices` documents `"priceTypeKey"` on each price, and
+  `create_season_holder_import` documents `"holderEmail"` and `"holderName"` on each row.
+- `Webhooks::EVENT_NAMES` lists all 56 public event names, adding `object.resale.*`,
+  `season.occurrence.*`, `season.performance.*` (including `postponed`, `cancelled`, and
+  `rescheduled`), `season.bulk_action.completed`, `season.order.*`, `season.ticket.issued`,
+  `season.ticket.voided`, and the Season lifecycle, hold, booking, renewal, operation and
+  amendment events.
+- `events.list` and `events.list_all` take `series_key:` to list one event series' dates.
+- Added `seasons.retrieve_season_renewal_quote`: what renewing an offer costs, and whether SeatLayer checkout can take it now.
+- Added `seasons.create_season_renewal_intent`: record a holder's intent for a renewal taken by phone or at the box office, so your own checkout can commit.
+- Added `seasons.create_season_renewal_checkout`: a SeatLayer checkout that renews an offer with no hosted page, with header replay.
+- Added `holders.create_holder_renewal_checkout`: the same checkout for one of a holder's offers, with header replay.
+- Added `holders.decline_holder_renewal_offer`: decline one of a holder's offers, with an optional `reason:`.
+- `seasons.decline_season_renewal_offer` takes an optional `reason:`, kept on the offer as `declineReason`.
+- `update_season` takes `audience:` (`"embed_only"` or `"public"`).
+- `open_season_sales` answers `warnings` (`checkout_test_missing` until a checkout test or rehearsal has passed) and can refuse with `409 plan_not_published` or `409 checkout_mode_not_chosen`.
+- A cancelled date refunds per date only: an amendment's `refund:` is `"none"` or `"per_date"`, and `refund_season_performance` takes `amount: "per_date"` (`full` answers `422 date_refund_per_date_only`; refund a whole order with the order refund).
+- `add_event_series_dates` takes `retry_failed: true` to make the failed dates again (`409 series_busy`, `422 nothing_to_retry`).
+- `list_orders` takes `holder_ref:`; orders carry `holderRef` and `customerId`, and the buyer's email can be nil (a box office sale with no email).
+- Season holds, give-backs and date cancels can refuse with `performance_cancelled`, `refund_not_started` (503), `missing_manage_capability` (403) or `invalid_refund`; a holder's status can be `reserved`; hosted renewal readiness carries `missingPrices`.
+- `create_event_series` takes `from_event_key:`: an event you already set up becomes the first date under its own key, and every other date is a copy of it. `name:` and `chart_key:` are then left out. It refuses with `404 event_not_found`, or `422 event_has_no_date`, `event_in_season`, `event_in_performance_group`, `event_in_series` or `invalid_request`.
+- Every date of an event series carries the series' plain name (`Hamlet`, not `Hamlet · 3 Nov`); tell dates apart by `startsAt`. `update_event_series` renames each date that carries the series name, and a series name cannot hold `{n}`, `{date}` or `{time}`.
+- Added `seasons.release_season_lapsed_offers`: release the seats of every lapsed renewal offer as a job (`202 {"job"}`), with header replay. An offer extended before its turn is skipped and keeps its seat. It can refuse with `503 job_busy` or `season_not_configured`; send it again.
+- `retrieve_season_hosted_renewals` and `list_season_renewal_offers` take `cursor:` and `limit:` (1 to 500 and 1 to 100) and answer one page, newest first, with `nextCursor` (nil on the last page); a bad cursor or limit is refused with `400 invalid_cursor` or `invalid_limit`.
+- `create_season_renewal_offers` answers `201 {"offers"}` for 100 contracts or fewer, and `202 {"job", "batchId"}` above that: a `renewal_run` job makes the offers. Follow it with `retrieve_season_bulk_job`, then page the offers with `list_season_renewal_offers`.
+- `create_season_holder_import_from_season` answers `202 {"job"}` when a commit brings across more than 100 holders: a `holder_import` job, whose `summary` has the same counts once it completes. It and `create_season_renewal_offers` can refuse with `409 job_mismatch` or `503 season_not_configured`, and the bring-across also with `503 job_busy`.
+- `create_season_renewal_notices` takes up to 20,000 `offer_ids:`; more is refused with `422 too_many_offer_ids`.
+- `create_season_renewal_notices` takes `batch_id:` instead of `offer_ids:`: email every open offer one `create_season_renewal_offers` batch made, such as the batch a `renewal_run` job made.
+- Single tickets on a season: `create_season` and `update_season` take `single_tickets:` (default `false`, Season only; anything else is refused with `422 invalid_single_tickets`). Every season read carries `singleTickets`, and a season on sale may carry `singleTicketsNotOpen`. `update_season`, `open_season_sales` and `resume_season_sales` answer `singleTicketDates` (`direction`, `opened`, `closed`, `notOpened`, `jobId`) when they open or stop the dates' own sales; a `season_singles` job does it for more than 12 upcoming dates.
+
+## 0.8.0 (2026-09-10)
+
+- Added Event hosting regions: `region:` on event create, `default_region:` on workspace create and update, and `EVENT_HOSTING_REGIONS` to check a value before it is sent. Events created without a region run in Western Europe.
+
 ## 0.7.0 — 2026-08-30
 
 - Added coverage for all 48 Fixed Renewable Season server

data/README.md

@@ -5,6 +5,8 @@
 [![Ruby](https://img.shields.io/badge/Ruby-%E2%89%A53.0-CC342D.svg)](https://www.ruby-lang.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-111827.svg)](LICENSE)
 
+The official Ruby client for the SeatLayer API. The `seatlayer` gem lets a Ruby or Rails backend inspect seat holds, price orders from server data, book reserved seats and verify webhooks, with no runtime dependencies. SeatLayer is seating chart and reserved-seat ticketing software built for venues up to stadium scale.
+
 SeatLayer's official Ruby server SDK is the trusted side of its reserved seating and seat booking
 API. Inspect what a hold really contains, price from server-owned seating-chart data, and book
 with a stable `booking_ref`, while managing charts, events, inventory, allocations, and webhooks
@@ -17,7 +19,15 @@ through one typed ticketing API client.
 [Server API reference](https://docs.seatlayer.io/server-api/events/)
 
 > **Server-side only.** This gem authenticates with your secret key. Never load it anywhere a
-> ticket buyer can reach — browser surfaces get short-lived, origin-bound tokens that you mint here.
+> ticket buyer can reach. Browser surfaces get short-lived, origin-bound tokens that you mint here.
+
+Two-step shape: the buyer picks and holds seats in the client with your public key, then this SDK confirms the booking from your server with your secret key while your platform keeps checkout and its own payment provider.
+
+**Start here:** [Quickstart](https://docs.seatlayer.io/start/quickstart/) · [Holds and checkout](https://docs.seatlayer.io/buyer-sdk/holds-and-checkout/) · [Ruby server SDK guide](https://docs.seatlayer.io/server-sdk/ruby/) · [SDK catalog](https://docs.seatlayer.io/sdk-catalog.json) · [Pricing](https://seatlayer.io/pricing/): $0 entry, 100 free confirmed-sold-seat credits per organization each month, then $0.10 down to $0.05 a credit, and credits never expire.
+
+## Scale evidence
+
+Benchmarked on public 100,000-, 150,000- and 200,000-seat venue fixtures on 15 September 2026: 200,000 seats chart-ready in 1.95 s, desktop, local production build. Fixtures, method and run logs: https://github.com/seatlayer/seatlayer-performance. Live 200,000-seat stadium demo: https://app.seatlayer.io/demo/play/century-stadium-200k. This is renderer evidence, not a concurrent-buyer claim.
 
 ## Install the Ruby seat booking SDK
 
@@ -29,7 +39,7 @@ gem "seatlayer"
 gem install seatlayer
 ```
 
-Requires Ruby 3.0 or newer. **No runtime dependencies** — `net/http`, `json` and `openssl` from the
+Requires Ruby 3.0 or newer. **No runtime dependencies**: `net/http`, `json` and `openssl` from the
 standard library.
 
 ## Quick start
@@ -76,14 +86,28 @@ Nullable event-create fields distinguish omission from an explicit reset: passin
 
 ## Fixed Renewable Seasons
 
-Version `0.7.0` exposes all 48 trusted organizer operations through
-`client.seasons`.
+`client.seasons` exposes all 87 trusted organizer operations: catalogue and
+package lifecycle, performances, prices (each price hash may name a
+`"priceTypeKey"`: `adult`, `child`, `concession`, `senior` or `student`),
+checkout tests, sales windows, buyer access and booking, holder imports,
+renewals with their quotes, intents and checkouts, occurrences, Season orders, reports and CSV exports, and the bulk
+refund of a cancelled date (`refund_season_performance`) and the release of
+lapsed renewal offers (`release_season_lapsed_offers`) with their jobs
+(`list_season_bulk_jobs`, `retrieve_season_bulk_job`).
+
+Above 100 contracts, `create_season_renewal_offers` answers `202` with
+`{"job", "batchId"}` instead of the offers: follow the `renewal_run` job with
+`retrieve_season_bulk_job`, then page the offers with `list_season_renewal_offers`
+(`cursor:` and `limit:`, until `nextCursor` is nil). A bring-across of more than 100
+holders (`create_season_holder_import_from_season`) answers `202` with a
+`holder_import` job the same way.
 
 After the test hold/book/cancel journey and matching webhook deliveries,
 `validate_season_buyer_rehearsal(season_key)` sends no evidence body; SeatLayer
 discovers the retained chain automatically. Retrieved Season holds contain
-inventory identity, not an authoritative amount—your platform owns package
-price, payment, order, tax, refunds, benefits, and ticket or pass delivery.
+inventory identity, not an authoritative amount. When you sell a Season through
+your own checkout, your platform owns package price, payment, order, tax, refunds,
+benefits, and ticket or pass delivery.
 
 ```ruby
 checked = client.seasons.validate_season(
@@ -101,6 +125,92 @@ returned operation identity. Buyer-session minting and domain-exact booking,
 cancellation, and renewal actions remain single-attempt; only declared
 header-replay catalogue mutations retry automatically.
 
+When SeatLayer takes the Season's payments, renew a holder with no hosted page:
+read the price, start a checkout, and send the holder to `payment.url`. For a
+renewal taken by phone or at the box office, `create_season_renewal_intent`
+records the holder's intent before you commit the offer. A decline can carry the
+holder's reason.
+
+```ruby
+quote = client.seasons.retrieve_season_renewal_quote(season_key, offer_id)
+if quote["problem"].nil?
+  started = client.seasons.create_season_renewal_checkout(
+    season_key, offer_id,
+    return_url: "https://tickets.yourclub.example/renewed",
+    idempotency_key: "renew-#{offer_id}"
+  )
+  redirect_to started.dig("payment", "url")
+end
+
+client.holders.decline_holder_renewal_offer("holder_123", offer_id, reason: "Moving away")
+```
+
+### Season seats
+
+Season seats are the seats a season sets aside on every date before its sales open. A season
+buyer's hold then doesn't have to ask each date, and single-ticket buyers see those seats as
+unavailable. They are off for every season until you pass `inventory_mode: "block"` to
+`create_season` or `update_season`. The season needs one package, and its sales must not have
+opened.
+
+```ruby
+client.seasons.update_season(season_key, expected_revision: revision, inventory_mode: "block")
+
+job = client.seasons.set_aside_season_block(
+  season_key,
+  expected_revision: revision,
+  keep_for_single_tickets: { "sectionIds" => ["sec_family"] }
+).fetch("job")
+while %w[planning running].include?(job["state"])
+  sleep 2
+  job = client.seasons.retrieve_season_bulk_job(season_key, job["jobId"]).fetch("job")
+end
+block = client.seasons.retrieve_season_block(season_key).fetch("block")
+
+# Release unsold season seats to single sale. Leave out at: to release now.
+client.seasons.release_season_block(
+  season_key,
+  expected_revision: block["revision"],
+  scope: { "all" => true },
+  at: "2026-12-01T09:00:00Z"
+)
+```
+
+- On an active season, block mode turns on by itself once every date has the seats, and
+  `season.block.ready` is sent once. On a draft, `publish_season` turns it on.
+  `season.block.released` is sent once a release has run.
+- In block mode, a date cancel (`create_season_amendment`, kind `"cancel"`) or
+  `mark_season_performance_past` first takes the date off every season seat. Until that finishes
+  the answer is a `202`: check it with `SeatLayer::Seasons.date_leave_pending?(answer)`, then send
+  the same request again after `Retry-After`.
+- Refusals come through `SeatLayer::APIError` with `code`, and nothing changes. For example
+  `409 season_block_packages` (more than one package), `409 season_block_on_sale` (sales have
+  opened), or `409 block_not_ready` from `open_season_sales` before block mode is on.
+- A partner's seat on a date (one a sales channel sells there) stays out of the block. It is
+  listed in `block["notFreeOnEveryDate"]` with reason `channel`.
+
+The [Season seats docs](https://docs.seatlayer.io/server-api/seasons/#season-seats) list every refusal.
+
+## Orders, holders, event sales and event series
+
+`client.orders` reads, exports, refunds and cancels the orders SeatLayer took through its own
+checkout; `client.holders` covers Season holders, customers, their tickets and ticket transfers;
+the event sales settings (who takes payment, gateway, booking fee, sales state, discount codes)
+are on `client.events`; and `client.event_series` plans many dates of one show from a schedule.
+The CSV exports return the raw CSV text, not a Hash.
+
+```ruby
+page = client.orders.list_event_orders(event_key, status: "confirmed", limit: 50)
+csv = client.orders.export_event_orders_csv(event_key, status: "confirmed") # a String
+client.orders.refund_event_order(event_key, order_id, amount_minor: 1500)
+
+client.events.transition_event_sales(event_key, to: "live", expected_revision: 4)
+client.event_series.create_event_series(
+  name: "Hamlet", chart_key: chart_key, dry_run: true,
+  schedule: { "rule" => "weekly", "from" => "2027-01-04", "count" => 6, "times" => ["19:30"] }
+)
+```
+
 ## Test vs live
 
 Keys carry their own mode. `sk_test_…` keys can only touch test-mode events and `sk_live_…` only
@@ -118,7 +228,7 @@ failing as a `401` three round-trips later.
 ## Book reserved seats from Ruby
 
 **Buyer picks seats in the browser.** Your frontend holds them; your backend confirms the price and
-books. Never price from what the browser sent you — `retrieve_hold` is authoritative.
+books. Never price from what the browser sent you: `retrieve_hold` is authoritative.
 
 ```ruby
 hold = client.inventory.retrieve_hold(event_key, hold_id)
@@ -136,7 +246,7 @@ client.inventory.book(event_key, hold_id: hold_id, booking_ref: charge.id)
 **Your backend picks the seats.** Phone orders, box office, comps.
 
 ```ruby
-# Payment already taken — book outright, so nothing is stranded if a second call fails.
+# Payment already taken: book outright, so nothing is stranded if a second call fails.
 client.inventory.book_best_available(event_key, qty: 2, booking_ref: "phone-1183")
 
 # Or name the seats yourself.
@@ -167,7 +277,7 @@ pause/archive controls, audit-safe session listing, and channel reports are on
 ## Listing and pagination
 
 `list` returns one page plus a `nextCursor`. `list_all` pages for you and returns a lazy
-`Enumerator` when no block is given — the point of paginating is to *not* hold an unbounded result
+`Enumerator` when no block is given, because the point of paginating is to *not* hold an unbounded result
 set in memory, so `.lazy.first(n)` stops fetching once it has enough.
 
 ```ruby
@@ -181,28 +291,30 @@ client.events.list_all do |event|
   sync(event)
 end
 
-# Lazily — this fetches one page, not all of them.
+# Lazily: this fetches one page, not all of them.
 client.charts.list_all.lazy.first(5)
 ```
 
 Listing events includes live availability `counts` by default, which costs the server one
-round-trip **per event**. `list_all` turns them off automatically — walking a whole catalogue is
-exactly when you don't want that — and you can control it explicitly:
+round-trip **per event**. `list_all` turns them off automatically, since walking a whole catalogue is
+exactly when you don't want that, and you can control it explicitly:
 
 ```ruby
 client.events.list(limit: 50, counts: false)
 ```
 
+Pass `series_key: "ser_1"` to list only the dates of one event series.
+
 ## Keeping a hold alive
 
-When an order takes longer than the checkout window — an invoice, a phone sale — extend rather than
+When an order takes longer than the checkout window (an invoice, a phone sale), extend rather than
 release and re-hold. Releasing first hands the seats to whoever is racing for them in between.
 
 ```ruby
 begin
   client.inventory.extend_hold(event_key, hold_id, ttl_ms: 10 * 60_000)
 rescue SeatLayer::ConflictError
-  # Gone, expired, or at its renewal cap — the buyer has to re-pick.
+  # Gone, expired, or at its renewal cap: the buyer has to re-pick.
 end
 ```
 
@@ -240,8 +352,8 @@ The full set, all opt-in:
 | `event:door:checkin` | Check tickets in and out |
 | `event:boxoffice` | Use the managed box-office surface |
 
-The two `event:channels:*` capabilities are **not** in the default — a token minted before sales
-channels existed must not silently acquire channel authority — so ask for them explicitly if the
+The two `event:channels:*` capabilities are **not** in the default (a token minted before sales
+channels existed must not silently acquire channel authority), so ask for them explicitly if the
 page manages channels.
 
 Designer minting returns the API envelope unchanged: read the token and effective safe-mode and
@@ -251,7 +363,7 @@ feature policy under `result["session"]`. Pass `safe_mode_options` only with `mo
 
 Subscription responses use the wire envelopes exactly: `list` returns `{"subs" => [...]}`,
 `create` returns `{"sub" => ..., "secret" => ...}` (the secret is shown once), and `update`
-returns `{"sub" => ...}`. `SeatLayer::Webhooks::EVENT_NAMES` is the exact eight-name event set;
+returns `{"sub" => ...}`. `SeatLayer::Webhooks::EVENT_NAMES` is the exact 56-name public event set;
 delivery history accepts `limit`, `status` (`"ok"` or `"failed"`), and `before`.
 
 Verify every delivery against the **raw** body. Re-encoding a parsed Hash changes the bytes and
@@ -270,7 +382,7 @@ class WebhooksController < ApplicationController
     )
 
     # The signed body carries `at`, but nothing enforces a freshness window, so a
-    # captured delivery stays valid indefinitely. Deduplicate on occurrenceId —
+    # captured delivery stays valid indefinitely. Deduplicate on occurrenceId:
     # this is your replay protection, not an optimisation.
     return head :ok if already_processed?(event["occurrenceId"])
 
@@ -305,23 +417,36 @@ end
 | `ConflictError` | 409 | Inventory moved, or a guard rejected the change |
 | `ValidationError` | 422 | Understood and rejected |
 | `RateLimitError` | 429 | Over budget; carries `retry_after` |
-| `ConnectionError` | — | No answer: DNS, TLS, socket, timeout |
+| `ConnectionError` | none | No answer: DNS, TLS, socket, timeout |
 
 All descend from `SeatLayer::Error`, so `rescue SeatLayer::Error` catches everything. Every API
-error carries `status`, `code`, `body` and `request_id` — quote the request id in support requests.
+error carries `status`, `code`, `body` and `request_id`. Quote the request id in support requests.
 
 ## Reliability
 
 **Retries.** Reads (`GET`/`HEAD`) retry 429, 408 and 5xx with exponential backoff and full jitter;
-`Retry-After` wins when the server sends it. Fourteen mutations use exact header replay:
-`charts.create`, `charts.copy`, `templates.instantiate_template`, `events.create`,
-`workspaces.create`, `performance_groups.create`, `seasons.create_season`,
-`seasons.update_season`, `seasons.delete_season`, `seasons.create_season_plan`,
-`seasons.duplicate_season_to_live`, `seasons.create_season_holder_import`,
-`seasons.create_season_renewal_offers`, and `seasons.create_season_amendment`. Other 4xx responses
-are never retried.
-
-**Idempotency.** Those 14 replay-backed operations carry an `Idempotency-Key`, generated when you
+`Retry-After` wins when the server sends it. Forty-one mutations use exact header replay:
+
+- `charts.create`, `charts.copy`, `templates.instantiate_template`, `events.create`,
+  `workspaces.create`, and `performance_groups.create`;
+- 26 on `seasons`: `create_season`, `update_season`, `delete_season`, `create_season_plan`,
+  `update_season_plan`, `delete_season_plan`, `publish_season`, `duplicate_season_to_live`,
+  `create_season_holder_import`, `create_season_holder_import_from_season`,
+  `create_season_renewal_offers`, `create_season_amendment`, `create_season_performances`,
+  `attach_season_performances`, `delete_season_performance`, `create_season_checkout_test`,
+  `replace_season_package_prices`, `attach_season_plan_performance`,
+  `delete_season_plan_performance`, `mark_season_performance_past`, `refund_season_order`,
+  `cancel_season_order`, `cancel_season_order_date`, `refund_season_performance`,
+  `release_season_lapsed_offers`, and `create_season_renewal_checkout`;
+- `holders.update_holder`, `holders.create_holder_transfer`, `holders.create_holder_return`, and
+  `holders.create_holder_renewal_checkout`;
+- `orders.refund_event_order` and `orders.cancel_event_order`;
+- `event_series.create_event_series`, `event_series.add_event_series_dates`, and
+  `event_series.update_event_series`.
+
+Other 4xx responses are never retried.
+
+**Idempotency.** Those 41 replay-backed operations carry an `Idempotency-Key`, generated when you
 do not supply one and reused across attempts. All remaining SDK mutations are single-attempt. Some
 have a server-side domain idempotency contract, but the SDK does not retry them automatically. This
 includes inventory holds and bookings, show-once credential or secret creation, unsupported
@@ -359,14 +484,17 @@ outbox, and support operations.
 | --- | --- |
 | `charts` | `list` `list_all` `create` `retrieve` `update` `delete` `copy` `archive` `unarchive` `publish` |
 | `templates` | `instantiate_template` |
-| `events` | `list` `list_all` `create` `retrieve` `retrieve_configuration_binding` `update_configuration_binding` `update` `delete` `update_poster` `delete_poster` `update_chart` `close` `reopen` `archive` `retrieve_hold_ttl` `update_hold_ttl` `list_ticket_releases` `update_ticket_releases` `close_ticket_release` `retrieve_report` `retrieve_log` |
+| `events` | `list` `list_all` `create` `retrieve` `retrieve_configuration_binding` `update_configuration_binding` `update` `delete` `update_poster` `delete_poster` `update_chart` `close` `reopen` `archive` `retrieve_hold_ttl` `update_hold_ttl` `list_ticket_releases` `update_ticket_releases` `close_ticket_release` `retrieve_report` `retrieve_log` `retrieve_event_buyer_checkout` `replace_event_buyer_checkout` `retrieve_event_payment_gateway` `replace_event_payment_gateway` `retrieve_event_sales_readiness` `preflight_event_sales` `transition_event_sales` `retrieve_event_booking_fee` `replace_event_booking_fee` `list_event_discount_codes` `create_event_discount_code` `update_event_discount_code` `end_event_discount_code` `delete_event_discount_code` |
 | `inventory` | `hold` `hold_best_available` `book_best_available` `extend_hold` `retrieve_hold` `release` `book` `box_office_book` `unbook` `list_bookings` `retrieve_booking` `block` `unblock` `unblock_all` `retrieve_availability` `update_availability` |
 | `channels` | `list_channels` `create_channel` `update_channel` `update_assignments` `list_allocation` `retrieve_access_preview` `retrieve_report` `pause` `unpause` `archive` `create_buyer_access_session` `list_buyer_access_sessions` `revoke_buyer_access_session` `create_access_link` `list_access_links` `rotate_access_link` `revoke_access_link` |
 | `sessions` | `create_manage_session` `revoke_manage_session` `create_designer_session` `revoke_designer_session` |
 | `webhooks` | `list` `create` `update` `delete` `list_deliveries` |
 | `workspaces` | `list` `create` `retrieve` `update` |
 | `performance_groups` | `list` `create` `retrieve` `delete` `activate` `close` `retrieve_lifecycle` `create_buyer_access_session` `list_buyer_access_sessions` `revoke_buyer_access_session` `retrieve_hold` `book_hold` `retrieve_booking` |
-| `seasons` | 48 operations for catalogue and Plan lifecycle, sales windows, buyer access and booking, holder imports, renewals, occurrence amendments, reports, audit, outbox, and support export |
+| `seasons` | 87 operations for catalogue and Plan lifecycle, performances, package prices, checkout tests, sales windows, buyer access and booking, holder imports, holders, renewals, renewal quotes and checkouts, occurrence amendments, returns and reclaims, Season orders, bulk refunds, lapsed-offer releases and jobs, reports and CSV exports, audit, outbox, and support export |
+| `holders` | `list_customers` `retrieve_holder` `update_holder` `revoke_holder_sessions` `list_holder_seasons` `list_holder_tickets` `retrieve_holder_ticket` `create_holder_transfer` `list_holder_transfers` `cancel_holder_transfer` `accept_holder_transfer` `create_holder_return` `create_holder_renewal_checkout` `decline_holder_renewal_offer` |
+| `orders` | `list_orders` `retrieve_order` `list_order_tickets` `list_event_orders` `retrieve_event_order` `export_event_orders_csv` `refund_event_order` `cancel_event_order` `resend_event_order_tickets` |
+| `event_series` | `create_event_series` `list_event_series` `retrieve_event_series` `add_event_series_dates` `update_event_series` |
 
 Full reference: [SeatLayer Ruby server SDK guide](https://docs.seatlayer.io/server-sdk/ruby/)
 
@@ -374,24 +502,21 @@ Full reference: [SeatLayer Ruby server SDK guide](https://docs.seatlayer.io/serv
 
 Some API surface is intentionally unwrapped, not merely pending:
 
-- **Hosted-checkout orders and refunds.** Reading or refunding a SeatLayer-hosted-checkout sale is
-  not a server-SDK capability. Those records only exist for organisations using hosted checkout; if
-  you run your own commerce store you refund in that store, through your own gateway.
-- **Connecting or assigning payment gateways.** Connecting one is a dashboard flow, so shipping only
-  the assignment half across seven SDKs would hand you a method that cannot yet succeed.
+- **Connecting a payment gateway.** Connecting one is a dashboard flow. Once it is connected,
+  `events.replace_event_payment_gateway` assigns it to an event.
 - **Realtime seat updates.** Live seat state reaches the *browser* through the widget's own socket.
   There is no server-side subscribe; a secret-key caller gets authoritative state from
   `events.retrieve_report` and `inventory.retrieve_availability`.
 
-None of these are reachable through `request` as a supported path either — they are excluded from
-the public manifest, not just from the wrapper.
+Neither is reachable through `request` as a supported path either; both are excluded from the
+public manifest, not just from the wrapper.
 
 ## Frequently asked questions
 
 ### How do I book seats from Ruby?
 
-Create a client with your secret key, obtain a hold id — either from the buyer's
-browser session or by holding server-side — and call `inventory.book(event_key, hold_id: ..., booking_ref: ...)`.
+Create a client with your secret key, obtain a hold id (either from the buyer's
+browser session or by holding server-side) and call `inventory.book(event_key, hold_id: ..., booking_ref: ...)`.
 `booking_ref` is your own stable order id and is the join between SeatLayer
 inventory and your commercial order, so the same reference identifies the booking
 in Booking History and when you later cancel it. For phone orders, box office, and
@@ -403,7 +528,7 @@ The buyer SDK runs where the ticket buyer is: it renders the interactive seating
 chart, handles seat selection, and creates temporary holds. This server SDK is the
 trusted side. It authenticates with your secret key, inspects what a hold actually
 contains, prices from server-owned data, and books. Never bundle the secret key
-into a browser or a mobile app — browser surfaces get short-lived, origin-bound
+into a browser or a mobile app. Browser surfaces get short-lived, origin-bound
 tokens that you mint here.
 
 ### How do temporary holds work server-side?
@@ -414,7 +539,7 @@ and at what price, so charge from its `items` rather than from anything the brow
 sent you. When an order runs longer than the checkout window, `inventory.extend_hold`
 renews the hold instead of releasing and re-holding, which would hand the seats to
 whoever is racing for them. Bookings carry the server's exact-selection plus
-`booking_ref` safeguard, but the SDK sends each booking once — reconcile an unknown
+`booking_ref` safeguard, but the SDK sends each booking once; reconcile an unknown
 outcome before trying again.
 
 ### Can I use my own payment provider?

data/lib/seatlayer/event_series.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module SeatLayer
+  # Event series: many dates of one show, planned from a schedule and run as
+  # one. A series is addressed by the key of its first event.
+  class EventSeries < Resource
+    # Plan an event series from a +schedule+ Hash, or create it as a job.
+    # Pass <tt>dry_run: true</tt> to get the dates back without creating any.
+    # Every date carries +name+ as its name.
+    #
+    # Give +name+ and +chart_key+, or +from_event_key+: an event you already set
+    # up becomes the first date under its own key, and every other date is a copy
+    # of it (floor plan, prices, checkout, poster and its own seat blocks, none of
+    # its orders, holds or sales). The series takes the event's name, zone and
+    # floor plan.
+    #
+    # A series from an event that never started and was given up answers 409
+    # create_abandoned for that key every time: send it again with a new
+    # +idempotency_key+.
+    def create_event_series( # rubocop:disable Metrics/ParameterLists
+      schedule:, name: nil, chart_key: nil, timezone: nil, venue: nil,
+      duration_minutes: nil, dry_run: nil, idempotency_key: nil, from_event_key: nil
+    )
+      if from_event_key.nil? && (name.nil? || chart_key.nil?)
+        raise ArgumentError, "give name: and chart_key:, or from_event_key:"
+      end
+
+      body = compact({ "fromEventKey" => from_event_key, "name" => name, "chartKey" => chart_key,
+                       "schedule" => schedule, "timezone" => timezone, "venue" => venue,
+                       "durationMinutes" => duration_minutes, "dryRun" => dry_run })
+      @client.post("/v1/event-series", body, idempotency_key: idempotency_key,
+                                             retry_policy: :header_replay)
+    end
+
+    # One page of event series.
+    def list_event_series(limit: nil, cursor: nil)
+      @client.get("/v1/event-series", compact({ "limit" => limit, "cursor" => cursor }))
+    end
+
+    # Read one event series.
+    def retrieve_event_series(event_key)
+      @client.get(path(event_key))
+    end
+
+    # Add dates to a series, copied from its first date. Pass one of a +schedule+
+    # Hash, a +dates+ list of "YYYY-MM-DDTHH:MM" strings, or +retry_failed: true+ to
+    # make again every date that failed to be made (422 nothing_to_retry when none
+    # did, 409 series_busy while another change runs).
+    def add_event_series_dates(event_key, schedule: nil, dates: nil, retry_failed: false,
+                               idempotency_key: nil)
+      @client.post(path(event_key, "/dates"),
+                   compact({ "schedule" => schedule, "dates" => dates,
+                             "retryFailed" => (retry_failed ? true : nil) }),
+                   idempotency_key: idempotency_key, retry_policy: :header_replay)
+    end
+
+    # Rename a series, change its prices, or turn sales "on" or "off" on every
+    # upcoming date. +prices+ ({ "categories" => [...] }) takes only the
+    # categories whose price changes (for a tiered category, only the tiers
+    # sent); every price left out keeps each date's own value. Sales "on" never
+    # opens a date its season cancelled: that date is a failed item of the job
+    # (season_date_cancelled), counted in the job's "failed" but not in
+    # "failedDates", which are the dates that could not be made.
+    def update_event_series(event_key, name: nil, prices: nil, sales: nil, idempotency_key: nil)
+      @client.mutation_with_header_replay(
+        "PATCH", path(event_key),
+        compact({ "name" => name, "prices" => prices, "sales" => sales }),
+        idempotency_key: idempotency_key
+      )
+    end
+
+    private
+
+    def path(event_key, suffix = "")
+      "/v1/event-series/#{encode(event_key)}#{suffix}"
+    end
+  end
+end