ScreenshotOne API JavaScript SDK

Common errors

• TypeError: screenshotone.Client is not a constructor

  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.
  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');`

• APIError: Access key is not valid or provided. (Status: 401, Code: INVALID_ACCESS_KEY)

  cause The provided access key is either missing, incorrect, or not active. This indicates a problem with authentication.
  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.

• APIError: Signature is invalid. (Status: 403, Code: INVALID_SIGNATURE)

  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.
  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.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• npm install screenshotone-api-sdk npm
• yarn add screenshotone-api-sdk yarn
• pnpm add screenshotone-api-sdk pnpm

Imports

• Client
  wrong:

  const Client = require('screenshotone-api-sdk').Client;

  correct:

  import { Client } from 'screenshotone-api-sdk';

  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.
• TakeOptions
  wrong:

  import screenshotone from 'screenshotone-api-sdk'; const options = screenshotone.TakeOptions.url(...);

  correct:

  import { TakeOptions } from 'screenshotone-api-sdk';

  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.
• APIError
  wrong:

  import * as screenshotone from 'screenshotone-api-sdk'; if (error instanceof screenshotone.APIError) { ... }

  correct:

  import { APIError } from 'screenshotone-api-sdk';

  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.

Quickstart

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.

import * as fs from 'fs';
import { Client, TakeOptions, APIError } from 'screenshotone-api-sdk';

// Create API client using environment variables for security
const accessKey = process.env.SCREENSHOTONE_ACCESS_KEY ?? '';
const secretKey = process.env.SCREENSHOTONE_SECRET_KEY ?? '';

if (!accessKey || !secretKey) {
  console.error('SCREENSHOTONE_ACCESS_KEY and SCREENSHOTONE_SECRET_KEY environment variables must be set.');
  process.exit(1);
}

const client = new Client(accessKey, secretKey);

async function generateAndDownloadScreenshot() {
  // Set up options for the screenshot
  const options = TakeOptions
      .url("https://www.example.com")
      .delay(2) // Wait 2 seconds before taking the screenshot
      .blockAds(true)
      .fullPage(true) // Capture the entire page
      .viewportWidth(1280) // Set viewport width
      .viewportHeight(800); // Set viewport height

  try {
      // Generate a signed URL for the screenshot
      const url = client.generateTakeURL(options);
      console.log('Generated screenshot URL:', url);

      // Download the screenshot directly
      console.log('Downloading screenshot...');
      const imageBlob = await client.take(options);

      const buffer = Buffer.from(await imageBlob.arrayBuffer());
      const outputPath = 'example-screenshot.png';
      fs.writeFileSync(outputPath, buffer);
      console.log(`Screenshot saved to ${outputPath}`);
  } catch (error) {
      if (error instanceof APIError) {
          console.error(`ScreenshotOne API Error: ${error.errorMessage} (Status: ${error.httpStatusCode}, Code: ${error.errorCode})`);
          console.error(`Documentation: ${error.documentationUrl}`);
      } else if (error instanceof Error) {
          console.error("An unexpected error occurred:", error.message);
      } else {
          console.error("An unknown error occurred:", error);
      }
  }
}

generateAndDownloadScreenshot();