OpenClaw
0999474fbd
All checks were successful
Build & Deploy to Staging / Build & Deploy to Staging (push) Successful in 10m33s
178 lines
4.2 KiB
Markdown
178 lines
4.2 KiB
Markdown
# SnapAPI Node.js SDK
|
||
|
||
Official Node.js client for [SnapAPI](https://snapapi.eu) — the EU-hosted screenshot API.
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
npm install snapapi
|
||
```
|
||
|
||
## Quick Start
|
||
|
||
```typescript
|
||
import { SnapAPI } from 'snapapi';
|
||
import fs from 'fs';
|
||
|
||
const snap = new SnapAPI('your-api-key');
|
||
|
||
// Simple screenshot
|
||
const png = await snap.capture('https://example.com');
|
||
fs.writeFileSync('screenshot.png', png);
|
||
```
|
||
|
||
## Usage
|
||
|
||
### Basic Screenshot
|
||
|
||
```typescript
|
||
const screenshot = await snap.capture('https://example.com');
|
||
```
|
||
|
||
### With Options
|
||
|
||
```typescript
|
||
const screenshot = await snap.capture('https://example.com', {
|
||
format: 'jpeg',
|
||
width: 1920,
|
||
height: 1080,
|
||
quality: 90,
|
||
});
|
||
```
|
||
|
||
### Full-Page Capture
|
||
|
||
```typescript
|
||
const screenshot = await snap.capture({
|
||
url: 'https://example.com/blog',
|
||
fullPage: true,
|
||
format: 'png',
|
||
deviceScale: 2, // Retina
|
||
});
|
||
```
|
||
|
||
### Mobile Viewport
|
||
|
||
```typescript
|
||
const screenshot = await snap.capture({
|
||
url: 'https://example.com',
|
||
width: 375,
|
||
height: 812,
|
||
deviceScale: 2,
|
||
});
|
||
```
|
||
|
||
### Wait for Dynamic Content
|
||
|
||
```typescript
|
||
const screenshot = await snap.capture({
|
||
url: 'https://example.com/dashboard',
|
||
waitForSelector: '#chart-loaded',
|
||
waitUntil: 'networkidle2',
|
||
});
|
||
```
|
||
|
||
### Dark Mode Capture
|
||
|
||
```typescript
|
||
// Capture in dark mode (prefers-color-scheme: dark)
|
||
const darkScreenshot = await snap.capture({
|
||
url: 'https://example.com',
|
||
darkMode: true,
|
||
format: 'png',
|
||
});
|
||
```
|
||
|
||
### Hide Elements Before Capture
|
||
|
||
```typescript
|
||
// Hide cookie banners, popups, ads
|
||
const cleanScreenshot = await snap.capture({
|
||
url: 'https://example.com',
|
||
hideSelectors: [
|
||
'.cookie-banner',
|
||
'.popup-overlay',
|
||
'#advertisement',
|
||
'.tracking-notice'
|
||
],
|
||
});
|
||
|
||
// Hide single element
|
||
const singleHide = await snap.capture('https://example.com', {
|
||
hideSelectors: '.newsletter-popup',
|
||
});
|
||
```
|
||
|
||
### Custom CSS Injection
|
||
|
||
```typescript
|
||
// Inject custom CSS before capture
|
||
const styled = await snap.capture({
|
||
url: 'https://example.com',
|
||
css: 'body { background: #1a1a2e !important; color: #eee !important; font-family: "Comic Sans MS" }',
|
||
});
|
||
|
||
// Combine with other options
|
||
const combined = await snap.capture({
|
||
url: 'https://example.com',
|
||
css: '.hero { padding: 80px 0 } h1 { font-size: 48px }',
|
||
darkMode: true,
|
||
hideSelectors: ['.cookie-banner'],
|
||
});
|
||
```
|
||
|
||
## API Reference
|
||
|
||
### `new SnapAPI(apiKey, config?)`
|
||
|
||
| Parameter | Type | Description |
|
||
|-----------|------|-------------|
|
||
| `apiKey` | `string` | Your SnapAPI API key (required) |
|
||
| `config.baseUrl` | `string` | API base URL (default: `https://snapapi.eu`) |
|
||
| `config.timeout` | `number` | Request timeout in ms (default: `30000`) |
|
||
|
||
### `snap.capture(url, options?)` / `snap.capture(options)`
|
||
|
||
Returns a `Promise<Buffer>` containing the screenshot image.
|
||
|
||
| Option | Type | Default | Description |
|
||
|--------|------|---------|-------------|
|
||
| `url` | `string` | — | URL to capture (required) |
|
||
| `format` | `'png' \| 'jpeg' \| 'webp'` | `'png'` | Output format |
|
||
| `width` | `number` | `1280` | Viewport width (320–3840) |
|
||
| `height` | `number` | `800` | Viewport height (200–2160) |
|
||
| `fullPage` | `boolean` | `false` | Capture full scrollable page |
|
||
| `quality` | `number` | `80` | JPEG/WebP quality (1–100) |
|
||
| `waitForSelector` | `string` | — | CSS selector to wait for |
|
||
| `deviceScale` | `number` | `1` | Device pixel ratio (1–3) |
|
||
| `delay` | `number` | `0` | Extra delay in ms (0–5000) |
|
||
| `waitUntil` | `string` | `'domcontentloaded'` | Load event to wait for |
|
||
| `darkMode` | `boolean` | `false` | Emulate prefers-color-scheme: dark |
|
||
| `hideSelectors` | `string \| string[]` | — | CSS selectors to hide before capture |
|
||
| `css` | `string` | — | Custom CSS to inject before capture (max 5000 chars) |
|
||
|
||
### `snap.health()`
|
||
|
||
Returns API health status.
|
||
|
||
### Error Handling
|
||
|
||
```typescript
|
||
import { SnapAPI, SnapAPIError } from 'snapapi';
|
||
|
||
try {
|
||
const screenshot = await snap.capture('https://example.com');
|
||
} catch (err) {
|
||
if (err instanceof SnapAPIError) {
|
||
console.error(`API error ${err.status}: ${err.detail}`);
|
||
}
|
||
}
|
||
```
|
||
|
||
## EU-Hosted & GDPR Compliant
|
||
|
||
SnapAPI runs entirely on EU infrastructure (Germany). Your data never leaves the EU. [Learn more](https://snapapi.eu).
|
||
|
||
## License
|
||
|
||
MIT — [Cloonar Technologies GmbH](https://snapapi.eu)
|