@open-mercato/web-research-tavily 0.7.1-develop.7194.1.ab4fc81f82

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+[build:web-research-tavily] found 2 entry points
+[build:web-research-tavily] built successfully

package/build.mjs

@@ -0,0 +1,10 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { buildPackage } from '../../scripts/build-package.mjs'
+
+const packageDir = dirname(fileURLToPath(import.meta.url))
+
+await buildPackage(packageDir, {
+  name: 'web-research-tavily',
+  entryPoints: 'src/**/*.ts',
+})

package/dist/adapter.js

@@ -0,0 +1,126 @@
+import {
+  CONTRACT_VERSION,
+  READY,
+  defineAdapterModule,
+  notReady,
+  searchOk,
+  stripTrailingSlashes,
+  toOutcomeFailure
+} from "@open-mercato/web-research";
+import { z } from "zod";
+const tavilyOptionsSchema = z.object({
+  apiKey: z.string().min(1).optional(),
+  baseUrl: z.url().optional(),
+  searchDepth: z.enum(["basic", "advanced"]).optional(),
+  includeContent: z.boolean().optional(),
+  timeoutMs: z.number().int().min(1e3).max(12e4).optional()
+});
+const DEFAULT_BASE_URL = "https://api.tavily.com";
+const DEFAULT_TIMEOUT_MS = 15e3;
+const responseSchema = z.object({
+  answer: z.string().nullish(),
+  results: z.array(
+    z.object({
+      url: z.string(),
+      title: z.string().nullish(),
+      content: z.string().nullish(),
+      raw_content: z.string().nullish(),
+      score: z.number().nullish(),
+      published_date: z.string().nullish()
+    })
+  ).nullish()
+});
+function parseJson(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+function createTavilyAdapter(options) {
+  const apiKey = options.apiKey?.trim() ?? "";
+  const baseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL);
+  const searchDepth = options.searchDepth ?? "basic";
+  const includeContent = options.includeContent ?? false;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return {
+    id: "tavily",
+    kind: "api",
+    capabilities: {
+      search: true,
+      fetch: false,
+      snippets: true,
+      content: includeContent,
+      freshness: false,
+      siteFilter: true,
+      cost: "metered"
+    },
+    /** `billable` — issues a real /search query. */
+    probeCost: "billable",
+    readiness: () => apiKey.length > 0 ? READY : notReady("Tavily API key is not set"),
+    async search(request, context) {
+      if (apiKey.length === 0) return { status: "unavailable", reason: "Tavily API key is not set" };
+      try {
+        const response = await context.http.request(`${baseUrl}/search`, {
+          method: "POST",
+          headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
+          body: JSON.stringify({
+            query: request.site ? `${request.query} site:${request.site}` : request.query,
+            max_results: request.limit,
+            search_depth: searchDepth,
+            include_answer: true,
+            include_raw_content: includeContent
+          }),
+          accept: ["application/json"],
+          timeoutMs,
+          signal: context.signal
+        });
+        const parsed = responseSchema.safeParse(parseJson(response.body));
+        if (!parsed.success) {
+          return { status: "error", reason: "Tavily returned an unrecognized response shape", retriable: false };
+        }
+        const results = (parsed.data.results ?? []).map((item) => ({
+          url: item.url,
+          title: item.title ?? null,
+          snippet: item.content ?? null,
+          content: item.raw_content ?? null,
+          publishedAt: item.published_date ?? null,
+          score: item.score ?? null
+        }));
+        context.report("ok", `Tavily returned ${results.length} result(s)`, { resultCount: results.length });
+        return searchOk(results, parsed.data.answer ?? void 0);
+      } catch (error) {
+        return toOutcomeFailure(error);
+      }
+    },
+    async healthCheck(context) {
+      if (apiKey.length === 0) return { ok: false, detail: "Tavily API key is not set" };
+      try {
+        await context.http.request(`${baseUrl}/search`, {
+          method: "POST",
+          headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
+          body: JSON.stringify({ query: "open mercato health check", max_results: 1 }),
+          accept: ["application/json"],
+          timeoutMs,
+          signal: context.signal
+        });
+        return { ok: true };
+      } catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+      }
+    }
+  };
+}
+const tavilyAdapterModule = defineAdapterModule({
+  id: "tavily",
+  kind: "api",
+  contractVersion: CONTRACT_VERSION,
+  optionsSchema: tavilyOptionsSchema,
+  createAdapter: createTavilyAdapter
+});
+export {
+  createTavilyAdapter,
+  tavilyAdapterModule,
+  tavilyOptionsSchema
+};
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/adapter.ts"],
+  "sourcesContent": ["import {\n  CONTRACT_VERSION,\n  READY,\n  defineAdapterModule,\n  notReady,\n  searchOk,\n  stripTrailingSlashes,\n  toOutcomeFailure,\n  type RawResult,\n  type SearchAdapter,\n  type SearchOutcome,\n} from '@open-mercato/web-research'\nimport { z } from 'zod'\n\nexport const tavilyOptionsSchema = z.object({\n  apiKey: z.string().min(1).optional(),\n  baseUrl: z.url().optional(),\n  searchDepth: z.enum(['basic', 'advanced']).optional(),\n  includeContent: z.boolean().optional(),\n  timeoutMs: z.number().int().min(1000).max(120_000).optional(),\n})\n\nexport type TavilyOptions = z.infer<typeof tavilyOptionsSchema>\n\nconst DEFAULT_BASE_URL = 'https://api.tavily.com'\nconst DEFAULT_TIMEOUT_MS = 15_000\n\nconst responseSchema = z.object({\n  answer: z.string().nullish(),\n  results: z\n    .array(\n      z.object({\n        url: z.string(),\n        title: z.string().nullish(),\n        content: z.string().nullish(),\n        raw_content: z.string().nullish(),\n        score: z.number().nullish(),\n        published_date: z.string().nullish(),\n      }),\n    )\n    .nullish(),\n})\n\nfunction parseJson(body: string): unknown {\n  try {\n    return JSON.parse(body)\n  } catch {\n    return null\n  }\n}\n\nexport function createTavilyAdapter(options: TavilyOptions): SearchAdapter {\n  const apiKey = options.apiKey?.trim() ?? ''\n  const baseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL)\n  const searchDepth = options.searchDepth ?? 'basic'\n  const includeContent = options.includeContent ?? false\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS\n\n  return {\n    id: 'tavily',\n    kind: 'api',\n    capabilities: {\n      search: true,\n      fetch: false,\n      snippets: true,\n      content: includeContent,\n      freshness: false,\n      siteFilter: true,\n      cost: 'metered',\n    },\n    /** `billable` \u2014 issues a real /search query. */\n    probeCost: 'billable' as const,\n    readiness: () => (apiKey.length > 0 ? READY : notReady('Tavily API key is not set')),\n\n    async search(request, context): Promise<SearchOutcome> {\n      if (apiKey.length === 0) return { status: 'unavailable', reason: 'Tavily API key is not set' }\n      try {\n        const response = await context.http.request(`${baseUrl}/search`, {\n          method: 'POST',\n          headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },\n          body: JSON.stringify({\n            query: request.site ? `${request.query} site:${request.site}` : request.query,\n            max_results: request.limit,\n            search_depth: searchDepth,\n            include_answer: true,\n            include_raw_content: includeContent,\n          }),\n          accept: ['application/json'],\n          timeoutMs,\n          signal: context.signal,\n        })\n        const parsed = responseSchema.safeParse(parseJson(response.body))\n        if (!parsed.success) {\n          return { status: 'error', reason: 'Tavily returned an unrecognized response shape', retriable: false }\n        }\n        const results: RawResult[] = (parsed.data.results ?? []).map((item) => ({\n          url: item.url,\n          title: item.title ?? null,\n          snippet: item.content ?? null,\n          content: item.raw_content ?? null,\n          publishedAt: item.published_date ?? null,\n          score: item.score ?? null,\n        }))\n        context.report('ok', `Tavily returned ${results.length} result(s)`, { resultCount: results.length })\n        return searchOk(results, parsed.data.answer ?? undefined)\n      } catch (error) {\n        return toOutcomeFailure(error)\n      }\n    },\n\n    async healthCheck(context) {\n      if (apiKey.length === 0) return { ok: false, detail: 'Tavily API key is not set' }\n      try {\n        await context.http.request(`${baseUrl}/search`, {\n          method: 'POST',\n          headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },\n          body: JSON.stringify({ query: 'open mercato health check', max_results: 1 }),\n          accept: ['application/json'],\n          timeoutMs,\n          signal: context.signal,\n        })\n        return { ok: true }\n      } catch (error) {\n        return { ok: false, detail: error instanceof Error ? error.message : String(error) }\n      }\n    },\n  }\n}\n\nexport const tavilyAdapterModule = defineAdapterModule({\n  id: 'tavily',\n  kind: 'api',\n  contractVersion: CONTRACT_VERSION,\n  optionsSchema: tavilyOptionsSchema,\n  createAdapter: createTavilyAdapter,\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/index.js

@@ -0,0 +1,9 @@
+import { createTavilyAdapter, tavilyAdapterModule, tavilyOptionsSchema } from "./adapter.js";
+import { tavilyAdapterModule as tavilyAdapterModule2 } from "./adapter.js";
+export {
+  createTavilyAdapter,
+  tavilyAdapterModule2 as default,
+  tavilyAdapterModule,
+  tavilyOptionsSchema
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["export { createTavilyAdapter, tavilyAdapterModule, tavilyOptionsSchema, type TavilyOptions } from './adapter'\n\nexport { tavilyAdapterModule as default } from './adapter'\n"],
+  "mappings": "AAAA,SAAS,qBAAqB,qBAAqB,2BAA+C;AAElG,SAAgC,uBAAvBA,4BAAsC;",
+  "names": ["tavilyAdapterModule"]
+}

package/jest.config.cjs

@@ -0,0 +1,28 @@
+/** @type {import('jest').Config} */
+const base = require('../../jest.config.base.cjs')
+
+module.exports = {
+  ...base,
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  watchman: false,
+  rootDir: '.',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
+  moduleNameMapper: {
+    '^@open-mercato/web-research/(.*)$': '<rootDir>/../web-research/src/$1',
+    '^@open-mercato/web-research$': '<rootDir>/../web-research/src/index.ts',
+  },
+  transform: {
+    '^.+\\.(t|j)sx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          rootDir: '.',
+          ignoreDeprecations: '6.0',
+        },
+      },
+    ],
+  },
+  testMatch: ['<rootDir>/src/**/__tests__/**/*.test.(ts|tsx)'],
+  passWithNoTests: true,
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@open-mercato/web-research-tavily",
+  "version": "0.7.1-develop.7194.1.ab4fc81f82",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "openMercato": {
+    "webResearchAdapter": {
+      "id": "tavily"
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node watch.mjs",
+    "test": "jest --config jest.config.cjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*": {
+      "types": [
+        "./src/*.ts"
+      ],
+      "default": "./dist/*.js"
+    }
+  },
+  "peerDependencies": {
+    "@open-mercato/web-research": "^0.6.0"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@open-mercato/web-research": "0.7.1-develop.7194.1.ab4fc81f82",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.0.1",
+    "esbuild": "^0.28.1",
+    "glob": "^13.0.6",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-mercato/open-mercato",
+    "directory": "packages/web-research-tavily"
+  },
+  "stableVersion": "0.7.0"
+}

