renderscreenshot 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RenderScreenshot
+
+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,366 @@
+# RenderScreenshot Node.js SDK
+
+Official Node.js/TypeScript SDK for [RenderScreenshot](https://renderscreenshot.com) - A developer-friendly screenshot API.
+
+## Installation
+
+```bash
+npm install renderscreenshot
+```
+
+## Quick Start
+
+```typescript
+import { Client, TakeOptions } from 'renderscreenshot';
+
+// Initialize the client
+const client = new Client('rs_live_xxxxx');
+
+// Take a screenshot
+const image = await client.take(
+  TakeOptions.url('https://example.com').preset('og_card')
+);
+
+// Save to file
+import { writeFile } from 'fs/promises';
+await writeFile('screenshot.png', image);
+```
+
+## Features
+
+- **Full TypeScript support** - Complete type definitions for all options
+- **Fluent builder pattern** - Chain methods for clean, readable code
+- **All screenshot options** - Viewport, format, blocking, PDF, and more
+- **Batch processing** - Capture multiple screenshots in one request
+- **Cache management** - Retrieve, delete, and purge cached screenshots
+- **Webhook verification** - Secure webhook signature verification
+- **Signed URLs** - Generate secure URLs for public embedding
+
+## Usage
+
+### Basic Screenshot
+
+```typescript
+import { Client, TakeOptions } from 'renderscreenshot';
+
+const client = new Client('rs_live_xxxxx');
+
+// Take a PNG screenshot
+const image = await client.take(
+  TakeOptions.url('https://example.com')
+    .width(1200)
+    .height(630)
+    .format('png')
+);
+```
+
+### Using Presets
+
+```typescript
+// OG Card preset (1200x630)
+const ogCard = await client.take(
+  TakeOptions.url('https://example.com').preset('og_card')
+);
+
+// Twitter Card preset
+const twitterCard = await client.take(
+  TakeOptions.url('https://example.com').preset('twitter_card')
+);
+
+// Full page screenshot
+const fullPage = await client.take(
+  TakeOptions.url('https://example.com').preset('full_page')
+);
+```
+
+### Device Emulation
+
+```typescript
+// iPhone 14 Pro
+const mobile = await client.take(
+  TakeOptions.url('https://example.com').device('iphone_14_pro')
+);
+
+// iPad Pro
+const tablet = await client.take(
+  TakeOptions.url('https://example.com').device('ipad_pro_12')
+);
+```
+
+### Content Blocking
+
+```typescript
+const image = await client.take(
+  TakeOptions.url('https://example.com')
+    .blockAds()
+    .blockTrackers()
+    .blockCookieBanners()
+    .blockChatWidgets()
+);
+```
+
+### Dark Mode & Browser Emulation
+
+```typescript
+const image = await client.take(
+  TakeOptions.url('https://example.com')
+    .darkMode()
+    .timezone('America/New_York')
+    .locale('en-US')
+);
+```
+
+### PDF Generation
+
+```typescript
+const pdf = await client.take(
+  TakeOptions.url('https://example.com/report')
+    .format('pdf')
+    .pdfPaperSize('a4')
+    .pdfLandscape()
+    .pdfPrintBackground()
+    .pdfMargin('1in')
+);
+```
+
+### JSON Response
+
+```typescript
+const response = await client.takeJson(
+  TakeOptions.url('https://example.com').preset('og_card')
+);
+
+console.log(response.url);      // CDN URL
+console.log(response.width);    // 1200
+console.log(response.height);   // 630
+console.log(response.cached);   // true/false
+```
+
+### Signed URLs for Embedding
+
+Generate secure URLs for public `<img>` tags without exposing your API key:
+
+```typescript
+const signedUrl = client.generateUrl(
+  TakeOptions.url('https://example.com').preset('og_card'),
+  new Date(Date.now() + 24 * 60 * 60 * 1000) // Expires in 24 hours
+);
+
+// Use in HTML: <img src="${signedUrl}" />
+```
+
+### Batch Processing
+
+```typescript
+// Simple batch with same options
+const results = await client.batch(
+  ['https://example1.com', 'https://example2.com', 'https://example3.com'],
+  TakeOptions.url('').preset('og_card')
+);
+
+// Advanced batch with per-URL options
+const results = await client.batch([
+  { url: 'https://example1.com', options: { width: 1200 } },
+  { url: 'https://example2.com', options: { preset: 'full_page' } },
+  { url: 'https://example3.com', options: { darkMode: true } },
+]);
+
+// Check batch status
+const status = await client.getBatch('batch_abc123');
+```
+
+### Cache Management
+
+```typescript
+// Get cached screenshot
+const cached = await client.cache.get('cache_xyz789');
+
+// Delete single entry
+await client.cache.delete('cache_xyz789');
+
+// Bulk purge by keys
+await client.cache.purge(['cache_abc', 'cache_def']);
+
+// Purge by URL pattern
+await client.cache.purgeUrl('https://mysite.com/blog/*');
+
+// Purge entries older than a date
+await client.cache.purgeBefore(new Date('2024-01-01'));
+```
+
+### Webhook Verification
+
+```typescript
+import { verifyWebhook, parseWebhook } from 'renderscreenshot';
+
+// In your webhook handler
+const signature = req.headers['x-webhook-signature'];
+const timestamp = req.headers['x-webhook-timestamp'];
+const payload = JSON.stringify(req.body);
+
+if (verifyWebhook(payload, signature, timestamp, process.env.WEBHOOK_SECRET)) {
+  const event = parseWebhook(req.body);
+
+  if (event.type === 'screenshot.completed') {
+    console.log('Screenshot ready:', event.data.response?.url);
+  }
+} else {
+  res.status(401).send('Invalid signature');
+}
+```
+
+## All Screenshot Options
+
+### Target
+
+| Method | Description |
+|--------|-------------|
+| `url(string)` | URL to capture |
+| `html(string)` | HTML content to render |
+
+### Viewport
+
+| Method | Description |
+|--------|-------------|
+| `width(number)` | Viewport width in pixels |
+| `height(number)` | Viewport height in pixels |
+| `scale(number)` | Device scale factor (1-3) |
+| `mobile(boolean)` | Enable mobile emulation |
+
+### Capture
+
+| Method | Description |
+|--------|-------------|
+| `fullPage(boolean)` | Capture full scrollable page |
+| `element(string)` | CSS selector for element capture |
+| `format(string)` | `png`, `jpeg`, `webp`, `pdf` |
+| `quality(number)` | JPEG/WebP quality (1-100) |
+
+### Wait Conditions
+
+| Method | Description |
+|--------|-------------|
+| `waitFor(string)` | `load`, `networkidle`, `domcontentloaded` |
+| `delay(number)` | Additional delay in milliseconds |
+| `waitForSelector(string)` | Wait for CSS selector to appear |
+| `waitForTimeout(number)` | Maximum wait time in ms |
+
+### Presets & Devices
+
+| Method | Description |
+|--------|-------------|
+| `preset(string)` | `og_card`, `twitter_card`, `full_page`, etc. |
+| `device(string)` | `iphone_14_pro`, `pixel_7`, `ipad_pro_12`, etc. |
+
+### Content Blocking
+
+| Method | Description |
+|--------|-------------|
+| `blockAds(boolean)` | Block ad network domains |
+| `blockTrackers(boolean)` | Block analytics/tracking |
+| `blockCookieBanners(boolean)` | Auto-dismiss cookie popups |
+| `blockChatWidgets(boolean)` | Block chat widgets |
+| `blockUrls(string[])` | Block URLs matching patterns |
+| `blockResources(string[])` | Block resource types |
+
+### Browser Emulation
+
+| Method | Description |
+|--------|-------------|
+| `darkMode(boolean)` | Enable prefers-color-scheme: dark |
+| `reducedMotion(boolean)` | Enable prefers-reduced-motion |
+| `mediaType(string)` | `screen` or `print` |
+| `userAgent(string)` | Custom user agent |
+| `timezone(string)` | IANA timezone |
+| `locale(string)` | BCP 47 locale |
+| `geolocation(lat, lng, accuracy)` | Spoof geolocation |
+
+### Network
+
+| Method | Description |
+|--------|-------------|
+| `headers(object)` | Custom HTTP headers |
+| `cookies(array)` | Cookies to set |
+| `authBasic(user, pass)` | HTTP Basic authentication |
+| `authBearer(token)` | Bearer token authentication |
+| `bypassCsp(boolean)` | Bypass Content Security Policy |
+
+### Cache
+
+| Method | Description |
+|--------|-------------|
+| `cacheTtl(number)` | Cache TTL in seconds |
+| `cacheRefresh(boolean)` | Force cache refresh |
+
+### PDF Options
+
+| Method | Description |
+|--------|-------------|
+| `pdfPaperSize(string)` | `a4`, `letter`, `legal`, etc. |
+| `pdfWidth(string)` | Custom width (CSS units) |
+| `pdfHeight(string)` | Custom height (CSS units) |
+| `pdfLandscape(boolean)` | Landscape orientation |
+| `pdfMargin(string)` | Uniform margin |
+| `pdfScale(number)` | Scale factor (0.1-2.0) |
+| `pdfPrintBackground(boolean)` | Include backgrounds |
+| `pdfPageRanges(string)` | Page ranges |
+| `pdfHeader(string)` | Header HTML template |
+| `pdfFooter(string)` | Footer HTML template |
+
+### Storage (BYOS)
+
+| Method | Description |
+|--------|-------------|
+| `storageEnabled(boolean)` | Upload to custom storage |
+| `storagePath(string)` | Path template |
+| `storageAcl(string)` | `public-read` or `private` |
+
+## Error Handling
+
+```typescript
+import { RenderScreenshotError } from 'renderscreenshot';
+
+try {
+  const image = await client.take(TakeOptions.url('https://example.com'));
+} catch (error) {
+  if (error instanceof RenderScreenshotError) {
+    console.error('HTTP Status:', error.httpStatus);
+    console.error('Error Code:', error.code);
+    console.error('Message:', error.message);
+    console.error('Retryable:', error.retryable);
+
+    if (error.retryAfter) {
+      console.log(`Retry after ${error.retryAfter} seconds`);
+    }
+  }
+}
+```
+
+### Error Codes
+
+| Code | HTTP | Retryable | Description |
+|------|------|-----------|-------------|
+| `invalid_request` | 400 | No | Malformed request |
+| `invalid_url` | 400 | No | Invalid URL provided |
+| `unauthorized` | 401 | No | Invalid API key |
+| `forbidden` | 403 | No | Access denied |
+| `not_found` | 404 | No | Resource not found |
+| `rate_limited` | 429 | Yes | Rate limit exceeded |
+| `timeout` | 408 | Yes | Screenshot timed out |
+| `render_failed` | 500 | Yes | Browser rendering failed |
+| `internal_error` | 500 | Yes | Internal server error |
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- Native `fetch` support (built into Node.js 18+)
+
+## License
+
+MIT
+
+## Links
+
+- [Documentation](https://renderscreenshot.com/docs)
+- [API Reference](https://renderscreenshot.com/docs/endpoints/post-screenshot)
+- [GitHub Issues](https://github.com/Render-Screenshot/rs-node/issues)

package/dist/cjs/cache.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheManager = void 0;
+/**
+ * Cache management methods for RenderScreenshot
+ */
+class CacheManager {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get a cached screenshot by its cache key
+     *
+     * @param key - The cache key returned in X-Cache-Key header
+     * @returns Buffer containing the screenshot, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const image = await client.cache.get('cache_xyz789');
+     * if (image) {
+     *   await fs.writeFile('cached.png', image);
+     * }
+     * ```
+     */
+    async get(key) {
+        try {
+            return await this.client.request('GET', `/cache/${key}`, {
+                responseType: 'buffer',
+            });
+        }
+        catch (error) {
+            // Return null for 404 errors
+            if (error !== null &&
+                typeof error === 'object' &&
+                'httpStatus' in error &&
+                error.httpStatus === 404) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Delete a single cache entry
+     *
+     * @param key - The cache key to delete
+     * @returns true if deleted, false if not found
+     *
+     * @example
+     * ```typescript
+     * const deleted = await client.cache.delete('cache_xyz789');
+     * ```
+     */
+    async delete(key) {
+        const response = await this.client.request('DELETE', `/cache/${key}`);
+        return response.deleted;
+    }
+    /**
+     * Bulk purge cache entries by keys
+     *
+     * @param keys - Array of cache keys to purge
+     * @returns Purge result with count and keys
+     *
+     * @example
+     * ```typescript
+     * const result = await client.cache.purge(['cache_abc', 'cache_def']);
+     * console.log(`Purged ${result.purged} entries`);
+     * ```
+     */
+    async purge(keys) {
+        return this.client.request('POST', '/cache/purge', {
+            body: { keys },
+        });
+    }
+    /**
+     * Purge cache entries matching a URL pattern
+     *
+     * @param pattern - Glob pattern to match source URLs (e.g., "https://mysite.com/*")
+     * @returns Purge result with count
+     *
+     * @example
+     * ```typescript
+     * const result = await client.cache.purgeUrl('https://mysite.com/blog/*');
+     * ```
+     */
+    async purgeUrl(pattern) {
+        return this.client.request('POST', '/cache/purge', {
+            body: { url: pattern },
+        });
+    }
+    /**
+     * Purge cache entries created before a specific date
+     *
+     * @param date - Purge entries created before this date
+     * @returns Purge result with count
+     *
+     * @example
+     * ```typescript
+     * const result = await client.cache.purgeBefore(new Date('2024-01-01'));
+     * ```
+     */
+    async purgeBefore(date) {
+        return this.client.request('POST', '/cache/purge', {
+            body: { before: date.toISOString() },
+        });
+    }
+    /**
+     * Purge cache entries matching a storage path pattern
+     *
+     * @param pattern - Glob pattern for storage paths (e.g., "screenshots/2024/01/*")
+     * @returns Purge result with count
+     *
+     * @example
+     * ```typescript
+     * const result = await client.cache.purgePattern('screenshots/2024/*');
+     * ```
+     */
+    async purgePattern(pattern) {
+        return this.client.request('POST', '/cache/purge', {
+            body: { pattern },
+        });
+    }
+}
+exports.CacheManager = CacheManager;
+//# sourceMappingURL=cache.js.map

package/dist/cjs/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":";;;AAiBA;;GAEG;AACH,MAAa,YAAY;IACN,MAAM,CAAkB;IAEzC,YAAY,MAAuB;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAS,KAAK,EAAE,UAAU,GAAG,EAAE,EAAE;gBAC/D,YAAY,EAAE,QAAQ;aACvB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,6BAA6B;YAC7B,IACE,KAAK,KAAK,IAAI;gBACd,OAAO,KAAK,KAAK,QAAQ;gBACzB,YAAY,IAAI,KAAK;gBACrB,KAAK,CAAC,UAAU,KAAK,GAAG,EACxB,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,CAAC,GAAW;QAItB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAiB,QAAQ,EAAE,UAAU,GAAG,EAAE,CAAC,CAAC;QACtF,OAAO,QAAQ,CAAC,OAAO,CAAC;IAC1B,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,KAAK,CAAC,IAAc;QACxB,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAc,MAAM,EAAE,cAAc,EAAE;YAC9D,IAAI,EAAE,EAAE,IAAI,EAAE;SACf,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,QAAQ,CAAC,OAAe;QAC5B,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAc,MAAM,EAAE,cAAc,EAAE;YAC9D,IAAI,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE;SACvB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,WAAW,CAAC,IAAU;QAC1B,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAc,MAAM,EAAE,cAAc,EAAE;YAC9D,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,EAAE;SACrC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,YAAY,CAAC,OAAe;QAChC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAc,MAAM,EAAE,cAAc,EAAE;YAC9D,IAAI,EAAE,EAAE,OAAO,EAAE;SAClB,CAAC,CAAC;IACL,CAAC;CACF;AA/HD,oCA+HC"}