@pingroom/sdk 0.8.0 → 0.9.0

package/src/namespaces/questions.ts

@@ -0,0 +1,133 @@
+// `pr.questions`: Questions and polls in a room.
+
+import { PingRoomError } from '../errors.js';
+import type { HttpClient } from '../http.js';
+import { assertStructuredData, requireNonEmpty } from '../internal/guards.js';
+import { pollUntilSettled } from '../internal/retry.js';
+import type {
+  ListQuestionsInput,
+  Question,
+  QuestionInput,
+  WaitForOutcomeOptions,
+  WaitQuestionInput,
+} from '../types.js';
+import {
+  MIN_WAIT_POLL_INTERVAL_MS,
+  enc,
+  splitIdempotencyKey,
+  assertOnRetry,
+  dropUndefined,
+  waitTimeoutMs,
+} from '../internal/request.js';
+import { isRecord, sameId, invalidWaitResponse } from '../internal/validate.js';
+
+const QUESTION_STATES: ReadonlySet<string> = new Set(['pending', 'answered', 'expired', 'cancelled']);
+
+function validateQuestionWait(value: unknown, questionId: string): Question {
+  const state = isRecord(value) ? value['state'] : undefined;
+  if (!isRecord(value) || !sameId(value['id'], questionId) || typeof state !== 'string' || !QUESTION_STATES.has(state)) {
+    return invalidWaitResponse('question', questionId, value, 'state');
+  }
+  return value as unknown as Question;
+}
+
+/**
+ * The general human-in-the-loop primitive: ask a human a question with 2–4
+ * options (or a short typed answer) and block until they tap an answer. An
+ * {@link ApprovalsApi | approval} is the two-option case; reach for questions
+ * when you need more choices, a typed reply, or room-scope answering.
+ */
+export class QuestionsApi {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Ask a Question in a room; returns the pending Question (id + computed
+   * expiry). Pass `resolution_policy: 'all'` to poll the room: everyone asked
+   * votes once, and `results` carries the tally on every read.
+   */
+  ask(inviteCode: string, input: QuestionInput): Promise<Question> {
+    requireNonEmpty(input.prompt, 'prompt');
+    assertStructuredData(input.data);
+    assertPollShape(input);
+    const { body, headers } = splitIdempotencyKey(input);
+    return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/questions`, {
+      body: dropUndefined(body),
+      ...(headers ? { headers } : {}),
+    });
+  }
+
+  /** Fetch a Question's current state. */
+  get(questionId: string): Promise<Question> {
+    return this.http.request('GET', `/api/agent/questions/${enc(questionId)}`);
+  }
+
+  /** One long-poll for the answer; returns the (possibly still-pending) Question. */
+  wait(questionId: string, input: WaitQuestionInput = {}): Promise<Question> {
+    return this.http.request('GET', `/api/agent/questions/${enc(questionId)}/wait`, {
+      query: dropUndefined({ timeout: input.timeout }),
+      timeoutMs: waitTimeoutMs(input.timeout),
+      ...(input.signal ? { signal: input.signal } : {}),
+    });
+  }
+
+  /**
+   * Block until the human answers (or the question expires/cancels), looping
+   * wait() under the hood. Returns the resolved Question — inspect `state` and
+   * `answer.value` to branch. A poll returns once it closes; its `answer` is the
+   * leading option, or `null` on a tie, and `results` holds the tally.
+   *
+   * Polls start at least 2.1 s apart. A response that is not this Question in a
+   * known state rejects with `invalid_response`. Network failures, 429 and 5xx
+   * are retried with backoff (honouring `retryAfter`), and reported to
+   * `onRetry`, until `signal` aborts or the outage outlasts the Question's
+   * `expires_at` by 5 minutes (15 minutes of failures while no `expires_at` has
+   * been read); that rejects with `unavailable`. See {@link WaitForOutcomeOptions}.
+   */
+  async waitForAnswer(questionId: string, input: WaitForOutcomeOptions = {}): Promise<Question> {
+    requireNonEmpty(questionId, 'questionId');
+    assertOnRetry(input.onRetry);
+    return pollUntilSettled({
+      poll: () => this.wait(questionId, input.signal ? { signal: input.signal } : {}),
+      validate: (value) => validateQuestionWait(value, questionId),
+      settled: (question) => question.state !== 'pending',
+      expiresAt: (question) => question.expires_at,
+      what: `question ${questionId}`,
+      minIntervalMs: MIN_WAIT_POLL_INTERVAL_MS,
+      ...(input.signal ? { signal: input.signal } : {}),
+      ...(input.onRetry ? { onRetry: input.onRetry } : {}),
+    });
+  }
+
+  /** List the asker's Questions, optionally filtered by state. */
+  async list(input: ListQuestionsInput = {}): Promise<Question[]> {
+    const res = await this.http.request<{ questions: Question[] }>('GET', '/api/agent/questions', {
+      query: dropUndefined({ state: input.state }),
+    });
+    return res.questions ?? [];
+  }
+
+  /** Withdraw a still-pending Question (409 if it already resolved). */
+  cancel(questionId: string): Promise<Question> {
+    return this.http.request('POST', `/api/agent/questions/${enc(questionId)}/cancel`, { body: {} });
+  }
+}
+
+/**
+ * A poll asks the whole room and counts option votes, so the server refuses it
+ * (422 on `resolution_policy`) alongside a direct scope, a named target, or a
+ * typed answer. Fail before the request instead.
+ */
+function assertPollShape(input: QuestionInput): void {
+  if (input.resolution_policy !== 'all') return;
+  const target = input.target_user_id as unknown;
+  if (
+    input.responder_scope === 'direct'
+    || (target !== undefined && target !== null && target !== '')
+    || (input.text_input !== undefined && input.text_input !== null)
+  ) {
+    throw new PingRoomError(
+      "A poll (`resolution_policy: 'all'`) asks the whole room with options only; it cannot use `responder_scope: 'direct'`, `target_user_id`, or `text_input`.",
+      { code: 'invalid_request' },
+    );
+  }
+}

package/src/namespaces/rooms.ts

@@ -0,0 +1,53 @@
+// `pr.rooms`: list, read, create and join rooms.
+
+import { PingRoomError } from '../errors.js';
+import type { HttpClient } from '../http.js';
+import { requireNonEmpty } from '../internal/guards.js';
+import type {
+  CreatePublicRoomInput,
+  CreateRoomInput,
+  JoinRoomInput,
+  Room,
+  RoomIconCatalog,
+} from '../types.js';
+import { enc, dropUndefined } from '../internal/request.js';
+
+export class RoomsApi {
+  constructor(private readonly http: HttpClient) {}
+
+  icons(): Promise<RoomIconCatalog> {
+    return this.http.request('GET', '/api/agent/room-icons');
+  }
+
+  list(): Promise<Room[]> {
+    return this.http.request('GET', '/api/agent/rooms');
+  }
+
+  get(inviteCode: string): Promise<Room> {
+    return this.http.request('GET', `/api/agent/rooms/${enc(inviteCode)}`);
+  }
+
+  create(input: CreateRoomInput): Promise<Room> {
+    requireNonEmpty(input.name, 'name');
+    return this.http.request('POST', '/api/agent/rooms', { body: dropUndefined({ ...input }) });
+  }
+
+  createPublic(input: CreatePublicRoomInput): Promise<Room> {
+    requireNonEmpty(input.name, 'name');
+    requireNonEmpty(input.handle, 'handle');
+    // The server takes the location trio all-or-nothing; a partial set is a
+    // 422 on a field the caller may not have meant to send at all.
+    const present = [input.location_name, input.location_latitude, input.location_longitude].filter((v) => v !== undefined).length;
+    if (present !== 0 && present !== 3) {
+      throw new PingRoomError('Send `location_name`, `location_latitude` and `location_longitude` together, or none of them.', {
+        code: 'invalid_request',
+      });
+    }
+    return this.http.request('POST', '/api/agent/rooms/public', { body: dropUndefined({ ...input }) });
+  }
+
+  join(input: JoinRoomInput): Promise<Room> {
+    requireNonEmpty(input.invite_code, 'invite_code');
+    return this.http.request('POST', '/api/agent/rooms/join', { body: dropUndefined({ ...input }) });
+  }
+}

package/src/namespaces/webhooks.ts

@@ -0,0 +1,38 @@
+// `pr.webhooks`: a room's incoming webhooks.
+
+import type { HttpClient } from '../http.js';
+import { assertActionNumber, requireNonEmpty } from '../internal/guards.js';
+import type { CreateWebhookInput, UpdateWebhookInput, Webhook } from '../types.js';
+import { enc, dropUndefined } from '../internal/request.js';
+
+export class WebhooksApi {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(inviteCode: string): Promise<Webhook[]> {
+    const result = await this.http.request<{ webhooks: Webhook[] }>(
+      'GET', `/api/agent/rooms/${enc(inviteCode)}/webhooks`,
+    );
+    return result.webhooks;
+  }
+
+  create(inviteCode: string, input: CreateWebhookInput): Promise<Webhook> {
+    requireNonEmpty(input.name, 'name');
+    assertActionNumber(input.action_number);
+    return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/webhooks`, {
+      body: dropUndefined({ ...input }),
+    });
+  }
+
+  update(inviteCode: string, webhookId: string, input: UpdateWebhookInput): Promise<Webhook> {
+    requireNonEmpty(webhookId, 'webhookId');
+    assertActionNumber(input.action_number);
+    return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/webhooks/${enc(webhookId)}`, {
+      body: dropUndefined({ ...input }),
+    });
+  }
+
+  async delete(inviteCode: string, webhookId: string): Promise<void> {
+    requireNonEmpty(webhookId, 'webhookId');
+    await this.http.request('DELETE', `/api/agent/rooms/${enc(inviteCode)}/webhooks/${enc(webhookId)}`);
+  }
+}

package/src/types/approvals.ts

@@ -0,0 +1,67 @@
+import type { PingRoomError } from '../errors.js';
+import type { JsonObject } from './common.js';
+
+// --- approvals ------------------------------------------------------------
+
+export interface ApprovalInput {
+  question: string;
+  title?: string;
+  options?: string[];
+  correlation_id?: string;
+  data?: JsonObject;
+  ttl?: number;
+  /**
+   * Sent as the `Idempotency-Key` header (1–255 printable ASCII characters,
+   * spaces allowed), never in the body.
+   * Reuse the same key when retrying after a timeout or network error: the
+   * server replays the first result instead of asking the human a second time.
+   */
+  idempotencyKey?: string;
+}
+
+export interface Approval {
+  id: string;
+  /**
+   * A human answer has status `decided`; inspect `decision` for the chosen
+   * option. `approved`/`denied` are never sent.
+   */
+  status: 'pending' | 'decided' | 'expired' | 'cancelled' | (string & {});
+  question: string;
+  title: string | null;
+  options: string[];
+  decision: string | null;
+  decided_at: string | null;
+  expires_at: string | null;
+  correlation_id: string | null;
+  data: JsonObject | null;
+  /** Null when the approval's room no longer exists. */
+  room_code: string | null;
+  [key: string]: unknown;
+}
+
+export interface WaitApprovalInput {
+  /** Seconds the server holds the connection (0–30, default 20). */
+  timeout?: number;
+  signal?: AbortSignal;
+}
+
+/**
+ * Options for the blocking waits: `approvals.waitForDecision()`,
+ * `questions.waitForAnswer()` and `handoffs.waitForResult()`.
+ *
+ * Network errors, request timeouts, 429 and 5xx are retried with backoff. The
+ * retries stop with `PingRoomError` code `unavailable` (the last failure as
+ * its `cause`) once only failures have come back since the last valid
+ * response and the last-seen `expires_at` is more than 5 minutes past, or,
+ * before any `expires_at` was seen, after 15 minutes of unbroken failures.
+ */
+export interface WaitForOutcomeOptions {
+  /** Abort to stop waiting; the wait rejects with the signal's reason. */
+  signal?: AbortSignal;
+  /**
+   * Called before each retry of a transient failure, with that failure and
+   * the number of consecutive failures so far (1 on the first). Throwing from
+   * it ends the wait with the thrown error.
+   */
+  onRetry?: (error: PingRoomError, attempt: number) => void;
+}

package/src/types/auth.ts

@@ -0,0 +1,202 @@
+import type { ScopeInput } from './common.js';
+
+// --- auth -----------------------------------------------------------------
+
+export type AgentRegisterType = 'identity_assertion' | 'anonymous';
+export type AgentAssertionType = 'urn:ietf:params:oauth:token-type:id-jag' | 'verified_email';
+
+export interface RegisterParams {
+  type: AgentRegisterType;
+  assertion_type?: AgentAssertionType;
+  assertion?: string;
+  scopes?: ScopeInput[];
+  agent_label?: string;
+}
+
+/**
+ * How wide the human made this agent's room grant.
+ *
+ * `'all'` — every room the account is in; the grant lists none, while `room`
+ * may identify one eligible private delivery destination. `'selected'` —
+ * exactly the rooms in `rooms`.
+ */
+export type AgentRoomAccess = 'all' | 'selected';
+
+/** One room inside an agent's grant. */
+export interface AgentAccessRoom {
+  id: string;
+  invite_code: string;
+  name: string;
+}
+
+/** The delivery room: where handoffs and questions land. */
+export interface AgentDeliveryRoom {
+  invite_code: string;
+  name?: string | null;
+}
+
+/** Stable, non-credential URLs returned with an approved agent connection. */
+export interface AgentCredentialLinks {
+  /** REST endpoint for the agent's latest visible pings. Authenticate normally. */
+  latest_pings: string;
+  /** Token-free smart link for installing PingRoom on iOS or Android. */
+  install_app?: string;
+}
+
+/** Public robot identity provisioned before a person approves pairing. */
+export interface AgentProfile {
+  display_name: string | null;
+  handle: string | null;
+  avatar_id: string | null;
+  avatar_url: string | null;
+}
+
+/** Agent wrapper used by pairing v2. Older servers omit it entirely. */
+export interface PairingAgent {
+  id?: string;
+  label?: string | null;
+  handle?: string | null;
+  profile?: AgentProfile;
+}
+
+/** Human who claimed the robot. Present only after approval. */
+export interface PairingOwner {
+  name: string | null;
+}
+
+/** Visible home-room membership, distinct from the wider room-access grant. */
+export interface AgentRoomMembership {
+  status: 'active' | 'removed';
+  joined_at: string | null;
+  removed_at: string | null;
+  /** True for the robot's home room. Sent by `auth.connection()`. */
+  is_home?: boolean;
+  room: AgentDeliveryRoom | null;
+}
+
+/** Additive pairing-v2 identity metadata; every field is optional for old servers. */
+export interface PairingIdentityMetadata {
+  flow_version?: 2;
+  claim_mode?: 'agent_identity';
+  agent?: PairingAgent;
+  owner?: PairingOwner;
+  /** Alias of legacy `room`: the robot's Question/Handoff delivery room. */
+  home_room?: AgentDeliveryRoom | null;
+  room_membership?: AgentRoomMembership | null;
+}
+
+export interface Credential extends PairingIdentityMetadata {
+  credential: string;
+  credential_type: 'pre_claim' | 'active';
+  expires_in: number | null;
+  scopes: string[];
+  handle?: string;
+  claim?: { start_uri: string; complete_uri: string };
+  account?: { name?: string | null } | null;
+  /** The delivery room, or null when the human pinned none. */
+  room?: AgentDeliveryRoom | null;
+  room_access?: AgentRoomAccess | null;
+  /** The full grant. Empty under `room_access: 'all'`. */
+  rooms?: AgentAccessRoom[];
+  /** Server-authoritative endpoints associated with this connection. */
+  links?: AgentCredentialLinks;
+}
+
+/** The human a connection belongs to, as `auth.connection()` and `auth.disconnect()` report it. */
+export interface AgentConnectionOwner {
+  /** Public user id. Match it to the account you approved before sending. */
+  id: string;
+  name: string;
+}
+
+/** `auth.connection()`: what this credential is connected to. */
+export interface AgentConnectionInfo {
+  flow_version: 2;
+  claim_mode: 'agent_identity';
+  status: 'active';
+  handle: string | null;
+  agent: PairingAgent;
+  owner: AgentConnectionOwner;
+  /** The robot's Question/Handoff delivery room, or null when none is designated. */
+  home_room: AgentAccessRoom | null;
+  /** The robot's membership of its home room. */
+  room_membership: AgentRoomMembership | null;
+  /** Every active room membership, home room first. */
+  room_memberships: AgentRoomMembership[];
+  room_access: AgentRoomAccess | null;
+  links: AgentCredentialLinks;
+  [key: string]: unknown;
+}
+
+/** `auth.disconnect()`: the calling credential and its refresh credentials are revoked. */
+export interface AgentDisconnectResult {
+  status: 'revoked';
+  handle: string | null;
+  owner: AgentConnectionOwner;
+  /** Reconnect guidance for the human. */
+  message: string;
+  [key: string]: unknown;
+}
+
+export interface ClaimStartParams {
+  email: string;
+}
+
+export interface ClaimCompleteParams {
+  email: string;
+  otp: string;
+  scopes?: ScopeInput[];
+}
+
+/** Start an app-approved pairing without copying an API token or room code. */
+export interface StartPairingParams {
+  /**
+   * @deprecated Pairing grants are server-authoritative. This value is ignored
+   * and retained only so existing TypeScript callers continue to compile.
+   */
+  scopes?: ScopeInput[];
+  agent_label?: string;
+}
+
+/** Short-lived browser and native-app links returned when pairing starts. */
+export interface PairingStart extends PairingIdentityMetadata {
+  pair_token: string;
+  /** Legacy approval link, kept QR-compatible for existing clients. */
+  pair_url: string;
+  /** Browser approval page. Fall back to `pair_url` on older servers. */
+  pair_browser_url?: string;
+  /** Native app universal link for QR renderers. Falls back to `pair_url` on older servers. */
+  pair_qr_url?: string;
+  /** Token-free smart install link. Never append `pair_token` to it. */
+  app_install_url?: string;
+  expires_in: number;
+  poll_interval_ms: number;
+}
+
+export type PairedCredential = Omit<Credential, 'credential_type' | 'scopes'> & {
+  credential_type: 'active';
+  /**
+   * The selected/deterministic private delivery room. Null remains valid when
+   * the account has no eligible private room (and for older servers).
+   */
+  room: AgentDeliveryRoom | null;
+  room_access: AgentRoomAccess;
+  /** The full grant. Empty under `room_access: 'all'`. */
+  rooms: AgentAccessRoom[];
+};
+
+export type PairingStatus =
+  | (PairingIdentityMetadata & { status: 'pending' })
+  | (PairingIdentityMetadata & { status: 'expired' })
+  | (PairedCredential & {
+      status: 'active';
+      /** Legacy server metadata accepted on input and omitted from the result. */
+      scopes?: string[];
+    });
+
+export interface WaitForPairingOptions {
+  /** Stop waiting without consuming the pairing session. */
+  signal?: AbortSignal;
+  /** Override the server-suggested polling interval (clamped to 1–10 seconds). */
+  pollIntervalMs?: number;
+}

package/src/types/common.ts

@@ -0,0 +1,74 @@
+/** A plain JSON object — the shape the API accepts for structured `data`. */
+export type JsonObject = Record<string, unknown>;
+
+/** Minimal fetch signature the SDK depends on (Node >= 18, browsers, workers, Deno, Bun). */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+/** The scopes an agent credential can hold. */
+export type AgentScope =
+  | 'pingroom:full'
+  | 'pingroom:rooms:read'
+  | 'pingroom:rooms:write'
+  | 'pingroom:rooms:publish'
+  | 'pingroom:rooms:join'
+  | 'pingroom:actions:write'
+  | 'pingroom:actions:trigger'
+  | 'pingroom:broadcast:send'
+  | 'pingroom:attachments:write'
+  | 'pingroom:notifications:read'
+  | 'pingroom:webhooks:read'
+  | 'pingroom:webhooks:write'
+  | 'pingroom:webhooks:delete'
+  | 'pingroom:agents:ping'
+  | 'pingroom:approvals:request'
+  | 'pingroom:questions:ask'
+  | 'pingroom:handoffs:create'
+  | 'pingroom:live:write'
+  | 'pingroom:profile:write'
+  | 'pingroom:codes:redeem';
+
+/** A known scope, or any forward-compatible string (keeps autocomplete on the knowns). */
+export type ScopeInput = AgentScope | (string & {});
+
+// --- client options -------------------------------------------------------
+
+export interface PingRoomOptions {
+  /** Agent credential (Bearer JWT). Optional — public reads (directory) work without it. */
+  token?: string | null;
+  /** API base URL. Defaults to env PINGROOM_API_URL/PINGROOM_BASE_URL, else https://api.pingroom.io. */
+  baseUrl?: string;
+  /** Default per-request timeout in ms (long-poll calls extend this automatically). Default 30000. */
+  timeoutMs?: number;
+  /** Custom fetch implementation (for tests or non-global-fetch runtimes). */
+  fetch?: FetchLike;
+  /** Override the User-Agent header. */
+  userAgent?: string;
+  /** Allow plain-http base URLs to non-loopback hosts. Off by default — credentials require https. */
+  allowInsecure?: boolean;
+}
+
+// --- gift and promotional codes --------------------------------------------
+
+/** Pro entitlement applied to the human who authorized this agent. */
+export interface RedeemCodeResult {
+  message: string;
+  kind: 'gift' | 'redeem';
+  reward_days: number | null;
+  package: string | null;
+  lifetime: boolean;
+  plan: 'pro';
+  plan_expires_at: string | null;
+}
+
+// --- pagination -----------------------------------------------------------
+
+export interface Paginated<T> {
+  current_page: number;
+  data: T[];
+  per_page: number;
+  total: number;
+  last_page: number;
+  next_page_url: string | null;
+  prev_page_url: string | null;
+  [key: string]: unknown;
+}