@coreviz/sdk 1.0.19 → 1.1.0

package/README.md

@@ -221,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 {
 }
@@ -35,8 +172,20 @@ export interface GenerateOptions {
 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>;

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');

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 {
 }
@@ -35,8 +152,17 @@ export interface GenerateOptions {
 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>;

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');

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.19",
+  "version": "1.1.0",
   "description": "CoreViz SDK",
   "main": "dist/index.js",
   "react-native": "dist/index.native.js",