snapapi-sdk 1.3.0

package/README.md

@@ -0,0 +1,131 @@
+# snapapi-js
+
+Official Node.js SDK for [SnapAPI](https://snapapi.tech) — capture any website as an image.
+
+Zero dependencies. Uses native `fetch` (Node 18+).
+
+## Install
+
+```bash
+npm install snapapi-js
+```
+
+## Quick Start
+
+```js
+const SnapAPI = require('snapapi-js');
+const fs = require('fs');
+
+const snap = new SnapAPI('snap_your_key_here');
+
+// Basic screenshot
+const image = await snap.screenshot('example.com');
+fs.writeFileSync('screenshot.png', image);
+
+// With options
+const webp = await snap.screenshot('example.com', {
+  format: 'webp',
+  darkMode: true,
+  fullPage: true,
+});
+fs.writeFileSync('screenshot.webp', webp);
+
+// Mobile screenshot (iPhone 14)
+const mobile = await snap.screenshot('example.com', { device: 'iphone14' });
+
+// Capture a specific element
+const header = await snap.screenshot('example.com', { selector: 'header' });
+
+// Get structured page data (great for AI agents)
+const meta = await snap.screenshot('example.com', { meta: true });
+console.log(meta.title, meta.description);
+console.log(meta.headings);  // [{level: 1, text: "..."}, ...]
+console.log(meta.links);     // [{text: "...", href: "..."}, ...]
+console.log(meta.text);      // Extracted visible text (first 2000 chars)
+
+// Check your usage
+const usage = await snap.usage();
+console.log(`${usage.usage.count} screenshots this month`);
+```
+
+## Screenshot Options
+
+| Option     | Type    | Description                          |
+|------------|---------|--------------------------------------|
+| `width`    | number  | Viewport width in pixels             |
+| `height`   | number  | Viewport height in pixels            |
+| `format`   | string  | `"png"`, `"jpeg"`, or `"webp"`       |
+| `quality`  | number  | Image quality 1-100 (jpeg/webp only) |
+| `fullPage` | boolean | Capture the full scrollable page     |
+| `delay`    | number  | Wait ms before capturing             |
+| `darkMode` | boolean | Emulate dark color scheme            |
+| `blockAds` | boolean | Block common ad networks             |
+| `cache`    | boolean | Use cached result if available       |
+| `selector` | string  | CSS selector to capture              |
+| `device`   | string  | Device preset: `"iphone14"`, `"pixel7"`, `"ipad"`, `"desktop"`, etc. |
+| `meta`     | boolean | Return page metadata as JSON         |
+
+## Error Handling
+
+```js
+const { SnapAPIError } = require('snapapi-js');
+
+try {
+  const image = await snap.screenshot('example.com');
+} catch (err) {
+  if (err instanceof SnapAPIError) {
+    console.error(err.status, err.message);
+  }
+}
+```
+
+## Scheduled Monitors
+
+```js
+// Create a monitor — captures every 15 minutes
+const monitor = await snap.createMonitor({
+  url: 'https://example.com',
+  name: 'Homepage',
+  interval_minutes: 15,
+  params: { format: 'webp', fullPage: true },
+  webhook_url: 'https://your-app.com/webhook',
+});
+
+// List all monitors
+const monitors = await snap.listMonitors();
+
+// Pause / resume
+await snap.updateMonitor(monitor.id, { status: 'paused' });
+await snap.updateMonitor(monitor.id, { status: 'active' });
+
+// Browse snapshots
+const { snapshots } = await snap.listSnapshots(monitor.id, { limit: 10 });
+
+// Download a snapshot image
+const image = await snap.getSnapshot(monitor.id, snapshots[0].id);
+fs.writeFileSync('snapshot.webp', image);
+
+// Delete a monitor (cascades to snapshots)
+await snap.deleteMonitor(monitor.id);
+```
+
+> Monitors require **Starter** tier or above. See [pricing](https://snapapi.tech/#pricing) for limits.
+
+## Account Management
+
+```js
+// Full account info
+const account = await snap.account();
+
+// Update settings
+await snap.updateSettings({ name: 'My App' });
+
+// Sign up (no API key needed)
+const snap = new SnapAPI('placeholder');
+const result = await snap.signup('you@example.com');
+console.log(result.key); // Your new API key
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,177 @@
+declare class SnapAPIError extends Error {
+  name: 'SnapAPIError';
+  status: number;
+  body: unknown;
+  constructor(message: string, status: number, body: unknown);
+}
+
+interface SnapAPIOptions {
+  baseUrl?: string;
+}
+
+interface ScreenshotOptions {
+  width?: number;
+  height?: number;
+  format?: 'png' | 'jpeg' | 'webp';
+  quality?: number;
+  fullPage?: boolean;
+  delay?: number;
+  darkMode?: boolean;
+  blockAds?: boolean;
+  cache?: boolean;
+  selector?: string;
+  device?: 'iphone14' | 'iphone14pro' | 'iphone15' | 'pixel7' | 'pixel8' | 'galaxys23' | 'ipad' | 'ipadpro' | 'desktop';
+  meta?: boolean;
+}
+
+interface MetadataResult {
+  url: string;
+  title: string;
+  description: string;
+  og_title: string;
+  og_image: string;
+  og_type: string;
+  favicon: string;
+  viewport: string;
+  canonical: string;
+  language: string;
+  headings: Array<{ level: number; text: string }>;
+  links: Array<{ text: string; href: string }>;
+}
+
+interface RenderOptions {
+  width?: number;
+  height?: number;
+  format?: 'png' | 'jpeg' | 'webp';
+  quality?: number;
+}
+
+interface UsageResponse {
+  tier: string;
+  usage: {
+    month: string;
+    count: number;
+  };
+  limits: Record<string, unknown>;
+}
+
+interface SignupResponse {
+  key: string;
+  tier: string;
+  limit: number;
+}
+
+interface AccountSettings {
+  name?: string;
+  allowed_domains?: string[];
+}
+
+interface MonitorParams {
+  url: string;
+  name?: string;
+  interval_minutes: number;
+  params?: Partial<ScreenshotOptions>;
+  webhook_url?: string;
+}
+
+interface MonitorUpdateParams {
+  name?: string;
+  interval_minutes?: number;
+  status?: 'active' | 'paused';
+  params?: Partial<ScreenshotOptions>;
+  webhook_url?: string;
+}
+
+interface Monitor {
+  id: string;
+  name: string;
+  url: string;
+  interval_minutes: number;
+  status: string;
+  params: Record<string, unknown>;
+  webhook_url: string | null;
+  created_at: string;
+  last_run: string | null;
+  next_run: string | null;
+  run_count: number;
+  error_count: number;
+  last_error: string | null;
+}
+
+interface Snapshot {
+  id: string;
+  monitor_id: string;
+  taken_at: string;
+  file_size: number;
+  status: string;
+  error: string | null;
+  meta: Record<string, unknown>;
+}
+
+interface SnapshotListResponse {
+  snapshots: Snapshot[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+declare class SnapAPI {
+  constructor(apiKey: string, options?: SnapAPIOptions);
+
+  /**
+   * Capture a screenshot of a URL.
+   * Returns a Buffer (image) when meta is false/omitted,
+   * or a metadata object when meta is true.
+   */
+  screenshot(url: string, options?: ScreenshotOptions & { meta?: false }): Promise<Buffer>;
+  screenshot(url: string, options: ScreenshotOptions & { meta: true }): Promise<Record<string, unknown>>;
+
+  /**
+   * Extract metadata from a URL without taking a screenshot.
+   * Available on all plans.
+   */
+  metadata(url: string): Promise<MetadataResult>;
+
+  /**
+   * Render raw HTML to an image. Requires Starter tier or above.
+   */
+  render(html: string, options?: RenderOptions): Promise<Buffer>;
+
+  /** Get current usage stats for this API key. */
+  usage(): Promise<UsageResponse>;
+
+  /** Get full account information. */
+  account(): Promise<Record<string, unknown>>;
+
+  /** Update account settings. */
+  updateSettings(settings: AccountSettings): Promise<Record<string, unknown>>;
+
+  /** Sign up for a free SnapAPI account. Does not require an API key. */
+  signup(email: string): Promise<SignupResponse>;
+
+  // ─── Monitors (Scheduled Screenshots) ───
+
+  /** Create a new monitor. Requires Starter tier or above. */
+  createMonitor(params: MonitorParams): Promise<Monitor>;
+
+  /** List all monitors for this API key. */
+  listMonitors(): Promise<Monitor[]>;
+
+  /** Get a single monitor by ID. */
+  getMonitor(id: string): Promise<Monitor>;
+
+  /** Update a monitor (name, interval, status, params, webhook_url). */
+  updateMonitor(id: string, updates: MonitorUpdateParams): Promise<Monitor>;
+
+  /** Delete a monitor and all its snapshots. */
+  deleteMonitor(id: string): Promise<void>;
+
+  /** List snapshots for a monitor. */
+  listSnapshots(monitorId: string, options?: { limit?: number; offset?: number }): Promise<SnapshotListResponse>;
+
+  /** Download a specific snapshot image. */
+  getSnapshot(monitorId: string, snapshotId: string): Promise<Buffer>;
+}
+
+export = SnapAPI;
+export { SnapAPIError };

package/index.js

@@ -0,0 +1,300 @@
+'use strict';
+
+const DEFAULT_BASE_URL = 'https://snapapi.tech';
+
+class SnapAPIError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = 'SnapAPIError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function toSnakeCase(str) {
+  return str.replace(/[A-Z]/g, (ch) => '_' + ch.toLowerCase());
+}
+
+class SnapAPI {
+  /**
+   * @param {string} apiKey - Your SnapAPI key (e.g. "snap_...")
+   * @param {object} [options]
+   * @param {string} [options.baseUrl] - API base URL
+   */
+  constructor(apiKey, options = {}) {
+    if (!apiKey || typeof apiKey !== 'string') {
+      throw new SnapAPIError('API key is required', 0, null);
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+  }
+
+  /**
+   * Internal request helper.
+   * @private
+   */
+  async _request(method, path, { query, json, needsAuth = true } = {}) {
+    let url = `${this.baseUrl}${path}`;
+
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== null) {
+          params.set(k, String(v));
+        }
+      }
+      const qs = params.toString();
+      if (qs) url += '?' + qs;
+    }
+
+    const headers = {};
+    if (needsAuth) {
+      headers['x-api-key'] = this.apiKey;
+    }
+
+    const fetchOptions = { method, headers };
+
+    if (json) {
+      headers['content-type'] = 'application/json';
+      fetchOptions.body = JSON.stringify(json);
+    }
+
+    const res = await fetch(url, fetchOptions);
+
+    if (!res.ok) {
+      let body = null;
+      let message = `SnapAPI request failed: ${res.status} ${res.statusText}`;
+      try {
+        body = await res.json();
+        if (body.error) message = body.error;
+        else if (body.message) message = body.message;
+      } catch {
+        // response wasn't JSON
+      }
+      throw new SnapAPIError(message, res.status, body);
+    }
+
+    return res;
+  }
+
+  /**
+   * Capture a screenshot of a URL.
+   *
+   * @param {string} url - The webpage URL to capture
+   * @param {object} [options]
+   * @param {number}  [options.width]     - Viewport width in px
+   * @param {number}  [options.height]    - Viewport height in px
+   * @param {string}  [options.format]    - "png" | "jpeg" | "webp"
+   * @param {number}  [options.quality]   - Image quality 1-100 (jpeg/webp)
+   * @param {boolean} [options.fullPage]  - Capture full scrollable page
+   * @param {number}  [options.delay]     - Wait ms before capture
+   * @param {boolean} [options.darkMode]  - Emulate dark color scheme
+   * @param {boolean} [options.blockAds]  - Block common ad networks
+   * @param {boolean} [options.cache]     - Use cached result if available
+   * @param {string}  [options.selector]  - CSS selector to capture
+   * @param {string}  [options.device]    - Device preset: "iphone14", "pixel7", "ipad", "desktop", etc.
+   * @param {boolean} [options.meta]      - Return page metadata instead of image
+   * @returns {Promise<Buffer|object>} Image buffer, or metadata object when meta=true
+   */
+  async screenshot(url, options = {}) {
+    if (!url || typeof url !== 'string') {
+      throw new SnapAPIError('URL is required', 0, null);
+    }
+
+    const query = { url };
+
+    for (const [key, value] of Object.entries(options)) {
+      if (value === undefined || value === null) continue;
+      const snakeKey = toSnakeCase(key);
+      query[snakeKey] = value;
+    }
+
+    const wantMeta = !!options.meta;
+
+    const res = await this._request('GET', '/v1/screenshot', { query });
+
+    if (wantMeta) {
+      return res.json();
+    }
+
+    const arrayBuffer = await res.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+
+  /**
+   * Extract metadata from a URL without taking a screenshot.
+   * Returns title, description, OG tags, favicon, headings, links, and more.
+   * Available on all plans.
+   * @param {string} url - The webpage URL to extract metadata from
+   * @returns {Promise<object>}
+   */
+  async metadata(url) {
+    if (!url || typeof url !== 'string') {
+      throw new SnapAPIError('URL is required', 0, null);
+    }
+    const res = await this._request('GET', '/v1/metadata', { query: { url } });
+    return res.json();
+  }
+
+  /**
+   * Render raw HTML to an image (PNG, JPEG, or WebP).
+   * Perfect for OG cards, email previews, and dashboard exports.
+   * Requires Starter tier or above.
+   * @param {string} html - Full HTML string to render (max 2MB)
+   * @param {object} [options]
+   * @param {number} [options.width]   - Viewport width in px (default 1200)
+   * @param {number} [options.height]  - Viewport height in px (default 630)
+   * @param {string} [options.format]  - "png" | "jpeg" | "webp" (default "png")
+   * @param {number} [options.quality] - Image quality 1-100 for jpeg/webp (default 90)
+   * @returns {Promise<Buffer>}
+   */
+  async render(html, options = {}) {
+    if (!html || typeof html !== 'string') {
+      throw new SnapAPIError('html is required', 0, null);
+    }
+    const res = await this._request('POST', '/v1/render', {
+      json: {
+        html,
+        width: options.width || 1200,
+        height: options.height || 630,
+        format: options.format || 'png',
+        quality: options.quality || 90,
+      },
+    });
+    const arrayBuffer = await res.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+
+  /**
+   * Get current usage stats for this API key.
+   * @returns {Promise<{ tier: string, usage: { month: string, count: number }, limits: object }>}
+   */
+  async usage() {
+    const res = await this._request('GET', '/v1/usage');
+    return res.json();
+  }
+
+  /**
+   * Get full account information.
+   * @returns {Promise<object>}
+   */
+  async account() {
+    const res = await this._request('GET', '/v1/account');
+    return res.json();
+  }
+
+  /**
+   * Update account settings.
+   * @param {object} settings
+   * @param {string} [settings.name]
+   * @param {string[]} [settings.allowed_domains]
+   * @returns {Promise<object>}
+   */
+  async updateSettings(settings) {
+    if (!settings || typeof settings !== 'object') {
+      throw new SnapAPIError('Settings object is required', 0, null);
+    }
+    const res = await this._request('PATCH', '/v1/account', { json: settings });
+    return res.json();
+  }
+
+  // ─── Monitors (Scheduled Screenshots) ───
+
+  /**
+   * Create a new monitor.
+   * @param {object} params
+   * @param {string}  params.url             - URL to monitor
+   * @param {string}  [params.name]          - Display name
+   * @param {number}  params.interval_minutes - Capture interval in minutes
+   * @param {object}  [params.params]        - Screenshot options (width, height, format, etc.)
+   * @param {string}  [params.webhook_url]   - Webhook URL for notifications
+   * @returns {Promise<object>}
+   */
+  async createMonitor(params) {
+    const res = await this._request('POST', '/v1/monitors', { json: params });
+    return res.json();
+  }
+
+  /**
+   * List all monitors for this API key.
+   * @returns {Promise<object[]>}
+   */
+  async listMonitors() {
+    const res = await this._request('GET', '/v1/monitors');
+    return res.json();
+  }
+
+  /**
+   * Get a single monitor by ID.
+   * @param {string} id
+   * @returns {Promise<object>}
+   */
+  async getMonitor(id) {
+    const res = await this._request('GET', `/v1/monitors/${id}`);
+    return res.json();
+  }
+
+  /**
+   * Update a monitor.
+   * @param {string} id
+   * @param {object} updates - Fields to update (name, interval_minutes, status, params, webhook_url)
+   * @returns {Promise<object>}
+   */
+  async updateMonitor(id, updates) {
+    const res = await this._request('PATCH', `/v1/monitors/${id}`, { json: updates });
+    return res.json();
+  }
+
+  /**
+   * Delete a monitor and all its snapshots.
+   * @param {string} id
+   * @returns {Promise<void>}
+   */
+  async deleteMonitor(id) {
+    await this._request('DELETE', `/v1/monitors/${id}`);
+  }
+
+  /**
+   * List snapshots for a monitor.
+   * @param {string} monitorId
+   * @param {object} [options]
+   * @param {number} [options.limit]  - Max results (default 50)
+   * @param {number} [options.offset] - Pagination offset
+   * @returns {Promise<object>}
+   */
+  async listSnapshots(monitorId, options = {}) {
+    const res = await this._request('GET', `/v1/monitors/${monitorId}/snapshots`, { query: options });
+    return res.json();
+  }
+
+  /**
+   * Download a specific snapshot image.
+   * @param {string} monitorId
+   * @param {string} snapshotId
+   * @returns {Promise<Buffer>}
+   */
+  async getSnapshot(monitorId, snapshotId) {
+    const res = await this._request('GET', `/v1/monitors/${monitorId}/snapshots/${snapshotId}`);
+    const arrayBuffer = await res.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+
+  /**
+   * Sign up for a free SnapAPI account. Does not require an API key.
+   * @param {string} email
+   * @returns {Promise<{ key: string, tier: string, limit: number }>}
+   */
+  async signup(email) {
+    if (!email || typeof email !== 'string') {
+      throw new SnapAPIError('Email is required', 0, null);
+    }
+    const res = await this._request('POST', '/v1/signup', {
+      json: { email },
+      needsAuth: false,
+    });
+    return res.json();
+  }
+}
+
+module.exports = SnapAPI;
+module.exports.SnapAPIError = SnapAPIError;

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "snapapi-sdk",
+  "version": "1.3.0",
+  "description": "Official Node.js SDK for SnapAPI — screenshot, metadata extraction, and HTML rendering",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "keywords": [
+    "screenshot",
+    "api",
+    "webpage-capture",
+    "snapapi"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}