@nebula-ai/sdk 0.0.19

package/dist/index.mjs

@@ -0,0 +1,651 @@
+// src/types.ts
+var RetrievalType = /* @__PURE__ */ ((RetrievalType2) => {
+  RetrievalType2["BASIC"] = "basic";
+  RetrievalType2["ADVANCED"] = "advanced";
+  RetrievalType2["CUSTOM"] = "custom";
+  return RetrievalType2;
+})(RetrievalType || {});
+var GraphSearchResultType = /* @__PURE__ */ ((GraphSearchResultType2) => {
+  GraphSearchResultType2["ENTITY"] = "entity";
+  GraphSearchResultType2["RELATIONSHIP"] = "relationship";
+  GraphSearchResultType2["COMMUNITY"] = "community";
+  return GraphSearchResultType2;
+})(GraphSearchResultType || {});
+var NebulaException = class extends Error {
+  constructor(message, statusCode, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "NebulaException";
+  }
+};
+var NebulaClientException = class extends NebulaException {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "NebulaClientException";
+  }
+};
+var NebulaAuthenticationException = class extends NebulaException {
+  constructor(message = "Invalid API key") {
+    super(message, 401);
+    this.name = "NebulaAuthenticationException";
+  }
+};
+var NebulaRateLimitException = class extends NebulaException {
+  constructor(message = "Rate limit exceeded") {
+    super(message, 429);
+    this.name = "NebulaRateLimitException";
+  }
+};
+var NebulaValidationException = class extends NebulaException {
+  constructor(message = "Validation error", details) {
+    super(message, 400);
+    this.details = details;
+    this.name = "NebulaValidationException";
+  }
+};
+var NebulaClusterNotFoundException = class extends NebulaException {
+  constructor(message = "Cluster not found") {
+    super(message, 404);
+    this.name = "NebulaClusterNotFoundException";
+  }
+};
+
+// src/client.ts
+var NebulaSDK = class {
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    if (!this.apiKey) {
+      throw new NebulaClientException(
+        "API key is required. Pass it to the constructor or set NEBULA_API_KEY environment variable."
+      );
+    }
+    this.baseUrl = (config.baseUrl || "https://api.nebulacloud.app").replace(/\/$/, "");
+    this.timeout = config.timeout || 3e4;
+  }
+  // Public mutators used by tests
+  setApiKey(next) {
+    this.apiKey = next;
+  }
+  setBaseUrl(next) {
+    this.baseUrl = (next || this.baseUrl).replace(/\/$/, "");
+  }
+  // Kept for backwards-compat tests; no-op in current implementation
+  setCorsProxy(_next) {
+  }
+  /** Check if API key is set */
+  isApiKeySet() {
+    return !!(this.apiKey && this.apiKey.trim() !== "");
+  }
+  /** Detect if a token looks like a Nebula API key (public.raw) */
+  _isNebulaApiKey(token) {
+    const candidate = token || this.apiKey;
+    if (!candidate) return false;
+    const parts = candidate.split(".");
+    if (parts.length !== 2) return false;
+    const [publicPart, rawPart] = parts;
+    return publicPart.startsWith("key_") && !!rawPart && rawPart.length > 0;
+  }
+  /** Build authentication headers */
+  _buildAuthHeaders(includeContentType = true) {
+    const headers = {};
+    if (this._isNebulaApiKey()) {
+      headers["X-API-Key"] = this.apiKey;
+    } else {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    if (includeContentType) {
+      headers["Content-Type"] = "application/json";
+    }
+    return headers;
+  }
+  /** Make an HTTP request to the Nebula API */
+  async _makeRequest(method, endpoint, jsonData, params) {
+    const url = new URL(endpoint, this.baseUrl);
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+    const headers = this._buildAuthHeaders(true);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url.toString(), {
+        method,
+        headers,
+        body: jsonData ? JSON.stringify(jsonData) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (response.status === 200) {
+        return await response.json();
+      } else if (response.status === 401) {
+        throw new NebulaAuthenticationException("Invalid API key");
+      } else if (response.status === 429) {
+        throw new NebulaRateLimitException("Rate limit exceeded");
+      } else if (response.status === 400) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new NebulaValidationException(errorData.message || "Validation error", errorData.details);
+      } else {
+        const errorData = await response.json().catch(() => ({}));
+        throw new NebulaException(errorData.message || `API error: ${response.status}`, response.status, errorData);
+      }
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof NebulaException) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new NebulaClientException(`Request timed out after ${this.timeout} milliseconds`);
+      }
+      if (error instanceof Error) {
+        throw new NebulaClientException(`Request failed: ${error.message}`, error);
+      }
+      throw new NebulaClientException(`Request failed: ${String(error)}`);
+    }
+  }
+  // Cluster Management Methods
+  /** Create a new cluster */
+  async createCluster(name, description, metadata) {
+    const data = { name };
+    if (description) data.description = description;
+    if (metadata) data.metadata = metadata;
+    const response = await this._makeRequest("POST", "/v3/collections", data);
+    const result = response.results || response;
+    return this._clusterFromDict(result);
+  }
+  /** Get a specific cluster by ID */
+  async getCluster(clusterId) {
+    const response = await this._makeRequest("GET", `/v3/collections/${clusterId}`);
+    const result = response.results || response;
+    return this._clusterFromDict(result);
+  }
+  /** Get a specific cluster by name */
+  async getClusterByName(name) {
+    const response = await this._makeRequest("GET", `/v3/collections/name/${name}`);
+    const result = response.results || response;
+    return this._clusterFromDict(result);
+  }
+  /** Get all clusters */
+  async listClusters(limit = 100, offset = 0) {
+    const params = { limit, offset };
+    const response = await this._makeRequest("GET", "/v3/collections", void 0, params);
+    let clusters;
+    if (response.results) {
+      clusters = response.results;
+    } else if (Array.isArray(response)) {
+      clusters = response;
+    } else {
+      clusters = [response];
+    }
+    return clusters.map((cluster) => this._clusterFromDict(cluster));
+  }
+  // Conversations Methods
+  /** List conversations for the authenticated user */
+  async listConversations(limit = 100, offset = 0) {
+    const params = { limit, offset };
+    const response = await this._makeRequest("GET", "/v3/conversations", void 0, params);
+    let conversations;
+    if (response && response.results) {
+      conversations = response.results;
+    } else if (Array.isArray(response)) {
+      conversations = response;
+    } else {
+      conversations = response ? [response] : [];
+    }
+    return conversations;
+  }
+  /** Update a cluster */
+  async updateCluster(clusterId, name, description, metadata) {
+    const data = {};
+    if (name !== void 0) data.name = name;
+    if (description !== void 0) data.description = description;
+    if (metadata !== void 0) data.metadata = metadata;
+    const response = await this._makeRequest("POST", `/v3/collections/${clusterId}`, data);
+    const result = response.results || response;
+    return this._clusterFromDict(result);
+  }
+  /** Delete a cluster */
+  async deleteCluster(clusterId) {
+    await this._makeRequest("DELETE", `/v3/collections/${clusterId}`);
+    return true;
+  }
+  // Memory Management Methods
+  /**
+   * Legacy convenience: store raw text content into a cluster as a document
+   */
+  async store(content, clusterId, metadata = {}) {
+    const docMetadata = {
+      ...metadata,
+      memory_type: "memory",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const data = {
+      metadata: JSON.stringify(docMetadata),
+      ingestion_mode: "fast",
+      collection_ids: JSON.stringify([clusterId]),
+      raw_text: String(content || "")
+    };
+    const url = `${this.baseUrl}/v3/documents`;
+    const headers = this._buildAuthHeaders(false);
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: this._formDataFromObject(data)
+    });
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      throw new NebulaException(
+        errorData.message || `Failed to create document: ${response.status}`,
+        response.status,
+        errorData
+      );
+    }
+    const respData = await response.json();
+    const id = respData?.results?.document_id || respData?.results?.id || respData?.id || "";
+    const result = {
+      id: String(id),
+      content: String(content || ""),
+      metadata: docMetadata,
+      cluster_ids: [clusterId],
+      created_at: docMetadata.timestamp,
+      updated_at: docMetadata.timestamp
+    };
+    return result;
+  }
+  /** Store a single memory */
+  async storeMemory(memory) {
+    let mem;
+    if ("cluster_id" in memory) {
+      mem = memory;
+    } else {
+      mem = {
+        cluster_id: memory.cluster_id,
+        content: memory.content,
+        role: memory.role,
+        parent_id: memory.parent_id,
+        metadata: memory.metadata || {}
+      };
+    }
+    if (mem.role) {
+      let convId = mem.parent_id;
+      if (!convId) {
+        const created = await this._makeRequest("POST", "/v3/conversations", {});
+        const conv = created.results || created;
+        convId = conv.id;
+        if (!convId) {
+          throw new NebulaClientException("Failed to create conversation: no id returned");
+        }
+      }
+      const payload = {
+        messages: [
+          {
+            content: String(mem.content),
+            role: mem.role,
+            metadata: mem.metadata
+          }
+        ],
+        collection_id: mem.cluster_id
+      };
+      await this._makeRequest("POST", `/v3/conversations/${convId}/messages`, payload);
+      return String(convId);
+    }
+    const contentText = String(mem.content || "");
+    const contentHash = await this._sha256(contentText);
+    const docMetadata = { ...mem.metadata };
+    docMetadata.memory_type = "memory";
+    docMetadata.content_hash = contentHash;
+    const data = {
+      metadata: JSON.stringify(docMetadata),
+      ingestion_mode: "fast",
+      collection_ids: JSON.stringify([mem.cluster_id]),
+      raw_text: contentText
+    };
+    const url = `${this.baseUrl}/v3/documents`;
+    const headers = this._buildAuthHeaders(false);
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: this._formDataFromObject(data)
+    });
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      throw new NebulaException(
+        errorData.message || `Failed to create document: ${response.status}`,
+        response.status,
+        errorData
+      );
+    }
+    const respData = await response.json();
+    if (respData.results) {
+      if (respData.results.document_id) return String(respData.results.document_id);
+      if (respData.results.id) return String(respData.results.id);
+    }
+    return "";
+  }
+  /** Store multiple memories */
+  async storeMemories(memories) {
+    const results = [];
+    const convGroups = {};
+    const others = [];
+    for (const m of memories) {
+      if (m.role) {
+        const key = m.parent_id || `__new__::${m.cluster_id}`;
+        if (!convGroups[key]) convGroups[key] = [];
+        convGroups[key].push(m);
+      } else {
+        others.push(m);
+      }
+    }
+    for (const [key, group] of Object.entries(convGroups)) {
+      const clusterId = group[0].cluster_id;
+      let convId;
+      if (key.startsWith("__new__::")) {
+        const created = await this._makeRequest("POST", "/v3/conversations", {});
+        const conv = created.results || created;
+        convId = conv.id;
+        if (!convId) {
+          throw new NebulaClientException("Failed to create conversation: no id returned");
+        }
+      } else {
+        convId = key;
+      }
+      const messages = group.map((m) => ({
+        content: String(m.content || ""),
+        role: m.role,
+        metadata: m.metadata || {}
+      }));
+      const payload = { messages, collection_id: clusterId };
+      await this._makeRequest("POST", `/v3/conversations/${convId}/messages`, payload);
+      results.push(...Array(group.length).fill(String(convId)));
+    }
+    for (const m of others) {
+      results.push(await this.storeMemory(m));
+    }
+    return results;
+  }
+  /** Delete a specific memory */
+  async delete(memoryId) {
+    try {
+      await this._makeRequest("DELETE", `/v3/documents/${memoryId}`);
+      return true;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw error;
+      }
+      throw new NebulaClientException(`Unknown error: ${String(error)}`);
+    }
+  }
+  /** Get all memories from specific clusters */
+  async listMemories(clusterIds, limit = 100, offset = 0) {
+    const ids = Array.isArray(clusterIds) ? clusterIds : [clusterIds];
+    if (!ids.length) {
+      throw new NebulaClientException("cluster_ids must be provided to list_memories().");
+    }
+    const params = { limit, offset, collection_ids: ids };
+    const response = await this._makeRequest("GET", "/v3/documents", void 0, params);
+    let documents;
+    if (response.results) {
+      documents = response.results;
+    } else if (Array.isArray(response)) {
+      documents = response;
+    } else {
+      documents = [response];
+    }
+    return documents.map((doc) => this._memoryResponseFromDict(doc, ids));
+  }
+  /** Get a specific memory by ID */
+  async getMemory(memoryId) {
+    const response = await this._makeRequest("GET", `/v3/documents/${memoryId}`);
+    const content = response.text || response.content;
+    const chunks = Array.isArray(response.chunks) ? response.chunks : void 0;
+    const memoryData = {
+      id: response.id,
+      content,
+      chunks,
+      metadata: response.metadata || {},
+      collection_ids: response.collection_ids || []
+    };
+    return this._memoryResponseFromDict(memoryData, []);
+  }
+  // Search Methods
+  /** Search within specific clusters */
+  async search(query, clusters, limitOrOptions, retrievalType = "advanced" /* ADVANCED */, filters, searchSettings) {
+    const clusterIds = Array.isArray(clusters) ? clusters : [clusters];
+    if (!clusterIds.length) {
+      throw new NebulaClientException("cluster_ids must be provided to search().");
+    }
+    let limit = 10;
+    if (typeof limitOrOptions === "number") {
+      limit = limitOrOptions;
+    } else if (typeof limitOrOptions === "object" && limitOrOptions) {
+      if (typeof limitOrOptions.limit === "number") limit = limitOrOptions.limit;
+    }
+    if (typeof retrievalType === "string") {
+      retrievalType = RetrievalType[retrievalType.toUpperCase()] || "advanced" /* ADVANCED */;
+    }
+    const effectiveSettings = { ...searchSettings };
+    effectiveSettings.limit = limit;
+    effectiveSettings.use_semantic_search = false;
+    effectiveSettings.use_fulltext_search = false;
+    effectiveSettings.use_hybrid_search = false;
+    effectiveSettings.chunk_settings = {
+      ...effectiveSettings.chunk_settings || {},
+      enabled: false
+    };
+    effectiveSettings.search_strategy = "rag_fusion";
+    effectiveSettings.num_sub_queries = 3;
+    const gs = { ...effectiveSettings.graph_settings };
+    gs.enabled = true;
+    gs.bfs_enabled = true;
+    gs.bfs_max_depth = 2;
+    effectiveSettings.graph_settings = gs;
+    if (retrievalType !== "advanced" /* ADVANCED */) {
+      effectiveSettings.retrieval_type = retrievalType;
+    }
+    const userFilters = { ...effectiveSettings.filters };
+    if (filters) {
+      Object.assign(userFilters, filters);
+    }
+    userFilters.collection_ids = { $overlap: clusterIds };
+    effectiveSettings.filters = userFilters;
+    const data = {
+      query,
+      search_mode: "custom",
+      search_settings: effectiveSettings
+    };
+    const response = await this._makeRequest("POST", "/v3/retrieval/search", data);
+    let chunkResults = [];
+    let graphResults = [];
+    if (response.results) {
+      chunkResults = response.results.chunk_search_results || [];
+      graphResults = response.results.graph_search_results || [];
+    }
+    const out = [];
+    out.push(...chunkResults.map((result) => this._searchResultFromDict(result)));
+    for (const g of graphResults) {
+      out.push(this._searchResultFromGraphDict(g));
+    }
+    return out;
+  }
+  /**
+   * Legacy wrapper: store a two-message conversation turn as a document
+   */
+  async storeConversation(userMessage, assistantMessage, clusterId, sessionId) {
+    const content = `User: ${String(userMessage || "")}
+Assistant: ${String(assistantMessage || "")}`;
+    const metadata = { session_id: sessionId, content_type: "conversation" };
+    return this.store(content, clusterId, metadata);
+  }
+  /**
+   * Legacy wrapper: search conversations optionally scoped by session
+   */
+  async searchConversations(query, clusterId, sessionId, includeAllSessions = true) {
+    const filters = { "metadata.content_type": "conversation" };
+    if (sessionId && !includeAllSessions) {
+      filters["metadata.session_id"] = sessionId;
+    }
+    return this.search(query, [clusterId], { limit: 10 }, "advanced" /* ADVANCED */, filters);
+  }
+  // Health Check
+  async healthCheck() {
+    return this._makeRequest("GET", "/health");
+  }
+  // Helpers
+  _clusterFromDict(data) {
+    let createdAt;
+    if (data.created_at) {
+      createdAt = typeof data.created_at === "string" ? data.created_at : data.created_at.toISOString();
+    }
+    let updatedAt;
+    if (data.updated_at) {
+      updatedAt = typeof data.updated_at === "string" ? data.updated_at : data.updated_at.toISOString();
+    }
+    const clusterId = String(data.id || "");
+    const clusterName = data.name || "";
+    const clusterDescription = data.description;
+    const clusterOwnerId = data.owner_id ? String(data.owner_id) : void 0;
+    const memoryCount = data.document_count || 0;
+    const metadata = {
+      graph_cluster_status: data.graph_cluster_status || "",
+      graph_sync_status: data.graph_sync_status || "",
+      user_count: data.user_count || 0,
+      document_count: data.document_count || 0
+    };
+    return {
+      id: clusterId,
+      name: clusterName,
+      description: clusterDescription,
+      metadata,
+      created_at: createdAt,
+      updated_at: updatedAt,
+      memory_count: memoryCount,
+      owner_id: clusterOwnerId
+    };
+  }
+  _memoryResponseFromDict(data, clusterIds) {
+    let createdAt;
+    if (data.created_at) {
+      createdAt = typeof data.created_at === "string" ? data.created_at : data.created_at.toISOString();
+    }
+    let updatedAt;
+    if (data.updated_at) {
+      updatedAt = typeof data.updated_at === "string" ? data.updated_at : data.updated_at.toISOString();
+    }
+    const memoryId = String(data.id || "");
+    const content = data.content || data.text;
+    let chunks;
+    if (data.chunks && Array.isArray(data.chunks)) {
+      if (data.chunks.every((x) => typeof x === "string")) {
+        chunks = data.chunks;
+      } else {
+        chunks = data.chunks.filter((item) => item && typeof item === "object" && "text" in item).map((item) => item.text);
+      }
+    }
+    const metadata = { ...data.metadata };
+    if (data.document_id) {
+      metadata.document_id = data.document_id;
+    }
+    let finalId = memoryId;
+    if (data.document_id && !memoryId) {
+      finalId = data.document_id;
+    }
+    if (data.document_metadata) {
+      Object.assign(metadata, data.document_metadata);
+    }
+    return {
+      id: finalId,
+      content,
+      chunks,
+      metadata,
+      cluster_ids: data.collection_ids || clusterIds,
+      created_at: createdAt,
+      updated_at: updatedAt
+    };
+  }
+  _searchResultFromDict(data) {
+    const content = data.content || data.text || "";
+    const resultId = data.id || data.chunk_id || "";
+    return {
+      id: String(resultId),
+      content: String(content),
+      score: Number(data.score || 0),
+      metadata: data.metadata || {},
+      source: data.source
+    };
+  }
+  _searchResultFromGraphDict(data) {
+    const rid = data.id ? String(data.id) : "";
+    const rtype = GraphSearchResultType[(data.result_type || "entity").toUpperCase()] || "entity" /* ENTITY */;
+    const content = data.content || {};
+    const score = data.score !== void 0 ? Number(data.score) : 0;
+    const metadata = data.metadata || {};
+    const chunkIds = Array.isArray(data.chunk_ids) ? data.chunk_ids : void 0;
+    let entity;
+    let rel;
+    let comm;
+    if (rtype === "entity" /* ENTITY */) {
+      entity = {
+        id: content.id ? String(content.id) : void 0,
+        name: content.name || "",
+        description: content.description || "",
+        metadata: content.metadata || {}
+      };
+    } else if (rtype === "relationship" /* RELATIONSHIP */) {
+      rel = {
+        id: content.id ? String(content.id) : void 0,
+        subject: content.subject || "",
+        predicate: content.predicate || "",
+        object: content.object || "",
+        subject_id: content.subject_id ? String(content.subject_id) : void 0,
+        object_id: content.object_id ? String(content.object_id) : void 0,
+        description: content.description,
+        metadata: content.metadata || {}
+      };
+    } else {
+      comm = {
+        id: content.id ? String(content.id) : void 0,
+        name: content.name || "",
+        summary: content.summary || "",
+        metadata: content.metadata || {}
+      };
+    }
+    return {
+      id: rid,
+      score,
+      metadata,
+      source: "graph",
+      content: void 0,
+      graph_result_type: rtype,
+      graph_entity: entity,
+      graph_relationship: rel,
+      graph_community: comm,
+      chunk_ids: chunkIds
+    };
+  }
+  async _sha256(message) {
+    const msgBuffer = new TextEncoder().encode(message);
+    const hashBuffer = await crypto.subtle.digest("SHA-256", msgBuffer);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+    return hashHex;
+  }
+  _formDataFromObject(obj) {
+    const formData = new FormData();
+    Object.entries(obj).forEach(([key, value]) => {
+      formData.append(key, value);
+    });
+    return formData;
+  }
+};
+
+// src/index.ts
+var index_default = NebulaSDK;
+
+export { GraphSearchResultType, NebulaAuthenticationException, NebulaClientException, NebulaClusterNotFoundException, NebulaException, NebulaRateLimitException, NebulaSDK, NebulaValidationException, RetrievalType, index_default as default };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map