seatschart 0.2.0 → 0.3.0

data/lib/seatschart/api/seats_api.rb

@@ -210,7 +210,7 @@ module SeatsChart
     end
 
     # Confirm GA purchase (Postgres sold_count)
-    # Server-to-server only (`x-api-key`): commits GA capacity after payment. SeatsChart-catalog events require a durable quote and matching externalPaymentId/paidAmountCents/paidCurrency; partner-priced events accept the declared paidAmountCents without a quote and synced catalogs validate it (409 `price_mismatch`). The final ticketTypeId is re-checked against the event sales rules (409 `quota_exceeded`, `buyer_limit_exceeded`, `lot_sold_out`) and the quantity against the organizer's booking limits (409 `booking_limit_exceeded`; holds placed before the current limits were published stay confirmable). Previously accepted legacy receipts remain retryable. Consumer JWTs are rejected. Durably records Idempotency-Key and conditionally increments sold_count before reconciling Redis holds. **Idempotency-Key** required. Optional `ticketBuyerId` is stored on the GA receipt (inherited from the hold token when omitted). Quote failures return 409 with `error: quote_required` (no quoteId) or `error: quote_mismatch` (quote or payment attestation does not match).
+    # Server-to-server only (`x-api-key`): commits GA capacity after payment. SeatsChart-catalog events require a durable quote and matching externalPaymentId/paidAmountCents/paidCurrency; partner-priced events accept the declared paidAmountCents without a quote and synced catalogs validate it (409 `price_mismatch`). The final ticketTypeId is re-checked against the event sales rules (409 `quota_exceeded`, `buyer_limit_exceeded`, `lot_sold_out`) and the quantity against the organizer's booking limits (409 `booking_limit_exceeded`; holds placed before the current limits were published stay confirmable). Previously accepted legacy receipts remain retryable. Consumer JWTs are rejected. Durably records Idempotency-Key and conditionally increments sold_count before reconciling Redis holds. **Idempotency-Key** required. Optional `ticketBuyerId` is stored on the GA receipt (inherited from the hold token when omitted). Quote failures return 409 with `error: quote_required` (no quoteId) or `error: quote_mismatch` (quote or payment attestation does not match). Areas sold as a whole (`fixedOccupancy` / `variableOccupancy`): `quantity` is the number of people held (fixed: the capacity); every place of the area is sold and the receipt records the people. Another quantity answers 400 `ga_area_whole`, a quantity different from the people of the hold token 409 `conflict`. Price: the ticket type's price per person, or once for the area when it is priced per area (`priceBy: \"area\"`). The response adds `places`, `people` and `areaType`.
     # @param idempotency_key [String] Required. Reuse with the same request on retry; a different payload conflicts. Seat confirmation binds this key durably in PostgreSQL; hold mutations use bounded Redis receipts.
     # @param post_api_ga_confirm_request [PostApiGaConfirmRequest] 
     # @param [Hash] opts the optional parameters
@@ -221,7 +221,7 @@ module SeatsChart
     end
 
     # Confirm GA purchase (Postgres sold_count)
-    # Server-to-server only (`x-api-key`): commits GA capacity after payment. SeatsChart-catalog events require a durable quote and matching externalPaymentId/paidAmountCents/paidCurrency; partner-priced events accept the declared paidAmountCents without a quote and synced catalogs validate it (409 `price_mismatch`). The final ticketTypeId is re-checked against the event sales rules (409 `quota_exceeded`, `buyer_limit_exceeded`, `lot_sold_out`) and the quantity against the organizer's booking limits (409 `booking_limit_exceeded`; holds placed before the current limits were published stay confirmable). Previously accepted legacy receipts remain retryable. Consumer JWTs are rejected. Durably records Idempotency-Key and conditionally increments sold_count before reconciling Redis holds. **Idempotency-Key** required. Optional `ticketBuyerId` is stored on the GA receipt (inherited from the hold token when omitted). Quote failures return 409 with `error: quote_required` (no quoteId) or `error: quote_mismatch` (quote or payment attestation does not match).
+    # Server-to-server only (`x-api-key`): commits GA capacity after payment. SeatsChart-catalog events require a durable quote and matching externalPaymentId/paidAmountCents/paidCurrency; partner-priced events accept the declared paidAmountCents without a quote and synced catalogs validate it (409 `price_mismatch`). The final ticketTypeId is re-checked against the event sales rules (409 `quota_exceeded`, `buyer_limit_exceeded`, `lot_sold_out`) and the quantity against the organizer's booking limits (409 `booking_limit_exceeded`; holds placed before the current limits were published stay confirmable). Previously accepted legacy receipts remain retryable. Consumer JWTs are rejected. Durably records Idempotency-Key and conditionally increments sold_count before reconciling Redis holds. **Idempotency-Key** required. Optional `ticketBuyerId` is stored on the GA receipt (inherited from the hold token when omitted). Quote failures return 409 with `error: quote_required` (no quoteId) or `error: quote_mismatch` (quote or payment attestation does not match). Areas sold as a whole (`fixedOccupancy` / `variableOccupancy`): `quantity` is the number of people held (fixed: the capacity); every place of the area is sold and the receipt records the people. Another quantity answers 400 `ga_area_whole`, a quantity different from the people of the hold token 409 `conflict`. Price: the ticket type's price per person, or once for the area when it is priced per area (`priceBy: \"area\"`). The response adds `places`, `people` and `areaType`.
     # @param idempotency_key [String] Required. Reuse with the same request on retry; a different payload conflicts. Seat confirmation binds this key durably in PostgreSQL; hold mutations use bounded Redis receipts.
     # @param post_api_ga_confirm_request [PostApiGaConfirmRequest] 
     # @param [Hash] opts the optional parameters
@@ -374,7 +374,7 @@ module SeatsChart
     end
 
     # Hold GA area capacity (Redis)
-    # Places a temporary hold on unnumbered GA capacity. **Idempotency-Key** is required; repeats within ~24h return the cached hold response. Optional `ticketBuyerId` is stored on the GA hold token and inherited by `POST /ga/confirm`. The organizer's booking limits cap `quantity` (designer *Max GA tickets per order*, else *Max seats per order*; strictest with the sales-channel default): 409 `booking_limit_exceeded` (`limit`, `current`, `requested`, `kind: \"ga\"`). GA tables sold as a whole (`shape.bookAs: \"whole\"`) take every place in one hold: any other `quantity` answers 409 `ga_table_whole` (`capacity`, `requested`).
+    # Places a temporary hold on unnumbered GA capacity. **Idempotency-Key** is required; repeats within ~24h return the cached hold response. Optional `ticketBuyerId` is stored on the GA hold token and inherited by `POST /ga/confirm`. The organizer's booking limits cap `quantity` (designer *Max GA tickets per order*, else *Max seats per order*; strictest with the sales-channel default): 409 `booking_limit_exceeded` (`limit`, `current`, `requested`, `kind: \"ga\"`). GA tables sold as a whole (`shape.bookAs: \"whole\"`) take every place in one hold: any other `quantity` answers 409 `ga_table_whole` (`capacity`, `requested`). Areas sold as a whole (`areaType` `fixedOccupancy` / `variableOccupancy`) are held for one buyer in one piece: `quantity` is the number of people (fixed: exactly the capacity; variable: `minOccupancy`..capacity), every place of the area is held atomically and a second buyer can never hold part of it. Any other quantity answers 400 `ga_area_whole` (`areaType`, `capacity`, `minOccupancy`, `maxOccupancy`, `requested`); an area already held, sold or partly withheld answers 409 `conflict`. A whole area counts as one object against the booking limits (its capacity, at most 50, caps it); its people count against quotas, lots and per-buyer limits. The response adds `places`, `people` and `areaType`.
     # @param idempotency_key [String] Required. Reuse with the same request on retry; a different payload conflicts. Seat confirmation binds this key durably in PostgreSQL; hold mutations use bounded Redis receipts.
     # @param post_api_ga_reserve_request [PostApiGaReserveRequest] 
     # @param [Hash] opts the optional parameters
