hiloop-sdk 0.8.7 → 0.9.1

package/dist/client.d.ts

@@ -17,8 +17,15 @@ export interface SendOptions {
 }
 export interface HiloopClientOptions {
     apiKey: string;
-    /** Agent name. Auto-creates the agent if it doesn't exist (space API keys only). */
-    agentName?: string;
+    /** Agent name or UUID. Sent as X-Hiloop header to identify the agent. */
+    agentName: string;
+    /**
+     * Space name. If provided, the SDK auto-creates the space on first use
+     * (idempotent — returns existing if slug matches). Requires a key with
+     * "owner" permission. The slug is derived from the name (lowercased,
+     * non-alphanumeric replaced with hyphens).
+     */
+    spaceName?: string;
     baseUrl?: string;
     /** Agent's X25519 secret key (base64). Required for E2E encryption. */
     secretKey?: string;
@@ -42,6 +49,8 @@ export declare class HiloopClient {
     private initialized;
     private initPromise;
     private options;
+    /** Cached spaceId after auto-creation resolves spaceName. */
+    private resolvedSpaceId;
     constructor(options: HiloopClientOptions);
     /**
      * Initialize encryption: derive keypair from API key, register public key,

package/dist/client.js

@@ -14,11 +14,9 @@ export class HiloopClient {
         this.publicKeyB64 = "";
         this.initialized = false;
         this.initPromise = null;
+        /** Cached spaceId after auto-creation resolves spaceName. */
+        this.resolvedSpaceId = null;
         this.apiKey = options.apiKey;
-        if (options.apiKey.startsWith("hlp_prov_")) {
-            throw new Error("Provisioning keys (hlp_prov_*) cannot be used with HiloopClient. " +
-                "Use the agent API key returned by POST /v1/provision/agents instead.");
-        }
         this.baseUrl = (options.baseUrl ?? "https://api.hi-loop.com").replace(/\/$/, "");
         this.timeout = options.timeout ?? 30000;
         this.options = options;
@@ -38,11 +36,7 @@ export class HiloopClient {
      * Initialize encryption: derive keypair from API key, register public key,
      * and fetch space encryption info. Called automatically on first API call.
      */
-    async ensureInitialized(agentName) {
-        // If an agentName is provided and we don't have one yet, store it for init
-        if (agentName && !this.options.agentName) {
-            this.options = { ...this.options, agentName };
-        }
+    async ensureInitialized() {
         if (this.initialized)
             return;
         if (this.initPromise)
@@ -51,6 +45,17 @@ export class HiloopClient {
         await this.initPromise;
     }
     async doInit() {
+        // 0. Auto-create space if spaceName is provided (idempotent)
+        if (this.options.spaceName && !this.resolvedSpaceId) {
+            const slug = this.options.spaceName.toLowerCase().replace(/[^a-z0-9]/g, "-").slice(0, 100);
+            try {
+                const space = await this.rawRequest("POST", "/org/spaces", { body: { name: this.options.spaceName, slug } });
+                this.resolvedSpaceId = space.id;
+            }
+            catch {
+                // Space creation failed — may not have owner permission, continue without
+            }
+        }
         // 1. Derive keypair from API key (or use provided keys)
         let secretKey = this.options.secretKey;
         let publicKey = this.options.publicKey;
@@ -96,14 +101,11 @@ export class HiloopClient {
     }
     /** Raw HTTP request without triggering auto-init (used during init itself). */
     buildHeaders(agentName) {
-        const h = {
+        return {
             "Content-Type": "application/json",
             "X-API-Key": this.apiKey,
+            "X-Hiloop": agentName ?? this.options.agentName,
         };
-        const agent = agentName ?? this.options.agentName;
-        if (agent)
-            h["X-Agent"] = agent;
-        return h;
     }
     async rawRequest(method, path, options) {
         const url = `${this.baseUrl}/v1${path}`;
@@ -319,7 +321,7 @@ export class HiloopClient {
     // -- Unified Message API ----------------------------------------------------
     /** Options for send / sendText. */
     async sendComponents(sessionId, components, opts) {
-        await this.ensureInitialized(opts?.agentName);
+        await this.ensureInitialized();
         const encryptedComponents = await this.crypto.encryptSessionMessage(JSON.stringify(components));
         const body = { encryptedComponents };
         // Extract metadata from components for server-side routing

package/dist/ws.d.ts

@@ -3,7 +3,7 @@
  *
  * Usage:
  *   const ws = new HiloopWsClient({
- *     apiKey: "hlp_space_...",
+ *     apiKey: "hlp_...",
  *     agentName: "my-bot",
  *   });
  *   ws.on("session.message.new", (msg) => console.log(msg.content));
@@ -13,8 +13,8 @@
  */
 export interface HiloopWsClientOptions {
     apiKey: string;
-    /** Agent name (required for space API keys, auto-creates if needed). */
-    agentName?: string;
+    /** Agent name or UUID. Sent as X-Hiloop header and query param. */
+    agentName: string;
     baseUrl?: string;
     /** Auto-reconnect on disconnect (default: true). */
     autoReconnect?: boolean;

package/dist/ws.js

@@ -3,7 +3,7 @@
  *
  * Usage:
  *   const ws = new HiloopWsClient({
- *     apiKey: "hlp_space_...",
+ *     apiKey: "hlp_...",
  *     agentName: "my-bot",
  *   });
  *   ws.on("session.message.new", (msg) => console.log(msg.content));
@@ -41,8 +41,7 @@ export class HiloopWsClient {
             "X-API-Key": this.options.apiKey,
             "Content-Type": "application/json",
         };
-        if (this.options.agentName)
-            headers["X-Agent"] = this.options.agentName;
+        headers["X-Hiloop"] = this.options.agentName;
         // Register public key
         const fingerprint = await computeFingerprint(kp.publicKey);
         try {
@@ -70,9 +69,7 @@ export class HiloopWsClient {
         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);
+            const params = new URLSearchParams({ key: this.options.apiKey, agent: this.options.agentName });
             this.ws = new WebSocket(`${wsUrl}/v1/agent/ws?${params}`);
             this.ws.onopen = () => {
                 this.reconnectAttempts = 0;

package/package.json

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