{"id":16209,"library":"screenshotone-api-sdk","title":"ScreenshotOne API JavaScript SDK","description":"The `screenshotone-api-sdk` is the official client library for the ScreenshotOne.com API, enabling developers to programmatically generate and download screenshots of any website. It provides a fluent API for configuring various screenshot options, such as delay, ad blocking, and more, directly mirroring the latest API specifications. The current stable version is 1.1.21. The package appears to have an active release cadence, with continuous integration indicated by its build badge and consistent updates to synchronize with the underlying ScreenshotOne API. Key differentiators include its tight integration with the ScreenshotOne service, offering specific error handling for API-level issues, and providing both URL generation and direct screenshot download functionalities. It is designed for both JavaScript and TypeScript environments, shipping with its own type definitions.","status":"active","version":"1.1.21","language":"javascript","source_language":"en","source_url":"https://github.com/screenshotone/jssdk","tags":["javascript","screenshot","phantom","phantomjs","screenshots","webkit","webkit2png","url2png","headless","typescript"],"install":[{"cmd":"npm install screenshotone-api-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add screenshotone-api-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add screenshotone-api-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The SDK primarily uses named exports. While CommonJS `require` can technically access it, the recommended approach is ESM named imports for modern Node.js and browser environments, especially when using TypeScript.","wrong":"const Client = require('screenshotone-api-sdk').Client;","symbol":"Client","correct":"import { Client } from 'screenshotone-api-sdk';"},{"note":"TakeOptions is a static class for fluently building screenshot parameters. It is exported as a named export. The common mistake is trying to access it as a property of a default import, which does not exist.","wrong":"import screenshotone from 'screenshotone-api-sdk'; const options = screenshotone.TakeOptions.url(...);","symbol":"TakeOptions","correct":"import { TakeOptions } from 'screenshotone-api-sdk';"},{"note":"APIError is a specific error class for handling responses from the ScreenshotOne API. It should be imported directly as a named export for correct `instanceof` checks and type inference. While `* as screenshotone` works, importing directly is clearer and often preferred.","wrong":"import * as screenshotone from 'screenshotone-api-sdk'; if (error instanceof screenshotone.APIError) { ... }","symbol":"APIError","correct":"import { APIError } from 'screenshotone-api-sdk';"}],"quickstart":{"code":"import * as fs from 'fs';\nimport { Client, TakeOptions, APIError } from 'screenshotone-api-sdk';\n\n// Create API client using environment variables for security\nconst accessKey = process.env.SCREENSHOTONE_ACCESS_KEY ?? '';\nconst secretKey = process.env.SCREENSHOTONE_SECRET_KEY ?? '';\n\nif (!accessKey || !secretKey) {\n  console.error('SCREENSHOTONE_ACCESS_KEY and SCREENSHOTONE_SECRET_KEY environment variables must be set.');\n  process.exit(1);\n}\n\nconst client = new Client(accessKey, secretKey);\n\nasync function generateAndDownloadScreenshot() {\n  // Set up options for the screenshot\n  const options = TakeOptions\n      .url(\"https://www.example.com\")\n      .delay(2) // Wait 2 seconds before taking the screenshot\n      .blockAds(true)\n      .fullPage(true) // Capture the entire page\n      .viewportWidth(1280) // Set viewport width\n      .viewportHeight(800); // Set viewport height\n\n  try {\n      // Generate a signed URL for the screenshot\n      const url = client.generateTakeURL(options);\n      console.log('Generated screenshot URL:', url);\n\n      // Download the screenshot directly\n      console.log('Downloading screenshot...');\n      const imageBlob = await client.take(options);\n\n      const buffer = Buffer.from(await imageBlob.arrayBuffer());\n      const outputPath = 'example-screenshot.png';\n      fs.writeFileSync(outputPath, buffer);\n      console.log(`Screenshot saved to ${outputPath}`);\n  } catch (error) {\n      if (error instanceof APIError) {\n          console.error(`ScreenshotOne API Error: ${error.errorMessage} (Status: ${error.httpStatusCode}, Code: ${error.errorCode})`);\n          console.error(`Documentation: ${error.documentationUrl}`);\n      } else if (error instanceof Error) {\n          console.error(\"An unexpected error occurred:\", error.message);\n      } else {\n          console.error(\"An unknown error occurred:\", error);\n      }\n  }\n}\n\ngenerateAndDownloadScreenshot();","lang":"typescript","description":"This quickstart demonstrates how to initialize the ScreenshotOne client, configure screenshot options using the fluent API, generate a signed URL, and then download the resulting screenshot to a local file. It also includes error handling for both API-specific and generic errors."},"warnings":[{"fix":"Store `SCREENSHOTONE_ACCESS_KEY` and `SCREENSHOTONE_SECRET_KEY` in environment variables. Access them via `process.env.VARIABLE_NAME` in Node.js or a build-time substitution for client-side applications.","message":"API keys (access key and secret key) are crucial for authentication and generating valid, signed URLs. Exposing these keys directly in client-side code or committing them to public repositories is a severe security risk. Always use environment variables or a secure configuration management system.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always wrap `await client.take(options)` in a `try...catch` block. Utilize `if (error instanceof APIError)` to differentiate between API-specific errors (with status codes, error codes, and documentation URLs) and other runtime errors.","message":"Network requests for downloading screenshots (`client.take()`) are asynchronous operations and can fail due to various reasons (network issues, API limits, invalid options). Proper error handling, including specific `APIError` checks, is essential.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Before upgrading to a new major SDK version, consult the package's changelog or GitHub releases page for any breaking changes related to API options, client methods, or error structures. Test thoroughly in a development environment.","message":"Major version updates to the underlying ScreenshotOne API might introduce breaking changes to options or responses that the SDK needs to adapt to. While the SDK aims to stay synchronized, always review the changelog for new major versions of the SDK itself.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For ES Modules, use `import { Client } from 'screenshotone-api-sdk';`. If forced to use CommonJS, ensure you're accessing the named export correctly: `const { Client } = require('screenshotone-api-sdk');`","cause":"Attempting to use `require()` for the `Client` class in a CommonJS module when the SDK is primarily designed for ESM or when incorrectly accessing named exports.","error":"TypeError: screenshotone.Client is not a constructor"},{"fix":"Double-check your `accessKey` and `secretKey` values. Ensure they are correctly copied from your ScreenshotOne.com dashboard and are being passed to the `Client` constructor.","cause":"The provided access key is either missing, incorrect, or not active. This indicates a problem with authentication.","error":"APIError: Access key is not valid or provided. (Status: 401, Code: INVALID_ACCESS_KEY)"},{"fix":"Verify that your `secretKey` is correct and has not been truncated or altered. Ensure no extra characters or whitespace are included. Regenerate your secret key on the ScreenshotOne.com dashboard if issues persist.","cause":"The request signature generated by the SDK (using your secret key) does not match the signature expected by the API. This often happens if the secret key is incorrect or corrupted.","error":"APIError: Signature is invalid. (Status: 403, Code: INVALID_SIGNATURE)"}],"ecosystem":"npm"}