seatlayer 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d51f4f004070a397c4ac39e08f183df2c8a72dca70c35ce1ef61042d247b30c
-  data.tar.gz: a37f6748bf6d656ee1b5daa4902609678bf039992766c9fa9dce7742e4ee47f8
+  metadata.gz: 07a3046d14b181d770f7dddf673476c7b0d695d31d725adc042555afa145c144
+  data.tar.gz: 5923f05115c9741d3ab20ac8598616351eeac43d74a91b5da0c590275f0105b0
 SHA512:
-  metadata.gz: 25dfd25bc366329bb38f52f59522dde781225df50fcfe5b6c523e9b7af3ab54d16aa22b6c6ea022b8e65d5e98b1a8dcbabd04c3716026cc257918c0fa3b9ce73
-  data.tar.gz: 98af014bd435e3f5ee7233c5b3c8feeb9b4ed950e9df55b5c1be4ec1dc94506657cb83c0149202c9421bbf223efb760ad15fb713ea88797222326b435236f41c
+  metadata.gz: d9b16c52a2dad95aab45a2d0d75dad7be100ddb60497b554ce9adc1a86dacdab4e8a6dd273314ba67dd93a7156eebb5984550ebf9a5ad8c2cdc519a356ccf70a
+  data.tar.gz: 0fbe576e636045d4cdfc6ff3cffcbd16403fc3e595913832d352bdcebe66cc03fc128dcc2ab7bca3fc490558e099c77838a4fe6a88d54f66305c9a7928ea0ea8

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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,

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
@@ -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,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
@@ -252,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 })
@@ -263,9 +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` |
+| `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` |
+| `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` |

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)
@@ -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.2.0"
+  VERSION = "0.3.0"
 end

data/lib/seatlayer.rb

@@ -46,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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - SeatLayer