@pingroom/cli 0.8.1 → 0.9.0

package/README.md

@@ -257,7 +257,12 @@ it **silently**, `end` closes it with one completion alert.
 The management nouns cover the rest of the agent surface (agent token required;
 `--room` where noted):
 
+Room `--icon` takes a v3 catalog id (`bell`, `globe`, `terminal`, …), never an
+emoji — the server rejects anything off-catalog. Browse ids with
+`pingroom rooms icons`. Quick-action `--icon` is the opposite: it takes an emoji.
+
 ```bash
+pingroom rooms icons                      # browse the v3 room-icon catalog
 pingroom rooms list                       # rooms this account belongs to
 pingroom rooms get GZNFB6BZGJIH
 pingroom rooms create -n "Deploys" --icon bell --color "#e33122"

package/lib/commands/manage.js

@@ -38,9 +38,21 @@ function printJsonOr(args, text, lines) {
 
 export async function rooms(args) {
   if (args.help) { process.stdout.write(`${commandHelp('rooms')}\n`); return EXIT.OK; }
-  const action = sub(args, ['list', 'get', 'create', 'join'], 'rooms');
+  const action = sub(args, ['list', 'get', 'create', 'join', 'icons'], 'rooms');
   const { token, apiBase } = agentContext(args);
 
+  if (action === 'icons') {
+    const { text, json } = await requireOk(
+      httpJson('GET', `${apiBase}/api/agent/room-icons`, { headers: auth(token) }),
+      'rooms icons',
+    );
+    if (args.json) { process.stdout.write(`${text}\n`); return EXIT.OK; }
+    const categories = Array.isArray(json.categories) ? json.categories : [];
+    const lines = categories.map((c) => `${c.label ?? c.id}: ${(c.icons ?? []).join(' ')}`);
+    process.stdout.write(`${lines.join('\n') || '(no icons)'}\n`);
+    return EXIT.OK;
+  }
+
   if (action === 'list') {
     const { text, json } = await requireOk(
       httpJson('GET', `${apiBase}/api/agent/rooms`, { headers: auth(token) }),
@@ -69,17 +81,18 @@ export async function rooms(args) {
       httpJson('POST', `${apiBase}/api/agent/rooms/join`, { headers: auth(token), body: { invite_code: code } }),
       'rooms join',
     );
-    printJsonOr(args, text, `joined ${json.room?.name ?? code}`);
+    // The server returns the room flat, so `json.room` is never set and the
+    // name always fell back to the invite code.
+    printJsonOr(args, text, `joined ${json.room?.name ?? json.name ?? code}`);
     return EXIT.OK;
   }
 
   // create — private by default; --public requires --handle and uses the
   // dedicated consent scope on the server.
   if (!args.name) fail('rooms create needs --name', EXIT.USAGE);
-  if (!args.icon || !args.color) fail('rooms create needs --icon and --color (see "pingroom rooms list-icons" via the app, e.g. --icon bell --color "#e33122")', EXIT.USAGE);
+  if (!args.icon || !args.color) fail('rooms create needs --icon and --color. --icon is a v3 catalog id, not an emoji — run "pingroom rooms icons" to browse, e.g. --icon bell --color "#e33122"', EXIT.USAGE);
 
   const body = { name: args.name, icon: args.icon, color: args.color };
-  if (args.description) body.description = args.description;
 
   let url = `${apiBase}/api/agent/rooms`;
   if (args.public) {
@@ -88,6 +101,17 @@ export async function rooms(args) {
     url = `${apiBase}/api/agent/rooms/public`;
   }
 
+  // The ordinary rooms:write scope creates a MINIMAL private room: the server
+  // marks description (with is_public, handle, category, actions and friends)
+  // `prohibited` there and answers 422. Only the public create carries them.
+  // Say so here rather than posting a request that cannot succeed.
+  if (args.description !== undefined) {
+    if (!args.public) {
+      fail('--description is only accepted on a public room (add --public --handle <handle>). A private agent room is created minimal; set its description from the app.', EXIT.USAGE);
+    }
+    body.description = args.description;
+  }
+
   const { text, json } = await requireOk(httpJson('POST', url, { headers: auth(token), body }), 'rooms create');
   printJsonOr(args, text, `created ${json.room?.invite_code ?? json.invite_code ?? ''} ${args.name}`.trim());
   return EXIT.OK;
@@ -128,7 +152,13 @@ export async function webhooks(args) {
     if (!body.name) fail('webhooks create needs --name', EXIT.USAGE);
     const { text, json } = await requireOk(httpJson('POST', base, { headers: auth(token), body }), 'webhooks create');
     // The trigger URL carries the webhook secret — print it once, like the app.
-    printJsonOr(args, text, `created ${json.webhook?.id ?? ''}\n${json.webhook?.url ?? json.url ?? ''}`.trim());
+    // The server answers with the webhook FLAT plus `webhook_url`; the nested
+    // shapes are only kept as fallbacks. Reading `json.webhook.*` alone printed
+    // a bare "created" and swallowed the one credential this command exists to
+    // hand over.
+    const created = json.webhook ?? json;
+    const url = created.webhook_url ?? created.url ?? json.webhook_url ?? json.url ?? '';
+    printJsonOr(args, text, `created ${created.id ?? ''}\n${url}`.trim());
     return EXIT.OK;
   }
 
@@ -169,7 +199,12 @@ export async function actions(args) {
     return EXIT.OK;
   }
 
-  if (!args.label || !args.icon) fail('actions set needs --label and --icon', EXIT.USAGE);
+  // A Ping's title is optional — its emoji can be the whole name — so
+  // `--label ""` is a deliberate value, not a missing flag. The emoji is the
+  // half that must be there.
+  if (args.label === undefined || !args.icon) {
+    fail('actions set needs --label (may be empty) and --icon', EXIT.USAGE);
+  }
   const body = { label: args.label, icon: args.icon };
   if (args.sound !== undefined) body.sound = args.sound;
   if (args.require_ack) body.requires_ack = true;

package/lib/help.js

@@ -32,7 +32,8 @@ Commands:
            Claude Desktop
   skills   List the PingRoom agent skills, or install them for Claude Code
   activate Retry Agent Inbox activation with the saved QR-paired credential
-  rooms    List, inspect, create, or join rooms (rooms list|get|create|join)
+  rooms    List, inspect, create, or join rooms; browse the icon catalog
+           (rooms list|get|create|join|icons)
   webhooks Manage a room's incoming webhooks (webhooks list|create|update|delete)
   actions  List, configure, or trigger a room's quick actions (actions list|set|trigger)
   approval Send an approve/deny request; with --wait, block on the decision
@@ -313,10 +314,14 @@ export const COMMAND_HELP_SECTIONS = {
   rooms: `rooms (agent token required):
   pingroom rooms list               List the rooms this account belongs to
   pingroom rooms get <code>         Show one room
