TypeScript SDK

The official TypeScript SDK for the AllScreenshots API with full type definitions and IntelliSense support.

Source code: GitHub | Package: @allscreenshots/sdk

Requirements

Node.js 18.0.0 or higher
TypeScript 5.0+ (for TypeScript projects)

Installation

npm install @allscreenshots/sdk
# or
pnpm add @allscreenshots/sdk
# or
yarn add @allscreenshots/sdk

Quick start

import { AllscreenshotsClient } from '@allscreenshots/sdk';
import fs from 'fs';

const client = new AllscreenshotsClient();

const imageBuffer = await client.screenshot({
  url: 'https://github.com',
  device: 'Desktop HD',
  fullPage: true
});

fs.writeFileSync('screenshot.png', imageBuffer);

Configuration

The client can be configured using the builder pattern, direct configuration, or environment variables.

Builder pattern

import { AllscreenshotsClient } from '@allscreenshots/sdk';

const client = AllscreenshotsClient.builder()
  .apiKey(process.env.ALLSCREENSHOTS_API_KEY!)
  .baseUrl('https://api.allscreenshots.com')
  .timeout(60000)
  .maxRetries(3)
  .build();

Direct configuration

const client = new AllscreenshotsClient({
  apiKey: process.env.ALLSCREENSHOTS_API_KEY!,
  baseUrl: 'https://api.allscreenshots.com',
  timeout: 60000,
  autoRetry: true,
  maxRetries: 3,
});

Environment variables

Set ALLSCREENSHOTS_API_KEY to automatically configure authentication:

// Client will read API key from environment
const client = new AllscreenshotsClient();

Capture screenshots

Basic capture

const screenshot = await client.screenshot({
  url: 'https://example.com',
});

fs.writeFileSync('screenshot.png', screenshot);

With options

const screenshot = await client.screenshot({
  url: 'https://example.com',
  device: 'Desktop HD',
  format: 'png',
  quality: 90,
  fullPage: true,
  darkMode: true,
  blockAds: true,
  blockCookieBanners: true,
  delay: 1000,
});

Device presets

// Desktop
const desktop = await client.screenshot({
  url: 'https://example.com',
  device: 'Desktop HD',
});

// Mobile
const mobile = await client.screenshot({
  url: 'https://example.com',
  device: 'iPhone 15',
});

// Tablet
const tablet = await client.screenshot({
  url: 'https://example.com',
  device: 'iPad Pro 11',
});

Async jobs

For long-running captures, use async jobs:

// Create async job
const job = await client.screenshotAsync({
  url: 'https://example.com',
  fullPage: true,
});

console.log(`Job ID: ${job.jobId}`);

// Poll for completion
const result = await client.getJob(job.jobId);

if (result.status === 'completed') {
  const imageData = await client.getJobResult(job.jobId);
  fs.writeFileSync('screenshot.png', imageData);
}

Bulk capture

Process multiple URLs efficiently:

const bulkJob = await client.bulk({
  urls: [
    { url: 'https://example1.com' },
    { url: 'https://example2.com' },
    { url: 'https://example3.com' },
  ],
  defaults: {
    device: 'Desktop HD',
    format: 'png',
  },
});

// Check status
const status = await client.getBulkJob(bulkJob.bulkJobId);

Composition

Combine multiple screenshots into a single image:

const composed = await client.compose({
  url: 'https://example.com',
  variants: [
    { device: 'Desktop HD', label: 'Desktop' },
    { device: 'iPhone 15', label: 'Mobile' },
  ],
  output: {
    layout: 'horizontal',
    spacing: 20,
  },
});

Schedules

Create recurring screenshot captures:

// Create a schedule
const schedule = await client.schedules.create({
  name: 'Daily Homepage',
  url: 'https://example.com',
  schedule: '0 9 * * *',
  timezone: 'America/New_York',
});

// List schedules
const schedules = await client.schedules.list();

// Get captures
const captures = await client.schedules.getCaptures(schedule.scheduleId);

Usage tracking

Monitor your API usage:

const usage = await client.usage.get();
console.log(`Screenshots: ${usage.screenshotCount}/${usage.quota}`);

Error handling

The SDK provides typed error classes for granular exception handling:

import {
  AllscreenshotsError,
  AuthenticationError,
  ValidationError,
  RateLimitError,
  QuotaExceededError,
  ServerError,
  NetworkError,
  TimeoutError
} from '@allscreenshots/sdk';

try {
  const screenshot = await client.screenshot({
    url: 'https://example.com',
  });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof QuotaExceededError) {
    console.log('Quota exceeded for this billing period');
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.log(`Validation error: ${error.message}`);
  } else if (error instanceof AllscreenshotsError) {
    console.log(`API error: ${error.message}`);
  }
}

Type definitions

ScreenshotOptions

interface ScreenshotOptions {
  url: string;
  viewport?: {
    width?: number;   // 100-4096, default: 1920
    height?: number;  // 100-4096, default: 1080
    deviceScaleFactor?: number; // 1-3, default: 1
  };
  device?: DevicePreset;
  format?: 'png' | 'jpeg' | 'webp' | 'pdf';
  quality?: number;  // 1-100
  fullPage?: boolean;
  selector?: string;
  delay?: number;    // 0-30000
  waitFor?: string;
  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
  timeout?: number;  // 1000-60000
  darkMode?: boolean;
  customCss?: string;
  hideSelectors?: string[];
  blockAds?: boolean;
  blockCookieBanners?: boolean;
}

DevicePreset

type DevicePreset =
  // Desktop
  | 'Desktop HD'
  | 'Desktop Large'
  | 'Laptop'
  // iPhone
  | 'iPhone SE'
  | 'iPhone 12'
  | 'iPhone 14'
  | 'iPhone 15'
  | 'iPhone 15 Pro Max'
  // iPad
  | 'iPad'
  | 'iPad Mini'
  | 'iPad Pro 11'
  | 'iPad Pro 12.9'
  // Android
  | 'Pixel 7'
  | 'Samsung Galaxy S23'
  // Social
  | 'Facebook OG'
  | 'Twitter Card'
  | 'LinkedIn Post';

License

Apache License 2.0

TypeScript SDK

On this page