@nebula-ai/sdk 1.4.0 → 1.6.0-rc.0

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
@@ -22,26 +31,33 @@ const client = new Nebula({
   // or: bearerToken: process.env.NEBULA_BEARER_TOKEN,
 });
 
-const id = await client.storeMemory({
+const result = await client.memories.create({
   collection_id: "01234567-...",
   raw_text: "hello, world",
 });
 
-const results = await client.search({ query: "hello" });
+const results = await client.memories.search({ query: "hello" });
 ```
 
-The high-level methods (`storeMemory`, `search`, `deleteMemory`, ...) come
-from the handwritten DX layer at `src/lib/dx.ts`. The low-level resource
-clients (`client.memories.*`, `client.collections.*`, ...) are generated
-directly from the OpenAPI spec and remain available as
-`client.memories.create(...)`, `client.memories.search(...)`, etc.
+Resource methods (`client.memories.*`, `client.collections.*`,
+`client.connectors.*`, `client.snapshots.*`) are generated directly from
+the OpenAPI spec. A small DX layer at `src/lib/dx.ts` adds polymorphic
+helpers like `storeMemory` (dispatches create-vs-append based on whether
+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