@x12i/api-hub-search 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @x12i/api-hub-search
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Web search client for the x12i API hub
+
+ESM package for Node.js 24 or newer. Import the public name:
+
+```js
+import * as search from '@x12i/api-hub-search';
+```
+
+The whole set is also available from [`@x12i/api-hub`](https://www.npmjs.com/package/@x12i/api-hub).

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { type Logger, type WebSearch, type WebSearchResult } from '@x12i/api-hub-core';
+import { type SearchProvider } from '@x12i/search';
+import { type SearchAdapter } from '@x12i/search-adapter';
+export declare const MAX_RESULTS = 20;
+export declare const SERPER_NEWS_URL = "https://google.serper.dev/news";
+/** A news result; `source` is the publisher name when the provider reports one. */
+export interface NewsSearchResult extends WebSearchResult {
+    source?: string;
+}
+/** One POST to Serper's news endpoint. Injectable so tests never reach the network. */
+export type SerperNewsTransport = (body: Record<string, unknown>, signal: AbortSignal) => Promise<{
+    status: number;
+    data: unknown;
+}>;
+export declare function mapSerperNews(data: unknown, limit: number): NewsSearchResult[];
+/** Serper (Google results): web through `@x12i/search`, news through Serper's news endpoint (which `@x12i/search` does not cover). */
+export declare function serperSearchClient(options: {
+    apiKey?: string;
+    provider?: SearchProvider;
+    newsTransport?: SerperNewsTransport;
+    log?: Logger;
+    timeoutMs?: number;
+}): WebSearch;
+/** Tavily through `@x12i/search-adapter`. Its page-fetch stage stays off: caller URLs only go through `@x12i/api-hub-safe-fetch`. */
+export declare function tavilySearchClient(options: {
+    apiKey?: string;
+    adapter?: SearchAdapter;
+    log?: Logger;
+    timeoutMs?: number;
+}): WebSearch;
+/** Serper when `SERPER_API_KEY` is set, else Tavily when `TAVILY_API_KEY` is set, else the stub (`service_not_connected`). */
+export declare function createSearchFromEnv(env?: NodeJS.ProcessEnv, log?: Logger): WebSearch;

package/dist/index.js

@@ -0,0 +1,231 @@
+import { HubError, stubSearch, } from '@x12i/api-hub-core';
+import { createSerperProvider, search as serperSearch, SearchError } from '@x12i/search';
+import { createSearchAdapter } from '@x12i/search-adapter';
+import { request } from 'undici';
+export const MAX_RESULTS = 20;
+const DAYS = { day: 1, week: 7, month: 31, year: 365 };
+export const SERPER_NEWS_URL = 'https://google.serper.dev/news';
+const SERPER_NEWS_MAX_BYTES = 2 * 1024 * 1024;
+function serperNewsTransport(apiKey, timeoutMs) {
+    return async (body, signal) => {
+        const res = await request(SERPER_NEWS_URL, {
+            method: 'POST',
+            headers: { 'x-api-key': apiKey, 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]),
+        });
+        const length = Number(res.headers['content-length'] ?? 0);
+        if (length > SERPER_NEWS_MAX_BYTES) {
+            await res.body.dump();
+            return { status: 502, data: null };
+        }
+        const text = await res.body.text();
+        try {
+            return { status: res.statusCode, data: text.length <= SERPER_NEWS_MAX_BYTES ? JSON.parse(text) : null };
+        }
+        catch {
+            return { status: res.statusCode, data: null };
+        }
+    };
+}
+const nonEmpty = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+export function mapSerperNews(data, limit) {
+    const items = data?.news;
+    if (!Array.isArray(items))
+        throw new HubError('upstream_unavailable', 'The search provider returned an unusable response', { provider: 'serper' });
+    const results = [];
+    for (const raw of items) {
+        const title = nonEmpty(raw?.title);
+        const link = nonEmpty(raw?.link);
+        if (!title || !link || !/^https?:\/\//i.test(link))
+            continue;
+        const snippet = nonEmpty(raw.snippet);
+        const date = nonEmpty(raw.date);
+        const source = nonEmpty(raw.source);
+        results.push({
+            position: typeof raw.position === 'number' && raw.position > 0 ? raw.position : results.length + 1,
+            title,
+            url: link,
+            domain: domainOf(link),
+            ...(snippet ? { snippet } : {}),
+            ...(date ? { date } : {}),
+            ...(source ? { source } : {}),
+        });
+        if (results.length === limit)
+            break;
+    }
+    return results;
+}
+async function serperNews(req, transport, log) {
+    const limit = clampLimit(req.limit);
+    const body = { q: req.query, num: limit };
+    if (req.country)
+        body.gl = req.country;
+    if (req.language)
+        body.hl = req.language;
+    if (req.timeRange)
+        body.tbs = `qdr:${req.timeRange[0]}`;
+    let res;
+    try {
+        res = await transport(body, req.signal ?? new AbortController().signal);
+    }
+    catch (err) {
+        if (req.signal?.aborted)
+            throw new HubError('timeout', 'The search was cancelled');
+        const name = err?.name;
+        if (name === 'TimeoutError' || name === 'AbortError')
+            throw new HubError('timeout', 'The search provider did not answer in time');
+        throw new HubError('upstream_unavailable', 'The search provider is unavailable', { provider: 'serper' });
+    }
+    if (res.status === 401 || res.status === 403) {
+        log?.warn('search provider rejected the configured key', { provider: 'serper' });
+        throw new HubError('upstream_unavailable', 'The search provider rejected the configured key');
+    }
+    if (res.status >= 400)
+        throw new HubError('upstream_unavailable', 'The search provider is unavailable', { provider: 'serper', status: res.status });
+    return { provider: 'serper', query: req.query, results: mapSerperNews(res.data, limit) };
+}
+function domainOf(url) {
+    try {
+        return new URL(url).hostname.replace(/^www\./, '');
+    }
+    catch {
+        return '';
+    }
+}
+function clampLimit(limit) {
+    return Math.min(Math.max(Math.trunc(limit ?? 10), 1), MAX_RESULTS);
+}
+function serperError(err, log) {
+    if (err instanceof HubError)
+        throw err;
+    if (err instanceof SearchError) {
+        switch (err.code) {
+            case 'INVALID_SEARCH_REQUEST':
+                throw new HubError('invalid_input', err.message);
+            case 'SEARCH_PROVIDER_TIMEOUT':
+                throw new HubError('timeout', 'The search provider did not answer in time');
+            case 'SEARCH_PROVIDER_AUTH_ERROR':
+                log?.warn('search provider rejected the configured key', { provider: 'serper' });
+                throw new HubError('upstream_unavailable', 'The search provider rejected the configured key');
+            case 'INTERNAL_ERROR':
+                throw new HubError('internal', 'Search failed');
+            default:
+                throw new HubError('upstream_unavailable', 'The search provider is unavailable', { provider: 'serper', code: err.code });
+        }
+    }
+    if (err?.name === 'AbortError')
+        throw new HubError('timeout', 'The search was cancelled');
+    throw new HubError('upstream_unavailable', 'The search provider is unavailable', { provider: 'serper' });
+}
+/** Serper (Google results): web through `@x12i/search`, news through Serper's news endpoint (which `@x12i/search` does not cover). */
+export function serperSearchClient(options) {
+    const newsTransport = options.newsTransport ?? serperNewsTransport(options.apiKey ?? '', options.timeoutMs ?? 15_000);
+    const provider = options.provider ??
+        createSerperProvider({
+            apiKey: options.apiKey ?? '',
+            baseUrl: 'https://google.serper.dev',
+            timeoutMs: options.timeoutMs ?? 15_000,
+            maxRetries: 1,
+            defaultNum: 10,
+            maxNum: MAX_RESULTS,
+            includeRawByDefault: false,
+            enforceSafeSearch: true,
+        });
+    return {
+        async search(req) {
+            if (req.kind === 'news')
+                return serperNews(req, newsTransport, options.log);
+            let res;
+            try {
+                res = await serperSearch({
+                    query: req.query,
+                    limit: clampLimit(req.limit),
+                    country: req.country,
+                    language: req.language,
+                    timeRange: req.timeRange,
+                    safeSearch: 'active',
+                    includeRawProviderResponse: false,
+                }, { provider: provider ?? null, signal: req.signal });
+            }
+            catch (err) {
+                serperError(err, options.log);
+            }
+            return {
+                provider: 'serper',
+                query: req.query,
+                results: res.organic.map((r) => ({
+                    position: r.position,
+                    title: r.title,
+                    url: r.url,
+                    domain: r.domain || domainOf(r.url),
+                    ...(r.snippet ? { snippet: r.snippet } : {}),
+                    ...(r.dateText ? { date: r.dateText } : {}),
+                })),
+                ...(res.answerBox?.answer ? { answer: res.answerBox.answer } : {}),
+            };
+        },
+    };
+}
+function tavilyError(result, log) {
+    const code = result.error?.code;
+    if (code === 'INVALID_REQUEST')
+        throw new HubError('invalid_input', result.error?.message ?? 'Invalid search request');
+    if (code === 'PROVIDER_TIMEOUT')
+        throw new HubError('timeout', 'The search provider did not answer in time');
+    if (code === 'MISSING_API_KEY') {
+        log?.warn('tavily key missing at call time', { provider: 'tavily' });
+        throw new HubError('service_not_connected', 'Web search provider is not connected on this server', { service: 'search', docs: 'docs/ENV.md#search' });
+    }
+    throw new HubError('upstream_unavailable', 'The search provider is unavailable', { provider: 'tavily', code });
+}
+/** Tavily through `@x12i/search-adapter`. Its page-fetch stage stays off: caller URLs only go through `@x12i/api-hub-safe-fetch`. */
+export function tavilySearchClient(options) {
+    const adapter = options.adapter ??
+        createSearchAdapter({
+            includeSourceSnippets: true,
+            tavily: { apiKey: options.apiKey, timeoutMs: options.timeoutMs ?? 15_000, maxRetries: 1, includeAnswer: false },
+            fetch: { enabled: false },
+        });
+    return {
+        async search(req) {
+            let result;
+            try {
+                result = await adapter.search({
+                    query: req.query,
+                    topic: req.kind === 'news' ? 'news' : 'general',
+                    maxResults: clampLimit(req.limit),
+                    includeAnswer: false,
+                    fetchPages: false,
+                    ...(req.timeRange ? { days: DAYS[req.timeRange] } : {}),
+                });
+            }
+            catch {
+                throw new HubError('upstream_unavailable', 'The search provider is unavailable', { provider: 'tavily' });
+            }
+            if (!result.ok)
+                tavilyError(result, options.log);
+            return {
+                provider: 'tavily',
+                query: req.query,
+                results: result.discoveredSources.map((s, i) => ({
+                    position: s.rank ?? i + 1,
+                    title: s.title ?? s.url,
+                    url: s.url,
+                    domain: s.domain ?? domainOf(s.url),
+                    ...(s.snippet ? { snippet: s.snippet } : {}),
+                    ...(s.publishedAt ? { date: s.publishedAt } : {}),
+                })),
+            };
+        },
+    };
+}
+/** Serper when `SERPER_API_KEY` is set, else Tavily when `TAVILY_API_KEY` is set, else the stub (`service_not_connected`). */
+export function createSearchFromEnv(env = process.env, log) {
+    if (env.SERPER_API_KEY?.trim())
+        return serperSearchClient({ apiKey: env.SERPER_API_KEY.trim(), log });
+    if (env.TAVILY_API_KEY?.trim())
+        return tavilySearchClient({ apiKey: env.TAVILY_API_KEY.trim(), log });
+    return stubSearch;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/search/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  HubError,\n  stubSearch,\n  type Logger,\n  type WebSearch,\n  type WebSearchRequest,\n  type WebSearchResponse,\n  type WebSearchResult,\n} from '@x12i/api-hub-core';\nimport { createSerperProvider, search as serperSearch, SearchError, type SearchProvider } from '@x12i/search';\nimport { createSearchAdapter, type SearchAdapter, type SearchResult as TavilyResult } from '@x12i/search-adapter';\nimport { request } from 'undici';\n\nexport const MAX_RESULTS = 20;\n\nconst DAYS = { day: 1, week: 7, month: 31, year: 365 } as const;\n\nexport const SERPER_NEWS_URL = 'https://google.serper.dev/news';\nconst SERPER_NEWS_MAX_BYTES = 2 * 1024 * 1024;\n\n/** A news result; `source` is the publisher name when the provider reports one. */\nexport interface NewsSearchResult extends WebSearchResult {\n  source?: string;\n}\n\n/** One POST to Serper's news endpoint. Injectable so tests never reach the network. */\nexport type SerperNewsTransport = (body: Record<string, unknown>, signal: AbortSignal) => Promise<{ status: number; data: unknown }>;\n\nfunction serperNewsTransport(apiKey: string, timeoutMs: number): SerperNewsTransport {\n  return async (body, signal) => {\n    const res = await request(SERPER_NEWS_URL, {\n      method: 'POST',\n      headers: { 'x-api-key': apiKey, 'content-type': 'application/json' },\n      body: JSON.stringify(body),\n      signal: AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]),\n    });\n    const length = Number(res.headers['content-length'] ?? 0);\n    if (length > SERPER_NEWS_MAX_BYTES) {\n      await res.body.dump();\n      return { status: 502, data: null };\n    }\n    const text = await res.body.text();\n    try {\n      return { status: res.statusCode, data: text.length <= SERPER_NEWS_MAX_BYTES ? (JSON.parse(text) as unknown) : null };\n    } catch {\n      return { status: res.statusCode, data: null };\n    }\n  };\n}\n\ninterface SerperNewsItem {\n  title?: unknown;\n  link?: unknown;\n  snippet?: unknown;\n  date?: unknown;\n  source?: unknown;\n  position?: unknown;\n}\n\nconst nonEmpty = (v: unknown) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);\n\nexport function mapSerperNews(data: unknown, limit: number): NewsSearchResult[] {\n  const items = (data as { news?: unknown } | null)?.news;\n  if (!Array.isArray(items)) throw new HubError('upstream_unavailable', 'The search provider returned an unusable response', { provider: 'serper' });\n  const results: NewsSearchResult[] = [];\n  for (const raw of items as SerperNewsItem[]) {\n    const title = nonEmpty(raw?.title);\n    const link = nonEmpty(raw?.link);\n    if (!title || !link || !/^https?:\\/\\//i.test(link)) continue;\n    const snippet = nonEmpty(raw.snippet);\n    const date = nonEmpty(raw.date);\n    const source = nonEmpty(raw.source);\n    results.push({\n      position: typeof raw.position === 'number' && raw.position > 0 ? raw.position : results.length + 1,\n      title,\n      url: link,\n      domain: domainOf(link),\n      ...(snippet ? { snippet } : {}),\n      ...(date ? { date } : {}),\n      ...(source ? { source } : {}),\n    });\n    if (results.length === limit) break;\n  }\n  return results;\n}\n\nasync function serperNews(req: WebSearchRequest, transport: SerperNewsTransport, log?: Logger): Promise<WebSearchResponse> {\n  const limit = clampLimit(req.limit);\n  const body: Record<string, unknown> = { q: req.query, num: limit };\n  if (req.country) body.gl = req.country;\n  if (req.language) body.hl = req.language;\n  if (req.timeRange) body.tbs = `qdr:${req.timeRange[0]}`;\n  let res;\n  try {\n    res = await transport(body, req.signal ?? new AbortController().signal);\n  } catch (err) {\n    if (req.signal?.aborted) throw new HubError('timeout', 'The search was cancelled');\n    const name = (err as Error)?.name;\n    if (name === 'TimeoutError' || name === 'AbortError') throw new HubError('timeout', 'The search provider did not answer in time');\n    throw new HubError('upstream_unavailable', 'The search provider is unavailable', { provider: 'serper' });\n  }\n  if (res.status === 401 || res.status === 403) {\n    log?.warn('search provider rejected the configured key', { provider: 'serper' });\n    throw new HubError('upstream_unavailable', 'The search provider rejected the configured key');\n  }\n  if (res.status >= 400) throw new HubError('upstream_unavailable', 'The search provider is unavailable', { provider: 'serper', status: res.status });\n  return { provider: 'serper', query: req.query, results: mapSerperNews(res.data, limit) };\n}\n\nfunction domainOf(url: string): string {\n  try {\n    return new URL(url).hostname.replace(/^www\\./, '');\n  } catch {\n    return '';\n  }\n}\n\nfunction clampLimit(limit: number | undefined): number {\n  return Math.min(Math.max(Math.trunc(limit ?? 10), 1), MAX_RESULTS);\n}\n\nfunction serperError(err: unknown, log?: Logger): never {\n  if (err instanceof HubError) throw err;\n  if (err instanceof SearchError) {\n    switch (err.code) {\n      case 'INVALID_SEARCH_REQUEST':\n        throw new HubError('invalid_input', err.message);\n      case 'SEARCH_PROVIDER_TIMEOUT':\n        throw new HubError('timeout', 'The search provider did not answer in time');\n      case 'SEARCH_PROVIDER_AUTH_ERROR':\n        log?.warn('search provider rejected the configured key', { provider: 'serper' });\n        throw new HubError('upstream_unavailable', 'The search provider rejected the configured key');\n      case 'INTERNAL_ERROR':\n        throw new HubError('internal', 'Search failed');\n      default:\n        throw new HubError('upstream_unavailable', 'The search provider is unavailable', { provider: 'serper', code: err.code });\n    }\n  }\n  if ((err as Error)?.name === 'AbortError') throw new HubError('timeout', 'The search was cancelled');\n  throw new HubError('upstream_unavailable', 'The search provider is unavailable', { provider: 'serper' });\n}\n\n/** Serper (Google results): web through `@x12i/search`, news through Serper's news endpoint (which `@x12i/search` does not cover). */\nexport function serperSearchClient(options: {\n  apiKey?: string;\n  provider?: SearchProvider;\n  newsTransport?: SerperNewsTransport;\n  log?: Logger;\n  timeoutMs?: number;\n}): WebSearch {\n  const newsTransport = options.newsTransport ?? serperNewsTransport(options.apiKey ?? '', options.timeoutMs ?? 15_000);\n  const provider =\n    options.provider ??\n    createSerperProvider({\n      apiKey: options.apiKey ?? '',\n      baseUrl: 'https://google.serper.dev',\n      timeoutMs: options.timeoutMs ?? 15_000,\n      maxRetries: 1,\n      defaultNum: 10,\n      maxNum: MAX_RESULTS,\n      includeRawByDefault: false,\n      enforceSafeSearch: true,\n    });\n  return {\n    async search(req: WebSearchRequest): Promise<WebSearchResponse> {\n      if (req.kind === 'news') return serperNews(req, newsTransport, options.log);\n      let res;\n      try {\n        res = await serperSearch(\n          {\n            query: req.query,\n            limit: clampLimit(req.limit),\n            country: req.country,\n            language: req.language,\n            timeRange: req.timeRange,\n            safeSearch: 'active',\n            includeRawProviderResponse: false,\n          },\n          { provider: provider ?? null, signal: req.signal },\n        );\n      } catch (err) {\n        serperError(err, options.log);\n      }\n      return {\n        provider: 'serper',\n        query: req.query,\n        results: res.organic.map((r) => ({\n          position: r.position,\n          title: r.title,\n          url: r.url,\n          domain: r.domain || domainOf(r.url),\n          ...(r.snippet ? { snippet: r.snippet } : {}),\n          ...(r.dateText ? { date: r.dateText } : {}),\n        })),\n        ...(res.answerBox?.answer ? { answer: res.answerBox.answer } : {}),\n      };\n    },\n  };\n}\n\nfunction tavilyError(result: TavilyResult, log?: Logger): never {\n  const code = result.error?.code;\n  if (code === 'INVALID_REQUEST') throw new HubError('invalid_input', result.error?.message ?? 'Invalid search request');\n  if (code === 'PROVIDER_TIMEOUT') throw new HubError('timeout', 'The search provider did not answer in time');\n  if (code === 'MISSING_API_KEY') {\n    log?.warn('tavily key missing at call time', { provider: 'tavily' });\n    throw new HubError('service_not_connected', 'Web search provider is not connected on this server', { service: 'search', docs: 'docs/ENV.md#search' });\n  }\n  throw new HubError('upstream_unavailable', 'The search provider is unavailable', { provider: 'tavily', code });\n}\n\n/** Tavily through `@x12i/search-adapter`. Its page-fetch stage stays off: caller URLs only go through `@x12i/api-hub-safe-fetch`. */\nexport function tavilySearchClient(options: { apiKey?: string; adapter?: SearchAdapter; log?: Logger; timeoutMs?: number }): WebSearch {\n  const adapter =\n    options.adapter ??\n    createSearchAdapter({\n      includeSourceSnippets: true,\n      tavily: { apiKey: options.apiKey, timeoutMs: options.timeoutMs ?? 15_000, maxRetries: 1, includeAnswer: false },\n      fetch: { enabled: false },\n    });\n  return {\n    async search(req: WebSearchRequest): Promise<WebSearchResponse> {\n      let result: TavilyResult;\n      try {\n        result = await adapter.search({\n          query: req.query,\n          topic: req.kind === 'news' ? 'news' : 'general',\n          maxResults: clampLimit(req.limit),\n          includeAnswer: false,\n          fetchPages: false,\n          ...(req.timeRange ? { days: DAYS[req.timeRange] } : {}),\n        });\n      } catch {\n        throw new HubError('upstream_unavailable', 'The search provider is unavailable', { provider: 'tavily' });\n      }\n      if (!result.ok) tavilyError(result, options.log);\n      return {\n        provider: 'tavily',\n        query: req.query,\n        results: result.discoveredSources.map((s, i) => ({\n          position: s.rank ?? i + 1,\n          title: s.title ?? s.url,\n          url: s.url,\n          domain: s.domain ?? domainOf(s.url),\n          ...(s.snippet ? { snippet: s.snippet } : {}),\n          ...(s.publishedAt ? { date: s.publishedAt } : {}),\n        })),\n      };\n    },\n  };\n}\n\n/** Serper when `SERPER_API_KEY` is set, else Tavily when `TAVILY_API_KEY` is set, else the stub (`service_not_connected`). */\nexport function createSearchFromEnv(env: NodeJS.ProcessEnv = process.env, log?: Logger): WebSearch {\n  if (env.SERPER_API_KEY?.trim()) return serperSearchClient({ apiKey: env.SERPER_API_KEY.trim(), log });\n  if (env.TAVILY_API_KEY?.trim()) return tavilySearchClient({ apiKey: env.TAVILY_API_KEY.trim(), log });\n  return stubSearch;\n}\n"]}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@x12i/api-hub-search",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Web search client for the x12i API hub",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x12i/apis-hub.git",
+    "directory": "packages/search"
+  },
+  "bugs": {
+    "url": "https://github.com/x12i/apis-hub/issues"
+  },
+  "homepage": "https://github.com/x12i/apis-hub",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@x12i/api-hub-core": "0.1.0",
+    "@x12i/search": "0.4.0",
+    "@x12i/search-adapter": "1.5.1",
+    "undici": "8.12.3"
+  }
+}