@coreviz/sdk 1.1.0 → 1.1.1

package/README.md

@@ -64,162 +64,149 @@ Notes:
 
 ## Configuration
 
-To use the AI features, you need to instantiate the `CoreViz` class with your API key.
-
 ```typescript
 import { CoreViz } from '@coreviz/sdk';
 
-const coreviz = new CoreViz({
-    apiKey: process.env.COREVIZ_API_KEY // or 'your_api_key_here'
-});
+// External use — API key
+const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });
+
+// CLI / server — session token
+const coreviz = new CoreViz({ token: 'your_session_token' });
+
+// Self-hosted or local dev — override base URL
+const coreviz = new CoreViz({ apiKey: '...', baseUrl: 'http://localhost:3000' });
+
+// Browser same-origin — no credentials needed; session cookie is used automatically
+const coreviz = new CoreViz({ baseUrl: window.location.origin });
 ```
 
-## API Reference
+---
+
+## Vision AI Methods
 
 ### `coreviz.describe(image)`
 
 Generates a detailed text description of an image.
 
 **Parameters:**
-- `image` (string): The image to describe. Can be a base64 string or a URL.
-
-**Returns:**
-- `Promise<string>`: A text description of the image.
+- `image` (string): Base64 data URL or remote URL.
 
-**Example:**
+**Returns:** `Promise<string>`
 
 ```typescript
 const description = await coreviz.describe('https://example.com/image.jpg');
-console.log(description);
 ```
 
+---
+
 ### `coreviz.tag(image, options)`
 
-Analyzes an image and returns relevant tags or classifications based on a prompt.
+Analyzes an image and returns tags or classifications based on a prompt.
 
 **Parameters:**
-- `image` (string): The image to analyze. Can be a base64 string or a URL.
-- `options` (object):
-  - `prompt` (string): The context or question to guide the tagging (e.g., "What objects are in this image?").
-  - `options` (string[], optional): A specific list of tags to choose from.
-  - `multiple` (boolean, optional): Whether to allow multiple tags (default: `true`).
-
-**Returns:**
-- `Promise<TagResponse>`: An object containing:
-  - `tags` (string[]): The list of identified tags.
-  - `raw` (unknown): The raw API response.
+- `image` (string): Base64 data URL or remote URL.
+- `options`:
+  - `prompt` (string): Question to guide tagging (e.g. `"What color is the car?"`).
+  - `options` (string[], optional): Restrict answers to this list.
+  - `multiple` (boolean, optional): Allow multiple tags (default: `true`).
+  - `mode` (`'api' | 'local'`, optional): `'local'` runs fully in-browser via transformers.js.
 
-**Example:**
+**Returns:** `Promise<TagResponse>` — `{ tags: string[], raw }`
 
 ```typescript
-const result = await coreviz.tag('base64_image_string...', {
-  prompt: "Is this indoor or outdoor?",
-  options: ["indoor", "outdoor"],
-  multiple: false
+const { tags } = await coreviz.tag(imageUrl, {
+  prompt: 'Is this indoor or outdoor?',
+  options: ['indoor', 'outdoor'],
+  multiple: false,
 });
-console.log(result.tags); // ["indoor"]
 ```
 
+---
+
 ### `coreviz.edit(image, options)`
 
-Modifies an image based on a text prompt using generative AI.
+Edits an image using a generative AI prompt.
 
 **Parameters:**
-- `image` (string): The image to edit. Can be a base64 string or a URL.
-- `options` (object):
+- `image` (string): Base64 data URL or remote URL.
+- `options`:
   - `prompt` (string): Description of the desired edit.
-  - `aspectRatio` (string, optional): Target aspect ratio (`'match_input_image'`, `'1:1'`, `'16:9'`, `'9:16'`, `'4:3'`, `'3:4'`).
-  - `outputFormat` (string, optional): `'jpg'` or `'png'`.
-  - `model` (string, optional): The model to use (default: `'flux-kontext-max'`).
-
-**Returns:**
-- `Promise<string>`: The edited image as a base64 string or URL.
+  - `aspectRatio` (string, optional): `'match_input_image'` | `'1:1'` | `'16:9'` | `'9:16'` | `'4:3'` | `'3:4'`.
+  - `outputFormat` (`'jpg' | 'png'`, optional).
+  - `model` (string, optional): `'flux-kontext-max'` | `'google/nano-banana'` | `'seedream-4'`. Default: `'flux-kontext-max'`.
 
-**Example:**
+**Returns:** `Promise<string>` — edited image URL or base64.
 
 ```typescript
-const editedImage = await coreviz.edit('https://example.com/photo.jpg', {
-  prompt: "Make it look like a painting",
-  aspectRatio: "1:1"
+const edited = await coreviz.edit('https://example.com/photo.jpg', {
+  prompt: 'Make it look like a watercolor painting',
+  aspectRatio: '1:1',
 });
 ```
 
