@openclaw/brave-plugin 2026.5.1-beta.1

package/src/brave-web-search-provider.test.ts

@@ -0,0 +1,193 @@
+import fs from "node:fs";
+import { validateJsonSchemaValue } from "openclaw/plugin-sdk/config-schema";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { __testing } from "../test-api.js";
+import { createBraveWebSearchProvider } from "./brave-web-search-provider.js";
+
+const braveManifest = JSON.parse(
+  fs.readFileSync(new URL("../openclaw.plugin.json", import.meta.url), "utf-8"),
+) as {
+  configSchema?: Record<string, unknown>;
+};
+
+describe("brave web search provider", () => {
+  const priorFetch = global.fetch;
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    global.fetch = priorFetch;
+  });
+
+  it("normalizes brave language parameters and swaps reversed ui/search inputs", () => {
+    expect(
+      __testing.normalizeBraveLanguageParams({
+        search_lang: "en-US",
+        ui_lang: "ja",
+      }),
+    ).toEqual({
+      search_lang: "jp",
+      ui_lang: "en-US",
+    });
+    expect(__testing.normalizeBraveLanguageParams({ search_lang: "tr-TR", ui_lang: "tr" })).toEqual(
+      {
+        search_lang: "tr",
+        ui_lang: "tr-TR",
+      },
+    );
+    expect(__testing.normalizeBraveLanguageParams({ search_lang: "EN", ui_lang: "en-us" })).toEqual(
+      {
+        search_lang: "en",
+        ui_lang: "en-US",
+      },
+    );
+  });
+
+  it("flags invalid brave language fields", () => {
+    expect(
+      __testing.normalizeBraveLanguageParams({
+        search_lang: "xx",
+      }),
+    ).toEqual({ invalidField: "search_lang" });
+    expect(__testing.normalizeBraveLanguageParams({ search_lang: "en-US" })).toEqual({
+      invalidField: "search_lang",
+    });
+    expect(__testing.normalizeBraveLanguageParams({ ui_lang: "en" })).toEqual({
+      invalidField: "ui_lang",
+    });
+  });
+
+  it("normalizes Brave country codes and falls back unsupported values to ALL", () => {
+    expect(__testing.normalizeBraveCountry("de")).toBe("DE");
+    expect(__testing.normalizeBraveCountry(" VN ")).toBe("ALL");
+    expect(__testing.normalizeBraveCountry("")).toBeUndefined();
+  });
+
+  it("defaults brave mode to web unless llm-context is explicitly selected", () => {
+    expect(__testing.resolveBraveMode()).toBe("web");
+    expect(__testing.resolveBraveMode({ mode: "llm-context" })).toBe("llm-context");
+  });
+
+  it("accepts llm-context in the Brave plugin config schema", () => {
+    if (!braveManifest.configSchema) {
+      throw new Error("Expected Brave manifest config schema");
+    }
+
+    const result = validateJsonSchemaValue({
+      schema: braveManifest.configSchema,
+      cacheKey: "test:brave-config-schema",
+      value: {
+        webSearch: {
+          mode: "llm-context",
+        },
+      },
+    });
+
+    expect(result.ok).toBe(true);
+  });
+
+  it("rejects invalid Brave mode values in the plugin config schema", () => {
+    if (!braveManifest.configSchema) {
+      throw new Error("Expected Brave manifest config schema");
+    }
+
+    const result = validateJsonSchemaValue({
+      schema: braveManifest.configSchema,
+      cacheKey: "test:brave-config-schema",
+      value: {
+        webSearch: {
+          mode: "invalid-mode",
+        },
+      },
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({
+        path: "webSearch.mode",
+        allowedValues: ["web", "llm-context"],
+      }),
+    );
+  });
+
+  it("maps llm-context results into wrapped source entries", () => {
+    expect(
+      __testing.mapBraveLlmContextResults({
+        grounding: {
+          generic: [
+            {
+              url: "https://example.com/post",
+              title: "Example",
+              snippets: ["a", "", "b"],
+            },
+          ],
+        },
+      }),
+    ).toEqual([
+      {
+        url: "https://example.com/post",
+        title: "Example",
+        snippets: ["a", "b"],
+        siteName: "example.com",
+      },
+    ]);
+  });
+
+  it("returns validation errors for invalid date ranges", async () => {
+    vi.stubEnv("BRAVE_API_KEY", "");
+    const provider = createBraveWebSearchProvider();
+    const tool = provider.createTool({
+      config: {},
+      searchConfig: {
+        apiKey: "BSA...",
+        brave: { apiKey: "BSA..." },
+      },
+    });
+    if (!tool) {
+      throw new Error("Expected tool definition");
+    }
+
+    const result = await tool.execute({
+      query: "latest gpu news",
+      date_after: "2026-03-20",
+      date_before: "2026-03-01",
+    });
+
+    expect(result).toMatchObject({
+      error: "invalid_date_range",
+    });
+  });
+
+  it("falls back unsupported country values before calling Brave", async () => {
+    vi.stubEnv("BRAVE_API_KEY", "test-key");
+    const mockFetch = vi.fn(async (_input?: unknown, _init?: unknown) => {
+      return {
+        ok: true,
+        json: async () => ({ web: { results: [] } }),
+      } as Response;
+    });
+    global.fetch = mockFetch as typeof global.fetch;
+
+    const provider = createBraveWebSearchProvider();
+    const tool = provider.createTool({
+      config: {},
+      searchConfig: {
+        apiKey: "BSA...",
+        brave: { apiKey: "BSA..." },
+      },
+    });
+    if (!tool) {
+      throw new Error("Expected tool definition");
+    }
+
+    await tool.execute({
+      query: "latest Vietnam news",
+      country: "VN",
+    });
+
+    const requestUrl = new URL(String(mockFetch.mock.calls[0]?.[0]));
+    expect(requestUrl.searchParams.get("country")).toBe("ALL");
+  });
+});

