@shotapi/sdk 1.0.0

package/README.md

@@ -0,0 +1,265 @@
+# ShotAPI SDK
+
+Official Node.js SDK for [ShotAPI](https://shotapi.dev) - Screenshot API for Developers.
+
+## Installation
+
+```bash
+npm install @shotapi/sdk
+```
+
+## Quick Start
+
+```typescript
+import ShotAPI from '@shotapi/sdk';
+
+const client = new ShotAPI({ apiKey: 'your-api-key' });
+
+// Capture a screenshot
+const result = await client.screenshot({
+  url: 'https://example.com'
+});
+
+console.log(result.url); // URL to the screenshot
+```
+
+## Features
+
+- Full TypeScript support
+- Automatic retries with exponential backoff
+- Device presets (iPhone, iPad, Android, etc.)
+- Batch screenshot capture
+- Save directly to file
+- Get screenshot as Buffer
+
+## Usage Examples
+
+### Basic Screenshot
+
+```typescript
+const result = await client.screenshot({
+  url: 'https://example.com',
+  width: 1280,
+  height: 720
+});
+```
+
+### Full Page Screenshot
+
+```typescript
+const result = await client.screenshot({
+  url: 'https://example.com',
+  fullPage: true
+});
+```
+
+### Device Preset
+
+```typescript
+// Use iPhone 14 Pro dimensions
+const result = await client.screenshot({
+  url: 'https://example.com',
+  device: 'iphone-14-pro'
+});
+
+// Available presets:
+// desktop, laptop, tablet, mobile,
+// iphone-14, iphone-14-pro, iphone-14-pro-max,
+// ipad, ipad-pro, galaxy-s23, pixel-7
+```
+
+### Different Formats
+
+```typescript
+// JPEG with quality
+const jpeg = await client.screenshot({
+  url: 'https://example.com',
+  format: 'jpeg',
+  quality: 90
+});
+
+// WebP
+const webp = await client.screenshot({
+  url: 'https://example.com',
+  format: 'webp',
+  quality: 85
+});
+
+// PDF
+const pdf = await client.screenshot({
+  url: 'https://example.com',
+  format: 'pdf',
+  fullPage: true
+});
+```
+
+### Wait for Content
+
+```typescript
+// Wait for a specific element
+const result = await client.screenshot({
+  url: 'https://example.com',
+  waitForSelector: '.main-content'
+});
+
+// Add delay before capture
+const result2 = await client.screenshot({
+  url: 'https://example.com',
+  delay: 2000 // 2 seconds
+});
+```
+
+### Premium Features
+
+```typescript
+// Element screenshot
+const element = await client.screenshot({
+  url: 'https://example.com',
+  selector: '#hero-section'
+});
+
+// Inject custom CSS
+const styled = await client.screenshot({
+  url: 'https://example.com',
+  css: 'body { background: #f0f0f0; }'
+});
+
+// Execute JavaScript before capture
+const dynamic = await client.screenshot({
+  url: 'https://example.com',
+  js: 'document.querySelector(".popup").remove();'
+});
+
+// Block ads
+const clean = await client.screenshot({
+  url: 'https://example.com',
+  blockAds: true,
+  hideCookieBanners: true
+});
+
+// Generate thumbnail
+const thumb = await client.screenshot({
+  url: 'https://example.com',
+  thumbnailWidth: 300
+});
+```
+
+### Save to File
+
+```typescript
+await client.screenshotToFile(
+  { url: 'https://example.com' },
+  './screenshot.png'
+);
+```
+
+### Get as Buffer
+
+```typescript
+const buffer = await client.screenshotBuffer({
+  url: 'https://example.com'
+});
+
+// Use buffer (e.g., upload to S3, send in response, etc.)
+```
+
+### Batch Screenshots
+
+```typescript
+const urls = [
+  'https://example.com',
+  'https://google.com',
+  'https://github.com'
+];
+
+const results = await client.batch(urls, {
+  width: 1280,
+  height: 720
+});
+```
+
+## Configuration
+
+```typescript
+const client = new ShotAPI({
+  apiKey: 'your-api-key',      // Required
+  baseUrl: 'https://shotapi.dev', // Optional (default)
+  timeout: 30000,              // Request timeout in ms (default: 30000)
+  retries: 2                   // Retry attempts (default: 2)
+});
+```
+
+## Error Handling
+
+```typescript
+import ShotAPI, { ShotAPIException } from '@shotapi/sdk';
+
+try {
+  const result = await client.screenshot({
+    url: 'https://example.com'
+  });
+} catch (error) {
+  if (error instanceof ShotAPIException) {
+    console.error('API Error:', error.message);
+    console.error('Error Code:', error.code);
+    console.error('Status Code:', error.statusCode);
+  }
+}
+```
+
+## TypeScript
+
+The SDK is written in TypeScript and includes full type definitions:
+
+```typescript
+import ShotAPI, {
+  ScreenshotOptions,
+  ScreenshotResponse,
+  DevicePreset,
+  ImageFormat,
+  ShotAPIConfig
+} from '@shotapi/sdk';
+```
+
+## Response Format
+
+```typescript
+interface ScreenshotResponse {
+  url: string;           // URL to the screenshot
+  thumbnailUrl?: string; // Thumbnail URL (if requested)
+  metadata: {
+    width: number;
+    height: number;
+    format: string;
+    size: number;        // File size in bytes
+  };
+  creditsUsed: number;
+  creditsRemaining: number;
+}
+```
+
+## Device Presets
+
+| Preset | Width | Height | Mobile | Scale |
+|--------|-------|--------|--------|-------|
+| desktop | 1920 | 1080 | No | 1 |
+| laptop | 1366 | 768 | No | 1 |
+| tablet | 768 | 1024 | Yes | 2 |
+| mobile | 375 | 812 | Yes | 3 |
+| iphone-14 | 390 | 844 | Yes | 3 |
+| iphone-14-pro | 393 | 852 | Yes | 3 |
+| iphone-14-pro-max | 430 | 932 | Yes | 3 |
+| ipad | 810 | 1080 | Yes | 2 |
+| ipad-pro | 1024 | 1366 | Yes | 2 |
+| galaxy-s23 | 360 | 780 | Yes | 3 |
+| pixel-7 | 412 | 915 | Yes | 2.625 |
+
+## License
+
+MIT
+
+## Links
+
+- [Website](https://shotapi.dev)
+- [Documentation](https://shotapi.dev/docs)
+- [API Reference](https://shotapi.dev/docs/api)

package/dist/index.d.mts

@@ -0,0 +1,262 @@
+/**
+ * Device presets for responsive screenshots
+ */
+type DevicePreset = 'desktop' | 'laptop' | 'tablet' | 'mobile' | 'iphone-14' | 'iphone-14-pro' | 'iphone-14-pro-max' | 'ipad' | 'ipad-pro' | 'galaxy-s23' | 'pixel-7';
+/**
+ * Output format for screenshots
+ */
+type ImageFormat = 'png' | 'jpeg' | 'webp' | 'pdf';
+/**
+ * Screenshot options
+ */
+interface ScreenshotOptions {
+    /**
+     * Target URL to capture
+     */
+    url: string;
+    /**
+     * Viewport width in pixels (default: 1280)
+     */
+    width?: number;
+    /**
+     * Viewport height in pixels (default: 720)
+     */
+    height?: number;
+    /**
+     * Use a device preset instead of custom width/height
+     */
+    device?: DevicePreset;
+    /**
+     * Whether to capture full page (default: false)
+     */
+    fullPage?: boolean;
+    /**
+     * Output format (default: 'png')
+     */
+    format?: ImageFormat;
+    /**
+     * Image quality 1-100 (only for jpeg/webp, default: 80)
+     */
+    quality?: number;
+    /**
+     * Device scale factor (default: 1)
+     */
+    scale?: number;
+    /**
+     * Delay in milliseconds before capture (default: 0)
+     */
+    delay?: number;
+    /**
+     * Wait for a specific CSS selector to appear
+     */
+    waitForSelector?: string;
+    /**
+     * CSS selector to capture (element screenshot)
+     * Premium feature
+     */
+    selector?: string;
+    /**
+     * Custom CSS to inject before capture
+     * Premium feature
+     */
+    css?: string;
+    /**
+     * Custom JavaScript to execute before capture
+     * Premium feature
+     */
+    js?: string;
+    /**
+     * Block ads and trackers (default: false)
+     * Premium feature
+     */
+    blockAds?: boolean;
+    /**
+     * Hide cookie banners (default: false)
+     * Premium feature
+     */
+    hideCookieBanners?: boolean;
+    /**
+     * Dark mode (default: false)
+     */
+    darkMode?: boolean;
+    /**
+     * Emulate mobile device (default: false)
+     */
+    mobile?: boolean;
+    /**
+     * Generate thumbnail with specified width
+     * Premium feature
+     */
+    thumbnailWidth?: number;
+}
+/**
+ * Screenshot response
+ */
+interface ScreenshotResponse {
+    /**
+     * URL to the captured screenshot
+     */
+    url: string;
+    /**
+     * Thumbnail URL (if thumbnailWidth was specified)
+     */
+    thumbnailUrl?: string;
+    /**
+     * Screenshot metadata
+     */
+    metadata: {
+        width: number;
+        height: number;
+        format: ImageFormat;
+        size: number;
+    };
+    /**
+     * Credits used for this request
+     */
+    creditsUsed: number;
+    /**
+     * Remaining credits
+     */
+    creditsRemaining: number;
+}
+/**
+ * API Error response
+ */
+interface ShotAPIError {
+    error: string;
+    code?: string;
+    details?: string;
+}
+/**
+ * SDK Configuration
+ */
+interface ShotAPIConfig {
+    /**
+     * Your ShotAPI API key
+     */
+    apiKey: string;
+    /**
+     * Base URL for the API (default: https://shotapi.dev)
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds (default: 30000)
+     */
+    timeout?: number;
+    /**
+     * Number of retry attempts on failure (default: 2)
+     */
+    retries?: number;
+}
+
+/**
+ * ShotAPI Error class
+ */
+declare class ShotAPIException extends Error {
+    readonly code?: string;
+    readonly details?: string;
+    readonly statusCode?: number;
+    constructor(message: string, code?: string, details?: string, statusCode?: number);
+}
+/**
+ * ShotAPI - Screenshot API SDK
+ *
+ * @example
+ * ```typescript
+ * import ShotAPI from 'shotapi';
+ *
+ * const client = new ShotAPI({ apiKey: 'your-api-key' });
+ *
+ * // Basic screenshot
+ * const result = await client.screenshot({ url: 'https://example.com' });
+ * console.log(result.url);
+ *
+ * // Full page screenshot with custom options
+ * const result2 = await client.screenshot({
+ *   url: 'https://example.com',
+ *   fullPage: true,
+ *   format: 'jpeg',
+ *   quality: 90,
+ * });
+ * ```
+ */
+declare class ShotAPI {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly retries;
+    constructor(config: ShotAPIConfig);
+    /**
+     * Capture a screenshot of a URL
+     *
+     * @param options - Screenshot options
+     * @returns Screenshot response with URL and metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await client.screenshot({
+     *   url: 'https://example.com',
+     *   width: 1280,
+     *   height: 720,
+     *   fullPage: true,
+     * });
+     * ```
+     */
+    screenshot(options: ScreenshotOptions): Promise<ScreenshotResponse>;
+    /**
+     * Capture a screenshot and return as a Buffer
+     *
+     * @param options - Screenshot options
+     * @returns Screenshot as a Buffer
+     */
+    screenshotBuffer(options: ScreenshotOptions): Promise<Buffer>;
+    /**
+     * Capture a screenshot and save to a file
+     *
+     * @param options - Screenshot options
+     * @param filePath - Path to save the screenshot
+     */
+    screenshotToFile(options: ScreenshotOptions, filePath: string): Promise<ScreenshotResponse>;
+    /**
+     * Capture multiple screenshots in batch
+     *
+     * @param urls - Array of URLs to capture
+     * @param options - Common options for all screenshots
+     * @returns Array of screenshot responses
+     */
+    batch(urls: string[], options?: Omit<ScreenshotOptions, 'url'>): Promise<ScreenshotResponse[]>;
+    /**
+     * Get device preset dimensions
+     *
+     * @param device - Device preset name
+     * @returns Device dimensions
+     */
+    static getDevicePreset(device: DevicePreset): {
+        width: number;
+        height: number;
+        mobile: boolean;
+        scale: number;
+    };
+    /**
+     * List all available device presets
+     */
+    static get devicePresets(): DevicePreset[];
+    /**
+     * Build URL parameters from options
+     */
+    private buildParams;
+    /**
+     * Make an API request with retries
+     */
+    private request;
+    /**
+     * Fetch a URL as Buffer
+     */
+    private fetchBuffer;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+}
+
+export { type DevicePreset, type ImageFormat, type ScreenshotOptions, type ScreenshotResponse, ShotAPI, type ShotAPIConfig, type ShotAPIError, ShotAPIException, ShotAPI as default };

package/dist/index.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Device presets for responsive screenshots
+ */
+type DevicePreset = 'desktop' | 'laptop' | 'tablet' | 'mobile' | 'iphone-14' | 'iphone-14-pro' | 'iphone-14-pro-max' | 'ipad' | 'ipad-pro' | 'galaxy-s23' | 'pixel-7';
+/**
+ * Output format for screenshots
+ */
+type ImageFormat = 'png' | 'jpeg' | 'webp' | 'pdf';
+/**
+ * Screenshot options
+ */
+interface ScreenshotOptions {
+    /**
+     * Target URL to capture
+     */
+    url: string;
+    /**
+     * Viewport width in pixels (default: 1280)
+     */
+    width?: number;
+    /**
+     * Viewport height in pixels (default: 720)
+     */
+    height?: number;
+    /**
+     * Use a device preset instead of custom width/height
+     */
+    device?: DevicePreset;
+    /**
+     * Whether to capture full page (default: false)
+     */
+    fullPage?: boolean;
+    /**
+     * Output format (default: 'png')
+     */
+    format?: ImageFormat;
+    /**
+     * Image quality 1-100 (only for jpeg/webp, default: 80)
+     */
+    quality?: number;
+    /**
+     * Device scale factor (default: 1)
+     */
+    scale?: number;
+    /**
+     * Delay in milliseconds before capture (default: 0)
+     */
+    delay?: number;
+    /**
+     * Wait for a specific CSS selector to appear
+     */
+    waitForSelector?: string;
+    /**
+     * CSS selector to capture (element screenshot)
+     * Premium feature
+     */
+    selector?: string;
+    /**
+     * Custom CSS to inject before capture
+     * Premium feature
+     */
+    css?: string;
+    /**
+     * Custom JavaScript to execute before capture
+     * Premium feature
+     */
+    js?: string;
+    /**
+     * Block ads and trackers (default: false)
+     * Premium feature
+     */
+    blockAds?: boolean;
+    /**
+     * Hide cookie banners (default: false)
+     * Premium feature
+     */
+    hideCookieBanners?: boolean;
+    /**
+     * Dark mode (default: false)
+     */
+    darkMode?: boolean;
+    /**
+     * Emulate mobile device (default: false)
+     */
+    mobile?: boolean;
+    /**
+     * Generate thumbnail with specified width
+     * Premium feature
+     */
+    thumbnailWidth?: number;
+}
+/**
+ * Screenshot response
+ */
+interface ScreenshotResponse {
+    /**
+     * URL to the captured screenshot
+     */
+    url: string;
+    /**
+     * Thumbnail URL (if thumbnailWidth was specified)
+     */
+    thumbnailUrl?: string;
+    /**
+     * Screenshot metadata
+     */
+    metadata: {
+        width: number;
+        height: number;
+        format: ImageFormat;
+        size: number;
+    };
+    /**
+     * Credits used for this request
+     */
+    creditsUsed: number;
+    /**
+     * Remaining credits
+     */
+    creditsRemaining: number;
+}
+/**
+ * API Error response
+ */
+interface ShotAPIError {
+    error: string;
+    code?: string;
+    details?: string;
+}
+/**
+ * SDK Configuration
+ */
+interface ShotAPIConfig {
+    /**
+     * Your ShotAPI API key
+     */
+    apiKey: string;
+    /**
+     * Base URL for the API (default: https://shotapi.dev)
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds (default: 30000)
+     */
+    timeout?: number;
+    /**
+     * Number of retry attempts on failure (default: 2)
+     */
+    retries?: number;
+}
+
+/**
+ * ShotAPI Error class
+ */
+declare class ShotAPIException extends Error {
+    readonly code?: string;
+    readonly details?: string;
+    readonly statusCode?: number;
+    constructor(message: string, code?: string, details?: string, statusCode?: number);
+}
+/**
+ * ShotAPI - Screenshot API SDK
+ *
+ * @example
+ * ```typescript
+ * import ShotAPI from 'shotapi';
+ *
+ * const client = new ShotAPI({ apiKey: 'your-api-key' });
+ *
+ * // Basic screenshot
+ * const result = await client.screenshot({ url: 'https://example.com' });
+ * console.log(result.url);
+ *
+ * // Full page screenshot with custom options
+ * const result2 = await client.screenshot({
+ *   url: 'https://example.com',
+ *   fullPage: true,
+ *   format: 'jpeg',
+ *   quality: 90,
+ * });
+ * ```
+ */
+declare class ShotAPI {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly retries;
+    constructor(config: ShotAPIConfig);
+    /**
+     * Capture a screenshot of a URL
+     *
+     * @param options - Screenshot options
+     * @returns Screenshot response with URL and metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await client.screenshot({
+     *   url: 'https://example.com',
+     *   width: 1280,
+     *   height: 720,
+     *   fullPage: true,
+     * });
+     * ```
+     */
+    screenshot(options: ScreenshotOptions): Promise<ScreenshotResponse>;
+    /**
+     * Capture a screenshot and return as a Buffer
+     *
+     * @param options - Screenshot options
+     * @returns Screenshot as a Buffer
+     */
+    screenshotBuffer(options: ScreenshotOptions): Promise<Buffer>;
+    /**
+     * Capture a screenshot and save to a file
+     *
+     * @param options - Screenshot options
+     * @param filePath - Path to save the screenshot
+     */
+    screenshotToFile(options: ScreenshotOptions, filePath: string): Promise<ScreenshotResponse>;
+    /**
+     * Capture multiple screenshots in batch
+     *
+     * @param urls - Array of URLs to capture
+     * @param options - Common options for all screenshots
+     * @returns Array of screenshot responses
+     */
+    batch(urls: string[], options?: Omit<ScreenshotOptions, 'url'>): Promise<ScreenshotResponse[]>;
+    /**
+     * Get device preset dimensions
+     *
+     * @param device - Device preset name
+     * @returns Device dimensions
+     */
+    static getDevicePreset(device: DevicePreset): {
+        width: number;
+        height: number;
+        mobile: boolean;
+        scale: number;
+    };
+    /**
+     * List all available device presets
+     */
+    static get devicePresets(): DevicePreset[];
+    /**
+     * Build URL parameters from options
+     */
+    private buildParams;
+    /**
+     * Make an API request with retries
+     */
+    private request;
+    /**
+     * Fetch a URL as Buffer
+     */
+    private fetchBuffer;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+}
+
+export { type DevicePreset, type ImageFormat, type ScreenshotOptions, type ScreenshotResponse, ShotAPI, type ShotAPIConfig, type ShotAPIError, ShotAPIException, ShotAPI as default };

package/dist/index.js

@@ -0,0 +1,245 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ShotAPI: () => ShotAPI,
+  ShotAPIException: () => ShotAPIException,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var ShotAPIException = class extends Error {
+  constructor(message, code, details, statusCode) {
+    super(message);
+    this.name = "ShotAPIException";
+    this.code = code;
+    this.details = details;
+    this.statusCode = statusCode;
+  }
+};
+var DEVICE_PRESETS = {
+  desktop: { width: 1920, height: 1080, mobile: false, scale: 1 },
+  laptop: { width: 1366, height: 768, mobile: false, scale: 1 },
+  tablet: { width: 768, height: 1024, mobile: true, scale: 2 },
+  mobile: { width: 375, height: 812, mobile: true, scale: 3 },
+  "iphone-14": { width: 390, height: 844, mobile: true, scale: 3 },
+  "iphone-14-pro": { width: 393, height: 852, mobile: true, scale: 3 },
+  "iphone-14-pro-max": { width: 430, height: 932, mobile: true, scale: 3 },
+  "ipad": { width: 810, height: 1080, mobile: true, scale: 2 },
+  "ipad-pro": { width: 1024, height: 1366, mobile: true, scale: 2 },
+  "galaxy-s23": { width: 360, height: 780, mobile: true, scale: 3 },
+  "pixel-7": { width: 412, height: 915, mobile: true, scale: 2.625 }
+};
+var ShotAPI = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new ShotAPIException("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || "https://shotapi.dev";
+    this.timeout = config.timeout || 3e4;
+    this.retries = config.retries ?? 2;
+  }
+  /**
+   * Capture a screenshot of a URL
+   *
+   * @param options - Screenshot options
+   * @returns Screenshot response with URL and metadata
+   *
+   * @example
+   * ```typescript
+   * const result = await client.screenshot({
+   *   url: 'https://example.com',
+   *   width: 1280,
+   *   height: 720,
+   *   fullPage: true,
+   * });
+   * ```
+   */
+  async screenshot(options) {
+    if (!options.url) {
+      throw new ShotAPIException("URL is required");
+    }
+    const params = this.buildParams(options);
+    return this.request("/api/v1/screenshot", params);
+  }
+  /**
+   * Capture a screenshot and return as a Buffer
+   *
+   * @param options - Screenshot options
+   * @returns Screenshot as a Buffer
+   */
+  async screenshotBuffer(options) {
+    const response = await this.screenshot(options);
+    const imageResponse = await fetch(response.url);
+    if (!imageResponse.ok) {
+      throw new ShotAPIException("Failed to fetch screenshot image");
+    }
+    const arrayBuffer = await imageResponse.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+  /**
+   * Capture a screenshot and save to a file
+   *
+   * @param options - Screenshot options
+   * @param filePath - Path to save the screenshot
+   */
+  async screenshotToFile(options, filePath) {
+    const response = await this.screenshot(options);
+    const buffer = await this.fetchBuffer(response.url);
+    const fs = await import("fs/promises");
+    await fs.writeFile(filePath, buffer);
+    return response;
+  }
+  /**
+   * Capture multiple screenshots in batch
+   *
+   * @param urls - Array of URLs to capture
+   * @param options - Common options for all screenshots
+   * @returns Array of screenshot responses
+   */
+  async batch(urls, options) {
+    const promises = urls.map(
+      (url) => this.screenshot({ ...options, url })
+    );
+    return Promise.all(promises);
+  }
+  /**
+   * Get device preset dimensions
+   *
+   * @param device - Device preset name
+   * @returns Device dimensions
+   */
+  static getDevicePreset(device) {
+    return DEVICE_PRESETS[device];
+  }
+  /**
+   * List all available device presets
+   */
+  static get devicePresets() {
+    return Object.keys(DEVICE_PRESETS);
+  }
+  /**
+   * Build URL parameters from options
+   */
+  buildParams(options) {
+    const params = new URLSearchParams();
+    params.set("url", options.url);
+    params.set("api_key", this.apiKey);
+    if (options.device) {
+      const preset = DEVICE_PRESETS[options.device];
+      if (preset) {
+        params.set("width", preset.width.toString());
+        params.set("height", preset.height.toString());
+        if (preset.mobile) params.set("mobile", "true");
+        if (preset.scale !== 1) params.set("scale", preset.scale.toString());
+      }
+    } else {
+      if (options.width) params.set("width", options.width.toString());
+      if (options.height) params.set("height", options.height.toString());
+    }
+    if (options.fullPage) params.set("full_page", "true");
+    if (options.format) params.set("format", options.format);
+    if (options.quality) params.set("quality", options.quality.toString());
+    if (options.scale) params.set("scale", options.scale.toString());
+    if (options.delay) params.set("delay", options.delay.toString());
+    if (options.waitForSelector) params.set("wait_for", options.waitForSelector);
+    if (options.darkMode) params.set("dark_mode", "true");
+    if (options.mobile) params.set("mobile", "true");
+    if (options.selector) params.set("selector", options.selector);
+    if (options.css) params.set("css", options.css);
+    if (options.js) params.set("js", options.js);
+    if (options.blockAds) params.set("block_ads", "true");
+    if (options.hideCookieBanners) params.set("hide_cookie_banners", "true");
+    if (options.thumbnailWidth) params.set("thumbnail_width", options.thumbnailWidth.toString());
+    return params;
+  }
+  /**
+   * Make an API request with retries
+   */
+  async request(endpoint, params) {
+    const url = `${this.baseUrl}${endpoint}?${params.toString()}`;
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const response = await fetch(url, {
+          method: "GET",
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        const data = await response.json();
+        if (!response.ok) {
+          const error = data;
+          throw new ShotAPIException(
+            error.error || "Unknown error",
+            error.code,
+            error.details,
+            response.status
+          );
+        }
+        return data;
+      } catch (error) {
+        lastError = error;
+        if (error instanceof ShotAPIException && error.statusCode && error.statusCode < 500) {
+          throw error;
+        }
+        if (attempt < this.retries) {
+          await this.sleep(Math.pow(2, attempt) * 1e3);
+        }
+      }
+    }
+    throw lastError || new ShotAPIException("Request failed after retries");
+  }
+  /**
+   * Fetch a URL as Buffer
+   */
+  async fetchBuffer(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new ShotAPIException("Failed to fetch image");
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+  /**
+   * Sleep for specified milliseconds
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+var index_default = ShotAPI;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ShotAPI,
+  ShotAPIException
+});

package/dist/index.mjs

@@ -0,0 +1,209 @@
+// src/index.ts
+var ShotAPIException = class extends Error {
+  constructor(message, code, details, statusCode) {
+    super(message);
+    this.name = "ShotAPIException";
+    this.code = code;
+    this.details = details;
+    this.statusCode = statusCode;
+  }
+};
+var DEVICE_PRESETS = {
+  desktop: { width: 1920, height: 1080, mobile: false, scale: 1 },
+  laptop: { width: 1366, height: 768, mobile: false, scale: 1 },
+  tablet: { width: 768, height: 1024, mobile: true, scale: 2 },
+  mobile: { width: 375, height: 812, mobile: true, scale: 3 },
+  "iphone-14": { width: 390, height: 844, mobile: true, scale: 3 },
+  "iphone-14-pro": { width: 393, height: 852, mobile: true, scale: 3 },
+  "iphone-14-pro-max": { width: 430, height: 932, mobile: true, scale: 3 },
+  "ipad": { width: 810, height: 1080, mobile: true, scale: 2 },
+  "ipad-pro": { width: 1024, height: 1366, mobile: true, scale: 2 },
+  "galaxy-s23": { width: 360, height: 780, mobile: true, scale: 3 },
+  "pixel-7": { width: 412, height: 915, mobile: true, scale: 2.625 }
+};
+var ShotAPI = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new ShotAPIException("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || "https://shotapi.dev";
+    this.timeout = config.timeout || 3e4;
+    this.retries = config.retries ?? 2;
+  }
+  /**
+   * Capture a screenshot of a URL
+   *
+   * @param options - Screenshot options
+   * @returns Screenshot response with URL and metadata
+   *
+   * @example
+   * ```typescript
+   * const result = await client.screenshot({
+   *   url: 'https://example.com',
+   *   width: 1280,
+   *   height: 720,
+   *   fullPage: true,
+   * });
+   * ```
+   */
+  async screenshot(options) {
+    if (!options.url) {
+      throw new ShotAPIException("URL is required");
+    }
+    const params = this.buildParams(options);
+    return this.request("/api/v1/screenshot", params);
+  }
+  /**
+   * Capture a screenshot and return as a Buffer
+   *
+   * @param options - Screenshot options
+   * @returns Screenshot as a Buffer
+   */
+  async screenshotBuffer(options) {
+    const response = await this.screenshot(options);
+    const imageResponse = await fetch(response.url);
+    if (!imageResponse.ok) {
+      throw new ShotAPIException("Failed to fetch screenshot image");
+    }
+    const arrayBuffer = await imageResponse.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+  /**
+   * Capture a screenshot and save to a file
+   *
+   * @param options - Screenshot options
+   * @param filePath - Path to save the screenshot
+   */
+  async screenshotToFile(options, filePath) {
+    const response = await this.screenshot(options);
+    const buffer = await this.fetchBuffer(response.url);
+    const fs = await import("fs/promises");
+    await fs.writeFile(filePath, buffer);
+    return response;
+  }
+  /**
+   * Capture multiple screenshots in batch
+   *
+   * @param urls - Array of URLs to capture
+   * @param options - Common options for all screenshots
+   * @returns Array of screenshot responses
+   */
+  async batch(urls, options) {
+    const promises = urls.map(
+      (url) => this.screenshot({ ...options, url })
+    );
+    return Promise.all(promises);
+  }
+  /**
+   * Get device preset dimensions
+   *
+   * @param device - Device preset name
+   * @returns Device dimensions
+   */
+  static getDevicePreset(device) {
+    return DEVICE_PRESETS[device];
+  }
+  /**
+   * List all available device presets
+   */
+  static get devicePresets() {
+    return Object.keys(DEVICE_PRESETS);
+  }
+  /**
+   * Build URL parameters from options
+   */
+  buildParams(options) {
+    const params = new URLSearchParams();
+    params.set("url", options.url);
+    params.set("api_key", this.apiKey);
+    if (options.device) {
+      const preset = DEVICE_PRESETS[options.device];
+      if (preset) {
+        params.set("width", preset.width.toString());
+        params.set("height", preset.height.toString());
+        if (preset.mobile) params.set("mobile", "true");
+        if (preset.scale !== 1) params.set("scale", preset.scale.toString());
+      }
+    } else {
+      if (options.width) params.set("width", options.width.toString());
+      if (options.height) params.set("height", options.height.toString());
+    }
+    if (options.fullPage) params.set("full_page", "true");
+    if (options.format) params.set("format", options.format);
+    if (options.quality) params.set("quality", options.quality.toString());
+    if (options.scale) params.set("scale", options.scale.toString());
+    if (options.delay) params.set("delay", options.delay.toString());
+    if (options.waitForSelector) params.set("wait_for", options.waitForSelector);
+    if (options.darkMode) params.set("dark_mode", "true");
+    if (options.mobile) params.set("mobile", "true");
+    if (options.selector) params.set("selector", options.selector);
+    if (options.css) params.set("css", options.css);
+    if (options.js) params.set("js", options.js);
+    if (options.blockAds) params.set("block_ads", "true");
+    if (options.hideCookieBanners) params.set("hide_cookie_banners", "true");
+    if (options.thumbnailWidth) params.set("thumbnail_width", options.thumbnailWidth.toString());
+    return params;
+  }
+  /**
+   * Make an API request with retries
+   */
+  async request(endpoint, params) {
+    const url = `${this.baseUrl}${endpoint}?${params.toString()}`;
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const response = await fetch(url, {
+          method: "GET",
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        const data = await response.json();
+        if (!response.ok) {
+          const error = data;
+          throw new ShotAPIException(
+            error.error || "Unknown error",
+            error.code,
+            error.details,
+            response.status
+          );
+        }
+        return data;
+      } catch (error) {
+        lastError = error;
+        if (error instanceof ShotAPIException && error.statusCode && error.statusCode < 500) {
+          throw error;
+        }
+        if (attempt < this.retries) {
+          await this.sleep(Math.pow(2, attempt) * 1e3);
+        }
+      }
+    }
+    throw lastError || new ShotAPIException("Request failed after retries");
+  }
+  /**
+   * Fetch a URL as Buffer
+   */
+  async fetchBuffer(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new ShotAPIException("Failed to fetch image");
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+  /**
+   * Sleep for specified milliseconds
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+var index_default = ShotAPI;
+export {
+  ShotAPI,
+  ShotAPIException,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@shotapi/sdk",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for ShotAPI - Screenshot API for Developers",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "screenshot",
+    "api",
+    "web",
+    "capture",
+    "puppeteer",
+    "headless",
+    "browser",
+    "shotapi"
+  ],
+  "author": "ShotAPI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gaurav-aryal/shotapi-sdk"
+  },
+  "homepage": "https://shotapi.dev",
+  "bugs": {
+    "url": "https://github.com/gaurav-aryal/shotapi-sdk/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}