@pingroom/sdk 0.8.0 → 0.9.0

package/dist/types.d.ts

@@ -5,1203 +5,13 @@
  * SDK is a faithful, reviewable wrapper — what you pass is what the API sees.
  * SDK-only knobs (timeouts, signals, callbacks) use camelCase.
  */
-import type { PingRoomError } from './errors.js';
-/** 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 & {});
-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;
-}
-/** 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;
-}
-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;
-}
-/**
- * The detail every press of a quick action must carry. `location` needs
- * `data.location`, `link` needs `data.url`, `file`/`photo`/`pdf` need
- * `attachment_ids` (photo: jpg/png only, pdf: pdf only). A press without it is
- * refused with `422 quick_action_input_required` and nothing is sent.
- */
-export type QuickActionInputType = 'none' | 'location' | 'link' | 'file' | 'photo' | 'pdf';
-export interface QuickActionInput {
-    action_number: number;
-    label: string;
-    /**
-     * Emoji or icon id. Sending `label` and `icon` both empty reserves the slot
-     * as disabled: it stays in the layout and a press answers `404
-     * action_not_configured`.
-     */
-    icon: string;
-    sound?: string | null;
-    haptic_style?: string | null;
-    /** Every fire of this reusable action opens the acknowledgement lifecycle. */
-    requires_ack?: boolean;
-    /** Omit to keep the stored value; new slots default to `none`. */
-    input_type?: QuickActionInputType;
-}
-/**
- * Body of `actions.updateLayout()`. `page_order` lists the new page positions:
- * each entry is the ORIGINAL page number (1–4) to keep at that index, or
- * `null` for a fresh blank page; original pages absent from the list are
- * deleted. `actions` is the full renumbered 4–16 set. `base_action_ids` is
- * every stored action id in `action_number` order as last read — a stale
- * snapshot is refused with `409 quick_action_layout_changed`.
- */
-export interface UpdateQuickActionLayoutInput {
-    base_action_ids: string[];
-    page_order: Array<number | null>;
-    actions: QuickActionInput[];
-}
-export interface CreateRoomInput {
-    name: string;
-    icon: string;
-    color: string;
-}
-export interface CreatePublicRoomInput extends CreateRoomInput {
-    handle: string;
-    description?: string;
-    everyone_can_trigger?: boolean;
-    is_password_protected?: boolean;
-    password?: string;
-    actions?: QuickActionInput[];
-    category?: string;
-    show_owner?: boolean;
-    /**
-     * Public-room location for nearby discovery. Send all three or none —
-     * `createPublic()` rejects a partial trio locally, the server with a 422.
-     */
-    location_name?: string;
-    location_latitude?: number;
-    location_longitude?: number;
-}
-export interface JoinRoomInput {
-    invite_code: string;
-    password?: string;
-}
-export interface UpdateQuickActionInput {
-    /**
-     * The Ping's title. Must be sent, but may be `''` — a Ping can be named by
-     * its emoji alone, and the app renders an untitled one as just the emoji.
-     */
-    label: string;
-    icon: string;
-    sound?: string | null;
-    haptic_style?: string | null;
-    /** Every fire of this reusable action opens the acknowledgement lifecycle. */
-    requires_ack?: boolean;
-    /** Omit to keep the stored value. */
-    input_type?: QuickActionInputType;
-}
-export interface QuickAction {
-    id?: string;
-    action_number: number;
-    label: string;
-    icon: string;
-    sound?: string | null;
-    haptic_style?: string | null;
-    /** Every fire of this reusable action opens the acknowledgement lifecycle. */
-    requires_ack?: boolean;
-    /** Missing on pre-2026-09-16 rows; treat absent as `none`. */
-    input_type?: QuickActionInputType;
-    [key: string]: unknown;
-}
-export interface Room {
-    id: string;
-    name: string;
-    icon: string | null;
-    color: string | null;
-    invite_code: string;
-    is_public?: boolean;
-    handle?: string | null;
-    quick_actions?: QuickAction[];
-    /** 4, or 16 while the room owner is Pro. */
-    quick_action_limit?: 4 | 16;
-    /** Every stored slot, including pages hidden by a lapsed Pro. */
-    quick_action_count?: number;
-    location_name?: string | null;
-    location_latitude?: number | null;
-    location_longitude?: number | null;
-    [key: string]: unknown;
-}
-/** Catalog ids accepted by room and webhook creation. */
-export interface RoomIconCatalog {
-    version: number;
-    base_url: string;
-    categories: Array<{
-        id: string;
-        label: string;
-        icons: string[];
-    }>;
-    icons: Record<string, {
-        file: string;
-        tags: string[];
-    }>;
-}
-export interface CreateWebhookInput {
-    name: string;
-    title?: string | null;
-    message?: string | null;
-    emoji?: string | null;
-    icon?: string | null;
-    color?: string | null;
-    sound?: string | null;
-    haptic?: string | null;
-    /** Optional Quick Ping preset. Omit or use null for an independent webhook. */
-    action_number?: number | null;
-    enabled?: boolean;
-    cooldown_seconds?: number;
-}
-export interface UpdateWebhookInput extends Partial<CreateWebhookInput> {
-    /** Rotate the trigger URL; the previous URL stops working. */
-    regenerate_secret?: boolean;
-}
-/** Incoming webhook configuration. The trigger URL contains its credential. */
-export interface Webhook {
-    id: string;
-    room_id: string;
-    name: string;
-    title: string | null;
-    message: string | null;
-    emoji: string | null;
-    icon: string | null;
-    color: string | null;
-    sound: string | null;
-    haptic: string | null;
-    /** Null when the webhook uses its own content without a Quick Ping preset. */
-    action_number: number | null;
-    enabled: boolean;
-    cooldown_seconds: number;
-    trigger_count: number;
-    last_triggered_at?: string | null;
-    webhook_url: string;
-    created_at: string;
-    updated_at: string;
-    [key: string]: unknown;
-}
-/** 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.
-     */
-    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;
-}
-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;
-    [key: string]: unknown;
-}
-export interface DirectPingResult {
-    id: string;
-    target_handle: string;
-    room_code: string;
-    message: string;
-    correlation_id: string | null;
-    reply_to: string | null;
-    action_state?: ActionState | null;
-    created_at: string;
-    [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 {
-    after?: string;
-    timeout?: number;
-    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). It doubles on
-     * each consecutive failure up to 30 s; a server `retryAfter` replaces it.
-     */
-    backoffMs?: number;
-}
-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;
-}
-/**
- * The authenticated human who answered a Question or handoff (never
- * caller-supplied).
- *
- * Every field is redacted to `null` together when the caller is not entitled to
- * see who answered, which is why `id` is nullable even on a decided question.
- * The server sends all five fields from both `QuestionPresenter::responder` and
- * the handoff presenter; the type previously declared only `id` and
- * `display_name`, and being a closed object type that made the avatar fields
- * unreachable without a cast.
- */
-export interface QuestionResponder {
-    id: string | null;
-    display_name: string | null;
-    profile_image_url: string | null;
-    emoji: string | null;
-    color: string | null;
-}
-/** The lifecycle states of a Question. Terminal states are immutable. */
-export type QuestionState = 'pending' | 'answered' | 'expired' | 'cancelled';
-/** Who may answer: `direct` (one named person) or `room` (any eligible member). */
-export type ResponderScope = 'direct' | 'room';
-/**
- * How a room Question resolves: `first` (the default — the first valid answer
- * wins) or `all` (a poll — everyone asked votes once; it closes when they all
- * have, or at its deadline).
- */
-export type QuestionResolutionPolicy = 'first' | 'all';
-/** One option offered on a Question. A bare string is shorthand for `{ value, label: value }`. */
-export interface QuestionOptionInput {
-    /** Stable machine token returned as the answer (1–40 chars, unique per question). */
-    value: string;
-    /** Human text on the button (defaults to `value`; 1–40 chars). */
-    label?: string;
-    /** Presentation hint: `primary` = brand-strike affirmative, `danger` = cancel. */
-    style?: 'primary' | 'danger' | 'default';
-    /** Legacy boolean form of `style: 'primary'`. */
-    primary?: boolean;
-    /** Legacy boolean form of `style: 'danger'`. */
-    destructive?: boolean;
-}
-export type QuestionOptionSpec = string | QuestionOptionInput;
-/** Invite a short typed answer, on its own (text-only) or alongside options. */
-export interface QuestionTextInput {
-    placeholder?: string;
-    /** 1–60 (default 60). A value outside that range is refused with a 422. */
-    max_length?: number;
-}
-export interface QuestionInput {
-    /** The question the human reads (required, ≤ 500 chars). */
-    prompt: string;
-    /** Optional secondary line, e.g. a build number (≤ 40 chars). */
-    context?: string;
-    /** 2–4 options. Omit for the binary Approve/Deny default (the lock-screen fast path). */
-    options?: QuestionOptionSpec[];
-    /** Offer a typed answer instead of / alongside options. */
-    text_input?: QuestionTextInput;
-    /** `direct` (defaults to your bound user) or `room` (any eligible member). Default `direct`. */
-    responder_scope?: ResponderScope;
-    /**
-     * `first` (default) or `all` to poll the room: every member except your bound
-     * human gets one final vote. A poll implies `room` scope when
-     * `responder_scope` is omitted, and cannot be combined with
-     * `responder_scope: 'direct'`, `target_user_id`, or `text_input`. If your
-     * bound human is the room's only member the server falls back to a `direct`
-     * `first` Question — check `resolution_policy` on the returned Question.
-     */
-    resolution_policy?: QuestionResolutionPolicy;
-    /** For `direct` scope: a specific room member (UUID). Defaults to the bound user. */
-    target_user_id?: string;
-    /** Seconds until expiry. Omit for the server default (1h); clamped to 30–86400. A poll with at least one vote closes `answered` at this deadline. */
-    ttl?: number;
-    data?: JsonObject;
-    correlation_id?: string;
-    reply_to?: string;
-    /** Ordered ids from `attachments.upload()` (max 4). Same single-use rules as PingInput. */
-    attachment_ids?: string[];
-    /**
-     * Sent as the `Idempotency-Key` header (1–255 printable ASCII characters,
-     * spaces allowed). Reuse this key when retrying the same question creation.
-     */
-    idempotencyKey?: string;
-}
-/** A resolved option on the Question wire shape. */
-export interface QuestionOption {
-    value: string;
-    label: string;
-    primary?: boolean;
-    destructive?: boolean;
-    [key: string]: unknown;
-}
-/**
- * The resolution, present once `state === 'answered'` — except on a tied poll,
- * which is `answered` with a null `answer` (read `results` instead).
- */
-export interface QuestionAnswer {
-    /** The chosen option's `value` (a poll's leading option), 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. Always null on a poll. */
-    text: string | null;
-    /**
-     * The authenticated human who answered (never caller-supplied). Present once
-     * the question is decided — but every field is redacted to `null` when the
-     * caller is not entitled to see who answered, so `id` is nullable even here.
-     * Null on a poll: the room chose the answer, and the voters are in
-     * `results.responses`. Matches `HandoffAnswer.responder`.
-     */
-    responder: QuestionResponder | null;
-    answered_at: string | null;
-}
-/** One option's tally in a poll's {@link QuestionPollResults}. */
-export interface QuestionPollOptionResult {
-    value: string;
-    label: string;
-    /** Votes cast for this option (0 when nobody chose it). */
-    count: number;
-}
-/** One cast vote in a poll's {@link QuestionPollResults.responses}. */
-export interface QuestionPollResponse {
-    value: string;
-    label: string;
-    /** Who voted. Every field is `null` when the caller may not see who answered. */
-    responder: QuestionResponder;
-    answered_at: string | null;
-}
-/** The reading person's own seat in a poll. */
-export interface QuestionPollViewer {
-    /** Whether the poll asked this person. */
-    asked: boolean;
-    /** The value they voted, or null until they vote. */
-    response: string | null;
-}
-/**
- * A poll's tally (`resolution_policy: 'all'`). Present on every read of a poll
- * — including while it is still `pending` — and `null` on a `first` Question.
- */
-export interface QuestionPollResults {
-    /** People the poll asked, fixed when it was created. */
-    audience_count: number;
-    /** Votes cast so far (exact). */
-    response_count: number;
-    /** Every option, in display order, with its count. */
-    options: QuestionPollOptionResult[];
-    /** Up to the 100 most recent votes, oldest first. */
-    responses: QuestionPollResponse[];
-    /** Only on a signed-in person's own surfaces; always `null` on agent reads and webhook events. */
-    viewer: QuestionPollViewer | null;
-}
-/** The public Question wire shape — identical across ask / get / wait / list. */
-export interface Question {
-    id: string;
-    /** Canonical delivery notification when supplied by the server. */
-    notification_id?: string | null;
-    kind: 'question';
-    prompt: string;
-    context: string | null;
-    options: QuestionOption[];
-    text_input: {
-        placeholder: string | null;
-        max_length: number;
-    } | null;
-    responder_scope: ResponderScope;
-    target_user_id: string | null;
-    /** `first` or `all` (a poll). Open-ended so a future policy does not break callers. */
-    resolution_policy: QuestionResolutionPolicy | (string & {});
-    state: QuestionState;
-    /** Null until answered, and on a tied poll even once `answered`. */
-    answer: QuestionAnswer | null;
-    /** A poll's tally; `null` on a `first` Question (absent on servers before Question Protocol 1.3). */
-    results?: QuestionPollResults | null;
-    expires_at: string | null;
-    resolved_at: string | null;
-    correlation_id: string | null;
-    reply_to: string | null;
-    data: JsonObject | null;
-    created_at: string | null;
-    room?: {
-        code: string;
-        name: string;
-        icon: string | null;
-        color: string | null;
-    };
-    room_code?: string;
-    asker?: {
-        /**
-         * `'user'` for a human-asked Question (composer "Add Options"), `'agent'`
-         * when an agent asked it. Both reach an agent's listen/list feed, so this
-         * cannot be narrowed to `'agent'`.
-         */
-        type: 'agent' | 'user';
-        id: string | null;
-        handle: string | null;
-        display_name: string | null;
-        avatar_url: string | null;
-    };
-    [key: string]: unknown;
-}
-export interface WaitQuestionInput {
-    /** Seconds the server holds the connection (0–30, default 20). */
-    timeout?: number;
-    signal?: AbortSignal;
-}
-export interface ListQuestionsInput {
-    /** Filter by state; `all` returns every state. Omit for the recent window across states. */
-    state?: QuestionState | 'all';
-}
-/** 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';
-}
-/** 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;
-};
-export interface RotateHandleResult {
-    handle: string;
-    [key: string]: unknown;
-}
-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;
-}
-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;
-}
-export {};
+export type * from './types/common.js';
+export type * from './types/auth.js';
+export type * from './types/rooms.js';
+export type * from './types/notifications.js';
+export type * from './types/approvals.js';
+export type * from './types/questions.js';
+export type * from './types/handoffs.js';
+export type * from './types/inbox.js';
+export type * from './types/profile.js';
 //# sourceMappingURL=types.d.ts.map