@pingroom/sdk 0.8.0 → 0.9.0

package/src/errors.ts

@@ -0,0 +1,291 @@
+/**
+ * Error types. PingRoomError carries the HTTP status and the API's machine
+ * `code` (e.g. `room_not_granted`, `cooldown_active`, `rate_limited`) so callers
+ * can branch without string-matching messages. Retry any 429 after
+ * `retryAfter` rather than matching one code: route throttles answer
+ * `rate_limited`, but public-room and quick-action limits carry their own
+ * (`public_room_rate_limited`, `cooldown_active`). The agent token is NEVER
+ * stored on or serialized through an error.
+ */
+
+export interface ApiErrorBody {
+  code?: string;
+  error?: string;
+  message?: string;
+  retry_after?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * The codes the `agent.room` gate emits on every ROOM-SCOPED route — the ones
+ * whose path carries an invite code: `rooms.get()`, `actions.list()`,
+ * `actions.trigger()`, `broadcast()`, the webhook calls, and
+ * `liveStatus.get()`/`liveStatus.push()`. HTTP 403.
+ *
+ * NOT reachable from `handoffs.create()`: `POST /api/agent/handoffs` names no
+ * room in its path and so is not behind that gate.
+ *
+ * Server: `EnsureAgentRoomAccess` middleware.
+ */
+export const ROOM_SCOPED_ERROR_CODES = [
+  // The room is outside the grant the human gave this agent when connecting.
+  'room_not_granted',
+] as const;
+
+/**
+ * The machine `code`s a handoff create/read can surface on a {@link PingRoomError}.
+ * Branch on `error.code` (and `error.status`) instead of the message.
+ *
+ * Authentication and schema-validation failures may have no machine code; use
+ * `status` for those responses. This union holds the codes specific to handoffs.
+ * Codes any route can answer (`rate_limited`, `feature_disabled`) are in
+ * {@link COMMON_ERROR_CODES}.
+ *
+ * Server: `AgentHandoffController`, `HandoffService`, `RequestIdempotency`, the
+ * `agent.scope`/`agent.quota` middleware, and the `RecipientNotReady` /
+ * `CapabilityCheckUnavailable` renderers in `bootstrap/app.php`.
+ */
+export const HANDOFF_ERROR_CODES = [
+  'feature_temporarily_unavailable',
+  'handoff_room_unsupported',
+  'invalid_target',
+  // The agent has no delivery room designated; the human must pick one.
+  'no_room_configured',
+  // An agent may hand off only to the account that connected it.
+  'target_not_permitted',
+  'recipient_not_ready',
+  'idempotency_conflict',
+  'invalid_idempotency_key',
+  'capability_check_unavailable',
+  'insufficient_scope',
+  'free_limit_reached',
+] as const;
+
+/**
+ * The coded failures of the Inbox activation path (`inbox.ensure()` /
+ * `inbox.activate()`). All HTTP 409 except `feature_temporarily_unavailable`,
+ * which is 422.
+ *
+ * Server: `AgentInboxController`.
+ */
+export const AGENT_INBOX_ERROR_CODES = [
+  // Already activated, but the original connection-test record is gone.
+  'activation_evidence_unavailable',
+  // The human must pick the room this agent pings them in.
+  'no_room_configured',
+  // The chosen room is muted, or the human is no longer a member of it.
+  'activation_room_muted',
+  // No device could render the activation Question.
+  'activation_delivery_unavailable',
+  'feature_temporarily_unavailable',
+] as const;
+
+/**
+ * The coded failures of the quick-action surface (`actions.*` and a
+ * `broadcast()` that names an `action_number`).
+ *
+ * Server: `Room::assertQuickActionAccessible/Configured`, `QuickActionDispatcher`
+ * and `QuickActionLayoutService`.
+ */
+export const QUICK_ACTION_ERROR_CODES = [
+  // 422 — the action has an input_type and the press carried no matching detail.
+  'quick_action_input_required',
+  // 422 — photo/pdf actions accept only jpg/png or pdf attachments.
+  'quick_action_input_type',
+  // 404 — the slot is reserved but disabled (empty label and icon).
+  'action_not_configured',
+  // 403 — slots 5–16 and layout edits need the ROOM OWNER on Pro; attachments need this account.
+  'pro_required',
+  // 409 — base_action_ids / quick_action_id no longer match the stored layout.
+  'quick_action_layout_changed',
+  // 409 — a time trigger, webhook, agent binding or running live update still uses the page.
+  'quick_action_page_in_use',
+  // 403 — `actions.trigger()` with trigger_source 'location' from anyone but the room owner.
+  'location_trigger_owner_only',
+  // 409 — `actions.trigger()` with trigger_source 'location' in a room with no enabled
+  // location trigger, or one that does not listen for the reported crossing.
+  'location_trigger_inactive',
+] as const;
+
+/**
+ * The coded refusals of the "Who's on it?" surface (`live.claim()`, and a
+ * `live.push()` that starts a `claim` stream).
+ *
+ * Server: `ClaimService`, `ClaimService::startingBlock()`.
+ */
+export const LIVE_CLAIM_ERROR_CODES = [
+  // 409 — not allowed from the request's current state (someone else holds it,
+  // it already ended, or you are not who may do this). `body.claim` shows who.
+  'claim_conflict',
+  // 422 — the asker tried to claim their own request.
+  'claim_own_request',
+  // 422 — claim requests exist only in private standard rooms.
+  'claim_private_rooms_only',
+  // 404 — no claim request with that notification id in this room.
+  'claim_not_found',
+  // 422, on create — the request text is missing or over 120 characters.
+  'claim_request_invalid',
+  // 422, on create — the first ping must be `running`.
+  'claim_must_start_running',
+  // 422, on create — `deadline_at` is in the past or more than 8 hours away.
+  'claim_deadline_out_of_range',
+] as const;
+
+/**
+ * Codes any route can answer, whatever the surface, so they sit in no
+ * per-surface union.
+ *
+ * - `rate_limited` — 429, a route throttle (`throttle:N,1`). The body carries
+ *   `retry_after`. Per-surface limits answer their own 429 code instead
+ *   (`public_room_rate_limited`, `cooldown_active`), so retry any 429.
+ * - `feature_disabled` — 403, the operator switched the capability off for every
+ *   client (attachments, links, locations, questions, public rooms, Location
+ *   Pings, incoming webhooks, live progress, …). The body's `feature` names the
+ *   switch (for example `sending.attachments`). Retrying cannot succeed.
+ *
+ * Server: the `ThrottleRequestsException` renderer in `bootstrap/app.php` and
+ * `ClientFeatureGate` (the `feature:` middleware and the request-level gates).
+ */
+export const COMMON_ERROR_CODES = ['rate_limited', 'feature_disabled'] as const;
+
+/**
+ * Request-size failures. The server answers every oversized `api/*` body with
+ * `413 {"code":"payload_too_large"}`; the SDK refuses a >5 MiB attachment
+ * locally with `attachment_too_large` before any bytes are sent.
+ */
+export const REQUEST_LIMIT_ERROR_CODES = ['payload_too_large', 'attachment_too_large'] as const;
+
+/** @see COMMON_ERROR_CODES */
+export type CommonErrorCode = (typeof COMMON_ERROR_CODES)[number];
+
+/** @see ROOM_SCOPED_ERROR_CODES */
+export type RoomScopedErrorCode = (typeof ROOM_SCOPED_ERROR_CODES)[number];
+
+/** @see QUICK_ACTION_ERROR_CODES */
+export type QuickActionErrorCode = (typeof QUICK_ACTION_ERROR_CODES)[number];
+
+/** @see REQUEST_LIMIT_ERROR_CODES */
+export type RequestLimitErrorCode = (typeof REQUEST_LIMIT_ERROR_CODES)[number];
+
+/** @see LIVE_CLAIM_ERROR_CODES */
+export type LiveClaimErrorCode = (typeof LIVE_CLAIM_ERROR_CODES)[number];
+
+/** @see HANDOFF_ERROR_CODES */
+export type HandoffErrorCode = (typeof HANDOFF_ERROR_CODES)[number];
+
+/** @see AGENT_INBOX_ERROR_CODES */
+export type AgentInboxErrorCode = (typeof AGENT_INBOX_ERROR_CODES)[number];
+
+/**
+ * Every machine `code` this SDK's typed unions cover, for callers that branch
+ * once across surfaces instead of per-endpoint.
+ */
+export type AgentErrorCode =
+  | HandoffErrorCode
+  | RoomScopedErrorCode
+  | AgentInboxErrorCode
+  | QuickActionErrorCode
+  | LiveClaimErrorCode
+  | RequestLimitErrorCode
+  | CommonErrorCode;
+
+export interface PingRoomErrorInit {
+  status?: number;
+  code?: string | null;
+  retryAfter?: number | null;
+  body?: unknown;
+  /** The underlying failure, exposed as the standard `error.cause`. */
+  cause?: unknown;
+}
+
+export class PingRoomError extends Error {
+  /** HTTP status, or 0 for client-side/network errors. */
+  readonly status: number;
+  /** Machine-readable code from the API body (`code` or `error`), or a client code. */
+  readonly code: string | null;
+  /** Seconds to wait before retrying, when the API or a Retry-After header provides it. */
+  readonly retryAfter: number | null;
+  /** The parsed response body (or raw text), for inspection. Contains no credentials. */
+  readonly body: unknown;
+
+  constructor(message: string, init: PingRoomErrorInit = {}) {
+    super(message);
+    this.name = 'PingRoomError';
+    this.status = init.status ?? 0;
+    this.code = init.code ?? null;
+    this.retryAfter = init.retryAfter ?? null;
+    this.body = init.body ?? null;
+    if (init.cause !== undefined) {
+      (this as { cause?: unknown }).cause = init.cause;
+    }
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  static fromResponse(status: number, body: unknown, headers?: Headers): PingRoomError {
+    const b: ApiErrorBody = body && typeof body === 'object' ? (body as ApiErrorBody) : {};
+    const code =
+      (typeof b.code === 'string' && b.code) ||
+      (typeof b.error === 'string' && b.error) ||
+      null;
+    const message =
+      (typeof b.message === 'string' && b.message) ||
+      (code ? code : `HTTP ${status}`);
+
+    let retryAfter: number | null = typeof b.retry_after === 'number' ? b.retry_after : null;
+    if (retryAfter === null && headers) {
+      const h = headers.get('retry-after');
+      if (h && /^\d+$/.test(h.trim())) {
+        retryAfter = Number(h.trim());
+      }
+    }
+
+    return new PingRoomError(message, { status, code, retryAfter, body });
+  }
+}
+
+/** Thrown when a request exceeds its timeout. */
+export class PingRoomTimeoutError extends PingRoomError {
+  constructor(message = 'Request timed out') {
+    super(message, { code: 'timeout' });
+    this.name = 'PingRoomTimeoutError';
+  }
+}
+
+/** Thrown when the underlying fetch fails (DNS, connection, TLS, etc.). */
+export class PingRoomNetworkError extends PingRoomError {
+  constructor(message: string, cause?: unknown) {
+    super(message, { code: 'network_error' });
+    this.name = 'PingRoomNetworkError';
+    if (cause !== undefined) {
+      (this as { cause?: unknown }).cause = cause;
+    }
+  }
+}
+
+export type AgentInboxActivationIncompleteReason =
+  | 'deadline_exceeded'
+  | 'answered_without_completion'
+  | 'expired'
+  | 'cancelled';
+
+/**
+ * The onboarding Question reached a non-activating terminal outcome, or the
+ * caller's overall activation deadline elapsed. The client's credential is not
+ * changed or revoked when this error is thrown.
+ */
+export class PingRoomActivationIncompleteError extends PingRoomError {
+  readonly reason: AgentInboxActivationIncompleteReason;
+
+  constructor(
+    reason: AgentInboxActivationIncompleteReason,
+    message: string,
+    details: Record<string, unknown> = {},
+  ) {
+    super(message, {
+      code: 'inbox_activation_incomplete',
+      body: { reason, ...details },
+    });
+    this.name = 'PingRoomActivationIncompleteError';
+    this.reason = reason;
+  }
+}

package/src/http.ts

@@ -0,0 +1,225 @@
+import { PingRoomError, PingRoomNetworkError, PingRoomTimeoutError } from './errors.js';
+import { combineSignals } from './internal/async.js';
+import { assertSecureUrl, refuseRedirect } from './internal/url.js';
+import { invalidSuccessResponse } from './internal/validate.js';
+import type { FetchLike } from './types.js';
+import { VERSION } from './version.js';
+
+export interface HttpClientOptions {
+  baseUrl: string;
+  token?: string | null;
+  timeoutMs?: number;
+  fetch?: FetchLike;
+  userAgent?: string;
+  allowInsecure?: boolean;
+}
+
+export interface RequestOptions {
+  query?: Record<string, string | number | boolean | undefined>;
+  body?: unknown;
+  headers?: Record<string, string>;
+  /** Send the Authorization header (default true). Public endpoints pass false. */
+  auth?: boolean;
+  /** Per-call timeout override in ms. */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** Node's util.inspect hook, named through the global registry so no import is needed. */
+const INSPECT: unique symbol = Symbol.for('nodejs.util.inspect.custom');
+
+/**
+ * Thin authenticated fetch wrapper. Holds the token privately, enforces https
+ * for credentialed traffic, applies a timeout, and maps non-2xx responses to a
+ * PingRoomError. The token is never written into thrown errors or logs.
+ */
+export class HttpClient {
+  // An ES private field: TypeScript's `private` is compile-time only, so the
+  // token would otherwise reach JSON.stringify() and util.inspect() output.
+  #token: string | null;
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+  private readonly fetchImpl: FetchLike;
+  private readonly userAgent: string;
+
+  constructor(options: HttpClientOptions) {
+    const base = assertSecureUrl(options.baseUrl, options.allowInsecure ?? false);
+    // Normalise: keep origin + any path prefix, drop a trailing slash.
+    this.baseUrl = (base.origin + base.pathname).replace(/\/$/, '');
+    this.#token = options.token ?? null;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.fetchImpl = options.fetch ?? defaultFetch();
+    this.userAgent = options.userAgent ?? `pingroom-sdk/${VERSION}`;
+  }
+
+  setToken(token: string | null): void {
+    this.#token = token;
+  }
+
+  getToken(): string | null {
+    return this.#token;
+  }
+
+  /** What a logger or JSON.stringify() sees: the API origin, never the credential. */
+  toJSON(): { baseUrl: string; token: '[redacted]' | null } {
+    return { baseUrl: this.baseUrl, token: this.#token === null ? null : '[redacted]' };
+  }
+
+  [INSPECT](): string {
+    return `HttpClient { baseUrl: ${JSON.stringify(this.baseUrl)}, token: ${this.#token === null ? 'null' : '[redacted]'} }`;
+  }
+
+  async request<T>(method: string, path: string, opts: RequestOptions = {}): Promise<T> {
+    return this.send(method, path, opts, (res) => this.parse<T>(res));
+  }
+
+  /**
+   * The undecoded Response, for endpoints that return bytes rather than JSON.
+   * Non-2xx still raises a PingRoomError so callers never read an error body
+   * as if it were content.
+   */
+  async raw(method: string, path: string, opts: RequestOptions = {}): Promise<Response> {
+    return this.send(method, path, {
+      ...opts,
+      headers: { Accept: '*/*', ...opts.headers },
+    }, async (res) => {
+      if (!res.ok) {
+        // Route the failure through the shared JSON error mapping.
+        await this.parse<unknown>(res);
+      }
+      return res;
+    });
+  }
+
+  private async send<T>(
+    method: string,
+    path: string,
+    opts: RequestOptions,
+    consume: (res: Response) => Promise<T>,
+  ): Promise<T> {
+    const url = this.buildUrl(path, opts.query);
+
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      'User-Agent': this.userAgent,
+      ...opts.headers,
+    };
+
+    if (opts.auth !== false) {
+      if (!this.#token) {
+        throw new PingRoomError(
+          'This call requires an agent token. Pass `token` to the client or call setToken().',
+          { code: 'no_token' },
+        );
+      }
+      headers['Authorization'] = `Bearer ${this.#token}`;
+    }
+
+    // FormData is passed through untouched: the runtime has to generate the
+    // multipart boundary itself, so setting Content-Type here would corrupt it.
+    let payload: string | FormData | undefined;
+    if (opts.body instanceof FormData) {
+      payload = opts.body;
+    } else if (opts.body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+      payload = JSON.stringify(opts.body);
+    }
+
+    const timeoutMs = opts.timeoutMs ?? this.timeoutMs;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new PingRoomTimeoutError()), timeoutMs);
+    const signal = combineSignals(controller.signal, opts.signal);
+
+    // Called as a plain function, never as a method of this client: browsers
+    // and Workers reject a fetch whose receiver is not the global object.
+    const fetchImpl = this.fetchImpl;
+    try {
+      // A 307/308 can forward pairing secrets or uploaded bytes to another
+      // origin even when fetch strips the Authorization header. 'manual' plus
+      // an explicit refusal, because Workers reject redirect: 'error'.
+      const res = await fetchImpl(url, { method, headers, body: payload, signal, redirect: 'manual' });
+      refuseRedirect(res);
+      // Keep the deadline active while reading JSON, including error bodies.
+      return await consume(res);
+    } catch (err) {
+      if (signal.aborted) {
+        throw signal.reason;
+      }
+      // Our own timeout reason propagates as the rejection.
+      if (err instanceof PingRoomError) {
+        throw err;
+      }
+      if (isAbortError(err) || opts.signal?.aborted) {
+        throw err;
+      }
+      throw new PingRoomNetworkError(`Network request failed: ${errMessage(err)}`, err);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  private async parse<T>(res: Response): Promise<T> {
+    if (res.status === 204) {
+      return undefined as T;
+    }
+    const text = await res.text();
+    let json: unknown = null;
+    if (text.trim()) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        // A non-JSON error stays text for the error mapping below; a non-JSON
+        // success is a proxy's page, not data.
+        if (res.ok) {
+          throw invalidSuccessResponse(res.status, 'a JSON body', text);
+        }
+        json = text;
+      }
+    }
+    if (!res.ok) {
+      throw PingRoomError.fromResponse(res.status, json, res.headers);
+    }
+    return json as T;
+  }
+
+  private buildUrl(path: string, query?: RequestOptions['query']): string {
+    // Every call is relative to the base URL the token was configured for. An
+    // absolute URL would carry the Bearer token to another origin unchecked.
+    if (/^[a-z][a-z\d+.-]*:/i.test(path)) {
+      throw new PingRoomError('Request paths must be relative to the API base URL.', { code: 'invalid_request' });
+    }
+    const full = this.baseUrl + (path.startsWith('/') ? path : `/${path}`);
+    if (!query) {
+      return full;
+    }
+    const url = new URL(full);
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== undefined) {
+        url.searchParams.set(k, String(v));
+      }
+    }
+    return url.toString();
+  }
+}
+
+/** The global fetch, bound so that calling it detached keeps a valid receiver. */
+export function defaultFetch(): FetchLike {
+  const f = globalThis.fetch as unknown as FetchLike | undefined;
+  if (typeof f !== 'function') {
+    throw new PingRoomError(
+      'No fetch implementation available. Use Node >= 20, a modern browser, or pass `fetch`.',
+      { code: 'no_fetch' },
+    );
+  }
+  return f.bind(globalThis);
+}
+
+function isAbortError(err: unknown): boolean {
+  return Boolean(err) && typeof err === 'object' && (err as { name?: string }).name === 'AbortError';
+}
+
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/index.ts