package/src/brave-web-search-provider.ts

@@ -0,0 +1,158 @@
+import type {
+  SearchConfigRecord,
+  WebSearchProviderPlugin,
+  WebSearchProviderToolDefinition,
+} from "openclaw/plugin-sdk/provider-web-search";
+import { createWebSearchProviderContractFields } from "openclaw/plugin-sdk/provider-web-search-config-contract";
+
+const BRAVE_CREDENTIAL_PATH = "plugins.entries.brave.config.webSearch.apiKey";
+
+type BraveWebSearchRuntime = typeof import("./brave-web-search-provider.runtime.js");
+
+let braveWebSearchRuntimePromise: Promise<BraveWebSearchRuntime> | undefined;
+
+function loadBraveWebSearchRuntime(): Promise<BraveWebSearchRuntime> {
+  braveWebSearchRuntimePromise ??= import("./brave-web-search-provider.runtime.js");
+  return braveWebSearchRuntimePromise;
+}
+
+const BraveSearchSchema = {
+  type: "object",
+  properties: {
+    query: { type: "string", description: "Search query string." },
+    count: {
+      type: "number",
+      description: "Number of results to return (1-10).",
+      minimum: 1,
+      maximum: 10,
+    },
+    country: {
+      type: "string",
+      description:
+        "2-letter country code for region-specific results (e.g., 'DE', 'US', 'ALL'). Default: 'US'.",
+    },
+    language: {
+      type: "string",
+      description: "ISO 639-1 language code for results (e.g., 'en', 'de', 'fr').",
+    },
+    freshness: {
+      type: "string",
+      description: "Filter by time: 'day' (24h), 'week', 'month', or 'year'.",
+    },
+    date_after: {
+      type: "string",
+      description: "Only results published after this date (YYYY-MM-DD).",
+    },
+    date_before: {
+      type: "string",
+      description: "Only results published before this date (YYYY-MM-DD).",
+    },
+    search_lang: {
+      type: "string",
+      description:
+        "Brave language code for search results (e.g., 'en', 'de', 'en-gb', 'zh-hans', 'zh-hant', 'pt-br').",
+    },
+    ui_lang: {
+      type: "string",
+      description:
+        "Locale code for UI elements in language-region format (e.g., 'en-US', 'de-DE', 'fr-FR', 'tr-TR'). Must include region subtag.",
+    },
+  },
+} satisfies Record<string, unknown>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function resolveProviderWebSearchPluginConfig(
+  config: unknown,
+  pluginId: string,
+): Record<string, unknown> | undefined {
+  if (!isRecord(config)) {
+    return undefined;
+  }
+  const plugins = isRecord(config.plugins) ? config.plugins : undefined;
+  const entries = isRecord(plugins?.entries) ? plugins.entries : undefined;
+  const entry = isRecord(entries?.[pluginId]) ? entries[pluginId] : undefined;
+  const pluginConfig = isRecord(entry?.config) ? entry.config : undefined;
+  return isRecord(pluginConfig?.webSearch) ? pluginConfig.webSearch : undefined;
+}
+
+function mergeScopedSearchConfig(
+  searchConfig: Record<string, unknown> | undefined,
+  key: string,
+  pluginConfig: Record<string, unknown> | undefined,
+  options?: { mirrorApiKeyToTopLevel?: boolean },
+): Record<string, unknown> | undefined {
+  if (!pluginConfig) {
+    return searchConfig;
+  }
+
+  const currentScoped = isRecord(searchConfig?.[key]) ? searchConfig?.[key] : {};
+  const next: Record<string, unknown> = {
+    ...searchConfig,
+    [key]: {
+      ...currentScoped,
+      ...pluginConfig,
+    },
+  };
+
+  if (options?.mirrorApiKeyToTopLevel && pluginConfig.apiKey !== undefined) {
+    next.apiKey = pluginConfig.apiKey;
+  }
+
+  return next;
+}
+
+function resolveBraveMode(searchConfig?: Record<string, unknown>): "web" | "llm-context" {
+  const brave = isRecord(searchConfig?.brave) ? searchConfig.brave : undefined;
+  return brave?.mode === "llm-context" ? "llm-context" : "web";
+}
+
+function createBraveToolDefinition(
+  searchConfig?: SearchConfigRecord,
+): WebSearchProviderToolDefinition {
+  const braveMode = resolveBraveMode(searchConfig);
+
+  return {
+    description:
+      braveMode === "llm-context"
+        ? "Search the web using Brave Search LLM Context API. Returns pre-extracted page content (text chunks, tables, code blocks) optimized for LLM grounding."
+        : "Search the web using Brave Search API. Supports region-specific and localized search via country and language parameters. Returns titles, URLs, and snippets for fast research.",
+    parameters: BraveSearchSchema,
+    execute: async (args) => {
+      const { executeBraveSearch } = await loadBraveWebSearchRuntime();
+      return await executeBraveSearch(args, searchConfig);
+    },
+  };
+}
+
+export function createBraveWebSearchProvider(): WebSearchProviderPlugin {
+  return {
+    id: "brave",
+    label: "Brave Search",
+    hint: "Structured results · country/language/time filters",
+    onboardingScopes: ["text-inference"],
+    credentialLabel: "Brave Search API key",
+    envVars: ["BRAVE_API_KEY"],
+    placeholder: "BSA...",
+    signupUrl: "https://brave.com/search/api/",
+    docsUrl: "https://docs.openclaw.ai/brave-search",
+    autoDetectOrder: 10,
+    credentialPath: BRAVE_CREDENTIAL_PATH,
+    ...createWebSearchProviderContractFields({
+      credentialPath: BRAVE_CREDENTIAL_PATH,
+      searchCredential: { type: "top-level" },
+      configuredCredential: { pluginId: "brave" },
+    }),
+    createTool: (ctx) =>
+      createBraveToolDefinition(
+        mergeScopedSearchConfig(
+          ctx.searchConfig,
+          "brave",
+          resolveProviderWebSearchPluginConfig(ctx.config, "brave"),
+          { mirrorApiKeyToTopLevel: true },
+        ),
+      ),
+  };
+}

