@pingroom/sdk 0.8.0 → 0.9.0

package/src/types/handoffs.ts

@@ -0,0 +1,148 @@
+import type { JsonObject } from './common.js';
+import type { QuestionResponder } from './questions.js';
+
+// --- handoffs -------------------------------------------------------------
+//
+// A handoff is the Agent → one-human loop: DIRECT (exactly one human) and
+// PRIVATE (no other room member can read it). It's a façade over the ack and
+// question primitives, so its state space is the union of the two — kept
+// DISTINCT per kind:
+//
+//   ack      → open | acked | expired
+//   question → pending | answered | expired | cancelled
+//
+// A negative answer to a question handoff (e.g. `hold`/`deny`) is a SUCCESSFUL
+// `answered` state, not an error.
+
+/** Which primitive backs a handoff: an acknowledgement or a multi-option question. */
+export type HandoffKind = 'ack' | 'question';
+
+/** The lifecycle states of an `ack` handoff. Terminal: `acked`, `expired`. */
+export type HandoffAckState = 'open' | 'acked' | 'expired';
+
+/** The lifecycle states of a `question` handoff. Terminal: `answered`, `expired`, `cancelled`. */
+export type HandoffQuestionState = 'answered' | 'expired' | 'cancelled' | 'pending';
+
+/** The full handoff state space (union of ack + question states). */
+export type HandoffState = HandoffAckState | HandoffQuestionState;
+
+/**
+ * Whether the ping was enqueued, remains pending dispatch, or exhausted its
+ * retry budget (`failed`). Only populated on create; null on reads.
+ */
+export type HandoffDeliveryState = 'enqueued' | 'pending' | 'failed';
+
+/** One option offered on a `question` handoff. A bare string is shorthand for `{ value, label: value }`. */
+export interface HandoffOptionInput {
+  /** Stable machine token returned as the answer. */
+  value: string;
+  /** Human text on the button (defaults to `value`). */
+  label?: string;
+  /** Presentation hint: `primary` = affirmative, `danger` = cancel/negative. */
+  style?: 'primary' | 'danger' | 'default';
+}
+
+export type HandoffOptionSpec = string | HandoffOptionInput;
+
+/** A resolved option on the handoff wire shape. */
+export interface HandoffOption {
+  value: string;
+  label: string;
+  [key: string]: unknown;
+}
+
+/** The human who acknowledged an `ack` handoff (present once `state === 'acked'`). */
+export interface HandoffAcker {
+  /** Null when the actor is redacted (reader-privacy). */
+  id: string | null;
+  display_name: string | null;
+}
+
+/** The resolution of a `question` handoff (present once `state === 'answered'`). */
+export interface HandoffAnswer {
+  /** The chosen option's `value`, or null for a text-only answer. */
+  value: string | null;
+  /** The chosen option's `label`. */
+  label: string | null;
+  /** The typed answer, when the question invited one. */
+  text: string | null;
+  /** The authenticated human who answered. */
+  responder: QuestionResponder | null;
+  answered_at: string | null;
+}
+
+/**
+ * The public handoff wire shape — identical across create / get / wait / list.
+ * `options`/`answer` appear on question handoffs; `acked_by`/`acked_at` on ack
+ * handoffs.
+ */
+export interface Handoff {
+  id: string;
+  kind: HandoffKind;
+  prompt: string;
+  state: HandoffState;
+  /** Delivery status, populated only on create; null on reads. */
+  delivery_state: HandoffDeliveryState | null;
+  correlation_id: string | null;
+  reply_to: string | null;
+  data: JsonObject | null;
+  expires_at: string | null;
+  created_at: string | null;
+  /** ack handoff: the human who acknowledged (once `state === 'acked'`). */
+  acked_by?: HandoffAcker | null;
+  /** ack handoff: when it was acknowledged. */
+  acked_at?: string | null;
+  /** question handoff: the offered options. */
+  options?: HandoffOption[];
+  /** question handoff: the resolution (once `state === 'answered'`). */
+  answer?: HandoffAnswer | null;
+  /**
+   * Question handoffs used for Agent Inbox onboarding expose whether the
+   * server recorded the exact delivery + answer + agent-observation event.
+   */
+  activation_completed?: boolean;
+  [key: string]: unknown;
+}
+
+/** Ask a human to acknowledge (the ack handoff). Resolves on the first acknowledgement. */
+export interface RequestAckInput {
+  /** What the human reads (required, ≤ 500 chars). */
+  prompt: string;
+  /**
+   * Who to reach: `me`, the bound human (the default). The bound human's own
+   * user id is accepted as an alias; any other id is refused with 403
+   * `target_not_permitted`.
+   */
+  target?: string;
+  /** Seconds until expiry. Clamped server-side to 120–86400; default 900. */
+  expiresIn?: number;
+  /** Interruption level — `active` (default) or `passive`. */
+  urgency?: 'active' | 'passive';
+  correlationId?: string;
+  replyTo?: string;
+  data?: JsonObject;
+  /**
+   * Idempotency key — same key + same body replays the original resource; a
+   * different body for the same key returns a 409 `idempotency_conflict`.
+   * Reuse it verbatim on network retries. 1–255 printable ASCII characters
+   * (spaces allowed); an empty string sends no key.
+   */
+  idempotencyKey?: string;
+}
+
+/** Ask a human a multi-option question (the question handoff). Resolves on the first tapped answer. */
+export interface AskInput extends RequestAckInput {
+  /** 2–4 options. A bare string is shorthand for `{ value, label: value }`. */
+  options: HandoffOptionSpec[];
+}
+
+export interface WaitHandoffInput {
+  /** Seconds the server holds the connection (server caps at 25s; default 20). */
+  timeout?: number;
+  signal?: AbortSignal;
+}
+
+export interface ListHandoffsInput {
+  /** `open` for unresolved work, or `all` for recent history (up to 200 per kind). */
+  state?: 'open' | 'all';
+}

