@websitescreenshotworld/sdk 0.0.0-stage → 0.1.1

package/dist/esm/models/capture-options.d.ts

@@ -0,0 +1,144 @@
+import type { CaptureFormat, DeviceCategory, MediaCategory, PageSourceFormat, ScrollMode, WatermarkLocation } from "./tokens.js";
+/** The browser window the page is rendered in. */
+export interface ViewportOptions {
+    /** Width in CSS pixels, 250 to 7680. Default 1920. */
+    width?: number;
+    /** Height in CSS pixels, 250 to 7680. Default 1080. */
+    height?: number;
+    /** Device pixel ratio, 1 to 3. Default 1. */
+    deviceScaleFactor?: number;
+}
+/** The position the browser reports. Latitude and longitude are sent together or not at all. */
+export interface GeolocationOptions {
+    /** -90 to 90. */
+    latitude?: number;
+    /** -180 to 180. */
+    longitude?: number;
+    /** In metres, 1 to 10000. Default 100. */
+    accuracy?: number;
+}
+/** Elements to act on before the capture. */
+export interface SelectorOptions {
+    /** Capture only the element this XPath selects. At most 512 characters. */
+    xpath?: string;
+    /**
+     * Elements to hide: up to 25 comma-separated CSS selectors (an XPath starting with `//` works
+     * too), at most 2000 characters. Each is applied on its own; one the browser rejects is skipped.
+     */
+    hide?: string;
+    /** CSS selector of an element to click. At most 512 characters. */
+    click?: string;
+    /** CSS selector of an element to hover. At most 512 characters. */
+    hover?: string;
+}
+/** Route the capture through a proxy. Requires the ProxyLocation plan feature. */
+export interface ProxyOptions {
+    /** A country from the `proxyCountries` of `instantSnap.catalog()`. */
+    country: string;
+}
+/** A strip with the capture time and URL. Passing this turns it on. Not available for video. */
+export interface TimestampWatermarkOptions {
+    /** Default `true`. */
+    enabled?: boolean;
+    /** Default `"top"`. */
+    location?: WatermarkLocation;
+    /** Hex colour. Default `"#000000"`. */
+    fontColor?: string;
+    /** Hex colour. Default `"#FFFFFF"`. */
+    backgroundColor?: string;
+}
+/**
+ * Also keep the page source. Charged as a second capture, capped at 10 MB, not available with
+ * `captureFile`.
+ */
+export interface PageSourceOptions {
+    /** Default `"html"`. */
+    format?: PageSourceFormat;
+}
+/** The bucket `captureToBucket` uploads to. Needs `region` or `endpointUrl`. */
+export interface S3DeliveryOptions {
+    accessKeyId: string;
+    /** Sent to the API but never returned. */
+    secretAccessKey: string;
+    bucket: string;
+    region?: string;
+    /** An https endpoint for S3-compatible storage. */
+    endpointUrl?: string;
+    /** Default `false`. */
+    forcePathStyle?: boolean;
+    keyPrefix?: string;
+    /** Wait up to 30 seconds for the upload before answering. Default `false`. */
+    waitForSync?: boolean;
+}
+/**
+ * What to capture and how. Only `url` is required; anything left out takes the API's default,
+ * which `instantSnap.defaults()` lists.
+ */
+export interface CaptureOptions {
+    /** The page to capture: absolute http or https, without credentials, at most 2048 characters. */
+    url: string;
+    /** Default `"image"`. */
+    mediaCategory?: MediaCategory;
+    /** Must belong to `mediaCategory`. */
+    format?: CaptureFormat;
+    viewport?: ViewportOptions;
+    /** Default `"desktop"`. */
+    deviceCategory?: DeviceCategory;
+    /** A device from `instantSnap.catalog()`, case-insensitive. Mobile defaults to "iPhone 13". */
+    emulatedDevice?: string;
+    /** Default `"viewport"`, or `"scroll"` for video. */
+    scrollMode?: ScrollMode;
+    /** Default `false`. */
+    autoHeight?: boolean;
+    /** 250 to 100000, and within the format's own ceiling. */
+    maxHeight?: number;
+    /** Percent, 50 to 100. Default 100. */
+    zoom?: number;
+    /** Default `true`. */
+    blockAds?: boolean;
+    /** Default `true`. */
+    blockPopUps?: boolean;
+    /**
+     * Press Escape after the pop-up pass and again after scrolling (once in a video), for a modal
+     * that closes on Escape. Default `false`.
+     */
+    pressEscape?: boolean;
+    /** 1000 to 60000. Default 30000. */
+    pageTimeoutMs?: number;
+    /** The pause after each scroll step of a full-page capture, 0 to 10000. Default 500. */
+    scrollingDelayMs?: number;
+    userAgent?: string;
+    /** A BCP 47 language tag. */
+    locale?: string;
+    /** An IANA time zone. */
+    timeZone?: string;
+    /**
+     * Sent with every request the page makes, with names exactly as given. Requires the
+     * RequestHeadersCookies plan feature.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Set for the URL's origin, with names exactly as given. Requires the RequestHeadersCookies plan
+     * feature.
+     */
+    cookies?: Record<string, string>;
+    geolocation?: GeolocationOptions;
+    selectors?: SelectorOptions;
+    proxy?: ProxyOptions;
+    timestampWatermark?: TimestampWatermarkOptions;
+    pageSource?: PageSourceOptions;
+    /** Also receives the `capture.succeeded` or `capture.failed` webhook. Requires the Webhooks plan feature. */
+    callbackUrl?: string;
+    /**
+     * Async only (`submit` and `submitToBucket`): the seconds the capture may take in the browser,
+     * 30 to 300; time in the queue does not count. Server default 120. The server refuses it on the
+     * other capture operations.
+     */
+    timeout?: number;
+}
+/** Options for `instantSnap.captureFile()`, which cannot keep the page source. */
+export type CaptureFileOptions = Omit<CaptureOptions, "pageSource">;
+/** Options for `instantSnap.captureToBucket()`. */
+export interface CaptureToBucketOptions extends CaptureOptions {
+    s3Delivery: S3DeliveryOptions;
+}

