seatlayer 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6aa9b6c1e8985b0f261f5e0bf7743148a2fcf5dc3c9f9585b482d78e24b492a5
-  data.tar.gz: 70b5fb6fd1f3eb7cbed9d80917a7e1ef56d212c1bafb924e97a961878e71e906
+  metadata.gz: 07a3046d14b181d770f7dddf673476c7b0d695d31d725adc042555afa145c144
+  data.tar.gz: 5923f05115c9741d3ab20ac8598616351eeac43d74a91b5da0c590275f0105b0
 SHA512:
-  metadata.gz: 21ab307cdbc1676e6d463c3bb990ebe886f5d38906b988d129d1f5a722c4199ffeb80938b582e3d7b906fe287b9ea5a190dda5043200f27f569fc0c2d2aab7f1
-  data.tar.gz: d4d261bb2e9240a49bf373fd9faa63896fac970f9fb7a9f5c7583becce1c26a445f45ff623115463e833587f0a58be1762990864dba1066139c384d62d85005e
+  metadata.gz: d9b16c52a2dad95aab45a2d0d75dad7be100ddb60497b554ce9adc1a86dacdab4e8a6dd273314ba67dd93a7156eebb5984550ebf9a5ad8c2cdc519a356ccf70a
+  data.tar.gz: 0fbe576e636045d4cdfc6ff3cffcbd16403fc3e595913832d352bdcebe66cc03fc128dcc2ab7bca3fc490558e099c77838a4fe6a88d54f66305c9a7928ea0ea8

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## Unreleased
+
+- **Security/reliability:** Mutations now default to a single attempt. Automatic header-replay
+  retries are limited to chart create/copy, event create, and workspace create, preventing
+  transient failures from duplicating holds or best-available results and from issuing extra
+  show-once credentials.
+- Aligned event, inventory, webhook, manage-session, and Designer requests with the generated
+  public contract: event metadata, chart-update acknowledgement, trusted hold extension,
+  scheduled block release, hold-TTL reset, webhook envelopes and delivery filters, and Designer
+  safe-mode/feature-policy fields are now represented directly.
+- Removed unsupported `state` and `cursor` keywords from buyer-access-session listing; the route
+  supports only `limit`.
+- Added deterministic transport-contract coverage for stable error-code fallback, HTTP status,
+  decoded body and `X-Request-ID` exposure, typed 429 `Retry-After` precedence, non-JSON gateway
+  failures, and single-attempt unsafe mutations.
+- Reached all 71 public operation wrappers with raw event-poster upload/removal and the complete
+  hosted access-link lifecycle. One-time capability reveals remain single-attempt.
+- Added chart copy/metadata overrides, event-log pagination filters, and explicit-null support for
+  buyer-session and workspace fields.
+
+## 0.2.0 — 2026-08-12
+
+- Added the `channels` resource for allocation management, access previews,
+  channel reporting, and origin-bound buyer access sessions.
+- Added inventory booking lifecycle reads and channel-aware hold/book options.
+- Require a non-empty stable booking reference for booking, unbooking, and
+  booking-detail reads.
+- Expanded registry, documentation, and agent-discovery links in the README.
+
 ## 0.1.0 — 2026-08-04
 
 First public release: RubyGems `seatlayer`.

data/README.md

@@ -1,5 +1,10 @@
 # SeatLayer Ruby SDK
 
