@klarkxy/dsh-web-search-manager 0.1.11 → 0.2.1

package/lib/contracts.d.ts

@@ -1,4 +1,5 @@
 import { WebFetchProvider, WebSearchProvider } from "@deepseek-ai/dsh-web";
+import { DshWebManagementDescriptor } from "@klarkxy/dsh-plugin-kit/contracts";
 //#region src/contracts.d.ts
 declare const WEB_SEARCH_RPC_CHANNEL = "/web-search-manager";
 type RpcResult<T = unknown> = {
@@ -13,25 +14,16 @@ type RpcResult<T = 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. The page must not delete it. */
-  readonly credentialShared?: boolean;
-  /** Optional notice naming the settings surface that owns a shared credential. */
-  readonly credentialHint?: string;
-  readonly billing: 'request' | 'model-and-tools' | 'none';
-  /** Optional provider-supplied billing summary. */
-  readonly pricing?: string;
-  /** Public HTTPS page explaining provider charges. */
-  readonly pricingUrl?: string;
-  /** Public HTTPS page where the user can create an API key. */
-  readonly signupUrl?: string;
-}
+/** Management metadata only. Field contract lives in plugin-kit; execution stays with ctx.web. */
+interface ProviderDescriptor extends DshWebManagementDescriptor {}
+declare const WEB_MANAGER_OWNER = "@klarkxy/dsh-web-search-manager";
+/** Optional display metadata on a provider registered directly with ctx.web. */
+type DiscoverableSearchProvider = WebSearchProvider & {
+  readonly dshWebManagement?: ProviderDescriptor;
+};
+type DiscoverableFetchProvider = WebFetchProvider & {
+  readonly dshWebManagement?: ProviderDescriptor;
+};
 interface ProviderOptions {
   readonly apiKey?: string;
   readonly baseURL?: string;
@@ -67,6 +59,8 @@ declare function pickActiveSearch(order: readonly string[], configured: (id: str
 interface ProviderView extends ProviderDescriptor {
   kind: ProviderKind;
   configured: boolean;
+  /** True only for configuration explicitly owned by this manager bundle. */
+  configurationOwned?: boolean;
   baseURL?: string;
   calls: number;
   failures: number;
@@ -79,7 +73,8 @@ interface WebStatus {
   storageFailed: boolean;
 }
 declare function providerKey(kind: ProviderKind, id: string): string;
+declare function safeConfigurationUrl(value: unknown): string | undefined;
 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 };
+export { DEFAULT_SEARCH_ORDER, DiscoverableFetchProvider, DiscoverableSearchProvider, FetchProviderFactory, ProviderDescriptor, ProviderKind, ProviderOptions, ProviderView, RpcResult, SearchProviderFactory, WEB_MANAGER_OWNER, WEB_SEARCH_RPC_CHANNEL, WebSettings, WebStatus, defaultSearchOrder, defaultSettings, migrateSearchOrder, pickActiveSearch, providerKey, resolveSearchOrder, safeConfigurationUrl, validateBaseURL };
 //# sourceMappingURL=contracts.d.ts.map

package/lib/contracts.js

@@ -1,5 +1,6 @@
 //#region src/contracts.ts
 const WEB_SEARCH_RPC_CHANNEL = "/web-search-manager";
+const WEB_MANAGER_OWNER = "@klarkxy/dsh-web-search-manager";
 const DEFAULT_SEARCH_ORDER = ["ddg"];
 const defaultSettings = () => ({
 	revision: 0,
@@ -30,12 +31,23 @@ function pickActiveSearch(order, configured) {
 function providerKey(kind, id) {
 	return `${kind}:${id}`;
 }
+function safeConfigurationUrl(value) {
+	if (typeof value !== "string" || !value || /[\u0000-\u0020\\]/.test(value)) return;
+	try {
+		const url = new URL(value, "https://dsh.invalid");
+		if (url.username || url.password) return;
+		if (value.startsWith("/") && !value.startsWith("//") || value.startsWith("#")) return url.origin === "https://dsh.invalid" ? value : void 0;
+		return /^https:\/\//i.test(value) && url.protocol === "https:" ? value : void 0;
+	} catch {
+		return;
+	}
+}
 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 };
+export { DEFAULT_SEARCH_ORDER, WEB_MANAGER_OWNER, WEB_SEARCH_RPC_CHANNEL, defaultSearchOrder, defaultSettings, migrateSearchOrder, pickActiveSearch, providerKey, resolveSearchOrder, safeConfigurationUrl, validateBaseURL };
 
 //# sourceMappingURL=contracts.js.map

package/lib/contracts.js.map

@@ -1 +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. The page must not delete it. */\n  readonly credentialShared?: boolean\n  /** Optional notice naming the settings surface that owns a shared credential. */\n  readonly credentialHint?: string\n  readonly billing: 'request' | 'model-and-tools' | 'none'\n  /** Optional provider-supplied billing summary. */\n  readonly pricing?: string\n  /** Public HTTPS page explaining provider charges. */\n  readonly pricingUrl?: string\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;AA8CtC,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"}
+{"version":3,"file":"contracts.js","names":[],"sources":["../src/contracts.ts"],"sourcesContent":["import type { WebFetchProvider, WebSearchProvider } from '@deepseek-ai/dsh-web'\nimport type { DshWebManagementDescriptor } from '@klarkxy/dsh-plugin-kit/contracts'\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. Field contract lives in plugin-kit; execution stays with ctx.web. */\nexport interface ProviderDescriptor extends DshWebManagementDescriptor {}\nexport const WEB_MANAGER_OWNER = '@klarkxy/dsh-web-search-manager'\n/** Optional display metadata on a provider registered directly with ctx.web. */\nexport type DiscoverableSearchProvider = WebSearchProvider & { readonly dshWebManagement?: ProviderDescriptor }\nexport type DiscoverableFetchProvider = WebFetchProvider & { readonly dshWebManagement?: ProviderDescriptor }\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  /** True only for configuration explicitly owned by this manager bundle. */\n  configurationOwned?: 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 safeConfigurationUrl(value: unknown): string | undefined {\n  if (typeof value !== 'string' || !value || /[\\u0000-\\u0020\\\\]/.test(value)) return\n  try {\n    const url = new URL(value, 'https://dsh.invalid')\n    if (url.username || url.password) return\n    if ((value.startsWith('/') && !value.startsWith('//')) || value.startsWith('#')) {\n      return url.origin === 'https://dsh.invalid' ? value : undefined\n    }\n    return /^https:\\/\\//i.test(value) && url.protocol === 'https:' ? value : undefined\n  } catch { return }\n}\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":";AAGA,MAAa,yBAAyB;AAOtC,MAAa,oBAAoB;AA0BjC,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;AAiBA,SAAgB,YAAY,MAAoB,IAAoB;CAAE,OAAO,GAAG,KAAK,GAAG;AAAK;AAC7F,SAAgB,qBAAqB,OAAoC;CACvE,IAAI,OAAO,UAAU,YAAY,CAAC,SAAS,oBAAoB,KAAK,KAAK,GAAG;CAC5E,IAAI;EACF,MAAM,MAAM,IAAI,IAAI,OAAO,qBAAqB;EAChD,IAAI,IAAI,YAAY,IAAI,UAAU;EAClC,IAAK,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,WAAW,IAAI,KAAM,MAAM,WAAW,GAAG,GAC5E,OAAO,IAAI,WAAW,wBAAwB,QAAQ,KAAA;EAExD,OAAO,eAAe,KAAK,KAAK,KAAK,IAAI,aAAa,WAAW,QAAQ,KAAA;CAC3E,QAAQ;EAAE;CAAO;AACnB;AACA,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

@@ -1,11 +1,14 @@
 import { FetchProviderFactory, ProviderDescriptor, ProviderOptions, SearchProviderFactory, WebSettings, WebStatus } from "./contracts.js";
 import { WebFetchProvider, WebSearchProvider } from "@deepseek-ai/dsh-web";
+import { WEB_PROVIDER_AVAILABILITY_EVENT } from "@klarkxy/dsh-plugin-kit/contracts";
 import { Context } from "@deepseek-ai/cordis";
-//#region src/manager.d.ts
+//#region src/web-registry.d.ts
 interface WebRegistry {
   registerSearchProvider(provider: WebSearchProvider): () => void;
   registerFetchProvider(provider: WebFetchProvider): () => void;
 }
+//#endregion
+//#region src/manager.d.ts
 interface ManagerOptions {
   web: WebRegistry;
   initial?: Omit<WebSettings, 'searchOrder'> & {
@@ -25,22 +28,29 @@ declare class WebSearchManager {
   private suspended;
   private disposed;
   private storageFailed;
+  private refreshRevision;
+  private detach;
+  private legacyRegistrations;
   constructor(options: ManagerOptions);
   subscribe(listener: () => void): () => void;
   private notify;
   private knownSearchIds;
   private keyed;
   private configured;
+  private ready;
   private searchOrder;
   private activeSearchId;
   private selected;
   status(): WebStatus;
   refresh(): Promise<WebStatus>;
   private abort;
-  private add;
-  private registration;
+  private discover;
+  /** @deprecated Provider plugins should register directly with ctx.web. */
   registerSearchProvider(descriptor: ProviderDescriptor, factory: SearchProviderFactory): () => void;
+  /** @deprecated Provider plugins should register directly with ctx.web. */
   registerFetchProvider(descriptor: ProviderDescriptor, factory: FetchProviderFactory): () => void;
+  private providerConfiguration;
+  private legacyRegistration;
   private execute;
   update(next: Omit<WebSettings, 'revision'>, expectedRevision: number): Promise<WebStatus>;
   dispose(): Promise<void>;
@@ -55,6 +65,12 @@ declare module '@deepseek-ai/cordis' {
   }
 }
 declare function apply(ctx: Context): Promise<void>;
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    /** Repository extension: native providers announce a local availability change. */
+    [WEB_PROVIDER_AVAILABILITY_EVENT](kind: 'search' | 'fetch', id: string): void;
+  }
+}
 //#endregion
 export { type FetchProviderFactory, type ProviderDescriptor, type ProviderOptions, type SearchProviderFactory, WebSearchManager, apply, inject, name };
 //# sourceMappingURL=index.d.ts.map