hiloop-sdk 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { HiloopClient, HiloopError } from "./client.js";
 export type { HiloopClientOptions } from "./client.js";
+export { HiloopWsClient } from "./ws.js";
+export type { HiloopWsClientOptions, WsEventType, WsEventHandler } from "./ws.js";
 export { generateKeyPair, deriveKeyPairFromApiKey, computeFingerprint, encrypt, decrypt, encryptAes, decryptAes, deriveWrappingKey, CryptoContext } from "./crypto.js";
 export type { KeyPair, ContentWrappingResult } from "./crypto.js";
 export type { Interaction, InteractionType, InteractionStatus, Priority, Message, PaginatedResult, CreateInteractionOptions, ConvSession, ConvSessionType, ConvSessionStatus, ConvSessionRole, ConvSessionParticipant, ConvSessionMessage, GuestToken, CreateConvSessionOptions, Channel, ChannelStatus, ChannelMessage, ChannelParticipant, CreateChannelOptions, FileChangeStatus, CommandInvocationStatus, AgentCommand, CommandInvocation, } from "./types.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { HiloopClient, HiloopError } from "./client.js";
+export { HiloopWsClient } from "./ws.js";
 export { generateKeyPair, deriveKeyPairFromApiKey, computeFingerprint, encrypt, decrypt, encryptAes, decryptAes, deriveWrappingKey, CryptoContext } from "./crypto.js";
 export { parseInteraction, parseMessage, parseConvSession, parseConvSessionMessage, parseGuestToken, parseChannel, parseChannelMessage, parseChannelParticipant, } from "./types.js";

package/dist/ws.d.ts

@@ -0,0 +1,64 @@
+/**
+ * HiloopWsClient — real-time WebSocket client for agents.
+ *
+ * Usage:
+ *   const ws = new HiloopWsClient({
+ *     apiKey: "hlp_space_...",
+ *     agentName: "my-bot",
+ *   });
+ *   ws.on("session.message.new", (msg) => console.log(msg.content));
+ *   await ws.connect();
+ *   ws.subscribe(`session:${sessionId}`);
+ *   ws.sendSessionMessage(sessionId, "Hello!");
+ */
+export interface HiloopWsClientOptions {
+    apiKey: string;
+    /** Agent name (required for space API keys, auto-creates if needed). */
+    agentName?: string;
+    baseUrl?: string;
+    /** Auto-reconnect on disconnect (default: true). */
+    autoReconnect?: boolean;
+    /** Max reconnect delay in ms (default: 30000). */
+    maxReconnectDelay?: number;
+}
+export type WsEventType = "connected" | "session.message.new" | "session.message.sent" | "interaction.created" | "interaction.sent" | "interaction.updated" | "interaction.message.new" | "typing.start" | "typing.stop" | "session.closed" | "session.member.joined" | "session.member.left" | "subscribed" | "unsubscribed" | "error" | "pong";
+export type WsEventHandler = (data: any) => void;
+export declare class HiloopWsClient {
+    private ws;
+    private options;
+    private agentId;
+    private handlers;
+    private anyHandlers;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private closed;
+    private crypto;
+    private initPromise;
+    constructor(options: HiloopWsClientOptions);
+    /** Initialize encryption context (derives keypair from API key, fetches space key). */
+    private ensureCrypto;
+    private doInitCrypto;
+    /** Connect to the agent WebSocket. Returns when connected. */
+    connect(): Promise<void>;
+    /** Disconnect and stop reconnecting. */
+    disconnect(): void;
+    /** Subscribe to a topic (e.g., `session:<id>`, `agent:<id>`, `space:<id>`). */
+    subscribe(topic: string): void;
+    /** Unsubscribe from a topic. */
+    unsubscribe(topic: string): void;
+    /** Send a session message (auto-encrypts). */
+    sendSessionMessage(sessionId: string, content: string): Promise<void>;
+    /** Send a typing indicator. */
+    sendTyping(sessionId: string, isTyping: boolean): void;
+    /** Listen for a specific event type. */
+    on(eventType: WsEventType | string, handler: WsEventHandler): () => void;
+    /** Listen for all events. */
+    onAny(handler: WsEventHandler): () => void;
+    /** Remove all listeners for an event type. */
+    off(eventType: string): void;
+    /** Auto-decrypt a session message's encryptedContent field. */
+    decryptSessionMessage(encryptedContent: string): Promise<string | null>;
+    private send;
+    private emit;
+    private scheduleReconnect;
+}

package/dist/ws.js

