seatlayer 0.8.0 → 0.9.0

data/lib/seatlayer/holders.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module SeatLayer
+  # Season holders and customers: contact details, sessions, tickets, ticket
+  # transfers between holders, returns, and renewals.
+  class Holders < Resource
+    # One page of customers, or the one matching +email+ or +holder_ref+.
+    def list_customers(email: nil, holder_ref: nil, cursor: nil, limit: nil)
+      @client.get("/v1/customers", compact({ "email" => email, "holderRef" => holder_ref,
+                                             "cursor" => cursor, "limit" => limit }))
+    end
+
+    # Read one holder.
+    def retrieve_holder(holder_ref)
+      @client.get(path(holder_ref))
+    end
+
+    # Set a holder's email, name or phone. Pass +nil+ for +name+ or +phone+ to
+    # send an explicit JSON null.
+    def update_holder(holder_ref, email: nil, name: UNSET, phone: UNSET, idempotency_key: nil)
+      body = compact({ "email" => email })
+      body.merge!(supplied({ "name" => name, "phone" => phone }))
+      @client.mutation_with_header_replay(
+        "PATCH", path(holder_ref), body, idempotency_key: idempotency_key
+      )
+    end
+
+    # Sign a holder out of every session, or only out of +session_id+.
+    # Single-attempt.
+    def revoke_holder_sessions(holder_ref, session_id: nil)
+      @client.post(path(holder_ref, "/sessions/revoke"), compact({ "sessionId" => session_id }))
+    end
+
+    # List the Seasons a holder belongs to.
+    def list_holder_seasons(holder_ref)
+      @client.get(path(holder_ref, "/seasons"))
+    end
+
+    # One page of a holder's tickets. +from+ and +to+ are epoch milliseconds.
+    def list_holder_tickets(holder_ref, season_key: nil, from: nil, to: nil, cursor: nil,
+                            limit: nil)
+      @client.get(path(holder_ref, "/tickets"),
+                  compact({ "seasonKey" => season_key, "from" => from, "to" => to,
+                            "cursor" => cursor, "limit" => limit }))
+    end
+
+    # Read one of a holder's tickets.
+    def retrieve_holder_ticket(holder_ref, ticket_id)
+      @client.get(path(holder_ref, "/tickets/#{encode(ticket_id)}"))
+    end
+
+    # Offer tickets to another person by email. Turning customer sends off in
+    # Settings › Ticket site doesn't stop your server; cut-offs still apply.
+    def create_holder_transfer(holder_ref, ticket_ids:, to_email:, idempotency_key: nil)
+      @client.post(path(holder_ref, "/transfers"),
+                   { "ticketIds" => ticket_ids, "toEmail" => to_email },
+                   idempotency_key: idempotency_key, retry_policy: :header_replay)
+    end
+
+    # List a holder's ticket transfers.
+    def list_holder_transfers(holder_ref)
+      @client.get(path(holder_ref, "/transfers"))
+    end
+
+    # Cancel a transfer that has not been accepted yet. Single-attempt.
+    def cancel_holder_transfer(holder_ref, transfer_id)
+      @client.post(path(holder_ref, "/transfers/#{encode(transfer_id)}/cancel"))
+    end
+
+    # Accept a transfer for its recipient. Single-attempt.
+    def accept_holder_transfer(holder_ref, transfer_id)
+      @client.post(path(holder_ref, "/transfers/#{encode(transfer_id)}/accept"))
+    end
+
+    # Give back a holder's seat on one date, one per ticket: 1 to 20 tickets,
+    # all of one Season. A repeat with the same key answers with the same return.
+    # Turning give-backs off in Settings › Ticket site doesn't stop your server;
+    # cut-offs still apply.
+    def create_holder_return(holder_ref, ticket_ids:, idempotency_key: nil)
+      @client.post(path(holder_ref, "/returns"), { "ticketIds" => ticket_ids },
+                   idempotency_key: idempotency_key, retry_policy: :header_replay)
+    end
+
+    # Start a SeatLayer checkout that renews one of a holder's offers (+renewalOffer+
+    # on +list_holder_seasons+). Send the buyer to +payment.url+. Retried with one
+    # Idempotency-Key, which answers the same order.
+    def create_holder_renewal_checkout(holder_ref, offer_id, return_url:, buyer_email: nil,
+                                       buyer_name: nil, provider: nil, idempotency_key: nil)
+      @client.post(path(holder_ref, "/renewal-offers/#{encode(offer_id)}/checkout"),
+                   compact({ "returnUrl" => return_url, "buyerEmail" => buyer_email,
+                             "buyerName" => buyer_name, "provider" => provider }),
+                   idempotency_key: idempotency_key, retry_policy: :header_replay)
+    end
+
+    # Decline one of a holder's renewal offers and release its seats. +reason+
+    # (1 to 200 characters) is kept on the offer as +declineReason+; declining
+    # again answers the same offer, with the first reason. Single-attempt.
+    def decline_holder_renewal_offer(holder_ref, offer_id, reason: nil)
+      @client.post(path(holder_ref, "/renewal-offers/#{encode(offer_id)}/decline"),
+                   compact({ "reason" => reason }))
+    end
+
+    private
+
+    def path(holder_ref, suffix = "")
+      "/v1/holders/#{encode(holder_ref)}#{suffix}"
+    end
+  end
+end