package/src/__tests__/tavily.test.ts

@@ -0,0 +1,73 @@
+import { createStubHttpClient, createTestContext, describeAdapterContract } from '@open-mercato/web-research/testing'
+import { createTavilyAdapter, tavilyAdapterModule } from '../adapter'
+
+const BODY = JSON.stringify({
+  answer: 'Open Mercato is a modular commerce platform.',
+  results: [
+    { url: 'https://a.com/1', title: 'Alpha', content: 'Alpha snippet', score: 0.9 },
+    { url: 'https://b.com/2', title: 'Beta', content: 'Beta snippet', score: 0.5 },
+  ],
+})
+
+describe('tavily adapter', () => {
+  it('is unavailable without a key and makes no call', async () => {
+    const http = createStubHttpClient(() => ({ body: BODY }))
+    const outcome = await createTavilyAdapter({}).search({ query: 'x', limit: 5 }, createTestContext({ http }))
+    expect(outcome).toMatchObject({ status: 'unavailable' })
+    expect(http.calls).toHaveLength(0)
+  })
+
+  it('maps results and keeps the vendor answer', async () => {
+    const http = createStubHttpClient(() => ({ body: BODY }))
+    const outcome = await createTavilyAdapter({ apiKey: 'k' }).search(
+      { query: 'x', limit: 5 },
+      createTestContext({ http }),
+    )
+    expect(outcome.status).toBe('ok')
+    if (outcome.status !== 'ok') return
+    expect(outcome.results[0]).toMatchObject({ url: 'https://a.com/1', snippet: 'Alpha snippet', score: 0.9 })
+    expect(outcome.answer).toContain('modular commerce platform')
+  })
+
+  it('sends the key as a bearer token and honours the site filter', async () => {
+    const seen: Array<{ headers?: Record<string, string>; body?: string }> = []
+    const http = createStubHttpClient((_url, init) => {
+      seen.push({ headers: init?.headers as Record<string, string>, body: init?.body })
+      return { body: BODY }
+    })
+    await createTavilyAdapter({ apiKey: 'secret' }).search(
+      { query: 'pricing', limit: 5, site: 'example.com' },
+      createTestContext({ http }),
+    )
+    expect(seen[0].headers?.authorization).toBe('Bearer secret')
+    expect(JSON.parse(seen[0].body ?? '{}').query).toBe('pricing site:example.com')
+  })
+
+  it('reports an unrecognized payload as an error', async () => {
+    const http = createStubHttpClient(() => ({ body: '{"results":"nope"}' }))
+    const outcome = await createTavilyAdapter({ apiKey: 'k' }).search(
+      { query: 'x', limit: 5 },
+      createTestContext({ http }),
+    )
+    expect(outcome).toMatchObject({ status: 'error' })
+  })
+
+  it('returns empty when the vendor found nothing and offered no answer', async () => {
+    const http = createStubHttpClient(() => ({ body: JSON.stringify({ results: [] }) }))
+    const outcome = await createTavilyAdapter({ apiKey: 'k' }).search(
+      { query: 'x', limit: 5 },
+      createTestContext({ http }),
+    )
+    expect(outcome.status).toBe('empty')
+  })
+})
+
+describeAdapterContract(
+  tavilyAdapterModule,
+  {
+    unconfiguredOptions: {},
+    configuredOptions: { apiKey: 'test-key' },
+    context: () => createTestContext({ http: createStubHttpClient(() => ({ body: BODY })) }),
+  },
+  { describe, it, expect: expect as never },
+)