@@ -385,7 +385,7 @@ module SeatsChart
     end
 
     # Hold GA area capacity (Redis)
-    # Places a temporary hold on unnumbered GA capacity. **Idempotency-Key** is required; repeats within ~24h return the cached hold response. Optional `ticketBuyerId` is stored on the GA hold token and inherited by `POST /ga/confirm`. The organizer's booking limits cap `quantity` (designer *Max GA tickets per order*, else *Max seats per order*; strictest with the sales-channel default): 409 `booking_limit_exceeded` (`limit`, `current`, `requested`, `kind: \"ga\"`). GA tables sold as a whole (`shape.bookAs: \"whole\"`) take every place in one hold: any other `quantity` answers 409 `ga_table_whole` (`capacity`, `requested`).
+    # Places a temporary hold on unnumbered GA capacity. **Idempotency-Key** is required; repeats within ~24h return the cached hold response. Optional `ticketBuyerId` is stored on the GA hold token and inherited by `POST /ga/confirm`. The organizer's booking limits cap `quantity` (designer *Max GA tickets per order*, else *Max seats per order*; strictest with the sales-channel default): 409 `booking_limit_exceeded` (`limit`, `current`, `requested`, `kind: \"ga\"`). GA tables sold as a whole (`shape.bookAs: \"whole\"`) take every place in one hold: any other `quantity` answers 409 `ga_table_whole` (`capacity`, `requested`). Areas sold as a whole (`areaType` `fixedOccupancy` / `variableOccupancy`) are held for one buyer in one piece: `quantity` is the number of people (fixed: exactly the capacity; variable: `minOccupancy`..capacity), every place of the area is held atomically and a second buyer can never hold part of it. Any other quantity answers 400 `ga_area_whole` (`areaType`, `capacity`, `minOccupancy`, `maxOccupancy`, `requested`); an area already held, sold or partly withheld answers 409 `conflict`. A whole area counts as one object against the booking limits (its capacity, at most 50, caps it); its people count against quotas, lots and per-buyer limits. The response adds `places`, `people` and `areaType`.
     # @param idempotency_key [String] Required. Reuse with the same request on retry; a different payload conflicts. Seat confirmation binds this key durably in PostgreSQL; hold mutations use bounded Redis receipts.
     # @param post_api_ga_reserve_request [PostApiGaReserveRequest] 
     # @param [Hash] opts the optional parameters
@@ -621,7 +621,7 @@ module SeatsChart
     end
 
     # Suggest or atomically hold best available seats
-    # Returns seat IDs for the requested quantity, preferring adjacent same-row groups near the map center. Filter the candidate pool by `category` (or ordered `categories`, max 10: windows of the first category are tried before the second, and so on), optional `sectionId` (layout section id or name) and optional `zone` (layout zone id or name; seats resolve explicit zone assignment, then their section zone, then the zone outline) before ranking. `tryToPreventOrphanSeats` (default **true**) skips adjacent windows that would leave a single empty seat at either end of the run, falling back to them only when nothing else fits. `ticketTypes` (`{ ticketTypeId: count }`) sets `quantity` to the sum, restricts the search to categories whose ticket catalog offers every requested type, and returns `ticketTypes` (seatId → ticketTypeId) ready to send as `seatTicketTypes` on confirm; events without ticket types reject it. `accessibleSeats` (N) only returns windows containing at least N seats flagged `accessibility.wheelchair` in the published seat structure (409 when no such window exists). `channel` is salesChannel order limits only. Pass **`x-channel-key`** for inventory partitions — do not send the secret in the body. **`hold: false` (default):** suggest only — does not lock. **`hold: true`:** ranks up to 32 candidate windows across the category preferences, locks the first fit in one Lua call each (all-or-nothing per window), then O(cart) PG gates (available/forSale/channel); on gate failure releases only the locks it added. Requires **Idempotency-Key**, and `userId` unless `holdToken` is given. `holdToken` appends the seats to that existing hold session (same expiry bound; 409 `hold_token_conflict` when the session is expired, foreign, confirming or full). `extraData` is stored on the held seats (requires hold). Returns `hold_token` for confirm. The organizer's booking limits (designer *Max seats per order*) cap `quantity` and, with `holdToken`, the seats already on the token: best-available never picks more than allowed (409 `booking_limit_exceeded` with `limit`, `current`, `requested`). `sections` (max 20 section ids or names, XOR with `sectionId`) ranks across the union of those sections. **API keys / dashboard sessions only:** `channelKeys` (channel secret keys or ids) restricts the pool to public seats plus those channels, `ignoreChannels: true` allows every channel (both replace `x-channel-key`; buyers get 403). `orderId` (with `hold`) is stored on the held seats as `extraData.orderId` and echoed in the response; pass it as `externalOrderId` on confirm. **`status: \"booked\"`** (API keys with the `bookings` scope, or dashboard sessions allowed to change object statuses; buyers get 403) books the best window directly instead of holding it: the same administrative booking as POST /events/{eventId}/actions/book (one SQL transaction under the seat row locks; a seat held by a buyer is never taken; when a ranked window was taken meanwhile the next one is tried). Requires **Idempotency-Key**: the booking order id is derived from it, so a retry returns the same booking. `ticketTypes` are recorded per seat, `extraData` and `orderId` (as `extraData.orderId`) are stored on the booked seats. Response: `status: \"booked\"`, `booked: true`, `bookingOrderId` (cancel with POST /orders/{orderId}/cancel) and `objects` (status, extraData, orderId, ticketType per seat). `status: \"reservedByToken\"` is the same as `hold: true`. **`keepExtraData: true`** (hold or booked) keeps the seats' stored extraData and merges `extraData` / `orderId` on top instead of replacing it.
+    # Returns seat IDs for the requested quantity, preferring adjacent same-row groups near the map center. Filter the candidate pool by `category` (or ordered `categories`, max 10: windows of the first category are tried before the second, and so on), optional `sectionId` (layout section id or name) and optional `zone` (layout zone id or name; seats resolve explicit zone assignment, then their section zone, then the zone outline) before ranking. `tryToPreventOrphanSeats` (default **true**) skips adjacent windows that would leave a single empty seat at either end of the run, falling back to them only when nothing else fits. `ticketTypes` (`{ ticketTypeId: count }`) sets `quantity` to the sum, restricts the search to categories whose ticket catalog offers every requested type, and returns `ticketTypes` (seatId → ticketTypeId) ready to send as `seatTicketTypes` on confirm; events without ticket types reject it. `accessibleSeats` (N) only returns windows containing at least N seats flagged `accessibility.wheelchair` in the published seat structure (409 when no such window exists). `channel` is salesChannel order limits only. Pass **`x-channel-key`** for inventory partitions — do not send the secret in the body. **`hold: false` (default):** suggest only — does not lock. **`hold: true`:** ranks up to 32 candidate windows across the category preferences, locks the first fit in one Lua call each (all-or-nothing per window), then O(cart) PG gates (available/forSale/channel; seats that are not for sale are never picked, not even resale-listed ones of non-propagating season members: those are bought by holding the seats of the listing); on gate failure releases only the locks it added. Requires **Idempotency-Key**, and `userId` unless `holdToken` is given. `holdToken` appends the seats to that existing hold session (same expiry bound; 409 `hold_token_conflict` when the session is expired, foreign, confirming or full). `extraData` is stored on the held seats (requires hold). Returns `hold_token` for confirm. The organizer's booking limits (designer *Max seats per order*) cap `quantity` and, with `holdToken`, the seats already on the token: best-available never picks more than allowed (409 `booking_limit_exceeded` with `limit`, `current`, `requested`). `sections` (max 20 section ids or names, XOR with `sectionId`) ranks across the union of those sections. **API keys / dashboard sessions only:** `channelKeys` (channel secret keys or ids) restricts the pool to public seats plus those channels, `ignoreChannels: true` allows every channel (both replace `x-channel-key`; buyers get 403). `orderId` (with `hold`) is stored on the held seats as `extraData.orderId` and echoed in the response; pass it as `externalOrderId` on confirm. **`status: \"booked\"`** (API keys with the `bookings` scope, or dashboard sessions allowed to change object statuses; buyers get 403) books the best window directly instead of holding it: the same administrative booking as POST /events/{eventId}/actions/book (one SQL transaction under the seat row locks; a seat held by a buyer is never taken; when a ranked window was taken meanwhile the next one is tried). Requires **Idempotency-Key**: the booking order id is derived from it, so a retry returns the same booking. `ticketTypes` are recorded per seat, `extraData` and `orderId` (as `extraData.orderId`) are stored on the booked seats. Response: `status: \"booked\"`, `booked: true`, `bookingOrderId` (cancel with POST /orders/{orderId}/cancel) and `objects` (status, extraData, orderId, ticketType per seat). `status: \"reservedByToken\"` is the same as `hold: true`. **`keepExtraData: true`** (hold or booked) keeps the seats' stored extraData and merges `extraData` / `orderId` on top instead of replacing it.
     # @param post_api_seats_best_available_request [PostApiSeatsBestAvailableRequest] 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :idempotency_key Required on transactional routes. Reuse the same key for every retry of one logical operation; the API replays the stored outcome.
