@go-labs-sg/rsvp 1.0.0 → 1.1.0

package/README.md

@@ -85,6 +85,48 @@ The installed command uses the same portable Bun launcher as the other Go Labs C
 
 Global administrators can update another account's global role from the web user manager or with `rsvp user role update --allow-state-change --target <user-id> --payload '{"userId":"<user-id>","role":"admin"}'`. Administrators cannot remove their own global admin role.
 
+## Personal seating drafts
+
+`event seating draft get`, `save`, `preview`, and `publish` use the same server-owned
+personal draft as Assign Guests. Resume it on another authenticated device; drafts
+are isolated by event and signed-in owner. Do not pass an owner ID. Stored changes
+contain only `registrationAttendeeId`, `fromSeatId` (the first live source, nullable)
+and `toSeatId` (nullable to unseat). Stage does not book seats, acquire holds or send
+email. Preview reports fresh conflicts and grant-scoped guest details.
+
+Guest reads are live by default. Add `--include-draft` (or JSON `includeDraft: true`)
+to `event seating guests list` or `count` to apply only your saved draft before
+seating filters, facets and pagination. `--include-draft=false` keeps live results.
+Draft-mode cursors bind the saved version; restart pagination after a draft save.
+The Assign guests page always reads this personal-draft view.
+
+```sh
+rsvp event seating draft get --organization-id org_123 --event-id evt_123 --ack-sensitive-data
+rsvp event seating draft save --allow-state-change --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","expectedVersion":0,"changes":[{"registrationAttendeeId":"att_123","fromSeatId":null,"toSeatId":"seat_123"}]}'
+rsvp event seating draft preview --organization-id org_123 --event-id evt_123 \
+  --expected-version 1 --ack-sensitive-data
+rsvp event seating draft publish --organization-id org_123 --event-id evt_123 \
+  --expected-version 1 --request-id 123e4567-e89b-42d3-a456-426614174000 \
+  --reason 'Seat the confirmed guest' --allow-state-change --target evt_123
+```
+
+Save and Publish require the latest `expectedVersion`. A successful Publish applies
+all changed guests atomically and clears only that version of your draft. Resolve
+preview issues before publishing; conflicts leave all bookings and the draft intact.
+For an unknown outcome, retry the same UUID `requestId`, version, reason and email
+choice: the durable receipt returns the previous counts without sending again or
+clearing a newer draft. A different intent needs a new request ID. Email defaults
+off. To opt in, use `--allow-email` and a full JSON payload including organizationId,
+eventId, expectedVersion, requestId, reason and `sendSeatChangeEmail: true`. Do not
+combine `--payload` with command-local version/reason/request flags;
+the server additionally requires notice permission and enabled recipient policy.
+Preview counts recipient registrations, not guests. On realtime-enabled servers,
+free new targets require validated per-registration holds at Publish, supplied as
+`seatHolds: [{registrationId, holds: [{seatMapId, clientId, holdToken}]}]` in the
+payload. Acquire these through the existing organizer hold-token flow; Stage never
+holds seats. Swaps and cycles of changed live sources do not require free-seat holds.
+
 ## Command safety
 
 Argument-parsing errors use a safe command label and never echo option values,
@@ -125,6 +167,37 @@ key to clear the image. The public event guide reuses both assets. Campaign
 HTML can link to the guide with `{{eventDetailsUrl}}`; `{{eventUrl}}` still
 points to the registration page.
 
