webfox 4.0.1 → 4.1.0

package/README.md

@@ -137,6 +137,7 @@ Use different providers for different tasks:
 | [Serper]     |   ✔︎    |          |        |          |
 | [Tavily]     |   ✔︎    |    ✔︎     |        |          |
 | [Valyu]      |   ✔︎    |    ✔︎     |   ✔︎    |    ✔︎     |
+| [You.com]    |   ✔︎    |          |        |          |
 
 [Brave]: ./docs/provider.md#brave
 [Cloudflare]: ./docs/provider.md#cloudflare
@@ -152,6 +153,7 @@ Use different providers for different tasks:
 [Serper]: ./docs/provider.md#serper
 [Tavily]: ./docs/provider.md#tavily
 [Valyu]: ./docs/provider.md#valyu
+[You.com]: ./docs/provider.md#youcom
 
 See the [provider guide](./docs/provider.md) for credentials, examples, and caveats.
 
@@ -172,7 +174,7 @@ or, on Windows, `APPDATA`. Override it with `WEBFOX_CONFIG` or `--config <path>`
 For example:
 
 ```yaml
-$schema: https://unpkg.com/webfox@4.0.0/dist/config.schema.json
+$schema: https://unpkg.com/webfox@4.0.1/dist/config.schema.json
 defaults:
   search:
     provider: brave

package/dist/{adapter-MAG7X663.js → adapter-A7LV6L55.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-ZVTVERW5.js";
 import {
   WEBFOX_ERROR_CODES
-} from "./chunk-G2YAQEET.js";
+} from "./chunk-WVHMWLKU.js";
 import {
   WebfoxError
 } from "./chunk-U4BLULLV.js";

package/dist/adapter-YOHLAGYM.js

@@ -0,0 +1,124 @@
+import {
+  trimSnippet
+} from "./chunk-X6ZBIHZC.js";
+import {
+  httpError
+} from "./chunk-U4BLULLV.js";
+
+// src/providers/youcom/adapter.ts
+var DEFAULT_BASE_URL = "https://ydc-index.io";
+var adapter = {
+  async search(request, config, context) {
+    const apiKey = config.credentials?.api;
+    if (!apiKey) throw new Error("You.com search is missing an API key");
+    const options = asRecord(request.options);
+    const response = await fetch(joinUrl(config.baseUrl), {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "X-API-Key": apiKey
+      },
+      body: JSON.stringify({
+        query: request.query,
+        count: clamp(request.maxResults, 100),
+        ...pickDefined(options, [
+          "freshness",
+          "country",
+          "language",
+          "safesearch",
+          "offset",
+          "include_domains",
+          "exclude_domains",
+          "boost_domains",
+          "livecrawl",
+          "livecrawl_formats",
+          "crawl_timeout"
+        ])
+      }),
+      signal: context.signal
+    });
+    if (!response.ok) throw httpError(response, await buildHttpError(response));
+    const payload = asRecord(await response.json());
+    const searchMetadata = asRecord(payload.metadata);
+    const web = collectResults(
+      asRecord(payload.results).web,
+      "web",
+      searchMetadata
+    );
+    const news = collectResults(
+      asRecord(payload.results).news,
+      "news",
+      searchMetadata
+    );
+    const results = [];
+    for (let index = 0; index < Math.max(web.length, news.length); index++) {
+      if (web[index]) results.push(web[index]);
+      if (news[index]) results.push(news[index]);
+    }
+    return {
+      provider: "youcom",
+      results: results.slice(0, clamp(request.maxResults, 100))
+    };
+  }
+};
+function joinUrl(baseUrl) {
+  return `${(baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "")}/v1/search`;
+}
+function collectResults(results, section, searchMetadata) {
+  return array(results).map((entry) => asRecord(entry)).filter((entry) => Object.keys(entry).length > 0).map((entry) => {
+    const url = string(entry.url) ?? "";
+    const title = string(entry.title) ?? string(entry.name) ?? (url || "Untitled");
+    return {
+      title,
+      url,
+      snippet: buildSnippet(entry, section),
+      metadata: buildMetadata(entry, section, searchMetadata)
+    };
+  });
+}
+function buildSnippet(entry, section) {
+  const contents = asRecord(entry.contents);
+  const snippets = arrayOfStrings(entry.snippets);
+  if (snippets.length > 0) return trimSnippet(snippets.join("\n\n"), 1200);
+  const text = string(entry.description) ?? string(contents.markdown) ?? string(contents.html) ?? (section === "news" ? string(entry.page_age) : void 0) ?? "";
+  return trimSnippet(text);
+}
+function buildMetadata(entry, section, searchMetadata) {
+  const metadata = {
+    section,
+    ...searchMetadata ? { searchMetadata } : {},
+    ...entry
+  };
+  return Object.keys(metadata).length > 0 ? metadata : void 0;
+}
+function pickDefined(source, keys) {
+  return Object.fromEntries(
+    keys.flatMap(
+      (key) => source[key] === void 0 ? [] : [[key, source[key]]]
+    )
+  );
+}
+function clamp(value, max) {
+  return Math.max(1, Math.min(max, Math.trunc(value || 0)));
+}
+function array(value) {
+  return Array.isArray(value) ? value : [];
+}
+function arrayOfStrings(value) {
+  return array(value).flatMap(
+    (entry) => typeof entry === "string" ? [entry] : []
+  );
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function string(value) {
+  return typeof value === "string" ? value : void 0;
+}
+async function buildHttpError(response) {
+  const body = (await response.text()).trim();
+  return `You.com search request failed (${response.status}${response.statusText ? ` ${response.statusText}` : ""})${body ? `: ${body}` : "."}`;
+}
+export {
+  adapter
+};

package/dist/{chunk-MVCCEPDF.js → chunk-2DWEBTPX.js}

@@ -11,14 +11,14 @@ import {
   providers,
   selectProvider,
   validateConfiguredOptions
-} from "./chunk-GAWPRXAU.js";
+} from "./chunk-7BXAXZPA.js";
 import {
   cancelProcessGroup,
   killProcessGroup
 } from "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES
-} from "./chunk-G2YAQEET.js";
+} from "./chunk-WVHMWLKU.js";
 import {
   WebfoxError,
   asWebfoxError

package/dist/{chunk-GAWPRXAU.js → chunk-7BXAXZPA.js}

@@ -1,6 +1,6 @@
 import {
   CAPABILITIES
-} from "./chunk-G2YAQEET.js";
+} from "./chunk-WVHMWLKU.js";
 import {
   WebfoxError
 } from "./chunk-U4BLULLV.js";
@@ -8,7 +8,7 @@ import {
 // package.json
 var package_default = {
   name: "webfox",
-  version: "4.0.1",
+  version: "4.1.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: [
@@ -746,7 +746,7 @@ var customProvider = defineProvider({
       retrySafe: false
     }
   },
-  load: async () => (await import("./adapter-MAG7X663.js")).adapter
+  load: async () => (await import("./adapter-A7LV6L55.js")).adapter
 });
 
 // src/providers/exa/definition.ts
@@ -2788,6 +2788,197 @@ var valyuProvider = defineProvider({
   load: async () => (await import("./adapter-UAZNLDSS.js")).adapter
 });
 
+// src/providers/youcom/definition.ts
+var domains = {
+  type: "array",
+  maxItems: 500,
+  items: { type: "string", minLength: 1 }
+};
+var youcomProvider = defineProvider({
+  id: "youcom",
+  label: "You.com",
+  docsUrl: "https://you.com/docs/api-reference/search/v1-search-post",
+  local: false,
+  credentials: [
+    {
+      name: "api",
+      environmentVariable: "YDC_API_KEY",
+      capabilities: ["search"]
+    }
+  ],
+  fields: ["credentials", "baseUrl", "options"],
+  defaults: {},
+  credentialDefaults: {},
+  capabilities: {
+    search: {
+      options: {
+        type: "object",
+        properties: {
+          freshness: {
+            type: "string",
+            description: "Freshness window: day, week, month, year, or YYYY-MM-DDtoYYYY-MM-DD. You.com uses the broader timeframe when the query also specifies one."
+          },
+          country: {
+            type: "string",
+            enum: [
+              "AR",
+              "AU",
+              "AT",
+              "BE",
+              "BR",
+              "CA",
+              "CL",
+              "DK",
+              "FI",
+              "FR",
+              "DE",
+              "HK",
+              "IN",
+              "ID",
+              "IT",
+              "JP",
+              "KR",
+              "MY",
+              "MX",
+              "NL",
+              "NZ",
+              "NO",
+              "CN",
+              "PL",
+              "PT",
+              "PH",
+              "RU",
+              "SA",
+              "ZA",
+              "ES",
+              "SE",
+              "CH",
+              "TW",
+              "TR",
+              "GB",
+              "US"
+            ],
+            description: "Country code used to localize search results, for example US."
+          },
+          language: {
+            type: "string",
+            enum: [
+              "AR",
+              "EU",
+              "BN",
+              "BG",
+              "CA",
+              "ZH-HANS",
+              "ZH-HANT",
+              "HR",
+              "CS",
+              "DA",
+              "NL",
+              "EN",
+              "EN-GB",
+              "ET",
+              "FI",
+              "FR",
+              "GL",
+              "DE",
+              "EL",
+              "GU",
+              "HE",
+              "HI",
+              "HU",
+              "IS",
+              "IT",
+              "JA",
+              "KN",
+              "KO",
+              "LV",
+              "LT",
+              "MS",
+              "ML",
+              "MR",
+              "NB",
+              "PL",
+              "PT-BR",
+              "PT-PT",
+              "PA",
+              "RO",
+              "RU",
+              "SR",
+              "SK",
+              "SL",
+              "ES",
+              "SV",
+              "TA",
+              "TE",
+              "TH",
+              "TR",
+              "UK",
+              "VI"
+            ],
+            description: "Language of web results. Uses You.com's uppercase codes; defaults to EN."
+          },
+          safesearch: {
+            type: "string",
+            enum: ["moderate", "off", "strict"],
+            description: "Safe-search filtering level. Defaults to moderate."
+          },
+          offset: {
+            type: "integer",
+            minimum: 0,
+            maximum: 9,
+            description: "Pagination offset in count-sized pages, separately for web and news. Count is maxResults capped at 100."
+          },
+          include_domains: {
+            ...domains,
+            description: "Restrict results to these domains. Cannot be combined with exclude_domains or boost_domains."
+          },
+          exclude_domains: {
+            ...domains,
+            description: "Exclude these domains. Cannot be combined with include_domains."
+          },
+          boost_domains: {
+            ...domains,
+            description: "Boost these domains without excluding others. Can be combined with exclude_domains, but not include_domains."
+          },
+          livecrawl: {
+            type: "string",
+            enum: ["web", "news", "all"],
+            description: "Fetch full page content for the selected sections. Adds latency and per-page charges, including results omitted by maxResults. Content is preserved in result metadata.contents."
+          },
+          livecrawl_formats: {
+            type: "array",
+            minItems: 1,
+            maxItems: 2,
+            uniqueItems: true,
+            items: { type: "string", enum: ["html", "markdown"] },
+            description: "Formats for livecrawled content. Defaults to html; requires livecrawl to enable crawling."
+          },
+          crawl_timeout: {
+            type: "integer",
+            minimum: 1,
+            maximum: 60,
+            description: "Seconds to wait for page content when livecrawl is enabled. Defaults to 10."
+          }
+        },
+        // Property prohibitions also work for partial configured defaults:
+        // unlike required-based exclusions, they survive partial validation.
+        anyOf: [
+          { properties: { include_domains: false } },
+          { properties: { exclude_domains: false, boost_domains: false } }
+        ],
+        description: "You.com search options. Results alternate web and news, starting with web, up to maxResults (capped at 100)."
+      },
+      promptGuidelines: [
+        "Use You.com search for web and news results. Results alternate web and news, starting with web, within the overall result limit.",
+        "Use include_domains to restrict sources, or exclude_domains and boost_domains to adjust source selection. Do not combine include_domains with either of the other domain controls.",
+        "Search snippets already contain query-relevant passages. Enable livecrawl only when full page content is needed; it adds latency and per-page charges."
+      ],
+      retrySafe: true
+    }
+  },
+  load: async () => (await import("./adapter-YOHLAGYM.js")).adapter
+});
+
 // src/providers/registry.ts
 var providers = {
   brave: braveProvider,
@@ -2803,7 +2994,8 @@ var providers = {
   perplexity: perplexityProvider,
   serper: serperProvider,
   tavily: tavilyProvider,
-  valyu: valyuProvider
+  valyu: valyuProvider,
+  youcom: youcomProvider
 };
 
 // src/configuration/options-schema.ts

package/dist/{chunk-G2YAQEET.js → chunk-WVHMWLKU.js}

@@ -19,7 +19,8 @@ var PROVIDER_IDS = [
   "perplexity",
   "serper",
   "tavily",
-  "valyu"
+  "valyu",
+  "youcom"
 ];
 var WEBFOX_ERROR_CODES = [
   "INVALID_CONFIG",

package/dist/cli.js

@@ -11,17 +11,17 @@ import {
   redactConfig,
   resolveConfigPath,
   setCapabilityDefault
-} from "./chunk-MVCCEPDF.js";
+} from "./chunk-2DWEBTPX.js";
 import "./chunk-WCTOYZVB.js";
 import {
   PACKAGE_VERSION,
   validateConfiguredOptions
-} from "./chunk-GAWPRXAU.js";
+} from "./chunk-7BXAXZPA.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES,
   PROVIDER_IDS
-} from "./chunk-G2YAQEET.js";
+} from "./chunk-WVHMWLKU.js";
 import {
   WebfoxError
 } from "./chunk-U4BLULLV.js";

package/dist/config.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://unpkg.com/webfox@4.0.1/dist/config.schema.json",
+  "$id": "https://unpkg.com/webfox@4.1.0/dist/config.schema.json",
   "title": "webfox configuration",
   "type": "object",
   "additionalProperties": false,
@@ -30,7 +30,8 @@
                 "perplexity",
                 "serper",
                 "tavily",
-                "valyu"
+                "valyu",
+                "youcom"
               ]
             },
             "maxResults": {
@@ -4263,6 +4264,252 @@
               }
             }
           }
+        },
+        "youcom": {
+          "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": {
+                    "freshness": {
+                      "type": "string",
+                      "description": "Freshness window: day, week, month, year, or YYYY-MM-DDtoYYYY-MM-DD. You.com uses the broader timeframe when the query also specifies one."
+                    },
+                    "country": {
+                      "type": "string",
+                      "enum": [
+                        "AR",
+                        "AU",
+                        "AT",
+                        "BE",
+                        "BR",
+                        "CA",
+                        "CL",
+                        "DK",
+                        "FI",
+                        "FR",
+                        "DE",
+                        "HK",
+                        "IN",
+                        "ID",
+                        "IT",
+                        "JP",
+                        "KR",
+                        "MY",
+                        "MX",
+                        "NL",
+                        "NZ",
+                        "NO",
+                        "CN",
+                        "PL",
+                        "PT",
+                        "PH",
+                        "RU",
+                        "SA",
+                        "ZA",
+                        "ES",
+                        "SE",
+                        "CH",
+                        "TW",
+                        "TR",
+                        "GB",
+                        "US"
+                      ],
+                      "description": "Country code used to localize search results, for example US."
+                    },
+                    "language": {
+                      "type": "string",
+                      "enum": [
+                        "AR",
+                        "EU",
+                        "BN",
+                        "BG",
+                        "CA",
+                        "ZH-HANS",
+                        "ZH-HANT",
+                        "HR",
+                        "CS",
+                        "DA",
+                        "NL",
+                        "EN",
+                        "EN-GB",
+                        "ET",
+                        "FI",
+                        "FR",
+                        "GL",
+                        "DE",
+                        "EL",
+                        "GU",
+                        "HE",
+                        "HI",
+                        "HU",
+                        "IS",
+                        "IT",
+                        "JA",
+                        "KN",
+                        "KO",
+                        "LV",
+                        "LT",
+                        "MS",
+                        "ML",
+                        "MR",
+                        "NB",
+                        "PL",
+                        "PT-BR",
+                        "PT-PT",
+                        "PA",
+                        "RO",
+                        "RU",
+                        "SR",
+                        "SK",
+                        "SL",
+                        "ES",
+                        "SV",
+                        "TA",
+                        "TE",
+                        "TH",
+                        "TR",
+                        "UK",
+                        "VI"
+                      ],
+                      "description": "Language of web results. Uses You.com's uppercase codes; defaults to EN."
+                    },
+                    "safesearch": {
+                      "type": "string",
+                      "enum": ["moderate", "off", "strict"],
+                      "description": "Safe-search filtering level. Defaults to moderate."
+                    },
+                    "offset": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9,
+                      "description": "Pagination offset in count-sized pages, separately for web and news. Count is maxResults capped at 100."
+                    },
+                    "include_domains": {
+                      "type": "array",
+                      "maxItems": 500,
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "description": "Restrict results to these domains. Cannot be combined with exclude_domains or boost_domains."
+                    },
+                    "exclude_domains": {
+                      "type": "array",
+                      "maxItems": 500,
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "description": "Exclude these domains. Cannot be combined with include_domains."
+                    },
+                    "boost_domains": {
+                      "type": "array",
+                      "maxItems": 500,
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "description": "Boost these domains without excluding others. Can be combined with exclude_domains, but not include_domains."
+                    },
+                    "livecrawl": {
+                      "type": "string",
+                      "enum": ["web", "news", "all"],
+                      "description": "Fetch full page content for the selected sections. Adds latency and per-page charges, including results omitted by maxResults. Content is preserved in result metadata.contents."
+                    },
+                    "livecrawl_formats": {
+                      "type": "array",
+                      "minItems": 1,
+                      "maxItems": 2,
+                      "uniqueItems": true,
+                      "items": {
+                        "type": "string",
+                        "enum": ["html", "markdown"]
+                      },
+                      "description": "Formats for livecrawled content. Defaults to html; requires livecrawl to enable crawling."
+                    },
+                    "crawl_timeout": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 60,
+                      "description": "Seconds to wait for page content when livecrawl is enabled. Defaults to 10."
+                    }
+                  },
+                  "anyOf": [
+                    {
+                      "properties": {
+                        "include_domains": false
+                      }
+                    },
+                    {
+                      "properties": {
+                        "exclude_domains": false,
+                        "boost_domains": false
+                      }
+                    }
+                  ],
+                  "description": "You.com search options. Results alternate web and news, starting with web, up to maxResults (capped at 100).",
+                  "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"];
+export declare const PROVIDER_IDS: readonly ["brave", "cloudflare", "custom", "exa", "firecrawl", "gemini", "linkup", "ollama", "openai", "parallel", "perplexity", "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/index.js

@@ -6,18 +6,18 @@ import {
   resolveConfigPath,
   setCapabilityDefault,
   validateConfig
-} from "./chunk-MVCCEPDF.js";
+} from "./chunk-2DWEBTPX.js";
 import "./chunk-WCTOYZVB.js";
 import {
   CONFIG_SCHEMA_URL,
   validateConfiguredOptions
-} from "./chunk-GAWPRXAU.js";
+} from "./chunk-7BXAXZPA.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES,
   PROVIDER_IDS,
   WEBFOX_ERROR_CODES
-} from "./chunk-G2YAQEET.js";
+} from "./chunk-WVHMWLKU.js";
 import {
   WebfoxError
 } from "./chunk-U4BLULLV.js";

package/dist/pi.js

@@ -3,13 +3,13 @@ import {
 } from "./chunk-QRHDXM2L.js";
 import {
   createWebfox
-} from "./chunk-MVCCEPDF.js";
+} from "./chunk-2DWEBTPX.js";
 import "./chunk-WCTOYZVB.js";
-import "./chunk-GAWPRXAU.js";
+import "./chunk-7BXAXZPA.js";
 import "./chunk-ZVTVERW5.js";
 import {
   CAPABILITIES
-} from "./chunk-G2YAQEET.js";
+} from "./chunk-WVHMWLKU.js";
 import "./chunk-U4BLULLV.js";
 
 // src/pi.ts

package/dist/providers/contract.d.ts

@@ -84,5 +84,6 @@ export interface ProviderConfigMap {
     serper: import("./serper/types.js").Serper;
     tavily: import("./tavily/types.js").Tavily;
     valyu: import("./valyu/types.js").Valyu;
+    youcom: import("./youcom/types.js").Youcom;
 }
 export type ProviderConfig<T extends ProviderId = ProviderId> = ProviderConfigMap[T];

package/dist/providers/registry.d.ts

@@ -13,4 +13,5 @@ export declare const providers: {
     readonly serper: import("./definition.js").ProviderDefinitionFor<"serper">;
     readonly tavily: import("./definition.js").ProviderDefinitionFor<"tavily">;
     readonly valyu: import("./definition.js").ProviderDefinitionFor<"valyu">;
+    readonly youcom: import("./definition.js").ProviderDefinitionFor<"youcom">;
 };

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

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

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

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

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

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

package/docs/provider.md

@@ -160,6 +160,84 @@ Supports search. Set `SERPER_API_KEY`.
 web search "Node.js release notes" --provider serper
 ```
 