@@ -632,7 +632,7 @@ module SeatsChart
     end
 
     # Suggest or atomically hold best available seats
-    # Returns seat IDs for the requested quantity, preferring adjacent same-row groups near the map center. Filter the candidate pool by `category` (or ordered `categories`, max 10: windows of the first category are tried before the second, and so on), optional `sectionId` (layout section id or name) and optional `zone` (layout zone id or name; seats resolve explicit zone assignment, then their section zone, then the zone outline) before ranking. `tryToPreventOrphanSeats` (default **true**) skips adjacent windows that would leave a single empty seat at either end of the run, falling back to them only when nothing else fits. `ticketTypes` (`{ ticketTypeId: count }`) sets `quantity` to the sum, restricts the search to categories whose ticket catalog offers every requested type, and returns `ticketTypes` (seatId → ticketTypeId) ready to send as `seatTicketTypes` on confirm; events without ticket types reject it. `accessibleSeats` (N) only returns windows containing at least N seats flagged `accessibility.wheelchair` in the published seat structure (409 when no such window exists). `channel` is salesChannel order limits only. Pass **`x-channel-key`** for inventory partitions — do not send the secret in the body. **`hold: false` (default):** suggest only — does not lock. **`hold: true`:** ranks up to 32 candidate windows across the category preferences, locks the first fit in one Lua call each (all-or-nothing per window), then O(cart) PG gates (available/forSale/channel); on gate failure releases only the locks it added. Requires **Idempotency-Key**, and `userId` unless `holdToken` is given. `holdToken` appends the seats to that existing hold session (same expiry bound; 409 `hold_token_conflict` when the session is expired, foreign, confirming or full). `extraData` is stored on the held seats (requires hold). Returns `hold_token` for confirm. The organizer's booking limits (designer *Max seats per order*) cap `quantity` and, with `holdToken`, the seats already on the token: best-available never picks more than allowed (409 `booking_limit_exceeded` with `limit`, `current`, `requested`). `sections` (max 20 section ids or names, XOR with `sectionId`) ranks across the union of those sections. **API keys / dashboard sessions only:** `channelKeys` (channel secret keys or ids) restricts the pool to public seats plus those channels, `ignoreChannels: true` allows every channel (both replace `x-channel-key`; buyers get 403). `orderId` (with `hold`) is stored on the held seats as `extraData.orderId` and echoed in the response; pass it as `externalOrderId` on confirm. **`status: \"booked\"`** (API keys with the `bookings` scope, or dashboard sessions allowed to change object statuses; buyers get 403) books the best window directly instead of holding it: the same administrative booking as POST /events/{eventId}/actions/book (one SQL transaction under the seat row locks; a seat held by a buyer is never taken; when a ranked window was taken meanwhile the next one is tried). Requires **Idempotency-Key**: the booking order id is derived from it, so a retry returns the same booking. `ticketTypes` are recorded per seat, `extraData` and `orderId` (as `extraData.orderId`) are stored on the booked seats. Response: `status: \"booked\"`, `booked: true`, `bookingOrderId` (cancel with POST /orders/{orderId}/cancel) and `objects` (status, extraData, orderId, ticketType per seat). `status: \"reservedByToken\"` is the same as `hold: true`. **`keepExtraData: true`** (hold or booked) keeps the seats' stored extraData and merges `extraData` / `orderId` on top instead of replacing it.
+    # Returns seat IDs for the requested quantity, preferring adjacent same-row groups near the map center. Filter the candidate pool by `category` (or ordered `categories`, max 10: windows of the first category are tried before the second, and so on), optional `sectionId` (layout section id or name) and optional `zone` (layout zone id or name; seats resolve explicit zone assignment, then their section zone, then the zone outline) before ranking. `tryToPreventOrphanSeats` (default **true**) skips adjacent windows that would leave a single empty seat at either end of the run, falling back to them only when nothing else fits. `ticketTypes` (`{ ticketTypeId: count }`) sets `quantity` to the sum, restricts the search to categories whose ticket catalog offers every requested type, and returns `ticketTypes` (seatId → ticketTypeId) ready to send as `seatTicketTypes` on confirm; events without ticket types reject it. `accessibleSeats` (N) only returns windows containing at least N seats flagged `accessibility.wheelchair` in the published seat structure (409 when no such window exists). `channel` is salesChannel order limits only. Pass **`x-channel-key`** for inventory partitions — do not send the secret in the body. **`hold: false` (default):** suggest only — does not lock. **`hold: true`:** ranks up to 32 candidate windows across the category preferences, locks the first fit in one Lua call each (all-or-nothing per window), then O(cart) PG gates (available/forSale/channel; seats that are not for sale are never picked, not even resale-listed ones of non-propagating season members: those are bought by holding the seats of the listing); on gate failure releases only the locks it added. Requires **Idempotency-Key**, and `userId` unless `holdToken` is given. `holdToken` appends the seats to that existing hold session (same expiry bound; 409 `hold_token_conflict` when the session is expired, foreign, confirming or full). `extraData` is stored on the held seats (requires hold). Returns `hold_token` for confirm. The organizer's booking limits (designer *Max seats per order*) cap `quantity` and, with `holdToken`, the seats already on the token: best-available never picks more than allowed (409 `booking_limit_exceeded` with `limit`, `current`, `requested`). `sections` (max 20 section ids or names, XOR with `sectionId`) ranks across the union of those sections. **API keys / dashboard sessions only:** `channelKeys` (channel secret keys or ids) restricts the pool to public seats plus those channels, `ignoreChannels: true` allows every channel (both replace `x-channel-key`; buyers get 403). `orderId` (with `hold`) is stored on the held seats as `extraData.orderId` and echoed in the response; pass it as `externalOrderId` on confirm. **`status: \"booked\"`** (API keys with the `bookings` scope, or dashboard sessions allowed to change object statuses; buyers get 403) books the best window directly instead of holding it: the same administrative booking as POST /events/{eventId}/actions/book (one SQL transaction under the seat row locks; a seat held by a buyer is never taken; when a ranked window was taken meanwhile the next one is tried). Requires **Idempotency-Key**: the booking order id is derived from it, so a retry returns the same booking. `ticketTypes` are recorded per seat, `extraData` and `orderId` (as `extraData.orderId`) are stored on the booked seats. Response: `status: \"booked\"`, `booked: true`, `bookingOrderId` (cancel with POST /orders/{orderId}/cancel) and `objects` (status, extraData, orderId, ticketType per seat). `status: \"reservedByToken\"` is the same as `hold: true`. **`keepExtraData: true`** (hold or booked) keeps the seats' stored extraData and merges `extraData` / `orderId` on top instead of replacing it.
     # @param post_api_seats_best_available_request [PostApiSeatsBestAvailableRequest] 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :idempotency_key Required on transactional routes. Reuse the same key for every retry of one logical operation; the API replays the stored outcome.
