screenshotty-js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nihey Takizawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# screenshotty-js
+
+Official JavaScript / TypeScript client for the **[Screenshotty](https://screenshotty.link)** screenshot API — capture pixel-perfect screenshots and PDFs of any website or raw HTML with a single call.
+
+[![CI](https://github.com/nihey/screenshotty-js/actions/workflows/ci.yml/badge.svg)](https://github.com/nihey/screenshotty-js/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/screenshotty-js.svg)](https://www.npmjs.com/package/screenshotty-js)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+- 📸 Full-page, element, mobile, and PDF capture
+- 🌗 Dark mode, ad-blocking, cookie-banner removal, geo-targeting
+- 🧩 Zero runtime dependencies — uses the native `fetch` (Node 18+, Deno, Bun, browsers)
+- 🔒 Fully typed options and results
+
+> Powered by the [Screenshotty screenshot API](https://screenshotty.link). Grab a free API key (1,500 screenshots/month, no card) in the [dashboard](https://screenshotty.link) and read the full [API documentation](https://screenshotty.link/docs).
+
+## Install
+
+```bash
+npm install screenshotty-js
+```
+
+## Quick start
+
+```ts
+import { Screenshotty } from "screenshotty-js";
+
+const client = new Screenshotty(process.env.SCREENSHOTTY_API_KEY!);
+
+// Get raw PNG bytes
+const png = await client.capture({ url: "https://example.com", fullPage: true });
+
+// …or just the hosted URL
+const url = await client.captureToUrl({ url: "https://example.com" });
+
+// …or write straight to disk (Node.js)
+await client.captureToFile({ url: "https://example.com" }, "example.png");
+```
+
+## Examples
+
+**Mobile screenshot in dark mode:**
+
+```ts
+await client.capture({
+  url: "https://example.com",
+  viewportPreset: "iphone_15_pro_max",
+  lightMode: "dark",
+});
+```
+
+**Website → PDF:**
+
+```ts
+const pdf = await client.capture({
+  url: "https://example.com",
+  format: "application/pdf",
+  printed: true,
+});
+```
+
+**Capture a single element, clean of ads and cookie banners:**
+
+```ts
+await client.capture({
+  url: "https://news.example.com/article",
+  selector: "article",
+  adblock: true,
+  blockCookieBanner: true,
+});
+```
+
+**Render raw HTML (great for OG images):**
+
+```ts
+await client.capture({
+  html: "<h1 style='font:700 64px sans-serif'>Hello 👋</h1>",
+  viewportWidth: 1200,
+  viewportHeight: 630,
+});
+```
+
+**Geo-targeted capture:**
+
+```ts
+const countries = await client.countries(); // e.g. ["us", "de", "br", …]
+await client.capture({ url: "https://example.com", country: "de" });
+```
+
+## API
+
+### `new Screenshotty(apiKey, options?)`
+
+| Option | Type | Default |
+|--------|------|---------|
+| `baseUrl` | `string` | `https://api.screenshotty.link` |
+| `fetch` | `typeof fetch` | global `fetch` |
+
+### Methods
+
+| Method | Returns | Notes |
+|--------|---------|-------|
+| `capture(options)` | `Promise<Uint8Array>` | Raw image/PDF bytes |
+| `captureToJson(options)` | `Promise<ScreenshotResult>` | `{ url, width, height, mime }` |
+| `captureToUrl(options)` | `Promise<string>` | Hosted screenshot URL |
+| `captureToFile(options, path)` | `Promise<void>` | Node.js only |
+| `countries()` | `Promise<string[]>` | Geo-targeting country codes |
+
+### `ScreenshotOptions`
+
+camelCase options are mapped to the API's parameters automatically. See the full,
+always-current parameter reference in the [Screenshotty API docs](https://screenshotty.link/docs). Highlights: `url` / `html`,
+`format`, `fullPage`, `selector`, `viewportWidth` / `viewportHeight` /
+`viewportPreset`, `deviceScaleFactor`, `crop*`, `lightMode`, `adblock`,
+`blockCookieBanner`, `country`, `javascriptCode` / `cssCode`, `httpHeaders` /
+`cookies`, `readyEvent` / `waitMs`, `webhookUrl`.
+
+### Errors
+
+Non-2xx responses throw a `ScreenshottyError` with `.status` and `.body`:
+
+```ts
+import { ScreenshottyError } from "screenshotty-js";
+
+try {
+  await client.capture({ url: "https://example.com" });
+} catch (err) {
+  if (err instanceof ScreenshottyError) {
+    console.error(err.status, err.message, err.body);
+  }
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test        # node --test with a mocked fetch
+npm run build
+```
+
+## Links
+
+- 🌐 [Screenshotty](https://screenshotty.link) — the screenshot API
+- 📖 [API documentation](https://screenshotty.link/docs)
+- 🧪 [Interactive playground](https://screenshotty.link/screenshot-api)
+- 🐦 [@screenshotty](https://x.com/screenshotty)
+
+## License
+
+[MIT](./LICENSE) © Nihey Takizawa

package/dist/client.d.ts

@@ -0,0 +1,40 @@
+import type { ScreenshotOptions, ScreenshotResult } from "./types.js";
+/** Configuration for a {@link Screenshotty} client. */
+export interface ScreenshottyClientOptions {
+    /** Override the API base URL. Default: `https://api.screenshotty.link`. */
+    baseUrl?: string;
+    /** Custom fetch implementation (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+}
+/**
+ * Client for the Screenshotty screenshot API.
+ *
+ * @example
+ * ```ts
+ * const client = new Screenshotty(process.env.SCREENSHOTTY_API_KEY!);
+ * const png = await client.capture({ url: "https://example.com", fullPage: true });
+ * ```
+ *
+ * @see https://screenshotty.link/docs
+ */
+export declare class Screenshotty {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(apiKey: string, options?: ScreenshottyClientOptions);
+    /** Capture a screenshot and return the raw image (or PDF) bytes. */
+    capture(options: ScreenshotOptions): Promise<Uint8Array>;
+    /** Capture and return the result metadata (`{ url, width, height, mime }`). */
+    captureToJson(options: ScreenshotOptions): Promise<ScreenshotResult>;
+    /** Capture and return just the stored screenshot URL. */
+    captureToUrl(options: ScreenshotOptions): Promise<string>;
+    /**
+     * Capture and write the bytes to a file. Node.js only.
+     * @param filePath Destination path.
+     */
+    captureToFile(options: ScreenshotOptions, filePath: string): Promise<void>;
+    /** List the country codes available for geo-targeted captures. */
+    countries(): Promise<string[]>;
+    private request;
+    private rawFetch;
+}

package/dist/client.js

@@ -0,0 +1,111 @@
+import { ScreenshottyError } from "./errors.js";
+const DEFAULT_BASE_URL = "https://api.screenshotty.link";
+const SCREENSHOT_PATH = "/api/v1/screenshot";
+const COUNTRIES_PATH = "/api/v1/screenshot/countries";
+/** camelCase → snake_case (e.g. `viewportWidth` → `viewport_width`). */
+function toSnakeCase(key) {
+    return key.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`);
+}
+function toRequestBody(options) {
+    const body = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (value === undefined)
+            continue;
+        body[toSnakeCase(key)] = value;
+    }
+    return body;
+}
+function extractMessage(body) {
+    if (body && typeof body === "object") {
+        const record = body;
+        if (typeof record.error === "string")
+            return record.error;
+        if (typeof record.message === "string")
+            return record.message;
+    }
+    return undefined;
+}
+/**
+ * Client for the Screenshotty screenshot API.
+ *
+ * @example
+ * ```ts
+ * const client = new Screenshotty(process.env.SCREENSHOTTY_API_KEY!);
+ * const png = await client.capture({ url: "https://example.com", fullPage: true });
+ * ```
+ *
+ * @see https://screenshotty.link/docs
+ */
+export class Screenshotty {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    constructor(apiKey, options = {}) {
+        if (!apiKey) {
+            throw new Error("Screenshotty: an API key is required. Get one at https://screenshotty.link.");
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            throw new Error("Screenshotty: no fetch implementation found. Use Node 18+ or pass `options.fetch`.");
+        }
+        this.fetchImpl = fetchImpl;
+    }
+    /** Capture a screenshot and return the raw image (or PDF) bytes. */
+    async capture(options) {
+        const res = await this.request({ ...options, responseType: "image" });
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    /** Capture and return the result metadata (`{ url, width, height, mime }`). */
+    async captureToJson(options) {
+        const res = await this.request({ ...options, responseType: "json" });
+        return (await res.json());
+    }
+    /** Capture and return just the stored screenshot URL. */
+    async captureToUrl(options) {
+        const result = await this.captureToJson(options);
+        return result.url;
+    }
+    /**
+     * Capture and write the bytes to a file. Node.js only.
+     * @param filePath Destination path.
+     */
+    async captureToFile(options, filePath) {
+        const bytes = await this.capture(options);
+        const { writeFile } = await import("node:fs/promises");
+        await writeFile(filePath, bytes);
+    }
+    /** List the country codes available for geo-targeted captures. */
+    async countries() {
+        const res = await this.rawFetch(COUNTRIES_PATH, { method: "GET" });
+        const data = (await res.json());
+        return data.countries ?? [];
+    }
+    request(options) {
+        return this.rawFetch(SCREENSHOT_PATH, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(toRequestBody(options)),
+        });
+    }
+    async rawFetch(path, init) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            ...init,
+            headers: { "x-api-key": this.apiKey, ...(init.headers ?? {}) },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            let body = text;
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                /* keep raw text */
+            }
+            const message = extractMessage(body) ?? `Screenshotty request failed with status ${res.status}.`;
+            throw new ScreenshottyError(message, res.status, body);
+        }
+        return res;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+/** Error thrown when the Screenshotty API responds with a non-2xx status. */
+export declare class ScreenshottyError extends Error {
+    /** HTTP status code of the failed response. */
+    readonly status: number;
+    /** Parsed JSON body if available, otherwise the raw response text. */
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}

package/dist/errors.js

@@ -0,0 +1,15 @@
+/** Error thrown when the Screenshotty API responds with a non-2xx status. */
+export class ScreenshottyError extends Error {
+    /** HTTP status code of the failed response. */
+    status;
+    /** Parsed JSON body if available, otherwise the raw response text. */
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "ScreenshottyError";
+        this.status = status;
+        this.body = body;
+        // Restore prototype chain for instanceof across transpile targets.
+        Object.setPrototypeOf(this, ScreenshottyError.prototype);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Screenshotty } from "./client.js";
+export type { ScreenshottyClientOptions } from "./client.js";
+export { ScreenshottyError } from "./errors.js";
+export type { ScreenshotOptions, ScreenshotResult, ImageFormat, ResponseType, ReadyEvent, LightMode, ViewportPreset, WebhookMethod, Cookie, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Screenshotty } from "./client.js";
+export { ScreenshottyError } from "./errors.js";

package/dist/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Output formats supported by the Screenshotty API.
+ * @see https://screenshotty.link/docs
+ */
+export type ImageFormat = "image/png" | "image/jpg" | "image/jpeg" | "image/gif" | "image/webp" | "image/jp2" | "image/tiff" | "application/pdf";
+/** How the API should return the result. High-level client methods set this for you. */
+export type ResponseType = "image" | "json" | "url" | "redirect" | "file";
+/** Page-lifecycle event to wait for before capturing. */
+export type ReadyEvent = "load" | "domcontentloaded" | "networkidle" | "networkidle2" | "networkidle0";
+/** Force the page's color scheme. */
+export type LightMode = "default" | "light" | "dark";
+/** Named device/viewport presets. */
+export type ViewportPreset = "desktop" | "desktop_hd" | "desktop_4k" | "tablet" | "tablet_landscape" | "mobile" | "mobile_landscape" | "mobile_android" | "mobile_android_landscape" | "iphone_se" | "iphone_14" | "iphone_14_pro" | "iphone_14_pro_max" | "iphone_15" | "iphone_15_pro_max";
+/** HTTP method used to deliver the webhook callback. */
+export type WebhookMethod = "GET" | "POST" | "PUT" | "PATCH";
+/** A cookie to set before loading the page (used for capturing authenticated pages). */
+export interface Cookie {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    [key: string]: unknown;
+}
+/**
+ * Options for a screenshot request. All keys are camelCase and mapped to the
+ * API's snake_case parameters automatically. Provide either `url` or `html`.
+ */
+export interface ScreenshotOptions {
+    /** URL of the page to capture. Mutually exclusive with `html`. */
+    url?: string;
+    /** Raw HTML to render and capture. Mutually exclusive with `url`. */
+    html?: string;
+    /** Output format. Default: `image/png`. */
+    format?: ImageFormat;
+    /** Viewport width in px. Default: 1920. */
+    viewportWidth?: number;
+    /** Viewport height in px. Default: 1080. */
+    viewportHeight?: number;
+    /** Named viewport/device preset (overrides width/height). */
+    viewportPreset?: ViewportPreset;
+    /** Device pixel ratio. Default: 1. */
+    deviceScaleFactor?: number;
+    /** Crop origin X (px). */
+    cropX?: number;
+    /** Crop origin Y (px). */
+    cropY?: number;
+    /** Crop width (px). */
+    cropWidth?: number;
+    /** Crop height (px). */
+    cropHeight?: number;
+    /** Capture a single element by CSS selector instead of the page. */
+    selector?: string;
+    /** Capture the full scrollable page. Default: true. */
+    fullPage?: boolean;
+    /** Transparent background (PNG/WebP). Default: false. */
+    transparentBackground?: boolean;
+    /** Scroll to the bottom before capture (triggers lazy loading). Default: false. */
+    scrollToBottom?: boolean;
+    /** Use print CSS/media. Default: false. */
+    printed?: boolean;
+    /** Lifecycle event to wait for. Default: `domcontentloaded`. */
+    readyEvent?: ReadyEvent;
+    /** Extra fixed wait in ms after the ready event. */
+    waitMs?: number;
+    /** JavaScript to inject and run before capture. */
+    javascriptCode?: string;
+    /** CSS to inject before capture. */
+    cssCode?: string;
+    /** Override the User-Agent header. */
+    userAgent?: string;
+    /** Locale/language (e.g. `en-US`). Default: `en-US`. */
+    language?: string;
+    /** Cookies to set before loading (capture authed pages). */
+    cookies?: Cookie[];
+    /** Extra HTTP request headers. */
+    httpHeaders?: Record<string, string>;
+    /** Block ads. Default: false. */
+    adblock?: boolean;
+    /** Auto-dismiss cookie-consent banners. Default: false. */
+    blockCookieBanner?: boolean;
+    /** Force color scheme. Default: `default`. */
+    lightMode?: LightMode;
+    /** Route the request through a proxy in this country (ISO code). */
+    country?: string;
+    /** Webhook URL to call when the screenshot is ready. */
+    webhookUrl?: string;
+    /** Webhook HTTP method. Default: `POST`. */
+    webhookMethod?: WebhookMethod;
+    /** Extra headers to send with the webhook call. */
+    webhookHeaders?: Record<string, string>;
+}
+/** Result returned by `captureToJson` / `captureToUrl` (`response_type=json|url`). */
+export interface ScreenshotResult {
+    /** Public URL of the stored screenshot. */
+    url: string;
+    /** Rendered width in px, when available. */
+    width?: number;
+    /** Rendered height in px, when available. */
+    height?: number;
+    /** MIME type of the stored file, when available. */
+    mime?: string;
+    /** Extracted HTML, when requested. */
+    html?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "screenshotty-js",
+  "version": "0.1.0",
+  "description": "Official JavaScript/TypeScript client for the Screenshotty screenshot API — capture pixel-perfect screenshots and PDFs of any website or HTML.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "screenshot",
+    "screenshot-api",
+    "website-screenshot",
+    "html-to-image",
+    "html-to-pdf",
+    "puppeteer",
+    "playwright",
+    "url-to-image",
+    "og-image",
+    "pdf"
+  ],
+  "homepage": "https://screenshotty.link",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nihey/screenshotty-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nihey/screenshotty-js/issues"
+  },
+  "author": "Nihey Takizawa",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}