@coreviz/sdk 1.0.17 → 1.1.0

package/README.md

@@ -144,26 +144,24 @@ const editedImage = await coreviz.edit('https://example.com/photo.jpg', {
 });
 ```
 
-### `coreviz.batchGenerate(prompt, options)`
+### `coreviz.generate(prompt, options)`
 
-Generates multiple images based on a text prompt, optionally using reference images for style/structure guidance.
+Generates an image based on a text prompt, optionally using reference images for style/structure guidance.
 
 **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.
-  - `count` (number, optional): Number of images to generate (default: 1).
   - `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'`).
 
 **Returns:**
-- `Promise<string[]>`: An array of generated images as URLs.
+- `string`: The generated images as a URL.
 
 **Example:**
 
 ```typescript
-const images = await coreviz.batchGenerate("A futuristic city skyline", {
-  count: 4,
+const images = await coreviz.generate("A futuristic city skyline", {
   aspectRatio: "16:9"
 });
 ```
@@ -223,3 +221,207 @@ Utility function to resize images client-side or server-side before processing.
 const resized = await coreviz.resize(myFileObject, 800, 600);
 // or import { resize } from '@coreviz/sdk';
 ```
+
+---
+
+## Library Management API
+
+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
+```
+
+### `coreviz.collections.list()`
+
+List all collections in the user's current organization.
+
+**Returns:** `Promise<Collection[]>`
+
+```typescript
+const collections = await coreviz.collections.list();
+// [{ id, name, icon, type, organizationId }, ...]
+```
+
+---
+
+### `coreviz.collections.create(name, icon?)`
+
+Create a new collection in the user's current organization.
+
+**Parameters:**
+- `name` (string): Collection name.
+- `icon` (string, optional): Emoji or icon name.
+
+**Returns:** `Promise<Collection>`
+
+```typescript
+const collection = await coreviz.collections.create('Product Photos', '📦');
+```
+
+---
+
+### `coreviz.media.browse(collectionId, options?)`
+
+List media items and folders inside a collection. Navigates the ltree folder hierarchy.
+
+**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.
+
+**Returns:** `Promise<BrowseResult>` — `{ media: Media[], pagination }`
+
+```typescript
+const { media } = await coreviz.media.browse('abc123', { path: 'abc123.folderXyz', limit: 50 });
+```
+
+---
+
+### `coreviz.media.search(query, options?)`
+
+Semantically search across all media in the organization using natural language.
+
+**Parameters:**
+- `query` (string): Natural language search query.
+- `options.limit` (number, optional): Max results (default 20).
+
+**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 });
+```
+
+---
+
+### `coreviz.media.get(mediaId)`
+
+Get full details for a media item: blob URL, dimensions, tags, detected objects, and version info.
+
+**Returns:** `Promise<Media>`
+
+```typescript
+const item = await coreviz.media.get('mediaId123');
+console.log(item.blob, item.metadata?.tags, item.frames);
+```
+
+---
+
+### `coreviz.media.rename(mediaId, name)`
+
+Rename a media item.
+
+**Returns:** `Promise<Media>`
+
+```typescript
+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.
+
+**Parameters:**
+- `destinationPath` (string): ltree path of the destination folder (e.g. `"collectionId.targetFolder"`).
+
+**Returns:** `Promise<{ id, newPath }>`
+
+```typescript
+await coreviz.media.move('mediaId123', 'collectionId.archiveFolder');
+```
+
+---
+
+### `coreviz.media.addTag(mediaId, label, value)` / `removeTag(...)`
+
+Add or remove a tag from a media item. Tags are `label` (group) + `value` pairs.
+
+```typescript
+await coreviz.media.addTag('mediaId123', 'color', 'red');
+await coreviz.media.removeTag('mediaId123', 'color', 'red');
+```
+
+---
+
+### `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'`.
+
+**Returns:** `Promise<BrowseResult>`
+
+```typescript
+const similar = await coreviz.media.findSimilar('collectionId', 'objectId456', { model: 'faces' });
+```
+
+---
+
+### `coreviz.folders.create(collectionId, name, path?)`
+
+Create a new folder inside a collection.
+
+**Returns:** `Promise<Folder>`
+
+```typescript
+const folder = await coreviz.folders.create('collectionId', 'Spring 2025', 'collectionId.campaigns');
+```
+
+---
+
+### `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('collectionId');
+// { color: ['red', 'blue'], category: ['product', 'lifestyle'] }
+```
+
+---
+
+### `coreviz.media.upload(file, options)`
+
+Upload a photo or video to CoreViz.
+
+**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 }`
+
+**Supported formats:** JPEG, PNG, GIF, WebP, HEIC, MP4, WebM, MOV, AVI
+
+```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',
+});
+```
+
+> **Note:** File path strings are not supported on React Native / Expo. Pass a `File` or `Blob` object instead.