package/dist/esm/models/capture-options.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/models/capture.d.ts

@@ -0,0 +1,108 @@
+import type { ErrorCode } from "../error-codes.js";
+import type { CaptureFormat, CaptureStatus, MediaCategory, PageSourceFormat, ResponseType, S3DeliveryStatus } from "./tokens.js";
+/** The page source kept alongside a capture. */
+export interface PageSource {
+    format: PageSourceFormat;
+    contentType: string | null;
+    sizeBytes: number | null;
+    /** Lowercase hex SHA-256 of the source. */
+    sha256: string | null;
+    /** Short-lived; reissued on every read. */
+    downloadUrl: string | null;
+}
+/** How the upload to your bucket went. Present for `captureToBucket` only. */
+export interface S3Delivery {
+    status: S3DeliveryStatus;
+    bucket: string;
+    key: string | null;
+    /** Masked to its last four characters. */
+    accessKeyId: string | null;
+    error: string | null;
+}
+/**
+ * A capture, as `capture`, `captureToBucket`, `submit`, `submitToBucket`, `get` and `wait` return
+ * it.
+ */
+export interface Capture {
+    id: string;
+    /**
+     * `succeeded`, `failed` and the other end states; an async capture from `submit` or
+     * `submitToBucket` reads `queued` until a browser takes it and `running` while it is captured.
+     */
+    status: CaptureStatus;
+    responseType: ResponseType;
+    mediaCategory: MediaCategory;
+    /** The format written. */
+    format: CaptureFormat | null;
+    contentType: string | null;
+    sizeBytes: number | null;
+    width: number | null;
+    height: number | null;
+    /** How long the capture took. */
+    durationMs: number | null;
+    /** The status the website answered with. */
+    pageHttpStatus: number | null;
+    capturedAt: Date | null;
+    /** Where the browser ended up, when the page redirected. */
+    finalUrl: string | null;
+    /** Lowercase hex SHA-256 of the file. */
+    mediaSha256: string | null;
+    /**
+     * Valid for 60 minutes and reissued on every `get`. `null` for `captureToBucket` and for captures
+     * without a file.
+     */
+    downloadUrl: string | null;
+    /** When the file is deleted, 24 hours after the capture. */
+    expiresAt: Date | null;
+    pageSource: PageSource | null;
+    s3Delivery: S3Delivery | null;
+    callbackUrl: string | null;
+    /** Why a `failed` or `timed_out` capture ended. */
+    errorCode: ErrorCode | null;
+    /** The default set the capture was taken under, such as `v1`. */
+    specVersion: string;
+}
+/** A capture as the API sends it. */
+export interface WireCapture {
+    id: string;
+    status: string;
+    response_type: string;
+    media_category: string;
+    format?: string | null;
+    content_type?: string | null;
+    size_bytes?: number | null;
+    width?: number | null;
+    height?: number | null;
+    duration_ms?: number | null;
+    page_http_status?: number | null;
+    captured_at?: string | null;
+    final_url?: string | null;
+    media_sha256?: string | null;
+    download_url?: string | null;
+    expires_at?: string | null;
+    page_source?: WirePageSource | null;
+    s3_delivery?: WireS3Delivery | null;
+    callback_url?: string | null;
+    error_code?: string | null;
+    spec_version: string;
+}
+export interface WirePageSource {
+    format: string;
+    content_type?: string | null;
+    size_bytes?: number | null;
+    sha256?: string | null;
+    download_url?: string | null;
+}
+export interface WireS3Delivery {
+    status: string;
+    bucket: string;
+    key?: string | null;
+    access_key_id?: string | null;
+    error?: string | null;
+}
+/** The fields every form of a capture shares, webhooks included. */
+export type CaptureFields = Omit<Capture, "downloadUrl" | "pageSource" | "s3Delivery">;
+export declare function parseCaptureFields(wire: WireCapture): CaptureFields;
+export declare function parseCapture(wire: WireCapture): Capture;
+export declare function parsePageSourceFields(wire: WirePageSource): Omit<PageSource, "downloadUrl">;
+export declare function parseS3DeliveryFields(wire: WireS3Delivery): Omit<S3Delivery, "accessKeyId">;