@@ -930,7 +930,7 @@ module SeatsChart
     end
 
     # Clear Redis TTL holds before expiry (checkout abandoned / declined)
-    # Deletes KeyDB TTL seat locks when they are authorized by the **`holdToken`** capability, rejects seats already sold in Postgres, publishes **`SSE` `available`** only for locks actually removed. **`Idempotency-Key`** header is **required**; repeats within ~24h return the cached response (no duplicate side effects). Also: **`x-api-key`** or **`Authorization: Bearer`**.
+    # Deletes KeyDB TTL seat locks when they are authorized by the **`holdToken`** capability, rejects seats already sold in Postgres, publishes **`SSE` `available`** only for locks actually removed. Releasing any seat of a held listing sold as a whole releases the whole listing (its other seats in this hold) in the same atomic call; the response `seatIds` lists every seat released. **`Idempotency-Key`** header is **required**; repeats within ~24h return the cached response (no duplicate side effects). Also: **`x-api-key`** or **`Authorization: Bearer`**.
     # @param idempotency_key [String] Required deduplication key (max 255 chars after trim); 24h cache replay in Redis per tenant + route.
     # @param post_api_seats_release_request [PostApiSeatsReleaseRequest] 
     # @param [Hash] opts the optional parameters
@@ -942,7 +942,7 @@ module SeatsChart
     end
 
     # Clear Redis TTL holds before expiry (checkout abandoned / declined)
-    # Deletes KeyDB TTL seat locks when they are authorized by the **`holdToken`** capability, rejects seats already sold in Postgres, publishes **`SSE` `available`** only for locks actually removed. **`Idempotency-Key`** header is **required**; repeats within ~24h return the cached response (no duplicate side effects). Also: **`x-api-key`** or **`Authorization: Bearer`**.
+    # Deletes KeyDB TTL seat locks when they are authorized by the **`holdToken`** capability, rejects seats already sold in Postgres, publishes **`SSE` `available`** only for locks actually removed. Releasing any seat of a held listing sold as a whole releases the whole listing (its other seats in this hold) in the same atomic call; the response `seatIds` lists every seat released. **`Idempotency-Key`** header is **required**; repeats within ~24h return the cached response (no duplicate side effects). Also: **`x-api-key`** or **`Authorization: Bearer`**.
     # @param idempotency_key [String] Required deduplication key (max 255 chars after trim); 24h cache replay in Redis per tenant + route.
     # @param post_api_seats_release_request [PostApiSeatsReleaseRequest] 
     # @param [Hash] opts the optional parameters
@@ -1006,7 +1006,7 @@ module SeatsChart
     end
 
     # Place a temporary Redis hold (Lua TTL) before payment
-    # JSON body: `eventId`, `seatIds` (1–64 UUIDs, unique), `userId`, optional `holdToken` capability to append seats to an existing session. `userId` is customer metadata, never ownership proof. Renew/append share a two-hour maximum session lifetime. Optional `ticketBuyerId` (opaque partner buyer id) is stored on a new hold token and inherited by its confirmation. `eventId` also accepts the event key. Headers: **x-api-key** (B2B) *or* **Authorization: Bearer** (HS256 JWT); optional **x-tenant-id**; **`Idempotency-Key` is required** (1–255 chars after trim; use a fresh UUID v4 per checkout attempt). Repeats with the same key within ~24h return the cached HTTP status and JSON without re-running the Lua lock. Applies Redis TTL locks (**default 600 s**, overridden by **`SEAT_HOLD_TTL_SEC`**, or by the workspace **hold period** setting — `PATCH /workspace/settings`) with SSE `seat` → **`locked`**; Postgres remains **`available`** until **`POST /api/seats/confirm`** persists **`sold`** via the reservation worker. A hold token holds at most the workspace `maxSeatsPerHoldToken` seats (409 `seat_limit`). **Booking limits:** the organizer's *Max seats per order* (designer → Booking limits, stored as `layoutMeta.bookingRules` of the published chart/event layout) caps the seats one hold token holds, appends included, checked in the same atomic call as the locks (parallel appends cannot exceed it); the strictest of the sales-channel default, this limit, the per-buyer limit and `maxSeatsPerHoldToken` wins. Refused with 409 `booking_limit_exceeded` (`limit`, `current` seats already on the token, `requested`, `kind: \"seats\"`). Holds placed before a lower limit was published keep their seats and stay confirmable; they only cannot grow. With ticket buyer validation on, buyer tokens must carry a bound ticket buyer id (403 `ticket_buyer_required` / `ticket_buyer_mismatch`).
+    # JSON body: `eventId`, `seatIds` (1–64 UUIDs, unique; up to the workspace `maxSeatsPerHoldToken` with large group holds), `userId`, optional `holdToken` capability to append seats to an existing session. `userId` is customer metadata, never ownership proof. Renew/append share a two-hour maximum session lifetime. Optional `ticketBuyerId` (opaque partner buyer id) is stored on a new hold token and inherited by its confirmation. `eventId` also accepts the event key. Headers: **x-api-key** (B2B) *or* **Authorization: Bearer** (HS256 JWT); optional **x-tenant-id**; **`Idempotency-Key` is required** (1–255 chars after trim; use a fresh UUID v4 per checkout attempt). Repeats with the same key within ~24h return the cached HTTP status and JSON without re-running the Lua lock. Applies Redis TTL locks (**default 600 s**, overridden by **`SEAT_HOLD_TTL_SEC`**, or by the workspace **hold period** setting — `PATCH /workspace/settings`) with SSE `seat` → **`locked`**; Postgres remains **`available`** until **`POST /api/seats/confirm`** persists **`sold`** via the reservation worker. A hold token holds at most the workspace `maxSeatsPerHoldToken` seats (409 `seat_limit`). **Large group holds (opt-in):** a workspace `maxSeatsPerHoldToken` above 64 (up to 1000, `PATCH /workspace/settings`) lets one request and one hold token hold that many seats of one event; the request is still one atomic lock — every seat of the group is held under the token, or none is (409 `SEAT_LOCKED` when any seat is taken, nothing locked). The sales-channel defaults (web 8, box office 20, partner 64) then step aside; the organizer's booking limits and the workspace cap still apply. Season and multi-event holds keep the 64-lock limit. **Booking limits:** the organizer's *Max seats per order* (designer → Booking limits, stored as `layoutMeta.bookingRules` of the published chart/event layout) caps the seats one hold token holds, appends included, checked in the same atomic call as the locks (parallel appends cannot exceed it); the strictest of the sales-channel default, this limit, the per-buyer limit and `maxSeatsPerHoldToken` wins. Refused with 409 `booking_limit_exceeded` (`limit`, `current` seats already on the token, `requested`, `kind: \"seats\"`). Holds placed before a lower limit was published keep their seats and stay confirmable; they only cannot grow. With ticket buyer validation on, buyer tokens must carry a bound ticket buyer id (403 `ticket_buyer_required` / `ticket_buyer_mismatch`). Seats that are not for sale are refused with 409 `SEAT_NOT_FOR_SALE`, except a seat with an active **resale** listing in a season member whose for-sale configuration does not propagate (`forSalePropagated: false`, e.g. a season-ticket seat its holder resells for one game); the confirmation and the order commit apply the same rule.
     # @param idempotency_key [String] Required deduplication key (max 255 chars after trim; UUID v4 recommended). 24h idempotent cache replay in Redis per tenant.
     # @param post_api_seats_reserve_request [PostApiSeatsReserveRequest] 
     # @param [Hash] opts the optional parameters
