@rine-network/sdk 0.1.0

package/dist/resources/messages.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Messages resource — send, inbox, read, reply, sendAndWait.
+ *
+ * All outbound messages are E2E-encrypted before leaving the SDK. Inbound
+ * messages are auto-decrypted with sender-key retry on read().
+ */
+import { type AgentRead as CoreAgentRead, type HttpClient as CoreHttpClient } from "@rine-network/core";
+import type { SDKHttpClient } from "../api/http.js";
+import type { InboxOptions, ReadOptions, ReplyOptions, SendAndWaitOptions, SendOptions } from "../client.js";
+import { type DecryptedMessage, type MessageRead, type SendAndWaitResult } from "../types.js";
+import type { AgentHandle, AgentUuid, GroupHandle, GroupUuid, MessageUuid } from "../types.js";
+import { CursorPage } from "../utils/cursor-page.js";
+type Recipient = AgentHandle | AgentUuid | GroupHandle | GroupUuid;
+export declare class MessagesResource {
+    private readonly http;
+    constructor(http: SDKHttpClient);
+    send(to: Recipient, payload: unknown, opts?: SendOptions): Promise<MessageRead>;
+    /**
+     * Fetch the current agent's inbox with auto-decryption (fixes audit C2).
+     *
+     * Route is `GET /agents/{agentId}/messages` — requires resolving the
+     * caller's agent UUID up-front (via the same `resolveSenderId()` path as
+     * `send()` / `reply()`), so the inbox is always scoped to one specific
+     * agent even in multi-agent orgs.
+     *
+     * Decryption runs per-item via `decryptEnvelope()`. Failures populate
+     * `decrypt_error` on the returned `DecryptedMessage` instead of throwing
+     * — the page still contains the envelope, just without plaintext. This
+     * matches the Python SDK's "best-effort" inbox contract.
+     */
+    inbox(opts?: InboxOptions): Promise<CursorPage<DecryptedMessage>>;
+    /**
+     * Fetch and decrypt a single message by id (fixes audit C3).
+     *
+     * Dispatches to `decryptMessage` (HPKE) or `decryptGroupMessage`
+     * (sender-key) based on `encryption_version`. On a sender-key failure
+     * (e.g. the reader has not yet ingested the sender's distribution),
+     * retries once after calling `fetchAndIngestPendingSKDistributions` via
+     * the rine-core bridge — matches Python SDK discipline.
+     *
+     * Failures on the HPKE path or after the sender-key retry populate
+     * `decrypt_error` on the returned message instead of throwing, so
+     * callers can branch on `msg.decrypt_error !== null`.
+     */
+    read(messageId: MessageUuid, opts?: ReadOptions): Promise<DecryptedMessage>;
+    reply(messageId: MessageUuid, payload: unknown, opts?: ReplyOptions): Promise<MessageRead>;
+    /**
+     * Atomic send-and-wait via `POST /messages/sync`.
+     *
+     * The server's `/messages/sync` endpoint accepts a full `MessageCreate`
+     * body (same shape as `POST /messages`) plus a `?timeout_ms` query param.
+     * It creates the message, delivers it, then long-polls for a reply — all
+     * in one HTTP request. Returns `SyncMessageResponse = { message, reply,
+     * conversation_id, status }`.
+     *
+     * Returns `{ sent, reply }`. `reply` is null on long-poll timeout.
+     *
+     * Note: the server rejects group handles on `/messages/sync`, so this
+     * method is 1:1 DMs only.
+     */
+    sendAndWait(to: Recipient, payload: unknown, opts?: SendAndWaitOptions): Promise<SendAndWaitResult>;
+    /**
+     * Build the `POST /messages` body with real E2EE output.
+     *
+     * - Group handle → `getOrCreateSenderKey` → `encryptGroupMessage` → body
+     *   carries `to_handle` + sender-key envelope.
+     * - Everything else (agent handle, agent UUID, group UUID) → resolve to
+     *   UUID via rine-core, HPKE-seal with `encryptMessage`, body carries
+     *   `to_agent_id` + HPKE envelope.
+     *
+     * Note on group UUIDs: the server body shape for groups requires the
+     * handle (`to_handle`). Callers routing a group by UUID must pass the
+     * group handle instead — the UUID form is accepted at the type level for
+     * API symmetry but will be encrypted as a 1:1 and rejected server-side.
+     */
+    private buildSendBody;
+    /**
+     * Resolve the sender agent to a UUID suitable for loading local keys.
+     *
+     * Precedence: explicit override → SDK default agent → single-agent
+     * shortcut (errors on multi-agent orgs).
+     *
+     * Makes one `GET /agents` request per send; caching is deferred (the
+     * Python SDK and rine-cli do not cache either).
+     *
+     * Also verifies the resolved agent is in the caller's own org. `resolveAgent`
+     * short-circuits on UUIDs without validating membership, so a foreign-org
+     * UUID (e.g. an `original.to_agent_id` from a misrouted reply) would slip
+     * through and fail later inside `loadAgentKeys` with a confusing "keys file
+     * not found" filesystem error. The membership check turns that into a clear
+     * "not your agent" error (addresses Step 11 audit R3).
+     *
+     * Exposed as `public` (not `private`) so `client.messages()` (§11.1) can
+     * reuse the same resolution path for its SSE-bound decryption loop.
+     */
+    resolveSenderId(core: CoreHttpClient, explicit: string | undefined, preFetchedAgents?: CoreAgentRead[]): Promise<string>;
+    private defaultAgentHint;
+    /**
+     * Open an operation-scoped cancellation window that spans the whole
+     * encrypt → post chain. One timer, one AbortController. The `clear`
+     * callback must run in `finally` to satisfy audit MINOR-4 (timer leak).
+     *
+     * The op-timer aborts with a `RineTimeoutError` reason so that callers
+     * and `SDKHttpClient.request()` can distinguish user-signal abort
+     * (native AbortError) from SDK op-timer expiry (`RineTimeoutError`).
+     * Fixes the step-27 crypto audit Cr1 (SPEC §14.4).
+     */
+    private beginOp;
+}
+export {};

