pompelmi 1.10.0 → 1.12.0

package/.mailmap

@@ -0,0 +1,3 @@
+JustSouichi <tommasobertocchideveloper04@gmail.com> claude <claude@anthropic.com>
+JustSouichi <tommasobertocchideveloper04@gmail.com> Claude <claude@anthropic.com>
+JustSouichi <tommasobertocchideveloper04@gmail.com> Claude Code <noreply@anthropic.com>

package/README.md

@@ -21,12 +21,28 @@
 
 ---
 
+## Quick Start
+
+```bash
+# Scan a file
+npx pompelmi scan ./uploads/file.pdf
+
+# Scan a directory
+npx pompelmi scan ./uploads --recursive
+
+# Output as JSON
+npx pompelmi scan ./uploads --json
+```
+
+---
+
 ## Documentation
 
 | Guide | Description |
 |-------|-------------|
 | [Getting Started](./docs/getting-started.md) | Installation, prerequisites, quickstart examples |
 | [API Reference](./docs/api.md) | Full function signatures, options, verdicts, error conditions |
+| [CLI Reference](./docs/cli.html) | Terminal commands, options, examples |
 | [S3 Integration](./docs/s3.md) | Scan S3 objects directly, IAM setup, Lambda pattern |
 | [Docker / Remote Scanning](./docs/docker.md) | TCP sidecar, UNIX socket mount, docker-compose patterns |
 | [GitHub Action](./docs/github-action.md) | CI scanning, inputs/outputs, caching, example workflows |
@@ -56,6 +72,7 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 
 ## Features
 
+- Standalone CLI — scan files from any terminal with `npx pompelmi scan`
 - Single `scan(filePath, [options])` function — works locally or against a remote clamd instance
 - `scanBuffer(buffer, [options])` — scan in-memory Buffers directly, no temp file required in TCP mode
 - `scanStream(stream, [options])` — scan a Readable stream directly. In TCP mode, streamed to clamd with no disk I/O.
@@ -63,6 +80,8 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 - `scanS3(params, [options])` — scan S3 objects by streaming directly from AWS S3, no disk I/O
 - `createPool([options])` — persistent connection pool for high-throughput clamd scanning
 - `watch(dirPath, [options], callbacks)` — watch a directory and auto-scan new/modified files (300 ms debounce)
+- `notify(webhookUrl, scanResult, [options])` — send a POST webhook notification when a virus is detected; optional HMAC-SHA256 signing via `X-Pompelmi-Signature`; zero extra dependencies
+- `createScanner([options])` — EventEmitter-based scanner; call `.scan(filePath)` or `.scanDirectory(dirPath)` and listen to `'clean'`, `'malicious'`, `'scanError'`, and `'error'` events
 - Auto-retry on connection error — `retries` and `retryDelay` options on every scan function
 - Symbol-based verdicts (`Verdict.Clean` / `Verdict.Malicious` / `Verdict.ScanError`) — typo-proof comparisons
 - Full clamd support via the INSTREAM protocol — TCP (`host`/`port`) or UNIX socket (`socket`) with configurable timeout

package/bin/pompelmi.js