@@ -1018,7 +1018,7 @@ module SeatsChart
     end
 
     # Place a temporary Redis hold (Lua TTL) before payment
-    # JSON body: `eventId`, `seatIds` (1–64 UUIDs, unique), `userId`, optional `holdToken` capability to append seats to an existing session. `userId` is customer metadata, never ownership proof. Renew/append share a two-hour maximum session lifetime. Optional `ticketBuyerId` (opaque partner buyer id) is stored on a new hold token and inherited by its confirmation. `eventId` also accepts the event key. Headers: **x-api-key** (B2B) *or* **Authorization: Bearer** (HS256 JWT); optional **x-tenant-id**; **`Idempotency-Key` is required** (1–255 chars after trim; use a fresh UUID v4 per checkout attempt). Repeats with the same key within ~24h return the cached HTTP status and JSON without re-running the Lua lock. Applies Redis TTL locks (**default 600 s**, overridden by **`SEAT_HOLD_TTL_SEC`**, or by the workspace **hold period** setting — `PATCH /workspace/settings`) with SSE `seat` → **`locked`**; Postgres remains **`available`** until **`POST /api/seats/confirm`** persists **`sold`** via the reservation worker. A hold token holds at most the workspace `maxSeatsPerHoldToken` seats (409 `seat_limit`). **Booking limits:** the organizer's *Max seats per order* (designer → Booking limits, stored as `layoutMeta.bookingRules` of the published chart/event layout) caps the seats one hold token holds, appends included, checked in the same atomic call as the locks (parallel appends cannot exceed it); the strictest of the sales-channel default, this limit, the per-buyer limit and `maxSeatsPerHoldToken` wins. Refused with 409 `booking_limit_exceeded` (`limit`, `current` seats already on the token, `requested`, `kind: \"seats\"`). Holds placed before a lower limit was published keep their seats and stay confirmable; they only cannot grow. With ticket buyer validation on, buyer tokens must carry a bound ticket buyer id (403 `ticket_buyer_required` / `ticket_buyer_mismatch`).
+    # JSON body: `eventId`, `seatIds` (1–64 UUIDs, unique; up to the workspace `maxSeatsPerHoldToken` with large group holds), `userId`, optional `holdToken` capability to append seats to an existing session. `userId` is customer metadata, never ownership proof. Renew/append share a two-hour maximum session lifetime. Optional `ticketBuyerId` (opaque partner buyer id) is stored on a new hold token and inherited by its confirmation. `eventId` also accepts the event key. Headers: **x-api-key** (B2B) *or* **Authorization: Bearer** (HS256 JWT); optional **x-tenant-id**; **`Idempotency-Key` is required** (1–255 chars after trim; use a fresh UUID v4 per checkout attempt). Repeats with the same key within ~24h return the cached HTTP status and JSON without re-running the Lua lock. Applies Redis TTL locks (**default 600 s**, overridden by **`SEAT_HOLD_TTL_SEC`**, or by the workspace **hold period** setting — `PATCH /workspace/settings`) with SSE `seat` → **`locked`**; Postgres remains **`available`** until **`POST /api/seats/confirm`** persists **`sold`** via the reservation worker. A hold token holds at most the workspace `maxSeatsPerHoldToken` seats (409 `seat_limit`). **Large group holds (opt-in):** a workspace `maxSeatsPerHoldToken` above 64 (up to 1000, `PATCH /workspace/settings`) lets one request and one hold token hold that many seats of one event; the request is still one atomic lock — every seat of the group is held under the token, or none is (409 `SEAT_LOCKED` when any seat is taken, nothing locked). The sales-channel defaults (web 8, box office 20, partner 64) then step aside; the organizer's booking limits and the workspace cap still apply. Season and multi-event holds keep the 64-lock limit. **Booking limits:** the organizer's *Max seats per order* (designer → Booking limits, stored as `layoutMeta.bookingRules` of the published chart/event layout) caps the seats one hold token holds, appends included, checked in the same atomic call as the locks (parallel appends cannot exceed it); the strictest of the sales-channel default, this limit, the per-buyer limit and `maxSeatsPerHoldToken` wins. Refused with 409 `booking_limit_exceeded` (`limit`, `current` seats already on the token, `requested`, `kind: \"seats\"`). Holds placed before a lower limit was published keep their seats and stay confirmable; they only cannot grow. With ticket buyer validation on, buyer tokens must carry a bound ticket buyer id (403 `ticket_buyer_required` / `ticket_buyer_mismatch`). Seats that are not for sale are refused with 409 `SEAT_NOT_FOR_SALE`, except a seat with an active **resale** listing in a season member whose for-sale configuration does not propagate (`forSalePropagated: false`, e.g. a season-ticket seat its holder resells for one game); the confirmation and the order commit apply the same rule.
     # @param idempotency_key [String] Required deduplication key (max 255 chars after trim; UUID v4 recommended). 24h idempotent cache replay in Redis per tenant.
     # @param post_api_seats_reserve_request [PostApiSeatsReserveRequest] 
     # @param [Hash] opts the optional parameters

data/lib/seatschart/api/usage_api.rb

@@ -20,9 +20,10 @@ module SeatsChart
       @api_client = api_client
     end
     # Request monitoring per rate-limit lane, with in-flight (concurrent) requests
