@go-labs-sg/rsvp 0.15.0 → 0.17.0

package/README.md

@@ -135,6 +135,87 @@ rsvp event flow versions list --organization-id org_123 --event-id evt_123
 rsvp event flow resources get --organization-id org_123 --event-id evt_123
 ```
 
+### Registration-flow image upload lifecycle
+
+Registration-flow images are **named, event-local assets**. Create one with an
+optional `altText`, upload the bytes to the returned presigned URL, and then
+finalize that same asset. Creation and finalization store the asset; neither
+changes the draft or publishes a registration flow.
+
+The API validator accepts `image/jpeg`, `image/png`, and `image/webp`. `byteSize`
+must be a positive integer no larger than **10 MiB (10,485,760 bytes)**. The
+server rechecks the uploaded object's content type and exact declared size when
+finalizing. Use `event flow resources get` to verify the finalized asset ID in
+that event's catalog; never reuse an actual event's asset ID in a test event.
+
+```sh
+created="$(rsvp event flow image upload create \
+  --allow-external-write \
+  --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","mimeType":"image/png","byteSize":2048,"altText":"Beef entrée"}')"
+
+# Read data.asset.id and data.uploadUrl from the JSON response, then PUT the exact
+# bytes to uploadUrl using the same MIME type and declared byteSize.
+curl --fail --upload-file ./beef-entrée.png \
+  -H 'Content-Type: image/png' \
+  "<uploadUrl from the create response>"
+
+rsvp event flow image finalize \
+  --allow-state-change \
+  --target '<asset.id from the create response>' \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","assetId":"<asset.id from the create response>"}'
+```
+
+The CLI does not perform the external `PUT`, retry uploads automatically, or
+bypass authentication, event permissions, storage validation, or the existing
+server contract. If the upload or finalization fails, inspect the error and
+perform an explicit operator action; do not invent a new storage or retry
+protocol. Reference the finalized asset from the appropriate form choice, then
+save and publish the flow separately when the complete draft is approved.
+
+
+## Per-form confirmation presentation
+
+In the form builder's **Flow settings → Confirmation and check-in pass**, set
+lucky-draw visibility, primary/additional participant labels, and organiser
+support-contact visibility. Save and publish the exact form to apply changes.
+Draft edits do not affect live passes.
+
+The same settings are supported in `definition.confirmation` through
+`event flow draft save`:
+
+```json
+{
+  "confirmation": {
+    "showLuckyDrawId": false,
+    "showSupportContact": false,
+    "primaryAttendeeLabel": "Participant 1",
+    "additionalAttendeeLabel": "Participant 2"
+  }
+}
+```
+
+Merge these fields into the complete current definition; this is not a complete
+save payload. Include `organizationId`, `eventId`, the exact `flowId`, and the
+latest `expectedRevision`, then publish with `expectedDraftRevision`. Use the
+event ID as `--target` and pass `--allow-state-change` for both mutations.
+
+Omitted visibility settings retain legacy behavior (shown). Omitted labels use
+the stored attendee-type label; `null` hides a label. Custom labels must be
+nonempty after trimming and at most 120 characters. Completion `contactEmail`
+is optional; hiding support contact does not remove an email written into the
+completion message or hide the participant's confirmation-recipient address.
+
+Published display settings and completion message/contact updates apply to
+existing registrations of the same form. Their saved questions, answer scope,
+registration outcomes, attendee roles, lucky-draw records, QR credentials, and
+check-in references remain unchanged. `event flow published get` accepts
+`confirmation: true` in its payload for this saved-response presentation; omit
+it for the active registration/edit definition. Deploy the updated server before
+saving these settings because older validators discard unsupported fields.
+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
@@ -221,6 +302,51 @@ rsvp check-in by-reference \
 
 High-impact payment and retention commands remain protected by their matching financial, deletion, external-write, and sensitive-data gates. The API always re-evaluates the authenticated user's current Registration role, organization membership, event assignment, and resource permissions.
 
+## Operational report exports
+
+`export request` accepts `format: "XLSX"` (the default when omitted) or `"CSV"`.
+Use `filters.view` to name the population rather than relying on a dataset label:
+
+- RSVP: `MASTER` (all invitees, grouped employee/guest responses; default),
+  `CURRENT` (current response rows per person), `HISTORY` (all registration
+  records, not every edit revision), or `CLIENT_REGISTRATION` (current completed
+  employee/guest responses, including declines; excludes nonrespondents/drafts).
+  The client XLSX has **Attending**, **Not Attending**, **Master**, and **Metadata**
+  sheets; its CSV contains Master data only. Guest staff/department fields
+  describe the host, while menu and dietary answers remain person-scoped.
+- SEATING: `CURRENT` (active bookings; default) or `HISTORY` (active and released).
+- ATTENDANCE: `CURRENT` (expected people; default) or `CHECKED_IN` (expected people
+  with a check-in that has not been undone), or `ALL_INVITEES` (roster invitees,
+  including nonrespondents/declines, plus current guests). Registered, submitted,
+  attending, and active check-in states remain separate. None defines draw
+  eligibility.
+
+Form, registration-status and submission-date filters apply only to RSVP.
+Other datasets do not accept `view`. These combinations are validated by the API.
+
+```sh
+rsvp export request \
+  --ack-sensitive-data \
+  --allow-state-change \
+  --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","dataset":"RSVP","format":"XLSX","filters":{"view":"MASTER"},"reason":"Organizer master list"}'
+```
+
+Use `export list` to check the requester-scoped job, then `export download` for
+its current authorized download URL. For the client workbook, replace `MASTER`
+in the example with `CLIENT_REGISTRATION`. For the all-invitee attendance report,
+set `dataset` to `ATTENDANCE` and `filters.view` to `ALL_INVITEES`.
+
+Operational check-in accepts `ATTENDING` and legacy `SUBMITTED`; roster/detail,
+manual/QR/reference entry, `report overview`, and `event people overview` use that same
+population. Non-operational statuses remain excluded, and permissions, payment
+gates, duplicate protection, and undo behavior are unchanged. The web panel's
+realtime connection and manual refresh controls do not add a CLI subscription.
+
+Deploy matching API and export-worker versions before requesting the new views;
+old servers/workers do not understand them. Existing CLI commands pass the JSON
+payload to the shared typed API, so no new command or client-only rules are needed.
+
 ## Seating updates
 
 `event seating layout update` moves tables, changes table geometry, and can save a floor plan. It requires `--allow-state-change`; its `--target` must match the payload's top-level `eventId`, not a nested table or seat-map ID:
@@ -242,6 +368,106 @@ rsvp event seating table update \
   --payload '{"organizationId":"org_123","eventId":"evt_123","tableId":"table_123","label":"Table 1"}'
 ```
 
