@pingroom/sdk 0.8.0 → 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
@@ -53,7 +55,11 @@ 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.
+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' });
@@ -66,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
@@ -113,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.
 
@@ -183,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
@@ -248,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,
 });
@@ -262,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`
@@ -272,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' } },
@@ -339,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({
@@ -419,10 +452,19 @@ for await (const ping of pr.notifications.listen({ signal: ac.signal })) {
 ```
 
 `listen()` retries transient failures (network errors, request timeouts, 429
-and 5xx) with a backoff that starts at `backoffMs` (default 1 s), 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`.
+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:
@@ -482,10 +524,11 @@ approving `decision`, never on `decision !== 'Hold'`.
 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
-share a 30-requests-per-minute limit per human, so these loops retry a 429
+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 and question polls start at least 1 s apart, and handoff
-polls 2.1 s apart, even if something in between answers `pending` at once.
+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
@@ -533,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;
@@ -632,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
@@ -687,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,
@@ -700,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 },
@@ -713,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
 
@@ -730,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',
@@ -749,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', {
@@ -772,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
@@ -789,16 +895,12 @@ 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:
@@ -822,10 +924,12 @@ import {
 const signingSecret = process.env.PINGROOM_SIGNING_SECRET;
 if (!signingSecret) throw new Error('Set PINGROOM_SIGNING_SECRET to the webhook signing_secret.');
 
-// Express example — capture the raw body (e.g. express.raw())
-app.post('/pingroom', async (req, res) => {
+// 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),
@@ -839,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
@@ -905,7 +1016,7 @@ try {
 }
 ```
 
-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, `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 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:
@@ -915,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
 
@@ -925,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)
 });