@nebula-ai/sdk 1.5.0 → 1.6.1

package/README.md

@@ -7,11 +7,20 @@ health.
 ## Install
 
 ```bash
+# Stable
 npm install @nebula-ai/sdk
-# or
-bun add @nebula-ai/sdk
+# Preview (next iteration, RC versions)
+npm install @nebula-ai/sdk@next
 ```
 
+> **Pre-launch:** The public surface is still being shaped. Plain
+> semver releases (`1.6.0`, `1.7.0`, …) are stable and published to
+> the `latest` dist-tag. Iteration happens on the `next` dist-tag
+> as pre-release versions (`1.6.0-rc.1`, `-rc.2`, …). Caret ranges
+> like `^1.6.0` never auto-pick pre-releases — semver excludes them
+> unless you explicitly opt in. Stable consumers are insulated from
+> the iteration channel by default.
+
 ## Quick start
 
 ```ts
@@ -38,10 +47,17 @@ a `memory_id` is present); prefer the resource methods for everything else.
 
 ## Auth
 
-The constructor accepts both `apiKey` / `bearerToken` (camelCase) and the
-snake_case aliases `api_key` / `access_token`. If you pass an API key that
-doesn't look like a Nebula key (not prefixed with `key_` or `neb_`), the
-DX layer automatically routes it through the bearer-token header instead.
+Pass either `apiKey` (for Nebula API keys) or `bearerToken` (for JWTs)
+when constructing the client. If you pass an opaque-looking token via
+`apiKey` (one that isn't prefixed with `key_` or `neb_`), the DX layer
+automatically routes it through the `Authorization: Bearer` header
+instead — handy when your app exchanges a workspace token for the SDK
+and doesn't want to think about which header to use.
+
+```ts
+new Nebula({ apiKey: process.env.NEBULA_API_KEY });
+new Nebula({ bearerToken: process.env.NEBULA_BEARER_TOKEN });
+```
 
 ## Errors
 

package/dist/index.cjs

@@ -285,9 +285,8 @@ var ClientResource = class {
 		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
@@ -311,12 +310,11 @@ var CollectionsResource = class {
 		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.
@@ -335,11 +333,10 @@ var CollectionsResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -358,16 +355,15 @@ var CollectionsResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -391,11 +387,10 @@ var CollectionsResource = class {
 		});
 	}
 	/**
-	*
 	* 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.
@@ -413,11 +408,10 @@ var CollectionsResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -434,11 +428,10 @@ var CollectionsResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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.
@@ -465,9 +458,8 @@ var ConnectorsResource = class {
 		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
@@ -484,9 +476,8 @@ var ConnectorsResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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}
@@ -502,9 +493,8 @@ var ConnectorsResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -520,9 +510,8 @@ var ConnectorsResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -538,9 +527,8 @@ var ConnectorsResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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}
@@ -556,9 +544,8 @@ var ConnectorsResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -582,15 +569,14 @@ var MemoriesResource = class {
 		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
@@ -609,11 +595,10 @@ var MemoriesResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -636,19 +621,18 @@ var MemoriesResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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)
@@ -675,13 +659,12 @@ var MemoriesResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -698,17 +681,16 @@ var MemoriesResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -727,9 +709,8 @@ var MemoriesResource = class {
 		});
 	}
 	/**
-	*
 	* 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
@@ -746,16 +727,15 @@ var MemoriesResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -781,11 +761,10 @@ var MemoriesResource = class {
 		});
 	}
 	/**
-	*
 	* 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
@@ -809,15 +788,14 @@ var MemoriesResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -834,14 +812,13 @@ var MemoriesResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -859,20 +836,19 @@ var MemoriesResource = class {
 		})).results;
 	}
 	/**
-	*
 	* 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
@@ -898,9 +874,8 @@ var SnapshotsResource = class {
 		this.core = core;
 	}
 	/**
-	*
 	* Export a collection snapshot
-	* 
+	*
 	* Export a collection's full graph state as a
 	* portable SnapshotEnvelope.
 	* @operationId snapshots.export
@@ -918,9 +893,8 @@ var SnapshotsResource = class {
 		})).results;
 	}
 	/**
-	*
 	* Import a snapshot into an ephemeral collection
-	* 
+	*
 	* Import a SnapshotEnvelope into an ephemeral
 	* collection. Returns the ephemeral collection UUID.
 	* @operationId snapshots.import
@@ -939,6 +913,89 @@ var SnapshotsResource = class {
 	}
 };
 //#endregion
+//#region src/resources/workspaces.ts
+var WorkspacesResource = class {
+	core;
+	constructor(core) {
+		this.core = core;
+	}
+	/**
+	* Create workspace storage target
+	*
+	* Register a customer S3 bucket for hosted BYOC storage.
+	* @operationId workspaces.createStorageTarget
+	* @endpoint POST /v1/workspaces/{workspace_id}/storage-targets
+	*/
+	async createStorageTarget(params, options) {
+		return (await this.core.request({
+			method: "POST",
+			path: "/v1/workspaces/{workspace_id}/storage-targets",
+			pathParams: { workspace_id: params.workspaceId },
+			query: void 0,
+			body: params.body,
+			idempotent: false,
+			signal: options?.signal
+		})).results;
+	}
+	/**
+	* Disable workspace storage target
+	*
+	* Disable a customer storage target for future collection binds.
+	* @operationId workspaces.disableStorageTarget
+	* @endpoint DELETE /v1/workspaces/{workspace_id}/storage-targets/{target_id}
+	*/
+	async disableStorageTarget(params, options) {
+		return (await this.core.request({
+			method: "DELETE",
+			path: "/v1/workspaces/{workspace_id}/storage-targets/{target_id}",
+			pathParams: {
+				workspace_id: params.workspaceId,
+				target_id: params.targetId
+			},
+			query: void 0,
+			idempotent: false,
+			signal: options?.signal
+		})).results;
+	}
+	/**
+	* List workspace storage targets
+	*
+	* List customer-owned object storage targets for a workspace.
+	* @operationId workspaces.listStorageTargets
+	* @endpoint GET /v1/workspaces/{workspace_id}/storage-targets
+	*/
+	async listStorageTargets(workspaceId, options) {
+		return (await this.core.request({
+			method: "GET",
+			path: "/v1/workspaces/{workspace_id}/storage-targets",
+			pathParams: { workspace_id: workspaceId },
+			query: void 0,
+			idempotent: true,
+			signal: options?.signal
+		})).results;
+	}
+	/**
+	* Validate workspace storage target
+	*
+	* Probe a customer storage target and mark it active on success.
+	* @operationId workspaces.validateStorageTarget
+	* @endpoint POST /v1/workspaces/{workspace_id}/storage-targets/{target_id}/validate
+	*/
+	async validateStorageTarget(params, options) {
+		return (await this.core.request({
+			method: "POST",
+			path: "/v1/workspaces/{workspace_id}/storage-targets/{target_id}/validate",
+			pathParams: {
+				workspace_id: params.workspaceId,
+				target_id: params.targetId
+			},
+			query: void 0,
+			idempotent: false,
+			signal: options?.signal
+		})).results;
+	}
+};
+//#endregion
 //#region src/client.ts
 var NebulaClient = class {
 	core;
@@ -947,6 +1004,7 @@ var NebulaClient = class {
 	connectors;
 	memories;
 	snapshots;
+	workspaces;
 	constructor(options = {}) {
 		this.core = new NebulaCore(options);
 		this.client = new ClientResource(this.core);
@@ -954,6 +1012,7 @@ var NebulaClient = class {
 		this.connectors = new ConnectorsResource(this.core);
 		this.memories = new MemoriesResource(this.core);
 		this.snapshots = new SnapshotsResource(this.core);
+		this.workspaces = new WorkspacesResource(this.core);
 	}
 };
 //#endregion