package/src/types/inbox.ts

@@ -0,0 +1,64 @@
+import type {
+  HandoffQuestionState,
+  HandoffOption,
+  HandoffAnswer,
+  Handoff,
+  WaitHandoffInput,
+} from './handoffs.js';
+
+// --- Agent Inbox ---------------------------------------------------------
+
+/** Idempotent first-connect result from POST /api/agent/inbox/ensure. */
+export interface AgentInboxEnsureResult {
+  onboarded: true;
+  replayed: boolean;
+  room: {
+    id: string;
+    name: string;
+    invite_code: string;
+    is_agent_inbox: boolean;
+  };
+  question: {
+    id: string;
+    kind: 'question';
+    prompt: string;
+    options: HandoffOption[];
+    state: HandoffQuestionState;
+    expires_at: string | null;
+    created_at: string | null;
+  };
+}
+
+/** Cancellation for the idempotent Agent Inbox ensure request. */
+export interface AgentInboxEnsureInput {
+  signal?: AbortSignal;
+}
+
+/**
+ * Controls the activation handoff wait. `timeout` is the duration of each
+ * bounded server hold; a still-pending response is polled again until the
+ * server confirms activation, the Question expires/cancels, the overall
+ * deadline elapses, or `signal` is aborted.
+ */
+export interface AgentInboxActivateInput extends WaitHandoffInput {
+  /**
+   * Wall-clock limit for ensure + every pending long-poll combined. Defaults
+   * to 120000 (two minutes). Distinct from `timeout`, which controls one hold.
+   */
+  overallTimeoutMs?: number;
+}
+
+/** The terminal question returned by a completed Agent Inbox activation. */
+export type AgentInboxActivationQuestion =
+  Handoff & {
+    kind: 'question';
+    state: 'answered';
+    answer: HandoffAnswer;
+    activation_completed: true;
+  };
+
+/** `ensure` metadata plus the terminal, fully resolved onboarding handoff. */
+export type AgentInboxActivationResult = Omit<AgentInboxEnsureResult, 'question'> & {
+  activation_completed: true;
+  question: AgentInboxActivationQuestion;
+};

