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

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+[build:web-research-searxng] found 2 entry points
+[build:web-research-searxng] 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-searxng',
+  entryPoints: 'src/**/*.ts',
+})

package/dist/adapter.js

@@ -0,0 +1,128 @@
+import {
+  CONTRACT_VERSION,
+  READY,
+  defineAdapterModule,
+  notReady,
+  searchOk,
+  stripTrailingSlashes,
+  toOutcomeFailure
+} from "@open-mercato/web-research";
+import { z } from "zod";
+const searxngOptionsSchema = z.object({
+  baseUrl: z.url().optional(),
+  /** SearXNG engine names to restrict the query to, e.g. ["duckduckgo","brave"]. */
+  engines: z.array(z.string().min(1)).optional(),
+  language: z.string().min(2).max(16).optional(),
+  timeoutMs: z.number().int().min(1e3).max(12e4).optional()
+});
+const DEFAULT_TIMEOUT_MS = 12e3;
+const responseSchema = z.object({
+  results: z.array(
+    z.object({
+      url: z.string().nullish(),
+      title: z.string().nullish(),
+      content: z.string().nullish(),
+      score: z.number().nullish(),
+      publishedDate: z.string().nullish()
+    })
+  ).nullish()
+});
+const TIME_RANGE = {
+  day: "day",
+  week: "week",
+  month: "month",
+  year: "year"
+};
+function parseJson(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+function createSearxngAdapter(options) {
+  const baseUrl = options.baseUrl ? stripTrailingSlashes(options.baseUrl) : "";
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return {
+    id: "searxng",
+    kind: "serp",
+    capabilities: {
+      search: true,
+      fetch: false,
+      snippets: true,
+      content: false,
+      freshness: true,
+      siteFilter: true,
+      cost: "free"
+    },
+    /** `free` — pings /healthz on infrastructure the tenant runs itself. */
+    probeCost: "free",
+    readiness: () => baseUrl.length > 0 ? READY : notReady("SearXNG base URL is not set"),
+    async search(request, context) {
+      if (baseUrl.length === 0) return { status: "unavailable", reason: "SearXNG base URL is not set" };
+      try {
+        const url = new URL(`${baseUrl}/search`);
+        url.searchParams.set("q", request.site ? `${request.query} site:${request.site}` : request.query);
+        url.searchParams.set("format", "json");
+        if (options.engines?.length) url.searchParams.set("engines", options.engines.join(","));
+        if (options.language ?? request.locale) {
+          url.searchParams.set("language", options.language ?? request.locale);
+        }
+        if (request.freshness && TIME_RANGE[request.freshness]) {
+          url.searchParams.set("time_range", TIME_RANGE[request.freshness]);
+        }
+        const response = await context.http.request(url.toString(), {
+          accept: ["application/json"],
+          timeoutMs,
+          signal: context.signal
+        });
+        const parsed = responseSchema.safeParse(parseJson(response.body));
+        if (!parsed.success) {
+          return {
+            status: "error",
+            reason: "SearXNG returned an unrecognized response shape (is the JSON format enabled?)",
+            retriable: false
+          };
+        }
+        const results = [];
+        for (const item of parsed.data.results ?? []) {
+          if (!item.url) continue;
+          results.push({
+            url: item.url,
+            title: item.title ?? null,
+            snippet: item.content ?? null,
+            publishedAt: item.publishedDate ?? null,
+            score: item.score ?? null
+          });
+          if (results.length >= request.limit) break;
+        }
+        context.report("ok", `SearXNG returned ${results.length} result(s)`, { resultCount: results.length });
+        return searchOk(results);
+      } catch (error) {
+        return toOutcomeFailure(error);
+      }
+    },
+    async healthCheck(context) {
+      if (baseUrl.length === 0) return { ok: false, detail: "SearXNG base URL is not set" };
+      try {
+        await context.http.request(`${baseUrl}/healthz`, { timeoutMs, signal: context.signal });
+        return { ok: true };
+      } catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+      }
+    }
+  };
+}
+const searxngAdapterModule = defineAdapterModule({
+  id: "searxng",
+  kind: "serp",
+  contractVersion: CONTRACT_VERSION,
+  optionsSchema: searxngOptionsSchema,
+  createAdapter: createSearxngAdapter
+});
+export {
+  createSearxngAdapter,
+  searxngAdapterModule,
+  searxngOptionsSchema
+};
+//# 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\n/**\n * Client for an operator's OWN SearXNG instance. Only the client ships here \u2014\n * SearXNG is AGPL-3.0, so calling one over HTTP is fine but bundling the server\n * would be distribution.\n */\nexport const searxngOptionsSchema = z.object({\n  baseUrl: z.url().optional(),\n  /** SearXNG engine names to restrict the query to, e.g. [\"duckduckgo\",\"brave\"]. */\n  engines: z.array(z.string().min(1)).optional(),\n  language: z.string().min(2).max(16).optional(),\n  timeoutMs: z.number().int().min(1000).max(120_000).optional(),\n})\n\nexport type SearxngOptions = z.infer<typeof searxngOptionsSchema>\n\nconst DEFAULT_TIMEOUT_MS = 12_000\n\nconst responseSchema = z.object({\n  results: z\n    .array(\n      z.object({\n        url: z.string().nullish(),\n        title: z.string().nullish(),\n        content: z.string().nullish(),\n        score: z.number().nullish(),\n        publishedDate: z.string().nullish(),\n      }),\n    )\n    .nullish(),\n})\n\nconst TIME_RANGE: Readonly<Record<string, string>> = {\n  day: 'day',\n  week: 'week',\n  month: 'month',\n  year: 'year',\n}\n\nfunction parseJson(body: string): unknown {\n  try {\n    return JSON.parse(body)\n  } catch {\n    return null\n  }\n}\n\nexport function createSearxngAdapter(options: SearxngOptions): SearchAdapter {\n  const baseUrl = options.baseUrl ? stripTrailingSlashes(options.baseUrl) : ''\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS\n\n  return {\n    id: 'searxng',\n    kind: 'serp',\n    capabilities: {\n      search: true,\n      fetch: false,\n      snippets: true,\n      content: false,\n      freshness: true,\n      siteFilter: true,\n      cost: 'free',\n    },\n    /** `free` \u2014 pings /healthz on infrastructure the tenant runs itself. */\n    probeCost: 'free' as const,\n    readiness: () => (baseUrl.length > 0 ? READY : notReady('SearXNG base URL is not set')),\n\n    async search(request, context): Promise<SearchOutcome> {\n      if (baseUrl.length === 0) return { status: 'unavailable', reason: 'SearXNG base URL is not set' }\n      try {\n        const url = new URL(`${baseUrl}/search`)\n        url.searchParams.set('q', request.site ? `${request.query} site:${request.site}` : request.query)\n        url.searchParams.set('format', 'json')\n        if (options.engines?.length) url.searchParams.set('engines', options.engines.join(','))\n        if (options.language ?? request.locale) {\n          url.searchParams.set('language', options.language ?? (request.locale as string))\n        }\n        if (request.freshness && TIME_RANGE[request.freshness]) {\n          url.searchParams.set('time_range', TIME_RANGE[request.freshness])\n        }\n\n        const response = await context.http.request(url.toString(), {\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 {\n            status: 'error',\n            reason: 'SearXNG returned an unrecognized response shape (is the JSON format enabled?)',\n            retriable: false,\n          }\n        }\n        const results: RawResult[] = []\n        for (const item of parsed.data.results ?? []) {\n          if (!item.url) continue\n          results.push({\n            url: item.url,\n            title: item.title ?? null,\n            snippet: item.content ?? null,\n            publishedAt: item.publishedDate ?? null,\n            score: item.score ?? null,\n          })\n          if (results.length >= request.limit) break\n        }\n        context.report('ok', `SearXNG returned ${results.length} result(s)`, { resultCount: results.length })\n        return searchOk(results)\n      } catch (error) {\n        return toOutcomeFailure(error)\n      }\n    },\n\n    async healthCheck(context) {\n      if (baseUrl.length === 0) return { ok: false, detail: 'SearXNG base URL is not set' }\n      try {\n        await context.http.request(`${baseUrl}/healthz`, { timeoutMs, signal: context.signal })\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 searxngAdapterModule = defineAdapterModule({\n  id: 'searxng',\n  kind: 'serp',\n  contractVersion: CONTRACT_VERSION,\n  optionsSchema: searxngOptionsSchema,\n  createAdapter: createSearxngAdapter,\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/index.js

