@go-labs-sg/rsvp 0.14.0 → 0.16.0

package/README.md

@@ -2,6 +2,20 @@
 
 JSON-first command-line access to Registration organizations, events, guests, check-in, payments, reporting, retention, and administrative operations.
 
+## First step: update before use
+
+Before starting a task, **update to the latest published release first**, including when an AI agent runs this CLI:
+
+```bash
+bun add --global @go-labs-sg/rsvp@latest
+rsvp version
+rsvp --help
+```
+
+Run this sequence once per task, not before every command. Re-read the updated help before choosing commands or flags. If updating fails, stop and report the failure rather than silently using an outdated CLI. If the user explicitly requested a pinned version or a development/staging build, preserve that version instead of replacing it with the public release.
+
+New installation? Follow the runtime and installation instructions below to install Bun first, then return to this step.
+
 ## Runtime and installation
 
 The CLI requires [Bun](https://bun.com/docs/installation) 1.4.0 or newer. npm distributes the package, while the installed command runs under Bun.
@@ -77,7 +91,7 @@ Argument-parsing errors use a safe command label and never echo option values,
 including roster JSON passed through `--payload`. Surrounding shell history and
 automation can still record arguments independently of the CLI's error output.
 
-Use `rsvp help` for the command catalogue. Every response is a JSON envelope on stdout; errors and diagnostics go to stderr. `rsvp manifest` emits the machine-readable command reference for tooling.
+Use `rsvp help` or `rsvp --help` for the command catalogue. `--help=true` and `--help=1` also show help; `--help=false` and `--help=0` preserve normal command execution. Other inline help values are rejected before command execution, even if a later `--help` flag is valid. Every response is a JSON envelope on stdout; errors and diagnostics go to stderr. `rsvp manifest` emits the machine-readable command reference for tooling.
 
 ## Public event page and images
 
@@ -121,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
@@ -207,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:
@@ -295,6 +435,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"),
@@ -6692,6 +6694,7 @@ Object.assign(commands, {
   "waitlist offer respond": payloadCommand((api, input) => api.waitlist.respondToOffer.mutate(input), "Respond to a waitlist offer (--payload JSON).", ["state-change"])
 });
 var getCommandManifest = () => ({
+  beforeUse: "First step before each task: update to the latest published release with 'bun add --global @go-labs-sg/rsvp@latest', then run 'rsvp version' and 'rsvp --help' before using commands. Update once per task. If updating fails, stop and report it. Preserve an explicitly requested pinned or development/staging version.",
   commands: [
     {
       effects: [],
@@ -6730,6 +6733,7 @@ var getCommandManifest = () => ({
     }))
   ],
   globalOptions: [
+    "--help",
     "--api-url <url>",
     "--no-browser",
     "--organization-id <id>",
@@ -6792,6 +6796,7 @@ var booleanFlags = new Set([
   "--allow-external-write",
   "--allow-financial-write",
   "--allow-state-change",
+  "--help",
   "--no-browser"
 ]);
 var valueFlags = new Set([
@@ -6819,6 +6824,9 @@ var parseArgs = (argv) => {
       throw new CliUsageError(`Unknown option: ${name}.`);
     const inlineValue = equalSignIndex === -1 ? undefined : argument.slice(equalSignIndex + 1);
     if (inlineValue !== undefined) {
+      if (name === "--help" && !["true", "false", "1", "0"].includes(inlineValue)) {
+        throw new CliUsageError("--help accepts only true, false, 1, or 0.");
+      }
       flags.set(name, inlineValue);
       continue;
     }
@@ -6999,7 +7007,7 @@ var runRsvpCli = async (argv, dependencies) => {
   let command = "unknown";
   try {
     const parsed = parseArgs(argv);
-    const requestedCommand = parsed.positionals.join(" ") || "help";
+    const requestedCommand = isEnabledFlag(parsed.flags, "--help") ? "help" : parsed.positionals.join(" ") || "help";
     if (!knownCommandNames.has(requestedCommand)) {
       throw new CliUsageError("Unknown command. Run 'rsvp help' to list commands.");
     }

package/package.json

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