deepseek-web-retrieval 0.4.0 → 0.5.0

package/src/core/search.ts

@@ -1,7 +1,7 @@
-import { normalizeDomains } from "./domains"
-import { truncate } from "./format"
-import type { DeepSeekSearchResult, SearchOptions, SearchResult } from "./types"
-import { normalizeResultUrl } from "./url"
+import { normalizeDomains } from "./domains";
+import { truncate } from "./format";
+import type { DeepSeekSearchResult, SearchOptions, SearchResult } from "./types";
+import { normalizeResultUrl } from "./url";
 
 /**
  * Appends DeepSeek search operators:
@@ -13,72 +13,73 @@ export function buildQuery(
   query: string,
   options: Pick<SearchOptions, "blockedDomains" | "includeDomains" | "language">,
 ): string {
-  const parts = [query.trim()]
-  for (const domain of normalizeDomains(options.blockedDomains)) parts.push(`-site:${domain}`)
-  const include = normalizeDomains(options.includeDomains)
-  if (include.length) parts.push(include.map((domain) => `site:${domain}`).join(" OR "))
-  const language = options.language?.trim().replace(/^lang:/i, "")
-  if (language) parts.push(`lang:${language}`)
-  return parts.filter((part) => part.length > 0).join(" ")
+  const parts = [query.trim()];
+  for (const domain of normalizeDomains(options.blockedDomains)) parts.push(`-site:${domain}`);
+  const include = normalizeDomains(options.includeDomains);
+  if (include.length) parts.push(include.map((domain) => `site:${domain}`).join(" OR "));
+  const language = options.language?.trim().replace(/^lang:/i, "");
+  if (language) parts.push(`lang:${language}`);
+  return parts.filter((part) => part.length > 0).join(" ");
 }
 
 export function parsePublished(value: unknown): number | undefined {
-  if (typeof value !== "string" || !value.trim()) return undefined
-  const timestamp = Date.parse(value)
-  return Number.isFinite(timestamp) ? timestamp : undefined
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : undefined;
 }
 
 /**
  * Filters and maps DeepSeek results into the neutral SearchResult shape.
- * Missing/non-finite rerank_score never passes. Authority -1/missing is
+ * A present rerank_score always compares against minRerank; a missing or
+ * non-finite score passes only while no positive threshold is set, so the
+ * default returns exactly what DeepSeek ranked. Authority -1/missing is
  * "unknown" and only passes when allowUnknownAuthority is enabled.
  */
-export function processResults(
-  raw: readonly DeepSeekSearchResult[],
-  options: SearchOptions,
-): SearchResult[] {
-  const results: SearchResult[] = []
-  const seen = new Set<string>()
+export function processResults(raw: readonly DeepSeekSearchResult[], options: SearchOptions): SearchResult[] {
+  const results: SearchResult[] = [];
+  const seen = new Set<string>();
 
   for (const item of raw) {
-    if (results.length >= options.maxResults) break
-    if (!item || typeof item !== "object") continue
+    if (results.length >= options.maxResults) break;
+    if (!item || typeof item !== "object") continue;
 
-    const url = normalizeResultUrl(item.url)
-    if (!url || seen.has(url)) continue
+    const url = normalizeResultUrl(item.url);
+    if (!url || seen.has(url)) continue;
 
-    const rerank = item.rerank_score
-    if (typeof rerank !== "number" || !Number.isFinite(rerank) || rerank < options.minRerank) continue
+    const rerank = item.rerank_score;
+    if (typeof rerank === "number" && Number.isFinite(rerank)) {
+      if (rerank < options.minRerank) continue;
+    } else if (options.minRerank > 0) {
+      // A threshold was explicitly raised, so a result that cannot be scored
+      // against it must not slip through.
+      continue;
+    }
 
-    const authority = item.authority
-    const knownAuthority =
-      typeof authority === "number" && Number.isFinite(authority) && authority >= 0
+    const authority = item.authority;
+    const knownAuthority = typeof authority === "number" && Number.isFinite(authority) && authority >= 0;
     if (knownAuthority) {
-      if (authority < options.minAuthority) continue
+      if (authority < options.minAuthority) continue;
     } else if (!options.allowUnknownAuthority) {
-      continue
+      continue;
     }
 
-    seen.add(url)
-    const content = truncate(
-      optionalText(item.summary) ?? optionalText(item.snippet) ?? "",
-      options.maxSummaryChars,
-    )
-    const published = parsePublished(item.date)
-    const title = optionalText(item.title)
+    seen.add(url);
+    const content = truncate(optionalText(item.summary) ?? optionalText(item.snippet) ?? "", options.maxSummaryChars);
+    const published = parsePublished(item.date);
+    const title = optionalText(item.title);
     results.push({
       url,
       ...(title ? { title } : {}),
       ...(content ? { content } : {}),
       ...(published !== undefined ? { published } : {}),
-    })
+    });
   }
 
