seatlayer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6aa9b6c1e8985b0f261f5e0bf7743148a2fcf5dc3c9f9585b482d78e24b492a5
+  data.tar.gz: 70b5fb6fd1f3eb7cbed9d80917a7e1ef56d212c1bafb924e97a961878e71e906
+SHA512:
+  metadata.gz: 21ab307cdbc1676e6d463c3bb990ebe886f5d38906b988d129d1f5a722c4199ffeb80938b582e3d7b906fe287b9ea5a190dda5043200f27f569fc0c2d2aab7f1
+  data.tar.gz: d4d261bb2e9240a49bf373fd9faa63896fac970f9fb7a9f5c7583becce1c26a445f45ff623115463e833587f0a58be1762990864dba1066139c384d62d85005e

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.1.0 — 2026-08-04
+
+First public release: RubyGems `seatlayer`.
+
+Initial contents of the SeatLayer Ruby server SDK.
+
+- `SeatLayer::Client` with secret-key auth, per-attempt timeouts, and an escape hatch.
+- Resources: `charts`, `events`, `inventory`, `sessions`, `webhooks`, `workspaces`.
+- Automatic `Idempotency-Key` on every mutation, reused across retries so a retried
+  booking cannot become two bookings.
+- Retries on 429/408/5xx with exponential backoff and full jitter; honours `Retry-After`.
+  4xx is never retried.
+- Typed errors: `AuthError` (with `mode_mismatch?`), `ConflictError` (with `conflicts`
+  and `sold_out?`), `RateLimitError`, `ValidationError`, `NotFoundError`,
+  `ConnectionError` — all under `SeatLayer::Error`.
+- `SeatLayer::Webhook.verify` — raw-body HMAC-SHA256 via `OpenSSL.secure_compare`.
+- `create_manage_session` requires explicit capabilities; the API's default grants
+  `event:cancel`, which unbooks paid seats and authorises gateway refunds.
+- Constructor rejects a `pk_` key by name rather than failing as a 401 later.
+- `list_all` returns a lazy `Enumerator` when no block is given, so
+  `.lazy.first(n)` does not walk every page.
+- No runtime dependencies — `net/http`, `json` and `openssl` from the standard library.
+
+Requires Ruby 3.0 or newer.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SeatLayer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,305 @@
+# SeatLayer Ruby SDK
+
+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
+> ticket buyer can reach — browser surfaces get short-lived, origin-bound tokens that you mint here.
+
+## Install
+
+```ruby
+gem "seatlayer"
+```
+
+```bash
+gem install seatlayer
+```
+
+Requires Ruby 3.0 or newer. **No runtime dependencies** — `net/http`, `json` and `openssl` from the
+standard library.
+
+## Quick start
+
+```ruby
+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"]
+client.charts.publish(chart["id"])
+
+# 2. Create an event on it.
+event = client.events.create(chart_id: chart["id"], name: "Spring Gala")["meta"]
+
+# 3. Sell four seats over the phone.
+held = client.inventory.hold_best_available(event["key"], qty: 4)
+# … take payment against held["items"], which carry authoritative prices …
+client.inventory.book(event["key"], hold_id: held["holdId"], booking_ref: "order-8842")
+```
+
+## Test vs live
+
+Keys carry their own mode. `sk_test_…` keys can only touch test-mode events and `sk_live_…` only
+live ones; crossing them returns `403 mode_mismatch`, surfaced as `AuthError` with `mode_mismatch?`.
+
+```ruby
+client = SeatLayer::Client.new(ENV.fetch("SEATLAYER_SECRET_KEY"))
+raise "Refusing to boot production against test-mode seating data." if
+  ENV["RAILS_ENV"] == "production" && client.mode != "live"
+```
+
+A publishable `pk_` key is rejected at construction with a message naming the mistake, rather than
+failing as a `401` three round-trips later.
+
+## The two selling flows
+
+**Buyer picks seats in the browser.** Your frontend holds them; your backend confirms the price and
+books. Never price from what the browser sent you — `retrieve_hold` is authoritative.
+
+```ruby
+hold = client.inventory.retrieve_hold(event_key, hold_id)
+total = hold["items"].sum { |item| item["unitPrice"] }
+# … charge `total` in hold["currency"] …
+client.inventory.book(event_key, hold_id: hold_id, booking_ref: charge.id)
+```
+
+**Your backend picks the seats.** Phone orders, box office, comps.
+
+```ruby
+# Payment already taken — book outright, so nothing is stranded if a second call fails.
+client.inventory.book_best_available(event_key, qty: 2, booking_ref: "phone-1183")
+
+# Or name the seats yourself.
+client.inventory.box_office_book(event_key, labels: ["A-1", "A-2"], booking_ref: "comp-14")
+```
+
+## Listing and pagination
+
+`list` returns one page plus a `nextCursor`. `list_all` pages for you and returns a lazy
+`Enumerator` when no block is given — the point of paginating is to *not* hold an unbounded result
+set in memory, so `.lazy.first(n)` stops fetching once it has enough.
+
+```ruby
+# One page, your own paging.
+page = client.events.list(limit: 50)
+page["events"]
+page["nextCursor"]   # nil once exhausted
+
+# Or let the SDK walk it.
+client.events.list_all do |event|
+  sync(event)
+end
+
+# Lazily — this fetches one page, not all of them.
+client.charts.list_all.lazy.first(5)
+```
+
+Listing events includes live availability `counts` by default, which costs the server one
+round-trip **per event**. `list_all` turns them off automatically — walking a whole catalogue is
+exactly when you don't want that — and you can control it explicitly:
+
+```ruby
+client.events.list(limit: 50, counts: false)
+```
+
+## Keeping a hold alive
+
+When an order takes longer than the checkout window — an invoice, a phone sale — extend rather than
+release and re-hold. Releasing first hands the seats to whoever is racing for them in between.
+
+```ruby
+begin
+  client.inventory.extend_hold(event_key, hold_id, ttl_ms: 10 * 60_000)
+rescue SeatLayer::ConflictError
+  # Gone, expired, or at its renewal cap — the buyer has to re-pick.
+end
+```
+
+## Embedding the control room
+
+Your secret key never reaches a browser. Mint a scoped token instead.
+
+```ruby
+session = client.sessions.create_manage_session(
+  event_key,
+  allowed_origin: "https://box-office.yourplatform.com",
+  capabilities: ["event:view", "event:block"],
+  expires_in_seconds: 3600
+)
+```
+
+`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.
+
+The full set, all opt-in:
+
+| Capability | Grants |
+|---|---|
+| `event:view` | Read the seat map and its live states |
+| `event:block` | Block and unblock seats |
+| `event:cancel` | Unbook paid seats and issue gateway refunds — destructive, moves money |
+| `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 |
+
+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.
+
+## Webhooks
+
+Verify every delivery against the **raw** body. Re-encoding a parsed Hash changes the bytes and
+verification will fail.
+
+```ruby
+# Rails
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def seatlayer
+    event = SeatLayer::Webhook.verify(
+      request.raw_post,                          # raw body, never params
+      request.headers["X-SeatLayer-Signature"],
+      ENV.fetch("SEATLAYER_WEBHOOK_SECRET")
+    )
+
+    # The signed body carries `at`, but nothing enforces a freshness window, so a
+    # captured delivery stays valid indefinitely. Deduplicate on occurrenceId —
+    # this is your replay protection, not an optimisation.
+    return head :ok if already_processed?(event["occurrenceId"])
+
+    Handler.call(event)
+    head :ok
+  rescue SeatLayer::WebhookVerificationError
+    head :bad_request
+  end
+end
+```
+
+## Errors
+
+```ruby
+begin
+  client.inventory.hold_best_available(event_key, qty: 6)
+rescue SeatLayer::ConflictError => e
+  return show_alternative_dates if e.sold_out?   # a business outcome, not a bug
+  raise
+rescue SeatLayer::RateLimitError => e
+  return retry_after(e.retry_after)
+rescue SeatLayer::AuthError => e
+  raise "Test key pointed at a live event, or the reverse." if e.mode_mismatch?
+  raise
+end
+```
+
+| Class | Status | Means |
+|---|---|---|
+| `AuthError` | 401, 403 | Bad, revoked, or wrong-mode key |
+| `NotFoundError` | 404 | No such resource *for this organisation* |
+| `ConflictError` | 409 | Inventory moved, or a guard rejected the change |
+| `ValidationError` | 422 | Understood and rejected |
+| `RateLimitError` | 429 | Over budget; carries `retry_after` |
+| `ConnectionError` | — | No answer: DNS, TLS, socket, timeout |
+
+All descend from `SeatLayer::Error`, so `rescue SeatLayer::Error` catches everything. Every API
+error carries `status`, `code`, `body` and `request_id` — quote the request id in support requests.
+
+## 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.
+
+**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:
+
+```ruby
+client.inventory.book(event_key, hold_id: hold_id, idempotency_key: "order-#{order_id}")
+```
+
+```ruby
+SeatLayer::Client.new(
+  ENV.fetch("SEATLAYER_SECRET_KEY"),
+  max_retries: 3,   # total attempts
+  timeout: 30.0     # seconds, per attempt
+)
+```
+
+## Escape hatch
+
+For surface this SDK does not wrap yet — same auth, retries, idempotency and error mapping:
+
+```ruby
+client.request("POST", "/v1/events/ev_1/some-new-route", body: { "qty" => 2 })
+```
+
+## API surface
+
+| 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` |
+| `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` |
+
+Full reference: [docs.seatlayer.io/server-sdk](https://docs.seatlayer.io/server-sdk/install/)
+
+### Deliberately not in this SDK
+
+Some API surface is intentionally unwrapped, not merely pending:
+
+- **Hosted-checkout orders and refunds.** Reading or refunding a SeatLayer-hosted-checkout sale is
+  not a server-SDK capability. Those records only exist for organisations using hosted checkout; if
+  you run your own commerce store you refund in that store, through your own gateway.
+- **Connecting or assigning payment gateways.** Connecting one is a dashboard flow, so shipping only
+  the assignment half across seven SDKs would hand you a method that cannot yet succeed.
+- **Realtime seat updates.** Live seat state reaches the *browser* through the widget's own socket.
+  There is no server-side subscribe; a secret-key caller gets authoritative state from
+  `events.retrieve_report` and `inventory.retrieve_availability`.
+
+None of these are reachable through `request` as a supported path either — they are excluded from
+the public manifest, not just from the wrapper.
+
+## Related resources
+
+- [Server SDK guide](https://docs.seatlayer.io/server-sdk/install/)
+- [Errors, retries and idempotency](https://docs.seatlayer.io/server-sdk/reliability/)
+- [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)
+- [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) |
+| 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) |
+
+## Development
+
+```bash
+bundle install
+bundle exec rubocop
+bundle exec rspec
+```
+
+## License
+
+MIT

data/lib/seatlayer/errors.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module SeatLayer
+  # Base class for every SeatLayer error.
+  class Error < StandardError; end
+
+  # Raised for any non-2xx response.
+  #
+  # The API answers failures with {"error":…, "code":…, "message":…} and a status.
+  # Surfacing that as one opaque exception leaves every caller string-matching on
+  # +error+. The subclasses below are the ones an integration actually branches
+  # on — a sold-out seat is a business outcome that belongs in a rescue of its
+  # own, not lumped in with a bad key.
+  class APIError < Error
+    # @return [Integer] HTTP status the API answered with.
+    attr_reader :status
+    # @return [String] machine-readable slug: body "code", falling back to "error".
+    attr_reader :code
+    # @return [Hash] the decoded error body, for fields this SDK does not model.
+    attr_reader :body
+    # @return [String, nil] correlation id from X-Request-ID. Quote it in support requests.
+    attr_reader :request_id
+
+    def initialize(status:, code:, body:, request_id:, message: nil)
+      @status = status
+      @code = code
+      @body = body
+      @request_id = request_id
+      super(message || "SeatLayer API error #{status} (#{code})")
+    end
+
+    # Build the most specific error class for a response.
+    def self.from_response(status:, body:, request_id:, retry_after:)
+      code = presence(body["code"]) || presence(body["error"]) || "unknown_error"
+      attrs = { status: status, code: code, body: body, request_id: request_id,
+                message: presence(body["message"]) }
+
+      case status
+      when 401, 403 then AuthError.new(**attrs)
+      when 404 then NotFoundError.new(**attrs)
+      when 409 then ConflictError.new(**attrs)
+      when 422 then ValidationError.new(**attrs)
+      when 429 then RateLimitError.new(**attrs, retry_after: retry_after)
+      else APIError.new(**attrs)
+      end
+    end
+
+    def self.presence(value)
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+    private_class_method :presence
+  end
+
+  # 401/403 — bad key, revoked key, or a live key used against a test event.
+  class AuthError < APIError
+    # The key's mode and the event's mode disagree. The most common cause of a
+    # "works locally, 403s in production" report.
+    def mode_mismatch?
+      code == "mode_mismatch"
+    end
+  end
+
+  # 404 — including another organisation's resource.
+  #
+  # Asking for something owned by a different organisation answers 404, never
+  # 403: a 403 would confirm the resource exists, which is not something one
+  # customer should be able to learn about another.
+  class NotFoundError < APIError; end
+
+  # 409 — the seats moved under you.
+  #
+  # Normal in ticketing, not exceptional: two buyers wanted the same seat and one
+  # lost.
+  class ConflictError < APIError
+    # @return [Array<Hash>] per-object conflicts, when the endpoint reports them.
+    def conflicts
+      value = body["conflicts"]
+      value.is_a?(Array) ? value.grep(Hash) : []
+    end
+
+    # Best-available could not find enough free inventory.
+    def sold_out?
+      %w[sold_out not_enough_together].include?(body["reason"])
+    end
+  end
+
+  # 422 — the request was understood and rejected.
+  class ValidationError < APIError; end
+
+  # 429. +retry_after+ prefers the header over the JSON field.
+  class RateLimitError < APIError
+    # @return [Float] seconds to wait before retrying.
+    attr_reader :retry_after
+
+    def initialize(retry_after:, **attrs)
+      @retry_after = retry_after
+      super(**attrs)
+    end
+  end
+
+  # The request never got an answer: DNS, TLS, socket, or timeout.
+  class ConnectionError < Error; end
+
+  # The webhook delivery did not come from SeatLayer. Respond 400; do not
+  # process it.
+  class WebhookVerificationError < Error; end
+end

data/lib/seatlayer/http_client.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+module SeatLayer
+  # The transport: auth, idempotency, retry, and error mapping.
+  #
+  # Built on net/http from the standard library rather than Faraday or HTTParty.
+  # A server SDK that drags in an HTTP stack becomes a supply-chain surface for
+  # every customer who installs it, and can conflict with whatever the host
+  # application already uses.
+  class HTTPClient
+    DEFAULT_BASE_URL = "https://api.seatlayer.io"
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_TIMEOUT = 30.0
+
+    # The API's own charset for Idempotency-Key.
+    IDEMPOTENCY_KEY_PATTERN = /\A[A-Za-z0-9._:-]{1,128}\z/
+
+    # @return [String] "live", "test", or "unknown", derived from the key prefix.
+    attr_reader :mode
+    attr_reader :base_url
+
+    def initialize(secret_key:, base_url: DEFAULT_BASE_URL, max_retries: DEFAULT_MAX_RETRIES,
+                   timeout: DEFAULT_TIMEOUT, transport: nil)
+      raise ArgumentError, "A SeatLayer secret key is required." if secret_key.nil? || secret_key.empty?
+
+      # Caught here rather than as a 401 three round-trips later. The pk_ case
+      # gets its own message: it is the one people paste by mistake.
+      if secret_key.start_with?("pk_")
+        raise ArgumentError,
+              "That is a publishable key. The server SDK needs a secret key (sk_live_… or sk_test_…)."
+      end
+      unless secret_key.start_with?("sk_")
+        raise ArgumentError, "A SeatLayer secret key starts with sk_live_ or sk_test_."
+      end
+
+      @secret_key = secret_key
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @max_retries = max_retries
+      @timeout = timeout
+      @transport = transport
+      @mode = if secret_key.start_with?("sk_test_") then "test"
+              elsif secret_key.start_with?("sk_live_") then "live"
+              else "unknown"
+              end
+    end
+
+    def self.validate_idempotency_key!(key)
+      return if IDEMPOTENCY_KEY_PATTERN.match?(key)
+
+      raise ArgumentError,
+            "Invalid Idempotency-Key #{key.inspect}: allowed characters are " \
+            "A-Z a-z 0-9 . _ : - and the length must be 1-128."
+    end
+
+    # Percent-encode a path segment, including slashes.
+    def self.encode(segment)
+      URI.encode_www_form_component(segment.to_s).gsub("+", "%20")
+    end
+
+    def request(method, path, query: nil, body: nil, idempotency_key: nil)
+      url = @base_url + path
+      if query
+        pairs = query.compact
+        url += "?#{URI.encode_www_form(pairs)}" unless pairs.empty?
+      end
+
+      headers = {
+        "Authorization" => "Bearer #{@secret_key}",
+        "Accept" => "application/json",
+        "User-Agent" => "seatlayer-ruby"
+      }
+      payload = nil
+      if body
+        payload = JSON.generate(body)
+        headers["Content-Type"] = "application/json"
+      end
+
+      # 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.
+      unless %w[GET HEAD].include?(method)
+        key = idempotency_key || SecureRandom.uuid
+        self.class.validate_idempotency_key!(key)
+        headers["Idempotency-Key"] = key
+      end
+
+      execute(method, url, headers, payload)
+    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)
+    end
+
+    def put(path, body)
+      request("PUT", path, body: body)
+    end
+
+    def patch(path, body)
+      request("PATCH", path, body: body)
+    end
+
+    def delete(path)
+      request("DELETE", path)
+    end
+
+    private
+
+    # 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)
+      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
+
+          last_error = e
+          sleep(backoff(attempt, nil))
+          next
+        end
+
+        status = response[:status]
+        return parse_success(status, response[:body]) if status >= 200 && status < 300
+
+        error_body = decode_error_body(response[:body])
+        retry_after = parse_retry_after(response[:headers], error_body)
+
+        if retryable?(status) && attempt < @max_retries - 1
+          sleep(backoff(attempt, status == 429 ? retry_after : nil))
+          next
+        end
+
+        raise APIError.from_response(
+          status: status, body: error_body,
+          request_id: response[:headers]["x-request-id"], retry_after: retry_after
+        )
+      end
+
+      raise last_error || ConnectionError.new("Request failed with no attempts made.")
+    end
+
+    # A proxy or WAF can answer with HTML; that must not become a parse crash
+    # that hides the real status from the caller.
+    def decode_error_body(body)
+      parsed = JSON.parse(body.to_s)
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def parse_success(status, body)
+      return {} if status == 204 || body.nil? || body.empty?
+
+      JSON.parse(body)
+    end
+
+    def send_request(method, url, headers, payload)
+      return @transport.call(method, url, headers, payload) if @transport
+
+      uri = URI.parse(url)
+      request_class = Net::HTTP.const_get(method.capitalize)
+      http_request = request_class.new(uri)
+      headers.each { |name, value| http_request[name] = value }
+      http_request.body = payload if payload
+
+      response = Net::HTTP.start(uri.hostname, uri.port,
+                                 use_ssl: uri.scheme == "https",
+                                 open_timeout: @timeout, read_timeout: @timeout) do |http|
+        http.request(http_request)
+      end
+
+      normalised = {}
+      response.each_header { |name, value| normalised[name.downcase] = value }
+      { status: response.code.to_i, body: response.body, headers: normalised }
+    rescue StandardError => e
+      raise ConnectionError, "Request to #{method} #{url} failed: #{e.message}"
+    end
+
+    # Retry only what is safe to retry. 429 and 5xx are transient by definition;
+    # a 4xx is the API saying the request itself is wrong, and retrying only
+    # burns rate-limit budget and delays the error the caller needs to see.
+    def retryable?(status)
+      status == 429 || status == 408 || (status >= 500 && status < 600)
+    end
+
+    # Exponential with full jitter, so a fleet of workers limited at the same
+    # moment does not retry in lockstep and re-limit itself.
+    def backoff(attempt, retry_after)
+      return retry_after if retry_after
+
+      ceiling = [8.0, 0.25 * (2**attempt)].min
+      rand * ceiling
+    end
+
+    def parse_retry_after(headers, body)
+      header = headers["retry-after"]
+      if header
+        seconds = Float(header, exception: false)
+        return seconds if seconds && seconds >= 0
+      end
+      # Fall back to the JSON field for routes that predate the headers.
+      field = body["retryAfterSeconds"]
+      field.is_a?(Numeric) ? field.to_f : 1.0
+    end
+  end
+end

data/lib/seatlayer/inventory.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module SeatLayer
+  # Holds, booking, blocking and availability.
+  #
+  # Two complete flows, both first-class:
+  #
+  #   browser holds → retrieve_hold for authoritative pricing → charge → book(hold_id:)
+  #   backend books labels directly — box office, phone sales, comps
+  #
+  # 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
+    def hold(event_key, labels: nil, selections: nil, ttl_ms: nil,
+             replace_hold_id: nil, idempotency_key: nil)
+      body = compact({ "labels" => labels, "selections" => selections,
+                       "ttlMs" => ttl_ms, "replaceHoldId" => replace_hold_id })
+      @client.post(path(event_key, "/hold"), body, idempotency_key: idempotency_key)
+    end
+
+    # Ask us to pick the best free objects and hold them.
+    #
+    # The picker is the one the buyer widget uses, so a phone order and a web
+    # 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)
+      body = compact({ "qty" => qty, "categoryKey" => category_key,
+                       "zoneId" => zone_id, "ttlMs" => ttl_ms })
+      @client.post(path(event_key, "/best-available"), body, idempotency_key: idempotency_key)
+    end
+
+    # Pick and book in one call — the box-office shape.
+    #
+    # 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 })
+      @client.post(path(event_key, "/best-available-book"), body, idempotency_key: idempotency_key)
+    end
+
+    # Push an active hold's expiry out by a fresh window before it lapses.
+    #
+    # Use this rather than release-and-re-hold when an order takes longer than
+    # 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 }))
+    end
+
+    # Authoritative items and prices. Charge from this, not the browser.
+    def retrieve_hold(event_key, hold_id)
+      @client.get(path(event_key, "/holds/#{encode(hold_id)}"))
+    end
+
+    def release(event_key, labels:, hold_id:)
+      @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 })
+      @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 },
+                   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 })
+    end
+
+    # Hold inventory back from sale (house seats, production holds).
+    def block(event_key, labels:)
+      @client.post(path(event_key, "/block"), { "labels" => labels })
+    end
+
+    def unblock(event_key, labels:)
+      @client.post(path(event_key, "/unblock"), { "labels" => labels })
+    end
+
+    def unblock_all(event_key)
+      @client.post(path(event_key, "/unblock-all"))
+    end
+
+    def retrieve_availability(event_key)
+      @client.get(path(event_key, "/availability"))
+    end
+
+    def update_availability(event_key, fields)
+      @client.post(path(event_key, "/availability"), fields)
+    end
+
+    private
+
+    def path(event_key, suffix)
+      "/v1/events/#{encode(event_key)}#{suffix}"
+    end
+  end
+
+  # Short-lived, origin-bound browser tokens.
+  #
+  # 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
+
+    # 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)
+      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."
+      end
+
+      body = compact({ "allowedOrigin" => allowed_origin, "capabilities" => capabilities,
+                       "expiresInSeconds" => expires_in_seconds })
+      @client.post("/v1/events/#{encode(event_key)}/manage-sessions", body)
+    end
+
+    def revoke_manage_session(event_key, session_id)
+      @client.delete("/v1/events/#{encode(event_key)}/manage-sessions/#{encode(session_id)}")
+    end
+
+    # 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.
+    def create_designer_session(workspace_id:, chart_id:, allowed_origin:,
+                                authority: nil, mode: nil, expires_in_seconds: nil)
+      body = compact({ "workspaceId" => workspace_id, "chartId" => chart_id,
+                       "allowedOrigin" => allowed_origin, "authority" => authority,
+                       "mode" => mode, "expiresInSeconds" => expires_in_seconds })
+      @client.post("/v1/designer/sessions", body)
+    end
+
+    def revoke_designer_session(session_id)
+      @client.delete("/v1/designer/sessions/#{encode(session_id)}")
+    end
+  end
+
+  # Manage webhook subscriptions. To VERIFY a delivery, see SeatLayer::Webhook.
+  class Webhooks < Resource
+    def list
+      @client.get("/v1/webhooks")
+    end
+
+    def create(url:, events:)
+      @client.post("/v1/webhooks", { "url" => url, "events" => events })
+    end
+
+    def update(webhook_id, fields)
+      @client.patch("/v1/webhooks/#{encode(webhook_id)}", fields)
+    end
+
+    def delete(webhook_id)
+      @client.delete("/v1/webhooks/#{encode(webhook_id)}")
+    end
+
+    def list_deliveries(webhook_id)
+      @client.get("/v1/webhooks/#{encode(webhook_id)}/deliveries")
+    end
+  end
+
+  # Workspaces isolate one tenant's charts and events from another's.
+  class Workspaces < Resource
+    def list
+      @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)
+    end
+
+    def retrieve(workspace_id)
+      @client.get("/v1/workspaces/#{encode(workspace_id)}")
+    end
+
+    # Rename, re-reference, or disable a workspace.
+    #
+    # The organisation's default workspace cannot be disabled — the API answers
+    # 409 +default_workspace_required+. Promote another one first.
+    def update(workspace_id, fields)
+      @client.patch("/v1/workspaces/#{encode(workspace_id)}", fields)
+    end
+  end
+end

data/lib/seatlayer/resources.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module SeatLayer
+  # Shared plumbing for the resource namespaces.
+  class Resource
+    def initialize(client)
+      @client = client
+    end
+
+    private
+
+    # Build a request body, dropping nils so optional arguments stay optional
+    # rather than being sent as explicit JSON null.
+    def compact(hash)
+      hash.compact
+    end
+
+    def encode(segment)
+      HTTPClient.encode(segment)
+    end
+  end
+
+  # Seat-map definitions that events are created from.
+  #
+  # Even when organisers draw their own venues in the embedded Designer you need
+  # this: +create_designer_session+ requires a chart id that already exists, so
+  # the usual platform flow is copy a template here, then hand over a session.
+  class Charts < Resource
+    # One page of charts. Pass +cursor+ from the previous page's "nextCursor".
+    def list(workspace_id: nil, external_ref: nil, archived: false, limit: nil, cursor: nil)
+      query = compact({ "workspaceId" => workspace_id, "externalRef" => external_ref,
+                        "limit" => limit, "cursor" => cursor })
+      query["archived"] = "1" if archived
+      @client.get("/v1/charts", query)
+    end
+
+    # Every chart, paging transparently.
+    #
+    # Returns an Enumerator when no block is given, so it stays lazy — the point
+    # of paginating was to not hold an unbounded result set in memory, and
+    # returning an Array would hand that problem straight back.
+    #
+    #   client.charts.list_all { |chart| ... }
+    #   client.charts.list_all.lazy.first(5)
+    def list_all(**options, &block)
+      return enum_for(:list_all, **options) unless block_given?
+
+      cursor = nil
+      loop do
+        page = list(**options, cursor: cursor)
+        Array(page["charts"]).each(&block)
+        cursor = page["nextCursor"]
+        # An absent cursor terminates, so a caller looping cannot spin forever.
+        break if cursor.nil? || cursor.empty?
+      end
+    end
+
+    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)
+    end
+
+    def retrieve(chart_id)
+      @client.get("/v1/charts/#{encode(chart_id)}")
+    end
+
+    # Replace a chart document.
+    #
+    # +expected_updated_at+ is required for optimistic concurrency and is not
+    # optional here either: without it two concurrent writers silently overwrite
+    # each other, and a seat map is exactly the document where that loses work.
+    # Read it from +retrieve+ immediately before writing.
+    #
+    # 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 })
+      @client.put("/v1/charts/#{encode(chart_id)}", body)
+    end
+
+    def delete(chart_id)
+      @client.delete("/v1/charts/#{encode(chart_id)}")
+    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)
+    end
+
+    def archive(chart_id)
+      @client.post("/v1/charts/#{encode(chart_id)}/archive")
+    end
+
+    def unarchive(chart_id)
+      @client.post("/v1/charts/#{encode(chart_id)}/unarchive")
+    end
+
+    # Publish the draft. Events can only be created from a published chart.
+    def publish(chart_id)
+      @client.post("/v1/charts/#{encode(chart_id)}/publish")
+    end
+  end
+
+  # Event lifecycle, metadata and reports.
+  class Events < Resource
+    # One page of events.
+    #
+    # Live availability counts cost one round-trip per event server-side. They
+    # are on by default because most callers of a single page want them; pass
+    # <tt>counts: false</tt> when paging a whole catalogue.
+    def list(workspace_id: nil, external_ref: nil, limit: nil, cursor: nil, counts: true)
+      query = compact({ "workspaceId" => workspace_id, "externalRef" => external_ref,
+                        "limit" => limit, "cursor" => cursor })
+      query["counts"] = "0" unless counts
+      @client.get("/v1/events", query)
+    end
+
+    # Every event, paging transparently. Counts default off here — you are
+    # walking the whole list, so per-event availability is rarely what you want
+    # and always what it costs.
+    def list_all(counts: false, **options, &block)
+      return enum_for(:list_all, counts: counts, **options) unless block_given?
+
+      cursor = nil
+      loop do
+        page = list(**options, counts: counts, cursor: cursor)
+        Array(page["events"]).each(&block)
+        cursor = page["nextCursor"]
+        break if cursor.nil? || cursor.empty?
+      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)
+    end
+
+    def retrieve(event_key)
+      @client.get("/v1/events/#{encode(event_key)}")
+    end
+
+    def update(event_key, fields)
+      @client.patch("/v1/events/#{encode(event_key)}", fields)
+    end
+
+    def delete(event_key)
+      @client.delete("/v1/events/#{encode(event_key)}")
+    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")
+    end
+
+    # Stop buyer sales. Existing holds keep their TTL.
+    def close(event_key)
+      @client.post("/v1/events/#{encode(event_key)}/close")
+    end
+
+    def reopen(event_key)
+      @client.post("/v1/events/#{encode(event_key)}/reopen")
+    end
+
+    def archive(event_key)
+      @client.post("/v1/events/#{encode(event_key)}/archive")
+    end
+
+    def retrieve_hold_ttl(event_key)
+      @client.get("/v1/events/#{encode(event_key)}/hold-ttl")
+    end
+
+    def update_hold_ttl(event_key, hold_ttl_ms)
+      @client.post("/v1/events/#{encode(event_key)}/hold-ttl", { "holdTtlMs" => hold_ttl_ms })
+    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")
+    end
+  end
+end

data/lib/seatlayer/version.rb

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

data/lib/seatlayer/webhook.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module SeatLayer
+  # Webhook signature verification.
+  #
+  # The most security-sensitive thing an integrator writes by hand, and the two
+  # classic mistakes are both easy to make and silent:
+  #
+  # 1. verifying against a re-serialised body, which changes bytes and fails — or
+  #    worse, gets "fixed" by skipping verification entirely;
+  # 2. comparing signatures with ==, which leaks the expected value through timing.
+  #
+  # So the SDK does it, takes the RAW body, and compares in constant time.
+  module Webhook
+    module_function
+
+    # Verify a delivery and return its decoded payload.
+    #
+    # +payload+ must be the raw request body. In Rails that is
+    # <tt>request.raw_post</tt>; in Sinatra, <tt>request.body.read</tt>. Never a
+    # parsed Hash re-encoded.
+    #
+    # NOTE ON REPLAY: deliveries are signed over the body, which carries an "at"
+    # timestamp — but nothing enforces a freshness window, so a captured delivery
+    # stays valid indefinitely. Replay protection is yours: every event carries
+    # an occurrenceId, and the correct pattern is to record processed ids and
+    # ignore repeats. Do not skip this.
+    #
+    # @raise [SeatLayer::WebhookVerificationError] when the delivery is not ours
+    def verify(payload, signature, secret)
+      raise WebhookVerificationError, "A webhook signing secret is required." if secret.nil? || secret.empty?
+
+      if signature.nil? || signature.empty?
+        raise WebhookVerificationError, "Missing X-SeatLayer-Signature header."
+      end
+
+      scheme, _, provided = signature.partition("=")
+      if scheme != "sha256" || provided.empty?
+        raise WebhookVerificationError,
+              "Unsupported signature format #{signature.inspect}; expected \"sha256=<hex>\"."
+      end
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
+      # secure_compare is constant time and handles a length mismatch without
+      # leaking which of the two failures occurred.
+      unless OpenSSL.secure_compare(expected, provided)
+        raise WebhookVerificationError, "Webhook signature did not match."
+      end
+
+      begin
+        JSON.parse(payload)
+      rescue JSON::ParserError => e
+        raise WebhookVerificationError, "Signature verified but the body is not valid JSON: #{e.message}"
+      end
+    end
+  end
+end

data/lib/seatlayer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "seatlayer/version"
+require_relative "seatlayer/errors"
+require_relative "seatlayer/http_client"
+require_relative "seatlayer/resources"
+require_relative "seatlayer/inventory"
+require_relative "seatlayer/webhook"
+
+# Official Ruby server SDK for the SeatLayer reserved-seating API.
+#
+# Server-side only: this gem authenticates with your secret key. Never load it
+# anywhere a ticket buyer can reach — browser surfaces get short-lived, scoped
+# tokens that you mint with SeatLayer::Sessions.
+#
+#   client = SeatLayer::Client.new(ENV.fetch("SEATLAYER_SECRET_KEY"))
+#   held = client.inventory.hold_best_available("summer-gala", qty: 4)
+module SeatLayer
+  # The SeatLayer client.
+  class Client
+    attr_reader :charts, :events, :inventory, :sessions, :webhooks, :workspaces
+
+    def initialize(secret_key, base_url: HTTPClient::DEFAULT_BASE_URL,
+                   max_retries: HTTPClient::DEFAULT_MAX_RETRIES,
+                   timeout: HTTPClient::DEFAULT_TIMEOUT, transport: nil)
+      @http = HTTPClient.new(secret_key: secret_key, base_url: base_url,
+                             max_retries: max_retries, timeout: timeout, transport: transport)
+
+      @charts = Charts.new(@http)
+      @events = Events.new(@http)
+      @inventory = Inventory.new(@http)
+      @sessions = Sessions.new(@http)
+      @webhooks = Webhooks.new(@http)
+      @workspaces = Workspaces.new(@http)
+    end
+
+    # @return [String] "live" or "test", derived from the key prefix.
+    def mode
+      @http.mode
+    end
+
+    # Dependency-aware readiness probe.
+    def ready
+      @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)
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: seatlayer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- SeatLayer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Server-side Ruby client for SeatLayer: charts, events, holds, booking,
+  embed sessions and webhook verification, with idempotency and retries built in.'
+email:
+- hello@seatlayer.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/seatlayer.rb
+- lib/seatlayer/errors.rb
+- lib/seatlayer/http_client.rb
+- lib/seatlayer/inventory.rb
+- lib/seatlayer/resources.rb
+- lib/seatlayer/version.rb
+- lib/seatlayer/webhook.rb
+homepage: https://seatlayer.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://seatlayer.io
+  documentation_uri: https://docs.seatlayer.io/server-sdk/install/
+  source_code_uri: https://github.com/seatlayer/seatlayer-ruby
+  changelog_uri: https://github.com/seatlayer/seatlayer-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/seatlayer/seatlayer-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby server SDK for the SeatLayer reserved-seating API.
+test_files: []