@pingroom/sdk 0.7.1 → 0.9.0

package/src/namespaces/inbox.ts

@@ -0,0 +1,253 @@
+// `pr.inbox`: setting up and activating the human's Agent Inbox.
+
+import { PingRoomActivationIncompleteError, PingRoomError } from '../errors.js';
+import type { HttpClient } from '../http.js';
+import { combineSignals, sleep, throwIfAborted } from '../internal/async.js';
+import { isTransientError, transientDelayMs } from '../internal/retry.js';
+import type {
+  AgentInboxEnsureResult,
+  AgentInboxActivateInput,
+  AgentInboxActivationQuestion,
+  AgentInboxActivationResult,
+  AgentInboxEnsureInput,
+  Handoff,
+} from '../types.js';
+import {
+  MIN_HANDOFF_POLL_INTERVAL_MS,
+  enc,
+  dropUndefined,
+  waitTimeoutMs,
+} from '../internal/request.js';
+import { isRecord, isNonEmptyString, isNullableString } from '../internal/validate.js';
+
+const DEFAULT_INBOX_ACTIVATION_TIMEOUT_MS = 120_000;
+
+function invalidInboxResponse(message: string, body: Record<string, unknown> = {}): never {
+  throw new PingRoomError(message, { code: 'inbox_invalid_response', body });
+}
+
+function validateInboxEnsure(value: unknown): AgentInboxEnsureResult {
+  if (!isRecord(value) || value['onboarded'] !== true || typeof value['replayed'] !== 'boolean') {
+    return invalidInboxResponse('PingRoom returned an invalid Agent Inbox ensure response.');
+  }
+
+  const room = value['room'];
+  const question = value['question'];
+  if (
+    !isRecord(room)
+    || !isNonEmptyString(room['id'])
+    || typeof room['name'] !== 'string'
+    || !isNonEmptyString(room['invite_code'])
+    || typeof room['is_agent_inbox'] !== 'boolean'
+    || !isRecord(question)
+    || !isNonEmptyString(question['id'])
+    || question['kind'] !== 'question'
+    || !isNonEmptyString(question['prompt'])
+    || !Array.isArray(question['options'])
+    || question['options'].some((option) => (
+      !isRecord(option)
+      || !isNonEmptyString(option['value'])
+      || !isNonEmptyString(option['label'])
+    ))
+    || (question['state'] !== 'pending'
+      && question['state'] !== 'answered'
+      && question['state'] !== 'expired'
+      && question['state'] !== 'cancelled')
+    || !isNullableString(question['expires_at'])
+    || !isNullableString(question['created_at'])
+  ) {
+    return invalidInboxResponse('PingRoom returned an incomplete Agent Inbox ensure response.');
+  }
+
+  return value as unknown as AgentInboxEnsureResult;
+}
+
+function validateInboxWait(value: unknown, expectedId: string): Handoff {
+  if (!isRecord(value)) {
+    return invalidInboxResponse('PingRoom returned an invalid Agent Inbox wait response.');
+  }
+
+  const state = value['state'];
+  if (
+    !isNonEmptyString(value['id'])
+    || value['id'] !== expectedId
+    || value['kind'] !== 'question'
+    || (state !== 'pending' && state !== 'answered' && state !== 'expired' && state !== 'cancelled')
+    || (value['activation_completed'] !== undefined && typeof value['activation_completed'] !== 'boolean')
+    || (state !== 'answered' && value['activation_completed'] === true)
+  ) {
+    return invalidInboxResponse('PingRoom returned a mismatched Agent Inbox wait response.', {
+      expected_id: expectedId,
+      received_id: typeof value['id'] === 'string' ? value['id'] : null,
+      kind: typeof value['kind'] === 'string' ? value['kind'] : null,
+      state: typeof state === 'string' ? state : null,
+    });
+  }
+
+  if (state === 'answered') {
+    const answer = value['answer'];
+    if (
+      !isRecord(answer)
+      || !isNullableString(answer['value'])
+      || !isNullableString(answer['label'])
+      || !isNullableString(answer['text'])
+      || (!isNonEmptyString(answer['value']) && !isNonEmptyString(answer['text']))
+      || !isNullableString(answer['answered_at'])
+      || (answer['responder'] !== null && !isRecord(answer['responder']))
+    ) {
+      return invalidInboxResponse('PingRoom returned an answered activation without a valid answer.', {
+        id: expectedId,
+        state,
+      });
+    }
+
+    const responder = answer['responder'];
+    if (
+      isRecord(responder)
+      && (!isNullableString(responder['id']) || !isNullableString(responder['display_name']))
+    ) {
+      return invalidInboxResponse('PingRoom returned an invalid activation responder.', {
+        id: expectedId,
+        state,
+      });
+    }
+  } else if (value['answer'] !== undefined && value['answer'] !== null) {
+    return invalidInboxResponse('PingRoom returned an answer for an unresolved activation.', {
+      id: expectedId,
+      state,
+    });
+  }
+
+  return value as unknown as Handoff;
+}
+
+/** Setup and activation of the bound human's Agent Inbox delivery room. */
+export class InboxApi {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Replay the viable activation attempt or create its next numbered retry. */
+  ensure(input: AgentInboxEnsureInput = {}): Promise<AgentInboxEnsureResult> {
+    return this.http.request('POST', '/api/agent/inbox/ensure', {
+      body: {},
+      ...(input.signal ? { signal: input.signal } : {}),
+    });
+  }
+
+  /**
+   * Ensure the bound human's Agent Inbox, then block on its onboarding
+   * Question until the server confirms activation, it expires/cancels, or the
+   * overall deadline elapses. Pairing remains a separate operation so adopting
+   * a credential never silently waits for a phone response.
+   */
+  async activate(input: AgentInboxActivateInput = {}): Promise<AgentInboxActivationResult> {
+    const overallTimeoutMs = input.overallTimeoutMs ?? DEFAULT_INBOX_ACTIVATION_TIMEOUT_MS;
+    if (!Number.isFinite(overallTimeoutMs) || overallTimeoutMs < 0) {
+      throw new PingRoomError('`overallTimeoutMs` must be a non-negative finite number.', {
+        code: 'invalid_request',
+      });
+    }
+
+    const deadlineError = (): PingRoomActivationIncompleteError => (
+      new PingRoomActivationIncompleteError(
+        'deadline_exceeded',
+        'Agent Inbox activation did not complete before the overall deadline.',
+        { overall_timeout_ms: overallTimeoutMs },
+      )
+    );
+    const deadlineController = new AbortController();
+    const deadlineTimer = overallTimeoutMs === 0
+      ? null
+      : setTimeout(() => deadlineController.abort(deadlineError()), overallTimeoutMs);
+    if (overallTimeoutMs === 0) deadlineController.abort(deadlineError());
+
+    const signal = input.signal
+      ? combineSignals(input.signal, deadlineController.signal)
+      : deadlineController.signal;
+
+    try {
+      throwIfAborted(signal);
+      const ensured = validateInboxEnsure(await this.ensure({ signal }));
+      const questionId = ensured.question.id;
+
+      let failures = 0;
+      for (;;) {
+        throwIfAborted(signal);
+        const pollStartedAt = Date.now();
+        let question: Handoff;
+        try {
+          question = validateInboxWait(await this.http.request<unknown>(
+            'GET',
+            `/api/agent/handoffs/${enc(questionId)}/wait`,
+            {
+              query: dropUndefined({ timeout: input.timeout }),
+              timeoutMs: waitTimeoutMs(input.timeout),
+              signal,
+            },
+          ), questionId);
+        } catch (error) {
+          // A dropped connection, a request deadline, a 429 (each wait route
+          // has its own 30/min bucket per human) or a 5xx is not an outcome:
+          // retry it like every other wait, inside the overall deadline.
+          // Anything else is permanent and surfaces.
+          throwIfAborted(signal);
+          if (!isTransientError(error)) {
+            throw error;
+          }
+          failures += 1;
+          await sleep(Math.max(
+            transientDelayMs(error, failures),
+            MIN_HANDOFF_POLL_INTERVAL_MS - (Date.now() - pollStartedAt),
+          ), signal);
+          continue;
+        }
+        failures = 0;
+        throwIfAborted(signal);
+
+        if (question.state === 'pending') {
+          await sleep(
+            Math.max(0, MIN_HANDOFF_POLL_INTERVAL_MS - (Date.now() - pollStartedAt)),
+            signal,
+          );
+          continue;
+        }
+
+        if (question.state === 'answered' && question.activation_completed === true) {
+          return {
+            ...ensured,
+            activation_completed: true,
+            question: question as AgentInboxActivationQuestion,
+          };
+        }
+
+        if (question.state === 'answered') {
+          throw new PingRoomActivationIncompleteError(
+            'answered_without_completion',
+            'The onboarding Question was answered without verified native phone receipt before the answer.',
+            { question_id: questionId, activation_completed: question.activation_completed ?? null },
+          );
+        }
+
+        if (question.state === 'expired' || question.state === 'cancelled') {
+          throw new PingRoomActivationIncompleteError(
+            question.state,
+            `The onboarding Question ${question.state} before Agent Inbox activation completed.`,
+            { question_id: questionId, activation_completed: question.activation_completed ?? null },
+          );
+        }
+
+        return invalidInboxResponse('PingRoom returned an invalid terminal activation state.', {
+          id: questionId,
+          state: question.state,
+        });
+      }
+    } catch (error) {
+      // A custom fetch implementation may reject with a generic AbortError
+      // instead of the signal's richer reason. Preserve caller cancellation
+      // and the activation-specific deadline error at this public boundary.
+      throwIfAborted(signal);
+      throw error;
+    } finally {
+      if (deadlineTimer !== null) clearTimeout(deadlineTimer);
+    }
+  }
+}

