@pingroom/sdk 0.7.1 → 0.9.0

package/dist/types/auth.d.ts

@@ -0,0 +1,185 @@
+import type { ScopeInput } from './common.js';
+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;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/types/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/types/auth.ts"],"names":[],"mappings":"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"}

package/dist/types/auth.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth.js.map

package/dist/types/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/types/auth.ts"],"names":[],"mappings":""}

package/dist/types/common.d.ts

@@ -0,0 +1,43 @@
+/** 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 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;
+}
+//# sourceMappingURL=common.d.ts.map

package/dist/types/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/types/common.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,6FAA6F;AAC7F,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEjF,+CAA+C;AAC/C,MAAM,MAAM,UAAU,GAClB,eAAe,GACf,qBAAqB,GACrB,sBAAsB,GACtB,wBAAwB,GACxB,qBAAqB,GACrB,wBAAwB,GACxB,0BAA0B,GAC1B,yBAAyB,GACzB,4BAA4B,GAC5B,6BAA6B,GAC7B,wBAAwB,GACxB,yBAAyB,GACzB,0BAA0B,GAC1B,sBAAsB,GACtB,4BAA4B,GAC5B,wBAAwB,GACxB,0BAA0B,GAC1B,qBAAqB,GACrB,wBAAwB,GACxB,uBAAuB,CAAC;AAE5B,0FAA0F;AAC1F,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAIpD,MAAM,WAAW,eAAe;IAC9B,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,sGAAsG;IACtG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAID,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,KAAK,CAAC;IACZ,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAID,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/dist/types/common.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=common.js.map

package/dist/types/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/types/common.ts"],"names":[],"mappings":""}

package/dist/types/handoffs.d.ts

@@ -0,0 +1,121 @@
+import type { JsonObject } from './common.js';
+import type { QuestionResponder } from './questions.js';
+/** 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';
+}
+//# sourceMappingURL=handoffs.d.ts.map

package/dist/types/handoffs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoffs.d.ts","sourceRoot":"","sources":["../../src/types/handoffs.ts"],"names":[],"mappings":"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"}

package/dist/types/handoffs.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=handoffs.js.map

package/dist/types/handoffs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoffs.js","sourceRoot":"","sources":["../../src/types/handoffs.ts"],"names":[],"mappings":""}

package/dist/types/inbox.d.ts

@@ -0,0 +1,51 @@
+import type { HandoffQuestionState, HandoffOption, HandoffAnswer, Handoff, WaitHandoffInput } from './handoffs.js';
+/** 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;
+};
+//# sourceMappingURL=inbox.d.ts.map

package/dist/types/inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../../src/types/inbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,OAAO,EACP,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAIvB,yEAAyE;AACzE,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,OAAO,CAAC;KACzB,CAAC;IACF,QAAQ,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,UAAU,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,aAAa,EAAE,CAAC;QACzB,KAAK,EAAE,oBAAoB,CAAC;QAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,CAAC;CACH;AAED,kEAAkE;AAClE,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,4EAA4E;AAC5E,MAAM,MAAM,4BAA4B,GACtC,OAAO,GAAG;IACR,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,oBAAoB,EAAE,IAAI,CAAC;CAC5B,CAAC;AAEJ,8EAA8E;AAC9E,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,sBAAsB,EAAE,UAAU,CAAC,GAAG;IAClF,oBAAoB,EAAE,IAAI,CAAC;IAC3B,QAAQ,EAAE,4BAA4B,CAAC;CACxC,CAAC"}

package/dist/types/inbox.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=inbox.js.map

package/dist/types/inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.js","sourceRoot":"","sources":["../../src/types/inbox.ts"],"names":[],"mappings":""}