@calmlens/js-sdk 0.0.0 → 0.0.2

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/cjs/ApiKey.d.ts

@@ -0,0 +1,31 @@
+import * as zod from "zod/v4";
+export declare const API_KEY_STATUS_SCHEMA: zod.ZodEnum<{
+    active: "active";
+    revoked: "revoked";
+    expired: "expired";
+}>;
+export type ApiKeyStatus = zod.infer<typeof API_KEY_STATUS_SCHEMA>;
+export declare const API_KEY_SCHEMA: zod.ZodObject<{
+    id: zod.ZodString;
+    projectId: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+    userId: zod.ZodOptional<zod.ZodNullable<zod.ZodPipe<zod.ZodString, zod.ZodTransform<string, string>>>>;
+    createdAt: zod.ZodNumber;
+    updatedAt: zod.ZodOptional<zod.ZodNumber>;
+    name: zod.ZodPipe<zod.ZodString, zod.ZodTransform<string, string>>;
+    description: zod.ZodOptional<zod.ZodNullable<zod.ZodPipe<zod.ZodString, zod.ZodTransform<string, string>>>>;
+    keyHash: zod.ZodPipe<zod.ZodString, zod.ZodTransform<string, string>>;
+    keyPrefix: zod.ZodPipe<zod.ZodString, zod.ZodTransform<string, string>>;
+    roles: zod.ZodOptional<zod.ZodNullable<zod.ZodArray<zod.ZodEnum<{
+        "system:super-admin": "system:super-admin";
+        "system:banned": "system:banned";
+        "assets:view-all": "assets:view-all";
+    }>>>>;
+    status: zod.ZodEnum<{
+        active: "active";
+        revoked: "revoked";
+        expired: "expired";
+    }>;
+    expiresAt: zod.ZodOptional<zod.ZodNullable<zod.ZodNumber>>;
+    lastUsedAt: zod.ZodOptional<zod.ZodNullable<zod.ZodNumber>>;
+}, zod.z.core.$strip>;
+export type ApiKey = zod.infer<typeof API_KEY_SCHEMA>;

package/cjs/ApiKey.js

@@ -0,0 +1,59 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API_KEY_SCHEMA = exports.API_KEY_STATUS_SCHEMA = void 0;
+var zod = __importStar(require("zod/v4"));
+var Roles_1 = require("./Roles");
+var ZodUtils_1 = require("./ZodUtils");
+exports.API_KEY_STATUS_SCHEMA = zod.enum(["active", "revoked", "expired"]);
+exports.API_KEY_SCHEMA = zod.object({
+    id: (0, ZodUtils_1.primaryUuidField)(),
+    projectId: (0, ZodUtils_1.uuidField)().nullish(),
+    userId: (0, ZodUtils_1.saneStringField)().nullish(),
+    createdAt: (0, ZodUtils_1.createdAtField)(),
+    updatedAt: (0, ZodUtils_1.updatedAtField)(),
+    name: (0, ZodUtils_1.saneStringField)({
+        type: "medium",
+    }),
+    description: (0, ZodUtils_1.saneStringField)({
+        type: "large",
+    }).nullish(),
+    keyHash: (0, ZodUtils_1.saneStringField)(), // Store hashed version of the key for security
+    keyPrefix: (0, ZodUtils_1.saneStringField)(), // Store first few characters for identification
+    roles: zod.array(Roles_1.ROLE_SCHEMA).nullish(),
+    status: exports.API_KEY_STATUS_SCHEMA,
+    expiresAt: zod.number().nullish(), // Unix timestamp
+    lastUsedAt: zod.number().nullish(), // Unix timestamp
+});

package/cjs/Asset.d.ts

@@ -7,18 +7,56 @@ export declare const ASSET_STATUS_SCHEMA: zod.ZodEnum<{
 }>;
 export type AssetStatus = zod.infer<typeof ASSET_STATUS_SCHEMA>;
 export declare const ASSET_TYPE_SCHEMA: zod.ZodEnum<{
+    file: "file";
     image: "image";
     video: "video";
     audio: "audio";
-    document: "document";
+    "plaintext-document": "plaintext-document";
+    "multimedia-document": "multimedia-document";
     website: "website";
 }>;
 export type AssetType = zod.infer<typeof ASSET_TYPE_SCHEMA>;
+/**
+ * MIME types that are considered multimedia documents
+ * (documents that contain both text and embedded images/media)
+ */
+export declare const MULTIMEDIA_DOCUMENT_MIME_TYPES: readonly ["application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/msword", "application/rtf", "application/vnd.oasis.opendocument.text"];
+/**
+ * Checks if a MIME type is a multimedia document
+ */
+export declare const isMultimediaDocumentMimeType: (mimeType: string) => boolean;
 export declare const ASSET_VISIBILITY_SCHEMA: zod.ZodEnum<{
     public: "public";
     private: "private";
 }>;
 export type AssetVisibility = zod.infer<typeof ASSET_VISIBILITY_SCHEMA>;