package/src/namespaces/live.ts

@@ -0,0 +1,134 @@
+// `pr.live`: live-status streams.
+
+import { PingRoomError } from '../errors.js';
+import type { HttpClient } from '../http.js';
+import { assertStructuredData, requireNonEmpty } from '../internal/guards.js';
+import type {
+  LiveClaimAction,
+  LiveClaimResult,
+  LiveClaimStatus,
+  LiveClaimStreamState,
+  LiveStatusPing,
+  LiveStatusResult,
+  LiveStatusSnapshot,
+} from '../liveStatus.js';
+import { enc } from '../internal/request.js';
+import { isNonEmptyString, isRecord, sameId } from '../internal/validate.js';
+
+/**
+ * What each action's 200 receipt may say, as `[claim.status, stream state]`
+ * pairs. `release` has two: letting go reopens a request that can still be
+ * taken, but a request past its deadline (or four hours old with none) ends as
+ * `expired` with stream state `failed`, exactly as time ends an open one. That
+ * is still a 200, and a retry replays it. Only `release` can end that way.
+ */
+const CLAIM_OUTCOMES = {
+  claim: [['claimed', 'running']],
+  release: [['open', 'running'], ['expired', 'failed']],
+  done: [['done', 'done']],
+  cancel: [['cancelled', 'failed']],
+} as const satisfies Record<LiveClaimAction, ReadonlyArray<readonly [LiveClaimStatus, LiveClaimStreamState]>>;
+
+function validateClaimResult(value: unknown, notificationId: string, action: LiveClaimAction): LiveClaimResult {
+  const expected = CLAIM_OUTCOMES[action];
+  const claim = isRecord(value) ? value['claim'] : undefined;
+  const party = isRecord(claim) ? claim['by'] : undefined;
+  if (!isRecord(value) || !sameId(value['notification_id'], notificationId)
+    || !isNonEmptyString(value['correlation_id']) || typeof value['idempotent'] !== 'boolean'
+    || !isRecord(claim) || !expected
+    || !expected.some(([status, state]) => claim['status'] === status && value['state'] === state)
+    || typeof claim['late'] !== 'boolean'
+    || !(party === null || isRecord(party) && isNonEmptyString(party['id']) && typeof party['name'] === 'string')
+    || !(claim['at'] === null || typeof claim['at'] === 'number' && Number.isFinite(claim['at']))) {
+    throw new PingRoomError('PingRoom returned an invalid claim transition receipt.', {
+      code: 'invalid_response',
+      body: { expected_notification_id: notificationId, action },
+    });
+  }
+  return value as unknown as LiveClaimResult;
+}
+
+/**
+ * Live-status streams — a self-updating card on the room members' lock screen.
+ *
+ * Requires the `pingroom:live:write` scope. Free accounts get a small daily
+ * budget of NEW streams; updates and the terminal ping of an open stream are
+ * never charged, so a card can never be quota-blocked into hanging open. A
+ * first ping that is already `done`/`failed` is a new stream and is charged.
+ */
+export class LiveApi {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Send one stream ping — start, update, or end, chosen by `live_status.state`
+   * and whether the correlation already exists.
+   */
+  push(inviteCode: string, ping: LiveStatusPing): Promise<LiveStatusResult> {
+    requireNonEmpty(inviteCode, 'inviteCode');
+    requireNonEmpty(ping.correlation_id, 'correlation_id');
+    assertStructuredData(ping.data);
+    return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/live`, { body: ping });
+  }
+
+  /**
+   * Read back a stream this credential started, so a restarted producer can
+   * reconcile instead of opening a duplicate.
+   *
+   * Resolves null ONLY for a 404 `stream_not_found` — no stream with that
+   * correlation id in the last 24 hours. Every other failure throws: a 404 for
+   * an unknown or deleted room code, and a 403 `room_not_granted`
+   * ({@link RoomScopedErrorCode}) when the room is outside the grant the human
+   * gave this agent, both propagate rather than being reported as "no stream".
+   */
+  async get(inviteCode: string, correlationId: string): Promise<LiveStatusSnapshot | null> {
+    requireNonEmpty(inviteCode, 'inviteCode');
+    requireNonEmpty(correlationId, 'correlationId');
+    try {
+      return await this.http.request<LiveStatusSnapshot>(
+        'GET',
+        `/api/agent/rooms/${enc(inviteCode)}/live/${enc(correlationId)}`,
+      );
+    } catch (error) {
+      if (error instanceof PingRoomError && error.status === 404 && error.code === 'stream_not_found') return null;
+      throw error;
+    }
+  }
+
+  /**
+   * Act on a "Who's on it?" request as the human this credential acts for:
+   * `claim` takes an open request (anyone but its asker), `release` lets go of
+   * one you hold, `done` finishes it (its claimer, or its asker at any time) and
+   * `cancel` withdraws it (its asker, or a room owner or admin).
+   *
+   * `release` returns the request to `open` only while it can still be taken.
+   * Past its deadline (or four hours after it was made, when it has none) it
+   * ends the request as `expired` instead: a 200 whose `claim.status` is
+   * `expired` and whose `state` is `failed`, with `claim.by` and `claim.at`
+   * `null`. It is not an error, and the asker hears "No one took it". No other
+   * action resolves that way.
+   *
+   * `notificationId` is the request's `notification_id`, from the `push()`
+   * result or `notifications.list()`. It needs only room membership, not room
+   * ownership, and the `pingroom:live:write` scope.
+   *
+   * Repeating your own last action resolves with `idempotent: true`. A refusal
+   * throws `PingRoomError`: `claim_conflict` (409), `claim_own_request` (422),
+   * `claim_private_rooms_only` (422), `claim_not_found` (404) or `forbidden`
+   * (403). On 409 and 422 `error.body` is a `LiveClaimRefusal` carrying the
+   * request as it stands, so you can say who got it first.
+   * A malformed or mismatched success throws `invalid_response`; the SDK
+   * never repeats the transition POST automatically.
+   */
+  claim(inviteCode: string, notificationId: string, action: LiveClaimAction): Promise<LiveClaimResult> {
+    requireNonEmpty(inviteCode, 'inviteCode');
+    requireNonEmpty(notificationId, 'notificationId');
+    if (typeof action !== 'string' || !Object.hasOwn(CLAIM_OUTCOMES, action)) {
+      throw new PingRoomError('`action` must be claim, release, done or cancel.', { code: 'invalid_request' });
+    }
+    return this.http.request<unknown>(
+      'POST',
+      `/api/agent/rooms/${enc(inviteCode)}/live/${enc(notificationId)}/claim`,
+      { body: { action } },
+    ).then((value) => validateClaimResult(value, notificationId, action));
+  }
+}

package/src/namespaces/notifications.ts

@@ -0,0 +1,152 @@
+// `pr.notifications`: history, one-shot waits and the listen() iterator.
+
+import { PingRoomError } from '../errors.js';
+import type { HttpClient } from '../http.js';
+import { sleep } from '../internal/async.js';
+import { requireNonEmpty } from '../internal/guards.js';
+import { isTransientError, transientDelayMs } from '../internal/retry.js';
+import { isRecord } from '../internal/validate.js';
+import type {
+  AcknowledgementWaitResult,
+  AgentNotification,
+  ListNotificationsInput,
+  ListenInput,
+  NotificationDetail,
+  NotificationHistoryEntry,
+  Paginated,
+  WaitForAcknowledgementInput,
+  WaitInput,
+  WaitResult,
+} from '../types.js';
+import { enc, dropUndefined, MIN_LISTEN_POLL_INTERVAL_MS, waitTimeoutMs } from '../internal/request.js';
+
+/**
+ * A 2xx that is not a wait answer (a captive portal's HTML, a proxy's error
+ * page served as 200) must not end `listen()` with a bare TypeError, nor
+ * advance its cursor.
+ */
+function validateListenResult(value: unknown, requireCursor: boolean): WaitResult {
+  if (
+    !isRecord(value)
+    || !Array.isArray(value['notifications'])
+    || value['notifications'].some((notification) => !isRecord(notification))
+    || (value['cursor'] === undefined ? requireCursor : typeof value['cursor'] !== 'string')
+  ) {
+    throw new PingRoomError('PingRoom returned an invalid notifications wait response.', {
+      code: 'invalid_response',
+    });
+  }
+  return value as unknown as WaitResult;
+}
+
+export class NotificationsApi {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Paginated list (polling fallback). Prefer wait()/listen() for real-time. */
+  async list(input: ListNotificationsInput = {}): Promise<Paginated<NotificationHistoryEntry>> {
+    const { notifications_per_page, ...query } = input;
+    const page = await this.http.request<Paginated<NotificationDetail>>('GET', '/api/agent/notifications', {
+      query: dropUndefined({ ...query, limit: input.limit ?? notifications_per_page }),
+    });
+    return {
+      ...page,
+      data: page.data.map(({ room, ...notification }) => ({
+        ...notification,
+        ...(room ? { room: { ...room, code: room.invite_code } } : {}),
+      })),
+    };
+  }
+
+  /** Fetch one visible notification, including its current acknowledgement state. */
+  getNotification(notificationId: string): Promise<NotificationDetail> {
+    requireNonEmpty(notificationId, 'notificationId');
+    return this.http.request('GET', `/api/agent/notifications/${enc(notificationId)}`);
+  }
+
+  /**
+   * One bounded long-poll for an ack-required ping. The returned state may
+   * still be `open` when the hold timeout elapses; call again to keep waiting.
+   */
+  waitForAcknowledgement(
+    notificationId: string,
+    input: WaitForAcknowledgementInput = {},
+  ): Promise<AcknowledgementWaitResult> {
+    requireNonEmpty(notificationId, 'notificationId');
+    return this.http.request('GET', `/api/agent/notifications/${enc(notificationId)}/ack/wait`, {
+      query: dropUndefined({ timeout: input.timeout }),
+      timeoutMs: waitTimeoutMs(input.timeout),
+      ...(input.signal ? { signal: input.signal } : {}),
+    });
+  }
+
+  /** One long-poll: resolves as soon as new pings land, or with an empty list at timeout. */
+  wait(input: WaitInput = {}): Promise<WaitResult> {
+    return this.http.request('GET', '/api/agent/notifications/wait', {
+      query: dropUndefined({ after: input.after, timeout: input.timeout, limit: input.limit }),
+      timeoutMs: waitTimeoutMs(input.timeout),
+      ...(input.signal ? { signal: input.signal } : {}),
+    });
+  }
+
+  /**
+   * Continuous real-time inbound: an async iterator that long-polls in a loop,
+   * advancing the cursor, yielding each new ping. Stops when `signal` aborts.
+   *
+   *   for await (const ping of pr.notifications.listen({ signal })) { ... }
+   */
+  async *listen(input: ListenInput = {}): AsyncGenerator<AgentNotification, void, void> {
+    let cursor = input.after;
+    let headRead = cursor !== undefined;
+    const backoffMs = input.backoffMs ?? 1000;
+    let failures = 0;
+    while (!input.signal?.aborted) {
+      let result: WaitResult;
+      // The head read is an immediate answer by design; only polls ahead of
+      // the cursor are spaced.
+      const polledForward = headRead;
+      const pollStartedAt = Date.now();
+      try {
+        // The head read exists to obtain a cursor, so it must carry one.
+        result = validateListenResult(headRead
+          ? await this.wait({
+            after: cursor,
+            ...(input.timeout !== undefined ? { timeout: input.timeout } : {}),
+            ...(input.limit !== undefined ? { limit: input.limit } : {}),
+            ...(input.signal ? { signal: input.signal } : {}),
+          })
+          // No cursor yet: read the current head (an immediate, empty answer)
+          // so only pings that land after this call are delivered.
+          : await this.wait({ timeout: 0, ...(input.signal ? { signal: input.signal } : {}) }), !headRead);
+      } catch (err) {
+        if (input.signal?.aborted) {
+          return;
+        }
+        // A revoked credential or a bad request never heals; only network
+        // failures, deadlines, 429 and 5xx are retried.
+        if (!isTransientError(err)) {
+          throw err;
+        }
+        failures += 1;
+        input.onError?.(err);
+        await sleep(Math.max(
+          transientDelayMs(err, failures, backoffMs),
+          MIN_LISTEN_POLL_INTERVAL_MS - (Date.now() - pollStartedAt),
+        ), input.signal);
+        continue;
+      }
+      failures = 0;
+      headRead = true;
+      cursor = result.cursor ?? cursor;
+      for (const n of result.notifications) {
+        yield n;
+      }
+      // Yield between polls so timer-driven cancellation can run (see
+      // ApprovalsApi). After an empty answer also keep polls a floor apart, so
+      // `timeout: 0` or an early-answering proxy cannot spin the loop.
+      const spacingMs = polledForward && result.notifications.length === 0
+        ? Math.max(0, MIN_LISTEN_POLL_INTERVAL_MS - (Date.now() - pollStartedAt))
+        : 0;
+      await sleep(spacingMs, input.signal);
+    }
+  }
+}

package/src/namespaces/profile.ts

@@ -0,0 +1,24 @@
+// `pr.profile`: this agent's own avatar and handle.
+
+import type { HttpClient } from '../http.js';
+import { requireNonEmpty } from '../internal/guards.js';
+import type { RotateHandleResult } from '../types.js';
+
+export class ProfileApi {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Set this agent's own avatar (from the bot avatar set) — the robot face
+   * its pings and Questions wear. Never touches the bound human's profile
+   * picture. Returns `{ ok, avatar_id, avatar_url }`.
+   */
+  setAvatar(avatarId: string): Promise<{ ok: boolean; avatar_id: string; avatar_url: string }> {
+    requireNonEmpty(avatarId, 'avatarId');
+    return this.http.request('POST', '/api/agent/profile/avatar', { body: { avatar_id: avatarId } });
+  }
+
+  /** Rotate the agent's handle — the kill-switch for a leaked handle. */
+  rotateHandle(): Promise<RotateHandleResult> {
+    return this.http.request('POST', '/api/agent/profile/handle/rotate', { body: {} });
+  }
+}