@memberjunction/web-search-engine 0.0.1-seed.1 → 6.2.0-edge.0

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Public surface of the MemberJunction web search engine.
+ *
+ * Importing this module runs every driver's `@RegisterClass` decorator as a side effect, which
+ * is what makes them resolvable by `DriverClass`. That is why the providers are exported here
+ * rather than left for consumers to import individually.
+ *
+ * @module @memberjunction/web-search-engine
+ */
+export * from './types.js';
+export * from './BaseWebSearchProvider.js';
+export * from './WebSearchEngine.js';
+export * from './providers/BraveWebSearchProvider.js';
+export * from './providers/TavilyWebSearchProvider.js';
+export * from './providers/PerplexityWebSearchProvider.js';
+export * from './providers/GoogleCustomSearchWebSearchProvider.js';
+export * from './providers/DuckDuckGoWebSearchProvider.js';
+export * from './providers/httpFailure.js';
+export * from './operations/WebSearchQueryOperation.js';
+/**
+ * Keep every driver registration alive through tree-shaking.
+ *
+ * Bundlers drop a module whose exports are unused, and a dropped module never runs its
+ * decorator — so the driver silently vanishes from `ClassFactory` and the engine reports
+ * "no registered driver" for a `DriverClass` that plainly exists in the source.
+ */
+export declare function LoadWebSearchProviders(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,yCAAyC,CAAC;AACxD,cAAc,iDAAiD,CAAC;AAChE,cAAc,yCAAyC,CAAC;AACxD,cAAc,yBAAyB,CAAC;AACxC,cAAc,sCAAsC,CAAC;AASrD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAO7C"}

package/dist/index.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Public surface of the MemberJunction web search engine.
+ *
+ * Importing this module runs every driver's `@RegisterClass` decorator as a side effect, which
+ * is what makes them resolvable by `DriverClass`. That is why the providers are exported here
+ * rather than left for consumers to import individually.
+ *
+ * @module @memberjunction/web-search-engine
+ */
+export * from './types.js';
+export * from './BaseWebSearchProvider.js';
+export * from './WebSearchEngine.js';
+// Drivers — exported for their registration side effect as much as for their types.
+export * from './providers/BraveWebSearchProvider.js';
+export * from './providers/TavilyWebSearchProvider.js';
+export * from './providers/PerplexityWebSearchProvider.js';
+export * from './providers/GoogleCustomSearchWebSearchProvider.js';
+export * from './providers/DuckDuckGoWebSearchProvider.js';
+export * from './providers/httpFailure.js';
+export * from './operations/WebSearchQueryOperation.js';
+import { LoadBraveWebSearchProvider } from './providers/BraveWebSearchProvider.js';
+import { LoadTavilyWebSearchProvider } from './providers/TavilyWebSearchProvider.js';
+import { LoadPerplexityWebSearchProvider } from './providers/PerplexityWebSearchProvider.js';
+import { LoadGoogleCustomSearchWebSearchProvider } from './providers/GoogleCustomSearchWebSearchProvider.js';
+import { LoadDuckDuckGoWebSearchProvider } from './providers/DuckDuckGoWebSearchProvider.js';
+import { LoadWebSearchOperations } from './operations/WebSearchQueryOperation.js';
+/**
+ * Keep every driver registration alive through tree-shaking.
+ *
+ * Bundlers drop a module whose exports are unused, and a dropped module never runs its
+ * decorator — so the driver silently vanishes from `ClassFactory` and the engine reports
+ * "no registered driver" for a `DriverClass` that plainly exists in the source.
+ */
+export function LoadWebSearchProviders() {
+    LoadBraveWebSearchProvider();
+    LoadTavilyWebSearchProvider();
+    LoadPerplexityWebSearchProvider();
+    LoadGoogleCustomSearchWebSearchProvider();
+    LoadDuckDuckGoWebSearchProvider();
+    LoadWebSearchOperations();
+}
+LoadWebSearchProviders();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAElC,oFAAoF;AACpF,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,yCAAyC,CAAC;AACxD,cAAc,iDAAiD,CAAC;AAChE,cAAc,yCAAyC,CAAC;AACxD,cAAc,yBAAyB,CAAC;AACxC,cAAc,sCAAsC,CAAC;AAErD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,EAAE,+BAA+B,EAAE,MAAM,yCAAyC,CAAC;AAC1F,OAAO,EAAE,uCAAuC,EAAE,MAAM,iDAAiD,CAAC;AAC1G,OAAO,EAAE,+BAA+B,EAAE,MAAM,yCAAyC,CAAC;AAC1F,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB;IAClC,0BAA0B,EAAE,CAAC;IAC7B,2BAA2B,EAAE,CAAC;IAC9B,+BAA+B,EAAE,CAAC;IAClC,uCAAuC,EAAE,CAAC;IAC1C,+BAA+B,EAAE,CAAC;IAClC,uBAAuB,EAAE,CAAC;AAC9B,CAAC;AAED,sBAAsB,EAAE,CAAC"}

package/dist/operations/WebSearchQueryOperation.d.ts

@@ -0,0 +1,8 @@
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { WebSearchQueryOperation, type WebSearchQueryInput, type WebSearchQueryOutput } from '@memberjunction/core-entities';
+export declare class WebSearchQueryServerOperation extends WebSearchQueryOperation {
+    protected InternalExecute(input: WebSearchQueryInput, provider: IMetadataProvider, user: UserInfo): Promise<WebSearchQueryOutput>;
+}
+/** Keep the registration from being tree-shaken out of a bundled host. */
+export declare function LoadWebSearchOperations(): void;
+//# sourceMappingURL=WebSearchQueryOperation.d.ts.map

package/dist/operations/WebSearchQueryOperation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSearchQueryOperation.d.ts","sourceRoot":"","sources":["../../src/operations/WebSearchQueryOperation.ts"],"names":[],"mappings":"AASA,OAAO,EAA0B,iBAAiB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACH,uBAAuB,EACvB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAC5B,MAAM,+BAA+B,CAAC;AAIvC,qBACa,6BAA8B,SAAQ,uBAAuB;cACtD,eAAe,CAC3B,KAAK,EAAE,mBAAmB,EAC1B,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,oBAAoB,CAAC;CA+CnC;AAED,0EAA0E;AAC1E,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}