-    # Peak requests per minute and 429 counts per lane for the last 10 minutes, hour, 24 hours or 7 days. The **sales lane** carries the buyer path (seat map reads, manifest/geometry/state, the live stream, holds, renewals, best-available, releases, quotes, confirmations); the **api lane** carries everything else (reports, events, charts, workspaces, webhooks, keys), so reporting bursts never starve sales. Counters are written by the rate limiter in its existing Redis call (no extra round trip); minute data is kept 25 hours, hourly peaks 8 days. 10m/1h: one bucket per minute; 24h: 15-minute buckets (peak minute); 7d: hourly buckets. `concurrency` reports requests in flight now and the highest number of concurrent requests in the last hour and day, for the workspace and per API key (live SSE streams are connections and are not counted). Each API instance counts in memory and stores a new per-minute peak in the same limiter call, so with several instances the peaks are summed (an upper bound) and `current` is the instance that answered. Dashboard session (any role) or an API key with the `reports` scope.
+    # Peak requests per minute and 429 counts per lane for the last 10 minutes, hour, 24 hours, 7 days or 30 days, or for an earlier window of the same size with the `before` cursor (each response carries `previousBefore` / `nextBefore`; every point says whether it had 429s in `limited`). The **sales lane** carries the buyer path (seat map reads, manifest/geometry/state, the live stream, holds, renewals, best-available, releases, quotes, confirmations); the **api lane** carries everything else (reports, events, charts, workspaces, webhooks, keys), so reporting bursts never starve sales. Counters are written by the rate limiter in its existing Redis call (no extra round trip); minute data is kept 24 hours, hourly peaks 31 days. 10m/1h: one bucket per minute; 24h: 15-minute buckets (peak minute); 7d: hourly buckets; 30d: UTC days (rolled up from the hours on the first read and kept as long as the hours). `concurrency` always describes now (not the `before` window). `concurrency` reports requests in flight now and the highest number of concurrent requests in the last hour and day, for the workspace and per API key (live SSE streams are connections and are not counted). Each API instance counts in memory and stores a new per-minute peak in the same limiter call, so with several instances the peaks are summed (an upper bound) and `current` is the instance that answered. Dashboard session (any role) or an API key with the `reports` scope.
     # @param [Hash] opts the optional parameters
-    # @option opts [String] :range Time range (default `1h`).
+    # @option opts [String] :range Window size (default `1h`): 10 minutes, an hour or 24 hours (minute data, kept 24 hours), 7 days (hourly) or 30 days (daily), both kept 31 days.
+    # @option opts [Time] :before History cursor: the window ends just before this instant (aligned down to the bucket source: minute, hour or UTC day). Omit for the live window ending now. Use `previousBefore` / `nextBefore` of a response to step back and forth.
     # @return [GetApiMonitoringRequests200Response]
     def get_api_monitoring_requests(opts = {})
       data, _status_code, _headers = get_api_monitoring_requests_with_http_info(opts)
@@ -30,15 +31,16 @@ module SeatsChart
     end
 
     # Request monitoring per rate-limit lane, with in-flight (concurrent) requests
-    # Peak requests per minute and 429 counts per lane for the last 10 minutes, hour, 24 hours or 7 days. The **sales lane** carries the buyer path (seat map reads, manifest/geometry/state, the live stream, holds, renewals, best-available, releases, quotes, confirmations); the **api lane** carries everything else (reports, events, charts, workspaces, webhooks, keys), so reporting bursts never starve sales. Counters are written by the rate limiter in its existing Redis call (no extra round trip); minute data is kept 25 hours, hourly peaks 8 days. 10m/1h: one bucket per minute; 24h: 15-minute buckets (peak minute); 7d: hourly buckets. `concurrency` reports requests in flight now and the highest number of concurrent requests in the last hour and day, for the workspace and per API key (live SSE streams are connections and are not counted). Each API instance counts in memory and stores a new per-minute peak in the same limiter call, so with several instances the peaks are summed (an upper bound) and `current` is the instance that answered. Dashboard session (any role) or an API key with the `reports` scope.
+    # Peak requests per minute and 429 counts per lane for the last 10 minutes, hour, 24 hours, 7 days or 30 days, or for an earlier window of the same size with the `before` cursor (each response carries `previousBefore` / `nextBefore`; every point says whether it had 429s in `limited`). The **sales lane** carries the buyer path (seat map reads, manifest/geometry/state, the live stream, holds, renewals, best-available, releases, quotes, confirmations); the **api lane** carries everything else (reports, events, charts, workspaces, webhooks, keys), so reporting bursts never starve sales. Counters are written by the rate limiter in its existing Redis call (no extra round trip); minute data is kept 24 hours, hourly peaks 31 days. 10m/1h: one bucket per minute; 24h: 15-minute buckets (peak minute); 7d: hourly buckets; 30d: UTC days (rolled up from the hours on the first read and kept as long as the hours). `concurrency` always describes now (not the `before` window). `concurrency` reports requests in flight now and the highest number of concurrent requests in the last hour and day, for the workspace and per API key (live SSE streams are connections and are not counted). Each API instance counts in memory and stores a new per-minute peak in the same limiter call, so with several instances the peaks are summed (an upper bound) and `current` is the instance that answered. Dashboard session (any role) or an API key with the `reports` scope.
     # @param [Hash] opts the optional parameters
-    # @option opts [String] :range Time range (default `1h`).
+    # @option opts [String] :range Window size (default `1h`): 10 minutes, an hour or 24 hours (minute data, kept 24 hours), 7 days (hourly) or 30 days (daily), both kept 31 days.
+    # @option opts [Time] :before History cursor: the window ends just before this instant (aligned down to the bucket source: minute, hour or UTC day). Omit for the live window ending now. Use `previousBefore` / `nextBefore` of a response to step back and forth.
     # @return [Array<(GetApiMonitoringRequests200Response, Integer, Hash)>] GetApiMonitoringRequests200Response data, response status code and response headers
     def get_api_monitoring_requests_with_http_info(opts = {})
       if @api_client.config.debugging
         @api_client.config.logger.debug 'Calling API: UsageApi.get_api_monitoring_requests ...'
       end
-      allowable_values = ["10m", "1h", "24h", "7d"]
+      allowable_values = ["10m", "1h", "24h", "7d", "30d"]
       if @api_client.config.client_side_validation && opts[:'range'] && !allowable_values.include?(opts[:'range'])
         fail ArgumentError, "invalid value for \"range\", must be one of #{allowable_values}"
       end
@@ -48,6 +50,7 @@ module SeatsChart
       # query parameters
       query_params = opts[:query_params] || {}
       query_params[:'range'] = opts[:'range'] if !opts[:'range'].nil?
+      query_params[:'before'] = opts[:'before'] if !opts[:'before'].nil?
 
       # header parameters
       header_params = opts[:header_params] || {}
@@ -84,7 +87,7 @@ module SeatsChart
     end
 
     # Monthly usage: used objects, charts and events
-    # Test (sandbox) workspaces (`isTest: true`) are never metered and have no limits (`limit: null`). `usedObjects.count` is the number of distinct objects booked in the UTC calendar month (seats.io-style billing unit): every seat that became booked counts once per month however often it is retried, released and re-booked; each sold general-admission place counts as one. Holds, test events and replays never count. `history` has exactly 12 months ending at `month` (zero-filled); `byEvent` lists the top 100 events of the month. `charts`/`events` are current totals against the plan limits. Dashboard JWT (any role) or an API key with the `reports` scope.
+    # Sandboxes (`isTest: true`) are metered so their usage can be seen, but never billed and never held to plan limits (`limit: null`). `usedObjects.count` is the number of distinct objects booked in the UTC calendar month (seats.io-style billing unit): every seat that became booked counts once per month however often it is retried, released and re-booked; each sold general-admission place counts as one. Holds, test events and replays never count. Map-only renders (`bringYourOwnBackend`) count every object of the rendered chart once per chart and month (`byEvent` entry with the chart id and `mapOnly: true`). `history` has exactly 12 months ending at `month` (zero-filled); `byEvent` lists the top 100 events of the month. `charts`/`events` are current totals against the plan limits. Dashboard JWT (any role) or an API key with the `reports` scope.
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month &#x60;YYYY-MM&#x60; (default: current month).
     # @return [nil]