+The optional event footer is one image shown at the bottom of the registration
+and confirmation pages; events without one show no footer. Use
+`event footer upload create` for the upload URL and key, upload the image
+(PNG, JPG, WebP, or GIF up to 10 MB; SVG is not accepted), then save it with
+`event footer update`. `variant` defaults to `DESKTOP`; send `MOBILE` to set a
+separate image for screens under 640px. When only one variant is set it is used
+on every screen size. A null `footerImageKey` clears that variant.
+
+```sh
+rsvp event footer update \
+  --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","footerImageKey":"rsvp/events/evt_123/footers/<uuid>.png","variant":"MOBILE","version":7}'
+```
+
+Instead of one image, the footer can show separate logos scrolling across the
+page. Upload each logo with `event footer upload create`, then save the mode
+and the ordered list with `event footer logos update`. Each logo needs a
+`name` (also its alt text); `heading` (for example "Supported by"), a smaller
+`label` (for example "Principal partners") and an `https://` `url` are optional.
+Adjacent logos with the same heading appear together under it. Up to 30 logos.
+`footerMode` `IMAGE` switches back to the single image; both modes keep their
+uploads.
+
+```sh
+rsvp event footer logos update \
+  --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","footerMode":"LOGOS","logos":[{"imageKey":"rsvp/events/evt_123/footers/<uuid>.png","name":"FARM","heading":"Produced by","url":"https://www.farm.sg"}],"version":8}'
+```
+
 For a read-only registration-journey diagnosis, inspect the event, draft,
 published versions, and event-owned resources together:
 
@@ -402,6 +475,23 @@ metadata. It does not choose eligible people, apply category/exclusion rules,
 import a draw roster, or reconcile prizes/vouchers. Deploy the updated API before
 saving the new setup section; no database schema migration is required.
 
+### Registration card copy
+
+`section: "PUBLIC_PAGE"` replaces the event's saved landing-page card copy.
+Omit a text key to use the default wording; set a `show…` flag to `false` to
+hide that notice. Read the event first and use its current version:
+
+```sh
+rsvp event setup step update \
+  --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","version":7,"section":"PUBLIC_PAGE","publicPage":{"registrationTitle":"NELBD Quest Registration","deadlineLabel":"Register by","responseUpdateNotice":"You may return to update your registration details before the timing stated above.","accessNotice":"Continue to complete the registration for both team members.","registrationActionLabel":"Register now"}}'
+```
+
+Limits: title 120, description 500, deadline label 60, response-update notice
+300, access notice 500 and button label 100 characters. It requires
+`event.manage`; no database migration is required.
+
 ## Per-form confirmation presentation
 
 In the form builder's **Flow settings → Confirmation and check-in pass**, set
@@ -445,21 +535,37 @@ No database schema migration or attendee backfill is required.
 
 ## Administrator registration for an invitee
 
-Inspect the invitee's active registration form and current registration version
-before submitting. The context includes the published flow definition, invitee,
-and existing registration (if any):
+Organizers can register someone on their behalf at any time, including after
+registration has closed. This is the same action as the **Register invitee**
+page under People. Look the person up first. Pass `inviteeId` for someone on
+the invitee list, or `person` with their details. The response includes the
+published flow definition, the invitee, `isExistingInvitee`, any existing
+registration, `archivedRegistrationId`, `canAddInvitee` and
+`canOverrideCapacity`:
 
 ```sh
 rsvp event flow admin registration context get \
   --ack-sensitive-data \
   --payload '{"organizationId":"org_123","eventId":"evt_123","inviteeId":"invitee_123"}'
+
+rsvp event flow admin registration context get \
+  --ack-sensitive-data \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","person":{"email":"ava@example.com","employeeId":"E1042","audienceTierId":null}}'
 ```
 
+A `person` lookup matches an invitee with the same email (on the invitee or
+their account) or the same employee ID. If the email and employee ID belong to
+two different invitees, the lookup is refused. When nothing matches,
+`isExistingInvitee` is `false`, and the context previews the form and seats
+that a new invitee in the given audience tier would get. If
+`archivedRegistrationId` is set, restore that registration instead (`people
+registration restore`), which keeps the existing QR code.
+
 Use the returned `flowVersionId` and `expectedRegistrationVersion` in the
