From 936098e979a94186a506b8d48d8a9b2c7a75f133 Mon Sep 17 00:00:00 2001 From: Lucas-FullStackX Date: Sun, 1 Nov 2026 16:21:41 -0500 Subject: [PATCH 1/4] 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. From a2e4dc6ede903f98b127495fcf6799947df9289e Mon Sep 17 00:00:00 2001 From: Lucas-FullStackX Date: Sun, 1 Nov 2026 16:37:48 -0500 Subject: [PATCH 2/4] feat: dashboard-parity ops commands (contract 1.25.0) Schedule publication, presale windows CRUD, ticket transfer, check-in undo, courtesy recipient and courtesy seats. Destructive commands gate on --yes, and a test ties that gate to the contract's x-ft-destructive. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Fo7cm971JYzaEEhqNoSW8E --- .changeset/p1-ops.md | 5 + README.md | 6 + openapi.json | 5965 ++++++++++++++++++++----------- src/commands/ops.test.ts | 149 + src/commands/ops.ts | 270 ++ src/destructive-confirm.test.ts | 70 +- src/program.ts | 20 +- 7 files changed, 4295 insertions(+), 2190 deletions(-) create mode 100644 .changeset/p1-ops.md create mode 100644 src/commands/ops.test.ts create mode 100644 src/commands/ops.ts diff --git a/.changeset/p1-ops.md b/.changeset/p1-ops.md new file mode 100644 index 0000000..f401192 --- /dev/null +++ b/.changeset/p1-ops.md @@ -0,0 +1,5 @@ +--- +"@freeticket/cli": minor +--- + +Dashboard-parity operations (contract 1.25.0): `ft events schedule set|clear`, `ft presale-windows list|create|update|delete` (alias `presales`), `ft sales transfer`, `ft sales recipient set`, `ft tickets checkin-undo` and `ft event-dates courtesy-seats`. Transfer, recipient, check-in undo and presale delete ask for confirmation (`--yes` skips it); a test now fails if any `x-ft-destructive` operation in the contract lacks that gate. New `events update` fields (slug, PULEP, portal visibility, images, genre) and `maxPerCustomer` on dates go through `--data`. diff --git a/README.md b/README.md index 3559d02..b7b8ab7 100644 --- a/README.md +++ b/README.md @@ -99,15 +99,21 @@ ft sales list --status CONFIRMED --json | `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 events schedule set --publish-at ` \| `--sale-starts-at ` · `schedule clear ` | Schedule a DRAFT: publish later, or publish now and open sales later (exactly one flag) · cancel a pending `--publish-at` | ADMIN | | `ft event-dates list` · `create` · `update` · `delete` | Event dates | ADMIN | +| `ft event-dates courtesy-seats ` | Blocked seats of a numbered date that can be issued as courtesies | ADMIN | | `ft ticket-types list` · `get ` | Ticket types (`--event-date-id`) | VIEWER | | `ft ticket-types create` · `update ` · `delete ` | Manage ticket types (`--data `) | ADMIN | +| `ft presale-windows list ` · `create --plan --starts-at --ends-at [--capacity --active]` · `update ` · `delete ` | Membership presale windows (alias `presales`; one per plan; `delete` asks, `--yes` skips) | ADMIN | | `ft sales list` · `get ` | Sales (filters: `--status` `--channel` `--event` `--event-date` `--reference` `--buyer` `--from` `--to`) | STAFF | | `ft sales create` | Create a sale/order — comps & programmatic sales (`--data `) | ADMIN | | `ft sales cancel ` · `refund ` | Cancel / refund a sale (`--data` for the `acknowledge_open_payment` / `acknowledge_manual` flags) | ADMIN | | `ft sales tickets ` · `attempts ` | Tickets/attendees of a sale · its payment attempt history (why it did not go through) | STAFF | +| `ft sales transfer --email ` | Transfer one ticket to a registered buyer; voids the old QR, once per ticket (`--yes`) | ADMIN | +| `ft sales recipient set --name --email ` | Correct a courtesy's recipient and resend (a new email voids the old QRs; `--yes`) | ADMIN | | `ft tickets access ` | Read a ticket's access status (no admit) | STAFF | | `ft tickets checkin ` | Admit a ticket at the door (idempotent) | STAFF | +| `ft tickets checkin-undo ` | Undo a check-in so the ticket is valid again (idempotent; `--yes`) | ADMIN | | `ft tickets resend ` | Resend the ticket's confirmation email (QR) | ADMIN | | `ft tickets reassign ` | Move a sold ticket to another date and/or type (`--data '{"eventDateId":"…"}'`; no price difference charged/refunded) | ADMIN | | `ft plans list` · `get ` | Membership plans | VIEWER | diff --git a/openapi.json b/openapi.json index 839d068..8e5a720 100644 --- a/openapi.json +++ b/openapi.json @@ -720,7 +720,7 @@ "events" ], "summary": "Update an event", - "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\nAbsent fields are left untouched. Errors (`error.code`): 409 `SLUG_TAKEN`; 422 `PULEP_REQUIRED` (only evaluated when the request changes `genre` or `pulepCode`); 422 `GENRE_OTHER_WITHOUT_OTRO` (`genreOther` sent without `genre` while the stored genre is not \"otro\"); 422 `CLASSIFICATION_CONFLICT` (the resulting genre + audience, merged with the stored values, are incompatible, e.g. \"familiar\" with an 18+ audience). `genre`/`subgenre`/`audience` are validated against the stored classification (422 `CLASSIFICATION_CONFLICT`) and then saved as manual classification facets on a best-effort basis. Publication status, the external ticketing URL and the artist lineup have their own endpoints.", "security": [ { "apiKey": [] @@ -807,6 +807,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": { @@ -3500,14 +3510,14 @@ } } }, - "/membership-plans": { - "get": { - "operationId": "getMembershipPlans", + "/sales/{id}/items/{itemId}/transfer": { + "post": { + "operationId": "postSalesIdItemsItemIdTransfer", "tags": [ - "membership-plans" + "sales" ], - "summary": "List the workspace's membership plans", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Transfer one ticket of a sale to another person (destructive)", + "description": "DESTRUCTIVE: changes the ticket holder and voids the previous QR code (the ticket code is rotated and any installed Apple Wallet pass stops working). The new holder receives the ticket by email and the buyer is notified. Same rules as the dashboard and the buyer: the recipient must already have a verified FreeTicket buyer account (the holder name comes from that account), each ticket can be transferred only once (no staff override) and only until the show starts. 422 RECIPIENT_NOT_REGISTERED / SELF_TRANSFER: fix the recipient. 409 NOT_CONFIRMED, ALREADY_TRANSFERRED, CHECKED_IN, REFUNDED, ADDON, PRESALE_NOT_TRANSFERABLE, MULTI_QUANTITY, EVENT_STARTED or CONFLICT (the ticket changed in flight; re-read and retry). Not idempotent: a retry after success answers 409 ALREADY_TRANSFERRED. Minimum role: `ADMIN`.", "security": [ { "apiKey": [] @@ -3516,21 +3526,20 @@ "apiKeyHeader": [] } ], + "x-ft-destructive": true, "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", - "required": false, + "name": "itemId", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -3545,6 +3554,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SaleItemTransferRequest" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -3554,18 +3573,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MembershipPlan" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/SaleItemTransfer" } }, "required": [ - "data", - "page" + "data" ] } } @@ -3601,6 +3613,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": { @@ -3612,14 +3634,16 @@ } } } - }, - "post": { - "operationId": "postMembershipPlans", + } + }, + "/sales/{id}/recipient": { + "patch": { + "operationId": "patchSalesIdRecipient", "tags": [ - "membership-plans" + "sales" ], - "summary": "Create a membership plan", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Correct the recipient of a courtesy sale and resend its tickets", + "description": "DESTRUCTIVE when the email changes (previous QR codes are voided). Only for courtesy sales issued from the dashboard (confirmed, `is_courtesy`); any other sale answers 404. Updates the recipient's name and email and resends the tickets to the corrected address. When the email changes, the ticket codes of the non-transferred tickets are rotated, so the QR codes sent to the wrong address stop working (`ticketCodesRotated: true`). Minimum role: `ADMIN`.", "security": [ { "apiKey": [] @@ -3628,7 +3652,16 @@ "apiKeyHeader": [] } ], + "x-ft-destructive": true, "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -3644,13 +3677,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MembershipPlanCreate" + "$ref": "#/components/schemas/CourtesyRecipientUpdate" } } } }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -3658,7 +3691,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/MembershipPlan" + "$ref": "#/components/schemas/CourtesyRecipient" } }, "required": [ @@ -3711,14 +3744,14 @@ } } }, - "/membership-plans/{id}": { + "/event-dates/{id}/courtesy-seats": { "get": { - "operationId": "getMembershipPlansId", + "operationId": "getEventDatesIdCourtesySeats", "tags": [ - "membership-plans" + "events" ], - "summary": "Get a membership plan", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List blocked seats that can be issued as courtesies", + "description": "For a numbered (seats.io) event date: the seats that are booked on the map without an order (blocked from sale by the event wizard or by hand) and are not claimed by any live sale, grouped by numbered ticket type (matched by seats.io category). These are the seats the dashboard offers when issuing a courtesy. A date without a seat map, or without numbered ticket types, returns `ticketTypes: []`. 503 SEATSIO_UNAVAILABLE (retryable) when seats.io could not be read. Minimum role: `ADMIN`.", "security": [ { "apiKey": [] @@ -3755,7 +3788,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/MembershipPlan" + "$ref": "#/components/schemas/CourtesySeats" } }, "required": [ @@ -3804,16 +3837,28 @@ } } } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } - }, - "patch": { - "operationId": "patchMembershipPlansId", + } + }, + "/membership-plans": { + "get": { + "operationId": "getMembershipPlans", "tags": [ "membership-plans" ], - "summary": "Update a membership plan", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List the workspace's membership plans", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -3824,9 +3869,19 @@ ], "parameters": [ { - "name": "id", - "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" } @@ -3841,16 +3896,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/MembershipPlanUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -3860,11 +3905,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/MembershipPlan" + "type": "array", + "items": { + "$ref": "#/components/schemas/MembershipPlan" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -3912,12 +3964,12 @@ } } }, - "delete": { - "operationId": "deleteMembershipPlansId", + "post": { + "operationId": "postMembershipPlans", "tags": [ "membership-plans" ], - "summary": "Delete a membership plan (soft delete)", + "summary": "Create a membership plan", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -3928,14 +3980,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -3946,13 +3990,31 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MembershipPlanCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MembershipPlan" + } + }, + "required": [ + "data" + ] } } } @@ -3987,16 +4049,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": { @@ -4010,13 +4062,13 @@ } } }, - "/venues": { + "/membership-plans/{id}": { "get": { - "operationId": "getVenues", + "operationId": "getMembershipPlansId", "tags": [ - "venues" + "membership-plans" ], - "summary": "List workspace venues", + "summary": "Get a membership plan", "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -4028,19 +4080,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" } @@ -4064,18 +4106,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Venue" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/MembershipPlan" } }, "required": [ - "data", - "page" + "data" ] } } @@ -4123,12 +4158,12 @@ } } }, - "post": { - "operationId": "postVenues", + "patch": { + "operationId": "patchMembershipPlansId", "tags": [ - "venues" + "membership-plans" ], - "summary": "Create a venue", + "summary": "Update a membership plan", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -4139,6 +4174,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -4154,13 +4197,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/VenueCreate" + "$ref": "#/components/schemas/MembershipPlanUpdate" } } } }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -4168,7 +4211,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Venue" + "$ref": "#/components/schemas/MembershipPlan" } }, "required": [ @@ -4219,16 +4262,14 @@ } } } - } - }, - "/venues/{id}": { - "get": { - "operationId": "getVenuesId", + }, + "delete": { + "operationId": "deleteMembershipPlansId", "tags": [ - "venues" + "membership-plans" ], - "summary": "Get a venue", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Delete a membership plan (soft delete)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -4262,15 +4303,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Venue" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -4305,6 +4338,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": { @@ -4316,14 +4359,16 @@ } } } - }, - "patch": { - "operationId": "patchVenuesId", + } + }, + "/venues": { + "get": { + "operationId": "getVenues", "tags": [ "venues" ], - "summary": "Update a venue", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List workspace venues", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -4334,9 +4379,19 @@ ], "parameters": [ { - "name": "id", - "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" } @@ -4351,16 +4406,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/VenueUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -4370,11 +4415,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Venue" + "type": "array", + "items": { + "$ref": "#/components/schemas/Venue" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -4422,12 +4474,12 @@ } } }, - "delete": { - "operationId": "deleteVenuesId", + "post": { + "operationId": "postVenues", "tags": [ "venues" ], - "summary": "Delete a venue (soft delete)", + "summary": "Create a venue", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -4438,14 +4490,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -4456,13 +4500,31 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VenueCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Venue" + } + }, + "required": [ + "data" + ] } } } @@ -4510,14 +4572,14 @@ } } }, - "/staff": { + "/venues/{id}": { "get": { - "operationId": "getStaff", + "operationId": "getVenuesId", "tags": [ - "staff" + "venues" ], - "summary": "List staff with access to the workspace", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. With `?workspaceIds=`, cursor pagination is still per user: `limit` counts people, not rows.", + "summary": "Get a venue", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -4528,28 +4590,9 @@ ], "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": "workspaceIds", - "in": "query", - "required": false, - "description": "Comma-separated workspace ids (max. 25). Returns the staff of all of them in a single call, with each row tagged with `workspaceId`/`workspaceName` (one row per person and workspace). Always intersected with the workspaces the credential can already manage: it never widens its scope. Without the parameter, the workspace from the `X-Workspace-Id` header is listed.", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -4573,18 +4616,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/StaffUser" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/Venue" } }, "required": [ - "data", - "page" + "data" ] } } @@ -4632,12 +4668,12 @@ } } }, - "post": { - "operationId": "postStaff", + "patch": { + "operationId": "patchVenuesId", "tags": [ - "staff" + "venues" ], - "summary": "Create a staff user in the workspace", + "summary": "Update a venue", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -4648,6 +4684,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -4663,13 +4707,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/StaffCreate" + "$ref": "#/components/schemas/VenueUpdate" } } } }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -4677,7 +4721,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/StaffUser" + "$ref": "#/components/schemas/Venue" } }, "required": [ @@ -4717,16 +4761,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": { @@ -4736,38 +4770,15 @@ } } } - }, - "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" - } - } } } - } - }, - "/staff/{id}": { - "get": { - "operationId": "getStaffId", + }, + "delete": { + "operationId": "deleteVenuesId", "tags": [ - "staff" + "venues" ], - "summary": "Get a staff member", + "summary": "Delete a venue (soft delete)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -4802,15 +4813,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/StaffUser" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -4856,14 +4859,16 @@ } } } - }, - "delete": { - "operationId": "deleteStaffId", + } + }, + "/staff": { + "get": { + "operationId": "getStaff", "tags": [ "staff" ], - "summary": "Revoke a staff member's access to this workspace", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nRevokes access to THIS workspace: granted sections, ticket validation permissions, read-only events, membership, and the home workspace if it was this one. Terminates live sessions and invalidates the invitation QR code. It does NOT delete the account or its history: the person may belong to other workspaces. An `ADMIN` cannot revoke another admin (403) or themselves (409).", + "summary": "List staff with access to the workspace", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. With `?workspaceIds=`, cursor pagination is still per user: `limit` counts people, not rows.", "security": [ { "apiKey": [] @@ -4874,12 +4879,31 @@ ], "parameters": [ { - "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, + "schema": { + "type": "string" + } + }, + { + "name": "workspaceIds", + "in": "query", + "required": false, + "description": "Comma-separated workspace ids (max. 25). Returns the staff of all of them in a single call, with each row tagged with `workspaceId`/`workspaceName` (one row per person and workspace). Always intersected with the workspaces the credential can already manage: it never widens its scope. Without the parameter, the workspace from the `X-Workspace-Id` header is listed.", + "schema": { + "type": "string" + } }, { "name": "X-Workspace-Id", @@ -4897,7 +4921,22 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/StaffUser" + } + }, + "page": { + "$ref": "#/components/schemas/Page" + } + }, + "required": [ + "data", + "page" + ] } } } @@ -4932,16 +4971,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": { @@ -4953,15 +4982,13 @@ } } } - } - }, - "/staff/{id}/role": { - "patch": { - "operationId": "patchStaffIdRole", + }, + "post": { + "operationId": "postStaff", "tags": [ "staff" ], - "summary": "Change a staff user's role", + "summary": "Create a staff user in the workspace", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -4972,14 +4999,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -4995,13 +5014,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RoleUpdate" + "$ref": "#/components/schemas/StaffCreate" } } } }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -5068,18 +5087,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" + } + } } } } }, - "/reports/summary": { + "/staff/{id}": { "get": { - "operationId": "getReportsSummary", + "operationId": "getStaffId", "tags": [ - "reports" + "staff" ], - "summary": "Workspace KPIs (revenue, tickets, sales, memberships)", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Get a staff member", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -5090,19 +5130,11 @@ ], "parameters": [ { - "name": "period", - "in": "query", - "required": false, - "description": "7d | 30d (default) | 90d | 1y", + "name": "id", + "in": "path", + "required": true, "schema": { - "type": "string", - "enum": [ - "7d", - "30d", - "90d", - "1y" - ], - "default": "30d" + "type": "string" } }, { @@ -5124,7 +5156,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ReportSummary" + "$ref": "#/components/schemas/StaffUser" } }, "required": [ @@ -5175,16 +5207,14 @@ } } } - } - }, - "/reports/inventory": { - "get": { - "operationId": "getReportsInventory", + }, + "delete": { + "operationId": "deleteStaffId", "tags": [ - "reports" + "staff" ], - "summary": "Inventory aggregated by event/date/ticket type (capacity, sold, available)", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Revoke a staff member's access to this workspace", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nRevokes access to THIS workspace: granted sections, ticket validation permissions, read-only events, membership, and the home workspace if it was this one. Terminates live sessions and invalidates the invitation QR code. It does NOT delete the account or its history: the person may belong to other workspaces. An `ADMIN` cannot revoke another admin (403) or themselves (409).", "security": [ { "apiKey": [] @@ -5195,66 +5225,13 @@ ], "parameters": [ { - "name": "eventId", - "in": "query", - "required": false, - "description": "Filter by event", - "schema": { - "type": "string" - } - }, - { - "name": "eventDateId", - "in": "query", - "required": false, - "description": "Filter by event date", - "schema": { - "type": "string" - } - }, - { - "name": "from", - "in": "query", - "required": false, - "description": "Event date start ≥ (ISO 8601)", - "schema": { - "type": "string" - } - }, - { - "name": "to", - "in": "query", - "required": false, - "description": "Event date start ≤ (ISO 8601)", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } }, - { - "name": "includeDrafts", - "in": "query", - "required": false, - "description": "Include DRAFT events/dates (default false)", - "schema": { - "type": "boolean", - "default": false - } - }, - { - "name": "groupBy", - "in": "query", - "required": false, - "description": "event | date | ticketType (default)", - "schema": { - "type": "string", - "enum": [ - "event", - "date", - "ticketType" - ], - "default": "ticketType" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -5271,24 +5248,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InventoryRow" - } - }, - "warnings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Warning" - } - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -5323,6 +5283,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": { @@ -5336,13 +5306,13 @@ } } }, - "/reports/reconciliation": { - "get": { - "operationId": "getReportsReconciliation", + "/staff/{id}/role": { + "patch": { + "operationId": "patchStaffIdRole", "tags": [ - "reports" + "staff" ], - "summary": "CFO financial reconciliation (MP ↔ sale ↔ Siigo invoice)", + "summary": "Change a staff user's role", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -5354,96 +5324,33 @@ ], "parameters": [ { - "name": "date_from", - "in": "query", + "name": "id", + "in": "path", "required": true, - "description": "ISO 8601 (start, on Sale.created_at)", "schema": { "type": "string" } }, { - "name": "date_to", - "in": "query", - "required": true, - "description": "ISO 8601 (end)", - "schema": { - "type": "string" - } - }, - { - "name": "match_status", - "in": "query", - "required": false, - "description": "Filter by flag: OK|MISSING_INVOICE|MISSING_CUFE|AMOUNT_MISMATCH|MISSING_PAYMENT", - "schema": { - "type": "string", - "enum": [ - "OK", - "MISSING_INVOICE", - "MISSING_CUFE", - "AMOUNT_MISMATCH", - "MISSING_PAYMENT" - ] - } - }, - { - "name": "provider", - "in": "query", - "required": false, - "description": "Filter by payment_provider (e.g. mercadopago)", - "schema": { - "type": "string" - } - }, - { - "name": "event", - "in": "query", - "required": false, - "description": "Filter by event id", - "schema": { - "type": "string" - } - }, - { - "name": "eventDate", - "in": "query", - "required": false, - "description": "Filter by event date id (takes precedence over `event`)", - "schema": { - "type": "string" - } - }, - { - "name": "page", - "in": "query", - "required": false, - "description": "1-based page (default 1)", - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "page_size", - "in": "query", - "required": false, - "description": "Page size 1..500 (default 100)", - "schema": { - "type": "integer", - "default": 100 - } - }, - { - "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).", + "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/RoleUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -5453,10 +5360,7 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ReconciliationRow" - } + "$ref": "#/components/schemas/StaffUser" } }, "required": [ @@ -5496,6 +5400,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": { @@ -5509,14 +5423,14 @@ } } }, - "/reports/exports/reconciliation": { + "/reports/summary": { "get": { - "operationId": "getReportsExportsReconciliation", + "operationId": "getReportsSummary", "tags": [ "reports" ], - "summary": "CSV export of the CFO financial reconciliation", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Workspace KPIs (revenue, tickets, sales, memberships)", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -5527,64 +5441,19 @@ ], "parameters": [ { - "name": "date_from", - "in": "query", - "required": true, - "description": "ISO 8601 (start, on Sale.created_at)", - "schema": { - "type": "string" - } - }, - { - "name": "date_to", - "in": "query", - "required": true, - "description": "ISO 8601 (end)", - "schema": { - "type": "string" - } - }, - { - "name": "match_status", + "name": "period", "in": "query", "required": false, - "description": "Filter by flag: OK|MISSING_INVOICE|MISSING_CUFE|AMOUNT_MISMATCH|MISSING_PAYMENT", + "description": "7d | 30d (default) | 90d | 1y", "schema": { "type": "string", "enum": [ - "OK", - "MISSING_INVOICE", - "MISSING_CUFE", - "AMOUNT_MISMATCH", - "MISSING_PAYMENT" - ] - } - }, - { - "name": "provider", - "in": "query", - "required": false, - "description": "Filter by payment_provider (e.g. mercadopago)", - "schema": { - "type": "string" - } - }, - { - "name": "event", - "in": "query", - "required": false, - "description": "Filter by event id", - "schema": { - "type": "string" - } - }, - { - "name": "eventDate", - "in": "query", - "required": false, - "description": "Filter by event date id (takes precedence over `event`)", - "schema": { - "type": "string" + "7d", + "30d", + "90d", + "1y" + ], + "default": "30d" } }, { @@ -5603,7 +5472,15 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ReportSummary" + } + }, + "required": [ + "data" + ] } } } @@ -5651,14 +5528,14 @@ } } }, - "/reports/exports/attendees": { + "/reports/inventory": { "get": { - "operationId": "getReportsExportsAttendees", + "operationId": "getReportsInventory", "tags": [ "reports" ], - "summary": "Export attendees per ticket, with filters (max 5000)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Inventory aggregated by event/date/ticket type (capacity, sold, available)", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -5669,19 +5546,19 @@ ], "parameters": [ { - "name": "event", + "name": "eventId", "in": "query", "required": false, - "description": "Filter by Event.id", + "description": "Filter by event", "schema": { "type": "string" } }, { - "name": "eventDate", + "name": "eventDateId", "in": "query", "required": false, - "description": "Filter by EventDate.id", + "description": "Filter by event date", "schema": { "type": "string" } @@ -5690,7 +5567,7 @@ "name": "from", "in": "query", "required": false, - "description": "ISO 8601 — from (on Sale.created_at)", + "description": "Event date start ≥ (ISO 8601)", "schema": { "type": "string" } @@ -5699,25 +5576,34 @@ "name": "to", "in": "query", "required": false, - "description": "ISO 8601 — to (on Sale.created_at)", + "description": "Event date start ≤ (ISO 8601)", "schema": { "type": "string" } }, { - "name": "status", + "name": "includeDrafts", "in": "query", "required": false, - "description": "PENDING|CONFIRMED|ABANDONED|CANCELLED|REFUNDED (default CONFIRMED)", + "description": "Include DRAFT events/dates (default false)", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "groupBy", + "in": "query", + "required": false, + "description": "event | date | ticketType (default)", "schema": { "type": "string", "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] + "event", + "date", + "ticketType" + ], + "default": "ticketType" } }, { @@ -5741,16 +5627,18 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ExportAttendee" + "$ref": "#/components/schemas/InventoryRow" } }, - "page": { - "$ref": "#/components/schemas/Page" + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Warning" + } } }, "required": [ - "data", - "page" + "data" ] } } @@ -5799,13 +5687,13 @@ } } }, - "/reports/exports/buyers": { + "/reports/reconciliation": { "get": { - "operationId": "getReportsExportsBuyers", + "operationId": "getReportsReconciliation", "tags": [ "reports" ], - "summary": "Export buyers, with filters (max 5000)", + "summary": "CFO financial reconciliation (MP ↔ sale ↔ Siigo invoice)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -5817,55 +5705,84 @@ ], "parameters": [ { - "name": "event", + "name": "date_from", "in": "query", - "required": false, - "description": "Filter by Event.id", + "required": true, + "description": "ISO 8601 (start, on Sale.created_at)", "schema": { "type": "string" } }, { - "name": "eventDate", + "name": "date_to", "in": "query", - "required": false, - "description": "Filter by EventDate.id", + "required": true, + "description": "ISO 8601 (end)", "schema": { "type": "string" } }, { - "name": "from", + "name": "match_status", "in": "query", "required": false, - "description": "ISO 8601 — from (on Sale.created_at)", + "description": "Filter by flag: OK|MISSING_INVOICE|MISSING_CUFE|AMOUNT_MISMATCH|MISSING_PAYMENT", "schema": { - "type": "string" + "type": "string", + "enum": [ + "OK", + "MISSING_INVOICE", + "MISSING_CUFE", + "AMOUNT_MISMATCH", + "MISSING_PAYMENT" + ] } }, { - "name": "to", + "name": "provider", "in": "query", "required": false, - "description": "ISO 8601 — to (on Sale.created_at)", + "description": "Filter by payment_provider (e.g. mercadopago)", "schema": { "type": "string" } }, { - "name": "status", + "name": "event", "in": "query", "required": false, - "description": "PENDING|CONFIRMED|ABANDONED|CANCELLED|REFUNDED (default CONFIRMED)", + "description": "Filter by event id", "schema": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] + "type": "string" + } + }, + { + "name": "eventDate", + "in": "query", + "required": false, + "description": "Filter by event date id (takes precedence over `event`)", + "schema": { + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "required": false, + "description": "1-based page (default 1)", + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "page_size", + "in": "query", + "required": false, + "description": "Page size 1..500 (default 100)", + "schema": { + "type": "integer", + "default": 100 } }, { @@ -5889,16 +5806,12 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ExportBuyer" + "$ref": "#/components/schemas/ReconciliationRow" } - }, - "page": { - "$ref": "#/components/schemas/Page" } }, "required": [ - "data", - "page" + "data" ] } } @@ -5947,13 +5860,13 @@ } } }, - "/reports/exports/subscribers": { + "/reports/exports/reconciliation": { "get": { - "operationId": "getReportsExportsSubscribers", + "operationId": "getReportsExportsReconciliation", "tags": [ "reports" ], - "summary": "Export subscribers (max 5000)", + "summary": "CSV export of the CFO financial reconciliation", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -5964,6 +5877,67 @@ } ], "parameters": [ + { + "name": "date_from", + "in": "query", + "required": true, + "description": "ISO 8601 (start, on Sale.created_at)", + "schema": { + "type": "string" + } + }, + { + "name": "date_to", + "in": "query", + "required": true, + "description": "ISO 8601 (end)", + "schema": { + "type": "string" + } + }, + { + "name": "match_status", + "in": "query", + "required": false, + "description": "Filter by flag: OK|MISSING_INVOICE|MISSING_CUFE|AMOUNT_MISMATCH|MISSING_PAYMENT", + "schema": { + "type": "string", + "enum": [ + "OK", + "MISSING_INVOICE", + "MISSING_CUFE", + "AMOUNT_MISMATCH", + "MISSING_PAYMENT" + ] + } + }, + { + "name": "provider", + "in": "query", + "required": false, + "description": "Filter by payment_provider (e.g. mercadopago)", + "schema": { + "type": "string" + } + }, + { + "name": "event", + "in": "query", + "required": false, + "description": "Filter by event id", + "schema": { + "type": "string" + } + }, + { + "name": "eventDate", + "in": "query", + "required": false, + "description": "Filter by event date id (takes precedence over `event`)", + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -5980,18 +5954,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ExportSubscriber" - } - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -6039,14 +6002,14 @@ } } }, - "/reports/by-event": { + "/reports/exports/attendees": { "get": { - "operationId": "getReportsByEvent", + "operationId": "getReportsExportsAttendees", "tags": [ "reports" ], - "summary": "Sales KPIs per workspace event", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Export attendees per ticket, with filters (max 5000)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -6056,11 +6019,29 @@ } ], "parameters": [ + { + "name": "event", + "in": "query", + "required": false, + "description": "Filter by Event.id", + "schema": { + "type": "string" + } + }, + { + "name": "eventDate", + "in": "query", + "required": false, + "description": "Filter by EventDate.id", + "schema": { + "type": "string" + } + }, { "name": "from", "in": "query", "required": false, - "description": "ISO 8601, filters Sale.created_at (gte)", + "description": "ISO 8601 — from (on Sale.created_at)", "schema": { "type": "string" } @@ -6069,7 +6050,7 @@ "name": "to", "in": "query", "required": false, - "description": "ISO 8601, filters Sale.created_at (lte)", + "description": "ISO 8601 — to (on Sale.created_at)", "schema": { "type": "string" } @@ -6078,7 +6059,7 @@ "name": "status", "in": "query", "required": false, - "description": "PENDING|CONFIRMED (default)|ABANDONED|CANCELLED|REFUNDED", + "description": "PENDING|CONFIRMED|ABANDONED|CANCELLED|REFUNDED (default CONFIRMED)", "schema": { "type": "string", "enum": [ @@ -6111,27 +6092,21 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ReportByEventRow" + "$ref": "#/components/schemas/ExportAttendee" } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -6175,14 +6150,14 @@ } } }, - "/reports/timeseries": { + "/reports/exports/buyers": { "get": { - "operationId": "getReportsTimeseries", + "operationId": "getReportsExportsBuyers", "tags": [ "reports" ], - "summary": "Time series of CONFIRMED sales per bucket (day|week|month)", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Export buyers, with filters (max 5000)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -6193,24 +6168,28 @@ ], "parameters": [ { - "name": "interval", + "name": "event", "in": "query", - "required": true, - "description": "day | week | month", + "required": false, + "description": "Filter by Event.id", "schema": { - "type": "string", - "enum": [ - "day", - "week", - "month" - ] + "type": "string" + } + }, + { + "name": "eventDate", + "in": "query", + "required": false, + "description": "Filter by EventDate.id", + "schema": { + "type": "string" } }, { "name": "from", "in": "query", "required": false, - "description": "ISO 8601, filters Sale.created_at (gte)", + "description": "ISO 8601 — from (on Sale.created_at)", "schema": { "type": "string" } @@ -6219,18 +6198,25 @@ "name": "to", "in": "query", "required": false, - "description": "ISO 8601, filters Sale.created_at (lte)", + "description": "ISO 8601 — to (on Sale.created_at)", "schema": { "type": "string" } }, { - "name": "event", + "name": "status", "in": "query", "required": false, - "description": "Workspace event ID (optional)", + "description": "PENDING|CONFIRMED|ABANDONED|CANCELLED|REFUNDED (default CONFIRMED)", "schema": { - "type": "string" + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] } }, { @@ -6254,27 +6240,21 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ReportTimeseriesRow" + "$ref": "#/components/schemas/ExportBuyer" } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -6318,15 +6298,15 @@ } } }, - "/reports/financials": { + "/reports/exports/subscribers": { "get": { - "operationId": "getReportsFinancials", + "operationId": "getReportsExportsSubscribers", "tags": [ "reports" ], - "summary": "Financial statement per event date: gross, costs, and net payable", - "description": "One row per event date (event_date) with the financial breakdown of its confirmed sales — gross collected, platform fee + VAT (IVA), face value, payment gateway fee (actual for MercadoPago, rate-estimated for Wompi or Bold), 4x1000 tax, and net payable — plus the status of the associated settlement. If wompiSalesWithoutRate > 0, the gateway fee for some Wompi or Bold sales could not be estimated and the net amount is overstated.", - "security": [ + "summary": "Export subscribers (max 5000)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "security": [ { "apiKey": [] }, @@ -6335,28 +6315,6 @@ } ], "parameters": [ - { - "name": "event", - "in": "query", - "required": false, - "description": "Filter by event id", - "schema": { - "type": "string" - } - }, - { - "name": "past", - "in": "query", - "required": false, - "description": "true = only event dates that already took place (settleable); false = upcoming ones", - "schema": { - "type": "string", - "enum": [ - "true", - "false" - ] - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -6378,13 +6336,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ReportFinancialsRow" - } - }, - "warnings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Warning" + "$ref": "#/components/schemas/ExportSubscriber" } } }, @@ -6395,16 +6347,6 @@ } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -6448,14 +6390,14 @@ } } }, - "/settlements": { + "/reports/by-event": { "get": { - "operationId": "getSettlements", + "operationId": "getReportsByEvent", "tags": [ - "settlements" + "reports" ], - "summary": "Workspace settlements (payouts to the organizer)", - "description": "Lists the settlements visible to the organization (SENT, AWAITING_PAYMENT, PAID) with their standard id, amount, event/event date, and payment proofs. Download the files with `GET /settlements/{id}/document` (PDF) and `GET /settlements/{id}/proofs/{fileName}` (bank transfer proofs).", + "summary": "Sales KPIs per workspace event", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -6466,45 +6408,37 @@ ], "parameters": [ { - "name": "event", + "name": "from", "in": "query", "required": false, - "description": "Filter by event id", + "description": "ISO 8601, filters Sale.created_at (gte)", "schema": { "type": "string" } }, { - "name": "status", - "in": "query", - "required": false, - "description": "SENT|AWAITING_PAYMENT|PAID", - "schema": { - "type": "string", - "enum": [ - "SENT", - "AWAITING_PAYMENT", - "PAID" - ] - } - }, - { - "name": "limit", + "name": "to", "in": "query", "required": false, - "description": "1..100 (default 20)", + "description": "ISO 8601, filters Sale.created_at (lte)", "schema": { - "type": "integer", - "default": 20 + "type": "string" } }, { - "name": "cursor", + "name": "status", "in": "query", "required": false, - "description": "Id of the last row of the previous page", + "description": "PENDING|CONFIRMED (default)|ABANDONED|CANCELLED|REFUNDED", "schema": { - "type": "string" + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] } }, { @@ -6528,16 +6462,12 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Settlement" + "$ref": "#/components/schemas/ReportByEventRow" } - }, - "page": { - "$ref": "#/components/schemas/Page" } }, "required": [ - "data", - "page" + "data" ] } } @@ -6596,14 +6526,14 @@ } } }, - "/settlements/{id}": { + "/reports/timeseries": { "get": { - "operationId": "getSettlementsId", + "operationId": "getReportsTimeseries", "tags": [ - "settlements" + "reports" ], - "summary": "Get a settlement", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nThe same resource the list returns, by id. Only settlements already sent to the organizer (`SENT`, `AWAITING_PAYMENT`, `PAID`): internal master statuses are not exposed. Download the files with `GET /settlements/{id}/document` and `GET /settlements/{id}/proofs/{fileName}`.", + "summary": "Time series of CONFIRMED sales per bucket (day|week|month)", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -6614,9 +6544,42 @@ ], "parameters": [ { - "name": "id", - "in": "path", + "name": "interval", + "in": "query", "required": true, + "description": "day | week | month", + "schema": { + "type": "string", + "enum": [ + "day", + "week", + "month" + ] + } + }, + { + "name": "from", + "in": "query", + "required": false, + "description": "ISO 8601, filters Sale.created_at (gte)", + "schema": { + "type": "string" + } + }, + { + "name": "to", + "in": "query", + "required": false, + "description": "ISO 8601, filters Sale.created_at (lte)", + "schema": { + "type": "string" + } + }, + { + "name": "event", + "in": "query", + "required": false, + "description": "Workspace event ID (optional)", "schema": { "type": "string" } @@ -6640,7 +6603,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Settlement" + "type": "array", + "items": { + "$ref": "#/components/schemas/ReportTimeseriesRow" + } } }, "required": [ @@ -6650,6 +6616,16 @@ } } }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "401": { "description": "Missing or invalid credential.", "content": { @@ -6693,14 +6669,14 @@ } } }, - "/settlements/{id}/document": { + "/reports/financials": { "get": { - "operationId": "getSettlementsIdDocument", + "operationId": "getReportsFinancials", "tags": [ - "settlements" + "reports" ], - "summary": "Download a settlement PDF", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Files live in a private bucket, so the response is a **302** to a signed URL valid for 5 minutes (the client must follow the redirect; the `storage_path` is never exposed). Only settlements visible to the organization (SENT, AWAITING_PAYMENT, PAID) and within the key's `event_scope`.", + "summary": "Financial statement per event date: gross, costs, and net payable", + "description": "One row per event date (event_date) with the financial breakdown of its confirmed sales — gross collected, platform fee + VAT (IVA), face value, payment gateway fee (actual for MercadoPago, rate-estimated for Wompi or Bold), 4x1000 tax, and net payable — plus the status of the associated settlement. If wompiSalesWithoutRate > 0, the gateway fee for some Wompi or Bold sales could not be estimated and the net amount is overstated.", "security": [ { "apiKey": [] @@ -6711,13 +6687,27 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "event", + "in": "query", + "required": false, + "description": "Filter by event id", "schema": { "type": "string" } }, + { + "name": "past", + "in": "query", + "required": false, + "description": "true = only event dates that already took place (settleable); false = upcoming ones", + "schema": { + "type": "string", + "enum": [ + "true", + "false" + ] + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -6729,11 +6719,35 @@ } ], "responses": { - "302": { - "description": "Redirect to the signed URL (5 min TTL) of the PDF, with Content-Disposition: attachment." + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ReportFinancialsRow" + } + }, + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Warning" + } + } + }, + "required": [ + "data" + ] + } + } + } }, - "401": { - "description": "Invalid or missing credential.", + "400": { + "description": "Bad request: malformed parameters.", "content": { "application/json": { "schema": { @@ -6742,8 +6756,8 @@ } } }, - "403": { - "description": "Insufficient role (< ADMIN).", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -6752,8 +6766,8 @@ } } }, - "404": { - "description": "Settlement does not exist, belongs to another organization, is out of scope, or has no document yet.", + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { @@ -6762,8 +6776,8 @@ } } }, - "502": { - "description": "Could not sign the storage URL.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -6772,8 +6786,8 @@ } } }, - "503": { - "description": "Storage is not configured.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -6785,14 +6799,14 @@ } } }, - "/settlements/{id}/proofs/{fileName}": { + "/settlements": { "get": { - "operationId": "getSettlementsIdProofsFileName", + "operationId": "getSettlements", "tags": [ "settlements" ], - "summary": "Download a settlement payment proof", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. `fileName` is the same value returned in `paymentProofs[].fileName` by `GET /settlements` (URL-encoded). Like `/document`, it responds with a **302** to a signed URL, valid for 5 minutes, in the private bucket.", + "summary": "Workspace settlements (payouts to the organizer)", + "description": "Lists the settlements visible to the organization (SENT, AWAITING_PAYMENT, PAID) with their standard id, amount, event/event date, and payment proofs. Download the files with `GET /settlements/{id}/document` (PDF) and `GET /settlements/{id}/proofs/{fileName}` (bank transfer proofs).", "security": [ { "apiKey": [] @@ -6803,128 +6817,33 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "event", + "in": "query", + "required": false, + "description": "Filter by event id", "schema": { "type": "string" } }, { - "name": "fileName", - "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": { - "302": { - "description": "Redirect to the signed URL (5 min TTL) of the payment proof, with Content-Disposition: attachment." - }, - "401": { - "description": "Invalid or missing credential.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "403": { - "description": "Insufficient role (< ADMIN).", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "404": { - "description": "Settlement does not exist, belongs to another organization, is out of scope, or has no payment proof with that name.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "502": { - "description": "Could not sign the storage URL.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "503": { - "description": "Storage is not configured.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/discounts": { - "get": { - "operationId": "getDiscounts", - "tags": [ - "discounts" - ], - "summary": "List workspace discount codes", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", - "security": [ - { - "apiKey": [] - }, - { - "apiKeyHeader": [] - } - ], - "parameters": [ - { - "name": "event", - "in": "query", - "required": false, - "description": "event id to filter by", - "schema": { - "type": "string" - } - }, - { - "name": "active", + "name": "status", "in": "query", "required": false, - "description": "true|false", + "description": "SENT|AWAITING_PAYMENT|PAID", "schema": { - "type": "boolean" + "type": "string", + "enum": [ + "SENT", + "AWAITING_PAYMENT", + "PAID" + ] } }, { "name": "limit", "in": "query", "required": false, - "description": "1-100, default 20", + "description": "1..100 (default 20)", "schema": { "type": "integer", "default": 20 @@ -6934,6 +6853,7 @@ "name": "cursor", "in": "query", "required": false, + "description": "Id of the last row of the previous page", "schema": { "type": "string" } @@ -6959,7 +6879,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Discount" + "$ref": "#/components/schemas/Settlement" } }, "page": { @@ -6974,6 +6894,16 @@ } } }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "401": { "description": "Missing or invalid credential.", "content": { @@ -7015,14 +6945,16 @@ } } } - }, - "post": { - "operationId": "postDiscounts", + } + }, + "/settlements/{id}": { + "get": { + "operationId": "getSettlementsId", "tags": [ - "discounts" + "settlements" ], - "summary": "Create a discount code", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Get a settlement", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nThe same resource the list returns, by id. Only settlements already sent to the organizer (`SENT`, `AWAITING_PAYMENT`, `PAID`): internal master statuses are not exposed. Download the files with `GET /settlements/{id}/document` and `GET /settlements/{id}/proofs/{fileName}`.", "security": [ { "apiKey": [] @@ -7032,6 +6964,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -7042,18 +6982,8 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DiscountCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -7061,7 +6991,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Discount" + "$ref": "#/components/schemas/Settlement" } }, "required": [ @@ -7101,16 +7031,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": { @@ -7124,14 +7044,14 @@ } } }, - "/discounts/{id}": { - "patch": { - "operationId": "patchDiscountsId", + "/settlements/{id}/document": { + "get": { + "operationId": "getSettlementsIdDocument", "tags": [ - "discounts" + "settlements" ], - "summary": "Update a discount code", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Download a settlement PDF", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Files live in a private bucket, so the response is a **302** to a signed URL valid for 5 minutes (the client must follow the redirect; the `storage_path` is never exposed). Only settlements visible to the organization (SENT, AWAITING_PAYMENT, PAID) and within the key's `event_scope`.", "security": [ { "apiKey": [] @@ -7159,37 +7079,22 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DiscountUpdate" - } - } - } - }, "responses": { - "200": { - "description": "OK", + "302": { + "description": "Redirect to the signed URL (5 min TTL) of the PDF, with Content-Disposition: attachment." + }, + "401": { + "description": "Invalid or missing credential.", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Discount" - } - }, - "required": [ - "data" - ] + "$ref": "#/components/schemas/Error" } } } }, - "401": { - "description": "Missing or invalid credential.", + "403": { + "description": "Insufficient role (< ADMIN).", "content": { "application/json": { "schema": { @@ -7198,8 +7103,8 @@ } } }, - "403": { - "description": "Insufficient role or resource not accessible.", + "404": { + "description": "Settlement does not exist, belongs to another organization, is out of scope, or has no document yet.", "content": { "application/json": { "schema": { @@ -7208,8 +7113,8 @@ } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "502": { + "description": "Could not sign the storage URL.", "content": { "application/json": { "schema": { @@ -7218,8 +7123,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "503": { + "description": "Storage is not configured.", "content": { "application/json": { "schema": { @@ -7229,14 +7134,16 @@ } } } - }, - "delete": { - "operationId": "deleteDiscountsId", + } + }, + "/settlements/{id}/proofs/{fileName}": { + "get": { + "operationId": "getSettlementsIdProofsFileName", "tags": [ - "discounts" + "settlements" ], - "summary": "Delete a discount code (soft delete)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Download a settlement payment proof", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. `fileName` is the same value returned in `paymentProofs[].fileName` by `GET /settlements` (URL-encoded). Like `/document`, it responds with a **302** to a signed URL, valid for 5 minutes, in the private bucket.", "security": [ { "apiKey": [] @@ -7254,6 +7161,14 @@ "type": "string" } }, + { + "name": "fileName", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -7265,18 +7180,21 @@ } ], "responses": { - "200": { - "description": "OK", + "302": { + "description": "Redirect to the signed URL (5 min TTL) of the payment proof, with Content-Disposition: attachment." + }, + "401": { + "description": "Invalid or missing credential.", "content": { "application/json": { "schema": { - "type": "object" + "$ref": "#/components/schemas/Error" } } } }, - "401": { - "description": "Missing or invalid credential.", + "403": { + "description": "Insufficient role (< ADMIN).", "content": { "application/json": { "schema": { @@ -7285,8 +7203,8 @@ } } }, - "403": { - "description": "Insufficient role or resource not accessible.", + "404": { + "description": "Settlement does not exist, belongs to another organization, is out of scope, or has no payment proof with that name.", "content": { "application/json": { "schema": { @@ -7295,8 +7213,8 @@ } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "502": { + "description": "Could not sign the storage URL.", "content": { "application/json": { "schema": { @@ -7305,8 +7223,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "503": { + "description": "Storage is not configured.", "content": { "application/json": { "schema": { @@ -7318,13 +7236,13 @@ } } }, - "/webhooks": { + "/discounts": { "get": { - "operationId": "getWebhooks", + "operationId": "getDiscounts", "tags": [ - "webhooks" + "discounts" ], - "summary": "List workspace webhooks", + "summary": "List workspace discount codes", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -7335,6 +7253,24 @@ } ], "parameters": [ + { + "name": "event", + "in": "query", + "required": false, + "description": "event id to filter by", + "schema": { + "type": "string" + } + }, + { + "name": "active", + "in": "query", + "required": false, + "description": "true|false", + "schema": { + "type": "boolean" + } + }, { "name": "limit", "in": "query", @@ -7374,7 +7310,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Webhook" + "$ref": "#/components/schemas/Discount" } }, "page": { @@ -7432,11 +7368,11 @@ } }, "post": { - "operationId": "postWebhooks", + "operationId": "postDiscounts", "tags": [ - "webhooks" + "discounts" ], - "summary": "Create a webhook (returns the signingSecret only once)", + "summary": "Create a discount code", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -7462,7 +7398,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WebhookCreate" + "$ref": "#/components/schemas/DiscountCreate" } } } @@ -7476,7 +7412,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/WebhookCreated" + "$ref": "#/components/schemas/Discount" } }, "required": [ @@ -7516,6 +7452,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": { @@ -7529,13 +7475,13 @@ } } }, - "/webhooks/{id}": { - "delete": { - "operationId": "deleteWebhooksId", + "/discounts/{id}": { + "patch": { + "operationId": "patchDiscountsId", "tags": [ - "webhooks" + "discounts" ], - "summary": "Delete a workspace webhook", + "summary": "Update a discount code", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -7564,13 +7510,31 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DiscountUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Discount" + } + }, + "required": [ + "data" + ] } } } @@ -7617,13 +7581,13 @@ } } }, - "patch": { - "operationId": "patchWebhooksId", + "delete": { + "operationId": "deleteDiscountsId", "tags": [ - "webhooks" + "discounts" ], - "summary": "Edit a webhook without rotating its signing secret", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nChanges `url`, `events` or `active` while keeping the `signingSecret`. It is the alternative to `DELETE` + `POST`, which rotates the secret and forces the integrator on the other end to reconfigure signature verification.", + "summary": "Delete a discount code (soft delete)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -7651,31 +7615,13 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/WebhookUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Webhook" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -7723,14 +7669,13 @@ } } }, - "/membership-plans/{id}/subscribers": { + "/webhooks": { "get": { - "operationId": "getMembershipPlansIdSubscribers", + "operationId": "getWebhooks", "tags": [ - "membership-plans", - "subscriptions" + "webhooks" ], - "summary": "List subscribers of a membership plan", + "summary": "List workspace webhooks", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -7741,30 +7686,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "status", - "in": "query", - "required": false, - "description": "PENDING|ACTIVE|EXPIRED|CANCELLED|PAUSED", - "schema": { - "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" - ] - } - }, { "name": "limit", "in": "query", @@ -7804,7 +7725,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Subscriber" + "$ref": "#/components/schemas/Webhook" } }, "page": { @@ -7860,16 +7781,13 @@ } } } - } - }, - "/subscriptions/{id}/cancel": { + }, "post": { - "operationId": "postSubscriptionsIdCancel", + "operationId": "postWebhooks", "tags": [ - "subscriptions", - "membership-plans" + "webhooks" ], - "summary": "Cancel a membership subscription", + "summary": "Create a webhook (returns the signingSecret only once)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -7880,14 +7798,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -7898,8 +7808,18 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -7907,7 +7827,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/SubscriptionCancelResult" + "$ref": "#/components/schemas/WebhookCreated" } }, "required": [ @@ -7956,28 +7876,18 @@ } } } - }, - "502": { - "description": "The external provider failed to complete the operation.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } } } } }, - "/sales/{id}/tickets": { - "get": { - "operationId": "getSalesIdTickets", + "/webhooks/{id}": { + "delete": { + "operationId": "deleteWebhooksId", "tags": [ - "sales" + "webhooks" ], - "summary": "List the individual tickets of a sale", - "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Delete a workspace webhook", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -8011,18 +7921,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SaleTicket" - } - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -8068,16 +7967,14 @@ } } } - } - }, - "/sales/{id}/attempts": { - "get": { - "operationId": "getSalesIdAttempts", + }, + "patch": { + "operationId": "patchWebhooksId", "tags": [ - "sales" + "webhooks" ], - "summary": "List a sale's payment attempt history", - "description": "Minimum role: `STAFF`. One event per payment movement reported by the gateway (approved, declined, or a later refund), ordered from newest to oldest. It exists to answer \"why didn't this sale go through?\" without leaving the API: `Sale.status` only reflects the final outcome, and from `GET /sales/{id}` a `CANCELLED`/`ABANDONED` sale with `confirmedAt: null` is indistinguishable from an order that simply expired — see the derived `failureReason`/`paymentStatus`/`declineCode` fields on `SaleDetail`.", + "summary": "Edit a webhook without rotating its signing secret", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nChanges `url`, `events` or `active` while keeping the `signingSecret`. It is the alternative to `DELETE` + `POST`, which rotates the secret and forces the integrator on the other end to reconfigure signature verification.", "security": [ { "apiKey": [] @@ -8105,6 +8002,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -8114,10 +8021,7 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PaymentAttempt" - } + "$ref": "#/components/schemas/Webhook" } }, "required": [ @@ -8170,14 +8074,15 @@ } } }, - "/tickets/{ticketCode}": { - "patch": { - "operationId": "patchTicketsTicketCode", + "/membership-plans/{id}/subscribers": { + "get": { + "operationId": "getMembershipPlansIdSubscribers", "tags": [ - "tickets" + "membership-plans", + "subscriptions" ], - "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": "List subscribers of a membership plan", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -8188,13 +8093,47 @@ ], "parameters": [ { - "name": "ticketCode", + "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, + { + "name": "status", + "in": "query", + "required": false, + "description": "PENDING|ACTIVE|EXPIRED|CANCELLED|PAUSED", + "schema": { + "type": "string", + "enum": [ + "PENDING", + "ACTIVE", + "EXPIRED", + "CANCELLED", + "PAUSED" + ] + } + }, + { + "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", @@ -8205,16 +8144,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TicketReassign" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -8224,11 +8153,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/SaleItem" + "type": "array", + "items": { + "$ref": "#/components/schemas/Subscriber" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -8264,28 +8200,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" - } - } - } - }, - "502": { - "description": "The external provider failed to complete the operation.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -8297,13 +8213,14 @@ } } }, - "/tickets/{ticketCode}/resend": { + "/subscriptions/{id}/cancel": { "post": { - "operationId": "postTicketsTicketCodeResend", + "operationId": "postSubscriptionsIdCancel", "tags": [ - "tickets" + "subscriptions", + "membership-plans" ], - "summary": "Resend the confirmation email with the ticket", + "summary": "Cancel a membership subscription", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -8315,7 +8232,7 @@ ], "parameters": [ { - "name": "ticketCode", + "name": "id", "in": "path", "required": true, "schema": { @@ -8341,7 +8258,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ResendTicket" + "$ref": "#/components/schemas/SubscriptionCancelResult" } }, "required": [ @@ -8381,16 +8298,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": { @@ -8414,13 +8321,13 @@ } } }, - "/tickets/{ticketCode}/checkin": { - "post": { - "operationId": "postTicketsTicketCodeCheckin", + "/sales/{id}/tickets": { + "get": { + "operationId": "getSalesIdTickets", "tags": [ - "tickets" + "sales" ], - "summary": "Check in a ticket at the door", + "summary": "List the individual tickets of a sale", "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -8432,7 +8339,7 @@ ], "parameters": [ { - "name": "ticketCode", + "name": "id", "in": "path", "required": true, "schema": { @@ -8449,16 +8356,6 @@ } } ], - "requestBody": { - "required": false, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CheckinRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -8468,7 +8365,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CheckinResult" + "type": "array", + "items": { + "$ref": "#/components/schemas/SaleTicket" + } } }, "required": [ @@ -8508,16 +8408,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": { @@ -8531,14 +8421,14 @@ } } }, - "/tickets/{ticketCode}/access": { + "/sales/{id}/attempts": { "get": { - "operationId": "getTicketsTicketCodeAccess", + "operationId": "getSalesIdAttempts", "tags": [ - "tickets" + "sales" ], - "summary": "Check a ticket's validity without consuming it", - "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List a sale's payment attempt history", + "description": "Minimum role: `STAFF`. One event per payment movement reported by the gateway (approved, declined, or a later refund), ordered from newest to oldest. It exists to answer \"why didn't this sale go through?\" without leaving the API: `Sale.status` only reflects the final outcome, and from `GET /sales/{id}` a `CANCELLED`/`ABANDONED` sale with `confirmedAt: null` is indistinguishable from an order that simply expired — see the derived `failureReason`/`paymentStatus`/`declineCode` fields on `SaleDetail`.", "security": [ { "apiKey": [] @@ -8549,7 +8439,7 @@ ], "parameters": [ { - "name": "ticketCode", + "name": "id", "in": "path", "required": true, "schema": { @@ -8575,7 +8465,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/TicketAccess" + "type": "array", + "items": { + "$ref": "#/components/schemas/PaymentAttempt" + } } }, "required": [ @@ -8628,14 +8521,14 @@ } } }, - "/api-keys": { - "get": { - "operationId": "getApiKeys", + "/tickets/{ticketCode}": { + "patch": { + "operationId": "patchTicketsTicketCode", "tags": [ - "api-keys" + "tickets" ], - "summary": "List my API keys", - "description": "Lists the authenticated user's API keys (never the hash or the plaintext secret).", + "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": [] @@ -8646,19 +8539,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": "ticketCode", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -8673,6 +8556,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TicketReassign" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -8682,18 +8575,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ApiKey" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/SaleItem" } }, "required": [ - "data", - "page" + "data" ] } } @@ -8729,8 +8615,28 @@ } } }, + "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": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "502": { + "description": "The external provider failed to complete the operation.", "content": { "application/json": { "schema": { @@ -8740,14 +8646,16 @@ } } } - }, + } + }, + "/tickets/{ticketCode}/resend": { "post": { - "operationId": "postApiKeys", + "operationId": "postTicketsTicketCodeResend", "tags": [ - "api-keys" + "tickets" ], - "summary": "Mint an API key (returns the plaintext exactly once)", - "description": "Creates a service API key for the authenticated user. scope=\"read\" (default) only allows GET/HEAD; scope=\"write\" enables mutations according to the user role. The plaintext secret only appears in this response.", + "summary": "Resend the confirmation email with the ticket", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -8758,27 +8666,25 @@ ], "parameters": [ { - "name": "X-Workspace-Id", - "in": "header", - "required": false, + "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/ApiKeyCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -8786,7 +8692,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ApiKeyCreated" + "$ref": "#/components/schemas/ResendTicket" } }, "required": [ @@ -8826,6 +8732,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": { @@ -8835,18 +8751,28 @@ } } } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } } }, - "/api-keys/{id}": { - "delete": { - "operationId": "deleteApiKeysId", + "/tickets/{ticketCode}/checkin": { + "post": { + "operationId": "postTicketsTicketCodeCheckin", "tags": [ - "api-keys" + "tickets" ], - "summary": "Revoke one of my API keys", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Check in a ticket at the door", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -8857,7 +8783,7 @@ ], "parameters": [ { - "name": "id", + "name": "ticketCode", "in": "path", "required": true, "schema": { @@ -8874,82 +8800,18 @@ } } ], - "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" - } - } - } - }, - "422": { - "description": "Request body/parameter validation failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/customer/auth/request": { - "post": { - "operationId": "postCustomerAuthRequest", - "tags": [ - "customer", - "auth" - ], - "summary": "Request an access code to sign in (or create an account)", - "description": "Public endpoint (no auth): credential bootstrap for the Device Authorization Grant (RFC 8628).", - "security": [], "requestBody": { - "required": true, + "required": false, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CustomerAuthRequest" + "$ref": "#/components/schemas/CheckinRequest" } } } }, "responses": { - "202": { + "200": { "description": "OK", "content": { "application/json": { @@ -8957,7 +8819,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerAuthRequestResult" + "$ref": "#/components/schemas/CheckinResult" } }, "required": [ @@ -8997,8 +8859,8 @@ } } }, - "422": { - "description": "Operation error.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -9007,50 +8869,53 @@ } } }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "422": { + "description": "Request body/parameter validation failed.", "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/auth/verify": { - "post": { - "operationId": "postCustomerAuthVerify", + }, + "delete": { + "operationId": "deleteTicketsTicketCodeCheckin", "tags": [ - "customer", - "auth" + "tickets" ], - "summary": "Exchange the access code for a buyer session", - "description": "Public endpoint (no auth): credential bootstrap for the Device Authorization Grant (RFC 8628).", - "security": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerAuthVerify" - } + "summary": "Undo a ticket check-in (destructive)", + "description": "DESTRUCTIVE: reverts a door check-in so the ticket is valid again. Use it to fix a wrong scan; it is recorded in the audit log as CHECKIN_UNDO. Requires `ADMIN` (not `STAFF`): a checked-in ticket blocks cancelling its sale, and undoing the check-in reopens that path. The show's validation window does not apply. Idempotent: a ticket that is not checked in answers 200 with `undone: false`. 409 CHECKIN_CHANGED when the check-in changed between the read and the write (another undo or a new scan): re-read the ticket and retry. Minimum role: `ADMIN`.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "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" } } - }, + ], "responses": { "200": { "description": "OK", @@ -9060,7 +8925,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerAuthVerifyResult" + "$ref": "#/components/schemas/CheckinUndoResult" } }, "required": [ @@ -9071,7 +8936,7 @@ } }, "401": { - "description": "Operation error.", + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -9100,8 +8965,8 @@ } } }, - "422": { - "description": "Operation error.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -9110,38 +8975,27 @@ } } }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "422": { + "description": "Request body/parameter validation failed.", "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/me": { + "/tickets/{ticketCode}/access": { "get": { - "operationId": "getCustomerMe", + "operationId": "getTicketsTicketCodeAccess", "tags": [ - "customer" + "tickets" ], - "summary": "Authenticated buyer identity", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: if sent, it must be an enterprise service key (403 otherwise); without a key, it responds the same for the buyer acting on their own.", + "summary": "Check a ticket's validity without consuming it", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -9151,6 +9005,14 @@ } ], "parameters": [ + { + "name": "ticketCode", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -9170,7 +9032,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerMe" + "$ref": "#/components/schemas/TicketAccess" } }, "required": [ @@ -9223,14 +9085,14 @@ } } }, - "/customer/tickets": { + "/api-keys": { "get": { - "operationId": "getCustomerTickets", + "operationId": "getApiKeys", "tags": [ - "customer" + "api-keys" ], - "summary": "Buyer's tickets", - "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 the key (its own events AND those where it is listed as a linked artist); without a key, returns ALL of the buyer's tickets, not limited to any workspace. Only CONFIRMED sales, matched by the buyer's account or purchase email.", + "summary": "List my API keys", + "description": "Lists the authenticated user's API keys (never the hash or the plaintext secret).", "security": [ { "apiKey": [] @@ -9279,7 +9141,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/CustomerSale" + "$ref": "#/components/schemas/ApiKey" } }, "page": { @@ -9335,16 +9197,14 @@ } } } - } - }, - "/customer/tickets/{id}": { - "get": { - "operationId": "getCustomerTicketsId", - "tags": [ - "customer" + }, + "post": { + "operationId": "postApiKeys", + "tags": [ + "api-keys" ], - "summary": "Detail of a buyer's ticket (deep link)", - "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 the key; without a key, any of the buyer's own tickets is visible, not limited to a workspace. `{id}` accepts the sale id or its `reference`. Returns 404 if the ticket does not belong to the session's buyer or falls outside the scope.", + "summary": "Mint an API key (returns the plaintext exactly once)", + "description": "Creates a service API key for the authenticated user. scope=\"read\" (default) only allows GET/HEAD; scope=\"write\" enables mutations according to the user role. The plaintext secret only appears in this response.", "security": [ { "apiKey": [] @@ -9354,14 +9214,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -9372,8 +9224,18 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -9381,7 +9243,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerSale" + "$ref": "#/components/schemas/ApiKeyCreated" } }, "required": [ @@ -9434,14 +9296,14 @@ } } }, - "/customer/tickets/{id}/cancel": { - "post": { - "operationId": "postCustomerTicketsIdCancel", + "/api-keys/{id}": { + "delete": { + "operationId": "deleteApiKeysId", "tags": [ - "customer" + "api-keys" ], - "summary": "Cancel the buyer's own purchase (only if not yet paid)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (see /customer/tickets). Only cancels PENDING sales (releases inventory and seats). A CONFIRMED sale responds 409 with code `REFUND_REQUIRED`: refunds are handled by the organizer. `{id}` accepts the sale id or its `reference`.", + "summary": "Revoke one of my API keys", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -9475,15 +9337,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/CustomerTicketCancelResult" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -9518,16 +9372,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": { @@ -9541,35 +9385,28 @@ } } }, - "/customer/logout": { + "/customer/auth/request": { "post": { - "operationId": "postCustomerLogout", + "operationId": "postCustomerAuthRequest", "tags": [ - "customer" - ], - "summary": "Sign out the buyer session", - "description": "Revokes the session presented in `X-Customer-Session`: the token stops working immediately. Idempotent. The enterprise service API key is OPTIONAL: if sent, it must be an enterprise service key.", - "security": [ - { - "apiKey": [] - }, - { - "apiKeyHeader": [] - } + "customer", + "auth" ], - "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" + "summary": "Request an access code to sign in (or create an account)", + "description": "Public endpoint (no auth): credential bootstrap for the Device Authorization Grant (RFC 8628).", + "security": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomerAuthRequest" + } } } - ], + }, "responses": { - "200": { + "202": { "description": "OK", "content": { "application/json": { @@ -9577,7 +9414,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerLogout" + "$ref": "#/components/schemas/CustomerAuthRequestResult" } }, "required": [ @@ -9618,92 +9455,150 @@ } }, "422": { - "description": "Request body/parameter validation failed.", + "description": "Operation error.", + "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" + } } } } } }, - "/api/customer-auth/enterprise-exchange": { + "/customer/auth/verify": { "post": { - "operationId": "postApiCustomerAuthEnterpriseExchange", + "operationId": "postCustomerAuthVerify", "tags": [ - "customer" - ], - "summary": "Exchange the headless SSO one-time token for a session token", - "description": "Server-to-server: requires an enterprise service API key (Bearer or x-api-key). Exchanges the one-time token issued by /api/customer-auth/enterprise-return (single-use, 60 s TTL) for the buyer's session token. Plain body, no { data } envelope.", - "security": [ - { - "apiKey": [] - }, - { - "apiKeyHeader": [] - } - ], - "servers": [ - { - "url": "/", - "description": "Canonical host (outside /api/v1)" - } - ], - "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" - } - } + "customer", + "auth" ], + "summary": "Exchange the access code for a buyer session", + "description": "Public endpoint (no auth): credential bootstrap for the Device Authorization Grant (RFC 8628).", + "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EnterpriseExchangeRequest" + "$ref": "#/components/schemas/CustomerAuthVerify" } } } }, "responses": { "200": { - "description": "Buyer session exchanged.", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EnterpriseExchangeResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerAuthVerifyResult" + } + }, + "required": [ + "data" + ] } } } }, "401": { - "description": "Missing or invalid API key, or invalid/expired token." + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "403": { - "description": "The API key doesn't belong to an enterprise service user, or the token was minted for another workspace." + "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": "Invalid body." + "description": "Operation error.", + "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" + } + } } } } }, - "/customer/membership": { + "/customer/me": { "get": { - "operationId": "getCustomerMembership", + "operationId": "getCustomerMe", "tags": [ "customer" ], - "summary": "Buyer membership status in a workspace", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the workspace is the one pinned to it (`workspaceId` is ignored); without a key, `workspaceId` is REQUIRED (422 if missing). `active` is true only with an ACTIVE, unexpired membership. If none is current, `membership` returns the most recent one (expired, cancelled or pending payment) so the landing page can choose the CTA; `null` = never a member of that workspace.", + "summary": "Authenticated buyer identity", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: if sent, it must be an enterprise service key (403 otherwise); without a key, it responds the same for the buyer acting on their own.", "security": [ { "apiKey": [] @@ -9713,15 +9608,6 @@ } ], "parameters": [ - { - "name": "workspaceId", - "in": "query", - "required": false, - "description": "Required only without an enterprise service API key. Ignored with a key.", - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -9741,7 +9627,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerMembershipState" + "$ref": "#/components/schemas/CustomerMe" } }, "required": [ @@ -9782,7 +9668,7 @@ } }, "422": { - "description": "Operation error.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -9794,15 +9680,14 @@ } } }, - "/customer/subscriptions": { - "post": { - "operationId": "postCustomerSubscriptions", + "/customer/tickets": { + "get": { + "operationId": "getCustomerTickets", "tags": [ - "customer", - "subscriptions" + "customer" ], - "summary": "Start a membership sign-up (returns the payment URL)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the plan must belong to the workspace pinned to it; without a key, any active plan by its id (the plan itself determines the sign-up workspace). Validates that the buyer can acquire it and returns the membership checkout URL on the canonical host (the platform completes the charge). On return, re-read `GET /customer/membership`.", + "summary": "Buyer's tickets", + "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 the key (its own events AND those where it is listed as a linked artist); without a key, returns ALL of the buyer's tickets, not limited to any workspace. Only CONFIRMED sales, matched by the buyer's account or purchase email.", "security": [ { "apiKey": [] @@ -9812,6 +9697,24 @@ } ], "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", @@ -9822,16 +9725,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerSubscribeRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -9841,11 +9734,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerSubscribeResult" + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomerSale" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -9881,16 +9781,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": { @@ -9904,15 +9794,14 @@ } } }, - "/customer/subscriptions/cancel": { - "post": { - "operationId": "postCustomerSubscriptionsCancel", + "/customer/tickets/{id}": { + "get": { + "operationId": "getCustomerTicketsId", "tags": [ - "customer", - "subscriptions" + "customer" ], - "summary": "Cancel the buyer's own membership", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the workspace is the one pinned to it (any `workspaceId` in the body is ignored); without a key, `workspaceId` is REQUIRED in the body (422 if missing). The membership is ALWAYS resolved from the buyer session (a CustomerMembership id is never accepted). It first cancels the recurring charge at the provider and then marks the membership as CANCELLED. Idempotent.", + "summary": "Detail of a buyer's ticket (deep link)", + "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 the key; without a key, any of the buyer's own tickets is visible, not limited to a workspace. `{id}` accepts the sale id or its `reference`. Returns 404 if the ticket does not belong to the session's buyer or falls outside the scope.", "security": [ { "apiKey": [] @@ -9922,6 +9811,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -9932,16 +9829,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerSubscriptionCancelRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -9951,7 +9838,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerSubscriptionCancelResult" + "$ref": "#/components/schemas/CustomerSale" } }, "required": [ @@ -9982,7 +9869,7 @@ } }, "404": { - "description": "Operation error.", + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -9992,17 +9879,7 @@ } }, "422": { - "description": "Operation error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "502": { - "description": "The external provider failed to complete the operation.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -10014,14 +9891,14 @@ } } }, - "/customer/profile": { - "get": { - "operationId": "getCustomerProfile", + "/customer/tickets/{id}/cancel": { + "post": { + "operationId": "postCustomerTicketsIdCancel", "tags": [ "customer" ], - "summary": "Buyer profile (name and phone)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (issue #673): this endpoint is scoped only by the session's `customer.id`, so it behaves identically with or without a key.", + "summary": "Cancel the buyer's own purchase (only if not yet paid)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (see /customer/tickets). Only cancels PENDING sales (releases inventory and seats). A CONFIRMED sale responds 409 with code `REFUND_REQUIRED`: refunds are handled by the organizer. `{id}` accepts the sale id or its `reference`.", "security": [ { "apiKey": [] @@ -10031,6 +9908,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -10050,7 +9935,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerProfile" + "$ref": "#/components/schemas/CustomerTicketCancelResult" } }, "required": [ @@ -10090,6 +9975,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": { @@ -10101,14 +9996,16 @@ } } } - }, - "patch": { - "operationId": "patchCustomerProfile", + } + }, + "/customer/logout": { + "post": { + "operationId": "postCustomerLogout", "tags": [ "customer" ], - "summary": "Update the buyer profile", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL. Only updates the session's buyer: name and phone. The email cannot be changed (it is the account identity). Omitted fields are left untouched.", + "summary": "Sign out the buyer session", + "description": "Revokes the session presented in `X-Customer-Session`: the token stops working immediately. Idempotent. The enterprise service API key is OPTIONAL: if sent, it must be an enterprise service key.", "security": [ { "apiKey": [] @@ -10128,16 +10025,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerProfileUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -10147,7 +10034,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerProfile" + "$ref": "#/components/schemas/CustomerLogout" } }, "required": [ @@ -10200,15 +10087,80 @@ } } }, - "/customer/orders": { + "/api/customer-auth/enterprise-exchange": { + "post": { + "operationId": "postApiCustomerAuthEnterpriseExchange", + "tags": [ + "customer" + ], + "summary": "Exchange the headless SSO one-time token for a session token", + "description": "Server-to-server: requires an enterprise service API key (Bearer or x-api-key). Exchanges the one-time token issued by /api/customer-auth/enterprise-return (single-use, 60 s TTL) for the buyer's session token. Plain body, no { data } envelope.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "servers": [ + { + "url": "/", + "description": "Canonical host (outside /api/v1)" + } + ], + "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/EnterpriseExchangeRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Buyer session exchanged.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EnterpriseExchangeResponse" + } + } + } + }, + "401": { + "description": "Missing or invalid API key, or invalid/expired token." + }, + "403": { + "description": "The API key doesn't belong to an enterprise service user, or the token was minted for another workspace." + }, + "422": { + "description": "Invalid body." + } + } + } + }, + "/customer/membership": { "get": { - "operationId": "getCustomerOrders", + "operationId": "getCustomerMembership", "tags": [ - "customer", - "orders" + "customer" ], - "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": "Buyer membership status in a workspace", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the workspace is the one pinned to it (`workspaceId` is ignored); without a key, `workspaceId` is REQUIRED (422 if missing). `active` is true only with an ACTIVE, unexpired membership. If none is current, `membership` returns the most recent one (expired, cancelled or pending payment) so the landing page can choose the CTA; `null` = never a member of that workspace.", "security": [ { "apiKey": [] @@ -10219,10 +10171,10 @@ ], "parameters": [ { - "name": "eventDateId", + "name": "workspaceId", "in": "query", "required": false, - "description": "Required. The event date being queried.", + "description": "Required only without an enterprise service API key. Ignored with a key.", "schema": { "type": "string" } @@ -10246,7 +10198,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderCurrent" + "$ref": "#/components/schemas/CustomerMembershipState" } }, "required": [ @@ -10297,15 +10249,17 @@ } } } - }, + } + }, + "/customer/subscriptions": { "post": { - "operationId": "postCustomerOrders", + "operationId": "postCustomerSubscriptions", "tags": [ "customer", - "orders" + "subscriptions" ], - "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": "Start a membership sign-up (returns the payment URL)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the plan must belong to the workspace pinned to it; without a key, any active plan by its id (the plan itself determines the sign-up workspace). Validates that the buyer can acquire it and returns the membership checkout URL on the canonical host (the platform completes the charge). On return, re-read `GET /customer/membership`.", "security": [ { "apiKey": [] @@ -10323,15 +10277,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": { @@ -10339,13 +10284,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CustomerOrderCreateRequest" + "$ref": "#/components/schemas/CustomerSubscribeRequest" } } } }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -10353,7 +10298,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderCreateResult" + "$ref": "#/components/schemas/CustomerSubscribeResult" } }, "required": [ @@ -10412,50 +10357,19 @@ } } } - }, - "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" - } - } - } } } } }, - "/customer/orders/{id}/payment": { + "/customer/subscriptions/cancel": { "post": { - "operationId": "postCustomerOrdersIdPayment", + "operationId": "postCustomerSubscriptionsCancel", "tags": [ "customer", - "orders" + "subscriptions" ], - "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": "Cancel the buyer's own membership", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the workspace is the one pinned to it (any `workspaceId` in the body is ignored); without a key, `workspaceId` is REQUIRED in the body (422 if missing). The membership is ALWAYS resolved from the buyer session (a CustomerMembership id is never accepted). It first cancels the recurring charge at the provider and then marks the membership as CANCELLED. Idempotent.", "security": [ { "apiKey": [] @@ -10465,14 +10379,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -10481,17 +10387,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/CustomerSubscriptionCancelRequest" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -10501,7 +10408,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderStartPayment" + "$ref": "#/components/schemas/CustomerSubscriptionCancelResult" } }, "required": [ @@ -10532,17 +10439,7 @@ } }, "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.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -10552,7 +10449,7 @@ } }, "422": { - "description": "Request body/parameter validation failed.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -10561,39 +10458,27 @@ } } }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "502": { + "description": "The external provider failed to complete the operation.", "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}/payment/card": { - "post": { - "operationId": "postCustomerOrdersIdPaymentCard", + "/customer/profile": { + "get": { + "operationId": "getCustomerProfile", "tags": [ - "customer", - "orders" + "customer" ], - "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": "Buyer profile (name and phone)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (issue #673): this endpoint is scoped only by the session's `customer.id`, so it behaves identically with or without a key.", "security": [ { "apiKey": [] @@ -10603,14 +10488,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -10619,27 +10496,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", @@ -10649,7 +10507,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeResult" + "$ref": "#/components/schemas/CustomerProfile" } }, "required": [ @@ -10689,59 +10547,25 @@ } } }, - "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": { "$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}/payment/pse": { - "post": { - "operationId": "postCustomerOrdersIdPaymentPse", + }, + "patch": { + "operationId": "patchCustomerProfile", "tags": [ - "customer", - "orders" + "customer" ], - "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": "Update the buyer profile", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL. Only updates the session's buyer: name and phone. The email cannot be changed (it is the account identity). Omitted fields are left untouched.", "security": [ { "apiKey": [] @@ -10751,14 +10575,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -10767,17 +10583,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/CustomerProfileUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -10787,7 +10604,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoPse" + "$ref": "#/components/schemas/CustomerProfile" } }, "required": [ @@ -10827,16 +10644,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": { @@ -10846,40 +10653,19 @@ } } } - }, - "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}/release": { - "post": { - "operationId": "postCustomerOrdersIdRelease", + "/customer/orders": { + "get": { + "operationId": "getCustomerOrders", "tags": [ "customer", "orders" ], - "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": "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": [] @@ -10890,9 +10676,10 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "eventDateId", + "in": "query", + "required": false, + "description": "Required. The event date being queried.", "schema": { "type": "string" } @@ -10916,7 +10703,114 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderRelease" + "$ref": "#/components/schemas/CustomerOrderCurrent" + } + }, + "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": "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": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerOrderCreateResult" } }, "required": [ @@ -11010,15 +10904,15 @@ } } }, - "/customer/orders/{id}": { - "get": { - "operationId": "getCustomerOrdersId", + "/customer/orders/{id}/payment": { + "post": { + "operationId": "postCustomerOrdersIdPayment", "tags": [ "customer", "orders" ], - "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": "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": [] @@ -11044,6 +10938,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": { @@ -11055,7 +10958,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderStatus" + "$ref": "#/components/schemas/CustomerOrderStartPayment" } }, "required": [ @@ -11095,6 +10998,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": { @@ -11129,15 +11042,15 @@ } } }, - "/customer/purchase-sessions": { + "/customer/orders/{id}/payment/card": { "post": { - "operationId": "postCustomerPurchaseSessions", + "operationId": "postCustomerOrdersIdPaymentCard", "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": "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": [] @@ -11147,6 +11060,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -11155,6 +11076,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" + } } ], "requestBody": { @@ -11162,21 +11092,21 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PurchaseSessionCreateRequest" + "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeRequest" } } } }, "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/CustomerOrderMercadoPagoChargeResult" } }, "required": [ @@ -11186,19 +11116,1253 @@ } } }, - "201": { - "description": "OK", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/PurchaseSessionCreated" + "$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": { + "$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" + } + } + } + } + } + }, + "/customer/orders/{id}/payment/pse": { + "post": { + "operationId": "postCustomerOrdersIdPaymentPse", + "tags": [ + "customer", + "orders" + ], + "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": [] + }, + { + "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" + } + }, + { + "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": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerOrderMercadoPagoPse" + } + }, + "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" + } + } + } + } + } + }, + "/customer/orders/{id}/release": { + "post": { + "operationId": "postCustomerOrdersIdRelease", + "tags": [ + "customer", + "orders" + ], + "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": [] + }, + { + "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/CustomerOrderRelease" + } + }, + "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" + } + } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/customer/orders/{id}": { + "get": { + "operationId": "getCustomerOrdersId", + "tags": [ + "customer", + "orders" + ], + "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": [] + }, + { + "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/CustomerOrderStatus" + } + }, + "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" + } + } + } + }, + "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": { + "post": { + "operationId": "postCustomerPurchaseSessions", + "tags": [ + "customer", + "purchase-sessions" + ], + "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": [] + }, + { + "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/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": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PurchaseSessionCreated" + } + }, + "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" + } + } + } + }, + "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" + } + } + } + } + } + } + }, + "/customer/purchase-sessions/{id}": { + "get": { + "operationId": "getCustomerPurchaseSessionsId", + "tags": [ + "customer", + "purchase-sessions" + ], + "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": [] + }, + { + "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/PurchaseSessionStatus" + } + }, + "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" + } + } + } + } + } + } + }, + "/customer/purchase-sessions/{id}/release": { + "post": { + "operationId": "postCustomerPurchaseSessionsIdRelease", + "tags": [ + "customer", + "purchase-sessions" + ], + "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": [] + }, + { + "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/PurchaseSessionStatus" + } + }, + "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" + } + } + } + }, + "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/videos": { + "get": { + "operationId": "getContentVideos", + "tags": [ + "content" + ], + "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": [] + }, + { + "apiKeyHeader": [] + } + ], + "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", + "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/ContentVideo" + } + }, + "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" + } + } + } + } + } + } + }, + "/content/posts": { + "get": { + "operationId": "getContentPosts", + "tags": [ + "content" + ], + "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": [] + }, + { + "apiKeyHeader": [] + } + ], + "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", + "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/ContentPost" + } + }, + "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": "postContentPosts", + "tags": [ + "content" + ], + "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": [] + }, + { + "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/ContentPostCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentPost" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "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" + } + } + } + } + } + } + }, + "/content/lives": { + "get": { + "operationId": "getContentLives", + "tags": [ + "content" + ], + "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": [] + }, + { + "apiKeyHeader": [] + } + ], + "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", + "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/ContentLive" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -11243,50 +12407,18 @@ } } } - }, - "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" - } - } - } } } } }, - "/customer/purchase-sessions/{id}": { + "/content/lives/{id}": { "get": { - "operationId": "getCustomerPurchaseSessionsId", + "operationId": "getContentLivesId", "tags": [ - "customer", - "purchase-sessions" + "content" ], - "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": "Live stream status", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -11323,7 +12455,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/PurchaseSessionStatus" + "$ref": "#/components/schemas/ContentLive" } }, "required": [ @@ -11376,15 +12508,14 @@ } } }, - "/customer/purchase-sessions/{id}/release": { + "/content/playback-token": { "post": { - "operationId": "postCustomerPurchaseSessionsIdRelease", + "operationId": "postContentPlaybackToken", "tags": [ - "customer", - "purchase-sessions" + "content" ], - "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": "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": [] @@ -11394,14 +12525,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -11412,6 +12535,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentPlaybackTokenRequest" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -11421,7 +12554,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/PurchaseSessionStatus" + "$ref": "#/components/schemas/ContentPlaybackToken" } }, "required": [ @@ -11491,18 +12624,28 @@ "$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/videos": { - "get": { - "operationId": "getContentVideos", + "/waitlist": { + "post": { + "operationId": "postWaitlist", "tags": [ - "content" + "waitlist" ], - "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": "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": [] @@ -11513,35 +12656,54 @@ ], "parameters": [ { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "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-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": "Already on this city's waitlist (`created: false`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WaitlistEntryResult" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "201": { "description": "OK", "content": { "application/json": { @@ -11549,23 +12711,26 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentVideo" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/WaitlistEntryResult" } }, "required": [ - "data", - "page" + "data" ] } } } }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "401": { "description": "Missing or invalid credential.", "content": { @@ -11605,18 +12770,37 @@ } } } + }, + "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", + "operationId": "getWaitlist", "tags": [ - "content" + "waitlist" ], - "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": "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": [] @@ -11626,6 +12810,15 @@ } ], "parameters": [ + { + "name": "city", + "in": "query", + "required": false, + "description": "City name; accents and case are ignored", + "schema": { + "type": "string" + } + }, { "name": "limit", "in": "query", @@ -11665,7 +12858,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ContentPost" + "$ref": "#/components/schemas/WaitlistEntry" } }, "page": { @@ -11721,14 +12914,16 @@ } } } - }, + } + }, + "/events/{id}/schedule": { "post": { - "operationId": "postContentPosts", + "operationId": "postEventsIdSchedule", "tags": [ - "content" + "events" ], - "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": "Schedule a draft event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nSend exactly one of:\n- `publishAt`: the DRAFT publishes itself at that instant (checked every ~5 minutes). Must be in the future and before at least one of the event's dates. The response's `publishAt` echoes it.\n- `saleStartsAt`: publishes the DRAFT now and opens sales at that instant, setting `saleStartsAt` on every ticket type of the upcoming dates in the same transaction. Must be in the future and before the first upcoming date.\n\nErrors (`error.code`):\n- 409 `EVENT_NOT_DRAFT`: only drafts can be scheduled (also when it got published concurrently).\n- 422 `SCHEDULE_IN_PAST`, 422 `SCHEDULE_AFTER_EVENT_DATE`.\n- 409 `NO_FUTURE_DATE`, 409 `NO_TICKET_TYPES`, 422 `TICKET_TYPE_SALE_CLOSES_BEFORE` (`saleStartsAt` only).\n- Seated (seats.io) events: 409 `SEATSIO_INVALID`, 409 `SEAT_MAP_CATEGORIES_UNCOVERED` (`error.details.zones[]`), 503 `SEAT_MAP_UNVERIFIABLE` (retryable) — same as `POST /events/{id}/publish`.\n- 409 `IDENTITY_VERIFICATION_REQUIRED` (`saleStartsAt` on a paid event of an unverified workspace). Unlike `POST /events/{id}/publish`, the event is NOT queued: retry after the verification is approved.", "security": [ { "apiKey": [] @@ -11738,6 +12933,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -11753,13 +12956,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ContentPostCreate" + "$ref": "#/components/schemas/EventSchedule" } } } }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -11767,7 +12970,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ContentPost" + "$ref": "#/components/schemas/Event" } }, "required": [ @@ -11777,16 +12980,6 @@ } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -11836,18 +13029,26 @@ } } } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } - } - }, - "/content/lives": { - "get": { - "operationId": "getContentLives", + }, + "delete": { + "operationId": "deleteEventsIdSchedule", "tags": [ - "content" + "events" ], - "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": "Cancel a scheduled publication", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nClears the pending scheduled publication (`publishAt` becomes null). The event keeps its status. Does not undo a `saleStartsAt` schedule: edit the ticket types' `saleStartsAt` instead.", "security": [ { "apiKey": [] @@ -11858,19 +13059,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" } @@ -11894,18 +13085,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentLive" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/Event" } }, "required": [ - "data", - "page" + "data" ] } } @@ -11954,13 +13138,13 @@ } } }, - "/content/lives/{id}": { + "/ticket-types/{id}/presale-windows": { "get": { - "operationId": "getContentLivesId", + "operationId": "getTicketTypesIdPresaleWindows", "tags": [ - "content" + "ticket-types" ], - "summary": "Live stream status", + "summary": "List a ticket type's presale windows", "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -11998,7 +13182,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ContentLive" + "type": "array", + "items": { + "$ref": "#/components/schemas/PresaleWindow" + } } }, "required": [ @@ -12049,16 +13236,14 @@ } } } - } - }, - "/content/playback-token": { + }, "post": { - "operationId": "postContentPlaybackToken", + "operationId": "postTicketTypesIdPresaleWindows", "tags": [ - "content" + "ticket-types" ], - "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.", + "summary": "Create a presale window", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nActive members of `planId` can buy this ticket type between `presaleStartsAt` and `presaleEndsAt` (instants in UTC), optionally capped by `presaleCapacity`. One window per plan and ticket type.\n\nErrors (`error.code`): 422 `PLAN_NOT_ELIGIBLE` (the plan is not an active plan of the workspace that owns the event), 422 `PRESALE_WINDOW_INVERTED` (end not after start), 409 `DUPLICATE_PLAN` (that plan already has a window on this ticket type), 403 `EVENT_SCOPE_FORBIDDEN` (key restricted to other events).", "security": [ { "apiKey": [] @@ -12068,6 +13253,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -12083,13 +13276,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ContentPlaybackTokenRequest" + "$ref": "#/components/schemas/PresaleWindowCreate" } } } }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -12097,7 +13290,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ContentPlaybackToken" + "$ref": "#/components/schemas/PresaleWindow" } }, "required": [ @@ -12137,39 +13330,18 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "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.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -12181,14 +13353,14 @@ } } }, - "/waitlist": { - "post": { - "operationId": "postWaitlist", + "/presale-windows/{id}": { + "patch": { + "operationId": "patchPresaleWindowsId", "tags": [ - "waitlist" + "ticket-types" ], - "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.", + "summary": "Update a presale window", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nAbsent fields are left untouched; the start/end order is checked against the stored values.\n\nErrors (`error.code`): 422 `PLAN_NOT_ELIGIBLE` (the plan is not an active plan of the workspace that owns the event), 422 `PRESALE_WINDOW_INVERTED` (end not after start), 409 `DUPLICATE_PLAN` (that plan already has a window on this ticket type), 403 `EVENT_SCOPE_FORBIDDEN` (key restricted to other events).", "security": [ { "apiKey": [] @@ -12199,19 +13371,18 @@ ], "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).", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } }, { - "name": "X-Customer-Session", + "name": "X-Workspace-Id", "in": "header", "required": false, - "description": "Optional buyer session token; links the entry to that buyer.", + "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" } @@ -12222,31 +13393,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WaitlistEntryCreate" + "$ref": "#/components/schemas/PresaleWindowUpdate" } } } }, "responses": { "200": { - "description": "Already on this city's waitlist (`created: false`).", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/WaitlistEntryResult" - } - }, - "required": [ - "data" - ] - } - } - } - }, - "201": { "description": "OK", "content": { "application/json": { @@ -12254,7 +13407,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/WaitlistEntryResult" + "$ref": "#/components/schemas/PresaleWindow" } }, "required": [ @@ -12264,16 +13417,6 @@ } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -12304,8 +13447,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -12314,36 +13457,25 @@ } } }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "422": { + "description": "Request body/parameter validation failed.", "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" - } } } } }, - "get": { - "operationId": "getWaitlist", + "delete": { + "operationId": "deletePresaleWindowsId", "tags": [ - "waitlist" + "ticket-types" ], - "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).", + "summary": "Delete a presale window", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nDESTRUCTIVE: permanently deletes the window; members lose that presale access immediately. Re-creating it yields a new id.", "security": [ { "apiKey": [] @@ -12352,30 +13484,12 @@ "apiKeyHeader": [] } ], + "x-ft-destructive": true, "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": "cursor", - "in": "query", - "required": false, + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -12396,22 +13510,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/WaitlistEntry" - } - }, - "page": { - "$ref": "#/components/schemas/Page" - } - }, - "required": [ - "data", - "page" - ] + "type": "object" } } } @@ -13152,17 +14251,63 @@ } ] }, - "venue": { + "venue": { + "anyOf": [ + { + "$ref": "#/components/schemas/Venue" + }, + { + "type": "null" + } + ] + }, + "externalTicketUrl": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "access": { + "type": "string", + "enum": [ + "owner", + "artist" + ], + "description": "owner = the key's workspace owns the event (editable). artist = read-only: linked artist or catalog access." + }, + "nextDate": { + "anyOf": [ + { + "$ref": "#/components/schemas/EventNextDate" + }, + { + "type": "null" + } + ] + }, + "artists": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EventArtist" + } + }, + "publishAt": { + "description": "Scheduled publication instant (ISO 8601, UTC) of a DRAFT event; null = not scheduled. See `POST /events/{id}/schedule`.", "anyOf": [ { - "$ref": "#/components/schemas/Venue" + "type": "string" }, { "type": "null" } ] }, - "externalTicketUrl": { + "pulepCode": { + "description": "PULEP registration code (Colombian Ministry of Culture). Required for performing-arts events with capacity above 400.", "anyOf": [ { "type": "string" @@ -13172,30 +14317,21 @@ } ] }, - "access": { - "type": "string", - "enum": [ - "owner", - "artist" - ], - "description": "owner = the key's workspace owns the event (editable). artist = read-only: linked artist or catalog access." + "listedOnPortal": { + "description": "false = hidden from portal discovery (listings, search, home); still reachable by direct link.", + "type": "boolean" }, - "nextDate": { + "genreOther": { + "description": "Free-text event type, only when the genre is \"otro\".", "anyOf": [ { - "$ref": "#/components/schemas/EventNextDate" + "type": "string" }, { "type": "null" } ] }, - "artists": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EventArtist" - } - }, "createdAt": { "type": "string" }, @@ -13516,6 +14652,19 @@ "streamType": { "type": "string" }, + "maxPerCustomer": { + "description": "Cumulative per-buyer cap across ALL ticket types of this date. null = no date-level cap (each ticket type's own cap applies).", + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, "createdAt": { "type": "string" } @@ -13644,6 +14793,116 @@ "type": "null" } ] + }, + "slug": { + "description": "Public URL slug. Must be unique across live events (409 `SLUG_TAKEN`).", + "type": "string", + "minLength": 1, + "maxLength": 100, + "pattern": "^[a-z0-9-]+$" + }, + "squareImageUrl": { + "anyOf": [ + { + "type": "string", + "format": "uri" + }, + { + "type": "null" + } + ] + }, + "storyImageUrl": { + "anyOf": [ + { + "type": "string", + "format": "uri" + }, + { + "type": "null" + } + ] + }, + "pulepCode": { + "description": "PULEP code. Required (422 `PULEP_REQUIRED`) when the event is performing arts (or has no genre) and its capacity per date exceeds 400.", + "anyOf": [ + { + "type": "string", + "maxLength": 50 + }, + { + "type": "null" + } + ] + }, + "listedOnPortal": { + "type": "boolean" + }, + "genre": { + "description": "Event type from the taxonomy.", + "type": "string", + "enum": [ + "comedia", + "musica", + "teatro", + "danza", + "cultura", + "familiar", + "fiesta", + "deporte", + "conferencia", + "otro" + ] + }, + "subgenre": { + "description": "Subtype; must belong to `genre`, which must be sent in the same request. null = no subtype.", + "anyOf": [ + { + "type": "string", + "enum": [ + "stand_up", + "impro", + "sketch", + "satira", + "rock", + "indie", + "pop", + "urbano", + "salsa", + "vallenato", + "electronica", + "tributo", + "opera", + "musical" + ] + }, + { + "type": "null" + } + ] + }, + "genreOther": { + "description": "Free-text type. Required when `genre` is \"otro\".", + "type": "string", + "minLength": 1, + "maxLength": 60 + }, + "audience": { + "description": "Minimum age classification. null = unspecified.", + "anyOf": [ + { + "type": "string", + "enum": [ + "todo_publico", + "mayores_14", + "mayores_18", + "infantil" + ] + }, + { + "type": "null" + } + ] } }, "additionalProperties": false @@ -13714,6 +14973,18 @@ "ONLINE", "HIBRIDO" ] + }, + "maxPerCustomer": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 10000 + }, + { + "type": "null" + } + ] } }, "required": [ @@ -13796,6 +15067,18 @@ "CANCELLED", "COMPLETED" ] + }, + "maxPerCustomer": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 10000 + }, + { + "type": "null" + } + ] } }, "additionalProperties": false @@ -13881,94 +15164,243 @@ } }, "required": [ - "eventDateId", - "name", - "price", - "currency", - "capacity", - "maxPerOrder", - "isVisible", - "organizerAbsorbsFee" + "eventDateId", + "name", + "price", + "currency", + "capacity", + "maxPerOrder", + "isVisible", + "organizerAbsorbsFee" + ], + "additionalProperties": false + }, + "TicketTypeUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "description": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "price": { + "type": "number", + "minimum": 0 + }, + "currency": { + "description": "Solo COP; se tolera la moneda ya guardada si no cambia.", + "type": "string", + "minLength": 3, + "maxLength": 3 + }, + "capacity": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "maxPerOrder": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "isVisible": { + "type": "boolean" + }, + "organizerAbsorbsFee": { + "type": "boolean" + }, + "saleStartsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "saleEndsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "seatsioCategoryKey": { + "anyOf": [ + { + "type": "string", + "minLength": 1 + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false + }, + "EventSchedule": { + "type": "object", + "properties": { + "publishAt": { + "description": "Publish the DRAFT automatically at this instant (UTC). Must be in the future and before at least one of its dates.", + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + }, + "saleStartsAt": { + "description": "Publish the DRAFT NOW and open ticket sales at this instant (UTC): sets `saleStartsAt` on every ticket type of the upcoming dates. Must be in the future and before the first upcoming date.", + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + } + }, + "additionalProperties": false + }, + "PresaleWindow": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "ticketTypeId": { + "type": "string" + }, + "planId": { + "type": "string", + "description": "Membership plan whose active members get early access." + }, + "presaleStartsAt": { + "type": "string" + }, + "presaleEndsAt": { + "type": "string" + }, + "presaleCapacity": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ], + "description": "Sub-cap of tickets sellable during the presale. null = shares the ticket type's whole capacity." + }, + "isActive": { + "type": "boolean" + }, + "createdAt": { + "type": "string" + }, + "updatedAt": { + "type": "string" + } + }, + "required": [ + "id", + "ticketTypeId", + "planId", + "presaleStartsAt", + "presaleEndsAt", + "presaleCapacity", + "isActive", + "createdAt", + "updatedAt" ], "additionalProperties": false }, - "TicketTypeUpdate": { + "PresaleWindowCreate": { "type": "object", "properties": { - "name": { + "planId": { "type": "string", "minLength": 1 }, - "description": { + "presaleStartsAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + }, + "presaleEndsAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + }, + "presaleCapacity": { "anyOf": [ { - "type": "string" + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "price": { - "type": "number", - "minimum": 0 - }, - "currency": { - "description": "Solo COP; se tolera la moneda ya guardada si no cambia.", - "type": "string", - "minLength": 3, - "maxLength": 3 - }, - "capacity": { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 - }, - "maxPerOrder": { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 - }, - "isVisible": { + "isActive": { + "default": true, "type": "boolean" + } + }, + "required": [ + "planId", + "presaleStartsAt", + "presaleEndsAt" + ], + "additionalProperties": false + }, + "PresaleWindowUpdate": { + "type": "object", + "properties": { + "planId": { + "type": "string", + "minLength": 1 }, - "organizerAbsorbsFee": { - "type": "boolean" + "presaleStartsAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, - "saleStartsAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } - ] + "presaleEndsAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, - "saleEndsAt": { + "presaleCapacity": { "anyOf": [ { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "seatsioCategoryKey": { - "anyOf": [ - { - "type": "string", - "minLength": 1 - }, - { - "type": "null" - } - ] + "isActive": { + "type": "boolean" } }, "additionalProperties": false @@ -15859,6 +17291,148 @@ ], "additionalProperties": false }, + "SaleItemTransferRequest": { + "type": "object", + "properties": { + "email": { + "type": "string", + "maxLength": 254, + "format": "email", + "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + } + }, + "required": [ + "email" + ], + "additionalProperties": false + }, + "SaleItemTransfer": { + "type": "object", + "properties": { + "saleId": { + "type": "string" + }, + "itemId": { + "type": "string" + }, + "ticketCode": { + "type": "string", + "description": "New ticket code (the previous QR is void)." + }, + "holderName": { + "type": "string" + }, + "holderEmail": { + "type": "string" + }, + "transferredAt": { + "type": "string" + } + }, + "required": [ + "saleId", + "itemId", + "ticketCode", + "holderName", + "holderEmail", + "transferredAt" + ], + "additionalProperties": false + }, + "CourtesyRecipientUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 2, + "maxLength": 120 + }, + "email": { + "type": "string", + "maxLength": 254, + "format": "email", + "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + } + }, + "required": [ + "name", + "email" + ], + "additionalProperties": false + }, + "CourtesyRecipient": { + "type": "object", + "properties": { + "saleId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + }, + "resent": { + "type": "boolean" + }, + "ticketCodesRotated": { + "type": "boolean", + "description": "true when the email changed: the previous QR codes are void (transferred tickets keep theirs)." + } + }, + "required": [ + "saleId", + "name", + "email", + "resent", + "ticketCodesRotated" + ], + "additionalProperties": false + }, + "CourtesySeats": { + "type": "object", + "properties": { + "eventDateId": { + "type": "string" + }, + "eventId": { + "type": "string" + }, + "ticketTypes": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ticketTypeId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "labels": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Blocked seat labels of this ticket type's category that no live sale claims, in natural order." + } + }, + "required": [ + "ticketTypeId", + "name", + "labels" + ], + "additionalProperties": false + } + } + }, + "required": [ + "eventDateId", + "eventId", + "ticketTypes" + ], + "additionalProperties": false + }, "ReportByEventRow": { "type": "object", "properties": { @@ -16976,6 +18550,45 @@ }, "additionalProperties": false }, + "CheckinUndoResult": { + "type": "object", + "properties": { + "ticketCode": { + "type": "string" + }, + "undone": { + "type": "boolean", + "description": "true when this call reverted the check-in; false when the ticket was not checked in (idempotent no-op)." + }, + "previousCheckedInAt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "previousCheckedInBy": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "ticketCode", + "undone", + "previousCheckedInAt", + "previousCheckedInBy" + ], + "additionalProperties": false + }, "TicketAccess": { "type": "object", "properties": { diff --git a/src/commands/ops.test.ts b/src/commands/ops.test.ts new file mode 100644 index 0000000..436bf61 --- /dev/null +++ b/src/commands/ops.test.ts @@ -0,0 +1,149 @@ +import { Command } from "commander"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const sdk = vi.hoisted(() => ({ + postEventsIdSchedule: vi.fn(), + patchPresaleWindowsId: vi.fn(), + postTicketTypesIdPresaleWindows: vi.fn(), + postSalesIdItemsItemIdTransfer: vi.fn(), + getEventDatesIdCourtesySeats: vi.fn(), +})); + +vi.mock("../client/sdk.gen", async (importOriginal) => ({ + ...(await importOriginal()), + ...sdk, +})); + +vi.mock("../lib/api", async (importOriginal) => ({ + ...(await importOriginal()), + configureClient: vi.fn(), +})); + +const ops = await import("./ops"); + +const ok = (data: unknown) => ({ data: { data }, response: new Response() }); + +function run(...args: string[]) { + const program = new Command().exitOverride(); + ops.registerEventSchedule(program.command("events")); + ops.registerPresaleWindows(program); + ops.registerSaleOps(program.command("sales")); + ops.registerCourtesySeats(program.command("event-dates")); + return program.parseAsync(["node", "ft", ...args]); +} + +beforeEach(() => { + 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); + for (const fn of Object.values(sdk)) fn.mockResolvedValue(ok({})); +}); + +afterEach(() => { + vi.restoreAllMocks(); + for (const fn of Object.values(sdk)) fn.mockReset(); +}); + +describe("ft events schedule set", () => { + it("sends only publishAt", async () => { + await run( + "events", + "schedule", + "set", + "evt_1", + "--publish-at", + "2027-01-01T00:00:00Z", + ); + expect(sdk.postEventsIdSchedule).toHaveBeenCalledWith({ + path: { id: "evt_1" }, + body: { publishAt: "2027-01-01T00:00:00Z" }, + }); + }); + + it.each([ + [[]], + [ + [ + "--publish-at", + "2027-01-01T00:00:00Z", + "--sale-starts-at", + "2027-01-02T00:00:00Z", + ], + ], + ])("rejects %j: exactly one flag is required", async (flags) => { + await expect( + run("events", "schedule", "set", "evt_1", ...flags), + ).rejects.toThrow("exited"); + expect(sdk.postEventsIdSchedule).not.toHaveBeenCalled(); + }); +}); + +describe("ft presale-windows", () => { + it("create maps flags to the contract body", async () => { + await run( + "presales", + "create", + "tt_1", + "--plan", + "plan_1", + "--starts-at", + "2027-01-01T00:00:00Z", + "--ends-at", + "2027-01-02T00:00:00Z", + "--capacity", + "50", + ); + expect(sdk.postTicketTypesIdPresaleWindows).toHaveBeenCalledWith({ + path: { id: "tt_1" }, + body: { + planId: "plan_1", + presaleStartsAt: "2027-01-01T00:00:00Z", + presaleEndsAt: "2027-01-02T00:00:00Z", + presaleCapacity: 50, + }, + }); + }); + + it("update sends only the flags passed; --capacity none clears the cap", async () => { + await run( + "presale-windows", + "update", + "pw_1", + "--capacity", + "none", + "--active", + "false", + ); + expect(sdk.patchPresaleWindowsId).toHaveBeenCalledWith({ + path: { id: "pw_1" }, + body: { presaleCapacity: null, isActive: false }, + }); + }); +}); + +it("ft sales transfer --yes sends the recipient email", async () => { + await run( + "sales", + "transfer", + "sale_1", + "item_1", + "--email", + "a@b.co", + "--yes", + ); + expect(sdk.postSalesIdItemsItemIdTransfer).toHaveBeenCalledWith({ + path: { id: "sale_1", itemId: "item_1" }, + body: { email: "a@b.co" }, + }); +}); + +it("ft event-dates courtesy-seats reads the date", async () => { + sdk.getEventDatesIdCourtesySeats.mockResolvedValue(ok({ ticketTypes: [] })); + await run("event-dates", "courtesy-seats", "date_1", "--json"); + expect(sdk.getEventDatesIdCourtesySeats).toHaveBeenCalledWith({ + path: { id: "date_1" }, + }); +}); diff --git a/src/commands/ops.ts b/src/commands/ops.ts new file mode 100644 index 0000000..85ec9d1 --- /dev/null +++ b/src/commands/ops.ts @@ -0,0 +1,270 @@ +import type { Command } from "commander"; +import { + deleteEventsIdSchedule, + deletePresaleWindowsId, + deleteTicketsTicketCodeCheckin, + getEventDatesIdCourtesySeats, + getTicketTypesIdPresaleWindows, + patchPresaleWindowsId, + patchSalesIdRecipient, + postEventsIdSchedule, + postSalesIdItemsItemIdTransfer, + postTicketTypesIdPresaleWindows, +} from "../client/sdk.gen"; +import { configureClient, fail, unwrap } from "../lib/api"; +import { confirmOrExit } from "../lib/input"; +import { print } from "../lib/output"; + +/** + * Dashboard-parity operations from contract 1.25.0: scheduled publication, + * presale windows, ticket transfer, check-in undo, courtesy recipient and + * courtesy seats. Each hooks into the family it belongs to (`ft events`, + * `ft sales`, `ft tickets`, `ft event-dates`) because their paths take + * nested ids or no body that registerResource could model. + */ + +const PRESALE_COLUMNS = [ + "id", + "planId", + "presaleStartsAt", + "presaleEndsAt", + "presaleCapacity", + "isActive", +]; + +/** Presale window body from flags; only the flags passed are sent. */ +function presaleBody(opts: Record) { + const body: Record = {}; + if (opts.plan) body.planId = opts.plan; + if (opts.startsAt) body.presaleStartsAt = opts.startsAt; + if (opts.endsAt) body.presaleEndsAt = opts.endsAt; + if (opts.capacity !== undefined) + body.presaleCapacity = + opts.capacity === "none" ? null : Number(opts.capacity); + if (opts.active !== undefined) body.isActive = opts.active === "true"; + return body; +} + +/** `ft events schedule set|clear ` */ +export function registerEventSchedule(events: Command): void { + const schedule = events + .command("schedule") + .description("Scheduled publication of a draft event"); + + schedule + .command("set ") + .description( + "Schedule a DRAFT: --publish-at publishes it later; --sale-starts-at publishes now and opens sales later (exactly one)", + ) + .option("--publish-at ", "publish automatically at this UTC instant") + .option( + "--sale-starts-at ", + "publish now; open sales on every upcoming ticket type at this UTC instant", + ) + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, opts) => { + if (!opts.publishAt === !opts.saleStartsAt) + fail("Pass exactly one of --publish-at or --sale-starts-at."); + configureClient(opts.workspace); + const body = unwrap( + await postEventsIdSchedule({ + path: { id: eventId }, + body: opts.publishAt + ? { publishAt: opts.publishAt } + : { saleStartsAt: opts.saleStartsAt }, + }), + ); + print(body.data, { json: opts.json }); + }); + + schedule + .command("clear ") + .description( + "Cancel a pending --publish-at (does not undo --sale-starts-at: edit the ticket types)", + ) + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await deleteEventsIdSchedule({ path: { id: eventId } }), + ); + print(body.data, { json: opts.json }); + }); +} + +/** `ft presale-windows list|create|update|delete` (alias `presales`). */ +export function registerPresaleWindows(program: Command): void { + const root = program + .command("presale-windows") + .alias("presales") + .description( + "Membership presale windows on a ticket type (one window per plan)", + ); + + root + .command("list ") + .description("List a ticket type's presale windows") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (ticketTypeId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await getTicketTypesIdPresaleWindows({ path: { id: ticketTypeId } }), + ); + print(body.data, { json: opts.json, columns: PRESALE_COLUMNS }); + }); + + root + .command("create ") + .description("Open a presale window for the members of one plan") + .requiredOption("--plan ", "membership plan of this workspace") + .requiredOption("--starts-at ", "presale start (UTC)") + .requiredOption("--ends-at ", "presale end (UTC, after start)") + .option("--capacity ", "max tickets sold in the presale") + .option("--active ", "true | false (default true)") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (ticketTypeId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await postTicketTypesIdPresaleWindows({ + path: { id: ticketTypeId }, + body: presaleBody(opts) as never, + }), + ); + print(body.data, { json: opts.json }); + }); + + root + .command("update ") + .description("Edit a presale window (only the flags passed change)") + .option("--plan ", "membership plan of this workspace") + .option("--starts-at ", "presale start (UTC)") + .option("--ends-at ", "presale end (UTC)") + .option("--capacity ", 'max tickets, or "none" to remove the cap') + .option("--active ", "true | false") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (windowId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await patchPresaleWindowsId({ + path: { id: windowId }, + body: presaleBody(opts), + }), + ); + print(body.data, { json: opts.json }); + }); + + root + .command("delete ") + .description("Delete a presale window (members lose that access now)") + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (windowId, opts) => { + await confirmOrExit(`Delete presale window ${windowId}?`, opts.yes); + configureClient(opts.workspace); + const body = unwrap( + await deletePresaleWindowsId({ path: { id: windowId } }), + ); + print(body.data, { json: opts.json }); + }); +} + +/** `ft sales transfer` and `ft sales recipient set`. */ +export function registerSaleOps(sales: Command): void { + sales + .command("transfer ") + .description( + "Transfer one ticket to a registered buyer (voids the old QR; once per ticket, until the show starts)", + ) + .requiredOption("--email ", "recipient's verified FreeTicket email") + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (saleId, itemId, opts) => { + await confirmOrExit( + `Transfer ticket ${itemId} of sale ${saleId} to ${opts.email}? The current QR stops working.`, + opts.yes, + ); + configureClient(opts.workspace); + const body = unwrap( + await postSalesIdItemsItemIdTransfer({ + path: { id: saleId, itemId }, + body: { email: opts.email }, + }), + ); + print(body.data, { json: opts.json }); + }); + + sales + .command("recipient") + .description("Recipient of a courtesy sale") + .command("set ") + .description( + "Correct a courtesy's recipient and resend its tickets (a new email voids the old QRs)", + ) + .requiredOption("--name ", "recipient name") + .requiredOption("--email ", "recipient email") + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (saleId, opts) => { + await confirmOrExit( + `Set the recipient of courtesy ${saleId} to ${opts.name} <${opts.email}> and resend? If the email changes, the QRs already sent stop working.`, + opts.yes, + ); + configureClient(opts.workspace); + const body = unwrap( + await patchSalesIdRecipient({ + path: { id: saleId }, + body: { name: opts.name, email: opts.email }, + }), + ); + print(body.data, { json: opts.json }); + }); +} + +/** `ft tickets checkin-undo ` */ +export function registerCheckinUndo(tickets: Command): void { + tickets + .command("checkin-undo ") + .description( + "Undo a door check-in so the ticket is valid again (ADMIN; idempotent)", + ) + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (code, opts) => { + await confirmOrExit(`Undo the check-in of ticket ${code}?`, opts.yes); + configureClient(opts.workspace); + const body = unwrap( + await deleteTicketsTicketCodeCheckin({ path: { ticketCode: code } }), + ); + print(body.data, { json: opts.json }); + }); +} + +/** `ft event-dates courtesy-seats ` */ +export function registerCourtesySeats(eventDates: Command): void { + eventDates + .command("courtesy-seats ") + .description( + "Blocked seats of a numbered date that can be issued as courtesies", + ) + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (dateId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await getEventDatesIdCourtesySeats({ path: { id: dateId } }), + ); + print(opts.json ? body.data : body.data.ticketTypes, { + json: opts.json, + columns: ["ticketTypeId", "name", "labels"], + }); + }); +} diff --git a/src/destructive-confirm.test.ts b/src/destructive-confirm.test.ts index ac3ecd2..603dc05 100644 --- a/src/destructive-confirm.test.ts +++ b/src/destructive-confirm.test.ts @@ -1,3 +1,4 @@ +import { readFileSync } from "node:fs"; import { afterEach, beforeEach, @@ -19,6 +20,10 @@ const sdk = vi.hoisted(() => ({ deleteWorkspacesId: vi.fn(), deleteEventsIdArtistsOrganizationId: vi.fn(), deleteEventsIdArtistInvitationsInvitationId: vi.fn(), + deletePresaleWindowsId: vi.fn(), + postSalesIdItemsItemIdTransfer: vi.fn(), + patchSalesIdRecipient: vi.fn(), + deleteTicketsTicketCodeCheckin: vi.fn(), })); vi.mock("./client/sdk.gen", async (importOriginal) => ({ @@ -28,6 +33,10 @@ vi.mock("./client/sdk.gen", async (importOriginal) => ({ deleteEventsIdArtistsOrganizationId: sdk.deleteEventsIdArtistsOrganizationId, deleteEventsIdArtistInvitationsInvitationId: sdk.deleteEventsIdArtistInvitationsInvitationId, + deletePresaleWindowsId: sdk.deletePresaleWindowsId, + postSalesIdItemsItemIdTransfer: sdk.postSalesIdItemsItemIdTransfer, + patchSalesIdRecipient: sdk.patchSalesIdRecipient, + deleteTicketsTicketCodeCheckin: sdk.deleteTicketsTicketCodeCheckin, })); vi.mock("./admin-client/sdk.gen", async (importOriginal) => ({ @@ -62,19 +71,7 @@ describe("destructive commands refuse without a TTY and without --yes", () => { for (const fn of Object.values(sdk)) fn.mockReset(); }); - it.each([ - [["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) => { + it.each(CASES)("ft %j exits 1 and never calls the SDK", async (args, fn) => { await expect( program.parseAsync(["node", "ft", ...(args as string[])]), ).rejects.toThrow("exited"); @@ -83,4 +80,51 @@ describe("destructive commands refuse without a TTY and without --yes", () => { expect(stderr.mock.calls[0]?.[0]).toMatch(/^Refusing: .*no TTY to confirm/); expect(fn).not.toHaveBeenCalled(); }); + + it("covers every operation the contract marks x-ft-destructive", () => { + const spec = JSON.parse(readFileSync("openapi.json", "utf8")); + const destructive = Object.values(spec.paths).flatMap((ops) => + Object.values(ops as Record>) + .filter((op) => op?.["x-ft-destructive"] === true) + .map((op) => op.operationId as string), + ); + const gated = Object.entries(sdk) + .filter(([, fn]) => CASES.some(([, f]) => f === fn)) + .map(([name]) => name); + expect(destructive.length).toBeGreaterThan(0); + expect(destructive.filter((id) => !gated.includes(id))).toEqual([]); + }); }); + +const CASES: [string[], (typeof sdk)[keyof typeof sdk]][] = [ + [["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, + ], + [["presale-windows", "delete", "pw_1"], sdk.deletePresaleWindowsId], + [ + ["sales", "transfer", "sale_1", "item_1", "--email", "a@b.co"], + sdk.postSalesIdItemsItemIdTransfer, + ], + [ + [ + "sales", + "recipient", + "set", + "sale_1", + "--name", + "Ana", + "--email", + "a@b.co", + ], + sdk.patchSalesIdRecipient, + ], + [["tickets", "checkin-undo", "TKT1"], sdk.deleteTicketsTicketCodeCheckin], +]; diff --git a/src/program.ts b/src/program.ts index 6c9f5ec..11f6ef1 100644 --- a/src/program.ts +++ b/src/program.ts @@ -65,6 +65,13 @@ import { registerApiKeys } from "./commands/api-keys"; import { registerAuth } from "./commands/auth"; import { registerEventDates } from "./commands/event-dates"; import { registerArtists, registerEventLineup } from "./commands/lineup"; +import { + registerCheckinUndo, + registerCourtesySeats, + registerEventSchedule, + registerPresaleWindows, + registerSaleOps, +} from "./commands/ops"; import { registerReports } from "./commands/reports"; import { registerResource } from "./commands/resource"; import { registerTickets } from "./commands/tickets"; @@ -131,7 +138,10 @@ registerResource(program, { query: "withTotal", }, ], - extend: registerEventLineup, + extend: (root) => { + registerEventLineup(root); + registerEventSchedule(root); + }, }); registerArtists(program); @@ -246,6 +256,7 @@ registerResource(program, { }, { flag: "--to ", describe: "created to (ISO 8601)", query: "to" }, ], + extend: registerSaleOps, }); registerResource(program, { @@ -413,7 +424,14 @@ registerResource(program, { }, }); +registerPresaleWindows(program); + registerTickets(program); +// Commands added to existing families (contract 1.25.0, see commands/ops.ts). +const family = (name: string) => + program.commands.find((c) => c.name() === name) as Command; +registerCheckinUndo(family("tickets")); +registerCourtesySeats(family("event-dates")); registerReports(program); registerApiKeys(program); registerAdmin(program); From cb636e4cf3ff94f9aa576294e84e7b5aa3966d62 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 21:29:42 +0000 Subject: [PATCH 3/4] feat: commands for B2B contract 1.36.0 Covers the operations added between 1.24.0 and 1.36.0 on top of the lineup (#52) and dashboard-parity ops: viewers/validators, staff access and resend-invite, access-close, sales abandon and intents, live attendance, master QRs, ticket templates, community management (posts, videos, series, lives, channels, meetups, moderation), products, organization/profile, website and the merch catalog. Destructive operations and the ones that send email or notify a whole community ask for confirmation (--yes skips it, no TTY refuses). The destructive-confirm test now covers all 26 x-ft-destructive operations, and wire.test.ts checks method, path and body of the riskiest commands against the real SDK. Buyer-side merch checkout is left out. Consolidates the lineup and p1-ops changesets into one minor. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Fo7cm7S4yTPG5LztA8pEVi --- .changeset/contract-1-36.md | 14 ++ .changeset/lineup-artists.md | 5 - .changeset/p1-ops.md | 5 - README.md | 19 ++ src/commands/box-office.ts | 285 +++++++++++++++++++++++++ src/commands/community.ts | 315 ++++++++++++++++++++++++++++ src/commands/op.ts | 90 ++++++++ src/commands/storefront.ts | 128 ++++++++++++ src/commands/wire.test.ts | 355 ++++++++++++++++++++++++++++++++ src/destructive-confirm.test.ts | 98 ++++++++- src/program.ts | 163 ++++++++++++++- 11 files changed, 1455 insertions(+), 22 deletions(-) create mode 100644 .changeset/contract-1-36.md delete mode 100644 .changeset/lineup-artists.md delete mode 100644 .changeset/p1-ops.md create mode 100644 src/commands/box-office.ts create mode 100644 src/commands/community.ts create mode 100644 src/commands/op.ts create mode 100644 src/commands/storefront.ts create mode 100644 src/commands/wire.test.ts diff --git a/.changeset/contract-1-36.md b/.changeset/contract-1-36.md new file mode 100644 index 0000000..cd8c42b --- /dev/null +++ b/.changeset/contract-1-36.md @@ -0,0 +1,14 @@ +--- +"@freeticket/cli": minor +--- + +Catch up with the B2B contract 1.36.0 (from 1.24.0). + +- **Lineup**: `ft artists search`, `ft events artists set|remove` and `ft events invitations list|resend|cancel`. `set` asks before removing anyone from the lineup and prints `ARTIST_IDS_IGNORED` warnings. +- **Scheduling and presales**: `ft events schedule set|clear` and `ft presale-windows list|create|update|delete` (alias `presales`). +- **Box office and door**: `ft sales transfer`, `ft sales recipient set`, `ft sales abandon`, `ft sales intents` (checkout funnel), `ft tickets checkin-undo`, `ft event-dates courtesy-seats`, `ft event-dates access-close status|sign`, `ft reports live-attendance`, `ft master-qrs` (with `activate`/`deactivate`; the table hides the secret `code`/`url` unless `--full`) and `ft ticket-templates` (with `instantiate`). +- **Access**: `ft events viewers list|add|remove`, `ft events validators list|add`, `ft staff access` (full replace, from flags or `--data`) and `ft staff resend-invite`. +- **Community**: `ft content-posts update|delete|pin|unpin`, `ft content-videos update|delete|publish|unpublish|set-series`, `ft content-series`, `ft content-lives create|update|delete|chat|reset-key`, `ft content-channels`, `ft content-meetups` (with `publish`, `cancel`, `rsvp`, `attendance`), `ft content-moderation`, `ft content-comments` and `ft content-members ban|unban`. +- **Workspace**: `ft products`, `ft organization update|analytics|profile`, `ft website get|set|publish|unpublish` and `ft merch catalog`. + +Every operation the contract marks `x-ft-destructive`, and every command that sends email or notifies a whole community (viewer/validator invitations, resend-invite, meetup publish and RSVP decisions), asks for confirmation; `--yes` skips it and without a TTY they refuse. A test fails if a destructive operation of the contract has no such gate. The buyer side of the merch store (place an order, look one up, pay it by card) is left out on purpose: it needs the buyer's session and a Payment Brick token. diff --git a/.changeset/lineup-artists.md b/.changeset/lineup-artists.md deleted file mode 100644 index 92cd258..0000000 --- a/.changeset/lineup-artists.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@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/.changeset/p1-ops.md b/.changeset/p1-ops.md deleted file mode 100644 index f401192..0000000 --- a/.changeset/p1-ops.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@freeticket/cli": minor ---- - -Dashboard-parity operations (contract 1.25.0): `ft events schedule set|clear`, `ft presale-windows list|create|update|delete` (alias `presales`), `ft sales transfer`, `ft sales recipient set`, `ft tickets checkin-undo` and `ft event-dates courtesy-seats`. Transfer, recipient, check-in undo and presale delete ask for confirmation (`--yes` skips it); a test now fails if any `x-ft-destructive` operation in the contract lacks that gate. New `events update` fields (slug, PULEP, portal visibility, images, genre) and `maxPerCustomer` on dates go through `--data`. diff --git a/README.md b/README.md index 7fdea85..08d3444 100644 --- a/README.md +++ b/README.md @@ -100,8 +100,13 @@ ft sales list --status CONFIRMED --json | `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 events schedule set --publish-at ` \| `--sale-starts-at ` · `schedule clear ` | Schedule a DRAFT: publish later, or publish now and open sales later (exactly one flag) · cancel a pending `--publish-at` | ADMIN | +| `ft events viewers list ` · `add --email ` · `remove ` | Read-only viewers of an event's stats; `add` emails the link (and creates a VIEWER account if needed), both `add` and `remove` ask (`--yes`) | ADMIN | +| `ft events validators list ` · `add --name --email ` | Door staff of an event (additive; a new account gets an invitation email, so `add` asks, `--yes`) | ADMIN | | `ft event-dates list` · `create` · `update` · `delete` | Event dates | ADMIN | | `ft event-dates courtesy-seats ` | Blocked seats of a numbered date that can be issued as courtesies | ADMIN | +| `ft event-dates access-close status ` · `sign ` | Live entry count · sign the access-close record (freezes the count and emails it; IRREVERSIBLE, `--yes`) | STAFF · ADMIN | +| `ft ticket-templates list` · `create` · `update ` · `delete ` · `instantiate --event-date [--name --price --capacity]` | Reusable ticket type templates; `instantiate` creates a ticket type on a date (`delete` asks, `--yes`) | ADMIN | +| `ft master-qrs list [--full]` · `create` · `update ` · `activate ` · `deactivate ` · `delete ` | Master box-office QRs (`code`/`url` are secret: the table hides them unless `--full`; `delete` asks, `--yes`) | ADMIN | | `ft ticket-types list` · `get ` | Ticket types (`--event-date-id`) | VIEWER | | `ft ticket-types create` · `update ` · `delete ` | Manage ticket types (`--data `) | ADMIN | | `ft presale-windows list ` · `create --plan --starts-at --ends-at [--capacity --active]` · `update ` · `delete ` | Membership presale windows (alias `presales`; one per plan; `delete` asks, `--yes` skips) | ADMIN | @@ -111,6 +116,8 @@ ft sales list --status CONFIRMED --json | `ft sales tickets ` · `attempts ` | Tickets/attendees of a sale · its payment attempt history (why it did not go through) | STAFF | | `ft sales transfer --email ` | Transfer one ticket to a registered buyer; voids the old QR, once per ticket (`--yes`) | ADMIN | | `ft sales recipient set --name --email ` | Correct a courtesy's recipient and resend (a new email voids the old QRs; `--yes`) | ADMIN | +| `ft sales abandon ` | Mark a PENDING sale whose payment never started as abandoned; releases its stock (terminal, `--yes`) | ADMIN | +| `ft sales intents --event [--event-date --only-abandoned --limit --cursor]` | Purchase intents: checkout funnel and abandoned journeys (personal data) | VIEWER | | `ft tickets access ` | Read a ticket's access status (no admit) | STAFF | | `ft tickets checkin ` | Admit a ticket at the door (idempotent) | STAFF | | `ft tickets checkin-undo ` | Undo a check-in so the ticket is valid again (idempotent; `--yes`) | ADMIN | @@ -125,12 +132,24 @@ ft sales list --status CONFIRMED --json | `ft venues list` · `get ` | Venues | VIEWER | | `ft venues create` · `update ` · `delete ` | Manage venues (`--data `) | ADMIN | | `ft staff list` · `get ` · `create` · `set-role ` · `delete ` | Workspace staff (`--workspace-ids ` lists up to 25 workspaces in one call; `--data `) | ADMIN | +| `ft staff access --type admin\|validador\|personalizado\|lectura [--sections --validator-events --viewer-events --expires-at]` | FULL replace of a member's access in this workspace (or `--data`; asks, `--yes`) | ADMIN | +| `ft staff resend-invite ` | Email the invitation link again (asks, `--yes`) | ADMIN | | `ft reports summary` | KPIs (`--period 7d\|30d\|90d\|1y`) | VIEWER | | `ft reports by-event` · `timeseries` · `inventory` | Revenue/tickets by event, over time, and capacity/availability | VIEWER | | `ft reports export buyers\|attendees\|subscribers\|reconciliation` | Exports as CSV (filters `--event` `--event-date` `--from` `--to` `--status`) | ADMIN | | `ft reports reconciliation` · `financials` | CFO reconciliation (Mercado Pago vs sale vs Siigo invoice) · per-function P&L | ADMIN | +| `ft reports live-attendance [--scope all\|own\|partner:]` | Event dates happening right now, with check-in progress | VIEWER | | `ft settlements list` · `get ` · `document ` | Settlements paid to the organizer · signed download URL for the PDF, 5 min TTL (`--proof ` for a payment proof) | ADMIN | | `ft content-videos list` · `content-posts list\|create` · `content-lives list\|get\|playback-token` | Organization content; `content-posts create --data` publishes a post or article | ADMIN | +| `ft content-posts update ` · `delete ` · `pin ` · `unpin ` | Edit, delete (`--yes`) and pin community posts | ADMIN | +| `ft content-videos update ` · `delete ` · `publish ` · `unpublish ` · `set-series --series ` · `ft content-series list\|create\|update\|delete\|publish\|unpublish` | On-demand videos and video series (deletes ask, `--yes`) | ADMIN | +| `ft content-lives create` · `update ` · `delete ` · `chat ` · `reset-key ` | Live streams: `create` and `reset-key` print the SECRET stream key once; `delete` and `reset-key` ask (`--yes`) | ADMIN | +| `ft content-channels list` · `create` · `update ` · `order ` · `archive ` | Community channels (`archive` has no undo, `--yes`) | ADMIN | +| `ft content-meetups list` · `get` · `create` · `update` · `publish ` · `cancel ` · `rsvp --approve\|--reject` · `attendance ` | Community meetups; `publish`, `cancel` and `rsvp` notify members, so they ask (`--yes`) | ADMIN | +| `ft content-moderation queue\|bans\|member-posts` · `approve --expected-updated-at ` · `reject ` · `remove ` · `ft content-comments hide\|unhide\|ignore-reports\|delete ` · `ft content-members ban --comment ` · `unban ` | Community moderation (`reject`, `remove`, `delete` and `ban` ask, `--yes`) | STAFF · ADMIN | +| `ft products list` · `get` · `create` · `update` · `delete` · `status --status DRAFT\|PUBLISHED` | Digital products and courses (`--data `; `delete` asks) | ADMIN | +| `ft organization update --data` · `analytics ` · `profile get\|update` · `ft website get\|set --data\|publish\|unpublish` | Workspace identity, profile, GA4 and public website (`website set` is a FULL replace: start from `website get --json`) | ADMIN | +| `ft merch catalog` | Merch store settings and published products with live stock (needs an enterprise service key) | — | | `ft waitlist list [--city ]` · `waitlist create --data` | Per-city waitlist of an enterprise landing (export with personal data); `create` needs an enterprise service key | ADMIN | | `ft api-keys create ` · `list` · `revoke ` | Self-service API keys (the secret is shown once, never stored) | ADMIN | | `ft admin login` · `me` · `workspaces` · `users` · `plans` · `feature-flags` · `tokens` · `audit-log` | Superadmin, cross-tenant — needs a SUPER_ADMIN session, not an API key. Includes `admin workspaces plan ` (assisted plan assignment), `plan-show ` (current plan) and `delete ` (soft delete; suspend first) and `webTemplate` / `customDomain` on `update` | SUPER_ADMIN | diff --git a/src/commands/box-office.ts b/src/commands/box-office.ts new file mode 100644 index 0000000..9e5387e --- /dev/null +++ b/src/commands/box-office.ts @@ -0,0 +1,285 @@ +import type { Command } from "commander"; +import { + deleteEventsIdViewersViewerId, + getEventDatesIdAccessClose, + getEventsIdValidators, + getEventsIdViewers, + getMasterQrs, + getPaymentIntents, + getReportsLiveAttendance, + getTicketTemplates, + postEventDatesIdAccessClose, + postEventsIdValidators, + postEventsIdViewers, + postStaffIdResendInvite, + postTicketTemplatesIdInstantiate, + putMasterQrsIdActive, + putStaffIdAccess, +} from "../client/sdk.gen"; +import { fail } from "../lib/api"; +import { list, op, orNull } from "./op"; + +/** + * Box-office and door operations from contracts 1.26-1.36: who may see or + * validate an event, staff access, the access-close record, live attendance, + * the checkout funnel, master QRs and ticket templates. Each one hooks into + * the family it belongs to. + */ + +/** `ft events viewers …` and `ft events validators …` */ +export function registerEventAccess(events: Command): void { + const viewers = events + .command("viewers") + .description("Read-only viewers of an event's statistics"); + + op(viewers, { + name: "list ", + describe: "People with read-only access to the event's statistics", + call: ([eventId]) => getEventsIdViewers({ path: { id: eventId } }), + columns: ["id", "email", "createdAt"], + }); + + op(viewers, { + name: "add ", + describe: + "Grant read-only access to the event's statistics and email the link (creates a VIEWER account if needed)", + required: [["--email ", "viewer's email"]], + confirm: ([eventId], o) => + `Grant ${o.email} read-only access to event ${eventId} and email them?`, + call: ([eventId], o) => + postEventsIdViewers({ path: { id: eventId }, body: { email: o.email } }), + }); + + op(viewers, { + name: "remove ", + describe: + "Revoke a viewer's access (viewerId is the access id from `viewers list`; the account stays)", + confirm: ([eventId, viewerId]) => + `Revoke viewer ${viewerId} of event ${eventId}?`, + call: ([eventId, viewerId]) => + deleteEventsIdViewersViewerId({ path: { id: eventId, viewerId } }), + }); + + const validators = events + .command("validators") + .description("Door staff who can validate an event's tickets"); + + op(validators, { + name: "list ", + describe: + "Validators of the event (assigned to it, plus those with allEvents)", + call: ([eventId]) => getEventsIdValidators({ path: { id: eventId } }), + columns: ["id", "name", "email", "isActive", "allEvents"], + }); + + op(validators, { + name: "add ", + describe: + "Assign door staff to the event (additive; creates a STAFF account and emails an invitation if needed)", + required: [ + ["--name ", "validator's name"], + ["--email ", "validator's email"], + ], + confirm: ([eventId], o) => + `Make ${o.name} <${o.email}> a validator of event ${eventId}? A new account gets an invitation email.`, + call: ([eventId], o) => + postEventsIdValidators({ + path: { id: eventId }, + body: { name: o.name, email: o.email }, + }), + }); +} + +const ACCESS_TYPES = ["admin", "validador", "personalizado", "lectura"]; + +/** `ft staff access ` and `ft staff resend-invite ` */ +export function registerStaffAccess(staff: Command): void { + op(staff, { + name: "access ", + describe: + "Replace a staff member's access in this workspace (FULL replace: what you do not pass is removed)", + options: [ + ["--type ", "admin | validador | personalizado | lectura"], + [ + "--sections ", + "personalizado: comma-separated sections (e.g. eventos,validar,informes)", + ], + [ + "--validator-events ", + "events they may validate (comma-separated; empty = all)", + ], + ["--viewer-events ", "lectura: events whose stats they see"], + ["--expires-at ", 'YYYY-MM-DD, or "none" for permanent'], + ], + data: "optional", + check: (_args, o) => { + if (o.data !== undefined) return; + if (!o.type) fail("Pass --type (or the whole body with --data)."); + if (!ACCESS_TYPES.includes(o.type)) + fail(`--type must be one of: ${ACCESS_TYPES.join(", ")}.`); + }, + confirm: ([id], o) => + `Replace the access of staff ${id}${o.type ? ` with "${o.type}"` : ""}? Anything not in this request is removed.`, + call: ([id], o, data) => + putStaffIdAccess({ + path: { id }, + body: (data ?? { + accessType: o.type, + sections: list(o.sections), + validatorEventIds: list(o.validatorEvents), + viewerEventIds: list(o.viewerEvents), + expiresAt: + o.expiresAt === undefined ? undefined : orNull(o.expiresAt), + }) as never, + }), + }); + + op(staff, { + name: "resend-invite ", + describe: + "Email the staff member their invitation link again (same persistent link)", + confirm: ([id]) => `Resend the invitation email to staff ${id}?`, + call: ([id]) => postStaffIdResendInvite({ path: { id } }), + }); +} + +/** `ft event-dates access-close status|sign ` */ +export function registerAccessClose(eventDates: Command): void { + const close = eventDates + .command("access-close") + .description("Access-close record of an event date (door count)"); + + op(close, { + name: "status ", + describe: "Live entry count and whether the date is closed or signable", + call: ([dateId]) => getEventDatesIdAccessClose({ path: { id: dateId } }), + }); + + op(close, { + name: "sign ", + describe: + "Sign the access-close record: freezes the check-in count and emails it (IRREVERSIBLE; does not stop the scanner)", + confirm: ([dateId]) => + `Sign the access-close record of date ${dateId}? This is irreversible.`, + call: ([dateId]) => + postEventDatesIdAccessClose({ + path: { id: dateId }, + body: { confirm: true }, + }), + }); +} + +/** `ft sales intents --event ` */ +export function registerPaymentIntents(sales: Command): void { + op(sales, { + name: "intents", + describe: + "Purchase intents of an event: checkout funnel and abandoned journeys (personal data)", + required: [["--event ", "event id"]], + options: [ + ["--event-date ", "only this date"], + ["--only-abandoned", "only journeys that did not buy"], + ["--limit ", "rows per page"], + ["--cursor ", "pagination cursor"], + ], + call: (_args, o) => + getPaymentIntents({ + query: { + event: o.event, + eventDate: o.eventDate, + onlyAbandoned: o.onlyAbandoned ? true : undefined, + limit: o.limit ? Number(o.limit) : undefined, + cursor: o.cursor, + }, + }), + // The table shows the journeys; --json keeps funnel and cursor too. + pick: (body, o) => { + if (o.json) return body.data; + if (body.data?.nextCursor) + console.error(`More results: --cursor ${body.data.nextCursor}`); + console.error(`Funnel: ${JSON.stringify(body.data?.funnel ?? {})}`); + return body.data?.rows ?? []; + }, + columns: [ + "personName", + "personEmail", + "stage", + "outcome", + "reason", + "saleReference", + "lastAt", + ], + }); +} + +/** `ft reports live-attendance` */ +export function registerLiveAttendance(reports: Command): void { + op(reports, { + name: "live-attendance", + describe: "Event dates happening right now, with check-in progress", + options: [["--scope ", "all | own | partner:"]], + call: (_args, o) => getReportsLiveAttendance({ query: { scope: o.scope } }), + columns: [ + "eventName", + "city", + "sold", + "validated", + "validatedPct", + "eventDateId", + ], + }); +} + +/** Extras of `ft master-qrs`: list and activate/deactivate. */ +export function extendMasterQrs(root: Command): void { + op(root, { + name: "list", + describe: + "Master box-office QR codes (`code`/`url` are secret: shown only with --full or --json)", + options: [["--full", "show every field, including code and url"]], + call: () => getMasterQrs({}), + columns: (o) => + o.full + ? undefined + : ["id", "label", "mode", "eventId", "active", "scans", "lastScanAt"], + }); + for (const [name, active] of [ + ["activate", true], + ["deactivate", false], + ] as const) + op(root, { + name: `${name} `, + describe: `${active ? "Activate" : "Deactivate"} a master QR (a deactivated QR stops opening the sale flow)`, + call: ([id]) => putMasterQrsIdActive({ path: { id }, body: { active } }), + }); +} + +/** Extras of `ft ticket-templates`: list and instantiate. */ +export function extendTicketTemplates(root: Command): void { + op(root, { + name: "list", + describe: "Ticket templates of the workspace", + call: () => getTicketTemplates({}), + columns: ["id", "name", "price", "currency", "capacity", "isActive"], + }); + op(root, { + name: "instantiate ", + describe: "Create a ticket type on an event date from a template", + required: [["--event-date ", "event date that gets the ticket type"]], + options: [ + ["--name ", "override the template's name"], + ["--price ", "override the price"], + ["--capacity ", "override the capacity"], + ], + call: ([templateId], o) => + postTicketTemplatesIdInstantiate({ + path: { id: templateId }, + body: { + eventDateId: o.eventDate, + name: o.name, + price: o.price === undefined ? undefined : Number(o.price), + capacity: o.capacity === undefined ? undefined : Number(o.capacity), + }, + }), + }); +} diff --git a/src/commands/community.ts b/src/commands/community.ts new file mode 100644 index 0000000..2763ad7 --- /dev/null +++ b/src/commands/community.ts @@ -0,0 +1,315 @@ +import type { Command } from "commander"; +import { + deleteContentCommentsId, + deleteContentMembersIdBan, + getContentChannels, + getContentLivesIdChat, + getContentMeetups, + getContentModerationBans, + getContentModerationMemberPosts, + getContentModerationQueue, + patchContentMeetupsIdRsvpsRsvpId, + postContentLivesIdResetKey, + postContentMeetupsIdPublish, + postContentMembersIdBan, + postContentModerationCommentsIdHide, + postContentModerationCommentsIdIgnoreReports, + postContentModerationCommentsIdUnhide, + postContentModerationMemberPostsIdApprove, + postContentModerationMemberPostsIdReject, + postContentModerationMemberPostsIdRemove, + putContentChannelsOrder, + putContentMeetupsIdAttendance, + putContentPostsIdPin, + putContentSeriesIdPublished, + putContentVideosIdPublished, + putContentVideosIdSeries, +} from "../client/sdk.gen"; +import { fail } from "../lib/api"; +import { bool, list, op, orNull } from "./op"; + +/** + * Community management from contracts 1.26-1.36 (channels, posts, videos and + * series, live streams, meetups, moderation). The CRUD verbs go through + * registerResource in program.ts; these are the verbs that take a flag-built + * body, a second id or no id at all. + */ + +const page = (v: string | undefined) => + v === undefined ? undefined : Number(v); + +/** Extras of `ft content-posts`: pin/unpin. */ +export function extendContentPosts(root: Command): void { + for (const [name, pinned] of [ + ["pin", true], + ["unpin", false], + ] as const) + op(root, { + name: `${name} `, + describe: pinned + ? "Pin a published post (unpins the previous one)" + : "Unpin a post", + call: ([id]) => putContentPostsIdPin({ path: { id }, body: { pinned } }), + }); +} + +/** Extras of `ft content-videos`: publish/unpublish and series. */ +export function extendContentVideos(root: Command): void { + for (const [name, published] of [ + ["publish", true], + ["unpublish", false], + ] as const) + op(root, { + name: `${name} `, + describe: published + ? "Publish a video to the community feed (members are notified once)" + : "Take a video out of the feed", + call: ([id]) => + putContentVideosIdPublished({ path: { id }, body: { published } }), + }); + op(root, { + name: "set-series ", + describe: "Move a video into a series, or out of it with --series none", + required: [["--series ", 'series id, or "none"']], + call: ([id], o) => + putContentVideosIdSeries({ + path: { id }, + body: { seriesId: orNull(o.series) }, + }), + }); +} + +/** Extras of `ft content-series`: publish/unpublish. */ +export function extendContentSeries(root: Command): void { + for (const [name, published] of [ + ["publish", true], + ["unpublish", false], + ] as const) + op(root, { + name: `${name} `, + describe: `${published ? "Publish" : "Unpublish"} a video series`, + call: ([id]) => + putContentSeriesIdPublished({ path: { id }, body: { published } }), + }); +} + +/** Extras of `ft content-lives`: chat and reset-key. */ +export function extendContentLives(root: Command): void { + op(root, { + name: "chat ", + describe: "Chat history of a live stream", + call: ([id]) => getContentLivesIdChat({ path: { id } }), + pick: (body, o) => (o.json ? body.data : body.data?.messages), + }); + op(root, { + name: "reset-key ", + describe: + "Rotate the stream key (the old one stops working and an encoder on air is cut off); prints the new secret key", + confirm: ([id]) => + `Rotate the stream key of live ${id}? An encoder using the current key is cut off.`, + call: ([id]) => postContentLivesIdResetKey({ path: { id } }), + }); +} + +/** Extras of `ft content-channels`: list and order. */ +export function extendContentChannels(root: Command): void { + op(root, { + name: "list", + describe: "Active community channels in display order", + call: () => getContentChannels({}), + columns: ["id", "kind", "name", "slug", "whoCanPost", "requiresApproval"], + }); + op(root, { + name: "order ", + describe: + "Reorder the channels: EVERY active channel id, comma-separated, Announcements first", + call: ([ids]) => + putContentChannelsOrder({ body: { orderedIds: list(ids) ?? [] } }), + }); +} + +/** Extras of `ft content-meetups`: list, publish, rsvp, attendance. */ +export function extendContentMeetups(root: Command): void { + op(root, { + name: "list", + describe: "Community meetups", + call: () => getContentMeetups({}), + columns: [ + "id", + "title", + "format", + "status", + "startsAt", + "city", + "goingCount", + "pendingCount", + ], + }); + op(root, { + name: "publish ", + describe: + "Publish a draft meetup (queues a notification to the whole community)", + confirm: ([id]) => + `Publish meetup ${id}? The whole community gets notified.`, + call: ([id]) => postContentMeetupsIdPublish({ path: { id } }), + }); + op(root, { + name: "rsvp ", + describe: "Approve or reject an RSVP request (the member gets an email)", + options: [ + ["--approve", "approve the request"], + ["--reject", "reject the request"], + ], + check: (_args, o) => { + if (!o.approve === !o.reject) + fail("Pass exactly one of --approve or --reject."); + }, + confirm: ([id, rsvpId], o) => + `${o.approve ? "Approve" : "Reject"} RSVP ${rsvpId} of meetup ${id}? The member gets an email.`, + call: ([id, rsvpId], o) => + patchContentMeetupsIdRsvpsRsvpId({ + path: { id, rsvpId }, + body: { decision: o.approve ? "APPROVE" : "REJECT" }, + }), + }); + op(root, { + name: "attendance ", + describe: + "Mark (or with --attended false, unmark) an attendee as checked in", + options: [["--attended ", "true | false", "true"]], + call: ([id, rsvpId], o) => + putContentMeetupsIdAttendance({ + path: { id }, + body: { rsvpId, attended: bool(o.attended) }, + }), + }); +} + +/** `ft content-moderation …`, `ft content-comments …`, `ft content-members …` */ +export function registerModeration(program: Command): void { + const mod = program + .command("content-moderation") + .description("Community moderation: reported comments, member posts, bans"); + + op(mod, { + name: "queue", + describe: "Reported comments, most reported first (50 per page)", + options: [["--page ", "0-based page"]], + call: (_a, o) => + getContentModerationQueue({ query: { page: page(o.page) } }), + columns: ["commentId", "openReportCount", "hidden", "deleted", "body"], + }); + op(mod, { + name: "bans", + describe: "Members banned from the community (latest 200)", + call: () => getContentModerationBans({}), + columns: ["id", "customerName", "reason", "createdAt"], + }); + op(mod, { + name: "member-posts", + describe: "Member posts awaiting review (or recently published)", + options: [ + ["--status ", "PENDING_REVIEW | PUBLISHED"], + ["--page ", "0-based page"], + ], + call: (_a, o) => + getContentModerationMemberPosts({ + query: { status: o.status, page: page(o.page) }, + }), + columns: ["postId", "status", "channelName", "updatedAt", "content"], + }); + op(mod, { + name: "approve ", + describe: + "Publish a pending member post (author and mentioned members are notified)", + required: [ + [ + "--expected-updated-at ", + "the post's updatedAt from `member-posts` (409 if edited since)", + ], + ], + call: ([id], o) => + postContentModerationMemberPostsIdApprove({ + path: { id }, + body: { expectedUpdatedAt: o.expectedUpdatedAt }, + }), + }); + for (const [name, fn, what] of [ + ["reject", postContentModerationMemberPostsIdReject, "Reject a pending"], + ["remove", postContentModerationMemberPostsIdRemove, "Remove a published"], + ] as const) + op(mod, { + name: `${name} `, + describe: `${what} member post (--ban-author also bans its author)`, + options: [ + ["--reason ", "reason shown to the author"], + ["--ban-author", "also ban the author from the community"], + ], + confirm: ([id], o) => + `${name === "reject" ? "Reject" : "Remove"} member post ${id}${o.banAuthor ? " and ban its author" : ""}?`, + call: ([id], o) => + fn({ + path: { id }, + body: { reason: o.reason, banAuthor: Boolean(o.banAuthor) }, + }), + }); + + const comments = program + .command("content-comments") + .description("Community comments (moderation)"); + for (const [name, fn, describe] of [ + [ + "hide", + postContentModerationCommentsIdHide, + "Hide a comment (reversible)", + ], + ["unhide", postContentModerationCommentsIdUnhide, "Show a hidden comment"], + [ + "ignore-reports", + postContentModerationCommentsIdIgnoreReports, + "Dismiss the open reports of a comment", + ], + ] as const) + op(comments, { + name: `${name} `, + describe, + call: ([id]) => fn({ path: { id } }), + }); + op(comments, { + name: "delete ", + describe: + "Delete a comment and its replies (irreversible; `hide` is the reversible one)", + confirm: ([id]) => `Delete comment ${id} and its replies?`, + call: ([id]) => deleteContentCommentsId({ path: { id } }), + }); + + const members = program + .command("content-members") + .description("Community members (bans)"); + op(members, { + name: "ban ", + describe: + "Ban a member from posting, commenting and RSVPing (cancels their upcoming RSVPs)", + required: [["--comment ", "comment of theirs the ban comes from"]], + options: [ + ["--reason ", "reason"], + ["--hide-all-comments", "hide all their comments in this workspace"], + ], + confirm: ([id]) => + `Ban member ${id} from the community? Their upcoming RSVPs are cancelled.`, + call: ([id], o) => + postContentMembersIdBan({ + path: { id }, + body: { + commentId: o.comment, + reason: o.reason, + hideAllComments: Boolean(o.hideAllComments), + }, + }), + }); + op(members, { + name: "unban ", + describe: "Lift a member's community ban", + call: ([id]) => deleteContentMembersIdBan({ path: { id } }), + }); +} diff --git a/src/commands/op.ts b/src/commands/op.ts new file mode 100644 index 0000000..6419e30 --- /dev/null +++ b/src/commands/op.ts @@ -0,0 +1,90 @@ +// biome-ignore-all lint/suspicious/noExplicitAny: generated SDK boundary — signatures vary by operation. +import type { Command } from "commander"; +import { configureClient, unwrap } from "../lib/api"; +import { confirmOrExit, parseData } from "../lib/input"; +import { print } from "../lib/output"; + +type SdkResult = Promise<{ data?: any; error?: unknown; response: Response }>; +type Opts = Record; +/** Positional args in signature order (typed non-empty so `[id]` is a string). */ +type Args = [string, string, ...string[]]; + +/** + * One command bound to one contract operation, for the shapes registerResource + * cannot model: nested ids (` `), flag-built bodies, plain + * (unpaginated) lists, singleton resources. Every command gets `--workspace` + * and `--json`; `--account` is added globally by program.ts. + */ +export interface OpSpec { + /** Commander signature, e.g. `"remove "`. */ + name: string; + describe: string; + /** Optional flags: [flags, description, default?]. */ + options?: [string, string, string?][]; + /** Required flags: [flags, description]. */ + required?: [string, string][]; + /** `--data ` body (inline or @file): "required" or "optional". */ + data?: "required" | "optional"; + /** + * Destructive, sends email or otherwise hard to take back: ask first, with + * `--yes` to skip; without a TTY and without `--yes` it refuses (exit 1) + * before any request. + */ + confirm?: (args: Args, opts: Opts) => string; + /** Validate flags before anything else (call `fail` to abort). */ + check?: (args: Args, opts: Opts) => void; + /** The SDK call. `data` is the parsed `--data` body, when passed. */ + call: (args: Args, opts: Opts, data: unknown) => SdkResult; + /** Table columns for array output (or a function of the flags). */ + columns?: string[] | ((opts: Opts) => string[] | undefined); + /** What to print from the unwrapped body (default: `body.data ?? body`). */ + pick?: (body: any, opts: Opts) => unknown; +} + +export function op(parent: Command, spec: OpSpec): Command { + const cmd = parent.command(spec.name).description(spec.describe); + for (const [flags, describe] of spec.required ?? []) + cmd.requiredOption(flags, describe); + for (const [flags, describe, def] of spec.options ?? []) + cmd.option(flags, describe, def); + if (spec.data === "required") + cmd.requiredOption("--data ", "JSON body (inline or @file.json)"); + else if (spec.data === "optional") + cmd.option("--data ", "JSON body (inline or @file.json)"); + if (spec.confirm) cmd.option("--yes", "skip confirmation"); + cmd + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output"); + + cmd.action(async (...received: unknown[]) => { + // commander passes the positional args, then opts, then the command. + const opts = received[received.length - 2] as Opts; + const args = received.slice(0, -2) as Args; + spec.check?.(args, opts); + // Parse before asking: a typo in --data should not cost a confirmation. + const data = opts.data !== undefined ? parseData(opts.data) : undefined; + if (spec.confirm) await confirmOrExit(spec.confirm(args, opts), opts.yes); + configureClient(opts.workspace); + const body = unwrap(await spec.call(args, opts, data)); + const out = spec.pick ? spec.pick(body, opts) : (body?.data ?? body); + const columns = + typeof spec.columns === "function" ? spec.columns(opts) : spec.columns; + print(out ?? { ok: true }, { json: opts.json, columns }); + }); + return cmd; +} + +/** `"true"`/`"false"` flag value to boolean (anything else is false). */ +export const bool = (v: unknown) => v === true || v === "true"; + +/** `"none"` clears a nullable field; anything else is sent as is. */ +export const orNull = (v: string) => (v === "none" ? null : v); + +/** Comma-separated flag to a trimmed list, `undefined` when not passed. */ +export const list = (v: string | undefined) => + v === undefined + ? undefined + : v + .split(",") + .map((s) => s.trim()) + .filter(Boolean); diff --git a/src/commands/storefront.ts b/src/commands/storefront.ts new file mode 100644 index 0000000..db1e613 --- /dev/null +++ b/src/commands/storefront.ts @@ -0,0 +1,128 @@ +import type { Command } from "commander"; +import { + getMerchCatalog, + getOrganizationProfile, + getProducts, + getWebsite, + patchOrganization, + patchOrganizationAnalytics, + patchOrganizationProfile, + postProductsIdStatus, + putWebsite, + putWebsitePublished, +} from "../client/sdk.gen"; +import { fail } from "../lib/api"; +import { op, orNull } from "./op"; + +/** + * Workspace identity and storefront from contracts 1.26-1.36: organization and + * profile, the public website, digital products and the merch catalog. + */ + +/** Extras of `ft products`: list and status. */ +export function extendProducts(root: Command): void { + op(root, { + name: "list", + describe: "Digital products and courses", + call: () => getProducts({}), + columns: [ + "id", + "name", + "type", + "status", + "price", + "currency", + "salesCount", + ], + }); + op(root, { + name: "status ", + describe: "Publish or unpublish a product", + required: [["--status ", "DRAFT | PUBLISHED"]], + check: (_a, o) => { + if (!["DRAFT", "PUBLISHED"].includes(o.status)) + fail("--status must be DRAFT or PUBLISHED."); + }, + call: ([id], o) => + postProductsIdStatus({ path: { id }, body: { status: o.status } }), + }); +} + +/** `ft organization update|analytics|profile` (alias `org`). */ +export function registerOrganization(program: Command): void { + const root = program + .command("organization") + .alias("org") + .description("The active workspace's identity, profile and analytics"); + + op(root, { + name: "update", + describe: "Update the public identity (name, logoUrl, coverUrl)", + data: "required", + call: (_a, _o, data) => patchOrganization({ body: data as never }), + }); + op(root, { + name: "analytics ", + describe: 'Set the GA4 property (G-XXXXXXX), or "none" to remove it', + call: ([id]) => + patchOrganizationAnalytics({ body: { ga4MeasurementId: orNull(id) } }), + }); + + const profile = root + .command("profile") + .description("Workspace profile (artist, visual, contact, social)"); + op(profile, { + name: "get", + describe: "Get the workspace profile", + call: () => getOrganizationProfile({}), + }); + op(profile, { + name: "update", + describe: + "Update the profile (partial: --data with artist/visual/contact/social)", + data: "required", + call: (_a, _o, data) => patchOrganizationProfile({ body: data as never }), + }); +} + +/** `ft website get|set|publish|unpublish` */ +export function registerWebsite(program: Command): void { + const root = program + .command("website") + .description("The workspace's public website"); + + op(root, { + name: "get", + describe: "Get the website configuration", + call: () => getWebsite({}), + }); + op(root, { + name: "set", + describe: + "Save the whole website configuration (FULL replace: start from `ft website get --json`)", + data: "required", + call: (_a, _o, data) => putWebsite({ body: data as never }), + }); + for (const [name, published] of [ + ["publish", true], + ["unpublish", false], + ] as const) + op(root, { + name, + describe: `${published ? "Publish" : "Unpublish"} the public profile`, + call: () => putWebsitePublished({ body: { published } }), + }); +} + +/** `ft merch catalog` */ +export function registerMerch(program: Command): void { + const root = program + .command("merch") + .description("Merch store of an enterprise landing"); + op(root, { + name: "catalog", + describe: + "Store settings and published products with live stock (needs an enterprise service key)", + call: () => getMerchCatalog({}), + }); +} diff --git a/src/commands/wire.test.ts b/src/commands/wire.test.ts new file mode 100644 index 0000000..616fad2 --- /dev/null +++ b/src/commands/wire.test.ts @@ -0,0 +1,355 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { client } from "../client/client.gen"; + +/** + * Wire-level checks for the riskiest commands: the real generated SDK runs + * and only `fetch` is faked, so each test sees the HTTP method, the final URL + * (with every id in the slot the contract gives it) and the JSON body that + * would leave the machine. Two distinct ids per call catch a swapped pair. + */ +vi.mock("../lib/api", async (importOriginal) => ({ + ...(await importOriginal()), + configureClient: vi.fn(() => + client.setConfig({ baseUrl: "https://ft.test/api/v1", fetch: fetchMock }), + ), +})); + +const fetchMock = vi.hoisted(() => vi.fn()); +const { program } = await import("../program"); + +interface Sent { + method: string; + path: string; + body: unknown; +} + +async function send(...args: string[]): Promise { + await program.parseAsync(["node", "ft", ...args, "--json"]); + expect(fetchMock).toHaveBeenCalledTimes(1); + const req = fetchMock.mock.calls[0]?.[0] as Request; + const url = new URL(req.url); + const text = await req.text(); + return { + method: req.method, + path: `${url.pathname.replace("/api/v1", "")}${url.search}`, + body: text ? JSON.parse(text) : undefined, + }; +} + +beforeEach(() => { + 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); + fetchMock.mockImplementation( + async () => + new Response(JSON.stringify({ data: {} }), { + status: 200, + headers: { "Content-Type": "application/json" }, + }), + ); +}); + +afterEach(() => { + vi.restoreAllMocks(); + fetchMock.mockReset(); +}); + +describe("tickets and sales", () => { + it("sales transfer: sale id, then item id, email in the body", async () => { + expect( + await send( + "sales", + "transfer", + "sale_A", + "item_B", + "--email", + "to@b.co", + "--yes", + ), + ).toEqual({ + method: "POST", + path: "/sales/sale_A/items/item_B/transfer", + body: { email: "to@b.co" }, + }); + }); + + it("sales recipient set: name and email only", async () => { + expect( + await send( + "sales", + "recipient", + "set", + "sale_A", + "--name", + "Ana", + "--email", + "ana@b.co", + "--yes", + ), + ).toEqual({ + method: "PATCH", + path: "/sales/sale_A/recipient", + body: { name: "Ana", email: "ana@b.co" }, + }); + }); + + it("tickets checkin-undo: DELETE on the ticket code, no body", async () => { + expect(await send("tickets", "checkin-undo", "TKT-9", "--yes")).toEqual({ + method: "DELETE", + path: "/tickets/TKT-9/checkin", + body: undefined, + }); + }); + + it("sales abandon: POST, no body", async () => { + expect(await send("sales", "abandon", "sale_A", "--yes")).toEqual({ + method: "POST", + path: "/sales/sale_A/abandon", + body: undefined, + }); + }); +}); + +describe("staff access", () => { + it("builds the full-replace body from flags", async () => { + expect( + await send( + "staff", + "access", + "stf_A", + "--type", + "personalizado", + "--sections", + "eventos, validar", + "--validator-events", + "evt_1,evt_2", + "--expires-at", + "2027-01-31", + "--yes", + ), + ).toEqual({ + method: "PUT", + path: "/staff/stf_A/access", + body: { + accessType: "personalizado", + sections: ["eventos", "validar"], + validatorEventIds: ["evt_1", "evt_2"], + expiresAt: "2027-01-31", + }, + }); + }); + + it("--expires-at none sends null (permanent)", async () => { + const sent = await send( + "staff", + "access", + "stf_A", + "--type", + "lectura", + "--viewer-events", + "evt_1", + "--expires-at", + "none", + "--yes", + ); + expect(sent.body).toEqual({ + accessType: "lectura", + viewerEventIds: ["evt_1"], + expiresAt: null, + }); + }); + + it("--data replaces the flags", async () => { + const sent = await send( + "staff", + "access", + "stf_A", + "--data", + '{"accessType":"validador","validatorEventIds":[]}', + "--yes", + ); + expect(sent.body).toEqual({ + accessType: "validador", + validatorEventIds: [], + }); + }); + + it("rejects an unknown --type before any request", async () => { + await expect( + program.parseAsync([ + "node", + "ft", + "staff", + "access", + "stf_A", + "--type", + "owner", + "--yes", + ]), + ).rejects.toThrow("exited"); + expect(fetchMock).not.toHaveBeenCalled(); + }); + + it("resend-invite: POST, no body", async () => { + expect(await send("staff", "resend-invite", "stf_A", "--yes")).toEqual({ + method: "POST", + path: "/staff/stf_A/resend-invite", + body: undefined, + }); + }); +}); + +describe("event viewers and validators", () => { + it("viewers add: email in the body", async () => { + expect( + await send( + "events", + "viewers", + "add", + "evt_A", + "--email", + "v@b.co", + "--yes", + ), + ).toEqual({ + method: "POST", + path: "/events/evt_A/viewers", + body: { email: "v@b.co" }, + }); + }); + + it("viewers remove: event id, then viewer (access) id", async () => { + expect( + await send("events", "viewers", "remove", "evt_A", "vw_B", "--yes"), + ).toEqual({ + method: "DELETE", + path: "/events/evt_A/viewers/vw_B", + body: undefined, + }); + }); + + it("viewers list: GET", async () => { + fetchMock.mockResolvedValueOnce( + new Response(JSON.stringify({ data: [] }), { + headers: { "Content-Type": "application/json" }, + }), + ); + expect(await send("events", "viewers", "list", "evt_A")).toEqual({ + method: "GET", + path: "/events/evt_A/viewers", + body: undefined, + }); + }); + + it("validators add: name and email", async () => { + expect( + await send( + "events", + "validators", + "add", + "evt_A", + "--name", + "Door 1", + "--email", + "d@b.co", + "--yes", + ), + ).toEqual({ + method: "POST", + path: "/events/evt_A/validators", + body: { name: "Door 1", email: "d@b.co" }, + }); + }); +}); + +describe("door and box office", () => { + it("access-close sign sends the required confirm flag", async () => { + expect( + await send("event-dates", "access-close", "sign", "date_A", "--yes"), + ).toEqual({ + method: "POST", + path: "/event-dates/date_A/access-close", + body: { confirm: true }, + }); + }); + + it("master-qrs deactivate", async () => { + expect(await send("master-qrs", "deactivate", "mq_A")).toEqual({ + method: "PUT", + path: "/master-qrs/mq_A/active", + body: { active: false }, + }); + }); + + it("ticket-templates instantiate: template id in the path, date in the body", async () => { + expect( + await send( + "ticket-templates", + "instantiate", + "tpl_A", + "--event-date", + "date_B", + "--price", + "50000", + ), + ).toEqual({ + method: "POST", + path: "/ticket-templates/tpl_A/instantiate", + body: { eventDateId: "date_B", price: 50000 }, + }); + }); + + it("sales intents: query filters", async () => { + fetchMock.mockResolvedValueOnce( + new Response(JSON.stringify({ data: { rows: [], funnel: {} } }), { + headers: { "Content-Type": "application/json" }, + }), + ); + expect( + await send("sales", "intents", "--event", "evt_A", "--only-abandoned"), + ).toEqual({ + method: "GET", + path: "/payment-intents?event=evt_A&onlyAbandoned=true", + body: undefined, + }); + }); +}); + +describe("community", () => { + it("meetups rsvp: meetup id, then rsvp id, decision in the body", async () => { + expect( + await send( + "content-meetups", + "rsvp", + "mt_A", + "rsvp_B", + "--reject", + "--yes", + ), + ).toEqual({ + method: "PATCH", + path: "/content/meetups/mt_A/rsvps/rsvp_B", + body: { decision: "REJECT" }, + }); + }); + + it("members ban: customer id in the path, comment in the body", async () => { + expect( + await send( + "content-members", + "ban", + "cus_A", + "--comment", + "cmt_B", + "--yes", + ), + ).toEqual({ + method: "POST", + path: "/content/members/cus_A/ban", + body: { commentId: "cmt_B", hideAllComments: false }, + }); + }); +}); diff --git a/src/destructive-confirm.test.ts b/src/destructive-confirm.test.ts index 603dc05..67b5ab9 100644 --- a/src/destructive-confirm.test.ts +++ b/src/destructive-confirm.test.ts @@ -17,31 +17,48 @@ import { const sdk = vi.hoisted(() => ({ postEventsIdCancel: vi.fn(), deleteStaffId: vi.fn(), - deleteWorkspacesId: vi.fn(), deleteEventsIdArtistsOrganizationId: vi.fn(), deleteEventsIdArtistInvitationsInvitationId: vi.fn(), deletePresaleWindowsId: vi.fn(), postSalesIdItemsItemIdTransfer: vi.fn(), patchSalesIdRecipient: vi.fn(), deleteTicketsTicketCodeCheckin: vi.fn(), + deleteEventsIdViewersViewerId: vi.fn(), + putStaffIdAccess: vi.fn(), + deleteContentLivesId: vi.fn(), + postEventDatesIdAccessClose: vi.fn(), + postSalesIdAbandon: vi.fn(), + deleteContentPostsId: vi.fn(), + deleteContentCommentsId: vi.fn(), + postContentChannelsIdArchive: vi.fn(), + postContentModerationMemberPostsIdReject: vi.fn(), + postContentModerationMemberPostsIdRemove: vi.fn(), + postContentMembersIdBan: vi.fn(), + postContentMeetupsIdCancel: vi.fn(), + deleteProductsId: vi.fn(), + deleteContentVideosId: vi.fn(), + deleteContentSeriesId: vi.fn(), + postContentLivesIdResetKey: vi.fn(), + deleteTicketTemplatesId: vi.fn(), + deleteMasterQrsId: vi.fn(), + postEventsIdViewers: vi.fn(), + postEventsIdValidators: vi.fn(), + postStaffIdResendInvite: vi.fn(), + postContentMeetupsIdPublish: vi.fn(), + patchContentMeetupsIdRsvpsRsvpId: vi.fn(), + deleteWorkspacesId: vi.fn(), })); +const { deleteWorkspacesId, ...b2b } = sdk; + vi.mock("./client/sdk.gen", async (importOriginal) => ({ ...(await importOriginal()), - postEventsIdCancel: sdk.postEventsIdCancel, - deleteStaffId: sdk.deleteStaffId, - deleteEventsIdArtistsOrganizationId: sdk.deleteEventsIdArtistsOrganizationId, - deleteEventsIdArtistInvitationsInvitationId: - sdk.deleteEventsIdArtistInvitationsInvitationId, - deletePresaleWindowsId: sdk.deletePresaleWindowsId, - postSalesIdItemsItemIdTransfer: sdk.postSalesIdItemsItemIdTransfer, - patchSalesIdRecipient: sdk.patchSalesIdRecipient, - deleteTicketsTicketCodeCheckin: sdk.deleteTicketsTicketCodeCheckin, + ...b2b, })); vi.mock("./admin-client/sdk.gen", async (importOriginal) => ({ ...(await importOriginal()), - deleteWorkspacesId: sdk.deleteWorkspacesId, + deleteWorkspacesId, })); const { program } = await import("./program"); @@ -127,4 +144,63 @@ const CASES: [string[], (typeof sdk)[keyof typeof sdk]][] = [ sdk.patchSalesIdRecipient, ], [["tickets", "checkin-undo", "TKT1"], sdk.deleteTicketsTicketCodeCheckin], + // Contracts 1.26-1.36. + [ + ["events", "viewers", "remove", "evt_1", "vw_1"], + sdk.deleteEventsIdViewersViewerId, + ], + [["staff", "access", "stf_1", "--type", "lectura"], sdk.putStaffIdAccess], + [ + ["event-dates", "access-close", "sign", "date_1"], + sdk.postEventDatesIdAccessClose, + ], + [["sales", "abandon", "sale_1"], sdk.postSalesIdAbandon], + [["content-lives", "delete", "live_1"], sdk.deleteContentLivesId], + [["content-lives", "reset-key", "live_1"], sdk.postContentLivesIdResetKey], + [["content-posts", "delete", "post_1"], sdk.deleteContentPostsId], + [["content-videos", "delete", "vid_1"], sdk.deleteContentVideosId], + [["content-series", "delete", "ser_1"], sdk.deleteContentSeriesId], + [["content-comments", "delete", "cmt_1"], sdk.deleteContentCommentsId], + [["content-channels", "archive", "ch_1"], sdk.postContentChannelsIdArchive], + [ + ["content-moderation", "reject", "post_1"], + sdk.postContentModerationMemberPostsIdReject, + ], + [ + ["content-moderation", "remove", "post_1"], + sdk.postContentModerationMemberPostsIdRemove, + ], + [ + ["content-members", "ban", "cus_1", "--comment", "cmt_1"], + sdk.postContentMembersIdBan, + ], + [["content-meetups", "cancel", "mt_1"], sdk.postContentMeetupsIdCancel], + [["products", "delete", "prd_1"], sdk.deleteProductsId], + [["ticket-templates", "delete", "tpl_1"], sdk.deleteTicketTemplatesId], + [["master-qrs", "delete", "mq_1"], sdk.deleteMasterQrsId], + // Not x-ft-destructive, but they send email or notify a whole community: + // same gate, so a script cannot fire them by accident. + [ + ["events", "viewers", "add", "evt_1", "--email", "a@b.co"], + sdk.postEventsIdViewers, + ], + [ + [ + "events", + "validators", + "add", + "evt_1", + "--name", + "Ana", + "--email", + "a@b.co", + ], + sdk.postEventsIdValidators, + ], + [["staff", "resend-invite", "stf_1"], sdk.postStaffIdResendInvite], + [["content-meetups", "publish", "mt_1"], sdk.postContentMeetupsIdPublish], + [ + ["content-meetups", "rsvp", "mt_1", "rsvp_1", "--approve"], + sdk.patchContentMeetupsIdRsvpsRsvpId, + ], ]; diff --git a/src/program.ts b/src/program.ts index f32ed85..43a3b65 100644 --- a/src/program.ts +++ b/src/program.ts @@ -2,17 +2,26 @@ import { Command } from "commander"; // Version synced with package.json at build time (tsup injects it via import). import pkg from "../package.json" with { type: "json" }; import { + deleteContentLivesId, + deleteContentPostsId, + deleteContentSeriesId, + deleteContentVideosId, deleteDiscountsId, deleteEventsId, deleteEventsIdDatesDateId, + deleteMasterQrsId, deleteMembershipPlansId, + deleteProductsId, deleteStaffId, + deleteTicketTemplatesId, deleteTicketTypesId, deleteVenuesId, deleteWebhooksId, getContentLives, getContentLivesId, + getContentMeetupsId, getContentPosts, + getContentSeries, getContentVideos, getDiscounts, getEvents, @@ -21,6 +30,7 @@ import { getMembershipPlans, getMembershipPlansId, getMembershipPlansIdSubscribers, + getProductsId, getSales, getSalesId, getSalesIdAttempts, @@ -35,27 +45,46 @@ import { getVenuesId, getWaitlist, getWebhooks, + patchContentChannelsId, + patchContentLivesId, + patchContentMeetupsId, + patchContentPostsId, + patchContentSeriesId, + patchContentVideosId, patchDiscountsId, patchEventsId, patchEventsIdDatesDateId, + patchMasterQrsId, patchMembershipPlansId, + patchProductsId, patchStaffIdRole, + patchTicketTemplatesId, patchTicketTypesId, patchVenuesId, patchWebhooksId, + postContentChannels, + postContentChannelsIdArchive, + postContentLives, + postContentMeetups, + postContentMeetupsIdCancel, postContentPlaybackToken, postContentPosts, + postContentSeries, postDiscounts, postEvents, postEventsIdCancel, postEventsIdDates, postEventsIdPublish, + postMasterQrs, postMembershipPlans, + postProducts, postSales, + postSalesIdAbandon, postSalesIdCancel, postSalesIdRefund, postStaff, postSubscriptionsIdCancel, + postTicketTemplates, postTicketTypes, postVenues, postWaitlist, @@ -65,6 +94,24 @@ import { registerAccount } from "./commands/account"; import { registerAdmin } from "./commands/admin"; import { registerApiKeys } from "./commands/api-keys"; import { registerAuth } from "./commands/auth"; +import { + extendMasterQrs, + extendTicketTemplates, + registerAccessClose, + registerEventAccess, + registerLiveAttendance, + registerPaymentIntents, + registerStaffAccess, +} from "./commands/box-office"; +import { + extendContentChannels, + extendContentLives, + extendContentMeetups, + extendContentPosts, + extendContentSeries, + extendContentVideos, + registerModeration, +} from "./commands/community"; import { registerEventDates } from "./commands/event-dates"; import { registerArtists, registerEventLineup } from "./commands/lineup"; import { @@ -76,6 +123,12 @@ import { } from "./commands/ops"; import { registerReports } from "./commands/reports"; import { registerResource } from "./commands/resource"; +import { + extendProducts, + registerMerch, + registerOrganization, + registerWebsite, +} from "./commands/storefront"; import { registerTickets } from "./commands/tickets"; import { registerWorkspace } from "./commands/workspace"; import { @@ -143,6 +196,7 @@ registerResource(program, { extend: (root) => { registerEventLineup(root); registerEventSchedule(root); + registerEventAccess(root); }, }); @@ -226,6 +280,15 @@ registerResource(program, { "Payment attempt history of a sale (declines, approvals, refunds)", fn: getSalesIdAttempts, }, + { + // PENDING sale whose payment never started -> ABANDONED (terminal); its + // stock goes back on sale. Confirmed sales use `cancel` (contract 1.30). + name: "abandon", + describe: + "Mark a pending sale as abandoned and release its stock (terminal)", + fn: postSalesIdAbandon, + confirm: true, + }, ], columns: ["id", "reference", "status", "total", "currency", "createdAt"], listFlags: [ @@ -258,7 +321,10 @@ registerResource(program, { }, { flag: "--to ", describe: "created to (ISO 8601)", query: "to" }, ], - extend: registerSaleOps, + extend: (root) => { + registerSaleOps(root); + registerPaymentIntents(root); + }, }); registerResource(program, { @@ -367,6 +433,7 @@ registerResource(program, { }, ], columns: ["id", "name", "email", "role", "workspaceName"], + extend: registerStaffAccess, listFlags: [ { flag: "--workspace-ids ", @@ -386,7 +453,22 @@ registerResource(program, { name: "content-videos", describe: "Organization videos", list: getContentVideos, + update: patchContentVideosId, + del: deleteContentVideosId, columns: ["id", "title", "publishedAt", "memberOnly"], + extend: extendContentVideos, +}); + +registerResource(program, { + name: "content-series", + describe: "Video series", + list: getContentSeries, + create: postContentSeries, + update: patchContentSeriesId, + // Deleting a series keeps its videos (they move out of it). + del: deleteContentSeriesId, + columns: ["id", "title", "published", "videoCount", "memberOnly"], + extend: extendContentSeries, }); registerResource(program, { @@ -396,7 +478,10 @@ registerResource(program, { // type=ARTICLE needs title + body (Markdown); TEXT/IMAGE need content or // imageUrl. Minimum role ADMIN (contract 1.19). create: postContentPosts, + update: patchContentPostsId, + del: deleteContentPostsId, columns: ["id", "title", "publishedAt", "memberOnly"], + extend: extendContentPosts, }); registerResource(program, { @@ -404,8 +489,13 @@ registerResource(program, { describe: "Organization live streams", list: getContentLives, get: getContentLivesId, + // create answers the RTMPS server and the SECRET stream key, once. + create: postContentLives, + update: patchContentLivesId, + del: deleteContentLivesId, columns: ["id", "title", "status", "startsAt", "memberOnly"], extend: (root) => { + extendContentLives(root); root .command("playback-token") .description( @@ -426,6 +516,75 @@ registerResource(program, { }, }); +registerResource(program, { + name: "content-channels", + describe: "Community channels", + create: postContentChannels, + update: patchContentChannelsId, + actions: [ + { + name: "archive", + describe: "Archive a channel (no unarchive; its posts stay under All)", + fn: postContentChannelsIdArchive, + confirm: true, + }, + ], + extend: extendContentChannels, +}); + +registerResource(program, { + name: "content-meetups", + describe: "Community meetups", + get: getContentMeetupsId, + create: postContentMeetups, + update: patchContentMeetupsId, + actions: [ + { + name: "cancel", + describe: "Cancel a meetup (confirmed members are notified by email)", + fn: postContentMeetupsIdCancel, + confirm: true, + }, + ], + extend: extendContentMeetups, +}); + +registerModeration(program); + +registerResource(program, { + name: "products", + describe: "Digital products and courses", + get: getProductsId, + create: postProducts, + update: patchProductsId, + del: deleteProductsId, + extend: extendProducts, +}); + +// Master box-office QRs (contract 1.33): one printed QR opens the sale flow of +// an event (or of today's shows). `code`/`url` are secret and never rotate. +registerResource(program, { + name: "master-qrs", + describe: "Master box-office QR codes", + create: postMasterQrs, + update: patchMasterQrsId, + del: deleteMasterQrsId, + extend: extendMasterQrs, +}); + +registerResource(program, { + name: "ticket-templates", + describe: "Reusable ticket type templates", + create: postTicketTemplates, + update: patchTicketTemplatesId, + del: deleteTicketTemplatesId, + extend: extendTicketTemplates, +}); + +registerOrganization(program); +registerWebsite(program); +registerMerch(program); + registerPresaleWindows(program); // Per-city waitlist of an enterprise landing (contract 1.24). `list` is the @@ -451,7 +610,9 @@ const family = (name: string) => program.commands.find((c) => c.name() === name) as Command; registerCheckinUndo(family("tickets")); registerCourtesySeats(family("event-dates")); +registerAccessClose(family("event-dates")); registerReports(program); +registerLiveAttendance(family("reports")); registerApiKeys(program); registerAdmin(program); From 0f5f126d913e31614c4c9edf01d49e6b9efbc401 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 21:54:19 +0000 Subject: [PATCH 4/4] fix: validate typed flags, close confirmation gaps, redact master QR secrets QA follow-up on the 1.36.0 catch-up. - Whole-number and true/false flags are parsed by commander (lib/input wholeNumber, wholeNumberOrNone, booleanFlag) and exit 1 before any confirmation or request: Number("50.000") was 50 and NaN went out as null. Covers ticket-templates instantiate --price/--capacity, presale-windows --capacity/--active, content-meetups attendance --attended, content-moderation --page, discounts list --active, and --limit on artists search / sales intents (parseLimit now rejects 1e1). - New gates: events invitations resend, events artists set --invite, content-videos publish and website set (full replace). - staff access refuses --data together with body flags. - master-qrs list/update drop code and url from the table and --json unless --full; create documents that it prints them. - destructive-confirm: each row also runs with --yes and must call its SDK function exactly once; a sweep pins the set of commands that take --yes and an allowlist names the notifying writes left ungated on purpose. - coverage.test: every openapi.json operation has a command, an exclusion with its reason, or a DIRECT path; excluded ones are never called. - Wire tests for two-id commands, 404/500 through op() and ops.ts, and the real configureClient sending X-Workspace-Id. - vitest setupFiles: fetch throws, FT_API_URL is a closed port, HOME is a temp dir. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Fo7cm7S4yTPG5LztA8pEVi --- .changeset/contract-1-36.md | 14 +- README.md | 29 ++- src/commands/box-office.ts | 91 +++++++- src/commands/community.ts | 38 ++-- src/commands/lineup.ts | 42 +++- src/commands/op.ts | 15 +- src/commands/ops.ts | 44 +++- src/commands/resource.ts | 12 +- src/commands/storefront.ts | 5 +- src/commands/wire.test.ts | 289 ++++++++++++++++++++++++++ src/commands/workspace-header.test.ts | 81 ++++++++ src/coverage.test.ts | 167 +++++++++++++++ src/destructive-confirm.test.ts | 184 ++++++++++++++++ src/lib/input.ts | 52 ++++- src/program.ts | 10 +- src/test/setup.test.ts | 17 ++ src/test/setup.ts | 32 +++ vitest.config.ts | 8 + 18 files changed, 1055 insertions(+), 75 deletions(-) create mode 100644 src/commands/workspace-header.test.ts create mode 100644 src/coverage.test.ts create mode 100644 src/test/setup.test.ts create mode 100644 src/test/setup.ts create mode 100644 vitest.config.ts diff --git a/.changeset/contract-1-36.md b/.changeset/contract-1-36.md index cd8c42b..0b44633 100644 --- a/.changeset/contract-1-36.md +++ b/.changeset/contract-1-36.md @@ -4,11 +4,17 @@ Catch up with the B2B contract 1.36.0 (from 1.24.0). -- **Lineup**: `ft artists search`, `ft events artists set|remove` and `ft events invitations list|resend|cancel`. `set` asks before removing anyone from the lineup and prints `ARTIST_IDS_IGNORED` warnings. +- **Lineup**: `ft artists search`, `ft events artists set|remove` and `ft events invitations list|resend|cancel`. `set` asks before removing anyone from the lineup or emailing `--invite` invitations, and prints `ARTIST_IDS_IGNORED` warnings. - **Scheduling and presales**: `ft events schedule set|clear` and `ft presale-windows list|create|update|delete` (alias `presales`). -- **Box office and door**: `ft sales transfer`, `ft sales recipient set`, `ft sales abandon`, `ft sales intents` (checkout funnel), `ft tickets checkin-undo`, `ft event-dates courtesy-seats`, `ft event-dates access-close status|sign`, `ft reports live-attendance`, `ft master-qrs` (with `activate`/`deactivate`; the table hides the secret `code`/`url` unless `--full`) and `ft ticket-templates` (with `instantiate`). -- **Access**: `ft events viewers list|add|remove`, `ft events validators list|add`, `ft staff access` (full replace, from flags or `--data`) and `ft staff resend-invite`. +- **Box office and door**: `ft sales transfer`, `ft sales recipient set`, `ft sales abandon`, `ft sales intents` (checkout funnel), `ft tickets checkin-undo`, `ft event-dates courtesy-seats`, `ft event-dates access-close status|sign`, `ft reports live-attendance`, `ft master-qrs` (with `activate`/`deactivate`) and `ft ticket-templates` (with `instantiate`). +- **Access**: `ft events viewers list|add|remove`, `ft events validators list|add`, `ft staff access` (full replace, from flags or from `--data`, not both) and `ft staff resend-invite`. - **Community**: `ft content-posts update|delete|pin|unpin`, `ft content-videos update|delete|publish|unpublish|set-series`, `ft content-series`, `ft content-lives create|update|delete|chat|reset-key`, `ft content-channels`, `ft content-meetups` (with `publish`, `cancel`, `rsvp`, `attendance`), `ft content-moderation`, `ft content-comments` and `ft content-members ban|unban`. - **Workspace**: `ft products`, `ft organization update|analytics|profile`, `ft website get|set|publish|unpublish` and `ft merch catalog`. -Every operation the contract marks `x-ft-destructive`, and every command that sends email or notifies a whole community (viewer/validator invitations, resend-invite, meetup publish and RSVP decisions), asks for confirmation; `--yes` skips it and without a TTY they refuse. A test fails if a destructive operation of the contract has no such gate. The buyer side of the merch store (place an order, look one up, pay it by card) is left out on purpose: it needs the buyer's session and a Payment Brick token. +Confirmation: every operation the contract marks `x-ft-destructive` asks first, and so do `events viewers add`, `events validators add`, `events invitations resend`, `events artists set --invite`, `staff resend-invite`, `content-meetups publish`, `content-meetups rsvp`, `content-videos publish` (they email or notify people) and `website set` (a full replace). `--yes` skips the question; without a TTY they refuse. `content-moderation approve`, `tickets resend`, `content-posts create` and `products update` notify without asking, on purpose. Tests check that each gated command refuses without `--yes` and calls its operation with it, and that no `x-ft-destructive` operation of the contract is left without a gate. + +Master QR secrets: `ft master-qrs list` and `update` leave the secret `code` and `url` out, in the table and in `--json`, unless `--full`. `create` prints them, because you need them to print the QR. + +Flag validation: COP amounts, capacities and pages (`ticket-templates instantiate --price/--capacity`, `presale-windows --capacity`, `content-moderation --page`) take whole numbers only, `--limit` on `artists search` and `sales intents` an integer from 1 to 100, and `--active` (presale windows, `discounts list`) and `--attended` only `true` or `false`. `50.000`, `1,000`, `abc` or `yes` exit 1 before any request instead of being sent as 50, NaN/null or false. + +The buyer side of the merch store (place an order, look one up, pay it by card) and the buyer API (`/customer/*`) are left out on purpose: they need a buyer session or a Payment Brick token. diff --git a/README.md b/README.md index 08d3444..a1df0d8 100644 --- a/README.md +++ b/README.md @@ -96,20 +96,20 @@ ft sales list --status CONFIRMED --json | `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 set --artist ... [--invite ...]` | Replace the lineup, in order (unlisted artists are unlinked; asks before removing anyone or emailing `--invite` invitations, `--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 events invitations list ` · `resend ` · `cancel ` | Invitations sent to artists without an account: list, resend (renews 14 days, sends an email) and cancel; `resend` and `cancel` ask (`--yes`) | ADMIN | | `ft events schedule set --publish-at ` \| `--sale-starts-at ` · `schedule clear ` | Schedule a DRAFT: publish later, or publish now and open sales later (exactly one flag) · cancel a pending `--publish-at` | ADMIN | | `ft events viewers list ` · `add --email ` · `remove ` | Read-only viewers of an event's stats; `add` emails the link (and creates a VIEWER account if needed), both `add` and `remove` ask (`--yes`) | ADMIN | | `ft events validators list ` · `add --name --email ` | Door staff of an event (additive; a new account gets an invitation email, so `add` asks, `--yes`) | ADMIN | | `ft event-dates list` · `create` · `update` · `delete` | Event dates | ADMIN | | `ft event-dates courtesy-seats ` | Blocked seats of a numbered date that can be issued as courtesies | ADMIN | | `ft event-dates access-close status ` · `sign ` | Live entry count · sign the access-close record (freezes the count and emails it; IRREVERSIBLE, `--yes`) | STAFF · ADMIN | -| `ft ticket-templates list` · `create` · `update ` · `delete ` · `instantiate --event-date [--name --price --capacity]` | Reusable ticket type templates; `instantiate` creates a ticket type on a date (`delete` asks, `--yes`) | ADMIN | -| `ft master-qrs list [--full]` · `create` · `update ` · `activate ` · `deactivate ` · `delete ` | Master box-office QRs (`code`/`url` are secret: the table hides them unless `--full`; `delete` asks, `--yes`) | ADMIN | +| `ft ticket-templates list` · `create` · `update ` · `delete ` · `instantiate --event-date [--name --price --capacity]` | Reusable ticket type templates; `instantiate` creates a ticket type on a date (`--price`/`--capacity` are whole numbers: `50000`, not `50.000`; `delete` asks, `--yes`) | ADMIN | +| `ft master-qrs list [--full]` · `create` · `update ` · `activate ` · `deactivate ` · `delete ` | Master box-office QRs. `code`/`url` are secret and never rotate: `list` and `update` leave them out, `--json` included, unless `--full`; `create` prints them (you need them to print the QR); `delete` asks, `--yes` | ADMIN | | `ft ticket-types list` · `get ` | Ticket types (`--event-date-id`) | VIEWER | | `ft ticket-types create` · `update ` · `delete ` | Manage ticket types (`--data `) | ADMIN | -| `ft presale-windows list ` · `create --plan --starts-at --ends-at [--capacity --active]` · `update ` · `delete ` | Membership presale windows (alias `presales`; one per plan; `delete` asks, `--yes` skips) | ADMIN | +| `ft presale-windows list ` · `create --plan --starts-at --ends-at [--capacity --active]` · `update ` · `delete ` | Membership presale windows (alias `presales`; one per plan; `--capacity` is a whole number or `none`, `--active` is `true`/`false`; `delete` asks, `--yes` skips) | ADMIN | | `ft sales list` · `get ` | Sales (filters: `--status` `--channel` `--event` `--event-date` `--reference` `--buyer` `--from` `--to`) | STAFF | | `ft sales create` | Create a sale/order — comps & programmatic sales (`--data `) | ADMIN | | `ft sales cancel ` · `refund ` | Cancel / refund a sale (`--data` for the `acknowledge_open_payment` / `acknowledge_manual` flags) | ADMIN | @@ -132,7 +132,7 @@ ft sales list --status CONFIRMED --json | `ft venues list` · `get ` | Venues | VIEWER | | `ft venues create` · `update ` · `delete ` | Manage venues (`--data `) | ADMIN | | `ft staff list` · `get ` · `create` · `set-role ` · `delete ` | Workspace staff (`--workspace-ids ` lists up to 25 workspaces in one call; `--data `) | ADMIN | -| `ft staff access --type admin\|validador\|personalizado\|lectura [--sections --validator-events --viewer-events --expires-at]` | FULL replace of a member's access in this workspace (or `--data`; asks, `--yes`) | ADMIN | +| `ft staff access --type admin\|validador\|personalizado\|lectura [--sections --validator-events --viewer-events --expires-at]` | FULL replace of a member's access in this workspace (or the whole body with `--data`, not both; asks, `--yes`) | ADMIN | | `ft staff resend-invite ` | Email the invitation link again (asks, `--yes`) | ADMIN | | `ft reports summary` | KPIs (`--period 7d\|30d\|90d\|1y`) | VIEWER | | `ft reports by-event` · `timeseries` · `inventory` | Revenue/tickets by event, over time, and capacity/availability | VIEWER | @@ -142,13 +142,13 @@ ft sales list --status CONFIRMED --json | `ft settlements list` · `get ` · `document ` | Settlements paid to the organizer · signed download URL for the PDF, 5 min TTL (`--proof ` for a payment proof) | ADMIN | | `ft content-videos list` · `content-posts list\|create` · `content-lives list\|get\|playback-token` | Organization content; `content-posts create --data` publishes a post or article | ADMIN | | `ft content-posts update ` · `delete ` · `pin ` · `unpin ` | Edit, delete (`--yes`) and pin community posts | ADMIN | -| `ft content-videos update ` · `delete ` · `publish ` · `unpublish ` · `set-series --series ` · `ft content-series list\|create\|update\|delete\|publish\|unpublish` | On-demand videos and video series (deletes ask, `--yes`) | ADMIN | +| `ft content-videos update ` · `delete ` · `publish ` · `unpublish ` · `set-series --series ` · `ft content-series list\|create\|update\|delete\|publish\|unpublish` | On-demand videos and video series (deletes and video `publish`, which notifies members, ask, `--yes`) | ADMIN | | `ft content-lives create` · `update ` · `delete ` · `chat ` · `reset-key ` | Live streams: `create` and `reset-key` print the SECRET stream key once; `delete` and `reset-key` ask (`--yes`) | ADMIN | | `ft content-channels list` · `create` · `update ` · `order ` · `archive ` | Community channels (`archive` has no undo, `--yes`) | ADMIN | -| `ft content-meetups list` · `get` · `create` · `update` · `publish ` · `cancel ` · `rsvp --approve\|--reject` · `attendance ` | Community meetups; `publish`, `cancel` and `rsvp` notify members, so they ask (`--yes`) | ADMIN | -| `ft content-moderation queue\|bans\|member-posts` · `approve --expected-updated-at ` · `reject ` · `remove ` · `ft content-comments hide\|unhide\|ignore-reports\|delete ` · `ft content-members ban --comment ` · `unban ` | Community moderation (`reject`, `remove`, `delete` and `ban` ask, `--yes`) | STAFF · ADMIN | +| `ft content-meetups list` · `get` · `create` · `update` · `publish ` · `cancel ` · `rsvp --approve\|--reject` · `attendance ` | Community meetups; `publish`, `cancel` and `rsvp` notify members, so they ask (`--yes`); `attendance --attended true\|false` | ADMIN | +| `ft content-moderation queue\|bans\|member-posts` · `approve --expected-updated-at ` · `reject ` · `remove ` · `ft content-comments hide\|unhide\|ignore-reports\|delete ` · `ft content-members ban --comment ` · `unban ` | Community moderation (`reject`, `remove`, `delete` and `ban` ask, `--yes`; `approve` does not: it is the reviewer's decision and is pinned to `--expected-updated-at`) | STAFF · ADMIN | | `ft products list` · `get` · `create` · `update` · `delete` · `status --status DRAFT\|PUBLISHED` | Digital products and courses (`--data `; `delete` asks) | ADMIN | -| `ft organization update --data` · `analytics ` · `profile get\|update` · `ft website get\|set --data\|publish\|unpublish` | Workspace identity, profile, GA4 and public website (`website set` is a FULL replace: start from `website get --json`) | ADMIN | +| `ft organization update --data` · `analytics ` · `profile get\|update` · `ft website get\|set --data\|publish\|unpublish` | Workspace identity, profile, GA4 and public website (`website set` is a FULL replace, so it asks, `--yes`: start from `website get --json`) | ADMIN | | `ft merch catalog` | Merch store settings and published products with live stock (needs an enterprise service key) | — | | `ft waitlist list [--city ]` · `waitlist create --data` | Per-city waitlist of an enterprise landing (export with personal data); `create` needs an enterprise service key | ADMIN | | `ft api-keys create ` · `list` · `revoke ` | Self-service API keys (the secret is shown once, never stored) | ADMIN | @@ -156,7 +156,14 @@ ft sales list --status CONFIRMED --json > **Write operations** (`create`/`update`/`delete` and actions like `publish`, > `cancel`, `refund`) send a JSON body via `--data ` or -> `--data @file.json`. `delete` prompts for confirmation unless you pass `--yes`. +> `--data @file.json`. `delete` prompts for confirmation unless you pass `--yes`, and so do the +> commands that cannot be taken back or that email or notify people (each +> row says which). Without a TTY and without `--yes` they exit 1 before any +> write. Four notify without asking, on purpose: `tickets resend`, +> `content-posts create`, `products update` and `content-moderation approve`. +> Numeric flags take whole numbers only (`50000`, never +> `50.000` or `50,000`) and boolean flags only `true`/`false`: anything else +> exits 1 before any request. ### Common flags diff --git a/src/commands/box-office.ts b/src/commands/box-office.ts index 9e5387e..07b6769 100644 --- a/src/commands/box-office.ts +++ b/src/commands/box-office.ts @@ -8,15 +8,18 @@ import { getPaymentIntents, getReportsLiveAttendance, getTicketTemplates, + patchMasterQrsId, postEventDatesIdAccessClose, postEventsIdValidators, postEventsIdViewers, + postMasterQrs, postStaffIdResendInvite, postTicketTemplatesIdInstantiate, putMasterQrsIdActive, putStaffIdAccess, } from "../client/sdk.gen"; import { fail } from "../lib/api"; +import { parseLimit, wholeNumber } from "../lib/input"; import { list, op, orNull } from "./op"; /** @@ -92,6 +95,15 @@ export function registerEventAccess(events: Command): void { const ACCESS_TYPES = ["admin", "validador", "personalizado", "lectura"]; +/** Body flags of `staff access` (option key, flag), exclusive with --data. */ +const ACCESS_FLAGS = [ + ["type", "--type"], + ["sections", "--sections"], + ["validatorEvents", "--validator-events"], + ["viewerEvents", "--viewer-events"], + ["expiresAt", "--expires-at"], +] as const; + /** `ft staff access ` and `ft staff resend-invite ` */ export function registerStaffAccess(staff: Command): void { op(staff, { @@ -113,7 +125,16 @@ export function registerStaffAccess(staff: Command): void { ], data: "optional", check: (_args, o) => { - if (o.data !== undefined) return; + if (o.data !== undefined) { + // --data is the whole body: flags next to it would be dropped silently, + // and in a full replace a dropped --sections is access removed. + const mixed = ACCESS_FLAGS.filter(([key]) => o[key] !== undefined); + if (mixed.length > 0) + fail( + `Pass either --data or the flags, not both (got --data and ${mixed.map(([, flag]) => flag).join(", ")}).`, + ); + return; + } if (!o.type) fail("Pass --type (or the whole body with --data)."); if (!ACCESS_TYPES.includes(o.type)) fail(`--type must be one of: ${ACCESS_TYPES.join(", ")}.`); @@ -179,7 +200,7 @@ export function registerPaymentIntents(sales: Command): void { options: [ ["--event-date ", "only this date"], ["--only-abandoned", "only journeys that did not buy"], - ["--limit ", "rows per page"], + ["--limit ", "rows per page (1-100)", parseLimit], ["--cursor ", "pagination cursor"], ], call: (_args, o) => @@ -188,7 +209,7 @@ export function registerPaymentIntents(sales: Command): void { event: o.event, eventDate: o.eventDate, onlyAbandoned: o.onlyAbandoned ? true : undefined, - limit: o.limit ? Number(o.limit) : undefined, + limit: o.limit, cursor: o.cursor, }, }), @@ -230,19 +251,61 @@ export function registerLiveAttendance(reports: Command): void { }); } -/** Extras of `ft master-qrs`: list and activate/deactivate. */ +/** Master QR `code` and `url` are secrets: whoever has them reaches the sale flow. */ +const SECRET_QR_FIELDS = ["code", "url"]; + +/** + * Drops `code`/`url` from a master QR (or a list of them) unless `--full`. + * Applies to `--json` too: a JSON dump piped into a log or an agent's context + * leaks the secret just as well as a table, and it cannot be rotated. + */ +export function redactMasterQr(data: unknown, full: boolean): unknown { + if (full) return data; + const strip = (row: unknown) => + row && typeof row === "object" + ? Object.fromEntries( + Object.entries(row).filter(([k]) => !SECRET_QR_FIELDS.includes(k)), + ) + : row; + return Array.isArray(data) ? data.map(strip) : strip(data); +} + +const FULL: [string, string] = [ + "--full", + "include the secret code and url (table and --json)", +]; + +/** `ft master-qrs list|create|update|activate|deactivate` (delete is CRUD). */ export function extendMasterQrs(root: Command): void { op(root, { name: "list", describe: - "Master box-office QR codes (`code`/`url` are secret: shown only with --full or --json)", - options: [["--full", "show every field, including code and url"]], + "Master box-office QR codes (`code`/`url` are secret: left out, also from --json, unless --full)", + options: [FULL], call: () => getMasterQrs({}), + pick: (body, o) => redactMasterQr(body.data, Boolean(o.full)), columns: (o) => o.full ? undefined : ["id", "label", "mode", "eventId", "active", "scans", "lastScanAt"], }); + op(root, { + name: "create", + describe: + "Create a master QR. Prints its SECRET code and url: you need them to print the QR, they never rotate, and whoever has them reaches the sale flow. Keep the output private.", + data: "required", + call: (_a, _o, data) => postMasterQrs({ body: data as never }), + }); + op(root, { + name: "update ", + describe: + "Update a master QR (label, mode, eventId, ticketTypeId). The secret code/url are left out of the output unless --full", + data: "required", + options: [FULL], + call: ([id], _o, data) => + patchMasterQrsId({ path: { id }, body: data as never }), + pick: (body, o) => redactMasterQr(body.data, Boolean(o.full)), + }); for (const [name, active] of [ ["activate", true], ["deactivate", false], @@ -268,8 +331,16 @@ export function extendTicketTemplates(root: Command): void { required: [["--event-date ", "event date that gets the ticket type"]], options: [ ["--name ", "override the template's name"], - ["--price ", "override the price"], - ["--capacity ", "override the capacity"], + [ + "--price ", + "override the price (whole COP, no separators: 50000)", + wholeNumber("--price"), + ], + [ + "--capacity ", + "override the capacity (whole number)", + wholeNumber("--capacity"), + ], ], call: ([templateId], o) => postTicketTemplatesIdInstantiate({ @@ -277,8 +348,8 @@ export function extendTicketTemplates(root: Command): void { body: { eventDateId: o.eventDate, name: o.name, - price: o.price === undefined ? undefined : Number(o.price), - capacity: o.capacity === undefined ? undefined : Number(o.capacity), + price: o.price, + capacity: o.capacity, }, }), }); diff --git a/src/commands/community.ts b/src/commands/community.ts index 2763ad7..9fdce06 100644 --- a/src/commands/community.ts +++ b/src/commands/community.ts @@ -26,7 +26,8 @@ import { putContentVideosIdSeries, } from "../client/sdk.gen"; import { fail } from "../lib/api"; -import { bool, list, op, orNull } from "./op"; +import { booleanFlag, wholeNumber } from "../lib/input"; +import { list, op, orNull } from "./op"; /** * Community management from contracts 1.26-1.36 (channels, posts, videos and @@ -35,8 +36,11 @@ import { bool, list, op, orNull } from "./op"; * body, a second id or no id at all. */ -const page = (v: string | undefined) => - v === undefined ? undefined : Number(v); +const PAGE: [string, string, (input: string) => number] = [ + "--page ", + "0-based page", + wholeNumber("--page"), +]; /** Extras of `ft content-posts`: pin/unpin. */ export function extendContentPosts(root: Command): void { @@ -62,8 +66,12 @@ export function extendContentVideos(root: Command): void { op(root, { name: `${name} `, describe: published - ? "Publish a video to the community feed (members are notified once)" + ? "Publish a video to the community feed (members are notified once, so it asks; --yes skips)" : "Take a video out of the feed", + // Publishing notifies every member; unpublishing notifies nobody. + confirm: published + ? ([id]) => `Publish video ${id}? Community members get notified.` + : undefined, call: ([id]) => putContentVideosIdPublished({ path: { id }, body: { published } }), }); @@ -176,11 +184,17 @@ export function extendContentMeetups(root: Command): void { name: "attendance ", describe: "Mark (or with --attended false, unmark) an attendee as checked in", - options: [["--attended ", "true | false", "true"]], + options: [ + [ + "--attended ", + "true | false (default true)", + booleanFlag("--attended"), + ], + ], call: ([id, rsvpId], o) => putContentMeetupsIdAttendance({ path: { id }, - body: { rsvpId, attended: bool(o.attended) }, + body: { rsvpId, attended: o.attended ?? true }, }), }); } @@ -194,9 +208,8 @@ export function registerModeration(program: Command): void { op(mod, { name: "queue", describe: "Reported comments, most reported first (50 per page)", - options: [["--page ", "0-based page"]], - call: (_a, o) => - getContentModerationQueue({ query: { page: page(o.page) } }), + options: [PAGE], + call: (_a, o) => getContentModerationQueue({ query: { page: o.page } }), columns: ["commentId", "openReportCount", "hidden", "deleted", "body"], }); op(mod, { @@ -208,13 +221,10 @@ export function registerModeration(program: Command): void { op(mod, { name: "member-posts", describe: "Member posts awaiting review (or recently published)", - options: [ - ["--status ", "PENDING_REVIEW | PUBLISHED"], - ["--page ", "0-based page"], - ], + options: [["--status ", "PENDING_REVIEW | PUBLISHED"], PAGE], call: (_a, o) => getContentModerationMemberPosts({ - query: { status: o.status, page: page(o.page) }, + query: { status: o.status, page: o.page }, }), columns: ["postId", "status", "channelName", "updatedAt", "content"], }); diff --git a/src/commands/lineup.ts b/src/commands/lineup.ts index 02bf090..9589221 100644 --- a/src/commands/lineup.ts +++ b/src/commands/lineup.ts @@ -10,7 +10,7 @@ import { putEventsIdArtists, } from "../client/sdk.gen"; import { configureClient, unwrap } from "../lib/api"; -import { confirmOrExit } from "../lib/input"; +import { confirmOrExit, parseLimit } from "../lib/input"; import { print, printNextCursor } from "../lib/output"; /** Prints API `warnings[]` (e.g. ARTIST_IDS_IGNORED) on stderr, keeping stdout clean for --json. */ @@ -37,7 +37,7 @@ export function registerArtists(program: Command): void { root .command("search ") .description("Search registered artists by name (2+ characters)") - .option("--limit ", "results per page (1-100)", "20") + .option("--limit ", "results per page (1-100)", parseLimit, 20) .option("--cursor ", "pagination cursor") .option("--workspace ", "workspace override") .option("--json", "raw JSON output") @@ -45,7 +45,7 @@ export function registerArtists(program: Command): void { configureClient(opts.workspace); const body = unwrap( await getArtists({ - query: { q, limit: Number(opts.limit), cursor: opts.cursor }, + query: { q, limit: opts.limit, cursor: opts.cursor }, }), ); print(body.data, { @@ -77,25 +77,40 @@ export function registerEventLineup(events: Command): void { ) .option( "--invite ", - "invite artists without an account (additive)", + "invite artists without an account (additive; sends them an email, so it asks)", + ) + .option( + "--yes", + "skip confirmation (asked when artists would be removed or invitations emailed)", ) - .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 ?? []; + const invites: string[] = opts.invite ?? []; 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) + const asks: string[] = []; + if (artistIds.length === 0) + asks.push( + `Clear the lineup of event ${eventId}${removed.length ? ` (removes ${removed.map((a) => a.name).join(", ")})` : ""}`, + ); + else if (removed.length > 0) + asks.push( + `Remove ${removed.map((a) => a.name).join(", ")} from event ${eventId}`, + ); + // Each invitation is an email to someone outside FreeTicket. + if (invites.length > 0) + asks.push(`email an invitation to ${invites.join(", ")}`); + const question = asks.join(" and "); + if (question) 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}?`, + `${question[0]?.toUpperCase()}${question.slice(1)}?`, false, ); } @@ -158,10 +173,17 @@ export function registerEventLineup(events: Command): void { invitations .command("resend ") - .description("Resend an invitation email and renew it for 14 days") + .description( + "Resend an invitation email and renew it for 14 days (asks; --yes skips)", + ) + .option("--yes", "skip confirmation") .option("--workspace ", "workspace override") .option("--json", "raw JSON output") .action(async (eventId, invitationId, opts) => { + await confirmOrExit( + `Resend invitation ${invitationId} of event ${eventId}? The artist gets another email.`, + opts.yes, + ); configureClient(opts.workspace); const body = unwrap( await postEventsIdArtistInvitationsInvitationIdResend({ diff --git a/src/commands/op.ts b/src/commands/op.ts index 6419e30..81f9f41 100644 --- a/src/commands/op.ts +++ b/src/commands/op.ts @@ -19,8 +19,12 @@ export interface OpSpec { /** Commander signature, e.g. `"remove "`. */ name: string; describe: string; - /** Optional flags: [flags, description, default?]. */ - options?: [string, string, string?][]; + /** + * Optional flags: [flags, description, default or parser?]. A parser (e.g. + * `wholeNumber("--price")` from lib/input) runs while commander parses argv, + * so a bad value exits 1 before the confirmation and the request. + */ + options?: [string, string, (string | ((input: string) => unknown))?][]; /** Required flags: [flags, description]. */ required?: [string, string][]; /** `--data ` body (inline or @file): "required" or "optional". */ @@ -45,8 +49,8 @@ export function op(parent: Command, spec: OpSpec): Command { const cmd = parent.command(spec.name).description(spec.describe); for (const [flags, describe] of spec.required ?? []) cmd.requiredOption(flags, describe); - for (const [flags, describe, def] of spec.options ?? []) - cmd.option(flags, describe, def); + for (const [flags, describe, defOrParse] of spec.options ?? []) + cmd.option(flags, describe, defOrParse as never); if (spec.data === "required") cmd.requiredOption("--data ", "JSON body (inline or @file.json)"); else if (spec.data === "optional") @@ -74,9 +78,6 @@ export function op(parent: Command, spec: OpSpec): Command { return cmd; } -/** `"true"`/`"false"` flag value to boolean (anything else is false). */ -export const bool = (v: unknown) => v === true || v === "true"; - /** `"none"` clears a nullable field; anything else is sent as is. */ export const orNull = (v: string) => (v === "none" ? null : v); diff --git a/src/commands/ops.ts b/src/commands/ops.ts index 85ec9d1..a826df2 100644 --- a/src/commands/ops.ts +++ b/src/commands/ops.ts @@ -12,7 +12,12 @@ import { postTicketTypesIdPresaleWindows, } from "../client/sdk.gen"; import { configureClient, fail, unwrap } from "../lib/api"; -import { confirmOrExit } from "../lib/input"; +import { + booleanFlag, + confirmOrExit, + noneToNull, + wholeNumberOrNone, +} from "../lib/input"; import { print } from "../lib/output"; /** @@ -32,19 +37,32 @@ const PRESALE_COLUMNS = [ "isActive", ]; +/** Presale window flags, already typed by the commander parsers below. */ +interface PresaleOpts { + plan?: string; + startsAt?: string; + endsAt?: string; + capacity?: number | "none"; + active?: boolean; +} + /** Presale window body from flags; only the flags passed are sent. */ -function presaleBody(opts: Record) { +function presaleBody(opts: PresaleOpts) { const body: Record = {}; if (opts.plan) body.planId = opts.plan; if (opts.startsAt) body.presaleStartsAt = opts.startsAt; if (opts.endsAt) body.presaleEndsAt = opts.endsAt; if (opts.capacity !== undefined) - body.presaleCapacity = - opts.capacity === "none" ? null : Number(opts.capacity); - if (opts.active !== undefined) body.isActive = opts.active === "true"; + body.presaleCapacity = noneToNull(opts.capacity); + if (opts.active !== undefined) body.isActive = opts.active; return body; } +// Parsed while commander reads argv: `--capacity 1,000` or `--active yes` +// exit 1 before any request instead of sending 1 or false. +const capacity = wholeNumberOrNone("--capacity"); +const active = booleanFlag("--active"); + /** `ft events schedule set|clear ` */ export function registerEventSchedule(events: Command): void { const schedule = events @@ -122,8 +140,12 @@ export function registerPresaleWindows(program: Command): void { .requiredOption("--plan ", "membership plan of this workspace") .requiredOption("--starts-at ", "presale start (UTC)") .requiredOption("--ends-at ", "presale end (UTC, after start)") - .option("--capacity ", "max tickets sold in the presale") - .option("--active ", "true | false (default true)") + .option( + "--capacity ", + 'max tickets sold in the presale (whole number, or "none")', + capacity, + ) + .option("--active ", "true | false (default true)", active) .option("--workspace ", "workspace override") .option("--json", "raw JSON output") .action(async (ticketTypeId, opts) => { @@ -143,8 +165,12 @@ export function registerPresaleWindows(program: Command): void { .option("--plan ", "membership plan of this workspace") .option("--starts-at ", "presale start (UTC)") .option("--ends-at ", "presale end (UTC)") - .option("--capacity ", 'max tickets, or "none" to remove the cap') - .option("--active ", "true | false") + .option( + "--capacity ", + 'max tickets (whole number), or "none" to remove the cap', + capacity, + ) + .option("--active ", "true | false", active) .option("--workspace ", "workspace override") .option("--json", "raw JSON output") .action(async (windowId, opts) => { diff --git a/src/commands/resource.ts b/src/commands/resource.ts index 69a1555..b141432 100644 --- a/src/commands/resource.ts +++ b/src/commands/resource.ts @@ -54,7 +54,13 @@ interface ResourceSpec { /** Columns to show in list table / CSV output. */ columns?: string[]; /** Extra list flags -> query entries. Example: status, eventDateId. */ - listFlags?: { flag: string; describe: string; query: string }[]; + listFlags?: { + flag: string; + describe: string; + query: string; + /** Commander parser (e.g. `booleanFlag`), run before any request. */ + parse?: (input: string) => unknown; + }[]; /** Commands that don't fit the CRUD shape (extra args, non-JSON responses). */ extend?: (root: Command) => void; } @@ -88,7 +94,9 @@ export function registerResource(program: Command, spec: ResourceSpec): void { .option("--csv", "CSV output (for spreadsheets/accounting)") .option("--json", "raw JSON output (data only)") .option("--raw", "raw JSON output including pagination metadata (page)"); - for (const f of spec.listFlags ?? []) cmd.option(f.flag, f.describe); + for (const f of spec.listFlags ?? []) + if (f.parse) cmd.option(f.flag, f.describe, f.parse); + else cmd.option(f.flag, f.describe); cmd.action(async (opts) => { let columns = resolveColumns(opts, spec.columns); opts.limit = parseLimit(opts.limit); diff --git a/src/commands/storefront.ts b/src/commands/storefront.ts index db1e613..0ed6618 100644 --- a/src/commands/storefront.ts +++ b/src/commands/storefront.ts @@ -99,8 +99,11 @@ export function registerWebsite(program: Command): void { op(root, { name: "set", describe: - "Save the whole website configuration (FULL replace: start from `ft website get --json`)", + "Save the whole website configuration (FULL replace: start from `ft website get --json`; asks, --yes skips)", data: "required", + // A PUT of the whole config: a partial --data wipes every section left out. + confirm: () => + "Replace the whole website configuration of this workspace? Sections missing from --data are removed.", call: (_a, _o, data) => putWebsite({ body: data as never }), }); for (const [name, published] of [ diff --git a/src/commands/wire.test.ts b/src/commands/wire.test.ts index 616fad2..e2c73c1 100644 --- a/src/commands/wire.test.ts +++ b/src/commands/wire.test.ts @@ -353,3 +353,292 @@ describe("community", () => { }); }); }); + +/** Runs argv expecting exit 1; returns what went to stderr. */ +async function refused(...args: string[]): Promise { + await expect(program.parseAsync(["node", "ft", ...args])).rejects.toThrow( + "exited", + ); + expect(process.exit).toHaveBeenCalledWith(1); + return vi + .mocked(console.error) + .mock.calls.map((c) => String(c[0])) + .join("\n"); +} + +/** Everything written to stdout (where print sends --json and tables). */ +const stdout = () => + [ + ...vi.mocked(process.stdout.write).mock.calls.map((c) => String(c[0])), + ...vi.mocked(console.log).mock.calls.map((c) => String(c[0])), + ].join("\n"); + +const json = (body: unknown, status = 200) => + new Response(JSON.stringify(body), { + status, + headers: { "Content-Type": "application/json" }, + }); + +describe("typed flags: a malformed number or boolean exits 1 before any request", () => { + // Number("50.000") === 50 and NaN serializes as null: these used to reach + // the API as fifty pesos, or as a capacity silently cleared. + it.each([ + [ + ["ticket-templates", "instantiate", "tpl_A", "--event-date", "date_B"], + ["--price", "50.000"], + ], + [ + ["ticket-templates", "instantiate", "tpl_A", "--event-date", "date_B"], + ["--capacity", "abc"], + ], + [ + ["ticket-templates", "instantiate", "tpl_A", "--event-date", "date_B"], + ["--price", "-5"], + ], + [ + ["presale-windows", "update", "pw_A"], + ["--capacity", "1,000"], + ], + [ + ["presale-windows", "update", "pw_A"], + ["--active", "yes"], + ], + [ + [ + "presale-windows", + "create", + "tt_A", + "--plan", + "plan_B", + "--starts-at", + "2027-01-01T00:00:00Z", + "--ends-at", + "2027-01-02T00:00:00Z", + ], + ["--capacity", "abc"], + ], + [ + ["content-meetups", "attendance", "mt_A", "rsvp_B"], + ["--attended", "si"], + ], + [ + ["content-moderation", "queue"], + ["--page", "1.5"], + ], + [ + ["discounts", "list", "--workspace", "ws_A"], + ["--active", "yes"], + ], + [ + ["sales", "intents", "--event", "evt_A"], + ["--limit", "1e1"], + ], + [ + ["artists", "search", "rock"], + ["--limit", "abc"], + ], + ])("ft %j %j", async (args, [flag, value]) => { + const err = await refused(...args, flag as string, value as string); + expect(err).toContain(`Invalid ${flag}: ${value}`); + expect(fetchMock).not.toHaveBeenCalled(); + }); + + it("presale --capacity none still clears the cap and --active false is false", async () => { + const sent = await send( + "presale-windows", + "update", + "pw_A", + "--capacity", + "none", + "--active", + "false", + ); + expect(sent.body).toEqual({ presaleCapacity: null, isActive: false }); + }); + + it("instantiate sends whole numbers as numbers", async () => { + const sent = await send( + "ticket-templates", + "instantiate", + "tpl_A", + "--event-date", + "date_B", + "--price", + "50000", + "--capacity", + "1000", + ); + expect(sent.body).toEqual({ + eventDateId: "date_B", + price: 50000, + capacity: 1000, + }); + }); +}); + +describe("staff access: --data or flags, never both", () => { + it("--data with --type exits 1 before any request", async () => { + const err = await refused( + "staff", + "access", + "stf_A", + "--data", + '{"accessType":"admin"}', + "--type", + "lectura", + "--sections", + "eventos", + "--yes", + ); + expect(err).toContain( + "Pass either --data or the flags, not both (got --data and --type, --sections)", + ); + expect(fetchMock).not.toHaveBeenCalled(); + }); +}); + +describe("master-qrs: the secret code and url", () => { + const qr = { + id: "mq_A", + label: "Taquilla", + mode: "EVENT", + eventId: "evt_B", + ticketTypeId: null, + active: true, + scans: 3, + lastScanAt: null, + createdAt: "2026-11-01T00:00:00Z", + code: "SECRETCODE42", + url: "https://t.test/mq/SECRETCODE42", + }; + + it("list --json leaves code and url out", async () => { + fetchMock.mockResolvedValueOnce(json({ data: [qr] })); + await send("master-qrs", "list"); + expect(stdout()).toContain("mq_A"); + expect(stdout()).not.toContain("SECRETCODE42"); + }); + + it("list as a table leaves them out too", async () => { + fetchMock.mockResolvedValueOnce(json({ data: [qr] })); + await program.parseAsync(["node", "ft", "master-qrs", "list"]); + expect(stdout()).toContain("mq_A"); + expect(stdout()).not.toContain("SECRETCODE42"); + }); + + it("list --full --json shows them", async () => { + fetchMock.mockResolvedValueOnce(json({ data: [qr] })); + await send("master-qrs", "list", "--full"); + expect(stdout()).toContain("SECRETCODE42"); + expect(stdout()).toContain("https://t.test/mq/SECRETCODE42"); + }); + + it("update --json redacts the QR it answers with", async () => { + fetchMock.mockResolvedValueOnce(json({ data: qr })); + expect( + await send("master-qrs", "update", "mq_A", "--data", '{"label":"B"}'), + ).toEqual({ + method: "PATCH", + path: "/master-qrs/mq_A", + body: { label: "B" }, + }); + expect(stdout()).toContain("Taquilla"); + expect(stdout()).not.toContain("SECRETCODE42"); + }); + + it("create prints the secret (needed to print the QR) and says so in --help", async () => { + fetchMock.mockResolvedValueOnce(json({ data: qr })); + await send("master-qrs", "create", "--data", '{"label":"Taquilla"}'); + expect(stdout()).toContain("SECRETCODE42"); + const create = program.commands + .find((c) => c.name() === "master-qrs") + ?.commands.find((c) => c.name() === "create"); + expect(create?.description()).toMatch(/SECRET code and url/); + }); +}); + +describe("two ids in the right slots", () => { + it("events artists remove: event, then artist workspace", async () => { + expect( + await send("events", "artists", "remove", "evt_A", "org_B", "--yes"), + ).toEqual({ + method: "DELETE", + path: "/events/evt_A/artists/org_B", + body: undefined, + }); + }); + + it("events invitations cancel: event, then invitation", async () => { + expect( + await send("events", "invitations", "cancel", "evt_A", "inv_B", "--yes"), + ).toEqual({ + method: "DELETE", + path: "/events/evt_A/artist-invitations/inv_B", + body: undefined, + }); + }); + + it("events invitations resend: event, then invitation", async () => { + expect( + await send("events", "invitations", "resend", "evt_A", "inv_B", "--yes"), + ).toEqual({ + method: "POST", + path: "/events/evt_A/artist-invitations/inv_B/resend", + body: undefined, + }); + }); + + it("content-meetups attendance: meetup in the path, rsvp id in the body", async () => { + expect( + await send("content-meetups", "attendance", "mt_A", "rsvp_B"), + ).toEqual({ + method: "PUT", + path: "/content/meetups/mt_A/attendance", + body: { rsvpId: "rsvp_B", attended: true }, + }); + }); + + it("content-meetups attendance --attended false unmarks", async () => { + const sent = await send( + "content-meetups", + "attendance", + "mt_A", + "rsvp_B", + "--attended", + "false", + ); + expect(sent.body).toEqual({ rsvpId: "rsvp_B", attended: false }); + }); +}); + +describe("API errors exit 1 with the message on stderr", () => { + const notFound = () => + json( + { error: { code: "NOT_FOUND", message: "Event evt_A not found" } }, + 404, + ); + const serverError = () => + new Response("upstream exploded", { + status: 500, + headers: { "Content-Type": "text/plain" }, + }); + + it.each([ + ["op()", ["events", "viewers", "list", "evt_A"]], + ["ops.ts", ["presale-windows", "list", "tt_A"]], + ])("404 through %s", async (_via, args) => { + fetchMock.mockResolvedValueOnce(notFound()); + const err = await refused(...args); + expect(err).toContain("Error 404 [NOT_FOUND]: Event evt_A not found"); + expect(err).toContain("does not exist or belongs to another workspace"); + }); + + it.each([ + ["op()", ["events", "viewers", "list", "evt_A"]], + ["ops.ts", ["presale-windows", "list", "tt_A"]], + ])("500 without a JSON body through %s", async (_via, args) => { + fetchMock.mockResolvedValueOnce(serverError()); + const err = await refused(...args); + expect(err).toContain("The API responded with 500 without a readable body"); + }); +}); diff --git a/src/commands/workspace-header.test.ts b/src/commands/workspace-header.test.ts new file mode 100644 index 0000000..12a06c4 --- /dev/null +++ b/src/commands/workspace-header.test.ts @@ -0,0 +1,81 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +/** + * Nothing mocked but `fetch`: the real program, the real `configureClient` + * and the real config resolution, fed by a fake environment (FT_API_KEY, and + * FT_API_URL pointing at a closed local port from src/test/setup.ts). wire.test + * replaces `configureClient`, so a command that stopped calling it, or called + * it before reading `--workspace`, would still pass there. Here the request + * has to carry the key and the workspace the user asked for. + */ +const fetchMock = vi.fn(); +const { program } = await import("../program"); + +beforeEach(() => { + vi.stubEnv("FT_API_KEY", "ft_test_key"); + vi.stubGlobal("fetch", fetchMock); + fetchMock.mockImplementation( + async () => + new Response(JSON.stringify({ data: [] }), { + headers: { "Content-Type": "application/json" }, + }), + ); + 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); +}); + +afterEach(() => { + vi.unstubAllEnvs(); + vi.unstubAllGlobals(); + vi.restoreAllMocks(); + fetchMock.mockReset(); +}); + +async function request(...args: string[]): Promise { + await program.parseAsync(["node", "ft", ...args, "--json"]); + expect(fetchMock).toHaveBeenCalledTimes(1); + return fetchMock.mock.calls[0]?.[0] as Request; +} + +describe("X-Workspace-Id and the API key reach the wire", () => { + it.each([ + ["op()", ["events", "viewers", "list", "evt_A"], "/events/evt_A/viewers"], + [ + "ops.ts", + ["presale-windows", "list", "tt_A"], + "/ticket-types/tt_A/presale-windows", + ], + [ + "lineup.ts", + ["events", "invitations", "list", "evt_A"], + "/events/evt_A/artist-invitations", + ], + ])("%s: --workspace becomes the header", async (_via, args, path) => { + const req = await request(...args, "--workspace", "ws_FLAG"); + expect(req.url).toBe(`http://127.0.0.1:9/api/v1${path}`); + expect(req.headers.get("X-Workspace-Id")).toBe("ws_FLAG"); + expect(req.headers.get("Authorization")).toBe("Bearer ft_test_key"); + }); + + it("FT_WORKSPACE_ID applies when no --workspace is passed", async () => { + vi.stubEnv("FT_WORKSPACE_ID", "ws_ENV"); + const req = await request("events", "viewers", "list", "evt_A"); + expect(req.headers.get("X-Workspace-Id")).toBe("ws_ENV"); + }); + + it("--workspace beats FT_WORKSPACE_ID", async () => { + vi.stubEnv("FT_WORKSPACE_ID", "ws_ENV"); + const req = await request( + "presale-windows", + "list", + "tt_A", + "--workspace", + "ws_FLAG", + ); + expect(req.headers.get("X-Workspace-Id")).toBe("ws_FLAG"); + }); +}); diff --git a/src/coverage.test.ts b/src/coverage.test.ts new file mode 100644 index 0000000..04f45b1 --- /dev/null +++ b/src/coverage.test.ts @@ -0,0 +1,167 @@ +import { readdirSync, readFileSync } from "node:fs"; +import { join } from "node:path"; +import { describe, expect, it } from "vitest"; + +/** + * Contract sweep, ported from freeticket-mcp's coverage.test.ts: every + * operation of the spec either has a command, or is excluded here with its + * reason. Without it, a new endpoint arrives through `sync-openapi` and stays + * command-less forever, because nothing fails. + * + * The match is by operationId against the command sources: the generated SDK + * exports one function per operationId, so if the name shows up outside the + * imports, a command uses it. Operations the CLI reaches without the SDK (signed downloads stop + * at the 302, see `signedDownload`) are in DIRECT with the path they build. + */ + +interface Operation { + id: string; + /** `GET /events/{id}`, for readable failures. */ + where: string; + path: string; +} + +function operations(file: string): Operation[] { + const spec = JSON.parse(readFileSync(file, "utf8")) as { + paths: Record>; + }; + return Object.entries(spec.paths).flatMap(([path, ops]) => + Object.entries(ops) + .filter(([, op]) => typeof op?.operationId === "string") + .map(([method, op]) => ({ + id: op.operationId as string, + where: `${method.toUpperCase()} ${path}`, + path, + })), + ); +} + +/** Concatenated source of the files that hold commands (no tests). */ +function commandSource(): string { + const dir = join("src", "commands"); + return [ + ...readdirSync(dir) + .filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts")) + .map((f) => join(dir, f)), + join("src", "program.ts"), + ] + .map((f) => readFileSync(f, "utf8")) + .join("\n"); +} + +/** + * Paths kept out of the CLI as a whole. The buyer API (`/customer/*`) runs on + * a buyer session minted by a device grant or an enterprise exchange; the CLI + * authenticates staff with workspace API keys and has no buyer login. + */ +const EXCLUDED_PREFIXES: Record = { + "/customer/": + "buyer API: needs a buyer session, the CLI only holds staff API keys", +}; + +/** Single operations kept out of the CLI, each with its reason. */ +const EXCLUDED: Record = { + postApiCustomerAuthEnterpriseExchange: + "mints buyer sessions from a one-time token: server-to-server between free-admin and the integrator", + // Headless merch store of an enterprise landing (contract 1.36): the buyer + // side. The catalog is a command (`ft merch catalog`). + postMerchOrders: + "places a buyer's order (ID document, phone, stock hold): landing page checkout", + postMerchOrdersLookup: + "a buyer looking up their own order by code + email: landing page flow", + postMerchOrdersCodePaymentCard: + "charges a Payment Brick card token: card data never passes through the CLI", +}; + +/** + * Operations the CLI reaches with a hand-built path instead of the SDK + * function, with a string that must appear in the source. `ft settlements + * document` stops at the 302 so the file is not pulled into memory. + */ +const DIRECT: Record = { + getSettlementsIdDocument: { + reason: "signedDownload: stops at the 302 and prints the signed URL", + needle: `\`/settlements/\${id}/document\``, + }, + getSettlementsIdProofsFileName: { + reason: "signedDownload: stops at the 302 and prints the signed URL", + needle: `\`/settlements/\${id}/proofs/\${encodeURIComponent(opts.proof)}\``, + }, +}; + +const excludedWhy = (o: Operation): string | undefined => + EXCLUDED[o.id] ?? + Object.entries(EXCLUDED_PREFIXES).find(([p]) => o.path.startsWith(p))?.[1]; + +/** + * One row per contract. `admin-openapi.json` (superadmin, `ft admin`) joins + * with its own row, minimum and exclusions in the admin PR; its commands live + * in the same sources, so `commandSource` does not change. + */ +const SPECS: [label: string, file: string, minOps: number][] = [ + ["B2B /api/v1", "openapi.json", 200], +]; + +/** + * The source without its import statements: an import alone is not a command, + * and the SDK import list outlives the call it was for (removing the call + * leaves the import, which biome flags but this test would not). + */ +const withoutImports = (text: string) => + text.replace(/^import\b[\s\S]*?from\s+"[^"]+";$/gm, ""); + +describe.each(SPECS)("contract %s", (_label, file, minOps) => { + const ops = operations(file); + const source = commandSource(); + const body = withoutImports(source); + + it("did not shrink abruptly (a truncated spec would pass every other check)", () => { + expect(ops.length).toBeGreaterThanOrEqual(minOps); + }); + + it("has a command for every operation, or excludes it with a reason", () => { + const uncovered = ops + .filter((o) => !excludedWhy(o) && !DIRECT[o.id]) + .filter((o) => !new RegExp(`\\b${o.id}\\b`).test(body)) + .map((o) => `${o.where} [${o.id}]`); + expect(uncovered).toEqual([]); + }); + + it("reaches every DIRECT operation through the path it names", () => { + const missing = ops + .filter((o) => DIRECT[o.id]) + .filter((o) => !source.includes(DIRECT[o.id]?.needle as string)) + .map((o) => `${o.where} [${o.id}]`); + expect(missing).toEqual([]); + }); + + it("calls no excluded operation", () => { + // The coverage rule accepts a bare mention (a comment counts); this looks + // for a call, or an aliased import that would hide the call. + const leaked = ops + .filter((o) => excludedWhy(o)) + .filter((o) => new RegExp(`\\b${o.id}(\\s*\\(|\\s+as\\b)`).test(source)) + .map((o) => `${o.where} [${o.id}] — ${excludedWhy(o)}`); + expect(leaked).toEqual([]); + }); +}); + +it("carries no exclusions for operations or paths the contracts no longer have", () => { + // An orphaned exclusion is a rule nobody has looked at again. + const all = SPECS.flatMap(([, file]) => operations(file)); + const ids = new Set(all.map((o) => o.id)); + expect( + [...Object.keys(EXCLUDED), ...Object.keys(DIRECT)].filter( + (id) => !ids.has(id), + ), + ).toEqual([]); + expect( + Object.keys(EXCLUDED_PREFIXES).filter( + (p) => !all.some((o) => o.path.startsWith(p)), + ), + ).toEqual([]); +}); + +it("does not both exclude an operation and reach it directly", () => { + expect(Object.keys(DIRECT).filter((id) => EXCLUDED[id])).toEqual([]); +}); diff --git a/src/destructive-confirm.test.ts b/src/destructive-confirm.test.ts index 67b5ab9..e3bd118 100644 --- a/src/destructive-confirm.test.ts +++ b/src/destructive-confirm.test.ts @@ -1,4 +1,5 @@ import { readFileSync } from "node:fs"; +import type { Command } from "commander"; import { afterEach, beforeEach, @@ -13,6 +14,11 @@ import { * End-to-end through commander: a destructive command run without a TTY and * without --yes must exit 1 BEFORE the SDK call. The generated SDK functions * are mocked so nothing could reach the network even if the gate regressed. + * + * Each CASES row is checked both ways: refused without --yes, and with --yes + * its SDK function is called exactly once. Without the second half a row + * could point at a function its command never calls (or at another command's + * function) and the "never calls" assertion would pass vacuously. */ const sdk = vi.hoisted(() => ({ postEventsIdCancel: vi.fn(), @@ -46,6 +52,12 @@ const sdk = vi.hoisted(() => ({ postStaffIdResendInvite: vi.fn(), postContentMeetupsIdPublish: vi.fn(), patchContentMeetupsIdRsvpsRsvpId: vi.fn(), + postEventsIdArtistInvitationsInvitationIdResend: vi.fn(), + putEventsIdArtists: vi.fn(), + putContentVideosIdPublished: vi.fn(), + putWebsite: vi.fn(), + // Read by `events artists set` before it asks (who would drop out). + getEventsId: vi.fn(), deleteWorkspacesId: vi.fn(), })); @@ -63,6 +75,12 @@ vi.mock("./admin-client/sdk.gen", async (importOriginal) => ({ const { program } = await import("./program"); +/** A 200 the commands can print (lineup `set` reads `data.artists`). */ +const ok = () => ({ + data: { data: { artists: [] } }, + response: new Response(), +}); + describe("destructive commands refuse without a TTY and without --yes", () => { const tty = process.stdin.isTTY; let exit: MockInstance; @@ -74,9 +92,23 @@ describe("destructive commands refuse without a TTY and without --yes", () => { configurable: true, }); stderr = vi.spyOn(console, "error").mockImplementation(() => {}); + vi.spyOn(console, "log").mockImplementation(() => {}); + vi.spyOn(process.stdout, "write").mockImplementation(() => true); exit = vi.spyOn(process, "exit").mockImplementation((() => { throw new Error("exited"); }) as never); + // Credentials, so the only thing that can stop a command is the gate (the + // SDK is mocked: they never reach a network). Commands that configure the + // client before asking (`events artists set`) need them for the refusal. + vi.stubEnv("FT_API_KEY", "ft_test_key"); + vi.stubEnv("FT_ADMIN_SESSION", "test-session"); + for (const fn of Object.values(sdk)) fn.mockResolvedValue(ok()); + // The lineup already has org_1, so `set --artist org_1 --invite …` removes + // nobody: what it asks about is the invitation email alone. + sdk.getEventsId.mockResolvedValue({ + data: { data: { artists: [{ id: "org_1", name: "Artist One" }] } }, + response: new Response(), + }); }); afterEach(() => { @@ -85,6 +117,7 @@ describe("destructive commands refuse without a TTY and without --yes", () => { configurable: true, }); vi.restoreAllMocks(); + vi.unstubAllEnvs(); for (const fn of Object.values(sdk)) fn.mockReset(); }); @@ -98,6 +131,14 @@ describe("destructive commands refuse without a TTY and without --yes", () => { expect(fn).not.toHaveBeenCalled(); }); + it.each( + CASES, + )("ft %j --yes calls its SDK function exactly once", async (args, fn) => { + await program.parseAsync(["node", "ft", ...(args as string[]), "--yes"]); + expect(exit).not.toHaveBeenCalled(); + expect(fn).toHaveBeenCalledTimes(1); + }); + it("covers every operation the contract marks x-ft-destructive", () => { const spec = JSON.parse(readFileSync("openapi.json", "utf8")); const destructive = Object.values(spec.paths).flatMap((ops) => @@ -203,4 +244,147 @@ const CASES: [string[], (typeof sdk)[keyof typeof sdk]][] = [ ["content-meetups", "rsvp", "mt_1", "rsvp_1", "--approve"], sdk.patchContentMeetupsIdRsvpsRsvpId, ], + [ + ["events", "invitations", "resend", "evt_1", "inv_1"], + sdk.postEventsIdArtistInvitationsInvitationIdResend, + ], + [ + [ + "events", + "artists", + "set", + "evt_1", + "--artist", + "org_1", + "--invite", + "a@b.co", + ], + sdk.putEventsIdArtists, + ], + [["content-videos", "publish", "vid_1"], sdk.putContentVideosIdPublished], + // Not an email, but a FULL replace: a partial --data wipes the rest. + [["website", "set", "--data", '{"sections":[]}'], sdk.putWebsite], ]; + +/** Every leaf of the command tree, as `"events artists set"`. */ +function leaves(cmd: Command, path: string[] = []): [string, Command][] { + if (cmd.commands.length === 0) return [[path.join(" "), cmd]]; + return cmd.commands.flatMap((sub) => leaves(sub, [...path, sub.name()])); +} +/** The command path that argv resolves to (subcommand names, no args). */ +function commandPath(args: string[]): string { + const path: string[] = []; + let cmd: Command = program; + for (const arg of args) { + const sub = cmd.commands.find( + (c) => c.name() === arg || c.aliases().includes(arg), + ); + if (!sub) break; + path.push(sub.name()); + cmd = sub; + } + return path.join(" "); +} +const hasYes = (cmd: Command) => cmd.options.some((o) => o.long === "--yes"); + +/** + * Writes that notify someone and still run without asking, on purpose. If one + * of them gains a gate, or disappears, the sweep below fails and this list is + * revisited instead of rotting. + */ +const UNGATED_ON_PURPOSE: Record = { + "content-moderation approve": + "approving IS the reviewer's decision, and --expected-updated-at already pins the exact version read; the author's notification is the point", + "tickets resend": + "one email to the ticket's own buyer, the same QR again: the command exists to send it", + "content-posts create": + "the --data body is the message itself; with community_v2 members are notified like in the dashboard (no draft step to confirm separately)", + "products update": + "only new lessons on a published course notify its buyers, like the dashboard; the body is a full tree read just before", +}; + +describe("confirmation gates across the whole command tree", () => { + it("exactly these commands accept --yes", () => { + // A new destructive or notifying command that forgets its gate, or a gate + // dropped by a refactor, changes this list: update it on purpose. + expect( + leaves(program) + .filter(([, cmd]) => hasYes(cmd)) + .map(([path]) => path) + .sort(), + ).toEqual([ + "admin feature-flags set", + "admin impersonate", + "admin tokens revoke", + "admin workspaces delete", + "admin workspaces plan", + "admin workspaces plan-show", + "admin workspaces restore", + "admin workspaces suspend", + "api-keys revoke", + "content-channels archive", + "content-comments delete", + "content-lives delete", + "content-lives reset-key", + "content-meetups cancel", + "content-meetups publish", + "content-meetups rsvp", + "content-members ban", + "content-moderation reject", + "content-moderation remove", + "content-posts delete", + "content-series delete", + "content-videos delete", + "content-videos publish", + "discounts delete", + "event-dates access-close sign", + "event-dates delete", + "events artists remove", + "events artists set", + "events cancel", + "events delete", + "events invitations cancel", + "events invitations resend", + "events validators add", + "events viewers add", + "events viewers remove", + "master-qrs delete", + "plans delete", + "presale-windows delete", + "products delete", + "sales abandon", + "sales recipient set", + "sales transfer", + "staff access", + "staff delete", + "staff resend-invite", + "ticket-templates delete", + "ticket-types delete", + "tickets checkin-undo", + "venues delete", + "webhooks delete", + "website set", + ]); + }); + + it("every CASES row is a gated command of the tree", () => { + const gated = new Set( + leaves(program) + .filter(([, cmd]) => hasYes(cmd)) + .map(([path]) => path), + ); + const rows = CASES.map(([args]) => commandPath(args)); + expect(rows.filter((r) => !gated.has(r))).toEqual([]); + }); + + it.each( + Object.entries(UNGATED_ON_PURPOSE), + )("%s still exists and still runs without a gate", (path) => { + const leaf = leaves(program).find(([p]) => p === path); + expect( + leaf, + `${path} is gone: drop it from UNGATED_ON_PURPOSE`, + ).toBeDefined(); + expect(hasYes(leaf?.[1] as Command)).toBe(false); + }); +}); diff --git a/src/lib/input.ts b/src/lib/input.ts index d24d607..ea3b40f 100644 --- a/src/lib/input.ts +++ b/src/lib/input.ts @@ -9,7 +9,8 @@ import { fail } from "./api"; */ export function parseLimit(input: string): number { const n = Number(input); - if (!Number.isInteger(n) || n < 1 || n > 100) + // The regex too: Number() also takes "5.0", "1e1" and " 20". + if (!/^\d+$/.test(input) || n < 1 || n > 100) fail( `Invalid --limit: ${input}. Use an integer from 1 to 100.`, "For more rows, add --all to walk every page.", @@ -17,6 +18,55 @@ export function parseLimit(input: string): number { return n; } +/** + * Commander option parsers for typed flags. They run while commander parses + * argv, so a bad value exits 1 before any confirmation prompt or request. + * + * `Number()` was not enough: `Number("50.000") === 50` turned a COP price + * typed with a thousands separator into fifty pesos, and `Number("abc")` is + * NaN, which `JSON.stringify` sends as `null` (a capacity cleared by a typo). + * Booleans were `v === "true"`, so `--active yes` silently meant false. + */ +export function wholeNumber(flag: string): (input: string) => number { + return (input) => { + if (!/^\d+$/.test(input)) + fail( + `Invalid ${flag}: ${input}. Use a whole number with no separators or decimals (e.g. 50000).`, + ); + return Number(input); + }; +} + +/** + * `wholeNumber`, or `"none"` to clear a nullable field. Returns `"none"`, not + * null: commander turns a parser's null into "" (map it with `noneToNull`). + */ +export function wholeNumberOrNone( + flag: string, +): (input: string) => number | "none" { + return (input) => { + if (input === "none") return "none"; + if (!/^\d+$/.test(input)) + fail( + `Invalid ${flag}: ${input}. Use a whole number with no separators or decimals (e.g. 50000), or "none".`, + ); + return Number(input); + }; +} + +/** The body value of a `wholeNumberOrNone` flag. */ +export const noneToNull = (v: T | "none"): T | null => + v === "none" ? null : v; + +/** `"true"` / `"false"` only; anything else (yes, 1, si) exits 1. */ +export function booleanFlag(flag: string): (input: string) => boolean { + return (input) => { + if (input !== "true" && input !== "false") + fail(`Invalid ${flag}: ${input}. Use true or false.`); + return input === "true"; + }; +} + /** * Parses a `--data` value into a JSON body. Accepts inline JSON (`'{"x":1}'`) * or `@path/to/file.json` to read from disk. Aborts on missing/invalid input. diff --git a/src/program.ts b/src/program.ts index 43a3b65..dd523af 100644 --- a/src/program.ts +++ b/src/program.ts @@ -54,7 +54,6 @@ import { patchDiscountsId, patchEventsId, patchEventsIdDatesDateId, - patchMasterQrsId, patchMembershipPlansId, patchProductsId, patchStaffIdRole, @@ -75,7 +74,6 @@ import { postEventsIdCancel, postEventsIdDates, postEventsIdPublish, - postMasterQrs, postMembershipPlans, postProducts, postSales, @@ -138,7 +136,7 @@ import { unwrap, } from "./lib/api"; import { banner } from "./lib/banner"; -import { parseData } from "./lib/input"; +import { booleanFlag, parseData } from "./lib/input"; import { print } from "./lib/output"; /** @@ -377,6 +375,7 @@ registerResource(program, { flag: "--active ", describe: "filter by active (true/false)", query: "active", + parse: booleanFlag("--active"), }, ], }); @@ -562,12 +561,11 @@ registerResource(program, { }); // Master box-office QRs (contract 1.33): one printed QR opens the sale flow of -// an event (or of today's shows). `code`/`url` are secret and never rotate. +// an event (or of today's shows). `code`/`url` are secret and never rotate, so +// list/create/update live in extendMasterQrs, which redacts them. registerResource(program, { name: "master-qrs", describe: "Master box-office QR codes", - create: postMasterQrs, - update: patchMasterQrsId, del: deleteMasterQrsId, extend: extendMasterQrs, }); diff --git a/src/test/setup.test.ts b/src/test/setup.test.ts new file mode 100644 index 0000000..8634786 --- /dev/null +++ b/src/test/setup.test.ts @@ -0,0 +1,17 @@ +import { homedir, tmpdir } from "node:os"; +import { describe, expect, it } from "vitest"; + +/** The global guard of src/test/setup.ts is actually wired (vitest.config.ts). */ +describe("test setup guard", () => { + it("fetch throws instead of reaching the network", async () => { + await expect( + fetch("https://admin.appfreeticket.com/api/v1/me"), + ).rejects.toThrow(/Unexpected network call in a test/); + }); + + it("HOME is a temp dir and FT_API_URL a closed local port", () => { + expect(homedir().startsWith(tmpdir())).toBe(true); + expect(process.env.FT_API_URL).toBe("http://127.0.0.1:9"); + expect(process.env.FT_API_KEY).toBeUndefined(); + }); +}); diff --git a/src/test/setup.ts b/src/test/setup.ts new file mode 100644 index 0000000..5e2efb5 --- /dev/null +++ b/src/test/setup.ts @@ -0,0 +1,32 @@ +import { mkdtempSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +/** + * Global guard for every test file (vitest `setupFiles`, runs before the file + * imports anything): + * + * - `HOME` points at a fresh temp dir, so `~/.freeticket/config.json` (and the + * update-check cache) are never the developer's real accounts. config.ts + * reads `homedir()` at import time, which is why this has to run first. + * - `FT_API_URL` is a closed local port, and the FT_* credentials of the shell + * are dropped: a test that forgets to mock still cannot authenticate against + * a real backend. + * - `fetch` throws. A test that needs the network stubs it (`vi.stubGlobal`, + * or a `fetch` in the client config); restoring the stub comes back here, + * not to the real fetch. + */ +const home = mkdtempSync(join(tmpdir(), "ft-cli-test-")); +process.env.HOME = home; +process.env.USERPROFILE = home; +process.env.FT_API_URL = "http://127.0.0.1:9"; +for (const name of ["FT_API_KEY", "FT_WORKSPACE_ID", "FT_ADMIN_SESSION"]) + delete process.env[name]; +process.env.FT_NO_UPDATE_CHECK = "1"; + +globalThis.fetch = (async (input: unknown) => { + const url = input instanceof Request ? input.url : String(input); + throw new Error( + `Unexpected network call in a test: ${url}. Stub fetch (vi.stubGlobal) or mock the SDK.`, + ); +}) as typeof fetch; diff --git a/vitest.config.ts b/vitest.config.ts new file mode 100644 index 0000000..3f5eec5 --- /dev/null +++ b/vitest.config.ts @@ -0,0 +1,8 @@ +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + test: { + // Network and filesystem guard for every test file (see the file). + setupFiles: ["src/test/setup.ts"], + }, +});