@shotapi/sdk 1.0.0 → 1.0.1

package/dist/index.d.mts

@@ -147,6 +147,19 @@ interface ShotAPIConfig {
      * Number of retry attempts on failure (default: 2)
      */
     retries?: number;
+    /**
+     * Maximum concurrent requests for batch operations (default: 5)
+     */
+    maxConcurrent?: number;
+}
+/**
+ * Device preset dimensions
+ */
+interface DevicePresetConfig {
+    width: number;
+    height: number;
+    mobile: boolean;
+    scale: number;
 }
 
 /**
@@ -163,7 +176,7 @@ declare class ShotAPIException extends Error {
  *
  * @example
  * ```typescript
- * import ShotAPI from 'shotapi';
+ * import ShotAPI from '@shotapi/sdk';
  *
  * const client = new ShotAPI({ apiKey: 'your-api-key' });
  *
@@ -185,6 +198,7 @@ declare class ShotAPI {
     private readonly baseUrl;
     private readonly timeout;
     private readonly retries;
+    private readonly maxConcurrent;
     constructor(config: ShotAPIConfig);
     /**
      * Capture a screenshot of a URL
@@ -218,11 +232,20 @@ declare class ShotAPI {
      */
     screenshotToFile(options: ScreenshotOptions, filePath: string): Promise<ScreenshotResponse>;
     /**
-     * Capture multiple screenshots in batch
+     * Capture multiple screenshots in batch with rate limiting
      *
      * @param urls - Array of URLs to capture
      * @param options - Common options for all screenshots
      * @returns Array of screenshot responses
+     *
+     * @example
+     * ```typescript
+     * const results = await client.batch([
+     *   'https://example.com',
+     *   'https://google.com',
+     *   'https://github.com'
+     * ], { width: 1280 });
+     * ```
      */
     batch(urls: string[], options?: Omit<ScreenshotOptions, 'url'>): Promise<ScreenshotResponse[]>;
     /**
@@ -231,12 +254,7 @@ declare class ShotAPI {
      * @param device - Device preset name
      * @returns Device dimensions
      */
-    static getDevicePreset(device: DevicePreset): {
-        width: number;
-        height: number;
-        mobile: boolean;
-        scale: number;
-    };
+    static getDevicePreset(device: DevicePreset): DevicePresetConfig;
     /**
      * List all available device presets
      */
@@ -259,4 +277,4 @@ declare class ShotAPI {
     private sleep;
 }
 
-export { type DevicePreset, type ImageFormat, type ScreenshotOptions, type ScreenshotResponse, ShotAPI, type ShotAPIConfig, type ShotAPIError, ShotAPIException, ShotAPI as default };
+export { type DevicePreset, type DevicePresetConfig, type ImageFormat, type ScreenshotOptions, type ScreenshotResponse, ShotAPI, type ShotAPIConfig, type ShotAPIError, ShotAPIException, ShotAPI as default };

package/dist/index.d.ts

@@ -147,6 +147,19 @@ interface ShotAPIConfig {
      * Number of retry attempts on failure (default: 2)
      */
     retries?: number;
+    /**
+     * Maximum concurrent requests for batch operations (default: 5)
+     */
+    maxConcurrent?: number;
+}
+/**
+ * Device preset dimensions
+ */
+interface DevicePresetConfig {
+    width: number;
+    height: number;
+    mobile: boolean;
+    scale: number;
 }
 
 /**
@@ -163,7 +176,7 @@ declare class ShotAPIException extends Error {
  *
  * @example
  * ```typescript
- * import ShotAPI from 'shotapi';
+ * import ShotAPI from '@shotapi/sdk';
  *
  * const client = new ShotAPI({ apiKey: 'your-api-key' });
  *
@@ -185,6 +198,7 @@ declare class ShotAPI {
     private readonly baseUrl;
     private readonly timeout;
     private readonly retries;
+    private readonly maxConcurrent;
     constructor(config: ShotAPIConfig);
     /**
      * Capture a screenshot of a URL
@@ -218,11 +232,20 @@ declare class ShotAPI {
      */
     screenshotToFile(options: ScreenshotOptions, filePath: string): Promise<ScreenshotResponse>;
     /**
-     * Capture multiple screenshots in batch
+     * Capture multiple screenshots in batch with rate limiting
      *
      * @param urls - Array of URLs to capture
      * @param options - Common options for all screenshots
      * @returns Array of screenshot responses
+     *
+     * @example
+     * ```typescript
+     * const results = await client.batch([
+     *   'https://example.com',
+     *   'https://google.com',
+     *   'https://github.com'
+     * ], { width: 1280 });
+     * ```
      */
     batch(urls: string[], options?: Omit<ScreenshotOptions, 'url'>): Promise<ScreenshotResponse[]>;
     /**
@@ -231,12 +254,7 @@ declare class ShotAPI {
      * @param device - Device preset name
      * @returns Device dimensions
      */
