@search1api/client 0.2.0 → 0.3.0

package/README.md

@@ -3,7 +3,7 @@
 Official TypeScript client for Search1API. It supports Node.js 18+ and runtimes
 with a standards-compatible `fetch` implementation.
 
-API documentation: [search1api.com/docs](https://www.search1api.com/docs)
+API documentation: [search1api.com/docs](https://s1.dev/docs)
 
 ## Install
 
@@ -32,12 +32,39 @@ 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.
+
 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 +98,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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"}