Registry / http-networking / screenshotone-api-sdk

screenshotone-api-sdk

JSON →
library1.1.21jsnpmunverified

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.

npm install screenshotone-api-sdk
INSTALL
IMPORT
SIG · SCREENSHOTONE-API-
S
screenshotone-api-sdk
http-networkingjavascriptv1.1.21
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client
import { Client } from 'screenshotone-api-sdk';
const Client = require('screenshotone-api-sdk').Client;
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
import { TakeOptions } from 'screenshotone-api-sdk';
import screenshotone from 'screenshotone-api-sdk'; const options = screenshotone.TakeOptions.url(...);
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
import { APIError } from 'screenshotone-api-sdk';
import * as screenshotone from 'screenshotone-api-sdk'; if (error instanceof screenshotone.APIError) { ... }
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.

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();
Debug
Known issues
gotchaAPI 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.
affects: >=1.0.0
gotchaNetwork 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.
affects: >=1.0.0
breakingMajor 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.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: screenshotone.Client is not a constructor
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)
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)
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.
Upgrade
Version history
1.1.21latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
11 hits · last 30 days
node
8
Amazon
1
OpenAI (training)
1
Resources
screenshotone-api-sdk — npm install screenshotone-api-sdk · libregistry