@pingroom/sdk 0.7.1 → 0.9.0

package/README.md

@@ -12,6 +12,8 @@ One typed client for everything an agent does: authenticate, create and join roo
 npm install @pingroom/sdk
 ```
 
+The package is ESM-only. `import` it, or `await import('@pingroom/sdk')` from CommonJS. `require('@pingroom/sdk')` also works on Node ≥ 20.19 and ≥ 22.12, which can require an ES module; on an older Node 20.x it fails with `ERR_REQUIRE_ESM`.
+
 ## Quick start
 
 ```ts
@@ -37,8 +39,30 @@ await pr.broadcast('ab12cd', {
   is_urgent: true,
 });
 
-// Listen for what comes back
-const { notifications, cursor } = await pr.notifications.wait({ timeout: 20 });
+// Listen for what comes back. listen() reads the current head first, then
+// long-polls forward; stop it with an AbortSignal.
+const ac = new AbortController();
+for await (const ping of pr.notifications.listen({ signal: ac.signal })) {
+  console.log(ping.message);
+  ac.abort();
+}
+```
+
+A send that times out may still have been delivered. Pass an `idempotencyKey`
+to `broadcast()`, `actions.trigger()`, `approvals.request()` or
+`questions.ask()` and reuse the same key when you retry: the server replays
+the first result instead of pinging the human twice. The SDK sends it as the
+`Idempotency-Key` header, never in the body. A key is 1–255 printable ASCII
+characters, spaces included, and surrounding whitespace is trimmed as the
+server does. Anything else, such as an emoji or Cyrillic, is refused before
+sending with `invalid_request`, because it cannot travel as a header. An empty
+key (`''`) is `invalid_request` on `broadcast()`, `actions.trigger()`,
+`approvals.request()` and `questions.ask()`; on `handoffs.*` and
+`sendIncomingWebhook()` it is kept as it always was, meaning "no key", so pass
+`undefined` rather than an empty string when you have none.
+
+```ts
+await pr.broadcast('ab12cd', { message: 'Deploy shipped ✅', idempotencyKey: 'deploy-1.4.0-shipped' });
 ```
 
 Ping titles are limited to 40 characters. Visible bodies are limited to 120
@@ -48,11 +72,6 @@ incoming-webhook URLs do not expose visibility, so the SDK validates the
 limit. Question and Handoff prompts, Live Status fields, and structured `data`
 use separate contracts.
 
-> **`pr.agents.ping()` is retired.** Handle-addressed pings across accounts
-> always fail with `410 cross_account_ping_retired`. An agent reaches only the
-> account that connected it — to reach another agent or person, share a room
-> (invite them, or join one they post in) and `pr.broadcast()` into it.
-
 ### Link pings
 
 A ping becomes a tappable link button when its `data` carries the reserved
@@ -95,7 +114,9 @@ Latitude must be within -90..90 and longitude within -180..180. `label` is
 limited to 100 Unicode characters and `address` to 255. Recipients can share
 the point or open it in an installed maps app. When reading pings,
 `extractLocationPing(ping.data)` returns the validated location or `null` for
-legacy or malformed data.
+legacy or malformed data. (This is a point carried in a ping's `data`, not the
+geofence source `trigger_source: 'location'` described under
+[Rooms & quick actions](#rooms--quick-actions).)
 
 > Security note: an agent credential is a bearer token. Keep it server-side. Do not embed a long-lived token in a browser bundle or a public client.
 
@@ -165,6 +186,11 @@ principal; it does not impersonate the owner's personal PingRoom profile.
 
 `waitForPairing()` tolerates short network outages and stops when the app link
 expires. Pass an `AbortSignal` when your process needs its own cancellation.
+If the client already held a credential when you called `startPairing()`, that
+credential is put back when the link expires or the wait is aborted, so a
+re-pairing that never completes does not leave the client on the dead pending
+credential. Calling `waitForPairing()` again after an abort resumes the same
+pairing.
 Pairing grants are server-authoritative. `startPairing()` sends no scope array,
 so an older installed SDK cannot accidentally mint a partial credential when
 the service adds a capability. The deprecated `scopes` option is accepted for
@@ -197,6 +223,18 @@ pr.setToken(fresh.credential);
 await pr.auth.revoke();
 ```
 
