@pingroom/sdk 0.8.0 → 0.9.0

package/src/namespaces/auth.ts

@@ -0,0 +1,284 @@
+// `pr.auth`: registration, claim, app pairing and the credential lifecycle.
+
+import { PingRoomError } from '../errors.js';
+import type { HttpClient } from '../http.js';
+import { sleep, throwIfAborted } from '../internal/async.js';
+import { requireNonEmpty } from '../internal/guards.js';
+import type {
+  AgentConnectionInfo,
+  AgentDisconnectResult,
+  Credential,
+  ClaimCompleteParams,
+  ClaimStartParams,
+  RegisterParams,
+  PairingStart,
+  PairingStatus,
+  PairedCredential,
+  StartPairingParams,
+  WaitForPairingOptions,
+} from '../types.js';
+import { dropUndefined } from '../internal/request.js';
+import { isRecord } from '../internal/validate.js';
+
+/** Drop a malformed or unsafe server-provided URL without rejecting its response. */
+function normalizePublicHttpUrl(candidate: unknown): string | undefined {
+  if (typeof candidate !== 'string' || candidate.trim() === '') return undefined;
+  const trimmed = candidate.trim();
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001F\u007F-\u009F]/.test(trimmed)) return undefined;
+  try {
+    const url = new URL(trimmed);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return undefined;
+    if (url.username !== '' || url.password !== '') return undefined;
+  } catch {
+    return undefined;
+  }
+  return trimmed;
+}
+
+/** Drop malformed or unsafe server-provided links without rejecting a valid credential. */
+function normalizePairingLinks(value: unknown): { latest_pings: string; install_app?: string } | undefined {
+  if (!isRecord(value)) return undefined;
+  const latestPings = normalizePublicHttpUrl(value['latest_pings']);
+  if (!latestPings) return undefined;
+  const installApp = normalizePublicHttpUrl(value['install_app']);
+  return {
+    latest_pings: latestPings,
+    ...(installApp ? { install_app: installApp } : {}),
+  };
+}
+
+/**
+ * The credential a pairing swapped in, and the one to hand back when it ends
+ * without an approval. Held by `pair_token`, so a PairingStart that was only
+ * copied or re-serialised still finds it.
+ */
+interface PendingPairing {
+  pairToken: string;
+  pending: string;
+  previous: string | null;
+}
+
+/** Agent credential lifecycle (auth.md flow). */
+export class AuthApi {
+  private pairing: PendingPairing | null = null;
+
+  constructor(private readonly http: HttpClient) {}
+
+  /** Register an agent. Anonymous or via an identity assertion (ID-JAG / verified email). Public. */
+  register(params: RegisterParams): Promise<Credential> {
+    requireNonEmpty(params.type, 'type');
+    return this.http.request('POST', '/api/agent/auth', { auth: false, body: dropUndefined({ ...params }) });
+  }
+
+  /** Begin claiming a pre-claim credential onto a human account; emails an OTP. */
+  claimStart(params: ClaimStartParams): Promise<{ message: string; expires_in: number }> {
+    requireNonEmpty(params.email, 'email');
+    return this.http.request('POST', '/api/agent/auth/claim/start', { body: { email: params.email } });
+  }
+
+  /** Complete the claim with the emailed OTP; returns an active credential + handle. */
+  claimComplete(params: ClaimCompleteParams): Promise<Credential> {
+    requireNonEmpty(params.email, 'email');
+    requireNonEmpty(params.otp, 'otp');
+    return this.http.request('POST', '/api/agent/auth/claim/complete', { body: dropUndefined({ ...params }) });
+  }
+
+  /**
+   * Register a pending agent and create a short-lived link that opens the
+   * PingRoom app. The server owns the full grant shown to the approver; this
+   * client sends no scope list. The pending credential stays private inside the
+   * client and is replaced automatically once waitForPairing() succeeds. If the
+   * client already held a credential, it is put back when the pairing expires
+   * or the wait is aborted, so a re-pairing that never completes leaves the
+   * client on the working credential rather than the dead pending one.
+   */
+  async startPairing(params: StartPairingParams = {}): Promise<PairingStart> {
+    const previousToken = this.http.getToken();
+    const pending = await this.register({
+      type: 'anonymous',
+      ...(params.agent_label ? { agent_label: params.agent_label } : {}),
+    });
+    this.http.setToken(pending.credential);
+
+    try {
+      const started = await this.http.request<PairingStart>('POST', '/api/agent/auth/pair/start', {
+        body: {},
+      });
+      // A second pairing started while the first is still pending falls back
+      // to the credential beneath it, not to the first pairing's pending one.
+      this.pairing = {
+        pairToken: started.pair_token,
+        pending: pending.credential,
+        previous: this.pairing !== null && this.pairing.pending === previousToken
+          ? this.pairing.previous
+          : previousToken,
+      };
+      return started;
+    } catch (error) {
+      if (this.http.getToken() === pending.credential) {
+        this.http.setToken(previousToken);
+      }
+      throw error;
+    }
+  }
+
+  /** Read the current state of an app pairing using the pending credential. */
+  pairingStatus(options: Pick<WaitForPairingOptions, 'signal'> = {}): Promise<PairingStatus> {
+    return this.http.request('GET', '/api/agent/auth/pair/status', { signal: options.signal });
+  }
+
+  /**
+   * Wait until the person approves in PingRoom, or the short-lived link
+   * expires. Transient network, 429, and 5xx failures are retried inside the
+   * server-provided lifetime. On success the client immediately starts using
+   * the active credential returned by the server. When the link expires or the
+   * wait is aborted, the credential the client held before startPairing() is
+   * restored; calling waitForPairing() again after an abort resumes the same
+   * pairing.
+   */
+  async waitForPairing(
+    pairing: PairingStart,
+    options: WaitForPairingOptions = {},
+  ): Promise<PairedCredential> {
+    const tracked = this.pairing !== null && this.pairing.pairToken === pairing.pair_token
+      ? this.pairing
+      : null;
+    if (tracked !== null && this.http.getToken() === tracked.previous) {
+      // Resuming after an abort put the earlier credential back.
+      this.http.setToken(tracked.pending);
+    }
+    try {
+      const paired = await this.pollPairing(pairing, options);
+      if (tracked !== null && this.pairing === tracked) this.pairing = null;
+      return paired;
+    } catch (error) {
+      if (tracked !== null && this.pairing === tracked) {
+        const expired = error instanceof PingRoomError && error.code === 'pairing_expired';
+        if (expired || options.signal?.aborted === true) {
+          if (this.http.getToken() === tracked.pending) this.http.setToken(tracked.previous);
+        }
+        // An expired pairing cannot be resumed; an aborted one can.
+        if (expired) this.pairing = null;
+      }
+      throw error;
+    }
+  }
+
+  private async pollPairing(
+    pairing: PairingStart,
+    options: WaitForPairingOptions,
+  ): Promise<PairedCredential> {
+    const lifetimeMs = Math.max(1, Number(pairing.expires_in) || 900) * 1000;
+    const requestedInterval = options.pollIntervalMs ?? pairing.poll_interval_ms;
+    const intervalMs = Math.min(Math.max(Number(requestedInterval) || 1500, 1000), 10_000);
+    const startedAt = Date.now();
+    const deadline = startedAt + lifetimeMs;
+    let transientFailures = 0;
+
+    while (Date.now() < deadline) {
+      throwIfAborted(options.signal);
+
+      try {
+        const status = await this.pairingStatus({ signal: options.signal });
+        throwIfAborted(options.signal);
+        transientFailures = 0;
+
+        if (status.status === 'active') {
+          if (
+            typeof status.credential !== 'string'
+            || status.credential.trim() === ''
+            || status.credential_type !== 'active'
+            || (status.expires_in !== null
+              && (typeof status.expires_in !== 'number'
+                || !Number.isFinite(status.expires_in)
+                || status.expires_in < 0))
+            // A null/absent `room` is valid when the account has no eligible
+            // private delivery room (and on older servers). Only a room that is
+            // present but malformed is a broken response.
+            || (status.room != null
+              && (typeof status.room.invite_code !== 'string'
+                || status.room.invite_code.trim() === ''))
+          ) {
+            throw new PingRoomError('PingRoom returned an incomplete approved pairing.', {
+              code: 'pairing_invalid_response',
+              body: { status: status.status },
+            });
+          }
+          this.http.setToken(status.credential);
+          // Pairing is server-authoritative. Some servers still include their
+          // internal grant marker for protocol compatibility; it is neither a
+          // client input nor part of the paired credential surface.
+          const { status: _status, scopes: _serverScopes, links: rawLinks, ...credential } = status;
+          const links = normalizePairingLinks(rawLinks);
+          return links ? { ...credential, links } : credential;
+        }
+        if (status.status === 'expired') {
+          throw new PingRoomError('The PingRoom pairing link expired before it was approved.', {
+            code: 'pairing_expired',
+          });
+        }
+      } catch (error) {
+        if (
+          error instanceof PingRoomError
+          && [401, 403, 404].includes(error.status)
+          && Date.now() - startedAt >= lifetimeMs / 2
+        ) {
+          // The pending bearer can expire before the server returns an
+          // explicit expired pairing state. Keep early auth failures intact.
+          throw new PingRoomError('The PingRoom pairing link expired before it was approved.', {
+            code: 'pairing_expired',
+          });
+        }
+        if (
+          error instanceof PingRoomError
+          && (error.code === 'network_error'
+            || error.code === 'timeout'
+            || error.status === 429
+            || error.status >= 500)
+        ) {
+          transientFailures += 1;
+          const backoffMs = Math.min(intervalMs * 2 ** Math.max(0, transientFailures - 3), 30_000);
+          await sleep(Math.max(0, Math.min(backoffMs, deadline - Date.now())), options.signal);
+          continue;
+        }
+        throw error;
+      }
+
+      await sleep(Math.max(0, Math.min(intervalMs, deadline - Date.now())), options.signal);
+    }
+
+    throw new PingRoomError('The PingRoom pairing link expired before it was approved.', {
+      code: 'pairing_expired',
+    });
+  }
+
+  /** Rotate to a fresh credential (same scopes/handle). */
+  refresh(): Promise<Credential> {
+    return this.http.request('POST', '/api/agent/auth/refresh', { body: {} });
+  }
+
+  /** Revoke the current credential. */
+  revoke(): Promise<void> {
+    return this.http.request('POST', '/api/agent/auth/revoke', { body: {} });
+  }
+
+  /**
+   * What this credential is connected to: the robot, the owner's public id and
+   * name, the home room and room memberships, and the room grant. Check
+   * `owner.id` and `handle` against the account and robot you approved before
+   * sending anything.
+   */
+  connection(): Promise<AgentConnectionInfo> {
+    return this.http.request('GET', '/api/agent/connection');
+  }
+
+  /**
+   * Disconnect this agent: revokes the calling credential and its refresh
+   * credentials. The client keeps the now-revoked token; clear it with
+   * `setToken(null)` or pair again.
+   */
+  disconnect(): Promise<AgentDisconnectResult> {
+    return this.http.request('POST', '/api/agent/disconnect', { body: {} });
+  }
+}