-  return results
+  return results;
 }
 
 function optionalText(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined
-  const trimmed = value.trim()
-  return trimmed ? trimmed : undefined
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
 }

package/src/core/transport.ts

@@ -1,41 +1,41 @@
-import { MAX_ERROR_BODY_CHARS, MAX_RESPONSE_BYTES, MAX_RETRY_DELAY_MS } from "./constants"
-import { formatApiError, formatTimeoutError, redactSecrets, truncate } from "./format"
-import type { RequestAuth, RetryOptions } from "./types"
+import { MAX_ERROR_BODY_CHARS, MAX_RESPONSE_BYTES, MAX_RETRY_DELAY_MS } from "./constants";
+import { formatApiError, formatTimeoutError, redactSecrets, truncate } from "./format";
+import type { RequestAuth, RetryOptions } from "./types";
 
 /** Everything one POST needs; `fetchImpl` is injectable so tests need no monkey-patching. */
 export interface TransportOptions {
-  readonly signal: AbortSignal
-  readonly auth: RequestAuth
-  readonly retry: RetryOptions
-  readonly timeoutMs: number
-  readonly fetchImpl?: typeof fetch
+  readonly signal: AbortSignal;
+  readonly auth: RequestAuth;
+  readonly retry: RetryOptions;
+  readonly timeoutMs: number;
+  readonly fetchImpl?: typeof fetch;
 }
 
 export class DeepSeekApiError extends Error {
-  readonly operation: string
-  readonly status: number
-  readonly body: string
-  readonly retryable: boolean
-  readonly retryAfterMs?: number
+  readonly operation: string;
+  readonly status: number;
+  readonly body: string;
+  readonly retryable: boolean;
+  readonly retryAfterMs?: number;
 
   constructor(input: {
-    operation: string
-    status: number
-    body: string
-    retryAfterMs?: number
+    operation: string;
+    status: number;
+    body: string;
+    retryAfterMs?: number;
   }) {
-    const body = redactSecrets(input.body)
-    super(formatApiError(input.operation, input.status, body))
-    this.name = "DeepSeekApiError"
-    this.operation = input.operation
-    this.status = input.status
-    this.body = body
+    const body = redactSecrets(input.body);
+    super(formatApiError(input.operation, input.status, body));
+    this.name = "DeepSeekApiError";
+    this.operation = input.operation;
+    this.status = input.status;
+    this.body = body;
     this.retryable =
       input.status === 408 ||
       input.status === 425 ||
       input.status === 429 ||
-      (input.status >= 500 && input.status <= 599)
-    this.retryAfterMs = input.retryAfterMs
+      (input.status >= 500 && input.status <= 599);
+    this.retryAfterMs = input.retryAfterMs;
   }
 }
 
