npm package: @opswat/mcl-platform-sdk-javascript
Description: MetaDefender Cloud SDK for TypeScript/JavaScript - File scanning, threat detection, and CDR with 20+ anti-malware engines
Author: OPSWAT
Latest version: 1.0.1

# MetaDefender TypeScript SDK

[![npm version](https://img.shields.io/npm/v/@opswat/mcl-platform-sdk-javascript.svg)](https://www.npmjs.com/package/@opswat/mcl-platform-sdk-javascript)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)

TypeScript/JavaScript SDK for MetaDefender Cloud - file scanning, threat detection, and CDR with 20+ anti-malware engines.

## Versions

- API version: `4.0`
- SDK version: `1.0.1`

## About the API

MetaDefender SDK provides an interface for interacting with MetaDefender Cloud and Core services. It enables file analysis with 20+ anti-malware engines, Deep Content Disarm and Reconstruction (CDR), sandbox analysis, and more.

### Key Features of MetaDefender Cloud

- **File Analysis** – Scan files using 20+ anti-malware engines
- **Deep CDR** – Supports sanitization of 100+ file types
- **Sandbox Analysis** – Detects unknown and targeted attacks through dynamic analysis

## Table of Contents

- [Versions](#versions)
- [About the API](#about-the-api)
- [Setup & Configuration](#setup--configuration)
  - [Supported Node.js Versions](#supported-nodejs-versions)
- [Installation](#installation)
- [Authentication](#authentication)
  - [Basic Usage](#basic-usage)
- [API Services](#api-services)
  - [File Scanning](#file-scanning)
  - [Data Sanitization (CDR)](#data-sanitization-cdr)
  - [Hash Lookups](#hash-lookups)
  - [Reputation Service](#reputation-service)
  - [Dynamic Analysis (Sandbox)](#dynamic-analysis-sandbox)
  - [API Key Management](#api-key-management)
- [Error Handling](#error-handling)
- [Example Workflow](#example-workflow)
- [License](#license)

## Setup & Configuration

### Supported Node.js Versions

This SDK is compatible with the following versions:

- Node.js 16.x or higher
- npm or yarn package manager

## Installation

Install the SDK using npm:

```bash
npm install @opswat/mcl-platform-sdk-javascript
```

**Requirements:** Node.js 16.x or higher

```bash
yarn add @opswat/mcl-platform-sdk-javascript
```

## Authentication

Set your API key as an environment variable:

```bash
export METADEFENDER_APIKEY="YOUR_API_KEY_HERE"
```

The SDK automatically reads from `METADEFENDER_APIKEY`. Alternatively, pass it directly:

```typescript
import { Configuration } from "@opswat/mcl-platform-sdk-javascript";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });
```

### Basic Usage

```typescript
import { Configuration, FileScanningApi } from "@opswat/mcl-platform-sdk-javascript";
import * as fs from "fs";

const config = new Configuration(); // Reads METADEFENDER_APIKEY
const fsApi = new FileScanningApi(config);

// Upload and scan file
const fileBuffer = fs.readFileSync("test.pdf");
const file = new File([fileBuffer], "test.pdf");
const upload = await fsApi.analyzeFile(file, {
  filename: "test.pdf",
  rule: "sanitize",
});

// Poll for results with timeout
const result = await fsApi.fileLookupWithPolling(upload.data.data_id, {
  timeout: 60,
  pollInterval: 2000,
});

console.log("Scan result:", result.data.scan_results?.scan_all_result_a);
```

## API Services

### File Scanning

```typescript
import { FileScanningApi } from "@opswat/mcl-platform-sdk-javascript";

const fsApi = new FileScanningApi(config);

// Upload file
const upload = await fsApi.analyzeFile(file, {
  filename: "filename.pdf",
  rule: "sanitize", // multiscan, sanitize, cdr, unarchive, dlp
});

// Poll for scan completion (recommended)
const result = await fsApi.fileLookupWithPolling(dataId, {
  timeout: 60,
  pollInterval: 2000,
});
```

### Data Sanitization (CDR)

```typescript
import { DataSanitizationCDRApi } from "@opswat/mcl-platform-sdk-javascript";

const cdrApi = new DataSanitizationCDRApi(config);

// Get sanitized file URL
const sanitized = await cdrApi.downloadSanitizedFile(dataId);
console.log("Download URL:", sanitized.data.sanitizedFilePath);

// Cleanup
await cdrApi.deleteSanitizedFile(dataId);
```

### Hash Lookups

```typescript
import { HashLookupsApi } from "@opswat/mcl-platform-sdk-javascript";

const hashApi = new HashLookupsApi(config);
const result = await hashApi.lookupHash("640CCA22FBF439406BA200EEFB9C52BE87BC97D6");
```

### Reputation Service

```typescript
import { ReputationServiceApi } from "@opswat/mcl-platform-sdk-javascript";

const repApi = new ReputationServiceApi(config);

// Check IP, domain, or URL reputation
const ipRep = await repApi.lookupIP("198.15.127.171");
const domainRep = await repApi.lookupDomain("example.com");
const urlRep = await repApi.lookupURL("http://suspicious-url.com");
```

### Dynamic Analysis (Sandbox)

```typescript
import { DynamicAnalysisApi } from "@opswat/mcl-platform-sdk-javascript";

const sandboxApi = new DynamicAnalysisApi(config);
const sandboxRes = await sandboxApi.getSandbox(sandboxId);
console.log("Verdict:", sandboxRes.data.final_verdict);
```

### API Key Management

```typescript
import { ApikeyApi } from "@opswat/mcl-platform-sdk-javascript";

const apikeyApi = new ApikeyApi(config);

// Get API key info
const info = await apikeyApi.getAPIKey();
console.log("Nickname:", info.data.nickname);

// Check limits
const limits = await apikeyApi.getAPIKeyLimits();
const remaining = await apikeyApi.getAPIKeyRemainingLimits();
const history = await apikeyApi.listAPIKeyScanHistory();
```

## Error Handling

```typescript
import { AxiosError } from "axios";

try {
  const result = await fsApi.getFileAnalysis(dataId);
} catch (error) {
  if (error instanceof AxiosError) {
    console.error("Status:", error.response?.status);
    console.error("Details:", error.response?.data);
  } else {
    console.error("Error:", error);
  }
}
```

## Example Workflow

See the complete example in `tests/exemple_all_workflows.ts`:

```bash
export METADEFENDER_APIKEY="YOUR_API_KEY"
# Use this only if you have a staging API key
export METADEFENDER_BASE_PATH="https://api-staging.metadefender.com/v4"
npm test
```

The example demonstrates:

- API key validation
- File upload and scanning
- Polling for results
- Sanitized file retrieval
- Hash lookups
- IP/Domain/URL reputation checks

## License

MIT License - see [LICENSE.md](LICENSE.md) for details.