@go-labs-sg/registration 1.0.0

package/README.md

@@ -0,0 +1,86 @@
+# Registration CLI (`reg`)
+
+Command-line access to Registration organizations, events, forms, and attendee registrations. Responses use deterministic JSON envelopes for scripts and agent tools.
+
+## 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:
+
+```bash
+bun add --global @go-labs-sg/registration
+reg version
+```
+
+## Authentication
+
+```bash
+reg auth login
+reg auth status
+reg auth whoami
+```
+
+`reg auth login` opens Registration in the system browser. Sign in through the normal Google-backed web flow if needed, confirm that the code and device match your terminal, and click **Authorize CLI**. An existing browser session skips another Google login but never skips explicit authorization.
+
+The CLI polls automatically and stores only Registration-issued credentials through `Bun.secrets`. It does not store Google credentials and has no API-key or environment-variable fallback. Use `reg auth logout` to revoke the remote session and remove its local credential. For SSH and containers, pass `--no-browser` and open the printed URL on another device.
+
+The CLI uses `https://registration.getout.events` by default. Set `REG_API_URL` or pass `--api-url` for staging or local development. Overrides must use HTTPS, except `http://localhost` and `http://127.0.0.1`.
+
+## Commands
+
+```bash
+reg organization list --input '{}'
+reg event list --input '{"organizationId":"..."}'
+reg form list --input '{"eventId":"..."}'
+reg registration check-in --input '{"registrationId":"..."}'
+reg email list --input '{"eventId":"...","page":1,"perPage":25}'
+```
+
+Run `reg help` for every option. Lists support archived records where relevant. Registration lists also support pagination, form, text-search, and status filters.
+
+## Mutation safety
+
+State-changing commands describe the exact target and require typing `CONFIRM` in an interactive terminal. Non-interactive automation must pass an explicit `--target` description and every applicable granular effect flag: `--allow-state-change`, `--allow-email`, `--allow-external-write`, `--allow-delete`, and/or `--allow-financial-write`.
+
+Reads that expose attendee, team, email, or user records require `--ack-sensitive-data`. For mutations, `--target` must exactly match an affected identifier in the validated `--input '<json-object>'`. The API authorizes the browser-authenticated CLI user against the target organization and resource.
+
+Email delivery and arbitrary attachment URLs remain browser-session-only. The CLI exposes authorized email reads, while sends stay in the web app because they create irreversible external communications. Public registration and payment callback flows are intentionally excluded.
+
+## Monorepo development
+
+```bash
+bun --filter @go-labs-sg/registration typecheck
+bun --filter @go-labs-sg/registration build
+bun run golabs -- reg version
+```
+
+Pushing a matching `registration-cli-v<version>` tag runs the release workflow, verifies the packed artifact under Bun 1.4, and publishes it to npm.