@rine-network/sdk 0.1.0

package/dist/utils/abort.d.ts

@@ -0,0 +1,40 @@
+/**
+ * AbortSignal helpers for composable cancellation.
+ *
+ * Provides:
+ * - `timeoutSignal(ms)` — `{ signal, clear }` pair that aborts after ms ms
+ *   with an `RineTimeoutError` reason. Callers MUST call `clear()` in a
+ *   `finally` block so the timer is cancelled on early completion
+ *   (audit MINOR-4, SPEC_v2 §14.3).
+ * - `anySignal(...signals)` — signal that aborts when ANY of the inputs abort
+ */
+/**
+ * Create a signal that fires after `ms` milliseconds.
+ *
+ * Returns a `{ signal, clear }` pair. Callers MUST invoke `clear()` in a
+ * `finally` block (or equivalent) to cancel the timer on early completion —
+ * otherwise the timer will still fire, aborting an already-settled signal
+ * and leaking a timer handle per call. `clear()` is idempotent.
+ *
+ * When the timer fires, the signal is aborted with an `RineTimeoutError`
+ * reason so `catch` sites can distinguish an SDK timeout from a user-cancel
+ * via `err instanceof RineTimeoutError` (SPEC_v2 §14.4).
+ */
+export declare function timeoutSignal(ms: number): {
+    signal: AbortSignal;
+    clear: () => void;
+};
+/**
+ * Combine multiple signals into one that aborts when ANY input aborts.
+ *
+ * The composed signal's `reason` is the reason from whichever input fired
+ * first — this preserves the `RineTimeoutError` reason attached by
+ * `timeoutSignal()` (and matching per-op timers in resources), so downstream
+ * `signal.reason instanceof RineTimeoutError` checks classify timeouts
+ * correctly instead of seeing a generic `AbortError` (SPEC_v2 §14.4).
+ *
+ * Listeners are detached from the remaining inputs as soon as the combined
+ * signal fires — this prevents retaining long-lived source signals (e.g. a
+ * global client signal) through short-lived request signals.
+ */
+export declare function anySignal(...signals: AbortSignal[]): AbortSignal;

package/dist/utils/cursor-page.d.ts

@@ -0,0 +1,23 @@
+/**
+ * CursorPage<T> — async iterable + hasNext/hasPrev.
+ *
+ * Mirrors the Python SDK's CursorPage[T] pattern. The caller-passing
+ * `autoPaginate(fetchPage)` method was deleted per SPEC §13.3 — use the
+ * dedicated `client.inboxAll()` / `client.discoverAll()` / `client.discoverGroupsAll()`
+ * async generators instead, which own their fetch loop.
+ */
+/**
+ * Cursor-paginated response.
+ *
+ * @typeParam T - Item type (DecryptedMessage, AgentSummary, etc.)
+ */
+export declare class CursorPage<T> implements AsyncIterable<T> {
+    readonly items: T[];
+    readonly total: number;
+    readonly nextCursor: string | null;
+    readonly prevCursor: string | null;
+    constructor(items: T[], total: number, nextCursor: string | null, prevCursor: string | null);
+    get hasNext(): boolean;
+    get hasPrev(): boolean;
+    [Symbol.asyncIterator](): AsyncGenerator<T>;
+}

package/dist/utils/schema.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Standard Schema v1 integration helpers — SPEC §7.4 / §11.4.
+ *
+ * The SDK accepts user-supplied schemas on `send<T>`, `read<T>`, `reply<T>`,
+ * `messages<T>`, `sendAndWait<Req, Rep>`, `conversation(id).{send,reply,messages,history}<T>`,
+ * and `defineAgent<T>`. `@standard-schema/spec` is a type-only package — no
+ * validator runtime ships with the SDK (D3). Users bring Zod, Valibot, ArkType,
+ * Effect Schema, or any other compliant library and pass a schema object via
+ * the `schema` option slot.
+ *
+ * Two exported helpers:
+ *
+ * - `parsePlaintext<T>(value, schema)` — validates an arbitrary plaintext
+ *   value against a Standard Schema v1 and returns the typed output. Throws
+ *   `ValidationError` on the first issue reported by the schema.
+ *
+ * - `parseMessagePlaintext<T>(msg, schema)` — wraps `parsePlaintext` with
+ *   the JSON-parse step specific to `DecryptedMessage.plaintext` (which is
+ *   a string coming out of rine-core's `decryptMessage` / `decryptGroupMessage`
+ *   helpers) and returns a `DecryptedMessage<T>` with the typed plaintext
+ *   folded back in. If `msg.plaintext` is `null` (decrypt failed upstream)
+ *   the message is returned untouched — the schema is not applied to a
+ *   `decrypt_error` envelope.
+ */
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { DecryptedMessage } from "../types.js";
+export type { StandardSchemaV1 };
+/**
+ * Validate an arbitrary value against a Standard Schema v1 and return the
+ * typed output. The validator may return a synchronous result or a promise,
+ * so this helper always awaits. On failure, the first issue's message is
+ * used as the `ValidationError` detail — detail enough to point at the
+ * field without dumping the full issue list into the error message.
+ */
+export declare function parsePlaintext<T>(value: unknown, schema: StandardSchemaV1<unknown, T>): Promise<T>;
+/**
+ * JSON-parse a `DecryptedMessage.plaintext` string and validate it via a
+ * Standard Schema v1, returning a typed `DecryptedMessage<T>`. Leaves
+ * messages with `plaintext == null` untouched (decrypt-failed envelopes
+ * still surface to the caller so they can branch on `decrypt_error`).
+ *
+ * The JSON-parse step is mandatory: Standard Schemas like Zod's `z.object`
+ * validate structured input, not raw strings. If a caller's payload is
+ * already a plain string, they can use `z.string()` as the schema and the
+ * JSON-parse round-trip is still well-defined (`JSON.parse('"hi"') === "hi"`).
+ */
+export declare function parseMessagePlaintext<T>(msg: DecryptedMessage, schema: StandardSchemaV1<unknown, T>): Promise<DecryptedMessage<T>>;
+/**
+ * Validate an outbound payload against a Standard Schema v1 before it is
+ * handed to the encryption layer. SPEC §11.4: outbound schemas run *before*
+ * encrypt so a shape failure rejects without sending any ciphertext.
+ *
+ * This helper returns the validated (possibly transformed — schemas may
+ * parse / coerce) value so the caller can encrypt the narrowed form rather
+ * than the raw input. For schemas that are pure type guards (no transforms)
+ * the returned value is reference-equal to the input.
+ */
+export declare function validateOutbound<T>(payload: T, schema: StandardSchemaV1<unknown, T>): Promise<T>;

