@pingroom/cli 0.7.3 → 0.7.5

package/README.md

@@ -153,12 +153,15 @@ 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"}'
       --url <https-url>  Make the ping a tappable link (absolute http(s) URL)
       --button-label <t> Link button text (<= 26 chars; requires --url)
+      --location <lat,lng>  Attach a map location (latitude,longitude)
+      --location-label <t>  Location label (<= 100 chars; requires --location)
+      --location-address <t> Address (<= 255 chars; requires --location)
       --require-ack      Keep the ping open until an eligible recipient acknowledges it
       --ack-timeout <s>  Ack deadline in seconds (requires --require-ack)
       --attach <path>    Attach a file; repeat for up to 4 (requires --token)
@@ -169,6 +172,28 @@ 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 send a location, pass decimal latitude and longitude as one comma-separated
+value. Optional map text rides inside the same reserved `data.location` object:
+
+```bash
+pingroom ping --room ab12cd -m "Meet me here" \
+  --location "25.2048,55.2708" \
+  --location-label "Dubai Mall" \
+  --location-address "Downtown Dubai"
+```
+
+Latitude is inclusive -90..90 and longitude is inclusive -180..180. Labels are
+limited to 100 Unicode characters and addresses to 255. The recipient can share
+the point or open it in Waze, Google Maps, Apple Maps, or another installed map
+app. These flags work with agent-token and incoming-webhook sends. When combined
+with `--data`, the explicit flags replace only `data.location`; sibling keys are
+preserved.
+
 To make the ping actionable, add `--require-ack`. The first eligible recipient to
 acknowledge it wins; `--ack-timeout` optionally expires it if nobody responds:
 
@@ -370,13 +395,15 @@ Full protocol: <https://pingroom.io/liveactivities.md>
   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.
+# `scope: room` is what opens it to the room — without it a question is
+# answerable only by the connecting account. Requires v0.7.5 or newer.
 - id: env
-  uses: pingroom/cli@v0.7.3
+  uses: pingroom/cli@v0.7.5
   with:
     token: ${{ secrets.PINGROOM_TOKEN }}
     room: ab12cd
     ask: 'true'
+    scope: 'room'
     message: 'Which environment?'
     context: 'build ${{ github.run_number }}'
     options: |
@@ -392,6 +419,19 @@ Full protocol: <https://pingroom.io/liveactivities.md>
 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.