-### `coreviz.generate(prompt, options)`
+---
 
-Generates an image based on a text prompt, optionally using reference images for style/structure guidance.
+### `coreviz.generate(prompt, options?)`
 
-**Parameters:**
-- `prompt` (string): The text description of the image(s) to generate.
-- `options` (object, optional):
-  - `referenceImages` (string[], optional): Array of reference images (URL/base64) to guide generation.
-  - `aspectRatio` (string, optional): Target aspect ratio (e.g., `'1:1'`, `'16:9'`, `'4:3'`).
-  - `model` (string, optional): The model to use (default: `'google/nano-banana-pro'`).
+Generates an image from a text prompt, optionally guided by reference images.
 
-**Returns:**
-- `string`: The generated images as a URL.
+**Parameters:**
+- `prompt` (string): Text description.
+- `options` (optional):
+  - `referenceImages` (string[]): Reference images (URL/base64) to guide style or structure.
+  - `aspectRatio` (string): e.g. `'1:1'`, `'16:9'`, `'4:3'`.
+  - `model` (string): `'google/nano-banana'` | `'google/nano-banana-pro'` | `'seedream-4'` | `'flux-kontext-max'`. Default: `'google/nano-banana-pro'`.
 
-**Example:**
+**Returns:** `Promise<string>` — generated image URL.
 
 ```typescript
-const images = await coreviz.generate("A futuristic city skyline", {
-  aspectRatio: "16:9"
-});
+const image = await coreviz.generate('A futuristic city at dusk', { aspectRatio: '16:9' });
 ```
 
+---
+
 ### `coreviz.embed(input, options?)`
 
 Generates embeddings for image or text inputs, enabling semantic search and similarity comparison. Use with `coreviz.similarity(embeddingA, embeddingB)` to compare two images or an image and a text.
 
 **Parameters:**
-- `input` (string): The text string or image (URL/base64) to embed.
-- `options` (object, optional):
-  - `type` ('image' | 'text', optional): Explicitly define the input type.
-  - `mode` ('api' | 'local', optional): Execution mode (default: `'api'`). `'local'` runs in-browser/node using transformers.js.
-
-**Returns:**
-- `Promise<EmbedResponse>`: An object containing:
-  - `embedding` (number[]): The high-dimensional vector representation.
+- `input` (string): Text string, image URL, or base64 data URL.
+- `options` (optional):
+  - `type` (`'image' | 'text'`): Explicit type hint (auto-detected if omitted).
+  - `mode` (`'api' | 'local'`): `'local'` runs in-browser using transformers.js. Default: `'api'`.
 
-**Example:**
+**Returns:** `Promise<EmbedResponse>` — `{ embedding: number[] }`
 
 ```typescript
-const { embedding } = await coreviz.embed('A photo of a sunset');
+const { embedding } = await coreviz.embed('A photo of a red sneaker');
 ```
 
-### `coreviz.similarity(embeddingA, embeddingB)`
+---
+
+### `coreviz.similarity(vecA, vecB)`
 
 Calculates the degree of similarity between two embeddings.
 
 **Parameters:**
-- `embeddingA` (number[]): The first image/text embedding.
-- `embeddingB` (number[]): The second image/text embedding.
-
-**Returns:**
-- `number`: A similarity score between -1 and 1.
+- `vecA`, `vecB` (number[]): Embedding vectors from `embed()`.
 
-**Example:**
+**Returns:** `number` — score between -1 and 1.
 
 ```typescript
-const similarity = coreviz.similarity(embeddingA, embeddingB);
+const score = coreviz.similarity(embeddingA, embeddingB);
 ```
 
-### `coreviz.resize(input, maxWidth?, maxHeight?)`
-
-Utility function to resize images client-side or server-side before processing. Also available as a standalone import.
+---
 
-**Parameters:**
-- `input` (string | File): The image to resize.
-- `maxWidth` (number, optional): Maximum width (default: 1920).
-- `maxHeight` (number, optional): Maximum height (default: 1080).
+### `coreviz.resize(input, maxWidth?, maxHeight?)`
 
-**Returns:**
-- `Promise<string>`: The resized image as a base64 string.
+Resizes an image client-side (canvas) or server-side (Sharp). Also available as a standalone import.
 
-**Example:**
+**Returns:** `Promise<string>` — base64 data URL.
 
 ```typescript
-const resized = await coreviz.resize(myFileObject, 800, 600);
-// or import { resize } from '@coreviz/sdk';
+const resized = await coreviz.resize(file, 800, 600);
+// or: import { resize } from '@coreviz/sdk';
 ```
 
 ---
