@youdotcom-oss/api 0.1.1 → 0.2.1

package/src/shared/command-runner.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared command infrastructure for CLI commands
+ * Handles flag parsing, validation, and execution
+ *
+ * @internal
+ */
+
+import { parseArgs } from 'node:util'
+import * as z from 'zod'
+import type { GetUserAgent } from './api.types.ts'
+import type { DryRunResult } from './dry-run-utils.ts'
+import { useGetUserAgent } from './use-get-user-agents.ts'
+
+/**
+ * Configuration for a command
+ *
+ * @typeParam TInput - Zod-inferred input type
+ * @typeParam TOutput - Command output type
+ */
+export type CommandConfig<TInput, TOutput> = {
+  schema: z.ZodType<TInput>
+  handler: (params: { input: TInput; YDC_API_KEY: string; getUserAgent: GetUserAgent }) => Promise<TOutput>
+  dryRunHandler?: (params: { input: TInput; YDC_API_KEY: string; getUserAgent: GetUserAgent }) => DryRunResult
+}
+
+/**
+ * Run a command with standardized flag parsing and validation
+ * Handles --schema, --json, --api-key, --client, and --dry-run flags
+ *
+ * @param args - Command line arguments
+ * @param config - Command configuration with schema and handler
+ *
+ * @internal
+ */
+export const runCommand = async <TInput, TOutput>(args: string[], config: CommandConfig<TInput, TOutput>) => {
+  // Handle --schema flag
+  if (args.includes('--schema')) {
+    console.log(JSON.stringify(z.toJSONSchema(config.schema)))
+    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' },
+      'dry-run': { type: 'boolean' },
+    },
+  })
+
+  // --json is required
+  if (!values.json) {
+    throw new Error('--json flag is required')
+  }
+
+  // Parse JSON input
+  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
+  const validatedInput = config.schema.parse(input)
+
+  // Create getUserAgent function
+  const getUserAgent = useGetUserAgent(client)
+
+  // Handle --dry-run flag
+  if (values['dry-run'] && config.dryRunHandler) {
+    const dryRunResult = config.dryRunHandler({
+      input: validatedInput,
+      YDC_API_KEY,
+      getUserAgent,
+    })
+    console.log(JSON.stringify(dryRunResult))
+    return
+  }
+
+  // Execute handler
+  const response = await config.handler({
+    input: validatedInput,
+    YDC_API_KEY,
+    getUserAgent,
+  })
+
+  // Output response to stdout (success)
+  console.log(JSON.stringify(response))
+}

package/src/shared/dry-run-utils.ts

@@ -0,0 +1,141 @@
+/**
+ * Dry-run utilities for testing request construction without API calls
+ * These functions build request details (URL, headers, body) that can be inspected
+ * without making actual API calls.
+ *
+ * @public
+ */
+
+import type { ContentsQuery } from '../contents/contents.schemas.ts'
+import type { DeepSearchQuery } from '../deep-search/deep-search.schemas.ts'
+import type { SearchQuery } from '../search/search.schemas.ts'
+import { CONTENTS_API_URL, DEEP_SEARCH_API_URL, SEARCH_API_URL } from './api.constants.ts'
+import type { GetUserAgent } from './api.types.ts'
+
+/**
+ * Result structure for dry-run request inspection
+ *
+ * @public
+ */
+export type DryRunResult = {
+  url: string
+  method: 'GET' | 'POST'
+  headers: Record<string, string>
+  body?: string
+  queryParams?: Record<string, string>
+}
+
+/**
+ * Build search request details without making API call
+ * Useful for testing and debugging query construction
+ *
+ * @param params - Search query parameters
+ * @returns Request details including URL, headers, and query params
+ *
+ * @public
+ */
+export const buildSearchRequest = ({
+  searchQuery,
+  YDC_API_KEY,
+  getUserAgent,
+}: {
+  searchQuery: SearchQuery
+  YDC_API_KEY: string
+  getUserAgent: GetUserAgent
+}): DryRunResult => {
+  // Convert all search query params to query string parameters
+  const queryParams: Record<string, string> = {}
+
+  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,
+  }
+}
+
+/**
+ * Build contents request details without making API call
+ * Useful for testing and debugging POST body construction
+ *
+ * @param params - Contents query parameters
+ * @returns Request details including URL, headers, and POST body
+ *
+ * @public
+ */
+export const buildContentsRequest = ({
+  contentsQuery: { urls, formats, format, crawl_timeout },
+  YDC_API_KEY,
+  getUserAgent,
+}: {
+  contentsQuery: ContentsQuery
+  YDC_API_KEY: string
+  getUserAgent: GetUserAgent
+}): DryRunResult => {
+  // 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
+  }
+
+  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),
+  }
+}
+
+/**
+ * Build deep-search request details without making API call
+ * Useful for testing and debugging POST body construction
+ *
+ * @param params - Deep-search query parameters
+ * @returns Request details including URL, headers, and POST body
+ *
+ * @public
+ */
+export const buildDeepSearchRequest = ({
+  deepSearchQuery,
+  YDC_API_KEY,
+  getUserAgent,
+}: {
+  deepSearchQuery: DeepSearchQuery
+  YDC_API_KEY: string
+  getUserAgent: GetUserAgent
+}): DryRunResult => {
+  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),
+  }
+}