+
+`scope` was added in **v0.7.5**, and without it every `ask` goes out as a direct
+question to the connecting account — the step still succeeds, so an Action meant
+to poll the room silently polls one person instead.
+
+`urgent` shipped in the **0.7.4 npm package**, but no `v0.7.4` Action tag was
+ever cut, so **v0.7.5 is the first tag that carries it**. It 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`.
 

package/lib/commands/hook.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 
-import { EXIT } from '../constants.js';
+import { EXIT, PRIVATE_PING_MESSAGE_MAX_LENGTH } from '../constants.js';
 import { truncate } from '../util.js';
 import { commandHelp } from '../help.js';
 import { hookFetch, isSafeUrl } from '../http.js';
@@ -62,7 +62,14 @@ function summarizeTranscript(path) {
     const msg = entry && entry.message;
     if (!msg || msg.role !== 'assistant') continue;
     const text = extractAssistantText(msg.content).replace(/\s+/g, ' ').trim();
-    if (text) return truncate(text, 500);
+    // The tighter PRIVATE bound, not the public one. `ping --message` may sit at
+    // the public ceiling because the caller typed that text and the server is
+    // entitled to reject it. Here the CLI COMPOSES the body, and a hook room is
+    // private (max 120), so truncating at 160 would hand the server a body it
+    // rejects — and hookPing swallows the 422, silently dropping the ping. The
+    // text is already being truncated, so the tighter cut costs nothing and is
+    // valid in a public room too.
+    if (text) return truncate(text, PRIVATE_PING_MESSAGE_MAX_LENGTH);
   }
   return '';
 }
@@ -185,7 +192,7 @@ async function hookNotify(event, name, { token, room, apiBase, args }) {
     title = 'Claude finished';
     message = summarizeTranscript(event.transcript_path) || 'Session finished — waiting for you.';
   } else if (name === 'Notification') {
-    message = truncate(event.message || 'Claude is waiting for your input.', 500);
+    message = truncate(event.message || 'Claude is waiting for your input.', PRIVATE_PING_MESSAGE_MAX_LENGTH);
     // A PreToolUse hook already turns permission prompts into a question; skip
     // the duplicate "needs your permission" Notification so you aren't paged twice.
     if (/permission/i.test(message)) return EXIT.OK;
@@ -193,7 +200,12 @@ async function hookNotify(event, name, { token, room, apiBase, args }) {
   } else if (name === 'SessionEnd') {
     if (event.reason === 'clear') return EXIT.OK; // /clear isn't worth a ping
     title = 'Session ended';
-    message = `Claude Code session ended (${event.reason || 'unknown'}).`;
+    // `reason` is whatever the host put in the event, so bound the composed
+    // line rather than trusting it to stay short.
+    message = truncate(
+      `Claude Code session ended (${event.reason || 'unknown'}).`,
+      PRIVATE_PING_MESSAGE_MAX_LENGTH,
+    );
   } else {
     return EXIT.OK; // unknown event — stay silent rather than send noise
   }

package/lib/commands/live.js

@@ -51,7 +51,8 @@ export async function live(args) {
     state: sub === 'end' ? (args.failed ? 'failed' : 'done') : 'running',
   };
 
-  // 256, not the 500 a ping body gets: this is the card's one live line.
+  // This live-status payload field has its own 256-character contract; ordinary
+  // Ping bodies are 120 in private rooms and 160 in public rooms.
   requireMaxLength(args.message, 256, '--message');
   requireMaxLength(args.title, 40, '--title');
   requireMaxLength(args.prompt, 256, '--prompt');

package/lib/commands/ping.js

@@ -1,16 +1,51 @@
-import { EXIT } from '../constants.js';
+import {
+  EXIT,
+  LOCATION_ADDRESS_MAX_LENGTH,
+  LOCATION_LABEL_MAX_LENGTH,
+  PING_TITLE_MAX_LENGTH,
+  PUBLIC_PING_MESSAGE_MAX_LENGTH,
+} from '../constants.js';
 import { fail, parseDataObject, requireMaxLength } from '../util.js';
 import { commandHelp } from '../help.js';
 import { apiDetail, httpJson, requireSafeUrl, uploadAttachments } from '../http.js';
 import { requireStoredCredentialOrigin, resolveApiBase, resolveRoom, resolveToken } from '../config.js';
 
+const DECIMAL_COORDINATE = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+function parseLocation(value) {
+  const parts = String(value).split(',');
+  if (parts.length !== 2) {
+    fail('--location must contain exactly two coordinates formatted "latitude,longitude"', EXIT.USAGE);
+  }
+
+  const [latitudeText, longitudeText] = parts.map((part) => part.trim());
+  if (!DECIMAL_COORDINATE.test(latitudeText) || !DECIMAL_COORDINATE.test(longitudeText)) {
+    fail('--location coordinates must be finite numbers formatted "latitude,longitude"', EXIT.USAGE);
+  }
+
+  const latitude = Number(latitudeText);
+  const longitude = Number(longitudeText);
+  if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
+    fail('--location coordinates must be finite numbers formatted "latitude,longitude"', EXIT.USAGE);
+  }
+  if (latitude < -90 || latitude > 90) {
+    fail('--location latitude must be between -90 and 90', EXIT.USAGE);
+  }
+  if (longitude < -180 || longitude > 180) {
+    fail('--location longitude must be between -180 and 180', EXIT.USAGE);
+  }
+  return { latitude, longitude };
+}
+
 export async function ping(args) {
   if (args.help) { process.stdout.write(`${commandHelp('ping')}\n`); return EXIT.OK; }
 
   const message = args.message;
   if (!message) fail('a --message is required', EXIT.USAGE);
-  requireMaxLength(message, 500, '--message');
-  requireMaxLength(args.title, 40, '--title');
+  // Room visibility is not encoded in a room code or webhook URL. Validate the
+  // public ceiling here; the API applies 120 for private rooms and 160 for public.
+  requireMaxLength(message, PUBLIC_PING_MESSAGE_MAX_LENGTH, '--message');
+  requireMaxLength(args.title, PING_TITLE_MAX_LENGTH, '--title');
 
   if (args.action !== undefined && !/^[1-4]$/.test(String(args.action))) {
     fail('--action must be an integer 1–4', EXIT.USAGE);
@@ -57,6 +92,23 @@ export async function ping(args) {
     if (args.button_label !== undefined) data.button_label = args.button_label;
   }
 
+  // Location ping: explicit flags own the reserved data.location object. They
+  // replace a raw --data location while leaving every sibling key untouched.
+  if (args.location_label !== undefined && args.location === undefined) {
+    fail('--location-label requires --location', EXIT.USAGE);
+  }
+  if (args.location_address !== undefined && args.location === undefined) {
+    fail('--location-address requires --location', EXIT.USAGE);
+  }
+  if (args.location !== undefined) {
+    requireMaxLength(args.location_label, LOCATION_LABEL_MAX_LENGTH, '--location-label');
+    requireMaxLength(args.location_address, LOCATION_ADDRESS_MAX_LENGTH, '--location-address');
+    const location = parseLocation(args.location);
+    if (args.location_label !== undefined) location.label = args.location_label;
+    if (args.location_address !== undefined) location.address = args.location_address;
+    data = { ...(data || {}), location };
+  }
+
   const webhook = args.webhook || process.env.PINGROOM_WEBHOOK_URL;
   const token = resolveToken(args);
   const apiBase = resolveApiBase(args);
@@ -81,6 +133,7 @@ export async function ping(args) {
     if (args.action !== undefined) body.action = Number(args.action);
     if (data) body.data = data;
     if (args.require_ack) body.requires_ack = true;
+    if (args.urgent) body.is_urgent = true;
     if (ackTimeout !== undefined) body.ack_timeout_seconds = ackTimeout;
     result = await httpJson('POST', webhook, { body });
   } else if (token) {
@@ -96,6 +149,7 @@ export async function ping(args) {
     if (args.action !== undefined) body.action_number = Number(args.action);
     if (data) body.data = data;
     if (args.require_ack) body.requires_ack = true;
+    if (args.urgent) body.is_urgent = true;
     if (ackTimeout !== undefined) body.ack_timeout_seconds = ackTimeout;
     if (attachPaths.length) {
       body.attachment_ids = await uploadAttachments(attachPaths, apiBase, token);

package/lib/constants.js

@@ -5,3 +5,15 @@ export const MCP_ENDPOINT = `${BUILTIN_API}/api/agent/mcp`;
 export const DEFAULT_API = process.env.PINGROOM_API_URL || BUILTIN_API;
 
 export const EXIT = { OK: 0, ERROR: 1, USAGE: 2, EXPIRED: 3, CANCELLED: 4 };
+
+// A caller holding only a room code or webhook URL cannot know the room's
+// visibility without another request. Keep the CLI's local ceiling at the
+// public-room limit; Laravel applies the tighter private-room limit.
+export const PING_TITLE_MAX_LENGTH = 40;
+export const PRIVATE_PING_MESSAGE_MAX_LENGTH = 120;
+export const PUBLIC_PING_MESSAGE_MAX_LENGTH = 160;
+
+// Reserved data.location display metadata. Coordinate ranges are part of the
+// numeric format itself; these caps mirror the API's Unicode-aware string rules.
+export const LOCATION_LABEL_MAX_LENGTH = 100;
+export const LOCATION_ADDRESS_MAX_LENGTH = 255;

package/lib/help.js

@@ -35,13 +35,20 @@ Commands:
   logout   Forget the stored credential`;
 
 export const HELP_PING = `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 object, e.g. '{"commit":"abc123"}'
       --url <https-url>  Make the ping a tappable link (absolute http(s) URL)
       --button-label <t> Link button text (<= 26 chars; requires --url)
-      --require-ack      Keep the ping open until an eligible recipient acknowledges it
+      --location <lat,lng>  Attach a map location (latitude,longitude)
+      --location-label <t>  Location label (<= 100 chars; requires --location)
+      --location-address <t> Address (<= 255 chars; requires --location)
+      --urgent           Deliver time-sensitive so it breaks through Focus / Do Not
+                         Disturb. Delivery only - asks nothing of the recipient
+      --require-ack      Keep the ping open until an eligible recipient acknowledges it,
+                         showing a lock-screen card with an Acknowledge button. Does
+                         not raise the interruption level; combine with --urgent
       --ack-timeout <s>  Ack deadline in seconds (requires --require-ack)
       --attach <path>    Attach a file (md/pdf/html/txt/jpg/jpeg/png/zip, <= 5 MiB);
                          repeat for up to 4. Requires --token and a Pro account
@@ -105,7 +112,7 @@ export const HELP_LIVE = `live <start|update|end|get> options (agent token, or a
                              'question', which is still accepted)
       --category <name>      start only: status | steps | alert. Legacy, but
                              'alert' has no template equivalent and is the only