@@ -228,32 +215,39 @@ const resized = await coreviz.resize(myFileObject, 800, 600);
 
 The SDK also exposes namespaced methods for programmatically managing your CoreViz visual library — browsing collections, searching media, organizing folders, and managing tags. These require authentication via a user token (from `coreviz login`) or an API key.
 
-```typescript
-const coreviz = new CoreViz({ token: 'your_session_token' });
-// or: new CoreViz({ apiKey: 'your_api_key' })
-// or: new CoreViz({ token, baseUrl: 'http://localhost:3000' }) // for local dev
-```
+---
+
+## Collections
+
+### `coreviz.collections.list(organizationId?)`
 
-### `coreviz.collections.list()`
+List all collections in an organization.
 
-List all collections in the user's current organization.
+- `organizationId` (string, optional): Pass explicitly to skip the `/api/me` round-trip.
 
 **Returns:** `Promise<Collection[]>`
 
 ```typescript
 const collections = await coreviz.collections.list();
-// [{ id, name, icon, type, organizationId }, ...]
 ```
 
 ---
 
-### `coreviz.collections.create(name, icon?)`
+### `coreviz.collections.get(collectionId)`
 
-Create a new collection in the user's current organization.
+Get a single collection by ID.
 
-**Parameters:**
-- `name` (string): Collection name.
-- `icon` (string, optional): Emoji or icon name.
+**Returns:** `Promise<Collection>`
+
+```typescript
+const collection = await coreviz.collections.get('abc123');
+```
+
+---
+
+### `coreviz.collections.create(name, icon?)`
+
+Create a new collection.
 
 **Returns:** `Promise<Collection>`
 
@@ -263,47 +257,78 @@ const collection = await coreviz.collections.create('Product Photos', '📦');
 
 ---
 
-### `coreviz.media.browse(collectionId, options?)`
+### `coreviz.collections.update(collectionId, updates)`
 
-List media items and folders inside a collection. Navigates the ltree folder hierarchy.
+Update a collection's name or icon.
 
 **Parameters:**
-- `collectionId` (string): The collection to browse.
-- `options` (object, optional):
-  - `path` (string): ltree path to list (e.g. `"collectionId.folderId"`). Defaults to collection root.
-  - `limit` / `offset` (number): Pagination.
-  - `type` (`'image' | 'video' | 'folder' | 'all'`): Filter by type.
-  - `dateFrom` / `dateTo` (string): Filter by creation date (`YYYY-MM-DD`).
-  - `sortBy` / `sortDirection`: Sort options.
-  - `tagFilters` (`Record<string, string[]>`): Filter by tag groups.
+- `updates`: `{ name?: string; icon?: string }`
+
+**Returns:** `Promise<Collection>`
+
+```typescript
+await coreviz.collections.update('abc123', { name: 'Campaign Assets 2025' });
+```
+
+---
+
+## Media
+
+### `coreviz.media.browse(collectionId, options?)`
+
+List media and folders inside a collection. Supports browsing, filtering, searching, and similarity queries all through the same method.
+
+**Options:**
+| Field | Type | Description |
+|---|---|---|
+| `path` | string | ltree path to list (e.g. `"collId.folderId"`). Defaults to collection root. |
+| `limit` / `offset` | number | Pagination. |
+| `type` | `'image' \| 'video' \| 'folder' \| 'all'` | Filter by media type. |
+| `dateFrom` / `dateTo` | string | Date range filter (`YYYY-MM-DD`). |
+| `sortBy` / `sortDirection` | string | Sort field and direction (`'asc' \| 'desc'`). |
+| `tagFilters` | `Record<string, string[]>` | AND between groups, OR within group. |
+| `q` | string | Text/semantic search query (triggers scored mode). |
+| `similarToObjectId` | string | Find visually similar media by detected object ID. |
+| `similarToObjectModel` | string | Vision model for similarity scoring. |
+| `tags` | string | Comma-separated tag label filter. |
+| `mediaId` | string | Filter to a specific media item. |
+| `clusterId` | string | Filter to a specific object cluster. |
+| `recursive` | boolean | List all descendants recursively (flattened view). |
 
 **Returns:** `Promise<BrowseResult>` — `{ media: Media[], pagination }`
 
 ```typescript
-const { media } = await coreviz.media.browse('abc123', { path: 'abc123.folderXyz', limit: 50 });
+// Browse a folder
+const { media } = await coreviz.media.browse('collId', { path: 'collId.folderXyz', limit: 50 });
+
+// In-folder semantic search
+const { media: results } = await coreviz.media.browse('collId', { q: 'red shoes' });
+
+// Find similar media by object
+const { media: similar } = await coreviz.media.browse('collId', { similarToObjectId: 'objId' });
 ```
 
 ---
 
 ### `coreviz.media.search(query, options?)`
 
-Semantically search across all media in the organization using natural language.
+Semantically search across all media in the organization.
 
