@coreviz/sdk 1.0.0 → 1.0.3

package/README.md

@@ -1,6 +1,6 @@
 # @coreviz/sdk
 
-CoreViz SDK - A JavaScript/Node.js interface for CoreViz's Vision AI APIs.
+The official JavaScript/TypeScript SDK for CoreViz's Vision AI APIs. Easily integrate powerful image analysis and manipulation features into your applications.
 
 ## Installation
 
@@ -8,17 +8,107 @@ CoreViz SDK - A JavaScript/Node.js interface for CoreViz's Vision AI APIs.
 npm install @coreviz/sdk
 ```
 
-## Usage
+## Configuration
 
-```js
-const coreviz = require('@coreviz/sdk');
-coreviz();
+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'
+});
 ```
 
-## Development
+## API Reference
+
+### `coreviz.describe(image)`
+
+Generates a detailed text description of an image.
 
-This is currently a placeholder package. The actual API functionality will be implemented soon.
+**Parameters:**
+- `image` (string): The image to describe. Can be a base64 string or a URL.
+
+**Returns:**
+- `Promise<string>`: A text description of the image.
+
+**Example:**
+
+```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.
+
+**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.
+
+**Example:**
+
+```typescript
+const result = await coreviz.tag('base64_image_string...', {
+  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.
+
+**Parameters:**
+- `image` (string): The image to edit. Can be a base64 string or a URL.
+- `options` (object):
+  - `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.
+
+**Example:**
+
+```typescript
+const editedImage = await coreviz.edit('https://example.com/photo.jpg', {
+  prompt: "Make it look like a painting",
+  aspectRatio: "1:1"
+});
+```
+
+### `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).
+
+**Returns:**
+- `Promise<string>`: The resized image as a base64 string.
+
+**Example:**
+
+```typescript
+const resized = await coreviz.resize(myFileObject, 800, 600);
+// or import { resize } from '@coreviz/sdk';
+```
 
 ## License
 
-MIT 
+MIT

package/dist/coreviz.d.ts

@@ -0,0 +1,39 @@
+export interface CoreVizConfig {
+    apiKey?: string;
+    token?: string;
+}
+export interface DescribeOptions {
+}
+export interface EditOptions {
+    prompt: string;
+    aspectRatio?: 'match_input_image' | '1:1' | '16:9' | '9:16' | '4:3' | '3:4';
+    outputFormat?: 'jpg' | 'png';
+    model?: 'flux-kontext-max' | 'google/nano-banana' | 'seedream-4';
+}
+export interface TagOptions {
+    prompt: string;
+    options?: string[];
+    multiple?: boolean;
+}
+export interface TagResponse {
+    tags: string[];
+    raw?: unknown;
+}
+export interface EmbedOptions {
+    type?: 'image' | 'text';
+}
+export interface EmbedResponse {
+    embedding: number[];
+}
+export declare class CoreViz {
+    private apiKey?;
+    private token?;
+    constructor(config?: CoreVizConfig);
+    private getHeaders;
+    private handleResponse;
+    describe(image: string, options?: DescribeOptions): Promise<string>;
+    edit(image: string, options: EditOptions): 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.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoreViz = void 0;
+const resize_1 = require("./resize");
+class CoreViz {
+    constructor(config = {}) {
+        this.apiKey = config.apiKey || (typeof process !== 'undefined' ? process.env.COREVIZ_API_KEY : undefined);
+        this.token = config.token;
+    }
+    getHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.token) {
+            headers['Authorization'] = `Bearer ${this.token}`;
+        }
+        else {
+            headers['x-api-key'] = this.apiKey || "";
+        }
+        return headers;
+    }
+    async handleResponse(response) {
+        if (response.status === 402) {
+            throw new Error('Insufficient credits');
+        }
+        if (!response.ok) {
+            throw new Error(`Request failed (${response.status})`);
+        }
+        const data = await response.json();
+        if (data.error) {
+            throw new Error(data.error);
+        }
+        return data;
+    }
+    async describe(image, options) {
+        try {
+            const resizedImage = await (0, resize_1.resize)(image);
+            const headers = this.getHeaders();
+            const response = await fetch(`https://lab.coreviz.io/api/ai/describe`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ image: resizedImage }),
+            });
+            const data = await this.handleResponse(response);
+            return data.description;
+        }
+        catch (err) {
+            throw err instanceof Error ? err : new Error("An unexpected error occurred.");
+        }
+    }
+    async edit(image, options) {
+        try {
+            const resizedImage = await (0, resize_1.resize)(image);
+            const headers = this.getHeaders();
+            const response = await fetch(`https://lab.coreviz.io/api/ai/edit`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    image: resizedImage,
+                    prompt: options.prompt,
+                    aspectRatio: options.aspectRatio || 'match_input_image',
+                    outputFormat: options.outputFormat || 'jpg',
+                    model: options.model || 'flux-kontext-max',
+                }),
+            });
+            const data = await this.handleResponse(response);
+            return data.result;
+        }
+        catch (err) {
+            throw err instanceof Error ? err : new Error("An unexpected error occurred.");
+        }
+    }
+    async tag(image, options) {
+        try {
+            const resizedImage = await (0, resize_1.resize)(image);
+            const headers = this.getHeaders();
+            const response = await fetch("https://lab.coreviz.io/api/ai/tag", {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    image: resizedImage,
+                    prompt: options.prompt,
+                    options: options.options && options.options.length > 0 ? options.options : undefined,
+                    multiple: options.multiple ?? true,
+                }),
+            });
+            const data = await this.handleResponse(response);
+            const tags = Array.isArray(data.tags)
+                ? data.tags
+                : Array.isArray(data.result)
+                    ? data.result
+                    : typeof data.tag === 'string'
+                        ? [data.tag]
+                        : [];
+            return {
+                tags,
+                raw: data,
+            };
+        }
+        catch (err) {
+            throw err instanceof Error ? err : new Error("An unexpected error occurred.");
+        }
+    }
+    async embed(input, options) {
+        try {
+            const headers = this.getHeaders();
+            let body = {};
+            // Determine type
+            let isImage = false;
+            if (options?.type) {
+                isImage = options.type === 'image';
+            }
+            else {
+                // Heuristic: Check if input starts with data:image or http
+                // Assuming http/https implies image URL in this context unless specified otherwise
+                isImage = input.startsWith('data:image') || input.startsWith('http://') || input.startsWith('https://');
+            }
+            if (isImage) {
+                const resizedImage = await (0, resize_1.resize)(input);
+                body.image = resizedImage;
+            }
+            else {
+                body.text = input;
+            }
+            const response = await fetch("https://lab.coreviz.io/api/ai/embed", {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+            });
+            const data = await this.handleResponse(response);
+            return data;
+        }
+        catch (err) {
+            throw err instanceof Error ? err : new Error("An unexpected error occurred.");
+        }
+    }
+    async resize(input, maxWidth, maxHeight) {
+        return (0, resize_1.resize)(input, maxWidth, maxHeight);
+    }
+}
+exports.CoreViz = CoreViz;