+export interface CheckSums {
+    readonly md5?: string;
+    readonly sha1?: string;
+    readonly sha256?: string;
+    readonly sha384?: string;
+    readonly sha512?: string;
+}
+export declare const CHECKSUMS_SCHEMA: zod.ZodObject<{
+    md5: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+    sha1: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+    sha256: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+    sha384: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+    sha512: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+}, zod.z.core.$strip>;
+export declare const IMAGE_DATA_SCHEMA: zod.ZodObject<{
+    perceptualHash: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+}, zod.z.core.$strip>;
+export type ImageData = zod.infer<typeof IMAGE_DATA_SCHEMA>;
+export declare const DOCUMENT_DATA_SCHEMA: zod.ZodObject<{}, zod.z.core.$strip>;
+export type DocumentData = zod.infer<typeof DOCUMENT_DATA_SCHEMA>;
+export declare const PROCESSING_OPTIONS_SCHEMA: zod.ZodOptional<zod.ZodNullable<zod.ZodObject<{
+    keepAfterProcessing: zod.ZodOptional<zod.ZodNullable<zod.ZodBoolean>>;
+    image: zod.ZodOptional<zod.ZodNullable<zod.ZodObject<{
+        ocrEnabled: zod.ZodOptional<zod.ZodNullable<zod.ZodBoolean>>;
+    }, zod.z.core.$strip>>>;
+}, zod.z.core.$strip>>>;
+export type ProcessingOptions = zod.infer<typeof PROCESSING_OPTIONS_SCHEMA>;
 export declare const ASSET_SCHEMA: zod.ZodObject<{
     id: zod.ZodString;
     projectId: zod.ZodString;
@@ -27,6 +65,17 @@ export declare const ASSET_SCHEMA: zod.ZodObject<{
     parentId: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
     createdAt: zod.ZodNumber;
     updatedAt: zod.ZodOptional<zod.ZodNumber>;
+    checksums: zod.ZodOptional<zod.ZodNullable<zod.ZodObject<{
+        md5: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+        sha1: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+        sha256: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+        sha384: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+        sha512: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+    }, zod.z.core.$strip>>>;
+    imageData: zod.ZodOptional<zod.ZodNullable<zod.ZodObject<{
+        perceptualHash: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+    }, zod.z.core.$strip>>>;
+    documentData: zod.ZodOptional<zod.ZodNullable<zod.ZodObject<{}, zod.z.core.$strip>>>;
     name: zod.ZodPipe<zod.ZodString, zod.ZodTransform<string, string>>;
     fileFormat: zod.ZodOptional<zod.ZodNullable<zod.ZodPipe<zod.ZodString, zod.ZodTransform<string, string>>>>;
     fileExtension: zod.ZodOptional<zod.ZodNullable<zod.ZodPipe<zod.ZodString, zod.ZodTransform<string, string>>>>;
@@ -37,10 +86,12 @@ export declare const ASSET_SCHEMA: zod.ZodObject<{
     storageId: zod.ZodOptional<zod.ZodNullable<zod.ZodPipe<zod.ZodString, zod.ZodTransform<string, string>>>>;
     averageColor: zod.ZodOptional<zod.ZodNullable<zod.ZodPipe<zod.ZodString, zod.ZodTransform<string, string>>>>;
     type: zod.ZodEnum<{
+        file: "file";
         image: "image";
         video: "video";
         audio: "audio";
-        document: "document";
+        "plaintext-document": "plaintext-document";
+        "multimedia-document": "multimedia-document";
         website: "website";
     }>;
     previewHash: zod.ZodOptional<zod.ZodNullable<zod.ZodPipe<zod.ZodString, zod.ZodTransform<string, string>>>>;
@@ -100,10 +151,39 @@ export declare const ASSET_SCHEMA: zod.ZodObject<{
         approved: "approved";
         rejected: "rejected";
     }>;
-    keepAfterProcessing: zod.ZodOptional<zod.ZodNullable<zod.ZodBoolean>>;
+    extractedTextId: zod.ZodOptional<zod.ZodNullable<zod.ZodPipe<zod.ZodString, zod.ZodTransform<string, string>>>>;
+    processingOptions: zod.ZodOptional<zod.ZodNullable<zod.ZodObject<{
+        keepAfterProcessing: zod.ZodOptional<zod.ZodNullable<zod.ZodBoolean>>;
+        image: zod.ZodOptional<zod.ZodNullable<zod.ZodObject<{
+            ocrEnabled: zod.ZodOptional<zod.ZodNullable<zod.ZodBoolean>>;
+        }, zod.z.core.$strip>>>;
+    }, zod.z.core.$strip>>>;
     visibility: zod.ZodOptional<zod.ZodNullable<zod.ZodEnum<{
         public: "public";
         private: "private";
     }>>>;
+    storageDeletedAt: zod.ZodOptional<zod.ZodNullable<zod.ZodNumber>>;
+    classificationWorkflow: zod.ZodOptional<zod.ZodNullable<zod.ZodObject<{
+        id: zod.ZodString;
+        name: zod.ZodString;
+        steps: zod.ZodArray<zod.ZodObject<{
+            id: zod.ZodString;
+            label: zod.ZodString;
+            status: zod.ZodEnum<{
+                error: "error";
+                pending: "pending";
+                in_progress: "in_progress";
+                completed: "completed";
+                skipped: "skipped";
+            }>;
+            optional: zod.ZodOptional<zod.ZodBoolean>;
+            startedAt: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+            completedAt: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+            error: zod.ZodOptional<zod.ZodNullable<zod.ZodString>>;
+        }, zod.z.core.$strip>>;
+        createdAt: zod.ZodString;
+        updatedAt: zod.ZodString;
+    }, zod.z.core.$strip>>>;
 }, zod.z.core.$strip>;
 export type Asset = zod.infer<typeof ASSET_SCHEMA>;
+export type AssetInput = Omit<zod.input<typeof ASSET_SCHEMA>, "createdAt" | "status">;