@nebula-ai/sdk 1.3.0 → 1.4.0

package/dist/index.js

@@ -0,0 +1,1244 @@
+//#region src/runtime/errors.ts
+var NebulaError = class extends Error {
+	name = "NebulaError";
+	constructor(message, options) {
+		super(message, options);
+	}
+};
+var NebulaConnectionError = class extends NebulaError {
+	name = "NebulaConnectionError";
+};
+var NebulaTimeoutError = class extends NebulaError {
+	name = "NebulaTimeoutError";
+};
+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 NebulaBadRequestError = class extends NebulaAPIError {
+	name = "NebulaBadRequestError";
+};
+var NebulaUnauthorizedError = class extends NebulaAPIError {
+	name = "NebulaUnauthorizedError";
+};
+var NebulaForbiddenError = class extends NebulaAPIError {
+	name = "NebulaForbiddenError";
+};
+var NebulaNotFoundError = class extends NebulaAPIError {
+	name = "NebulaNotFoundError";
+};
+var NebulaConflictError = class extends NebulaAPIError {
+	name = "NebulaConflictError";
+};
+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 };
+
+//# sourceMappingURL=index.js.map