e6c34ef760
Some checks failed
Build & Deploy to Staging / Build & Deploy to Staging (push) Has been cancelled
- Add 5 new Python tests for darkMode and hideSelectors parameters - Update Node.js SDK README with darkMode/hideSelectors examples - Update Python SDK README with darkMode/hideSelectors examples - Add API reference entries for new parameters - All tests passing: Node.js (19 tests), Python (22 tests) Features already implemented in v0.7.0 but needed better test coverage and documentation.
173 lines
4 KiB
Markdown
173 lines
4 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',
|
||
});
|
||
```
|
||
|
||
### Combined Dark Mode + Element Hiding
|
||
|
||
```typescript
|
||
// Perfect for clean marketing screenshots
|
||
const marketingShot = await snap.capture({
|
||
url: 'https://your-saas-app.com',
|
||
darkMode: true,
|
||
hideSelectors: ['.dev-banner', '.beta-notice'],
|
||
width: 1920,
|
||
height: 1080,
|
||
deviceScale: 2,
|
||
});
|
||
```
|
||
|
||
## 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 |
|
||
|
||
### `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)
|