@youdotcom-oss/api 0.1.0 → 0.2.0

package/bin/cli.js

@@ -11,11 +11,11 @@ var __export = (target, all) => {
 };
 
 // src/cli.ts
-import { parseArgs as parseArgs4 } from "node:util";
+import { parseArgs as parseArgs2 } from "node:util";
 // package.json
 var package_default = {
   name: "@youdotcom-oss/api",
-  version: "0.1.0",
+  version: "0.2.0",
   description: "You.com API client with bundled CLI for agents supporting Agent Skills",
   license: "MIT",
   engines: {
@@ -78,13 +78,10 @@ var package_default = {
     "test:watch": "bun test --watch"
   },
   dependencies: {
-    zod: "^4.3.5"
+    zod: "^4.3.6"
   }
 };
 
-// src/commands/contents.ts
-import { parseArgs } from "node:util";
-
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/core/core.js
 var NEVER = Object.freeze({
   status: "aborted"
@@ -2340,114 +2337,6 @@ function handleIntersectionResults(result, left, right) {
   result.value = merged.data;
   return result;
 }
-var $ZodRecord = /* @__PURE__ */ $constructor("$ZodRecord", (inst, def) => {
-  $ZodType.init(inst, def);
-  inst._zod.parse = (payload, ctx) => {
-    const input = payload.value;
-    if (!isPlainObject(input)) {
-      payload.issues.push({
-        expected: "record",
-        code: "invalid_type",
-        input,
-        inst
-      });
-      return payload;
-    }
-    const proms = [];
-    const values = def.keyType._zod.values;
-    if (values) {
-      payload.value = {};
-      const recordKeys = new Set;
-      for (const key of values) {
-        if (typeof key === "string" || typeof key === "number" || typeof key === "symbol") {
-          recordKeys.add(typeof key === "number" ? key.toString() : key);
-          const result = def.valueType._zod.run({ value: input[key], issues: [] }, ctx);
-          if (result instanceof Promise) {
-            proms.push(result.then((result2) => {
-              if (result2.issues.length) {
-                payload.issues.push(...prefixIssues(key, result2.issues));
-              }
-              payload.value[key] = result2.value;
-            }));
-          } else {
-            if (result.issues.length) {
-              payload.issues.push(...prefixIssues(key, result.issues));
-            }
-            payload.value[key] = result.value;
-          }
-        }
-      }
-      let unrecognized;
-      for (const key in input) {
-        if (!recordKeys.has(key)) {
-          unrecognized = unrecognized ?? [];
-          unrecognized.push(key);
-        }
-      }
-      if (unrecognized && unrecognized.length > 0) {
-        payload.issues.push({
-          code: "unrecognized_keys",
-          input,
-          inst,
-          keys: unrecognized
-        });
-      }
-    } else {
-      payload.value = {};
-      for (const key of Reflect.ownKeys(input)) {
-        if (key === "__proto__")
-          continue;
-        let keyResult = def.keyType._zod.run({ value: key, issues: [] }, ctx);
-        if (keyResult instanceof Promise) {
-          throw new Error("Async schemas not supported in object keys currently");
-        }
-        const checkNumericKey = typeof key === "string" && number.test(key) && keyResult.issues.length;
-        if (checkNumericKey) {
-          const retryResult = def.keyType._zod.run({ value: Number(key), issues: [] }, ctx);
-          if (retryResult instanceof Promise) {
-            throw new Error("Async schemas not supported in object keys currently");
-          }
-          if (retryResult.issues.length === 0) {
-            keyResult = retryResult;
-          }
-        }
-        if (keyResult.issues.length) {
-          if (def.mode === "loose") {
-            payload.value[key] = input[key];
-          } else {
-            payload.issues.push({
-              code: "invalid_key",
-              origin: "record",
-              issues: keyResult.issues.map((iss) => finalizeIssue(iss, ctx, config())),
-              input: key,
-              path: [key],
-              inst
-            });
-          }
-          continue;
-        }
-        const result = def.valueType._zod.run({ value: input[key], issues: [] }, ctx);
-        if (result instanceof Promise) {
-          proms.push(result.then((result2) => {
-            if (result2.issues.length) {
-              payload.issues.push(...prefixIssues(key, result2.issues));
-            }
-            payload.value[keyResult.value] = result2.value;
-          }));
-        } else {
-          if (result.issues.length) {
-            payload.issues.push(...prefixIssues(key, result.issues));
-          }
-          payload.value[keyResult.value] = result.value;
-        }
-      }
-    }
-    if (proms.length) {
-      return Promise.all(proms).then(() => payload);
-    }
-    return payload;
-  };
-});
 var $ZodEnum = /* @__PURE__ */ $constructor("$ZodEnum", (inst, def) => {
   $ZodType.init(inst, def);
   const values = getEnumValues(def.entries);
@@ -2468,28 +2357,6 @@ var $ZodEnum = /* @__PURE__ */ $constructor("$ZodEnum", (inst, def) => {
     return payload;
   };
 });
-var $ZodLiteral = /* @__PURE__ */ $constructor("$ZodLiteral", (inst, def) => {
-  $ZodType.init(inst, def);
-  if (def.values.length === 0) {
-    throw new Error("Cannot create literal schema with no valid values");
-  }
-  const values = new Set(def.values);
-  inst._zod.values = values;
-  inst._zod.pattern = new RegExp(`^(${def.values.map((o) => typeof o === "string" ? escapeRegex(o) : o ? escapeRegex(o.toString()) : String(o)).join("|")})$`);
-  inst._zod.parse = (payload, _ctx) => {
-    const input = payload.value;
-    if (values.has(input)) {
-      return payload;
-    }
-    payload.issues.push({
-      code: "invalid_value",
-      values: def.values,
-      input,
-      inst
-    });
-    return payload;
-  };
-});
 var $ZodTransform = /* @__PURE__ */ $constructor("$ZodTransform", (inst, def) => {
   $ZodType.init(inst, def);
   inst._zod.parse = (payload, ctx) => {
@@ -4663,21 +4530,6 @@ function intersection(left, right) {
     right
   });
 }
-var ZodRecord = /* @__PURE__ */ $constructor("ZodRecord", (inst, def) => {
-  $ZodRecord.init(inst, def);
-  ZodType.init(inst, def);
-  inst._zod.processJSONSchema = (ctx, json, params) => recordProcessor(inst, ctx, json, params);
-  inst.keyType = def.keyType;
-  inst.valueType = def.valueType;
-});
-function record(keyType, valueType, params) {
-  return new ZodRecord({
-    type: "record",
-    keyType,
-    valueType,
-    ...exports_util.normalizeParams(params)
-  });
-}
 var ZodEnum = /* @__PURE__ */ $constructor("ZodEnum", (inst, def) => {
   $ZodEnum.init(inst, def);
   ZodType.init(inst, def);
@@ -4724,27 +4576,6 @@ function _enum(values, params) {
     ...exports_util.normalizeParams(params)
   });
 }
-var ZodLiteral = /* @__PURE__ */ $constructor("ZodLiteral", (inst, def) => {
-  $ZodLiteral.init(inst, def);
-  ZodType.init(inst, def);
-  inst._zod.processJSONSchema = (ctx, json, params) => literalProcessor(inst, ctx, json, params);
-  inst.values = new Set(def.values);
-  Object.defineProperty(inst, "value", {
-    get() {
-      if (def.values.length > 1) {
-        throw new Error("This schema contains multiple valid literal values. Use `.values` instead.");
-      }
-      return def.values[0];
-    }
-  });
-});
-function literal(value, params) {
-  return new ZodLiteral({
-    type: "literal",
-    values: Array.isArray(value) ? value : [value],
-    ...exports_util.normalizeParams(params)
-  });
-}
 var ZodTransform = /* @__PURE__ */ $constructor("ZodTransform", (inst, def) => {
   $ZodTransform.init(inst, def);
   ZodType.init(inst, def);
@@ -4926,20 +4757,19 @@ var ContentsQuerySchema = object({
 });
 var ContentsItemSchema = object({
   url: string2().describe("URL"),
-  title: string2().optional().describe("Title"),
-  html: string2().optional().describe("HTML content"),
-  markdown: string2().optional().describe("Markdown content"),
+  title: string2().optional().describe("Title (optional in actual API responses)"),
+  html: string2().nullable().optional().describe("HTML content"),
+  markdown: string2().nullable().optional().describe("Markdown content"),
   metadata: object({
-    jsonld: array(record(string2(), unknown())).optional().describe("JSON-LD structured data (Schema.org)"),
-    opengraph: record(string2(), string2()).optional().describe("OpenGraph meta tags"),
-    twitter: record(string2(), string2()).optional().describe("Twitter Card metadata")
-  }).optional().describe("Structured metadata when available")
+    site_name: string2().nullable().optional().describe("OpenGraph site name"),
+    favicon_url: string2().describe("Favicon URL")
+  }).nullable().optional().describe("Page metadata (only when metadata format requested)")
 });
 var ContentsApiResponseSchema = array(ContentsItemSchema);
 
 // src/shared/api.constants.ts
 var SEARCH_API_URL = "https://ydc-index.io/v1/search";
-var EXPRESS_API_URL = "https://api.you.com/v1/agents/runs";
+var DEEP_SEARCH_API_URL = "https://api.you.com/v1/deep_search";
 var CONTENTS_API_URL = "https://ydc-index.io/v1/contents";
 
 // src/shared/check-response-for-errors.ts
@@ -5007,199 +4837,98 @@ var fetchContents = async ({
   return parsedResults;
 };
 
-// src/shared/use-get-user-agents.ts
-var useGetUserAgent = (client = "") => () => `CLI/ ${package_default.version} (You.com;${client})`;
-
-// src/commands/contents.ts
-var contentsCommand = async (args) => {
-  if (args.includes("--schema")) {
-    console.log(JSON.stringify(toJSONSchema(ContentsQuerySchema)));
-    process.exit(0);
-  }
-  const { values } = parseArgs({
-    args,
-    options: {
-      json: { type: "string" },
-      "api-key": { type: "string" },
-      client: { type: "string" }
-    }
-  });
-  if (!values.json) {
-    throw new Error("--json flag is required");
-  }
-  const query = JSON.parse(values.json);
-  const apiKey = values["api-key"];
-  const client = values.client || process.env.YDC_CLIENT;
-  const YDC_API_KEY = apiKey || process.env.YDC_API_KEY;
-  if (!YDC_API_KEY) {
-    throw new Error("YDC_API_KEY environment variable is required");
-  }
-  const contentsQuery = ContentsQuerySchema.parse(query);
-  const response = await fetchContents({
-    contentsQuery,
-    YDC_API_KEY,
-    getUserAgent: useGetUserAgent(client)
-  });
-  console.log(JSON.stringify(response));
-};
-
-// src/commands/express.ts
-import { parseArgs as parseArgs2 } from "node:util";
-
-// src/express/express.schemas.ts
-var ExpressAgentInputSchema = object({
-  input: string2().min(1, "Input is required").describe("Query or prompt"),
-  tools: array(object({
-    type: _enum(["web_search"]).describe("Tool type")
-  })).optional().describe("Tools (web search only)")
+// src/deep-search/deep-search.schemas.ts
+var SearchEffortSchema = _enum(["low", "medium", "high"]).describe("Search effort level");
+var DeepSearchQuerySchema = object({
+  query: string2().min(1, "Query is required").describe("The research question or complex query requiring in-depth investigation and multi-step reasoning"),
+  search_effort: SearchEffortSchema.optional().default("medium").describe("Computation budget: low (<30s), medium (<60s, default), high (<300s)")
 });
-var ApiSearchResultItemSchema = object({
-  source_type: string2().nullable().optional(),
-  citation_uri: string2().optional(),
-  url: string2(),
-  title: string2(),
-  snippet: string2(),
-  thumbnail_url: string2().nullable().optional(),
-  provider: string2().nullable().optional()
+var DeepSearchSourceSchema = object({
+  url: string2().describe("Source webpage URL"),
+  title: string2().describe("Source webpage title"),
+  snippets: array(string2()).describe("Relevant excerpts from the source page used in generating the answer")
 });
-var ExpressAgentApiOutputItemSchema = union([
-  object({
-    type: literal("web_search.results"),
-    content: array(ApiSearchResultItemSchema)
-  }),
-  object({
-    type: literal("message.answer"),
-    text: string2()
-  })
-]);
-var ExpressAgentApiResponseSchema = object({
-  output: array(ExpressAgentApiOutputItemSchema),
-  agent: string2().optional().describe("Agent identifier"),
-  mode: string2().optional().describe("Agent mode"),
-  input: array(object({
-    role: _enum(["user"]).describe("User role"),
-    content: string2().describe("User question")
-  })).optional().describe("Input messages")
-}).passthrough();
-var McpSearchResultItemSchema = object({
-  url: string2().describe("URL"),
-  title: string2().describe("Title"),
-  snippet: string2().describe("Snippet")
-});
-var ExpressAgentMcpResponseSchema = object({
-  answer: string2().describe("AI answer"),
-  results: object({
-    web: array(McpSearchResultItemSchema).describe("Web results")
-  }).optional().describe("Search results"),
-  agent: string2().optional().describe("Agent ID")
+var DeepSearchResponseSchema = object({
+  answer: string2().describe("Comprehensive response with inline citations, formatted in Markdown"),
+  results: array(DeepSearchSourceSchema).describe("List of web sources used to generate the answer")
 });
 
-// src/express/express.utils.ts
-var agentThrowOnFailedStatus = async (response) => {
-  const errorCode = response.status;
-  const errorData = await response.json();
-  if (errorCode === 400) {
-    throw new Error(`Bad Request:
-${JSON.stringify(errorData)}`);
-  } else if (errorCode === 401) {
-    throw new Error(`Unauthorized: The Agent APIs require a valid You.com API key with agent access. Ensure your YDC_API_KEY has permissions for agent endpoints.`);
-  } else if (errorCode === 403) {
-    throw new Error(`Forbidden: You are not allowed to use the requested tool for this agent or tenant`);
-  } else if (errorCode === 429) {
-    throw new Error("Rate limited by You.com API. Please try again later.");
-  }
-  throw new Error(`Failed to call agent. Error code: ${errorCode}`);
-};
-var callExpressAgent = async ({
-  YDC_API_KEY = process.env.YDC_API_KEY,
-  agentInput: { input, tools },
+// src/deep-search/deep-search.utils.ts
+var callDeepSearch = async ({
+  deepSearchQuery,
+  YDC_API_KEY,
   getUserAgent
 }) => {
-  const requestBody = {
-    agent: "express",
-    input,
-    stream: false
-  };
-  if (tools) {
-    requestBody.tools = tools;
-  }
-  const options = {
+  const response = await fetch(DEEP_SEARCH_API_URL, {
     method: "POST",
     headers: new Headers({
-      Authorization: `Bearer ${YDC_API_KEY || ""}`,
+      "X-API-Key": YDC_API_KEY || "",
       "Content-Type": "application/json",
-      Accept: "application/json",
       "User-Agent": getUserAgent()
     }),
-    body: JSON.stringify(requestBody)
-  };
-  const response = await fetch(EXPRESS_API_URL, options);
-  if (!response.ok) {
-    await agentThrowOnFailedStatus(response);
-  }
-  const jsonResponse = await response.json();
-  checkResponseForErrors(jsonResponse);
-  const apiResponse = ExpressAgentApiResponseSchema.parse(jsonResponse);
-  const answerItem = apiResponse.output.find((item) => item.type === "message.answer");
-  if (!answerItem) {
-    throw new Error("Express API response missing required message.answer item");
-  }
-  const searchItem = apiResponse.output.find((item) => item.type === "web_search.results");
-  const mcpResponse = {
-    answer: answerItem.text,
-    agent: apiResponse.agent
-  };
-  if (searchItem && "content" in searchItem && Array.isArray(searchItem.content)) {
-    mcpResponse.results = {
-      web: searchItem.content.map((item) => ({
-        url: item.url || item.citation_uri || "",
-        title: item.title || "",
-        snippet: item.snippet || ""
-      }))
-    };
-  }
-  return mcpResponse;
-};
-
-// src/commands/express.ts
-var expressCommand = async (args) => {
-  if (args.includes("--schema")) {
-    console.log(JSON.stringify(toJSONSchema(ExpressAgentInputSchema)));
-    process.exit(0);
-  }
-  const { values } = parseArgs2({
-    args,
-    options: {
-      json: { type: "string" },
-      "api-key": { type: "string" },
-      client: { type: "string" }
-    }
-  });
-  if (!values.json) {
-    throw new Error("--json flag is required");
-  }
-  const input = JSON.parse(values.json);
-  const apiKey = values["api-key"];
-  const client = values.client || process.env.YDC_CLIENT;
-  const YDC_API_KEY = apiKey || process.env.YDC_API_KEY;
-  if (!YDC_API_KEY) {
-    throw new Error("YDC_API_KEY environment variable is required");
-  }
-  const agentInput = ExpressAgentInputSchema.parse(input);
-  const response = await callExpressAgent({
-    agentInput,
-    YDC_API_KEY,
-    getUserAgent: useGetUserAgent(client)
+    body: JSON.stringify(deepSearchQuery)
   });
-  console.log(JSON.stringify(response));
+  await checkResponseForErrors(response);
+  const data = await response.json();
+  return DeepSearchResponseSchema.parse(data);
 };
 
-// src/commands/search.ts
-import { parseArgs as parseArgs3 } from "node:util";
-
 // src/search/search.schemas.ts
+var LanguageSchema = _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",
+  "JP",
+  "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"
+]);
 var SearchQuerySchema = object({
-  query: string2().min(1, "Query is required").describe("Search query (supports +, -, site:, filetype:, lang:)"),
+  query: string2().min(1, "Query is required").describe('Search query. Supports operators: site:domain.com (domain filter), filetype:pdf (file type), +term (include), -term (exclude), AND/OR/NOT (boolean logic), lang:en (language). Example: "machine learning (Python OR PyTorch) -TensorFlow filetype:pdf"'),
   count: number2().int().min(1).max(100).optional().describe("Max results per section"),
   freshness: string2().optional().describe("day/week/month/year or YYYY-MM-DDtoYYYY-MM-DD"),
   offset: number2().int().min(0).max(9).optional().describe("Pagination offset"),
@@ -5229,6 +4958,7 @@ var SearchQuerySchema = object({
     "CN",
     "PL",
     "PT",
+    "PT-BR",
     "PH",
     "RU",
     "SA",
@@ -5242,11 +4972,6 @@ var SearchQuerySchema = object({
     "US"
   ]).optional().describe("Country code"),
   safesearch: _enum(["off", "moderate", "strict"]).optional().describe("Filter level"),
-  site: string2().optional().describe("Specific domain"),
-  fileType: string2().optional().describe("File type"),
-  language: string2().optional().describe("ISO 639-1 language code"),
-  excludeTerms: string2().optional().describe("Terms to exclude (pipe-separated)"),
-  exactTerms: string2().optional().describe("Exact terms (pipe-separated)"),
   livecrawl: _enum(["web", "news", "all"]).optional().describe("Live-crawl sections for full content"),
   livecrawl_formats: _enum(["html", "markdown"]).optional().describe("Format for crawled content")
 });
@@ -5291,24 +5016,15 @@ var SearchResponseSchema = object({
 // src/search/search.utils.ts
 var fetchSearchResults = async ({
   YDC_API_KEY = process.env.YDC_API_KEY,
-  searchQuery: { query, site, fileType, language, exactTerms, excludeTerms, ...rest },
+  searchQuery,
   getUserAgent
 }) => {
   const url = new URL(SEARCH_API_URL);
   const searchParams = new URLSearchParams;
-  const searchQuery = [query];
-  site && searchQuery.push(`site:${site}`);
-  fileType && searchQuery.push(`filetype:${fileType}`);
-  language && searchQuery.push(`lang:${language}`);
-  if (exactTerms && excludeTerms) {
-    throw new Error("Cannot specify both exactTerms and excludeTerms - please use only one");
-  }
-  exactTerms && searchQuery.push(exactTerms.split("|").map((term) => `+${term}`).join(" AND "));
-  excludeTerms && searchQuery.push(excludeTerms.split("|").map((term) => `-${term}`).join(" AND "));
-  searchParams.append("query", searchQuery.join(" "));
-  for (const [name, value] of Object.entries(rest)) {
-    if (value)
+  for (const [name, value] of Object.entries(searchQuery)) {
+    if (value !== undefined && value !== null) {
       searchParams.append(name, `${value}`);
+    }
   }
   url.search = searchParams.toString();
   const options = {
@@ -5334,39 +5050,119 @@ var fetchSearchResults = async ({
   return parsedResults;
 };
 
-// src/commands/search.ts
-var searchCommand = async (args) => {
+// src/shared/command-runner.ts
+import { parseArgs } from "node:util";
+
+// src/shared/use-get-user-agents.ts
+var useGetUserAgent = (client = "") => () => `CLI/${package_default.version}(You.com;${client})`;
+
+// src/shared/command-runner.ts
+var runCommand = async (args, config2) => {
   if (args.includes("--schema")) {
-    console.log(JSON.stringify(toJSONSchema(SearchQuerySchema)));
+    console.log(JSON.stringify(toJSONSchema(config2.schema)));
     process.exit(0);
   }
-  const { values } = parseArgs3({
+  const { values } = parseArgs({
     args,
     options: {
       json: { type: "string" },
       "api-key": { type: "string" },
-      client: { type: "string" }
+      client: { type: "string" },
+      "dry-run": { type: "boolean" }
     }
   });
   if (!values.json) {
     throw new Error("--json flag is required");
   }
-  const query = JSON.parse(values.json);
+  const input = JSON.parse(values.json);
   const apiKey = values["api-key"];
   const client = values.client || process.env.YDC_CLIENT;
   const YDC_API_KEY = apiKey || process.env.YDC_API_KEY;
   if (!YDC_API_KEY) {
     throw new Error("YDC_API_KEY environment variable is required");
   }
-  const searchQuery = SearchQuerySchema.parse(query);
-  const response = await fetchSearchResults({
-    searchQuery,
+  const validatedInput = config2.schema.parse(input);
+  const getUserAgent = useGetUserAgent(client);
+  if (values["dry-run"] && config2.dryRunHandler) {
+    const dryRunResult = config2.dryRunHandler({
+      input: validatedInput,
+      YDC_API_KEY,
+      getUserAgent
+    });
+    console.log(JSON.stringify(dryRunResult));
+    return;
+  }
+  const response = await config2.handler({
+    input: validatedInput,
     YDC_API_KEY,
-    getUserAgent: useGetUserAgent(client)
+    getUserAgent
   });
   console.log(JSON.stringify(response));
 };
 
+// src/shared/dry-run-utils.ts
+var buildSearchRequest = ({
+  searchQuery,
+  YDC_API_KEY,
+  getUserAgent
+}) => {
+  const queryParams = {};
+  for (const [name, value] of Object.entries(searchQuery)) {
+    if (value !== undefined && value !== null) {
+      queryParams[name] = `${value}`;
+    }
+  }
+  return {
+    url: SEARCH_API_URL,
+    method: "GET",
+    headers: {
+      "X-API-Key": YDC_API_KEY,
+      "User-Agent": getUserAgent()
+    },
+    queryParams
+  };
+};
+var buildContentsRequest = ({
+  contentsQuery: { urls, formats, format, crawl_timeout },
+  YDC_API_KEY,
+  getUserAgent
+}) => {
+  const requestFormats = formats || (format ? [format] : ["markdown"]);
+  const requestBody = {
+    urls,
+    formats: requestFormats
+  };
+  if (crawl_timeout !== undefined) {
+    requestBody.crawl_timeout = crawl_timeout;
+  }
+  return {
+    url: CONTENTS_API_URL,
+    method: "POST",
+    headers: {
+      "X-API-Key": YDC_API_KEY,
+      "Content-Type": "application/json",
+      "User-Agent": getUserAgent()
+    },
+    body: JSON.stringify(requestBody)
+  };
+};
+var buildDeepSearchRequest = ({
+  deepSearchQuery,
+  YDC_API_KEY,
+  getUserAgent
+}) => {
+  return {
+    url: DEEP_SEARCH_API_URL,
+    method: "POST",
+    headers: {
+      "X-API-Key": YDC_API_KEY,
+      "Content-Type": "application/json",
+      "User-Agent": getUserAgent()
+    },
+    body: JSON.stringify(deepSearchQuery)
+  };
+};
+
 // src/shared/generate-error-report-link.ts
 var generateErrorReportLink = ({
   errorMessage,
@@ -5406,7 +5202,7 @@ Usage: ydc <command> --json <json> [options]
 
 Commands:
   search                      Search the web with You.com
-  express                     Get AI answers with web context
+  deep-search                 Perform deep research with comprehensive answers
   contents                    Extract content from URLs
 
 Global Options:
@@ -5414,6 +5210,7 @@ Global Options:
   --api-key <key>             You.com API key (overrides YDC_API_KEY)
   --client <name>             Client name for tracking and debugging
   --schema                    Output JSON schema for what can be passed to --json
+  --dry-run                   Show request details without making API call
   --help, -h                  Show this help
 
 Environment Variables:
@@ -5426,36 +5223,69 @@ Output Format:
 
 Examples:
   ydc search --json '{"query":"AI developments"}' --client Openclaw
-  ydc express --json '{"input":"What happened today?","tools":[{"type":"web_search"}]}' --client MyAgent
+  ydc deep-search --json '{"query":"What are the latest breakthroughs in AI?","search_effort":"high"}' --client MyAgent
   ydc contents --json '{"urls":["https://example.com"],"formats":["markdown"]}'
   ydc search --schema  # Get JSON schema for search --json input
+  ydc search --json '{"query":"AI"}' --dry-run  # Inspect request without API call
   ydc search --json '{"query":"AI"}' | jq '.data.results.web[0].title'
 
 More info: https://github.com/youdotcom-oss/dx-toolkit/tree/main/packages/api
 `);
   process.exit(command ? 0 : 2);
 }
-try {
-  switch (command) {
-    case "search":
-      await searchCommand(args);
-      break;
-    case "express":
-      await expressCommand(args);
-      break;
-    case "contents":
-      await contentsCommand(args);
-      break;
-    default:
-      console.error(`Unknown command: ${command}`);
-      console.error(`Run 'ydc --help' for usage`);
-      process.exit(2);
+var commands = {
+  search: {
+    schema: SearchQuerySchema,
+    handler: ({
+      input,
+      YDC_API_KEY,
+      getUserAgent
+    }) => fetchSearchResults({ searchQuery: input, YDC_API_KEY, getUserAgent }),
+    dryRunHandler: ({
+      input,
+      YDC_API_KEY,
+      getUserAgent
+    }) => buildSearchRequest({ searchQuery: input, YDC_API_KEY, getUserAgent })
+  },
+  "deep-search": {
+    schema: DeepSearchQuerySchema,
+    handler: ({
+      input,
+      YDC_API_KEY,
+      getUserAgent
+    }) => callDeepSearch({ deepSearchQuery: input, YDC_API_KEY, getUserAgent }),
+    dryRunHandler: ({
+      input,
+      YDC_API_KEY,
+      getUserAgent
+    }) => buildDeepSearchRequest({ deepSearchQuery: input, YDC_API_KEY, getUserAgent })
+  },
+  contents: {
+    schema: ContentsQuerySchema,
+    handler: ({
+      input,
+      YDC_API_KEY,
+      getUserAgent
+    }) => fetchContents({ contentsQuery: input, YDC_API_KEY, getUserAgent }),
+    dryRunHandler: ({
+      input,
+      YDC_API_KEY,
+      getUserAgent
+    }) => buildContentsRequest({ contentsQuery: input, YDC_API_KEY, getUserAgent })
   }
+};
+if (!(command in commands)) {
+  console.error(`Unknown command: ${command}`);
+  console.error(`Run 'ydc --help' for usage`);
+  process.exit(2);
+}
+try {
+  await runCommand(args, commands[command]);
   process.exit(0);
 } catch (error2) {
   console.error(error2);
   const message = error2 instanceof Error ? error2.message : String(error2);
-  const { values } = parseArgs4({
+  const { values } = parseArgs2({
     args,
     options: {
       client: { type: "string" }