webfox 4.8.0 → 4.10.0

package/dist/config.schema.json

@@ -23,6 +23,7 @@
                 "custom",
                 "exa",
                 "firecrawl",
+                "keenable",
                 "linkup",
                 "ollama",
                 "openai",
@@ -2197,6 +2198,117 @@
             }
           }
         },
+        "keenable": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "credentials": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "api": {
+                  "oneOf": [
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "properties": {
+                        "env": {
+                          "type": "string",
+                          "minLength": 1
+                        }
+                      },
+                      "required": ["env"]
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "properties": {
+                        "value": {
+                          "type": "string",
+                          "minLength": 1
+                        }
+                      },
+                      "required": ["value"]
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "properties": {
+                        "command": {
+                          "type": "array",
+                          "minItems": 1,
+                          "items": {
+                            "type": "string",
+                            "minLength": 1
+                          }
+                        }
+                      },
+                      "required": ["command"]
+                    }
+                  ]
+                }
+              }
+            },
+            "baseUrl": {
+              "type": "string",
+              "minLength": 1
+            },
+            "options": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "search": {
+                  "type": "object",
+                  "properties": {
+                    "mode": {
+                      "type": "string",
+                      "enum": ["pro", "realtime"],
+                      "description": "Search mode: 'pro' (default) for deeper retrieval, 'realtime' for the fastest results. Each mode is billed separately."
+                    },
+                    "site": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Restrict results to one site, e.g. 'techcrunch.com'."
+                    },
+                    "published_after": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Only pages published at or after this time. Accepts YYYY-MM-DD, an ISO 8601 timestamp, or a relative delta such as 7d, 12h, or 30min."
+                    },
+                    "published_before": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Only pages published at or before this time. Accepts YYYY-MM-DD, an ISO 8601 timestamp, or a relative delta such as 7d, 12h, or 30min."
+                    },
+                    "acquired_after": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Only pages indexed at or after this time. Accepts YYYY-MM-DD, an ISO 8601 timestamp, or a relative delta such as 7d, 12h, or 30min."
+                    },
+                    "acquired_before": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Only pages indexed at or before this time. Accepts YYYY-MM-DD, an ISO 8601 timestamp, or a relative delta such as 7d, 12h, or 30min."
+                    },
+                    "query_time": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Search the index as it stood at this date or ISO 8601 timestamp; relative time filters resolve against it."
+                    },
+                    "snippet_max_length": {
+                      "type": "integer",
+                      "minimum": 180,
+                      "maximum": 10000,
+                      "description": "Maximum characters of the excerpt per result."
+                    }
+                  },
+                  "description": "Keenable search options.",
+                  "additionalProperties": false
+                }
+              }
+            }
+          }
+        },
         "linkup": {
           "type": "object",
           "additionalProperties": false,

package/dist/document-schema.d.ts

@@ -8,7 +8,7 @@ export declare const DOCUMENT_SCHEMAS: {
     readonly search: Type.TObject<{
         schemaVersion: Type.TLiteral<1>;
         capability: Type.TLiteral<"search">;
-        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"]>;
+        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"]>;
         status: Type.TEnum<["ok", "partial"]>;
         results: Type.TArray<Type.TUnion<[Type.TObject<{
             input: Type.TString;
@@ -35,7 +35,7 @@ export declare const DOCUMENT_SCHEMAS: {
     readonly contents: Type.TObject<{
         schemaVersion: Type.TLiteral<1>;
         capability: Type.TLiteral<"contents">;
-        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"]>;
+        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"]>;
         status: Type.TEnum<["ok", "partial"]>;
         results: Type.TArray<Type.TUnion<[Type.TObject<{
             input: Type.TString;
@@ -59,7 +59,7 @@ export declare const DOCUMENT_SCHEMAS: {
     readonly answer: Type.TObject<{
         schemaVersion: Type.TLiteral<1>;
         capability: Type.TLiteral<"answer">;
-        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"]>;
+        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"]>;
         status: Type.TEnum<["ok", "partial"]>;
         results: Type.TArray<Type.TUnion<[Type.TObject<{
             input: Type.TString;
@@ -82,7 +82,7 @@ export declare const DOCUMENT_SCHEMAS: {
     readonly research: Type.TObject<{
         schemaVersion: Type.TLiteral<1>;
         capability: Type.TLiteral<"research">;
-        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"]>;
+        provider: Type.TEnum<["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"]>;
         status: Type.TEnum<["ok", "partial"]>;
         results: Type.TArray<Type.TUnion<[Type.TObject<{
             input: Type.TString;

package/dist/domain.d.ts

@@ -1,6 +1,6 @@
 export declare const CAPABILITIES: readonly ["search", "contents", "answer", "research"];
 export type Capability = (typeof CAPABILITIES)[number];
-export declare const PROVIDER_IDS: readonly ["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"];
+export declare const PROVIDER_IDS: readonly ["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "keenable", "linkup", "ollama", "openai", "parallel", "perplexity", "serpbase", "serper", "tavily", "valyu", "youcom"];
 export type ProviderId = (typeof PROVIDER_IDS)[number];
 export declare const WEBFOX_ERROR_CODES: readonly ["INVALID_CONFIG", "INVALID_INPUT", "PROVIDER_UNAVAILABLE", "PROVIDER_FAILURE", "PARTIAL_BATCH", "TIMEOUT", "CANCELLED"];
 export type WebfoxErrorCode = (typeof WEBFOX_ERROR_CODES)[number];

package/dist/durable.js

@@ -8,14 +8,14 @@ import {
 } from "./chunk-BTWECET5.js";
 import {
   createWebfox
-} from "./chunk-IRKSK34I.js";
+} from "./chunk-3WBE6UEW.js";
 import "./chunk-WCTOYZVB.js";
-import "./chunk-G7LMBPW4.js";
-import "./chunk-QERSNL3J.js";
+import "./chunk-TGULKHB5.js";
+import "./chunk-5FP7KNMC.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES
-} from "./chunk-GPACLYNT.js";
+} from "./chunk-57OOEOXI.js";
 import "./chunk-U4BLULLV.js";
 
 // src/durable.ts

package/dist/index.js

@@ -6,20 +6,20 @@ import {
   resolveConfigPath,
   setCapabilityDefault,
   validateConfig
-} from "./chunk-IRKSK34I.js";
+} from "./chunk-3WBE6UEW.js";
 import "./chunk-WCTOYZVB.js";
 import {
   CONFIG_SCHEMA_URL
-} from "./chunk-G7LMBPW4.js";
+} from "./chunk-TGULKHB5.js";
 import {
   validateConfiguredOptions
-} from "./chunk-QERSNL3J.js";
+} from "./chunk-5FP7KNMC.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES,
   PROVIDER_IDS,
   WEBFOX_ERROR_CODES
-} from "./chunk-GPACLYNT.js";
+} from "./chunk-57OOEOXI.js";
 import {
   WebfoxError
 } from "./chunk-U4BLULLV.js";

package/dist/pi.js

@@ -9,16 +9,16 @@ import {
 import {
   createWebfox,
   resolveConfigPath
-} from "./chunk-IRKSK34I.js";
+} from "./chunk-3WBE6UEW.js";
 import "./chunk-WCTOYZVB.js";
-import "./chunk-G7LMBPW4.js";
-import "./chunk-QERSNL3J.js";
+import "./chunk-TGULKHB5.js";
+import "./chunk-5FP7KNMC.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES,
   PROVIDER_IDS,
   WEBFOX_ERROR_CODES
-} from "./chunk-GPACLYNT.js";
+} from "./chunk-57OOEOXI.js";
 import {
   WebfoxError
 } from "./chunk-U4BLULLV.js";

package/dist/providers/contract.d.ts

@@ -76,6 +76,7 @@ export interface ProviderConfigMap {
     exa: import("./exa/types.js").Exa;
     firecrawl: import("./firecrawl/types.js").Firecrawl;
     gemini: import("./gemini/types.js").Gemini;
+    keenable: import("./keenable/types.js").Keenable;
     linkup: import("./linkup/types.js").Linkup;
     ollama: import("./ollama/types.js").Ollama;
     openai: import("./openai/types.js").OpenAI;

package/dist/providers/keenable/adapter.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderContext, ProviderRequest, SearchResponse } from "../contract.js";
+import type { Keenable } from "./types.js";
+export declare const adapter: {
+    search(request: ProviderRequest<"search">, config: Keenable, context: ProviderContext): Promise<SearchResponse>;
+};

package/dist/providers/keenable/definition.d.ts

@@ -0,0 +1 @@
+export declare const keenableProvider: import("../definition.js").ProviderDefinitionFor<"keenable">;

package/dist/providers/keenable/types.d.ts

@@ -0,0 +1,4 @@
+import type { Provider } from "../contract.js";
+export interface Keenable extends Provider {
+    baseUrl?: string;
+}

package/dist/providers/registry.d.ts

@@ -5,6 +5,7 @@ export declare const providers: {
     readonly exa: import("./definition.js").ProviderDefinitionFor<"exa">;
     readonly firecrawl: import("./definition.js").ProviderDefinitionFor<"firecrawl">;
     readonly gemini: import("./definition.js").ProviderDefinitionFor<"gemini">;
+    readonly keenable: import("./definition.js").ProviderDefinitionFor<"keenable">;
     readonly linkup: import("./definition.js").ProviderDefinitionFor<"linkup">;
     readonly ollama: import("./definition.js").ProviderDefinitionFor<"ollama">;
     readonly openai: import("./definition.js").ProviderDefinitionFor<"openai">;

package/dist/providers/shared.d.ts

@@ -2,3 +2,19 @@ export declare function trimSnippet(input: string | undefined, maxLength?: numbe
 export declare function normalizeContentText(input: string | undefined): string;
 export declare function asJsonObject(value: Record<string, unknown> | undefined): Record<string, unknown>;
 export declare function formatJson(value: unknown): string;
+export declare function joinUrl(baseUrl: string, path: string): string;
+/** Read a response body as JSON, falling back to its text. */
+export declare function readResponseBody(response: Response): Promise<unknown>;
+/** Reject successful responses whose body is empty or not JSON. */
+export declare function expectJsonBody(payload: unknown, response: Response): unknown;
+/**
+ * Send one JSON request without retries; the runtime owns retry policy.
+ * Non-2xx responses become classified provider errors with the message that
+ * `describeError` extracts from the response body.
+ */
+export declare function requestJson(url: string, init: {
+    method?: "GET" | "POST";
+    headers?: Record<string, string>;
+    body?: unknown;
+    signal?: AbortSignal;
+}, describeError: (payload: unknown, response: Response) => string): Promise<unknown>;

package/docs/provider.md

@@ -123,6 +123,23 @@ The research agent is fixed; answer model settings don't affect it.
 If you previously selected Gemini for search, choose a search-capable provider
 and remove `providers.gemini.options.search` from your configuration.
 
+## Keenable
+
+Supports search. Set `KEENABLE_API_KEY`, or configure
+`providers.keenable.credentials.api` with a credential source. No defaults change
+unless you select Keenable.
+
+```sh
+web search "Node.js release notes" --provider keenable \
+  --site nodejs.org --published-after 30d
+web config default search keenable
+```
+
+Keenable caps `maxResults` at 50. Native options include `mode` (`pro` or
+`realtime`), `site`, `published_after`/`published_before`,
+`acquired_after`/`acquired_before`, `query_time`, and `snippet_max_length`.
+Time filters accept dates, ISO 8601 timestamps, or relative deltas such as `7d`.
+
 ## Linkup
 
 Supports search, page extraction, and research. Set `LINKUP_API_KEY`.
@@ -160,8 +177,49 @@ web search --provider openai --help
 
 Supports search and page extraction. Set `PARALLEL_API_KEY`.
 
+Search defaults to `advanced`. Choose `fast` for interactive lookups, or see
+[Parallel's search modes](https://docs.parallel.ai/search/modes) for the available
+tradeoffs:
+
+```sh
+web search "Node.js release notes" --provider parallel --mode fast
+```
+
+Limit a query to particular sources with `advanced_settings.source_policy`.
+Use Webfox's `--max-results` to control the number of results:
+
+```sh
+web search "Node.js release notes" --provider parallel --mode fast --max-results 3 \
+  --options-json '{"advanced_settings":{"source_policy":{"include_domains":["nodejs.org"]}}}'
+```
+
+To reuse Fast mode, merge this into your [configuration](./reference.md#configuration):
+
+```yaml
+providers:
+  parallel:
+    options:
+      search:
+        mode: fast
+```
+
+Provider options don't select a provider. Continue to pass `--provider parallel`
+or use your saved Parallel search default. A request's `--mode` overrides the
+saved mode.
+
+For known URLs, use page extraction instead of another search. Parallel returns
+full page content by default:
+
+```sh
+web contents https://nodejs.org/en/about/previous-releases --provider parallel
+```
+
+To request only excerpts relevant to a question, disable full content and enable
+excerpts with an objective:
+
 ```sh
-web search "Node.js release notes" --provider parallel
+web contents https://nodejs.org/en/about/previous-releases --provider parallel \
+  --no-full-content --excerpts --objective "Which Node.js releases are supported?"
 ```
 
 ## Perplexity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webfox",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "description": "Search the web, extract pages, get grounded answers, and run deep research with the web CLI, a TypeScript library, and a pi extension. Bring your own providers and API keys.",
   "type": "module",
   "files": [
@@ -92,17 +92,14 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@mendable/firecrawl-js": "^4.38.0",
-    "@perplexity-ai/perplexity_ai": "^0.38.5",
-    "@tavily/core": "^0.7.9",
-    "cloudflare": "^7.1.0",
+    "@perplexity-ai/perplexity_ai": "^0.41.0",
+    "@tavily/core": "^0.7.14",
+    "cloudflare": "^7.3.0",
     "commander": "^14.0.3",
-    "exa-js": "^2.19.0",
-    "linkup-sdk": "^3.6.0",
-    "openai": "^7.10.0",
-    "parallel-web": "^1.3.3",
+    "openai": "^7.47.0",
+    "parallel-web": "^1.3.7",
     "picocolors": "^1.1.1",
-    "valyu-js": "^2.10.1",
+    "valyu-js": "^2.11.5",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

package/dist/chunk-X6ZBIHZC.js

@@ -1,21 +0,0 @@
-// src/providers/shared.ts
-function trimSnippet(input, maxLength = 300) {
-  const text = (input ?? "").replace(/\s+/g, " ").trim();
-  return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}\u2026`;
-}
-function normalizeContentText(input) {
-  return (input ?? "").replace(/\r/g, "").trim().split("\n").map((line) => line.replace(/[ \t]+$/g, "")).join("\n").replace(/\n{3,}/g, "\n\n");
-}
-function asJsonObject(value) {
-  return value ? { ...value } : {};
-}
-function formatJson(value) {
-  return JSON.stringify(value, null, 2);
-}
-
-export {
-  trimSnippet,
-  normalizeContentText,
-  asJsonObject,
-  formatJson
-};