@search1api/client 0.2.1 → 0.4.0

package/README.md

@@ -32,12 +32,43 @@ for (const result of response.results) {
 
 The constructor reads `SEARCH1API_API_KEY` when `apiKey` is omitted.
 
+`searchService` selects one engine (`google` by default), for example `bing`,
+`bingcn`, `yandex`, `reddit`, `github`, `arxiv`, `wikipedia`, or `grokipedia`.
+`page` requests a later results page on engines with native pagination
+(`bing`, `bingcn`, `baidu`, `grokipedia`). Results carry `published_date` when the source
+exposes one. Engine-specific fields are in each result's optional `metadata`:
+GitHub uses `metadata.kind`, `metadata.stars`, `metadata.language`, and
+`metadata.num_comments`; Hacker News news results use `metadata.story_url`,
+`metadata.points`, and `metadata.num_comments`. The former top-level paths
+are removed in 0.4.0; `published_date` stays at the top level.
+
 CommonJS projects can load the same client with `require`:
 
 ```js
 const { Search1API } = require('@search1api/client');
 ```
 
+## Ask
+
+`ask` sends a natural-language request and lets Search1API choose the engines
+and time window. It returns at most 10 results ranked by relevance, and
+`intent` reports what was searched:
+
+```ts
+const answer = await client.ask(
+  'What are developers saying about Bun 1.3 this month?'
+);
+
+console.log(answer.intent.sources, answer.intent.time_range);
+for (const result of answer.results) {
+  console.log(result.relevance, result.source, result.title, result.link);
+}
+```
+
+A completed request costs 5 credits. Ask is not available with pay-per-request
+payments, and its default timeout is 45 seconds. Use `search` when you already
+know which engine and keywords you want.
+
 ## Deepcrawl
 
 `deepcrawl` starts a task and waits for it to finish:
@@ -71,10 +102,22 @@ console.log(screenshot.contentType, screenshot.requestId);
 The client also provides `news`, `crawl`, `sitemap`, `trending`, `extract`,
 `usage`, and their batch variants where the HTTP API supports them.
 
+`feedback` reports a Search1API problem, missing capability, or confusing
+documentation. It is free and is never retried automatically, because a retry
+could file a duplicate report. Do not include credentials or personal data:
+
+```ts
+await client.feedback('Results for this query have no publication dates', {
+  category: 'feature_request',
+  requestId: 'the x-search1api-request-id of the original request',
+});
+```
+
 Requests time out after 30 seconds and retry `429` and transient `5xx`
 responses twice by default. Authentication, payment, and validation errors are
-never retried. Deepcrawl task creation is not retried automatically because it
-is not idempotent. Configure this with `timeoutMs` and `maxRetries`.
+never retried. Deepcrawl task creation and feedback are not retried
+automatically because they are not idempotent. Configure this with `timeoutMs`
+and `maxRetries`.
 
 ## Development
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { BatchResponse, CrawlOptions, CrawlRequest, CrawlResponse, DeepcrawlAcceptedResponse, DeepcrawlOptions, DeepcrawlStatusResponse, ExtractOptions, ExtractResponse, HealthResponse, JsonValue, NewsOptions, NewsRequest, NewsResponse, RequestOptions, Search1APIOptions, SearchOptions, SearchRequest, SearchResponse, ScreenshotOptions, ScreenshotResponse, SitemapOptions, SitemapResponse, TimeRange, TrendingOptions, TrendingResponse, UsageResponse, WaitForDeepcrawlOptions } from './types.js';
+import type { AskResponse, BatchResponse, CrawlOptions, CrawlRequest, CrawlResponse, DeepcrawlAcceptedResponse, DeepcrawlOptions, DeepcrawlStatusResponse, ExtractOptions, ExtractResponse, FeedbackOptions, FeedbackResponse, HealthResponse, JsonValue, NewsOptions, NewsRequest, NewsResponse, RequestOptions, Search1APIOptions, SearchOptions, SearchRequest, SearchResponse, ScreenshotOptions, ScreenshotResponse, SitemapOptions, SitemapResponse, TimeRange, TrendingOptions, TrendingResponse, UsageResponse, WaitForDeepcrawlOptions } from './types.js';
 export declare class Search1API {
     readonly apiKey: string;
     readonly baseUrl: string;
@@ -12,6 +12,12 @@ export declare class Search1API {
     searchBatch(requests: SearchRequest[], requestOptions?: RequestOptions): Promise<BatchResponse<SearchResponse>>;
     news(query: string, options?: NewsOptions, requestOptions?: RequestOptions): Promise<NewsResponse>;
     newsBatch(requests: NewsRequest[], requestOptions?: RequestOptions): Promise<BatchResponse<NewsResponse>>;
+    /**
+     * Agentic search: a decision model picks the engines and time window from a
+     * natural-language query and returns only relevant results. 5 credits per
+     * completed request; requires an API key or OAuth token.
+     */
+    ask(query: string, requestOptions?: RequestOptions): Promise<AskResponse>;
     crawl(url: string, options?: CrawlOptions, requestOptions?: RequestOptions): Promise<CrawlResponse>;
     crawlBatch(requests: CrawlRequest[], requestOptions?: RequestOptions): Promise<CrawlResponse[]>;
     screenshot(url: string, options?: ScreenshotOptions, requestOptions?: RequestOptions): Promise<ScreenshotResponse>;
@@ -24,6 +30,11 @@ export declare class Search1API {
     deepcrawl(url: string, options?: DeepcrawlOptions, waitOptions?: WaitForDeepcrawlOptions, requestOptions?: RequestOptions): Promise<DeepcrawlStatusResponse>;
     usage(period?: TimeRange, requestOptions?: RequestOptions): Promise<UsageResponse>;
     health(requestOptions?: RequestOptions): Promise<HealthResponse>;
+    /**
+     * Report a Search1API problem, missing capability, or confusing docs. Free.
+     * Never include credentials or personal data in the report.
+     */
+    feedback(message: string, options?: FeedbackOptions, requestOptions?: RequestOptions): Promise<FeedbackResponse>;
     private requestJson;
     private request;
     private fetchOnce;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/generated.d.ts

@@ -3,6 +3,26 @@
  * Do not make direct changes to the file.
  */
 export interface paths {
+    "/feedback": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Report a Search1API problem or feature request
+         * @description Report a Search1API problem, missing capability, or confusing documentation encountered during a task. Only message is required. Optional request_id refers to the original problem request. Do not include credentials, personal data, or private user content. Reports are stored in Agentback and linked to an opaque account reference. Do not report every empty result or retry the same report automatically; feedback should not block the main task. Returns 201 only after storage succeeds. Maximum JSON body size: 16 KiB. Limited to 10 submissions per account per minute at a Cloudflare location. Free to call.
+         */
+        post: operations["feedback"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/screenshot": {
         parameters: {
             query?: never;
@@ -34,7 +54,7 @@ export interface paths {
         put?: never;
         /**
          * Search the web using multiple search engines
-         * @description Search the live public web when the answer depends on current information, sources, or research a model's training data cannot cover. Returns ranked results with id, title, URL, and snippet across 13+ engines, with optional images. Set `crawl_results` to pull the top N result pages in the same call — each crawled page is billed as an additional crawl — or pass a result URL to POST /crawl separately. Costs 1 credit per request.
+         * @description Search the live public web when the answer depends on current information, sources, or research a model's training data cannot cover. Returns ranked results with id, title, URL, snippet, and `published_date` (ISO 8601, when the engine exposes one) across 13+ engines, with optional images. Set `crawl_results` to pull the top N result pages in the same call — each crawled page is billed as an additional crawl — or pass a result URL to POST /crawl separately. Costs 1 credit per request.
          */
         post: operations["search"];
         delete?: never;
@@ -54,7 +74,7 @@ export interface paths {
         put?: never;
         /**
          * Search news articles across multiple sources
-         * @description Search recent news when the question is about events, announcements, or coverage rather than reference material. Returns articles from verified publishers with title, URL, snippet, and optional full page content, filterable by site, language, and time range. For questions that are not time-sensitive, prefer POST /search. Costs 1 credit per request.
+         * @description Search recent news when the question is about events, announcements, or coverage rather than reference material. Returns articles from verified publishers with title, URL, snippet, `published_date` (ISO 8601, when known), and optional full page content, filterable by site, language, and time range. For questions that are not time-sensitive, prefer POST /search. Costs 1 credit per request.
          */
         post: operations["news"];
         delete?: never;
@@ -63,6 +83,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/ask": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Search the engines a natural-language request calls for
+         * @description Agentic search. Describe what you are looking for in plain language and let a decision model (currently TypeSafe Jev) decide where to look. It picks up to five engines (web search, Hacker News, Reddit, GitHub, X, arXiv, Wikipedia, IMDb, WeChat, YouTube), rewrites the request into search keywords, infers a publication window from phrases such as "this week", searches the engines in parallel, and returns only the results judged relevant, merged and ranked, so agents read fewer off-topic results. The request takes only `query`; engines, keywords, and the window are always chosen by the model, and the response reports them in `intent`. Use POST /search instead when you already know the engine and keywords and want its raw ranking. Costs 5 credits per request.
+         */
+        post: operations["ask"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/crawl": {
         parameters: {
             query?: never;
@@ -74,7 +114,7 @@ export interface paths {
         put?: never;
         /**
          * Crawl a URL and extract its content
-         * @description Fetch one public URL and return its readable title and body as clean text, with navigation, boilerplate, and scripts stripped. Use it on a URL the user supplied or one returned by POST /search. To ingest a whole site rather than a single page, use POST /deepcrawl. Costs 1 credit per request.
+         * @description Fetch one public URL and return its readable title and body as clean text, with navigation, boilerplate, and scripts stripped. Use it on a URL the user supplied or one returned by POST /search. To ingest a whole site rather than a single page, use POST /deepcrawl. Send an array of request objects to crawl several URLs in one call: the response is an array containing only the URLs that succeeded, in no guaranteed order, so match items back to your input by `crawlParameters.url`; failed URLs are omitted and not charged. `enable_fallback` is accepted as a snake_case alias of `enableFallback`. Costs 1 credit per request.
          */
         post: operations["crawl"];
         delete?: never;
@@ -94,7 +134,7 @@ export interface paths {
         put?: never;
         /**
          * Extract sitemap URLs from a website
-         * @description Discover the public URLs of a site when you need to know which pages exist before fetching any of them — scoping a crawl, auditing coverage, or locating a section. Returns the links discovered for the given page or domain; it does not fetch their content. Costs 1 credit per request.
+         * @description Discover the public URLs of a site when you need to know which pages exist before fetching any of them — scoping a crawl, auditing coverage, or locating a section. With the default `type: "sitemap"` this reads the site's own sitemap: `Sitemap:` directives in robots.txt first, then the conventional paths, following sitemap index files and gzipped sitemaps, and returns the URLs it declares for the requested host. A site that publishes no sitemap falls back to the links found on the given page. Use `type: "all"` to skip the sitemap and get every link on that one page instead, including links to other hosts. Neither mode fetches page content. Costs 1 credit per request.
          */
         post: operations["sitemap"];
         delete?: never;
@@ -227,7 +267,7 @@ export interface paths {
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
-        /** @description Search1API error. Payment challenges may use RFC 9457 problem detail fields. */
+        /** @description Search1API error. Every JSON error carries `ok: false`, `error` (a short status-derived label) and `message` (human-readable detail); validation failures add `errors`. Payment challenges may use RFC 9457 problem detail fields. */
         ApiError: {
             /** @enum {boolean} */
             ok?: false;
@@ -249,9 +289,11 @@ export interface components {
         SearchParameters: {
             query: string;
             /** @enum {string} */
-            search_service?: "google" | "bing" | "duckduckgo" | "yahoo" | "youtube" | "x" | "reddit" | "github" | "arxiv" | "wechat" | "bilibili" | "imdb" | "wikipedia" | "" | "sogou" | "baidu" | "360" | "quark";
+            search_service?: "google" | "bing" | "bingcn" | "duckduckgo" | "yahoo" | "yandex" | "youtube" | "x" | "reddit" | "github" | "arxiv" | "wechat" | "bilibili" | "imdb" | "wikipedia" | "grokipedia" | "" | "baidu" | "360" | "quark";
             /** @default 5 */
             max_results: number;
+            /** @default 1 */
+            page: number;
             /** @default 0 */
             crawl_results: number;
             /** @default false */
@@ -318,6 +360,35 @@ export interface components {
             link: string;
             snippet: string;
             content?: string;
+            /**
+             * @description When the page was published, as ISO 8601: `YYYY-MM-DD` when only the day is known (web search engines), or `YYYY-MM-DDTHH:MM:SSZ` in UTC when the source carries a time (x, reddit, github, arxiv, youtube, bilibili, wechat, news feeds). Omitted when the source exposes no date, so treat it as optional per result.
+             * @example 2026-09-03
+             */
+            published_date?: string;
+            metadata?: components["schemas"]["SearchResultMetadata"];
+        } & {
+            [key: string]: unknown;
+        };
+        /** @description Optional engine-specific fields. Omitted when none apply. GitHub fields appear on POST /search; Hacker News fields appear on POST /news. */
+        SearchResultMetadata: {
+            /**
+             * @description What a `github` result is: a repository, an issue, a pull request, or a discussion. Only present for `search_service: "github"`.
+             * @enum {string}
+             */
+            kind?: "repo" | "issue" | "pr" | "discussion";
+            /** @description Stargazer count of a `github` repository result (`metadata.kind: "repo"`). */
+            stars?: number;
+            /** @description Primary language of a `github` repository result (`metadata.kind: "repo"`). Omitted when GitHub reports none. */
+            language?: string;
+            /** @description Comment count on a `github` issue, pull request or discussion, or on a `hackernews` thread (POST /news). */
+            num_comments?: number;
+            /**
+             * Format: uri
+             * @description POST /news with `search_service: "hackernews"` only: the submitted article. `link` is the Hacker News discussion thread; `metadata.story_url` is omitted for Ask HN / Show HN text posts.
+             */
+            story_url?: string;
+            /** @description POST /news with `search_service: "hackernews"` only: upvotes on the thread. */
+            points?: number;
         } & {
             [key: string]: unknown;
         };
@@ -365,6 +436,44 @@ export interface components {
                 totalCost: number;
             };
         };
+        AskResult: {
+            title: string;
+            /** Format: uri */
+            link: string;
+            snippet: string;
+            /**
+             * @description When the page was published, as ISO 8601 (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`). Omitted when the engine exposes no date.
+             * @example 2026-09-03
+             */
+            published_date?: string;
+            /** @description Engine that returned the result. */
+            source: string;
+            /** @description How likely the result is to be about the query, two decimals. Only results scoring at least 0.5 are returned. */
+            relevance: number;
+        };
+        AskResponse: {
+            /** @description The query as sent. */
+            query: string;
+            /** @description How the request was interpreted and searched. */
+            intent: {
+                /** @description Query sent to the first engine in `sources`. Each engine searches its own span of the request words, without platform names; the time window is applied as a filter. */
+                search_query: string;
+                /** @description Engines searched. */
+                sources: string[];
+                /**
+                 * @description Publication window applied, or null for none. year means the past 365 days, not the current calendar year.
+                 * @enum {string|null}
+                 */
+                time_range: "day" | "week" | "month" | "year" | null;
+            };
+            /** @description Relevant results from every engine, best first, with duplicates merged. May be empty. */
+            results: components["schemas"]["AskResult"][];
+            /** @description Engines that failed while others completed. The request is still charged. */
+            errors: {
+                source: string;
+                message: string;
+            }[];
+        };
         CrawlResult: {
             title: string;
             /** Format: uri */
@@ -436,6 +545,11 @@ export interface components {
             credential_type: "api_key" | "oauth";
             client_id?: string | null;
         };
+        FeedbackResponse: {
+            id: string;
+            /** @enum {string} */
+            status: "new";
+        };
     };
     responses: never;
     parameters: never;
@@ -445,6 +559,115 @@ export interface components {
 }
 export type $defs = Record<string, never>;
 export interface operations {
+    feedback: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    message: string;
+                    intent?: string;
+                    /**
+                     * @default other
+                     * @enum {string}
+                     */
+                    category?: "bug" | "feature_request" | "docs" | "other";
+                    request_id?: string;
+                    agent?: {
+                        name?: string;
+                        model?: string;
+                    };
+                };
+            };
+        };
+        responses: {
+            /** @description Successful response */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FeedbackResponse"];
+                };
+            };
+            /** @description Bad Request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Payload Too Large */
+            413: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Unsupported Media Type */
+            415: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Too Many Requests */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Internal Server Error */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Service Unavailable */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+        };
+    };
     screenshot: {
         parameters: {
             query?: never;
@@ -622,9 +845,11 @@ export interface operations {
                 "application/json": {
                     query: string;
                     /** @enum {string} */
-                    search_service?: "google" | "bing" | "duckduckgo" | "yahoo" | "youtube" | "x" | "reddit" | "github" | "arxiv" | "wechat" | "bilibili" | "imdb" | "wikipedia" | "" | "sogou" | "baidu" | "360" | "quark";
+                    search_service?: "google" | "bing" | "bingcn" | "duckduckgo" | "yahoo" | "yandex" | "youtube" | "x" | "reddit" | "github" | "arxiv" | "wechat" | "bilibili" | "imdb" | "wikipedia" | "grokipedia" | "" | "baidu" | "360" | "quark";
                     /** @default 5 */
                     max_results?: number;
+                    /** @default 1 */
+                    page?: number;
                     /** @default 0 */
                     crawl_results?: number;
                     /** @default false */
@@ -639,9 +864,11 @@ export interface operations {
                 } | {
                     query: string;
                     /** @enum {string} */
-                    search_service?: "google" | "bing" | "duckduckgo" | "yahoo" | "youtube" | "x" | "reddit" | "github" | "arxiv" | "wechat" | "bilibili" | "imdb" | "wikipedia" | "" | "sogou" | "baidu" | "360" | "quark";
+                    search_service?: "google" | "bing" | "bingcn" | "duckduckgo" | "yahoo" | "yandex" | "youtube" | "x" | "reddit" | "github" | "arxiv" | "wechat" | "bilibili" | "imdb" | "wikipedia" | "grokipedia" | "" | "baidu" | "360" | "quark";
                     /** @default 5 */
                     max_results?: number;
+                    /** @default 1 */
+                    page?: number;
                     /** @default 0 */
                     crawl_results?: number;
                     /** @default false */
@@ -852,6 +1079,87 @@ export interface operations {
             };
         };
     };
+    ask: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description What you are looking for, in natural language. Platform hints ("on Reddit", "papers") and time hints ("this week") steer engine and time-range selection. */
+                    query: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Successful response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AskResponse"];
+                };
+            };
+            /** @description Bad Request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Payment Required */
+            402: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Too Many Requests */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Internal Server Error */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Bad Gateway */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+        };
+    };
     crawl: {
         parameters: {
             query?: never;
@@ -911,6 +1219,24 @@ export interface operations {
                     "application/problem+json": components["schemas"]["ApiError"];
                 };
             };
+            /** @description Not Found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Gone */
+            410: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
             /** @description Validation Error */
             422: {
                 headers: {