@pingroom/cli 0.7.2 → 0.7.4

package/README.md

@@ -6,11 +6,6 @@ from CI, scripts, and agents. Delivered as push straight to your phone.
 One dependency (`qrcode-terminal`, used only to draw the pairing QR). Works
 anywhere Node ≥ 20 runs.
 
-> **Release status:** 0.7.2 is prepared for publish — the room grant, the
-> `attachments:write` scope `--attach` always needed, and actionable text on the
-> refusals you can fix. The GitHub Action pins 0.7.2, so publish before relying
-> on it.
-
 ## Install and first run
 
 Install globally, then connect:
@@ -106,8 +101,9 @@ Approving on the phone grants two separate things, and both are enforced:
   `handoffs:create`, `live:write`. Nothing widens them later; a command needing
   one you did not approve returns `403 insufficient_scope`.
 - **Rooms** — one room, several, or all of them. A room outside that grant
-  returns `403 room_not_granted` on any write, including pings, questions and
-  live streams. Widen it under Connected Agents in the app.
+  returns `403 room_not_granted` on every room-scoped call — writes such as
+  pings, questions and live streams, and reads such as listing a room's quick
+  actions or webhooks. Widen it under Connected Agents in the app.
 
 Both refusals print the fix, not just the code. A credential paired by an older
 CLI carries the scope set that version asked for — reconnect to re-approve if a
@@ -157,7 +153,7 @@ URL (it embeds its own secret — treat it like a password and store it as a CI
 ```
 pingroom ping [options]
 
-  -m, --message <text>   Ping body text (required)
+  -m, --message <text>   Ping body (required; <= 120 private / <= 160 public)
   -t, --title <text>     Ping title (<= 40 chars)
   -a, --action <1-4>     Quick-action slot to attribute the ping to
   -d, --data <json>      Extra JSON data, e.g. '{"commit":"abc123"}'
@@ -173,6 +169,11 @@ pingroom ping [options]
       --json             Print the raw JSON response
 ```
 
+Ping titles are limited to 40 characters. Bodies are limited to 120 characters
+in private rooms and 160 in public rooms. A room code or webhook URL does not
+reveal room visibility, so the CLI rejects only bodies over 160 locally; the
+server applies the tighter 120-character private-room limit.
+
 To make the ping actionable, add `--require-ack`. The first eligible recipient to
 acknowledge it wins; `--ack-timeout` optionally expires it if nobody responds:
 
@@ -205,8 +206,9 @@ pingroom ping --token "$PINGROOM_TOKEN" --room AB12 -m "Nightly report" \
   --attach ./report.pdf --attach ./summary.md
 ```
 
-Accepted types are `md`, `pdf`, `html`, `txt`, `jpg`, `jpeg`, `png`, up to
-5 MiB each and at most 4 per Ping. `--attach` needs an agent token — a webhook ping
+Accepted types are `md`, `pdf`, `html`, `txt`, `jpg`, `jpeg`, `png`, `zip`, up to
+5 MiB each and at most 4 per Ping. A `.zip` must be a real archive starting at
+byte zero — the server rejects one with any payload prefixed to it. `--attach` needs an agent token — a webhook ping
 has no uploader identity to bind private files to — and the bound account must
 hold Pro (otherwise the upload fails with `pro_required`). An upload that never
 reaches a ping expires by itself after 24 hours.
@@ -364,15 +366,55 @@ Full protocol: <https://pingroom.io/liveactivities.md>
     message: 'Ship ${{ github.sha }} to production?'
     handoff: 'true'
     question: 'true'
-    options: 'deploy:Deploy,hold:Hold'
+    options: |
+      deploy:Deploy
+      hold:Hold
     idempotency-key: 'deploy-${{ github.run_id }}'
     wait: 'true'
 - if: steps.gate.outputs.answer == 'deploy'
   run: ./deploy-prod.sh
+
+# Or ask the whole room instead of one person. Same outputs, plus question-id.
+# Requires v0.7.3 or newer — see the note below before copying this block.
+- id: env
+  uses: pingroom/cli@v0.7.3
+  with:
+    token: ${{ secrets.PINGROOM_TOKEN }}
+    room: ab12cd
+    ask: 'true'
+    message: 'Which environment?'
+    context: 'build ${{ github.run_number }}'
+    options: |
+      prod:Production
+      staging:Staging
+    wait: 'true'
 ```
 
+### Version requirements
+
+`ask`, `context`, `timeout`, `api` and the `question-id` output were added in
+**v0.7.3**. Pin at least `pingroom/cli@v0.7.3` to use them. On an older pin —
+including `@v0` before it is moved to v0.7.3 — GitHub treats them as unexpected
+inputs, warns, and drops them; the step then falls through to the plain `ping`
+path, `outputs.answer` is never set, and any job gated on it silently proceeds.
+
+`urgent` was added in **v0.7.4** and has the same failure mode on an older pin:
+GitHub drops the unknown input and the Ping goes out at normal priority, which
+looks like it worked. `require-ack` is not a substitute — as of the same release
+it opens the acknowledgement lifecycle without raising the interruption level,
+so a workflow that used it to break through Focus needs `urgent: true`.
+
+Everything else on this page (ping, `require-ack`, and the whole `handoff`
+family) works on `@v0`.
+
+`options` is one `value:label` per line. Trailing newlines are ignored first, so
+a value that is a single line after trimming — including a one-line `options: |`
+block — still splits on commas. A label that contains a comma must therefore be
+written one-per-line.
+
 The handoff action exposes outputs `handoff-id`, `state`, `acknowledged-by`,
-`answer`, and `delivery-state`.
+`answer`, and `delivery-state`; the ask action exposes `question-id`, `state`,
+and `answer`. `api` overrides the API base URL for every mode.
 
 ## GitLab CI