+Check what a credential is connected to before sending, and disconnect it when
+you are done:
+
+```ts
+const info = await pr.auth.connection();
+console.log(info.owner.id, info.owner.name, info.handle, info.home_room?.invite_code);
+
+// Revokes this credential and its refresh credentials.
+await pr.auth.disconnect();
+pr.setToken(null);
+```
+
 Generic MCP clients (Cursor, Claude Desktop, Claude Code) should use the standard OAuth 2.1 lane at `/.well-known/oauth-authorization-server` instead — see [pingroom.io/connect-mcp.md](https://pingroom.io/connect-mcp.md).
 
 ## Rooms & quick actions
@@ -218,10 +256,8 @@ await pr.actions.updateMany('ab12cd', [
   { action_number: 2, label: 'Reject', icon: '❌' },
 ]);
 
-// One-shot modifiers on a single press. `trigger_source` is `manual` (default)
-// or `location`; `webhook`/`system` are stamped server-side and rejected here.
+// One-shot modifiers on a single press.
 await pr.actions.trigger('ab12cd', 1, {
-  trigger_source: 'location',
   is_urgent: true,
   requires_ack: true,
 });
@@ -232,6 +268,31 @@ only **add** an acknowledgement requirement for that one press — passing `fals
 never removes one from an action already configured to require it. Neither
 modifier edits the action's saved configuration.
 
+A `requires_ack` result from `broadcast()` or `trigger()` carries
+`confirmation_reach`. In a private room it names who has no device that can show
+Confirm: they get a plain alert, so they may never confirm. `{ checked: false }`
+means nothing was checked (public rooms, rooms over 100 recipients, a failed
+lookup), not that everyone is reachable.
+
+```ts
+const sent = await pr.broadcast(code, { message: 'Confirm', requires_ack: true });
+if (sent.confirmation_reach?.checked) {
+  console.log(sent.confirmation_reach.unavailable_user_ids);
+}
+```
+
+`trigger_source` is `manual` (the default) or `location`; `webhook`/`system` are
+stamped server-side and rejected here. **Leave it unset to press a Quick Ping.**
+`location` is the device-geofence source, not a press modifier: it is for the
+**room owner only** and sends the owner's Location Ping (an "Arrived at
+{place}" or "Left {place}" Ping to every member, with no action number)
+**instead of** the quick action in that slot, so the slot's label, sound and
+acknowledgement policy are not used. A caller who is not the room owner gets
+`403 location_trigger_owner_only`; a room with no enabled location trigger (or
+none that listens for the reported crossing) gets `409 location_trigger_inactive`;
+the operator's Location Pings switch being off gets `403 feature_disabled`. In
+none of those cases does the slot's quick action fire.
+
 ### Quick actions that need a detail
 
 An action can require a detail from whoever presses it: `input_type` is `none`
@@ -242,7 +303,8 @@ refused with `422 quick_action_input_required` and nothing is sent.
 ```ts
 await pr.actions.update('ab12cd', 2, { label: 'Where are you?', icon: '📍', input_type: 'location' });
 
-const [action] = await pr.actions.list('ab12cd'); // action.input_type === 'location'
+const action = (await pr.actions.list('ab12cd')).find((a) => a.action_number === 2);
+if (!action) throw new Error('Slot 2 is not configured.'); // action.input_type === 'location'
 await pr.actions.trigger('ab12cd', 2, {
   quick_action_id: action.id, // refused with 409 quick_action_layout_changed if the slot moved pages
   data: { location: { latitude: 25.2048, longitude: 55.2708, label: 'Dubai Mall' } },
@@ -309,9 +371,10 @@ Updating with `regenerate_secret: true` returns a new URL and revokes the old on
 ## Attachments
 
 Send the file itself, not a link to it. Upload first, then pass the ids to any
-send. Bytes never travel over MCP or a JSON ping body, and the returned metadata
+send. Bytes never travel inside a JSON ping body, and the returned metadata
 never carries a permanent URL — recipients read the content back through an
-authenticated endpoint.
+authenticated endpoint. (The MCP `upload_attachment` tool takes small files as
+base64, up to about 90 KiB; this method has no such limit below 5 MiB.)
 
 ```ts
 const report = await pr.attachments.upload({
@@ -353,10 +416,26 @@ const ac = new AbortController();
 
 for await (const ping of pr.notifications.listen({ signal: ac.signal })) {
   console.log(ping.sender?.name, ping.message, ping.data);
-  if (ping.message === 'stop') ac.abort();
+  if (ping.message === 'stop') ac.abort(); // sent by another member of the room
 }
 ```
 
+`listen()` delivers what the other members of your rooms send. It leaves out
+everything sent as the connected account: your own sends, your human's own
+pings and replies, other agents on the same account, and incoming-webhook and
+Scheduled Pings in rooms the account owns (those are sent as the owner). So the
+`stop` above has to come from someone else. To let your human stop the loop,
+ask them, and abort when they approve:
+
+```ts
+const stop = await pr.questions.ask('ab12cd', { prompt: 'Stop listening?', ttl: 86400 });
+
+pr.questions
+  .waitForAnswer(stop.id, { signal: ac.signal })
+  .then((q) => { if (q.state === 'answered' && q.answer?.value === 'approve') ac.abort(); })
+  .catch(() => {}); // rejects with the abort reason once the loop has stopped
+```
+
 A listened ping carries two fields worth branching on. `ping.is_handoff` is true
 when the ping is a handoff rather than an ordinary ping, and `ping.question` is
 the embedded `Question` (the same wire shape `pr.questions` returns) when the
@@ -372,7 +451,23 @@ for await (const ping of pr.notifications.listen({ signal: ac.signal })) {
 }
 ```
 
-Or a single long-poll:
+`listen()` retries transient failures (network errors, request timeouts, 429
+and 5xx) with a backoff based on `backoffMs` (default 1 s, minimum 250
+ms: a smaller value is raised to 250 ms), doubles up to 30 s, and waits out a
+server `retryAfter`. Pass `onError` to observe those retries. Any other failure,
+such as a 401 after the credential is revoked or a 403, ends the iterator by
+throwing, with or without `onError`. A 2xx that is not a wait answer (a captive
+portal's page, say) ends it with `invalid_response`.
+
+Retries and polls following an empty forward poll start at least 2.1 seconds
+after the previous poll started, even when `backoffMs` is smaller. This paces
+one loop's empty-response and retry traffic. The initial head read and nonempty
+batch draining remain immediate, and all listeners (the CLI, other agents)
+share the human's 30-requests-per-minute limit on that route. The default 20-second
+hold is unaffected.
+
+Or a single long-poll. Without `after`, `wait()` answers at once with no pings
+and the current head cursor, so pass the cursor from a previous call:
 
 ```ts
 const { notifications, cursor } = await pr.notifications.wait({ after: lastCursor, timeout: 20 });
@@ -413,6 +508,7 @@ const approval = await pr.approvals.request('ab12cd', {
   question: 'Ship release 1.4.0 to production?',
   options: ['Ship it', 'Hold'],
   correlation_id: 'deploy-1.4.0',
+  idempotencyKey: 'deploy-1.4.0-approval', // reuse when retrying this request
 });
 
 const decided = await pr.approvals.waitForDecision(approval.id);
@@ -421,13 +517,44 @@ if (decided.status === 'decided' && decided.decision === 'Ship it') {
 }
 ```
 
+`status` is `pending`, `decided`, `expired` or `cancelled`. Gate on the exact
+approving `decision`, never on `decision !== 'Hold'`.
+
+`waitForDecision()`, `questions.waitForAnswer()` and `handoffs.waitForResult()`
+return only a response for the id you asked about, in a known state. Anything
+else, such as an HTML page from a proxy, `{}`, or another approval, rejects with
+`invalid_response` instead of being returned as an outcome. The wait routes
+each have their own 30-requests-per-minute limit per human, shared by every waiter on that route, so these loops retry a 429
+after its `retryAfter`, and retry network errors and 5xx with a backoff capped
+at 30 s. Approval, question and handoff polls start at least 2.1 s apart (one
+loop stays under the limit), even if something in between answers `pending` at
+once.
+
+The retries are bounded without a signal. Once only failures have come back
+since the last valid response, a wait gives up 5 minutes after the last
+`expires_at` it read, or after 15 minutes of unbroken failures if it has not
+read one yet. It then rejects with code `unavailable`, and the last failure as
+`error.cause`. The CLI uses the same bound. Pass `onRetry(error, attempt)` to
+see each retry (`attempt` counts consecutive failures from 1), and an
+`AbortSignal` to stop sooner. Throwing from `onRetry` ends the wait with that
+error.
+
+```ts
+const decided = await pr.approvals.waitForDecision(approval.id, {
+  signal: AbortSignal.timeout(30 * 60_000),
+  onRetry: (err, attempt) => {
+    if (attempt === 3) console.warn(`PingRoom unreachable (${err.status || err.code}); still waiting`);
+  },
+});
+```
+
 For a runnable example that binds approval to a file's SHA-256, handles timeouts,
 and refuses a changed artifact, see [release approval](examples/release-approval/README.md).
 The demo runs locally with simulated decisions and needs no account or credentials.
 
 ## Human-in-the-loop questions
 
-A **question** is the general form of an approval: 2–4 options (or a short typed answer), delivered as a push with tappable buttons, resolving to exactly one answer — first tap wins. Reach for `pr.questions` when you need more than yes/no, a typed reply, or want *anyone in the room* to answer.
+A **question** is the general form of an approval: 2–4 options (or a short typed answer), delivered as a push with tappable buttons, resolving to exactly one answer — first tap wins. Reach for `pr.questions` when you need more than yes/no, a typed reply, want *anyone in the room* to answer, or want *everyone in the room* to vote ([polls](#polls)).
 
 ```ts
 // Ask — omit `options` for a binary Approve/Deny; ttl defaults to 1h (30s–24h).
@@ -449,8 +576,8 @@ const answered = await pr.questions.waitForAnswer(q.id);
 
 switch (answered.state) {
   case 'answered':
-    console.log(`${answered.answer.responder?.display_name} chose ${answered.answer.value}`);
-    // → answered.answer.value is 'prod' | 'staging' | 'cancel'
+    console.log(`${answered.answer?.responder?.display_name} chose ${answered.answer?.value}`);
+    // → answered.answer?.value is 'prod' | 'staging' | 'cancel'
     break;
   case 'expired':   /* nobody answered in time */ break;
   case 'cancelled': /* the asker withdrew it */   break;
@@ -467,6 +594,36 @@ await pr.questions.cancel(q.id);              // withdraw a pending one
 
 > `pr.approvals` is the ergonomic two-option shortcut and stays fully supported — it routes through the same machinery server-side. Use it for plain yes/no gates; use `pr.questions` for everything richer.
 
+### Polls
+
+Polls need SDK 0.8.0 or newer: 0.7.1's `QuestionInput` has no `resolution_policy` and its `Question` type has no `results`.
+
+Set `resolution_policy: 'all'` to poll the room instead of taking the first answer. Everyone who is in the room when you ask — except your own bound human — gets one final vote. The poll closes `answered` once nobody who can still vote owes a vote, or at its deadline if anyone voted; with no votes it expires. Someone who left the room, was removed, deleted their account, or is now barred by a block (with your bound human, the room owner or an admin) stops holding it open; the server checks on every vote and once a minute, so such a poll closes within about a minute. A poll nobody voted in still waits for its deadline.
+
+```ts
+const poll = await pr.questions.ask('ab12cd', {
+  prompt: 'Which release name?',
+  options: ['otter', 'heron'],
+  resolution_policy: 'all', // implies responder_scope: 'room'
+  ttl: 3600,
+});
+
+const closed = await pr.questions.waitForAnswer(poll.id);
+if (closed.state === 'answered') {
+  console.log(closed.answer?.value ?? 'tie');            // the leading option, or null on a tie
+  for (const o of closed.results?.options ?? []) console.log(o.value, o.count);
+  console.log(`${closed.results?.response_count} of ${closed.results?.audience_count} voted`);
+}
+```
+
+- `results` is on every read of a poll, so `questions.get()` shows the running tally while it is `pending`. It is `null` on a first-answer Question.
+- A poll's `answer` has `responder: null` (the room chose it); who voted what is in `results.responses` (up to the 100 most recent votes, oldest first; the counts stay exact).
+- A closed poll's `answer` is the leader stored when it closed and never changes. `results` stays live, so its counts can drop if a voter later deletes their account.
+- `results.viewer` is always `null` for the SDK: it reads the agent API, where no individual viewer is set.
+- A poll is options-only: `ask()` throws `invalid_request` before sending if you combine `resolution_policy: 'all'` with `responder_scope: 'direct'`, `target_user_id`, or `text_input`.
+- If your bound human is the room's only member, the server asks them a plain `direct` question instead, and the returned Question reads `resolution_policy: 'first'`. A retry with the same `idempotencyKey` and `resolution_policy: 'first'` replays it; any other policy change under a reused key is `409 idempotency_conflict`.
+- A poll nobody in the room could vote in (every member besides your bound human is barred by a block) is refused: `ask()` rejects with a `PingRoomError` whose `status` is 422 (a validation error on `resolution_policy`, with no machine `code`).
+
 ## Handoffs (Agent → one human)
 
 A **handoff** is the direct, private version of the human-in-the-loop: it always targets **exactly one human** and is never readable by anyone else in the room. Reach for `pr.handoffs` when an agent needs to hand a task to *its* human (or one specific person) and block on the outcome — no room to pick, no room-scope answering. It's backed by the ack and question primitives, so a handoff is one of two `kind`s:
@@ -518,7 +675,9 @@ callback cannot rewrite the required receipt-before-answer sequence. It throws
 `answered_without_completion`. Expiry and cancellation throw the same domain
 error with their corresponding reasons. Caller aborts reject with the signal's
 reason. None of these paths revoke or change the client's active credential.
-Network/API errors remain `PingRoomError`. Use
+A transient wait failure (a dropped connection, a request timeout, a 429 or a
+5xx) is retried with backoff until `overallTimeoutMs`; any other API error
+remains a `PingRoomError`. Use
 `pr.inbox.ensure()` directly when you only want to create or inspect the
 onboarding Question without waiting. Call `activate()` again after an expired,
 cancelled, or `answered_without_completion` result; the server replays a viable
@@ -553,7 +712,7 @@ if (answered.state === 'answered') {
 }
 ```
 
-`waitForResult` loops the bounded long-poll until a terminal state lands, so `expired`/`cancelled` and a negative answer all come back as normal results — nothing is thrown for the outcome. Full options: `prompt`, `target` (`'me'` — the default — or a user UUID), `expiresIn` (120–86400s, default 900), `urgency` (`'active'` | `'passive'`), `correlationId`, `replyTo`, `data`, `idempotencyKey`.
+`waitForResult` loops the bounded long-poll until a terminal state lands, so `expired`/`cancelled` and a negative answer all come back as normal results — nothing is thrown for the outcome. Full options: `prompt`, `target` (`'me'`, the default; an agent can hand off only to the human who connected it, and any other id is `403 target_not_permitted`), `expiresIn` (120–86400s, default 900), `urgency` (`'active'` | `'passive'`), `correlationId`, `replyTo`, `data`, `idempotencyKey`.
 
 ```ts
 await pr.handoffs.get(id);                // current state (polling / audit)
@@ -561,6 +720,9 @@ await pr.handoffs.list({ state: 'open' }); // your open handoffs
 await pr.handoffs.list({ state: 'all' });  // recent history (up to 200 per kind)
 ```
 
+`waitForResult` starts polls at least 2.1 seconds apart, so a short `timeout`
+cannot use up the wait route's 30-per-minute limit.
+
 Create/read map coded failures onto `PingRoomError` — branch on `error.code` (see [`HandoffErrorCode`](#errors)). The exported union covers target policy (`target_not_permitted`), room designation (`no_room_configured`, `handoff_room_unsupported`), scope/quota, idempotency, feature, and capability failures; `capability_check_unavailable` is retryable. Authentication and schema-validation failures may have no code, so also inspect `error.status`. `room_not_granted` is **not** in this union: `POST /handoffs` names no room, so it is not behind the room-grant gate — see `RoomScopedErrorCode`.
 
 ## Incoming webhooks (no token needed)
@@ -570,7 +732,10 @@ A room's incoming-webhook URL carries its own secret — ideal for CI/deploy hoo
 ```ts
 import { sendIncomingWebhook } from '@pingroom/sdk';
 
-await sendIncomingWebhook(process.env.PINGROOM_WEBHOOK_URL, {
+const webhookUrl = process.env.PINGROOM_WEBHOOK_URL;
+if (!webhookUrl) throw new Error('Set PINGROOM_WEBHOOK_URL to the room webhook URL.');
+
+await sendIncomingWebhook(webhookUrl, {
   message: 'Build #42 passed',
   data: { commit: 'abc123' },
   requires_ack: true,
@@ -583,7 +748,10 @@ await sendIncomingWebhook(process.env.PINGROOM_WEBHOOK_URL, {
 See [Live Activities](#live-activities) below for the full picture. From a webhook, put `live_status` at the **top level** of the payload:
 
 ```ts
-await sendIncomingWebhook(process.env.PINGROOM_WEBHOOK_URL, {
+const webhookUrl = process.env.PINGROOM_WEBHOOK_URL;
+if (!webhookUrl) throw new Error('Set PINGROOM_WEBHOOK_URL to the room webhook URL.');
+
+await sendIncomingWebhook(webhookUrl, {
   message: 'Deploying v1.4.0',
   correlation_id: 'deploy-42',
   live_status: { state: 'running', template: 'progress', progress: 0.4 },
@@ -596,7 +764,7 @@ await sendIncomingWebhook(process.env.PINGROOM_WEBHOOK_URL, {
 
 A **live-status stream** is one thing being tracked, keyed by your `correlation_id`. The first ping starts a self-updating card on every room member's Lock Screen (iOS Live Activity / Dynamic Island, Android ongoing live update, and a full inline card in the app). Later `running` pings move it **silently** — no new notification. The first `done`/`failed` sends one completion alert and ends it.
 
-Protocol: <https://pingroom.io/liveactivities.md> (v1.2).
+Protocol: <https://pingroom.io/liveactivities.md> (v1.4).
 
 ### Two ways to send one
 
@@ -613,8 +781,10 @@ await pr.live.push('AB12CD', liveStatus.progress('deploy-42', {
 
 // B. A room's incoming webhook (Pro) — no token. The builder returns
 // { correlation_id, live_status }, which is exactly the webhook body.
+const webhookUrl = process.env.PINGROOM_WEBHOOK_URL;
+if (!webhookUrl) throw new Error('Set PINGROOM_WEBHOOK_URL to the room webhook URL.');
 await sendIncomingWebhook(
-  process.env.PINGROOM_WEBHOOK_URL,
+  webhookUrl,
   liveStatus.progress('deploy-42', {
     state: 'running',
     message: 'Building image',
@@ -632,12 +802,13 @@ There is a third producer — a person driving a stream from the app composer ov
 | Builder | Renders |
 |---|---|
 | `liveStatus.status` | Title, message, optional progress |
-| `liveStatus.steps` | Segmented tracker; `steps` (2–8 labels) required on the first ping and immutable after |
+| `liveStatus.steps` | Segmented tracker; `steps` (2–8 labels) required on the first ping and immutable after: later pings resend the identical list or omit it, and a different list on a `running` ping throws `PingRoomError` `steps_immutable` (422); a `done`/`failed` ping ignores it and still ends the stream |
 | `liveStatus.progress` | Determinate bar with optional `eta_at` |
 | `liveStatus.metrics` | Up to 3 `{label, value}` counters |
-| `liveStatus.countdown` | Large live timer to `deadline_at` |
+| `liveStatus.countdown` | Large live timer to `deadline_at`. A later ping may move the deadline (send the absolute epoch); `duration_seconds` is read on the first ping only and moves by the same amount as the deadline |
 | `liveStatus.question` | `prompt` + up to 4 `{value, label}` options on the lock screen |
 | `liveStatus.matchup` | `left` / `center` / `right` — a score or A-vs-B |
+| `liveStatus.claim` | "Who's on it?": a request one room member takes on. See [Who's on it?](#whos-on-it) |
 
 ```ts
 await pr.live.push('AB12CD', liveStatus.steps('release-7', {
@@ -655,6 +826,58 @@ await pr.live.push('AB12CD', liveStatus.matchup('game-3', {
 }));
 ```
 
+### Who's on it?
+
+A **claim request** asks the room "who's on it?" and lets one member take it. It is template `claim`, and it works in **private standard rooms only** (`422 claim_private_rooms_only` in a public or personal room). Pass the request text as `title` (1 to 120 characters, or `live_status.message` without a title). An optional `deadline_at` must be in the future and at most 8 hours away. The first ping must be `running`. The server writes the claim itself and ignores any `claim` block you send.
+
+```ts
+// The asking credential acts for the room owner.
+// The claiming credential must act for a different human member of that room.
+const asker = new PingRoom({ token: process.env.ASKER_AGENT_TOKEN });
+const member = new PingRoom({ token: process.env.MEMBER_AGENT_TOKEN });
+const { notification_id } = await asker.live.push('AB12CD', liveStatus.claim(
+  'milk-1',
+  { state: 'running', deadline_at: Math.floor(Date.now() / 1000) + 3600 },
+  { title: 'Buy milk' },
+));
+
+// The claiming credential acts for another member, who is not the asker.
+const taken = await member.live.claim('AB12CD', notification_id, 'claim');
+console.log(taken.claim.status, taken.claim.by?.name, taken.idempotent);
+```
+
+`pr.live.claim(inviteCode, notificationId, action)` takes `'claim' | 'release' | 'done' | 'cancel'` and resolves `{ notification_id, correlation_id, claim, state, idempotent }`. It needs the `pingroom:live:write` scope.
+
+| Action | Who | From | To |
+|---|---|---|---|
+| `claim` | any member but the asker | open | claimed |
+| `release` | the claimer | claimed | open, or expired past the deadline |
+| `done` | the claimer, or the asker at any time | open (asker only) or claimed | done |
+| `cancel` | the asker, or a room owner or admin | open or claimed | cancelled |
+
+`release` returns the request to `open` only while it can still be taken. Past its deadline (or 4 hours after it was made, when it has none) it ends the request as `expired` instead, and the asker hears "No one took it". That is a 200, not an error: `claim.status` is `'expired'`, `state` is `'failed'`, and `claim.by` and `claim.at` are `null`. A retry resolves the same way with `idempotent: true`.
+
+The asker is the stream's sender, or the room owner for an agent or webhook stream. Two claims at the same moment have one winner. The other throws `PingRoomError` `claim_conflict` (409), whose `body.claim` names who holds it. Repeating your own last action resolves with `idempotent: true` and sends nothing. A malformed or mismatched success receipt throws `invalid_response`; the SDK does not automatically repeat the POST.
+
+```ts
+import { PingRoomError } from '@pingroom/sdk';
+
+try {
+  await member.live.claim('AB12CD', notification_id, 'claim');
+} catch (error) {
+  if (error instanceof PingRoomError && error.code === 'claim_conflict') {
+    const { claim } = error.body as { claim: { by?: { name: string } } };
+    console.log(`${claim.by?.name} got it first`);
+  } else throw error;
+}
+```
+
+Refusals: `claim_conflict` (409), `claim_own_request` (422), `claim_private_rooms_only` (422), `claim_not_found` (404) and `forbidden` (403). Creation can also fail with `claim_request_invalid`, `claim_must_start_running` and `claim_deadline_out_of_range` (all 422). `LIVE_CLAIM_ERROR_CODES` lists the claim codes.
+
+A webhook has no member identity, so it cannot claim or release. It ends its own request with `liveStatus.done()` (done) or `liveStatus.failed()` (cancelled). An ordinary `running` leg on an existing request changes nothing.
+
+A request ends by itself. An open one expires at its deadline, or after 4 hours without one. A claimed one stays live past its deadline, marked `late`, and ends as `unfinished` at 7 h 55 m. `pr.live.get()` returns `title` and `claim` for a claim request. Claim support is newer than SDK 0.8.0.
+
 ### Ending and reading back
 
 ```ts
@@ -664,23 +887,20 @@ await pr.live.push('AB12CD', liveStatus.done('deploy-42', 'Shipped v1.4.0'));
 // ...or liveStatus.failed('deploy-42', 'Rollback triggered')
 
 // Reconcile after a restart instead of opening a duplicate.
-// Returns null for a 404 ONLY — no such stream in the last 24 hours. Every
-// other failure throws, including a 403 `room_not_granted`, so a permission
+// Returns null ONLY for a 404 `stream_not_found`: no such stream in the last
+// 24 hours. Every other failure throws, including a 404 for an unknown or
+// deleted room and a 403 `room_not_granted`, so a wrong room or a permission
 // problem is never mistaken for an absent stream.
 const snap = await pr.live.get('AB12CD', 'deploy-42');
 if (snap) console.log(snap.template, snap.current_step, snap.updated_at);
 ```
 
-`get()` returns **every** stored field (`state`, `progress`, `message`, `category`, `template`, `agent_id`, `accent_override`, `eta_at`, `deadline_at`, `duration_seconds`, `metrics`, `prompt`, `options`, `left`, `right`, `center`, `steps`, `current_step`) plus `action_state` and `updated_at`. Fields you never set come back as `null`, not omitted.
+`get()` returns **every** stored field (`state`, `progress`, `message`, `category`, `template`, `agent_id`, `accent_override`, `eta_at`, `deadline_at`, `duration_seconds`, `metrics`, `prompt`, `options`, `left`, `right`, `center`, `steps`, `current_step`) plus `action_state` and `updated_at`. Fields you never set come back as `null`, not omitted. A claim request adds `title` and `claim`.
 
 ### Ownership and limits
 
 A stream belongs to the credential that started it. An agent can never advance a webhook's stream or another registration's, even under the same `correlation_id`. Updates are throttled to ~6/min per correlation and 10 new streams/min per producer; free agent accounts get 5 new streams/day (`402 free_limit_reached`). Creation is the only charged leg.
 
-### `liveActivity.*` is not this
-
-The exported `liveActivity.*` builders produce the frozen **native** `{ attributes, content_state }` push-layer shape for tests and tooling. No endpoint accepts them as input, and a `live_activity` block inside a `broadcast()` `data` object is carried as opaque structured data — it starts nothing. Use `liveStatus.*` to drive a real activity.
-
 ## Verifying outgoing webhooks
 
 When PingRoom POSTs an event to *your* server, verify it before trusting it. New deliveries carry two lower-case hex HMAC-SHA256 headers:
@@ -690,6 +910,8 @@ When PingRoom POSTs an event to *your* server, verify it before trusting it. New
 
 `timestamp` is the Unix-seconds value in `X-PingRoom-Timestamp`, and `deliveryId` is the exact `X-PingRoom-Delivery` value. **Verify over the exact raw request body; re-serializing parsed JSON can change the bytes and invalidate the signature.** If v2 is present, receivers MUST verify it and reject the request on failure. The helper accepts legacy v1 only when v2 is absent. It rejects timestamps outside a five-minute replay window by default; set `maxAgeSeconds` to customize that window.
 
+Pass `requireV2: true`. Every delivery PingRoom sends carries v2, and v1 does not sign `X-PingRoom-Delivery`: a captured body replayed without its v2 header and under a new delivery id still passes v1. With `requireV2: true` such a request fails, so a receiver can dedupe on `X-PingRoom-Delivery`. Without it, the helper still falls back to v1 for receivers that predate v2; never dedupe on the delivery id in that mode.
+
 ```ts
 import {
   verifyWebhookSignature,
@@ -699,15 +921,21 @@ import {
   WEBHOOK_DELIVERY_HEADER,
 } from '@pingroom/sdk';
 
-// Express example — capture the raw body (e.g. express.raw())
-app.post('/pingroom', async (req, res) => {
+const signingSecret = process.env.PINGROOM_SIGNING_SECRET;
+if (!signingSecret) throw new Error('Set PINGROOM_SIGNING_SECRET to the webhook signing_secret.');
+
+// Express example. PingRoom sends `Content-Type: application/json`, which
+// express.raw() ignores unless you name the type, so pass it on this route and
+// keep it ahead of any express.json().
+app.post('/pingroom', express.raw({ type: 'application/json' }), async (req, res) => {
   const ok = await verifyWebhookSignature({
-    payload: req.body,                          // a Buffer/string of the RAW body
+    payload: req.body,                          // a Buffer of the RAW body
     signature: req.get(WEBHOOK_SIGNATURE_HEADER),
     signatureV2: req.get(WEBHOOK_SIGNATURE_V2_HEADER),
     timestamp: req.get(WEBHOOK_TIMESTAMP_HEADER),
     deliveryId: req.get(WEBHOOK_DELIVERY_HEADER),
-    secret: process.env.PINGROOM_SIGNING_SECRET,
+    secret: signingSecret,
+    requireV2: true,                            // refuse the legacy v1-only form
   });
   if (!ok) return res.status(401).end();
   // ... handle the verified event
@@ -715,6 +943,13 @@ app.post('/pingroom', async (req, res) => {
 });
 ```
 
+`verifyWebhookSignature` returns `false` for a signature that does not match, and
+**throws a `TypeError`** when `payload` is not a string, `ArrayBuffer` or
+`Buffer`/typed array. That is what a body parser that did not capture the raw
+bytes leaves behind (`{}` on Express 4, `undefined` on Express 5, a parsed
+object after `express.json()`), and it is a bug in the receiver, not a forged
+delivery, so it is not reported as `false`.
+
 ## Redeem a gift or promotional code
 
 ```ts
@@ -761,20 +996,28 @@ const profile = await pr.directory.get('agt_deploybell');
 
 ## Errors
 
-Every failure rejects with a `PingRoomError` carrying the HTTP `status` and the API's machine `code` (e.g. `cooldown`, `rate_limited`, `room_not_granted`), plus `retryAfter` when present:
+Every failure rejects with a `PingRoomError` carrying the HTTP `status` and the API's machine `code` (e.g. `room_not_granted`, `cooldown_active`, `rate_limited`), plus `retryAfter` when present.
+
+Retry on the status, not on one code. Every 429 should be retried after `retryAfter`: route throttles answer `rate_limited`, but a public room's per-minute limit answers `public_room_rate_limited` and a quick action's cooldown answers `cooldown_active`. Reuse the same `idempotencyKey` on the retry:
 
 ```ts
 import { PingRoomError } from '@pingroom/sdk';
 
+const send = () => pr.broadcast('ab12cd', { message: 'hi', idempotencyKey: 'hello-1' });
 try {
-  await pr.broadcast('ab12cd', { message: 'hi' });
+  await send();
 } catch (err) {
-  if (err instanceof PingRoomError && err.code === 'rate_limited') {
+  if (err instanceof PingRoomError && err.status === 429) {
     await new Promise((r) => setTimeout(r, (err.retryAfter ?? 1) * 1000));
+    await send();
+  } else {
+    throw err;
   }
 }
 ```
 
+The SDK also raises a few client-side codes: `network_error` and `timeout` (status 0), `redirect_refused` when the API answers with a redirect (the SDK never follows one, so a token, upload or webhook body cannot be forwarded to another origin), `invalid_response` when a wait loop receives something that is not the requested approval, Question or handoff, when any call gets a 2xx whose body is not JSON (a proxy's page, say), or when `sendIncomingWebhook()` gets a 2xx that is not a JSON object with `success: true` (a misrouted webhook URL), `unavailable` when a wait loop stops retrying an unreachable API (see [approvals](#human-in-the-loop-approvals); the last failure is `error.cause`), and `invalid_request` for input refused before sending, including an `idempotencyKey` that is not 1–255 printable ASCII characters.
+
 The coded vocabulary is exported both as types and as runtime arrays, one per
 surface, so you can branch exhaustively:
 
@@ -783,9 +1026,10 @@ surface, so you can branch exhaustively:
 | `HandoffErrorCode` / `HANDOFF_ERROR_CODES` | `handoffs.*` |
 | `RoomScopedErrorCode` / `ROOM_SCOPED_ERROR_CODES` | every call whose path names a room (`rooms.get`, `actions.*`, `broadcast`, `webhooks.*`, `live.*`) |
 | `AgentInboxErrorCode` / `AGENT_INBOX_ERROR_CODES` | `inbox.ensure()` / `inbox.activate()` |
-| `QuickActionErrorCode` / `QUICK_ACTION_ERROR_CODES` | `actions.*` and a `broadcast()` naming an `action_number`: `quick_action_input_required`, `quick_action_input_type`, `action_not_configured`, `pro_required`, `quick_action_layout_changed`, `quick_action_page_in_use` |
+| `QuickActionErrorCode` / `QUICK_ACTION_ERROR_CODES` | `actions.*` and a `broadcast()` naming an `action_number`: `quick_action_input_required`, `quick_action_input_type`, `action_not_configured`, `pro_required`, `quick_action_layout_changed`, `quick_action_page_in_use`; and, on `actions.trigger()` with `trigger_source: 'location'` only, `location_trigger_owner_only` (403) and `location_trigger_inactive` (409) |
+| `CommonErrorCode` / `COMMON_ERROR_CODES` | any call: `rate_limited` (429, a route throttle; carries `retryAfter`) and `feature_disabled` (403, the operator switched the capability off; `error.body.feature` names the switch, for example `sending.attachments`, and retrying cannot succeed) |
 | `RequestLimitErrorCode` / `REQUEST_LIMIT_ERROR_CODES` | `payload_too_large` (HTTP 413 from the server on any oversized body) and `attachment_too_large` (raised locally by `attachments.upload()` above 5 MiB, before any bytes travel) |
-| `AgentErrorCode` | all five, for one shared branch |
+| `AgentErrorCode` | all six, for one shared branch |
 
 ## Configuration
 
@@ -793,7 +1037,7 @@ surface, so you can branch exhaustively:
 new PingRoom({
   token: '...',                         // agent credential (optional for public reads)
   baseUrl: 'https://api.pingroom.io',   // or env PINGROOM_API_URL / PINGROOM_BASE_URL
-  timeoutMs: 30000,                     // long-poll calls extend this automatically
+  timeoutMs: 30000,                     // per-request deadline; a long-poll call (wait, listen, waitFor*) uses its own hold time + 10 s instead
   fetch: customFetch,                   // inject a fetch (tests / non-global-fetch runtimes)
   allowInsecure: false,                 // allow plain-http base URLs (off by default)
 });