seatlayer 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d51f4f004070a397c4ac39e08f183df2c8a72dca70c35ce1ef61042d247b30c
-  data.tar.gz: a37f6748bf6d656ee1b5daa4902609678bf039992766c9fa9dce7742e4ee47f8
+  metadata.gz: 7fdf50105cfef210f1afd2ae7073ce1b1da6c17a9ab3754204f3ebce145dcea7
+  data.tar.gz: 415f72edd18e2d97e603a563e2b33f4d920ae03f9e649e42bac287860cb4a3de
 SHA512:
-  metadata.gz: 25dfd25bc366329bb38f52f59522dde781225df50fcfe5b6c523e9b7af3ab54d16aa22b6c6ea022b8e65d5e98b1a8dcbabd04c3716026cc257918c0fa3b9ce73
-  data.tar.gz: 98af014bd435e3f5ee7233c5b3c8feeb9b4ed950e9df55b5c1be4ec1dc94506657cb83c0149202c9421bbf223efb760ad15fb713ea88797222326b435236f41c
+  metadata.gz: ab1db651d6aafa3d2c2c238bc3ddab90d8c8d4c103bcd581fb34993e9aa25f0bc9028b8071cd992985d4ea641a03daa4b91349a3f1cafb815302ed0c6fdbb2c2
+  data.tar.gz: afc024d09db7ddeffc1fe399c04241e17f33a8fa52066d3372beae5032cd1cd08248214cea641a66a8c707919910f5d06e4ec766adbcd2bf12ed928b326dfff1

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## Unreleased
+
+- Added `templates.instantiate_template` and the ticket-release lifecycle on
+  `events` (`list_ticket_releases`, `update_ticket_releases`, and
+  `close_ticket_release`). Template instantiation sends `{}` when no overrides
+  are supplied, URI-escapes identifiers, and uses exact-response replay;
+  ticket-release writes remain single-attempt.
+
+- **Security/reliability:** Mutations now default to a single attempt. Automatic header-replay
+  retries are limited to chart create/copy, template instantiation, 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,

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
@@ -25,8 +30,8 @@ require "seatlayer"
 
 client = SeatLayer::Client.new(ENV.fetch("SEATLAYER_SECRET_KEY"))
 
-# 1. Provision a venue for a new organiser from one of your templates.
-chart = client.charts.copy("c_template_arena")["meta"]
+# 1. Provision a venue for a new organiser from a public template.
+chart = client.templates.instantiate_template("arena-standard")["meta"]
 client.charts.publish(chart["id"])
 
 # 2. Create an event on it.
@@ -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
@@ -150,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:
 
@@ -166,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.
 
@@ -231,15 +251,21 @@ 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 five
+operations backed by exact response replay: `charts.create`, `charts.copy`,
+`templates.instantiate_template`, `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 five 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
@@ -252,7 +278,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 })
@@ -263,9 +290,10 @@ 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` |
+| `templates` | `instantiate_template` |
+| `events` | `list` `list_all` `create` `retrieve` `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` |
 | `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` |
+| `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` |
@@ -311,7 +339,7 @@ the public manifest, not just from the wrapper.
 | 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) |
+| Java (server) | [`io.seatlayer:seatlayer-java`](https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java/0.3.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) |
 

data/lib/seatlayer/channels.rb

@@ -65,26 +65,64 @@ module SeatLayer
     # 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: nil, buyer_ref: nil,
-                                    partner_ref: nil, client_request_id: nil, idempotency_key: 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,
-                       "maxQuantity" => max_quantity, "buyerRef" => buyer_ref,
-                       "partnerRef" => partner_ref, "clientRequestId" => client_request_id })
+                       "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, state: nil, limit: nil, cursor: nil)
+    def list_buyer_access_sessions(event_key, limit: nil)
       @client.get("/v1/events/#{encode(event_key)}/buyer-access-sessions",
-                  compact({ "state" => state, "limit" => limit, "cursor" => cursor }))
+                  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}"

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

@@ -62,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.
@@ -98,8 +103,9 @@ module SeatLayer
     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:)
@@ -147,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
 
@@ -174,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)}")
@@ -189,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
 
@@ -205,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
 
@@ -216,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)
@@ -102,6 +129,23 @@ module SeatLayer
     end
   end
 
+  # Published SeatLayer catalogue templates.
+  #
+  # Instantiation creates an independent draft chart. Publish that returned
+  # chart before creating an event from it.
+  class Templates < Resource
+    # Instantiate a public template into a new draft chart.
+    #
+    # +fields+ intentionally defaults to an empty Hash: the API requires a JSON
+    # object even when there are no overrides, and JSON.generate({}) is `{}`.
+    def instantiate_template(template_id, fields: {}, idempotency_key: nil)
+      @client.post(
+        "/v1/templates/#{encode(template_id)}/instantiate", fields,
+        idempotency_key: idempotency_key, retry_policy: :header_replay
+      )
+    end
+  end
+
   # Event lifecycle, metadata and reports.
   class Events < Resource
     # One page of events.
@@ -131,13 +175,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 +204,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,15 +238,32 @@ 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
 
+    def list_ticket_releases(event_key)
+      @client.get("/v1/events/#{encode(event_key)}/releases")
+    end
+
+    # Replace every ticket release for an event. This stays single-attempt: the
+    # route does not promise exact idempotent-response replay.
+    def update_ticket_releases(event_key, releases:)
+      @client.put("/v1/events/#{encode(event_key)}/releases", { "releases" => releases })
+    end
+
+    # Close one release while preserving its audit provenance.
+    def close_ticket_release(event_key, release_id)
+      @client.post("/v1/events/#{encode(event_key)}/releases/#{encode(release_id)}/close")
+    end
+
     def retrieve_report(event_key)
       @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.2.0"
+  VERSION = "0.4.0"
 end

data/lib/seatlayer.rb

@@ -19,7 +19,7 @@ require_relative "seatlayer/webhook"
 module SeatLayer
   # The SeatLayer client.
   class Client
-    attr_reader :charts, :events, :inventory, :channels, :sessions, :webhooks, :workspaces
+    attr_reader :charts, :events, :inventory, :channels, :sessions, :webhooks, :workspaces, :templates
 
     def initialize(secret_key, base_url: HTTPClient::DEFAULT_BASE_URL,
                    max_retries: HTTPClient::DEFAULT_MAX_RETRIES,
@@ -32,6 +32,7 @@ module SeatLayer
       @inventory = Inventory.new(@http)
       @channels = Channels.new(@http)
       @sessions = Sessions.new(@http)
+      @templates = Templates.new(@http)
       @webhooks = Webhooks.new(@http)
       @workspaces = Workspaces.new(@http)
     end
@@ -46,10 +47,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.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - SeatLayer