+  pingroom rooms icons              Browse the v3 room-icon catalog
   pingroom rooms create -n <name> --icon <id> --color <hex>
-                                    Create a private room (add --description);
+                                    Create a minimal private room.
+                                    --icon is a v3 catalog id from "rooms icons"
+                                    (e.g. bell), NOT an emoji;
                                     --public --handle <handle> creates a public
-                                    room under its own consent scope
+                                    room under its own consent scope, and is
+                                    the only create that takes --description
   pingroom rooms join <code>        Join a room by invite code`,
   webhooks: `webhooks (agent token + --room required):
   pingroom webhooks list --room <code>
@@ -329,6 +334,7 @@ export const COMMAND_HELP_SECTIONS = {
   actions: `actions (agent token + --room required):
   pingroom actions list --room <code>
   pingroom actions set <1-4> --room <code> --label <text> --icon <emoji>
+                                          (--label "" makes an emoji-only Ping)
                                     Optional: --sound, --require-ack
   pingroom actions trigger <1-4> --room <code>`,
   approval: `approval (agent token + --room required):

package/lib/http.js

@@ -35,7 +35,13 @@ export function apiDetail(res, json) {
   const base = stripControlChars(
     (json && (json.message || json.error || json.code)) || `HTTP ${res ? res.status : 'error'}`,
   );
-  const hint = json && typeof json.code === 'string' ? API_HINTS[json.code] : undefined;
+  let hint = json && typeof json.code === 'string' ? API_HINTS[json.code] : undefined;
+  // A 401 means the stored credential is dead (revoked in the app, or the
+  // pairing was cleaned up). Without this line the CLI prints a bare
+  // "Unauthenticated." and leaves the user to guess the remedy.
+  if (!hint && res && res.status === 401) {
+    hint = 'This credential is no longer valid — run "pingroom reconnect" to pair again.';
+  }
   return hint ? `${base}\n  ${hint}` : base;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingroom/cli",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Send PingRoom Pings and wait for human decisions from CI, scripts, and agents.",
   "type": "module",
   "bin": {