package/dist/operations/WebSearchQueryOperation.js

@@ -0,0 +1,72 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * @fileoverview `WebSearch.Query` — server implementation of the Web Search remote operation.
+ *
+ * Exposes WebSearchEngine to client applications through MemberJunction's Remote Operations
+ * RPC gateway with `websearch:execute` API scope enforcement.
+ *
+ * @module @memberjunction/web-search-engine
+ */
+import { RegisterClass } from '@memberjunction/global';
+import { BaseRemotableOperation } from '@memberjunction/core';
+import { WebSearchQueryOperation, } from '@memberjunction/core-entities';
+import { WebSearchEngine } from '../WebSearchEngine.js';
+let WebSearchQueryServerOperation = class WebSearchQueryServerOperation extends WebSearchQueryOperation {
+    async InternalExecute(input, provider, user) {
+        const query = input?.query?.trim();
+        if (!query) {
+            throw new Error('query is required');
+        }
+        await WebSearchEngine.Instance.Config(false, user, provider);
+        const searchParams = {
+            Query: query,
+            MaxResults: input.maxResults,
+            Provider: input.provider,
+            IncludeDomains: input.includeDomains,
+            ExcludeDomains: input.excludeDomains,
+            Freshness: input.freshness,
+            Country: input.country,
+            Language: input.language,
+            SafeSearch: input.safeSearch,
+            IncludeAnswer: input.includeAnswer,
+        };
+        const result = await WebSearchEngine.Instance.Search(searchParams, user);
+        if (!result.Success) {
+            throw new Error(`${result.ResultCode}: ${result.ErrorMessage ?? 'Search failed'}`);
+        }
+        return {
+            hits: (result.Hits ?? []).map((hit) => ({
+                title: hit.Title,
+                url: hit.URL,
+                snippet: hit.Snippet,
+                displayUrl: hit.DisplayURL,
+                publishedAt: hit.PublishedAt instanceof Date ? hit.PublishedAt.toISOString() : undefined,
+                score: hit.Score,
+            })),
+            answer: result.Answer,
+            providerUsed: result.ProviderUsed ?? '',
+            attempts: (result.Attempts ?? []).map((attempt) => ({
+                providerName: attempt.ProviderName,
+                succeeded: attempt.Succeeded,
+                durationMs: attempt.DurationMs,
+                hitCount: attempt.HitCount,
+                failureKind: attempt.FailureKind,
+                errorMessage: attempt.ErrorMessage,
+            })),
+        };
+    }
+};
+WebSearchQueryServerOperation = __decorate([
+    RegisterClass(BaseRemotableOperation, 'WebSearch.Query')
+], WebSearchQueryServerOperation);
+export { WebSearchQueryServerOperation };
+/** Keep the registration from being tree-shaken out of a bundled host. */
+export function LoadWebSearchOperations() {
+    void WebSearchQueryServerOperation;
+}
+//# sourceMappingURL=WebSearchQueryOperation.js.map