package/dist/esm/models/capture.js

@@ -0,0 +1,57 @@
+import { parseDate } from "../wire.js";
+export function parseCaptureFields(wire) {
+    return {
+        id: wire.id,
+        status: wire.status,
+        responseType: wire.response_type,
+        mediaCategory: wire.media_category,
+        format: wire.format ?? null,
+        contentType: wire.content_type ?? null,
+        sizeBytes: wire.size_bytes ?? null,
+        width: wire.width ?? null,
+        height: wire.height ?? null,
+        durationMs: wire.duration_ms ?? null,
+        pageHttpStatus: wire.page_http_status ?? null,
+        capturedAt: parseDate(wire.captured_at),
+        finalUrl: wire.final_url ?? null,
+        mediaSha256: wire.media_sha256 ?? null,
+        expiresAt: parseDate(wire.expires_at),
+        callbackUrl: wire.callback_url ?? null,
+        errorCode: wire.error_code ?? null,
+        specVersion: wire.spec_version,
+    };
+}
+export function parseCapture(wire) {
+    return {
+        ...parseCaptureFields(wire),
+        downloadUrl: wire.download_url ?? null,
+        pageSource: wire.page_source
+            ? {
+                ...parsePageSourceFields(wire.page_source),
+                downloadUrl: wire.page_source.download_url ?? null,
+            }
+            : null,
+        s3Delivery: wire.s3_delivery
+            ? {
+                ...parseS3DeliveryFields(wire.s3_delivery),
+                accessKeyId: wire.s3_delivery.access_key_id ?? null,
+            }
+            : null,
+    };
+}
+export function parsePageSourceFields(wire) {
+    return {
+        format: wire.format,
+        contentType: wire.content_type ?? null,
+        sizeBytes: wire.size_bytes ?? null,
+        sha256: wire.sha256 ?? null,
+    };
+}
+export function parseS3DeliveryFields(wire) {
+    return {
+        status: wire.status,
+        bucket: wire.bucket,
+        key: wire.key ?? null,
+        error: wire.error ?? null,
+    };
+}

package/dist/esm/models/defaults.d.ts

