Node.js SDK

The official TypeScript/JavaScript SDK wraps every API endpoint with typed methods and includes a polling helper for waiting on async jobs.

Installation

npm / yarn / pnpm

npm install screenshotfreeapi

Initialization

Initialize the client

import { ScreenshotFreeAPIClient } from 'screenshotfreeapi';

const client = new ScreenshotFreeAPIClient({
  apiKey: process.env.SCREENSHOTFREEAPI_KEY,  // required
  timeout: 30_000,                        // optional, ms
});

Pass apiKey via an environment variable. The SDK throws at construction time if the key is missing.

Web screenshots

client.screenshots.web()

// Basic capture
const job = await client.screenshots.web({
  url: 'https://stripe.com/pricing',
  format: 'png',
});

// With AI targeting
const aiJob = await client.screenshots.web({
  url: 'https://stripe.com/pricing',
  description: 'the pricing comparison table',
});

// With full options
const richJob = await client.screenshots.web({
  url: 'https://stripe.com/pricing',
  dimensions: { width: 1440, height: 900 },
  fullPage: true,
  blockAds: true,
  acceptCookies: true,
  webhookUrl: 'https://your-app.com/webhook',
});

Mobile screenshots

client.screenshots.mobile()

const job = await client.screenshots.mobile({
  appName: 'Instagram',
  platform: 'both',
  includeStoreListing: true,
  deviceEmulation: 'iPhone 14',
});

Job helpers

client.jobs.*

// Poll until done (built-in exponential backoff)
const result = await client.jobs.waitForResult(job.jobId, {
  pollIntervalMs: 2000,
  timeoutMs: 60_000,
});

console.log(result.screenshotUrl); // presigned S3 URL
console.log(result.dimensions);
console.log(result.metadata.processingMs);

// Get a fresh URL for an existing job
const fresh = await client.jobs.getResult('job_web_7a91bcd3');

Webhook verification

Verify the X-ScreenshotFree-Signature header on every incoming webhook using HMAC-SHA256 and a timing-safe comparison. Always read the raw request body before parsing JSON.

Verify webhook signature

import crypto from 'node:crypto';

// Header format: "X-ScreenshotFree-Signature: t=<unix_ts>,v1=<hex_hmac>"
// Signed content is "<timestamp>.<raw_body>" — NOT the raw body alone.
function verifyWebhook(rawBody: Buffer, header: string, secret: string, toleranceSeconds = 300): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const timestamp = parseInt(parts['t'] ?? '0', 10);
  const v1 = parts['v1'] ?? '';
  if (!timestamp || !v1) return false;

  // Reject replayed webhooks older than the tolerance window
  if (Math.floor(Date.now() / 1000) - timestamp > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const expectedBuf = Buffer.from(expected, 'hex');
  const receivedBuf = Buffer.from(v1, 'hex');
  if (expectedBuf.length !== receivedBuf.length) return false;
  return crypto.timingSafeEqual(expectedBuf, receivedBuf);
}

// Express handler example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-screenshotfree-signature'] as string ?? '';
  if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  const event = JSON.parse(req.body.toString());
  if (event.event === 'job.completed') {
    // resultUrl is a relative path — fetch it against the API base URL
    const result = await fetch(`https://api.screenshotfreeapi.com${event.resultUrl}`, {
      headers: { Authorization: `Bearer ${process.env.SCREENSHOTFREEAPI_KEY}` },
    }).then((r) => r.json());
    console.log('Screenshot ready:', result.screenshots[0].url);
  }
  res.sendStatus(200);
});