@@ -0,0 +1,198 @@
+/**
+ * HiloopWsClient — real-time WebSocket client for agents.
+ *
+ * Usage:
+ *   const ws = new HiloopWsClient({
+ *     apiKey: "hlp_space_...",
+ *     agentName: "my-bot",
+ *   });
+ *   ws.on("session.message.new", (msg) => console.log(msg.content));
+ *   await ws.connect();
+ *   ws.subscribe(`session:${sessionId}`);
+ *   ws.sendSessionMessage(sessionId, "Hello!");
+ */
+import { CryptoContext, deriveKeyPairFromApiKey, computeFingerprint } from "./crypto.js";
+export class HiloopWsClient {
+    constructor(options) {
+        this.ws = null;
+        this.agentId = null;
+        this.handlers = new Map();
+        this.anyHandlers = new Set();
+        this.reconnectAttempts = 0;
+        this.reconnectTimer = null;
+        this.closed = false;
+        this.crypto = null;
+        this.initPromise = null;
+        this.options = options;
+    }
+    /** Initialize encryption context (derives keypair from API key, fetches space key). */
+    async ensureCrypto() {
+        if (this.crypto)
+            return;
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = this.doInitCrypto();
+        await this.initPromise;
+    }
+    async doInitCrypto() {
+        const kp = await deriveKeyPairFromApiKey(this.options.apiKey);
+        const baseUrl = (this.options.baseUrl ?? "https://api.hi-loop.com").replace(/\/$/, "");
+        const headers = {
+            "X-API-Key": this.options.apiKey,
+            "Content-Type": "application/json",
+        };
+        if (this.options.agentName)
+            headers["X-Agent"] = this.options.agentName;
+        // Register public key
+        const fingerprint = await computeFingerprint(kp.publicKey);
+        try {
+            await fetch(`${baseUrl}/v1/agent/keys/me`, { method: "PUT", headers, body: JSON.stringify({ publicKey: kp.publicKey, fingerprint }) });
+        }
+        catch { /* non-fatal */ }
+        // Fetch space encryption info
+        let spacePublicKey = "";
+        let spaceKeyId = "";
+        try {
+            const res = await fetch(`${baseUrl}/v1/agent/encryption-info`, { headers });
+            if (res.ok) {
+                const info = await res.json();
+                spacePublicKey = info.spacePublicKey;
+                spaceKeyId = info.spaceKeyId;
+            }
+        }
+        catch { /* non-fatal */ }
+        this.crypto = new CryptoContext(kp.secretKey, kp.publicKey, spacePublicKey, spaceKeyId);
+    }
+    /** Connect to the agent WebSocket. Returns when connected. */
+    async connect() {
+        await this.ensureCrypto();
+        this.closed = false;
+        return new Promise((resolve, reject) => {
+            const baseUrl = (this.options.baseUrl ?? "https://api.hi-loop.com").replace(/\/$/, "");
+            const wsUrl = baseUrl.replace(/^http/, "ws");
+            const params = new URLSearchParams({ key: this.options.apiKey });
+            if (this.options.agentName)
+                params.set("agent", this.options.agentName);
+            this.ws = new WebSocket(`${wsUrl}/v1/agent/ws?${params}`);
+            this.ws.onopen = () => {
+                this.reconnectAttempts = 0;
+            };
+            this.ws.onmessage = (event) => {
+                try {
+                    const data = JSON.parse(event.data);
+                    if (data.type === "connected") {
+                        this.agentId = data.agentId;
+                        resolve();
+                    }
+                    // Skip metadata-only message.new (agents get the richer session.message.new instead)
+                    if (data.type === "message.new") {
+                        return;
+                    }
+                    // Skip echoes: don't emit session messages sent by this agent
+                    if (data.type === "session.message.new" && data.senderType === "agent" && data.senderId === this.agentId) {
+                        return;
+                    }
+                    this.emit(data.type, data);
+                }
+                catch { /* ignore malformed */ }
+            };
+            this.ws.onclose = () => {
+                if (!this.closed && (this.options.autoReconnect ?? true)) {
+                    this.scheduleReconnect();
+                }
+            };
+            this.ws.onerror = (err) => {
+                if (this.reconnectAttempts === 0) {
+                    reject(err);
+                }
+            };
+        });
+    }
+    /** Disconnect and stop reconnecting. */
+    disconnect() {
+        this.closed = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+    /** Subscribe to a topic (e.g., `session:<id>`, `agent:<id>`, `space:<id>`). */
+    subscribe(topic) {
+        this.send({ type: "subscribe", topic });
+    }
+    /** Unsubscribe from a topic. */
+    unsubscribe(topic) {
+        this.send({ type: "unsubscribe", topic });
+    }
+    /** Send a session message (auto-encrypts). */
+    async sendSessionMessage(sessionId, content) {
+        await this.ensureCrypto();
+        const encryptedContent = await this.crypto.encryptSessionMessage(content);
+        this.send({ type: "session.send", sessionId, encryptedContent });
+    }
+    /** Send a typing indicator. */
+    sendTyping(sessionId, isTyping) {
+        this.send({ type: "typing", sessionId, isTyping });
+    }
+    /** Listen for a specific event type. */
+    on(eventType, handler) {
+        let handlers = this.handlers.get(eventType);
+        if (!handlers) {
+            handlers = new Set();
+            this.handlers.set(eventType, handlers);
+        }
+        handlers.add(handler);
+        return () => { handlers.delete(handler); };
+    }
+    /** Listen for all events. */
+    onAny(handler) {
+        this.anyHandlers.add(handler);
+        return () => { this.anyHandlers.delete(handler); };
+    }
+    /** Remove all listeners for an event type. */
+    off(eventType) {
+        this.handlers.delete(eventType);
+    }
+    /** Auto-decrypt a session message's encryptedContent field. */
+    async decryptSessionMessage(encryptedContent) {
+        await this.ensureCrypto();
+        return this.crypto.decryptSessionMessage(encryptedContent);
+    }
+    // -- Private ----------------------------------------------------------------
+    send(data) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(data));
+        }
+    }
+    emit(eventType, data) {
+        const handlers = this.handlers.get(eventType);
+        if (handlers) {
+            for (const h of handlers) {
+                try {
+                    h(data);
+                }
+                catch { /* don't break event loop */ }
+            }
+        }
+        for (const h of this.anyHandlers) {
+            try {
+                h(data);
+            }
+            catch { /* don't break event loop */ }
+        }
+    }
+    scheduleReconnect() {
+        const maxDelay = this.options.maxReconnectDelay ?? 30000;
+        const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), maxDelay);
+        this.reconnectAttempts++;
+        this.reconnectTimer = setTimeout(() => {
+            this.connect().catch(() => {
+                // reconnect will retry via onclose
+            });
+        }, delay);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hiloop-sdk",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "TypeScript SDK for Hiloop — zero-trust human-AI agent interaction platform",
   "type": "module",
   "main": "dist/index.js",