opencode-websearch-deepseek 0.2.0 → 0.3.1

package/README.md

@@ -77,6 +77,34 @@ in:
 > so no environment variable is required when that provider is already
 > authenticated.
 
+### Plugin options
+
+As an alternative to environment variables, configure the plugin with the
+`plugins` object form (read from `ctx.options`):
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "opencode-websearch-deepseek",
+      "options": {
+        "apiKey": "{file:~/.config/opencode/deepseek.key}",
+        "model": "deepseek-v4-flash",
+        "maxUses": 5,
+        "thinking": "enabled"
+      }
+    }
+  ]
+}
+```
+
+Precedence for the API key: `options.apiKey` → `DEEPSEEK_API_KEY` /
+`WEBSEARCH_API_KEY` → stored `deepseek` provider credential. `model`, `maxUses`,
+and `thinking` fall back to their environment variables and defaults.
+OpenCode interpolates `{file:...}` (and `{env:...}`) in config values, so the
+key can live in a file instead of the OS environment.
+
 > The plugin always selects the DeepSeek provider. Without an API key, a
 > `websearch` call fails with a clear error rather than silently falling back
 > to a different provider.

package/dist/index.d.ts

@@ -95,25 +95,48 @@ export interface IntegrationContext {
         resolve(connection: unknown): Promise<StoredCredential | undefined>;
     };
 }
+/**
+ * Options accepted through the `plugins` object form in `opencode.json(c)` and
+ * forwarded to the plugin via `ctx.options`:
+ *
+ * ```jsonc
+ * { "plugins": [{ "package": "opencode-websearch-deepseek", "options": {
+ *   "apiKey": "...", "model": "deepseek-v4-flash", "maxUses": 5, "thinking": "enabled"
+ * } }] }
+ * ```
+ */
+export interface WebsearchOptions {
+    /** DeepSeek API key; takes precedence over env and the stored credential. */
+    apiKey?: string;
+    /** Model used for search and synthesis. */
+    model?: string;
+    /** Max server-side searches per query. */
+    maxUses?: number | string;
+    /** `enabled` or `disabled`. */
+    thinking?: string;
+}
 /** Context passed to the plugin's `setup`. */
 export interface WebsearchContext {
     websearch: {
         transform(callback: (editor: WebsearchEditor) => void): Promise<unknown> | unknown;
     };
+    /** Plugin options from the `plugins` object form. */
+    options?: Record<string, unknown>;
     /** Present in OpenCode 2.x; used to reuse the DeepSeek provider credential. */
     integration?: IntegrationContext;
 }
 /**
- * Resolve the DeepSeek API key. An explicit environment variable takes
- * precedence; otherwise the key OpenCode stores for the `deepseek` provider
- * (configured via `opencode auth login`) is used.
+ * Resolve the DeepSeek API key, in order of precedence: the `apiKey` plugin
+ * option, then the `DEEPSEEK_API_KEY`/`WEBSEARCH_API_KEY` environment
+ * variables, then the credential OpenCode stores for the `deepseek` provider
+ * (configured via `opencode auth login`).
  */
-export declare function resolveApiKey(ctx: WebsearchContext): Promise<string | undefined>;
+export declare function resolveApiKey(ctx: WebsearchContext, options?: WebsearchOptions): Promise<string | undefined>;
 /**
  * Resolve the `max_uses` value for the search tool declaration.
  * Falls back to {@link DEFAULT_MAX_USES} for missing or invalid input.
  */
-export declare function resolveMaxUses(raw?: string | undefined): number;
+export declare function resolveMaxUses(raw?: string | number | undefined): number;
 /**
  * Resolve the thinking mode. Only `disabled` disables extended thinking;
  * anything else (including unset) keeps the historical `enabled` behavior.

package/dist/index.js

@@ -46,12 +46,20 @@ export const SYSTEM_PROMPT = [
     "",
     "Your response must be the final answer, not another search request.",
 ].join("\n");
+/** Return a trimmed non-empty string, or undefined for any other value. */
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
 /**
- * Resolve the DeepSeek API key. An explicit environment variable takes
- * precedence; otherwise the key OpenCode stores for the `deepseek` provider
- * (configured via `opencode auth login`) is used.
+ * Resolve the DeepSeek API key, in order of precedence: the `apiKey` plugin
+ * option, then the `DEEPSEEK_API_KEY`/`WEBSEARCH_API_KEY` environment
+ * variables, then the credential OpenCode stores for the `deepseek` provider
+ * (configured via `opencode auth login`).
  */
-export async function resolveApiKey(ctx) {
+export async function resolveApiKey(ctx, options) {
+    const fromOptions = readString(options?.apiKey);
+    if (fromOptions)
+        return fromOptions;
     const fromEnv = readEnv("DEEPSEEK_API_KEY") ?? readEnv("WEBSEARCH_API_KEY");
     if (fromEnv)
         return fromEnv;
@@ -63,11 +71,11 @@ export async function resolveApiKey(ctx) {
         if (!connection)
             return undefined;
         const credential = await integration.connection.resolve(connection);
-        const key = credential?.key;
-        return typeof key === "string" && key.trim() ? key.trim() : undefined;
+        return readString(credential?.key);
     }
-    catch {
-        return undefined;
+    catch (error) {
+        // A genuine integration failure is not "no key": surface it with context.
+        throw new Error("Failed to read the DeepSeek credential from OpenCode", { cause: error });
     }
 }
 /** Read an environment variable, treating blank strings as unset. */
@@ -76,44 +84,77 @@ function readEnv(name, env = process.env) {
     return value && value.trim() ? value.trim() : undefined;
 }
 /**
- * Rethrow the cancellation reason from `signal`. `Error` and `DOMException`
- * (e.g. `AbortError`) are preserved as-is; other values (primitives) are
+ * Rethrow the cancellation reason from `signal`. `Error` and `AbortError`
+ * objects (e.g. `DOMException`) are preserved as-is; other reasons are
  * normalised to an `Error` so callers always receive one.
  */
 function throwCancellation(signal, fallback) {
     const reason = signal.reason;
     if (reason instanceof Error)
         throw reason;
-    if (typeof reason === "object" && reason !== null)
-        throw reason;
-    if (reason !== undefined && reason !== null)
-        throw new Error(String(reason));
+    if (typeof reason === "object" && reason !== null) {
+        // Preserve AbortError-like objects (DOMException has a message); wrap the rest.
+        const candidate = reason;
+        if (candidate.name === "AbortError" && typeof candidate.message === "string")
+            throw reason;
+        throw new Error("The web search was aborted", { cause: reason });
+    }
+    if (reason !== undefined && reason !== null) {
+        const text = String(reason).trim();
+        if (text)
+            throw new Error(text);
+    }
     if (fallback instanceof Error)
         throw fallback;
     throw new Error("The web search was aborted");
 }
+/**
+ * Validate a `max_uses` value: a positive safe integer, given as a number or a
+ * plain-integer string. Returns `undefined` when unset or invalid.
+ */
+function pickMaxUses(value) {
+    if (typeof value === "number") {
+        return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+    }
+    if (typeof value !== "string")
+        return undefined;
+    // Strict: only a plain positive integer. Rejects "1e3", "5.5", "5abc" and
+    // values outside the safe-integer range (e.g. a 24-digit number).
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed))
+        return undefined;
+    const parsed = Number(trimmed);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
 /**
  * Resolve the `max_uses` value for the search tool declaration.
  * Falls back to {@link DEFAULT_MAX_USES} for missing or invalid input.
  */
 export function resolveMaxUses(raw = process.env.WEBSEARCH_MAX_USES) {
-    const value = (typeof raw === "string" ? raw : "").trim();
-    // Strict: only a plain positive integer. Rejects "1e3", "5.5", "5abc" and
-    // values outside the safe-integer range (e.g. a 24-digit number).
-    if (!/^\d+$/.test(value))
-        return DEFAULT_MAX_USES;
-    const parsed = Number(value);
-    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_USES;
+    return pickMaxUses(raw) ?? DEFAULT_MAX_USES;
+}
+/**
+ * Validate a thinking mode: only recognised `enabled`/`disabled` spellings
+ * count. Returns `undefined` when unset or unrecognised.
+ */
+function pickThinking(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "enabled" || normalized === "on" || normalized === "true" || normalized === "1") {
+        return "enabled";
+    }
+    if (normalized === "disabled" || normalized === "off" || normalized === "false" || normalized === "0") {
+        return "disabled";
+    }
+    return undefined;
 }
 /**
  * Resolve the thinking mode. Only `disabled` disables extended thinking;
  * anything else (including unset) keeps the historical `enabled` behavior.
  */
 export function resolveThinking(raw = process.env.WEBSEARCH_THINKING) {
-    const value = (typeof raw === "string" ? raw : "").trim().toLowerCase();
-    return value === "disabled" || value === "off" || value === "false" || value === "0"
-        ? "disabled"
-        : "enabled";
+    return pickThinking(raw) ?? "enabled";
 }
 /** Build the JSON request body sent to the DeepSeek Messages endpoint. */
 export function buildRequestBody(query, options) {
@@ -143,7 +184,7 @@ export function buildRequestBody(query, options) {
  */
 export function dedupeSources(sources) {
     const byUrl = new Map();
-    for (const source of sources) {
+    for (const source of Array.isArray(sources) ? sources : []) {
         if (typeof source?.url !== "string" || source.url.length === 0)
             continue;
         const existing = byUrl.get(source.url);
@@ -199,16 +240,17 @@ export function extractAnswerAndSources(data) {
  * present), followed by the individual sources.
  */
 export function toResults(answer, sources = []) {
+    const valid = (Array.isArray(sources) ? sources : []).filter((source) => typeof source?.url === "string" && source.url.length > 0);
     const results = [];
     if (answer) {
         results.push({
-            url: sources[0]?.url ?? FALLBACK_URL,
+            url: valid[0]?.url ?? FALLBACK_URL,
             title: "DeepSeek answer",
             content: answer,
             time: {},
         });
     }
-    for (const source of sources) {
+    for (const source of valid) {
         results.push({
             url: source.url,
             title: source.title || source.url,
@@ -230,51 +272,64 @@ export function toResults(answer, sources = []) {
 export const plugin = {
     id: "websearch.deepseek",
     async setup(ctx) {
+        const options = (ctx.options ?? {});
         await ctx.websearch.transform((editor) => {
             editor.add({
                 id: "deepseek",
                 name: "DeepSeek Web Search",
-                execute: async ({ query }, { signal } = {}) => {
-                    const apiKey = await resolveApiKey(ctx);
-                    if (!apiKey) {
-                        throw new Error("DEEPSEEK_API_KEY is not set and no stored DeepSeek credential was found; set the env var or sign in to the deepseek provider in OpenCode");
-                    }
-                    if (!/^[\x21-\x7e]+$/.test(apiKey)) {
-                        throw new Error("The API key contains invalid characters");
-                    }
-                    const body = buildRequestBody(query, {
-                        model: readEnv("WEBSEARCH_MODEL") ?? DEFAULT_MODEL,
-                        maxUses: resolveMaxUses(),
-                        thinking: resolveThinking(),
-                    });
-                    const response = await fetch(API_URL, {
-                        method: "POST",
-                        signal,
-                        headers: {
-                            "content-type": "application/json",
-                            "x-api-key": apiKey,
-                            "anthropic-version": ANTHROPIC_VERSION,
-                        },
-                        body: JSON.stringify(body),
-                    });
-                    if (!response.ok) {
-                        const text = await response.text().catch((error) => {
-                            // Preserve cancellation: never turn an abort into an API error.
-                            if (signal?.aborted)
-                                return throwCancellation(signal, error);
-                            if (error?.name === "AbortError")
-                                throw error;
-                            return "";
+                execute: async ({ query }, context) => {
+                    const signal = context?.signal;
+                    try {
+                        const apiKey = await resolveApiKey(ctx, options);
+                        if (!apiKey) {
+                            throw new Error("No DeepSeek API key: set the DEEPSEEK_API_KEY env var, pass the apiKey plugin option, or sign in to the deepseek provider in OpenCode");
+                        }
+                        if (!/^[\x21-\x7e]+$/.test(apiKey)) {
+                            throw new Error("The API key contains invalid characters");
+                        }
+                        const body = buildRequestBody(query, {
+                            model: readString(options.model) ?? readEnv("WEBSEARCH_MODEL") ?? DEFAULT_MODEL,
+                            // Valid options win; an unset or invalid option falls back to env.
+                            maxUses: pickMaxUses(options.maxUses) ?? resolveMaxUses(readEnv("WEBSEARCH_MAX_USES")),
+                            thinking: pickThinking(options.thinking) ?? resolveThinking(readEnv("WEBSEARCH_THINKING")),
                         });
-                        // An abort can also arrive after the body resolves; re-check so it
-                        // is not masked as an API error.
+                        const response = await fetch(API_URL, {
+                            method: "POST",
+                            signal,
+                            headers: {
+                                "content-type": "application/json",
+                                "x-api-key": apiKey,
+                                "anthropic-version": ANTHROPIC_VERSION,
+                            },
+                            body: JSON.stringify(body),
+                        });
+                        if (!response.ok) {
+                            const text = await response.text().catch((error) => {
+                                // Preserve cancellation: never turn an abort into an API error.
+                                if (signal?.aborted)
+                                    return throwCancellation(signal, error);
+                                if (error?.name === "AbortError")
+                                    throw error;
+                                const detail = error instanceof Error ? error.message : String(error);
+                                return `[body read failed: ${detail}]`;
+                            });
+                            // An abort can also arrive after the body resolves; re-check so it
+                            // is not masked as an API error.
+                            if (signal?.aborted)
+                                throwCancellation(signal, undefined);
+                            throw new Error(`DeepSeek API error ${response.status}: ${text.slice(0, 300)}`);
+                        }
+                        const data = (await response.json());
+                        const { answer, sources } = extractAnswerAndSources(data);
+                        return toResults(answer, sources);
+                    }
+                    catch (error) {
+                        // `fetch`/`json` reject with the raw signal reason; normalise any
+                        // cancellation so callers always receive an Error.
                         if (signal?.aborted)
-                            throwCancellation(signal, undefined);
-                        throw new Error(`DeepSeek API error ${response.status}: ${text.slice(0, 300)}`);
+                            throwCancellation(signal, error);
+                        throw error;
                     }
-                    const data = (await response.json());
-                    const { answer, sources } = extractAnswerAndSources(data);
-                    return toResults(answer, sources);
                 },
             });
             editor.default.set("deepseek");

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-websearch-deepseek",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "DeepSeek-powered web search provider for OpenCode's built-in websearch tool.",
   "type": "module",
   "license": "MIT",
@@ -44,8 +44,8 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test",
+    "prepare": "node -e \"try{require.resolve('typescript')}catch{process.exit(0)};require('node:child_process').execSync('npm run build',{stdio:'inherit'})\"",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run build && node --test",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
   },
   "devDependencies": {