package/dist/operations/WebSearchQueryOperation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSearchQueryOperation.js","sourceRoot":"","sources":["../../src/operations/WebSearchQueryOperation.ts"],"names":[],"mappings":"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"}

package/dist/providers/BraveWebSearchProvider.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Brave Search driver.
+ * @module @memberjunction/web-search-engine
+ */
+import { UserInfo } from '@memberjunction/core';
+import { BaseWebSearchProvider } from '../BaseWebSearchProvider.js';
+import { WebSearchCapabilities, WebSearchParams, WebSearchProviderResponse } from '../types.js';
+/**
+ * Searches the web through the Brave Search API.
+ *
+ * Brave is the recommended default for a structural reason rather than a qualitative one: it
+ * serves from **its own index** rather than reselling Google's or Bing's. Every SERP-proxy
+ * vendor, and the Google Custom Search JSON API that this engine exists to replace, depends on
+ * a search engine continuing to permit that access. Brave does not, so it fails independently
+ * of every other driver here — which is the entire point of having a provider set.
+ *
+ * Credential key `apiKey`; environment fallback `BRAVE_SEARCH_API_KEY`.
+ */
+export declare class BraveWebSearchProvider extends BaseWebSearchProvider {
+    private static readonly ENDPOINT;
+    /** Brave rejects queries longer than this outright. */
+    private static readonly MAX_QUERY_CHARS;
+    /** Brave's cap on the pagination offset, in pages. */
+    private static readonly MAX_OFFSET;
+    readonly Capabilities: WebSearchCapabilities;
+    private apiKey;
+    CheckAvailability(_contextUser: UserInfo): Promise<void>;
+    ExecuteSearch(params: WebSearchParams, _contextUser: UserInfo): Promise<WebSearchProviderResponse>;
+    /**
+     * Brave has no domain-filter request parameter — it expresses domain scoping through query
+     * operators, so that is how the capability is honoured. Includes become an OR-group of
+     * `site:` terms; excludes become `-site:` terms.
+     */
+    private applyDomainFilters;
+    /** Brave expresses relative windows as pd/pw/pm/py and ranges as `YYYY-MM-DDtoYYYY-MM-DD`. */
+    private mapFreshness;
+    private toHit;
+}
+/** Anti-tree-shaking anchor — importing this module is what runs the @RegisterClass decorator. */
+export declare function LoadBraveWebSearchProvider(): void;
+//# sourceMappingURL=BraveWebSearchProvider.d.ts.map

