@pingroom/sdk 0.8.0 → 0.9.0

package/src/namespaces/actions.ts

@@ -0,0 +1,234 @@
+// `pr.actions`: a room's quick-action slots, pages and presses.
+
+import { PingRoomError } from '../errors.js';
+import type { HttpClient } from '../http.js';
+import { assertActionNumber, requireNonEmpty, requirePresentString } from '../internal/guards.js';
+import { linkPing } from '../linkPing.js';
+import { locationPing } from '../locationPing.js';
+import type {
+  PingResult,
+  QuickAction,
+  TriggerInput,
+  QuickActionInput,
+  UpdateQuickActionInput,
+  UpdateQuickActionLayoutInput,
+} from '../types.js';
+import { enc, splitIdempotencyKey, dropUndefined } from '../internal/request.js';
+
+const MAX_TRIGGER_ATTACHMENTS = 4;
+const QUICK_ACTION_PAGE_SIZE = 4;
+const MAX_QUICK_ACTION_PAGES = 4;
+
+/**
+ * The per-slot checks shared by `updateMany()` and `updateLayout()`: a valid,
+ * present, unique action_number and an icon whenever the slot has a label.
+ * Two entries for one slot would let the last silently win, and the caller
+ * would never learn which of its definitions was stored.
+ */
+function assertActionSlots(actions: QuickActionInput[]): void {
+  const seen = new Set<number>();
+  for (const action of actions) {
+    assertActionNumber(action.action_number);
+    if (action.action_number === undefined || action.action_number === null) {
+      throw new PingRoomError('`action_number` is required for each action.', { code: 'invalid_request' });
+    }
+    if (seen.has(action.action_number)) {
+      throw new PingRoomError(`Duplicate action_number ${action.action_number}.`, { code: 'invalid_request' });
+    }
+    seen.add(action.action_number);
+    assertQuickActionIcon(action);
+  }
+}
+
+/**
+ * Mirrors the server's `icon` rule (`present`, `required_with:label`): the emoji
+ * is the half that must be there unless BOTH are empty, which reserves the
+ * slot as disabled.
+ */
+function assertQuickActionIcon(action: { label: unknown; icon: unknown }): void {
+  requirePresentString(action.label, 'label');
+  requirePresentString(action.icon, 'icon');
+  if ((action.icon as string).trim() === '' && (action.label as string).trim() !== '') {
+    throw new PingRoomError('`icon` is required when `label` is set; send both empty to disable the slot.', {
+      code: 'invalid_request',
+    });
+  }
+}
+
+function assertTriggerInput(input: TriggerInput): void {
+  const data = input.data;
+  if (data !== undefined) {
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+      throw new PingRoomError('`data` must be an object with `location` and/or `url`.', { code: 'invalid_request' });
+    }
+    for (const key of Object.keys(data)) {
+      if (key !== 'location' && key !== 'url') {
+        throw new PingRoomError(`\`data.${key}\` is not accepted on a quick-action press; only location and url are.`, {
+          code: 'invalid_request',
+        });
+      }
+    }
+    try {
+      if (data.location !== undefined) locationPing(data.location);
+      if (data.url !== undefined) linkPing({ url: data.url });
+    } catch (error) {
+      throw new PingRoomError((error as Error).message, { code: 'invalid_request' });
+    }
+  }
+  if (input.attachment_ids !== undefined) {
+    if (!Array.isArray(input.attachment_ids) || input.attachment_ids.length > MAX_TRIGGER_ATTACHMENTS) {
+      throw new PingRoomError(`\`attachment_ids\` accepts at most ${MAX_TRIGGER_ATTACHMENTS} ids.`, { code: 'invalid_request' });
+    }
+    for (const id of input.attachment_ids) requireNonEmpty(id, 'attachment_ids[]');
+  }
+}
+
+export class ActionsApi {
+  constructor(private readonly http: HttpClient) {}
+
+  list(inviteCode: string): Promise<QuickAction[]> {
+    return this.http.request('GET', `/api/agent/rooms/${enc(inviteCode)}/actions`);
+  }
+
+  update(inviteCode: string, actionNumber: number, input: UpdateQuickActionInput): Promise<QuickAction> {
+    assertActionNumber(actionNumber);
+    // A Ping's title is optional — its emoji can be the whole name — so an
+    // empty `label` is a valid update. `icon` is the half that must be there,
+    // unless both are empty: that reserves the slot as disabled.
+    assertQuickActionIcon(input);
+    return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/actions/${actionNumber}`, {
+      body: dropUndefined({ ...input }),
+    });
+  }
+
+  /**
+   * Write up to 16 action slots in one request. The server enforces the room owner's plan.
+   * Add new pages in complete groups of four; existing slots may be edited individually.
+   *
+   * Prefer this over looping `update()`. Each single-slot write enqueues its
+   * own silent rooms-refresh push, so configuring a room's four Pings one at a
+   * time wakes room members' devices four times inside a few seconds — four of a
+   * finite daily background-push budget spent on one logical operation.
+   *
+   * Partial and additive: slots absent from `actions` keep their current
+   * configuration, so this is also the right call for editing a single Ping.
+   * Nothing here deletes an action, and an empty array is rejected locally
+   * rather than being sent as a clear. Resolves to the room's full ordered
+   * action set, not just the slots written.
+   */
+  updateMany(inviteCode: string, actions: QuickActionInput[]): Promise<QuickAction[]> {
+    if (!Array.isArray(actions) || actions.length === 0) {
+      throw new PingRoomError('`actions` must contain at least one action.', { code: 'invalid_request' });
+    }
+    if (actions.length > 16) {
+      throw new PingRoomError('A batch may contain at most 16 action slots.', { code: 'invalid_request' });
+    }
+
+    assertActionSlots(actions);
+
+    return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/actions`, {
+      body: { actions: actions.map((action) => dropUndefined({ ...action })) },
+    });
+  }
+
+  /**
+   * Press a slot. When the action has an `input_type`, pass the matching
+   * detail (`data.location`, `data.url`, or `attachment_ids`) or the server
+   * refuses the press with `422 quick_action_input_required` and sends nothing.
+   * Read `input_type` from `list()` first; pass the action's `id` as
+   * `quick_action_id` to be refused rather than fire the wrong Ping if the
+   * owner moved pages meanwhile.
+   */
+  trigger(inviteCode: string, actionNumber: number, input: TriggerInput = {}): Promise<PingResult> {
+    assertActionNumber(actionNumber);
+    assertTriggerInput(input);
+    const { body, headers } = splitIdempotencyKey(input);
+    return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/actions/${actionNumber}/trigger`, {
+      body: dropUndefined({ ...body }),
+      ...(headers ? { headers } : {}),
+    });
+  }
+
+  /**
+   * Replace the room's page layout atomically (room owner on Pro only). See
+   * `UpdateQuickActionLayoutInput` for the snapshot contract; a stale
+   * `base_action_ids` is `409 quick_action_layout_changed`, a page still used
+   * by a time trigger, webhook, agent binding or running live update is
+   * `409 quick_action_page_in_use`. Prefer `deletePage()`, which builds the
+   * body from a fresh read.
+   */
+  updateLayout(inviteCode: string, input: UpdateQuickActionLayoutInput): Promise<QuickAction[]> {
+    if (!Array.isArray(input.base_action_ids)) {
+      throw new PingRoomError('`base_action_ids` must be an array of action ids (may be empty).', { code: 'invalid_request' });
+    }
+    if (!Array.isArray(input.page_order) || input.page_order.length < 1 || input.page_order.length > MAX_QUICK_ACTION_PAGES) {
+      throw new PingRoomError(`\`page_order\` must list 1–${MAX_QUICK_ACTION_PAGES} pages.`, { code: 'invalid_request' });
+    }
+    for (const page of input.page_order) {
+      if (page !== null && (!Number.isInteger(page) || page < 1 || page > MAX_QUICK_ACTION_PAGES)) {
+        throw new PingRoomError('`page_order` entries must be an original page number 1–4 or null for a blank page.', {
+          code: 'invalid_request',
+        });
+      }
+    }
+    const expected = input.page_order.length * QUICK_ACTION_PAGE_SIZE;
+    if (!Array.isArray(input.actions) || input.actions.length !== expected) {
+      throw new PingRoomError(`\`actions\` must hold exactly ${expected} slots for ${input.page_order.length} page(s).`, {
+        code: 'invalid_request',
+      });
+    }
+    assertActionSlots(input.actions);
+    return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/actions/layout`, {
+      body: {
+        base_action_ids: input.base_action_ids,
+        page_order: input.page_order,
+        actions: input.actions.map((action) => dropUndefined({ ...action })),
+      },
+    });
+  }
+
+  /**
+   * Delete one page (1–4) and shift the later pages left, keeping every other
+   * slot's configuration. Reads the current action set first so the layout
+   * snapshot is real, then calls `updateLayout()`. Page 1 can be deleted only
+   * when another page remains.
+   */
+  async deletePage(inviteCode: string, page: number): Promise<QuickAction[]> {
+    if (!Number.isInteger(page) || page < 1 || page > MAX_QUICK_ACTION_PAGES) {
+      throw new PingRoomError('`page` must be an integer 1–4.', { code: 'invalid_request' });
+    }
+    const current = await this.list(inviteCode);
+    const stored = [...current].sort((a, b) => a.action_number - b.action_number);
+    const pageCount = Math.max(1, Math.ceil((stored.at(-1)?.action_number ?? 0) / QUICK_ACTION_PAGE_SIZE));
+    if (page > pageCount) {
+      throw new PingRoomError(`The room has ${pageCount} page(s); page ${page} does not exist.`, { code: 'invalid_request' });
+    }
+    if (pageCount === 1) {
+      throw new PingRoomError('A room keeps at least one page; configure its slots instead of deleting it.', {
+        code: 'invalid_request',
+      });
+    }
+    const keep = Array.from({ length: pageCount }, (_, i) => i + 1).filter((p) => p !== page);
+    const byNumber = new Map(stored.map((a) => [a.action_number, a]));
+    const actions: QuickActionInput[] = [];
+    keep.forEach((originalPage, index) => {
+      for (let offset = 1; offset <= QUICK_ACTION_PAGE_SIZE; offset++) {
+        const source = byNumber.get((originalPage - 1) * QUICK_ACTION_PAGE_SIZE + offset);
+        actions.push({
+          action_number: index * QUICK_ACTION_PAGE_SIZE + offset,
+          label: source?.label ?? '',
+          icon: source?.icon ?? '',
+          ...(source?.sound !== undefined ? { sound: source.sound } : {}),
+          ...(source?.haptic_style !== undefined ? { haptic_style: source.haptic_style } : {}),
+          ...(source?.requires_ack !== undefined ? { requires_ack: source.requires_ack } : {}),
+          ...(source?.input_type !== undefined ? { input_type: source.input_type } : {}),
+        });
+      }
+    });
+    return this.updateLayout(inviteCode, {
+      base_action_ids: stored.map((a) => a.id).filter((id): id is string => typeof id === 'string'),
+      page_order: keep,
+      actions,
+    });
+  }
+}

package/src/namespaces/approvals.ts

@@ -0,0 +1,104 @@
+// `pr.approvals`: two-option human-in-the-loop decisions.
+
+import type { HttpClient } from '../http.js';
+import { assertStructuredData, requireNonEmpty } from '../internal/guards.js';
+import { pollUntilSettled } from '../internal/retry.js';
+import type {
+  Approval,
+  ApprovalInput,
+  WaitApprovalInput,
+  WaitForOutcomeOptions,
+} from '../types.js';
+import {
+  MIN_WAIT_POLL_INTERVAL_MS,
+  enc,
+  splitIdempotencyKey,
+  assertOnRetry,
+  dropUndefined,
+  waitTimeoutMs,
+} from '../internal/request.js';
+import {
+  isRecord,
+  isNonEmptyString,
+  isNullableString,
+  sameId,
+  invalidWaitResponse,
+} from '../internal/validate.js';
+
+const APPROVAL_STATUSES: ReadonlySet<string> = new Set(['pending', 'decided', 'expired', 'cancelled']);
+
+/**
+ * A wait response is trusted as an outcome only when it is the approval that
+ * was asked about, in a known status. A captive portal's HTML, `{}`, or another
+ * approval must not read as "decided".
+ */
+function validateApprovalWait(value: unknown, approvalId: string): Approval {
+  const status = isRecord(value) ? value['status'] : undefined;
+  if (
+    !isRecord(value)
+    || !sameId(value['id'], approvalId)
+    || typeof status !== 'string'
+    || !APPROVAL_STATUSES.has(status)
+    || !isNullableString(value['decided_at'])
+    // A gate acts on `decision`; a decided approval without one, or a pending
+    // one already stamped decided, is not an outcome it can act on.
+    || (status === 'decided' && !isNonEmptyString(value['decision']))
+    || (status === 'pending' && value['decided_at'] !== null)
+  ) {
+    return invalidWaitResponse('approval', approvalId, value, 'status');
+  }
+  return value as unknown as Approval;
+}
+
+export class ApprovalsApi {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Ask the human you act for to decide; returns the pending approval. */
+  request(inviteCode: string, input: ApprovalInput): Promise<Approval> {
+    requireNonEmpty(input.question, 'question');
+    assertStructuredData(input.data);
+    const { body, headers } = splitIdempotencyKey(input);
+    return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/approvals`, {
+      body: dropUndefined({ ...body }),
+      ...(headers ? { headers } : {}),
+    });
+  }
+
+  get(approvalId: string): Promise<Approval> {
+    return this.http.request('GET', `/api/agent/approvals/${enc(approvalId)}`);
+  }
+
+  /** One long-poll for the decision; returns the (possibly still-pending) approval. */
+  wait(approvalId: string, input: WaitApprovalInput = {}): Promise<Approval> {
+    return this.http.request('GET', `/api/agent/approvals/${enc(approvalId)}/wait`, {
+      query: dropUndefined({ timeout: input.timeout }),
+      timeoutMs: waitTimeoutMs(input.timeout),
+      ...(input.signal ? { signal: input.signal } : {}),
+    });
+  }
+
+  /**
+   * Block until the human decides (or the request expires or is cancelled),
+   * looping wait() under the hood, with polls started at least 2.1 s apart. A
+   * response that is not this approval in a known status 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 approval'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 waitForDecision(approvalId: string, input: WaitForOutcomeOptions = {}): Promise<Approval> {
+    requireNonEmpty(approvalId, 'approvalId');
+    assertOnRetry(input.onRetry);
+    return pollUntilSettled({
+      poll: () => this.wait(approvalId, input.signal ? { signal: input.signal } : {}),
+      validate: (value) => validateApprovalWait(value, approvalId),
+      settled: (approval) => approval.status !== 'pending',
+      expiresAt: (approval) => approval.expires_at,
+      what: `approval ${approvalId}`,
+      minIntervalMs: MIN_WAIT_POLL_INTERVAL_MS,
+      ...(input.signal ? { signal: input.signal } : {}),
+      ...(input.onRetry ? { onRetry: input.onRetry } : {}),
+    });
+  }
+}

package/src/namespaces/attachments.ts

@@ -0,0 +1,106 @@
+// `pr.attachments`: upload, read and discard private files.
+
+import { PingRoomError } from '../errors.js';
+import type { HttpClient } from '../http.js';
+import { requireNonEmpty } from '../internal/guards.js';
+import type { Attachment, ZipManifest, UploadAttachmentInput } from '../types.js';
+import { enc } from '../internal/request.js';
+
+/** Server cap per uploaded file; a larger body is a 413 the server answers before reading it. */
+const ATTACHMENT_MAX_BYTES = 5 * 1024 * 1024;
+
+function attachmentByteLength(content: UploadAttachmentInput['content']): number {
+  if (content instanceof Blob) return content.size;
+  if (typeof content === 'string') return new TextEncoder().encode(content).byteLength;
+  return content.byteLength;
+}
+
+/**
+ * Private files that a Ping or Question can carry.
+ *
+ * Upload first, then pass the returned ids to `broadcast()` / `questions.ask()`
+ * as `attachment_ids`. Bytes never travel inside a JSON ping body (the MCP
+ * `upload_attachment` tool takes only small files, about 90 KiB, as base64). An
+ * upload that is never attached expires on its own after 24 hours.
+ * Each file must be 1 byte–5 MiB with an md/pdf/html/txt/jpg/jpeg/png/zip filename;
+ * a Ping or Question accepts at most four ids.
+ *
+ * Uploading requires the bound account to hold Pro (the API answers 402
+ * `pro_required` otherwise). Reading and deleting are not gated.
+ */
+export class AttachmentsApi {
+  constructor(private readonly http: HttpClient) {}
+
+  /** Upload one file and get back the id a send can claim. */
+  upload(input: UploadAttachmentInput): Promise<Attachment> {
+    requireNonEmpty(input.filename, 'filename');
+    // The server answers an oversized body with 413 before reading it; refuse
+    // locally so no bytes travel for a file that can never be accepted.
+    if (attachmentByteLength(input.content) > ATTACHMENT_MAX_BYTES) {
+      return Promise.reject(
+        new PingRoomError('Attachments are at most 5 MiB each.', { code: 'attachment_too_large', status: 413 }),
+      );
+    }
+
+    const body = new FormData();
+    body.append('file', toAttachmentBlob(input), input.filename);
+
+    return this.http
+      .request<{ attachment: Attachment }>('POST', '/api/agent/attachments', {
+        body,
+        ...(input.signal ? { signal: input.signal } : {}),
+      })
+      .then((res) => res.attachment);
+  }
+
+  /**
+   * Raw bytes for an attachment this credential is allowed to see. Returns the
+   * undecoded Response so a caller can stream it, or read text/arrayBuffer.
+   */
+  content(attachmentId: string, signal?: AbortSignal): Promise<Response> {
+    requireNonEmpty(attachmentId, 'attachmentId');
+    return this.http.raw('GET', `/api/agent/attachments/${enc(attachmentId)}/content`, {
+      ...(signal ? { signal } : {}),
+    });
+  }
+
+  /**
+   * The listing of a `.zip`'s contents, recorded when it was uploaded.
+   *
+   * Resolves null for a non-archive, and for an archive whose central
+   * directory did not parse. Nothing decompresses the file to produce this, so
+   * the declared sizes are what the archive claims, not verified output.
+   */
+  manifest(attachmentId: string, signal?: AbortSignal): Promise<ZipManifest | null> {
+    requireNonEmpty(attachmentId, 'attachmentId');
+    return this.http
+      .request<{ manifest: ZipManifest | null }>(
+        'GET',
+        `/api/agent/attachments/${enc(attachmentId)}/manifest`,
+        { ...(signal ? { signal } : {}) },
+      )
+      .then((res) => res.manifest ?? null);
+  }
+
+  /** Discard an upload that has not been attached to a ping yet. */
+  delete(attachmentId: string): Promise<void> {
+    requireNonEmpty(attachmentId, 'attachmentId');
+    return this.http.request('DELETE', `/api/agent/attachments/${enc(attachmentId)}`);
+  }
+}
+
+/** Normalise the three accepted content shapes into one multipart part. */
+function toAttachmentBlob(input: UploadAttachmentInput): Blob {
+  const type = input.contentType ?? '';
+  if (input.content instanceof Blob) {
+    return type ? new Blob([input.content], { type }) : input.content;
+  }
+  // Copy into a plain ArrayBuffer: a Uint8Array view may be a window onto a
+  // larger (or SharedArrayBuffer-backed) buffer, which Blob would not accept.
+  const parts: BlobPart[] =
+    typeof input.content === 'string'
+      ? [input.content]
+      : [new Uint8Array(input.content).slice().buffer as ArrayBuffer];
+
+  return new Blob(parts, type ? { type } : undefined);
+}