package/dist/coreviz.d.ts

@@ -1,6 +1,143 @@
 export interface CoreVizConfig {
     apiKey?: string;
     token?: string;
+    /** Override the API base URL (default: https://lab.coreviz.io) */
+    baseUrl?: string;
+}
+export interface UserContext {
+    userId: string;
+    email: string;
+    name: string;
+    organizationId: string;
+    organizationName: string | null;
+}
+export interface Collection {
+    id: string;
+    name: string;
+    icon?: string;
+    type: string;
+    organizationId: string;
+}
+export interface MediaObject {
+    id: string;
+    type: string;
+    label: string;
+}
+export interface MediaFrame {
+    id: string;
+    timestamp: number;
+    blob: string;
+    objects: MediaObject[];
+}
+export interface Media {
+    id: string;
+    name: string;
+    type: 'image' | 'video' | 'folder';
+    blob: string | null;
+    path: string;
+    width?: number;
+    height?: number;
+    sizeBytes?: number;
+    metadata?: Record<string, unknown>;
+    frames?: MediaFrame[];
+    createdAt?: string;
+    _score?: number;
+}
+export interface Folder {
+    id: string;
+    name: string;
+    path: string;
+    collectionId: string;
+}
+export interface BrowseOptions {
+    path?: string;
+    limit?: number;
+    offset?: number;
+    type?: 'image' | 'video' | 'folder' | 'all';
+    dateFrom?: string;
+    dateTo?: string;
+    sortBy?: string;
+    sortDirection?: 'asc' | 'desc';
+    tagFilters?: Record<string, string[]>;
+}
+export interface BrowseResult {
+    media: Media[];
+    pagination: {
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
+}
+export interface SearchResult {
+    mediaId: string;
+    mediaName: string;
+    mediaType: string;
+    blobUrl: string;
+    objects: MediaObject[];
+    rank: number;
+    caption?: string;
+}
+export interface SearchOptions {
+    limit?: number;
+}
+export interface SimilarityOptions {
+    limit?: number;
+    model?: string;
+}
+export interface UploadOptions {
+    /** Target collection ID */
+    collectionId: string;
+    /** ltree folder path to upload into (e.g. "collectionId.folderId"). Defaults to collection root. */
+    path?: string;
+    /** Override the file name stored in CoreViz */
+    name?: string;
+}
+export interface UploadResult {
+    mediaId: string;
+    url: string;
+    message: string;
+}
+export interface CollectionsNamespace {
+    /** List all collections in the user's current organization */
+    list(): Promise<Collection[]>;
+    /** Create a new collection in the user's current organization */
+    create(name: string, icon?: string): Promise<Collection>;
+}
+export interface MediaNamespace {
+    /** Browse/list media items in a collection folder */
+    browse(collectionId: string, options?: BrowseOptions): Promise<BrowseResult>;
+    /** Semantic search across all org media */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /** Get full details for a media item */
+    get(mediaId: string): Promise<Media>;
+    /** Rename a media item */
+    rename(mediaId: string, name: string): Promise<Media>;
+    /** Move a media item to a new ltree destination path */
+    move(mediaId: string, destinationPath: string): Promise<{
+        id: string;
+        newPath: string;
+    }>;
+    /** 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 */
+    removeTag(mediaId: string, label: string, value: string): Promise<void>;
+    /** Find visually similar media using an object ID */
+    findSimilar(collectionId: string, objectId: string, options?: SimilarityOptions): Promise<BrowseResult>;
+    /**
+     * Upload a photo or video to CoreViz.
+     * - Node.js: pass a local file path string
+     * - Browser: pass a File or Blob object
+     */
+    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>;
+}
+export interface TagsNamespace {
+    /** Aggregate all tag groups + values across a collection */
+    list(collectionId: string): Promise<Record<string, string[]>>;
 }
 export interface DescribeOptions {
 }
@@ -27,21 +164,32 @@ export interface EmbedOptions {
 export interface EmbedResponse {
     embedding: number[];
 }
-export interface BatchGenerateOptions {
+export interface GenerateOptions {
     referenceImages?: string[];
-    count?: number;
     aspectRatio?: '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' | '21:9';
-    model?: 'google/nano-banana' | 'google/nano-banana-pro';
+    model?: 'google/nano-banana' | 'google/nano-banana-pro' | 'seedream-4' | 'flux-kontext-max';
 }
 export declare class CoreViz {
     private apiKey?;
     private token?;
+    private _baseUrl;
+    private _orgIdCache;
+    collections: CollectionsNamespace;
+    media: MediaNamespace;
+    folders: FoldersNamespace;
+    tags: TagsNamespace;
     constructor(config?: CoreVizConfig);
     private getHeaders;
+    /** Resolve the current user's org ID (cached after first call) */
+    private _me;
+    /** GET request helper for management endpoints */
+    private _fetch;
+    /** Non-GET request helper for management endpoints */
+    private _fetchMethod;
     private handleResponse;
     describe(image: string, options?: DescribeOptions): Promise<string>;
     edit(image: string, options: EditOptions): Promise<string>;
-    batchGenerate(prompt: string, options?: BatchGenerateOptions): Promise<string[]>;
+    generate(prompt: string, options?: GenerateOptions): Promise<string>;
     tag(image: string, options: TagOptions): Promise<TagResponse>;
     private tagLocal;
     embed(input: string, options?: EmbedOptions): Promise<EmbedResponse>;

package/dist/coreviz.js

@@ -37,9 +37,154 @@ exports.CoreViz = void 0;
 const resize_1 = require("./resize");
 class CoreViz {
     constructor(config = {}) {
+        this._orgIdCache = null;
         this.apiKey = config.apiKey || (typeof process !== 'undefined' ? process.env.COREVIZ_API_KEY : undefined);
         this.token = config.token;
+        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`);
+                return Array.isArray(data) ? data : data.datasets ?? [];
+            },
+            create: async (name, icon) => {
+                const { organizationId } = await this._me();
+                const data = await this._fetchMethod('POST', `/api/organization/${organizationId}/datasets`, {
+                    name,
+                    ...(icon ? { icon } : {}),
+                });
+                return data.dataset;
+            },
+        };
+        this.media = {
+            browse: async (collectionId, options = {}) => {
+                const params = new URLSearchParams();
+                if (options.path)
+                    params.set('path', options.path);
+                if (options.limit != null)
+                    params.set('limit', String(options.limit));
+                if (options.offset != null)
+                    params.set('offset', String(options.offset));
+                if (options.type)
+                    params.set('type', options.type);
+                if (options.dateFrom)
+                    params.set('dateFrom', options.dateFrom);
+                if (options.dateTo)
+                    params.set('dateTo', options.dateTo);
+                if (options.sortBy)
+                    params.set('sortBy', options.sortBy);
+                if (options.sortDirection)
+                    params.set('sortDirection', options.sortDirection);
+                if (options.tagFilters)
+                    params.set('tagFilters', JSON.stringify(options.tagFilters));
+                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 });
+                if (options.limit != null)
+                    params.set('limit', String(options.limit));
+                const data = await this._fetch(`/api/search?${params.toString()}`);
+                return (data.results || []).map((r) => ({
+                    mediaId: r.media?.id,
+                    mediaName: r.media?.name,
+                    mediaType: r.media?.type,
+                    blobUrl: r.blob,
+                    objects: (r.objects || []).map((o) => ({ id: o.id, type: o.type, label: o.label })),
+                    rank: r.rank,
+                    caption: r.captions?.[0]?.text,
+                }));
+            },
+            get: async (mediaId) => {
+                const data = await this._fetch(`/api/media/${mediaId}`);
+                return data.media;
+            },
+            rename: async (mediaId, name) => {
+                const data = await this._fetchMethod('PATCH', `/api/media/${mediaId}`, { name });
+                return data.media;
+            },
+            move: async (mediaId, destinationPath) => {
+                return this._fetchMethod('PATCH', `/api/media/${mediaId}/move`, { destinationPath });
+            },
+            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 });
+            },
+            findSimilar: async (collectionId, objectId, options = {}) => {
+                const params = new URLSearchParams({ similarToObjectId: objectId });
+                if (options.limit != null)
+                    params.set('limit', String(options.limit));
+                if (options.model)
+                    params.set('similarToObjectModel', options.model);
+                return this._fetch(`/api/dataset/${collectionId}/media?${params.toString()}`);
+            },
+            upload: async (file, options) => {
+                const formData = new FormData();
+                formData.append('datasetId', options.collectionId);
+                if (options.path)
+                    formData.append('path', options.path);
+                if (typeof file === 'string') {
+                    // Node.js: treat as a file path — dynamic import fs to stay browser-compatible
+                    const fs = await Promise.resolve().then(() => __importStar(require('fs')));
+                    const path = await Promise.resolve().then(() => __importStar(require('path')));
+                    const buffer = fs.readFileSync(file);
+                    const ext = path.extname(file).slice(1).toLowerCase();
+                    const mimeTypes = {
+                        jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png',
+                        gif: 'image/gif', webp: 'image/webp', heic: 'image/heic',
+                        mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime',
+                    };
+                    const contentType = mimeTypes[ext] || 'application/octet-stream';
+                    const fileName = options.name || path.basename(file);
+                    const blob = new Blob([buffer], { type: contentType });
+                    formData.append('file', blob, fileName);
+                    if (!options.name)
+                        formData.append('name', fileName);
+                }
+                else {
+                    const fileName = options.name || (file instanceof File ? file.name : 'upload');
+                    formData.append('file', file, fileName);
+                    if (options.name)
+                        formData.append('name', options.name);
+                }
+                // Build headers without Content-Type (let fetch set the multipart boundary)
+                const authHeaders = {};
+                if (this.token) {
+                    authHeaders['Authorization'] = `Bearer ${this.token}`;
+                }
+                else {
+                    authHeaders['x-api-key'] = this.apiKey || '';
+                }
+                const response = await fetch(`${this._baseUrl}/api/upload/multipart`, {
+                    method: 'POST',
+                    headers: authHeaders,
+                    body: formData,
+                });
+                return this.handleResponse(response);
+            },
+        };
+        this.folders = {
+            create: async (collectionId, name, path) => {
+                const data = await this._fetchMethod('POST', '/api/folder', {
+                    datasetId: collectionId,
+                    name,
+                    ...(path ? { path } : {}),
+                });
+                return data.folder;
+            },
+        };
+        this.tags = {
+            list: async (collectionId) => {
+                const data = await this._fetch(`/api/dataset/${collectionId}/tags`);
+                return data.tags;
+            },
+        };
     }
+    // ── Private helpers ──────────────────────────────────────────────────────
     getHeaders() {
         const headers = {
             'Content-Type': 'application/json',
@@ -52,6 +197,32 @@ class CoreViz {
         }
         return headers;
     }
+    /** Resolve the current user's org ID (cached after first call) */
+    async _me() {
+        const data = await this._fetch('/api/me');
+        if (!this._orgIdCache)
+            this._orgIdCache = data.organizationId;
+        return data;
+    }
+    /** GET request helper for management endpoints */
+    async _fetch(path) {
+        const response = await fetch(`${this._baseUrl}${path}`, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        return this.handleResponse(response);
+    }
+    /** Non-GET request helper for management endpoints */
+    async _fetchMethod(method, path, body) {
+        const response = await fetch(`${this._baseUrl}${path}`, {
+            method,
+            headers: this.getHeaders(),
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (response.status === 204)
+            return undefined;
+        return this.handleResponse(response);
+    }
     async handleResponse(response) {
         if (response.status === 402) {
             throw new Error('Insufficient credits');
@@ -103,26 +274,25 @@ class CoreViz {
             throw err instanceof Error ? err : new Error("An unexpected error occurred.");
         }
     }
-    async batchGenerate(prompt, options = {}) {
+    async generate(prompt, options = {}) {
         try {
             const headers = this.getHeaders();
             let resizedImages = [];
             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/batch-generate`, {
+            const response = await fetch(`https://lab.coreviz.io/api/ai/generate`, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify({
                     prompt,
                     image: resizedImages.length > 0 ? resizedImages : undefined,
-                    count: options.count || 1,
                     aspectRatio: options.aspectRatio,
                     model: options.model || 'google/nano-banana-pro',
                 }),
             });
             const data = await this.handleResponse(response);
-            return data.results || [];
+            return data.result;
         }
         catch (err) {
             throw err instanceof Error ? err : new Error("An unexpected error occurred.");

package/dist/coreviz.native.d.ts

@@ -1,6 +1,123 @@
 export interface CoreVizConfig {
     apiKey?: string;
     token?: string;
+    /** Override the API base URL (default: https://lab.coreviz.io) */
+    baseUrl?: string;
+}
+export interface UserContext {
+    userId: string;
+    email: string;
+    name: string;
+    organizationId: string;
+    organizationName: string | null;
+}
+export interface Collection {
+    id: string;
+    name: string;
+    icon?: string;
+    type: string;
+    organizationId: string;
+}
+export interface MediaObject {
+    id: string;
+    type: string;
+    label: string;
+}
+export interface MediaFrame {
+    id: string;
+    timestamp: number;
+    blob: string;
+    objects: MediaObject[];
+}
+export interface Media {
+    id: string;
+    name: string;
+    type: 'image' | 'video' | 'folder';
+    blob: string | null;
+    path: string;
+    width?: number;
+    height?: number;
+    sizeBytes?: number;
+    metadata?: Record<string, unknown>;
+    frames?: MediaFrame[];
+    createdAt?: string;
+    _score?: number;
+}
+export interface Folder {
+    id: string;
+    name: string;
+    path: string;
+    datasetId: string;
+}
+export interface BrowseOptions {
+    path?: string;
+    limit?: number;
+    offset?: number;
+    type?: 'image' | 'video' | 'folder' | 'all';
+    dateFrom?: string;
+    dateTo?: string;
+    sortBy?: string;
+    sortDirection?: 'asc' | 'desc';
+    tagFilters?: Record<string, string[]>;
+}
+export interface BrowseResult {
+    media: Media[];
+    pagination: {
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
+}
+export interface SearchResult {
+    mediaId: string;
+    mediaName: string;
+    mediaType: string;
+    blobUrl: string;
+    objects: MediaObject[];
+    rank: number;
+    caption?: string;
+}
+export interface SearchOptions {
+    limit?: number;
+}
+export interface SimilarityOptions {
+    limit?: number;
+    model?: string;
+}
+export interface UploadOptions {
+    collectionId: string;
+    path?: string;
+    name?: string;
+}
+export interface UploadResult {
+    mediaId: string;
+    url: string;
+    message: string;
+}
+export interface CollectionsNamespace {
+    list(): Promise<Collection[]>;
+    create(name: string, icon?: string): Promise<Collection>;
+}
+export interface MediaNamespace {
+    browse(collectionId: string, options?: BrowseOptions): Promise<BrowseResult>;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    get(mediaId: string): Promise<Media>;
+    rename(mediaId: string, name: string): Promise<Media>;
+    move(mediaId: string, destinationPath: string): Promise<{
+        id: string;
+        newPath: string;
+    }>;
+    addTag(mediaId: string, label: string, value: string): Promise<void>;
+    removeTag(mediaId: string, label: string, value: string): Promise<void>;
+    findSimilar(collectionId: string, objectId: string, options?: SimilarityOptions): Promise<BrowseResult>;
+    upload(file: string | File | Blob, options: UploadOptions): Promise<UploadResult>;
+}
+export interface FoldersNamespace {
+    create(collectionId: string, name: string, path?: string): Promise<Folder>;
+}
+export interface TagsNamespace {
+    list(collectionId: string): Promise<Record<string, string[]>>;
 }
 export interface DescribeOptions {
 }
@@ -27,21 +144,29 @@ export interface EmbedOptions {
 export interface EmbedResponse {
     embedding: number[];
 }
-export interface BatchGenerateOptions {
+export interface GenerateOptions {
     referenceImages?: string[];
-    count?: number;
     aspectRatio?: '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' | '21:9';
-    model?: 'google/nano-banana' | 'google/nano-banana-pro';
+    model?: 'google/nano-banana' | 'google/nano-banana-pro' | 'seedream-4' | 'flux-kontext-max';
 }
 export declare class CoreViz {
     private apiKey?;
     private token?;
+    private _baseUrl;
+    private _orgIdCache;
+    collections: CollectionsNamespace;
+    media: MediaNamespace;
+    folders: FoldersNamespace;
+    tags: TagsNamespace;
     constructor(config?: CoreVizConfig);
     private getHeaders;
+    private _me;
+    private _fetch;
+    private _fetchMethod;
     private handleResponse;
     describe(image: string, _options?: DescribeOptions): Promise<string>;
     edit(image: string, options: EditOptions): Promise<string>;
-    batchGenerate(prompt: string, options?: BatchGenerateOptions): Promise<string[]>;
+    generate(prompt: string, options?: GenerateOptions): Promise<string>;
     tag(image: string, options: TagOptions): Promise<TagResponse>;
     embed(input: string, options?: EmbedOptions): Promise<EmbedResponse>;
     resize(input: string | File, maxWidth?: number, maxHeight?: number): Promise<string>;

package/dist/coreviz.native.js

@@ -4,9 +4,125 @@ exports.CoreViz = void 0;
 const resize_native_1 = require("./resize.native");
 class CoreViz {
     constructor(config = {}) {
+        this._orgIdCache = null;
         // React Native / Expo doesn't provide `process.env` in the same way; keep config explicit.
         this.apiKey = config.apiKey;
         this.token = config.token;
+        this._baseUrl = config.baseUrl || 'https://lab.coreviz.io';
+        this.collections = {
+            list: async () => {
+                const { organizationId } = await this._me();
+                const data = await this._fetch(`/api/organization/${organizationId}/datasets`);
+                return Array.isArray(data) ? data : data.datasets ?? [];
+            },
+            create: async (name, icon) => {
+                const { organizationId } = await this._me();
+                const data = await this._fetchMethod('POST', `/api/organization/${organizationId}/datasets`, { name, icon });
+                return data.dataset;
+            },
+        };
+        this.media = {
+            browse: async (collectionId, options = {}) => {
+                const params = new URLSearchParams();
+                if (options.path)
+                    params.set('path', options.path);
+                if (options.limit != null)
+                    params.set('limit', String(options.limit));
+                if (options.offset != null)
+                    params.set('offset', String(options.offset));
+                if (options.type)
+                    params.set('type', options.type);
+                if (options.dateFrom)
+                    params.set('dateFrom', options.dateFrom);
+                if (options.dateTo)
+                    params.set('dateTo', options.dateTo);
+                if (options.sortBy)
+                    params.set('sortBy', options.sortBy);
+                if (options.sortDirection)
+                    params.set('sortDirection', options.sortDirection);
+                if (options.tagFilters)
+                    params.set('tagFilters', JSON.stringify(options.tagFilters));
+                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 });
+                if (options.limit != null)
+                    params.set('limit', String(options.limit));
+                const data = await this._fetch(`/api/search?${params.toString()}`);
+                return (data.results || []).map((r) => ({
+                    mediaId: r.media?.id, mediaName: r.media?.name, mediaType: r.media?.type,
+                    blobUrl: r.blob, objects: (r.objects || []).map((o) => ({ id: o.id, type: o.type, label: o.label })),
+                    rank: r.rank, caption: r.captions?.[0]?.text,
+                }));
+            },
+            get: async (mediaId) => {
+                const data = await this._fetch(`/api/media/${mediaId}`);
+                return data.media;
+            },
+            rename: async (mediaId, name) => {
+                const data = await this._fetchMethod('PATCH', `/api/media/${mediaId}`, { name });
+                return data.media;
+            },
+            move: async (mediaId, destinationPath) => {
+                return this._fetchMethod('PATCH', `/api/media/${mediaId}/move`, { destinationPath });
+            },
+            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 });
+            },
+            findSimilar: async (collectionId, objectId, options = {}) => {
+                const params = new URLSearchParams({ similarToObjectId: objectId });
+                if (options.limit != null)
+                    params.set('limit', String(options.limit));
+                if (options.model)
+                    params.set('similarToObjectModel', options.model);
+                return this._fetch(`/api/dataset/${collectionId}/media?${params.toString()}`);
+            },
+            upload: async (file, options) => {
+                if (typeof file === 'string') {
+                    throw new Error('File path strings are not supported on React Native. Pass a File or Blob object instead.');
+                }
+                const formData = new FormData();
+                formData.append('datasetId', options.collectionId);
+                if (options.path)
+                    formData.append('path', options.path);
+                const fileName = options.name || (file instanceof File ? file.name : 'upload');
+                formData.append('file', file, fileName);
+                if (options.name)
+                    formData.append('name', options.name);
+                const authHeaders = {};
+                if (this.token) {
+                    authHeaders['Authorization'] = `Bearer ${this.token}`;
+                }
+                else {
+                    authHeaders['x-api-key'] = this.apiKey || '';
+                }
+                const response = await fetch(`${this._baseUrl}/api/upload/multipart`, {
+                    method: 'POST',
+                    headers: authHeaders,
+                    body: formData,
+                });
+                return this.handleResponse(response);
+            },
+        };
+        this.folders = {
+            create: async (collectionId, name, path) => {
+                const data = await this._fetchMethod('POST', '/api/folder', {
+                    datasetId: collectionId, name, ...(path ? { path } : {}),
+                });
+                return data.folder;
+            },
+        };
+        this.tags = {
+            list: async (collectionId) => {
+                const data = await this._fetch(`/api/dataset/${collectionId}/tags`);
+                return data.tags;
+            },
+        };
     }
     getHeaders() {
         const headers = {
@@ -20,6 +136,29 @@ class CoreViz {
         }
         return headers;
     }
+    async _me() {
+        const data = await this._fetch('/api/me');
+        if (!this._orgIdCache)
+            this._orgIdCache = data.organizationId;
+        return data;
+    }
+    async _fetch(path) {
+        const response = await fetch(`${this._baseUrl}${path}`, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        return this.handleResponse(response);
+    }
+    async _fetchMethod(method, path, body) {
+        const response = await fetch(`${this._baseUrl}${path}`, {
+            method,
+            headers: this.getHeaders(),
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (response.status === 204)
+            return undefined;
+        return this.handleResponse(response);
+    }
     async handleResponse(response) {
         if (response.status === 402) {
             throw new Error('Insufficient credits');
@@ -61,25 +200,24 @@ class CoreViz {
         const data = await this.handleResponse(response);
         return data.result;
     }
-    async batchGenerate(prompt, options = {}) {
+    async generate(prompt, options = {}) {
         const headers = this.getHeaders();
         let resizedImages = [];
         if (options.referenceImages && options.referenceImages.length > 0) {
             resizedImages = await Promise.all(options.referenceImages.map((img) => (0, resize_native_1.resize)(img, 1024, 1024)));
         }
-        const response = await fetch(`https://lab.coreviz.io/api/ai/batch-generate`, {
+        const response = await fetch(`https://lab.coreviz.io/api/ai/generate`, {
             method: 'POST',
             headers,
             body: JSON.stringify({
                 prompt,
                 image: resizedImages.length > 0 ? resizedImages : undefined,
-                count: options.count || 1,
                 aspectRatio: options.aspectRatio,
                 model: options.model || 'google/nano-banana-pro',
             }),
         });
         const data = await this.handleResponse(response);
-        return data.results || [];
+        return data.result;
     }
     async tag(image, options) {
         const mode = options?.mode || 'api';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CoreViz, CoreVizConfig, DescribeOptions, EditOptions, TagOptions, TagResponse, EmbedOptions, EmbedResponse } 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 } from './coreviz';
 import { resize } from './resize';
 export { CoreViz, resize };
-export type { CoreVizConfig, DescribeOptions, EditOptions, TagOptions, TagResponse, EmbedOptions, EmbedResponse };
+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 };

package/dist/index.native.d.ts

@@ -1,4 +1,4 @@
-import { CoreViz, CoreVizConfig, DescribeOptions, EditOptions, TagOptions, TagResponse, EmbedOptions, EmbedResponse } from './coreviz.native';
+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.native';
 import { resize } from './resize.native';
 export { CoreViz, resize };
-export type { CoreVizConfig, DescribeOptions, EditOptions, TagOptions, TagResponse, EmbedOptions, EmbedResponse };
+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 };

package/package.json

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