snaprender 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SnapRender
+
+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,95 @@
+# @snaprender/node
+
+Official Node.js SDK for the [SnapRender](https://snap-render.com) Screenshot API.
+
+## Install
+
+```bash
+npm install @snaprender/node
+```
+
+## Quick Start
+
+```typescript
+import SnapRender from '@snaprender/node';
+
+const snap = new SnapRender({ apiKey: 'sk_live_...' });
+
+// Capture a screenshot
+const buffer = await snap.capture({ url: 'https://example.com' });
+fs.writeFileSync('screenshot.png', buffer);
+
+// Capture as JPEG with options
+const jpg = await snap.capture({
+  url: 'https://example.com',
+  format: 'jpeg',
+  width: 1920,
+  height: 1080,
+  fullPage: true,
+  darkMode: true,
+  quality: 95,
+});
+
+// Check cache status
+const info = await snap.info({ url: 'https://example.com' });
+console.log(info.cached); // true/false
+
+// Get usage
+const usage = await snap.usage();
+console.log(`${usage.used}/${usage.limit} screenshots used`);
+```
+
+## API
+
+### `new SnapRender(options)`
+
+| Option | Type | Required | Default |
+|--------|------|----------|---------|
+| `apiKey` | string | Yes | — |
+| `baseUrl` | string | No | `https://app.snap-render.com` |
+
+### `snap.capture(options)` → `Promise<Buffer>`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | string | — | URL to capture (required) |
+| `format` | `'png' \| 'jpeg' \| 'webp' \| 'pdf'` | `'png'` | Output format |
+| `width` | number | `1280` | Viewport width |
+| `height` | number | `800` | Viewport height |
+| `fullPage` | boolean | `false` | Capture full scrollable page |
+| `quality` | number | `90` | JPEG/WebP quality (1-100) |
+| `delay` | number | `0` | Wait ms after page load |
+| `darkMode` | boolean | `false` | Emulate dark mode |
+| `blockAds` | boolean | `true` | Block ad networks |
+| `blockCookieBanners` | boolean | `true` | Remove cookie banners |
+| `device` | string | — | Device preset (e.g. `'iPhone 15'`) |
+| `cache` | boolean | `true` | Use cache |
+| `cacheTtl` | number | `86400` | Cache TTL in seconds |
+
+### `snap.info(options)` → `Promise<CacheInfo>`
+
+Check if a screenshot is cached without capturing.
+
+### `snap.usage()` → `Promise<UsageResponse>`
+
+Get current month's usage.
+
+### `snap.usageDaily(days?)` → `Promise<DailyUsage>`
+
+Get daily usage breakdown (default 30 days).
+
+## Error Handling
+
+```typescript
+import { SnapRenderError } from '@snaprender/node';
+
+try {
+  await snap.capture({ url: 'https://example.com' });
+} catch (err) {
+  if (err instanceof SnapRenderError) {
+    console.log(err.code);    // 'QUOTA_EXCEEDED'
+    console.log(err.status);  // 429
+    console.log(err.message); // 'Monthly quota exceeded'
+  }
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+export interface SnapRenderOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface CaptureOptions {
+    url: string;
+    format?: 'png' | 'jpeg' | 'webp' | 'pdf';
+    width?: number;
+    height?: number;
+    fullPage?: boolean;
+    quality?: number;
+    delay?: number;
+    darkMode?: boolean;
+    blockAds?: boolean;
+    blockCookieBanners?: boolean;
+    hideSelectors?: string;
+    clickSelector?: string;
+    device?: string;
+    userAgent?: string;
+    cache?: boolean;
+    cacheTtl?: number;
+}
+export interface CacheInfo {
+    url: string;
+    cached: boolean;
+    cachedAt?: string;
+    expiresAt?: string;
+    size?: number;
+}
+export interface UsageResponse {
+    plan: string;
+    used: number;
+    limit: number;
+    remaining: number;
+}
+export interface DailyUsage {
+    days: number;
+    data: Array<{
+        date: string;
+        count: number;
+    }>;
+}
+export declare class SnapRenderError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status: number);
+}
+export declare class SnapRender {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(options: SnapRenderOptions);
+    /**
+     * Capture a screenshot of a URL.
+     * Returns the image as a Buffer.
+     */
+    capture(options: CaptureOptions): Promise<Buffer>;
+    /**
+     * Get cache info for a URL without capturing.
+     */
+    info(options: CaptureOptions): Promise<CacheInfo>;
+    /**
+     * Get current usage for the authenticated account.
+     */
+    usage(): Promise<UsageResponse>;
+    /**
+     * Get daily usage breakdown.
+     */
+    usageDaily(days?: number): Promise<DailyUsage>;
+    private request;
+    private json;
+}
+export default SnapRender;

package/dist/index.js

@@ -0,0 +1,107 @@
+export class SnapRenderError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'SnapRenderError';
+    }
+}
+export class SnapRender {
+    apiKey;
+    baseUrl;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error('apiKey is required');
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? 'https://app.snap-render.com').replace(/\/$/, '');
+    }
+    /**
+     * Capture a screenshot of a URL.
+     * Returns the image as a Buffer.
+     */
+    async capture(options) {
+        const params = new URLSearchParams();
+        params.set('url', options.url);
+        if (options.format)
+            params.set('format', options.format);
+        if (options.width)
+            params.set('width', String(options.width));
+        if (options.height)
+            params.set('height', String(options.height));
+        if (options.fullPage !== undefined)
+            params.set('full_page', String(options.fullPage));
+        if (options.quality)
+            params.set('quality', String(options.quality));
+        if (options.delay)
+            params.set('delay', String(options.delay));
+        if (options.darkMode !== undefined)
+            params.set('dark_mode', String(options.darkMode));
+        if (options.blockAds !== undefined)
+            params.set('block_ads', String(options.blockAds));
+        if (options.blockCookieBanners !== undefined)
+            params.set('block_cookie_banners', String(options.blockCookieBanners));
+        if (options.hideSelectors)
+            params.set('hide_selectors', options.hideSelectors);
+        if (options.clickSelector)
+            params.set('click_selector', options.clickSelector);
+        if (options.device)
+            params.set('device', options.device);
+        if (options.userAgent)
+            params.set('user_agent', options.userAgent);
+        if (options.cache !== undefined)
+            params.set('cache', String(options.cache));
+        if (options.cacheTtl)
+            params.set('cache_ttl', String(options.cacheTtl));
+        const res = await this.request(`/v1/screenshot?${params}`);
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({}));
+            throw new SnapRenderError(body.error?.message ?? `HTTP ${res.status}`, body.error?.code ?? 'UNKNOWN', res.status);
+        }
+        const arrayBuffer = await res.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    }
+    /**
+     * Get cache info for a URL without capturing.
+     */
+    async info(options) {
+        const params = new URLSearchParams();
+        params.set('url', options.url);
+        if (options.format)
+            params.set('format', options.format);
+        if (options.width)
+            params.set('width', String(options.width));
+        if (options.height)
+            params.set('height', String(options.height));
+        const res = await this.request(`/v1/screenshot/info?${params}`);
+        return this.json(res);
+    }
+    /**
+     * Get current usage for the authenticated account.
+     */
+    async usage() {
+        const res = await this.request('/v1/usage');
+        return this.json(res);
+    }
+    /**
+     * Get daily usage breakdown.
+     */
+    async usageDaily(days = 30) {
+        const res = await this.request(`/v1/usage/daily?days=${days}`);
+        return this.json(res);
+    }
+    async request(path) {
+        return fetch(`${this.baseUrl}${path}`, {
+            headers: { 'X-API-Key': this.apiKey },
+        });
+    }
+    async json(res) {
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({}));
+            throw new SnapRenderError(body.error?.message ?? `HTTP ${res.status}`, body.error?.code ?? 'UNKNOWN', res.status);
+        }
+        return res.json();
+    }
+}
+export default SnapRender;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "snaprender",
+  "version": "0.1.0",
+  "description": "Official Node.js SDK for SnapRender Screenshot API",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["screenshot", "api", "snaprender", "capture", "webpage"],
+  "license": "MIT",
+  "homepage": "https://snap-render.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/User0856/snaprender"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}