package/src/namespaces/directory.ts

@@ -0,0 +1,21 @@
+// `pr.directory`: the public agent directory.
+
+import type { HttpClient } from '../http.js';
+import type { DirectoryEntry, DirectoryListInput, DirectoryProfile, Paginated } from '../types.js';
+import { enc, dropUndefined } from '../internal/request.js';
+
+/** Public, unauthenticated agent directory. */
+export class DirectoryApi {
+  constructor(private readonly http: HttpClient) {}
+
+  list(input: DirectoryListInput = {}): Promise<Paginated<DirectoryEntry>> {
+    return this.http.request('GET', '/api/agents/directory', {
+      auth: false,
+      query: dropUndefined({ ...input }),
+    });
+  }
+
+  get(handle: string): Promise<DirectoryProfile> {
+    return this.http.request('GET', `/api/agents/directory/${enc(handle)}`, { auth: false });
+  }
+}

package/src/namespaces/handoffs.ts

@@ -0,0 +1,160 @@
+// `pr.handoffs`: the direct, private agent-to-human loop.
+
+import { PingRoomError } from '../errors.js';
+import type { HttpClient } from '../http.js';
+import {
+  assertStructuredData,
+  normalizeIdempotencyKey,
+  requireNonEmpty,
+} from '../internal/guards.js';
+import { pollUntilSettled } from '../internal/retry.js';
+import type {
+  AskInput,
+  Handoff,
+  HandoffOptionInput,
+  HandoffOptionSpec,
+  ListHandoffsInput,
+  RequestAckInput,
+  WaitHandoffInput,
+  WaitForOutcomeOptions,
+} from '../types.js';
+import {
+  MIN_HANDOFF_POLL_INTERVAL_MS,
+  enc,
+  assertOnRetry,
+  dropUndefined,
+  waitTimeoutMs,
+} from '../internal/request.js';
+import { isRecord, sameId, invalidWaitResponse } from '../internal/validate.js';
+
+const HANDOFF_STATES: ReadonlySet<string> = new Set(['open', 'acked', 'pending', 'answered', 'expired', 'cancelled']);
+
+function validateHandoffWait(value: unknown, handoffId: string): Handoff {
+  const state = isRecord(value) ? value['state'] : undefined;
+  if (!isRecord(value) || !sameId(value['id'], handoffId) || typeof state !== 'string' || !HANDOFF_STATES.has(state)) {
+    return invalidWaitResponse('handoff', handoffId, value, 'state');
+  }
+  return value as unknown as Handoff;
+}
+
+/** A bare string option is shorthand for `{ value, label: value }`. */
+function normalizeHandoffOptions(options: HandoffOptionSpec[]): HandoffOptionInput[] {
+  return options.map((o) => (typeof o === 'string' ? { value: o, label: o } : o));
+}
+
+/** Terminal states never change again — the wait loop can stop as soon as one lands. */
+function isHandoffTerminal(handoff: Handoff): boolean {
+  const s = handoff.state;
+  return s === 'acked' || s === 'answered' || s === 'expired' || s === 'cancelled';
+}
+
+/**
+ * The Handoff façade: the Agent → one-human loop. Always DIRECT (exactly one
+ * human) and PRIVATE (no other room member can read it). Backed by the ack and
+ * question primitives, so its {@link Handoff.state | state} space is their union
+ * — kept DISTINCT per {@link Handoff.kind | kind}. A negative answer to a
+ * question handoff (e.g. `hold`) is a SUCCESSFUL `answered` result, not an error.
+ *
+ *   const task = await pr.handoffs.requestAck({ prompt, idempotencyKey });
+ *   const result = await pr.handoffs.waitForResult(task.id);
+ *
+ *   const q = await pr.handoffs.ask({ prompt, options: ['deploy', 'hold'], idempotencyKey });
+ */
+export class HandoffsApi {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Ask a human to acknowledge (an `ack` handoff). Resolves on the first acknowledgement. */
+  requestAck(input: RequestAckInput): Promise<Handoff> {
+    requireNonEmpty(input.prompt, 'prompt');
+    assertStructuredData(input.data);
+    return this.create('ack', input);
+  }
+
+  /**
+   * Ask a human a multi-option question (a `question` handoff). Resolves on the
+   * first tapped answer. Bare-string options normalize to `{ value, label }`.
+   */
+  ask(input: AskInput): Promise<Handoff> {
+    requireNonEmpty(input.prompt, 'prompt');
+    assertStructuredData(input.data);
+    if (!Array.isArray(input.options) || input.options.length < 2 || input.options.length > 4) {
+      throw new PingRoomError('`options` must contain between 2 and 4 entries for a question handoff.', {
+        code: 'invalid_request',
+      });
+    }
+    return this.create('question', input, normalizeHandoffOptions(input.options));
+  }
+
+  /** Fetch a handoff's current state. */
+  get(id: string): Promise<Handoff> {
+    requireNonEmpty(id, 'id');
+    return this.http.request('GET', `/api/agent/handoffs/${enc(id)}`);
+  }
+
+  /**
+   * Block until the handoff resolves (or expires/cancels), looping the bounded
+   * long-poll under the hood. `expired`/`cancelled` and a negative answer (e.g.
+   * `hold`) all surface as normal terminal results — nothing is thrown for them.
+   *
+   * Polls start at least 2.1 s apart, so a short `timeout` stays under the
+   * route's 30-per-minute limit. A response that is not this handoff 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 handoff'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 waitForResult(id: string, input: WaitHandoffInput & WaitForOutcomeOptions = {}): Promise<Handoff> {
+    requireNonEmpty(id, 'id');
+    assertOnRetry(input.onRetry);
+    return pollUntilSettled({
+      poll: () => this.wait(id, input),
+      validate: (value) => validateHandoffWait(value, id),
+      settled: isHandoffTerminal,
+      expiresAt: (handoff) => handoff.expires_at,
+      what: `handoff ${id}`,
+      minIntervalMs: MIN_HANDOFF_POLL_INTERVAL_MS,
+      ...(input.signal ? { signal: input.signal } : {}),
+      ...(input.onRetry ? { onRetry: input.onRetry } : {}),
+    });
+  }
+
+  /** List the agent's open handoffs or bounded recent history. */
+  async list(input: ListHandoffsInput = {}): Promise<Handoff[]> {
+    const res = await this.http.request<{ handoffs: Handoff[] }>('GET', '/api/agent/handoffs', {
+      query: dropUndefined({ state: input.state }),
+    });
+    return res.handoffs ?? [];
+  }
+
+  /** One bounded long-poll; returns the (possibly still-open) handoff. */
+  private wait(id: string, input: WaitHandoffInput): Promise<Handoff> {
+    return this.http.request('GET', `/api/agent/handoffs/${enc(id)}/wait`, {
+      query: dropUndefined({ timeout: input.timeout }),
+      timeoutMs: waitTimeoutMs(input.timeout),
+      ...(input.signal ? { signal: input.signal } : {}),
+    });
+  }
+
+  private create(
+    kind: 'ack' | 'question',
+    input: RequestAckInput,
+    options?: HandoffOptionInput[],
+  ): Promise<Handoff> {
+    const body = dropUndefined({
+      kind,
+      prompt: input.prompt,
+      audience: { type: 'direct', user_id: input.target ?? 'me' },
+      expires_in: input.expiresIn,
+      urgency: input.urgency,
+      options,
+      correlation_id: input.correlationId,
+      reply_to: input.replyTo,
+      data: input.data,
+    });
+    return this.http.request('POST', '/api/agent/handoffs', {
+      body,
+      ...(input.idempotencyKey ? { headers: { 'Idempotency-Key': normalizeIdempotencyKey(input.idempotencyKey) } } : {}),
+    });
+  }
+}