@@ -0,0 +1,82 @@
+/** The viewport a capture uses when it does not set one. */
+export interface DefaultViewport {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+}
+/**
+ * The values a capture takes for fields it does not send, and the limits it is checked against.
+ * Every field is optional because the set is versioned by `specVersion` and may change.
+ */
+export interface Defaults {
+    specVersion?: string;
+    responseType?: string;
+    mediaCategory?: string;
+    /** The default format of each media category. */
+    format?: Record<string, string>;
+    /** The formats each media category accepts. */
+    formats?: Record<string, string[]>;
+    deviceCategory?: string;
+    emulatedDevice?: string;
+    viewport?: DefaultViewport;
+    zoom?: number;
+    scrollMode?: string;
+    autoHeight?: boolean;
+    autoHeightMaxHeight?: number | null;
+    autoHeightMaxHeightWebp?: number;
+    blockAds?: boolean;
+    blockPopUps?: boolean;
+    pressEscape?: boolean;
+    pageTimeoutMs?: number;
+    scrollingDelayMs?: number;
+    geolocation?: boolean;
+    geolocationAccuracy?: number;
+    waitForCloudSync?: boolean;
+    timestampWatermark?: Record<string, unknown>;
+    pageSource?: Record<string, unknown>;
+    limits?: Record<string, unknown>;
+    /** Settings the API leaves to the browser rather than fixing a value. */
+    leftToTheBrowser?: string[];
+}
+/** What `emulatedDevice` and `proxy.country` accept. */
+export interface Catalog {
+    emulatedDevices: string[];
+    proxyCountries: string[];
+}
+export interface WireDefaults {
+    spec_version?: string;
+    response_type?: string;
+    media_category?: string;
+    format?: Record<string, string>;
+    formats?: Record<string, string[]>;
+    device_category?: string;
+    emulated_device?: string;
+    viewport?: {
+        width: number;
+        height: number;
+        device_scale_factor: number;
+    };
+    zoom?: number;
+    scroll_mode?: string;
+    auto_height?: boolean;
+    auto_height_max_height?: number | null;
+    auto_height_max_height_webp?: number;
+    block_ads?: boolean;
+    block_pop_ups?: boolean;
+    press_escape?: boolean;
+    page_timeout_ms?: number;
+    scrolling_delay_ms?: number;
+    geolocation?: boolean;
+    geolocation_accuracy?: number;
+    wait_for_cloud_sync?: boolean;
+    timestamp_watermark?: Record<string, unknown>;
+    page_source?: Record<string, unknown>;
+    limits?: Record<string, unknown>;
+    left_to_the_browser?: string[];
+}
+export interface WireCatalog {
+    emulated_devices: string[];
+    proxy_countries: string[];
+}
+export declare function parseDefaults(wire: WireDefaults): Defaults;
+export declare function parseCatalog(wire: WireCatalog): Catalog;

package/dist/esm/models/defaults.js

@@ -0,0 +1,42 @@
+import { camelCaseKeys } from "../wire.js";
+export function parseDefaults(wire) {
+    const defaults = {
+        specVersion: wire.spec_version,
+        responseType: wire.response_type,
+        mediaCategory: wire.media_category,
+        format: wire.format,
+        formats: wire.formats,
+        deviceCategory: wire.device_category,
+        emulatedDevice: wire.emulated_device,
+        viewport: wire.viewport && {
+            width: wire.viewport.width,
+            height: wire.viewport.height,
+            deviceScaleFactor: wire.viewport.device_scale_factor,
+        },
+        zoom: wire.zoom,
+        scrollMode: wire.scroll_mode,
+        autoHeight: wire.auto_height,
+        autoHeightMaxHeight: wire.auto_height_max_height,
+        autoHeightMaxHeightWebp: wire.auto_height_max_height_webp,
+        blockAds: wire.block_ads,
+        blockPopUps: wire.block_pop_ups,
+        pressEscape: wire.press_escape,
+        pageTimeoutMs: wire.page_timeout_ms,
+        scrollingDelayMs: wire.scrolling_delay_ms,
+        geolocation: wire.geolocation,
+        geolocationAccuracy: wire.geolocation_accuracy,
+        waitForCloudSync: wire.wait_for_cloud_sync,
+        timestampWatermark: camelCaseKeys(wire.timestamp_watermark),
+        pageSource: camelCaseKeys(wire.page_source),
+        limits: camelCaseKeys(wire.limits),
+        leftToTheBrowser: wire.left_to_the_browser,
+    };
+    // Fields the API did not send stay absent rather than showing up as `undefined`.
+    return Object.fromEntries(Object.entries(defaults).filter(([, value]) => value !== undefined));
+}
+export function parseCatalog(wire) {
+    return {
+        emulatedDevices: wire.emulated_devices,
+        proxyCountries: wire.proxy_countries,
+    };
+}