-**Parameters:**
-- `query` (string): Natural language search query.
-- `options.limit` (number, optional): Max results (default 20).
+**Options:**
+- `limit` (number): Max results.
+- `organizationId` (string): Pass explicitly to skip the `/api/me` round-trip.
 
 **Returns:** `Promise<SearchResult[]>` — each result includes `mediaId`, `blobUrl`, `objects`, `rank`, `caption`.
 
 ```typescript
-const results = await coreviz.media.search('red shoes on a white background', { limit: 10 });
+const results = await coreviz.media.search('sunset over water', { limit: 10 });
 ```
 
 ---
 
 ### `coreviz.media.get(mediaId)`
 
-Get full details for a media item: blob URL, dimensions, tags, detected objects, and version info.
+Get full details for a media item including blob URL, dimensions, metadata, detected objects, and frames.
 
 **Returns:** `Promise<Media>`
 
@@ -328,100 +353,218 @@ await coreviz.media.rename('mediaId123', 'hero-shot-final.jpg');
 
 ### `coreviz.media.move(mediaId, destinationPath)`
 
-Move a media item or folder to a different location within the same collection.
+Move a media item to a different folder within the same collection.
 
-**Parameters:**
-- `destinationPath` (string): ltree path of the destination folder (e.g. `"collectionId.targetFolder"`).
+- `destinationPath` (string): ltree path of the destination folder.
 
 **Returns:** `Promise<{ id, newPath }>`
 
 ```typescript
-await coreviz.media.move('mediaId123', 'collectionId.archiveFolder');
+await coreviz.media.move('mediaId123', 'collId.archiveFolder');
+```
+
+---
+
+### `coreviz.media.delete(mediaId)`
+
+Permanently delete a media item.
+
+```typescript
+await coreviz.media.delete('mediaId123');
+```
+
+---
+
+### `coreviz.media.upload(file, options)`
+
+Upload a photo or video.
+
+**Parameters:**
+- `file`: Local file path string (Node.js), `File` (browser), or `Blob`.
+- `options`:
+  - `collectionId` (string, required)
+  - `path` (string, optional): Destination ltree folder path.
+  - `name` (string, optional): Override stored file name.
+
+**Returns:** `Promise<UploadResult>` — `{ mediaId, url, message }`
+
+```typescript
+// Node.js
+const result = await coreviz.media.upload('/path/to/photo.jpg', { collectionId: 'abc123' });
+
+// Browser
+const result = await coreviz.media.upload(file, { collectionId: 'abc123', path: 'abc123.folder' });
 ```
 
+> File path strings are not supported on React Native / Expo. Pass a `File` or `Blob` instead.
+
 ---
 
-### `coreviz.media.addTag(mediaId, label, value)` / `removeTag(...)`
+## Tags
+
+### `coreviz.media.addTag(mediaId, label, value)`
 
-Add or remove a tag from a media item. Tags are `label` (group) + `value` pairs.
+Add a tag to a media item. Tags are `label` (group) + `value` pairs.
 
 ```typescript
 await coreviz.media.addTag('mediaId123', 'color', 'red');
+```
+
+---
+
+### `coreviz.media.removeTag(mediaId, label, value)`
+
+Remove a specific tag value from a media item.
+
+```typescript
 await coreviz.media.removeTag('mediaId123', 'color', 'red');
 ```
 
 ---
 
+### `coreviz.media.removeTagGroup(mediaId, label)`
+
+Remove an entire tag group (all values under that label) from a media item.
+
+```typescript
+await coreviz.media.removeTagGroup('mediaId123', 'color');
+```
+
+---
+
+### `coreviz.media.renameTagGroup(mediaId, oldLabel, newLabel)`
+
+Rename a tag group on a media item, preserving all its values.
+
+```typescript
+await coreviz.media.renameTagGroup('mediaId123', 'colour', 'color');
+```
+
+---
+
+### `coreviz.tags.list(collectionId)`
+
+Aggregate all tag groups and values across an entire collection.
+
+**Returns:** `Promise<Record<string, string[]>>`
+
+```typescript
+const tags = await coreviz.tags.list('collId');
+// { color: ['red', 'blue'], category: ['product', 'lifestyle'] }
+```
+
+---
+
+## Versions
+
+Media items in CoreViz track edit history as versions. Each AI edit or bulk operation creates a new version linked to the original.
+
+### `coreviz.media.listVersions(mediaId)`
+
+List all versions of a media item (original + all AI-edited derivatives).
+
+**Returns:** `Promise<Media[]>`
+
+```typescript
+const versions = await coreviz.media.listVersions('mediaId123');
+```
+
+---
+
+### `coreviz.media.selectVersion(versionId)`
+
+Mark a version as the active/current version.
+
+```typescript
+await coreviz.media.selectVersion('versionId456');
+```
+
+---
+
+### `coreviz.media.deleteVersion(rootMediaId, versionId)`
+
+Delete a specific version. If the deleted version was active, the server promotes another version automatically.
+
+**Returns:** `Promise<{ deletedId: string; promotedId: string | null }>`
+
+```typescript
+const { promotedId } = await coreviz.media.deleteVersion('rootMediaId', 'versionId456');
+if (promotedId) {
+  // navigate to promoted version
+}
+```
+
+---
+
+## Similarity Search
+
 ### `coreviz.media.findSimilar(collectionId, objectId, options?)`
 
 Find visually similar media using a detected object ID (from `media.get()` frames).
 