@@ -94,7 +97,7 @@ module SeatsChart
     end
 
     # Monthly usage: used objects, charts and events
-    # Test (sandbox) workspaces (&#x60;isTest: true&#x60;) are never metered and have no limits (&#x60;limit: null&#x60;). &#x60;usedObjects.count&#x60; is the number of distinct objects booked in the UTC calendar month (seats.io-style billing unit): every seat that became booked counts once per month however often it is retried, released and re-booked; each sold general-admission place counts as one. Holds, test events and replays never count. &#x60;history&#x60; has exactly 12 months ending at &#x60;month&#x60; (zero-filled); &#x60;byEvent&#x60; lists the top 100 events of the month. &#x60;charts&#x60;/&#x60;events&#x60; are current totals against the plan limits. Dashboard JWT (any role) or an API key with the &#x60;reports&#x60; scope.
+    # Sandboxes (&#x60;isTest: true&#x60;) are metered so their usage can be seen, but never billed and never held to plan limits (&#x60;limit: null&#x60;). &#x60;usedObjects.count&#x60; is the number of distinct objects booked in the UTC calendar month (seats.io-style billing unit): every seat that became booked counts once per month however often it is retried, released and re-booked; each sold general-admission place counts as one. Holds, test events and replays never count. Map-only renders (&#x60;bringYourOwnBackend&#x60;) count every object of the rendered chart once per chart and month (&#x60;byEvent&#x60; entry with the chart id and &#x60;mapOnly: true&#x60;). &#x60;history&#x60; has exactly 12 months ending at &#x60;month&#x60; (zero-filled); &#x60;byEvent&#x60; lists the top 100 events of the month. &#x60;charts&#x60;/&#x60;events&#x60; are current totals against the plan limits. Dashboard JWT (any role) or an API key with the &#x60;reports&#x60; scope.
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month &#x60;YYYY-MM&#x60; (default: current month).
     # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
@@ -147,7 +150,7 @@ module SeatsChart
     end
 
     # Monthly used objects per chart and event
-    # Breakdown of `usedObjects` (see GET /usage) by chart, each with its events (most used first). Events are grouped under their current chart; deleted events or events without a chart are listed under `chartId: null`. Read from the metering table (no counters on the booking path). Dashboard JWT (any role) or an API key.
+    # Breakdown of `usedObjects` (see GET /usage) by chart, each with its events (most used first). Events are grouped under their current chart; deleted events or events without a chart are listed under `chartId: null`; map-only renders of a chart (`bringYourOwnBackend`) are one entry `{ eventId: <chart id>, mapOnly: true }` under that chart. Read from the metering table (no counters on the booking path). Dashboard JWT (any role) or an API key.
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month &#x60;YYYY-MM&#x60; (default: current month).
     # @return [nil]
@@ -157,7 +160,7 @@ module SeatsChart
     end
 
     # Monthly used objects per chart and event
-    # Breakdown of &#x60;usedObjects&#x60; (see GET /usage) by chart, each with its events (most used first). Events are grouped under their current chart; deleted events or events without a chart are listed under &#x60;chartId: null&#x60;. Read from the metering table (no counters on the booking path). Dashboard JWT (any role) or an API key.
+    # Breakdown of &#x60;usedObjects&#x60; (see GET /usage) by chart, each with its events (most used first). Events are grouped under their current chart; deleted events or events without a chart are listed under &#x60;chartId: null&#x60;; map-only renders of a chart (&#x60;bringYourOwnBackend&#x60;) are one entry &#x60;{ eventId: &lt;chart id&gt;, mapOnly: true }&#x60; under that chart. Read from the metering table (no counters on the booking path). Dashboard JWT (any role) or an API key.
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month &#x60;YYYY-MM&#x60; (default: current month).
     # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
@@ -210,7 +213,7 @@ module SeatsChart
     end
 
     # Monthly used objects per event (paginated)
-    # Every event with used objects in the month, most used first (ties by event id): `items: [{ eventId, eventKey, eventName, chartId, usedObjects }]` (`eventName: null` for deleted events), `eventCount` and the month total `usedObjects`. `limit` 1..100 (default 50); pass `nextCursor` as `cursor` for the next page. Unlike `byEvent` of GET /usage (top 100) this lists every event. Closed months are immutable and their per-event totals are cached by the API. Dashboard JWT (any role) or an API key with the `reports` scope.
+    # Every event with used objects in the month, most used first (ties by event id): `items: [{ eventId, eventKey, eventName, chartId, usedObjects }]` (`eventName: null` for deleted events; map-only renders of a chart: `eventId` = `chartId` = the chart id and `mapOnly: true`), `eventCount` and the month total `usedObjects`. `limit` 1..100 (default 50); pass `nextCursor` as `cursor` for the next page. Unlike `byEvent` of GET /usage (top 100) this lists every event. Closed months are immutable and their per-event totals are cached by the API. Dashboard JWT (any role) or an API key with the `reports` scope.
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month &#x60;YYYY-MM&#x60; (default: current month).
     # @option opts [Float] :limit Page size (1..100, default 50).
@@ -222,7 +225,7 @@ module SeatsChart
     end
 
     # Monthly used objects per event (paginated)
-    # Every event with used objects in the month, most used first (ties by event id): &#x60;items: [{ eventId, eventKey, eventName, chartId, usedObjects }]&#x60; (&#x60;eventName: null&#x60; for deleted events), &#x60;eventCount&#x60; and the month total &#x60;usedObjects&#x60;. &#x60;limit&#x60; 1..100 (default 50); pass &#x60;nextCursor&#x60; as &#x60;cursor&#x60; for the next page. Unlike &#x60;byEvent&#x60; of GET /usage (top 100) this lists every event. Closed months are immutable and their per-event totals are cached by the API. Dashboard JWT (any role) or an API key with the &#x60;reports&#x60; scope.
+    # Every event with used objects in the month, most used first (ties by event id): &#x60;items: [{ eventId, eventKey, eventName, chartId, usedObjects }]&#x60; (&#x60;eventName: null&#x60; for deleted events; map-only renders of a chart: &#x60;eventId&#x60; &#x3D; &#x60;chartId&#x60; &#x3D; the chart id and &#x60;mapOnly: true&#x60;), &#x60;eventCount&#x60; and the month total &#x60;usedObjects&#x60;. &#x60;limit&#x60; 1..100 (default 50); pass &#x60;nextCursor&#x60; as &#x60;cursor&#x60; for the next page. Unlike &#x60;byEvent&#x60; of GET /usage (top 100) this lists every event. Closed months are immutable and their per-event totals are cached by the API. Dashboard JWT (any role) or an API key with the &#x60;reports&#x60; scope.
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month &#x60;YYYY-MM&#x60; (default: current month).
     # @option opts [Float] :limit Page size (1..100, default 50).
@@ -300,7 +303,7 @@ module SeatsChart
     end
 
     # Monthly used objects of one event (paginated)