package/test-api.ts

@@ -0,0 +1,13 @@
+import {
+  mapBraveLlmContextResults,
+  normalizeBraveCountry,
+  normalizeBraveLanguageParams,
+  resolveBraveMode,
+} from "./src/brave-web-search-provider.shared.js";
+
+export const __testing = {
+  normalizeBraveCountry,
+  normalizeBraveLanguageParams,
+  resolveBraveMode,
+  mapBraveLlmContextResults,
+} as const;

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}

package/web-search-contract-api.ts

@@ -0,0 +1,28 @@
+import {
+  createWebSearchProviderContractFields,
+  type WebSearchProviderPlugin,
+} from "openclaw/plugin-sdk/provider-web-search-config-contract";
+
+export function createBraveWebSearchProvider(): WebSearchProviderPlugin {
+  const credentialPath = "plugins.entries.brave.config.webSearch.apiKey";
+
+  return {
+    id: "brave",
+    label: "Brave Search",
+    hint: "Structured results · country/language/time filters",
+    onboardingScopes: ["text-inference"],
+    credentialLabel: "Brave Search API key",
+    envVars: ["BRAVE_API_KEY"],
+    placeholder: "BSA...",
+    signupUrl: "https://brave.com/search/api/",
+    docsUrl: "https://docs.openclaw.ai/brave-search",
+    autoDetectOrder: 10,
+    credentialPath,
+    ...createWebSearchProviderContractFields({
+      credentialPath,
+      searchCredential: { type: "top-level" },
+      configuredCredential: { pluginId: "brave" },
+    }),
+    createTool: () => null,
+  };
+}

package/web-search-provider.ts

@@ -0,0 +1 @@
+export { createBraveWebSearchProvider } from "./src/brave-web-search-provider.js";