@@ -0,0 +1,13 @@
+import {
+  createSearxngAdapter,
+  searxngAdapterModule,
+  searxngOptionsSchema
+} from "./adapter.js";
+import { searxngAdapterModule as searxngAdapterModule2 } from "./adapter.js";
+export {
+  createSearxngAdapter,
+  searxngAdapterModule2 as default,
+  searxngAdapterModule,
+  searxngOptionsSchema
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["export {\n  createSearxngAdapter,\n  searxngAdapterModule,\n  searxngOptionsSchema,\n  type SearxngOptions,\n} from './adapter'\n\nexport { searxngAdapterModule as default } from './adapter'\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AAEP,SAAiC,wBAAxBA,6BAAuC;",
+  "names": ["searxngAdapterModule"]
+}

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-searxng",
+  "version": "0.7.1-develop.7194.1.ab4fc81f82",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "openMercato": {
+    "webResearchAdapter": {
+      "id": "searxng"
+    }
+  },
+  "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-searxng"
+  },
+  "stableVersion": "0.7.0"
+}

package/src/__tests__/searxng.test.ts

@@ -0,0 +1,75 @@
+import { createStubHttpClient, createTestContext, describeAdapterContract } from '@open-mercato/web-research/testing'
+import { createSearxngAdapter, searxngAdapterModule } from '../adapter'
+
+const BODY = JSON.stringify({
+  results: [
+    { url: 'https://a.com/1', title: 'Alpha', content: 'Alpha snippet', score: 3.2 },
+    { title: 'No url here', content: 'skipped' },
+    { url: 'https://b.com/2', title: 'Beta', content: 'Beta snippet' },
+  ],
+})
+
+const BASE = { baseUrl: 'https://searx.internal' }
+
+describe('searxng adapter', () => {
+  it('is unavailable without a base URL and makes no call', async () => {
+    const http = createStubHttpClient(() => ({ body: BODY }))
+    const outcome = await createSearxngAdapter({}).search({ query: 'x', limit: 5 }, createTestContext({ http }))
+    expect(outcome).toMatchObject({ status: 'unavailable' })
+    expect(http.calls).toHaveLength(0)
+  })
+
+  it('maps results and skips entries without a url', async () => {
+    const http = createStubHttpClient(() => ({ body: BODY }))
+    const outcome = await createSearxngAdapter(BASE).search(
+      { query: 'x', limit: 5 },
+      createTestContext({ http }),
+    )
+    expect(outcome.status).toBe('ok')
+    if (outcome.status !== 'ok') return
+    expect(outcome.results.map((result) => result.url)).toEqual(['https://a.com/1', 'https://b.com/2'])
+  })
+
+  it('asks for JSON and passes engines, language and freshness through', async () => {
+    const http = createStubHttpClient(() => ({ body: BODY }))
+    await createSearxngAdapter({ ...BASE, engines: ['duckduckgo', 'brave'], language: 'en' }).search(
+      { query: 'pricing', limit: 5, site: 'example.com', freshness: 'week' },
+      createTestContext({ http }),
+    )
+    const requested = decodeURIComponent(http.calls[0])
+    expect(requested).toContain('format=json')
+    expect(requested).toContain('engines=duckduckgo,brave')
+    expect(requested).toContain('language=en')
+    expect(requested).toContain('time_range=week')
+    expect(requested).toContain('site:example.com')
+  })
+
+  it('explains an unparseable payload as a likely JSON-format problem', async () => {
+    const http = createStubHttpClient(() => ({ body: '<html>not json</html>' }))
+    const outcome = await createSearxngAdapter(BASE).search(
+      { query: 'x', limit: 5 },
+      createTestContext({ http }),
+    )
+    expect(outcome).toMatchObject({ status: 'error' })
+    if (outcome.status === 'error') expect(outcome.reason).toContain('JSON format')
+  })
+
+  it('respects the requested limit', async () => {
+    const http = createStubHttpClient(() => ({ body: BODY }))
+    const outcome = await createSearxngAdapter(BASE).search(
+      { query: 'x', limit: 1 },
+      createTestContext({ http }),
+    )
+    expect(outcome.status === 'ok' && outcome.results).toHaveLength(1)
+  })
+})
+
+describeAdapterContract(
+  searxngAdapterModule,
+  {
+    unconfiguredOptions: {},
+    configuredOptions: BASE,
+    context: () => createTestContext({ http: createStubHttpClient(() => ({ body: BODY })) }),
+  },
+  { describe, it, expect: expect as never },
+)