-    static getDevicePreset(device: DevicePreset): {
-        width: number;
-        height: number;
-        mobile: boolean;
-        scale: number;
-    };
+    static getDevicePreset(device: DevicePreset): DevicePresetConfig;
     /**
      * List all available device presets
      */
@@ -259,4 +277,4 @@ declare class ShotAPI {
     private sleep;
 }
 
-export { type DevicePreset, type ImageFormat, type ScreenshotOptions, type ScreenshotResponse, ShotAPI, type ShotAPIConfig, type ShotAPIError, ShotAPIException, ShotAPI as default };
+export { type DevicePreset, type DevicePresetConfig, type ImageFormat, type ScreenshotOptions, type ScreenshotResponse, ShotAPI, type ShotAPIConfig, type ShotAPIError, ShotAPIException, ShotAPI as default };

package/dist/index.js

@@ -57,15 +57,24 @@ var DEVICE_PRESETS = {
   "galaxy-s23": { width: 360, height: 780, mobile: true, scale: 3 },
   "pixel-7": { width: 412, height: 915, mobile: true, scale: 2.625 }
 };
+function isValidUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
 var ShotAPI = class {
   constructor(config) {
     if (!config.apiKey) {
-      throw new ShotAPIException("API key is required");
+      throw new ShotAPIException("API key is required", "MISSING_API_KEY");
     }
     this.apiKey = config.apiKey;
     this.baseUrl = config.baseUrl || "https://shotapi.dev";
     this.timeout = config.timeout || 3e4;
     this.retries = config.retries ?? 2;
+    this.maxConcurrent = config.maxConcurrent ?? 5;
   }
   /**
    * Capture a screenshot of a URL
@@ -85,7 +94,29 @@ var ShotAPI = class {
    */
   async screenshot(options) {
     if (!options.url) {
-      throw new ShotAPIException("URL is required");
+      throw new ShotAPIException("URL is required", "MISSING_URL");
+    }
+    if (!isValidUrl(options.url)) {
+      throw new ShotAPIException(
+        `Invalid URL: ${options.url}. URL must start with http:// or https://`,
+        "INVALID_URL"
+      );
+    }
+    if (options.quality !== void 0) {
+      if (options.quality < 1 || options.quality > 100) {
+        throw new ShotAPIException(
+          "Quality must be between 1 and 100",
+          "INVALID_QUALITY"
+        );
+      }
+    }
+    if (options.delay !== void 0) {
+      if (options.delay < 0 || options.delay > 1e4) {
+        throw new ShotAPIException(
+          "Delay must be between 0 and 10000 milliseconds",
+          "INVALID_DELAY"
+        );
+      }
     }
     const params = this.buildParams(options);
     return this.request("/api/v1/screenshot", params);
@@ -98,12 +129,7 @@ var ShotAPI = class {
    */
   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);
+    return this.fetchBuffer(response.url);
   }
   /**
    * Capture a screenshot and save to a file
@@ -115,21 +141,42 @@ var ShotAPI = class {
     const response = await this.screenshot(options);
     const buffer = await this.fetchBuffer(response.url);
     const fs = await import("fs/promises");
+    const path = await import("path");
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
     await fs.writeFile(filePath, buffer);
     return response;
   }
   /**
-   * Capture multiple screenshots in batch
+   * Capture multiple screenshots in batch with rate limiting
    *
    * @param urls - Array of URLs to capture
    * @param options - Common options for all screenshots
    * @returns Array of screenshot responses
+   *
+   * @example
+   * ```typescript
+   * const results = await client.batch([
+   *   'https://example.com',
+   *   'https://google.com',
+   *   'https://github.com'
+   * ], { width: 1280 });
+   * ```
    */
   async batch(urls, options) {
-    const promises = urls.map(
-      (url) => this.screenshot({ ...options, url })
-    );
-    return Promise.all(promises);
+    const results = [];
+    for (let i = 0; i < urls.length; i += this.maxConcurrent) {
+      const chunk = urls.slice(i, i + this.maxConcurrent);
+      const promises = chunk.map(
+        (url) => this.screenshot({ ...options, url })
+      );
+      const chunkResults = await Promise.all(promises);
+      results.push(...chunkResults);
+      if (i + this.maxConcurrent < urls.length) {
+        await this.sleep(100);
+      }
+    }
+    return results;
   }
   /**
    * Get device preset dimensions
@@ -168,11 +215,11 @@ var ShotAPI = class {
     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.scale && !options.device) 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.mobile && !options.device) 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);
@@ -188,36 +235,61 @@ var ShotAPI = class {
     const url = `${this.baseUrl}${endpoint}?${params.toString()}`;
     let lastError = null;
     for (let attempt = 0; attempt <= this.retries; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
       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,
+          let errorData = null;
+          try {
+            errorData = await response.json();
+          } catch {
+          }
+          const error = new ShotAPIException(
+            errorData?.error || `HTTP ${response.status}: ${response.statusText}`,
+            errorData?.code || "HTTP_ERROR",
+            errorData?.details,
             response.status
           );
+          if (response.status >= 400 && response.status < 500) {
+            throw error;
+          }
+          lastError = error;
+          if (attempt < this.retries) {
+            await this.sleep(Math.pow(2, attempt) * 1e3);
+          }
+          continue;
         }
+        const data = await response.json();
         return data;
       } catch (error) {
-        lastError = error;
-        if (error instanceof ShotAPIException && error.statusCode && error.statusCode < 500) {
+        clearTimeout(timeoutId);
+        if (error instanceof ShotAPIException) {
           throw error;
         }
+        if (error instanceof Error && error.name === "AbortError") {
+          lastError = new ShotAPIException(
+            `Request timeout after ${this.timeout}ms`,
+            "TIMEOUT"
+          );
+        } else if (error instanceof Error) {
+          lastError = new ShotAPIException(
+            error.message || "Network error",
+            "NETWORK_ERROR"
+          );
+        } else {
+          lastError = new ShotAPIException("Unknown error occurred", "UNKNOWN_ERROR");
+        }
         if (attempt < this.retries) {
           await this.sleep(Math.pow(2, attempt) * 1e3);
         }
       }
     }
-    throw lastError || new ShotAPIException("Request failed after retries");
+    throw lastError || new ShotAPIException("Request failed after retries", "MAX_RETRIES");
   }
   /**
    * Fetch a URL as Buffer
@@ -225,7 +297,12 @@ var ShotAPI = class {
   async fetchBuffer(url) {
     const response = await fetch(url);
     if (!response.ok) {
-      throw new ShotAPIException("Failed to fetch image");
+      throw new ShotAPIException(
+        `Failed to fetch image: HTTP ${response.status}`,
+        "IMAGE_FETCH_ERROR",
+        void 0,
+        response.status
+      );
     }
     const arrayBuffer = await response.arrayBuffer();
     return Buffer.from(arrayBuffer);

package/dist/index.mjs

@@ -21,15 +21,24 @@ var DEVICE_PRESETS = {
   "galaxy-s23": { width: 360, height: 780, mobile: true, scale: 3 },
   "pixel-7": { width: 412, height: 915, mobile: true, scale: 2.625 }
 };
+function isValidUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
 var ShotAPI = class {
   constructor(config) {
     if (!config.apiKey) {
-      throw new ShotAPIException("API key is required");
+      throw new ShotAPIException("API key is required", "MISSING_API_KEY");
     }
     this.apiKey = config.apiKey;
     this.baseUrl = config.baseUrl || "https://shotapi.dev";
     this.timeout = config.timeout || 3e4;
     this.retries = config.retries ?? 2;
+    this.maxConcurrent = config.maxConcurrent ?? 5;
   }
   /**
    * Capture a screenshot of a URL
@@ -49,7 +58,29 @@ var ShotAPI = class {
    */
   async screenshot(options) {
     if (!options.url) {
-      throw new ShotAPIException("URL is required");
+      throw new ShotAPIException("URL is required", "MISSING_URL");
+    }
+    if (!isValidUrl(options.url)) {
+      throw new ShotAPIException(
+        `Invalid URL: ${options.url}. URL must start with http:// or https://`,
+        "INVALID_URL"
+      );
+    }
+    if (options.quality !== void 0) {
+      if (options.quality < 1 || options.quality > 100) {
+        throw new ShotAPIException(
+          "Quality must be between 1 and 100",
+          "INVALID_QUALITY"
+        );
+      }
+    }
+    if (options.delay !== void 0) {
+      if (options.delay < 0 || options.delay > 1e4) {
+        throw new ShotAPIException(
+          "Delay must be between 0 and 10000 milliseconds",
+          "INVALID_DELAY"
+        );
+      }
     }
     const params = this.buildParams(options);
     return this.request("/api/v1/screenshot", params);
@@ -62,12 +93,7 @@ var ShotAPI = class {
    */
   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);
+    return this.fetchBuffer(response.url);
   }
   /**
    * Capture a screenshot and save to a file
@@ -79,21 +105,42 @@ var ShotAPI = class {
     const response = await this.screenshot(options);
     const buffer = await this.fetchBuffer(response.url);
     const fs = await import("fs/promises");
+    const path = await import("path");
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
     await fs.writeFile(filePath, buffer);
     return response;
   }
   /**
-   * Capture multiple screenshots in batch
+   * Capture multiple screenshots in batch with rate limiting
    *
    * @param urls - Array of URLs to capture
    * @param options - Common options for all screenshots
    * @returns Array of screenshot responses
+   *
+   * @example
+   * ```typescript
+   * const results = await client.batch([
+   *   'https://example.com',
+   *   'https://google.com',
+   *   'https://github.com'
+   * ], { width: 1280 });
+   * ```
    */
   async batch(urls, options) {
-    const promises = urls.map(
-      (url) => this.screenshot({ ...options, url })
-    );
-    return Promise.all(promises);
+    const results = [];
+    for (let i = 0; i < urls.length; i += this.maxConcurrent) {
+      const chunk = urls.slice(i, i + this.maxConcurrent);
+      const promises = chunk.map(
+        (url) => this.screenshot({ ...options, url })
+      );
+      const chunkResults = await Promise.all(promises);
+      results.push(...chunkResults);
+      if (i + this.maxConcurrent < urls.length) {
+        await this.sleep(100);
+      }
+    }
+    return results;
   }
   /**
    * Get device preset dimensions
@@ -132,11 +179,11 @@ var ShotAPI = class {
     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.scale && !options.device) 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.mobile && !options.device) 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);
@@ -152,36 +199,61 @@ var ShotAPI = class {
     const url = `${this.baseUrl}${endpoint}?${params.toString()}`;
     let lastError = null;
     for (let attempt = 0; attempt <= this.retries; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
       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,
+          let errorData = null;
+          try {
+            errorData = await response.json();
+          } catch {
+          }
+          const error = new ShotAPIException(
+            errorData?.error || `HTTP ${response.status}: ${response.statusText}`,
+            errorData?.code || "HTTP_ERROR",
+            errorData?.details,
             response.status
           );
+          if (response.status >= 400 && response.status < 500) {
+            throw error;
+          }
+          lastError = error;
+          if (attempt < this.retries) {
+            await this.sleep(Math.pow(2, attempt) * 1e3);
+          }
+          continue;
         }
+        const data = await response.json();
         return data;
       } catch (error) {
-        lastError = error;
-        if (error instanceof ShotAPIException && error.statusCode && error.statusCode < 500) {
+        clearTimeout(timeoutId);
+        if (error instanceof ShotAPIException) {
           throw error;
         }
+        if (error instanceof Error && error.name === "AbortError") {
+          lastError = new ShotAPIException(
+            `Request timeout after ${this.timeout}ms`,
+            "TIMEOUT"
+          );
+        } else if (error instanceof Error) {
+          lastError = new ShotAPIException(
+            error.message || "Network error",
+            "NETWORK_ERROR"
+          );
+        } else {
+          lastError = new ShotAPIException("Unknown error occurred", "UNKNOWN_ERROR");
+        }
         if (attempt < this.retries) {
           await this.sleep(Math.pow(2, attempt) * 1e3);
         }
       }
     }
-    throw lastError || new ShotAPIException("Request failed after retries");
+    throw lastError || new ShotAPIException("Request failed after retries", "MAX_RETRIES");
   }
   /**
    * Fetch a URL as Buffer
@@ -189,7 +261,12 @@ var ShotAPI = class {
   async fetchBuffer(url) {
     const response = await fetch(url);
     if (!response.ok) {
-      throw new ShotAPIException("Failed to fetch image");
+      throw new ShotAPIException(
+        `Failed to fetch image: HTTP ${response.status}`,
+        "IMAGE_FETCH_ERROR",
+        void 0,
+        response.status
+      );
     }
     const arrayBuffer = await response.arrayBuffer();
     return Buffer.from(arrayBuffer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shotapi/sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Official Node.js SDK for ShotAPI - Screenshot API for Developers",
   "main": "dist/index.js",
   "module": "dist/index.mjs",