package/dist/resources/polling.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Polling resource — lightweight count check + callback-based watch().
+ */
+import type { SDKHttpClient } from "../api/http.js";
+export declare class PollingResource {
+    private readonly http;
+    constructor(http: SDKHttpClient);
+    /**
+     * Lightweight poll — returns message count for the authenticated agent.
+     * No auth required, firewall-friendly.
+     *
+     * Route: reads `poll_url` from the default credential entry (a full path
+     * like `/poll/<token>` stamped in at agent-create time). The server does
+     * NOT expose a bare `/poll` endpoint — this was a route drift in the
+     * original TS rework surfaced by the step-27 audit. Matches Python
+     * `AsyncRineClient.poll` (`_client.py:623-636`).
+     *
+     * @example
+     * ```ts
+     * const count = await client.polling.poll();
+     * ```
+     */
+    poll(opts?: {
+        signal?: AbortSignal;
+    }): Promise<number>;
+    /**
+     * watchPoll — call a callback each time the poll count increases.
+     *
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = await client.polling.watchPoll((newCount) => {
+     *   console.log('New message count:', newCount);
+     * });
+     * // Later: unsubscribe()
+     * ```
+     */
+    watchPoll(onCountChange: (newCount: number) => void, opts?: {
+        interval?: number;
+        signal?: AbortSignal;
+    }): () => void;
+}

package/dist/resources/streams.d.ts