package/src/adapter.ts

@@ -0,0 +1,145 @@
+import {
+  CONTRACT_VERSION,
+  READY,
+  defineAdapterModule,
+  notReady,
+  searchOk,
+  stripTrailingSlashes,
+  toOutcomeFailure,
+  type RawResult,
+  type SearchAdapter,
+  type SearchOutcome,
+} from '@open-mercato/web-research'
+import { z } from 'zod'
+
+/**
+ * Client for an operator's OWN SearXNG instance. Only the client ships here —
+ * SearXNG is AGPL-3.0, so calling one over HTTP is fine but bundling the server
+ * would be distribution.
+ */
+export const searxngOptionsSchema = z.object({
+  baseUrl: z.url().optional(),
+  /** SearXNG engine names to restrict the query to, e.g. ["duckduckgo","brave"]. */
+  engines: z.array(z.string().min(1)).optional(),
+  language: z.string().min(2).max(16).optional(),
+  timeoutMs: z.number().int().min(1000).max(120_000).optional(),
+})
+
+export type SearxngOptions = z.infer<typeof searxngOptionsSchema>
+
+const DEFAULT_TIMEOUT_MS = 12_000
+
+const responseSchema = z.object({
+  results: z
+    .array(
+      z.object({
+        url: z.string().nullish(),
+        title: z.string().nullish(),
+        content: z.string().nullish(),
+        score: z.number().nullish(),
+        publishedDate: z.string().nullish(),
+      }),
+    )
+    .nullish(),
+})
+
+const TIME_RANGE: Readonly<Record<string, string>> = {
+  day: 'day',
+  week: 'week',
+  month: 'month',
+  year: 'year',
+}
+
+function parseJson(body: string): unknown {
+  try {
+    return JSON.parse(body)
+  } catch {
+    return null
+  }
+}
+
+export function createSearxngAdapter(options: SearxngOptions): SearchAdapter {
+  const baseUrl = options.baseUrl ? stripTrailingSlashes(options.baseUrl) : ''
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+
+  return {
+    id: 'searxng',
+    kind: 'serp',
+    capabilities: {
+      search: true,
+      fetch: false,
+      snippets: true,
+      content: false,
+      freshness: true,
+      siteFilter: true,
+      cost: 'free',
+    },
+    /** `free` — pings /healthz on infrastructure the tenant runs itself. */
+    probeCost: 'free' as const,
+    readiness: () => (baseUrl.length > 0 ? READY : notReady('SearXNG base URL is not set')),
+
+    async search(request, context): Promise<SearchOutcome> {
+      if (baseUrl.length === 0) return { status: 'unavailable', reason: 'SearXNG base URL is not set' }
+      try {
+        const url = new URL(`${baseUrl}/search`)
+        url.searchParams.set('q', request.site ? `${request.query} site:${request.site}` : request.query)
+        url.searchParams.set('format', 'json')
+        if (options.engines?.length) url.searchParams.set('engines', options.engines.join(','))
+        if (options.language ?? request.locale) {
+          url.searchParams.set('language', options.language ?? (request.locale as string))
+        }
+        if (request.freshness && TIME_RANGE[request.freshness]) {
+          url.searchParams.set('time_range', TIME_RANGE[request.freshness])
+        }
+
+        const response = await context.http.request(url.toString(), {
+          accept: ['application/json'],
+          timeoutMs,
+          signal: context.signal,
+        })
+        const parsed = responseSchema.safeParse(parseJson(response.body))
+        if (!parsed.success) {
+          return {
+            status: 'error',
+            reason: 'SearXNG returned an unrecognized response shape (is the JSON format enabled?)',
+            retriable: false,
+          }
+        }
+        const results: RawResult[] = []
+        for (const item of parsed.data.results ?? []) {
+          if (!item.url) continue
+          results.push({
+            url: item.url,
+            title: item.title ?? null,
+            snippet: item.content ?? null,
+            publishedAt: item.publishedDate ?? null,
+            score: item.score ?? null,
+          })
+          if (results.length >= request.limit) break
+        }
+        context.report('ok', `SearXNG returned ${results.length} result(s)`, { resultCount: results.length })
+        return searchOk(results)
+      } catch (error) {
+        return toOutcomeFailure(error)
+      }
+    },
+
+    async healthCheck(context) {
+      if (baseUrl.length === 0) return { ok: false, detail: 'SearXNG base URL is not set' }
+      try {
+        await context.http.request(`${baseUrl}/healthz`, { timeoutMs, signal: context.signal })
+        return { ok: true }
+      } catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) }
+      }
+    },
+  }
+}
+
+export const searxngAdapterModule = defineAdapterModule({
+  id: 'searxng',
+  kind: 'serp',
+  contractVersion: CONTRACT_VERSION,
+  optionsSchema: searxngOptionsSchema,
+  createAdapter: createSearxngAdapter,
+})

package/src/index.ts

@@ -0,0 +1,8 @@
+export {
+  createSearxngAdapter,
+  searxngAdapterModule,
+  searxngOptionsSchema,
+  type SearxngOptions,
+} from './adapter'
+
+export { searxngAdapterModule 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)