package/dist/describe.d.ts

@@ -1 +1,5 @@
-export declare function describe(image: string): Promise<string | undefined>;
+export interface DescribeOptions {
+    token?: string;
+    apiKey?: string;
+}
+export declare function describe(image: string, options?: DescribeOptions): Promise<string | undefined>;

package/dist/describe.js

@@ -2,17 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.describe = describe;
 const resize_1 = require("./resize");
-async function describe(image) {
+async function describe(image, options) {
     try {
         const resizedImage = await (0, resize_1.resize)(image);
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (options?.token) {
+            headers['Authorization'] = `Bearer ${options.token}`;
+        }
+        else {
+            headers['x-api-key'] = options?.apiKey || process.env.COREVIZ_API_KEY || "";
+        }
         const response = await fetch(`https://lab.coreviz.io/api/ai/describe`, {
             method: 'POST',
-            headers: {
-                'x-api-key': process.env.COREVIZ_API_KEY || "",
-                'Content-Type': 'application/json',
-            },
+            headers,
             body: JSON.stringify({ image: resizedImage }),
         });
+        if (response.status === 402) {
+            throw new Error('Insufficient credits');
+        }
         if (!response.ok) {
             throw new Error(`Failed to describe image (${response.status})`);
         }
@@ -23,7 +32,6 @@ async function describe(image) {
         return data.description;
     }
     catch (err) {
-        console.error('Error in describeImage:', err);
         throw err instanceof Error ? err : new Error("An unexpected error occurred.");
     }
 }

package/dist/edit.d.ts

@@ -3,5 +3,7 @@ export interface EditOptions {
     aspectRatio?: 'match_input_image' | '1:1' | '16:9' | '9:16' | '4:3' | '3:4';
     outputFormat?: 'jpg' | 'png';
     model?: 'flux-kontext-max' | 'google/nano-banana' | 'seedream-4';
+    token?: string;
+    apiKey?: string;
 }
 export declare function edit(image: string, options: EditOptions): Promise<string | undefined>;

package/dist/edit.js

@@ -5,12 +5,18 @@ const resize_1 = require("./resize");
 async function edit(image, options) {
     try {
         const resizedImage = await (0, resize_1.resize)(image);
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (options.token) {
+            headers['Authorization'] = `Bearer ${options.token}`;
+        }
+        else {
+            headers['x-api-key'] = options.apiKey || process.env.COREVIZ_API_KEY || "";
+        }
         const response = await fetch(`https://lab.coreviz.io/api/ai/edit`, {
             method: 'POST',
-            headers: {
-                'x-api-key': process.env.COREVIZ_API_KEY || "",
-                'Content-Type': 'application/json',
-            },
+            headers,
             body: JSON.stringify({
                 image: resizedImage,
                 prompt: options.prompt,
@@ -19,6 +25,9 @@ async function edit(image, options) {
                 model: options.model || 'flux-kontext-max',
             }),
         });
+        if (response.status === 402) {
+            throw new Error('Insufficient credits');
+        }
         if (!response.ok) {
             throw new Error(`Failed to edit image (${response.status})`);
         }
@@ -29,7 +38,6 @@ async function edit(image, options) {
         return data.result;
     }
     catch (err) {
-        console.error('Error in editImage:', err);
         throw err instanceof Error ? err : new Error("An unexpected error occurred.");
     }
 }

package/dist/index.d.ts

@@ -1,6 +1,4 @@
-import { describe } from './describe';
+import { CoreViz, CoreVizConfig, DescribeOptions, EditOptions, TagOptions, TagResponse, EmbedOptions, EmbedResponse } from './coreviz';
 import { resize } from './resize';
-import { edit, EditOptions } from './edit';
-import { tag, TagOptions, TagResponse } from './tag';
-export { describe, resize, edit, tag };
-export type { EditOptions, TagOptions, TagResponse };
+export { CoreViz, resize };
+export type { CoreVizConfig, DescribeOptions, EditOptions, TagOptions, TagResponse, EmbedOptions, EmbedResponse };

package/dist/index.js

@@ -1,11 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.tag = exports.edit = exports.resize = exports.describe = void 0;
-const describe_1 = require("./describe");
-Object.defineProperty(exports, "describe", { enumerable: true, get: function () { return describe_1.describe; } });
+exports.resize = exports.CoreViz = void 0;
+const coreviz_1 = require("./coreviz");
+Object.defineProperty(exports, "CoreViz", { enumerable: true, get: function () { return coreviz_1.CoreViz; } });
 const resize_1 = require("./resize");
 Object.defineProperty(exports, "resize", { enumerable: true, get: function () { return resize_1.resize; } });
-const edit_1 = require("./edit");
-Object.defineProperty(exports, "edit", { enumerable: true, get: function () { return edit_1.edit; } });
-const tag_1 = require("./tag");
-Object.defineProperty(exports, "tag", { enumerable: true, get: function () { return tag_1.tag; } });

package/dist/tag.d.ts

@@ -2,6 +2,8 @@ export interface TagOptions {
     prompt: string;
     options?: string[];
     multiple?: boolean;
+    token?: string;
+    apiKey?: string;
 }
 export interface TagResponse {
     tags: string[];

package/dist/tag.js

@@ -5,12 +5,18 @@ const resize_1 = require("./resize");
 async function tag(image, options) {
     try {
         const resizedImage = await (0, resize_1.resize)(image);
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (options.token) {
+            headers['Authorization'] = `Bearer ${options.token}`;
+        }
+        else {
+            headers['x-api-key'] = options.apiKey || process.env.COREVIZ_API_KEY || "";
+        }
         const response = await fetch("https://lab.coreviz.io/api/ai/tag", {
             method: 'POST',
-            headers: {
-                'x-api-key': process.env.COREVIZ_API_KEY || "",
-                'Content-Type': 'application/json',
-            },
+            headers,
             body: JSON.stringify({
                 image: resizedImage,
                 prompt: options.prompt,
@@ -18,6 +24,9 @@ async function tag(image, options) {
                 multiple: options.multiple ?? true,
             }),
         });
+        if (response.status === 402) {
+            throw new Error('Insufficient credits');
+        }
         if (!response.ok) {
             throw new Error(`Failed to tag image (${response.status})`);
         }
@@ -38,7 +47,6 @@ async function tag(image, options) {
         };
     }
     catch (err) {
-        console.error('Error in tagImage:', err);
         throw err instanceof Error ? err : new Error("An unexpected error occurred.");
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coreviz/sdk",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "CoreViz SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,4 +34,4 @@
   "dependencies": {
     "sharp": "^0.34.5"
   }
-}
+}