-**Parameters:**
-- `collectionId` (string): The collection to search within.
-- `objectId` (string): ID of a detected object to use as the similarity query.
-- `options.model` (string): `'faces'`, `'objects'`, or `'shoeprints'`.
+**Options:**
+- `limit` (number)
+- `model` (string): e.g. `'faces'`, `'objects'`, `'shoeprints'`.
 
 **Returns:** `Promise<BrowseResult>`
 
 ```typescript
-const similar = await coreviz.media.findSimilar('collectionId', 'objectId456', { model: 'faces' });
+const { media } = await coreviz.media.findSimilar('collId', 'objectId456', { model: 'faces' });
 ```
 
 ---
 
-### `coreviz.folders.create(collectionId, name, path?)`
+## Folders
+
+### `coreviz.folders.create(collectionId, name, path?, reuse?)`
 
 Create a new folder inside a collection.
 
+- `path` (string, optional): Parent ltree path. Defaults to collection root.
+- `reuse` (boolean, optional): When `true`, returns the existing folder if one with the same name already exists at that path (upsert behavior).
+
 **Returns:** `Promise<Folder>`
 
 ```typescript
-const folder = await coreviz.folders.create('collectionId', 'Spring 2025', 'collectionId.campaigns');
+const folder = await coreviz.folders.create('collId', 'Spring 2025', 'collId.campaigns');
+
+// Upsert — safe to call repeatedly
+const folder = await coreviz.folders.create('collId', 'Imports', undefined, true);
 ```
 
 ---
 
-### `coreviz.tags.list(collectionId)`
+### `coreviz.folders.get(folderId)`
 
-Aggregate all tag groups and values across an entire collection.
+Get a folder by ID.
 
-**Returns:** `Promise<Record<string, string[]>>`
+**Returns:** `Promise<Folder>`
 
 ```typescript
-const tags = await coreviz.tags.list('collectionId');
-// { color: ['red', 'blue'], category: ['product', 'lifestyle'] }
+const folder = await coreviz.folders.get('folderId123');
 ```
 
 ---
 
-### `coreviz.media.upload(file, options)`
+### `coreviz.folders.update(folderId, updates)`
 
-Upload a photo or video to CoreViz.
+Update a folder's name or metadata.
 
 **Parameters:**
-- `file`: Local file path string (Node.js), `File` object (browser), or `Blob`
-- `options`:
-  - `collectionId` (string, required): Target collection
-  - `path` (string, optional): ltree folder path (e.g. `"collectionId.folderId"`). Defaults to collection root.
-  - `name` (string, optional): Override the file name stored in CoreViz
-
-**Returns:** `Promise<UploadResult>` — `{ mediaId, url, message }`
+- `updates`: `{ name?: string; metadata?: Record<string, unknown> }`
 
-**Supported formats:** JPEG, PNG, GIF, WebP, HEIC, MP4, WebM, MOV, AVI
+**Returns:** `Promise<Folder>`
 
 ```typescript
-// Node.js — local file path
-const result = await coreviz.media.upload('/path/to/photo.jpg', {
-  collectionId: 'abc123',
-  path: 'abc123.campaignFolder',
-  name: 'hero-shot.jpg',
-});
-console.log(result.mediaId, result.url);
-
-// Browser — File object
-const result = await coreviz.media.upload(fileInputEvent.target.files[0], {
-  collectionId: 'abc123',
-});
+await coreviz.folders.update('folderId123', { name: 'Archived Campaign' });
 ```
 
-> **Note:** File path strings are not supported on React Native / Expo. Pass a `File` or `Blob` object instead.
+---
+
+### `coreviz.folders.delete(folderId)`
+
+Delete a folder and all its contents.
+
+```typescript
+await coreviz.folders.delete('folderId123');
+```

package/dist/coreviz.d.ts