data/lib/seatlayer/http_client.rb

@@ -64,17 +64,8 @@ module SeatLayer
 
     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
-        url += "?#{URI.encode_www_form(pairs)}" unless pairs.empty?
-      end
-
-      headers = {
-        "Authorization" => "Bearer #{@secret_key}",
-        "Accept" => "application/json",
-        "User-Agent" => "seatlayer-ruby"
-      }
+      url = build_url(path, query)
+      headers = default_headers
       payload = build_payload(body, raw_body, content_type, headers)
 
       # Only operations with exact server-side response replay get an automatic
@@ -97,6 +88,13 @@ module SeatLayer
       request("GET", path, query: query)
     end
 
+    # Internal path for CSV exports. Same auth, retries and error mapping as
+    # #get, but a success body comes back as the raw String, never parsed.
+    def get_text(path, query = nil)
+      headers = default_headers.merge("Accept" => "text/csv")
+      execute("GET", build_url(path, query), headers, nil, retry_allowed: true, text: true)
+    end
+
     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
@@ -125,6 +123,22 @@ module SeatLayer
 
     private
 
+    def build_url(path, query)
+      url = @base_url + path
+      return url unless query
+
+      pairs = query.compact
+      pairs.empty? ? url : "#{url}?#{URI.encode_www_form(pairs)}"
+    end
+
+    def default_headers
+      {
+        "Authorization" => "Bearer #{@secret_key}",
+        "Accept" => "application/json",
+        "User-Agent" => "seatlayer-ruby"
+      }
+    end
+
     def build_payload(body, raw_body, content_type, headers)
       raise ArgumentError, "body and raw_body are mutually exclusive" if !body.nil? && !raw_body.nil?
 
@@ -140,7 +154,7 @@ module SeatLayer
 
     # 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, retry_allowed:)
+    def execute(method, url, headers, payload, retry_allowed:, text: false)
       last_error = nil
 
       @max_retries.times do |attempt|
@@ -155,7 +169,7 @@ module SeatLayer
         end
 
         status = response[:status]
-        return parse_success(status, response[:body]) if status >= 200 && status < 300
+        return parse_success(status, response[:body], text) if status >= 200 && status < 300
 
         error_body = decode_error_body(response[:body])
         retry_after = parse_retry_after(response[:headers], error_body)
@@ -183,7 +197,8 @@ module SeatLayer
       {}
     end
 
-    def parse_success(status, body)
+    def parse_success(status, body, text)
+      return body.to_s if text
       return {} if status == 204 || body.nil? || body.empty?
 
       JSON.parse(body)

data/lib/seatlayer/inventory.rb

@@ -205,9 +205,26 @@ module SeatLayer
 
   # Manage webhook subscriptions. To VERIFY a delivery, see SeatLayer::Webhook.
   class Webhooks < Resource
