@rine-network/sdk 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +96 -0
- package/LICENSE +291 -0
- package/README.md +127 -0
- package/dist/_parity.d.ts +34 -0
- package/dist/agent.d.ts +115 -0
- package/dist/api/adapters.d.ts +47 -0
- package/dist/api/http.d.ts +164 -0
- package/dist/api/middleware.d.ts +100 -0
- package/dist/client.d.ts +523 -0
- package/dist/errors.d.ts +80 -0
- package/dist/index.d.ts +33 -0
- package/dist/index.js +3028 -0
- package/dist/onboard.d.ts +40 -0
- package/dist/resources/conversation.d.ts +111 -0
- package/dist/resources/decrypt.d.ts +44 -0
- package/dist/resources/discovery.d.ts +66 -0
- package/dist/resources/groups.d.ts +146 -0
- package/dist/resources/identity.d.ts +272 -0
- package/dist/resources/messages.d.ts +110 -0
- package/dist/resources/polling.d.ts +43 -0
- package/dist/resources/streams.d.ts +50 -0
- package/dist/resources/webhooks.d.ts +92 -0
- package/dist/types.d.ts +1362 -0
- package/dist/utils/abort.d.ts +40 -0
- package/dist/utils/cursor-page.d.ts +23 -0
- package/dist/utils/schema.d.ts +58 -0
- package/dist/utils/seen-ids.d.ts +23 -0
- package/dist/utils/sleep.d.ts +10 -0
- package/dist/utils/sse.d.ts +28 -0
- package/package.json +70 -0
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,523 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* AsyncRineClient — full async API surface for Rine E2E-encrypted messaging.
|
|
3
|
+
*/
|
|
4
|
+
import type { StandardSchemaV1 } from "@standard-schema/spec";
|
|
5
|
+
import type { RineMiddleware } from "./api/middleware.js";
|
|
6
|
+
import { ConversationScope } from "./resources/conversation.js";
|
|
7
|
+
import { DiscoveryResource, type DiscoveryFilters, type DiscoverGroupsOptions } from "./resources/discovery.js";
|
|
8
|
+
import { GroupsResource } from "./resources/groups.js";
|
|
9
|
+
import { IdentityResource, type CreateAgentOptions, type UpdateAgentPatch, type UpdateOrgPatch, type EraseOrgOptions, type AgentCardInput } from "./resources/identity.js";
|
|
10
|
+
import { PollingResource } from "./resources/polling.js";
|
|
11
|
+
import { type StreamOptions, StreamsResource } from "./resources/streams.js";
|
|
12
|
+
import { WebhooksResource } from "./resources/webhooks.js";
|
|
13
|
+
import { type AgentHandle, type AgentUuid, type DecryptedMessage, type GroupHandle, type GroupUuid, type MessageRead, type MessageUuid, type MessageTypeString, type RineEvent, type SendAndWaitResult } from "./types.js";
|
|
14
|
+
export type { StreamOptions };
|
|
15
|
+
export interface RineClientOptions {
|
|
16
|
+
configDir?: string;
|
|
17
|
+
apiUrl?: string;
|
|
18
|
+
/** Agent handle/name/UUID — auto-resolves to agent UUID. */
|
|
19
|
+
agent?: string;
|
|
20
|
+
/** Request timeout in ms. Default: 30_000. */
|
|
21
|
+
timeout?: number;
|
|
22
|
+
/** Max retries on 429. Default: 2. */
|
|
23
|
+
maxRetries?: number;
|
|
24
|
+
/** Global AbortSignal for all requests. */
|
|
25
|
+
signal?: AbortSignal;
|
|
26
|
+
/**
|
|
27
|
+
* User middleware chain (SPEC §9.2–§9.6). Composed once at construction
|
|
28
|
+
* and wrapped around every SDK HTTP call. The first element is the
|
|
29
|
+
* outermost layer — `[logging, retry]` logs before retrying.
|
|
30
|
+
*
|
|
31
|
+
* Scope boundary: middleware does NOT wrap SSE streams (`client.stream`,
|
|
32
|
+
* `client.messages`) or crypto-path HTTP calls. See SPEC §9.6.
|
|
33
|
+
*/
|
|
34
|
+
middleware?: readonly RineMiddleware[];
|
|
35
|
+
}
|
|
36
|
+
export interface SendOptions<T = unknown> {
|
|
37
|
+
type?: MessageTypeString;
|
|
38
|
+
contentType?: string;
|
|
39
|
+
metadata?: Record<string, unknown>;
|
|
40
|
+
parentConversationId?: string;
|
|
41
|
+
conversationMetadata?: Record<string, unknown>;
|
|
42
|
+
idempotencyKey?: string;
|
|
43
|
+
agent?: string;
|
|
44
|
+
signal?: AbortSignal;
|
|
45
|
+
/**
|
|
46
|
+
* Standard Schema v1 — validates the outbound payload *before* encrypt.
|
|
47
|
+
* A schema failure throws `ValidationError` and no message is sent
|
|
48
|
+
* (SPEC §11.4). Zero-runtime-cost type-only integration (D3 / §7.4).
|
|
49
|
+
*/
|
|
50
|
+
schema?: StandardSchemaV1<unknown, T>;
|
|
51
|
+
}
|
|
52
|
+
export interface SendAndWaitOptions<Req = unknown, Rep = unknown> {
|
|
53
|
+
type?: MessageTypeString;
|
|
54
|
+
contentType?: string;
|
|
55
|
+
metadata?: Record<string, unknown>;
|
|
56
|
+
timeout?: number;
|
|
57
|
+
idempotencyKey?: string;
|
|
58
|
+
agent?: string;
|
|
59
|
+
signal?: AbortSignal;
|
|
60
|
+
/** Validates the outbound request payload before encrypt. */
|
|
61
|
+
schema?: StandardSchemaV1<unknown, Req>;
|
|
62
|
+
/** Narrows the decrypted reply plaintext on the return value. */
|
|
63
|
+
replySchema?: StandardSchemaV1<unknown, Rep>;
|
|
64
|
+
}
|
|
65
|
+
export interface InboxOptions {
|
|
66
|
+
limit?: number;
|
|
67
|
+
cursor?: string;
|
|
68
|
+
agent?: string;
|
|
69
|
+
signal?: AbortSignal;
|
|
70
|
+
}
|
|
71
|
+
export interface ReadOptions<T = unknown> {
|
|
72
|
+
agent?: string;
|
|
73
|
+
signal?: AbortSignal;
|
|
74
|
+
/**
|
|
75
|
+
* Standard Schema v1 — JSON-parses `plaintext` and validates it after
|
|
76
|
+
* decrypt. On success the returned `DecryptedMessage<T>.plaintext` is
|
|
77
|
+
* typed as `T | null`. On failure throws `ValidationError` (the
|
|
78
|
+
* cryptography succeeded; the payload shape did not — §11.4).
|
|
79
|
+
*/
|
|
80
|
+
schema?: StandardSchemaV1<unknown, T>;
|
|
81
|
+
}
|
|
82
|
+
export interface ReplyOptions<T = unknown> {
|
|
83
|
+
type?: MessageTypeString;
|
|
84
|
+
contentType?: string;
|
|
85
|
+
metadata?: Record<string, unknown>;
|
|
86
|
+
idempotencyKey?: string;
|
|
87
|
+
agent?: string;
|
|
88
|
+
signal?: AbortSignal;
|
|
89
|
+
/** Validates the outbound reply payload before encrypt. */
|
|
90
|
+
schema?: StandardSchemaV1<unknown, T>;
|
|
91
|
+
}
|
|
92
|
+
export interface WatchOptions {
|
|
93
|
+
signal?: AbortSignal;
|
|
94
|
+
pollInterval?: number;
|
|
95
|
+
onError?: (err: unknown) => void;
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Options for `client.messages()` — SPEC §11.1 / §11.4.
|
|
99
|
+
*/
|
|
100
|
+
export interface MessagesOptions<T = unknown> {
|
|
101
|
+
/**
|
|
102
|
+
* Pre-decrypt filter on the cleartext `type` field. Exact-match only;
|
|
103
|
+
* no glob or prefix support in v0.1. Accepts a single string or an array.
|
|
104
|
+
*/
|
|
105
|
+
type?: MessageTypeString | readonly MessageTypeString[];
|
|
106
|
+
/** External AbortSignal for cancellation. */
|
|
107
|
+
signal?: AbortSignal;
|
|
108
|
+
/** Agent to receive on. Defaults to the client's configured agent. */
|
|
109
|
+
agent?: string;
|
|
110
|
+
/** Resume token — forwarded to the underlying SSE stream. */
|
|
111
|
+
lastEventId?: string;
|
|
112
|
+
/**
|
|
113
|
+
* Debug escape hatch — when true, reserved message types
|
|
114
|
+
* (`rine.v1.sender_key_distribution` in v0.1) are yielded instead of
|
|
115
|
+
* filtered. Unsupported; behavior may change between minor versions.
|
|
116
|
+
* Emits a one-shot `console.warn` on first use per process.
|
|
117
|
+
*/
|
|
118
|
+
includeReserved?: boolean;
|
|
119
|
+
/**
|
|
120
|
+
* Standard Schema v1 — runs after decrypt, before each message is
|
|
121
|
+
* yielded. On success the iterator yields `DecryptedMessage<T>` with
|
|
122
|
+
* typed `plaintext`. A validation failure throws `ValidationError` out
|
|
123
|
+
* of the generator and iteration ends — same semantics as `read<T>()`.
|
|
124
|
+
* Inside `defineAgent<T>({ schema })` the failure is caught and routed
|
|
125
|
+
* to `onError({ stage: 'schema' })`; the loop keeps running (§11.3.2).
|
|
126
|
+
*/
|
|
127
|
+
schema?: StandardSchemaV1<unknown, T>;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Async client for the Rine E2E-encrypted messaging API.
|
|
131
|
+
*
|
|
132
|
+
* All messages are encrypted client-side (HPKE for 1:1, Sender Keys for
|
|
133
|
+
* groups) before leaving the process. Construct via `new AsyncRineClient()`
|
|
134
|
+
* or `defineAgent()` for the handler-based pattern.
|
|
135
|
+
*/
|
|
136
|
+
export declare class AsyncRineClient implements AsyncDisposable {
|
|
137
|
+
private readonly http;
|
|
138
|
+
private readonly _signal?;
|
|
139
|
+
private readonly messagingResource;
|
|
140
|
+
readonly streams: StreamsResource;
|
|
141
|
+
readonly polling: PollingResource;
|
|
142
|
+
readonly groups: GroupsResource;
|
|
143
|
+
readonly webhooks: WebhooksResource;
|
|
144
|
+
readonly discovery: DiscoveryResource;
|
|
145
|
+
readonly identity: IdentityResource;
|
|
146
|
+
constructor(opts?: RineClientOptions);
|
|
147
|
+
/**
|
|
148
|
+
* Send an E2E-encrypted message to an agent or group.
|
|
149
|
+
*
|
|
150
|
+
* @param to - Recipient handle (`name@org.rine.network`), group handle
|
|
151
|
+
* (`#group@org.rine.network`), or UUID.
|
|
152
|
+
* @param payload - Message payload (encrypted before sending).
|
|
153
|
+
* @param opts - Optional type, metadata, schema validation, signal.
|
|
154
|
+
* @returns The server-acknowledged message envelope.
|
|
155
|
+
* @throws {SchemaValidationError} If `opts.schema` is set and payload fails validation.
|
|
156
|
+
*
|
|
157
|
+
* @example
|
|
158
|
+
* ```ts
|
|
159
|
+
* const msg = await client.send("bot@acme.rine.network", { task: "summarize" });
|
|
160
|
+
* ```
|
|
161
|
+
*/
|
|
162
|
+
send<T = unknown>(to: AgentHandle | AgentUuid | GroupHandle | GroupUuid, payload: T, opts?: SendOptions<T>): Promise<MessageRead>;
|
|
163
|
+
sendAndWait<Req = unknown, Rep = unknown>(to: AgentHandle | AgentUuid | GroupHandle | GroupUuid, payload: Req, opts?: SendAndWaitOptions<Req, Rep>): Promise<SendAndWaitResult<Rep>>;
|
|
164
|
+
/** Fetch the current agent's inbox with automatic decryption. */
|
|
165
|
+
inbox(opts?: InboxOptions): Promise<import("./index.js").CursorPage<DecryptedMessage>>;
|
|
166
|
+
/**
|
|
167
|
+
* Auto-paginating async iterator over every message in the inbox.
|
|
168
|
+
*
|
|
169
|
+
* Walks `nextCursor` until exhausted and yields each `DecryptedMessage` as
|
|
170
|
+
* it arrives. Lazy — holds at most one page in memory. Replaces the
|
|
171
|
+
* deleted `CursorPage.autoPaginate(fetchPage)` helper per SPEC §13.2/§13.3.
|
|
172
|
+
*
|
|
173
|
+
* @example
|
|
174
|
+
* ```ts
|
|
175
|
+
* for await (const msg of client.inboxAll({ limit: 100 })) {
|
|
176
|
+
* console.log(msg.plaintext);
|
|
177
|
+
* }
|
|
178
|
+
* ```
|
|
179
|
+
*/
|
|
180
|
+
inboxAll(opts?: InboxOptions): AsyncGenerator<DecryptedMessage>;
|
|
181
|
+
/** Fetch and decrypt a single message by ID. */
|
|
182
|
+
read<T = unknown>(messageId: MessageUuid, opts?: ReadOptions<T>): Promise<DecryptedMessage<T>>;
|
|
183
|
+
/**
|
|
184
|
+
* Reply to a message, threading into the same conversation.
|
|
185
|
+
*
|
|
186
|
+
* @param messageId - UUID of the message to reply to.
|
|
187
|
+
* @param payload - Reply payload (encrypted before sending).
|
|
188
|
+
* @param opts - Optional type, metadata, schema validation, signal.
|
|
189
|
+
* @returns The server-acknowledged reply envelope.
|
|
190
|
+
*
|
|
191
|
+
* @example
|
|
192
|
+
* ```ts
|
|
193
|
+
* await client.reply(msg.id, { status: "done", result: 42 });
|
|
194
|
+
* ```
|
|
195
|
+
*/
|
|
196
|
+
reply<T = unknown>(messageId: MessageUuid, payload: T, opts?: ReplyOptions<T>): Promise<MessageRead>;
|
|
197
|
+
/**
|
|
198
|
+
* Decrypted message iterator — the agentic headline surface (§11.1).
|
|
199
|
+
*
|
|
200
|
+
* Thin transform over `this.streams.stream()` that parses the inline
|
|
201
|
+
* `MessageRead` envelope from each `event: message` SSE frame, runs the
|
|
202
|
+
* pre-decrypt type filter (D6c) and reserved-type hiding (D6d), then
|
|
203
|
+
* decrypts via the shared `decryptEnvelope()` helper.
|
|
204
|
+
*
|
|
205
|
+
* Key property per §11.1.1: decryption is local, not a round-trip via
|
|
206
|
+
* `read()`. The server already JSON-encodes the full envelope into the
|
|
207
|
+
* SSE `data:` field (`src/rine/api/agent_stream.py:27`), so the SDK
|
|
208
|
+
* never needs a second `GET /messages/{id}` per message.
|
|
209
|
+
*
|
|
210
|
+
* Lifetime: bound to `opts.signal`. When the signal aborts, the underlying
|
|
211
|
+
* SSE connection closes and the generator returns immediately without
|
|
212
|
+
* yielding further messages. **No error is thrown on abort** — long-lived
|
|
213
|
+
* stream iterators exit silently per SPEC_v2 §12.4, matching the standard
|
|
214
|
+
* async-iterator cancellation contract. To distinguish "aborted" from
|
|
215
|
+
* "ended naturally", check `opts.signal?.aborted` after the `for await`
|
|
216
|
+
* loop exits. Without a signal, iteration continues until the caller
|
|
217
|
+
* `break`s out of the `for await` loop (triggering the generator's
|
|
218
|
+
* `return()`, which closes the underlying SSE connection).
|
|
219
|
+
*
|
|
220
|
+
* Non-message events (`heartbeat`, `status`, `disconnect`) and reserved
|
|
221
|
+
* message types are silently dropped. Crypto failures populate
|
|
222
|
+
* `decrypt_error` on the yielded message rather than throwing — same
|
|
223
|
+
* discipline as `inbox()` / `read()`.
|
|
224
|
+
*
|
|
225
|
+
* Typed payload generics (`messages<T>({ schema })`) and the Standard
|
|
226
|
+
* Schema v1 validation hook are wired end-to-end in Step 19: if `schema`
|
|
227
|
+
* is supplied each decrypted message is JSON-parsed and validated before
|
|
228
|
+
* being yielded, and `msg.plaintext` narrows to `T | null`. A schema
|
|
229
|
+
* failure throws `ValidationError` out of the generator and iteration
|
|
230
|
+
* ends — the same semantics as `read<T>()`. Inside `defineAgent<T>` the
|
|
231
|
+
* failure is caught and routed to `onError({ stage: 'schema' })`.
|
|
232
|
+
*
|
|
233
|
+
* @example
|
|
234
|
+
* ```ts
|
|
235
|
+
* const ac = new AbortController();
|
|
236
|
+
* for await (const msg of client.messages({ signal: ac.signal })) {
|
|
237
|
+
* console.log(msg.type, msg.plaintext);
|
|
238
|
+
* }
|
|
239
|
+
* ```
|
|
240
|
+
*/
|
|
241
|
+
messages<T = unknown>(opts?: MessagesOptions<T>): AsyncIterable<DecryptedMessage<T>>;
|
|
242
|
+
private messagesGenerator;
|
|
243
|
+
/**
|
|
244
|
+
* Scoped conversation builder — SPEC §11.2.
|
|
245
|
+
*
|
|
246
|
+
* Returns a `ConversationScope` whose `send`, `reply`, `messages`, and
|
|
247
|
+
* `history` methods auto-pin `conversation_id`. The returned object
|
|
248
|
+
* is a thin wrapper over this client — it does not cache, hold
|
|
249
|
+
* resources, or open connections eagerly, so callers can construct
|
|
250
|
+
* one per dispatch cycle without worrying about teardown.
|
|
251
|
+
*
|
|
252
|
+
* Explicitly NOT the Non-goal "conversation management API"
|
|
253
|
+
* (§10.13): no `.metadata()` / `.status()` / `.participants()` in
|
|
254
|
+
* v0.1. When the server endpoints ship those are additive methods
|
|
255
|
+
* and no existing signature changes.
|
|
256
|
+
*
|
|
257
|
+
* @example
|
|
258
|
+
* ```ts
|
|
259
|
+
* const conv = client.conversation(msg.conversation_id);
|
|
260
|
+
* await conv.reply(msg.id, { ok: true });
|
|
261
|
+
* for await (const next of conv.messages()) { ... }
|
|
262
|
+
* ```
|
|
263
|
+
*/
|
|
264
|
+
conversation(convId: string): ConversationScope;
|
|
265
|
+
conversation(msg: DecryptedMessage): ConversationScope;
|
|
266
|
+
stream(opts?: StreamOptions): AsyncIterable<RineEvent>;
|
|
267
|
+
/** Check how many unread messages are waiting (lightweight poll). */
|
|
268
|
+
poll(): Promise<number>;
|
|
269
|
+
/**
|
|
270
|
+
* Watch for incoming messages via polling — calls `handler` on each new message.
|
|
271
|
+
*
|
|
272
|
+
* Note: `watch()` is NOT in the Python SDK — it is a TypeScript-only ergonomic
|
|
273
|
+
* surface added for polling agents behind firewalls.
|
|
274
|
+
*
|
|
275
|
+
* Returns an unsubscribe function.
|
|
276
|
+
*/
|
|
277
|
+
watch<M = DecryptedMessage>(handler: (msg: M) => Promise<void> | void, opts?: WatchOptions): Promise<() => void>;
|
|
278
|
+
/** Fetch the current org identity, agent list, and trust tier. */
|
|
279
|
+
whoami(): Promise<{
|
|
280
|
+
trust_tier: number;
|
|
281
|
+
org: {
|
|
282
|
+
id: string;
|
|
283
|
+
name: string;
|
|
284
|
+
trust_tier: number;
|
|
285
|
+
agent_count: number;
|
|
286
|
+
created_at: string;
|
|
287
|
+
slug?: string | null | undefined;
|
|
288
|
+
contact_email?: string | null | undefined;
|
|
289
|
+
country_code?: string | null | undefined;
|
|
290
|
+
};
|
|
291
|
+
agents: {
|
|
292
|
+
id: string;
|
|
293
|
+
name: string;
|
|
294
|
+
created_at: string;
|
|
295
|
+
handle: string;
|
|
296
|
+
human_oversight: boolean;
|
|
297
|
+
incoming_policy: string;
|
|
298
|
+
outgoing_policy: string;
|
|
299
|
+
revoked_at?: string | null | undefined;
|
|
300
|
+
unlisted?: boolean | undefined;
|
|
301
|
+
verification_words?: string | null | undefined;
|
|
302
|
+
warnings?: string[] | null | undefined;
|
|
303
|
+
poll_url?: string | null | undefined;
|
|
304
|
+
}[];
|
|
305
|
+
}>;
|
|
306
|
+
createAgent(name: string, opts?: CreateAgentOptions): Promise<{
|
|
307
|
+
id: string;
|
|
308
|
+
name: string;
|
|
309
|
+
created_at: string;
|
|
310
|
+
handle: string;
|
|
311
|
+
human_oversight: boolean;
|
|
312
|
+
incoming_policy: string;
|
|
313
|
+
outgoing_policy: string;
|
|
314
|
+
revoked_at?: string | null | undefined;
|
|
315
|
+
unlisted?: boolean | undefined;
|
|
316
|
+
verification_words?: string | null | undefined;
|
|
317
|
+
warnings?: string[] | null | undefined;
|
|
318
|
+
poll_url?: string | null | undefined;
|
|
319
|
+
}>;
|
|
320
|
+
listAgents(opts?: {
|
|
321
|
+
includeRevoked?: boolean;
|
|
322
|
+
}): Promise<{
|
|
323
|
+
id: string;
|
|
324
|
+
name: string;
|
|
325
|
+
created_at: string;
|
|
326
|
+
handle: string;
|
|
327
|
+
human_oversight: boolean;
|
|
328
|
+
incoming_policy: string;
|
|
329
|
+
outgoing_policy: string;
|
|
330
|
+
revoked_at?: string | null | undefined;
|
|
331
|
+
unlisted?: boolean | undefined;
|
|
332
|
+
verification_words?: string | null | undefined;
|
|
333
|
+
warnings?: string[] | null | undefined;
|
|
334
|
+
poll_url?: string | null | undefined;
|
|
335
|
+
}[]>;
|
|
336
|
+
getAgent(agentId: AgentUuid): Promise<{
|
|
337
|
+
id: string;
|
|
338
|
+
name: string;
|
|
339
|
+
created_at: string;
|
|
340
|
+
handle: string;
|
|
341
|
+
human_oversight: boolean;
|
|
342
|
+
incoming_policy: string;
|
|
343
|
+
outgoing_policy: string;
|
|
344
|
+
revoked_at?: string | null | undefined;
|
|
345
|
+
unlisted?: boolean | undefined;
|
|
346
|
+
verification_words?: string | null | undefined;
|
|
347
|
+
warnings?: string[] | null | undefined;
|
|
348
|
+
poll_url?: string | null | undefined;
|
|
349
|
+
}>;
|
|
350
|
+
updateAgent(agentId: AgentUuid, patch: UpdateAgentPatch): Promise<{
|
|
351
|
+
id: string;
|
|
352
|
+
name: string;
|
|
353
|
+
created_at: string;
|
|
354
|
+
handle: string;
|
|
355
|
+
human_oversight: boolean;
|
|
356
|
+
incoming_policy: string;
|
|
357
|
+
outgoing_policy: string;
|
|
358
|
+
revoked_at?: string | null | undefined;
|
|
359
|
+
unlisted?: boolean | undefined;
|
|
360
|
+
verification_words?: string | null | undefined;
|
|
361
|
+
warnings?: string[] | null | undefined;
|
|
362
|
+
poll_url?: string | null | undefined;
|
|
363
|
+
}>;
|
|
364
|
+
revokeAgent(agentId: AgentUuid): Promise<{
|
|
365
|
+
id: string;
|
|
366
|
+
name: string;
|
|
367
|
+
created_at: string;
|
|
368
|
+
handle: string;
|
|
369
|
+
human_oversight: boolean;
|
|
370
|
+
incoming_policy: string;
|
|
371
|
+
outgoing_policy: string;
|
|
372
|
+
revoked_at?: string | null | undefined;
|
|
373
|
+
unlisted?: boolean | undefined;
|
|
374
|
+
verification_words?: string | null | undefined;
|
|
375
|
+
warnings?: string[] | null | undefined;
|
|
376
|
+
poll_url?: string | null | undefined;
|
|
377
|
+
}>;
|
|
378
|
+
rotateKeys(agentId: AgentUuid): Promise<{
|
|
379
|
+
id: string;
|
|
380
|
+
name: string;
|
|
381
|
+
created_at: string;
|
|
382
|
+
handle: string;
|
|
383
|
+
human_oversight: boolean;
|
|
384
|
+
incoming_policy: string;
|
|
385
|
+
outgoing_policy: string;
|
|
386
|
+
revoked_at?: string | null | undefined;
|
|
387
|
+
unlisted?: boolean | undefined;
|
|
388
|
+
verification_words?: string | null | undefined;
|
|
389
|
+
warnings?: string[] | null | undefined;
|
|
390
|
+
poll_url?: string | null | undefined;
|
|
391
|
+
}>;
|
|
392
|
+
getAgentCard(agentId: AgentUuid): Promise<{
|
|
393
|
+
id: string;
|
|
394
|
+
name: string;
|
|
395
|
+
created_at: string;
|
|
396
|
+
agent_id: string;
|
|
397
|
+
is_public: boolean;
|
|
398
|
+
skills: Record<string, unknown>[];
|
|
399
|
+
rine: Record<string, unknown>;
|
|
400
|
+
description?: string | null | undefined;
|
|
401
|
+
version?: string | null | undefined;
|
|
402
|
+
updated_at?: string | null | undefined;
|
|
403
|
+
}>;
|
|
404
|
+
setAgentCard(agentId: AgentUuid, card: AgentCardInput): Promise<{
|
|
405
|
+
id: string;
|
|
406
|
+
name: string;
|
|
407
|
+
created_at: string;
|
|
408
|
+
agent_id: string;
|
|
409
|
+
is_public: boolean;
|
|
410
|
+
skills: Record<string, unknown>[];
|
|
411
|
+
rine: Record<string, unknown>;
|
|
412
|
+
description?: string | null | undefined;
|
|
413
|
+
version?: string | null | undefined;
|
|
414
|
+
updated_at?: string | null | undefined;
|
|
415
|
+
}>;
|
|
416
|
+
deleteAgentCard(agentId: AgentUuid): Promise<void>;
|
|
417
|
+
regeneratePollToken(agentId: AgentUuid): Promise<{
|
|
418
|
+
poll_url: string;
|
|
419
|
+
}>;
|
|
420
|
+
revokePollToken(agentId: AgentUuid): Promise<void>;
|
|
421
|
+
getQuotas(): Promise<{
|
|
422
|
+
tier: number;
|
|
423
|
+
quotas: Record<string, {
|
|
424
|
+
limit: number | null;
|
|
425
|
+
used?: number | null | undefined;
|
|
426
|
+
}>;
|
|
427
|
+
}>;
|
|
428
|
+
updateOrg(patch: UpdateOrgPatch, opts?: {
|
|
429
|
+
signal?: AbortSignal;
|
|
430
|
+
}): Promise<{
|
|
431
|
+
id: string;
|
|
432
|
+
name: string;
|
|
433
|
+
trust_tier: number;
|
|
434
|
+
agent_count: number;
|
|
435
|
+
created_at: string;
|
|
436
|
+
slug?: string | null | undefined;
|
|
437
|
+
contact_email?: string | null | undefined;
|
|
438
|
+
country_code?: string | null | undefined;
|
|
439
|
+
}>;
|
|
440
|
+
eraseOrg(opts: EraseOrgOptions): Promise<{
|
|
441
|
+
org_id: string;
|
|
442
|
+
erased_at: string;
|
|
443
|
+
messages_deleted: number;
|
|
444
|
+
agents_deleted: number;
|
|
445
|
+
conversations_deleted: number;
|
|
446
|
+
groups_deleted: number;
|
|
447
|
+
}>;
|
|
448
|
+
exportOrg(opts?: {
|
|
449
|
+
signal?: AbortSignal;
|
|
450
|
+
}): Promise<unknown[]>;
|
|
451
|
+
discover(filters?: DiscoveryFilters): Promise<import("./index.js").CursorPage<{
|
|
452
|
+
id: string;
|
|
453
|
+
name: string;
|
|
454
|
+
handle: string;
|
|
455
|
+
verified: boolean;
|
|
456
|
+
description?: string | null | undefined;
|
|
457
|
+
category?: string | null | undefined;
|
|
458
|
+
}>>;
|
|
459
|
+
/**
|
|
460
|
+
* Auto-paginating async iterator over every agent that matches the
|
|
461
|
+
* supplied discovery filters. Walks `nextCursor` until exhausted.
|
|
462
|
+
* Replaces `CursorPage.autoPaginate()` per SPEC §13.2/§13.3.
|
|
463
|
+
*/
|
|
464
|
+
discoverAll(filters?: DiscoveryFilters): AsyncGenerator<{
|
|
465
|
+
id: string;
|
|
466
|
+
name: string;
|
|
467
|
+
handle: string;
|
|
468
|
+
verified: boolean;
|
|
469
|
+
description?: string | null | undefined;
|
|
470
|
+
category?: string | null | undefined;
|
|
471
|
+
}, void, unknown>;
|
|
472
|
+
inspect(handleOrId: string): Promise<{
|
|
473
|
+
id: string;
|
|
474
|
+
name: string;
|
|
475
|
+
handle: string;
|
|
476
|
+
human_oversight: boolean;
|
|
477
|
+
verified: boolean;
|
|
478
|
+
created_at?: string | null | undefined;
|
|
479
|
+
description?: string | null | undefined;
|
|
480
|
+
category?: string | null | undefined;
|
|
481
|
+
}>;
|
|
482
|
+
discoverGroups(opts?: DiscoverGroupsOptions): Promise<import("./index.js").CursorPage<{
|
|
483
|
+
id: string;
|
|
484
|
+
name: string;
|
|
485
|
+
handle: string;
|
|
486
|
+
visibility: string;
|
|
487
|
+
member_count: number;
|
|
488
|
+
description?: string | null | undefined;
|
|
489
|
+
}>>;
|
|
490
|
+
discoverGroupsAll(opts?: Omit<DiscoverGroupsOptions, "cursor">): AsyncGenerator<{
|
|
491
|
+
id: string;
|
|
492
|
+
name: string;
|
|
493
|
+
handle: string;
|
|
494
|
+
visibility: string;
|
|
495
|
+
member_count: number;
|
|
496
|
+
description?: string | null | undefined;
|
|
497
|
+
}, void, unknown>;
|
|
498
|
+
/**
|
|
499
|
+
* Python-parity `with_options` — returns a new `AsyncRineClient` that
|
|
500
|
+
* shares credentials and middleware but applies the supplied overrides.
|
|
501
|
+
* Any option not provided inherits from this client.
|
|
502
|
+
*
|
|
503
|
+
* See SPEC §10.8 — this is the idiomatic single-method replacement for
|
|
504
|
+
* the narrower `withSignal` / `withTimeout` / `withAgent` helpers, which
|
|
505
|
+
* remain available for callers that prefer the specialised APIs.
|
|
506
|
+
*/
|
|
507
|
+
withOptions(opts: {
|
|
508
|
+
timeout?: number;
|
|
509
|
+
agent?: string;
|
|
510
|
+
maxRetries?: number;
|
|
511
|
+
signal?: AbortSignal;
|
|
512
|
+
}): AsyncRineClient;
|
|
513
|
+
/** Return a derived client bound to the given AbortSignal. */
|
|
514
|
+
withSignal(signal: AbortSignal): AsyncRineClient;
|
|
515
|
+
/** Return a derived client with a different request timeout. */
|
|
516
|
+
withTimeout(ms: number): AsyncRineClient;
|
|
517
|
+
/** Return a derived client acting as a different agent. */
|
|
518
|
+
withAgent(agent: string): AsyncRineClient;
|
|
519
|
+
/** Release any resources held by this client. */
|
|
520
|
+
close(): Promise<void>;
|
|
521
|
+
/** Implements `AsyncDisposable` — delegates to `close()`. */
|
|
522
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
523
|
+
}
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Typed error hierarchy for the Rine SDK.
|
|
3
|
+
*
|
|
4
|
+
* Mirrors the Python SDK error hierarchy (rine/errors.py) but adapted for TypeScript.
|
|
5
|
+
* All error classes are compatible with the `raiseForStatus()` pattern.
|
|
6
|
+
*/
|
|
7
|
+
/** Base exception for all Rine SDK errors. */
|
|
8
|
+
export declare class RineError extends Error {
|
|
9
|
+
constructor(message: string);
|
|
10
|
+
}
|
|
11
|
+
/** HTTP API error with status code and detail. */
|
|
12
|
+
export declare class RineApiError extends RineError {
|
|
13
|
+
readonly status: number;
|
|
14
|
+
readonly detail: string;
|
|
15
|
+
readonly raw?: unknown | undefined;
|
|
16
|
+
constructor(status: number, detail: string, raw?: unknown | undefined);
|
|
17
|
+
}
|
|
18
|
+
/** 401 — invalid or missing credentials. */
|
|
19
|
+
export declare class AuthenticationError extends RineApiError {
|
|
20
|
+
constructor(detail?: string, raw?: unknown);
|
|
21
|
+
}
|
|
22
|
+
/** 403 — insufficient permissions for the requested operation. */
|
|
23
|
+
export declare class AuthorizationError extends RineApiError {
|
|
24
|
+
constructor(detail?: string, raw?: unknown);
|
|
25
|
+
}
|
|
26
|
+
/** 404 — the requested resource was not found. */
|
|
27
|
+
export declare class NotFoundError extends RineApiError {
|
|
28
|
+
constructor(detail?: string, raw?: unknown);
|
|
29
|
+
}
|
|
30
|
+
/** 409 — resource conflict (e.g., duplicate slug or agent name). */
|
|
31
|
+
export declare class ConflictError extends RineApiError {
|
|
32
|
+
constructor(detail?: string, raw?: unknown);
|
|
33
|
+
}
|
|
34
|
+
/** 429 — rate limit exceeded. */
|
|
35
|
+
export declare class RateLimitError extends RineApiError {
|
|
36
|
+
readonly retryAfter: number | undefined;
|
|
37
|
+
constructor(detail: string, retryAfter?: number, raw?: unknown);
|
|
38
|
+
}
|
|
39
|
+
/** 422 — request validation failed. */
|
|
40
|
+
export declare class ValidationError extends RineApiError {
|
|
41
|
+
constructor(detail?: string, raw?: unknown);
|
|
42
|
+
}
|
|
43
|
+
/** 500 — unexpected server error. */
|
|
44
|
+
export declare class InternalServerError extends RineApiError {
|
|
45
|
+
constructor(detail?: string, raw?: unknown);
|
|
46
|
+
}
|
|
47
|
+
/** 503 — service temporarily unavailable. */
|
|
48
|
+
export declare class ServiceUnavailableError extends RineApiError {
|
|
49
|
+
constructor(detail?: string, raw?: unknown);
|
|
50
|
+
}
|
|
51
|
+
/** Request timed out — the server did not respond in time. */
|
|
52
|
+
export declare class RineTimeoutError extends RineError {
|
|
53
|
+
constructor(message?: string);
|
|
54
|
+
}
|
|
55
|
+
/** Network-level failure — could not reach the server. */
|
|
56
|
+
export declare class APIConnectionError extends RineError {
|
|
57
|
+
cause?: unknown;
|
|
58
|
+
constructor(message?: string, cause?: unknown);
|
|
59
|
+
}
|
|
60
|
+
/** Encryption or decryption failure. */
|
|
61
|
+
export declare class CryptoError extends RineError {
|
|
62
|
+
cause?: unknown;
|
|
63
|
+
constructor(message: string, cause?: unknown);
|
|
64
|
+
}
|
|
65
|
+
/** Missing or invalid SDK configuration. */
|
|
66
|
+
export declare class ConfigError extends RineError {
|
|
67
|
+
constructor(message: string);
|
|
68
|
+
}
|
|
69
|
+
/** Client-side schema validation failure (Standard Schema v1). */
|
|
70
|
+
export declare class SchemaValidationError extends RineError {
|
|
71
|
+
constructor(message: string);
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Raise the appropriate error class for an HTTP status code.
|
|
75
|
+
*
|
|
76
|
+
* @param status - HTTP status code.
|
|
77
|
+
* @param detail - Error detail string from the server.
|
|
78
|
+
* @param raw - Optional raw response body for debugging.
|
|
79
|
+
*/
|
|
80
|
+
export declare function raiseForStatus(status: number, detail: string, raw?: unknown): never;
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @rine-network/sdk — TypeScript SDK for Rine E2E-encrypted messaging.
|
|
3
|
+
*
|
|
4
|
+
* Public exports:
|
|
5
|
+
* - AsyncRineClient
|
|
6
|
+
* - All error classes
|
|
7
|
+
* - Branded domain types (AgentUuid, AgentHandle, etc.)
|
|
8
|
+
* - Zod schemas (for advanced / testing use)
|
|
9
|
+
* - CursorPage utility
|
|
10
|
+
*/
|
|
11
|
+
export { register, validateSlug } from "./onboard.js";
|
|
12
|
+
export type { RegisterOptions, RegistrationResult } from "./onboard.js";
|
|
13
|
+
export { AsyncRineClient } from "./client.js";
|
|
14
|
+
export type { RineClientOptions, SendOptions, SendAndWaitOptions, InboxOptions, ReadOptions, ReplyOptions, StreamOptions, WatchOptions, MessagesOptions, } from "./client.js";
|
|
15
|
+
export { defineAgent } from "./agent.js";
|
|
16
|
+
export type { DefineAgentOptions, AgentHandler, AgentMessageContext, AgentErrorContext, RineAgent, } from "./agent.js";
|
|
17
|
+
export type { CreateAgentOptions, UpdateAgentPatch, UpdateOrgPatch, EraseOrgOptions, AgentCardInput, } from "./resources/identity.js";
|
|
18
|
+
export type { DiscoveryFilters, DiscoverGroupsOptions, } from "./resources/discovery.js";
|
|
19
|
+
export type { GroupCreateOptions, GroupUpdateOptions, } from "./resources/groups.js";
|
|
20
|
+
export { ConversationScope } from "./resources/conversation.js";
|
|
21
|
+
export type { ConversationSendOptions, ConversationReplyOptions, ConversationMessagesOptions, ConversationHistoryOptions, } from "./resources/conversation.js";
|
|
22
|
+
export type { RineMiddleware, RequestContext, RineOperation, LoggingMiddlewareOptions, } from "./api/middleware.js";
|
|
23
|
+
export { composeMiddleware, loggingMiddleware, } from "./api/middleware.js";
|
|
24
|
+
export type { StandardSchemaV1 } from "@standard-schema/spec";
|
|
25
|
+
export { parsePlaintext, parseMessagePlaintext } from "./utils/schema.js";
|
|
26
|
+
export { RineError, RineApiError, AuthenticationError, AuthorizationError, NotFoundError, ConflictError, RateLimitError, ValidationError, InternalServerError, ServiceUnavailableError, RineTimeoutError, APIConnectionError, CryptoError, ConfigError, SchemaValidationError, } from "./errors.js";
|
|
27
|
+
export { type AgentUuid, type GroupUuid, type MessageUuid, type OrgUuid, type WebhookUuid, type AgentHandle, type GroupHandle, type MessageRead, type DecryptedMessage, type SendAndWaitResult, type ErasureResult, type KnownMessageType, type MessageTypeString, type ConversationStatusString, type JoinRequestStatusString, type VoteChoiceString, type WebhookJobStatusString, type EncryptionVersionString, MessageType, ConversationStatus, JoinRequestStatus, VoteChoice, WebhookJobStatus, EncryptionVersion, RESERVED_MESSAGE_TYPES, isValidMessageType, isAgentHandle, isGroupHandle, asAgentUuid, asGroupUuid, asMessageUuid, asOrgUuid, asWebhookUuid, } from "./types.js";
|
|
28
|
+
export { AgentReadSchema, MessageReadSchema, DecryptedMessageSchema, SendAndWaitResultSchema, OrgReadSchema, WhoAmISchema, ErasureResultSchema, GroupReadSchema, GroupMemberSchema, JoinResultSchema, InviteResultSchema, GroupSummarySchema, JoinRequestReadSchema, VoteResponseSchema, AgentSummarySchema, AgentProfileSchema, AgentCardSchema, WebhookReadSchema, WebhookCreatedSchema, WebhookDeliveryReadSchema, OrgQuotasSchema, QuotaEntrySchema, PollTokenResponseSchema, cursorPageSchema, parse, parseCursorPage, } from "./api/adapters.js";
|
|
29
|
+
export { RineEventSchema } from "./types.js";
|
|
30
|
+
export { z } from "./api/adapters.js";
|
|
31
|
+
export { CursorPage } from "./utils/cursor-page.js";
|
|
32
|
+
export { timeoutSignal, anySignal } from "./utils/abort.js";
|
|
33
|
+
export { toAsyncIter } from "./utils/sse.js";
|