@go-labs-sg/rsvp 0.2.0

package/README.md

@@ -0,0 +1,97 @@
+# RSVP CLI (`rsvp`)
+
+JSON-first command-line access to RSVP organizations, events, guests, check-in, payments, reporting, retention, and administrative operations.
+
+## 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.
+
+Check whether a compatible Bun version is already available:
+
+```bash
+bun --version
+```
+
+If Bun is missing, install it for the current operating system:
+
+**macOS (Homebrew)**
+
+```bash
+brew install oven-sh/bun/bun
+```
+
+**Windows (PowerShell)**
+
+```powershell
+powershell -c "irm bun.sh/install.ps1|iex"
+```
+
+**Linux**
+
+```bash
+curl -fsSL https://bun.com/install | bash
+```
+
+If Bun is installed but older than 1.4.0, run `bun upgrade`. Open a new terminal if the installer changes `PATH`, then verify `bun --version` again. Installation agents should skip the platform installer when Bun 1.4.0 or newer is already available.
+
+Install and verify the CLI:
+
+```sh
+bun add --global @go-labs-sg/rsvp
+rsvp version
+```
+
+## Authentication
+
+```sh
+rsvp auth login
+rsvp auth status
+rsvp auth whoami
+```
+
+`rsvp auth login` opens RSVP in the system browser. Sign in through RSVP's normal Google-backed web flow if needed, verify that the displayed device and code match the terminal, then click **Authorize CLI**. Existing browser sessions skip another Google login but never skip explicit CLI approval.
+
+RSVP CLI access is limited to global administrators. The server rechecks the account's current global role and ban state when issuing, refreshing, and authenticating CLI credentials, so removing the admin role immediately blocks further CLI access.
+
+The CLI polls automatically and stores only RSVP-issued credentials through `Bun.secrets`. It does not store Google credentials and has no API-key or environment-variable fallback. Use `rsvp auth logout` to revoke the remote session and remove its local credential. For SSH or containers, pass `--no-browser` and open the printed URL on another device.
+
+The default API is `https://rsvp.getout.events`. Override it with `RSVP_API_URL` or `--api-url`; non-local overrides must use HTTPS.
+
+## Command safety
+
+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.
+
+Commands returning invitee, registration, roster, report, audit, export, payment, or user data require `--ack-sensitive-data`. Mutations require their exact effect gates and a `--target` matching the affected resource in the payload. Depending on the operation, gates include:
+
+- `--allow-state-change`
+- `--allow-email`
+- `--allow-delete`
+- `--allow-external-write`
+- `--allow-financial-write`
+
+Example:
+
+```sh
+rsvp check-in by-reference \
+  --allow-state-change \
+  --target ABC123 \
+  --payload '{"organizationId":"org_123","eventId":"evt_123","referenceCode":"ABC123"}'
+```
+
+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 RSVP role, organization membership, event assignment, and resource permissions.
+
+## Reusable event configurations
+
+`template create` accepts a complete JSON payload, so event-specific workflows remain data rather than product code. This package includes `examples/amgen-dinner-dance-2026-template.json` as a validated example of Staff ID confirmation, employment-based eligibility, conditional fields, guest limits, and categorized decline reasons.
+
+Create the template after replacing its organization ID:
+
+```sh
+payload="$(jq --arg organizationId "org_123" '.organizationId = $organizationId' examples/amgen-dinner-dance-2026-template.json)"
+rsvp template create \
+  --allow-state-change \
+  --target "Amgen Dinner & Dance 2026" \
+  --payload "$payload"
+```
+
+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.