webfox 4.2.1 → 4.3.0

package/dist/{chunk-TJWQTB6W.js → chunk-VYMIR35R.js}

@@ -1,144 +1,32 @@
 import {
   CAPABILITIES
-} from "./chunk-WVHMWLKU.js";
+} from "./chunk-GPACLYNT.js";
 import {
   WebfoxError
 } from "./chunk-U4BLULLV.js";
 
-// package.json
-var package_default = {
-  name: "webfox",
-  version: "4.2.1",
-  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: [
-    "dist",
-    "README.md",
-    "assets/webfox-lockup.png",
-    "assets/webfox-lockup-dark.png",
-    "docs/cli-experience.md",
-    "docs/provider.md",
-    "docs/reference.md",
-    "LICENSE",
-    "example-config.yaml",
-    "examples"
-  ],
-  keywords: [
-    "webfox",
-    "web-cli",
-    "typescript-library",
-    "pi-package",
-    "pi-extension",
-    "coding-agent",
-    "web-search",
-    "web-contents",
-    "web-answer",
-    "web-research",
-    "provider-routing",
-    "brave",
-    "cloudflare",
-    "custom",
-    "exa",
-    "firecrawl",
-    "gemini",
-    "linkup",
-    "ollama",
-    "openai",
-    "parallel",
-    "perplexity",
-    "serper",
-    "tavily",
-    "valyu"
-  ],
-  author: "mavam",
-  license: "MIT",
-  repository: {
-    type: "git",
-    url: "git+https://github.com/mavam/webfox.git"
-  },
-  engines: {
-    node: ">=22.0.0"
-  },
-  publishConfig: {
-    access: "public"
-  },
-  pi: {
-    extensions: [
-      "./dist/pi.js"
-    ]
-  },
-  bin: {
-    web: "./dist/cli.js"
-  },
-  main: "./dist/index.js",
-  types: "./dist/index.d.ts",
-  exports: {
-    ".": {
-      types: "./dist/index.d.ts",
-      import: "./dist/index.js"
-    },
-    "./pi": {
-      types: "./dist/pi.d.ts",
-      import: "./dist/pi.js"
-    },
-    "./config.schema.json": "./dist/config.schema.json"
-  },
-  scripts: {
-    build: "rm -rf dist && esbuild index=src/index.ts cli=src/cli.ts pi=src/pi.ts generate-schema=scripts/generate-schema.ts --bundle --splitting --format=esm --platform=node --target=node22 --packages=external --outdir=dist && node dist/generate-schema.js && biome format --write src/config.schema.json >&2 && rm dist/generate-schema.js && tsc --project tsconfig.build.json && cp src/config.schema.json dist/config.schema.json && chmod +x dist/cli.js",
-    prepare: "npm run build",
-    prepack: "npm run build",
-    check: "tsc --noEmit",
-    format: "biome format --write .",
-    "format:check": "biome format .",
-    "smoke:live": "npm run build && node scripts/live-smoke.mjs",
-    "smoke:package": "node scripts/package-smoke.mjs",
-    test: "vitest run",
-    "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",
-    commander: "^14.0.3",
-    "exa-js": "^2.19.0",
-    "linkup-sdk": "^3.6.0",
-    openai: "^7.10.0",
-    "parallel-web": "^1.3.3",
-    picocolors: "^1.1.1",
-    typebox: "^1.3.6",
-    "valyu-js": "^2.10.1",
-    yaml: "^2.9.0"
-  },
-  devDependencies: {
-    "@biomejs/biome": "^2.5.4",
-    "@earendil-works/pi-ai": "^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1",
-    "@types/node": "^26.1.1",
-    esbuild: "^0.28.1",
-    typescript: "^7.0.2",
-    vitest: "^4.1.10"
-  },
-  peerDependencies: {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
-  },
-  peerDependenciesMeta: {
-    "@earendil-works/pi-coding-agent": {
-      optional: true
-    },
-    "@earendil-works/pi-tui": {
-      optional: true
-    }
+// src/providers/serpbase/types.ts
+var SERPBASE_MODES = {
+  search: {
+    path: "search",
+    result: "organic",
+    options: ["hl", "gl", "page", "device"]
+  },
+  images: { path: "images", result: "images", options: ["hl", "gl", "page"] },
+  news: { path: "news", result: "news", options: ["hl", "gl", "page"] },
+  videos: { path: "videos", result: "videos", options: ["hl", "gl", "page"] },
+  maps: {
+    path: "maps/search",
+    result: "places",
+    options: ["hl", "gl", "page", "lat", "lng", "zoom"]
+  },
+  "maps-detail": {
+    path: "maps/detail",
+    result: "place",
+    options: ["hl", "gl"]
   }
 };
 
-// src/package-metadata.ts
-var PACKAGE_NAME = package_default.name;
-var PACKAGE_VERSION = package_default.version;
-var CONFIG_SCHEMA_URL = `https://unpkg.com/${PACKAGE_NAME}@latest/dist/config.schema.json`;
-
 // src/configuration/planning.ts
 import { Check, Errors } from "typebox/value";
 
@@ -745,7 +633,7 @@ var customProvider = defineProvider({
       retrySafe: false
     }
   },
-  load: async () => (await import("./adapter-A7LV6L55.js")).adapter
+  load: async () => (await import("./adapter-VW4FMMJC.js")).adapter
 });
 
 // src/providers/exa/definition.ts
