grabshot-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GrabShot
+
+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,73 @@
+# grabshot
+
+Capture website screenshots with a simple Node.js API. No headless browser required.
+
+## Install
+
+```bash
+npm install grabshot-api
+```
+
+## Quick Start
+
+```js
+const GrabShot = require('grabshot-api');
+const fs = require('fs');
+
+const client = new GrabShot('your-api-key');
+
+// Take a screenshot
+const image = await client.screenshot('https://github.com');
+fs.writeFileSync('github.png', image);
+
+// Full page capture
+const full = await client.screenshot('https://example.com', {
+  fullPage: true,
+  width: 1440,
+  format: 'webp'
+});
+
+// Custom viewport (mobile)
+const mobile = await client.screenshot('https://example.com', {
+  width: 375,
+  height: 812,
+  format: 'jpeg'
+});
+```
+
+## API
+
+### `new GrabShot(apiKey, options?)`
+
+- `apiKey` - Your API key ([get one free](https://grabshot.dev))
+- `options.baseUrl` - Custom API URL (default: `https://grabshot.dev`)
+
+### `.screenshot(url, options?)`
+
+Returns a `Promise<Buffer>` with the screenshot image.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `width` | number | 1440 | Viewport width in pixels |
+| `height` | number | 900 | Viewport height in pixels |
+| `format` | string | `'png'` | Output format: `png`, `jpeg`, `webp` |
+| `fullPage` | boolean | `false` | Capture full scrollable page |
+| `delay` | number | `0` | Wait ms before capture |
+| `aiCleanup` | boolean | `false` | AI-powered cleanup (paid plans) |
+
+### `.ogImage(url, options?)`
+
+Generate an Open Graph image for a URL. Returns `Promise<Buffer>`.
+
+## Pricing
+
+- **Free**: 25 screenshots/month
+- **Starter** ($9/mo): 2,500 screenshots/month + AI cleanup
+- **Pro** ($29/mo): 15,000 screenshots/month + priority
+- **Business** ($79/mo): 50,000 screenshots/month + dedicated support
+
+[Sign up free at grabshot.dev](https://grabshot.dev)
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,19 @@
+declare class GrabShot {
+  constructor(apiKey: string, options?: { baseUrl?: string });
+
+  screenshot(url: string, options?: {
+    width?: number;
+    height?: number;
+    format?: 'png' | 'jpeg' | 'webp';
+    fullPage?: boolean;
+    delay?: number;
+    aiCleanup?: boolean;
+  }): Promise<Buffer>;
+
+  ogImage(url: string, options?: {
+    template?: string;
+  }): Promise<Buffer>;
+}
+
+export = GrabShot;
+export { GrabShot };

package/index.js

@@ -0,0 +1,91 @@
+const https = require('https');
+const http = require('http');
+
+class GrabShot {
+  /**
+   * @param {string} apiKey - Your GrabShot API key (get one free at grabshot.dev)
+   * @param {object} [options]
+   * @param {string} [options.baseUrl] - API base URL (default: https://grabshot.dev)
+   */
+  constructor(apiKey, options = {}) {
+    if (!apiKey) throw new Error('API key required. Get one free at https://grabshot.dev');
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl || 'https://grabshot.dev').replace(/\/$/, '');
+  }
+
+  /**
+   * Capture a screenshot of a URL
+   * @param {string} url - URL to screenshot
+   * @param {object} [options]
+   * @param {number} [options.width=1440] - Viewport width
+   * @param {number} [options.height=900] - Viewport height
+   * @param {string} [options.format=png] - Output format (png, jpeg, webp)
+   * @param {boolean} [options.fullPage=false] - Capture full scrollable page
+   * @param {number} [options.delay=0] - Wait ms before capture
+   * @param {boolean} [options.aiCleanup=false] - AI-powered cleanup (paid plans)
+   * @returns {Promise<Buffer>} Screenshot image buffer
+   */
+  async screenshot(url, options = {}) {
+    const params = new URLSearchParams({
+      url,
+      apiKey: this.apiKey,
+      width: String(options.width || 1440),
+      height: String(options.height || 900),
+      format: options.format || 'png',
+    });
+
+    if (options.fullPage) params.set('fullPage', 'true');
+    if (options.delay) params.set('delay', String(options.delay));
+    if (options.aiCleanup) params.set('aiCleanup', 'true');
+
+    const reqUrl = `${this.baseUrl}/v1/screenshot?${params}`;
+    return this._request(reqUrl);
+  }
+
+  /**
+   * Generate an OG image for a URL
+   * @param {string} url - URL to generate OG image for
+   * @param {object} [options]
+   * @param {string} [options.template] - OG template name
+   * @returns {Promise<Buffer>} OG image buffer
+   */
+  async ogImage(url, options = {}) {
+    const params = new URLSearchParams({
+      url,
+      apiKey: this.apiKey,
+    });
+    if (options.template) params.set('template', options.template);
+
+    const reqUrl = `${this.baseUrl}/v1/og?${params}`;
+    return this._request(reqUrl);
+  }
+
+  /** @private */
+  _request(url) {
+    return new Promise((resolve, reject) => {
+      const mod = url.startsWith('https') ? https : http;
+      mod.get(url, (res) => {
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          return this._request(res.headers.location).then(resolve, reject);
+        }
+        if (res.statusCode !== 200) {
+          let body = '';
+          res.on('data', (c) => body += c);
+          res.on('end', () => {
+            try { body = JSON.parse(body); } catch {}
+            reject(new Error(body.error || body.message || `HTTP ${res.statusCode}`));
+          });
+          return;
+        }
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => resolve(Buffer.concat(chunks)));
+        res.on('error', reject);
+      }).on('error', reject);
+    });
+  }
+}
+
+module.exports = GrabShot;
+module.exports.default = GrabShot;
+module.exports.GrabShot = GrabShot;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "grabshot-sdk",
+  "version": "1.0.0",
+  "description": "Capture website screenshots with a simple API. Free tier included.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "keywords": [
+    "screenshot",
+    "website screenshot",
+    "webpage capture",
+    "url to image",
+    "screenshot api",
+    "web capture",
+    "html to image",
+    "page screenshot",
+    "og image",
+    "social preview",
+    "puppeteer alternative",
+    "headless browser",
+    "website thumbnail"
+  ],
+  "author": "GrabShot <hello@grabshot.dev>",
+  "license": "MIT",
+  "homepage": "https://grabshot.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aitaskorchestra/grabshot-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/aitaskorchestra/grabshot-sdk/issues"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ]
+}