@@ -59,6 +59,20 @@ export interface BrowseOptions {
     sortBy?: string;
     sortDirection?: 'asc' | 'desc';
     tagFilters?: Record<string, string[]>;
+    /** Text / semantic search query (triggers scored mode on the server) */
+    q?: string;
+    /** Object ID to find visually similar media within this collection */
+    similarToObjectId?: string;
+    /** Vision model used for similarity scoring */
+    similarToObjectModel?: string;
+    /** Comma-separated tag label filter */
+    tags?: string;
+    /** Filter to a specific media item ID */
+    mediaId?: string;
+    /** Filter to a specific cluster ID */
+    clusterId?: string;
+    /** When true, list all descendants recursively (flattened view) */
+    recursive?: boolean;
 }
 export interface BrowseResult {
     media: Media[];
@@ -80,6 +94,20 @@ export interface SearchResult {
 }
 export interface SearchOptions {
     limit?: number;
+    /** Pass the organization ID directly to skip the /api/me round-trip. */
+    organizationId?: string;
+}
+export interface FolderUpdateOptions {
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CollectionUpdateOptions {
+    name?: string;
+    icon?: string;
+}
+export interface DeleteVersionResult {
+    deletedId: string;
+    promotedId: string | null;
 }
 export interface SimilarityOptions {
     limit?: number;
@@ -99,10 +127,17 @@ export interface UploadResult {
     message: string;
 }
 export interface CollectionsNamespace {
-    /** List all collections in the user's current organization */
-    list(): Promise<Collection[]>;
+    /**
+     * List all collections in an organization.
+     * @param organizationId - If omitted the SDK resolves it via /api/me (one extra round-trip).
+     */
+    list(organizationId?: string): Promise<Collection[]>;
+    /** Get a single collection by ID */
+    get(collectionId: string): Promise<Collection>;
     /** Create a new collection in the user's current organization */
     create(name: string, icon?: string): Promise<Collection>;
+    /** Update a collection's name or icon */
+    update(collectionId: string, updates: CollectionUpdateOptions): Promise<Collection>;
 }
 export interface MediaNamespace {
     /** Browse/list media items in a collection folder */
@@ -118,10 +153,22 @@ export interface MediaNamespace {
         id: string;
         newPath: string;
     }>;
+    /** Permanently delete a media item */
+    delete(mediaId: string): Promise<void>;
     /** Add a tag group+value to a media item */
     addTag(mediaId: string, label: string, value: string): Promise<void>;
-    /** Remove a tag group+value from a media item */
+    /** Remove a specific tag value from a media item */
     removeTag(mediaId: string, label: string, value: string): Promise<void>;
+    /** Remove an entire tag group (all values) from a media item */
+    removeTagGroup(mediaId: string, label: string): Promise<void>;
+    /** Rename a tag group across a media item */
+    renameTagGroup(mediaId: string, oldLabel: string, newLabel: string): Promise<void>;
+    /** List all versions of a media item */
+    listVersions(mediaId: string): Promise<Media[]>;
+    /** Delete a specific version; returns the promoted active version ID if applicable */
+    deleteVersion(rootMediaId: string, versionId: string): Promise<DeleteVersionResult>;
+    /** Mark a version as the active/current version */
+    selectVersion(versionId: string): Promise<void>;
     /** Find visually similar media using an object ID */
     findSimilar(collectionId: string, objectId: string, options?: SimilarityOptions): Promise<BrowseResult>;
     /**
@@ -132,8 +179,17 @@ export interface MediaNamespace {
     upload(file: string | File | Blob, options: UploadOptions): Promise<UploadResult>;
 }
 export interface FoldersNamespace {
-    /** Create a folder inside a collection */
-    create(collectionId: string, name: string, path?: string): Promise<Folder>;
+    /**
+     * Create a folder inside a collection.
+     * @param reuse - When true, return the existing folder if one with the same name already exists at that path (upsert).
+     */
+    create(collectionId: string, name: string, path?: string, reuse?: boolean): Promise<Folder>;
+    /** Get a folder by ID */
+    get(folderId: string): Promise<Folder>;
+    /** Update a folder's name or metadata */
+    update(folderId: string, updates: FolderUpdateOptions): Promise<Folder>;
+    /** Delete a folder and all its contents */
+    delete(folderId: string): Promise<void>;
 }
 export interface TagsNamespace {
     /** Aggregate all tag groups + values across a collection */

package/dist/coreviz.js

@@ -43,11 +43,15 @@ class CoreViz {
         this._baseUrl = config.baseUrl || 'https://lab.coreviz.io';
         // ── Management namespaces ────────────────────────────────────────────
         this.collections = {
-            list: async () => {
-                const { organizationId } = await this._me();
-                const data = await this._fetch(`/api/organization/${organizationId}/datasets`);
+            list: async (organizationId) => {
+                const orgId = organizationId || (await this._me()).organizationId;
+                const data = await this._fetch(`/api/organization/${orgId}/datasets`);
                 return Array.isArray(data) ? data : data.datasets ?? [];
             },
+            get: async (collectionId) => {
+                const data = await this._fetch(`/api/dataset/${collectionId}`);
+                return data.dataset;
+            },
             create: async (name, icon) => {
                 const { organizationId } = await this._me();
                 const data = await this._fetchMethod('POST', `/api/organization/${organizationId}/datasets`, {
@@ -56,6 +60,10 @@ class CoreViz {
                 });
                 return data.dataset;
             },
+            update: async (collectionId, updates) => {
+                const data = await this._fetchMethod('PATCH', `/api/dataset/${collectionId}`, updates);
+                return data.dataset;
+            },
         };
         this.media = {
             browse: async (collectionId, options = {}) => {
@@ -78,12 +86,26 @@ class CoreViz {
                     params.set('sortDirection', options.sortDirection);
                 if (options.tagFilters)
                     params.set('tagFilters', JSON.stringify(options.tagFilters));
+                if (options.q)
+                    params.set('q', options.q);
+                if (options.similarToObjectId)
+                    params.set('similarToObjectId', options.similarToObjectId);
+                if (options.similarToObjectModel)
+                    params.set('similarToObjectModel', options.similarToObjectModel);
+                if (options.tags)
+                    params.set('tags', options.tags);
+                if (options.mediaId)
+                    params.set('mediaId', options.mediaId);
+                if (options.clusterId)
+                    params.set('clusterId', options.clusterId);
+                if (options.recursive)
+                    params.set('recursive', 'true');
                 const qs = params.toString();
                 return this._fetch(`/api/dataset/${collectionId}/media${qs ? `?${qs}` : ''}`);
             },
             search: async (query, options = {}) => {
-                const { organizationId } = await this._me();
-                const params = new URLSearchParams({ q: query, organizationId });
+                const orgId = options.organizationId || (await this._me()).organizationId;
+                const params = new URLSearchParams({ q: query, organizationId: orgId });
                 if (options.limit != null)
                     params.set('limit', String(options.limit));
                 const data = await this._fetch(`/api/search?${params.toString()}`);
@@ -108,12 +130,31 @@ class CoreViz {
             move: async (mediaId, destinationPath) => {
                 return this._fetchMethod('PATCH', `/api/media/${mediaId}/move`, { destinationPath });
             },
+            delete: async (mediaId) => {
+                await this._fetchMethod('DELETE', `/api/media/${mediaId}`);
+            },
             addTag: async (mediaId, label, value) => {
                 await this._fetchMethod('POST', `/api/media/${mediaId}/tags`, { label, value });
             },
             removeTag: async (mediaId, label, value) => {
                 await this._fetchMethod('DELETE', `/api/media/${mediaId}/tags`, { label, value });
             },
+            removeTagGroup: async (mediaId, label) => {
+                await this._fetchMethod('DELETE', `/api/media/${mediaId}/tags`, { label });
+            },
+            renameTagGroup: async (mediaId, oldLabel, newLabel) => {
+                await this._fetchMethod('PATCH', `/api/media/${mediaId}/tags`, { oldLabel, newLabel });
+            },
+            listVersions: async (mediaId) => {
+                const data = await this._fetch(`/api/media/${mediaId}/versions`);
+                return data.versions;
+            },
+            deleteVersion: async (rootMediaId, versionId) => {
+                return this._fetchMethod('DELETE', `/api/media/${rootMediaId}/versions?versionId=${versionId}`);
+            },
+            selectVersion: async (versionId) => {
+                await this._fetchMethod('PATCH', `/api/media/${versionId}/select-version`);
+            },
             findSimilar: async (collectionId, objectId, options = {}) => {
                 const params = new URLSearchParams({ similarToObjectId: objectId });
                 if (options.limit != null)
@@ -168,14 +209,26 @@ class CoreViz {
             },
         };
         this.folders = {
-            create: async (collectionId, name, path) => {
+            create: async (collectionId, name, path, reuse) => {
                 const data = await this._fetchMethod('POST', '/api/folder', {
                     datasetId: collectionId,
                     name,
                     ...(path ? { path } : {}),
+                    ...(reuse ? { reuse: true } : {}),
                 });
                 return data.folder;
             },
+            get: async (folderId) => {
+                const data = await this._fetch(`/api/folder/${folderId}`);
+                return data.folder;
+            },
+            update: async (folderId, updates) => {
+                const data = await this._fetchMethod('PATCH', `/api/folder/${folderId}`, updates);
+                return data.folder;
+            },
+            delete: async (folderId) => {
+                await this._fetchMethod('DELETE', `/api/folder/${folderId}`);
+            },
         };
         this.tags = {
             list: async (collectionId) => {
@@ -192,9 +245,10 @@ class CoreViz {
         if (this.token) {
             headers['Authorization'] = `Bearer ${this.token}`;
         }
-        else {
-            headers['x-api-key'] = this.apiKey || "";
+        else if (this.apiKey) {
+            headers['x-api-key'] = this.apiKey;
         }
+        // If neither is set, rely on session cookies (browser same-origin requests).
         return headers;
     }
     /** Resolve the current user's org ID (cached after first call) */
@@ -228,7 +282,10 @@ class CoreViz {
             throw new Error('Insufficient credits');
         }
         if (!response.ok) {
-            throw new Error(`Request failed (${response.status})`);
+            // Try to surface the server's error message from the response body.
+            const body = await response.json().catch(() => null);
+            const serverMessage = body?.error || body?.message;
+            throw new Error(serverMessage || `Request failed (${response.status})`);
         }
         const data = await response.json();
         if (data.error) {
@@ -240,7 +297,7 @@ class CoreViz {
         try {
             const resizedImage = await (0, resize_1.resize)(image, 512, 512);
             const headers = this.getHeaders();
-            const response = await fetch(`https://lab.coreviz.io/api/ai/describe`, {
+            const response = await fetch(`${this._baseUrl}/api/ai/describe`, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify({ image: resizedImage }),
@@ -256,7 +313,7 @@ class CoreViz {
         try {
             const resizedImage = await (0, resize_1.resize)(image, 1024, 1024);
             const headers = this.getHeaders();
-            const response = await fetch(`https://lab.coreviz.io/api/ai/edit`, {
+            const response = await fetch(`${this._baseUrl}/api/ai/edit`, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify({
@@ -281,7 +338,7 @@ class CoreViz {
             if (options.referenceImages && options.referenceImages.length > 0) {
                 resizedImages = await Promise.all(options.referenceImages.map(img => (0, resize_1.resize)(img, 1024, 1024)));
             }
-            const response = await fetch(`https://lab.coreviz.io/api/ai/generate`, {
+            const response = await fetch(`${this._baseUrl}/api/ai/generate`, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify({
@@ -306,7 +363,7 @@ class CoreViz {
         try {
             const resizedImage = await (0, resize_1.resize)(image, 512, 512);
             const headers = this.getHeaders();
-            const response = await fetch("https://lab.coreviz.io/api/ai/tag", {
+            const response = await fetch(`${this._baseUrl}/api/ai/tag`, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify({
@@ -460,7 +517,7 @@ Output:
             else {
                 body.text = input;
             }
-            const response = await fetch("https://lab.coreviz.io/api/ai/embed", {
+            const response = await fetch(`${this._baseUrl}/api/ai/embed`, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify(body),

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CoreViz, CoreVizConfig, DescribeOptions, EditOptions, TagOptions, TagResponse, EmbedOptions, EmbedResponse, GenerateOptions, UserContext, Collection, Media, MediaObject, MediaFrame, Folder, BrowseOptions, BrowseResult, SearchResult, SearchOptions, SimilarityOptions, UploadOptions, UploadResult, CollectionsNamespace, MediaNamespace, FoldersNamespace, TagsNamespace } from './coreviz';
+import { CoreViz, CoreVizConfig, DescribeOptions, EditOptions, TagOptions, TagResponse, EmbedOptions, EmbedResponse, GenerateOptions, UserContext, Collection, Media, MediaObject, MediaFrame, Folder, BrowseOptions, BrowseResult, SearchResult, SearchOptions, SimilarityOptions, UploadOptions, UploadResult, CollectionsNamespace, MediaNamespace, FoldersNamespace, TagsNamespace, FolderUpdateOptions, CollectionUpdateOptions, DeleteVersionResult } from './coreviz';
 import { resize } from './resize';
 export { CoreViz, resize };
-export type { CoreVizConfig, DescribeOptions, EditOptions, TagOptions, TagResponse, EmbedOptions, EmbedResponse, GenerateOptions, UserContext, Collection, Media, MediaObject, MediaFrame, Folder, BrowseOptions, BrowseResult, SearchResult, SearchOptions, SimilarityOptions, UploadOptions, UploadResult, CollectionsNamespace, MediaNamespace, FoldersNamespace, TagsNamespace };
+export type { CoreVizConfig, DescribeOptions, EditOptions, TagOptions, TagResponse, EmbedOptions, EmbedResponse, GenerateOptions, UserContext, Collection, Media, MediaObject, MediaFrame, Folder, BrowseOptions, BrowseResult, SearchResult, SearchOptions, SimilarityOptions, UploadOptions, UploadResult, CollectionsNamespace, MediaNamespace, FoldersNamespace, TagsNamespace, FolderUpdateOptions, CollectionUpdateOptions, DeleteVersionResult };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coreviz/sdk",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "CoreViz SDK",
   "main": "dist/index.js",
   "react-native": "dist/index.native.js",