+    # All 58 public event names, in the order the API lists them.
     EVENT_NAMES = [
-      "seat.booked", "seat.released", "seat.blocked", "hold.expired",
-      "hold.created", "hold.extended", "event.created", "event.soldout"
+      "seat.booked", "seat.released", "seat.blocked", "hold.expired", "hold.created",
+      "hold.extended", "event.created", "event.soldout", "object.resale.listed",
+      "object.resale.unlisted", "object.resale.sold", "customer.created", "customer.email_changed",
+      "order.paid", "order.refunded", "order.cancelled", "season.ticket.transfer_sent",
+      "season.ticket.transferred", "season.ticket.transfer_cancelled", "season.ticket.issued",
+      "season.ticket.voided", "season.structure.activated", "season.structure.closed",
+      "season.structure.archived", "season.plan.published", "season.plan.superseded",
+      "season.sales.opened", "season.sales.paused", "season.sales.ended", "season.hold.committed",
+      "season.hold.released", "season.hold.expired", "season.booking.confirmed",
+      "season.booking.cancelled", "season.booking.emergency_requested",
+      "season.occurrence.returned", "season.occurrence.reclaimed", "season.renewal.offered",
+      "season.renewal.intent_received", "season.renewal.renewed", "season.renewal.declined",
+      "season.renewal.lapsed", "season.renewal.released", "season.operation.partial_terminal",
+      "season.amendment.applied", "season.performance.added", "season.performance.removed",
+      "season.performance.past", "season.performance.postponed", "season.performance.cancelled",
+      "season.performance.rescheduled", "season.bulk_action.completed", "season.block.ready",
+      "season.block.released", "season.order.paid", "season.order.refunded", "series.created",
+      "series.dates_added"
     ].freeze
 
     def list

data/lib/seatlayer/orders.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module SeatLayer
+  # Orders SeatLayer took through its own checkout: reads, CSV export,
+  # refunds, cancellations and ticket resends.
+  class Orders < Resource
+    # One page of orders. +from+ and +to+ are epoch milliseconds. +holder_ref+ lists
+    # one holder's orders: the Season order with that id and renewals offered to that
+    # reference. Each order carries "holderRef" and "customerId"; "buyer"/"email" is
+    # nil for a box office sale taken without one.
+    def list_orders(event_key: nil, season_key: nil, status: nil, from: nil, to: nil,
+                    cursor: nil, limit: nil, holder_ref: nil)
+      @client.get("/v1/orders", compact({ "eventKey" => event_key, "seasonKey" => season_key,
+                                          "holderRef" => holder_ref,
+                                          "status" => status, "from" => from, "to" => to,
+                                          "cursor" => cursor, "limit" => limit }))
+    end
+
+    # Read one order.
+    def retrieve_order(order_id)
+      @client.get("/v1/orders/#{encode(order_id)}")
+    end
+
+    # List one order's tickets.
+    def list_order_tickets(order_id)
+      @client.get("/v1/orders/#{encode(order_id)}/tickets")
+    end
+
+    # One page of an event's orders. +search+ is sent as the API's +q+
+    # parameter; +from+ and +to+ are epoch milliseconds.
+    def list_event_orders(event_key, search: nil, status: nil, paid_by: nil, from: nil, to: nil,
+                          cursor: nil, limit: nil)
+      @client.get("/v1/events/#{encode(event_key)}/orders",
+                  compact({ "q" => search, "status" => status, "paidBy" => paid_by,
+                            "from" => from, "to" => to, "cursor" => cursor, "limit" => limit }))
+    end
+
+    # Read one of an event's orders.
+    def retrieve_event_order(event_key, order_id)
+      @client.get("/v1/events/#{encode(event_key)}/orders/#{encode(order_id)}")
+    end
+
+    # Download an event's orders as CSV, with the same filters as
+    # +list_event_orders+. Returns the raw CSV text.
+    def export_event_orders_csv(event_key, search: nil, status: nil, paid_by: nil, from: nil,
+                                to: nil)
+      @client.get_text("/v1/events/#{encode(event_key)}/orders.csv",
+                       compact({ "q" => search, "status" => status, "paidBy" => paid_by,
+                                 "from" => from, "to" => to }))
+    end
+
+    # Refund an event order, in full or by +amount_minor+.
+    def refund_event_order(event_key, order_id, amount_minor: nil, idempotency_key: nil)
+      @client.post("/v1/events/#{encode(event_key)}/orders/#{encode(order_id)}/refund",
+                   compact({ "amountMinor" => amount_minor }),
+                   idempotency_key: idempotency_key, retry_policy: :header_replay)
+    end
+
+    # Cancel an event order.
+    def cancel_event_order(event_key, order_id, reason:, note: nil, refund_confirmed: nil,
+                           used_tickets_acknowledged: nil, notify_buyer: nil, idempotency_key: nil)
+      body = compact({ "reason" => reason, "note" => note, "refundConfirmed" => refund_confirmed,
+                       "usedTicketsAcknowledged" => used_tickets_acknowledged,
+                       "notifyBuyer" => notify_buyer })
+      @client.post("/v1/events/#{encode(event_key)}/orders/#{encode(order_id)}/cancel", body,
+                   idempotency_key: idempotency_key, retry_policy: :header_replay)
+    end
+
+    # Send an event order's tickets again. Single-attempt: never retried automatically.
+    def resend_event_order_tickets(event_key, order_id, email: nil)
+      @client.post("/v1/events/#{encode(event_key)}/orders/#{encode(order_id)}/resend",
+                   compact({ "email" => email }))
+    end
+  end
+end

