@isdk/web-searcher 0.1.1

package/docs/interfaces/PaginationConfig.md

@@ -0,0 +1,86 @@
+[**@isdk/web-searcher**](../README.md)
+
+***
+
+[@isdk/web-searcher](../globals.md) / PaginationConfig
+
+# Interface: PaginationConfig
+
+Defined in: [web-searcher/src/types.ts:26](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L26)
+
+Configuration for pagination strategies.
+Defines how the searcher should navigate to the next page of results.
+
+## Properties
+
+### increment?
+
+> `optional` **increment**: `number`
+
+Defined in: [web-searcher/src/types.ts:53](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L53)
+
+The increment step for each page.
+- If the parameter represents an item offset (like Google's 'start'), this might be 10.
+- If the parameter represents a page number, this is usually 1.
+
+#### Default
+
+```ts
+1
+```
+
+***
+
+### nextButtonSelector?
+
+> `optional` **nextButtonSelector**: `string`
+
+Defined in: [web-searcher/src/types.ts:59](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L59)
+
+The CSS selector for the "Next" page button.
+Required if type is 'click-next'.
+
+***
+
+### paramName?
+
+> `optional` **paramName**: `string`
+
+Defined in: [web-searcher/src/types.ts:39](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L39)
+
+The name of the URL parameter used for pagination.
+Required if type is 'url-param'.
+
+#### Example
+
+```ts
+'start' for Google, 'page' or 'p' for others.
+```
+
+***
+
+### startValue?
+
+> `optional` **startValue**: `number`
+
+Defined in: [web-searcher/src/types.ts:45](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L45)
+
+The starting value for the pagination parameter.
+
+#### Default
+
+```ts
+0
+```
+
+***
+
+### type
+
+> **type**: `"url-param"` \| `"click-next"`
+
+Defined in: [web-searcher/src/types.ts:32](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L32)
+
+The type of pagination mechanism:
+- 'url-param': Pagination is handled by modifying URL parameters (e.g., `?page=2` or `?start=10`).
+- 'click-next': Pagination is handled by clicking a "Next" button on the page (only works in 'browser' mode).

package/docs/interfaces/SearchContext.md

@@ -0,0 +1,41 @@
+[**@isdk/web-searcher**](../README.md)
+
+***
+
+[@isdk/web-searcher](../globals.md) / SearchContext
+
+# Interface: SearchContext
+
+Defined in: [web-searcher/src/types.ts:65](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L65)
+
+Context object passed to the transform function.
+
+## Properties
+
+### limit?
+
+> `optional` **limit**: `number`
+
+Defined in: [web-searcher/src/types.ts:73](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L73)
+
+The requested limit of results.
+
+***
+
+### page
+
+> **page**: `number`
+
+Defined in: [web-searcher/src/types.ts:70](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L70)
+
+The current page index (0-based).
+
+***
+
+### query
+
+> **query**: `string`
+
+Defined in: [web-searcher/src/types.ts:67](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L67)
+
+The original search query.

package/docs/interfaces/SearchOptions.md

@@ -0,0 +1,105 @@
+[**@isdk/web-searcher**](../README.md)
+
+***
+
+[@isdk/web-searcher](../globals.md) / SearchOptions
+
+# Interface: SearchOptions
+
+Defined in: [web-searcher/src/types.ts:94](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L94)
+
+Options provided when executing a search.
+
+## Indexable
+
+\[`key`: `string`\]: `any`
+
+Any other custom variables to be injected into the template.
+
+## Properties
+
+### category?
+
+> `optional` **category**: [`SearchCategory`](../type-aliases/SearchCategory.md)
+
+Defined in: [web-searcher/src/types.ts:108](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L108)
+
+The category of results to return.
+Default: 'all' (web search)
+
+***
+
+### language?
+
+> `optional` **language**: `string`
+
+Defined in: [web-searcher/src/types.ts:118](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L118)
+
+Language code (ISO 639-1) for the interface or results (e.g., 'en', 'zh-CN').
+
+***
+
+### limit?
+
+> `optional` **limit**: `number`
+
+Defined in: [web-searcher/src/types.ts:96](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L96)
+
+The maximum number of results to retrieve.
+
+***
+
+### region?
+
+> `optional` **region**: `string`
+
+Defined in: [web-searcher/src/types.ts:113](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L113)
+
+Region code (ISO 3166-1 alpha-2) to bias results (e.g., 'US', 'CN', 'JP').
+
+***
+
+### safeSearch?
+
+> `optional` **safeSearch**: [`SafeSearchLevel`](../type-aliases/SafeSearchLevel.md)
+
+Defined in: [web-searcher/src/types.ts:124](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L124)
+
+Safe search filtering level.
+Default: engine dependent (usually 'moderate' or 'strict' by default).
+
+***
+
+### timeRange?
+
+> `optional` **timeRange**: [`SearchTimeRange`](../type-aliases/SearchTimeRange.md)
+
+Defined in: [web-searcher/src/types.ts:102](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L102)
+
+Date range for the search results.
+Default: 'all'
+
+***
+
+### transform()?
+
+> `optional` **transform**: (`results`, `context`) => [`StandardSearchResult`](StandardSearchResult.md)[] \| `Promise`\<[`StandardSearchResult`](StandardSearchResult.md)[]\>
+
+Defined in: [web-searcher/src/types.ts:130](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L130)
+
+A custom transform function to filter or modify results at runtime.
+This runs AFTER the engine-level transform.
+
+#### Parameters
+
+##### results
+
+[`StandardSearchResult`](StandardSearchResult.md)[]
+
+##### context
+
+[`SearchContext`](SearchContext.md)
+
+#### Returns
+
+[`StandardSearchResult`](StandardSearchResult.md)[] \| `Promise`\<[`StandardSearchResult`](StandardSearchResult.md)[]\>

package/docs/interfaces/StandardSearchResult.md

@@ -0,0 +1,58 @@
+[**@isdk/web-searcher**](../README.md)
+
+***
+
+[@isdk/web-searcher](../globals.md) / StandardSearchResult
+
+# Interface: StandardSearchResult
+
+Defined in: [web-searcher/src/types.ts:5](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L5)
+
+Interface representing a standardized search result item.
+This ensures consistency across different search engines.
+
+## Indexable
+
+\[`key`: `string`\]: `any`
+
+Allows for engine-specific extra fields (e.g., rank, author, date).
+
+## Properties
+
+### image?
+
+> `optional` **image**: `string`
+
+Defined in: [web-searcher/src/types.ts:16](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L16)
+
+An optional image URL associated with the result.
+
+***
+
+### snippet?
+
+> `optional` **snippet**: `string`
+
+Defined in: [web-searcher/src/types.ts:13](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L13)
+
+A brief snippet or description of the result.
+
+***
+
+### title
+
+> **title**: `string`
+
+Defined in: [web-searcher/src/types.ts:7](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L7)
+
+The title of the search result.
+
+***
+
+### url
+
+> **url**: `string`
+
+Defined in: [web-searcher/src/types.ts:10](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L10)
+
+The URL of the search result.

package/docs/type-aliases/SafeSearchLevel.md

@@ -0,0 +1,11 @@
+[**@isdk/web-searcher**](../README.md)
+
+***
+
+[@isdk/web-searcher](../globals.md) / SafeSearchLevel
+
+# Type Alias: SafeSearchLevel
+
+> **SafeSearchLevel** = `"off"` \| `"moderate"` \| `"strict"`
+
+Defined in: [web-searcher/src/types.ts:89](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L89)

package/docs/type-aliases/SearchCategory.md

@@ -0,0 +1,11 @@
+[**@isdk/web-searcher**](../README.md)
+
+***
+
+[@isdk/web-searcher](../globals.md) / SearchCategory
+
+# Type Alias: SearchCategory
+
+> **SearchCategory** = `"all"` \| `"images"` \| `"videos"` \| `"news"`
+
+Defined in: [web-searcher/src/types.ts:87](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L87)

package/docs/type-aliases/SearchTimeRange.md

@@ -0,0 +1,11 @@
+[**@isdk/web-searcher**](../README.md)
+
+***
+
+[@isdk/web-searcher](../globals.md) / SearchTimeRange
+
+# Type Alias: SearchTimeRange
+
+> **SearchTimeRange** = [`SearchTimeRangePreset`](SearchTimeRangePreset.md) \| [`CustomTimeRange`](../interfaces/CustomTimeRange.md)
+
+Defined in: [web-searcher/src/types.ts:85](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L85)

package/docs/type-aliases/SearchTimeRangePreset.md

@@ -0,0 +1,11 @@
+[**@isdk/web-searcher**](../README.md)
+
+***
+
+[@isdk/web-searcher](../globals.md) / SearchTimeRangePreset
+
+# Type Alias: SearchTimeRangePreset
+
+> **SearchTimeRangePreset** = `"all"` \| `"day"` \| `"week"` \| `"month"` \| `"year"`
+
+Defined in: [web-searcher/src/types.ts:76](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/types.ts#L76)

package/docs/type-aliases/SearcherConstructor.md

@@ -0,0 +1,23 @@
+[**@isdk/web-searcher**](../README.md)
+
+***
+
+[@isdk/web-searcher](../globals.md) / SearcherConstructor
+
+# Type Alias: SearcherConstructor()
+
+> **SearcherConstructor** = (`options?`) => [`WebSearcher`](../classes/WebSearcher.md)
+
+Defined in: [web-searcher/src/searcher.ts:10](https://github.com/isdk/web-searcher.js/blob/e9a6e5ec9526780489427743389b927a5c16db5c/src/searcher.ts#L10)
+
+Constructor definition for Searcher subclasses.
+
+## Parameters
+
+### options?
+
+`FetcherOptions`
+
+## Returns
+
+[`WebSearcher`](../classes/WebSearcher.md)

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@isdk/web-searcher",
+  "version": "0.1.1",
+  "description": "A high-level framework for building search engine scrapers, supporting multi-page navigation, session persistence, and result standardization.",
+  "license": "MIT",
+  "author": "Riceball LEE <snowyu.lee@gmail.com>",
+  "homepage": "https://github.com/isdk/web-searcher.js",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/isdk/web-searcher.js.git"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "custom-factory": "^3.0.0",
+    "lodash-es": "^4.17.22",
+    "@isdk/web-fetcher": "^0.2.12"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^7.0.1",
+    "@fastify/cookie": "^11.0.2",
+    "@fastify/formbody": "^8.0.2",
+    "@types/jest": "^30.0.0",
+    "@types/jsdom": "^27.0.0",
+    "@types/lodash-es": "^4.17.12",
+    "@typescript-eslint/eslint-plugin": "~8.53.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-tsdoc": "^0.5.0",
+    "fastify": "^5.7.1",
+    "prettier": "^3.8.0",
+    "terser": "^5.46.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "type-fest": "^5.4.1",
+    "typedoc": "^0.28.16",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript": "~5.7.3",
+    "vite": "^7.3.1",
+    "vite-tsconfig-paths": "^6.0.4",
+    "vitest": "^4.0.17",
+    "vitest-fetch-mock": "^0.4.5"
+  },
+  "files": [
+    "docs",
+    "dist"
+  ],
+  "keywords": [
+    "web",
+    "fetch",
+    "crawler",
+    "spider",
+    "structure",
+    "data"
+  ],
+  "maintainers": [
+    "Riceball LEE <snowyu.lee@gmail.com>"
+  ],
+  "engines": {
+    "node": ">=20.11.1"
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build-fast": "tsup",
+    "build": "pnpm run build-fast --dts-resolve --dts && pnpm run doc:md",
+    "clean": "rm -fr web docs dist",
+    "doc": "typedoc --plugin none --out web",
+    "doc:md": "typedoc --plugin typedoc-plugin-markdown --out docs",
+    "style": "pnpm run format:base -c && pnpm run lint",
+    "style:fix": "pnpm run format:fix && npm run lint:fix",
+    "format": "pnpm run format:base -c",
+    "format:base": "prettier \"src/**/*.{ts,tsx,js,jsx,css,scss,sass,less,md}\"",
+    "format:fix": "pnpm run format:base --write",
+    "lint": "eslint .",
+    "lint:fix": "pnpm run lint --fix",
+    "test": "vitest run",
+    "release": "pnpm run clean && pnpm run build && git add -f docs && git ci -m 'docs: update API docs' && pnpm dlx commit-and-tag-version -s",
+    "release.alpha": "pnpm run release -- --prerelease alpha"
+  }
+}