hiloop-sdk 0.2.0 → 0.4.0

package/dist/client.d.ts

@@ -7,6 +7,8 @@ export declare class HiloopError extends Error {
 }
 export interface HiloopClientOptions {
     apiKey: string;
+    /** Agent name. Auto-creates the agent if it doesn't exist (space API keys only). */
+    agentName?: string;
     baseUrl?: string;
     /** Agent's X25519 secret key (base64). Required for E2E encryption. */
     secretKey?: string;
@@ -38,6 +40,7 @@ export declare class HiloopClient {
     private ensureInitialized;
     private doInit;
     /** Raw HTTP request without triggering auto-init (used during init itself). */
+    private buildHeaders;
     private rawRequest;
     private encryptField;
     /**

package/dist/client.js

@@ -87,15 +87,20 @@ export class HiloopClient {
         this.initialized = true;
     }
     /** Raw HTTP request without triggering auto-init (used during init itself). */
-    async rawRequest(method, path, options) {
-        const url = `${this.baseUrl}/v1${path}`;
-        const headers = {
+    buildHeaders() {
+        const h = {
             "Content-Type": "application/json",
             "X-API-Key": this.apiKey,
         };
+        if (this.options.agentName)
+            h["X-Agent"] = this.options.agentName;
+        return h;
+    }
+    async rawRequest(method, path, options) {
+        const url = `${this.baseUrl}/v1${path}`;
         const res = await fetch(url, {
             method,
-            headers,
+            headers: this.buildHeaders(),
             body: options?.body ? JSON.stringify(options.body) : undefined,
         });
         if (!res.ok) {
@@ -115,6 +120,7 @@ export class HiloopClient {
      * with the same (scope, recipientKeyId) are silently dropped.
      */
     async encryptFields(fields) {
+        await this.ensureInitialized();
         const encrypted = {};
         const entries = Object.entries(fields).filter(([, v]) => v !== undefined);
         if (entries.length === 0)
@@ -158,10 +164,7 @@ export class HiloopClient {
         try {
             const res = await fetch(url, {
                 method,
-                headers: {
-                    "X-API-Key": this.apiKey,
-                    "Content-Type": "application/json",
-                },
+                headers: this.buildHeaders(),
                 body: options?.body !== undefined ? JSON.stringify(options.body) : undefined,
                 signal: controller.signal,
             });
@@ -184,7 +187,7 @@ export class HiloopClient {
         try {
             const res = await fetch(url, {
                 method: "GET",
-                headers: { "X-API-Key": this.apiKey },
+                headers: this.buildHeaders(),
                 signal: controller.signal,
             });
             if (!res.ok) {
@@ -358,6 +361,7 @@ export class HiloopClient {
     }
     /** Push content blocks to an interaction. */
     async pushContentBlocks(interactionId, blocks) {
+        await this.ensureInitialized();
         const encryptedBlocks = await Promise.all(blocks.map(async (block) => {
             const plaintext = JSON.stringify(block.data);
             const wrapped = await this.crypto.encryptWithWrapping(plaintext);
@@ -488,6 +492,7 @@ export class HiloopClient {
     }
     // -- Conversation Sessions -------------------------------------------------
     async createConvSession(opts) {
+        await this.ensureInitialized();
         const body = {
             sessionType: opts.sessionType ?? "direct",
             isPublic: opts.isPublic ?? false,
@@ -547,6 +552,7 @@ export class HiloopClient {
      * using the session message key (`{agentPub}:{AES-GCM ciphertext}` format).
      */
     async sendConvSessionMessage(sessionId, content) {
+        await this.ensureInitialized();
         const encryptedContent = await this.crypto.encryptSessionMessage(content);
         const data = await this.request("POST", `/agent/sessions/${sessionId}/messages`, { body: { encryptedContent } });
         return parseConvSessionMessage(data);
@@ -1039,6 +1045,7 @@ export class HiloopClient {
     // -- Channels ---------------------------------------------------------------
     /** Create a new agent-to-agent channel. */
     async createChannel(opts) {
+        await this.ensureInitialized();
         const body = {};
         if (opts.name !== undefined) {
             const w = await this.crypto.encryptWithWrapping(opts.name);
@@ -1095,6 +1102,7 @@ export class HiloopClient {
     }
     /** Send a message in a channel. */
     async sendChannelMessage(channelId, content) {
+        await this.ensureInitialized();
         const wrapped = await this.crypto.encryptWithWrapping(content);
         const body = {
             encryptedContent: wrapped.ciphertext,

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,63 @@
+/**
+ * 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 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,188 @@
+/**
+ * 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.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") {
+                        resolve();
+                    }
+                    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.2.0",
+  "version": "0.4.0",
   "description": "TypeScript SDK for Hiloop — zero-trust human-AI agent interaction platform",
   "type": "module",
   "main": "dist/index.js",