+## Live seating and seat-change notifications
+
+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.
+
+```sh
+rsvp event seating live get --ack-sensitive-data \
+  --payload '{"organizationId":"org_123","eventId":"evt_123"}'
+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"}'
+```
+
+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
+field lookup. Follow `nextCursor` until null; counts and department/category
+context contain only permitted data. The API projects all active occupants of the
+selected map in batches before filtering; small pages are not database-level
+filtered pagination.
+
+### Imported-field seating categories
+
+Category coloring is optional and disabled by default. An authorized organizer
+can read the eligible imported fields and their actual event values, then save one
+selected field and a unique six-digit hex color for each canonical value. The
+server includes unregistered invitees when it discovers the imported values;
+guests inherit the host's imported value. It excludes identity, contact, system,
+nested and multi-value data, and enforces sensitive-field grants before it returns
+field keys, values, legends, filters or seat colors.
+
+```sh
+rsvp event seating category config get --ack-sensitive-data \
+  --payload '{"organizationId":"org_123","eventId":"evt_123"}'
+
+rsvp event seating category config update \
+  --ack-sensitive-data --allow-state-change --target evt_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","configurationVersion":3,"config":{"enabled":true,"fieldKey":"department","seed":"chosen-once","colors":[{"value":"finance","color":"#155e75"},{"value":"operations","color":"#7c2d12"}]}}'
+```
+
+The get command is sensitive-data acknowledged. The update command additionally
+requires explicit state-change confirmation and a target matching `eventId`; it
+forwards `configurationVersion` for optimistic concurrency and the complete
+configuration payload unchanged. It never assigns colors, interprets imported
+values, or bypasses authorization in the CLI.
+
+When categories are enabled, the API preserves saved mappings while new imported
+values arrive and assigns only unused colors. Distinct groups never share a color;
+there is an explicit capacity error instead of palette reuse or truncation. An
+explicit auto-assign-all save is the only intentional re-randomization. Blank,
+missing, unreadable and unauthorized values stay neutral. Disable the setting to
+return ordinary seating status colors while retaining the selected field and
+stable mappings. Clearing the selected field explicitly resets its mappings. Deploy matching web, API and CLI releases, then
+perform separate live acceptance before enabling it for an event.
+
+`people registration update` forwards the organizer-edit API. Supply the current
+`expectedVersion`, audit `reason`, and complete `seats` array preserving unchanged
+party assignments. Realtime-enabled changes additionally require valid exact-seat
+holds through the existing realtime protocol; the CLI does not acquire holds.
+Use `--ack-sensitive-data --allow-state-change --target <registration-id>`.
+Saving does not send email unless the payload opts in. Re-read the revision
+after conflicts.
+
+To notify for a seat-only move, add `seatChangeNotice` to the same save. The
+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.
+
+```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"}}'
+```
+
+A separate manual notice for an already committed revision remains available:
+
+```sh
+rsvp people registration confirmation resend \
+  --allow-email --allow-state-change --target reg_123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","registrationId":"reg_123","purpose":"SEAT_CHANGE","expectedRegistrationVersion":5,"idempotencyKey":"4d68a320-013d-43c7-bfcc-d1126827d8c5"}'
+```
+
+Replace the sample UUID with a new UUID for a new request; reuse that same UUID
+for retries of that request. Omitted `purpose` remains `CONFIRMATION`; seat-change
+requests require the committed `expectedRegistrationVersion`. Queue acceptance
+is not delivery. Stale revisions, unavailable copy and current permissions are
+checked by the server, and delivery rechecks the current recipient and active
+seats without including names, private answers or QR codes.
+
+Legacy copy is `seatChangeNotification: {enabled, subject, body}` in the
+`REGISTRATION_RULES` payload for `event setup step update`, with the current
+configuration version. Configurable copy is
+`definition.communications.participant.seatChange: {enabled, subject, body}`;
+merge into the complete named draft, preview, save with its revision, read back,
+then publish only with separate approval. Existing responses use their saved
+published version. Both default disabled/blank; missing copy never falls back to
+confirmation copy. No event-specific copy is supplied or enabled by this change.
+
 ## Audience tiers
 
 Audience tiers control which invitees can use a seat or table. List the tiers and their current invitee, table, and seat counts with:
