@calmlens/js-sdk 0.0.0 → 0.0.1

package/README.md

@@ -1,37 +1,205 @@
-# [api-def](https://github.com/Censkh/api-def/) · [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Censkh/api-def/blob/master/LICENSE) [![npm version](https://img.shields.io/npm/v/api-def.svg?style=flat)](https://www.npmjs.com/package/api-def) [![build status](https://img.shields.io/github/actions/workflow/status/censkh/api-def/workflow.yml)](https://github.com/Censkh/api-def/actions)
+# @calmlens/js-sdk
 
-Typed APIs with middleware support
+Official JavaScript/TypeScript SDK for CalmLens API
 
-API def provides a unified way to type your endpoints allowing for compile time checking of query, body, response and even url parameters
+CalmLens provides content moderation and classification services for images, videos, audio, documents, and websites. This SDK makes it easy to integrate CalmLens into your JavaScript/TypeScript applications.
+
+## Installation
 
 ```bash
-npm i api-def
+npm install @calmlens/js-sdk
 ```
 
-- [Documentation](https://censkh.github.io/api-def/)
+## Quick Start
 
 ```typescript
-import { Api } from "api-def";
+import CalmLensClient from "@calmlens/js-sdk";
 
-const api = new Api({
-  baseUrl: "https://my-api/",
-  name: "My API",
+const client = new CalmLensClient({
+  apiKey: "your-api-key",
+  projectId: "your-project-id",
 });
 
-const fetchData = api
-  .endpoint()
-  .queryOf<{ includeAwesome: boolean }>()
-  .responseOf<{ data: { awesome: boolean } }>()
-  .build({
-    id: "fetch_data",
-    method: "get",
-    path: "/data",
-  });
+// Submit an asset for processing
+const asset = await client.submitAsset({
+  name: "my-image.jpg",
+  file: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...", // base64 encoded file
+  fileType: "image/jpeg",
+  description: "User uploaded image",
+  visibility: "private"
+});
+
+console.log(asset.id); // Asset ID for future reference
+console.log(asset.status); // "pending", "approved", "rejected", or "error"
+```
+
+## API Reference
+
+### CalmLensClient
+
+The main client class for interacting with the CalmLens API.
+
+#### Constructor
+
+```typescript
+new CalmLensClient(options: CalmLensClientOptions)
+```
+
+**Options:**
+- `apiKey` (string, required): Your CalmLens API key
+- `projectId` (string, required): Your CalmLens project ID
+- `baseUrl` (string, optional): API base URL (defaults to "https://api.calmlens.com")
+
+#### Methods
+
+##### submitAsset(options)
+
+Submit an asset for processing and classification.
+
+```typescript
+async submitAsset(options: SubmitAssetOptions): Promise<Asset>
+```
+
+**Options:**
+- `name` (string, required): Name of the asset
+- `file` (string, optional): Base64 encoded file content or data URL
+- `fileType` (string, optional): MIME type or file extension (required if using `file`)
+- `url` (string, optional): External URL to the asset (alternative to `file`)
+- `description` (string, optional): Description of the asset
+- `keepAfterProcessing` (boolean, optional): Whether to keep the asset after processing
+- `visibility` (string, optional): "public" or "private"
+
+**Example:**
+```typescript
+// Submit from file content
+const asset = await client.submitAsset({
+  name: "document.pdf",
+  file: "data:application/pdf;base64,JVBERi0xLjQKJcfs...",
+  fileType: "application/pdf",
+  description: "Important document",
+  visibility: "private"
+});
+
+// Submit from URL
+const asset = await client.submitAsset({
+  name: "website-content",
+  url: "https://example.com/page",
+  description: "Web page to analyze"
+});
+```
+
+##### getAsset(assetId)
+
+Retrieve details of a specific asset.
+
+```typescript
+async getAsset(assetId: string): Promise<Asset>
+```
+
+**Example:**
+```typescript
+const asset = await client.getAsset("asset-uuid-here");
+console.log(asset.status);
+console.log(asset.report); // Classification results
+```
+
+##### listAssets(options)
+
+List assets in your project with pagination.
 
-// calls GET https://my-api/data?includeAwesome=true
-const res = await fetchData.submit({
-  query: { includeAwesome: true },
+```typescript
+async listAssets(options?: {
+  pageIndex?: number;
+  pageSize?: number;
+}): Promise<{
+  items: Asset[];
+  total: number;
+  pageIndex: number;
+  pageSize: number;
+}>
+```
+
+**Example:**
+```typescript
+const result = await client.listAssets({
+  pageIndex: 0,
+  pageSize: 20
 });
 
-console.log(res.data); // { data: { awesome: true } }
+console.log(`Found ${result.total} assets`);
+result.items.forEach(asset => {
+  console.log(`${asset.name}: ${asset.status}`);
+});
 ```
+
+#### Static Methods
+
+##### verifyWebhookSignature(payload, signature, secret)
+
+Verify webhook signatures to ensure authenticity.
+
+```typescript
+static async verifyWebhookSignature(
+  payload: string | object,
+  signatureHex: string,
+  secret: string
+): Promise<boolean>
+```
+
+**Example:**
+```typescript
+// In your webhook handler
+const signature = req.headers['x-calmlens-signature'];
+const payload = req.body;
+const isValid = await CalmLensClient.verifyWebhookSignature(
+  payload, 
+  signature, 
+  WEBHOOK_SECRET
+);
+
+if (!isValid) {
+  return res.status(401).send('Unauthorized');
+}
+```
+
+## Asset Types
+
+Assets can be of the following types:
+- `image` - Images (JPEG, PNG, GIF, WebP, etc.)
+- `video` - Video files (MP4, WebM, etc.)
+- `audio` - Audio files (MP3, WAV, etc.)
+- `document` - Documents (PDF, DOC, TXT, etc.)
+- `website` - Web pages and URLs
+
+## Asset Status
+
+Assets progress through these statuses:
+- `pending` - Asset is being processed
+- `approved` - Asset passed moderation
+- `rejected` - Asset failed moderation
+- `error` - Processing failed
+
+## Asset Visibility
+
+- `public` - Asset is publicly accessible
+- `private` - Asset is only accessible to your project
+
+## Error Handling
+
+The SDK throws errors for common issues:
+
+```typescript
+try {
+  const asset = await client.submitAsset({
+    name: "test.jpg"
+    // Missing required file or url
+  });
+} catch (error) {
+  console.error(error.message); // "Either file content or URL is required"
+}
+```
+
+## Webhooks
+
+CalmLens can send webhooks when asset processing is complete. Use `verifyWebhookSignature` to verify the authenticity of incoming webhooks.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmlens/js-sdk",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "main": "cjs/index.js",
   "types": "esm/index.d.ts",
   "module": "esm/index.js",