@@ -45,23 +45,23 @@ export async function postJson<T>(
   operation: string,
   opts: TransportOptions,
 ): Promise<T> {
-  const fetchImpl = opts.fetchImpl ?? globalThis.fetch
-  const attempts = opts.retry.maxRetries + 1
-  let lastError: unknown
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const attempts = opts.retry.maxRetries + 1;
+  let lastError: unknown;
 
   for (let attempt = 0; attempt < attempts; attempt++) {
     try {
-      return await requestOnce<T>(endpoint, body, operation, opts, fetchImpl)
+      return await requestOnce<T>(endpoint, body, operation, opts, fetchImpl);
     } catch (error) {
-      lastError = error
+      lastError = error;
       if (!(error instanceof DeepSeekApiError) || !error.retryable || attempt === attempts - 1) {
-        throw error
+        throw error;
       }
-      await sleep(retryDelay(error.retryAfterMs, opts.retry.baseDelayMs, attempt), opts.signal)
+      await sleep(retryDelay(error.retryAfterMs, opts.retry.baseDelayMs, attempt), opts.signal);
     }
   }
 
-  throw lastError
+  throw lastError;
 }
 
 async function requestOnce<T>(
@@ -87,25 +87,25 @@ async function requestOnce<T>(
     fetchImpl,
     async (response) => {
       if (!response.ok) {
-        const text = await readBoundedText(response, MAX_ERROR_BODY_CHARS)
+        const text = await readBoundedText(response, MAX_ERROR_BODY_CHARS);
         throw new DeepSeekApiError({
           operation,
           status: response.status,
           body: text,
           retryAfterMs: parseRetryAfter(response.headers.get("retry-after")),
-        })
+        });
       }
 
-      const text = await readResponseText(response, MAX_RESPONSE_BYTES, operation)
-      if (!text.trim()) throw new Error(`${operation} returned an empty response body`)
+      const text = await readResponseText(response, MAX_RESPONSE_BYTES, operation);
+      if (!text.trim()) throw new Error(`${operation} returned an empty response body`);
 
       try {
-        return JSON.parse(text) as T
+        return JSON.parse(text) as T;
       } catch {
-        throw new Error(`${operation} returned invalid JSON: ${truncate(redactSecrets(text), 500)}`)
+        throw new Error(`${operation} returned invalid JSON: ${truncate(redactSecrets(text), 500)}`);
       }
     },