+## You.com
+
+Supports search. Set `YDC_API_KEY`; the library, CLI, and Pi extension use the
+same credential. No defaults change unless you select You.com.
+
+```sh
+web search "Node.js release notes" --provider youcom \
+  --freshness week --country US --language EN --include-domains nodejs.org
+web config default search youcom
+```
+
+You.com returns separate web and news sections. Webfox alternates results from
+these sections, starting with web and preserving each section's order, up to
+`maxResults` (capped at 100 overall). If one section is exhausted, the other fills
+the remaining slots. With `maxResults: 1`, web takes precedence. The `offset`
+option selects pages from each section independently, using the capped
+`maxResults` as the upstream page size.
+
+Use `include_domains` to restrict sources, or combine `exclude_domains` with
+`boost_domains` to exclude some sources and favor others. Don't combine
+`include_domains` with either of the other domain lists. Each list supports up to
+500 domains. Country and language codes use the API's uppercase spelling, such
+as `US`, `EN`, and `EN-GB`. Run `web search --provider youcom --help` for supported
+values and all native options.
+
+Search snippets already contain query-relevant passages. For full page content,
+enable live crawling:
+
+```sh
+web search "Node.js cancellation" --provider youcom \
+  --livecrawl web --livecrawl-formats markdown --crawl-timeout 10 --format json
+```
+
+Live crawling adds latency and per-page charges, including pages that don't fit
+within the final result limit. By default, it returns HTML; request `markdown` or
+both formats as needed. Full content is preserved in each result's
+`metadata.contents`; text output shows snippets rather than full pages. See
+[You.com's API reference](https://you.com/docs/api-reference/search/v1-search-post)
+for current pricing and filter behavior.
+
+Provider-specific defaults belong under `providers.youcom.options.search`:
+
+```yaml
+defaults:
+  search:
+    provider: youcom
+providers:
+  youcom:
+    options:
+      search:
+        country: US
+        language: EN
+        safesearch: moderate
+```
+
+`providers.youcom.baseUrl` optionally replaces the API origin for a proxy; webfox
+appends `/v1/search`. Credential overrides use `providers.youcom.credentials.api`.
+For example, `{env: MY_YOUCOM_KEY}` selects another environment variable.
+
+The TypeScript library accepts the same native option names:
+
+```ts
+import { createWebfox } from "webfox";
+
+const result = await createWebfox().search({
+  provider: "youcom",
+  queries: ["Node.js release notes"],
+  maxResults: 5,
+  options: { freshness: "week", include_domains: ["nodejs.org"] },
+});
+```
+
+The provider uses the JSON POST API directly, like the HTTP-based Brave and
+Serper providers. Option names follow the wire contract rather than the official
+You.com SDK's camelCase names. Selecting You.com as the search default exposes
+these options through the existing `web_search` Pi tool; no separate tool is
+needed.
+
 ## Tavily
 
 Supports search and page extraction. Set `TAVILY_API_KEY`.

package/example-config.yaml

@@ -1,4 +1,4 @@
-$schema: https://unpkg.com/webfox@4.0.0/dist/config.schema.json
+$schema: https://unpkg.com/webfox@4.0.1/dist/config.schema.json
 defaults:
   search:
     provider: brave
@@ -34,3 +34,11 @@ providers:
     credentials:
       api:
         env: GOOGLE_API_KEY
+  youcom:
+    credentials:
+      api:
+        env: YDC_API_KEY
+    options:
+      search:
+        language: EN
+        safesearch: moderate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webfox",
-  "version": "4.0.1",
+  "version": "4.1.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": [