From 936098e979a94186a506b8d48d8a9b2c7a75f133 Mon Sep 17 00:00:00 2001 From: Lucas-FullStackX Date: Sun, 1 Nov 2026 16:21:41 -0500 Subject: [PATCH] feat: event lineup commands (contract 1.25.0) Sync openapi.json to free-admin's feat/api-v1-lineup branch (1.25.0, not deployed yet) and add: - ft artists search - ft events artists set --artist ... [--invite ...] (asks before removing artists or clearing the lineup; prints ARTIST_IDS_IGNORED warnings) - ft events artists remove (--yes) - ft events invitations list|resend|cancel (cancel takes --yes) Depends on AppFreeticket/free-admin#1155. Co-Authored-By: Claude Opus 5.5 --- .changeset/lineup-artists.md | 5 + README.md | 4 + openapi.json | 3278 ++++++++++++++++++++++--------- src/commands/lineup.test.ts | 153 ++ src/commands/lineup.ts | 193 ++ src/destructive-confirm.test.ts | 13 + src/program.ts | 4 + 7 files changed, 2728 insertions(+), 922 deletions(-) create mode 100644 .changeset/lineup-artists.md create mode 100644 src/commands/lineup.test.ts create mode 100644 src/commands/lineup.ts diff --git a/.changeset/lineup-artists.md b/.changeset/lineup-artists.md new file mode 100644 index 0000000..92cd258 --- /dev/null +++ b/.changeset/lineup-artists.md @@ -0,0 +1,5 @@ +--- +"@freeticket/cli": minor +--- + +Manage an event's lineup from the terminal (contract 1.25.0): `ft artists search`, `ft events artists set|remove` and `ft events invitations list|resend|cancel`. `set` asks before removing anyone from the lineup (`--yes` skips it) and prints `ARTIST_IDS_IGNORED` warnings. diff --git a/README.md b/README.md index 3c9db65..3559d02 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,10 @@ ft sales list --status CONFIRMED --json | `ft events list` · `get ` | Workspace events (`--q` `--status` `--with-total`) | VIEWER | | `ft events create` · `update ` · `delete ` | Manage events (`--data `) | ADMIN | | `ft events publish ` · `cancel ` | Publish an event · cancel it and all its dates, keeping sales and tickets (no refunds; `--yes` skips the prompt) | ADMIN | +| `ft artists search ` | Find registered artists by name to get the ids a lineup takes (`--limit` `--cursor`) | VIEWER | +| `ft events artists set --artist ... [--invite ...]` | Replace the lineup, in order (unlisted artists are unlinked; asks before removing anyone, `--yes` skips it; ignored ids are shown as `ARTIST_IDS_IGNORED`) | ADMIN | +| `ft events artists remove ` | Unlink one artist (`--yes` skips the prompt) | ADMIN | +| `ft events invitations list ` · `resend ` · `cancel ` | Invitations sent to artists without an account: list, resend (renews 14 days, sends an email) and cancel (`--yes`) | ADMIN | | `ft event-dates list` · `create` · `update` · `delete` | Event dates | ADMIN | | `ft ticket-types list` · `get ` | Ticket types (`--event-date-id`) | VIEWER | | `ft ticket-types create` · `update ` · `delete ` | Manage ticket types (`--data `) | ADMIN | diff --git a/openapi.json b/openapi.json index 2fdb8dd..839d068 100644 --- a/openapi.json +++ b/openapi.json @@ -2,8 +2,8 @@ "openapi": "3.1.0", "info": { "title": "FreeTicket B2B API", - "version": "1.20.0", - "description": "FreeTicket B2B REST API for integrations and the CLI. Authentication is by API key (`Authorization: Bearer ` header or `x-api-key`); the active workspace is selected with the `X-Workspace-Id` header.\n\nScopes: each key is either `read` (GET/HEAD only) or `write` (additionally creates, edits, deletes, cancels, refunds and checks in). Self-service keys are issued as `read`. A `read` key calling a mutating method gets a 403. The machine-readable declaration lives at `/.well-known/oauth-protected-resource` (RFC 9728)." + "version": "1.25.0", + "description": "FreeTicket B2B REST API for integrations, the `ft` CLI and the FreeTicket MCP server. Authentication is by API key (`Authorization: Bearer ` header or `x-api-key`); the active workspace is selected with the `X-Workspace-Id` header.\n\nScopes: each key is either `read` (GET/HEAD only) or `write` (additionally creates, edits, deletes, cancels, refunds and checks in). Self-service keys are issued as `read`. A `read` key calling a mutating method gets a 403. The machine-readable declaration lives at `/.well-known/oauth-protected-resource` (RFC 9728).\n\nGetting a key (self-serve, no sales contact): `ft login` runs the Device Authorization Grant (RFC 8628, `POST /auth/device/code` + `POST /auth/device/token`); the user approves the code at https://admin.appfreeticket.com/device and the CLI receives a key. New organizers can bootstrap headless with `POST /auth/signup` (verify-first, then `ft login`). With a key, `POST /api-keys` mints more (born `read` unless `write` is requested). There is no sandbox environment: test against a dedicated workspace with `read` keys.\n\n## Versioning and deprecation\n\n- **Path version.** The B2B API is versioned in the path (`/api/v1`). A breaking change ships under a new path (`/api/v2`); the previous version keeps running in parallel until its sunset date.\n- **Contract version.** `info.version` is the semantic version of this document. MINOR = additive (new endpoints, new optional fields, new enum values, new error codes; clients must ignore unknown fields). PATCH = documentation or fixes that do not change shapes. The public API (`/api/public`) is pre-1.0 and not versioned in the path: there, a MINOR bump may include a breaking change and PATCH never does.\n- **Deprecation signals.** A deprecated operation is marked `deprecated: true` in this document and its responses carry `Deprecation` (RFC 9745, e.g. `Deprecation: @1767225600`), `Sunset` (RFC 8594, an HTTP-date after which the operation may stop working) and `Link: ; rel=\"deprecation\"`.\n- **Timeline.** At least 6 months between the first `Deprecation` header and the `Sunset` date for `/api/v1`, and at least 90 days for `/api/public`. A path version is only retired after all its operations have sunset.\n- **Current status.** No operation is deprecated today.\n\n## Rate limits\n\n- **429 always carries `Retry-After`** (seconds). Wait at least that long before retrying the same request. The JSON error envelope comes with `error.retryable: true`; most rate-limited responses use `error.code: \"RATE_LIMITED\"`, and some return a more specific code (for example `TOO_MANY_REQUESTS` or `SEAT_BUDGET_EXHAUSTED`).\n- **RateLimit headers are sent where listed below.** Those endpoints answer every response, success or error, with the IETF RateLimit headers (draft-ietf-httpapi-ratelimit-headers): `RateLimit-Policy: \"\";q=;w=` and `RateLimit: \"\";r=;t=`. Other endpoints may answer 429 without them.\n- Counters are fixed windows kept per server instance: treat the numbers as pacing hints, not as a global account quota.\n\nEndpoints that send RateLimit headers today: `POST /auth/signup` (per client IP), `POST /customer/auth/request` and `POST /customer/auth/verify` (per client IP), and the buyer-session endpoints `GET /customer/orders/{id}`, `POST /customer/orders/{id}/payment`, `/payment/card`, `/payment/pse`, `/release`, `POST /customer/purchase-sessions` and `POST /customer/purchase-sessions/{id}/release`." }, "servers": [ { @@ -19,211 +19,6 @@ } ], "paths": { - "/events/{id}/dates": { - "get": { - "operationId": "getEventsIdDates", - "tags": [ - "events" - ], - "summary": "List an event's dates", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", - "security": [ - { - "apiKey": [] - }, - { - "apiKeyHeader": [] - } - ], - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "X-Workspace-Id", - "in": "header", - "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EventDate" - } - } - }, - "required": [ - "data" - ] - } - } - } - }, - "401": { - "description": "Missing or invalid credential.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "403": { - "description": "Insufficient role or resource not accessible.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "404": { - "description": "Resource does not exist or is out of scope.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "422": { - "description": "Request body/parameter validation failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - }, - "post": { - "operationId": "postEventsIdDates", - "tags": [ - "events" - ], - "summary": "Add a date to an event", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", - "security": [ - { - "apiKey": [] - }, - { - "apiKeyHeader": [] - } - ], - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "X-Workspace-Id", - "in": "header", - "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EventDateCreate" - } - } - } - }, - "responses": { - "201": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EventDate" - } - }, - "required": [ - "data" - ] - } - } - } - }, - "401": { - "description": "Missing or invalid credential.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "403": { - "description": "Insufficient role or resource not accessible.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "404": { - "description": "Resource does not exist or is out of scope.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "422": { - "description": "Request body/parameter validation failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, "/auth/device/code": { "post": { "operationId": "postAuthDeviceCode", @@ -1030,7 +825,7 @@ "events" ], "summary": "Delete an event (soft delete)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nReturns 409 `EVENT_HAS_SALES` when the event has CONFIRMED or REFUNDED sales; cancel it with `POST /events/{id}/cancel` instead.", "security": [ { "apiKey": [] @@ -1099,6 +894,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -1326,14 +1131,14 @@ } } }, - "/events/{id}/dates/{dateId}": { - "patch": { - "operationId": "patchEventsIdDatesDateId", + "/events/{id}/dates": { + "get": { + "operationId": "getEventsIdDates", "tags": [ "events" ], - "summary": "Update an event date", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List an event's dates", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -1351,14 +1156,6 @@ "type": "string" } }, - { - "name": "dateId", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -1369,16 +1166,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EventDateUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -1388,7 +1175,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/EventDate" + "type": "array", + "items": { + "$ref": "#/components/schemas/EventDate" + } } }, "required": [ @@ -1440,12 +1230,12 @@ } } }, - "delete": { - "operationId": "deleteEventsIdDatesDateId", + "post": { + "operationId": "postEventsIdDates", "tags": [ "events" ], - "summary": "Delete an event date", + "summary": "Add a date to an event", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -1464,14 +1254,6 @@ "type": "string" } }, - { - "name": "dateId", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -1482,13 +1264,31 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventDateCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EventDate" + } + }, + "required": [ + "data" + ] } } } @@ -1523,16 +1323,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -1546,14 +1336,14 @@ } } }, - "/ticket-types": { - "get": { - "operationId": "getTicketTypes", + "/events/{id}/dates/{dateId}": { + "patch": { + "operationId": "patchEventsIdDatesDateId", "tags": [ - "ticket-types" + "events" ], - "summary": "List workspace ticket types", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Update an event date", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -1564,28 +1354,17 @@ ], "parameters": [ { - "name": "eventDateId", - "in": "query", - "required": false, - "description": "filter by event date", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } }, { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "name": "cursor", - "in": "query", - "required": false, + "name": "dateId", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -1600,6 +1379,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventDateUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -1609,18 +1398,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TicketType" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/EventDate" } }, "required": [ - "data", - "page" + "data" ] } } @@ -1668,12 +1450,12 @@ } } }, - "post": { - "operationId": "postTicketTypes", + "delete": { + "operationId": "deleteEventsIdDatesDateId", "tags": [ - "ticket-types" + "events" ], - "summary": "Create a ticket type", + "summary": "Delete an event date", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -1684,6 +1466,22 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "dateId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -1694,31 +1492,13 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TicketTypeCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/TicketType" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -1753,6 +1533,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -1766,14 +1556,14 @@ } } }, - "/ticket-types/{id}": { - "get": { - "operationId": "getTicketTypesId", + "/events/{id}/artists": { + "put": { + "operationId": "putEventsIdArtists", "tags": [ - "ticket-types" + "events" ], - "summary": "Get a ticket type", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Replace the event lineup", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nReplaces the artists linked to the event with `artistIds`, in that order (the lineup order). Artists not in the list are unlinked (send the full lineup, not a diff); `[]` clears it. Ids come from `GET /artists?q=` (workspace ids of registered artists). Newly linked artists get a notification email.\n\n`inviteEmails` invites artists without an account: each email gets an invitation (only once per email and event) and is linked when it signs up. `inviteEmails` is additive: omitting it does not cancel existing invitations (use `DELETE /events/{id}/artist-invitations/{invitationId}`).\n\nIds that are not a registered artist (or the event's own workspace) are skipped and reported in `warnings[]` with code `ARTIST_IDS_IGNORED` (`ids`).\n\nLimits: up to 50 `artistIds` and 20 `inviteEmails` per request; 20 lineup changes per hour per API key and event (429 `RATE_LIMITED` with `Retry-After`).", "security": [ { "apiKey": [] @@ -1801,6 +1591,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventArtistsReplace" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -1810,7 +1610,13 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/TicketType" + "$ref": "#/components/schemas/Event" + }, + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Warning" + } } }, "required": [ @@ -1859,16 +1665,39 @@ } } } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } } } - }, - "patch": { - "operationId": "patchTicketTypesId", + } + }, + "/events/{id}/artists/{organizationId}": { + "delete": { + "operationId": "deleteEventsIdArtistsOrganizationId", "tags": [ - "ticket-types" + "events" ], - "summary": "Update a ticket type", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Unlink an artist from an event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nRemoves one artist from the event lineup. Allowed for the workspace that owns the event, or for the artist itself (`organizationId` equal to the active workspace) to remove itself from an event it was linked to. 404 `EVENT_NOT_FOUND` when the event is not owned by the workspace; 404 `ARTIST_NOT_LINKED` when the artist is not in its lineup (when unlinking itself, the artist always gets `ARTIST_NOT_LINKED`).", "security": [ { "apiKey": [] @@ -1886,6 +1715,14 @@ "type": "string" } }, + { + "name": "organizationId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -1896,16 +1733,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TicketTypeUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -1915,7 +1742,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/TicketType" + "$ref": "#/components/schemas/EventArtistUnlink" } }, "required": [ @@ -1955,16 +1782,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -1976,14 +1793,16 @@ } } } - }, - "delete": { - "operationId": "deleteTicketTypesId", + } + }, + "/events/{id}/artist-invitations": { + "get": { + "operationId": "getEventsIdArtistInvitations", "tags": [ - "ticket-types" + "events" ], - "summary": "Delete a ticket type (soft delete)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List artist invitations of an event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nPending and expired invitations sent to artists without an account (via `inviteEmails` in `PUT /events/{id}/artists`), newest first. Accepted invitations are not listed: they are already linked artists. Invitations expire 14 days after being sent.", "security": [ { "apiKey": [] @@ -2017,7 +1836,18 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtistInvitation" + } + } + }, + "required": [ + "data" + ] } } } @@ -2052,8 +1882,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -2061,9 +1891,912 @@ } } } - }, - "422": { - "description": "Request body/parameter validation failed.", + } + } + } + }, + "/events/{id}/artist-invitations/{invitationId}": { + "delete": { + "operationId": "deleteEventsIdArtistInvitationsInvitationId", + "tags": [ + "events" + ], + "summary": "Cancel an artist invitation", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nCancels a pending or expired invitation; its link stops working. 409 `INVITATION_ACCEPTED` when the artist already accepted it (unlink the artist with `DELETE /events/{id}/artists/{organizationId}` instead).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "invitationId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ArtistInvitationDeleted" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/events/{id}/artist-invitations/{invitationId}/resend": { + "post": { + "operationId": "postEventsIdArtistInvitationsInvitationIdResend", + "tags": [ + "events" + ], + "summary": "Resend an artist invitation", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nResends the invitation email and renews its expiry to 14 days from now (status back to `PENDING`, same link). Works on expired invitations too. 409 `INVITATION_ACCEPTED` when already accepted. 502 `EMAIL_NOT_SENT` when the email provider failed (the expiry was renewed; retry). Rate limited: 3 resends per hour per API key and invitation (429 `RATE_LIMITED` with `Retry-After`).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "invitationId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ArtistInvitation" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/artists": { + "get": { + "operationId": "getArtists", + "tags": [ + "artists" + ], + "summary": "Search registered artists", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.\n\nSearches artist workspaces registered on FreeTicket by name (case-insensitive, `q` of 2+ characters). Returns public brand data only. Use the `id` in `PUT /events/{id}/artists`; for artists without an account use `inviteEmails` there.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "q", + "in": "query", + "required": true, + "description": "Name to search, 2-100 characters", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtistSummary" + } + }, + "page": { + "$ref": "#/components/schemas/Page" + } + }, + "required": [ + "data", + "page" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/ticket-types": { + "get": { + "operationId": "getTicketTypes", + "tags": [ + "ticket-types" + ], + "summary": "List workspace ticket types", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "eventDateId", + "in": "query", + "required": false, + "description": "filter by event date", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TicketType" + } + }, + "page": { + "$ref": "#/components/schemas/Page" + } + }, + "required": [ + "data", + "page" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postTicketTypes", + "tags": [ + "ticket-types" + ], + "summary": "Create a ticket type", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TicketTypeCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/TicketType" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/ticket-types/{id}": { + "get": { + "operationId": "getTicketTypesId", + "tags": [ + "ticket-types" + ], + "summary": "Get a ticket type", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/TicketType" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "patch": { + "operationId": "patchTicketTypesId", + "tags": [ + "ticket-types" + ], + "summary": "Update a ticket type", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TicketTypeUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/TicketType" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteTicketTypesId", + "tags": [ + "ticket-types" + ], + "summary": "Delete a ticket type (soft delete)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -4012,6 +4745,17 @@ "$ref": "#/components/schemas/Error" } } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } } } } @@ -7403,8 +8147,135 @@ } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/tickets/{ticketCode}": { + "patch": { + "operationId": "patchTicketsTicketCode", + "tags": [ + "tickets" + ], + "summary": "Reassign a sold ticket to another date or ticket type", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nMoves an ALREADY SOLD ticket to another `ticketTypeId` and/or to the `eventDateId` date (at least one of the two is required). Intended for a postponement: moving buyers from the old date to the new one without refunding and reselling.\n\nWith only `eventDateId`, the target ticket type is resolved by NAME (the same type the ticket had, on the new date); if the target date doesn't have exactly one type with that name, it responds 422 and you must pass an explicit `ticketTypeId`.\n\nIt does NOT charge or refund the price difference if the new type costs something else: the ticket's `unitPrice`/`subtotal` keep the sale's ORIGINAL price. If money needs adjusting, use `POST /sales/{id}/refund` separately.\n\nIt does NOT reissue the QR: `ticketCode` is always preserved (it is what the buyer already has printed, in Wallet and in their email).\n\nIt does NOT notify the buyer. This endpoint only moves data; to resend the updated ticket use `POST /tickets/{ticketCode}/resend`, and for a bulk postponement notice, use the communications module.\n\nA ticket that is already checked in, or that belongs to a sale that is not CONFIRMED, responds 409 and is not reassigned. A ticket refunded by item (or whose seat was blocked after a refund) responds 409 `TICKET_REFUNDED`.\n\nNUMBERED SEATING (seats.io): if the target date has numbered seating, `seatLabel` is REQUIRED (409 `SEAT_REQUIRED` if missing) — the server never picks a seat on its own. The seat is validated and booked in seats.io before moving the ticket; if it is no longer available, it responds 409 `SEAT_UNAVAILABLE` without changing anything. If the ticket held a numbered seat on the source date, that seat is released after the move is confirmed.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "ticketCode", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TicketReassign" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/SaleItem" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -7413,8 +8284,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "502": { + "description": "The external provider failed to complete the operation.", "content": { "application/json": { "schema": { @@ -7426,14 +8297,14 @@ } } }, - "/tickets/{ticketCode}": { - "patch": { - "operationId": "patchTicketsTicketCode", + "/tickets/{ticketCode}/resend": { + "post": { + "operationId": "postTicketsTicketCodeResend", "tags": [ "tickets" ], - "summary": "Reassign a sold ticket to another date or ticket type", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nMoves an ALREADY SOLD ticket to another `ticketTypeId` and/or to the `eventDateId` date (at least one of the two is required). Intended for a postponement: moving buyers from the old date to the new one without refunding and reselling.\n\nWith only `eventDateId`, the target ticket type is resolved by NAME (the same type the ticket had, on the new date); if the target date doesn't have exactly one type with that name, it responds 422 and you must pass an explicit `ticketTypeId`.\n\nIt does NOT charge or refund the price difference if the new type costs something else: the ticket's `unitPrice`/`subtotal` keep the sale's ORIGINAL price. If money needs adjusting, use `POST /sales/{id}/refund` separately.\n\nIt does NOT reissue the QR: `ticketCode` is always preserved (it is what the buyer already has printed, in Wallet and in their email).\n\nIt does NOT notify the buyer. This endpoint only moves data; to resend the updated ticket use `POST /tickets/{ticketCode}/resend`, and for a bulk postponement notice, use the communications module.\n\nA ticket that is already checked in, or that belongs to a sale that is not CONFIRMED, responds 409 and is not reassigned. A ticket refunded by item (or whose seat was blocked after a refund) responds 409 `TICKET_REFUNDED`.\n\nNUMBERED SEATING (seats.io): if the target date has numbered seating, `seatLabel` is REQUIRED (409 `SEAT_REQUIRED` if missing) — the server never picks a seat on its own. The seat is validated and booked in seats.io before moving the ticket; if it is no longer available, it responds 409 `SEAT_UNAVAILABLE` without changing anything. If the ticket held a numbered seat on the source date, that seat is released after the move is confirmed.", + "summary": "Resend the confirmation email with the ticket", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -7461,16 +8332,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TicketReassign" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -7480,7 +8341,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/SaleItem" + "$ref": "#/components/schemas/ResendTicket" } }, "required": [ @@ -7531,7 +8392,7 @@ } }, "422": { - "description": "Operation error.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -8154,6 +9015,17 @@ "$ref": "#/components/schemas/Error" } } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } } } } @@ -8246,6 +9118,17 @@ "$ref": "#/components/schemas/Error" } } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } } } } @@ -9317,15 +10200,15 @@ } } }, - "/customer/purchase-sessions": { - "post": { - "operationId": "postCustomerPurchaseSessions", + "/customer/orders": { + "get": { + "operationId": "getCustomerOrders", "tags": [ "customer", - "purchase-sessions" + "orders" ], - "summary": "Open the purchase session (only one live per buyer)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, the event date must belong to the workspace pinned to it; otherwise 404). Opens THE buyer purchase session: there is ONLY one live per buyer across any tab or device, and the latest wins — the previous one becomes `superseded` (it can no longer create an order or start a new payment) and its seats.io hold is released, unless it backs a live sale. On seated event dates the server ISSUES the `holdToken` (mount the chart with `session: \"manual\"`) and sets `seatsDeadline`: each session gets up to 3 minutes and the budget is 3 attempts (9 CUMULATIVE minutes) per buyer and event date, summing all of their sessions within a 30-minute window, and it only runs while no order has been created. Once exhausted, it responds 429 with `error.code` `SEAT_BUDGET_EXHAUSTED`, `error.details.reason` `seat_budget_exhausted` and `error.details.retryAfterSeconds` (10-minute cooldown; also in the `Retry-After` header). If the SAME browser (`deviceKey`) reopens the SAME event date with its session alive, it gets that same session with 200 instead of 201. Only event dates on sale: published event and current event date (otherwise 404). Limits: 10 creations per minute per buyer, 30 per minute per IP when called without an API key, and a global ceiling per event date (429 `RATE_LIMITED`). Once the session is created, `POST /customer/orders` and the payment POSTs carry the `X-Purchase-Session: ` header; when the clock runs out, call `POST /customer/purchase-sessions/{id}/release`.", + "summary": "The purchase the buyer left unfinished for this event date", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, results are additionally scoped to the workspace pinned to it; without a key, any of the buyer's own unfinished purchases is visible. Returns the PENDING sale whose inventory hold is STILL ALIVE that the buyer has for that event date —with its seats, its total and when it expires—, or `order: null` if there is none. This is what lets reloading the checkout, or coming back from signing in, RESUME the purchase instead of starting from scratch: the seats remain held in that person's name. If `paymentOpened` is true the payment is already open and `POST /customer/orders/{id}/payment` returns the SAME signed configuration; to discard it and pick other seats, use `POST /customer/orders/{id}/release`.", "security": [ { "apiKey": [] @@ -9335,6 +10218,15 @@ } ], "parameters": [ + { + "name": "eventDateId", + "in": "query", + "required": false, + "description": "Required. The event date being queried.", + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -9345,26 +10237,16 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PurchaseSessionCreateRequest" - } - } - } - }, "responses": { "200": { - "description": "The SAME browser (`deviceKey`) reopened the SAME event date while its session was still alive: that session is returned (same `holdToken`, same clock) and nothing was created.", + "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/PurchaseSessionCreated" + "$ref": "#/components/schemas/CustomerOrderCurrent" } }, "required": [ @@ -9374,6 +10256,95 @@ } } }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postCustomerOrders", + "tags": [ + "customer", + "orders" + ], + "summary": "Create the ticket reservation (step 1 of the headless purchase)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the date and the ticket type must belong to the workspace pinned to it (anything else is 404); without a key, it is enough for the ticket type to exist and be on sale (same eligibility as the first-party checkout). Reserves inventory and creates the PENDING sale with the SAME rules as the first-party checkout (stock under lock, seats validated against seats.io, per-buyer limit, presale, memberships and virtual queue turn). The buyer email comes from the session, never from the body. Rejections carry a stable `reason` in `error.details.reason` (`sold_out`, `queue_turn_required`, `seats_not_held`, `members_only`, `members_only_withdrawn` — a members-only ticket whose artist withdrew the permission or left the lineup: it is no longer sold even to members —, …). With `pending_sale_in_progress` the inventory is taken by a half-paid purchase FROM THE SAME buyer: `error.details.pendingSaleId` and `pendingReference` identify it, and the right step is to reopen its payment with `POST /customer/orders/{pendingSaleId}/payment` (idempotent) instead of reserving again. If `free` is true the sale is already confirmed and `/payment` must NOT be called. Next step: `POST /customer/orders/{id}/payment`.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + }, + { + "name": "X-Purchase-Session", + "in": "header", + "required": false, + "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomerOrderCreateRequest" + } + } + } + }, + "responses": { "201": { "description": "OK", "content": { @@ -9382,7 +10353,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/PurchaseSessionCreated" + "$ref": "#/components/schemas/CustomerOrderCreateResult" } }, "required": [ @@ -9422,6 +10393,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -9440,6 +10421,17 @@ "$ref": "#/components/schemas/Error" } } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } } }, "503": { @@ -9455,15 +10447,15 @@ } } }, - "/customer/purchase-sessions/{id}": { - "get": { - "operationId": "getCustomerPurchaseSessionsId", + "/customer/orders/{id}/payment": { + "post": { + "operationId": "postCustomerOrdersIdPayment", "tags": [ "customer", - "purchase-sessions" + "orders" ], - "summary": "Purchase session status", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL. Returns the status of one of THE buyer's purchase sessions: `live` (this tab can create the order), `superseded` (another tab or device replaced it: stop offering the map and the payment), `expired` (the map clock ran out or it was released) or `converted` (it already created its order: `orderId`). A session whose `seatsDeadline` has passed is reported as `expired` immediately. Designed to be polled every ~10 s. Another buyer's session is 404.", + "summary": "Open payment for a reservation (Bold or MercadoPago, depending on the event)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). The payment rail is chosen on the SERVER: Bold-eligible events (legend plan + allowlist) return the SIGNED configuration of the embedded Bold Payment Button (`apiKey` + `renderMode: \"embedded\"` + `integritySignature`, …), which the landing page mounts with `new BoldCheckout({...})`; all others return `publicKey` + `amount` + `currency` + `reference` + `payerEmail` to mount the MercadoPago Payment Brick (`POST .../payment/card` to charge, `POST .../payment/pse` for PSE). The landing page tells the rails apart by the SHAPE of the response (`apiKey`/`renderMode` ⇒ Bold, `publicKey` ⇒ MercadoPago), never by a separate flag. The sale must belong to the session buyer (and, with a key, to the workspace pinned to it): anything else is 404. Responds 409 with code `PAYMENT_UNAVAILABLE` if the reservation expired, the sale is no longer pending, or (Bold only) the event has no legend plan or a payment attempt is already in flight with another gateway. `{id}` accepts the sale id or its `reference`. Limited to 10 opens per minute per buyer (429 with `Retry-After`).", "security": [ { "apiKey": [] @@ -9489,6 +10481,15 @@ "schema": { "type": "string" } + }, + { + "name": "X-Purchase-Session", + "in": "header", + "required": false, + "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", + "schema": { + "type": "string" + } } ], "responses": { @@ -9500,7 +10501,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/PurchaseSessionStatus" + "$ref": "#/components/schemas/CustomerOrderStartPayment" } }, "required": [ @@ -9540,6 +10541,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -9549,19 +10560,40 @@ } } } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } } } } }, - "/customer/purchase-sessions/{id}/release": { + "/customer/orders/{id}/payment/card": { "post": { - "operationId": "postCustomerPurchaseSessionsIdRelease", + "operationId": "postCustomerOrdersIdPaymentCard", "tags": [ "customer", - "purchase-sessions" + "orders" ], - "summary": "Release the seats of a purchase session", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL. Marks the session `expired` and releases in seats.io the seats held with its `holdToken`. Idempotent: repeating it changes nothing. It NEVER releases a token that backs a live sale (pending payment or confirmed) nor that of a `converted` session: those seats belong to the order. Call it when the map clock runs out. Another buyer's session is 404.", + "summary": "Charge with the MercadoPago Payment Brick token", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). Receives the token the Payment Brick produced on the landing page's domain and charges through the Orders API using the sale amount (never one sent by the client); `payer.email` travels in the body but is ignored — the payer is ALWAYS the sale's. `status` is `approved`, `pending` (normal, may require additional authentication from the bank) or `rejected` (business decline; the reason is in `message`) — all three are returned with 200. With `rejected`, `saleAlive` tells what happened to the purchase: `false` = it was cancelled and a new one must be started; `true` = this payment was declined but the purchase is still pending because another payment is in progress on it (do not start a new purchase: wait and check the order). Responds 409 with code `PAYMENT_UNAVAILABLE` if the reservation expired, the sale is no longer pending, a payment attempt is in flight with another gateway, the event only charges through Bold, or MercadoPago returned an error that cannot be classified as a decline. The sale must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. `{id}` accepts the sale id or its `reference`. Limited to 10 attempts per minute per buyer (429 with `Retry-After`).", "security": [ { "apiKey": [] @@ -9587,8 +10619,27 @@ "schema": { "type": "string" } + }, + { + "name": "X-Purchase-Session", + "in": "header", + "required": false, + "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeRequest" + } + } } - ], + }, "responses": { "200": { "description": "OK", @@ -9598,7 +10649,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/PurchaseSessionStatus" + "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeResult" } }, "required": [ @@ -9638,8 +10689,18 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { - "description": "Request body/parameter validation failed.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -9656,19 +10717,31 @@ "$ref": "#/components/schemas/Error" } } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } } } } } }, - "/content/videos": { - "get": { - "operationId": "getContentVideos", + "/customer/orders/{id}/payment/pse": { + "post": { + "operationId": "postCustomerOrdersIdPaymentPse", "tags": [ - "content" + "customer", + "orders" ], - "summary": "List the organization's published videos", - "description": "Only published videos that have finished processing (READY) in the active workspace. Does not include the playback id: to play one, request a token from `POST /content/playback-token`.", + "summary": "Open a PSE payment through MercadoPago (redirect)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). Creates a MercadoPago preference restricted to PSE and returns `redirectUrl` (`init_point`): the landing page must REDIRECT the browser there, not mount it in an iframe. The buyer picks their bank and confirms the transfer inside MercadoPago; on return, they land on `GET /api/mp/return` (our domain), which issues a 302 to the `returnUrl` sent in `POST /customer/orders` — the landing page must call `GET /customer/orders/{id}` for the authoritative status, never infer it from the return URL. The sale is confirmed by webhook when the bank settles the payment (asynchronous: it may take a while). Responds 409 with code `PAYMENT_UNAVAILABLE` if the reservation expired, the sale is no longer pending, a payment attempt is in flight with another gateway, or the event only charges through Bold. The sale must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. `{id}` accepts the sale id or its `reference`. Limited to 10 opens per minute per buyer (429 with `Retry-After`).", "security": [ { "apiKey": [] @@ -9679,28 +10752,27 @@ ], "parameters": [ { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", + "name": "id", + "in": "path", + "required": true, "schema": { - "type": "integer", - "default": 20 + "type": "string" } }, { - "name": "cursor", - "in": "query", + "name": "X-Workspace-Id", + "in": "header", "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", "schema": { "type": "string" } }, { - "name": "X-Workspace-Id", + "name": "X-Purchase-Session", "in": "header", "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", "schema": { "type": "string" } @@ -9715,18 +10787,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentVideo" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/CustomerOrderMercadoPagoPse" } }, "required": [ - "data", - "page" + "data" ] } } @@ -9762,6 +10827,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -9771,18 +10846,40 @@ } } } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } } } } }, - "/content/posts": { - "get": { - "operationId": "getContentPosts", + "/customer/orders/{id}/release": { + "post": { + "operationId": "postCustomerOrdersIdRelease", "tags": [ - "content" + "customer", + "orders" ], - "summary": "List the organization's community feed", - "description": "Posts from the active workspace, newest first, excluding deleted posts and posts scheduled for the future. A post with `locked: true` arrives redacted (`content`, `imageUrl`, `videoId`, `eventId` and `link` set to null, `commentsCount` set to 0): it is members-only content and the key does not represent a buyer with a current membership. Does not include `likes_count` (only visible to the workspace owner) or the post's internal author.", + "summary": "Release a reservation the buyer will not pay for", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). Abandons the PENDING sale and returns its inventory (and its seats) to stock, so the buyer can start over without waiting for the reservation to expire. It is the counterpart of `pending_sale_in_progress`: when `POST /customer/orders` rejects with that `reason`, the landing page can offer *continue paying* (`/payment`, idempotent) or *start over* (this route). It ONLY releases with evidence that nobody started the payment: if Bold reports any transaction, if a provider response is already stored, or if the payment goes through a rail we cannot query, it responds 409 with `details.reason` = `payment_in_flight` and the sale is left intact. If the gateway does not respond, 503 (`gateway_unreachable`): retry later. The sale must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. `{id}` accepts the sale id or its `reference`. Limited to 10 calls per minute per buyer.", "security": [ { "apiKey": [] @@ -9793,19 +10890,9 @@ ], "parameters": [ { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "name": "cursor", - "in": "query", - "required": false, + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -9829,18 +10916,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentPost" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/CustomerOrderRelease" } }, "required": [ - "data", - "page" + "data" ] } } @@ -9876,6 +10956,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -9885,16 +10975,50 @@ } } } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } - }, - "post": { - "operationId": "postContentPosts", + } + }, + "/customer/orders/{id}": { + "get": { + "operationId": "getCustomerOrdersId", "tags": [ - "content" + "customer", + "orders" ], - "summary": "Publish community content (including articles)", - "description": "Creates a community post. `type=ARTICLE` requires `title` and `body` (Markdown) and builds a slug unique per organization (manual via `slug`, or derived from `title` if omitted); `type=TEXT`/`IMAGE` require `content` or `imageUrl`, same as the dashboard composer. Unlike the dashboard, this path does NOT resolve the link's Open Graph snapshot (`link` is always null in the response). Minimum role ADMIN, like every other `POST` in `/api/v1`. If the workspace has the `community_v2` flag enabled, publishing enqueues a notification to members in the same transaction; with a future `publishedAt`, the notification goes out when the post is published. The response does not change.", + "summary": "Status of a headless purchase (and its tickets, once paid)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). `{id}` accepts the `reference` (FT-…) or the sale id. If the sale is still PENDING and its payment goes through Bold, the authoritative payment status is re-read from Bold; between re-reads it responds with the internal status, which the webhook keeps up to date. `status` is `approved`, `pending` or `rejected`; `pending` is a NORMAL state (asynchronous payment methods take time) and the landing page must retry. `tickets` —with each ticket's `ticketCode`— is only present when `status` is `approved`. The purchase must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. The route MAY rate-limit polling and respond 429: honor `Retry-After` and apply backoff. Polling every ~2 s fits comfortably, but do not treat any threshold as a guarantee.", "security": [ { "apiKey": [] @@ -9904,6 +11028,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -9914,18 +11046,8 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentPostCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -9933,7 +11055,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ContentPost" + "$ref": "#/components/schemas/CustomerOrderStatus" } }, "required": [ @@ -9943,16 +11065,6 @@ } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -9983,8 +11095,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -9993,27 +11105,39 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "429": { + "description": "Too many requests: rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } } } } } }, - "/content/lives": { - "get": { - "operationId": "getContentLives", + "/customer/purchase-sessions": { + "post": { + "operationId": "postCustomerPurchaseSessions", "tags": [ - "content" + "customer", + "purchase-sessions" ], - "summary": "List the organization's live streams", - "description": "Live streams from the active workspace, newest first. `status: ACTIVE` is the one on air. Does not include the RTMP key or the playback ids.", + "summary": "Open the purchase session (only one live per buyer)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, the event date must belong to the workspace pinned to it; otherwise 404). Opens THE buyer purchase session: there is ONLY one live per buyer across any tab or device, and the latest wins — the previous one becomes `superseded` (it can no longer create an order or start a new payment) and its seats.io hold is released, unless it backs a live sale. On seated event dates the server ISSUES the `holdToken` (mount the chart with `session: \"manual\"`) and sets `seatsDeadline`: each session gets up to 3 minutes and the budget is 3 attempts (9 CUMULATIVE minutes) per buyer and event date, summing all of their sessions within a 30-minute window, and it only runs while no order has been created. Once exhausted, it responds 429 with `error.code` `SEAT_BUDGET_EXHAUSTED`, `error.details.reason` `seat_budget_exhausted` and `error.details.retryAfterSeconds` (10-minute cooldown; also in the `Retry-After` header). If the SAME browser (`deviceKey`) reopens the SAME event date with its session alive, it gets that same session with 200 instead of 201. Only event dates on sale: published event and current event date (otherwise 404). Limits: 10 creations per minute per buyer, 30 per minute per IP when called without an API key, and a global ceiling per event date (429 `RATE_LIMITED`). Once the session is created, `POST /customer/orders` and the payment POSTs carry the `X-Purchase-Session: ` header; when the clock runs out, call `POST /customer/purchase-sessions/{id}/release`.", "security": [ { "apiKey": [] @@ -10023,24 +11147,6 @@ } ], "parameters": [ - { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "name": "cursor", - "in": "query", - "required": false, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -10050,9 +11156,37 @@ "type": "string" } } - ], + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PurchaseSessionCreateRequest" + } + } + } + }, "responses": { "200": { + "description": "The SAME browser (`deviceKey`) reopened the SAME event date while its session was still alive: that session is returned (same `holdToken`, same clock) and nothing was created.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PurchaseSessionCreated" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "201": { "description": "OK", "content": { "application/json": { @@ -10060,18 +11194,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentLive" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/PurchaseSessionCreated" } }, "required": [ - "data", - "page" + "data" ] } } @@ -10116,18 +11243,50 @@ } } } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } } }, - "/content/lives/{id}": { + "/customer/purchase-sessions/{id}": { "get": { - "operationId": "getContentLivesId", + "operationId": "getCustomerPurchaseSessionsId", "tags": [ - "content" + "customer", + "purchase-sessions" ], - "summary": "Live stream status", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Purchase session status", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL. Returns the status of one of THE buyer's purchase sessions: `live` (this tab can create the order), `superseded` (another tab or device replaced it: stop offering the map and the payment), `expired` (the map clock ran out or it was released) or `converted` (it already created its order: `orderId`). A session whose `seatsDeadline` has passed is reported as `expired` immediately. Designed to be polled every ~10 s. Another buyer's session is 404.", "security": [ { "apiKey": [] @@ -10164,7 +11323,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ContentLive" + "$ref": "#/components/schemas/PurchaseSessionStatus" } }, "required": [ @@ -10217,14 +11376,15 @@ } } }, - "/content/playback-token": { + "/customer/purchase-sessions/{id}/release": { "post": { - "operationId": "postContentPlaybackToken", + "operationId": "postCustomerPurchaseSessionsIdRelease", "tags": [ - "content" + "customer", + "purchase-sessions" ], - "summary": "Signed token to play a video or a live stream", - "description": "Requires an enterprise service API key. `memberOnly` content additionally requires the `X-Customer-Session` header of a buyer with a current membership in the key's organization (otherwise 403 `MEMBERSHIP_REQUIRED`). Content from another organization responds 404. Short-lived tokens: 30 minutes for live streams, 1 hour for videos.", + "summary": "Release the seats of a purchase session", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL. Marks the session `expired` and releases in seats.io the seats held with its `holdToken`. Idempotent: repeating it changes nothing. It NEVER releases a token that backs a live sale (pending payment or confirmed) nor that of a `converted` session: those seats belong to the order. Call it when the map clock runs out. Another buyer's session is 404.", "security": [ { "apiKey": [] @@ -10234,6 +11394,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -10244,16 +11412,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentPlaybackTokenRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -10263,7 +11421,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ContentPlaybackToken" + "$ref": "#/components/schemas/PurchaseSessionStatus" } }, "required": [ @@ -10313,27 +11471,38 @@ } } }, - "503": { - "description": "Service unavailable: an external dependency is down or initialization failed.", + "429": { + "description": "Too many requests: rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } } } } } }, - "/tickets/{ticketCode}/resend": { - "post": { - "operationId": "postTicketsTicketCodeResend", + "/content/videos": { + "get": { + "operationId": "getContentVideos", "tags": [ - "tickets" + "content" ], - "summary": "Resend the confirmation email with the ticket", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List the organization's published videos", + "description": "Only published videos that have finished processing (READY) in the active workspace. Does not include the playback id: to play one, request a token from `POST /content/playback-token`.", "security": [ { "apiKey": [] @@ -10344,9 +11513,19 @@ ], "parameters": [ { - "name": "ticketCode", - "in": "path", - "required": true, + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, "schema": { "type": "string" } @@ -10370,11 +11549,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ResendTicket" + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentVideo" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -10410,16 +11596,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -10433,15 +11609,14 @@ } } }, - "/customer/orders": { + "/content/posts": { "get": { - "operationId": "getCustomerOrders", + "operationId": "getContentPosts", "tags": [ - "customer", - "orders" + "content" ], - "summary": "The purchase the buyer left unfinished for this event date", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, results are additionally scoped to the workspace pinned to it; without a key, any of the buyer's own unfinished purchases is visible. Returns the PENDING sale whose inventory hold is STILL ALIVE that the buyer has for that event date —with its seats, its total and when it expires—, or `order: null` if there is none. This is what lets reloading the checkout, or coming back from signing in, RESUME the purchase instead of starting from scratch: the seats remain held in that person's name. If `paymentOpened` is true the payment is already open and `POST /customer/orders/{id}/payment` returns the SAME signed configuration; to discard it and pick other seats, use `POST /customer/orders/{id}/release`.", + "summary": "List the organization's community feed", + "description": "Posts from the active workspace, newest first, excluding deleted posts and posts scheduled for the future. A post with `locked: true` arrives redacted (`content`, `imageUrl`, `videoId`, `eventId` and `link` set to null, `commentsCount` set to 0): it is members-only content and the key does not represent a buyer with a current membership. Does not include `likes_count` (only visible to the workspace owner) or the post's internal author.", "security": [ { "apiKey": [] @@ -10452,10 +11627,19 @@ ], "parameters": [ { - "name": "eventDateId", + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", "in": "query", "required": false, - "description": "Required. The event date being queried.", "schema": { "type": "string" } @@ -10479,11 +11663,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderCurrent" + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentPost" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -10520,7 +11711,7 @@ } }, "422": { - "description": "Operation error.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -10532,13 +11723,12 @@ } }, "post": { - "operationId": "postCustomerOrders", + "operationId": "postContentPosts", "tags": [ - "customer", - "orders" + "content" ], - "summary": "Create the ticket reservation (step 1 of the headless purchase)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the date and the ticket type must belong to the workspace pinned to it (anything else is 404); without a key, it is enough for the ticket type to exist and be on sale (same eligibility as the first-party checkout). Reserves inventory and creates the PENDING sale with the SAME rules as the first-party checkout (stock under lock, seats validated against seats.io, per-buyer limit, presale, memberships and virtual queue turn). The buyer email comes from the session, never from the body. Rejections carry a stable `reason` in `error.details.reason` (`sold_out`, `queue_turn_required`, `seats_not_held`, `members_only`, `members_only_withdrawn` — a members-only ticket whose artist withdrew the permission or left the lineup: it is no longer sold even to members —, …). With `pending_sale_in_progress` the inventory is taken by a half-paid purchase FROM THE SAME buyer: `error.details.pendingSaleId` and `pendingReference` identify it, and the right step is to reopen its payment with `POST /customer/orders/{pendingSaleId}/payment` (idempotent) instead of reserving again. If `free` is true the sale is already confirmed and `/payment` must NOT be called. Next step: `POST /customer/orders/{id}/payment`.", + "summary": "Publish community content (including articles)", + "description": "Creates a community post. `type=ARTICLE` requires `title` and `body` (Markdown) and builds a slug unique per organization (manual via `slug`, or derived from `title` if omitted); `type=TEXT`/`IMAGE` require `content` or `imageUrl`, same as the dashboard composer. Unlike the dashboard, this path does NOT resolve the link's Open Graph snapshot (`link` is always null in the response). Minimum role ADMIN, like every other `POST` in `/api/v1`. If the workspace has the `community_v2` flag enabled, publishing enqueues a notification to members in the same transaction; with a future `publishedAt`, the notification goes out when the post is published. The response does not change.", "security": [ { "apiKey": [] @@ -10556,15 +11746,6 @@ "schema": { "type": "string" } - }, - { - "name": "X-Purchase-Session", - "in": "header", - "required": false, - "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", - "schema": { - "type": "string" - } } ], "requestBody": { @@ -10572,7 +11753,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CustomerOrderCreateRequest" + "$ref": "#/components/schemas/ContentPostCreate" } } } @@ -10586,7 +11767,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderCreateResult" + "$ref": "#/components/schemas/ContentPost" } }, "required": [ @@ -10596,6 +11777,16 @@ } } }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "401": { "description": "Missing or invalid credential.", "content": { @@ -10645,39 +11836,18 @@ } } } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "503": { - "description": "Service unavailable: an external dependency is down or initialization failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } } } } }, - "/customer/orders/{id}/payment": { - "post": { - "operationId": "postCustomerOrdersIdPayment", + "/content/lives": { + "get": { + "operationId": "getContentLives", "tags": [ - "customer", - "orders" + "content" ], - "summary": "Open payment for a reservation (Bold or MercadoPago, depending on the event)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). The payment rail is chosen on the SERVER: Bold-eligible events (legend plan + allowlist) return the SIGNED configuration of the embedded Bold Payment Button (`apiKey` + `renderMode: \"embedded\"` + `integritySignature`, …), which the landing page mounts with `new BoldCheckout({...})`; all others return `publicKey` + `amount` + `currency` + `reference` + `payerEmail` to mount the MercadoPago Payment Brick (`POST .../payment/card` to charge, `POST .../payment/pse` for PSE). The landing page tells the rails apart by the SHAPE of the response (`apiKey`/`renderMode` ⇒ Bold, `publicKey` ⇒ MercadoPago), never by a separate flag. The sale must belong to the session buyer (and, with a key, to the workspace pinned to it): anything else is 404. Responds 409 with code `PAYMENT_UNAVAILABLE` if the reservation expired, the sale is no longer pending, or (Bold only) the event has no legend plan or a payment attempt is already in flight with another gateway. `{id}` accepts the sale id or its `reference`. Limited to 10 opens per minute per buyer (429 with `Retry-After`).", + "summary": "List the organization's live streams", + "description": "Live streams from the active workspace, newest first. `status: ACTIVE` is the one on air. Does not include the RTMP key or the playback ids.", "security": [ { "apiKey": [] @@ -10688,27 +11858,28 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", "schema": { - "type": "string" + "type": "integer", + "default": 20 } }, { - "name": "X-Workspace-Id", - "in": "header", + "name": "cursor", + "in": "query", "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", "schema": { "type": "string" } }, { - "name": "X-Purchase-Session", + "name": "X-Workspace-Id", "in": "header", "required": false, - "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", "schema": { "type": "string" } @@ -10723,11 +11894,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderStartPayment" + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentLive" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -10763,16 +11941,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -10782,29 +11950,18 @@ } } } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } } } } }, - "/customer/orders/{id}/payment/card": { - "post": { - "operationId": "postCustomerOrdersIdPaymentCard", + "/content/lives/{id}": { + "get": { + "operationId": "getContentLivesId", "tags": [ - "customer", - "orders" + "content" ], - "summary": "Charge with the MercadoPago Payment Brick token", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). Receives the token the Payment Brick produced on the landing page's domain and charges through the Orders API using the sale amount (never one sent by the client); `payer.email` travels in the body but is ignored — the payer is ALWAYS the sale's. `status` is `approved`, `pending` (normal, may require additional authentication from the bank) or `rejected` (business decline; the reason is in `message`) — all three are returned with 200. With `rejected`, `saleAlive` tells what happened to the purchase: `false` = it was cancelled and a new one must be started; `true` = this payment was declined but the purchase is still pending because another payment is in progress on it (do not start a new purchase: wait and check the order). Responds 409 with code `PAYMENT_UNAVAILABLE` if the reservation expired, the sale is no longer pending, a payment attempt is in flight with another gateway, the event only charges through Bold, or MercadoPago returned an error that cannot be classified as a decline. The sale must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. `{id}` accepts the sale id or its `reference`. Limited to 10 attempts per minute per buyer (429 with `Retry-After`).", + "summary": "Live stream status", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -10830,27 +11987,8 @@ "schema": { "type": "string" } - }, - { - "name": "X-Purchase-Session", - "in": "header", - "required": false, - "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", - "schema": { - "type": "string" - } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -10860,7 +11998,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeResult" + "$ref": "#/components/schemas/ContentLive" } }, "required": [ @@ -10900,28 +12038,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { - "description": "Operation error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -10933,15 +12051,14 @@ } } }, - "/customer/orders/{id}/payment/pse": { + "/content/playback-token": { "post": { - "operationId": "postCustomerOrdersIdPaymentPse", + "operationId": "postContentPlaybackToken", "tags": [ - "customer", - "orders" + "content" ], - "summary": "Open a PSE payment through MercadoPago (redirect)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). Creates a MercadoPago preference restricted to PSE and returns `redirectUrl` (`init_point`): the landing page must REDIRECT the browser there, not mount it in an iframe. The buyer picks their bank and confirms the transfer inside MercadoPago; on return, they land on `GET /api/mp/return` (our domain), which issues a 302 to the `returnUrl` sent in `POST /customer/orders` — the landing page must call `GET /customer/orders/{id}` for the authoritative status, never infer it from the return URL. The sale is confirmed by webhook when the bank settles the payment (asynchronous: it may take a while). Responds 409 with code `PAYMENT_UNAVAILABLE` if the reservation expired, the sale is no longer pending, a payment attempt is in flight with another gateway, or the event only charges through Bold. The sale must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. `{id}` accepts the sale id or its `reference`. Limited to 10 opens per minute per buyer (429 with `Retry-After`).", + "summary": "Signed token to play a video or a live stream", + "description": "Requires an enterprise service API key. `memberOnly` content additionally requires the `X-Customer-Session` header of a buyer with a current membership in the key's organization or, for a live stream tied to a show date, a CONFIRMED ticket for that date (otherwise 403 `MEMBERSHIP_REQUIRED`). Rate limited: 600 requests/min per key and 30/min per buyer (429 `RATE_LIMITED` with `Retry-After`). Content from another organization responds 404. Short-lived tokens: 30 minutes for live streams, 1 hour for videos.", "security": [ { "apiKey": [] @@ -10951,14 +12068,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -10967,17 +12076,18 @@ "schema": { "type": "string" } - }, - { - "name": "X-Purchase-Session", - "in": "header", - "required": false, - "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", - "schema": { - "type": "string" - } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentPlaybackTokenRequest" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -10987,7 +12097,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoPse" + "$ref": "#/components/schemas/ContentPlaybackToken" } }, "required": [ @@ -11027,8 +12137,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -11037,18 +12147,29 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "429": { + "description": "Too many requests: rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } } }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", "content": { "application/json": { "schema": { @@ -11060,15 +12181,14 @@ } } }, - "/customer/orders/{id}/release": { + "/waitlist": { "post": { - "operationId": "postCustomerOrdersIdRelease", + "operationId": "postWaitlist", "tags": [ - "customer", - "orders" + "waitlist" ], - "summary": "Release a reservation the buyer will not pay for", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). Abandons the PENDING sale and returns its inventory (and its seats) to stock, so the buyer can start over without waiting for the reservation to expire. It is the counterpart of `pending_sale_in_progress`: when `POST /customer/orders` rejects with that `reason`, the landing page can offer *continue paying* (`/payment`, idempotent) or *start over* (this route). It ONLY releases with evidence that nobody started the payment: if Bold reports any transaction, if a provider response is already stored, or if the payment goes through a rail we cannot query, it responds 409 with `details.reason` = `payment_in_flight` and the sale is left intact. If the gateway does not respond, 503 (`gateway_unreachable`): retry later. The sale must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. `{id}` accepts the sale id or its `reference`. Limited to 10 calls per minute per buyer.", + "summary": "Join the per-city waitlist of an enterprise landing", + "description": "Requires an enterprise service API key; the entry belongs to the key's organization. `X-Customer-Session` is optional: when present the entry is linked to that buyer. `contact` must be an email or a phone number (7-15 digits; only a leading `+`, spaces and dashes besides digits — parentheses, dots, letters or extensions respond 422). Phones are stored without spaces or dashes. Idempotent per (organization, city folded without accents/case, contact normalized — lowercased email, or the last 10 phone digits so `+57 300…` and `300…` are the same contact): 201 with `created: true` on the first call, 200 with `created: false` afterwards. Rate limited: 120 requests/min per key and 10/min per contact (429 `RATE_LIMITED` with `Retry-After`). Invalid JSON responds 400; an invalid body 422.", "security": [ { "apiKey": [] @@ -11079,33 +12199,44 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", "schema": { "type": "string" } }, { - "name": "X-Workspace-Id", + "name": "X-Customer-Session", "in": "header", "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "description": "Optional buyer session token; links the entry to that buyer.", "schema": { "type": "string" } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WaitlistEntryCreate" + } + } + } + }, "responses": { "200": { - "description": "OK", + "description": "Already on this city's waitlist (`created: false`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderRelease" + "$ref": "#/components/schemas/WaitlistEntryResult" } }, "required": [ @@ -11115,18 +12246,26 @@ } } }, - "401": { - "description": "Missing or invalid credential.", + "201": { + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WaitlistEntryResult" + } + }, + "required": [ + "data" + ] } } } }, - "403": { - "description": "Insufficient role or resource not accessible.", + "400": { + "description": "Bad request: malformed parameters.", "content": { "application/json": { "schema": { @@ -11135,8 +12274,8 @@ } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -11145,8 +12284,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { @@ -11155,8 +12294,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -11165,8 +12304,8 @@ } } }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -11175,41 +12314,68 @@ } } }, - "503": { - "description": "Service unavailable: an external dependency is down or initialization failed.", + "429": { + "description": "Too many requests: rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } } } } - } - }, - "/customer/orders/{id}": { + }, "get": { - "operationId": "getCustomerOrdersId", + "operationId": "getWaitlist", "tags": [ - "customer", - "orders" + "waitlist" ], - "summary": "Status of a headless purchase (and its tickets, once paid)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). `{id}` accepts the `reference` (FT-…) or the sale id. If the sale is still PENDING and its payment goes through Bold, the authoritative payment status is re-read from Bold; between re-reads it responds with the internal status, which the webhook keeps up to date. `status` is `approved`, `pending` or `rejected`; `pending` is a NORMAL state (asynchronous payment methods take time) and the landing page must retry. `tickets` —with each ticket's `ticketCode`— is only present when `status` is `approved`. The purchase must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. The route MAY rate-limit polling and respond 429: honor `Retry-After` and apply backoff. Polling every ~2 s fits comfortably, but do not treat any threshold as a guarantee.", + "summary": "List the waitlist entries of the workspace", + "description": "Export for staff (CLI/MCP). Contains personal data, so it requires ADMIN. Newest first, cursor pagination; `city` filters by the folded city (accents and case ignored).", "security": [ { "apiKey": [] }, { - "apiKeyHeader": [] - } - ], - "parameters": [ + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "city", + "in": "query", + "required": false, + "description": "City name; accents and case are ignored", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, { - "name": "id", - "in": "path", - "required": true, + "name": "cursor", + "in": "query", + "required": false, "schema": { "type": "string" } @@ -11233,11 +12399,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderStatus" + "type": "array", + "items": { + "$ref": "#/components/schemas/WaitlistEntry" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -11282,16 +12455,6 @@ } } } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } } } } @@ -11357,6 +12520,12 @@ }, "suggestedWorkspaceName": { "type": "string" + }, + "ids": { + "type": "array", + "items": { + "type": "string" + } } }, "required": [ @@ -14220,6 +15389,140 @@ ], "additionalProperties": false }, + "EventArtistsReplace": { + "type": "object", + "properties": { + "artistIds": { + "maxItems": 50, + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 64 + } + }, + "inviteEmails": { + "maxItems": 20, + "type": "array", + "items": { + "type": "string", + "format": "email", + "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + } + } + }, + "required": [ + "artistIds" + ], + "additionalProperties": false + }, + "ArtistSummary": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "slug": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "logoUrl": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "id", + "name", + "slug", + "logoUrl" + ], + "additionalProperties": false + }, + "ArtistInvitation": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "email": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "PENDING", + "EXPIRED" + ] + }, + "expiresAt": { + "type": "string" + }, + "createdAt": { + "type": "string" + } + }, + "required": [ + "id", + "email", + "status", + "expiresAt", + "createdAt" + ], + "additionalProperties": false + }, + "EventArtistUnlink": { + "type": "object", + "properties": { + "eventId": { + "type": "string" + }, + "organizationId": { + "type": "string" + }, + "unlinked": { + "type": "boolean" + } + }, + "required": [ + "eventId", + "organizationId", + "unlinked" + ], + "additionalProperties": false + }, + "ArtistInvitationDeleted": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "deleted": { + "type": "boolean", + "const": true + } + }, + "required": [ + "id", + "deleted" + ], + "additionalProperties": false + }, "SaleCreate": { "type": "object", "properties": { @@ -14872,6 +16175,16 @@ "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 + }, + "amount": { + "type": "number" + }, + "mode": { + "type": "string", + "enum": [ + "PERCENT", + "AMOUNT" + ] } }, "required": [ @@ -15583,6 +16896,26 @@ }, "additionalProperties": false }, + "ResendTicket": { + "type": "object", + "properties": { + "ticketCode": { + "type": "string" + }, + "sentTo": { + "type": "string" + }, + "sentAt": { + "type": "string" + } + }, + "required": [ + "ticketCode", + "sentTo", + "sentAt" + ], + "additionalProperties": false + }, "CheckinResult": { "type": "object", "properties": { @@ -16894,57 +18227,166 @@ } }, "required": [ - "redirectUrl" + "redirectUrl" + ], + "additionalProperties": false + }, + "CustomerOrderStatus": { + "type": "object", + "properties": { + "reference": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "approved", + "pending", + "rejected" + ], + "description": "`pending` is a NORMAL state: Bold may take a while to reflect the payment (PSE, Nequi and the Bancolombia button approve asynchronously) and the webhook settles it. The landing page must retry, not treat the purchase as lost." + }, + "saleStatus": { + "type": "string", + "description": "Internal sale status (PENDING, CONFIRMED, …)." + }, + "total": { + "type": "number" + }, + "currency": { + "type": "string" + }, + "tickets": { + "anyOf": [ + { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomerTicketItem" + } + }, + { + "type": "null" + } + ], + "description": "Tickets with their `ticketCode`. ONLY present when `status` is `approved`; null in any other case. A code handed out before the payment settles would be a valid ticket with no money behind it." + } + }, + "required": [ + "reference", + "status", + "saleStatus", + "total", + "currency", + "tickets" + ], + "additionalProperties": false + }, + "CustomerOrderItem": { + "type": "object", + "properties": { + "ticketTypeId": { + "type": "string", + "minLength": 1 + }, + "quantity": { + "type": "integer", + "minimum": 1, + "maximum": 30 + }, + "seats": { + "description": "seats.io labels. Only for seated events.", + "maxItems": 30, + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 120 + } + } + }, + "required": [ + "ticketTypeId", + "quantity" ], "additionalProperties": false }, - "CustomerOrderStatus": { + "CustomerOrderCreateRequest": { "type": "object", "properties": { - "reference": { - "type": "string" - }, - "status": { + "eventDateId": { "type": "string", - "enum": [ - "approved", - "pending", - "rejected" - ], - "description": "`pending` is a NORMAL state: Bold may take a while to reflect the payment (PSE, Nequi and the Bancolombia button approve asynchronously) and the webhook settles it. The landing page must retry, not treat the purchase as lost." + "minLength": 1 }, - "saleStatus": { - "type": "string", - "description": "Internal sale status (PENDING, CONFIRMED, …)." + "items": { + "minItems": 1, + "maxItems": 1, + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomerOrderItem" + } }, - "total": { - "type": "number" + "holdToken": { + "description": "Hold token of the seats.io map session. Required if seats are sent.", + "type": "string", + "maxLength": 120 }, - "currency": { - "type": "string" + "discountCode": { + "type": "string", + "maxLength": 40 }, - "tickets": { - "anyOf": [ - { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomerTicketItem" - } + "buyer": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 2, + "maxLength": 120 }, - { - "type": "null" + "phone": { + "type": "string", + "maxLength": 40 + }, + "idType": { + "type": "string", + "enum": [ + "CC", + "CE", + "NIT", + "PP", + "TI", + "PEP" + ] + }, + "idNumber": { + "type": "string", + "minLength": 5, + "maxLength": 20 + }, + "nitDigit": { + "description": "Check digit. Required if idType is NIT.", + "type": "string", + "maxLength": 1 } + }, + "required": [ + "name", + "phone", + "idType", + "idNumber" ], - "description": "Tickets with their `ticketCode`. ONLY present when `status` is `approved`; null in any other case. A code handed out before the payment settles would be a valid ticket with no money behind it." + "additionalProperties": false + }, + "returnUrl": { + "type": "string", + "maxLength": 2048, + "description": "Absolute URL of the landing page the buyer returns to. Validated against the enterprise domain allowlist and the workspace that owns the event; if it fails validation it is ignored and the purchase proceeds as usual." } }, "required": [ - "reference", - "status", - "saleStatus", - "total", - "currency", - "tickets" + "eventDateId", + "items", + "buyer", + "returnUrl" ], "additionalProperties": false }, @@ -17448,136 +18890,128 @@ ], "additionalProperties": false }, - "ResendTicket": { + "WaitlistEntryCreate": { "type": "object", "properties": { - "ticketCode": { - "type": "string" + "city": { + "type": "string", + "minLength": 1, + "maxLength": 60 }, - "sentTo": { - "type": "string" + "name": { + "type": "string", + "minLength": 1, + "maxLength": 80 }, - "sentAt": { - "type": "string" + "contact": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "source": { + "type": "string", + "maxLength": 40 } }, "required": [ - "ticketCode", - "sentTo", - "sentAt" + "city", + "name", + "contact" ], "additionalProperties": false }, - "CustomerOrderItem": { + "WaitlistEntryResult": { "type": "object", "properties": { - "ticketTypeId": { - "type": "string", - "minLength": 1 + "id": { + "type": "string" }, - "quantity": { - "type": "integer", - "minimum": 1, - "maximum": 30 + "city": { + "type": "string" }, - "seats": { - "description": "seats.io labels. Only for seated events.", - "maxItems": 30, - "type": "array", - "items": { - "type": "string", - "minLength": 1, - "maxLength": 120 - } + "created": { + "type": "boolean" } }, "required": [ - "ticketTypeId", - "quantity" + "id", + "city", + "created" ], "additionalProperties": false }, - "CustomerOrderCreateRequest": { + "WaitlistEntry": { "type": "object", "properties": { - "eventDateId": { - "type": "string", - "minLength": 1 + "id": { + "type": "string" }, - "items": { - "minItems": 1, - "maxItems": 1, - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomerOrderItem" - } + "city": { + "type": "string" }, - "holdToken": { - "description": "Hold token of the seats.io map session. Required if seats are sent.", - "type": "string", - "maxLength": 120 + "name": { + "type": "string" }, - "discountCode": { - "type": "string", - "maxLength": 40 + "contact": { + "type": "string" }, - "buyer": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 2, - "maxLength": 120 - }, - "phone": { - "type": "string", - "maxLength": 40 - }, - "idType": { - "type": "string", - "enum": [ - "CC", - "CE", - "NIT", - "PP", - "TI", - "PEP" - ] + "customerId": { + "anyOf": [ + { + "type": "string" }, - "idNumber": { - "type": "string", - "minLength": 5, - "maxLength": 20 + { + "type": "null" + } + ] + }, + "source": { + "anyOf": [ + { + "type": "string" }, - "nitDigit": { - "description": "Check digit. Required if idType is NIT.", - "type": "string", - "maxLength": 1 + { + "type": "null" } - }, - "required": [ - "name", - "phone", - "idType", - "idNumber" - ], - "additionalProperties": false + ] }, - "returnUrl": { - "type": "string", - "maxLength": 2048, - "description": "Absolute URL of the landing page the buyer returns to. Validated against the enterprise domain allowlist and the workspace that owns the event; if it fails validation it is ignored and the purchase proceeds as usual." + "createdAt": { + "type": "string" } }, "required": [ - "eventDateId", - "items", - "buyer", - "returnUrl" + "id", + "city", + "name", + "contact", + "customerId", + "source", + "createdAt" ], "additionalProperties": false } }, + "headers": { + "RateLimitPolicy": { + "description": "Quota policies applied to this request (draft-ietf-httpapi-ratelimit-headers), one list member per limiter: `\"\";q=;w=`. Example: `\"public-orders\";q=8;w=300`.", + "schema": { + "type": "string" + } + }, + "RateLimit": { + "description": "Remaining quota per policy (draft-ietf-httpapi-ratelimit-headers): `\"\";r=;t=`. Example: `\"public-orders\";r=7;t=280`.", + "schema": { + "type": "string" + } + }, + "RetryAfter": { + "description": "Seconds to wait before retrying (RFC 9110 §10.2.3). Always sent with a 429.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, "securitySchemes": { "apiKey": { "type": "apiKey", diff --git a/src/commands/lineup.test.ts b/src/commands/lineup.test.ts new file mode 100644 index 0000000..754eb7d --- /dev/null +++ b/src/commands/lineup.test.ts @@ -0,0 +1,153 @@ +import { Command } from "commander"; +import { + afterEach, + beforeEach, + describe, + expect, + it, + type MockInstance, + vi, +} from "vitest"; + +const sdk = vi.hoisted(() => ({ + getEventsId: vi.fn(), + putEventsIdArtists: vi.fn(), + getArtists: vi.fn(), +})); + +vi.mock("../client/sdk.gen", async (importOriginal) => ({ + ...(await importOriginal()), + ...sdk, +})); + +vi.mock("../lib/api", async (importOriginal) => ({ + ...(await importOriginal()), + configureClient: vi.fn(), +})); + +const { registerArtists, registerEventLineup } = await import("./lineup"); + +const ok = (data: unknown, extra: Record = {}) => ({ + data: { data, ...extra }, + response: new Response(), +}); + +function build(): Command { + const program = new Command().exitOverride(); + registerEventLineup(program.command("events")); + registerArtists(program); + return program; +} + +const run = (...args: string[]) => build().parseAsync(["node", "ft", ...args]); + +describe("ft events artists set", () => { + const tty = process.stdin.isTTY; + let stderr: MockInstance; + + beforeEach(() => { + Object.defineProperty(process.stdin, "isTTY", { + value: false, + configurable: true, + }); + stderr = vi.spyOn(console, "error").mockImplementation(() => {}); + vi.spyOn(console, "log").mockImplementation(() => {}); + vi.spyOn(process.stdout, "write").mockImplementation(() => true); + vi.spyOn(process, "exit").mockImplementation((() => { + throw new Error("exited"); + }) as never); + sdk.putEventsIdArtists.mockResolvedValue(ok({ artists: [] })); + }); + + afterEach(() => { + Object.defineProperty(process.stdin, "isTTY", { + value: tty, + configurable: true, + }); + vi.restoreAllMocks(); + for (const fn of Object.values(sdk)) fn.mockReset(); + }); + + it("sends the full lineup in order and skips confirmation when nobody drops out", async () => { + sdk.getEventsId.mockResolvedValue( + ok({ artists: [{ id: "a1", name: "Uno" }] }), + ); + await run("events", "artists", "set", "evt_1", "--artist", "a2", "a1"); + expect(sdk.putEventsIdArtists).toHaveBeenCalledWith({ + path: { id: "evt_1" }, + body: { artistIds: ["a2", "a1"], inviteEmails: undefined }, + }); + }); + + it("refuses without --yes when an artist would be removed, naming them", async () => { + sdk.getEventsId.mockResolvedValue( + ok({ artists: [{ id: "a1", name: "Uno" }] }), + ); + await expect( + run("events", "artists", "set", "evt_1", "--artist", "a2"), + ).rejects.toThrow("exited"); + expect(stderr.mock.calls[0]?.[0]).toMatch(/Refusing: Remove Uno/); + expect(sdk.putEventsIdArtists).not.toHaveBeenCalled(); + }); + + it("refuses to clear the lineup without --yes, even if it is already empty", async () => { + sdk.getEventsId.mockResolvedValue(ok({ artists: [] })); + await expect(run("events", "artists", "set", "evt_1")).rejects.toThrow( + "exited", + ); + expect(sdk.putEventsIdArtists).not.toHaveBeenCalled(); + }); + + it("--yes skips the lookup and prints ARTIST_IDS_IGNORED warnings", async () => { + sdk.putEventsIdArtists.mockResolvedValue( + ok( + { artists: [] }, + { + warnings: [ + { code: "ARTIST_IDS_IGNORED", message: "Ignored", ids: ["bad"] }, + ], + }, + ), + ); + await run( + "events", + "artists", + "set", + "evt_1", + "--artist", + "bad", + "--invite", + "x@y.co", + "--yes", + ); + expect(sdk.getEventsId).not.toHaveBeenCalled(); + expect(sdk.putEventsIdArtists).toHaveBeenCalledWith({ + path: { id: "evt_1" }, + body: { artistIds: ["bad"], inviteEmails: ["x@y.co"] }, + }); + expect(stderr.mock.calls[0]?.[0]).toMatch(/ARTIST_IDS_IGNORED.*bad/); + }); + + it("artists search passes q, limit and cursor", async () => { + sdk.getArtists.mockResolvedValue( + ok([], { page: { nextCursor: null, hasMore: false } }), + ); + await run("artists", "search", "bad bunny", "--limit", "5", "--json"); + expect(sdk.getArtists).toHaveBeenCalledWith({ + query: { q: "bad bunny", limit: 5, cursor: undefined }, + }); + }); +}); + +describe("lineup command tree", () => { + it("registers artists set|remove and invitations list|resend|cancel under events", () => { + const events = build().commands.find((c) => c.name() === "events"); + const sub = (n: string) => + events?.commands + .find((c) => c.name() === n) + ?.commands.map((c) => c.name()) + .sort(); + expect(sub("artists")).toEqual(["remove", "set"]); + expect(sub("invitations")).toEqual(["cancel", "list", "resend"]); + }); +}); diff --git a/src/commands/lineup.ts b/src/commands/lineup.ts new file mode 100644 index 0000000..02bf090 --- /dev/null +++ b/src/commands/lineup.ts @@ -0,0 +1,193 @@ +import chalk from "chalk"; +import type { Command } from "commander"; +import { + deleteEventsIdArtistInvitationsInvitationId, + deleteEventsIdArtistsOrganizationId, + getArtists, + getEventsId, + getEventsIdArtistInvitations, + postEventsIdArtistInvitationsInvitationIdResend, + putEventsIdArtists, +} from "../client/sdk.gen"; +import { configureClient, unwrap } from "../lib/api"; +import { confirmOrExit } from "../lib/input"; +import { print, printNextCursor } from "../lib/output"; + +/** Prints API `warnings[]` (e.g. ARTIST_IDS_IGNORED) on stderr, keeping stdout clean for --json. */ +function printWarnings( + warnings?: { code: string; message: string; ids?: string[] }[], +): void { + for (const w of warnings ?? []) + console.error( + chalk.yellow( + `warning [${w.code}]: ${w.message}${w.ids?.length ? ` (${w.ids.join(", ")})` : ""}`, + ), + ); +} + +/** + * `ft artists search ` — resolves registered artist workspaces (across + * FreeTicket, not just yours) to the ids `ft events artists set` takes. + */ +export function registerArtists(program: Command): void { + const root = program + .command("artists") + .description("Artists registered on FreeTicket (to build event lineups)"); + + root + .command("search ") + .description("Search registered artists by name (2+ characters)") + .option("--limit ", "results per page (1-100)", "20") + .option("--cursor ", "pagination cursor") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (q, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await getArtists({ + query: { q, limit: Number(opts.limit), cursor: opts.cursor }, + }), + ); + print(body.data, { + json: opts.json, + columns: ["id", "name", "slug"], + }); + if (!opts.json) printNextCursor(body.page); + }); +} + +/** + * `ft events artists set|remove` and `ft events invitations list|resend|cancel` + * — the event lineup (contract 1.25.0). Hooked under `ft events` through + * registerResource's `extend`, because the paths take two ids. + */ +export function registerEventLineup(events: Command): void { + const artists = events + .command("artists") + .description("Event lineup: the artists linked to an event"); + + artists + .command("set ") + .description( + "Replace the lineup with --artist ids, in order (unlisted artists are unlinked; no --artist clears it)", + ) + .option( + "--artist ", + "artist workspace id (from `ft artists search`), in lineup order", + ) + .option( + "--invite ", + "invite artists without an account (additive)", + ) + .option("--yes", "skip confirmation when artists would be removed") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, opts) => { + configureClient(opts.workspace); + const artistIds: string[] = opts.artist ?? []; + if (!opts.yes) { + // The PUT replaces the whole lineup: name who drops out before asking. + const current = unwrap(await getEventsId({ path: { id: eventId } })); + const removed = (current.data.artists ?? []).filter( + (a) => !artistIds.includes(a.id), + ); + if (removed.length > 0 || artistIds.length === 0) + await confirmOrExit( + artistIds.length === 0 + ? `Clear the lineup of event ${eventId}${removed.length ? ` (removes ${removed.map((a) => a.name).join(", ")})` : ""}?` + : `Remove ${removed.map((a) => a.name).join(", ")} from event ${eventId}?`, + false, + ); + } + const body = unwrap( + await putEventsIdArtists({ + path: { id: eventId }, + body: { artistIds, inviteEmails: opts.invite }, + }), + ); + printWarnings(body.warnings); + print(opts.json ? body : body.data.artists, { + json: opts.json, + columns: ["id", "name", "slug", "type"], + }); + }); + + artists + .command("remove ") + .description( + "Unlink one artist from an event (owner, or the artist itself)", + ) + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, organizationId, opts) => { + await confirmOrExit( + `Remove artist ${organizationId} from event ${eventId}?`, + opts.yes, + ); + configureClient(opts.workspace); + const body = unwrap( + await deleteEventsIdArtistsOrganizationId({ + path: { id: eventId, organizationId }, + }), + ); + print(body.data, { json: opts.json }); + }); + + const invitations = events + .command("invitations") + .description( + "Pending/expired invitations sent to artists without an account", + ); + + invitations + .command("list ") + .description("List an event's artist invitations (newest first)") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await getEventsIdArtistInvitations({ path: { id: eventId } }), + ); + print(body.data, { + json: opts.json, + columns: ["id", "email", "status", "expiresAt", "createdAt"], + }); + }); + + invitations + .command("resend ") + .description("Resend an invitation email and renew it for 14 days") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, invitationId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await postEventsIdArtistInvitationsInvitationIdResend({ + path: { id: eventId, invitationId }, + }), + ); + print(body.data, { json: opts.json }); + }); + + invitations + .command("cancel ") + .description("Cancel (delete) a pending artist invitation") + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, invitationId, opts) => { + await confirmOrExit( + `Cancel invitation ${invitationId} of event ${eventId}?`, + opts.yes, + ); + configureClient(opts.workspace); + const body = unwrap( + await deleteEventsIdArtistInvitationsInvitationId({ + path: { id: eventId, invitationId }, + }), + ); + print(body.data, { json: opts.json }); + }); +} diff --git a/src/destructive-confirm.test.ts b/src/destructive-confirm.test.ts index e6a6e61..ac3ecd2 100644 --- a/src/destructive-confirm.test.ts +++ b/src/destructive-confirm.test.ts @@ -17,12 +17,17 @@ const sdk = vi.hoisted(() => ({ postEventsIdCancel: vi.fn(), deleteStaffId: vi.fn(), deleteWorkspacesId: vi.fn(), + deleteEventsIdArtistsOrganizationId: vi.fn(), + deleteEventsIdArtistInvitationsInvitationId: vi.fn(), })); vi.mock("./client/sdk.gen", async (importOriginal) => ({ ...(await importOriginal()), postEventsIdCancel: sdk.postEventsIdCancel, deleteStaffId: sdk.deleteStaffId, + deleteEventsIdArtistsOrganizationId: sdk.deleteEventsIdArtistsOrganizationId, + deleteEventsIdArtistInvitationsInvitationId: + sdk.deleteEventsIdArtistInvitationsInvitationId, })); vi.mock("./admin-client/sdk.gen", async (importOriginal) => ({ @@ -61,6 +66,14 @@ describe("destructive commands refuse without a TTY and without --yes", () => { [["events", "cancel", "evt_1"], sdk.postEventsIdCancel], [["staff", "delete", "stf_1"], sdk.deleteStaffId], [["admin", "workspaces", "delete", "ws_1"], sdk.deleteWorkspacesId], + [ + ["events", "artists", "remove", "evt_1", "org_1"], + sdk.deleteEventsIdArtistsOrganizationId, + ], + [ + ["events", "invitations", "cancel", "evt_1", "inv_1"], + sdk.deleteEventsIdArtistInvitationsInvitationId, + ], ])("ft %j exits 1 and never calls the SDK", async (args, fn) => { await expect( program.parseAsync(["node", "ft", ...(args as string[])]), diff --git a/src/program.ts b/src/program.ts index 677a9e6..6c9f5ec 100644 --- a/src/program.ts +++ b/src/program.ts @@ -64,6 +64,7 @@ import { registerAdmin } from "./commands/admin"; import { registerApiKeys } from "./commands/api-keys"; import { registerAuth } from "./commands/auth"; import { registerEventDates } from "./commands/event-dates"; +import { registerArtists, registerEventLineup } from "./commands/lineup"; import { registerReports } from "./commands/reports"; import { registerResource } from "./commands/resource"; import { registerTickets } from "./commands/tickets"; @@ -130,8 +131,11 @@ registerResource(program, { query: "withTotal", }, ], + extend: registerEventLineup, }); +registerArtists(program); + // Read-only: settlements are created by FreeTicket, never by the organizer. // The PDF and the payment proofs download through `ft settlements document` // (contract 1.7.0): the API answers 302 with a 5-minute signed URL.