-submission. Set `expectedOutcomeId` to the outcome selected by the answers in
-the published definition, and provide answers keyed by each field's `outputKey`.
-A new UUID `idempotencyKey` identifies this submission. The audit reason records
-why an administrator submitted on the invitee's behalf.
+submission. Set `expectedOutcomeId` to the outcome selected by the answers, and
+key the answers by each field's `outputKey`. A new UUID `idempotencyKey`
+identifies the submission. The audit reason records why an organizer submitted
+on the person's behalf. Give exactly one of `inviteeId` or `newInvitee`:
 
 ```sh
 rsvp event flow admin registration submit \
@@ -467,14 +573,42 @@ rsvp event flow admin registration submit \
   --allow-state-change \
   --target invitee_123 \
   --payload '{"organizationId":"org_123","eventId":"evt_123","inviteeId":"invitee_123","flowVersionId":"flow_version_123","answers":{"attendance":"ATTENDING"},"expectedOutcomeId":"attending","expectedRegistrationVersion":0,"idempotencyKey":"9dd0ba39-b55e-4e65-aa3e-d08242c45b8f","auditReason":"Recorded response by phone"}'
+
+rsvp event flow admin registration submit \
+  --ack-sensitive-data \
+  --allow-state-change \
+  --target ava@example.com \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","newInvitee":{"displayName":"Ava Tan","email":"ava@example.com","employeeId":"E1042","audienceTierId":null},"flowVersionId":"flow_version_123","answers":{"attendance":"ATTENDING"},"expectedOutcomeId":"attending","expectedRegistrationVersion":0,"idempotencyKey":"3f0c5a4e-2a43-4d8b-9a59-6d0e8f5b8a11","auditReason":"Late addition approved by the client","sendConfirmation":true}'
 ```
 
+With `newInvitee`, the target is the email. Matching uses the same identity
+rules as roster import and admission: email case and Gmail dot/`+alias`
+spellings are ignored, and so is employee ID case. If an invitee already matches
+the details, that invitee is registered. Otherwise a new invitee is added to the
+list and registered in the same transaction. Adding someone new needs the
+`roster.manage` permission. Invitees who declined can be registered; anyone
+with an active registration is changed through `people registration update`
+instead, and archived registrations go through restore.
+
+Optional fields:
+
+- `sendConfirmation` (default `true`): set it to `false` to skip the
+  participant confirmation email with the QR code.
+  The result's `confirmationQueued` says whether the email was actually queued:
+  it is `false` when the form's email settings send no confirmation for this
+  registration, even if `sendConfirmation` is `true`.
+- `overCapacityReason` (10–500 characters): registers the person even when the
+  event is full. This needs the `capacity.override` permission (event and
+  organization admins). The reason is recorded in the activity log. Without it,
+  a full event returns a conflict with `eventAtCapacity: true` in the error
+  data. Menu (dish) capacity is still enforced.
+- `consentOverrideReason`: required when the flow has a consent step. It
+  records the organizer's reason in the audit trail; it does not record
+  attendee consent or a signature.
+
 Replace the example answer key and value with those required by the returned
-definition. If the flow requires a consent override, include a nonempty
-`consentOverrideReason` in the submission payload. The override records the
-administrator's reason in the audit trail; it does not record attendee consent
-or a signature. A stale registration version or flow version is rejected; fetch
-the context again before retrying with a new idempotency key.
+definition. A stale registration version or flow version is rejected; fetch the
+context again before retrying with a new idempotency key.
 
 Create an immutable menu version with an explicit mutation acknowledgement. The
 target is the event ID in the payload:
@@ -584,15 +718,38 @@ Deploy the matching API and worker before using these commands from an updated
 CLI. They retain browser authentication, event permissions and sensitive-field
 grants; the CLI does not implement separate seating rules.
 
+`event seating swap` refuses invalid swaps using first/second selected-attendee
+labels, never attendee names. This applies even when the caller can view identity
+fields: reseating permission alone is not identity access. Notice failures retain
+their API error code but do not forward attendee names or nested private details;
+the entire swap rolls back if its requested notices cannot be queued. A notice
+precondition refusal can be retried without the optional notice. Input/output
+schemas, acknowledgement gates and seating/payment rules are unchanged.
+
 ```sh
 rsvp event seating live get --ack-sensitive-data \
   --payload '{"organizationId":"org_123","eventId":"evt_123"}'
+rsvp event seating guests list --ack-sensitive-data \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","seatMapId":"map_123","seating":"UNSEATED","sort":"GROUP","limit":25}'
+rsvp event seating guests count --ack-sensitive-data \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","seatMapId":"map_123","seating":"UNSEATED"}'
 rsvp event seating occupants list --ack-sensitive-data \
   --payload '{"organizationId":"org_123","eventId":"evt_123","seatMapId":"map_123","categoryValue":"finance","limit":25,"cursor":0}'
 rsvp people registration edit get --ack-sensitive-data \
   --payload '{"organizationId":"org_123","eventId":"evt_123","registrationId":"reg_123"}'
 ```
 
