@nebula-ai/sdk 1.2.2 → 1.4.0

package/dist/index.js

@@ -1,1345 +1,1244 @@
-'use strict';
-
-Object.defineProperty(exports, '__esModule', { value: true });
-
-// src/types.ts
-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";
-  }
+//#region src/runtime/errors.ts
+var NebulaError = class extends Error {
+	name = "NebulaError";
+	constructor(message, options) {
+		super(message, options);
+	}
 };
-var NebulaClientException = class extends NebulaException {
-  constructor(message, cause) {
-    super(message);
-    this.cause = cause;
-    this.name = "NebulaClientException";
-  }
+var NebulaConnectionError = class extends NebulaError {
+	name = "NebulaConnectionError";
 };
-var NebulaAuthenticationException = class extends NebulaException {
-  constructor(message = "Invalid API key") {
-    super(message, 401);
-    this.name = "NebulaAuthenticationException";
-  }
+var NebulaTimeoutError = class extends NebulaError {
+	name = "NebulaTimeoutError";
 };
-var NebulaRateLimitException = class extends NebulaException {
-  constructor(message = "Rate limit exceeded") {
-    super(message, 429);
-    this.name = "NebulaRateLimitException";
-  }
+function isEnvelope(body) {
+	return typeof body === "object" && body !== null && typeof body.type === "string" && typeof body.message === "string";
+}
+var NebulaAPIError = class extends NebulaError {
+	name = "NebulaAPIError";
+	status;
+	requestId;
+	body;
+	type;
+	code;
+	details;
+	constructor(payload, message) {
+		const envelope = isEnvelope(payload.body) ? payload.body : void 0;
+		super(message ?? envelope?.message ?? `Nebula API error (status ${payload.status})`);
+		this.status = payload.status;
+		const envCode = typeof envelope?.code === "string" ? envelope.code : void 0;
+		const envRid = typeof envelope?.request_id === "string" ? envelope.request_id : void 0;
+		this.requestId = envRid ?? payload.requestId;
+		this.body = payload.body;
+		this.type = envelope?.type;
+		this.code = envCode;
+		this.details = envelope?.details ?? void 0;
+	}
 };
-var NebulaValidationException = class extends NebulaException {
-  constructor(message = "Validation error", details) {
-    super(message, 400);
-    this.details = details;
-    this.name = "NebulaValidationException";
-  }
+var NebulaBadRequestError = class extends NebulaAPIError {
+	name = "NebulaBadRequestError";
 };
-var NebulaCollectionNotFoundException = class extends NebulaException {
-  constructor(message = "Collection not found") {
-    super(message, 404);
-    this.name = "NebulaCollectionNotFoundException";
-  }
+var NebulaUnauthorizedError = class extends NebulaAPIError {
+	name = "NebulaUnauthorizedError";
 };
-var NebulaNotFoundException = class extends NebulaException {
-  constructor(resourceId, resourceType = "Resource") {
-    super(`${resourceType} not found: ${resourceId}`, 404);
-    this.name = "NebulaNotFoundException";
-  }
+var NebulaForbiddenError = class extends NebulaAPIError {
+	name = "NebulaForbiddenError";
 };
-
-// src/client.ts
-var _Nebula = class _Nebula {
-  // 5MB
-  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.trynebula.ai").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_") || publicPart.startsWith("neb_")) && !!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;
-  }
-  _isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-  }
-  _unwrapResults(value) {
-    if (this._isRecord(value) && "results" in value) {
-      return value.results;
-    }
-    return value;
-  }
-  _unwrapResultsArray(value) {
-    const unwrapped = this._unwrapResults(value);
-    if (Array.isArray(unwrapped)) {
-      return unwrapped;
-    }
-    if (unwrapped === void 0 || unwrapped === null) {
-      return [];
-    }
-    return [unwrapped];
-  }
-  _looksLikeMultimodalContent(content) {
-    if (!Array.isArray(content)) return false;
-    return content.some((part) => {
-      if (!this._isRecord(part)) return false;
-      if (typeof part.type === "string") return true;
-      if ("data" in part || "s3_key" in part || "url" in part) return true;
-      return false;
-    });
-  }
-  _normalizeContentParts(contentParts) {
-    return contentParts.map((part) => {
-      if (typeof part === "string") {
-        return { type: "text", text: part };
-      }
-      if (!this._isRecord(part)) {
-        return { type: "text", text: String(part) };
-      }
-      if (typeof part.type === "string") {
-        return part;
-      }
-      if ("s3_key" in part && typeof part.s3_key === "string") {
-        return {
-          type: "s3_ref",
-          s3_key: part.s3_key,
-          bucket: typeof part.bucket === "string" ? part.bucket : void 0,
-          media_type: typeof part.media_type === "string" ? part.media_type : "application/octet-stream",
-          filename: typeof part.filename === "string" ? part.filename : void 0,
-          size_bytes: typeof part.size_bytes === "number" ? part.size_bytes : void 0
-        };
-      }
-      if ("data" in part && typeof part.data === "string") {
-        return {
-          type: "file",
-          data: part.data,
-          media_type: typeof part.media_type === "string" ? part.media_type : "application/octet-stream",
-          filename: typeof part.filename === "string" ? part.filename : void 0,
-          duration_seconds: typeof part.duration_seconds === "number" ? part.duration_seconds : void 0
-        };
-      }
-      return { type: "text", text: String(part) };
-    });
-  }
-  async _serializeContentAsText(content) {
-    if (this._looksLikeMultimodalContent(content)) {
-      const normalized = this._normalizeContentParts(content);
-      const processed = await this._processContentParts(normalized);
-      return JSON.stringify(processed);
-    }
-    if (typeof content === "object" && content !== null) {
-      return JSON.stringify(content);
-    }
-    return String(content ?? "");
-  }
-  async _serializeContentAsParts(content) {
-    if (!this._looksLikeMultimodalContent(content)) return null;
-    const normalized = this._normalizeContentParts(content);
-    return await this._processContentParts(normalized);
-  }
-  /** Make an HTTP request to the Nebula API */
-  async _makeRequest(method, endpoint, jsonData, params, extraHeaders) {
-    const url = new URL(endpoint, this.baseUrl);
-    if (params) {
-      Object.entries(params).forEach(([key, value]) => {
-        if (value !== void 0 && value !== null) {
-          if (Array.isArray(value)) {
-            value.forEach((item) => {
-              url.searchParams.append(key, String(item));
-            });
-          } else {
-            url.searchParams.append(key, String(value));
-          }
-        }
-      });
-    }
-    const headers = { ...this._buildAuthHeaders(true), ...extraHeaders };
-    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 || response.status === 202) {
-        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 if (response.status === 422) {
-        const errorData = await response.json().catch(() => ({}));
-        console.error("[SDK] 422 Validation error - Full details:");
-        console.error("  Status:", response.status);
-        console.error("  Error data:", JSON.stringify(errorData, null, 2));
-        console.error("  Message:", errorData.message);
-        console.error("  Detail:", errorData.detail);
-        throw new NebulaValidationException(
-          errorData.message || (typeof errorData.detail === "string" ? errorData.detail : JSON.stringify(errorData.detail)) || "Validation error",
-          errorData
-        );
-      } 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)}`);
-    }
-  }
-  // Collection Management Methods
-  /** Create a new collection */
-  async createCollection(options) {
-    const data = { name: options.name };
-    if (options.description) data.description = options.description;
-    if (options.metadata) data.metadata = options.metadata;
-    const response = await this._makeRequest("POST", "/v1/collections", data);
-    const result = response.results || response;
-    return this._collectionFromDict(result);
-  }
-  /** Get a specific collection by ID */
-  async getCollection(collectionId) {
-    const response = await this._makeRequest("GET", `/v1/collections/${collectionId}`);
-    const result = response.results || response;
-    return this._collectionFromDict(result);
-  }
-  /** Get a specific collection by name */
-  async getCollectionByName(name) {
-    const response = await this._makeRequest("GET", `/v1/collections/name/${name}`);
-    const result = response.results || response;
-    return this._collectionFromDict(result);
-  }
-  /** Get all collections */
-  async listCollections(options) {
-    const params = {
-      limit: options?.limit ?? 100,
-      offset: options?.offset ?? 0
-    };
-    if (options?.name !== void 0) {
-      params.name = options.name;
-    }
-    const response = await this._makeRequest("GET", "/v1/collections", void 0, params);
-    let collections;
-    if (typeof response === "object" && response !== null && "results" in response) {
-      collections = response.results;
-    } else if (Array.isArray(response)) {
-      collections = response;
-    } else {
-      collections = [response];
-    }
-    return collections.map((collection) => this._collectionFromDict(collection));
-  }
-  /** Update a collection */
-  async updateCollection(options) {
-    const data = {};
-    if (options.name !== void 0) data.name = options.name;
-    if (options.description !== void 0) data.description = options.description;
-    if (options.metadata !== void 0) data.metadata = options.metadata;
-    const response = await this._makeRequest("POST", `/v1/collections/${options.collectionId}`, data);
-    const result = response.results || response;
-    return this._collectionFromDict(result);
-  }
-  /** Delete a collection */
-  async deleteCollection(collectionId) {
-    await this._makeRequest("DELETE", `/v1/collections/${collectionId}`);
-    return true;
-  }
-  // Memory Management Methods
-  /**
-   * Legacy convenience: store raw text content into a collection as a document
-   */
-  async store(content, collectionId, metadata = {}) {
-    const docMetadata = {
-      ...metadata,
-      memory_type: "memory",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    const payload = {
-      collection_id: collectionId,
-      raw_text: String(content || ""),
-      metadata: docMetadata,
-      ingestion_mode: "fast"
-    };
-    const response = await this._makeRequest("POST", "/v1/memories", payload);
-    const id = response?.results?.engram_id || response?.results?.id || response?.id || "";
-    const timestamp = docMetadata.timestamp;
-    const result = {
-      id: String(id),
-      memory_id: String(id),
-      content: String(content || ""),
-      metadata: docMetadata,
-      collection_ids: [collectionId],
-      created_at: timestamp,
-      updated_at: timestamp
-    };
-    return result;
-  }
-  /**
-   * Store a single memory using the unified engrams API.
-   *
-   * Automatically infers memory type:
-   * - If role is present, creates a conversation
-   * - Otherwise, creates a document
-   */
-  async storeMemory(memory, name) {
-    let mem;
-    if ("collection_id" in memory || "snapshot" in memory) {
-      mem = memory;
-    } else {
-      const memRecord2 = memory;
-      mem = {
-        collection_id: memRecord2.collection_id || memRecord2.collectionId || "",
-        content: memRecord2.content || "",
-        role: memRecord2.role,
-        memory_id: memRecord2.memory_id || memRecord2.memoryId || void 0,
-        metadata: memRecord2.metadata || {},
-        snapshot: memRecord2.snapshot
-      };
-    }
-    if (mem.snapshot) {
-      const contentText = await this._serializeContentAsText(mem.content);
-      const payload2 = {
-        snapshot: mem.snapshot,
-        raw_text: contentText
-      };
-      const response2 = await this._makeRequest("POST", "/v1/memories", payload2);
-      const snapshot = response2?.results?.snapshot;
-      if (snapshot) {
-        return snapshot;
-      }
-      return response2?.results ?? {};
-    }
-    if (mem.memory_id) {
-      return await this._appendToMemory(mem.memory_id, mem);
-    }
-    const memoryType = mem.role ? "conversation" : "document";
-    if (memoryType === "conversation") {
-      const messages = [];
-      if (mem.content && mem.role) {
-        const multimodalParts2 = await this._serializeContentAsParts(mem.content);
-        const msgContent = multimodalParts2 ?? await this._serializeContentAsText(mem.content);
-        const memRecord2 = mem;
-        messages.push({
-          content: msgContent,
-          role: mem.role,
-          metadata: mem.metadata || {},
-          ...typeof memRecord2.authority === "number" ? { authority: Number(memRecord2.authority) } : {}
-        });
-      }
-      if (messages.length === 0) {
-        throw new NebulaClientException("Cannot create conversation without messages. Provide content and role.");
-      }
-      const data = {
-        collection_id: mem.collection_id,
-        name: name || "Conversation",
-        messages,
-        metadata: mem.metadata || {}
-      };
-      const response2 = await this._makeRequest("POST", "/v1/memories", data);
-      if (response2.results) {
-        const convId = response2.results.memory_id || response2.results.id;
-        if (!convId) {
-          throw new NebulaClientException("Failed to create conversation: no id returned");
-        }
-        return String(convId);
-      }
-      throw new NebulaClientException("Failed to create conversation: invalid response format");
-    }
-    const docMetadata = { ...mem.metadata };
-    docMetadata.memory_type = "memory";
-    const memRecord = mem;
-    if (typeof memRecord.authority === "number") {
-      const v = Number(memRecord.authority);
-      if (!Number.isNaN(v) && v >= 0 && v <= 1) {
-        docMetadata.authority = v;
-      }
-    }
-    let payload;
-    const multimodalParts = await this._serializeContentAsParts(mem.content);
-    if (multimodalParts) {
-      payload = {
-        collection_id: mem.collection_id,
-        content_parts: multimodalParts,
-        metadata: docMetadata,
-        ingestion_mode: "fast"
-      };
-    } else if (Array.isArray(mem.content) && mem.content.every((x) => typeof x === "string")) {
-      payload = {
-        collection_id: mem.collection_id,
-        chunks: mem.content,
-        metadata: docMetadata,
-        ingestion_mode: "fast"
-      };
-    } else {
-      const contentText = await this._serializeContentAsText(mem.content);
-      if (!contentText || contentText === '""' || contentText === "[]" || contentText === "{}") {
-        throw new NebulaClientException("Content is required for document memories");
-      }
-      payload = {
-        collection_id: mem.collection_id,
-        raw_text: contentText,
-        metadata: docMetadata,
-        ingestion_mode: "fast"
-      };
-    }
-    const response = await this._makeRequest("POST", "/v1/memories", payload);
-    const id = response?.results?.engram_id || response?.results?.id || response?.id || "";
-    return String(id || "");
-  }
-  /**
-   * Internal method to append content to an existing memory
-   *
-   * @throws NebulaNotFoundException if memory_id doesn't exist
-   */
-  async _appendToMemory(memoryId, memory) {
-    const collectionId = memory.collection_id;
-    const content = memory.content;
-    const metadata = memory.metadata;
-    if (!collectionId) {
-      throw new NebulaClientException("collection_id is required");
-    }
-    const payload = {
-      collection_id: collectionId
-    };
-    if (Array.isArray(content)) {
-      if (content.length > 0 && typeof content[0] === "object" && "content" in content[0]) {
-        payload.messages = content;
-      } else {
-        payload.chunks = content;
-      }
-    } else if (typeof content === "string") {
-      payload.raw_text = content;
-    } else {
-      throw new NebulaClientException(
-        "content must be a string, array of strings, or array of message objects"
-      );
-    }
-    if (metadata) {
-      payload.metadata = metadata;
-    }
-    try {
-      await this._makeRequest("POST", `/v1/memories/${memoryId}/append`, payload);
-      return memoryId;
-    } catch (error) {
-      if (error instanceof NebulaException && error.statusCode === 404) {
-        throw new NebulaNotFoundException(memoryId, "Memory");
-      }
-      throw error;
-    }
-  }
-  /** Store multiple memories using the unified engrams API.
-   *  @param memories - List of Memory objects to store.
-   *  @param metadata - Optional memory-level metadata for conversation groups.
-   *    Each Memory's own metadata is used as per-message metadata.
-   */
-  async storeMemories(memories, metadata) {
-    const results = [];
-    const convGroups = {};
-    const others = [];
-    for (const m of memories) {
-      if (m.role) {
-        const key = m.memory_id || `__new__::${m.collection_id}`;
-        if (!convGroups[key]) convGroups[key] = [];
-        convGroups[key].push(m);
-      } else {
-        others.push(m);
-      }
-    }
-    for (const [key, group] of Object.entries(convGroups)) {
-      const collectionId = group[0].collection_id;
-      let convId;
-      const messages = [];
-      for (const m of group) {
-        const multimodalParts = await this._serializeContentAsParts(m.content);
-        const msgContent = multimodalParts ?? await this._serializeContentAsText(m.content);
-        if (typeof msgContent === "string") {
-          if (!msgContent.trim()) continue;
-        } else if (msgContent.length === 0) {
-          continue;
-        }
-        const mRecord = m;
-        messages.push({
-          content: msgContent,
-          role: m.role,
-          metadata: m.metadata || {},
-          ...typeof mRecord.authority === "number" ? { authority: Number(mRecord.authority) } : {}
-        });
-      }
-      if (!messages.length) {
-        throw new NebulaClientException(
-          "Cannot create/append conversation without messages. Provide non-empty content."
-        );
-      }
-      if (key.startsWith("__new__::")) {
-        const data = {
-          collection_id: collectionId,
-          name: "Conversation",
-          messages,
-          metadata: metadata ?? {}
-        };
-        const response = await this._makeRequest("POST", "/v1/memories", data);
-        if (response.results) {
-          convId = response.results.memory_id || response.results.id || "";
-          if (!convId) {
-            throw new NebulaClientException("Failed to create conversation: no id returned");
-          }
-        } else {
-          throw new NebulaClientException("Failed to create conversation: invalid response format");
-        }
-      } else {
-        convId = key;
-        const appendMem = {
-          collection_id: collectionId,
-          content: messages,
-          memory_id: convId,
-          metadata: metadata ?? {}
-        };
-        await this._appendToMemory(convId, appendMem);
-      }
-      results.push(...Array(group.length).fill(String(convId)));
-    }
-    for (const m of others) {
-      results.push(await this.storeMemory(m));
-    }
-    return results;
-  }
-  /** Delete one or more memories */
-  async delete(memoryIds) {
-    try {
-      console.log("[SDK] delete() called with:", { memoryIds, type: typeof memoryIds, isArray: Array.isArray(memoryIds) });
-      if (typeof memoryIds === "string") {
-        console.log("[SDK] Single deletion path for ID:", memoryIds);
-        try {
-          await this._makeRequest("DELETE", `/v1/memories/${memoryIds}`);
-          return true;
-        } catch {
-          console.log("[SDK] Falling back to POST /v1/memories/delete with single ID");
-          const response = await this._makeRequest("POST", "/v1/memories/delete", memoryIds);
-          return typeof response === "object" && response.success !== void 0 ? response.success : true;
-        }
-      } else {
-        console.log("[SDK] Batch deletion path for IDs:", memoryIds);
-        console.log("[SDK] Sending POST request with body:", memoryIds);
-        const response = await this._makeRequest("POST", "/v1/memories/delete", memoryIds);
-        console.log("[SDK] Batch deletion response:", response);
-        return response;
-      }
-    } catch (error) {
-      console.error("[SDK] Delete error:", error);
-      if (error instanceof Error) {
-        throw error;
-      }
-      throw new NebulaClientException(`Unknown error: ${String(error)}`);
-    }
-  }
-  /** Delete a specific source within a memory */
-  async deleteSource(sourceId) {
-    try {
-      await this._makeRequest("DELETE", `/v1/sources/${sourceId}`);
-      return true;
-    } catch (error) {
-      if (error instanceof NebulaException && error.statusCode === 404) {
-        throw new NebulaNotFoundException(sourceId, "Source");
-      }
-      throw error;
-    }
-  }
-  /** Update a specific source within a memory */
-  async updateSource(sourceId, content, metadata) {
-    const payload = { content };
-    if (metadata !== void 0) {
-      payload.metadata = metadata;
-    }
-    try {
-      await this._makeRequest("PATCH", `/v1/sources/${sourceId}`, payload);
-      return true;
-    } catch (error) {
-      if (error instanceof NebulaException && error.statusCode === 404) {
-        throw new NebulaNotFoundException(sourceId, "Source");
-      }
-      throw error;
-    }
-  }
-  /**
-   * Update memory-level properties including name, metadata, and collection associations.
-   *
-   * This method allows updating properties of an entire memory (document or conversation)
-   * without modifying its content. For updating individual sources within a memory,
-   * use updateSource(). For updating content, use storeMemory() to append.
-   *
-   * @param options - Update configuration
-   * @param options.memoryId - The ID of the memory to update
-   * @param options.name - New name for the memory (useful for conversations and documents)
-   * @param options.metadata - Metadata to set. By default, replaces existing metadata.
-   *                           Set mergeMetadata=true to merge with existing metadata instead.
-   * @param options.collectionIds - New collection associations. Must specify at least one valid collection.
-   * @param options.mergeMetadata - If true, merges provided metadata with existing metadata.
-   *                                If false (default), replaces existing metadata entirely.
-   *
-   * @returns Promise resolving to true if successful
-   *
-   * @throws NebulaNotFoundException if memory_id doesn't exist
-   * @throws NebulaValidationException if validation fails (e.g., no fields provided)
-   * @throws NebulaAuthenticationException if user doesn't have permission to update this memory
-   */
-  async updateMemory(options) {
-    const payload = {};
-    if (options.name !== void 0) {
-      payload.name = options.name;
-    }
-    if (options.metadata !== void 0) {
-      payload.metadata = options.metadata;
-      payload.merge_metadata = options.mergeMetadata ?? false;
-    }
-    if (options.collectionIds !== void 0) {
-      payload.collection_ids = options.collectionIds;
-    }
-    if (Object.keys(payload).length === 0) {
-      throw new NebulaValidationException(
-        "At least one field (name, metadata, or collectionIds) must be provided to update"
-      );
-    }
-    try {
-      await this._makeRequest("PATCH", `/v1/memories/${options.memoryId}`, payload);
-      return true;
-    } catch (error) {
-      if (error instanceof NebulaException && error.statusCode === 404) {
-        throw new NebulaNotFoundException(options.memoryId, "Memory");
-      }
-      throw error;
-    }
-  }
-  /**
-   * Get all memories from specific collections with optional metadata filtering
-   *
-   * @param options - Configuration for listing memories
-   * @param options.collection_ids - One or more collection IDs to retrieve memories from
-   * @param options.limit - Maximum number of memories to return (default: 100)
-   * @param options.offset - Number of memories to skip for pagination (default: 0)
-   * @param options.metadata_filters - Optional metadata filters using MongoDB-like operators.
-   *   Supported operators: $eq, $ne, $in, $nin, $exists, $and, $or
-   *
-   * @returns Promise resolving to array of MemoryResponse objects
-   *
-   * @example
-   * // Get all playground memories excluding conversations
-   * const memories = await client.listMemories({
-   *   collection_ids: ['collection-id'],
-   *   metadata_filters: {
-   *     'metadata.content_type': { $ne: 'conversation' }
-   *   }
-   * });
-   *
-   * @example
-   * // Complex filter with multiple conditions
-   * const memories = await client.listMemories({
-   *   collection_ids: ['collection-id'],
-   *   metadata_filters: {
-   *     $and: [
-   *       { 'metadata.playground': { $eq: true } },
-   *       { 'metadata.session_id': { $exists: true } }
-   *     ]
-   *   }
-   * });
-   */
-  async listMemories(options) {
-    const ids = Array.isArray(options.collection_ids) ? options.collection_ids : [options.collection_ids];
-    if (!ids.length) {
-      throw new NebulaClientException("collection_ids must be provided to list_memories().");
-    }
-    const params = {
-      limit: options.limit ?? 100,
-      offset: options.offset ?? 0,
-      collection_ids: ids
-    };
-    if (options.metadata_filters) {
-      params.metadata_filters = JSON.stringify(options.metadata_filters);
-    }
-    const response = await this._makeRequest("GET", "/v1/memories", void 0, params);
-    let documents;
-    if (typeof response === "object" && response !== null && "results" in response) {
-      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 engram ID */
-  async getMemory(memoryId) {
-    const response = await this._makeRequest("GET", `/v1/memories/${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 collections with optional metadata filtering.
-   *
-   * @param options - Search configuration
-   * @param options.query - Search query string
-   * @param options.collection_ids - One or more collection IDs to search within
-   * @param options.effort - Compute effort budget (auto/low/medium/high). Controls traversal compute, not MemoryResponse size.
-   * @param options.filters - Optional filters to apply to the search. Supports comprehensive metadata filtering
-   *                          with MongoDB-like operators for both vector/chunk search and graph search.
-   * @param options.searchSettings - Optional search configuration
-   *
-   * @returns Promise resolving to array of SearchResult objects containing both vector/chunk and graph search results
-   *
-   * @example
-   * // Basic equality filter
-   * await client.search({
-   *   query: "machine learning",
-   *   collection_ids: ["research-collection"],
-   *   filters: {
-   *     "metadata.category": { $eq: "research" },
-   *     "metadata.verified": true  // Shorthand for $eq
-   *   }
-   * });
-   *
-   * @example
-   * // Numeric comparisons
-   * await client.search({
-   *   query: "high priority",
-   *   collection_ids: ["tasks"],
-   *   filters: {
-   *     "metadata.priority": { $gte: 8 },
-   *     "metadata.score": { $lt: 100 }
-   *   }
-   * });
-   *
-   * @example
-   * // String matching
-   * await client.search({
-   *   query: "employees",
-   *   collection_ids: ["team"],
-   *   filters: {
-   *     "metadata.email": { $ilike: "%@company.com" }  // Case-insensitive
-   *   }
-   * });
-   *
-   * @example
-   * // Array operations
-   * await client.search({
-   *   query: "developers",
-   *   collection_ids: ["team"],
-   *   filters: {
-   *     "metadata.skills": { $overlap: ["python", "typescript"] }  // Has any
-   *   }
-   * });
-   *
-   * @example
-   * // Nested paths
-   * await client.search({
-   *   query: "users",
-   *   collection_ids: ["profiles"],
-   *   filters: {
-   *     "metadata.user.preferences.theme": { $eq: "dark" }
-   *   }
-   * });
-   *
-   * @example
-   * // Complex logical combinations
-   * await client.search({
-   *   query: "candidates",
-   *   collection_ids: ["hiring"],
-   *   filters: {
-   *     $and: [
-   *       { "metadata.verified": true },
-   *       { "metadata.level": { $gte: 5 } },
-   *       {
-   *         $or: [
-   *           { "metadata.skills": { $overlap: ["python", "go"] } },
-   *           { "metadata.years_experience": { $gte: 8 } }
-   *         ]
-   *       }
-   *     ]
-   *   }
-   * });
-   *
-   * @remarks
-   * Supported Operators:
-   * - Comparison: $eq, $ne, $lt, $lte, $gt, $gte
-   * - String: $like (case-sensitive), $ilike (case-insensitive)
-   * - Array: $in, $nin, $overlap, $contains
-   * - JSONB: $json_contains
-   * - Logical: $and, $or
-   *
-   * For comprehensive filtering documentation, see the Metadata Filtering Guide:
-   * https://docs.trynebula.ai/guides/metadata-filtering
-   */
-  async search(options) {
-    if (options.snapshot) {
-      const snapshotData = {
-        snapshot: options.snapshot,
-        query: options.query
-      };
-      if (options.effort) {
-        snapshotData.effort = options.effort;
-      }
-      const response2 = await this._makeRequest("POST", "/v1/memories/search", snapshotData);
-      const memoryResponseData2 = response2.results;
-      return {
-        query: memoryResponseData2.query || options.query,
-        semantics: memoryResponseData2.semantics || memoryResponseData2.knowledge || [],
-        procedures: memoryResponseData2.procedures || [],
-        episodes: memoryResponseData2.episodes || [],
-        sources: memoryResponseData2.sources || [],
-        total_traversal_time_ms: memoryResponseData2.total_traversal_time_ms,
-        token_count: memoryResponseData2.token_count,
-        entities: memoryResponseData2.entities || []
-      };
-    }
-    const data = {
-      query: options.query
-    };
-    if (options.effort) {
-      data.effort = options.effort;
-    }
-    if (options.collection_ids) {
-      const collectionIds2 = Array.isArray(options.collection_ids) ? options.collection_ids : [options.collection_ids];
-      const validCollectionIds = collectionIds2.filter((id) => id && id.trim() !== "");
-      if (validCollectionIds.length) {
-        data.collection_ids = validCollectionIds;
-      }
-    }
-    if (options.filters) {
-      data.filters = options.filters;
-    }
-    if (options.searchSettings) {
-      data.search_settings = options.searchSettings;
-    }
-    const collectionIds = data.collection_ids;
-    let extraHeaders;
-    if (collectionIds && collectionIds.length === 1) {
-      extraHeaders = { "X-Nebula-Collection-Id": collectionIds[0] };
-    } else if (collectionIds && collectionIds.length > 1) {
-      extraHeaders = { "X-Nebula-Collection-Id": [...collectionIds].sort().join(",") };
-    }
-    const response = await this._makeRequest("POST", "/v1/memories/search", data, void 0, extraHeaders);
-    const memoryResponseData = response.results;
-    const memoryResponse = {
-      query: memoryResponseData.query || options.query,
-      semantics: memoryResponseData.semantics || memoryResponseData.knowledge || [],
-      procedures: memoryResponseData.procedures || [],
-      episodes: memoryResponseData.episodes || [],
-      sources: memoryResponseData.sources || [],
-      total_traversal_time_ms: memoryResponseData.total_traversal_time_ms,
-      token_count: memoryResponseData.token_count,
-      entities: memoryResponseData.entities || []
-    };
-    return memoryResponse;
-  }
-  // Connector Methods
-  /** List available connector providers */
-  async listProviders() {
-    const response = await this._makeRequest("GET", "/v1/connectors/providers");
-    return this._unwrapResultsArray(response);
-  }
-  /** Start an OAuth connection flow */
-  async connectProvider(provider, collectionId, config) {
-    const body = { collection_id: collectionId };
-    if (config !== void 0) body.config = config;
-    const response = await this._makeRequest("POST", `/v1/connectors/${provider}/connect`, body);
-    return this._unwrapResults(response);
-  }
-  /** List active connections for a collection */
-  async listConnections(collectionId) {
-    const response = await this._makeRequest("GET", "/v1/connectors", void 0, { collection_id: collectionId });
-    return this._unwrapResultsArray(response);
-  }
-  /** Browse Google Drive folders for a connection */
-  async listFolders(connectionId, parentId) {
-    const params = {};
-    if (parentId !== void 0) params.parent_id = parentId;
-    const response = await this._makeRequest("GET", `/v1/connectors/${connectionId}/folders`, void 0, Object.keys(params).length ? params : void 0);
-    return this._unwrapResultsArray(response);
-  }
-  /** List Slack channels for a connection */
-  async listChannels(connectionId) {
-    const response = await this._makeRequest("GET", `/v1/connectors/${connectionId}/channels`);
-    return this._unwrapResultsArray(response);
-  }
-  /** Get a single connection by ID */
-  async getConnection(connectionId) {
-    const response = await this._makeRequest("GET", `/v1/connectors/${connectionId}`);
-    return this._unwrapResults(response);
-  }
-  /** Manually trigger a sync for a connection */
-  async triggerSync(connectionId) {
-    const response = await this._makeRequest("POST", `/v1/connectors/${connectionId}/sync`);
-    return this._unwrapResults(response);
-  }
-  /** Update connection config (e.g., folder/channel selection) */
-  async updateConnectionConfig(connectionId, config, apply = "full_resync") {
-    const response = await this._makeRequest("PATCH", `/v1/connectors/${connectionId}/config`, { config, apply });
-    return this._unwrapResults(response);
-  }
-  /** Disconnect an external data source */
-  async disconnect(connectionId, deleteMemories = false) {
-    const params = {};
-    if (deleteMemories) params.delete_memories = "true";
-    const response = await this._makeRequest("DELETE", `/v1/connectors/${connectionId}`, void 0, Object.keys(params).length ? params : void 0);
-    return this._unwrapResults(response);
-  }
-  // Health Check
-  async healthCheck() {
-    return this._makeRequest("GET", "/v1/health");
-  }
-  // Helpers
-  _collectionFromDict(data) {
-    let createdAt;
-    if (data.created_at) {
-      if (typeof data.created_at === "string") {
-        createdAt = data.created_at;
-      } else if (data.created_at instanceof Date) {
-        createdAt = data.created_at.toISOString();
-      }
-    }
-    let updatedAt;
-    if (data.updated_at) {
-      if (typeof data.updated_at === "string") {
-        updatedAt = data.updated_at;
-      } else if (data.updated_at instanceof Date) {
-        updatedAt = data.updated_at.toISOString();
-      }
-    }
-    const collectionId = String(data.id || "");
-    const collectionName = String(data.name || "");
-    const collectionDescription = typeof data.description === "string" ? data.description : void 0;
-    const collectionOwnerId = data.owner_id ? String(data.owner_id) : void 0;
-    const memoryCount = typeof data.memory_count === "number" ? data.memory_count : 0;
-    const metadata = {
-      graph_collection_status: String(data.graph_collection_status || ""),
-      graph_sync_status: String(data.graph_sync_status || ""),
-      user_count: typeof data.user_count === "number" ? data.user_count : 0
-    };
-    return {
-      id: collectionId,
-      name: collectionName,
-      description: collectionDescription,
-      metadata,
-      created_at: createdAt,
-      updated_at: updatedAt,
-      memory_count: memoryCount,
-      owner_id: collectionOwnerId
-    };
-  }
-  _memoryResponseFromDict(data, collectionIds) {
-    let createdAt;
-    if (data.created_at) {
-      if (typeof data.created_at === "string") {
-        createdAt = data.created_at;
-      } else if (data.created_at instanceof Date) {
-        createdAt = data.created_at.toISOString();
-      }
-    }
-    let updatedAt;
-    if (data.updated_at) {
-      if (typeof data.updated_at === "string") {
-        updatedAt = data.updated_at;
-      } else if (data.updated_at instanceof Date) {
-        updatedAt = data.updated_at.toISOString();
-      }
-    }
-    const engramId = String(data.id || "");
-    const content = typeof data.content === "string" ? data.content : typeof data.text === "string" ? data.text : void 0;
-    let chunks;
-    if (data.chunks && Array.isArray(data.chunks)) {
-      if (data.chunks.every((x) => typeof x === "string")) {
-        chunks = data.chunks.map((text) => ({
-          id: "",
-          content: text,
-          metadata: {}
-        }));
-      } else {
-        chunks = data.chunks.filter((item) => item && typeof item === "object" && ("text" in item || "content" in item)).map((item) => ({
-          id: String(item.id || ""),
-          content: String(item.text || item.content || ""),
-          metadata: typeof item.metadata === "object" && item.metadata !== null ? item.metadata : {},
-          role: typeof item.role === "string" ? item.role : void 0
-        }));
-      }
-    }
-    const metadata = { ...typeof data.metadata === "object" && data.metadata !== null ? data.metadata : {} };
-    if (data.engram_id) {
-      metadata.engram_id = data.engram_id;
-    }
-    let finalId = engramId;
-    if (data.engram_id && !engramId) {
-      finalId = String(data.engram_id);
-    }
-    if (data.document_metadata && typeof data.document_metadata === "object") {
-      Object.assign(metadata, data.document_metadata);
-    }
-    return {
-      id: finalId,
-      memory_id: finalId,
-      content,
-      chunks,
-      metadata,
-      collection_ids: Array.isArray(data.collection_ids) ? data.collection_ids : collectionIds,
-      created_at: createdAt,
-      updated_at: updatedAt
-    };
-  }
-  _searchResultFromDict(data) {
-    const content = typeof data.content === "string" ? data.content : typeof data.text === "string" ? data.text : "";
-    const resultId = String(data.id || data.chunk_id || "");
-    return {
-      id: String(resultId),
-      content: String(content),
-      score: typeof data.score === "number" ? data.score : Number(data.score || 0),
-      metadata: typeof data.metadata === "object" && data.metadata !== null ? data.metadata : {},
-      source: typeof data.source === "string" ? data.source : void 0
-    };
-  }
-  _searchResultFromGraphDict(data) {
-    const rid = data.id ? String(data.id) : "";
-    const resultTypeStr = typeof data.result_type === "string" ? data.result_type : "entity";
-    const rtype = GraphSearchResultType[resultTypeStr.toUpperCase()] || "entity" /* ENTITY */;
-    const content = typeof data.content === "object" && data.content !== null ? data.content : {};
-    const score = data.score !== void 0 ? Number(data.score) : 0;
-    const metadata = typeof data.metadata === "object" && data.metadata !== null ? data.metadata : {};
-    const chunkIds = Array.isArray(data.chunk_ids) ? data.chunk_ids : void 0;
-    let timestamp;
-    if (data.timestamp) {
-      if (typeof data.timestamp === "string") {
-        timestamp = data.timestamp;
-      } else if (data.timestamp instanceof Date) {
-        timestamp = data.timestamp.toISOString();
-      } else {
-        const parsed = new Date(String(data.timestamp));
-        if (!Number.isNaN(parsed.valueOf())) {
-          timestamp = parsed.toISOString();
-        }
-      }
-    }
-    const displayName = typeof data.display_name === "string" ? data.display_name : void 0;
-    const sourceRole = typeof data.source_role === "string" ? data.source_role : void 0;
-    const engramId = data.engram_id ? String(data.engram_id) : void 0;
-    const ownerId = data.owner_id ? String(data.owner_id) : void 0;
-    let entity;
-    let rel;
-    let comm;
-    if (rtype === "entity" /* ENTITY */) {
-      entity = {
-        id: content.id ? String(content.id) : void 0,
-        name: String(content.name || ""),
-        description: String(content.description || ""),
-        metadata: typeof content.metadata === "object" && content.metadata !== null ? content.metadata : {}
-      };
-    } else if (rtype === "relationship" /* RELATIONSHIP */) {
-      rel = {
-        id: content.id ? String(content.id) : void 0,
-        subject: String(content.subject || ""),
-        predicate: String(content.predicate || ""),
-        object: String(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: typeof content.description === "string" ? content.description : void 0,
-        metadata: typeof content.metadata === "object" && content.metadata !== null ? content.metadata : {}
-      };
-    } else {
-      comm = {
-        id: content.id ? String(content.id) : void 0,
-        name: String(content.name || ""),
-        summary: String(content.summary || ""),
-        metadata: typeof content.metadata === "object" && content.metadata !== null ? 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,
-      timestamp,
-      display_name: displayName,
-      source_role: sourceRole,
-      engram_id: engramId,
-      owner_id: ownerId
-    };
-  }
-  async _sha256(message) {
-    const msgBuffer = new TextEncoder().encode(message);
-    let crypto;
-    if (typeof globalThis.crypto !== "undefined" && globalThis.crypto.subtle) {
-      crypto = globalThis.crypto;
-    } else {
-      const nodeCrypto = await import('crypto');
-      crypto = nodeCrypto.webcrypto;
-    }
-    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;
-  }
-  /**
-   * Convert and process multimodal content parts, auto-uploading large base64 files to S3.
-   *
-   * - Binary parts (`image`/`audio`/`document` with `data`) larger than 5MB are uploaded to S3 and converted to `s3_ref`.
-   */
-  async _processContentParts(contentParts) {
-    const processed = [];
-    for (const part of contentParts) {
-      if (part.type !== "text" && part.type !== "s3_ref" && "data" in part && part.data) {
-        const filePart = part;
-        const dataSize = Math.floor(String(filePart.data).length * 3 / 4);
-        if (dataSize > _Nebula.MAX_INLINE_SIZE) {
-          const filename = filePart.filename || `file.bin`;
-          const mediaType = filePart.media_type || "application/octet-stream";
-          const uploadInfo = await this.getUploadUrl({
-            filename,
-            content_type: mediaType,
-            file_size: dataSize
-          });
-          let bytes;
-          const atobFn = globalThis.atob;
-          if (typeof atobFn === "function") {
-            const binaryString = atobFn(String(filePart.data));
-            bytes = new Uint8Array(binaryString.length);
-            for (let i = 0; i < binaryString.length; i++) {
-              bytes[i] = binaryString.charCodeAt(i);
-            }
-          } else {
-            const { Buffer } = await import('buffer');
-            bytes = Uint8Array.from(Buffer.from(String(filePart.data), "base64"));
-          }
-          await fetch(uploadInfo.upload_url, {
-            method: "PUT",
-            body: bytes,
-            headers: { "Content-Type": mediaType }
-          });
-          processed.push({
-            type: "s3_ref",
-            s3_key: uploadInfo.s3_key,
-            media_type: mediaType,
-            filename
-          });
-          continue;
-        }
-      }
-      processed.push(part);
-    }
-    return processed;
-  }
-  /**
-   * Get a presigned URL for uploading large files to S3.
-   */
-  async getUploadUrl(options) {
-    const response = await this._makeRequest("POST", "/v1/memories/upload", void 0, {
-      filename: options.filename,
-      content_type: options.content_type,
-      file_size: options.file_size
-    });
-    if (response.results) {
-      return response.results;
-    }
-    return response;
-  }
-  // ------------------------------------------------------------------
-  // Device Memory
-  // ------------------------------------------------------------------
-  /**
-   * Export a collection's full graph state as a portable snapshot.
-   */
-  async exportSnapshot(collectionId) {
-    const response = await this._makeRequest("POST", "/v1/device-memory/snapshot/export", {
-      collection_id: collectionId
-    });
-    return response.results ?? response;
-  }
-  /**
-   * Import a snapshot into an ephemeral server-side collection.
-   * @returns The ephemeral collection ID.
-   */
-  async importSnapshot(snapshot) {
-    const response = await this._makeRequest("POST", "/v1/device-memory/snapshot/import", {
-      snapshot
-    });
-    const result = response.results ?? response;
-    return result.ephemeral_collection_id ?? "";
-  }
+var NebulaNotFoundError = class extends NebulaAPIError {
+	name = "NebulaNotFoundError";
 };
-// Files larger than 5MB are automatically uploaded to S3
-_Nebula.MAX_INLINE_SIZE = 5 * 1024 * 1024;
-var Nebula = _Nebula;
-
-// src/content.ts
-var MIME_TYPES = {
-  // Images
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".png": "image/png",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".heic": "image/heic",
-  ".bmp": "image/bmp",
-  ".tiff": "image/tiff",
-  // Audio
-  ".mp3": "audio/mpeg",
-  ".wav": "audio/wav",
-  ".m4a": "audio/m4a",
-  ".ogg": "audio/ogg",
-  ".flac": "audio/flac",
-  ".aac": "audio/aac",
-  ".webm": "audio/webm",
-  // Documents
-  ".pdf": "application/pdf",
-  ".doc": "application/msword",
-  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-  ".xls": "application/vnd.ms-excel",
-  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-  ".ppt": "application/vnd.ms-powerpoint",
-  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-  ".txt": "text/plain",
-  ".csv": "text/csv",
-  ".rtf": "application/rtf",
-  ".epub": "application/epub+zip"
+var NebulaConflictError = class extends NebulaAPIError {
+	name = "NebulaConflictError";
 };
-var NebulaContent = class {
-  /**
-   * Create a FileContentPart from a file path.
-   * Automatically deduces media_type and the backend 'type' (image, audio, document).
-   */
-  static async fromFile(filePath, mediaType) {
-    let fs;
-    let path;
-    try {
-      fs = await import('fs/promises');
-      path = await import('path');
-    } catch (e) {
-      throw new Error("File system operations are only supported in Node.js environments.");
-    }
-    const absolutePath = path.resolve(filePath);
-    const fileName = path.basename(absolutePath);
-    const ext = path.extname(absolutePath).toLowerCase();
-    const detectedMime = mediaType || MIME_TYPES[ext] || "application/octet-stream";
-    const buffer = await fs.readFile(absolutePath);
-    const data = buffer.toString("base64");
-    return {
-      data,
-      media_type: detectedMime,
-      filename: fileName
-    };
-  }
+var NebulaValidationError = class extends NebulaAPIError {
+	name = "NebulaValidationError";
 };
+var NebulaRateLimitError = class extends NebulaAPIError {
+	name = "NebulaRateLimitError";
+	retryAfter;
+	constructor(payload, retryAfter) {
+		super(payload);
+		this.retryAfter = retryAfter;
+	}
+};
+var NebulaServerError = class extends NebulaAPIError {
+	name = "NebulaServerError";
+};
+const STATUS_TO_CLASS = {
+	400: NebulaBadRequestError,
+	401: NebulaUnauthorizedError,
+	403: NebulaForbiddenError,
+	404: NebulaNotFoundError,
+	409: NebulaConflictError,
+	422: NebulaValidationError
+};
+function errorFromResponse(payload, retryAfter) {
+	if (payload.status === 429) return new NebulaRateLimitError(payload, retryAfter);
+	const cls = STATUS_TO_CLASS[payload.status];
+	if (cls) return new cls(payload);
+	if (payload.status >= 500) return new NebulaServerError(payload);
+	return new NebulaAPIError(payload);
+}
+//#endregion
+//#region src/runtime/retry.ts
+const DEFAULT_RETRY = {
+	maxRetries: 2,
+	baseMs: 250,
+	maxMs: 8e3
+};
+const RETRYABLE_STATUSES = new Set([
+	408,
+	429,
+	502,
+	503,
+	504
+]);
+function isRetryableStatus(status) {
+	return RETRYABLE_STATUSES.has(status);
+}
+function backoffMs(attempt, policy, retryAfterSec) {
+	if (retryAfterSec != null && Number.isFinite(retryAfterSec)) return Math.min(retryAfterSec * 1e3, policy.maxMs);
+	const exp = Math.min(policy.baseMs * 2 ** attempt, policy.maxMs);
+	return Math.floor(Math.random() * exp);
+}
+function sleep(ms, signal) {
+	if (ms <= 0) return Promise.resolve();
+	return new Promise((resolveSleep, reject) => {
+		const handle = setTimeout(resolveSleep, ms);
+		if (signal) {
+			const onAbort = () => {
+				clearTimeout(handle);
+				reject(signal.reason ?? /* @__PURE__ */ new Error("aborted"));
+			};
+			if (signal.aborted) onAbort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+		}
+	});
+}
+//#endregion
+//#region src/runtime/client.ts
+const DEFAULT_BASE_URL = "https://api.zeroset.com";
+const DEFAULT_TIMEOUT_MS = 6e4;
+var NebulaCore = class {
+	baseUrl;
+	apiKey;
+	bearerToken;
+	defaultHeaders;
+	fetchImpl;
+	fetchOptions;
+	timeoutMs;
+	retry;
+	userAgent;
+	constructor(options = {}) {
+		this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+		this.apiKey = options.apiKey;
+		this.bearerToken = options.bearerToken;
+		this.defaultHeaders = filterNullishHeaders(options.defaultHeaders);
+		this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+		this.fetchOptions = options.fetchOptions ?? {};
+		this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.retry = {
+			...DEFAULT_RETRY,
+			...options.retry ?? {}
+		};
+		this.userAgent = options.userAgent ?? "nebula-sdk-js/0.0.1";
+	}
+	buildUrl(path, pathParams, query) {
+		let resolved = path;
+		if (pathParams) for (const [k, v] of Object.entries(pathParams)) resolved = resolved.replace(`{${k}}`, encodeURIComponent(String(v)));
+		const url = new URL(this.baseUrl + resolved);
+		if (query) for (const [k, v] of Object.entries(query)) {
+			if (v === void 0 || v === null) continue;
+			if (Array.isArray(v)) for (const item of v) url.searchParams.append(k, String(item));
+			else url.searchParams.set(k, String(v));
+		}
+		return url.toString();
+	}
+	buildHeaders(perRequest, hasBody = false) {
+		const headers = new Headers(this.defaultHeaders);
+		headers.set("User-Agent", this.userAgent);
+		headers.set("Accept", "application/json");
+		if (hasBody) headers.set("Content-Type", "application/json");
+		if (this.apiKey) headers.set("X-API-Key", this.apiKey);
+		if (this.bearerToken) headers.set("Authorization", `Bearer ${this.bearerToken}`);
+		if (perRequest) for (const [k, v] of Object.entries(perRequest)) headers.set(k, v);
+		return headers;
+	}
+	async request(args) {
+		const url = this.buildUrl(args.path, args.pathParams, args.query);
+		const hasBody = args.body !== void 0 && args.body !== null;
+		const headers = this.buildHeaders(args.headers, hasBody);
+		const init = {
+			...this.fetchOptions,
+			method: args.method,
+			headers,
+			body: hasBody ? JSON.stringify(args.body) : void 0
+		};
+		const maxAttempts = args.idempotent ?? false ? this.retry.maxRetries + 1 : 1;
+		let lastError;
+		for (let attempt = 0; attempt < maxAttempts; attempt++) {
+			const controller = new AbortController();
+			const timeoutHandle = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("timeout")), this.timeoutMs);
+			const { signal: composedSignal, dispose: disposeAbort } = composeAbort(controller.signal, args.signal);
+			try {
+				const response = await this.fetchImpl(url, {
+					...init,
+					signal: composedSignal
+				});
+				if (response.ok) {
+					if (response.status === 204) return void 0;
+					return await response.json();
+				}
+				const text = await safeReadText(response);
+				const parsed = safeParseJSON(text);
+				const retryAfter = parseRetryAfter(response.headers.get("Retry-After"));
+				const err = errorFromResponse({
+					status: response.status,
+					requestId: response.headers.get("X-Request-Id") ?? void 0,
+					body: parsed ?? text
+				}, retryAfter);
+				if (isRetryableStatus(response.status) && attempt + 1 < maxAttempts) {
+					await sleep(backoffMs(attempt, this.retry, retryAfter), args.signal);
+					lastError = err;
+					continue;
+				}
+				throw err;
+			} catch (rawError) {
+				if (rawError instanceof Error && rawError.name === "AbortError") {
+					if (args.signal?.aborted) throw rawError;
+					throw new NebulaTimeoutError(`Request timed out after ${this.timeoutMs}ms`, { cause: rawError });
+				}
+				if (rawError instanceof NebulaAPIError || rawError instanceof NebulaConnectionError) throw rawError;
+				if (attempt + 1 < maxAttempts) {
+					await sleep(backoffMs(attempt, this.retry), args.signal);
+					lastError = rawError;
+					continue;
+				}
+				if (rawError instanceof Error) throw new NebulaConnectionError(rawError.message, { cause: rawError });
+				throw rawError;
+			} finally {
+				clearTimeout(timeoutHandle);
+				disposeAbort();
+			}
+		}
+		throw lastError ?? new NebulaConnectionError("retry budget exhausted");
+	}
+};
+function composeAbort(timeoutSignal, userSignal) {
+	if (!userSignal) return {
+		signal: timeoutSignal,
+		dispose: () => {}
+	};
+	const controller = new AbortController();
+	const onTimeoutAbort = () => controller.abort(timeoutSignal.reason ?? /* @__PURE__ */ new Error("aborted"));
+	const onUserAbort = () => controller.abort(userSignal.reason ?? /* @__PURE__ */ new Error("aborted"));
+	if (timeoutSignal.aborted) controller.abort(timeoutSignal.reason);
+	if (userSignal.aborted) controller.abort(userSignal.reason);
+	timeoutSignal.addEventListener("abort", onTimeoutAbort, { once: true });
+	userSignal.addEventListener("abort", onUserAbort, { once: true });
+	const dispose = () => {
+		timeoutSignal.removeEventListener("abort", onTimeoutAbort);
+		userSignal.removeEventListener("abort", onUserAbort);
+	};
+	return {
+		signal: controller.signal,
+		dispose
+	};
+}
+async function safeReadText(response) {
+	try {
+		return await response.text();
+	} catch {
+		return "";
+	}
+}
+function safeParseJSON(text) {
+	if (!text) return void 0;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+function filterNullishHeaders(headers) {
+	if (!headers) return {};
+	const out = {};
+	for (const [k, v] of Object.entries(headers)) if (v !== null && v !== void 0) out[k] = v;
+	return out;
+}
+function parseRetryAfter(header) {
+	if (!header) return void 0;
+	const asNumber = Number.parseFloat(header);
+	if (Number.isFinite(asNumber)) return asNumber;
+	const asDate = Date.parse(header);
+	if (Number.isFinite(asDate)) return Math.max(0, (asDate - Date.now()) / 1e3);
+}
+//#endregion
+//#region src/resources/client.ts
+var ClientResource = class {
+	core;
+	constructor(core) {
+		this.core = core;
+	}
+	/**
+	*
+	* Health probe
+	* 
+	* Lightweight liveness probe. Returns a 200 with a fixed message when the API process is up. Does not verify downstream dependencies (database, storage, workers) — use the internal status endpoints for those.
+	* @operationId client.health
+	* @endpoint GET /v1/health
+	*/
+	async health(options) {
+		return this.core.request({
+			method: "GET",
+			path: "/v1/health",
+			pathParams: {},
+			query: void 0,
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+};
+//#endregion
+//#region src/resources/collections.ts
+var CollectionsResource = class {
+	core;
+	constructor(core) {
+		this.core = core;
+	}
+	/**
+	*
+	* Create a new collection
+	* 
+	* Create a new collection and automatically add the creating user
+	* to it.
+	* 
+	* This endpoint allows authenticated users to create a new collection
+	* with a specified name and optional description. The user creating
+	* the collection is automatically added as a member.
+	* @operationId collections.create
+	* @endpoint POST /v1/collections
+	*/
+	async create(params, options) {
+		return this.core.request({
+			method: "POST",
+			path: "/v1/collections",
+			pathParams: {},
+			query: void 0,
+			body: params.body,
+			idempotent: false,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Delete collection
+	* 
+	* Delete an existing collection.
+	* 
+	* This endpoint allows deletion of a collection identified by its
+	* UUID. The user must have appropriate permissions to delete the
+	* collection. Deleting a collection removes all associations but does
+	* not delete the engrams within it.
+	* @operationId collections.delete
+	* @endpoint DELETE /v1/collections/{id}
+	*/
+	async delete(id, options) {
+		return this.core.request({
+			method: "DELETE",
+			path: "/v1/collections/{id}",
+			pathParams: { id },
+			query: void 0,
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* List collections
+	* 
+	* Returns a cursor-paginated list of collections the authenticated
+	* user has access to.
+	* 
+	* Results can be filtered by providing specific collection IDs.
+	* Regular users will only see collections they own or have access to.
+	* Superusers can see all collections.
+	* 
+	* The collections are returned in order of last modification, with
+	* most recent first.
+	* @operationId collections.list
+	* @endpoint GET /v1/collections
+	*/
+	async list(params = {}, options) {
+		return this.core.request({
+			method: "GET",
+			path: "/v1/collections",
+			pathParams: {},
+			query: {
+				ids: params.ids,
+				name: params.name,
+				cursor: params.cursor,
+				limit: params.limit,
+				owner_only: params.ownerOnly,
+				workspace_id: params.workspaceId
+			},
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Get collection details
+	* 
+	* Get details of a specific collection.
+	* 
+	* This endpoint retrieves detailed information about a single
+	* collection identified by its UUID. The user must have access to the
+	* collection to view its details.
+	* @operationId collections.retrieve
+	* @endpoint GET /v1/collections/{id}
+	*/
+	async retrieve(id, options) {
+		return this.core.request({
+			method: "GET",
+			path: "/v1/collections/{id}",
+			pathParams: { id },
+			query: void 0,
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Get a collection by name
+	* 
+	* Retrieve a collection by its (owner_id, name) combination.
+	* 
+	* The authenticated user can only fetch collections they own, or, if
+	* superuser, from anyone.
+	* @operationId collections.retrieveByName
+	* @endpoint GET /v1/collections/name/{collection_name}
+	*/
+	async retrieveByName(params, options) {
+		return this.core.request({
+			method: "GET",
+			path: "/v1/collections/name/{collection_name}",
+			pathParams: { collection_name: params.collectionName },
+			query: { owner_id: params.ownerId },
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Update collection
+	* 
+	* Update an existing collection's configuration.
+	* 
+	* This endpoint allows updating the name, description, and access settings of an
+	* existing collection. The user must have appropriate permissions to
+	* modify the collection.
+	* @operationId collections.update
+	* @endpoint POST /v1/collections/{id}
+	*/
+	async update(params, options) {
+		return this.core.request({
+			method: "POST",
+			path: "/v1/collections/{id}",
+			pathParams: { id: params.id },
+			query: void 0,
+			body: params.body,
+			idempotent: false,
+			signal: options?.signal
+		});
+	}
+};
+//#endregion
+//#region src/resources/connectors.ts
+var ConnectorsResource = class {
+	core;
+	constructor(core) {
+		this.core = core;
+	}
+	/**
+	*
+	* Start OAuth connection flow
+	* 
+	* Start the OAuth connection flow for the given external provider. Returns the authorization URL the user should visit to grant Nebula access. After consent the provider redirects back to Nebula and the connection becomes active.
+	* @operationId connectors.connect
+	* @endpoint POST /v1/connectors/{provider}/connect
+	*/
+	async connect(params, options) {
+		return this.core.request({
+			method: "POST",
+			path: "/v1/connectors/{provider}/connect",
+			pathParams: { provider: params.provider },
+			query: void 0,
+			body: params.body,
+			idempotent: false,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Disconnect an external data source
+	* 
+	* Disconnect the named connection, revoking the stored OAuth credentials and stopping future syncs. Optionally pass `delete_memories=true` to also remove every memory this connection had ingested.
+	* @operationId connectors.disconnect
+	* @endpoint DELETE /v1/connectors/{connection_id}
+	*/
+	async disconnect(params, options) {
+		return this.core.request({
+			method: "DELETE",
+			path: "/v1/connectors/{connection_id}",
+			pathParams: { connection_id: params.connectionId },
+			query: { delete_memories: params.deleteMemories },
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* List active connections for a collection
+	* 
+	* Return every connector connection associated with the given collection, with encrypted credentials redacted. Useful for showing the user which third-party data sources are wired up to a collection.
+	* @operationId connectors.list
+	* @endpoint GET /v1/connectors
+	*/
+	async list(params, options) {
+		return this.core.request({
+			method: "GET",
+			path: "/v1/connectors",
+			pathParams: {},
+			query: { collection_id: params.collectionId },
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* List available connector providers
+	* 
+	* Return the set of connector provider identifiers (e.g. `google_drive`, `slack`) that this Nebula instance is configured to expose. Pass one of these to `POST /connectors/{provider}/connect` to start an OAuth flow.
+	* @operationId connectors.listProviders
+	* @endpoint GET /v1/connectors/providers
+	*/
+	async listProviders(options) {
+		return this.core.request({
+			method: "GET",
+			path: "/v1/connectors/providers",
+			pathParams: {},
+			query: void 0,
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Get a single connection by ID
+	* 
+	* Fetch a single connector connection by its UUID. Returns the connection metadata plus whether the underlying subscription is active. Encrypted credentials are never returned to clients.
+	* @operationId connectors.retrieve
+	* @endpoint GET /v1/connectors/{connection_id}
+	*/
+	async retrieve(connectionId, options) {
+		return this.core.request({
+			method: "GET",
+			path: "/v1/connectors/{connection_id}",
+			pathParams: { connection_id: connectionId },
+			query: void 0,
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Manually trigger a sync
+	* 
+	* Schedule an immediate sync for an active connection, bypassing the normal cadence. Returns 409 if a sync is already in progress and 400 if the connection isn't in the `active` state.
+	* @operationId connectors.sync
+	* @endpoint POST /v1/connectors/{connection_id}/sync
+	*/
+	async sync(connectionId, options) {
+		return this.core.request({
+			method: "POST",
+			path: "/v1/connectors/{connection_id}/sync",
+			pathParams: { connection_id: connectionId },
+			query: void 0,
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+};
+//#endregion
+//#region src/resources/memories.ts
+var MemoriesResource = class {
+	core;
+	constructor(core) {
+		this.core = core;
+	}
+	/**
+	*
+	* Append content to an engram
+	* 
+	* Append content to an existing engram.
+	* 
+	* **For conversation engrams:**
+	* - Provide `messages` array with content, role, and optional metadata
+	* - Works like `/conversations/{id}/messages` endpoint
+	* 
+	* **For document engrams:**
+	* - Provide either `raw_text` or `chunks` to append additional content
+	* - Content will be processed and added to the engram
+	* @operationId memories.append
+	* @endpoint POST /v1/memories/{id}/append
+	*/
+	async append(params, options) {
+		return this.core.request({
+			method: "POST",
+			path: "/v1/memories/{id}/append",
+			pathParams: { id: params.id },
+			query: void 0,
+			body: params.body,
+			idempotent: false,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Create a new memory (conversation or document)
+	* 
+	* Create a new memory (conversation or document) using clean JSON body.
+	* 
+	* - Use `collection_id` (UUID)
+	* - `kind` is optional and inferred from payload shape:
+	*   - If `messages` present -> conversation
+	*   - Otherwise -> document
+	* - For conversations: provide `messages` array
+	* - For documents: provide `raw_text` or `chunks`
+	* - Use `snapshot` for device-memory mode (mutually exclusive with collection_id)
+	* @operationId memories.create
+	* @endpoint POST /v1/memories
+	*/
+	async create(params, options) {
+		return this.core.request({
+			method: "POST",
+			path: "/v1/memories",
+			pathParams: {},
+			query: void 0,
+			body: params.body,
+			idempotent: false,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Get presigned URL for large file upload
+	* 
+	* Get a presigned URL for uploading large files directly to S3.
+	* 
+	* Use this for files larger than 5MB that cannot be sent inline as base64.
+	* After uploading, reference the file in memory creation using S3FileReference.
+	* 
+	* Args:
+	*     filename: Original filename (e.g., "image.jpg")
+	*     content_type: MIME type (e.g., "image/jpeg", "application/pdf")
+	*     file_size: Expected file size in bytes (max 100MB)
+	* 
+	* Returns:
+	*     dict with:
+	*     - upload_url: Presigned URL for PUT request (expires in 1 hour)
+	*     - upload_headers: Headers that must be sent with the presigned PUT request
+	*     - s3_key: The S3 key to reference in memory creation
+	*     - bucket: S3 bucket name
+	*     - expires_in: Seconds until URL expires
+	*     - max_size: Maximum allowed file size
+	* @operationId memories.createUpload
+	* @endpoint POST /v1/memories/upload
+	*/
+	async createUpload(params, options) {
+		return this.core.request({
+			method: "POST",
+			path: "/v1/memories/upload",
+			pathParams: {},
+			query: {
+				filename: params.filename,
+				content_type: params.contentType,
+				file_size: params.fileSize
+			},
+			idempotent: false,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Delete an engram
+	* 
+	* Delete a specific engram with graph awareness. All chunks corresponding to the
+	* engram are deleted, and graph components (entities/relationships) are updated
+	* or deleted based on remaining chunk references from other engrams.
+	* 
+	* This method now properly handles graph components and maintains graph integrity
+	* for search operations.
+	* @operationId memories.delete
+	* @endpoint DELETE /v1/memories/{id}
+	*/
+	async delete(id, options) {
+		return this.core.request({
+			method: "DELETE",
+			path: "/v1/memories/{id}",
+			pathParams: { id },
+			query: void 0,
+			idempotent: false,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Delete one or more engrams
+	* 
+	* Delete one or more engrams.
+	* 
+	* This endpoint efficiently handles both single and batch deletions.
+	* When multiple IDs are provided, it uses optimized batch operations.
+	* 
+	* Args:
+	*     ids: Either a single UUID or a list of UUIDs to delete
+	* 
+	* Returns:
+	*     For single deletion: boolean success response
+	*     For batch deletion: detailed results with successful and failed deletions
+	* @operationId memories.deleteMany
+	* @endpoint POST /v1/memories/delete
+	*/
+	async deleteMany(params, options) {
+		return this.core.request({
+			method: "POST",
+			path: "/v1/memories/delete",
+			pathParams: {},
+			query: void 0,
+			body: params.body,
+			idempotent: false,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Delete a previously uploaded S3 file
+	* 
+	* Delete a file from S3 that was uploaded via a presigned URL.
+	* Verifies the caller owns the file via S3 object metadata.
+	* @operationId memories.deleteUpload
+	* @endpoint DELETE /v1/memories/upload
+	*/
+	async deleteUpload(params, options) {
+		return this.core.request({
+			method: "DELETE",
+			path: "/v1/memories/upload",
+			pathParams: {},
+			query: { s3_key: params.s3Key },
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* List engrams
+	* 
+	* Returns a cursor-paginated list of engrams the authenticated user
+	* has access to.
+	* 
+	* Results can be filtered by providing specific engram IDs or collection IDs.
+	* Regular users will only see engrams they own or have access to through
+	* collections. Superusers can see all engrams.
+	* 
+	* The engrams are returned in order of creation time, most recent
+	* first. The response includes the engram's text field if available.
+	* @operationId memories.list
+	* @endpoint GET /v1/memories
+	*/
+	async list(params = {}, options) {
+		return this.core.request({
+			method: "GET",
+			path: "/v1/memories",
+			pathParams: {},
+			query: {
+				ids: params.ids,
+				cursor: params.cursor,
+				limit: params.limit,
+				chunks_limit: params.chunksLimit,
+				owner_only: params.ownerOnly,
+				collection_ids: params.collectionIds,
+				metadata_filters: params.metadataFilters,
+				min_applied_wal_seq: params.minAppliedWalSeq
+			},
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Recall workflow patterns by intent
+	* 
+	* Workflow-pattern recall over 5 intents.
+	* 
+	* * ``cursor`` -- match the caller's anchor against pattern
+	*   canonical states, return ranked patterns + position.
+	* * ``predict`` -- like cursor but include the predicted next
+	*   trace from each pattern's canonical instance.
+	* * ``resume`` -- like cursor, biased toward longer patterns.
+	* * ``evidence`` -- expand a specific pattern via
+	*   ``hydrate_pattern``.
+	* * ``bootstrap`` -- top-K patterns by confidence with no anchor.
+	* @operationId memories.recallWorkflow
+	* @endpoint POST /v1/memories/workflow/recall
+	*/
+	async recallWorkflow(params, options) {
+		return this.core.request({
+			method: "POST",
+			path: "/v1/memories/workflow/recall",
+			pathParams: {},
+			query: void 0,
+			body: params.body,
+			idempotent: false,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Retrieve an engram
+	* 
+	* Retrieves detailed information about a specific engram by its
+	* ID.
+	* 
+	* This endpoint returns the engram's metadata, status, and system information. It does not
+	* return the engram's content - use the `/engrams/{id}/download` endpoint for that.
+	* 
+	* Users can only retrieve engrams they own or have access to through collections.
+	* Superusers can retrieve any engram.
+	* @operationId memories.retrieve
+	* @endpoint GET /v1/memories/{id}
+	*/
+	async retrieve(id, options) {
+		return this.core.request({
+			method: "GET",
+			path: "/v1/memories/{id}",
+			pathParams: { id },
+			query: void 0,
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Search memories
+	* 
+	* Perform a search query across your memories.
+	* 
+	* **Standard mode** (collection_ids or readable-scope search): returns hierarchical MemoryRecall
+	* with semantics, episodes, procedures, and sources.
+	* 
+	* **Snapshot mode** (snapshot field): returns graph-search results with
+	* {entities, relationships} from stateless in-memory traversal.
+	* @operationId memories.search
+	* @endpoint POST /v1/memories/search
+	*/
+	async search(params, options) {
+		return this.core.request({
+			method: "POST",
+			path: "/v1/memories/search",
+			pathParams: {},
+			query: void 0,
+			body: params.body,
+			idempotent: false,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Update a memory
+	* 
+	* Update memory-level properties including name, metadata, and collection associations.
+	* 
+	* This endpoint allows updating properties of an entire memory (document or conversation)
+	* without modifying its content:
+	* - **name**: Updates the authoritative engram title
+	* - **metadata**: Can replace or merge with existing metadata
+	* - **collection_ids**: Updates authoritative engram collection associations
+	* 
+	* Users can only update memories they own or have access to through collections.
+	* At least one collection association must be maintained.
+	* 
+	* If collection_id is provided and the engram is shared across collections, a copy-on-write
+	* will be performed to create a collection-specific copy before modification.
+	* @operationId memories.update
+	* @endpoint PATCH /v1/memories/{id}
+	*/
+	async update(params, options) {
+		return this.core.request({
+			method: "PATCH",
+			path: "/v1/memories/{id}",
+			pathParams: { id: params.id },
+			query: { collection_id: params.collectionId },
+			body: params.body,
+			idempotent: false,
+			signal: options?.signal
+		});
+	}
+};
+//#endregion
+//#region src/resources/snapshots.ts
+var SnapshotsResource = class {
+	core;
+	constructor(core) {
+		this.core = core;
+	}
+	/**
+	*
+	* Export a collection snapshot
+	* 
+	* Export a collection's full graph state as a
+	* portable SnapshotEnvelope.
+	* @operationId snapshots.export
+	* @endpoint POST /v1/device-memory/snapshot/export
+	*/
+	async export(params, options) {
+		return this.core.request({
+			method: "POST",
+			path: "/v1/device-memory/snapshot/export",
+			pathParams: {},
+			query: void 0,
+			body: params.body,
+			idempotent: true,
+			signal: options?.signal
+		});
+	}
+	/**
+	*
+	* Import a snapshot into an ephemeral collection
+	* 
+	* Import a SnapshotEnvelope into an ephemeral
+	* collection. Returns the ephemeral collection UUID.
+	* @operationId snapshots.import
+	* @endpoint POST /v1/device-memory/snapshot/import
+	*/
+	async import(params, options) {
+		return this.core.request({
+			method: "POST",
+			path: "/v1/device-memory/snapshot/import",
+			pathParams: {},
+			query: void 0,
+			body: params.body,
+			idempotent: false,
+			signal: options?.signal
+		});
+	}
+};
+//#endregion
+//#region src/client.ts
+var NebulaClient = class {
+	core;
+	client;
+	collections;
+	connectors;
+	memories;
+	snapshots;
+	constructor(options = {}) {
+		this.core = new NebulaCore(options);
+		this.client = new ClientResource(this.core);
+		this.collections = new CollectionsResource(this.core);
+		this.connectors = new ConnectorsResource(this.core);
+		this.memories = new MemoriesResource(this.core);
+		this.snapshots = new SnapshotsResource(this.core);
+	}
+};
+//#endregion
+//#region src/lib/_dx_generated.ts
+/** Strip a `results` envelope at runtime; matches `Unwrapped<>`. */
+function unwrap$1(p) {
+	return p.then((r) => {
+		if (r !== null && typeof r === "object" && "results" in r) return r.results;
+		return r;
+	});
+}
+/**
+* Generated DX layer: simple unwrap/passthrough convenience methods.
+* Signatures are derived from the underlying resource methods so
+* callers see the same arg names + types in IDE hover.
+*/
+var NebulaDX = class extends NebulaClient {
+	/** Retrieve a single memory by id and return just the data. (generated from dx-extensions.yaml). */
+	async getMemory(...args) {
+		return unwrap$1(this.memories.retrieve(...args));
+	}
+	/** Update a memory by id; returns the updated record. (generated from dx-extensions.yaml). */
+	async updateMemory(...args) {
+		return unwrap$1(this.memories.update(...args));
+	}
+	/** Liveness probe with the wire envelope unwrapped. (generated from dx-extensions.yaml). */
+	async healthCheck(...args) {
+		return unwrap$1(this.client.health(...args));
+	}
+	/** unwrap → collections.create (generated from dx-extensions.yaml). */
+	async createCollection(...args) {
+		return unwrap$1(this.collections.create(...args));
+	}
+	/** unwrap → collections.retrieve (generated from dx-extensions.yaml). */
+	async getCollection(...args) {
+		return unwrap$1(this.collections.retrieve(...args));
+	}
+	/** unwrap → collections.retrieveByName (generated from dx-extensions.yaml). */
+	async getCollectionByName(...args) {
+		return unwrap$1(this.collections.retrieveByName(...args));
+	}
+	/** unwrap → collections.list (generated from dx-extensions.yaml). */
+	async listCollections(...args) {
+		return unwrap$1(this.collections.list(...args));
+	}
+	/** unwrap → collections.update (generated from dx-extensions.yaml). */
+	async updateCollection(...args) {
+		return unwrap$1(this.collections.update(...args));
+	}
+	/** unwrap → connectors.listProviders (generated from dx-extensions.yaml). */
+	async listProviders(...args) {
+		return unwrap$1(this.connectors.listProviders(...args));
+	}
+	/** unwrap → connectors.retrieve (generated from dx-extensions.yaml). */
+	async getConnection(...args) {
+		return unwrap$1(this.connectors.retrieve(...args));
+	}
+	/** unwrap → connectors.sync (generated from dx-extensions.yaml). */
+	async triggerSync(...args) {
+		return unwrap$1(this.connectors.sync(...args));
+	}
+	/** unwrap → memories.createUpload (generated from dx-extensions.yaml). */
+	async getUploadUrl(...args) {
+		return unwrap$1(this.memories.createUpload(...args));
+	}
+	/** unwrap → snapshots.export (generated from dx-extensions.yaml). */
+	async exportSnapshot(...args) {
+		return unwrap$1(this.snapshots.export(...args));
+	}
+	/** unwrap → snapshots.import (generated from dx-extensions.yaml). */
+	async importSnapshot(...args) {
+		return unwrap$1(this.snapshots.import(...args));
+	}
+};
+//#endregion
+//#region src/lib/dx.ts
+var Nebula = class extends NebulaDX {
+	constructor(options = {}) {
+		super(normalizeAuthOptions(normalizeClientOptions(options)));
+	}
+	/**
+	* Polymorphic memory creator: dispatches to memories.create or memories.append
+	* based on whether `memory_id` is set on the input. Returns the new memory's
+	* id (string), or — when `snapshot` is set — the updated snapshot envelope.
+	*/
+	async storeMemory(memory, options) {
+		if ("memory_id" in memory && memory.memory_id != null) {
+			const memoryID = memory.memory_id;
+			await this.memories.append({
+				id: memoryID,
+				body: toMemoryAppendParams(memory)
+			}, options);
+			return memoryID;
+		}
+		const result = unwrapResults(await this.memories.create({ body: toMemoryCreateParams(memory) }, options));
+		if (isSnapshotResult(result)) return result.snapshot ?? result;
+		return extractID(result);
+	}
+	/**
+	* Bulk parallel version of storeMemory with a concurrency cap.
+	*
+	* Default 8 concurrent in-flight requests matches the Python DX's
+	* `asyncio.Semaphore(max_concurrency)` pattern. Use `maxConcurrency: 1`
+	* for strictly serial submission; higher values risk overwhelming the
+	* server when memories[] is large.
+	*/
+	async storeMemories(memories, options) {
+		const cap = Math.max(1, options?.maxConcurrency ?? 8);
+		const signal = options?.signal;
+		const results = new Array(memories.length);
+		let nextIndex = 0;
+		const worker = async () => {
+			while (true) {
+				const i = nextIndex++;
+				if (i >= memories.length) return;
+				results[i] = await this.storeMemory(memories[i], { signal });
+			}
+		};
+		await Promise.all(Array.from({ length: Math.min(cap, memories.length) }, () => worker()));
+		return results;
+	}
+	/**
+	* List memories scoped to one or more collection ids (string | string[])
+	* or a full MemoryListParams object.
+	*/
+	async listMemories(query, options) {
+		const normalized = typeof query === "string" || Array.isArray(query) ? { collectionIds: arrayify(query) } : query;
+		return unwrap(this.memories.list(normalized, options));
+	}
+	/**
+	* Memory search shortcut: unwraps `results`. (Affinity-header injection
+	* is a planned enhancement; currently delegates straight to the resource.)
+	*/
+	async search(body, options) {
+		return unwrap(this.memories.search({ body }, options));
+	}
+	/**
+	* deleteCollection coerces the wire {success: bool} envelope into a Python-
+	* style boolean return.
+	*/
+	async deleteCollection(id, options) {
+		const result = unwrapResults(await this.collections.delete(id, options));
+		return Boolean(result.success);
+	}
+	createCluster = this.createCollection;
+	getCluster = this.getCollection;
+	getClusterByName = this.getCollectionByName;
+	listClusters = this.listCollections;
+	updateCluster = this.updateCollection;
+	deleteCluster = this.deleteCollection;
+	/**
+	* Positional `connectProvider(provider, collectionID, config?)` — wraps the
+	* generated `connectors.connect({provider, body})` to build the body shape.
+	*/
+	async connectProvider(provider, collectionID, config, options) {
+		const body = {
+			collection_id: collectionID,
+			...config !== void 0 ? { config } : {}
+		};
+		return unwrap(this.connectors.connect({
+			provider,
+			body
+		}, options));
+	}
+	/** Positional listConnections(collectionID) — wraps the query wrapper. */
+	async listConnections(collectionID, options) {
+		return unwrap(this.connectors.list({ collectionId: collectionID }, options));
+	}
+	/** Positional disconnect(connectionID, deleteMemories?). */
+	async disconnectConnection(connectionID, deleteMemories = false, options) {
+		return unwrap(this.connectors.disconnect({
+			connectionId: connectionID,
+			deleteMemories
+		}, options));
+	}
+	/** Alias for disconnectConnection (same arg shape). */
+	async disconnect(connectionID, deleteMemories = false, options) {
+		return unwrap(this.connectors.disconnect({
+			connectionId: connectionID,
+			deleteMemories
+		}, options));
+	}
+	/** Single-id delete; coerces 204 to boolean true. */
+	async deleteMemory(memoryID, options) {
+		await this.memories.delete(memoryID, options);
+		return true;
+	}
+	/** Bulk delete by ids. */
+	async deleteMemories(memoryIDs, options) {
+		return this.memories.deleteMany({ body: memoryIDs }, options);
+	}
+	/**
+	* Polymorphic delete: dispatches based on argument type.
+	* - `delete("/some/path")` -> raw HTTP DELETE (escape hatch; not implemented)
+	* - `delete("memory-id")` -> deleteMemory
+	* - `delete(["id1", "id2"])` -> deleteMemories (bulk)
+	*/
+	async delete(pathOrMemoryIDs, options) {
+		if (Array.isArray(pathOrMemoryIDs)) return this.deleteMemories(pathOrMemoryIDs, options);
+		if (isRequestPath(pathOrMemoryIDs)) throw new Error(`delete("${pathOrMemoryIDs}") raw-path escape hatch is not implemented in this SDK yet`);
+		return this.deleteMemory(pathOrMemoryIDs, options);
+	}
+};
+function normalizeAuthOptions(options) {
+	if (options.apiKey != null && options.bearerToken == null && !looksLikeNebulaAPIKey(options.apiKey)) return {
+		...options,
+		apiKey: void 0,
+		bearerToken: options.apiKey
+	};
+	return options;
+}
+function normalizeClientOptions(options) {
+	const { api_key: apiKeyAlias, apiKey, baseUrl: baseUrlAlias, baseURL: baseURLCapAlias, base_url: baseUrlSnakeAlias, timeout: timeoutAlias, bearerToken, bearer_token: bearerTokenAlias, accessToken, access_token: accessTokenAlias, ...rest } = options;
+	const restClientOptions = rest;
+	return {
+		...restClientOptions,
+		apiKey: firstDefined(apiKey, apiKeyAlias) ?? void 0,
+		bearerToken: firstDefined(bearerToken, bearerTokenAlias, accessToken, accessTokenAlias) ?? void 0,
+		baseUrl: firstDefined(restClientOptions.baseUrl, baseUrlAlias, baseURLCapAlias, baseUrlSnakeAlias) ?? void 0,
+		timeoutMs: firstDefined(restClientOptions.timeoutMs, timeoutAlias) ?? void 0
+	};
+}
+function firstDefined(...values) {
+	return values.find((value) => value !== void 0);
+}
+function looksLikeNebulaAPIKey(token) {
+	const parts = token.split(".");
+	if (parts.length !== 2) return false;
+	const [publicPart, rawPart] = parts;
+	return Boolean(rawPart) && (publicPart.startsWith("key_") || publicPart.startsWith("neb_"));
+}
+function toMemoryCreateParams(memory) {
+	const collectionID = memory.collection_id ?? memory.collectionId ?? void 0;
+	const { collectionId: _ignore, content, memory_id: _ignoreMemoryID, ...rest } = memory;
+	const params = { ...rest };
+	if (collectionID !== void 0) params.collection_id = collectionID;
+	if (content != null) if (typeof content === "string") params.raw_text = content;
+	else params.content_parts = content;
+	if (params.messages != null && !params.engram_type) params.engram_type = "conversation";
+	return params;
+}
+function toMemoryAppendParams(memory) {
+	const collectionID = memory.collection_id ?? memory.collectionId ?? void 0;
+	if (!collectionID) throw new Error("collection_id is required when appending to an existing memory");
+	const params = { collection_id: collectionID };
+	for (const key of [
+		"metadata",
+		"ingestion_config",
+		"ingestion_mode",
+		"raw_text",
+		"chunks",
+		"messages"
+	]) {
+		const value = memory[key];
+		if (value != null) params[key] = value;
+	}
+	const content = memory.content;
+	if (content != null) {
+		if (typeof content === "string") params.raw_text = content;
+		else if (Array.isArray(content) && content.every((item) => typeof item === "string")) params.chunks = content;
+		else if (Array.isArray(content)) params.messages = content;
+	}
+	return params;
+}
+function unwrap(promise) {
+	return Promise.resolve(promise).then((response) => unwrapResults(response));
+}
+function unwrapResults(response) {
+	if (response !== null && typeof response === "object" && "results" in response) return response.results;
+	return response;
+}
+function extractID(value) {
+	if (typeof value === "object" && value !== null) {
+		const record = value;
+		const id = record["id"] ?? record["memory_id"] ?? record["engram_id"] ?? record["ephemeral_collection_id"];
+		if (typeof id === "string") return id;
+	}
+	throw new Error("Nebula memory create response did not include an id");
+}
+function isSnapshotResult(value) {
+	return typeof value === "object" && value !== null && "snapshot" in value;
+}
+function arrayify(value) {
+	return Array.isArray(value) ? value : [value];
+}
+function isRequestPath(value) {
+	return value.startsWith("/") || /^https?:\/\//i.test(value);
+}
+//#endregion
+export { DEFAULT_RETRY, Nebula, Nebula as default, NebulaAPIError, NebulaBadRequestError, NebulaClient, NebulaConflictError, NebulaConnectionError, NebulaCore, NebulaError, NebulaForbiddenError, NebulaNotFoundError, NebulaRateLimitError, NebulaServerError, NebulaTimeoutError, NebulaUnauthorizedError, NebulaValidationError, backoffMs, errorFromResponse, isRetryableStatus, sleep };
 
-// src/index.ts
-var MemoryBase = (data) => data;
-var Memory2 = Object.assign(MemoryBase, {
-  /**
-   * Helper to create a file content part from a file path.
-   * Alias for NebulaContent.fromFile().
-   */
-  File: NebulaContent.fromFile,
-  /**
-   * Helper to create a complete Memory object from a single file.
-   */
-  async fromFile(filePath, collection_id, metadata, role) {
-    const path = await import('path');
-    const filename = path.basename(filePath);
-    return {
-      collection_id,
-      content: [await NebulaContent.fromFile(filePath)],
-      metadata: { filename, ...metadata },
-      role
-    };
-  }
-});
-
-exports.GraphSearchResultType = GraphSearchResultType;
-exports.Memory = Memory2;
-exports.Nebula = Nebula;
-exports.NebulaAuthenticationException = NebulaAuthenticationException;
-exports.NebulaClientException = NebulaClientException;
-exports.NebulaCollectionNotFoundException = NebulaCollectionNotFoundException;
-exports.NebulaContent = NebulaContent;
-exports.NebulaException = NebulaException;
-exports.NebulaNotFoundException = NebulaNotFoundException;
-exports.NebulaRateLimitException = NebulaRateLimitException;
-exports.NebulaValidationException = NebulaValidationException;
-exports.default = Nebula;
-//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map