package/src/shared/tests/command-runner.spec.ts

@@ -0,0 +1,210 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import * as z from 'zod'
+import { runCommand } from '../command-runner.ts'
+
+describe('runCommand', () => {
+  const TestSchema = z.object({
+    value: z.string(),
+  })
+
+  let originalApiKey: string | undefined
+
+  beforeAll(() => {
+    // Save original API key
+    originalApiKey = process.env.YDC_API_KEY
+  })
+
+  afterAll(() => {
+    // Restore original API key
+    if (originalApiKey) {
+      process.env.YDC_API_KEY = originalApiKey
+    } else {
+      delete process.env.YDC_API_KEY
+    }
+  })
+
+  test('outputs JSON schema when --schema flag is provided', async () => {
+    const originalExit = process.exit
+    const originalLog = console.log
+
+    process.exit = (() => {
+      throw new Error('EXIT')
+    }) as typeof process.exit
+
+    let outputData = ''
+    console.log = (data: string) => {
+      outputData = data
+    }
+
+    try {
+      await runCommand(['--schema'], {
+        schema: TestSchema,
+        handler: async () => ({ result: 'test' }),
+      })
+    } catch (error) {
+      if (error instanceof Error && error.message === 'EXIT') {
+        const schema = JSON.parse(outputData)
+        expect(schema.type).toBe('object')
+        expect(schema.properties).toBeDefined()
+      }
+    }
+
+    // Restore original functions
+    process.exit = originalExit
+    console.log = originalLog
+  })
+
+  test('throws error when --json flag is missing', async () => {
+    expect(async () => {
+      await runCommand([], {
+        schema: TestSchema,
+        handler: async () => ({ result: 'test' }),
+      })
+    }).toThrow('--json flag is required')
+  })
+
+  test('throws error when JSON is malformed', async () => {
+    expect(async () => {
+      await runCommand(['--json', 'invalid-json'], {
+        schema: TestSchema,
+        handler: async () => ({ result: 'test' }),
+      })
+    }).toThrow()
+  })
+
+  test('throws error when API key is missing from both flag and env', async () => {
+    const originalApiKey = process.env.YDC_API_KEY
+    delete process.env.YDC_API_KEY
+
+    expect(async () => {
+      await runCommand(['--json', '{"value":"test"}'], {
+        schema: TestSchema,
+        handler: async () => ({ result: 'test' }),
+      })
+    }).toThrow('YDC_API_KEY environment variable is required')
+
+    // Restore original value
+    if (originalApiKey) {
+      process.env.YDC_API_KEY = originalApiKey
+    }
+  })
+
+  test('resolves API key from --api-key flag over environment', async () => {
+    const originalLog = console.log
+    process.env.YDC_API_KEY = 'env-key'
+
+    let capturedKey = ''
+    console.log = () => {
+      // Suppress output
+    }
+
+    await runCommand(['--json', '{"value":"test"}', '--api-key', 'flag-key'], {
+      schema: TestSchema,
+      handler: async ({ YDC_API_KEY }) => {
+        capturedKey = YDC_API_KEY
+        return { result: 'test' }
+      },
+    })
+
+    expect(capturedKey).toBe('flag-key')
+
+    // Restore original function
+    console.log = originalLog
+  })
+
+  test('throws error when schema validation fails', async () => {
+    process.env.YDC_API_KEY = 'test-key'
+
+    expect(async () => {
+      await runCommand(['--json', '{"invalid":"field"}'], {
+        schema: TestSchema,
+        handler: async () => ({ result: 'test' }),
+      })
+    }).toThrow()
+  })
+
+  test('calls handler when all validations pass', async () => {
+    const originalLog = console.log
+    process.env.YDC_API_KEY = 'test-key'
+
+    let handlerCalled = false
+    let outputData = ''
+    console.log = (data: string) => {
+      outputData = data
+    }
+
+    await runCommand(['--json', '{"value":"test"}'], {
+      schema: TestSchema,
+      handler: async () => {
+        handlerCalled = true
+        return { result: 'success' }
+      },
+    })
+
+    expect(handlerCalled).toBe(true)
+    const output = JSON.parse(outputData)
+    expect(output.result).toBe('success')
+
+    // Restore original function
+    console.log = originalLog
+  })
+
+  test('calls dryRunHandler when --dry-run flag is provided', async () => {
+    const originalLog = console.log
+    process.env.YDC_API_KEY = 'test-key'
+
+    let dryRunCalled = false
+    let handlerCalled = false
+    let outputData = ''
+    console.log = (data: string) => {
+      outputData = data
+    }
+
+    await runCommand(['--json', '{"value":"test"}', '--dry-run'], {
+      schema: TestSchema,
+      handler: async () => {
+        handlerCalled = true
+        return { result: 'success' }
+      },
+      dryRunHandler: () => {
+        dryRunCalled = true
+        return {
+          url: 'https://test.com',
+          method: 'GET',
+          headers: { 'X-API-Key': 'test-key' },
+        }
+      },
+    })
+
+    expect(dryRunCalled).toBe(true)
+    expect(handlerCalled).toBe(false)
+    const output = JSON.parse(outputData)
+    expect(output.url).toBe('https://test.com')
+
+    // Restore original function
+    console.log = originalLog
+  })
+
+  test('respects --client flag for User-Agent', async () => {
+    const originalLog = console.log
+    process.env.YDC_API_KEY = 'test-key'
+
+    let capturedUserAgent = ''
+    console.log = () => {
+      // Suppress output
+    }
+
+    await runCommand(['--json', '{"value":"test"}', '--client', 'TestClient'], {
+      schema: TestSchema,
+      handler: async ({ getUserAgent }) => {
+        capturedUserAgent = getUserAgent()
+        return { result: 'test' }
+      },
+    })
+
+    expect(capturedUserAgent).toContain('TestClient')
+
+    // Restore original function
+    console.log = originalLog
+  })
+})

package/src/shared/use-get-user-agents.ts

@@ -5,4 +5,4 @@ import type { GetUserAgent } from './api.types.ts'
 export const useGetUserAgent =
   (client = ''): GetUserAgent =>
   () =>
-    `CLI/ ${packageJson.version} (You.com;${client})`
+    `CLI/${packageJson.version}(You.com;${client})`

package/src/commands/contents.ts

@@ -1,52 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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/express/express.schemas.ts

@@ -1,85 +0,0 @@
-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().nullable().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().nullable().optional(), // API-only, not transformed to MCP output
-  provider: z.string().nullable().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.object({
-          role: z.enum(['user']).describe('User role'),
-          content: z.string().describe('User question'),
-        }),
-      )
-      .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>