@youdotcom-oss/api 0.0.1

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@youdotcom-oss/api",
+  "version": "0.0.1",
+  "description": "You.com API client with bundled CLI for agents supporting Agent Skills",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18",
+    "bun": ">= 1.2.21"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/youdotcom-oss/dx-toolkit.git",
+    "directory": "packages/api"
+  },
+  "bugs": {
+    "url": "https://github.com/youdotcom-oss/dx-toolkit/issues"
+  },
+  "homepage": "https://github.com/youdotcom-oss/dx-toolkit/tree/main/packages/api#readme",
+  "author": "You.com (https://you.com)",
+  "keywords": [
+    "you.com",
+    "api",
+    "cli",
+    "search",
+    "ai",
+    "agent",
+    "agent-skills",
+    "bash",
+    "web-search",
+    "crawling",
+    "content-extraction"
+  ],
+  "bin": {
+    "ydc": "./bin/cli.js"
+  },
+  "type": "module",
+  "main": "./src/main.ts",
+  "exports": {
+    ".": "./src/main.ts"
+  },
+  "files": [
+    "./src/**",
+    "!./src/**/tests/*",
+    "!./src/**/*.spec.ts",
+    "bin/cli.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build ./src/cli.ts --outfile ./bin/cli.js --target=node",
+    "check": "bun run check:biome && bun run check:types && bun run check:package",
+    "check:biome": "biome check",
+    "check:package": "format-package --check",
+    "check:types": "tsc --noEmit",
+    "check:write": "biome check --write && bun run format:package",
+    "dev": "bun src/cli.ts",
+    "format:package": "format-package --write",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "test:coverage:watch": "bun test --coverage --watch",
+    "test:watch": "bun test --watch"
+  },
+  "dependencies": {
+    "zod": "^4.3.5"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * ydc - You.com API CLI
+ *
+ * Commands:
+ *   search <query>              - Search the web with You.com
+ *   express <input>             - Get AI answers with web context
+ *   contents <url> [url...]     - Extract content from URLs
+ *
+ * Options:
+ *   --api-key <key>             - You.com API key (overrides YDC_API_KEY)
+ *   --client <name>             - Client name for tracking (overrides YDC_CLIENT)
+ *   --output <json|text>        - Output format (default: json)
+ *   --help, -h                  - Show help
+ */
+import { parseArgs } from 'node:util'
+import packageJson from '../package.json' with { type: 'json' }
+import { contentsCommand } from './commands/contents.ts'
+import { expressCommand } from './commands/express.ts'
+import { searchCommand } from './commands/search.ts'
+import { generateErrorReportLink } from './shared/generate-error-report-link.ts'
+import { useGetUserAgent } from './shared/use-get-user-agents.ts'
+
+// Extract command and args (allows flags anywhere)
+const rawArgs = process.argv.slice(2)
+const command = rawArgs.find((arg) => !arg.startsWith('-')) || ''
+const commandIndex = rawArgs.indexOf(command)
+const args = commandIndex >= 0 ? rawArgs.slice(commandIndex + 1) : []
+
+// Check for help
+if (rawArgs.includes('--help') || rawArgs.includes('-h') || !command) {
+  console.log(`ydc v${packageJson.version} - You.com API CLI
+
+Usage: ydc <command> --json <json> [options]
+
+Commands:
+  search                      Search the web with You.com
+  express                     Get AI answers with web context
+  contents                    Extract content from URLs
+
+Global Options:
+  --json <json>               JSON string with command parameters (required)
+  --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
+  --help, -h                  Show this help
+
+Environment Variables:
+  YDC_API_KEY                 You.com API key (required)
+
+Output Format:
+  Success: API response on stdout (exit 0)
+  Error: { success: false, error: {...} } on stderr (exit 1)
+  Invalid args: Error message on stderr (exit 2)
+
+Examples:
+  ydc search "AI developments" --client Openclaw
+  ydc search "AI" --client Openclaw | jq '.data.results.web[0].title'
+  ydc express "What happened today?" --client MyAgent --tools web_search
+  ydc contents https://example.com --formats markdown
+  ydc search --schema  # Get JSON schema for search --json input
+
+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)
+  }
+  process.exit(0)
+} catch (error) {
+  console.error(error)
+  const message = error instanceof Error ? error.message : String(error)
+  const { values } = parseArgs({
+    args,
+    options: {
+      client: { type: 'string' },
+    },
+  })
+  const getUserAgent = useGetUserAgent(values.client || process.env.YDC_CLIENT)
+  console.error('\nTo report this error, share this mailto link with the user:')
+  console.error(generateErrorReportLink({ errorMessage: message, tool: command, clientInfo: getUserAgent() }))
+  process.exit(1)
+}

package/src/commands/contents.ts

@@ -0,0 +1,52 @@
+import { parseArgs } from 'node:util'
+import * as z from 'zod'
+import { ContentsQuerySchema } from '../contents/contents.schemas.ts'
+import { fetchContents } from '../contents/contents.utils.ts'
+import { useGetUserAgent } from '../shared/use-get-user-agents.ts'
+
+export const contentsCommand = async (args: string[]) => {
+  // Handle --schema flag
+  if (args.includes('--schema')) {
+    console.log(JSON.stringify(z.toJSONSchema(ContentsQuerySchema)))
+    process.exit(0)
+  }
+
+  // Parse flags with Node's built-in parseArgs
+  const { values } = parseArgs({
+    args,
+    options: {
+      json: { type: 'string' },
+      'api-key': { type: 'string' },
+      client: { type: 'string' },
+    },
+  })
+
+  // --json is required
+  if (!values.json) {
+    throw new Error('--json flag is required')
+  }
+
+  // Parse JSON and validate with schema
+  const query = JSON.parse(values.json)
+  const apiKey = values['api-key']
+  const client = values.client || process.env.YDC_CLIENT
+
+  // Get API key from options or environment
+  const YDC_API_KEY = apiKey || process.env.YDC_API_KEY
+  if (!YDC_API_KEY) {
+    throw new Error('YDC_API_KEY environment variable is required')
+  }
+
+  // Validate with schema (includes urls validation)
+  const contentsQuery = ContentsQuerySchema.parse(query)
+
+  // Fetch contents
+  const response = await fetchContents({
+    contentsQuery,
+    YDC_API_KEY,
+    getUserAgent: useGetUserAgent(client),
+  })
+
+  // Output response to stdout (success)
+  console.log(JSON.stringify(response))
+}

package/src/commands/express.ts

@@ -0,0 +1,52 @@
+import { parseArgs } from 'node:util'
+import * as z from 'zod'
+import { ExpressAgentInputSchema } from '../express/express.schemas.ts'
+import { callExpressAgent } from '../express/express.utils.ts'
+import { useGetUserAgent } from '../shared/use-get-user-agents.ts'
+
+export const expressCommand = async (args: string[]) => {
+  // Handle --schema flag
+  if (args.includes('--schema')) {
+    console.log(JSON.stringify(z.toJSONSchema(ExpressAgentInputSchema)))
+    process.exit(0)
+  }
+
+  // Parse flags with Node's built-in parseArgs
+  const { values } = parseArgs({
+    args,
+    options: {
+      json: { type: 'string' },
+      'api-key': { type: 'string' },
+      client: { type: 'string' },
+    },
+  })
+
+  // --json is required
+  if (!values.json) {
+    throw new Error('--json flag is required')
+  }
+
+  // Parse JSON and validate with schema
+  const input = JSON.parse(values.json)
+  const apiKey = values['api-key']
+  const client = values.client || process.env.YDC_CLIENT
+
+  // Get API key from options or environment
+  const YDC_API_KEY = apiKey || process.env.YDC_API_KEY
+  if (!YDC_API_KEY) {
+    throw new Error('YDC_API_KEY environment variable is required')
+  }
+
+  // Validate with schema (includes input validation)
+  const agentInput = ExpressAgentInputSchema.parse(input)
+
+  // Call agent
+  const response = await callExpressAgent({
+    agentInput,
+    YDC_API_KEY,
+    getUserAgent: useGetUserAgent(client),
+  })
+
+  // Output response to stdout (success)
+  console.log(JSON.stringify(response))
+}

package/src/commands/search.ts

@@ -0,0 +1,52 @@
+import { parseArgs } from 'node:util'
+import * as z from 'zod'
+import { SearchQuerySchema } from '../search/search.schemas.ts'
+import { fetchSearchResults } from '../search/search.utils.ts'
+import { useGetUserAgent } from '../shared/use-get-user-agents.ts'
+
+export const searchCommand = async (args: string[]) => {
+  // Handle --schema flag
+  if (args.includes('--schema')) {
+    console.log(JSON.stringify(z.toJSONSchema(SearchQuerySchema)))
+    process.exit(0)
+  }
+
+  // Parse flags with Node's built-in parseArgs
+  const { values } = parseArgs({
+    args,
+    options: {
+      json: { type: 'string' },
+      'api-key': { type: 'string' },
+      client: { type: 'string' },
+    },
+  })
+
+  // --json is required
+  if (!values.json) {
+    throw new Error('--json flag is required')
+  }
+
+  // Parse JSON and validate with schema
+  const query = JSON.parse(values.json)
+  const apiKey = values['api-key']
+  const client = values.client || process.env.YDC_CLIENT
+
+  // Get API key from options or environment
+  const YDC_API_KEY = apiKey || process.env.YDC_API_KEY
+  if (!YDC_API_KEY) {
+    throw new Error('YDC_API_KEY environment variable is required')
+  }
+
+  // Validate with schema (includes query validation)
+  const searchQuery = SearchQuerySchema.parse(query)
+
+  // Fetch results
+  const response = await fetchSearchResults({
+    searchQuery,
+    YDC_API_KEY,
+    getUserAgent: useGetUserAgent(client),
+  })
+
+  // Output response to stdout (success)
+  console.log(JSON.stringify(response))
+}

package/src/contents/contents.schemas.ts

@@ -0,0 +1,46 @@
+import * as z from 'zod'
+
+/**
+ * Input schema for the you-contents tool
+ * Accepts an array of URLs, optional formats array (or legacy format string), and optional crawl timeout
+ */
+export const ContentsQuerySchema = z.object({
+  urls: z
+    .array(z.string().url())
+    .min(1)
+    .describe('Array of webpage URLs to extract content from (e.g., ["https://example.com"])'),
+  formats: z
+    .array(z.enum(['markdown', 'html', 'metadata']))
+    .optional()
+    .describe('Output formats: array of "markdown" (text), "html" (layout), or "metadata" (structured data)'),
+  format: z.enum(['markdown', 'html']).optional().describe('(Deprecated) Output format - use formats array instead'),
+  crawl_timeout: z.number().min(1).max(60).optional().describe('Optional timeout in seconds (1-60) for page crawling'),
+})
+
+export type ContentsQuery = z.infer<typeof ContentsQuerySchema>
+
+/**
+ * Schema for a single content item in the API response
+ */
+const ContentsItemSchema = z.object({
+  url: z.string().describe('URL'),
+  title: z.string().optional().describe('Title'),
+  html: z.string().optional().describe('HTML content'),
+  markdown: z.string().optional().describe('Markdown content'),
+  metadata: z
+    .object({
+      jsonld: z.array(z.record(z.string(), z.unknown())).optional().describe('JSON-LD structured data (Schema.org)'),
+      opengraph: z.record(z.string(), z.string()).optional().describe('OpenGraph meta tags'),
+      twitter: z.record(z.string(), z.string()).optional().describe('Twitter Card metadata'),
+    })
+    .optional()
+    .describe('Structured metadata when available'),
+})
+
+/**
+ * API response schema from You.com Contents API
+ * Validates the full response array
+ */
+export const ContentsApiResponseSchema = z.array(ContentsItemSchema)
+
+export type ContentsApiResponse = z.infer<typeof ContentsApiResponseSchema>

package/src/contents/contents.utils.ts

@@ -0,0 +1,98 @@
+import { CONTENTS_API_URL } from '../shared/api.constants.ts'
+import type { GetUserAgent } from '../shared/api.types.ts'
+import { checkResponseForErrors } from '../shared/check-response-for-errors.ts'
+import { type ContentsApiResponse, ContentsApiResponseSchema, type ContentsQuery } from './contents.schemas.ts'
+
+/**
+ * Fetch content from You.com Contents API
+ * The API accepts multiple URLs in a single request and returns all results
+ * @param contentsQuery - Query parameters including URLs and format
+ * @param YDC_API_KEY - You.com API key
+ * @param getUserAgent - Function to get User-Agent string
+ * @returns Parsed and validated API response
+ */
+export const fetchContents = async ({
+  contentsQuery: { urls, formats, format, crawl_timeout },
+  YDC_API_KEY = process.env.YDC_API_KEY,
+  getUserAgent,
+}: {
+  contentsQuery: ContentsQuery
+  YDC_API_KEY?: string
+  getUserAgent: GetUserAgent
+}): Promise<ContentsApiResponse> => {
+  if (!YDC_API_KEY) {
+    throw new Error('YDC_API_KEY is required for Contents API')
+  }
+
+  // Handle backward compatibility: prefer formats array, fallback to format string, default to ['markdown']
+  const requestFormats = formats || (format ? [format] : ['markdown'])
+
+  // Build request body
+  const requestBody: {
+    urls: string[]
+    formats: string[]
+    crawl_timeout?: number
+  } = {
+    urls,
+    formats: requestFormats,
+  }
+
+  if (crawl_timeout !== undefined) {
+    requestBody.crawl_timeout = crawl_timeout
+  }
+
+  // Make single API call with all URLs
+  const options = {
+    method: 'POST',
+    headers: new Headers({
+      'X-API-Key': YDC_API_KEY,
+      'Content-Type': 'application/json',
+      'User-Agent': getUserAgent(),
+    }),
+    body: JSON.stringify(requestBody),
+  }
+
+  const response = await fetch(CONTENTS_API_URL, options)
+
+  // Handle HTTP errors
+  if (!response.ok) {
+    const errorCode = response.status
+
+    // Try to parse error response body
+    let errorDetail = `Failed to fetch contents. HTTP ${errorCode}`
+    try {
+      const errorBody = await response.json()
+      if (errorBody && typeof errorBody === 'object' && 'detail' in errorBody) {
+        errorDetail = String(errorBody.detail)
+      }
+    } catch {
+      // If parsing fails, use default error message
+    }
+
+    // Handle specific error codes
+    if (errorCode === 401) {
+      throw new Error(`Authentication failed: ${errorDetail}. Please check your You.com API key.`)
+    }
+    if (errorCode === 403) {
+      throw new Error(`Forbidden: ${errorDetail}. Your API key may not have access to the Contents API.`)
+    }
+    if (errorCode === 429) {
+      throw new Error('Rate limited by You.com API. Please try again later.')
+    }
+    if (errorCode >= 500) {
+      throw new Error(`You.com API server error: ${errorDetail}`)
+    }
+
+    throw new Error(errorDetail)
+  }
+
+  const results = await response.json()
+
+  // Check for error field in 200 responses
+  checkResponseForErrors(results)
+
+  // Validate schema
+  const parsedResults = ContentsApiResponseSchema.parse(results)
+
+  return parsedResults
+}

package/src/contents/tests/contents.utils.spec.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from 'bun:test'
+import { fetchContents } from '../contents.utils.ts'
+
+const getUserAgent = () => 'API/test (You.com;TEST)'
+
+// NOTE: The following tests require a You.com API key with access to the Contents API
+// Using example.com/example.org as test URLs since You.com blocks self-scraping
+describe('fetchContents', () => {
+  test(
+    'returns valid response structure for single URL',
+    async () => {
+      const result = await fetchContents({
+        contentsQuery: {
+          urls: ['https://documentation.you.com/developer-resources/mcp-server'],
+          format: 'markdown',
+        },
+        getUserAgent,
+      })
+
+      expect(Array.isArray(result)).toBe(true)
+      expect(result.length).toBeGreaterThan(0)
+
+      const firstItem = result[0]
+      expect(firstItem).toBeDefined()
+
+      // Should have markdown content
+      expect(firstItem?.markdown).toBeDefined()
+      expect(typeof firstItem?.markdown).toBe('string')
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'handles multiple URLs',
+    async () => {
+      const result = await fetchContents({
+        contentsQuery: {
+          urls: [
+            'https://documentation.you.com/developer-resources/mcp-server',
+            'https://documentation.you.com/developer-resources/python-sdk',
+          ],
+          format: 'markdown',
+        },
+        getUserAgent,
+      })
+
+      expect(Array.isArray(result)).toBe(true)
+      expect(result.length).toBe(2)
+
+      for (const item of result) {
+        expect(item).toHaveProperty('url')
+        expect(item.markdown).toBeDefined()
+      }
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'handles html format',
+    async () => {
+      const result = await fetchContents({
+        contentsQuery: {
+          urls: ['https://documentation.you.com/developer-resources/mcp-server'],
+          format: 'html',
+        },
+        getUserAgent,
+      })
+
+      expect(Array.isArray(result)).toBe(true)
+      const firstItem = result[0]
+      expect(firstItem).toBeDefined()
+
+      expect(firstItem?.html).toBeDefined()
+      expect(typeof firstItem?.html).toBe('string')
+    },
+    { retry: 2 },
+  )
+})

package/src/express/express.schemas.ts

@@ -0,0 +1,77 @@
+import * as z from 'zod'
+
+export const ExpressAgentInputSchema = z.object({
+  input: z.string().min(1, 'Input is required').describe('Query or prompt'),
+  tools: z
+    .array(
+      z.object({
+        type: z.enum(['web_search']).describe('Tool type'),
+      }),
+    )
+    .optional()
+    .describe('Tools (web search only)'),
+})
+
+export type ExpressAgentInput = z.infer<typeof ExpressAgentInputSchema>
+
+// API Response Schema - Validates the full response from You.com API
+
+// Search result content item from web_search.results
+// Note: thumbnail_url, source_type, and provider are API-only pass-through fields not used in MCP output
+const ApiSearchResultItemSchema = z.object({
+  source_type: z.string().optional(),
+  citation_uri: z.string().optional(), // Used as fallback for url in transformation
+  url: z.string(),
+  title: z.string(),
+  snippet: z.string(),
+  thumbnail_url: z.string().optional(), // API-only, not transformed to MCP output
+  provider: z.any().optional(), // API-only, not transformed to MCP output
+})
+
+// Union of possible output item types from API
+const ExpressAgentApiOutputItemSchema = z.union([
+  // web_search.results type - has content array, no text
+  z.object({
+    type: z.literal('web_search.results'),
+    content: z.array(ApiSearchResultItemSchema),
+  }),
+  // message.answer type - has text, no content
+  z.object({
+    type: z.literal('message.answer'),
+    text: z.string(),
+  }),
+])
+
+export const ExpressAgentApiResponseSchema = z
+  .object({
+    output: z.array(ExpressAgentApiOutputItemSchema),
+    agent: z.string().optional().describe('Agent identifier'),
+    mode: z.string().optional().describe('Agent mode'),
+    input: z.array(z.any()).optional().describe('Input messages'),
+  })
+  .passthrough()
+
+export type ExpressAgentApiResponse = z.infer<typeof ExpressAgentApiResponseSchema>
+
+// MCP Output Schema - Defines what we return to the MCP client (answer + optional search results, token efficient)
+
+// Search result item for MCP output
+const McpSearchResultItemSchema = z.object({
+  url: z.string().describe('URL'),
+  title: z.string().describe('Title'),
+  snippet: z.string().describe('Snippet'),
+})
+
+// MCP response structure: answer (always) + results (optional when web_search used)
+const ExpressAgentMcpResponseSchema = z.object({
+  answer: z.string().describe('AI answer'),
+  results: z
+    .object({
+      web: z.array(McpSearchResultItemSchema).describe('Web results'),
+    })
+    .optional()
+    .describe('Search results'),
+  agent: z.string().optional().describe('Agent ID'),
+})
+
+export type ExpressAgentMcpResponse = z.infer<typeof ExpressAgentMcpResponseSchema>