Virus Scan for TypeScript Developer Guide

TypeScript developers invest in type safety to catch bugs at compile time rather than in production. That same mindset should extend to security: when your application accepts files from users—form uploads, API payloads, document imports—you should verify those files before they enter your system. Viruses, ransomware, and trojans routinely arrive disguised as harmless documents. Without a virus scan at the point of entry, an infected file can move through your pipeline, reach your storage, and eventually harm other users or systems. Compliance requirements under GDPR, HIPAA, and SOC 2 further reinforce the need to validate uploaded content.

This developer guide walks you through every step of integrating virus and malware scanning into a TypeScript application using the attachmentAV API. The SDK ships with full TypeScript type definitions, giving you autocompletion, compile-time checks, and self-documenting code as you build your virus scanning workflow. The detection engine behind the API is Sophos—a globally recognized provider of enterprise-grade malware protection.

Prerequisites

Before you begin, make sure you have:

• Node.js 18+ installed
• An attachmentAV API key — available in three tiers: 10k, 50k, or 100k scans per month

Install and Configure the SDK

The attachmentAV SDK is published on npm under @attachmentav/virus-scan-sdk-ts. It includes full type definitions out of the box.

npm i @attachmentav/virus-scan-sdk-ts

Create a typed configuration and instantiate the API client. By default, the SDK points at the European endpoint. You can override this with basePath if your infrastructure is in another region.

import { AttachmentAVApi, Configuration } from '@attachmentav/virus-scan-sdk-ts';

const config = new Configuration({
  apiKey: '<API_KEY_PLACEHOLDER>'
});

const api = new AttachmentAVApi(config);

Available API regions:

• https://eu.developer.attachmentav.com/v1/ (Europe, default)
• https://us.developer.attachmentav.com/v1/ (United States)
• https://canada.developer.attachmentav.com/v1/ (Canada)
• https://india.developer.attachmentav.com/v1/ (India)

Scan a Local File for Viruses and Malware

To virus scan a file from disk—such as a user upload that your server has just received—read it into a Blob and call scanSyncBinaryPost. The synchronous mode returns the malware scan result directly in the response, so you can gate your upload pipeline on it.

import { AttachmentAVApi, Configuration } from '@attachmentav/virus-scan-sdk-ts';
import { readFileSync } from 'node:fs';
import { Blob } from 'node:buffer';

const config = new Configuration({
  apiKey: '<API_KEY_PLACEHOLDER>'
});

const api = new AttachmentAVApi(config);

const scanResult = await api.scanSyncBinaryPost({
  body: new Blob([readFileSync('/path/to/file')])
});
console.log('Sync binary scan result:', scanResult);

The response object is fully typed. The status field is one of 'clean', 'infected', or 'no'. When the Sophos engine detects a threat, finding contains the name of the virus, trojan, or ransomware variant, and realfiletype reveals the actual file type regardless of the extension.

Scan a URL for Malware

When you need to verify a file that is available at a remote URL—a user-submitted link, a webhook download URL, or a partner integration endpoint—let the API fetch and scan it. This keeps untrusted content away from your TypeScript application entirely.

import { AttachmentAVApi, Configuration } from '@attachmentav/virus-scan-sdk-ts';

const config = new Configuration({
  apiKey: '<API_KEY_PLACEHOLDER>'
});

const api = new AttachmentAVApi(config);

const scanResult = await api.scanSyncDownloadPost({
  syncDownloadScanRequest: {
    downloadUrl: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
  }
});
console.log('Sync download scan result:', scanResult);

The URL scan mode supports files up to 200 MB.

Asynchronous Virus Scanning with Polling

For files that exceed synchronous limits (up to 5 GB in async mode) or when you want to process virus scans in the background, use the asynchronous scanning mode with polling. Submit a scan job with a unique traceId and then query the result endpoint until the scan completes.

import { AttachmentAVApi, Configuration, ResponseError } from '@attachmentav/virus-scan-sdk-ts';
import { randomUUID } from 'node:crypto';
import { exit } from 'node:process';

const config = new Configuration({
  apiKey: '<API_KEY_PLACEHOLDER>'
});

const api = new AttachmentAVApi(config);

const traceId = randomUUID();

async function sleep(ms) {
  return new Promise((resolve) => {
    setTimeout(resolve, ms);
  });
}

await api.scanAsyncDownloadPost({
  asyncDownloadScanRequest: {
    downloadUrl: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf',
    traceId
  }
});
console.log('Async download submitted. Start to poll for scan result...');

let i = 0;
while(true) {
  try {
    console.log('.');
    const scanResult = await api.scanAsyncResultGet({
      traceId
    });
    console.log('Async download scan result:', scanResult);
    exit(0)
  } catch (e: unknown) {
    if (e instanceof ResponseError) {
      if (e.response.status === 404) {
        i++;
        if (i < 10) {
          await sleep(5000);
        } else {
          console.error('Async download scan result not found');
          exit(1);
        }
      } else {
        throw e;
      }
    } else {
      throw e;
    }
  }
}

Alternatively, you can pass a callbackUrl instead of polling. The API will POST the scan result—including status, finding, and timing data—directly to your endpoint when the virus scan finishes. See the callback documentation for payload format and signature verification.

Synchronous vs. Asynchronous: Which Mode to Use

Self-Hosted Option for AWS

Organizations with strict data residency or compliance requirements can deploy the attachmentAV scanning engine directly into their own AWS account. The self-hosted version uses the same Sophos-powered detection but runs entirely within your cloud infrastructure.

Next Steps

You now have a complete toolkit for integrating virus scanning into TypeScript applications—from synchronous file checks to asynchronous background processing. The attachmentAV SDK gives you full type safety, and the Sophos engine behind the API provides reliable detection of viruses, malware, ransomware, and trojans.

Ready to secure your application? Subscribe to the Virus and Malware Scan API and start scanning files in your TypeScript project today.