package/src/types/notifications.ts

@@ -0,0 +1,393 @@
+import type { JsonObject } from './common.js';
+import type { Room } from './rooms.js';
+import type { Question } from './questions.js';
+
+// --- pings / notifications ------------------------------------------------
+
+/** A visible Ping — used for broadcasts and the retired direct-ping compatibility method. */
+export interface PingInput {
+  /** Visible body (≤ 120 characters in private rooms; ≤ 160 in public rooms). */
+  message: string;
+  /** Optional visible title (≤ 40 characters). */
+  title?: string;
+  action_number?: number;
+  action_icon?: string;
+  /**
+   * Structured data echoed on every read surface (<= 25 keys / 8KB).
+   * Reserved keys `url` + `button_label` make the ping a tappable link —
+   * see the `linkPing()` helper. Reserved `location` carries finite numeric
+   * latitude/longitude plus an optional label/address — see `locationPing()`.
+   */
+  data?: JsonObject;
+  correlation_id?: string;
+  reply_to?: string;
+  /**
+   * Ordered ids from `attachments.upload()` (max 4). Ids are single-use: the
+   * send claims them, and an already-claimed or expired id fails the whole
+   * ping. File bytes never ride this JSON body.
+   */
+  attachment_ids?: string[];
+  /**
+   * Open the acknowledgement lifecycle for this ping. The ack_mode rule
+   * determines when it resolves, and recipients see a lock-screen card with an Acknowledge button.
+   *
+   * Does NOT raise the delivery priority — that is {@link PingInput.is_urgent},
+   * and the two are independent. They were one flag, which meant asking for a
+   * ping that cuts through Focus also demanded that somebody acknowledge it.
+   */
+  requires_ack?: boolean;
+  /** Confirmation rule; defaults to any. all waits for every original eligible recipient. */
+  ack_mode?: AckMode;
+  /**
+   * Deliver time-sensitive so the ping breaks through Focus / Do Not Disturb
+   * and reaches members who muted the room or you (a block still wins).
+   * Delivery priority only: no acknowledgement, no Live Activity, nothing asked
+   * of the recipient. Set alongside `requires_ack` for an acknowledgement that
+   * also cuts through Focus.
+   */
+  is_urgent?: boolean;
+  /**
+   * Optional acknowledgement deadline in seconds (60–86400). Omit/null for no
+   * deadline. Validated on every send, so an out-of-range value is a 422 even
+   * without `requires_ack`; it takes effect only when the ping requires
+   * acknowledgement.
+   */
+  ack_timeout_seconds?: number | null;
+  /**
+   * 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 sending the ping again.
+   */
+  idempotencyKey?: string;
+}
+
+/**
+ * Safe attachment metadata. Storage keys, checksums, owner ids, and permanent
+ * URLs are deliberately not part of this contract — read the bytes through
+ * `attachments.content()` with the credential that can see the ping.
+ */
+export interface Attachment {
+  id: string;
+  filename: string;
+  mime_type: string;
+  size_bytes: number;
+  created_at: string;
+}
+
+/** The file types the attachment endpoint accepts. */
+/** One row of a `.zip` attachment's listing. */
+export interface ZipManifestEntry {
+  name: string;
+  /** Null when the archive declared no size, or declared a ZIP64 sentinel. */
+  size_bytes: number | null;
+  is_directory: boolean;
+}
+
+/**
+ * A `.zip` attachment's contents as recorded at upload. Bounded server-side, so
+ * `entries` may be shorter than `total_entries`.
+ */
+export interface ZipManifest {
+  entries: ZipManifestEntry[];
+  total_entries: number;
+  truncated: boolean;
+  /** Sum of the sizes the archive DECLARES. Nothing verifies or expands them. */
+  total_uncompressed_bytes: number;
+}
+
+export type AttachmentExtension =
+  | 'md'
+  | 'pdf'
+  | 'html'
+  | 'txt'
+  | 'jpg'
+  | 'jpeg'
+  | 'png'
+  | 'zip';
+
+export interface UploadAttachmentInput {
+  /** File bytes (1 byte–5 MiB). A Blob/File, a Uint8Array, or a UTF-8 string. */
+  content: Blob | Uint8Array | string;
+  /** Display filename. Its extension must be one of AttachmentExtension. */
+  filename: string;
+  /** Overrides the type sent in the multipart part. Usually inferred is fine. */
+  contentType?: string;
+  signal?: AbortSignal;
+}
+
+export interface TriggerInput {
+  /**
+   * Only the sources a device legitimately originates; `webhook`/`system` are
+   * stamped server-side and are rejected here. `manual` (the default) presses
+   * the slot.
+   *
+   * `location` is the device-geofence source, not a press modifier. It is for
+   * the ROOM OWNER only and sends the owner's Location Ping (an "Arrived at
+   * {place}" or "Left {place}" Ping to every member, with no action number)
+   * INSTEAD of the quick action in the slot. A caller who is not the room owner
+   * gets `403 location_trigger_owner_only`; a room with no enabled location
+   * trigger (or none that listens for the reported crossing) gets
+   * `409 location_trigger_inactive`; the operator's Location Pings switch being
+   * off gets `403 feature_disabled`. `is_urgent` and `requires_ack` still apply
+   * to it. To press a Quick Ping leave this unset.
+   */
+  trigger_source?: 'manual' | 'location';
+  /**
+   * Deliver this one press time-sensitive so it breaks through Focus / Do Not
+   * Disturb and reaches members who muted the room or you (a block still
+   * wins). Send-time only — the action's saved configuration is untouched,
+   * and quick actions have no stored urgency policy to override. Never implies
+   * `requires_ack`, which is the action's own saved acknowledgement policy.
+   */
+  is_urgent?: boolean;
+  /**
+   * One-shot acknowledgement modifier for this press only. It is OR-ed with the
+   * action's stored policy, so it can only ADD an ack requirement — passing
+   * `false` never removes one from an action already configured to require it.
+   * The action's saved configuration is untouched either way.
+   */
+  requires_ack?: boolean;
+  /** Applies to this press only, when its effective acknowledgement policy is enabled. */
+  ack_mode?: AckMode;
+  /**
+   * The detail this press carries when the action has an `input_type`. Only
+   * `location` and `url` are accepted on a trigger — no `button_label`; build
+   * the fragments with `locationPing()` / `linkPing()` or pass them directly.
+   */
+  data?: TriggerData;
+  /**
+   * Ids from `attachments.upload()`, at most 4. Required when `input_type` is
+   * `file`, `photo` (jpg/png only) or `pdf` (pdf only); a mismatched type is
+   * `422 quick_action_input_type`.
+   */
+  attachment_ids?: string[];
+  /**
+   * The action's `id` as read from `actions.list()`. When that slot has since
+   * moved pages the press is refused with `409 quick_action_layout_changed`
+   * rather than firing the wrong Ping.
+   */
+  quick_action_id?: string;
+  /**
+   * 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 firing the press again.
+   */
+  idempotencyKey?: string;
+}
+
+/** The closed `data` object a quick-action press may carry. */
+export interface TriggerData {
+  location?: TriggerLocation;
+  /** Absolute http(s) URL, at most 2048 characters. */
+  url?: string;
+}
+
+/** Same shape as `LocationPingLocation`; declared here to keep types.ts import-free. */
+export interface TriggerLocation {
+  latitude: number;
+  longitude: number;
+  label?: string;
+  address?: string;
+}
+
+export type AckMode = 'any' | 'all';
+
+/** The server-authoritative acknowledgement lifecycle attached to a ping. */
+export interface ActionState {
+  /** Omitted by older servers and by the default any mode. */
+  mode?: AckMode;
+  confirmed_count?: number;
+  required_count?: number;
+  /** REST only; public rooms redact identities and MCP omits them. */
+  confirmed_user_ids?: string[];
+  status: 'open' | 'acked' | 'expired' | null;
+  requires_ack: boolean;
+  acked_by: {
+    id: string | null;
+    name: string | null;
+    profile_image: string | null;
+  } | null;
+  acked_at: string | null;
+  expires_at: string | null;
+  /** Set when the confirmation window was closed early. */
+  ended_at?: string | null;
+  /** Viewer-specific human mutation eligibility; agent read paths return false. */
+  can_ack?: boolean;
+  /** Recipients who dismissed the card without confirming. Never counts as a confirmation. */
+  dismissed_count?: number;
+  /** REST only; public rooms redact identities and MCP omits them. */
+  dismissed_user_ids?: string[];
+  /** Viewer-scoped: when the reading viewer dismissed it. */
+  dismissed_at?: string | null;
+}
+
+/**
+ * Who cannot show Confirm for this ping. A recipient with no capable device
+ * gets a plain alert, so their confirmation may never come. `checked: false`
+ * means nothing was checked (public rooms, rooms over 100 recipients, a failed
+ * lookup), not that everyone is reachable. Absent unless `requires_ack`.
+ */
+export type ConfirmationReach =
+  | { checked: true; unavailable_user_ids: string[]; unavailable_count: number }
+  | { checked: false };
+
+export interface PingResult {
+  id: string;
+  message: string;
+  action_number: number | null;
+  action_icon: string | null;
+  trigger_source: string | null;
+  data?: JsonObject | null;
+  correlation_id?: string | null;
+  reply_to?: string | null;
+  attachments?: Attachment[];
+  action_state?: ActionState | null;
+  created_at: string;
+  recipient_count?: number;
+  muted_count?: number;
+  confirmation_reach?: ConfirmationReach;
+  [key: string]: unknown;
+}
+
+/**
+ * The named fields of a listened/listed notification, without the index
+ * signature. `Omit` collapses a type carrying a string index signature down to
+ * that signature alone, so `NotificationDetail` derives from this rather than
+ * from `AgentNotification` — otherwise every named field would widen to
+ * `unknown`.
+ */
+interface AgentNotificationFields {
+  id: string;
+  message: string;
+  action_number: number | null;
+  action_icon: string | null;
+  trigger_source: string | null;
+  /**
+   * True when this ping is an agent handoff (a request to take over a
+   * conversation) rather than an ordinary ping.
+   */
+  is_handoff?: boolean;
+  data?: JsonObject | null;
+  correlation_id?: string | null;
+  reply_to?: string | null;
+  attachments?: Attachment[];
+  action_state?: ActionState | null;
+  /** Confirmation rule the ping was sent with; absent on older rows. */
+  ack_mode?: AckMode;
+  /**
+   * Delivered without sound/haptics (the sender's silent mode at send time).
+   * `null` on rows written before 2026-09-16; not surfaced through MCP.
+   */
+  is_silent?: boolean | null;
+  /**
+   * The embedded Question when this ping carries one, else null. Same wire
+   * shape as the dedicated Question read paths.
+   */
+  question?: Question | null;
+  created_at: string;
+  room?: { code: string; name: string; icon: string | null; color: string | null };
+  sender?: { id: string; name: string | null };
+  /**
+   * Present when a connected agent (MCP / CLI credential) originated the
+   * ping: the agent registration's display identity. Null/absent on human,
+   * webhook, and trigger rows.
+   */
+  origin_agent?: {
+    id?: string;
+    handle: string | null;
+    display_name: string | null;
+    avatar_url?: string | null;
+  } | null;
+}
+
+export interface AgentNotification extends AgentNotificationFields {
+  [key: string]: unknown;
+}
+
+/** Full notification record returned by the single-notification read path. */
+export type NotificationDetail = Omit<AgentNotificationFields, 'room'> & {
+  room_id?: string;
+  sender_id?: string;
+  type?: string;
+  requires_ack?: boolean;
+  /** Whether this ping was delivered time-sensitive. Independent of `requires_ack`. */
+  is_urgent?: boolean;
+  action_state: ActionState | null;
+  room?: Room;
+  [key: string]: unknown;
+};
+
+/** History keeps the full room and adds the listener-compatible `room.code`. */
+export interface NotificationHistoryEntry extends AgentNotification {
+  room?: Room & { code: string };
+}
+
+export interface ListNotificationsInput {
+  /** `received` or `sent`; the server refuses any other value. */
+  type?: 'received' | 'sent';
+  room_id?: string;
+  date?: string;
+  /** Page size (1–25). Omit to retain the server's legacy default. */
+  limit?: number;
+  /** Page number, starting at 1. */
+  page?: number;
+  /** @deprecated Use limit. Sent as limit when limit is absent. */
+  notifications_per_page?: number;
+}
+
+export interface WaitInput {
+  /** Cursor (a notification id). Omit to start from the current head. */
+  after?: string;
+  /** Seconds to hold the connection (0–30, default 20). */
+  timeout?: number;
+  /** Max notifications to return (1–100, default 50). */
+  limit?: number;
+  signal?: AbortSignal;
+}
+
+export interface WaitResult {
+  notifications: AgentNotification[];
+  cursor: string;
+}
+
+export interface WaitForAcknowledgementInput {
+  /** Seconds to hold the connection (0–30, default 20). */
+  timeout?: number;
+  signal?: AbortSignal;
+}
+
+export interface AcknowledgementWaitResult {
+  id: string;
+  action_state: ActionState;
+}
+
+export interface ListenInput {
+  /** Cursor (a notification id). Omit to start from the current head. */
+  after?: string;
+  /**
+   * Seconds each poll holds the connection (0–30, default 20). Polls start at
+   * least 2.1 s apart after an empty answer, so `0` (or a proxy that answers
+   * early) cannot use up the wait route's 30-per-minute limit, which is shared
+   * with the human's other listeners.
+   */
+  timeout?: number;
+  /** Max notifications per poll (1–100, default 50). */
+  limit?: number;
+  signal?: AbortSignal;
+  /**
+   * Called with each transient error (network failure, request timeout, 429,
+   * 5xx) before the loop backs off and retries; transient errors are retried
+   * whether or not this is set. Any other error (401, 403, 422, …) ends the
+   * iterator by throwing, so a revoked credential never retries forever.
+   */
+  onError?: (err: unknown) => void;
+  /**
+   * First backoff after a transient error, in ms (default 1000, minimum 250:
+   * a smaller value is raised to 250, so a persistent failure never retries in
+   * a tight loop against the shared wait limit). It doubles on each consecutive
+   * failure up to 30 s; a server `retryAfter` replaces it.
+   */
+  backoffMs?: number;
+}

package/src/types/profile.ts

@@ -0,0 +1,37 @@
+// --- profile --------------------------------------------------------------
+
+export interface RotateHandleResult {
+  handle: string;
+  [key: string]: unknown;
+}
+
+// --- directory ------------------------------------------------------------
+
+export type PingPolicy = 'open' | 'members' | 'closed' | (string & {});
+export type ActivityBucket = 'active_now' | 'today' | 'this_week' | 'quiet' | (string & {});
+
+export interface DirectoryEntry {
+  handle: string;
+  display_name: string;
+  tagline: string;
+  tags: string[];
+  icon: string | null;
+  color: string | null;
+  ping_policy: PingPolicy;
+  is_featured: boolean;
+  operated_by: string | null;
+  last_active: ActivityBucket;
+}
+
+export interface DirectoryProfile extends DirectoryEntry {
+  description: string | null;
+  listed_at: string | null;
+  card_url: string | null;
+}
+
+export interface DirectoryListInput {
+  search?: string;
+  tag?: string;
+  per_page?: number;
+  page?: number;
+}