+`event seating category colors get` returns only the configured category
+colour of each booked seat (for example job function) and the legend for one
+seat map, which is what the live map paints without opening the occupant
+workspace. It needs `seating.view` and registration view access, and respects
+sensitive-field access to the configured field:
+
+```sh
+rsvp event seating category colors get --ack-sensitive-data \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","seatMapId":"map_123"}'
+```
+
 Occupants supports optional `tableId`, `department`, `categoryValue` and `query`
 filters. `categoryValue` is the canonical (trimmed, case-normalized) value
 returned by the occupant response's category legend; it is not an arbitrary
@@ -648,12 +805,88 @@ notice is queued in the move's database transaction, so the move and notice
 request commit together or not at all; this additionally requires
 `--allow-email`. It is rejected alongside identity, contact or response edits.
 
+To swap two seated people, use `event seating swap`. Give each attendee's
+`registrationAttendeeId` with the `seatId` they hold now, plus a `reason`. Both
+seats change in one transaction, so neither is free for anyone else in between.
+If either person has moved since you looked, the swap is refused; list the
+occupants again and retry. Each person must be attending or submitted with no
+payment pending, and each seat must be allowed for the other person's audience
+tier, form and published seat map. `--target` is either attendee ID:
+
+```sh
+rsvp event seating swap \
+  --ack-sensitive-data \
+  --allow-state-change \
+  --target attendee_a \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","attendees":[{"registrationAttendeeId":"attendee_a","seatId":"seat_1"},{"registrationAttendeeId":"attendee_b","seatId":"seat_2"}],"reason":"Client asked to seat them with their team"}'
+```
+
+Add `"seatChangeNotice":{"idempotencyKey":"<uuid>"}` and `--allow-email` to
+queue a seat-change notice for each registration involved. Use
+`event seating occupants list` to find attendee and seat IDs. Swaps need the
+`seating.reseat` permission; notices also need `confirmation.resend`.
+
 ```sh
 rsvp people registration update \
   --ack-sensitive-data --allow-state-change --allow-email --target reg_123 \
   --payload '{"organizationId":"org_123","eventId":"evt_123","registrationId":"reg_123","expectedVersion":4,"reason":"Moved to finance table","seats":[{"registrationAttendeeId":"att_1","seatId":"seat_9"},{"registrationAttendeeId":"att_2","seatId":"seat_2"}],"seatChangeNotice":{"idempotencyKey":"4d68a320-013d-43c7-bfcc-d1126827d8c5"}}'
 ```
 