data/lib/seatlayer/resources.rb

@@ -157,11 +157,14 @@ module SeatLayer
     #
     # 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)
+    # <tt>counts: false</tt> when paging a whole catalogue. +series_key+ lists only
+    # the dates of one event series.
+    def list(workspace_id: nil, external_ref: nil, limit: nil, cursor: nil, counts: true,
+             series_key: nil)
       query = compact({ "workspaceId" => workspace_id, "externalRef" => external_ref,
                         "limit" => limit, "cursor" => cursor })
       query["counts"] = "0" unless counts
+      query["seriesKey"] = series_key unless series_key.nil?
       @client.get("/v1/events", query)
     end
 
@@ -249,6 +252,8 @@ module SeatLayer
       @client.post("/v1/events/#{encode(event_key)}/close")
     end
 
+    # Open a paused event's sales again. A date its season cancelled never opens
+    # again: 409 season_date_cancelled.
     def reopen(event_key)
       @client.post("/v1/events/#{encode(event_key)}/reopen")
     end
@@ -289,5 +294,101 @@ module SeatLayer
       @client.get("/v1/events/#{encode(event_key)}/log",
                   compact({ "limit" => limit, "before" => before }))
     end
+
+    # Read who takes payment for the event, and what blocks a change.
+    def retrieve_event_buyer_checkout(event_key)
+      @client.get("/v1/events/#{encode(event_key)}/buyer-checkout")
+    end
+
+    # Choose who takes payment: "seatlayer" or "integrator". Single-attempt;
+    # +expected_revision+ stops two writers overwriting each other.
+    def replace_event_buyer_checkout(event_key, buyer_checkout:, expected_revision:)
+      @client.put("/v1/events/#{encode(event_key)}/buyer-checkout",
+                  { "buyerCheckout" => buyer_checkout, "expectedRevision" => expected_revision })
+    end
+
+    # Read the payment gateway the event uses, optionally for one +currency+.
+    def retrieve_event_payment_gateway(event_key, currency: nil)
+      @client.get("/v1/events/#{encode(event_key)}/payment-gateway",
+                  compact({ "currency" => currency }))
+    end
+
+    # Assign a payment gateway connection to the event. Pass +nil+ to send an
+    # explicit JSON null. Single-attempt: never retried automatically.
+    def replace_event_payment_gateway(event_key, connection_id: UNSET, provider: UNSET)
+      @client.put("/v1/events/#{encode(event_key)}/payment-gateway",
+                  supplied({ "connectionId" => connection_id, "provider" => provider }))
+    end
+
+    # Read what the event still needs before it can sell.
+    def retrieve_event_sales_readiness(event_key)
+      @client.get("/v1/events/#{encode(event_key)}/sales/readiness")
+    end
+
+    # Check one order against the event's sales setup. Single-attempt.
+    def preflight_event_sales(event_key, order_id:)
+      @client.post("/v1/events/#{encode(event_key)}/sales/preflight", { "orderId" => order_id })
+    end
+
+    # Move the event's sales to another state (setup, testable, live, paused or ended).
+    # A date its season cancelled never opens again: moving it to testable or live
+    # answers 409 season_date_cancelled.
+    def transition_event_sales(event_key, to:, expected_revision:, reason: nil)
+      @client.post("/v1/events/#{encode(event_key)}/sales/transition",
+                   compact({ "to" => to, "expectedRevision" => expected_revision,
+                             "reason" => reason }))
+    end
+
+    # Read the event's booking fee.
+    def retrieve_event_booking_fee(event_key)
+      @client.get("/v1/events/#{encode(event_key)}/booking-fee")
+    end
+
+    # Set the booking fee in minor units; +nil+ clears it and stays an explicit
+    # JSON null. Single-attempt: never retried automatically.
+    def replace_event_booking_fee(event_key, booking_fee_minor:)
+      @client.put("/v1/events/#{encode(event_key)}/booking-fee",
+                  { "bookingFeeMinor" => booking_fee_minor })
+    end
+
+    # List the event's discount codes.
+    def list_event_discount_codes(event_key)
+      @client.get("/v1/events/#{encode(event_key)}/discount-codes")
+    end
+
+    # Create a discount code. +kind+ is "percent" or "amount". Pass +nil+ for
+    # +starts_at+, +ends_at+ or +max_uses+ to send an explicit JSON null.
+    # Single-attempt: never retried automatically.
+    # rubocop:disable-next Metrics/ParameterLists
+    def create_event_discount_code(event_key, code:, kind:, percent: nil, amount_minor: nil,
+                                   starts_at: UNSET, ends_at: UNSET, max_uses: UNSET, active: nil)
+      body = compact({ "code" => code, "kind" => kind, "percent" => percent,
+                       "amountMinor" => amount_minor, "active" => active })
+      body.merge!(supplied({ "startsAt" => starts_at, "endsAt" => ends_at, "maxUses" => max_uses }))
+      @client.post("/v1/events/#{encode(event_key)}/discount-codes", body)
+    end
+
+    # Change a discount code. Only the fields you pass are sent; pass +nil+ for
+    # +starts_at+, +ends_at+ or +max_uses+ to send an explicit JSON null.
+    # Single-attempt: never retried automatically.
+    # rubocop:disable-next Metrics/ParameterLists
+    def update_event_discount_code(event_key, code_id, code: nil, kind: nil, percent: nil,
+                                   amount_minor: nil, starts_at: UNSET, ends_at: UNSET,
+                                   max_uses: UNSET, active: nil, state: nil)
+      body = compact({ "code" => code, "kind" => kind, "percent" => percent,
+                       "amountMinor" => amount_minor, "active" => active, "state" => state })
+      body.merge!(supplied({ "startsAt" => starts_at, "endsAt" => ends_at, "maxUses" => max_uses }))
+      @client.patch("/v1/events/#{encode(event_key)}/discount-codes/#{encode(code_id)}", body)
+    end
+
+    # End a discount code now, keeping its history.
+    def end_event_discount_code(event_key, code_id)
+      @client.post("/v1/events/#{encode(event_key)}/discount-codes/#{encode(code_id)}/end")
+    end
+
+    # Delete a discount code. The API answers 204, so this returns an empty Hash.
+    def delete_event_discount_code(event_key, code_id)
+      @client.delete("/v1/events/#{encode(event_key)}/discount-codes/#{encode(code_id)}")
+    end
   end
 end