package/dist/providers/BraveWebSearchProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BraveWebSearchProvider.d.ts","sourceRoot":"","sources":["../../src/providers/BraveWebSearchProvider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EACH,qBAAqB,EAErB,eAAe,EACf,yBAAyB,EAC5B,MAAM,UAAU,CAAC;AAkBlB;;;;;;;;;;GAUG;AACH,qBACa,sBAAuB,SAAQ,qBAAqB;IAC7D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAoD;IACpF,uDAAuD;IACvD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAO;IAC9C,sDAAsD;IACtD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAK;IAEvC,SAAgB,YAAY,EAAE,qBAAqB,CAMjD;IAEF,OAAO,CAAC,MAAM,CAAqB;IAEtB,iBAAiB,CAAC,YAAY,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxD,aAAa,CACtB,MAAM,EAAE,eAAe,EACvB,YAAY,EAAE,QAAQ,GACvB,OAAO,CAAC,yBAAyB,CAAC;IA4DrC;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAgB1B,8FAA8F;IAC9F,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,KAAK;CA2BhB;AAED,kGAAkG;AAClG,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/dist/providers/BraveWebSearchProvider.js

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview Brave Search driver.
+ * @module @memberjunction/web-search-engine
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var BraveWebSearchProvider_1;
+import { RegisterClass } from '@memberjunction/global';
+import { HttpGet } from '@memberjunction/network-utils';
+import { BaseWebSearchProvider } from '../BaseWebSearchProvider.js';
+import { classifyHttpFailure, failure } from './httpFailure.js';
+/**
+ * Searches the web through the Brave Search API.
+ *
+ * Brave is the recommended default for a structural reason rather than a qualitative one: it
+ * serves from **its own index** rather than reselling Google's or Bing's. Every SERP-proxy
+ * vendor, and the Google Custom Search JSON API that this engine exists to replace, depends on
+ * a search engine continuing to permit that access. Brave does not, so it fails independently
+ * of every other driver here — which is the entire point of having a provider set.
+ *
+ * Credential key `apiKey`; environment fallback `BRAVE_SEARCH_API_KEY`.
+ */
+let BraveWebSearchProvider = class BraveWebSearchProvider extends BaseWebSearchProvider {
+    constructor() {
+        super(...arguments);
+        this.Capabilities = {
+            Answer: false,
+            DomainFilter: true,
+            Freshness: true,
+            Region: true,
+            MaxResultsCap: 20,
+        };
+    }
+    static { BraveWebSearchProvider_1 = this; }
+    static { this.ENDPOINT = 'https://api.search.brave.com/res/v1/web/search'; }
+    /** Brave rejects queries longer than this outright. */
+    static { this.MAX_QUERY_CHARS = 400; }
+    /** Brave's cap on the pagination offset, in pages. */
+    static { this.MAX_OFFSET = 9; }
+    async CheckAvailability(_contextUser) {
+        this.apiKey = this.GetSecret('apiKey', 'BRAVE_SEARCH_API_KEY');
+        if (this.apiKey) {
+            this.MarkAvailable();
+        }
+        else {
+            this.MarkUnavailable('No Brave API key. Set it on the linked Credential (key `apiKey`) or as BRAVE_SEARCH_API_KEY.');
+        }
+    }
+    async ExecuteSearch(params, _contextUser) {
+        // Rejected rather than truncated: silently cutting a query changes what was asked and
+        // returns confident results for a different question. Permanent — no other provider
+        // will accept it either.
+        if (params.Query.length > BraveWebSearchProvider_1.MAX_QUERY_CHARS) {
+            return failure('permanent', `Query is ${params.Query.length} characters; Brave's limit is ${BraveWebSearchProvider_1.MAX_QUERY_CHARS}.`);
+        }
+        const q = this.applyDomainFilters(params);
+        if (q.length > BraveWebSearchProvider_1.MAX_QUERY_CHARS) {
+            return failure('permanent', `Query plus domain filters is ${q.length} characters; Brave's limit is ${BraveWebSearchProvider_1.MAX_QUERY_CHARS}.`);
+        }
+        const query = {
+            q,
+            count: this.ResolveMaxResults(params.MaxResults),
+            offset: 0,
+            safesearch: params.SafeSearch ?? 'moderate',
+        };
+        const freshness = this.mapFreshness(params);
+        if (freshness) {
+            query.freshness = freshness;
+        }
+        if (params.Country) {
+            query.country = params.Country.toUpperCase();
+        }
+        if (params.Language) {
+            query.search_lang = params.Language.toLowerCase();
+        }
+        try {
+            const response = await HttpGet(BraveWebSearchProvider_1.ENDPOINT, {
+                Query: query,
+                Headers: {
+                    'X-Subscription-Token': this.apiKey ?? '',
+                    Accept: 'application/json',
+                },
+                Timeout: 15000,
+            });
+            if (!response.Data) {
+                return failure('transient', 'Empty response from Brave Search.');
+            }
+            return {
+                Success: true,
+                Hits: (response.Data.web?.results ?? []).map((item) => this.toHit(item)),
+            };
+        }
+        catch (e) {
+            return classifyHttpFailure(e, 'Brave');
+        }
+    }
+    /**
+     * Brave has no domain-filter request parameter — it expresses domain scoping through query
+     * operators, so that is how the capability is honoured. Includes become an OR-group of
+     * `site:` terms; excludes become `-site:` terms.
+     */
+    applyDomainFilters(params) {
+        const parts = [params.Query.trim()];
+        const include = (params.IncludeDomains ?? []).map((d) => d.trim()).filter(Boolean);
+        const exclude = (params.ExcludeDomains ?? []).map((d) => d.trim()).filter(Boolean);
+        if (include.length === 1) {
+            parts.push(`site:${include[0]}`);
+        }
+        else if (include.length > 1) {
+            parts.push(`(${include.map((d) => `site:${d}`).join(' OR ')})`);
+        }
+        for (const domain of exclude) {
+            parts.push(`-site:${domain}`);
+        }
+        return parts.join(' ');
+    }
+    /** Brave expresses relative windows as pd/pw/pm/py and ranges as `YYYY-MM-DDtoYYYY-MM-DD`. */
+    mapFreshness(params) {
+        const freshness = params.Freshness;
+        if (!freshness) {
+            return undefined;
+        }
+        if (typeof freshness === 'string') {
+            return { day: 'pd', week: 'pw', month: 'pm', year: 'py' }[freshness];
+        }
+        const iso = (d) => d.toISOString().slice(0, 10);
+        return `${iso(freshness.From)}to${iso(freshness.To)}`;
+    }
+    toHit(item) {
+        const hit = {
+            Title: item.title ?? '',
+            URL: item.url ?? '',
+            Snippet: item.description ?? '',
+            DisplayURL: item.meta_url?.netloc ?? item.meta_url?.hostname ?? undefined,
+        };
+        if (item.page_age) {
+            const parsed = new Date(item.page_age);
+            if (!isNaN(parsed.getTime())) {
+                hit.PublishedAt = parsed;
+            }
+        }
+        // Brave's relative age string and extra snippets have no slot in the normalised shape,
+        // and they are part of why Brave is worth having — so they ride along here.
+        const extras = {};
+        if (item.age) {
+            extras.age = item.age;
+        }
+        if (item.extra_snippets?.length) {
+            extras.extraSnippets = item.extra_snippets;
+        }
+        if (Object.keys(extras).length > 0) {
+            hit.ProviderExtras = extras;
+        }
+        return hit;
+    }
+};
+BraveWebSearchProvider = BraveWebSearchProvider_1 = __decorate([
+    RegisterClass(BaseWebSearchProvider, 'BraveWebSearchProvider')
+], BraveWebSearchProvider);
+export { BraveWebSearchProvider };
+/** Anti-tree-shaking anchor — importing this module is what runs the @RegisterClass decorator. */
+export function LoadBraveWebSearchProvider() {
+    void BraveWebSearchProvider;
+}
+//# sourceMappingURL=BraveWebSearchProvider.js.map