-  )
+  );
 }
 
 /**
@@ -122,132 +122,128 @@ async function fetchWithTimeout<T>(
   fetchImpl: typeof fetch,
   handleResponse: (response: Response) => Promise<T>,
 ): Promise<T> {
-  const controller = new AbortController()
-  let timedOut = false
-  const forwardAbort = () => controller.abort(signal.reason)
-  if (signal.aborted) forwardAbort()
-  else signal.addEventListener("abort", forwardAbort, { once: true })
+  const controller = new AbortController();
+  let timedOut = false;
+  const forwardAbort = () => controller.abort(signal.reason);
+  if (signal.aborted) forwardAbort();
+  else signal.addEventListener("abort", forwardAbort, { once: true });
 
   const timer = signal.aborted
     ? undefined
     : setTimeout(() => {
-        timedOut = true
-        controller.abort(new Error("timeout"))
-      }, timeoutMs)
+        timedOut = true;
+        controller.abort(new Error("timeout"));
+      }, timeoutMs);
 
   try {
-    const response = await fetchImpl(endpoint, { ...init, signal: controller.signal })
-    return await handleResponse(response)
+    const response = await fetchImpl(endpoint, { ...init, signal: controller.signal });
+    return await handleResponse(response);
   } catch (error) {
-    if (timedOut) throw new Error(formatTimeoutError(operation, timeoutMs))
-    if (signal.aborted) throw abortReason(signal, operation)
-    throw error
+    if (timedOut) throw new Error(formatTimeoutError(operation, timeoutMs));
+    if (signal.aborted) throw abortReason(signal, operation);
+    throw error;
   } finally {
-    if (timer !== undefined) clearTimeout(timer)
-    signal.removeEventListener("abort", forwardAbort)
+    if (timer !== undefined) clearTimeout(timer);
+    signal.removeEventListener("abort", forwardAbort);
   }
 }
 
 export function parseRetryAfter(value: string | null): number | undefined {
-  if (!value) return undefined
-  const trimmed = value.trim()
-  if (!trimmed) return undefined
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
 
   if (/^\d+$/.test(trimmed)) {
-    return Math.min(MAX_RETRY_DELAY_MS, Number(trimmed) * 1000)
+    return Math.min(MAX_RETRY_DELAY_MS, Number(trimmed) * 1000);
   }
 
-  const timestamp = Date.parse(trimmed)
-  if (!Number.isFinite(timestamp)) return undefined
-  return Math.min(MAX_RETRY_DELAY_MS, Math.max(0, timestamp - Date.now()))
+  const timestamp = Date.parse(trimmed);
+  if (!Number.isFinite(timestamp)) return undefined;
+  return Math.min(MAX_RETRY_DELAY_MS, Math.max(0, timestamp - Date.now()));
 }
 
 export function retryDelay(retryAfterMs: number | undefined, baseDelayMs: number, attempt: number): number {
-  if (retryAfterMs !== undefined) return retryAfterMs
-  return Math.min(MAX_RETRY_DELAY_MS, baseDelayMs * 2 ** attempt)
+  if (retryAfterMs !== undefined) return retryAfterMs;
+  return Math.min(MAX_RETRY_DELAY_MS, baseDelayMs * 2 ** attempt);
 }
 
 function sleep(ms: number, signal: AbortSignal): Promise<void> {
-  if (ms <= 0) return Promise.resolve()
+  if (ms <= 0) return Promise.resolve();
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
-      signal.removeEventListener("abort", onAbort)
-      resolve()
-    }, ms)
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
     const onAbort = () => {
-      clearTimeout(timer)
-      reject(abortReason(signal, "DeepSeek request"))
-    }
+      clearTimeout(timer);
+      reject(abortReason(signal, "DeepSeek request"));
+    };
     if (signal.aborted) {
-      clearTimeout(timer)
-      reject(abortReason(signal, "DeepSeek request"))
-      return
+      clearTimeout(timer);
+      reject(abortReason(signal, "DeepSeek request"));
+      return;
     }
-    signal.addEventListener("abort", onAbort, { once: true })
-  })
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
 }
 
 function abortReason(signal: AbortSignal, operation: string): unknown {
-  return signal.reason instanceof Error ? signal.reason : new Error(`${operation} request aborted`)
+  return signal.reason instanceof Error ? signal.reason : new Error(`${operation} request aborted`);
 }
 
 /** Reads at most `maxChars + 1` characters, enough for formatApiError to add its marker. */
 async function readBoundedText(response: Response, maxChars: number): Promise<string> {
-  if (!response.body) return truncate(await response.text(), maxChars + 1)
+  if (!response.body) return truncate(await response.text(), maxChars + 1);
 
-  const reader = response.body.getReader()
-  const decoder = new TextDecoder()
-  const limit = maxChars + 1
-  let text = ""
-  let chars = 0
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  const limit = maxChars + 1;
+  let text = "";
+  let chars = 0;
   try {
     while (chars < limit) {
-      const { done, value } = await reader.read()
-      if (done) break
-      const chunk = decoder.decode(value, { stream: true })
-      text += chunk
-      chars += Array.from(chunk).length
+      const { done, value } = await reader.read();
+      if (done) break;
+      const chunk = decoder.decode(value, { stream: true });
+      text += chunk;
+      chars += Array.from(chunk).length;
     }
-    text += decoder.decode()
+    text += decoder.decode();
   } finally {
-    await reader.cancel().catch(() => undefined)
-    reader.releaseLock()
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
   }
-  return truncate(text, limit)
+  return truncate(text, limit);
 }
 
 /** Reads a successful response body, rejecting payloads above `maxBytes`. */
