@search1api/client 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Search1API
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,80 @@
+# Search1API TypeScript SDK
+
+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)
+
+## Install
+
+```bash
+npm install @search1api/client
+```
+
+## Search
+
+```ts
+import { Search1API } from '@search1api/client';
+
+const client = new Search1API({
+  apiKey: process.env.SEARCH1API_API_KEY,
+});
+
+const response = await client.search('latest AI agent frameworks', {
+  maxResults: 10,
+  crawlResults: 3,
+});
+
+for (const result of response.results) {
+  console.log(result.title, result.link);
+}
+```
+
+The constructor reads `SEARCH1API_API_KEY` when `apiKey` is omitted.
+
+CommonJS projects can load the same client with `require`:
+
+```js
+const { Search1API } = require('@search1api/client');
+```
+
+## Deepcrawl
+
+`deepcrawl` starts a task and waits for it to finish:
+
+```ts
+const result = await client.deepcrawl('https://example.com', { type: 'all' });
+console.log(result.zipUrl);
+```
+
+Use `startDeepcrawl`, `getDeepcrawlStatus`, and `waitForDeepcrawl` when the
+application needs to control task persistence or polling itself.
+
+## Other APIs
+
+The client also provides `news`, `crawl`, `sitemap`, `trending`, `extract`,
+`usage`, and their batch or asynchronous variants where the HTTP API supports
+them.
+
+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`.
+
+## Development
+
+```bash
+npm install
+npm run generate
+npm run typecheck
+npm test
+npm run build
+```
+
+The generated wire-level types come from the checked-in public OpenAPI
+snapshot. Update the snapshot before regenerating types when the API contract
+changes.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+import type { BatchResponse, CrawlOptions, CrawlRequest, CrawlResponse, DeepcrawlAcceptedResponse, DeepcrawlOptions, DeepcrawlStatusResponse, ExtractOptions, ExtractResponse, HealthResponse, JsonValue, NewsOptions, NewsRequest, NewsResponse, RequestOptions, Search1APIOptions, SearchOptions, SearchRequest, SearchResponse, SitemapOptions, SitemapResponse, TimeRange, TrendingOptions, TrendingResponse, UsageResponse, WaitForDeepcrawlOptions } from './types.js';
+export declare class Search1API {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly maxRetries: number;
+    readonly timeoutMs: number;
+    private readonly defaultHeaders;
+    private readonly fetchClient;
+    private readonly retryDelayMs;
+    constructor(options?: Search1APIOptions | string);
+    search(query: string, options?: SearchOptions, requestOptions?: RequestOptions): Promise<SearchResponse>;
+    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>>;
+    crawl(url: string, options?: CrawlOptions, requestOptions?: RequestOptions): Promise<CrawlResponse>;
+    crawlBatch(requests: CrawlRequest[], requestOptions?: RequestOptions): Promise<CrawlResponse[]>;
+    sitemap(url: string, options?: SitemapOptions, requestOptions?: RequestOptions): Promise<SitemapResponse>;
+    trending(searchService: string, options?: TrendingOptions, requestOptions?: RequestOptions): Promise<TrendingResponse>;
+    extract<T = JsonValue>(url: string, options?: ExtractOptions, requestOptions?: RequestOptions): Promise<ExtractResponse<T>>;
+    startDeepcrawl(url: string, options?: DeepcrawlOptions, requestOptions?: RequestOptions): Promise<DeepcrawlAcceptedResponse>;
+    getDeepcrawlStatus(taskId: string, requestOptions?: RequestOptions): Promise<DeepcrawlStatusResponse>;
+    waitForDeepcrawl(taskId: string, options?: WaitForDeepcrawlOptions): Promise<DeepcrawlStatusResponse>;
+    deepcrawl(url: string, options?: DeepcrawlOptions, waitOptions?: WaitForDeepcrawlOptions, requestOptions?: RequestOptions): Promise<DeepcrawlStatusResponse>;
+    usage(period?: TimeRange, requestOptions?: RequestOptions): Promise<UsageResponse>;
+    health(requestOptions?: RequestOptions): Promise<HealthResponse>;
+    private requestJson;
+    private request;
+    private fetchOnce;
+    private retryDelay;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/errors.d.ts

@@ -0,0 +1,41 @@
+import type { ApiErrorBody, DeepcrawlStatusResponse } from './types.js';
+export declare class Search1APIError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class Search1APIConfigurationError extends Search1APIError {
+}
+export declare class APIConnectionError extends Search1APIError {
+}
+export declare class APITimeoutError extends APIConnectionError {
+}
+export declare class APIStatusError extends Search1APIError {
+    readonly body?: ApiErrorBody;
+    readonly headers: Headers;
+    readonly requestId?: string;
+    readonly status: number;
+    constructor(message: string, status: number, headers: Headers, body?: ApiErrorBody);
+}
+export declare class BadRequestError extends APIStatusError {
+}
+export declare class AuthenticationError extends APIStatusError {
+}
+export declare class PaymentRequiredError extends APIStatusError {
+}
+export declare class NotFoundError extends APIStatusError {
+}
+export declare class UnprocessableEntityError extends APIStatusError {
+}
+export declare class RateLimitError extends APIStatusError {
+}
+export declare class InternalServerError extends APIStatusError {
+}
+export declare class DeepcrawlFailedError extends Search1APIError {
+    readonly response: DeepcrawlStatusResponse;
+    constructor(response: DeepcrawlStatusResponse);
+}
+export declare class DeepcrawlTimeoutError extends Search1APIError {
+    readonly taskId: string;
+    constructor(taskId: string, timeoutMs: number);
+}
+export declare function apiStatusError(status: number, headers: Headers, body?: ApiErrorBody): APIStatusError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAExE,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED,qBAAa,4BAA6B,SAAQ,eAAe;CAAG;AAEpE,qBAAa,kBAAmB,SAAQ,eAAe;CAAG;AAE1D,qBAAa,eAAgB,SAAQ,kBAAkB;CAAG;AAE1D,qBAAa,cAAe,SAAQ,eAAe;IACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGtB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,YAAY;CAQtB;AAED,qBAAa,eAAgB,SAAQ,cAAc;CAAG;AACtD,qBAAa,mBAAoB,SAAQ,cAAc;CAAG;AAC1D,qBAAa,oBAAqB,SAAQ,cAAc;CAAG;AAC3D,qBAAa,aAAc,SAAQ,cAAc;CAAG;AACpD,qBAAa,wBAAyB,SAAQ,cAAc;CAAG;AAC/D,qBAAa,cAAe,SAAQ,cAAc;CAAG;AACrD,qBAAa,mBAAoB,SAAQ,cAAc;CAAG;AAE1D,qBAAa,oBAAqB,SAAQ,eAAe;IACvD,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;gBAE/B,QAAQ,EAAE,uBAAuB;CAQ9C;AAED,qBAAa,qBAAsB,SAAQ,eAAe;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAI9C;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,YAAY,GAClB,cAAc,CAyBhB"}