package/src/adapter.ts

@@ -0,0 +1,136 @@
+import {
+  CONTRACT_VERSION,
+  READY,
+  defineAdapterModule,
+  notReady,
+  searchOk,
+  stripTrailingSlashes,
+  toOutcomeFailure,
+  type RawResult,
+  type SearchAdapter,
+  type SearchOutcome,
+} from '@open-mercato/web-research'
+import { z } from 'zod'
+
+export const tavilyOptionsSchema = z.object({
+  apiKey: z.string().min(1).optional(),
+  baseUrl: z.url().optional(),
+  searchDepth: z.enum(['basic', 'advanced']).optional(),
+  includeContent: z.boolean().optional(),
+  timeoutMs: z.number().int().min(1000).max(120_000).optional(),
+})
+
+export type TavilyOptions = z.infer<typeof tavilyOptionsSchema>
+
+const DEFAULT_BASE_URL = 'https://api.tavily.com'
+const DEFAULT_TIMEOUT_MS = 15_000
+
+const responseSchema = z.object({
+  answer: z.string().nullish(),
+  results: z
+    .array(
+      z.object({
+        url: z.string(),
+        title: z.string().nullish(),
+        content: z.string().nullish(),
+        raw_content: z.string().nullish(),
+        score: z.number().nullish(),
+        published_date: z.string().nullish(),
+      }),
+    )
+    .nullish(),
+})
+
+function parseJson(body: string): unknown {
+  try {
+    return JSON.parse(body)
+  } catch {
+    return null
+  }
+}
+
+export function createTavilyAdapter(options: TavilyOptions): SearchAdapter {
+  const apiKey = options.apiKey?.trim() ?? ''
+  const baseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL)
+  const searchDepth = options.searchDepth ?? 'basic'
+  const includeContent = options.includeContent ?? false
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+
+  return {
+    id: 'tavily',
+    kind: 'api',
+    capabilities: {
+      search: true,
+      fetch: false,
+      snippets: true,
+      content: includeContent,
+      freshness: false,
+      siteFilter: true,
+      cost: 'metered',
+    },
+    /** `billable` — issues a real /search query. */
+    probeCost: 'billable' as const,
+    readiness: () => (apiKey.length > 0 ? READY : notReady('Tavily API key is not set')),
+
+    async search(request, context): Promise<SearchOutcome> {
+      if (apiKey.length === 0) return { status: 'unavailable', reason: 'Tavily API key is not set' }
+      try {
+        const response = await context.http.request(`${baseUrl}/search`, {
+          method: 'POST',
+          headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+          body: JSON.stringify({
+            query: request.site ? `${request.query} site:${request.site}` : request.query,
+            max_results: request.limit,
+            search_depth: searchDepth,
+            include_answer: true,
+            include_raw_content: includeContent,
+          }),
+          accept: ['application/json'],
+          timeoutMs,
+          signal: context.signal,
+        })
+        const parsed = responseSchema.safeParse(parseJson(response.body))
+        if (!parsed.success) {
+          return { status: 'error', reason: 'Tavily returned an unrecognized response shape', retriable: false }
+        }
+        const results: RawResult[] = (parsed.data.results ?? []).map((item) => ({
+          url: item.url,
+          title: item.title ?? null,
+          snippet: item.content ?? null,
+          content: item.raw_content ?? null,
+          publishedAt: item.published_date ?? null,
+          score: item.score ?? null,
+        }))
+        context.report('ok', `Tavily returned ${results.length} result(s)`, { resultCount: results.length })
+        return searchOk(results, parsed.data.answer ?? undefined)
+      } catch (error) {
+        return toOutcomeFailure(error)
+      }
+    },
+
+    async healthCheck(context) {
+      if (apiKey.length === 0) return { ok: false, detail: 'Tavily API key is not set' }
+      try {
+        await context.http.request(`${baseUrl}/search`, {
+          method: 'POST',
+          headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+          body: JSON.stringify({ query: 'open mercato health check', max_results: 1 }),
+          accept: ['application/json'],
+          timeoutMs,
+          signal: context.signal,
+        })
+        return { ok: true }
+      } catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) }
+      }
+    },
+  }
+}
+
+export const tavilyAdapterModule = defineAdapterModule({
+  id: 'tavily',
+  kind: 'api',
+  contractVersion: CONTRACT_VERSION,
+  optionsSchema: tavilyOptionsSchema,
+  createAdapter: createTavilyAdapter,
+})

package/src/index.ts

@@ -0,0 +1,3 @@
+export { createTavilyAdapter, tavilyAdapterModule, tavilyOptionsSchema, type TavilyOptions } from './adapter'
+
+export { tavilyAdapterModule as default } from './adapter'

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/__tests__/**"]
+}

package/watch.mjs

@@ -0,0 +1,7 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { watch } from '../../scripts/watch.mjs'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+watch(__dirname)