@copperline/rendex

Official TypeScript SDK for the Rendex screenshot API. Capture any webpage as a high-quality image with a single function call.

• Zero runtime dependencies (uses native fetch)
• Full TypeScript types with IntelliSense
• Works in Node.js 18+, Deno, Bun, and browsers
• Typed error handling with API error codes

Install

npm install @copperline/rendex
# or
pnpm add @copperline/rendex
# or
bun add @copperline/rendex

Quick Start

import { Rendex } from "@copperline/rendex";

const rendex = new Rendex("your-api-key");

// Capture a screenshot (returns binary image)
const { image, metadata } = await rendex.screenshot({
  url: "https://example.com",
  format: "png",
  fullPage: true,
});

// Write to file (Node.js)
import { writeFile } from "node:fs/promises";
await writeFile("screenshot.png", image);

console.log(`${metadata.bytesSize} bytes, loaded in ${metadata.loadTimeMs}ms`);

API Reference

new Rendex(apiKey, config?)

Create a new Rendex client.

const rendex = new Rendex("your-api-key", {
  baseUrl: "https://api.rendex.dev", // optional, default
});

| Parameter | Type | Description | |-----------|------|-------------| | apiKey | string | Your Rendex API key. Get one at rendex.dev | | config.baseUrl | string | Override the API base URL | | config.fetch | typeof fetch | Custom fetch implementation (for testing) |

rendex.screenshot(options)

Capture a screenshot and return the binary image with metadata.

const { image, metadata } = await rendex.screenshot({
  url: "https://example.com",
  format: "webp",
  width: 1920,
  height: 1080,
  darkMode: true,
});

Returns Promise<ScreenshotResult>:

• image — Uint8Array of the captured image
• metadata — ScreenshotMetadata with URL, dimensions, format, bytes, load time, quality signal

rendex.screenshotJson(options)

Capture a screenshot and return JSON with a base64-encoded image.

const result = await rendex.screenshotJson({
  url: "https://example.com",
});

console.log(result.data.image);          // base64 string
console.log(result.data.bytesSize);      // 45823
console.log(result.meta.usage?.remaining); // 499

Returns Promise<ScreenshotJsonResponse> with data (image + metadata) and meta (request ID, usage).

rendex.screenshotUrl(options)

Generate a GET URL for embedding. No network call — pure URL builder.

const url = rendex.screenshotUrl({
  url: "https://example.com",
  format: "png",
  width: 1200,
});
// Use in <img> tags, OpenGraph, etc.

Note: The API key is included in the URL. Use server-side only.

Returns string — a complete URL to the screenshot endpoint.

Screenshot Options

All options except url are optional:

| Option | Type | Default | Description | |--------|------|---------|-------------| | url | string | required | The webpage URL to capture | | format | "png" \| "jpeg" \| "webp" \| "pdf" | "png" | Output format | | width | number | 1280 | Viewport width (320–3840) | | height | number | 800 | Viewport height (240–2160) | | fullPage | boolean | false | Capture the full scrollable page | | quality | number | — | JPEG/WebP quality (1–100) | | delay | number | 0 | Delay before capture in ms (0–10000) | | darkMode | boolean | false | Emulate dark mode | | deviceScaleFactor | number | 1 | Device pixel ratio (1–3) for Retina | | blockAds | boolean | true | Block ads and trackers | | blockResourceTypes | string[] | — | Block: "font", "image", "media", "stylesheet", "other" | | timeout | number | 30 | Page load timeout in seconds (5–60) | | waitUntil | string | "networkidle2" | Wait strategy: "load", "domcontentloaded", "networkidle0", "networkidle2" | | waitForSelector | string | — | CSS selector to wait for before capture | | bestAttempt | boolean | true | Return best-effort screenshot on timeout | | selector | string | — | Capture a specific element by CSS selector |

Error Handling

import { Rendex, RendexApiError, RendexNetworkError } from "@copperline/rendex";

const rendex = new Rendex("your-api-key");

try {
  await rendex.screenshot({ url: "https://example.com" });
} catch (error) {
  if (error instanceof RendexApiError) {
    // API returned an error
    console.error(error.errorCode);  // "RATE_LIMITED", "VALIDATION_ERROR", etc.
    console.error(error.statusCode); // 429, 400, etc.
    console.error(error.requestId);  // For debugging with Rendex support
    console.error(error.details);    // Validation details (if any)
  } else if (error instanceof RendexNetworkError) {
    // Network failure (DNS, timeout, connection refused)
    console.error("Network error:", error.message);
  }
}

Error Codes

| Code | HTTP Status | Description | |------|-------------|-------------| | VALIDATION_ERROR | 400 | Invalid request parameters | | INVALID_URL | 400 | URL failed SSRF validation | | TIMEOUT | 408 | Page took too long to load | | CAPTURE_FAILED | 500 | Browser rendering error | | RATE_LIMITED | 429 | Rate limit exceeded | | USAGE_EXCEEDED | 429 | Monthly credit limit reached | | MISSING_API_KEY | 401 | No API key provided | | INVALID_API_KEY | 401 | API key verification failed |

License

MIT - Copperline Labs LLC