@@ -1984,6 +1872,107 @@ var perplexityProvider = defineProvider({
   load: async () => (await import("./adapter-NEXSOHGT.js")).adapter
 });
 
+// src/providers/serpbase/definition.ts
+var serpbaseProvider = defineProvider({
+  id: "serpbase",
+  label: "SerpBase",
+  docsUrl: "https://serpbase.dev/docs",
+  local: false,
+  credentials: [{ name: "api", environmentVariable: "SERPBASE_API_KEY" }],
+  fields: ["credentials", "baseUrl", "options"],
+  defaults: {
+    search: { mode: "search", hl: "en", gl: "us", page: 1, device: "default" }
+  },
+  credentialDefaults: {},
+  capabilities: {
+    search: {
+      defaultTimeoutMs: 12e4,
+      modeOptionKeys: Object.fromEntries(
+        Object.entries(SERPBASE_MODES).map(([mode, definition]) => [
+          mode,
+          definition.options
+        ])
+      ),
+      options: {
+        type: "object",
+        properties: {
+          mode: {
+            type: "string",
+            enum: Object.keys(SERPBASE_MODES),
+            description: "Google endpoint: 'search' (default) for organic results, 'images' for visual references, 'news' for journalism, 'videos' for clips/tutorials, 'maps' for businesses/places, or 'maps-detail' for place enrichment. In maps-detail, each queries entry must be a feature_id returned by maps (0x...:0x...), not search text."
+          },
+          hl: {
+            type: "string",
+            minLength: 1,
+            description: "Google results language code (for example 'en')."
+          },
+          gl: {
+            type: "string",
+            minLength: 1,
+            description: "Google results country code (for example 'us')."
+          },
+          page: {
+            type: "integer",
+            minimum: 1,
+            description: "1-based results page (default 1). Not accepted in maps-detail. Only this page is fetched; maxResults limits the returned results, not the upstream page size."
+          },
+          device: {
+            type: "string",
+            enum: ["default", "pc", "mobile"],
+            description: "Only for search mode: 'default' (default) for automatic routing, 'pc' for desktop, or 'mobile'."
+          },
+          lat: {
+            type: "number",
+            minimum: -90,
+            maximum: 90,
+            description: "Maps mode only: map center latitude. Requires lng."
+          },
+          lng: {
+            type: "number",
+            minimum: -180,
+            maximum: 180,
+            description: "Maps mode only: map center longitude. Requires lat."
+          },
+          zoom: {
+            type: "integer",
+            minimum: 1,
+            maximum: 21,
+            description: "Maps mode only: zoom level, 1\u201321. Requires lat and lng; defaults to 14 when coordinates are supplied."
+          }
+        },
+        // Flat properties keep CLI flags discoverable. Each branch prohibits
+        // fields for other modes; missing discriminators allow partial overrides.
+        anyOf: Object.entries(SERPBASE_MODES).map(([mode, definition]) => ({
+          properties: {
+            mode: { enum: [mode] },
+            ...Object.fromEntries(
+              ["page", "device", "lat", "lng", "zoom"].filter(
+                (key) => !definition.options.includes(key)
+              ).map((key) => [key, false])
+            )
+          },
+          ...mode === "maps" ? {
+            anyOf: [
+              { properties: { lat: false, lng: false, zoom: false } },
+              { required: ["lat", "lng"] }
+            ]
+          } : {}
+        })),
+        description: "SerpBase Google search modes. In maps-detail, queries contains feature IDs instead of search text. Unknown or mode-incompatible options are rejected. Changing mode drops incompatible inherited defaults, not explicitly supplied options."
+      },
+      promptGuidelines: [
+        "Use options.mode to choose SerpBase search (organic), images (visual references), news (journalism), videos (clips/tutorials), or maps (businesses/places).",
+        "To enrich a place, first use mode maps, then call the same web_search tool with mode maps-detail and the returned feature_id strings in queries. Do not substitute names, place_id, CID, or Maps URLs for feature_id.",
+        "Use lat and lng together to center a maps search; zoom requires both. Device selection applies only to organic search, and maps-detail accepts only hl and gl alongside mode.",
+        "Each query fetches one page or one place. maxResults only trims locally; request additional pages explicitly. Requests, including retries, may incur charges.",
+        "Image results include image and source-page URLs, not image contents. News/video times are upstream text, not verified timestamps. Maps hours and contact fields are shown only when returned."
+      ],
+      retrySafe: true
+    }
+  },
+  load: async () => (await import("./adapter-RL7JNB22.js")).adapter
+});
+
 // src/providers/serper/definition.ts
 var serperProvider = defineProvider({
   id: "serper",
@@ -2991,6 +2980,7 @@ var providers = {
   openai: openaiProvider,
   parallel: parallelProvider,
   perplexity: perplexityProvider,
+  serpbase: serpbaseProvider,
   serper: serperProvider,
   tavily: tavilyProvider,
   valyu: valyuProvider,
@@ -3071,8 +3061,19 @@ function optionSchema(definition, capability, mode = "request") {
   return result;
 }
 function effectiveOptions(config, definition, capability, options = {}, mode = "request") {
-  const result = deepMerge(
-    deepMerge(
+  const modes = definition.capabilities[capability]?.modeOptionKeys;
+  const merge = (base, override) => {
+    const inherited = { ...base };
+    if (modes && typeof override.mode === "string" && override.mode !== base.mode && Object.hasOwn(modes, override.mode)) {
+      const allowed = modes[override.mode];
+      for (const key of new Set(Object.values(modes).flat())) {
+        if (!allowed.includes(key)) delete inherited[key];
+      }
+    }
+    return deepMerge(inherited, override);
+  };
+  const result = merge(
+    merge(
       definition.defaults[capability] ?? {},
       config.providers?.[definition.id]?.options?.[capability] ?? {}
     ),
@@ -3133,110 +3134,13 @@ function isObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-// src/configuration/schema.ts
-var text = { type: "string", minLength: 1 };
-var object = (properties) => ({
-  type: "object",
-  additionalProperties: false,
-  properties
-});
-var source = {
-  oneOf: ["env", "value", "command"].map((key) => ({
-    ...object({
-      [key]: key === "command" ? { type: "array", minItems: 1, items: text } : text
-    }),
-    required: [key]
-  }))
-};
-var sourceMap = { type: "object", additionalProperties: source };
-var command = {
-  ...object({
-    argv: { type: "array", minItems: 1, items: text },
-    cwd: text,
-    env: sourceMap
-  }),
-  required: ["argv"]
-};
-var positive = { type: "integer", minimum: 1 };
-var timeout = { ...positive, maximum: 2147483647 };
-var fields = {
-  credentials: sourceMap,
-  baseUrl: text,
-  accountId: source,
-  commands: object(
-    Object.fromEntries(CAPABILITIES.map((capability) => [capability, command]))
-  )
-};
-var configurationSchema = {
-  $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: CONFIG_SCHEMA_URL,
-  title: "webfox configuration",
-  ...object({
-    $schema: text,
-    defaults: object(
-      Object.fromEntries(
-        CAPABILITIES.map((capability) => [
-          capability,
-          object({
-            provider: {
-              enum: Object.values(providers).filter((provider) => provider.capabilities[capability]).map((provider) => provider.id)
-            },
-            ...capability === "search" ? { maxResults: positive } : {}
-          })
-        ])
-      )
-    ),
-    execution: object({
-      timeoutMs: timeout,
-      researchTimeoutMs: timeout,
-      retries: { type: "integer", minimum: 0 },
-      retryDelayMs: { type: "integer", minimum: 0 },
-      concurrency: positive
-    }),
-    providers: object(
-      Object.fromEntries(
-        Object.values(providers).map((provider) => [
-          provider.id,
-          object(
-            Object.fromEntries(
-              provider.fields.map((field) => [
-                field,
-                field === "options" ? object(
-                  Object.fromEntries(
-                    CAPABILITIES.filter(
-                      (capability) => provider.capabilities[capability]
-                    ).map((capability) => [
-                      capability,
-                      optionSchema(provider, capability, "defaults") ?? {
-                        type: "object",
-                        additionalProperties: provider.id === "custom"
-                      }
-                    ])
-                  )
-                ) : field === "credentials" ? object(
-                  Object.fromEntries(
-                    provider.credentials.map((credential) => [
-                      credential.name,
-                      source
-                    ])
-                  )
-                ) : fields[field]
-              ])
-            )
-          )
-        ])
-      )
-    )
-  })
-};
-
 export {
-  PACKAGE_VERSION,
-  CONFIG_SCHEMA_URL,
-  providers,
+  SERPBASE_MODES,
   selectProvider,
   optionSchema,
   effectiveOptions,
+  validateOptions,
   validateConfiguredOptions,
-  configurationSchema
+  serpbaseProvider,
+  providers
 };

package/dist/cli.js

@@ -4,24 +4,26 @@ import {
 } from "./chunk-I2UIACY3.js";
 import {
   renderTextDocument
-} from "./chunk-QRHDXM2L.js";
+} from "./chunk-BTWECET5.js";
 import {
   createWebfox,
   loadConfig,
   redactConfig,
   resolveConfigPath,
   setCapabilityDefault
-} from "./chunk-SGHBA2PZ.js";
+} from "./chunk-5H6OAJCS.js";
 import "./chunk-WCTOYZVB.js";
 import {
-  PACKAGE_VERSION,
+  PACKAGE_VERSION
+} from "./chunk-4SX4TI7A.js";
+import {
   validateConfiguredOptions
-} from "./chunk-TJWQTB6W.js";
+} from "./chunk-VYMIR35R.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES,
   PROVIDER_IDS
-} from "./chunk-WVHMWLKU.js";
+} from "./chunk-GPACLYNT.js";
 import {
   WebfoxError
 } from "./chunk-U4BLULLV.js";

package/dist/config.schema.json

@@ -28,6 +28,7 @@
                 "openai",
                 "parallel",
                 "perplexity",
+                "serpbase",
                 "serper",
                 "tavily",
                 "valyu",
@@ -3294,6 +3295,201 @@
             }
           }
         },