package/dist/utils/seen-ids.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Bounded FIFO seen-ID set.
+ *
+ * Used by both the SSE stream layer (reconnect replay dedup per SPEC_v2 §12.3.3)
+ * and the poll-based `watch()` path (see `client.ts`). On reconnect with
+ * `Last-Event-ID`, the server's catch-up phase can race with the NOTIFY
+ * delivery and re-emit events already seen; this class is the guard against
+ * dispatching them twice.
+ *
+ * Capacity defaults to 500 (SPEC §12.3.3 N — ~18 KB of RAM, ~10 minutes of
+ * traffic at 1 msg/s — comfortably larger than any plausible reconnect
+ * replay window, small enough to stay negligible).
+ */
+export declare class SeenIds {
+    private readonly capacity;
+    private readonly set;
+    private readonly queue;
+    constructor(capacity?: number);
+    /** Returns true if the id is new (caller should dispatch), false if duplicate. */
+    record(id: string): boolean;
+    has(id: string): boolean;
+    get size(): number;
+}

package/dist/utils/sleep.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared sleep utility — avoids triplication across client.ts, polling.ts, streams.ts.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Like `sleep()` but aborts early when the given signal fires. Used in
+ * polling/streaming loops so cancellation during backoff doesn't wait
+ * the full interval.
+ */
+export declare function sleepWithSignal(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/utils/sse.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SSE → AsyncIterable adapter.
+ *
+ * Converts an SSE (Server-Sent Events) stream into a native TypeScript
+ * AsyncIterable, so it composes with `for-await-of`, TransformStream, etc.
+ *
+ * The adapter:
+ * - Handles SSE line parsing (event:, data:, id:, :)
+ * - Dispatches accumulated events on blank lines (the SSE delimiter)
+ * - Yields structured `{ type, data, id }` objects
+ * - Couples with AbortSignal for cancellation
+ */
+import type { RineEvent } from "../types.js";
+/**
+ * Convert a fetch Response with an SSE body into an AsyncIterable of RineEvent.
+ *
+ * @param response - A fetch Response whose body is an SSE stream.
+ * @param signal   - AbortSignal for cancellation.
+ *
+ * Usage:
+ * ```ts
+ * const resp = await fetch(url, { headers: { Accept: 'text/event-stream' } });
+ * for await (const event of toAsyncIter(resp, signal)) {
+ *   console.log(event.type, event.data);
+ * }
+ * ```
+ */
+export declare function toAsyncIter(response: Response, signal: AbortSignal): AsyncGenerator<RineEvent>;

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@rine-network/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Rine \u2014 E2E-encrypted messaging for AI agents",
+  "author": "Rine Network",
+  "license": "EUPL-1.2",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --outDir dist --clean && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p examples/tsconfig.json",
+    "typecheck:examples": "tsc --noEmit -p examples/tsconfig.json",
+    "lint": "biome check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest --coverage",
+    "dev": "tsx src/index.ts",
+    "docs": "typedoc"
+  },
+  "dependencies": {
+    "@rine-network/core": "^0.4.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@standard-schema/spec": "^1.1.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsdown": "^0.12.0",
+    "tsx": "^4.19.0",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.11.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "homepage": "https://rine.network",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/rine/rine-ts-sdk"
+  },
+  "bugs": {
+    "url": "https://codeberg.org/rine/rine-ts-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "messaging",
+    "ai-agents",
+    "sdk",
+    "a2a",
+    "e2ee",
+    "rine"
+  ]
+}