getsnap 1.0.0

package/README.md

@@ -0,0 +1,129 @@
+# snapapi-sdk
+
+Official Node.js/TypeScript SDK for [SnapAPI](https://getsnap.dev) — Screenshot & PDF API.
+
+## Installation
+
+```bash
+npm install snapapi-sdk
+```
+
+## Quick Start
+
+```typescript
+import SnapAPI from "snapapi-sdk";
+
+const snap = new SnapAPI("sk_live_YOUR_KEY");
+
+// Take a screenshot
+const { url } = await snap.screenshot({
+  url: "https://github.com",
+  format: "png",
+  full_page: true,
+  remove_popups: true,
+});
+console.log(url); // CDN URL to your screenshot
+```
+
+## Features
+
+- Full TypeScript types for all options and responses
+- Screenshot capture (URL or HTML)
+- Binary response (raw image bytes)
+- Batch capture (up to 100 URLs)
+- Usage tracking
+- Async status polling
+- All API parameters supported: lazy_load, wait_for_selector, hide_selectors, remove_selectors, extract_text, extract_html, click_selector, scroll_to_selector, and more
+
+## API
+
+### `new SnapAPI(apiKey, options?)`
+
+Create a client instance.
+
+- `apiKey` — Your SnapAPI key (starts with `sk_live_` or `sk_test_`)
+- `options.baseUrl` — Custom base URL (default: `https://api.getsnap.dev`)
+
+### `snap.screenshot(options)`
+
+Take a screenshot. Returns `{ url, cached, request_id, extracted_text?, extracted_html? }`.
+
+```typescript
+const result = await snap.screenshot({
+  url: "https://example.com",
+  format: "png",
+  viewport_width: 1280,
+  viewport_height: 720,
+  full_page: true,
+  remove_popups: true,
+  block_ads: true,
+  lazy_load: true,
+  extract_text: true,
+});
+```
+
+### `snap.screenshotBinary(options)`
+
+Get raw image/PDF bytes as an `ArrayBuffer`.
+
+```typescript
+import { writeFile } from "fs/promises";
+
+const buffer = await snap.screenshotBinary({
+  url: "https://example.com",
+  format: "webp",
+  quality: 90,
+});
+await writeFile("screenshot.webp", Buffer.from(buffer));
+```
+
+### `snap.batch(options)`
+
+Capture multiple URLs in one request.
+
+```typescript
+const batch = await snap.batch({
+  urls: ["https://github.com", "https://stripe.com", "https://vercel.com"],
+  format: "png",
+  remove_popups: true,
+});
+
+console.log(`${batch.succeeded}/${batch.count} captured`);
+batch.results.forEach(r => console.log(r.source_url, "->", r.url));
+```
+
+### `snap.usage()`
+
+Check current usage and quota.
+
+```typescript
+const { used, limit, plan } = await snap.usage();
+console.log(`${used}/${limit} (${plan})`);
+```
+
+### `snap.status(requestId)`
+
+Check status of an async (webhook) request.
+
+```typescript
+const status = await snap.status("req_abc123");
+```
+
+## Error Handling
+
+```typescript
+import { SnapAPI, SnapAPIError } from "snapapi-sdk";
+
+try {
+  await snap.screenshot({ url: "https://example.com", format: "png" });
+} catch (err) {
+  if (err instanceof SnapAPIError) {
+    console.error(err.status, err.error, err.message);
+    // 402, "quota_exceeded", "Monthly limit reached..."
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+export interface ScreenshotOptions {
+    /** URL to capture (required unless html is provided) */
+    url?: string;
+    /** HTML content to render (required unless url is provided) */
+    html?: string;
+    /** Output format */
+    format?: "png" | "jpg" | "jpeg" | "webp" | "pdf";
+    /** Viewport width in pixels (320-3840) */
+    viewport_width?: number;
+    /** Viewport height in pixels (200-2160) */
+    viewport_height?: number;
+    /** Capture full scrollable page */
+    full_page?: boolean;
+    /** Device preset */
+    device?: "desktop" | "mobile" | "tablet";
+    /** Extra delay in ms after page load (0-10000) */
+    delay?: number;
+    /** Custom CSS to inject */
+    css?: string;
+    /** Custom JavaScript to execute */
+    js?: string;
+    /** Render page in dark mode */
+    dark_mode?: boolean;
+    /** Image quality for JPEG/WebP (1-100) */
+    quality?: number;
+    /** Remove cookie banners and popups */
+    remove_popups?: boolean;
+    /** Block ads */
+    block_ads?: boolean;
+    /** CSS selector to capture specific element */
+    selector?: string;
+    /** Device scale factor / retina (0.5-3) */
+    device_scale_factor?: number;
+    /** Custom HTTP headers */
+    headers?: Record<string, string>;
+    /** Cookies to set */
+    cookies?: Array<{
+        name: string;
+        value: string;
+        domain?: string;
+        path?: string;
+        httpOnly?: boolean;
+        secure?: boolean;
+    }>;
+    /** Browser locale (e.g. "de-DE") */
+    locale?: string;
+    /** Browser timezone (e.g. "Europe/Berlin") */
+    timezone?: string;
+    /** Custom user agent string */
+    user_agent?: string;
+    /** Wait for this CSS selector to appear before capture */
+    wait_for_selector?: string;
+    /** Wait for network to become idle */
+    wait_for_network_idle?: boolean;
+    /** Auto-scroll page to trigger lazy-loaded content */
+    lazy_load?: boolean;
+    /** CSS selectors to hide (display: none) */
+    hide_selectors?: string[];
+    /** CSS selectors to remove from DOM */
+    remove_selectors?: string[];
+    /** Transparent background for PNG */
+    omit_background?: boolean;
+    /** Extract page text and return in response */
+    extract_text?: boolean;
+    /** Extract full HTML and return in response */
+    extract_html?: boolean;
+    /** Click this CSS selector before capture */
+    click_selector?: string;
+    /** Scroll to this CSS selector before capture */
+    scroll_to_selector?: string;
+    /** Return binary image data instead of CDN URL */
+    response_type?: "binary" | "url";
+    /** URL to receive async webhook with results */
+    webhook_url?: string;
+    /** Upload to your own S3 bucket */
+    s3_upload?: {
+        access_key_id: string;
+        secret_access_key: string;
+        bucket: string;
+        region: string;
+        endpoint?: string;
+        path?: string;
+        acl?: string;
+    };
+}
+export interface ScreenshotResponse {
+    url: string;
+    cached: boolean;
+    request_id: string;
+    response_time_ms?: number;
+    s3_key?: string;
+    s3_bucket?: string;
+    extracted_text?: string;
+    extracted_html?: string;
+}
+export interface AsyncResponse {
+    request_id: string;
+    status: "pending";
+    message: string;
+    status_url: string;
+}
+export interface BatchOptions extends Omit<ScreenshotOptions, "url" | "html" | "selector" | "response_type"> {
+    urls: string[];
+}
+export interface BatchResponse {
+    batch_id: string;
+    count: number;
+    succeeded: number;
+    failed: number;
+    response_time_ms: number;
+    results: Array<ScreenshotResponse & {
+        source_url: string;
+    }>;
+}
+export interface ErrorResponse {
+    error: string;
+    message: string;
+    details?: Record<string, string[]>;
+}
+export declare class SnapAPIError extends Error {
+    status: number;
+    error: string;
+    details?: Record<string, string[]>;
+    constructor(status: number, body: ErrorResponse);
+}
+export declare class SnapAPI {
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey: string, options?: {
+        baseUrl?: string;
+    });
+    /**
+     * Take a screenshot of a URL or HTML content.
+     */
+    screenshot(options: ScreenshotOptions): Promise<ScreenshotResponse>;
+    /**
+     * Take a screenshot and return raw binary image data.
+     */
+    screenshotBinary(options: Omit<ScreenshotOptions, "response_type">): Promise<ArrayBuffer>;
+    /**
+     * Capture screenshots of multiple URLs in one request.
+     */
+    batch(options: BatchOptions): Promise<BatchResponse>;
+    /**
+     * Check current usage and quota.
+     */
+    usage(): Promise<{
+        used: number;
+        limit: number;
+        plan: string;
+        period: string;
+    }>;
+    /**
+     * Check the status of an async webhook request.
+     */
+    status(requestId: string): Promise<Record<string, unknown>>;
+    private request;
+}
+export default SnapAPI;

package/dist/index.js

@@ -0,0 +1,76 @@
+export class SnapAPIError extends Error {
+    constructor(status, body) {
+        super(body.message);
+        this.name = "SnapAPIError";
+        this.status = status;
+        this.error = body.error;
+        this.details = body.details;
+    }
+}
+export class SnapAPI {
+    constructor(apiKey, options) {
+        this.apiKey = apiKey;
+        this.baseUrl = options?.baseUrl || "https://api.getsnap.dev";
+    }
+    /**
+     * Take a screenshot of a URL or HTML content.
+     */
+    async screenshot(options) {
+        return this.request("POST", "/v1/screenshot", options);
+    }
+    /**
+     * Take a screenshot and return raw binary image data.
+     */
+    async screenshotBinary(options) {
+        const response = await fetch(`${this.baseUrl}/v1/screenshot`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": this.apiKey,
+            },
+            body: JSON.stringify({ ...options, response_type: "binary" }),
+        });
+        if (!response.ok) {
+            const body = await response.json();
+            throw new SnapAPIError(response.status, body);
+        }
+        return response.arrayBuffer();
+    }
+    /**
+     * Capture screenshots of multiple URLs in one request.
+     */
+    async batch(options) {
+        return this.request("POST", "/v1/batch", options);
+    }
+    /**
+     * Check current usage and quota.
+     */
+    async usage() {
+        return this.request("GET", "/v1/usage");
+    }
+    /**
+     * Check the status of an async webhook request.
+     */
+    async status(requestId) {
+        return this.request("GET", `/v1/screenshot/${requestId}`);
+    }
+    async request(method, path, body) {
+        const options = {
+            method,
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": this.apiKey,
+            },
+        };
+        if (body && method !== "GET") {
+            options.body = JSON.stringify(body);
+        }
+        const response = await fetch(`${this.baseUrl}${path}`, options);
+        const data = await response.json();
+        if (!response.ok) {
+            throw new SnapAPIError(response.status, data);
+        }
+        return data;
+    }
+}
+export default SnapAPI;

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "getsnap",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for SnapAPI - Screenshot & PDF API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["screenshot", "api", "pdf", "webpage", "capture", "snapapi"],
+  "author": "SnapAPI",
+  "license": "MIT",
+  "homepage": "https://getsnap.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rokas-kve/snapapi-sdk-node"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}