package/dist/esm/models/tokens.d.ts

@@ -0,0 +1,92 @@
+/** Where a capture is in its life. */
+export declare const CaptureStatus: {
+    readonly Pending: "pending";
+    /** An async capture accepted and waiting for a browser. */
+    readonly Queued: "queued";
+    /** An async capture a browser is taking now. */
+    readonly Running: "running";
+    readonly Succeeded: "succeeded";
+    /** The end state of `captureFile`: the file went back in the answer and is not kept. */
+    readonly Delivered: "delivered";
+    readonly Failed: "failed";
+    readonly TimedOut: "timed_out";
+    readonly Expired: "expired";
+};
+export type CaptureStatus = (typeof CaptureStatus)[keyof typeof CaptureStatus] | (string & {});
+/** How the API answered a capture. */
+export declare const ResponseType: {
+    readonly Json: "json";
+    readonly ByFormat: "by_format";
+    readonly CloudStorage: "cloud_storage";
+};
+export type ResponseType = (typeof ResponseType)[keyof typeof ResponseType] | (string & {});
+export declare const MediaCategory: {
+    readonly Image: "image";
+    readonly Video: "video";
+    readonly Pdf: "pdf";
+};
+export type MediaCategory = (typeof MediaCategory)[keyof typeof MediaCategory] | (string & {});
+/** The file format. It must belong to the capture's media category. */
+export declare const CaptureFormat: {
+    readonly Png: "png";
+    readonly Jpeg: "jpeg";
+    readonly Webp: "webp";
+    readonly Tiff: "tiff";
+    readonly Mp4: "mp4";
+    readonly Webm: "webm";
+    readonly Mov: "mov";
+    readonly Gif: "gif";
+    readonly ImagePdf: "image_pdf";
+    readonly DocumentPdf: "document_pdf";
+};
+export type CaptureFormat = (typeof CaptureFormat)[keyof typeof CaptureFormat] | (string & {});
+export declare const DeviceCategory: {
+    readonly Desktop: "desktop";
+    readonly Mobile: "mobile";
+};
+export type DeviceCategory = (typeof DeviceCategory)[keyof typeof DeviceCategory] | (string & {});
+export declare const ScrollMode: {
+    /** Only what fits in the viewport. */
+    readonly Viewport: "viewport";
+    /** The full page. */
+    readonly Scroll: "scroll";
+};
+export type ScrollMode = (typeof ScrollMode)[keyof typeof ScrollMode] | (string & {});
+export declare const WatermarkLocation: {
+    readonly Top: "top";
+    readonly Bottom: "bottom";
+};
+export type WatermarkLocation = (typeof WatermarkLocation)[keyof typeof WatermarkLocation] | (string & {});
+export declare const PageSourceFormat: {
+    readonly Html: "html";
+    readonly Json: "json";
+    readonly Text: "text";
+};
+export type PageSourceFormat = (typeof PageSourceFormat)[keyof typeof PageSourceFormat] | (string & {});
+/** Where an upload to your bucket stands. */
+export declare const S3DeliveryStatus: {
+    readonly NotStarted: "not_started";
+    readonly InProgress: "in_progress";
+    readonly Completed: "completed";
+    readonly Failed: "failed";
+};
+export type S3DeliveryStatus = (typeof S3DeliveryStatus)[keyof typeof S3DeliveryStatus] | (string & {});
+/** What a trigger-now call did. */
+export declare const TriggerStatus: {
+    readonly Triggered: "triggered";
+    /** A capture was already queued or running; nothing new was started or charged. */
+    readonly AlreadyPending: "already_pending";
+};
+export type TriggerStatus = (typeof TriggerStatus)[keyof typeof TriggerStatus] | (string & {});
+/** Who started a scheduled web page's pending capture. */
+export declare const TriggeredBy: {
+    readonly Api: "api";
+    readonly Ui: "ui";
+};
+export type TriggeredBy = (typeof TriggeredBy)[keyof typeof TriggeredBy] | (string & {});
+/** The product a webhook event comes from. */
+export declare const Product: {
+    readonly InstantSnap: "instant_snap";
+    readonly AutoSchedule: "auto_schedule";
+};
+export type Product = (typeof Product)[keyof typeof Product] | (string & {});