+### Unarchive for a fresh response versus attending Restore
+
+`people registration unarchive` forwards the permissioned, audited
+`event.bulkManageRegistrations` RESTORE operation. Supply 1–100 unique
+`registrations`, each with its current `expectedVersion` (positive integer), and
+an audit `reason` (3–500 characters after trimming). `action` defaults to
+`RESTORE` when omitted; any other action is rejected. The approval target is
+exactly the payload's **event ID**, not an individual registration ID.
+
+```sh
+rsvp people registration unarchive \
+  --allow-state-change --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","reason":"Allow a fresh response","registrations":[{"id":"reg_123","expectedVersion":6}]}'
+```
+
+Unarchive clears the archive marker and lets an eligible cancelled nonattending
+invitee return to `IMPORTED` for a fresh response. The server checks current
+permissions, revisions, eligibility and settled financial state; the CLI does
+not interpret cancelled history or make eligibility decisions. Historical
+registration/payment records remain history, and the old cancelled
+registration and QR code are **not reinstated**. Seats, capacity, session
+selections and waitlist entries are not recovered. A fresh submission uses the
+normal flow and current checks, with new payment and credentials where required.
+Unarchive cannot shortcut attending recovery. The result's
+`readmittedInviteeCount` reports invitees reopened for a fresh response;
+`changedCount` and `releasedAttendeeCount` retain their existing meanings.
+
+`people registration restore` instead reinstates a cancelled or archived
+**attending registration**, with its existing identity/payment/QR subject to the
+server's restoration checks. It is not Unarchive and does not start a fresh response.
+Read it first with `people registration edit get` and `"mode":"RESTORE"` to see
+eligible seats and each attendee's previous seat. Supply `expectedVersion`, an
+audit `reason`, and a seat for every attendee who had one; the server claims
+capacity, books the seats and rejects full events, re-registered invitees and
+unresolved or refunded payments. A full event is rejected unless
+`overCapacityReason` (10–500 characters) is given, which needs the
+`capacity.override` permission (event and org admins); the override and reason
+are recorded in the activity log. Menu (dish) capacity is still enforced and
+cannot be overridden. While an event is over capacity, declines and smaller
+parties, payments confirmed while their hold is still live, and unexpired
+waitlist offers (up to the offered party size) still go through. A payment
+confirmed after its hold lapsed gets the normal capacity check and goes to
+review if the place was reused. The current limit can be saved unchanged; any
+new limit must be at least the confirmed count. The existing QR code works
+again. Add
+`confirmation` (with `--allow-email`) to queue the participant confirmation.
+Session selections cancelled by archiving are not restored; the response
+reports `droppedSessionSelections`.
+
+```sh
+rsvp people registration restore \
+  --ack-sensitive-data --allow-state-change --allow-email --target reg_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","registrationId":"reg_123","expectedVersion":6,"reason":"Archived by mistake","seats":[{"registrationAttendeeId":"att_1","seatId":"seat_9"}],"confirmation":{"idempotencyKey":"4d68a320-013d-43c7-bfcc-d1126827d8c5"}}'
+```
+
 A separate manual notice for an already committed revision remains available:
 
 ```sh
@@ -766,3 +999,27 @@ email, external-write, and state-change effect approvals. It creates a workspace
 awaiting owner acceptance and sends a 48-hour first-owner invitation. The internal
 provisioner does not receive customer organization membership. The response
 reports invitation delivery failure so the invitation can be resent safely.
+
+### Assign guests rail reads
+
+`event seating guests list` includes unarchived, confirmed attendees (legacy
+`ATTENDING` and current `SUBMITTED`), including guests with no active seat. An
+active booking on any layout counts as seated. Groups are registration parties.
+Both reads require `seating.view` and `rsvp.view`; names/search/name sorting and
+dietary filters/labels additionally require their sensitive-data grants.
+
+Shared filters: `seating` (`UNSEATED`, `SEATED`, `ALL`), `query` (max 120),
+`audienceTierId`, `registrationId`, `dietaryTag`, `guestKind` (`ALL`, `HOST`,
+`GUEST`). List adds `limit` (1–100; default 25), `sort` (`GROUP`, `NAME`), opaque
+`cursor`, and `direction` (`forward`, `backward`). Backward requires a cursor.
+The response is `{items,pageInfo}`; use its `nextCursor`/`previousCursor`, not a
+row ID. Cursors are bound to filters, ordering, scope and sensitive grants; a
+changed context requires restarting the list. Deleted cursor anchor rows do not
+break paging. Offset `page`/`perPage` and unknown keys are rejected.
+
+`event seating guests count` rejects paging/sort keys. It returns the matching
+count, seating-tab counts (ignore their own seating filter), tier counts (ignore
+their own tier filter), dietary choices (ignore their own dietary filter), and
+permission flags. Facets expose at most 100 choices with truncation flags; tier
+counts stream compact registration aggregates in bounded reads, without a hard
+registration-count ceiling. Rail page rows are never loaded event-wide.