@youdotcom-oss/api 0.1.0 → 0.2.0

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>

package/src/express/express.utils.ts

@@ -1,113 +0,0 @@
-import { EXPRESS_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 ExpressAgentApiResponse,
-  ExpressAgentApiResponseSchema,
-  type ExpressAgentInput,
-  type ExpressAgentMcpResponse,
-} from './express.schemas.ts'
-
-/**
- * Checks response status and throws appropriate errors for agent API calls
- */
-const agentThrowOnFailedStatus = async (response: Response) => {
-  const errorCode = response.status
-
-  const errorData = (await response.json()) as {
-    errors?: Array<{ detail?: string }>
-  }
-
-  if (errorCode === 400) {
-    throw new Error(`Bad Request:\n${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}`)
-}
-
-export const callExpressAgent = async ({
-  YDC_API_KEY = process.env.YDC_API_KEY,
-  agentInput: { input, tools },
-  getUserAgent,
-}: {
-  agentInput: ExpressAgentInput
-  YDC_API_KEY?: string
-  getUserAgent: GetUserAgent
-}) => {
-  const requestBody: {
-    agent: string
-    input: string
-    stream: boolean
-    tools?: Array<{ type: 'web_search' }>
-  } = {
-    agent: 'express',
-    input,
-    stream: false, // Use non-streaming JSON response
-  }
-
-  // Only include tools if provided
-  if (tools) {
-    requestBody.tools = tools
-  }
-
-  const options = {
-    method: 'POST',
-    headers: new Headers({
-      Authorization: `Bearer ${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)
-  }
-
-  // Parse JSON response directly
-  const jsonResponse = await response.json()
-
-  // Check for error field in response
-  checkResponseForErrors(jsonResponse)
-
-  // Validate API response schema (full response with all fields)
-  const apiResponse: ExpressAgentApiResponse = ExpressAgentApiResponseSchema.parse(jsonResponse)
-
-  // Find the answer (always present as message.answer, validated by Zod)
-  const answerItem = apiResponse.output.find((item) => item.type === 'message.answer')
-  if (!answerItem) {
-    throw new Error('Express API response missing required message.answer item')
-  }
-
-  // Find search results (optional, present when web_search tool is used)
-  const searchItem = apiResponse.output.find((item) => item.type === 'web_search.results')
-
-  // Transform API response to MCP output format (answer + optional search results, token efficient)
-  const mcpResponse: ExpressAgentMcpResponse = {
-    answer: answerItem.text,
-    agent: apiResponse.agent,
-  }
-
-  // Transform search results if present
-  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
-}

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

@@ -1,83 +0,0 @@
-import { describe, expect, setDefaultTimeout, test } from 'bun:test'
-import { callExpressAgent } from '../express.utils.ts'
-
-const getUserAgent = () => 'API/test (You.com;TEST)'
-
-setDefaultTimeout(20_000)
-
-describe('callExpressAgent', () => {
-  test(
-    'returns answer only (WITHOUT web_search tools)',
-    async () => {
-      const result = await callExpressAgent({
-        agentInput: { input: 'What is machine learning?' },
-        getUserAgent,
-      })
-
-      // Verify MCP response structure
-      expect(result).toHaveProperty('answer')
-      expect(typeof result.answer).toBe('string')
-      expect(result.answer.length).toBeGreaterThan(0)
-
-      // Should NOT have results when web_search is not used
-      expect(result.results).toBeUndefined()
-
-      expect(result.agent).toBe('express')
-    },
-    { retry: 2 },
-  )
-
-  test(
-    'returns answer and search results (WITH web_search tools)',
-    async () => {
-      const result = await callExpressAgent({
-        agentInput: {
-          input: 'Latest developments in quantum computing',
-          tools: [{ type: 'web_search' }],
-        },
-        getUserAgent,
-      })
-
-      // Verify MCP response has both answer and results
-      expect(result).toHaveProperty('answer')
-      expect(typeof result.answer).toBe('string')
-      expect(result.answer.length).toBeGreaterThan(0)
-
-      expect(result).toHaveProperty('results')
-      expect(result.results).toHaveProperty('web')
-      expect(Array.isArray(result.results?.web)).toBe(true)
-      expect(result.results?.web.length).toBeGreaterThan(0)
-
-      // Verify each search result has required fields
-      const firstResult = result.results?.web[0]
-      expect(firstResult).toHaveProperty('url')
-      expect(firstResult).toHaveProperty('title')
-      expect(firstResult).toHaveProperty('snippet')
-      expect(typeof firstResult?.url).toBe('string')
-      expect(typeof firstResult?.title).toBe('string')
-      expect(typeof firstResult?.snippet).toBe('string')
-      expect(firstResult?.url.length).toBeGreaterThan(0)
-      expect(firstResult?.title.length).toBeGreaterThan(0)
-
-      expect(result.agent).toBe('express')
-    },
-    { timeout: 30_000, retry: 2 },
-  )
-
-  test(
-    'works without optional parameters',
-    async () => {
-      const result = await callExpressAgent({
-        agentInput: { input: 'What is the capital of France?' },
-        getUserAgent,
-        // No progressToken or sendProgress provided
-      })
-
-      // Should work normally without progress tracking
-      expect(result).toHaveProperty('answer')
-      expect(result.answer.length).toBeGreaterThan(0)
-      expect(result.agent).toBe('express')
-    },
-    { retry: 2 },
-  )
-})