package/dist/esm/models/tokens.js

@@ -0,0 +1,82 @@
+// Each token is a set of named constants plus a type that also accepts any other string, so a value
+// the API adds later still comes through while the known ones keep their autocompletion.
+/** Where a capture is in its life. */
+export const CaptureStatus = {
+    Pending: "pending",
+    /** An async capture accepted and waiting for a browser. */
+    Queued: "queued",
+    /** An async capture a browser is taking now. */
+    Running: "running",
+    Succeeded: "succeeded",
+    /** The end state of `captureFile`: the file went back in the answer and is not kept. */
+    Delivered: "delivered",
+    Failed: "failed",
+    TimedOut: "timed_out",
+    Expired: "expired",
+};
+/** How the API answered a capture. */
+export const ResponseType = {
+    Json: "json",
+    ByFormat: "by_format",
+    CloudStorage: "cloud_storage",
+};
+export const MediaCategory = {
+    Image: "image",
+    Video: "video",
+    Pdf: "pdf",
+};
+/** The file format. It must belong to the capture's media category. */
+export const CaptureFormat = {
+    Png: "png",
+    Jpeg: "jpeg",
+    Webp: "webp",
+    Tiff: "tiff",
+    Mp4: "mp4",
+    Webm: "webm",
+    Mov: "mov",
+    Gif: "gif",
+    ImagePdf: "image_pdf",
+    DocumentPdf: "document_pdf",
+};
+export const DeviceCategory = {
+    Desktop: "desktop",
+    Mobile: "mobile",
+};
+export const ScrollMode = {
+    /** Only what fits in the viewport. */
+    Viewport: "viewport",
+    /** The full page. */
+    Scroll: "scroll",
+};
+export const WatermarkLocation = {
+    Top: "top",
+    Bottom: "bottom",
+};
+export const PageSourceFormat = {
+    Html: "html",
+    Json: "json",
+    Text: "text",
+};
+/** Where an upload to your bucket stands. */
+export const S3DeliveryStatus = {
+    NotStarted: "not_started",
+    InProgress: "in_progress",
+    Completed: "completed",
+    Failed: "failed",
+};
+/** What a trigger-now call did. */
+export const TriggerStatus = {
+    Triggered: "triggered",
+    /** A capture was already queued or running; nothing new was started or charged. */
+    AlreadyPending: "already_pending",
+};
+/** Who started a scheduled web page's pending capture. */
+export const TriggeredBy = {
+    Api: "api",
+    Ui: "ui",
+};
+/** The product a webhook event comes from. */
+export const Product = {
+    InstantSnap: "instant_snap",
+    AutoSchedule: "auto_schedule",
+};

package/dist/esm/models/trigger-result.d.ts

@@ -0,0 +1,20 @@
+import type { TriggerStatus, TriggeredBy } from "./tokens.js";
+/** What `autoSchedule.triggerNow` did. The capture's outcome arrives later by webhook. */
+export interface TriggerResult {
+    /** `triggered`, or `already_pending` when a capture was already queued or running. */
+    status: TriggerStatus;
+    webPageId: string;
+    triggeredBy: TriggeredBy;
+    /** When the capture was queued; for `already_pending`, when the earlier trigger was. */
+    triggeredAt: Date;
+    /** One sentence for a person. */
+    message: string;
+}
+export interface WireTriggerResult {
+    status: string;
+    web_page_id: string;
+    triggered_by: string;
+    triggered_at: string;
+    message: string;
+}
+export declare function parseTriggerResult(wire: WireTriggerResult): TriggerResult;

package/dist/esm/models/trigger-result.js

@@ -0,0 +1,10 @@
+import { parseDate } from "../wire.js";
+export function parseTriggerResult(wire) {
+    return {
+        status: wire.status,
+        webPageId: wire.web_page_id,
+        triggeredBy: wire.triggered_by,
+        triggeredAt: parseDate(wire.triggered_at),
+        message: wire.message,
+    };
+}