@@ -0,0 +1,403 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const readline = require('readline');
+
+const pkg = require('../package.json');
+
+// ── Logo ──────────────────────────────────────────────────────────────────────
+
+async function printLogo() {
+  try {
+    const terminalImage = (await import('terminal-image')).default;
+    const imgPath = path.join(__dirname, '../src/grapefruit.png');
+    if (fs.existsSync(imgPath)) {
+      const image = await terminalImage.file(imgPath, {
+        width: '20%',
+        height: '20%',
+        preserveAspectRatio: true,
+      });
+      process.stdout.write(image);
+    }
+  } catch (_) {}
+  console.log('\x1b[33m  pompelmi\x1b[0m — ClamAV Antivirus Scanning for Node.js');
+  console.log('\x1b[90m  v' + pkg.version + ' • Zero dependencies • TCP • UNIX socket • GitHub Action\x1b[0m\n');
+}
+
+// ── Argument parsing ──────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const opts = {
+    command: null,
+    target: null,
+    host: undefined,
+    port: undefined,
+    socket: undefined,
+    timeout: 15000,
+    retries: 0,
+    json: false,
+    quiet: false,
+    delete: false,
+    recursive: true,
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (a === 'scan' || a === 'watch' || a === 'version' || a === 'help') {
+      opts.command = a;
+    } else if (a === '--json') {
+      opts.json = true;
+    } else if (a === '--quiet' || a === '-q') {
+      opts.quiet = true;
+    } else if (a === '--recursive' || a === '-r') {
+      opts.recursive = true;
+    } else if (a === '--delete') {
+      opts.delete = true;
+    } else if (a === '--host') {
+      opts.host = args[++i];
+    } else if (a === '--port') {
+      opts.port = parseInt(args[++i], 10);
+    } else if (a === '--socket') {
+      opts.socket = args[++i];
+    } else if (a === '--timeout') {
+      opts.timeout = parseInt(args[++i], 10);
+    } else if (a === '--retries') {
+      opts.retries = parseInt(args[++i], 10);
+    } else if (!a.startsWith('-') && opts.command && !opts.target) {
+      opts.target = a;
+    }
+    i++;
+  }
+
+  return opts;
+}
+
+// ── Scan options builder ──────────────────────────────────────────────────────
+
+function buildScanOpts(opts) {
+  const o = { timeout: opts.timeout, retries: opts.retries };
+  if (opts.host !== undefined) o.host = opts.host;
+  if (opts.port !== undefined) o.port = opts.port;
+  if (opts.socket !== undefined) o.socket = opts.socket;
+  return o;
+}
+
+// ── Progress bar ──────────────────────────────────────────────────────────────
+
+function progressBar(done, total, infected) {
+  const pct = total === 0 ? 0 : Math.floor((done / total) * 100);
+  const filled = Math.floor(pct / 5);
+  const empty = 20 - filled;
+  const bar = '█'.repeat(filled) + '░'.repeat(empty);
+  return `  Scanning... [${bar}] ${pct}% • ${done}/${total} files • ${infected} infected`;
+}
+
+// ── Box drawing output ────────────────────────────────────────────────────────
+
+function boxLine(content, width) {
+  const padded = content.padEnd(width - 4);
+  return `│  ${padded}  │`;
+}
+
+function printResults(results, elapsed, opts) {
+  if (opts.json) {
+    const out = {
+      scanned: results.length,
+      infected: results.filter(r => r.verdict === 'infected').length,
+      errors: results.filter(r => r.verdict === 'error').length,
+      time: Math.round(elapsed / 100) / 10,
+      results: results.map(r => {
+        const o = { file: r.file, verdict: r.verdict };
+        if (r.viruses) o.viruses = r.viruses;
+        return o;
+      }),
+    };
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  const W = 46;
+  const top    = '┌' + '─'.repeat(W) + '┐';
+  const sep    = '├' + '─'.repeat(W) + '┤';
+  const bottom = '└' + '─'.repeat(W) + '┘';
+
+  const infected = results.filter(r => r.verdict === 'infected').length;
+  const secs     = (elapsed / 1000).toFixed(1);
+
+  console.log(top);
+  console.log(boxLine('🍊 pompelmi scan results', W));
+  console.log(sep);
+
+  for (const r of results) {
+    if (opts.quiet && r.verdict === 'clean') continue;
+    const short = r.file.length > 30 ? '...' + r.file.slice(-27) : r.file;
+    if (r.verdict === 'clean') {
+      console.log(boxLine(`\x1b[32m✅ CLEAN\x1b[0m     ${short}`, W + 9));
+    } else if (r.verdict === 'infected') {
+      console.log(boxLine(`\x1b[31m🚨 INFECTED\x1b[0m  ${short}`, W + 9));
+      if (r.viruses && r.viruses.length) {
+        const vname = r.viruses[0] || '';
+        console.log(boxLine(`\x1b[90m     └─ ${vname}\x1b[0m`, W + 8));
+      }
+    } else {
+      console.log(boxLine(`\x1b[33m⚠️  ERROR\x1b[0m    ${short}`, W + 12));
+    }
+  }
+
+  console.log(sep);
+  const summary = `Scanned: ${results.length}  • Infected: ${infected} • Time: ${secs}s`;
+  console.log(boxLine(summary, W));
+  console.log(bottom);
+}
+
+// ── Scan a single file ────────────────────────────────────────────────────────
+
+async function scanOne(filePath, scanOpts) {
+  const { scan }    = require('../src/ClamAVScanner.js');
+  const { Verdict } = require('../src/verdicts.js');
+  try {
+    const v = await scan(filePath, scanOpts);
+    if (v === Verdict.Clean)     return { file: filePath, verdict: 'clean' };
+    if (v === Verdict.Malicious) return { file: filePath, verdict: 'infected', viruses: [] };
+    return { file: filePath, verdict: 'error' };
+  } catch (err) {
+    if (/ECONNREFUSED|ENOTFOUND|ETIMEDOUT|unreachable/i.test(err.message)) {
+      return { file: filePath, verdict: 'error', _clamdUnreachable: true };
+    }
+    return { file: filePath, verdict: 'error' };
+  }
+}
+
+// ── Collect files from path ───────────────────────────────────────────────────
+
+function collectFiles(target) {
+  const stat = fs.statSync(target);
+  if (stat.isFile()) return [target];
+  const entries = fs.readdirSync(target, { recursive: true });
+  return entries
+    .map(e => path.join(target, e))
+    .filter(f => { try { return fs.statSync(f).isFile(); } catch { return false; } });
+}
+
+// ── Ask confirmation ──────────────────────────────────────────────────────────
+
+function confirm(question) {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, ans => {
+      rl.close();
+      resolve(ans.trim().toLowerCase() === 'y' || ans.trim().toLowerCase() === 'yes');
+    });
+  });
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+async function cmdScan(opts) {
+  if (!opts.target) {
+    console.error('Usage: pompelmi scan <file|dir> [options]');
+    process.exit(2);
+  }
+
+  const target = path.resolve(opts.target);
+  if (!fs.existsSync(target)) {
+    console.error(`Error: path not found: ${target}`);
+    process.exit(2);
+  }
+
+  if (!opts.json && !opts.quiet) await printLogo();
+
+  const files = collectFiles(target);
+  const scanOpts = buildScanOpts(opts);
+  const results = [];
+  const start = Date.now();
+  let infectedCount = 0;
+
+  for (let i = 0; i < files.length; i++) {
+    if (!opts.json && !opts.quiet && files.length > 1) {
+      process.stdout.write('\r' + progressBar(i, files.length, infectedCount));
+    }
+    const r = await scanOne(files[i], scanOpts);
+    if (r.verdict === 'infected') infectedCount++;
+    results.push(r);
+  }
+
+  if (!opts.json && !opts.quiet && files.length > 1) {
+    process.stdout.write('\r' + progressBar(files.length, files.length, infectedCount) + '\n');
+  }
+
+  const elapsed = Date.now() - start;
+
+  if (opts.delete) {
+    const infected = results.filter(r => r.verdict === 'infected');
+    if (infected.length > 0) {
+      if (!opts.json) {
+        console.log(`\nFound ${infected.length} infected file(s):`);
+        for (const r of infected) console.log(`  ${r.file}`);
+      }
+      const ok = await confirm('Delete these files? [y/N] ');
+      if (ok) {
+        for (const r of infected) {
+          try { fs.unlinkSync(r.file); if (!opts.json) console.log(`  Deleted: ${r.file}`); }
+          catch (e) { if (!opts.json) console.log(`  Failed to delete: ${r.file}: ${e.message}`); }
+        }
+      }
+    }
+  }
+
+  printResults(results, elapsed, opts);
+
+  const hasInfected = results.some(r => r.verdict === 'infected');
+  const hasError    = results.some(r => r.verdict === 'error');
+  const clamdDown   = results.some(r => r._clamdUnreachable);
+
+  if (clamdDown) process.exit(3);
+  if (hasInfected) process.exit(1);
+  if (hasError)    process.exit(2);
+  process.exit(0);
+}
+
+async function cmdWatch(opts) {
+  if (!opts.target) {
+    console.error('Usage: pompelmi watch <dir> [options]');
+    process.exit(2);
+  }
+
+  const target = path.resolve(opts.target);
+  if (!fs.existsSync(target)) {
+    console.error(`Error: directory not found: ${target}`);
+    process.exit(2);
+  }
+
+  if (!opts.json && !opts.quiet) await printLogo();
+
+  const { watch } = require('../src/Watcher.js');
+  const scanOpts = buildScanOpts(opts);
+
+  let scanned = 0, clean = 0, infected = 0;
+
+  function status() {
+    process.stdout.write(
+      `\rWatching ${target} • Scanned: ${scanned} • Clean: ${clean} • Infected: ${infected}  `
+    );
+  }
+
+  status();
+
+  watch(target, scanOpts, {
+    onClean(fp) {
+      scanned++; clean++;
+      if (!opts.quiet) process.stdout.write(`\n\x1b[32m✅ CLEAN\x1b[0m  ${fp}\n`);
+      status();
+    },
+    onMalicious(fp) {
+      scanned++; infected++;
+      process.stdout.write(`\n\x1b[31m🚨 INFECTED\x1b[0m  ${fp}\n`);
+      status();
+    },
+    onError(err) {
+      scanned++;
+      if (!opts.quiet) process.stdout.write(`\n\x1b[33m⚠️ ERROR\x1b[0m  ${err.message}\n`);
+      status();
+    },
+  });
+
+  process.on('SIGINT', () => { process.stdout.write('\n'); process.exit(0); });
+}
+
+function cmdVersion() {
+  console.log(pkg.version);
+}
+
+function cmdHelp() {
+  console.log(`
+pompelmi v${pkg.version} — ClamAV Antivirus Scanning for Node.js
+
+USAGE
+  pompelmi <command> [options]
+
+COMMANDS
+  scan <file|dir>    Scan a file or directory for viruses
+  watch <dir>        Watch a directory and auto-scan new/modified files
+  version            Print version number
+  help               Show this help message
+
+SCAN OPTIONS
+  --recursive, -r    Scan directory recursively (default: true)
+  --host <host>      clamd host (default: localhost, uses local clamscan if omitted)
+  --port <port>      clamd port (default: 3310)
+  --socket <path>    UNIX socket path (e.g. /run/clamav/clamd.sock)
+  --timeout <ms>     Connection timeout in ms (default: 15000)
+  --retries <n>      Auto-retry on connection failure (default: 0)
+  --json             Output results as JSON (no logo, no colors)
+  --quiet, -q        Only print infected files and summary
+  --delete           Delete infected files after confirmation
+
+WATCH OPTIONS
+  --host, --port, --socket, --timeout   (same as scan)
+
+EXIT CODES
+  0   All files clean
+  1   Virus found
+  2   Scan error
+  3   clamd unreachable
+
+EXAMPLES
+  # Scan a single file (local clamscan)
+  pompelmi scan ./upload.pdf
+
+  # Scan a directory recursively
+  pompelmi scan ./uploads --recursive
+
+  # Scan via clamd over TCP
+  pompelmi scan ./uploads --host 127.0.0.1 --port 3310
+
+  # Scan via UNIX socket
+  pompelmi scan ./uploads --socket /run/clamav/clamd.sock
+
+  # JSON output for scripting
+  pompelmi scan ./uploads --json
+
+  # Watch a directory
+  pompelmi watch ./uploads --host 127.0.0.1 --port 3310
+
+  # Use with npx (no install required)
+  npx pompelmi scan ./uploads
+`);
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+async function main() {
+  const opts = parseArgs(process.argv);
+
+  if (!opts.command || opts.command === 'help') {
+    await printLogo();
+    cmdHelp();
+    process.exit(0);
+  }
+
+  if (opts.command === 'version') {
+    cmdVersion();
+    process.exit(0);
+  }
+
+  if (opts.command === 'scan') {
+    await cmdScan(opts);
+    return;
+  }
+
+  if (opts.command === 'watch') {
+    await cmdWatch(opts);
+    return;
+  }
+}
+
+main().catch(err => {
+  console.error('\x1b[31mError:\x1b[0m', err.message);
+  process.exit(2);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "ClamAV for humans — scan any file and get back Clean, Malicious, or ScanError. No daemons. No cloud. No native bindings.",
   "license": "ISC",
   "author": "pompelmi contributors",
@@ -33,6 +33,9 @@
   "type": "commonjs",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
+  "bin": {
+    "pompelmi": "./bin/pompelmi.js"
+  },
   "scripts": {
     "test": "node --test test/unit.test.js && node test/scan.test.js",
     "lint": "eslint src/"
@@ -40,7 +43,9 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
-  "dependencies": {},
+  "dependencies": {
+    "terminal-image": "^4.3.0"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "eslint": "^10.2.0",

package/src/ScanEmitter.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+const path = require('path');
+const fs   = require('fs');
+const { scan } = require('./ClamAVScanner.js');
+const { Verdict } = require('./verdicts.js');
+
+/**
+ * Returns an EventEmitter-based scanner.
+ *
+ * Events:
+ *   'clean'     (filePath)           — file scanned clean
+ *   'malicious' (filePath, viruses)  — virus detected (viruses is always [])
+ *   'error'     (err)                — unexpected error (not a scan verdict)
+ *   'scanError' (filePath)           — scan returned Verdict.ScanError
+ *
+ * @param {object} [options] - ScanOptions forwarded to scan()
+ * @returns {EventEmitter & { scan(filePath): void, scanDirectory(dirPath): void }}
+ */
+function createScanner(options = {}) {
+    const emitter = new EventEmitter();
+
+    /**
+     * Scan a single file and emit the appropriate event.
+     * @param {string} filePath
+     */
+    emitter.scan = function scanFile(filePath) {
+        scan(filePath, options)
+            .then((verdict) => {
+                if (verdict === Verdict.Clean) {
+                    emitter.emit('clean', filePath);
+                } else if (verdict === Verdict.Malicious) {
+                    emitter.emit('malicious', filePath, []);
+                } else {
+                    emitter.emit('scanError', filePath);
+                }
+            })
+            .catch((err) => {
+                emitter.emit('error', err);
+            });
+    };
+
+    /**
+     * Recursively scan every file in dirPath and emit events per file.
+     * @param {string} dirPath
+     */
+    emitter.scanDirectory = function scanDir(dirPath) {
+        if (!fs.existsSync(dirPath)) {
+            emitter.emit('error', new Error(`Directory not found: ${dirPath}`));
+            return;
+        }
+
+        let files;
+        try {
+            files = fs.readdirSync(dirPath);
+        } catch (err) {
+            emitter.emit('error', err);
+            return;
+        }
+
+        for (const file of files) {
+            const fullPath = path.join(dirPath, file);
+            let stat;
+            try {
+                stat = fs.statSync(fullPath);
+            } catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                emitter.scanDirectory(fullPath);
+            } else {
+                emitter.scan(fullPath);
+            }
+        }
+    };
+
+    return emitter;
+}
+
+module.exports = { createScanner };

package/src/WebhookNotifier.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const https = require('https');
+const http  = require('http');
+const crypto = require('crypto');
+const os     = require('os');
+const { URL } = require('url');
+
+/**
+ * Send a POST webhook notification when a scan result is available.
+ *
+ * @param {string} webhookUrl - Destination URL (http or https).
+ * @param {object} scanResult - { file, verdict, viruses }
+ * @param {object} [options]  - { onlyOnMalicious, secret }
+ * @returns {Promise<void>}
+ */
+function notify(webhookUrl, scanResult, options = {}) {
+    const { onlyOnMalicious = true, secret } = options;
+
+    if (!webhookUrl || typeof webhookUrl !== 'string') {
+        return Promise.reject(new Error('webhookUrl must be a non-empty string'));
+    }
+    if (!scanResult || typeof scanResult !== 'object') {
+        return Promise.reject(new Error('scanResult must be an object'));
+    }
+
+    const verdictDescription =
+        scanResult.verdict && typeof scanResult.verdict === 'symbol'
+            ? scanResult.verdict.description
+            : String(scanResult.verdict ?? 'Unknown');
+
+    const isMalicious = verdictDescription === 'Malicious';
+
+    if (onlyOnMalicious && !isMalicious) {
+        return Promise.resolve();
+    }
+
+    const payload = JSON.stringify({
+        file:      scanResult.file ?? null,
+        verdict:   verdictDescription,
+        viruses:   scanResult.viruses ?? [],
+        timestamp: new Date().toISOString(),
+        hostname:  os.hostname(),
+    });
+
+    return new Promise((resolve, reject) => {
+        let parsed;
+        try {
+            parsed = new URL(webhookUrl);
+        } catch {
+            return reject(new Error(`Invalid webhookUrl: ${webhookUrl}`));
+        }
+
+        const isHttps = parsed.protocol === 'https:';
+        const transport = isHttps ? https : http;
+
+        const headers = {
+            'Content-Type':   'application/json',
+            'Content-Length': Buffer.byteLength(payload),
+            'User-Agent':     'pompelmi-webhook/1.0',
+        };
+
+        if (secret) {
+            const sig = crypto
+                .createHmac('sha256', secret)
+                .update(payload)
+                .digest('hex');
+            headers['X-Pompelmi-Signature'] = `sha256=${sig}`;
+        }
+
+        const reqOptions = {
+            hostname: parsed.hostname,
+            port:     parsed.port || (isHttps ? 443 : 80),
+            path:     parsed.pathname + parsed.search,
+            method:   'POST',
+            headers,
+        };
+
+        const req = transport.request(reqOptions, (res) => {
+            res.resume(); // drain response body
+            if (res.statusCode >= 200 && res.statusCode < 300) {
+                resolve();
+            } else {
+                reject(new Error(`Webhook responded with HTTP ${res.statusCode}`));
+            }
+        });
+
+        req.on('error', reject);
+        req.write(payload);
+        req.end();
+    });
+}
+
+module.exports = { notify };

package/src/index.js

@@ -4,5 +4,7 @@ const { middleware }                                  = require('./middleware.js
 const { scanS3 }                                      = require('./S3Scanner.js');
 const { createPool }                                  = require('./ClamdPool.js');
 const { watch }                                       = require('./Watcher.js');
+const { notify }                                      = require('./WebhookNotifier.js');
+const { createScanner }                               = require('./ScanEmitter.js');
 
-module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch };
+module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch, notify, createScanner };

package/types/index.d.ts

@@ -152,3 +152,66 @@ export declare function watch(
   options?: ScanOptions,
   callbacks?: WatchCallbacks
 ): FSWatcher;
+
+/** Payload sent by the webhook notifier */
+export interface WebhookPayload {
+  file: string | null;
+  verdict: string;
+  viruses: string[];
+  timestamp: string;
+  hostname: string;
+}
+
+/** Options for notify() */
+export interface NotifyOptions {
+  /** Only send a webhook when the verdict is Malicious (default: true) */
+  onlyOnMalicious?: boolean;
+  /** HMAC-SHA256 secret — adds X-Pompelmi-Signature header when set */
+  secret?: string;
+}
+
+/** scan result passed to notify() */
+export interface ScanResultInput {
+  file?: string | null;
+  verdict: symbol | string;
+  viruses?: string[];
+}
+
+/**
+ * Send a POST webhook notification for a scan result.
+ * Uses Node.js built-in https/http — no external dependencies.
+ * When secret is provided, adds an X-Pompelmi-Signature: sha256=<hmac> header.
+ */
+export declare function notify(
+  webhookUrl: string,
+  scanResult: ScanResultInput,
+  options?: NotifyOptions
+): Promise<void>;
+
+import { EventEmitter } from 'events';
+
+/** EventEmitter-based scanner returned by createScanner() */
+export interface ScanEmitter extends EventEmitter {
+  /** Scan a single file; emits 'clean', 'malicious', 'scanError', or 'error' */
+  scan(filePath: string): void;
+  /** Recursively scan every file in dirPath; emits per-file events */
+  scanDirectory(dirPath: string): void;
+
+  on(event: 'clean',     listener: (filePath: string) => void): this;
+  on(event: 'malicious', listener: (filePath: string, viruses: string[]) => void): this;
+  on(event: 'scanError', listener: (filePath: string) => void): this;
+  on(event: 'error',     listener: (err: Error) => void): this;
+  on(event: string,      listener: (...args: unknown[]) => void): this;
+}
+
+/**
+ * Create an EventEmitter-based scanner.
+ * Options are forwarded to the underlying scan() call (host, port, socket, etc.).
+ *
+ * @example
+ * const scanner = createScanner({ host: 'localhost', port: 3310 });
+ * scanner.on('malicious', (file, viruses) => console.log('VIRUS:', file));
+ * scanner.scan('file.pdf');
+ * scanner.scanDirectory('/uploads');
+ */
+export declare function createScanner(options?: ScanOptions): ScanEmitter;