clearscrape 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,374 @@
+/**
+ * ClearScrape SDK Types
+ */
+/**
+ * Configuration options for the ClearScrape client
+ */
+interface ClearScrapeConfig {
+    /** Your ClearScrape API key */
+    apiKey: string;
+    /** Base URL for the API (defaults to https://api.clearscrape.io) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (defaults to 60000) */
+    timeout?: number;
+    /** Number of retries for failed requests (defaults to 3) */
+    retries?: number;
+}
+/**
+ * Options for scraping a URL
+ */
+interface ScrapeOptions {
+    /** Target URL to scrape */
+    url: string;
+    /** HTTP method (defaults to GET) */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** Enable JavaScript rendering (+5 credits) */
+    jsRender?: boolean;
+    /** Use premium residential proxies (+10 credits) */
+    premiumProxy?: boolean;
+    /** Enable antibot bypass (+25 credits) */
+    antibot?: boolean;
+    /** 2-letter country code for geo-targeting */
+    proxyCountry?: string;
+    /** CSS selector to wait for (requires jsRender) */
+    waitFor?: string;
+    /** Fixed wait time in milliseconds (max 30000) */
+    wait?: number;
+    /** Scroll page to load lazy content */
+    autoScroll?: boolean;
+    /** Capture full page screenshot */
+    screenshot?: boolean;
+    /** Capture screenshot of specific element */
+    screenshotSelector?: string;
+    /** Custom HTTP headers */
+    headers?: Record<string, string>;
+    /** Request body for POST/PUT requests */
+    body?: string | Record<string, unknown>;
+    /** Domain extractor (amazon, walmart, google, etc.) */
+    domain?: DomainType;
+}
+/**
+ * Supported domain extractors
+ */
+type DomainType = 'amazon' | 'walmart' | 'google' | 'google_shopping' | 'ebay' | 'target' | 'etsy' | 'bestbuy' | 'homedepot' | 'zillow' | 'yelp' | 'indeed' | 'linkedin_jobs';
+/**
+ * Response from a successful scrape request
+ */
+interface ScrapeResponse {
+    success: true;
+    data: {
+        /** Raw HTML content */
+        html: string;
+        /** Extracted text content */
+        text?: string;
+        /** Base64 encoded screenshot (if requested) */
+        screenshot?: string;
+        /** Extracted data (if domain extractor used) */
+        extracted?: Record<string, unknown>;
+    };
+    metadata: {
+        /** Final URL after redirects */
+        url: string;
+        /** HTTP status code */
+        statusCode: number;
+        /** Credits consumed */
+        cost: number;
+        /** Request duration in milliseconds */
+        duration: number;
+        /** Response size in bytes */
+        byteSize: number;
+        /** Options used for the request */
+        options: {
+            js_render: boolean;
+            premium_proxy: boolean;
+            antibot: boolean;
+            proxy_country?: string;
+        };
+        /** Domain extractor used */
+        domain?: string;
+    };
+}
+/**
+ * Response from a failed scrape request
+ */
+interface ScrapeErrorResponse {
+    success: false;
+    error: string;
+    message: string;
+    /** Credits required (for insufficient credits error) */
+    required?: number;
+}
+/**
+ * Amazon product data extracted by domain API
+ */
+interface AmazonProduct {
+    title: string;
+    price: string;
+    originalPrice?: string;
+    currency: string;
+    rating: string;
+    reviewCount: string;
+    availability: string;
+    seller: string;
+    asin: string;
+    brand?: string;
+    images: string[];
+    features: string[];
+    breadcrumbs: string[];
+    description?: string;
+    specifications?: Record<string, string>;
+}
+/**
+ * Google SERP data extracted by domain API
+ */
+interface GoogleSerpResult {
+    searchQuery: string;
+    totalResults: string;
+    organicResults: Array<{
+        position: number;
+        title: string;
+        url: string;
+        displayUrl: string;
+        description: string;
+    }>;
+    featuredSnippet?: {
+        title: string;
+        content: string;
+        url: string;
+    };
+    peopleAlsoAsk?: Array<{
+        question: string;
+        answer: string;
+    }>;
+    relatedSearches?: string[];
+}
+/**
+ * Proxy configuration for residential proxy service
+ */
+interface ProxyConfig {
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+}
+/**
+ * Browser connection options for Scraping Browser
+ */
+interface BrowserOptions {
+    /** 2-letter country code for geo-targeting */
+    proxyCountry?: string;
+}
+/**
+ * ClearScrape API error
+ */
+declare class ClearScrapeError extends Error {
+    readonly statusCode: number;
+    readonly response?: ScrapeErrorResponse;
+    constructor(message: string, statusCode: number, response?: ScrapeErrorResponse);
+}
+/**
+ * Insufficient credits error
+ */
+declare class InsufficientCreditsError extends ClearScrapeError {
+    readonly required: number;
+    constructor(message: string, required: number);
+}
+/**
+ * Rate limit error
+ */
+declare class RateLimitError extends ClearScrapeError {
+    constructor(message: string);
+}
+
+/**
+ * ClearScrape API Client
+ *
+ * @example
+ * ```typescript
+ * import { ClearScrape } from 'clearscrape';
+ *
+ * const client = new ClearScrape({ apiKey: 'your-api-key' });
+ *
+ * const result = await client.scrape({
+ *   url: 'https://example.com',
+ *   jsRender: true
+ * });
+ *
+ * console.log(result.data.html);
+ * ```
+ */
+declare class ClearScrape {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly retries;
+    constructor(config: ClearScrapeConfig);
+    /**
+     * Scrape a URL and return the HTML content
+     *
+     * @param options - Scraping options
+     * @returns Promise resolving to scrape response
+     *
+     * @example
+     * ```typescript
+     * // Basic scrape
+     * const result = await client.scrape({ url: 'https://example.com' });
+     *
+     * // With JavaScript rendering
+     * const result = await client.scrape({
+     *   url: 'https://example.com',
+     *   jsRender: true,
+     *   waitFor: '.content'
+     * });
+     *
+     * // With premium proxy and country targeting
+     * const result = await client.scrape({
+     *   url: 'https://example.com',
+     *   premiumProxy: true,
+     *   proxyCountry: 'us'
+     * });
+     * ```
+     */
+    scrape(options: ScrapeOptions): Promise<ScrapeResponse>;
+    /**
+     * Scrape a URL and return only the HTML content
+     *
+     * @param url - URL to scrape
+     * @param options - Additional scraping options
+     * @returns Promise resolving to HTML string
+     */
+    getHtml(url: string, options?: Omit<ScrapeOptions, 'url'>): Promise<string>;
+    /**
+     * Scrape a URL and return only the text content
+     *
+     * @param url - URL to scrape
+     * @param options - Additional scraping options
+     * @returns Promise resolving to text string
+     */
+    getText(url: string, options?: Omit<ScrapeOptions, 'url'>): Promise<string>;
+    /**
+     * Take a screenshot of a URL
+     *
+     * @param url - URL to screenshot
+     * @param options - Additional options
+     * @returns Promise resolving to base64 encoded screenshot
+     *
+     * @example
+     * ```typescript
+     * const screenshot = await client.screenshot('https://example.com');
+     * // Save to file
+     * fs.writeFileSync('screenshot.png', Buffer.from(screenshot, 'base64'));
+     * ```
+     */
+    screenshot(url: string, options?: Omit<ScrapeOptions, 'url' | 'screenshot'>): Promise<string>;
+    /**
+     * Scrape using a domain-specific extractor (Amazon, Walmart, Google, etc.)
+     *
+     * @param url - URL to scrape
+     * @param domain - Domain extractor to use
+     * @returns Promise resolving to extracted data
+     *
+     * @example
+     * ```typescript
+     * // Extract Amazon product data
+     * const product = await client.extract(
+     *   'https://www.amazon.com/dp/B09V3KXJPB',
+     *   'amazon'
+     * );
+     * console.log(product.title, product.price);
+     *
+     * // Extract Google SERP data
+     * const serp = await client.extract(
+     *   'https://www.google.com/search?q=best+laptops',
+     *   'google'
+     * );
+     * console.log(serp.organicResults);
+     * ```
+     */
+    extract<T = Record<string, unknown>>(url: string, domain: ScrapeOptions['domain']): Promise<T>;
+    /**
+     * Get proxy configuration for the residential proxy service
+     *
+     * @param options - Proxy options
+     * @returns Proxy configuration object
+     *
+     * @example
+     * ```typescript
+     * // Basic proxy config
+     * const proxy = client.getProxyConfig();
+     * // { host: 'proxy.clearscrape.io', port: 8000, username: '...', password: '...' }
+     *
+     * // With country targeting
+     * const proxy = client.getProxyConfig({ country: 'us' });
+     *
+     * // With session sticky IP
+     * const proxy = client.getProxyConfig({ session: 'my-session-123' });
+     * ```
+     */
+    getProxyConfig(options?: {
+        country?: string;
+        session?: string;
+    }): ProxyConfig;
+    /**
+     * Get proxy URL string for use with HTTP clients
+     *
+     * @param options - Proxy options
+     * @returns Proxy URL string
+     *
+     * @example
+     * ```typescript
+     * const proxyUrl = client.getProxyUrl({ country: 'us' });
+     * // 'http://apikey-country-us:apikey@proxy.clearscrape.io:8000'
+     *
+     * // Use with axios
+     * const HttpsProxyAgent = require('https-proxy-agent');
+     * const agent = new HttpsProxyAgent(client.getProxyUrl());
+     * axios.get(url, { httpsAgent: agent });
+     * ```
+     */
+    getProxyUrl(options?: {
+        country?: string;
+        session?: string;
+    }): string;
+    /**
+     * Get WebSocket URL for Scraping Browser (Playwright/Puppeteer)
+     *
+     * @param options - Browser options
+     * @returns WebSocket URL string
+     *
+     * @example
+     * ```typescript
+     * // Use with Playwright
+     * const { chromium } = require('playwright');
+     * const browser = await chromium.connectOverCDP(client.getBrowserWsUrl());
+     *
+     * // Use with Puppeteer
+     * const puppeteer = require('puppeteer-core');
+     * const browser = await puppeteer.connect({
+     *   browserWSEndpoint: client.getBrowserWsUrl()
+     * });
+     *
+     * // With country targeting
+     * const wsUrl = client.getBrowserWsUrl({ proxyCountry: 'gb' });
+     * ```
+     */
+    getBrowserWsUrl(options?: BrowserOptions): string;
+    /**
+     * Build the API request payload
+     */
+    private buildPayload;
+    /**
+     * Make an API request with retries
+     */
+    private makeRequest;
+    /**
+     * Handle API errors
+     */
+    private handleError;
+    /**
+     * Sleep for a specified duration
+     */
+    private sleep;
+}
+
+export { type AmazonProduct, type BrowserOptions, ClearScrape, type ClearScrapeConfig, ClearScrapeError, type DomainType, type GoogleSerpResult, InsufficientCreditsError, type ProxyConfig, RateLimitError, type ScrapeErrorResponse, type ScrapeOptions, type ScrapeResponse, ClearScrape as default };