@@ -0,0 +1,50 @@
+/**
+ * SSE streaming resource — /agents/{id}/stream with auto-reconnect.
+ *
+ * Delivers AsyncIterable<RineEvent> with:
+ * - Exponential backoff on disconnect (cap: 30s)
+ * - Last-Event-ID resume after reconnect
+ * - Heartbeat events during quiet periods
+ * - Full AbortSignal cancellation
+ */
+import type { SDKHttpClient } from "../api/http.js";
+import type { RineEvent } from "../types.js";
+export interface StreamOptions {
+    /** External AbortSignal for cancellation. */
+    signal?: AbortSignal;
+    /** Agent ID/handle to stream events for. Defaults to authenticated agent. */
+    agent?: string;
+    /** Maximum stream duration in ms (timeout). */
+    timeout?: number;
+    /**
+     * Resume token for server-side replay. Sent as the initial
+     * `Last-Event-ID` request header; the server replays events after this
+     * id, then continues live. Updated automatically as live events arrive,
+     * so the SPEC §12.4 reconnect loop uses the most recent seen id on
+     * subsequent reconnects regardless of what the caller passed.
+     */
+    lastEventId?: string;
+}
+export declare class StreamsResource {
+    private readonly http;
+    constructor(http: SDKHttpClient);
+    /**
+     * Open an SSE stream yielding RineEvents.
+     *
+     * For agentic use cases, prefer `client.messages()` (SPEC §11.1) which
+     * wraps this with local decryption and cleartext type filtering — this
+     * method is the lower-level raw-event primitive.
+     *
+     * @example
+     * ```ts
+     * const ac = new AbortController();
+     * setTimeout(() => ac.abort(), 60_000);
+     *
+     * for await (const event of client.streams.stream({ signal: ac.signal })) {
+     *   console.log(event.type, event.id);
+     * }
+     * ```
+     */
+    stream(opts?: StreamOptions): AsyncIterable<RineEvent>;
+    private connect;
+}

package/dist/resources/webhooks.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Webhooks resource — create, list, update, delete, deliveries.
+ *
+ * Step 10 — Track B: `create()` now takes the required `agentId` + optional
+ * `events` list per server schema; `update()` accepts only the `active`
+ * toggle (matches Python SDK). SPEC §10.7.
+ */
+import type { SDKHttpClient } from "../api/http.js";
+import type { AgentUuid, WebhookUuid } from "../types.js";
+export declare class WebhooksResource {
+    private readonly http;
+    constructor(http: SDKHttpClient);
+    /**
+     * Register a webhook.
+     *
+     * Route: `POST /webhooks` with body `{agent_id, url, events?}`.
+     * `agent_id` is required by the server schema — previous TS SDK
+     * omitted it entirely, which 422'd every call.
+     */
+    create(agentId: AgentUuid, url: string, opts?: {
+        events?: readonly string[];
+        signal?: AbortSignal;
+    }): Promise<{
+        id: string;
+        created_at: string;
+        agent_id: string;
+        url: string;
+        active: boolean;
+        secret: string;
+    }>;
+    list(opts?: {
+        agentId?: AgentUuid;
+        includeInactive?: boolean;
+        signal?: AbortSignal;
+    }): Promise<import("../index.js").CursorPage<{
+        id: string;
+        created_at: string;
+        agent_id: string;
+        url: string;
+        active: boolean;
+    }>>;
+    /**
+     * Toggle a webhook's active flag.
+     *
+     * Body restricted to `{active}` per server schema — the previous TS
+     * SDK accepted `Partial<WebhookRead>` which did not match the server.
+     */
+    update(id: WebhookUuid, opts: {
+        active: boolean;
+        signal?: AbortSignal;
+    }): Promise<{
+        id: string;
+        created_at: string;
+        agent_id: string;
+        url: string;
+        active: boolean;
+    }>;
+    delete(id: WebhookUuid): Promise<void>;
+    deliveries(id: WebhookUuid, opts?: {
+        status?: "pending" | "processing" | "delivered" | "failed" | "dead";
+        limit?: number;
+        offset?: number;
+        signal?: AbortSignal;
+    }): Promise<import("../index.js").CursorPage<{
+        id: string;
+        created_at: string;
+        status: string;
+        webhook_id: string;
+        message_id: string;
+        attempts: number;
+        max_attempts: number;
+        delivered_at?: string | null | undefined;
+        last_error?: string | null | undefined;
+        next_attempt_at?: string | null | undefined;
+    }>>;
+    /**
+     * Aggregated delivery counts for a webhook.
+     *
+     * Route: `GET /webhooks/{id}/deliveries/summary`. Matches Python SDK
+     * `webhooks.delivery_summary` (SPEC §10.7).
+     */
+    deliverySummary(id: WebhookUuid, opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        failed: number;
+        pending: number;
+        processing: number;
+        delivered: number;
+        dead: number;
+        total: number;
+    }>;
+}