-async function readResponseText(
-  response: Response,
-  maxBytes: number,
-  operation: string,
-): Promise<string> {
+async function readResponseText(response: Response, maxBytes: number, operation: string): Promise<string> {
   if (!response.body) {
-    const text = await response.text()
+    const text = await response.text();
     if (new TextEncoder().encode(text).byteLength > maxBytes) {
-      throw new Error(`${operation} response exceeded ${maxBytes} bytes`)
+      throw new Error(`${operation} response exceeded ${maxBytes} bytes`);
     }
-    return text
+    return text;
   }
 
-  const reader = response.body.getReader()
-  const decoder = new TextDecoder()
-  let text = ""
-  let bytes = 0
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let text = "";
+  let bytes = 0;
   try {
     while (true) {
-      const { done, value } = await reader.read()
-      if (done) break
-      bytes += value.byteLength
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytes += value.byteLength;
       if (bytes > maxBytes) {
-        throw new Error(`${operation} response exceeded ${maxBytes} bytes`)
+        throw new Error(`${operation} response exceeded ${maxBytes} bytes`);
       }
-      text += decoder.decode(value, { stream: true })
+      text += decoder.decode(value, { stream: true });
     }
-    text += decoder.decode()
+    text += decoder.decode();
   } finally {
-    await reader.cancel().catch(() => undefined)
-    reader.releaseLock()
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
   }
-  return text
+  return text;
 }

package/src/core/types.ts

@@ -1,85 +1,85 @@
-export type ApiKeySource = "auto" | "opencode" | "env"
+export type ApiKeySource = "auto" | "opencode" | "env";
 
 export interface PluginOptions {
-  readonly [key: string]: unknown
+  readonly [key: string]: unknown;
 }
 
 export interface SearchOptions {
-  readonly count: number
-  readonly maxResults: number
-  readonly minRerank: number
-  readonly minAuthority: number
-  readonly allowUnknownAuthority: boolean
-  readonly blockedDomains: readonly string[]
-  readonly includeDomains: readonly string[]
-  readonly language?: string
-  readonly maxSummaryChars: number
-  readonly timeoutMs: number
-  readonly enabled: boolean
+  readonly count: number;
+  readonly maxResults: number;
+  readonly minRerank: number;
+  readonly minAuthority: number;
+  readonly allowUnknownAuthority: boolean;
+  readonly blockedDomains: readonly string[];
+  readonly includeDomains: readonly string[];
+  readonly language?: string;
+  readonly maxSummaryChars: number;
+  readonly timeoutMs: number;
+  readonly enabled: boolean;
 }
 
 export interface FetchOptions {
-  readonly maxChars: number
-  readonly allowedDomains: readonly string[]
-  readonly blockedDomains: readonly string[]
-  readonly timeoutMs: number
-  readonly blockPrivateHosts: boolean
-  readonly enabled: boolean
+  readonly maxChars: number;
+  readonly allowedDomains: readonly string[];
+  readonly blockedDomains: readonly string[];
+  readonly timeoutMs: number;
+  readonly blockPrivateHosts: boolean;
+  readonly enabled: boolean;
 }
 
 export interface AuthOptions {
-  readonly source: ApiKeySource
+  readonly source: ApiKeySource;
 }
 
 export interface RetryOptions {
-  readonly maxRetries: number
-  readonly baseDelayMs: number
+  readonly maxRetries: number;
+  readonly baseDelayMs: number;
 }
 
 export interface ResolvedOptions {
-  readonly search: SearchOptions
-  readonly fetch: FetchOptions
-  readonly auth: AuthOptions
-  readonly retry: RetryOptions
+  readonly search: SearchOptions;
+  readonly fetch: FetchOptions;
+  readonly auth: AuthOptions;
+  readonly retry: RetryOptions;
 }
 
 export interface DeepSeekSearchResult {
-  readonly rerank_score?: number
-  readonly authority?: number
-  readonly title?: string | null
-  readonly url?: string | null
-  readonly snippet?: string | null
-  readonly summary?: string | null
-  readonly date?: string | null
+  readonly rerank_score?: number;
+  readonly authority?: number;
+  readonly title?: string | null;
+  readonly url?: string | null;
+  readonly snippet?: string | null;
+  readonly summary?: string | null;
+  readonly date?: string | null;
 }
 
 /** A neutral, host-agnostic search result. */
 export interface SearchResult {
-  readonly url: string
-  readonly title?: string
-  readonly content?: string
-  readonly published?: number
+  readonly url: string;
+  readonly title?: string;
+  readonly content?: string;
+  readonly published?: number;
 }
 
 export interface FetchedPage {
-  readonly url: string
-  readonly title: string
-  readonly content: string
+  readonly url: string;
+  readonly title: string;
+  readonly content: string;
 }
 
 export interface FormattedFetchContent {
-  readonly content: string
-  readonly truncated: boolean
+  readonly content: string;
+  readonly truncated: boolean;
 }
 
 /** A fetched page formatted for the model, with truncation reported. */
 export interface FetchedDocument {
-  readonly url: string
-  readonly title: string
-  readonly content: string
-  readonly truncated: boolean
+  readonly url: string;
+  readonly title: string;
+  readonly content: string;
+  readonly truncated: boolean;
 }
 
 export interface RequestAuth {
-  readonly apiKey: string
+  readonly apiKey: string;
 }

package/src/core/url.ts

@@ -1,42 +1,42 @@
-import { MAX_URL_CHARS } from "./constants"
-import { normalizeHostname } from "./domains"
+import { MAX_URL_CHARS } from "./constants";
+import { normalizeHostname } from "./domains";
 
 export function parseFetchUrl(value: string): URL {
-  const input = value.trim()
-  if (!input) throw new Error("URL must not be empty")
+  const input = value.trim();
+  if (!input) throw new Error("URL must not be empty");
   if (input.length > MAX_URL_CHARS) {
-    throw new Error(`URL must be ${MAX_URL_CHARS} characters or fewer`)
+    throw new Error(`URL must be ${MAX_URL_CHARS} characters or fewer`);
   }
 
-  let url: URL
+  let url: URL;
   try {
-    url = new URL(input)
+    url = new URL(input);
   } catch {
-    throw new Error("URL must be an absolute http:// or https:// URL")
+    throw new Error("URL must be an absolute http:// or https:// URL");
   }
   if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error("URL must use http:// or https://")
+    throw new Error("URL must use http:// or https://");
   }
   if (!url.hostname || !normalizeHostname(url.hostname)) {
-    throw new Error("URL must include a host")
+    throw new Error("URL must include a host");
   }
   if (url.username || url.password) {
-    throw new Error("URL must not contain credentials")
+    throw new Error("URL must not contain credentials");
   }
-  return url
+  return url;
 }
 
 /** Normalizes a search-result URL and drops anything that is not public HTTP(S). */
 export function normalizeResultUrl(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined
-  const input = value.trim()
-  if (!input || input.length > MAX_URL_CHARS) return undefined
+  if (typeof value !== "string") return undefined;
+  const input = value.trim();
+  if (!input || input.length > MAX_URL_CHARS) return undefined;
   try {
-    const url = new URL(input)
-    if (url.protocol !== "http:" && url.protocol !== "https:") return undefined
-    if (!url.hostname || url.username || url.password) return undefined
-    return url.href
+    const url = new URL(input);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
+    if (!url.hostname || url.username || url.password) return undefined;
+    return url.href;
   } catch {
-    return undefined
+    return undefined;
   }
 }