@klarkxy/dsh-web-search-manager 0.1.0

package/lib/contracts.d.ts

@@ -0,0 +1,79 @@
+import { WebFetchProvider, WebSearchProvider } from "@deepseek-ai/dsh-web";
+//#region src/contracts.d.ts
+declare const WEB_SEARCH_RPC_CHANNEL = "/web-search-manager";
+type RpcResult<T = unknown> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: {
+    code: string;
+    message: string;
+    details: Record<string, unknown>;
+  };
+};
+type ProviderKind = 'search' | 'fetch';
+/** Management metadata only. Execution and source vocabulary belong to ctx.web. */
+interface ProviderDescriptor {
+  readonly id: string;
+  readonly label: string;
+  readonly description: string;
+  readonly defaultBaseURL?: string;
+  readonly credentialRef?: string;
+  /** True when the key is shared with another surface (e.g. the chat model Key). The page must not delete it. */
+  readonly credentialShared?: boolean;
+  readonly billing: 'request' | 'model-and-tools' | 'none';
+  /** Public HTTPS page where the user can create an API key. */
+  readonly signupUrl?: string;
+}
+interface ProviderOptions {
+  readonly apiKey?: string;
+  readonly baseURL?: string;
+  readonly timeoutMs: number;
+  readonly maxFetchChars: number;
+}
+type SearchProviderFactory = (options: ProviderOptions) => WebSearchProvider;
+type FetchProviderFactory = (options: ProviderOptions) => WebFetchProvider;
+/** Never store credential values here. Keys are resolved by reference per call. */
+interface WebSettings {
+  revision: number;
+  searchEnabled: boolean;
+  fetchEnabled: boolean;
+  searchProvider: string;
+  fetchProvider: string;
+  searchOrder: string[];
+  maxResults: number;
+  maxQueries: number;
+  timeoutMs: number;
+  maxFetchChars: number;
+  endpoints: Record<string, string>;
+}
+declare const DEFAULT_SEARCH_ORDER: readonly ["ddg"];
+declare const defaultSettings: () => WebSettings;
+/** Keyed backends first, keyless last — same idea as OpenClaw auto-detect. */
+declare function defaultSearchOrder(ids: readonly string[], keyed: (id: string) => boolean): string[];
+declare function migrateSearchOrder(settings: {
+  searchOrder?: string[];
+  searchProvider?: string;
+}): string[];
+declare function resolveSearchOrder(knownIds: readonly string[], settings: Pick<WebSettings, 'searchOrder' | 'searchProvider'>, _keyed: (id: string) => boolean): string[];
+declare function pickActiveSearch(order: readonly string[], configured: (id: string) => boolean): string;
+interface ProviderView extends ProviderDescriptor {
+  kind: ProviderKind;
+  configured: boolean;
+  baseURL?: string;
+  calls: number;
+  failures: number;
+}
+interface WebStatus {
+  settings: WebSettings;
+  providers: ProviderView[];
+  searchActive: boolean;
+  fetchActive: boolean;
+  storageFailed: boolean;
+}
+declare function providerKey(kind: ProviderKind, id: string): string;
+declare function validateBaseURL(value: string): string;
+//#endregion
+export { DEFAULT_SEARCH_ORDER, FetchProviderFactory, ProviderDescriptor, ProviderKind, ProviderOptions, ProviderView, RpcResult, SearchProviderFactory, WEB_SEARCH_RPC_CHANNEL, WebSettings, WebStatus, defaultSearchOrder, defaultSettings, migrateSearchOrder, pickActiveSearch, providerKey, resolveSearchOrder, validateBaseURL };
+//# sourceMappingURL=contracts.d.ts.map

package/lib/contracts.js

@@ -0,0 +1,41 @@
+//#region src/contracts.ts
+const WEB_SEARCH_RPC_CHANNEL = "/web-search-manager";
+const DEFAULT_SEARCH_ORDER = ["ddg"];
+const defaultSettings = () => ({
+	revision: 0,
+	searchEnabled: true,
+	fetchEnabled: true,
+	searchProvider: "ddg",
+	fetchProvider: "http",
+	searchOrder: [...DEFAULT_SEARCH_ORDER],
+	maxResults: 5,
+	maxQueries: 1,
+	timeoutMs: 3e4,
+	maxFetchChars: 1e5,
+	endpoints: {}
+});
+/** Keyed backends first, keyless last — same idea as OpenClaw auto-detect. */
+function defaultSearchOrder(ids, keyed) {
+	return [...ids.filter(keyed), ...ids.filter((id) => !keyed(id))];
+}
+function migrateSearchOrder(settings) {
+	return settings.searchOrder ?? (settings.searchProvider ? [settings.searchProvider] : [...DEFAULT_SEARCH_ORDER]);
+}
+function resolveSearchOrder(knownIds, settings, _keyed) {
+	return [...new Set(settings.searchOrder.filter((id) => knownIds.includes(id)))];
+}
+function pickActiveSearch(order, configured) {
+	return order.find(configured) ?? "";
+}
+function providerKey(kind, id) {
+	return `${kind}:${id}`;
+}
+function validateBaseURL(value) {
+	const url = new URL(value);
+	if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) throw new Error("供应商地址必须是 HTTPS，且不能包含用户名、密码、查询参数或片段。");
+	return url.href.replace(/\/+$/, "");
+}
+//#endregion
+export { DEFAULT_SEARCH_ORDER, WEB_SEARCH_RPC_CHANNEL, defaultSearchOrder, defaultSettings, migrateSearchOrder, pickActiveSearch, providerKey, resolveSearchOrder, validateBaseURL };
+
+//# sourceMappingURL=contracts.js.map