-                             way to start time-sensitive without --require-ack
+                             way to start a stream time-sensitive
       --steps <a,b,c>        start only: 2-8 comma-separated step labels
   -m, --message <text>       The card's live message line
       --progress <0..1>      Progress bar / Dynamic Island gauge
@@ -124,7 +131,8 @@ export const HELP_LIVE = `live <start|update|end|get> options (agent token, or a
   -d, --data <json>          Structured data object carried on this frame
   -t, --title <text>         Card title (<= 40 chars)
   -a, --action <1-4>         Quick-action slot supplying the icon and sound
-      --require-ack          Add an Acknowledge button
+      --require-ack          Add an Acknowledge button (does not raise the
+                             interruption level; see --category alert)
       --ack-timeout <s>      Ack deadline in seconds
       --room <code>          Room invite code (used with --token)
   -w, --webhook <url>        Room webhook URL instead of a token`;
@@ -202,6 +210,10 @@ Examples:
   pingroom ping -w "$PINGROOM_WEBHOOK_URL" -m "Build 512 ready" \\
     --url https://ci.example.com/builds/512 --button-label "Open build"
 
+  # Location ping — recipients can share it or open it in a maps app:
+  pingroom ping --room ab12cd -m "Meet me here" \\
+    --location "25.2048,55.2708" --location-label "Dubai Mall"
+
   # Gate a deploy on a human tap — the chosen value prints to stdout:
   if [ "$(pingroom ask --token "$T" --room ab12cd --wait \\
         -p 'Deploy 1.4.0 to production?')" = approve ]; then ./deploy.sh; fi

