@nimble-way/nimble-js 0.13.0 → 0.16.0

package/resources/serp.d.mts

@@ -0,0 +1,714 @@
+import { APIResource } from "../core/resource.mjs";
+import { APIPromise } from "../core/api-promise.mjs";
+import { RequestOptions } from "../internal/request-options.mjs";
+export declare class Serp extends APIResource {
+    /**
+     * SERP
+     *
+     * @example
+     * ```ts
+     * const response = await client.serp.run({
+     *   search_engine: 'google_search',
+     * });
+     * ```
+     */
+    run(body: SerpRunParams, options?: RequestOptions): APIPromise<SerpRunResponse>;
+    /**
+     * SERP Async Endpoint
+     *
+     * @example
+     * ```ts
+     * const response = await client.serp.runAsync({
+     *   search_engine: 'google_search',
+     * });
+     * ```
+     */
+    runAsync(body: SerpRunAsyncParams, options?: RequestOptions): APIPromise<SerpRunAsyncResponse>;
+    /**
+     * SERP Batch Endpoint
+     *
+     * @example
+     * ```ts
+     * const response = await client.serp.runBatch({
+     *   inputs: [{}],
+     * });
+     * ```
+     */
+    runBatch(body: SerpRunBatchParams, options?: RequestOptions): APIPromise<SerpRunBatchResponse>;
+}
+export interface SerpRunResponse {
+    data: SerpRunResponse.Data;
+    metadata: SerpRunResponse.Metadata;
+    /**
+     * The status of the task.
+     */
+    status: 'success' | 'skipped' | 'fatal' | 'error' | 'postponed' | 'ignored' | 'rejected' | 'blocked';
+    /**
+     * Unique identifier for the task.
+     */
+    task_id: string;
+    /**
+     * The final URL.
+     */
+    url: string;
+    debug?: SerpRunResponse.Debug;
+    /**
+     * Pagination information if applicable.
+     */
+    pagination?: SerpRunResponse.NextPageParams | Array<SerpRunResponse.UnionMember1>;
+    /**
+     * The HTTP status code of the task.
+     */
+    status_code?: number;
+    /**
+     * List of warnings generated during the task.
+     */
+    warnings?: Array<string>;
+}
+export declare namespace SerpRunResponse {
+    interface Data {
+        /**
+         * Browser actions execution results. Present only when browser_actions were
+         * specified in the request.
+         */
+        browser_actions?: Data.BrowserActions;
+        /**
+         * The cookies collected from browser actions during the task.
+         */
+        cookies?: Array<unknown>;
+        /**
+         * The evaluation results from browser actions during the task.
+         */
+        eval?: Array<unknown>;
+        /**
+         * The http requests from browser actions made during the task.
+         */
+        fetch?: Array<unknown>;
+        /**
+         * The headers received during the task.
+         */
+        headers?: {
+            [key: string]: string;
+        };
+        /**
+         * The HTML content of the page.
+         */
+        html?: string;
+        /**
+         * List of all unique URLs found on the page.
+         */
+        links?: Array<string>;
+        /**
+         * The Markdown version of the HTML content.
+         */
+        markdown?: string;
+        /**
+         * The network capture data collected during the task.
+         */
+        network_capture?: Array<Data.NetworkCapture>;
+        /**
+         * Individual HTML content of each pagination page, before merging.
+         */
+        pages_html?: Array<string>;
+        /**
+         * The parsing results extracted from the HTML & network content.
+         */
+        parsing?: Data.ParsingSuccessResult | Data.ParsingErrorResult | {
+            [key: string]: unknown;
+        };
+        /**
+         * The list of redirects that occurred during the task.
+         */
+        redirects?: Array<Data.Redirect>;
+        /**
+         * Screenshots taken during the task, from browser actions, or the screenshot
+         * format.
+         */
+        screenshots?: Array<unknown>;
+    }
+    namespace Data {
+        /**
+         * Browser actions execution results. Present only when browser_actions were
+         * specified in the request.
+         */
+        interface BrowserActions {
+            results: Array<BrowserActions.Result>;
+            success: boolean;
+            total_duration: number;
+        }
+        namespace BrowserActions {
+            interface Result {
+                duration: number;
+                name: 'goto' | 'wait' | 'wait_for_element' | 'wait_for_navigation' | 'click' | 'fill' | 'press' | 'scroll' | 'auto_scroll' | 'screenshot' | 'get_cookies' | 'eval' | 'fetch';
+                status: 'no-run' | 'in-progress' | 'done' | 'error' | 'skipped';
+                error?: string;
+                result?: unknown;
+            }
+        }
+        interface NetworkCapture {
+            filter: NetworkCapture.Filter;
+            results: Array<NetworkCapture.Result>;
+            errorMessage?: string;
+        }
+        namespace NetworkCapture {
+            interface Filter {
+                validation: boolean;
+                wait_for_requests_count: number;
+                method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE' | 'PATCH';
+                /**
+                 * Resource type for network capture filtering
+                 */
+                resource_type?: 'document' | 'stylesheet' | 'image' | 'media' | 'font' | 'script' | 'texttrack' | 'xhr' | 'fetch' | 'prefetch' | 'eventsource' | 'websocket' | 'manifest' | 'signedexchange' | 'ping' | 'cspviolationreport' | 'preflight' | 'other' | 'fedcm' | Array<'document' | 'stylesheet' | 'image' | 'media' | 'font' | 'script' | 'texttrack' | 'xhr' | 'fetch' | 'prefetch' | 'eventsource' | 'websocket' | 'manifest' | 'signedexchange' | 'ping' | 'cspviolationreport' | 'preflight' | 'other' | 'fedcm'>;
+                status_code?: number | Array<number>;
+                url?: Filter.URL;
+                wait_for_requests_count_timeout?: number;
+            }
+            namespace Filter {
+                interface URL {
+                    type: 'exact' | 'contains';
+                    value: string;
+                }
+            }
+            interface Result {
+                request: Result.Request;
+                response: Result.Response;
+            }
+            namespace Result {
+                interface Request {
+                    headers: {
+                        [key: string]: string;
+                    };
+                    method: string;
+                    /**
+                     * Resource type for network capture filtering
+                     */
+                    resource_type: 'document' | 'stylesheet' | 'image' | 'media' | 'font' | 'script' | 'texttrack' | 'xhr' | 'fetch' | 'prefetch' | 'eventsource' | 'websocket' | 'manifest' | 'signedexchange' | 'ping' | 'cspviolationreport' | 'preflight' | 'other' | 'fedcm';
+                    url: string;
+                    body?: string;
+                }
+                interface Response {
+                    body: string;
+                    headers: {
+                        [key: string]: string;
+                    };
+                    serialization: 'none' | 'base64';
+                    status: number;
+                    status_text: string;
+                }
+            }
+        }
+        interface ParsingSuccessResult {
+            entities: {
+                [key: string]: unknown;
+            };
+            status: 'success';
+        }
+        interface ParsingErrorResult {
+            error: string;
+            status: 'error';
+        }
+        interface Redirect {
+            status_code: number;
+            url: string;
+        }
+    }
+    interface Metadata {
+        /**
+         * The name of the agent used for the query.
+         */
+        agent?: string;
+        /**
+         * The driver used for the task.
+         */
+        driver?: string;
+        /**
+         * The localization identifier for the query.
+         */
+        localization_id?: string;
+        /**
+         * The duration in milliseconds of the query processing.
+         */
+        query_duration?: number;
+        /**
+         * The time when the query was received.
+         */
+        query_time?: string;
+        /**
+         * Additional response parameters.
+         */
+        response_parameters?: unknown;
+        /**
+         * A tag associated with the query.
+         */
+        tag?: string;
+    }
+    interface Debug {
+        /**
+         * Performance metrics collected during the task.
+         */
+        performance_metrics?: {
+            [key: string]: number;
+        };
+        /**
+         * Total bytes used by the proxy during the task.
+         */
+        proxy_total_bytes_usage?: number;
+        /**
+         * The transformed output after applying any transformations.
+         */
+        transformed_output?: unknown;
+        /**
+         * The userbrowser instance using during the task.
+         */
+        userbrowser?: unknown;
+    }
+    interface NextPageParams {
+        next_page_params: {
+            [key: string]: unknown;
+        };
+    }
+    interface UnionMember1 {
+        next_page_params: {
+            [key: string]: unknown;
+        };
+    }
+}
+/**
+ * Response when an async SERP task is created successfully.
+ */
+export interface SerpRunAsyncResponse {
+    /**
+     * Status indicating the async SERP task was created successfully.
+     */
+    status: 'success';
+    /**
+     * The created async task details.
+     */
+    task: SerpRunAsyncResponse.Task;
+}
+export declare namespace SerpRunAsyncResponse {
+    /**
+     * The created async task details.
+     */
+    interface Task {
+        /**
+         * Unique task identifier.
+         */
+        id: string;
+        _query: unknown;
+        /**
+         * Timestamp when the task was created.
+         */
+        created_at: string;
+        /**
+         * Original input data for the task.
+         */
+        input: unknown;
+        /**
+         * Current state of the task.
+         */
+        state: 'pending' | 'success' | 'error';
+        /**
+         * URL for checking the task status.
+         */
+        status_url: string;
+        /**
+         * Account name that owns the task.
+         */
+        account_name?: string;
+        api_type?: 'web' | 'serp' | 'ecommerce' | 'social' | 'media' | 'agent' | 'extract' | 'fast-serp';
+        /**
+         * Batch ID if this task is part of a batch.
+         */
+        batch_id?: string;
+        /**
+         * URL for downloading the task results.
+         */
+        download_url?: string;
+        /**
+         * Error message if the task failed.
+         */
+        error?: string;
+        /**
+         * Classification of the error type.
+         */
+        error_type?: string;
+        /**
+         * Timestamp when the task was last modified.
+         */
+        modified_at?: string;
+        /**
+         * Storage location of the output data.
+         */
+        output_url?: string;
+        /**
+         * HTTP status code from the task execution.
+         */
+        status_code?: number;
+    }
+}
+/**
+ * Response when a batch of SERP tasks is created successfully.
+ */
+export interface SerpRunBatchResponse {
+    /**
+     * Unique identifier for the batch.
+     */
+    batch_id: string;
+    /**
+     * Number of tasks in the batch.
+     */
+    batch_size: number;
+    /**
+     * List of created tasks.
+     */
+    tasks: Array<SerpRunBatchResponse.Task>;
+}
+export declare namespace SerpRunBatchResponse {
+    interface Task {
+        /**
+         * Unique task identifier.
+         */
+        id: string;
+        _query: unknown;
+        /**
+         * Timestamp when the task was created.
+         */
+        created_at: string;
+        /**
+         * Original input data for the task.
+         */
+        input: unknown;
+        /**
+         * Current state of the task.
+         */
+        state: 'pending' | 'success' | 'error';
+        /**
+         * URL for checking the task status.
+         */
+        status_url: string;
+        /**
+         * Account name that owns the task.
+         */
+        account_name?: string;
+        api_type?: 'web' | 'serp' | 'ecommerce' | 'social' | 'media' | 'agent' | 'extract' | 'fast-serp';
+        /**
+         * Batch ID if this task is part of a batch.
+         */
+        batch_id?: string;
+        /**
+         * URL for downloading the task results.
+         */
+        download_url?: string;
+        /**
+         * Error message if the task failed.
+         */
+        error?: string;
+        /**
+         * Classification of the error type.
+         */
+        error_type?: string;
+        /**
+         * Timestamp when the task was last modified.
+         */
+        modified_at?: string;
+        /**
+         * Storage location of the output data.
+         */
+        output_url?: string;
+        /**
+         * HTTP status code from the task execution.
+         */
+        status_code?: number;
+    }
+}
+export interface SerpRunParams {
+    /**
+     * The search engine to query.
+     */
+    search_engine: 'google_search' | 'google_sge' | 'google_aio' | 'google_maps_search' | 'google_maps_reviews' | 'google_maps_place' | 'google_news' | 'google_images' | 'bing_search' | 'yandex_search';
+    /**
+     * ISO Alpha-2 country code used to access the target search engine (e.g. US, DE,
+     * GB).
+     */
+    country?: string;
+    /**
+     * Device type used for the search request.
+     */
+    device?: 'desktop' | 'mobile';
+    /**
+     * Top-level domain for the search engine (e.g. "com", "co.uk", "de").
+     */
+    domain?: string;
+    /**
+     * Locale used for the search request.
+     */
+    locale?: string;
+    /**
+     * Geo-location for the search (canonical Google location name).
+     */
+    location?: string;
+    /**
+     * Number of results to return (1–100).
+     */
+    num_results?: number;
+    /**
+     * The result page number for pagination.
+     */
+    page?: number;
+    /**
+     * When true, the SERP response is parsed into structured JSON.
+     */
+    parse?: boolean;
+    /**
+     * The search keyword or phrase to query.
+     */
+    query?: string;
+    /**
+     * Whether to render the page in a browser before extracting.
+     */
+    render?: boolean;
+    /**
+     * When true, disables Google result filtering (filter=0) so omitted/duplicate and
+     * highly similar pages are also returned. Applies to Google search engines.
+     */
+    show_hidden_results?: boolean;
+}
+export interface SerpRunAsyncParams {
+    /**
+     * The search engine to query.
+     */
+    search_engine: 'google_search' | 'google_sge' | 'google_aio' | 'google_maps_search' | 'google_maps_reviews' | 'google_maps_place' | 'google_news' | 'google_images' | 'bing_search' | 'yandex_search';
+    /**
+     * URL to call back when async operation completes
+     */
+    callback_url?: string;
+    /**
+     * ISO Alpha-2 country code used to access the target search engine (e.g. US, DE,
+     * GB).
+     */
+    country?: string;
+    /**
+     * Device type used for the search request.
+     */
+    device?: 'desktop' | 'mobile';
+    /**
+     * Top-level domain for the search engine (e.g. "com", "co.uk", "de").
+     */
+    domain?: string;
+    /**
+     * Locale used for the search request.
+     */
+    locale?: string;
+    /**
+     * Geo-location for the search (canonical Google location name).
+     */
+    location?: string;
+    /**
+     * Number of results to return (1–100).
+     */
+    num_results?: number;
+    /**
+     * The result page number for pagination.
+     */
+    page?: number;
+    /**
+     * When true, the SERP response is parsed into structured JSON.
+     */
+    parse?: boolean;
+    /**
+     * The search keyword or phrase to query.
+     */
+    query?: string;
+    /**
+     * Whether to render the page in a browser before extracting.
+     */
+    render?: boolean;
+    /**
+     * When true, disables Google result filtering (filter=0) so omitted/duplicate and
+     * highly similar pages are also returned. Applies to Google search engines.
+     */
+    show_hidden_results?: boolean;
+    /**
+     * Whether to compress stored data
+     */
+    storage_compress?: boolean;
+    /**
+     * Custom name for the stored object
+     */
+    storage_object_name?: string;
+    /**
+     * Type of storage to use for results
+     */
+    storage_type?: string;
+    /**
+     * URL for storage location
+     */
+    storage_url?: string;
+}
+export interface SerpRunBatchParams {
+    /**
+     * Array of SERP requests. Each object can include search parameters and
+     * async/storage settings.
+     */
+    inputs: Array<SerpRunBatchParams.Input>;
+    /**
+     * Shared parameters applied to the entire batch. Can include search parameters and
+     * async/storage settings.
+     */
+    shared_inputs?: SerpRunBatchParams.SharedInputs;
+}
+export declare namespace SerpRunBatchParams {
+    interface Input {
+        /**
+         * URL to call back when async operation completes
+         */
+        callback_url?: string;
+        /**
+         * ISO Alpha-2 country code used to access the target search engine (e.g. US, DE,
+         * GB).
+         */
+        country?: string;
+        /**
+         * Device type used for the search request.
+         */
+        device?: 'desktop' | 'mobile';
+        /**
+         * Top-level domain for the search engine (e.g. "com", "co.uk", "de").
+         */
+        domain?: string;
+        /**
+         * Locale used for the search request.
+         */
+        locale?: string;
+        /**
+         * Geo-location for the search (canonical Google location name).
+         */
+        location?: string;
+        /**
+         * Number of results to return (1–100).
+         */
+        num_results?: number;
+        /**
+         * The result page number for pagination.
+         */
+        page?: number;
+        /**
+         * When true, the SERP response is parsed into structured JSON.
+         */
+        parse?: boolean;
+        /**
+         * The search keyword or phrase to query.
+         */
+        query?: string;
+        /**
+         * Whether to render the page in a browser before extracting.
+         */
+        render?: boolean;
+        /**
+         * The search engine to query.
+         */
+        search_engine?: 'google_search' | 'google_sge' | 'google_aio' | 'google_maps_search' | 'google_maps_reviews' | 'google_maps_place' | 'google_news' | 'google_images' | 'bing_search' | 'yandex_search';
+        /**
+         * When true, disables Google result filtering (filter=0) so omitted/duplicate and
+         * highly similar pages are also returned. Applies to Google search engines.
+         */
+        show_hidden_results?: boolean;
+        /**
+         * Whether to compress stored data
+         */
+        storage_compress?: boolean;
+        /**
+         * Custom name for the stored object
+         */
+        storage_object_name?: string;
+        /**
+         * Type of storage to use for results
+         */
+        storage_type?: string;
+        /**
+         * URL for storage location
+         */
+        storage_url?: string;
+    }
+    /**
+     * Shared parameters applied to the entire batch. Can include search parameters and
+     * async/storage settings.
+     */
+    interface SharedInputs {
+        /**
+         * URL to call back when async operation completes
+         */
+        callback_url?: string;
+        /**
+         * ISO Alpha-2 country code used to access the target search engine (e.g. US, DE,
+         * GB).
+         */
+        country?: string;
+        /**
+         * Device type used for the search request.
+         */
+        device?: 'desktop' | 'mobile';
+        /**
+         * Top-level domain for the search engine (e.g. "com", "co.uk", "de").
+         */
+        domain?: string;
+        /**
+         * Locale used for the search request.
+         */
+        locale?: string;
+        /**
+         * Geo-location for the search (canonical Google location name).
+         */
+        location?: string;
+        /**
+         * Number of results to return (1–100).
+         */
+        num_results?: number;
+        /**
+         * The result page number for pagination.
+         */
+        page?: number;
+        /**
+         * When true, the SERP response is parsed into structured JSON.
+         */
+        parse?: boolean;
+        /**
+         * The search keyword or phrase to query.
+         */
+        query?: string;
+        /**
+         * Whether to render the page in a browser before extracting.
+         */
+        render?: boolean;
+        /**
+         * The search engine to query.
+         */
+        search_engine?: 'google_search' | 'google_sge' | 'google_aio' | 'google_maps_search' | 'google_maps_reviews' | 'google_maps_place' | 'google_news' | 'google_images' | 'bing_search' | 'yandex_search';
+        /**
+         * When true, disables Google result filtering (filter=0) so omitted/duplicate and
+         * highly similar pages are also returned. Applies to Google search engines.
+         */
+        show_hidden_results?: boolean;
+        /**
+         * Whether to compress stored data
+         */
+        storage_compress?: boolean;
+        /**
+         * Custom name for the stored object
+         */
+        storage_object_name?: string;
+        /**
+         * Type of storage to use for results
+         */
+        storage_type?: string;
+        /**
+         * URL for storage location
+         */
+        storage_url?: string;
+    }
+}
+export declare namespace Serp {
+    export { type SerpRunResponse as SerpRunResponse, type SerpRunAsyncResponse as SerpRunAsyncResponse, type SerpRunBatchResponse as SerpRunBatchResponse, type SerpRunParams as SerpRunParams, type SerpRunAsyncParams as SerpRunAsyncParams, type SerpRunBatchParams as SerpRunBatchParams, };
+}
+//# sourceMappingURL=serp.d.mts.map