npm package: @render-api/sdk
Description: Official Node.js SDK for the RenderAPI screenshot and PDF rendering service
Author: RenderAPI
Latest version: 1.0.0

# renderapi

Official Node.js SDK for [RenderAPI](https://renderapi.com) — convert URLs and HTML to screenshots and PDFs via a simple API.

## Installation

```bash
npm install renderapi
```

Requires Node.js 18+ (uses native `fetch`).

## Quick Start

```js
const { RenderAPI } = require('renderapi');

const client = new RenderAPI('rapi_live_your_api_key');

// Take a screenshot
const screenshot = await client.screenshot({ url: 'https://example.com' });
console.log(screenshot.url); // URL to the rendered image
```

## API Reference

### `new RenderAPI(apiKey, options?)`

Create a client instance.

| Parameter | Type | Description |
|-----------|------|-------------|
| `apiKey` | `string` | **Required.** Your API key (`rapi_live_*` or `rapi_test_*`) |
| `options.baseUrl` | `string` | Custom API base URL |

---

### `client.screenshot(options)`

Take a screenshot of a URL or HTML string. Returns a `ScreenshotResult`.

```js
// Screenshot a URL
const result = await client.screenshot({
  url: 'https://example.com',
  format: 'png',
  width: 1440,
  height: 900,
  full_page: true,
});

console.log(result.id);              // "rnd_abc123"
console.log(result.url);             // "https://cdn.renderapi.com/..."
console.log(result.file_size_bytes); // 184320
console.log(result.duration_ms);     // 1250
```

```js
// Screenshot from HTML
const result = await client.screenshot({
  html: '<h1 style="color: red;">Hello World</h1>',
  format: 'jpeg',
  quality: 90,
  width: 800,
  height: 600,
});
```

```js
// With dark mode, ad blocking, and CSS injection
const result = await client.screenshot({
  url: 'https://news.ycombinator.com',
  dark_mode: true,
  block_ads: true,
  inject_css: 'body { font-family: "Inter", sans-serif; }',
  device_scale_factor: 2,
});
```

```js
// Capture a specific element
const result = await client.screenshot({
  url: 'https://example.com',
  selector: '#main-chart',
  wait_for: 'networkidle',
  delay_ms: 1000,
});
```

```js
// With caching and webhook notification
const result = await client.screenshot({
  url: 'https://example.com/dashboard',
  cache_ttl: 3600,
  webhook_url: 'https://your-server.com/webhook',
});
```

#### Screenshot Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `url` | `string` | — | URL to capture (provide `url` or `html`) |
| `html` | `string` | — | HTML to render (provide `url` or `html`) |
| `format` | `'png' \| 'jpeg' \| 'webp'` | `'png'` | Output format |
| `width` | `number` | `1280` | Viewport width (100–3840) |
| `height` | `number` | `800` | Viewport height (100–2160) |
| `full_page` | `boolean` | `false` | Capture full scrollable page |
| `device_scale_factor` | `number` | `1` | Device pixel ratio (1–3) |
| `quality` | `number` | `80` | Image quality (1–100) |
| `wait_for` | `string` | `'networkidle'` | Wait condition |
| `delay_ms` | `number` | `0` | Extra delay after load (0–10000) |
| `selector` | `string` | — | CSS selector to capture |
| `dark_mode` | `boolean` | `false` | Emulate dark mode |
| `block_ads` | `boolean` | `true` | Block ads/trackers |
| `inject_css` | `string` | — | Custom CSS to inject |
| `inject_js` | `string` | — | Custom JS to inject |
| `cache_ttl` | `number` | `0` | Cache TTL in seconds (0–86400) |
| `webhook_url` | `string` | — | Webhook URL for async notification |

---

### `client.pdf(options)`

Generate a PDF from a URL or HTML string. Returns a `PdfResult`.

```js
// PDF from URL
const result = await client.pdf({
  url: 'https://example.com/report',
  format: 'A4',
  landscape: false,
});

console.log(result.url);   // Download URL
console.log(result.pages); // Number of pages
```

```js
// PDF from HTML with custom margins and header/footer
const result = await client.pdf({
  html: '<h1>Invoice #1234</h1><p>Total: $99.00</p>',
  format: 'Letter',
  margin: {
    top: '25mm',
    bottom: '25mm',
    left: '20mm',
    right: '20mm',
  },
  header_html: '<div style="font-size:10px;text-align:center;">ACME Corp</div>',
  footer_html: '<div style="font-size:10px;text-align:center;">Page <span class="pageNumber"></span></div>',
  print_background: true,
});
```

```js
// PDF with custom dimensions
const result = await client.pdf({
  html: '<div>Custom size document</div>',
  format: 'custom',
  width: '210mm',
  height: '148mm',
});
```

#### PDF Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `url` | `string` | — | URL to render |
| `html` | `string` | — | HTML to render |
| `format` | `'A4' \| 'Letter' \| 'Legal' \| 'custom'` | `'A4'` | Page format |
| `width` | `string` | — | Custom width (when format is `'custom'`) |
| `height` | `string` | — | Custom height (when format is `'custom'`) |
| `landscape` | `boolean` | `false` | Landscape orientation |
| `margin` | `object` | — | `{ top, right, bottom, left }` margins |
| `header_html` | `string` | — | Page header HTML |
| `footer_html` | `string` | — | Page footer HTML |
| `print_background` | `boolean` | `true` | Include backgrounds |
| `wait_for` | `string` | `'networkidle'` | Wait condition |
| `delay_ms` | `number` | `0` | Extra delay (0–10000) |
| `inject_css` | `string` | — | Custom CSS |
| `inject_js` | `string` | — | Custom JS |
| `webhook_url` | `string` | — | Webhook URL |

---

### `client.usage()`

Get usage data for the current billing period.

```js
const usage = await client.usage();

console.log(usage.plan);            // "starter"
console.log(usage.renders_used);    // 1523
console.log(usage.renders_included); // 5000
console.log(usage.screenshots);     // 1200
console.log(usage.pdfs);            // 323
console.log(usage.period_start);    // "2026-03-01T00:00:00Z"
console.log(usage.period_end);      // "2026-04-01T00:00:00Z"
```

---

### `client.getRender(renderId)`

Retrieve details of a previous render by ID.

```js
const render = await client.getRender('rnd_abc123');

console.log(render.type);     // "screenshot"
console.log(render.status);   // "completed"
console.log(render.url);      // Download URL
console.log(render.format);   // "png"
```

---

### `client.templates.list()`

List all templates.

```js
const { templates } = await client.templates.list();

templates.forEach(t => {
  console.log(`${t.name} (${t.id}) - default: ${t.default_output}`);
});
```

---

### `client.templates.create(options)`

Create a new Handlebars template.

```js
const template = await client.templates.create({
  name: 'Invoice',
  html: `
    <h1>Invoice #{{invoice_number}}</h1>
    <p>Customer: {{customer_name}}</p>
    <p>Amount: ${{amount}}</p>
  `,
  sample_data: {
    invoice_number: '1001',
    customer_name: 'Jane Doe',
    amount: '150.00',
  },
  default_output: 'pdf',
});

console.log(template.id); // Use this ID to render
```

---

### `client.templates.render(templateId, data, options?)`

Render a template with data.

```js
// Render as PDF (default)
const result = await client.templates.render('tmpl_abc123', {
  invoice_number: '1042',
  customer_name: 'John Smith',
  amount: '250.00',
});

console.log(result.url); // Download URL for the PDF
```

```js
// Render as PNG screenshot
const result = await client.templates.render(
  'tmpl_abc123',
  { invoice_number: '1042', customer_name: 'John Smith', amount: '250.00' },
  { output: 'png', format: 'Letter' },
);
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `output` | `'pdf' \| 'png' \| 'jpeg' \| 'webp'` | `'pdf'` | Output format |
| `format` | `'A4' \| 'Letter' \| 'Legal'` | `'A4'` | Page format (PDF) |

---

## Error Handling

All API errors throw a `RenderAPIError` with structured details.

```js
const { RenderAPI, RenderAPIError } = require('renderapi');

const client = new RenderAPI('rapi_live_your_key');

try {
  await client.screenshot({ url: 'https://example.com' });
} catch (err) {
  if (err instanceof RenderAPIError) {
    console.error(err.message);  // Human-readable message
    console.error(err.status);   // HTTP status (400, 401, 408, 422, etc.)
    console.error(err.code);     // Error code ("render_timeout", "render_failed", etc.)
    console.error(err.details);  // Validation details (for 400 errors)
  }
}
```

## ESM Support

```js
import { RenderAPI } from 'renderapi';

const client = new RenderAPI('rapi_live_your_key');
```

## License

MIT