package/lib/parser.js

@@ -61,7 +61,11 @@ export const parseArgs = makeParser({
     '-w': 'webhook', '--webhook': 'webhook',
     '--url': 'url',
     '--button-label': 'button_label',
+    '--location': 'location',
+    '--location-label': 'location_label',
+    '--location-address': 'location_address',
     '--require-ack': 'require_ack',
+    '--urgent': 'urgent',
     '--ack-timeout': 'ack_timeout',
     '--attach': 'attach',
     '--token': 'token',
@@ -70,7 +74,7 @@ export const parseArgs = makeParser({
     '--json': 'json',
     '-h': 'help', '--help': 'help',
   },
-  booleans: ['require_ack', 'json', 'help'],
+  booleans: ['require_ack', 'urgent', 'json', 'help'],
   repeatable: ['attach'],
 });
 
@@ -159,6 +163,9 @@ export const parseLiveArgs = makeParser({
     '-a': 'action', '--action': 'action',
     '-d': 'data', '--data': 'data',
     '--require-ack': 'require_ack',
+    // No --urgent here on purpose. A STREAM starts time-sensitive via
+    // `--category alert` (fixed at creation); the live-status endpoint does not
+    // accept `is_urgent`, so the flag would parse and then be silently dropped.
     '--ack-timeout': 'ack_timeout',
     '-w': 'webhook', '--webhook': 'webhook',
     '--token': 'token',

package/lib/util.js

@@ -39,7 +39,8 @@ export function stripControlChars(value) {
 
 export function truncate(value, max) {
   const str = String(value ?? '');
-  return str.length <= max ? str : `${str.slice(0, max - 1)}…`;
+  const characters = Array.from(str);
+  return characters.length <= max ? str : `${characters.slice(0, max - 1).join('')}…`;
 }
 
 /**
@@ -51,8 +52,11 @@ export function truncate(value, max) {
  * it is, with the limit and the actual length named.
  */
 export function requireMaxLength(value, max, flag) {
-  if (typeof value === 'string' && value.length > max) {
-    fail(`${flag} must be at most ${max} characters (got ${value.length})`, EXIT.USAGE);
+  if (typeof value === 'string') {
+    const length = Array.from(value).length;
+    if (length > max) {
+      fail(`${flag} must be at most ${max} characters (got ${length})`, EXIT.USAGE);
+    }
   }
 }
 

package/package.json

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