+        "serpbase": {
+          "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": [
+                        "search",
+                        "images",
+                        "news",
+                        "videos",
+                        "maps",
+                        "maps-detail"
+                      ],
+                      "description": "Google endpoint: 'search' (default) for organic results, 'images' for visual references, 'news' for journalism, 'videos' for clips/tutorials, 'maps' for businesses/places, or 'maps-detail' for place enrichment. In maps-detail, each queries entry must be a feature_id returned by maps (0x...:0x...), not search text."
+                    },
+                    "hl": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Google results language code (for example 'en')."
+                    },
+                    "gl": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Google results country code (for example 'us')."
+                    },
+                    "page": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "description": "1-based results page (default 1). Not accepted in maps-detail. Only this page is fetched; maxResults limits the returned results, not the upstream page size."
+                    },
+                    "device": {
+                      "type": "string",
+                      "enum": ["default", "pc", "mobile"],
+                      "description": "Only for search mode: 'default' (default) for automatic routing, 'pc' for desktop, or 'mobile'."
+                    },
+                    "lat": {
+                      "type": "number",
+                      "minimum": -90,
+                      "maximum": 90,
+                      "description": "Maps mode only: map center latitude. Requires lng."
+                    },
+                    "lng": {
+                      "type": "number",
+                      "minimum": -180,
+                      "maximum": 180,
+                      "description": "Maps mode only: map center longitude. Requires lat."
+                    },
+                    "zoom": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 21,
+                      "description": "Maps mode only: zoom level, 1–21. Requires lat and lng; defaults to 14 when coordinates are supplied."
+                    }
+                  },
+                  "anyOf": [
+                    {
+                      "properties": {
+                        "mode": {
+                          "enum": ["search"]
+                        },
+                        "lat": false,
+                        "lng": false,
+                        "zoom": false
+                      }
+                    },
+                    {
+                      "properties": {
+                        "mode": {
+                          "enum": ["images"]
+                        },
+                        "device": false,
+                        "lat": false,
+                        "lng": false,
+                        "zoom": false
+                      }
+                    },
+                    {
+                      "properties": {
+                        "mode": {
+                          "enum": ["news"]
+                        },
+                        "device": false,
+                        "lat": false,
+                        "lng": false,
+                        "zoom": false
+                      }
+                    },
+                    {
+                      "properties": {
+                        "mode": {
+                          "enum": ["videos"]
+                        },
+                        "device": false,
+                        "lat": false,
+                        "lng": false,
+                        "zoom": false
+                      }
+                    },
+                    {
+                      "properties": {
+                        "mode": {
+                          "enum": ["maps"]
+                        },
+                        "device": false
+                      },
+                      "anyOf": [
+                        {
+                          "properties": {
+                            "lat": false,
+                            "lng": false,
+                            "zoom": false
+                          }
+                        },
+                        {}
+                      ]
+                    },
+                    {
+                      "properties": {
+                        "mode": {
+                          "enum": ["maps-detail"]
+                        },
+                        "page": false,
+                        "device": false,
+                        "lat": false,
+                        "lng": false,
+                        "zoom": false
+                      }
+                    }
+                  ],
+                  "description": "SerpBase Google search modes. In maps-detail, queries contains feature IDs instead of search text. Unknown or mode-incompatible options are rejected. Changing mode drops incompatible inherited defaults, not explicitly supplied options.",
+                  "additionalProperties": false
+                }
+              }
+            }
+          }
+        },
         "serper": {
           "type": "object",
           "additionalProperties": false,

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", "serper", "tavily", "valyu", "youcom"];
+export declare const PROVIDER_IDS: readonly ["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "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];