ShotAPI JavaScript/TypeScript SDK

Official JavaScript/TypeScript SDK for ShotAPI - The Screenshot & Rendering API.

Works in Node.js 16+ and modern browsers.

Installation

npm install shotapi-sdk
# or
yarn add shotapi-sdk
# or
pnpm add shotapi-sdk

Quick Start

import { ShotAPI } from 'shotapi-sdk';

const client = new ShotAPI({ apiKey: 'sk_your_api_key' });

// Take a screenshot
const image = await client.screenshot('https://example.com');

// Save to file (Node.js)
import { writeFileSync } from 'fs';
writeFileSync('screenshot.png', Buffer.from(image));

Features

• Full TypeScript support - Complete type definitions included
• URL Screenshots - Capture any webpage as PNG, JPEG, WebP, or PDF
• HTML Rendering - Convert HTML/CSS to images
• Metadata Extraction - Get OG tags, title, description, tech stack
• Batch Processing - Screenshot multiple URLs in parallel
• Visual Diff - Compare two pages and get difference percentage

Usage Examples

Basic Screenshot

import { ShotAPI } from 'shotapi-sdk';

const client = new ShotAPI({ apiKey: 'sk_your_api_key' });

// Simple screenshot
const image = await client.screenshot('https://stripe.com');

// Full-page screenshot
const fullPage = await client.screenshot('https://github.com', {
  fullPage: true,
  format: 'png',
});

// With options
const customized = await client.screenshot('https://example.com', {
  width: 1920,
  height: 1080,
  darkMode: true,
  deviceScaleFactor: 2,
  blockAds: true,
});

Device Mockups

// Wrap in iPhone frame
const iphone = await client.screenshot('https://example.com', {
  mockup: 'iphone',
});

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

HTML to Image

// Render HTML to image
const html = `
<div style="padding: 40px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);">
    <h1 style="color: white; font-family: sans-serif;">Hello World!</h1>
</div>
`;

const image = await client.render(html, { width: 800, height: 400 });

Metadata Extraction

// Get page metadata
const meta = await client.metadata('https://github.com');
console.log(meta.title);
console.log(meta.description);
console.log(meta.og_image);

// With markdown content
const metaWithContent = await client.metadata('https://example.com', {
  extractMarkdown: true,
});
console.log(metaWithContent.markdown);

Batch Screenshots

// Capture multiple URLs
const urls = [
  'https://google.com',
  'https://github.com',
  'https://stripe.com',
];

const result = await client.batch(urls, { format: 'png', fullPage: true });
for (const item of result.results) {
  console.log(`${item.url} -> ${item.filename}`);
}

Visual Diff

// Compare two pages
const { image, percentage } = await client.diff(
  'https://example.com',
  'https://example.org'
);

console.log(`Pages differ by ${percentage}%`);

// Save diff image
import { writeFileSync } from 'fs';
writeFileSync('diff.png', Buffer.from(image));

Advanced Options

// Full control over the capture
const image = await client.screenshot('https://example.com', {
  width: 1280,
  height: 720,
  fullPage: true,
  format: 'png',
  delay: 2, // Wait 2 seconds before capture
  darkMode: true,
  deviceScaleFactor: 2,
  customCss: "body { font-family: 'Comic Sans MS' !important; }",
  customJs: "document.querySelector('.popup').remove()",
  waitForSelector: '.content-loaded',
  clickSelector: '.accept-cookies',
  hideSelectors: ['.ad-banner', '.newsletter-popup'],
  blockAds: true,
  headers: { Authorization: 'Bearer token' },
  cookies: [{ name: 'session', value: 'abc123', domain: 'example.com' }],
  geolocation: { latitude: 40.7128, longitude: -74.006 },
  timezone: 'America/New_York',
});

Error Handling

import {
  ShotAPI,
  ShotAPIError,
  AuthenticationError,
  RateLimitError,
} from 'shotapi-sdk';

const client = new ShotAPI({ apiKey: 'sk_your_api_key' });

try {
  const image = await client.screenshot('https://example.com');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ShotAPIError) {
    console.log(`API error: ${error.message}`);
  }
}

Browser Usage

The SDK works in browsers too:

<script type="module">
  import { ShotAPI } from 'https://esm.sh/shotapi-sdk';

  const client = new ShotAPI({ apiKey: 'sk_your_api_key' });

  const image = await client.screenshot('https://example.com');

  // Display image
  const blob = new Blob([image], { type: 'image/png' });
  const url = URL.createObjectURL(blob);
  document.getElementById('img').src = url;
</script>

Configuration

const client = new ShotAPI({
  apiKey: 'sk_your_api_key',
  baseUrl: 'https://shotapi.net', // default
  timeout: 120000, // milliseconds (default: 60000)
});

Pro/Max Features

Some features require a Pro or Max plan:

| Feature | Free | Pro | Max | | -------------------- | ---- | --- | --- | | Basic screenshots | Yes | Yes | Yes | | Full-page capture | Yes | Yes | Yes | | Dark mode | No | Yes | Yes | | Device mockups | No | Yes | Yes | | Custom CSS/JS | No | Yes | Yes | | Element selection | No | Yes | Yes | | Geo/Timezone | No | Yes | Yes | | Block ads | No | Yes | Yes | | Batch processing | No | Yes | Yes | | Markdown extraction | No | Yes | Yes |

TypeScript

Full TypeScript support is included:

import { ShotAPI, ScreenshotOptions, MetadataResult } from 'shotapi-sdk';

const options: ScreenshotOptions = {
  width: 1920,
  height: 1080,
  darkMode: true,
};

const client = new ShotAPI({ apiKey: 'sk_...' });
const image: ArrayBuffer = await client.screenshot('https://example.com', options);
const meta: MetadataResult = await client.metadata('https://example.com');

Links

• Documentation
• Pricing
• Dashboard

License

MIT License - see LICENSE file for details.