package/dist/providers/BraveWebSearchProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BraveWebSearchProvider.js","sourceRoot":"","sources":["../../src/providers/BraveWebSearchProvider.ts"],"names":[],"mappings":"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"}

package/dist/providers/DuckDuckGoWebSearchProvider.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview DuckDuckGo driver — keyless last resort.
+ * @module @memberjunction/web-search-engine
+ */
+import { UserInfo } from '@memberjunction/core';
+import { BaseWebSearchProvider } from '../BaseWebSearchProvider.js';
+import { WebSearchCapabilities, WebSearchParams, WebSearchProviderResponse } from '../types.js';
+/**
+ * Searches through DuckDuckGo's Instant Answer API.
+ *
+ * **This is a last resort, and it is ordered last for good reasons.** The Instant Answer API is
+ * not a web search API: it returns disambiguation topics and an abstract, not a ranked result
+ * set, so it answers only a minority of queries and returns nothing at all for many ordinary
+ * ones. It also rate-limits aggressively and without documentation.
+ *
+ * It earns its place because it needs **no credential**, so a host that has configured nothing
+ * still gets some web capability rather than a hard failure. Treat a deployment that relies on
+ * it as unconfigured, not as working — configure Brave or Tavily for real coverage.
+ *
+ * ## Why there is no HTML fallback
+ *
+ * An earlier version fell back to fetching and regex-parsing DuckDuckGo's HTML results page,
+ * which answered far more queries. It was removed deliberately: running regular expressions over
+ * remote HTML is running them over **attacker-influenceable input**, and the parser carried two
+ * high-severity findings — polynomial backtracking in the result patterns (the `[^"]*…[^"]*`
+ * shape) and incomplete sanitization in its tag-stripping.
+ *
+ * Hardening those patterns would have narrowed the surface; deleting the parser removes it. For a
+ * fallback *inside* a last-resort provider that this engine already tells operators not to rely
+ * on, the capability was not worth the exposure — and "the regex looks safe now" is exactly the
+ * kind of claim that is true when written and wrong later. Anything needing real web coverage
+ * should configure a provider with an API.
+ */
+export declare class DuckDuckGoWebSearchProvider extends BaseWebSearchProvider {
+    private static readonly ENDPOINT;
+    readonly Capabilities: WebSearchCapabilities;
+    /** Keyless, so always available — which is the entire reason it is the fallback. */
+    CheckAvailability(_contextUser: UserInfo): Promise<void>;
+    ExecuteSearch(params: WebSearchParams, _contextUser: UserInfo): Promise<WebSearchProviderResponse>;
+    /** RelatedTopics nests one level for disambiguation groups; flatten to a single list. */
+    private flattenTopics;
+}
+/** Anti-tree-shaking anchor. */
+export declare function LoadDuckDuckGoWebSearchProvider(): void;
+//# sourceMappingURL=DuckDuckGoWebSearchProvider.d.ts.map

package/dist/providers/DuckDuckGoWebSearchProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DuckDuckGoWebSearchProvider.d.ts","sourceRoot":"","sources":["../../src/providers/DuckDuckGoWebSearchProvider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAgB,eAAe,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAgB3G;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBACa,2BAA4B,SAAQ,qBAAqB;IAClE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAEjE,SAAgB,YAAY,EAAE,qBAAqB,CAMjD;IAEF,oFAAoF;IACvE,iBAAiB,CAAC,YAAY,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD,aAAa,CACtB,MAAM,EAAE,eAAe,EACvB,YAAY,EAAE,QAAQ,GACvB,OAAO,CAAC,yBAAyB,CAAC;IAgCrC,yFAAyF;IACzF,OAAO,CAAC,aAAa;CAmBxB;AAED,gCAAgC;AAChC,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD"}

package/dist/providers/DuckDuckGoWebSearchProvider.js

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview DuckDuckGo driver — keyless last resort.
+ * @module @memberjunction/web-search-engine
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var DuckDuckGoWebSearchProvider_1;
+import { RegisterClass } from '@memberjunction/global';
+import { HttpGet } from '@memberjunction/network-utils';
+import { BaseWebSearchProvider } from '../BaseWebSearchProvider.js';
+import { classifyHttpFailure, failure } from './httpFailure.js';
+/**
+ * Searches through DuckDuckGo's Instant Answer API.
+ *
+ * **This is a last resort, and it is ordered last for good reasons.** The Instant Answer API is
+ * not a web search API: it returns disambiguation topics and an abstract, not a ranked result
+ * set, so it answers only a minority of queries and returns nothing at all for many ordinary
+ * ones. It also rate-limits aggressively and without documentation.
+ *
+ * It earns its place because it needs **no credential**, so a host that has configured nothing
+ * still gets some web capability rather than a hard failure. Treat a deployment that relies on
+ * it as unconfigured, not as working — configure Brave or Tavily for real coverage.
+ *
+ * ## Why there is no HTML fallback
+ *
+ * An earlier version fell back to fetching and regex-parsing DuckDuckGo's HTML results page,
+ * which answered far more queries. It was removed deliberately: running regular expressions over
+ * remote HTML is running them over **attacker-influenceable input**, and the parser carried two
+ * high-severity findings — polynomial backtracking in the result patterns (the `[^"]*…[^"]*`
+ * shape) and incomplete sanitization in its tag-stripping.
+ *
+ * Hardening those patterns would have narrowed the surface; deleting the parser removes it. For a
+ * fallback *inside* a last-resort provider that this engine already tells operators not to rely
+ * on, the capability was not worth the exposure — and "the regex looks safe now" is exactly the
+ * kind of claim that is true when written and wrong later. Anything needing real web coverage
+ * should configure a provider with an API.
+ */
+let DuckDuckGoWebSearchProvider = class DuckDuckGoWebSearchProvider extends BaseWebSearchProvider {
+    constructor() {
+        super(...arguments);
+        this.Capabilities = {
+            Answer: false,
+            DomainFilter: false,
+            Freshness: false,
+            Region: false,
+            MaxResultsCap: 30,
+        };
+    }
+    static { DuckDuckGoWebSearchProvider_1 = this; }
+    static { this.ENDPOINT = 'https://api.duckduckgo.com/'; }
+    /** Keyless, so always available — which is the entire reason it is the fallback. */
+    async CheckAvailability(_contextUser) {
+        this.MarkAvailable();
+    }
+    async ExecuteSearch(params, _contextUser) {
+        try {
+            const response = await HttpGet(DuckDuckGoWebSearchProvider_1.ENDPOINT, {
+                Query: { q: params.Query, format: 'json', no_html: 1, skip_disambig: 1 },
+                Timeout: 15000,
+            });
+            if (!response.Data) {
+                return failure('transient', 'Empty response from DuckDuckGo.');
+            }
+            const maxResults = this.ResolveMaxResults(params.MaxResults);
+            const hits = this.flattenTopics(response.Data.RelatedTopics ?? []);
+            // The abstract, when present, is the most relevant thing DDG returns — it leads.
+            if (response.Data.AbstractText && response.Data.AbstractURL) {
+                hits.unshift({
+                    Title: response.Data.Heading ?? params.Query,
+                    URL: response.Data.AbstractURL,
+                    Snippet: response.Data.AbstractText,
+                });
+            }
+            // Zero hits is common here and is reported honestly rather than escalated: the engine
+            // treats it as a successful empty answer, so a caller that needs coverage sees the
+            // gap instead of a failure it might retry.
+            return { Success: true, Hits: hits.slice(0, maxResults) };
+        }
+        catch (e) {
+            return classifyHttpFailure(e, 'DuckDuckGo');
+        }
+    }
+    /** RelatedTopics nests one level for disambiguation groups; flatten to a single list. */
+    flattenTopics(topics) {
+        const hits = [];
+        for (const topic of topics) {
+            if (topic.Topics?.length) {
+                hits.push(...this.flattenTopics(topic.Topics));
+                continue;
+            }
+            if (topic.FirstURL && topic.Text) {
+                // DDG puts "Title - description" in one string; split on the first separator only.
+                const separator = topic.Text.indexOf(' - ');
+                hits.push({
+                    Title: separator > 0 ? topic.Text.slice(0, separator) : topic.Text,
+                    URL: topic.FirstURL,
+                    Snippet: separator > 0 ? topic.Text.slice(separator + 3) : topic.Text,
+                });
+            }
+        }
+        return hits;
+    }
+};
+DuckDuckGoWebSearchProvider = DuckDuckGoWebSearchProvider_1 = __decorate([
+    RegisterClass(BaseWebSearchProvider, 'DuckDuckGoWebSearchProvider')
+], DuckDuckGoWebSearchProvider);
+export { DuckDuckGoWebSearchProvider };
+/** Anti-tree-shaking anchor. */
+export function LoadDuckDuckGoWebSearchProvider() {
+    void DuckDuckGoWebSearchProvider;
+}
+//# sourceMappingURL=DuckDuckGoWebSearchProvider.js.map

package/dist/providers/DuckDuckGoWebSearchProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DuckDuckGoWebSearchProvider.js","sourceRoot":"","sources":["../../src/providers/DuckDuckGoWebSearchProvider.ts"],"names":[],"mappings":"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"}

package/dist/providers/GoogleCustomSearchWebSearchProvider.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Google Custom Search driver — retiring 2027-01-01.
+ * @module @memberjunction/web-search-engine
+ */
+import { UserInfo } from '@memberjunction/core';
+import { BaseWebSearchProvider } from '../BaseWebSearchProvider.js';
+import { WebSearchCapabilities, WebSearchParams, WebSearchProviderResponse } from '../types.js';
+/**
+ * Searches through the Google Custom Search JSON API.
+ *
+ * **This provider has an end date.** Google closed the API to new customers during 2025 and
+ * discontinues it on **2027-01-01**. It ships so that hosts already holding a key keep working
+ * through the transition, and it is ordered behind Brave and Tavily deliberately.
+ *
+ * It needs no dated code change to retire: once Google stops serving, calls fail, the engine
+ * fails over, and removing the metadata row takes it out of rotation entirely. A host that
+ * never had a key sees `CheckAvailability` self-disable it on the first config, which is the
+ * ordinary "not configured here" path rather than an error.
+ *
+ * Credential keys `apiKey` and `cx`; environment fallbacks `GOOGLE_CUSTOM_SEARCH_API_KEY`
+ * and `GOOGLE_CUSTOM_SEARCH_CX`.
+ */
+export declare class GoogleCustomSearchWebSearchProvider extends BaseWebSearchProvider {
+    private static readonly ENDPOINT;
+    readonly Capabilities: WebSearchCapabilities;
+    private apiKey;
+    private cx;
+    CheckAvailability(_contextUser: UserInfo): Promise<void>;
+    ExecuteSearch(params: WebSearchParams, _contextUser: UserInfo): Promise<WebSearchProviderResponse>;
+    /** Google expresses recency as `d7`, `w2`, `m3`, `y1`. */
+    private mapFreshness;
+    private toHit;
+}
+/** Anti-tree-shaking anchor. */
+export declare function LoadGoogleCustomSearchWebSearchProvider(): void;
+//# sourceMappingURL=GoogleCustomSearchWebSearchProvider.d.ts.map

package/dist/providers/GoogleCustomSearchWebSearchProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GoogleCustomSearchWebSearchProvider.d.ts","sourceRoot":"","sources":["../../src/providers/GoogleCustomSearchWebSearchProvider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAgB,eAAe,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAe3G;;;;;;;;;;;;;;GAcG;AACH,qBACa,mCAAoC,SAAQ,qBAAqB;IAC1E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAgD;IAEhF,SAAgB,YAAY,EAAE,qBAAqB,CAOjD;IAEF,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,EAAE,CAAqB;IAElB,iBAAiB,CAAC,YAAY,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxD,aAAa,CACtB,MAAM,EAAE,eAAe,EACvB,YAAY,EAAE,QAAQ,GACvB,OAAO,CAAC,yBAAyB,CAAC;IA4CrC,0DAA0D;IAC1D,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,KAAK;CAQhB;AAED,gCAAgC;AAChC,wBAAgB,uCAAuC,IAAI,IAAI,CAE9D"}