-    # Total `usedObjects` of the event in the month, `objectCount` (metered objects) and one page of the metered objects (`objectKey`: seat id, or `ga:<receiptId>` with `units` places; `firstUsedAt` with microseconds), newest first. `limit` 1..1000 (default 1000); pass `nextCursor` as `cursor` for the next page (`null` on the last page; `truncated` is true when more pages follow). Keyset pagination over the primary-key range of the event and month. Works for deleted events that were metered. Dashboard JWT (any role) or an API key with the `reports` scope.
+    # Total `usedObjects` of the event in the month, `objectCount` (metered objects) and one page of the metered objects (`objectKey`: seat id, or `ga:<receiptId>` with `units` places; `firstUsedAt` with microseconds), newest first. `limit` 1..1000 (default 1000); pass `nextCursor` as `cursor` for the next page (`null` on the last page; `truncated` is true when more pages follow). Keyset pagination over the primary-key range of the event and month. Works for deleted events that were metered. Map-only renders of a chart (`objectKey: map-only`) are listed under the chart id with `mapOnly: true`. Dashboard JWT (any role) or an API key with the `reports` scope.
     # @param event_id [String] 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month &#x60;YYYY-MM&#x60; (default: current month).
@@ -313,7 +316,7 @@ module SeatsChart
     end
 
     # Monthly used objects of one event (paginated)
-    # Total &#x60;usedObjects&#x60; of the event in the month, &#x60;objectCount&#x60; (metered objects) and one page of the metered objects (&#x60;objectKey&#x60;: seat id, or &#x60;ga:&lt;receiptId&gt;&#x60; with &#x60;units&#x60; places; &#x60;firstUsedAt&#x60; with microseconds), newest first. &#x60;limit&#x60; 1..1000 (default 1000); pass &#x60;nextCursor&#x60; as &#x60;cursor&#x60; for the next page (&#x60;null&#x60; on the last page; &#x60;truncated&#x60; is true when more pages follow). Keyset pagination over the primary-key range of the event and month. Works for deleted events that were metered. Dashboard JWT (any role) or an API key with the &#x60;reports&#x60; scope.
+    # Total &#x60;usedObjects&#x60; of the event in the month, &#x60;objectCount&#x60; (metered objects) and one page of the metered objects (&#x60;objectKey&#x60;: seat id, or &#x60;ga:&lt;receiptId&gt;&#x60; with &#x60;units&#x60; places; &#x60;firstUsedAt&#x60; with microseconds), newest first. &#x60;limit&#x60; 1..1000 (default 1000); pass &#x60;nextCursor&#x60; as &#x60;cursor&#x60; for the next page (&#x60;null&#x60; on the last page; &#x60;truncated&#x60; is true when more pages follow). Keyset pagination over the primary-key range of the event and month. Works for deleted events that were metered. Map-only renders of a chart (&#x60;objectKey: map-only&#x60;) are listed under the chart id with &#x60;mapOnly: true&#x60;. Dashboard JWT (any role) or an API key with the &#x60;reports&#x60; scope.
     # @param event_id [String] 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month &#x60;YYYY-MM&#x60; (default: current month).
@@ -475,7 +478,7 @@ module SeatsChart
     end
 
     # Monthly used objects across my workspaces (admin view)
-    # Every workspace the caller administers (role admin), with its plan, status and used objects of the month against the plan limit (`null` for test workspaces, which are never metered), plus the total. Dashboard session, or a **workspace admin API key** (the admin it is bound to); other API keys: 403 `ERR_PARTNER_SCOPE`. One grouped read of the metering table.
+    # Every workspace the caller administers (role admin), with its plan, status and used objects of the month against the plan limit (`null` for sandboxes, which are metered but never billed), plus the total of the production workspaces (`usedObjects`) and, separately, of the sandboxes (`sandboxUsedObjects`). Dashboard session, or a **workspace admin API key** (the admin it is bound to); other API keys: 403 `ERR_PARTNER_SCOPE`. One grouped read of the metering table.
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month &#x60;YYYY-MM&#x60; (default: current month).
     # @return [nil]
@@ -485,7 +488,7 @@ module SeatsChart
     end
 
     # Monthly used objects across my workspaces (admin view)
-    # Every workspace the caller administers (role admin), with its plan, status and used objects of the month against the plan limit (&#x60;null&#x60; for test workspaces, which are never metered), plus the total. Dashboard session, or a **workspace admin API key** (the admin it is bound to); other API keys: 403 &#x60;ERR_PARTNER_SCOPE&#x60;. One grouped read of the metering table.
+    # Every workspace the caller administers (role admin), with its plan, status and used objects of the month against the plan limit (&#x60;null&#x60; for sandboxes, which are metered but never billed), plus the total of the production workspaces (&#x60;usedObjects&#x60;) and, separately, of the sandboxes (&#x60;sandboxUsedObjects&#x60;). Dashboard session, or a **workspace admin API key** (the admin it is bound to); other API keys: 403 &#x60;ERR_PARTNER_SCOPE&#x60;. One grouped read of the metering table.
     # @param [Hash] opts the optional parameters
     # @option opts [String] :month UTC calendar month &#x60;YYYY-MM&#x60; (default: current month).
     # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers

data/lib/seatschart/api/webhooks_api.rb

@@ -332,7 +332,7 @@ module SeatsChart
     end
 
     # List subscribable webhook event types
-    # Event types an endpoint can subscribe to through `eventTypes`. `webhook.test` is sent only by `POST /api/webhooks/{id}/test` and cannot be subscribed to. `aliases`: seats.io-named aliases (`{ type, aliasOf }`), opt-in per endpoint: the aliased event is delivered again under the alias name to endpoints that list it explicitly (same payload, `type` = alias); `[\"*\"]` does not include aliases.
+    # Event types an endpoint can subscribe to through `eventTypes`. `webhook.test` is sent only by `POST /api/webhooks/{id}/test` and cannot be subscribed to. `aliases`: seats.io-named aliases (`{ type, aliasOf }`), opt-in per endpoint: the aliased event is delivered again under the alias name to endpoints that list it explicitly (same payload, `type` = alias); `[\"*\"]` does not include aliases. **Deprecated spellings**: `event.for_sale_changed`, `event.channels_updated`, `event.categories_updated` and `event.table_booking_changed` carry `deprecated: { replacedBy, sunset }` — subscribe to the seats.io name in `replacedBy`; the old spelling is still emitted and is not removed before 2027-06-01.
     # @param [Hash] opts the optional parameters
     # @return [nil]
     def get_api_webhooks_event_types(opts = {})
@@ -341,7 +341,7 @@ module SeatsChart
     end
 
     # List subscribable webhook event types
-    # Event types an endpoint can subscribe to through `eventTypes`. `webhook.test` is sent only by `POST /api/webhooks/{id}/test` and cannot be subscribed to. `aliases`: seats.io-named aliases (`{ type, aliasOf }`), opt-in per endpoint: the aliased event is delivered again under the alias name to endpoints that list it explicitly (same payload, `type` = alias); `[\"*\"]` does not include aliases.
+    # Event types an endpoint can subscribe to through `eventTypes`. `webhook.test` is sent only by `POST /api/webhooks/{id}/test` and cannot be subscribed to. `aliases`: seats.io-named aliases (`{ type, aliasOf }`), opt-in per endpoint: the aliased event is delivered again under the alias name to endpoints that list it explicitly (same payload, `type` = alias); `[\"*\"]` does not include aliases. **Deprecated spellings**: `event.for_sale_changed`, `event.channels_updated`, `event.categories_updated` and `event.table_booking_changed` carry `deprecated: { replacedBy, sunset }` — subscribe to the seats.io name in `replacedBy`; the old spelling is still emitted and is not removed before 2027-06-01.
     # @param [Hash] opts the optional parameters
     # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
     def get_api_webhooks_event_types_with_http_info(opts = {})