package/lib/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","names":[],"sources":["../src/contracts.ts"],"sourcesContent":["import type { WebFetchProvider, WebSearchProvider } from '@deepseek-ai/dsh-web'\n\nexport const WEB_SEARCH_RPC_CHANNEL = '/web-search-manager'\nexport type RpcResult<T = unknown> = { ok: true; value: T } | {\n  ok: false; error: { code: string; message: string; details: Record<string, unknown> }\n}\nexport type ProviderKind = 'search' | 'fetch'\n/** Management metadata only. Execution and source vocabulary belong to ctx.web. */\nexport interface ProviderDescriptor {\n  readonly id: string\n  readonly label: string\n  readonly description: string\n  readonly defaultBaseURL?: string\n  readonly credentialRef?: string\n  /** True when the key is shared with another surface (e.g. the chat model Key). The page must not delete it. */\n  readonly credentialShared?: boolean\n  readonly billing: 'request' | 'model-and-tools' | 'none'\n  /** Public HTTPS page where the user can create an API key. */\n  readonly signupUrl?: string\n}\nexport interface ProviderOptions {\n  readonly apiKey?: string\n  readonly baseURL?: string\n  readonly timeoutMs: number\n  readonly maxFetchChars: number\n}\nexport type SearchProviderFactory = (options: ProviderOptions) => WebSearchProvider\nexport type FetchProviderFactory = (options: ProviderOptions) => WebFetchProvider\n/** Never store credential values here. Keys are resolved by reference per call. */\nexport interface WebSettings {\n  revision: number\n  searchEnabled: boolean\n  fetchEnabled: boolean\n  searchProvider: string\n  fetchProvider: string\n  searchOrder: string[]\n  maxResults: number\n  maxQueries: number\n  timeoutMs: number\n  maxFetchChars: number\n  endpoints: Record<string, string>\n}\nexport const DEFAULT_SEARCH_ORDER = ['ddg'] as const\n\nexport const defaultSettings = (): WebSettings => ({\n  revision: 0, searchEnabled: true, fetchEnabled: true,\n  searchProvider: 'ddg', fetchProvider: 'http', searchOrder: [...DEFAULT_SEARCH_ORDER],\n  maxResults: 5, maxQueries: 1,\n  timeoutMs: 30_000, maxFetchChars: 100_000, endpoints: {},\n})\n\n/** Keyed backends first, keyless last — same idea as OpenClaw auto-detect. */\nexport function defaultSearchOrder(ids: readonly string[], keyed: (id: string) => boolean): string[] {\n  return [...ids.filter(keyed), ...ids.filter(id => !keyed(id))]\n}\n\nexport function migrateSearchOrder(settings: { searchOrder?: string[]; searchProvider?: string }): string[] {\n  return settings.searchOrder ?? (settings.searchProvider ? [settings.searchProvider] : [...DEFAULT_SEARCH_ORDER])\n}\n\nexport function resolveSearchOrder(\n  knownIds: readonly string[],\n  settings: Pick<WebSettings, 'searchOrder' | 'searchProvider'>,\n  _keyed: (id: string) => boolean,\n): string[] {\n  return [...new Set(settings.searchOrder.filter(id => knownIds.includes(id)))]\n}\n\nexport function pickActiveSearch(order: readonly string[], configured: (id: string) => boolean): string {\n  return order.find(configured) ?? ''\n}\nexport interface ProviderView extends ProviderDescriptor {\n  kind: ProviderKind\n  configured: boolean\n  baseURL?: string\n  calls: number\n  failures: number\n}\nexport interface WebStatus {\n  settings: WebSettings\n  providers: ProviderView[]\n  searchActive: boolean\n  fetchActive: boolean\n  storageFailed: boolean\n}\nexport function providerKey(kind: ProviderKind, id: string): string { return `${kind}:${id}` }\nexport function validateBaseURL(value: string): string {\n  const url = new URL(value)\n  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) {\n    throw new Error('供应商地址必须是 HTTPS，且不能包含用户名、密码、查询参数或片段。')\n  }\n  return url.href.replace(/\\/+$/, '')\n}\n"],"mappings":";AAEA,MAAa,yBAAyB;AAwCtC,MAAa,uBAAuB,CAAC,KAAK;AAE1C,MAAa,yBAAsC;CACjD,UAAU;CAAG,eAAe;CAAM,cAAc;CAChD,gBAAgB;CAAO,eAAe;CAAQ,aAAa,CAAC,GAAG,oBAAoB;CACnF,YAAY;CAAG,YAAY;CAC3B,WAAW;CAAQ,eAAe;CAAS,WAAW,CAAC;AACzD;;AAGA,SAAgB,mBAAmB,KAAwB,OAA0C;CACnG,OAAO,CAAC,GAAG,IAAI,OAAO,KAAK,GAAG,GAAG,IAAI,QAAO,OAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC/D;AAEA,SAAgB,mBAAmB,UAAyE;CAC1G,OAAO,SAAS,gBAAgB,SAAS,iBAAiB,CAAC,SAAS,cAAc,IAAI,CAAC,GAAG,oBAAoB;AAChH;AAEA,SAAgB,mBACd,UACA,UACA,QACU;CACV,OAAO,CAAC,GAAG,IAAI,IAAI,SAAS,YAAY,QAAO,OAAM,SAAS,SAAS,EAAE,CAAC,CAAC,CAAC;AAC9E;AAEA,SAAgB,iBAAiB,OAA0B,YAA6C;CACtG,OAAO,MAAM,KAAK,UAAU,KAAK;AACnC;AAeA,SAAgB,YAAY,MAAoB,IAAoB;CAAE,OAAO,GAAG,KAAK,GAAG;AAAK;AAC7F,SAAgB,gBAAgB,OAAuB;CACrD,MAAM,MAAM,IAAI,IAAI,KAAK;CACzB,IAAI,IAAI,aAAa,YAAY,IAAI,YAAY,IAAI,YAAY,IAAI,UAAU,IAAI,MACjF,MAAM,IAAI,MAAM,qCAAqC;CAEvD,OAAO,IAAI,KAAK,QAAQ,QAAQ,EAAE;AACpC"}