@@ -0,0 +1,97 @@
+/**
+ * @pingroom/sdk — official TypeScript/JavaScript SDK for the PingRoom agent API.
+ *
+ *   import { PingRoom } from '@pingroom/sdk';
+ *   const pr = new PingRoom({ token: process.env.PINGROOM_TOKEN });
+ *   await pr.broadcast('ab12cd', { message: 'Deploy shipped ✅' });
+ */
+
+import { PingRoom } from './client.js';
+
+export { PingRoom };
+/** Alias for {@link PingRoom}. */
+export { PingRoom as PingRoomClient } from './client.js';
+
+export { McpClient } from './mcp.js';
+export type { JsonRpcError, McpInitializeResult, McpTool, McpToolResult } from './mcp.js';
+
+export {
+  PingRoomError,
+  PingRoomTimeoutError,
+  PingRoomNetworkError,
+  PingRoomActivationIncompleteError,
+  AGENT_INBOX_ERROR_CODES,
+  COMMON_ERROR_CODES,
+  HANDOFF_ERROR_CODES,
+  LIVE_CLAIM_ERROR_CODES,
+  ROOM_SCOPED_ERROR_CODES,
+  QUICK_ACTION_ERROR_CODES,
+  REQUEST_LIMIT_ERROR_CODES,
+} from './errors.js';
+export type {
+  AgentErrorCode,
+  AgentInboxActivationIncompleteReason,
+  AgentInboxErrorCode,
+  ApiErrorBody,
+  CommonErrorCode,
+  HandoffErrorCode,
+  LiveClaimErrorCode,
+  PingRoomErrorInit,
+  QuickActionErrorCode,
+  RequestLimitErrorCode,
+  RoomScopedErrorCode,
+} from './errors.js';
+
+export {
+  verifyWebhookSignature,
+  sendIncomingWebhook,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_SIGNATURE_V2_HEADER,
+  WEBHOOK_TIMESTAMP_HEADER,
+  WEBHOOK_DELIVERY_HEADER,
+  WEBHOOK_EVENT_HEADER,
+  INCOMING_WEBHOOK_FIELDS,
+} from './webhooks.js';
+export type {
+  VerifyWebhookSignatureOptions,
+  IncomingWebhookPayload,
+  SendIncomingWebhookOptions,
+  IncomingWebhookResult,
+} from './webhooks.js';
+
+export { linkPing } from './linkPing.js';
+export type { LinkPingInput, LinkPingData } from './linkPing.js';
+
+export { locationPing, extractLocationPing } from './locationPing.js';
+export type {
+  LocationPingInput,
+  LocationPingLocation,
+  LocationPingData,
+} from './locationPing.js';
+
+export { liveStatus } from './liveStatus.js';
+export type {
+  LiveActivityTemplate,
+  LiveStatus,
+  LiveStatusState,
+  LiveStatusCategory,
+  LiveStatusMetric,
+  LiveStatusOption,
+  LiveStatusSide,
+  LiveClaim,
+  LiveClaimAction,
+  LiveClaimParty,
+  LiveClaimRefusal,
+  LiveClaimResult,
+  LiveClaimStatus,
+  LiveClaimStreamState,
+  LiveStatusPing,
+  LiveStatusResult,
+  LiveStatusSnapshot,
+} from './liveStatus.js';
+
+export { VERSION } from './version.js';
+
+export type * from './types.js';
+
+export default PingRoom;

package/src/internal/async.ts

@@ -0,0 +1,54 @@
+/** Merge two abort signals into one (uses AbortSignal.any when available). */
+export function combineSignals(primary: AbortSignal, extra?: AbortSignal): AbortSignal {
+  if (!extra) {
+    return primary;
+  }
+  const anyFn = (AbortSignal as unknown as { any?: (signals: AbortSignal[]) => AbortSignal }).any;
+  if (typeof anyFn === 'function') {
+    return anyFn([primary, extra]);
+  }
+  const controller = new AbortController();
+  const forward = (s: AbortSignal): void => {
+    if (!controller.signal.aborted) {
+      controller.abort(s.reason);
+    }
+  };
+  for (const s of [primary, extra]) {
+    if (s.aborted) {
+      forward(s);
+      break;
+    }
+    s.addEventListener('abort', () => forward(s), { once: true });
+  }
+  return controller.signal;
+}
+
+/** Resolve after `ms`, or early (without rejecting) if `signal` aborts. */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      cleanup();
+      resolve();
+    };
+    const cleanup = (): void => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/** Throw the signal's reason once it has aborted. A missing signal never throws. */
+export function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new Error('aborted');
+  }
+}