+[![CI](https://github.com/seatlayer/seatlayer-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/seatlayer/seatlayer-ruby/actions/workflows/ci.yml)
+[![Gem](https://img.shields.io/gem/v/seatlayer.svg)](https://rubygems.org/gems/seatlayer)
+[![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)
+
 Official Ruby server SDK for the [SeatLayer](https://seatlayer.io) reserved-seating API.
 
 > **Server-side only.** This gem authenticates with your secret key. Never load it anywhere a
@@ -38,6 +43,9 @@ held = client.inventory.hold_best_available(event["key"], qty: 4)
 client.inventory.book(event["key"], hold_id: held["holdId"], booking_ref: "order-8842")
 ```
 
+Nullable event-create fields distinguish omission from an explicit reset: passing, for example,
+`venue: nil` sends JSON `null`; leaving `venue` out sends no field.
+
 ## Test vs live
 
 Keys carry their own mode. `sk_test_…` keys can only touch test-mode events and `sk_live_…` only
@@ -74,6 +82,27 @@ client.inventory.book_best_available(event_key, qty: 2, booking_ref: "phone-1183
 client.inventory.box_office_book(event_key, labels: ["A-1", "A-2"], booking_ref: "comp-14")
 ```
 
+## Private and partner sales
+
+Channels split event inventory into explicit allocations. A channel id is
+reporting/routing metadata, not browser authority. Authenticate the buyer in
+your backend and mint a short-lived token restricted to the event, origin, and
+allowed allocations:
+
+```ruby
+access = client.channels.create_buyer_access_session(
+  event_key,
+  channel_ids: ["chn_partner_a"],
+  include_public: false,
+  allowed_origin: "https://tickets.example"
+)
+# Return access["token"] to the in-memory buyerAccessTokenProvider only.
+```
+
+Never log or persist the returned `bse_…` bearer. Allocation setup, previews,
+pause/archive controls, audit-safe session listing, and channel reports are on
+`client.channels`.
+
 ## Listing and pagination
 
 `list` returns one page plus a `nextCursor`. `list_all` pages for you and returns a lazy
@@ -129,11 +158,9 @@ session = client.sessions.create_manage_session(
 )
 ```
 
-`capabilities` is **required** by this SDK even though the API defaults it. Omit it at the API level
-and you get `event:view`, `event:block`, `event:cancel` and `event:reports` — including
-`event:cancel`, which unbooks paid seats **and authorises refunds against the organiser's connected
-payment gateway**. That is real money, moved by a token you handed to a browser; it should not
-arrive by forgetting an argument. Grant the smallest set the page needs.
+`capabilities` is **required** by this SDK even though the raw API safely defaults an omitted list
+to view-only (`event:view`). Keeping the argument required makes browser authority visible at every
+call site. Grant the smallest set the page needs.
 
 The full set, all opt-in:
 
@@ -145,13 +172,27 @@ The full set, all opt-in:
 | `event:reports` | Read sales and availability reports |
 | `event:channels:view` | Read sales channels and their allocations |
 | `event:channels:manage` | Create, pause and archive channels; rotate access links |
+| `event:orders:read` | Read SeatLayer-managed orders |
+| `event:refund` | Refund a SeatLayer-managed order |
+| `event:tickets:send` | Send SeatLayer-managed tickets |
+| `event:door:view` | Read the door list |
+| `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
 page manages channels.
 
+Designer minting returns the API envelope unchanged: read the token and effective safe-mode and
+feature policy under `result["session"]`. Pass `safe_mode_options` only with `mode: "safe"`.
+
 ## Webhooks
 
+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;
+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
 verification will fail.
 
@@ -210,15 +251,20 @@ error carries `status`, `code`, `body` and `request_id` — quote the request id
 
 ## Reliability
 
-**Retries.** 429, 408 and 5xx are retried with exponential backoff and full jitter; `Retry-After`
-wins when the server sends it. 4xx is never retried — it will not start succeeding.
+**Retries.** Reads (`GET`/`HEAD`) retry 429, 408 and 5xx with exponential backoff and full jitter;
+`Retry-After` wins when the server sends it. Automatic mutation retries are limited to the four
+operations backed by exact response replay: `charts.create`, `charts.copy`, `events.create`, and
+`workspaces.create`. Other 4xx responses are never retried.
 
-**Idempotency.** Every mutating request carries an `Idempotency-Key`, generated if you do not supply
-one, and **reused across retries** so a retried booking cannot become two bookings. Pass your own
-order id for end-to-end deduplication:
+**Idempotency.** Those four replay-backed operations carry an `Idempotency-Key`, generated when you
+do not supply one and reused across attempts. Other mutations are single-attempt and receive no
+automatic key. A caller-supplied key is forwarded but does not enable retries. This includes
+inventory holds and bookings, show-once credential or secret creation, unsupported operations, and
+raw `request` mutations. Keep `booking_ref` in the booking body for reconciliation, but handle an
+unknown network outcome explicitly instead of automatically repeating the sale.
 
 ```ruby
-client.inventory.book(event_key, hold_id: hold_id, idempotency_key: "order-#{order_id}")
+client.events.create(chart_id: chart_id, idempotency_key: "provision-event-#{event_id}")
 ```
 
 ```ruby
@@ -231,7 +277,8 @@ SeatLayer::Client.new(
 
 ## Escape hatch
 
-For surface this SDK does not wrap yet — same auth, retries, idempotency and error mapping:
+For surface this SDK does not wrap yet, `request` keeps auth and error mapping. Raw reads retain the
+read retry policy; raw mutations are always single-attempt because their replay contract is unknown:
 
 ```ruby
 client.request("POST", "/v1/events/ev_1/some-new-route", body: { "qty" => 2 })
@@ -242,8 +289,9 @@ client.request("POST", "/v1/events/ev_1/some-new-route", body: { "qty" => 2 })
 | Resource | Methods |
 | --- | --- |
 | `charts` | `list` `list_all` `create` `retrieve` `update` `delete` `copy` `archive` `unarchive` `publish` |
-| `events` | `list` `list_all` `create` `retrieve` `update` `delete` `update_chart` `close` `reopen` `archive` `retrieve_hold_ttl` `update_hold_ttl` `retrieve_report` `retrieve_log` |
-| `inventory` | `hold` `hold_best_available` `book_best_available` `extend_hold` `retrieve_hold` `release` `book` `box_office_book` `unbook` `block` `unblock` `unblock_all` `retrieve_availability` `update_availability` |
+| `events` | `list` `list_all` `create` `retrieve` `update` `delete` `update_poster` `delete_poster` `update_chart` `close` `reopen` `archive` `retrieve_hold_ttl` `update_hold_ttl` `retrieve_report` `retrieve_log` |
+| `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` |
@@ -273,24 +321,25 @@ the public manifest, not just from the wrapper.
 - [Webhook verification](https://docs.seatlayer.io/server-sdk/webhooks/)
 - [Server API reference](https://docs.seatlayer.io/server-api/events/)
 - [OpenAPI description](https://docs.seatlayer.io/openapi.json)
+- [Agent-readable documentation](https://docs.seatlayer.io/llms.txt)
 - [SeatLayer GitHub organization](https://github.com/seatlayer)
 
 ### Other SeatLayer SDKs
 
 | Surface | Package |
 |---|---|
-| Browser (vanilla) | [`@seatlayer/js`](https://github.com/seatlayer/seatlayer-sdk) |
-| React | [`@seatlayer/react`](https://github.com/seatlayer/seatlayer-sdk) |
-| React Native | [`@seatlayer/react-native`](https://github.com/seatlayer/seatlayer-react-native) |
+| Browser (vanilla) | [`@seatlayer/js`](https://www.npmjs.com/package/@seatlayer/js) |
+| React | [`@seatlayer/react`](https://www.npmjs.com/package/@seatlayer/react) |
+| React Native | [`@seatlayer/react-native`](https://www.npmjs.com/package/@seatlayer/react-native) |
 | iOS | [`seatlayer-ios`](https://github.com/seatlayer/seatlayer-ios) |
 | Android | [`seatlayer-android`](https://github.com/seatlayer/seatlayer-android) |
-| Flutter | [`seatlayer_flutter`](https://github.com/seatlayer/seatlayer-flutter) |
-| Node.js (server) | [`@seatlayer/server`](https://github.com/seatlayer/seatlayer-node) |
-| Python (server) | [`seatlayer`](https://github.com/seatlayer/seatlayer-python) |
-| PHP (server) | [`seatlayer/seatlayer-php`](https://github.com/seatlayer/seatlayer-php) |
-| Java (server) | [`io.seatlayer:seatlayer-java`](https://github.com/seatlayer/seatlayer-java) |
-| Go (server) | [`github.com/seatlayer/seatlayer-go`](https://github.com/seatlayer/seatlayer-go) |
-| .NET (server) | [`SeatLayer`](https://github.com/seatlayer/seatlayer-dotnet) |
+| Flutter | [`seatlayer`](https://pub.dev/packages/seatlayer) |
+| Node.js (server) | [`@seatlayer/server`](https://www.npmjs.com/package/@seatlayer/server) |
+| Python (server) | [`seatlayer`](https://pypi.org/project/seatlayer/) |
+| PHP (server) | [`seatlayer/seatlayer-php`](https://packagist.org/packages/seatlayer/seatlayer-php) |
+| Java (server) | [`io.seatlayer:seatlayer-java`](https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java/0.1.0) |
+| Go (server) | [`github.com/seatlayer/seatlayer-go`](https://pkg.go.dev/github.com/seatlayer/seatlayer-go) |
+| .NET (server) | [`SeatLayer`](https://www.nuget.org/packages/SeatLayer) |
 
 ## Development
 

data/lib/seatlayer/channels.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module SeatLayer
+  # Private allocations, reporting, and origin-bound buyer access.
+  class Channels < Resource
+    def list_channels(event_key, include_archived: false)
+      query = include_archived ? { "includeArchived" => "1" } : nil
+      @client.get(path(event_key), query)
+    end
+
+    def create_channel(event_key, name:, color: nil, marker: nil, external_ref: nil,
+                       access_intent: nil, reason: nil, idempotency_key: nil)
+      body = compact({ "name" => name, "color" => color, "marker" => marker,
+                       "externalRef" => external_ref, "accessIntent" => access_intent,
+                       "reason" => reason })
+      @client.post(path(event_key), body, idempotency_key: idempotency_key)
+    end
+
+    def update_channel(event_key, channel_id, name: nil, access_intent: nil,
+                       acknowledge_live_access: nil, reason: nil)
+      body = compact({ "name" => name, "accessIntent" => access_intent,
+                       "acknowledgeLiveAccess" => acknowledge_live_access, "reason" => reason })
+      @client.patch(path(event_key, "/#{encode(channel_id)}"), body)
+    end
+
+    def update_assignments(event_key, labels:, assignment_version:, target_channel_id: nil,
+                           reason: nil, idempotency_key: nil)
+      body = compact({ "targetChannelId" => target_channel_id, "labels" => labels,
+                       "assignmentVersion" => assignment_version, "reason" => reason })
+      body["targetChannelId"] = nil if target_channel_id.nil?
+      @client.post(path(event_key, "/assignments"), body, idempotency_key: idempotency_key)
+    end
+
+    def list_allocation(event_key, after_label: nil, limit: nil)
+      @client.get(path(event_key, "/allocation"), compact({ "afterLabel" => after_label, "limit" => limit }))
+    end
+
+    def retrieve_access_preview(event_key, channel_ids: nil, include_public: nil)
+      include_public_value = if include_public.nil?
+                               nil
+                             else
+                               include_public ? "1" : "0"
+                             end
+      query = compact({ "channelIds" => channel_ids&.join(","),
+                        "includePublic" => include_public_value })
+      @client.get(path(event_key, "/preview"), query)
+    end
+
+    def retrieve_report(event_key) = @client.get(path(event_key, "/report"))
+
+    def pause(event_key, channel_id, reason: nil)
+      @client.post(path(event_key, "/#{encode(channel_id)}/pause"), compact({ "reason" => reason }))
+    end
+
+    def unpause(event_key, channel_id, reason: nil)
+      @client.post(path(event_key, "/#{encode(channel_id)}/unpause"), compact({ "reason" => reason }))
+    end
+
+    def archive(event_key, channel_id, destination:, reason: nil)
+      body = compact({ "reason" => reason })
+      body["destination"] = destination
+      @client.post(path(event_key, "/#{encode(channel_id)}/archive"), body)
+    end
+
+    # Explicit keywords document each security boundary carried by the token.
+    # rubocop:disable Metrics/ParameterLists
+    def create_buyer_access_session(event_key, include_public:, allowed_origin:, channel_ids: nil,
+                                    expires_in_seconds: nil, max_quantity: UNSET, buyer_ref: UNSET,
+                                    partner_ref: UNSET, client_request_id: UNSET, idempotency_key: nil)
+      body = compact({ "channelIds" => channel_ids, "includePublic" => include_public,
+                       "allowedOrigin" => allowed_origin, "expiresInSeconds" => expires_in_seconds })
+      body.merge!(supplied({ "maxQuantity" => max_quantity, "buyerRef" => buyer_ref,
+                             "partnerRef" => partner_ref,
+                             "clientRequestId" => client_request_id }))
+      @client.post("/v1/events/#{encode(event_key)}/buyer-access-sessions", body,
+                   idempotency_key: idempotency_key)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def list_buyer_access_sessions(event_key, limit: nil)
+      @client.get("/v1/events/#{encode(event_key)}/buyer-access-sessions",
+                  compact({ "limit" => limit }))
+    end
+
+    def revoke_buyer_access_session(event_key, session_id)
+      @client.delete("/v1/events/#{encode(event_key)}/buyer-access-sessions/#{encode(session_id)}")
+    end
+
+    # The URL and capability in this response are revealed once. Persist them
+    # immediately; this mutation is deliberately never retried automatically.
+    # rubocop:disable Metrics/ParameterLists
+    def create_access_link(event_key, channel_id, label: UNSET, expires_at: nil,
+                           max_redemptions: nil, max_quantity: nil,
+                           session_ttl_seconds: nil, include_public: nil, reason: nil,
+                           idempotency_key: nil)
+      body = compact({ "expiresAt" => expires_at, "maxRedemptions" => max_redemptions,
+                       "maxQuantity" => max_quantity,
+                       "sessionTtlSeconds" => session_ttl_seconds,
+                       "includePublic" => include_public, "reason" => reason })
+      body.merge!(supplied({ "label" => label }))
+      @client.post(path(event_key, "/#{encode(channel_id)}/access-links"), body,
+                   idempotency_key: idempotency_key)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Status only: the API never returns a previously revealed capability.
+    def list_access_links(event_key, channel_id)
+      @client.get(path(event_key, "/#{encode(channel_id)}/access-links"))
+    end
+
+    def rotate_access_link(event_key, channel_id, link_id, end_active_sessions:, reason: nil)
+      body = compact({ "endActiveSessions" => end_active_sessions, "reason" => reason })
+      @client.post(
+        path(event_key, "/#{encode(channel_id)}/access-links/#{encode(link_id)}/rotate"), body
+      )
+    end
+
+    def revoke_access_link(event_key, channel_id, link_id, end_active_sessions: false, reason: nil)
+      query = compact({ "endActiveSessions" => end_active_sessions ? "1" : nil,
+                        "reason" => reason })
+      @client.delete(
+        path(event_key, "/#{encode(channel_id)}/access-links/#{encode(link_id)}"), query
+      )
+    end
+
+    private
+
+    def path(event_key, suffix = "") = "/v1/events/#{encode(event_key)}/channels#{suffix}"
+  end
+end

data/lib/seatlayer/http_client.rb

@@ -62,7 +62,8 @@ module SeatLayer
       URI.encode_www_form_component(segment.to_s).gsub("+", "%20")
     end
 
-    def request(method, path, query: nil, body: nil, idempotency_key: nil)
+    def request(method, path, query: nil, body: nil, raw_body: nil, content_type: nil,
+                idempotency_key: nil, retry_policy: :none)
       url = @base_url + path
       if query
         pairs = query.compact
@@ -74,56 +75,73 @@ module SeatLayer
         "Accept" => "application/json",
         "User-Agent" => "seatlayer-ruby"
       }
-      payload = nil
-      if body
-        payload = JSON.generate(body)
-        headers["Content-Type"] = "application/json"
-      end
+      payload = build_payload(body, raw_body, content_type, headers)
 
-      # Every mutation carries one. A retried POST that creates a second hold is
-      # worse than a failed POST, and the caller cannot tell from outside — so
-      # the SDK, which knows it retried, is the right place to guarantee it.
+      # Only operations with exact server-side response replay get an automatic
+      # key. A caller key on any other mutation is forwarded, but cannot opt that
+      # operation into automatic retries.
       unless %w[GET HEAD].include?(method)
-        key = idempotency_key || SecureRandom.uuid
-        self.class.validate_idempotency_key!(key)
-        headers["Idempotency-Key"] = key
+        key = idempotency_key
+        key ||= SecureRandom.uuid if retry_policy == :header_replay
+        if key
+          self.class.validate_idempotency_key!(key)
+          headers["Idempotency-Key"] = key
+        end
       end
 
-      execute(method, url, headers, payload)
+      retry_allowed = %w[GET HEAD].include?(method) || retry_policy == :header_replay
+      execute(method, url, headers, payload, retry_allowed: retry_allowed)
     end
 
     def get(path, query = nil)
       request("GET", path, query: query)
     end
 
-    def post(path, body = nil, idempotency_key: nil)
-      request("POST", path, body: body, idempotency_key: idempotency_key)
+    def post(path, body = nil, idempotency_key: nil, retry_policy: :none)
+      request("POST", path, body: body, idempotency_key: idempotency_key, retry_policy: retry_policy)
     end
 
     def put(path, body)
       request("PUT", path, body: body)
     end
 
+    def put_raw(path, raw_body, content_type: "application/octet-stream")
+      request("PUT", path, raw_body: raw_body, content_type: content_type)
+    end
+
     def patch(path, body)
       request("PATCH", path, body: body)
     end
 
-    def delete(path)
-      request("DELETE", path)
+    def delete(path, query = nil)
+      request("DELETE", path, query: query)
     end
 
     private
 
+    def build_payload(body, raw_body, content_type, headers)
+      raise ArgumentError, "body and raw_body are mutually exclusive" if !body.nil? && !raw_body.nil?
+
+      unless raw_body.nil?
+        headers["Content-Type"] = content_type || "application/octet-stream"
+        return raw_body
+      end
+      return if body.nil?
+
+      headers["Content-Type"] = "application/json"
+      JSON.generate(body)
+    end
+
     # The retry loop, extracted from #request so each piece stays readable: the
     # public method builds the call, this one decides how many times to make it.
-    def execute(method, url, headers, payload)
+    def execute(method, url, headers, payload, retry_allowed:)
       last_error = nil
 
       @max_retries.times do |attempt|
         begin
           response = send_request(method, url, headers, payload)
         rescue ConnectionError => e
-          raise e if attempt >= @max_retries - 1
+          raise e unless retry_allowed && attempt < @max_retries - 1
 
           last_error = e
           sleep(backoff(attempt, nil))
@@ -136,7 +154,7 @@ module SeatLayer
         error_body = decode_error_body(response[:body])
         retry_after = parse_retry_after(response[:headers], error_body)
 
-        if retryable?(status) && attempt < @max_retries - 1
+        if retry_allowed && retryable?(status) && attempt < @max_retries - 1
           sleep(backoff(attempt, status == 429 ? retry_after : nil))
           next
         end

data/lib/seatlayer/inventory.rb

@@ -11,10 +11,16 @@ module SeatLayer
   # Never price from what the browser tells you. +retrieve_hold+ is the
   # authoritative answer, which is why it is a separate call.
   class Inventory < Resource
+    # Explicit keywords keep allocation authority visible at every sale call.
+    # rubocop:disable Metrics/ParameterLists
     def hold(event_key, labels: nil, selections: nil, ttl_ms: nil,
-             replace_hold_id: nil, idempotency_key: nil)
+             replace_hold_id: nil, channel_ids: nil, ignore_channel_restrictions: nil,
+             reason: nil, idempotency_key: nil)
       body = compact({ "labels" => labels, "selections" => selections,
-                       "ttlMs" => ttl_ms, "replaceHoldId" => replace_hold_id })
+                       "ttlMs" => ttl_ms, "replaceHoldId" => replace_hold_id,
+                       "channelIds" => channel_ids,
+                       "ignoreChannelRestrictions" => ignore_channel_restrictions,
+                       "reason" => reason })
       @client.post(path(event_key, "/hold"), body, idempotency_key: idempotency_key)
     end
 
@@ -24,9 +30,13 @@ module SeatLayer
     # order get the same answer for the same inventory. A +qty+ above the server
     # cap is clamped, not rejected.
     def hold_best_available(event_key, qty:, category_key: nil, zone_id: nil,
-                            ttl_ms: nil, idempotency_key: nil)
+                            ttl_ms: nil, channel_ids: nil, ignore_channel_restrictions: nil,
+                            reason: nil, idempotency_key: nil)
       body = compact({ "qty" => qty, "categoryKey" => category_key,
-                       "zoneId" => zone_id, "ttlMs" => ttl_ms })
+                       "zoneId" => zone_id, "ttlMs" => ttl_ms,
+                       "channelIds" => channel_ids,
+                       "ignoreChannelRestrictions" => ignore_channel_restrictions,
+                       "reason" => reason })
       @client.post(path(event_key, "/best-available"), body, idempotency_key: idempotency_key)
     end
 
@@ -35,11 +45,16 @@ module SeatLayer
     # Prefer this over hold-then-book when payment is already taken: a failure
     # between two calls would strand inventory until the TTL expired.
     def book_best_available(event_key, qty:, booking_ref:, category_key: nil,
-                            zone_id: nil, idempotency_key: nil)
-      body = compact({ "qty" => qty, "bookingRef" => booking_ref,
-                       "categoryKey" => category_key, "zoneId" => zone_id })
+                            zone_id: nil, channel_ids: nil, ignore_channel_restrictions: nil,
+                            reason: nil, idempotency_key: nil)
+      body = compact({ "qty" => qty, "bookingRef" => normalise_booking_ref(booking_ref),
+                       "categoryKey" => category_key, "zoneId" => zone_id,
+                       "channelIds" => channel_ids,
+                       "ignoreChannelRestrictions" => ignore_channel_restrictions,
+                       "reason" => reason })
       @client.post(path(event_key, "/best-available-book"), body, idempotency_key: idempotency_key)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Push an active hold's expiry out by a fresh window before it lapses.
     #
@@ -47,8 +62,13 @@ module SeatLayer
     # the checkout window — invoiced sales, a phone order on hold. Releasing
     # first hands the seats to whoever is racing for them in between. A hold that
     # is gone, expired, or at its renewal cap answers 409 +cannot_extend+.
-    def extend_hold(event_key, hold_id, ttl_ms: nil)
-      @client.post(path(event_key, "/extend"), compact({ "holdId" => hold_id, "ttlMs" => ttl_ms }))
+    def extend_hold(event_key, hold_id, ttl_ms: nil, channel_ids: nil,
+                    ignore_channel_restrictions: nil, reason: nil)
+      body = compact({ "holdId" => hold_id, "ttlMs" => ttl_ms,
+                       "channelIds" => channel_ids,
+                       "ignoreChannelRestrictions" => ignore_channel_restrictions,
+                       "reason" => reason })
+      @client.post(path(event_key, "/extend"), body)
     end
 
     # Authoritative items and prices. Charge from this, not the browser.
@@ -60,25 +80,32 @@ module SeatLayer
       @client.post(path(event_key, "/release"), { "labels" => labels, "holdId" => hold_id })
     end
 
-    def book(event_key, hold_id: nil, labels: nil, booking_ref: nil, idempotency_key: nil)
-      body = compact({ "holdId" => hold_id, "labels" => labels, "bookingRef" => booking_ref })
+    def book(event_key, hold_id: nil, labels: nil, booking_ref: nil, channel_ids: nil,
+             ignore_channel_restrictions: nil, reason: nil, idempotency_key: nil)
+      body = compact({ "holdId" => hold_id, "labels" => labels,
+                       "bookingRef" => normalise_booking_ref(booking_ref),
+                       "channelIds" => channel_ids,
+                       "ignoreChannelRestrictions" => ignore_channel_restrictions,
+                       "reason" => reason })
       @client.post(path(event_key, "/book"), body, idempotency_key: idempotency_key)
     end
 
     def box_office_book(event_key, labels:, booking_ref:, idempotency_key: nil)
       @client.post(path(event_key, "/box-book"),
-                   { "labels" => labels, "bookingRef" => booking_ref },
+                   { "labels" => labels, "bookingRef" => normalise_booking_ref(booking_ref) },
                    idempotency_key: idempotency_key)
     end
 
     # Reverse a booking. Requires a key with cancel authority.
-    def unbook(event_key, labels:)
-      @client.post(path(event_key, "/unbook"), { "labels" => labels })
+    def unbook(event_key, labels:, booking_ref:)
+      @client.post(path(event_key, "/unbook"),
+                   { "labels" => labels, "bookingRef" => normalise_booking_ref(booking_ref) })
     end
 
     # Hold inventory back from sale (house seats, production holds).
-    def block(event_key, labels:)
-      @client.post(path(event_key, "/block"), { "labels" => labels })
+    def block(event_key, labels:, release_at: nil)
+      @client.post(path(event_key, "/block"),
+                   compact({ "labels" => labels, "releaseAt" => release_at }))
     end
 
     def unblock(event_key, labels:)
@@ -97,11 +124,28 @@ module SeatLayer
       @client.post(path(event_key, "/availability"), fields)
     end
 
+    # One page of inventory booking lifecycles, newest first.
+    def list_bookings(event_key, query: nil, state: nil, limit: nil, cursor: nil)
+      @client.get(path(event_key, "/bookings"),
+                  compact({ "q" => query, "state" => state, "limit" => limit, "cursor" => cursor }))
+    end
+
+    def retrieve_booking(event_key, booking_ref)
+      @client.get(path(event_key, "/bookings/#{encode(normalise_booking_ref(booking_ref))}"))
+    end
+
     private
 
     def path(event_key, suffix)
       "/v1/events/#{encode(event_key)}#{suffix}"
     end
+
+    def normalise_booking_ref(booking_ref)
+      value = booking_ref&.strip
+      return value unless value.nil? || value.empty?
+
+      raise ArgumentError, "booking_ref is required and must be a non-empty stable reference"
+    end
   end
 
   # Short-lived, origin-bound browser tokens.
@@ -109,24 +153,29 @@ module SeatLayer
   # The governing rule: the SDK mints tokens, widgets consume them. Your secret
   # key never reaches a browser.
   class Sessions < Resource
-    CAPABILITIES = ["event:view", "event:block", "event:cancel", "event:reports"].freeze
+    CAPABILITIES = [
+      "event:view", "event:block", "event:cancel", "event:reports",
+      "event:channels:view", "event:channels:manage", "event:orders:read",
+      "event:refund", "event:tickets:send", "event:door:view",
+      "event:door:checkin", "event:boxoffice"
+    ].freeze
 
     # Mint a manage-session token for the control room.
     #
-    # +capabilities+ is required here even though the API defaults it. That
-    # default grants all four — including event:cancel, which un-books paid
-    # inventory. Granting the ability to reverse sales by forgetting an argument
-    # is not a default worth inheriting.
-    def create_manage_session(event_key, allowed_origin:, capabilities:, expires_in_seconds: nil)
+    # The raw API defaults an omitted list to view-only (+event:view+). This SDK
+    # still requires an explicit set so browser authority is visible at each call.
+    def create_manage_session(event_key, allowed_origin:, capabilities:, expires_in_seconds: nil,
+                              workspace_id: nil)
       if capabilities.nil? || capabilities.empty?
         raise ArgumentError,
-              "capabilities is required: pass the smallest set the page needs, e.g. " \
-              '["event:view"]. Omitting it server-side grants event:cancel, ' \
-              "which can reverse paid bookings."
+              'capabilities is required: pass the smallest set the page needs, e.g. ["event:view"].'
       end
+      unknown = capabilities - CAPABILITIES
+      raise ArgumentError, "unsupported manage capabilities: #{unknown.join(", ")}" unless unknown.empty?
 
       body = compact({ "allowedOrigin" => allowed_origin, "capabilities" => capabilities,
-                       "expiresInSeconds" => expires_in_seconds })
+                       "expiresInSeconds" => expires_in_seconds,
+                       "workspaceId" => workspace_id })
       @client.post("/v1/events/#{encode(event_key)}/manage-sessions", body)
     end
 
@@ -136,13 +185,19 @@ module SeatLayer
 
     # Mint a designer token so an organiser can edit a chart inside your own UI.
     # Requires a chart id that already exists — create or copy one first.
+    # Explicit keywords keep each security and feature-policy boundary visible.
+    # rubocop:disable Metrics/ParameterLists
     def create_designer_session(workspace_id:, chart_id:, allowed_origin:,
-                                authority: nil, mode: nil, expires_in_seconds: nil)
+                                authority: nil, can_publish: nil, mode: nil,
+                                safe_mode_options: nil, features: nil, expires_in_seconds: nil)
       body = compact({ "workspaceId" => workspace_id, "chartId" => chart_id,
                        "allowedOrigin" => allowed_origin, "authority" => authority,
-                       "mode" => mode, "expiresInSeconds" => expires_in_seconds })
+                       "canPublish" => can_publish, "mode" => mode,
+                       "safeModeOptions" => safe_mode_options, "features" => features,
+                       "expiresInSeconds" => expires_in_seconds })
       @client.post("/v1/designer/sessions", body)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     def revoke_designer_session(session_id)
       @client.delete("/v1/designer/sessions/#{encode(session_id)}")
@@ -151,15 +206,23 @@ module SeatLayer
 
   # Manage webhook subscriptions. To VERIFY a delivery, see SeatLayer::Webhook.
   class Webhooks < Resource
+    EVENT_NAMES = [
+      "seat.booked", "seat.released", "seat.blocked", "hold.expired",
+      "hold.created", "hold.extended", "event.created", "event.soldout"
+    ].freeze
+
     def list
       @client.get("/v1/webhooks")
     end
 
     def create(url:, events:)
+      validate_events!(events)
       @client.post("/v1/webhooks", { "url" => url, "events" => events })
     end
 
-    def update(webhook_id, fields)
+    def update(webhook_id, url: nil, events: nil, disabled: nil)
+      validate_events!(events) unless events.nil?
+      fields = compact({ "url" => url, "events" => events, "disabled" => disabled })
       @client.patch("/v1/webhooks/#{encode(webhook_id)}", fields)
     end
 
@@ -167,8 +230,20 @@ module SeatLayer
       @client.delete("/v1/webhooks/#{encode(webhook_id)}")
     end
 
-    def list_deliveries(webhook_id)
-      @client.get("/v1/webhooks/#{encode(webhook_id)}/deliveries")
+    def list_deliveries(webhook_id, limit: nil, status: nil, before: nil)
+      raise ArgumentError, "status must be ok or failed" unless status.nil? || %w[ok failed].include?(status)
+
+      query = compact({ "limit" => limit, "status" => status, "before" => before })
+      @client.get("/v1/webhooks/#{encode(webhook_id)}/deliveries", query)
+    end
+
+    private
+
+    def validate_events!(events)
+      unknown = Array(events) - EVENT_NAMES
+      return if !Array(events).empty? && unknown.empty?
+
+      raise ArgumentError, "events must contain only supported SeatLayer webhook event names"
     end
   end
 
@@ -178,9 +253,12 @@ module SeatLayer
       @client.get("/v1/workspaces")
     end
 
-    def create(name:, external_ref: nil, idempotency_key: nil)
-      body = compact({ "name" => name, "externalRef" => external_ref })
-      @client.post("/v1/workspaces", body, idempotency_key: idempotency_key)
+    def create(name:, external_ref: UNSET, idempotency_key: nil)
+      body = { "name" => name }
+      body.merge!(supplied({ "externalRef" => external_ref }))
+      @client.post(
+        "/v1/workspaces", body, idempotency_key: idempotency_key, retry_policy: :header_replay
+      )
     end
 
     def retrieve(workspace_id)

data/lib/seatlayer/resources.rb

@@ -3,6 +3,8 @@
 module SeatLayer
   # Shared plumbing for the resource namespaces.
   class Resource
+    UNSET = Object.new.freeze
+
     def initialize(client)
       @client = client
     end
@@ -15,6 +17,11 @@ module SeatLayer
       hash.compact
     end
 
+    # Drop only the private sentinel, preserving nil as explicit JSON null.
+    def supplied(hash)
+      hash.reject { |_key, value| value.equal?(UNSET) }
+    end
+
     def encode(segment)
       HTTPClient.encode(segment)
     end
@@ -58,14 +65,16 @@ module SeatLayer
     def create(name:, doc: nil, external_ref: nil, workspace_id: nil, idempotency_key: nil)
       body = compact({ "name" => name, "doc" => doc,
                        "externalRef" => external_ref, "workspaceId" => workspace_id })
-      @client.post("/v1/charts", body, idempotency_key: idempotency_key)
+      @client.post(
+        "/v1/charts", body, idempotency_key: idempotency_key, retry_policy: :header_replay
+      )
     end
 
     def retrieve(chart_id)
       @client.get("/v1/charts/#{encode(chart_id)}")
     end
 
-    # Replace a chart document.
+    # Replace a chart document or update metadata only.
     #
     # +expected_updated_at+ is required for optimistic concurrency and is not
     # optional here either: without it two concurrent writers silently overwrite
@@ -74,8 +83,20 @@ module SeatLayer
     #
     # The Designer is the authoring surface. Use this for bulk programmatic edits
     # and migrations, not for drawing.
-    def update(chart_id, doc:, expected_updated_at:, name: nil)
-      body = compact({ "doc" => doc, "expectedUpdatedAt" => expected_updated_at, "name" => name })
+    def update(chart_id, doc: UNSET, expected_updated_at: UNSET, name: nil, issues: nil,
+               external_ref: UNSET)
+      doc_supplied = !doc.equal?(UNSET)
+      expected_supplied = !expected_updated_at.equal?(UNSET)
+      unless doc_supplied == expected_supplied
+        raise ArgumentError, "doc and expected_updated_at must be supplied together"
+      end
+
+      body = compact({ "name" => name, "issues" => issues })
+      if doc_supplied
+        body["doc"] = doc
+        body["expectedUpdatedAt"] = expected_updated_at
+      end
+      body.merge!(supplied({ "externalRef" => external_ref }))
       @client.put("/v1/charts/#{encode(chart_id)}", body)
     end
 
@@ -84,8 +105,14 @@ module SeatLayer
     end
 
     # Copy a chart — the usual way to provision a venue from a template.
-    def copy(chart_id, idempotency_key: nil)
-      @client.post("/v1/charts/#{encode(chart_id)}/duplicate", nil, idempotency_key: idempotency_key)
+    def copy(chart_id, idempotency_key: nil, name: nil, external_ref: UNSET,
+             workspace_id: nil)
+      body = compact({ "name" => name, "workspaceId" => workspace_id })
+      body.merge!(supplied({ "externalRef" => external_ref }))
+      @client.post(
+        "/v1/charts/#{encode(chart_id)}/duplicate", body.empty? ? nil : body,
+        idempotency_key: idempotency_key, retry_policy: :header_replay
+      )
     end
 
     def archive(chart_id)
@@ -131,13 +158,22 @@ module SeatLayer
       end
     end
 
-    def create(chart_id:, name: nil, slug: nil, starts_at: nil, venue: nil,
-               external_ref: nil, currency: nil, idempotency_key: nil)
-      body = compact({ "chartId" => chart_id, "name" => name, "slug" => slug,
-                       "startsAt" => starts_at, "venue" => venue,
-                       "externalRef" => external_ref, "currency" => currency })
-      @client.post("/v1/events", body, idempotency_key: idempotency_key)
+    # rubocop:disable Metrics/ParameterLists
+    def create(chart_id:, name: nil, slug: nil, starts_at: UNSET, venue: UNSET,
+               external_ref: UNSET, currency: UNSET, idempotency_key: nil,
+               description: UNSET, ends_at: UNSET, timezone: UNSET, locale: UNSET,
+               poster_asset_id: UNSET, mode: nil)
+      body = compact({ "chartId" => chart_id, "name" => name, "slug" => slug, "mode" => mode })
+      body.merge!(supplied({ "startsAt" => starts_at, "venue" => venue,
+                             "externalRef" => external_ref, "currency" => currency,
+                             "description" => description, "endsAt" => ends_at,
+                             "timezone" => timezone, "locale" => locale,
+                             "posterAssetId" => poster_asset_id }))
+      @client.post(
+        "/v1/events", body, idempotency_key: idempotency_key, retry_policy: :header_replay
+      )
     end
+    # rubocop:enable Metrics/ParameterLists
 
     def retrieve(event_key)
       @client.get("/v1/events/#{encode(event_key)}")
@@ -151,9 +187,20 @@ module SeatLayer
       @client.delete("/v1/events/#{encode(event_key)}")
     end
 
+    # Upload raw PNG, JPEG, or WebP bytes (maximum 5 MiB).
+    def update_poster(event_key, image, content_type: "application/octet-stream")
+      @client.put_raw("/v1/events/#{encode(event_key)}/poster", image, content_type: content_type)
+    end
+
+    def delete_poster(event_key)
+      @client.delete("/v1/events/#{encode(event_key)}/poster")
+    end
+
     # Move a live event onto the latest published version of its chart.
-    def update_chart(event_key)
-      @client.post("/v1/events/#{encode(event_key)}/update-chart")
+    def update_chart(event_key, acknowledge_dropped_assignments: nil, reason: nil)
+      body = compact({ "acknowledgeDroppedAssignments" => acknowledge_dropped_assignments,
+                       "reason" => reason })
+      @client.post("/v1/events/#{encode(event_key)}/update-chart", body)
     end
 
     # Stop buyer sales. Existing holds keep their TTL.
@@ -174,6 +221,7 @@ module SeatLayer
     end
 
     def update_hold_ttl(event_key, hold_ttl_ms)
+      # +nil+ restores the event default and must remain an explicit JSON null.
       @client.post("/v1/events/#{encode(event_key)}/hold-ttl", { "holdTtlMs" => hold_ttl_ms })
     end
 
@@ -181,8 +229,9 @@ module SeatLayer
       @client.get("/v1/events/#{encode(event_key)}/report")
     end
 
-    def retrieve_log(event_key)
-      @client.get("/v1/events/#{encode(event_key)}/log")
+    def retrieve_log(event_key, limit: nil, before: nil)
+      @client.get("/v1/events/#{encode(event_key)}/log",
+                  compact({ "limit" => limit, "before" => before }))
     end
   end
 end

data/lib/seatlayer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SeatLayer
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/seatlayer.rb

@@ -5,6 +5,7 @@ require_relative "seatlayer/errors"
 require_relative "seatlayer/http_client"
 require_relative "seatlayer/resources"
 require_relative "seatlayer/inventory"
+require_relative "seatlayer/channels"
 require_relative "seatlayer/webhook"
 
 # Official Ruby server SDK for the SeatLayer reserved-seating API.
@@ -18,7 +19,7 @@ require_relative "seatlayer/webhook"
 module SeatLayer
   # The SeatLayer client.
   class Client
-    attr_reader :charts, :events, :inventory, :sessions, :webhooks, :workspaces
+    attr_reader :charts, :events, :inventory, :channels, :sessions, :webhooks, :workspaces
 
     def initialize(secret_key, base_url: HTTPClient::DEFAULT_BASE_URL,
                    max_retries: HTTPClient::DEFAULT_MAX_RETRIES,
@@ -29,6 +30,7 @@ module SeatLayer
       @charts = Charts.new(@http)
       @events = Events.new(@http)
       @inventory = Inventory.new(@http)
+      @channels = Channels.new(@http)
       @sessions = Sessions.new(@http)
       @webhooks = Webhooks.new(@http)
       @workspaces = Workspaces.new(@http)
@@ -44,10 +46,12 @@ module SeatLayer
       @http.get("/health/ready")
     end
 
-    # Escape hatch for surface this SDK does not wrap yet. Carries the same auth,
-    # retries, idempotency and error mapping.
-    def request(method, path, query: nil, body: nil, idempotency_key: nil)
-      @http.request(method, path, query: query, body: body, idempotency_key: idempotency_key)
+    # Escape hatch for surface this SDK does not wrap yet. Reads retain retries;
+    # raw mutations are single-attempt because their replay contract is unknown.
+    def request(method, path, query: nil, body: nil, raw_body: nil, content_type: nil,
+                idempotency_key: nil)
+      @http.request(method, path, query: query, body: body, raw_body: raw_body,
+                                  content_type: content_type, idempotency_key: idempotency_key)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: seatlayer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - SeatLayer
@@ -21,6 +21,7 @@ files:
 - LICENSE
 - README.md
 - lib/seatlayer.rb
+- lib/seatlayer/channels.rb
 - lib/seatlayer/errors.rb
 - lib/seatlayer/http_client.rb
 - lib/seatlayer/inventory.rb