package/lib/index.d.ts

@@ -0,0 +1,60 @@
+import { FetchProviderFactory, ProviderDescriptor, ProviderOptions, SearchProviderFactory, WebSettings, WebStatus } from "./contracts.js";
+import { WebFetchProvider, WebSearchProvider } from "@deepseek-ai/dsh-web";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/manager.d.ts
+interface WebRegistry {
+  registerSearchProvider(provider: WebSearchProvider): () => void;
+  registerFetchProvider(provider: WebFetchProvider): () => void;
+}
+interface ManagerOptions {
+  web: WebRegistry;
+  initial?: Omit<WebSettings, 'searchOrder'> & {
+    searchOrder?: string[];
+  };
+  resolveCredential(ref: string): Promise<string | undefined>;
+  save(settings: WebSettings): Promise<void>;
+}
+/** Manages consent and provider lifecycle. Selection and execution stay in ctx.web. */
+declare class WebSearchManager {
+  private readonly options;
+  private settings;
+  private entries;
+  private listeners;
+  private pending;
+  private epoch;
+  private suspended;
+  private disposed;
+  private storageFailed;
+  constructor(options: ManagerOptions);
+  subscribe(listener: () => void): () => void;
+  private notify;
+  private knownSearchIds;
+  private keyed;
+  private configured;
+  private searchOrder;
+  private activeSearchId;
+  private selected;
+  status(): WebStatus;
+  refresh(): Promise<WebStatus>;
+  private abort;
+  private add;
+  private registration;
+  registerSearchProvider(descriptor: ProviderDescriptor, factory: SearchProviderFactory): () => void;
+  registerFetchProvider(descriptor: ProviderDescriptor, factory: FetchProviderFactory): () => void;
+  private execute;
+  update(next: Omit<WebSettings, 'revision'>, expectedRevision: number): Promise<WebStatus>;
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/index.d.ts
+declare const name = "@klarkxy/dsh-web-search-manager";
+declare const inject: readonly ["web", "credentials", "storageDomain", "connection", "webServer"];
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    webSearchManager: WebSearchManager;
+  }
+}
+declare function apply(ctx: Context): Promise<void>;
+//#endregion
+export { type FetchProviderFactory, type ProviderDescriptor, type ProviderOptions, type SearchProviderFactory, WebSearchManager, apply, inject, name };
+//# sourceMappingURL=index.d.ts.map