@@ -309,6 +535,20 @@ rsvp template create \
 
 Instantiate the returned template version through `rsvp template instantiate`, then use the existing staged roster import. The example expects roster columns `email`, `name`, `staffId`, and `employmentType`; only `FTE` and `INTERN` values are configured as eligible profiles. Rules for other events should be expressed in their own template payloads using the same generic contracts.
 
+## Monorepo development
+
+Follow the [development workflow](../../../docs/development-workflow.md#required-cli-coverage). App/API changes affecting this CLI must update its commands, types/input-output contracts, help/docs and verification in the same change. Use the existing authenticated product API rather than CLI-only business logic. Presentation-only changes do not require CLI edits; record why when no CLI update was needed.
+
+From the repository root after isolated-worktree initialization:
+
+```bash
+bun --filter @go-labs-sg/rsvp typecheck
+bun --filter @go-labs-sg/rsvp build
+bun run packages/rsvp/cli/src/index.ts help
+```
+
+Building is not publication or permission to mutate live data. Use focused temporary business-behavior tests and the final pre-push gate from the shared workflow. Use this package's actual scripts; do not assume it has a command-artifact generator.
+
 ## Managed organization provisioning
 
 `organization create` requires an `ownerEmail` in its JSON payload and the

package/dist/index.js

@@ -6549,7 +6549,7 @@ var commands = {
     effects: ["sensitive-data", "state-change"],
     operation: (api, input) => api.export.requestExport.mutate(input),
     payloadOnly: true,
-    summary: "Request an export (--payload JSON)."
+    summary: "Request an operational report (--payload JSON; format CSV/XLSX, default XLSX; RSVP views MASTER/CURRENT/HISTORY/CLIENT_REGISTRATION; ATTENDANCE views CURRENT/CHECKED_IN/ALL_INVITEES; SEATING views CURRENT/HISTORY)."
   },
   "export list": {
     effects: ["sensitive-data"],
@@ -6626,6 +6626,8 @@ Object.assign(commands, {
   "admission identity-exception resolve": payloadCommand((api, input) => api.admission.resolveIdentityException.mutate(input), "Resolve an identity exception (--payload JSON).", ["sensitive-data", "state-change"]),
   "audit list": payloadCommand((api, input) => api.audit.listEventActivity.query(input), "List event audit activity (--payload JSON).", ["sensitive-data"]),
   "event check-in qr": payloadCommand((api, input) => api.event.checkInByQr.mutate(input), "Check in using a QR token (--payload JSON).", ["state-change"]),
+  "event flow image upload create": payloadCommand((api, input) => api.eventFlow.createImageAssetUpload.mutate(input), "Create an event-local registration-flow image upload URL (--payload JSON).", ["external-write", "state-change"], "eventId"),
+  "event flow image finalize": payloadCommand((api, input) => api.eventFlow.finalizeImageAsset.mutate(input), "Finalize an event-local registration-flow image after the external upload (--payload JSON).", ["state-change"], "assetId"),
   "event logo upload create": payloadCommand((api, input) => api.event.createLogoUpload.mutate(input), "Create an event-logo upload URL (--payload JSON).", ["external-write", "state-change"], "eventId"),
   "event logo update": payloadCommand((api, input) => api.event.updateLogo.mutate(input), "Set or clear the event logo (--payload JSON).", ["state-change"], "eventId"),
   "event banner upload create": payloadCommand((api, input) => api.event.createBannerUpload.mutate(input), "Create a banner-image upload URL (--payload JSON).", ["external-write", "state-change"], "eventId"),
@@ -6652,6 +6654,18 @@ Object.assign(commands, {
   "event reminder counts": payloadCommand((api, input) => api.event.getReminderSegmentCounts.query(input), "Get reminder segment counts (--payload JSON).", ["sensitive-data"]),
   "event rsvp manifest": payloadCommand((api, input) => api.event.getRsvpManifest.query(input), "Get the caller's registration manifest (--payload JSON).", ["sensitive-data"]),
   "event seating availability": payloadCommand((api, input) => api.event.getSeatAvailability.query(input), "Get seat availability (--payload JSON)."),
+  "event seating live get": payloadCommand((api, input) => api.event.getLiveSeating.query(input), "Get the selected live seating map (--payload JSON).", ["sensitive-data"]),
+  "event seating category config get": payloadCommand((api, input) => api.event.getSeatingCategoryConfig.query(input), "Get authorized imported-field seating category settings (--payload JSON).", ["sensitive-data"]),
+  "event seating category config update": payloadCommand((api, input) => api.event.updateSeatingCategoryConfig.mutate(input), "Save imported-field seating category settings with configurationVersion (--payload JSON).", ["sensitive-data", "state-change"], "eventId"),
+  "event seating occupants list": payloadCommand((api, input) => api.event.getLiveSeatingOccupants.query(input), "List permitted occupants by seatMapId, tableId, department, categoryValue and query; follow nextCursor (--payload JSON).", ["sensitive-data"]),
+  "people registration edit get": payloadCommand((api, input) => api.event.getRegistrationForEdit.query(input), "Get current revision, permitted attendees, eligible seats and notification readiness (--payload JSON).", ["sensitive-data"]),
+  "people registration update": {
+    ...payloadCommand((api, input) => api.event.updateRegistration.mutate(input), "Save organizer edits with expectedVersion and reason; seating requires full-party seats and configured holds. Optional seatChangeNotice queues a seat-change notice atomically with a seat-only save (--payload JSON).", ["sensitive-data", "state-change"], "registrationId"),
+    conditionalEffects: [
+      { effect: "email", whenPayloadField: "seatChangeNotice" }
+    ]
+  },
+  "people registration confirmation resend": payloadCommand((api, input) => api.event.resendRegistrationConfirmation.mutate(input), "Queue CONFIRMATION (default) or SEAT_CHANGE with expectedRegistrationVersion and idempotencyKey; retries reuse that key (--payload JSON).", ["email", "state-change"], "registrationId"),
   "event realtime-token issue": payloadCommand((api, input) => api.event.issueRealtimeToken.mutate(input), "Issue a realtime token (--payload JSON).", ["sensitive-data", "state-change"]),
   "event mine list": payloadCommand((api, input) => api.event.listMyEvents.query(input), "List the caller's events (--payload JSON)."),
   "event reminder list": payloadCommand((api, input) => api.event.listReminderSegments.query(input), "List reminder segments (--payload JSON).", ["sensitive-data"]),
@@ -6725,6 +6739,7 @@ var getCommandManifest = () => ({
       summary: "Show the CLI version and configured API base URL."
     },
     ...Object.entries(commands).map(([path, command]) => ({
+      ...command.conditionalEffects ? { conditionalEffects: command.conditionalEffects } : {},
       effects: command.effects,
       path,
       summary: command.summary
@@ -6966,6 +6981,7 @@ var collectTargets = (input, targetKey) => {
   }
   return [];
 };
+var getConditionalEffects = (definition, input) => (definition.conditionalEffects ?? []).flatMap(({ effect, whenPayloadField }) => input && Object.hasOwn(input, whenPayloadField) && Reflect.get(input, whenPayloadField) != null ? [effect] : []);
 var requireEffects = async (effects, flags, confirm, input, targetKey) => {
   if (effects.length === 0)
     return;
@@ -7129,7 +7145,12 @@ Waiting for approval\u2026
     if (!definition)
       throw new CliUsageError("Unknown command. Run 'rsvp help' to list commands.");
     const input = getInput(parsed.flags, definition.payloadOnly, definition.scope);
-    await requireEffects(definition.effects, parsed.flags, dependencies.confirm, input, definition.targetKey);
+    await requireEffects([
+      ...new Set([
+        ...definition.effects,
+        ...getConditionalEffects(definition, input)
+      ])
+    ], parsed.flags, dependencies.confirm, input, definition.targetKey);
     const accessToken = !dependencies.apiClient && !definition.public ? await getAuthenticatedAccessToken({
       apiBaseUrl,
       store: getCredentialStore()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/rsvp",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "RSVP CLI for authorized event operations.",
   "type": "module",
   "main": "./dist/index.js",