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

package/LICENSE

@@ -0,0 +1,183 @@
+Business Source License 1.1
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Blue Cypress, Inc.
+
+Licensed Work:        MemberJunction.
+                      The Licensed Work is (c) 2023-2026 Blue Cypress, Inc.
+
+Additional Use Grant: Subject to the terms of this License, Licensor grants
+                      you the following additional rights to make Production
+                      Use of the Licensed Work.
+
+                      1. Internal Use
+
+                      You may make production use of the Licensed Work for
+                      your own internal business or organizational operations.
+
+                      2. Nonprofit Use
+
+                      If you are a Nonprofit, you may make production use of
+                      the Licensed Work for the operations and activities of
+                      your Organizational Family.
+
+                      3. MemberJunction Certified Program Use
+
+                      If you are authorized by Licensor under the
+                      MemberJunction Certified Program to provide professional
+                      services using the Licensed Work, you may make
+                      production use of the Licensed Work in providing such
+                      professional services to a client, provided that:
+
+                      (a) the Licensed Work is deployed in, and the applicable
+                      production use occurs within, an environment owned,
+                      leased, licensed, subscribed to, or otherwise controlled
+                      by that client; and
+
+                      (b) the production use is for that client's own internal
+                      business or organizational operations or is otherwise
+                      independently permitted to that client under this
+                      Additional Use Grant.
+
+                      4. Definitions Applicable to the Additional Use Grant
+
+                      "Affiliate" means, with respect to a specified Person,
+                      any other Person that directly or indirectly Controls,
+                      is Controlled by, or is under common Control with such
+                      specified Person.
+
+                      "Control" (including the terms "Controls," "Controlled
+                      by," and "under common Control with") means the direct
+                      or indirect possession of the power to direct or cause
+                      the direction of the management and policies of a
+                      Person, whether through ownership of voting interests,
+                      by contract, or otherwise.
+
+                      "Organizational Family" means, with respect to a Person,
+                      (a) such Person and its Affiliates, and (b) any
+                      nonprofit organization, governmental entity, chapter,
+                      division, local affiliate, regional affiliate, state
+                      affiliate, national affiliate, or other entity that is
+                      formally affiliated with such Person through governing
+                      documents, a charter, bylaws, a membership agreement, or
+                      another written organizational instrument, and is
+                      recognized under such documents as part of the same
+                      organizational structure.
+
+                      "Nonprofit" means a Person recognized by the Internal
+                      Revenue Service as exempt from federal income taxation
+                      under Section 501(c)(3), 501(c)(4), 501(c)(5), or
+                      501(c)(6) of the Internal Revenue Code, or a foreign
+                      organization recognized under substantially equivalent
+                      laws.
+
+                      A Person claiming eligibility as a Nonprofit shall, upon
+                      Licensor's reasonable request, provide documentation
+                      reasonably sufficient to demonstrate that it qualifies
+                      as a Nonprofit. If such Person materially misrepresents,
+                      or is unable to demonstrate, its qualification as a
+                      Nonprofit, the rights granted to such Person under
+                      Section 2 of this Additional Use Grant shall terminate.
+
+                      "MemberJunction Certified Program" means Licensor's
+                      then-current program for certifying and authorizing a
+                      Person to provide professional services using the
+                      Licensed Work.
+
+                      "Person" means any individual, corporation, limited
+                      liability company, partnership, association, nonprofit
+                      organization, governmental entity, or other legal or
+                      organizational entity.
+
+Change Date:          Four (4) years from the date the Licensed Work is first
+                      made available.
+
+Change License:       MIT License.
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Blue Cypress, Inc.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/README.md

@@ -1,4 +1,344 @@
 # @memberjunction/web-search-engine
-Seed release published over OIDC to prove trusted publishing is configured for
-this package. It contains no code and is tagged `seed`, never `latest`.
-Real releases are published by .github/workflows/publish.yml.
+
+Metadata-driven **web search** for MemberJunction: a set of external search vendors behind one
+interface, with administrator-controlled priority and automatic failover.
+
+The administrator picks the vendor. The agent never does.
+
+```typescript
+import { WebSearchEngine } from '@memberjunction/web-search-engine';
+
+await WebSearchEngine.Instance.Config(false, contextUser);
+const result = await WebSearchEngine.Instance.Search({ Query: 'association management trends' }, contextUser);
+
+if (result.Success) {
+  for (const hit of result.Hits) console.log(hit.Title, hit.URL);
+  console.log('served by', result.ProviderUsed);
+}
+```
+
+---
+
+## Why this exists
+
+Google discontinues the Custom Search JSON API on **2027-01-01** and has already closed it to new
+customers. Microsoft retired the Bing Search APIs on **2025-08-11**. Both replaced a commodity SERP
+API with an answer-shaped grounding product locked to their own agent stack. Selling raw ranked web
+results to developers is a business both companies have chosen to exit.
+
+The lesson is not "pick a different vendor". It is that **any single web-search dependency has an
+expiry date**, so the architecture has to make the next shutdown a configuration change.
+
+Before this package, MJ had four independent web-search Actions — Google, Tavily, Perplexity,
+DuckDuckGo — with three incompatible output contracts (`Items`, `Results`, `Content`). Nothing could
+transparently fall back onto a different shape, so "Perplexity as a backup" was never actually a
+backup. Swapping vendors meant editing every agent that named one.
+
+Now it is a row in a table.
+
+---
+
+## How it differs from `@memberjunction/search-engine`
+
+They sound alike and are not interchangeable. **`search-engine` searches content MJ owns**;
+this package searches the open web.
+
+|  | `search-engine` | `web-search-engine` |
+|---|---|---|
+| Searches | entity records, vectors, full-text, storage files | the public web, via external vendors |
+| Result identity | `EntityName` + `RecordID` — a row you can open | a URL |
+| Result type | `SearchResultItem` | `WebSearchHit` |
+| Multiple sources | queried **together**, fused with RRF | tried **in order**, first success wins |
+| Cost per query | a database query | real money at a vendor |
+| Failure mode | a slow query | a rate limit, an expired key, a discontinued API |
+| Provider table | `__mj.SearchProvider` | `__mj.WebSearchProvider` |
+
+The decisive detail is the result contract: `SearchResultItem` **requires** `ID`, `EntityName` and
+`RecordID` — the primary key of a source record — and the pipeline ends in `SearchEnricher`, which
+resolves entity icons and record display names by entity lookup. A web hit has none of those.
+Fitting one in would mean lying in the type and dragging it through enrichment designed to decorate
+entity records.
+
+What the two **do** share is the plugin pattern, and this package reuses all of it: a provider table
+carrying `DriverClass` / `Priority` / `Status` / `CredentialID`, ClassFactory resolution, and the
+`Initialize()` → `CheckAvailability()` → `IsAvailable()` lifecycle.
+
+> **Blending the two** — web results and internal records in one ranked list — is reachable through
+> the existing RRF fusion, but it needs a result type that does not require `EntityName`. That is a
+> deliberate future step, not a side effect of this package.
+
+---
+
+## Three ways in
+
+Pick by who is calling.
+
+| Caller | Use | Why |
+|---|---|---|
+| Server-side TypeScript | `WebSearchEngine.Instance.Search()` | Direct, typed, no indirection |
+| Browser / Angular | the `WebSearch.Query` Remote Operation | Keys never leave the server; typed end to end |
+| An AI agent | the `Web Search` **Action** | Discoverable from metadata, one tool instead of four |
+
+All three land in the same engine and obey the same provider configuration.
+
+---
+
+## Who uses this
+
+**No agent or skill binds a search vendor directly.** Every agent and skill that does web lookups — including the `Web Research` skill — binds the provider-neutral `Web Search` Action, and leaves `Provider` unset so the engine can fail over.
+
+`Google Custom Search` and `Perplexity Search` remain registered for direct or manual execution, but carry **no agent or skill bindings**. Anything new binds `Web Search`, never a vendor.
+
+Verify at any time:
+```bash
+grep -rn "Google Custom Search\|Perplexity Search" metadata/agents/ metadata/ai-skills/
+# no output = no vendor bindings remain
+```
+
+---
+
+## Selection: how a provider is chosen
+
+### Without an explicit provider
+
+1. Filter to providers that are `Active`, report themselves available, and can do what was asked
+2. Order by `Priority` **ascending — lower wins**
+3. Try each in turn until one succeeds
+
+Failover is **conditional**, and the condition is the part that matters:
+
+| Failure | Engine does | Why |
+|---|---|---|
+| `transient` — rate limit, 5xx, timeout, bad key | try the next provider | another vendor may well succeed |
+| `permanent` — the request itself is rejected | **stop** | every other vendor will reject it too; retrying costs four more paid calls and buries the real error behind four identical ones |
+
+**Zero hits is a success.** A narrow query legitimately matches nothing. Treating that as failure
+makes the engine retry a query that will keep returning nothing, at four vendors' expense.
+
+### With an explicit provider
+
+`Provider` pins the search to one vendor, by `Name` or `DriverClass`, case-insensitively. There is
+**no failover** — the call fails, with a code that says exactly why:
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `PROVIDER_NOT_FOUND` | no such provider in metadata | add the row |
+| `PROVIDER_NOT_ACTIVE` | the row exists, `Status` is not `Active` | flip the status |
+| `PROVIDER_UNAVAILABLE` | Active, but not operational — usually no credential | set the key |
+| `PROVIDER_LACKS_CAPABILITY` | e.g. `IncludeAnswer` on a hits-only provider | ask a different provider, or drop the flag |
+
+Those are four different problems with four different fixes, which is why they are four codes and
+not one. And the reason a pinned provider never silently falls back: a substitution is invisible.
+Results keep arriving, from a vendor nobody chose, until something eventually surfaces it — usually
+an invoice.
+
+### `Attempts` — read this one
+
+Every provider tried is recorded in `result.Attempts`, **including on the success path**.
+
+If the primary provider rate-limits every call and the secondary quietly serves everything, the
+system looks completely healthy. Nothing else makes that visible while the spend moves to a vendor
+nobody selected.
+
+```typescript
+const result = await WebSearchEngine.Instance.Search({ Query: 'q' }, user);
+// result.ProviderUsed === 'Tavily'
+// result.Attempts === [
+//   { ProviderName: 'Brave',  Succeeded: false, FailureKind: 'transient', ErrorMessage: '429 …' },
+//   { ProviderName: 'Tavily', Succeeded: true,  HitCount: 10 },
+// ]
+```
+
+---
+
+## Configuring providers
+
+Rows live in `__mj.WebSearchProvider`, seeded from `metadata/web-search-providers/`.
+
+| Column | Purpose |
+|---|---|
+| `Name` | Admin-facing name, and what `Provider` matches. Unique |
+| `DriverClass` | ClassFactory key — `@RegisterClass(BaseWebSearchProvider, …)` |
+| `Status` | `Pending` / `Active` / `Terminated`. Only `Active` loads |
+| `Priority` | **Lower is tried first** |
+| `CredentialID` | FK to `Credential`; falls back to an env var when null |
+| `ProviderConfig` | JSON of non-secret driver settings |
+| `MaxResultsOverride` | Per-provider cap for pay-per-query vendors |
+| `AllowResultCaching` | Defaults to **0**. See *Caching rights*, below |
+| `DisplayName` / `Icon` / `Comments` | Admin UI and notes |
+
+**Capabilities are not columns.** Whether a driver can synthesize an answer or honour a domain
+filter is a property of the *implementation*, declared on the class — exactly as `search-engine`
+declares `SourceType`. The table holds configuration: on/off, order, credentials, limits.
+
+To change the primary vendor, edit one row's `Priority` and run `mj sync push`. No code change, no
+agent change, no redeploy.
+
+### Bundled drivers
+
+| Driver | Default priority | Answer | Notes |
+|---|---|---|---|
+| `BraveWebSearchProvider` | 10 | no | **Own index** — not a Google or Bing reseller, so it fails independently of everything else here. Default primary |
+| `TavilyWebSearchProvider` | 20 | yes | Returns extracted page content rather than snippets plus links. Aggregator |
+| `PerplexityWebSearchProvider` | 30 | yes | Hits from the raw `/search` endpoint; Sonar only when an answer is asked for |
+| `GoogleCustomSearchWebSearchProvider` | 40 | no | **Discontinued 2027-01-01.** Present so existing keys keep working through the transition |
+| `DuckDuckGoWebSearchProvider` | 90 | no | Keyless last resort, Instant Answer API only. Answers a minority of queries — treat reliance on it as *unconfigured*. No HTML fallback, [by design](#why-duckduckgo-has-no-html-fallback) |
+
+### Why DuckDuckGo has no HTML fallback
+
+An earlier revision fell back to fetching and regex-parsing DuckDuckGo's HTML results page, which
+answered far more queries than the Instant Answer API does. It was removed deliberately.
+
+Running regular expressions over remote HTML is running them over **attacker-influenceable input**,
+and CodeQL flagged the parser with 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 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.
+
+**If you need real web coverage, configure a provider with an API.** That is what the rest of this
+package is for.
+
+### Credentials
+
+Each driver reads its key from the linked `Credential` record first, then falls back to an
+environment variable:
+
+| Driver | Credential key(s) | Environment fallback |
+|---|---|---|
+| Brave | `apiKey` | `BRAVE_SEARCH_API_KEY` |
+| Tavily | `apiKey` | `TAVILY_API_KEY` |
+| Perplexity | `apiKey` | `PERPLEXITY_API_KEY` |
+| Google Custom Search | `apiKey`, `cx` | `GOOGLE_CUSTOM_SEARCH_API_KEY`, `GOOGLE_CUSTOM_SEARCH_CX` |
+| DuckDuckGo | — | — |
+
+The fallback exists so a host upgrading from the per-vendor Actions does not have to migrate its
+secrets into the Credential store on the same day it gains the engine.
+
+A driver with no key **self-disables** rather than throwing. An unconfigured vendor is a normal
+state in a product shipped to many hosts, not an error — the engine simply routes around it.
+
+### ⚠️ Caching rights
+
+`AllowResultCaching` defaults to `0`, and that default is deliberate.
+
+Caching rights differ sharply between vendors: some sell result storage as a distinct plan tier,
+others forbid persistent caching outright, and at least one major grounding product's terms prohibit
+caching, syndicating or analysing results at all. Violating any of it is **silent** — nothing fails,
+you are simply in breach.
+
+Nothing in this engine caches today. The column exists so that the first caching layer reads a
+per-provider gate instead of inventing one, and so the contractual answer lives next to the
+credential it applies to. **Confirm your plan's terms before setting it to 1.**
+
+---
+
+## Writing a driver
+
+```typescript
+import { RegisterClass } from '@memberjunction/global';
+import { BaseWebSearchProvider, WebSearchCapabilities } from '@memberjunction/web-search-engine';
+
+@RegisterClass(BaseWebSearchProvider, 'AcmeWebSearchProvider')
+export class AcmeWebSearchProvider extends BaseWebSearchProvider {
+  public readonly Capabilities: WebSearchCapabilities = {
+    Answer: false, DomainFilter: true, Freshness: true, Region: true, MaxResultsCap: 25,
+  };
+
+  private apiKey: string | undefined;
+
+  public async CheckAvailability(): Promise<void> {
+    this.apiKey = this.GetSecret('apiKey', 'ACME_API_KEY');
+    this.apiKey ? this.MarkAvailable() : this.MarkUnavailable('No Acme API key.');
+  }
+
+  public async ExecuteSearch(params: WebSearchParams): Promise<WebSearchProviderResponse> {
+    try {
+      const response = await HttpGet<AcmeResponse>(ENDPOINT, { /* … */ });
+      return { Success: true, Hits: (response.Data?.results ?? []).map(toHit) };
+    } catch (e) {
+      return classifyHttpFailure(e, 'Acme');   // sets FailureKind for you
+    }
+  }
+}
+```
+
+Four rules, each of which has a failure mode if ignored:
+
+1. **Declare capabilities honestly.** Claiming `DomainFilter: true` and then ignoring the filter
+   returns confident results for a different question than the one asked.
+2. **Classify failures correctly.** `classifyHttpFailure` handles the common cases; the distinction
+   that matters is 400/422 (`permanent`) versus everything else (`transient`).
+3. **Self-disable, don't throw**, when the driver is simply not configured on this host.
+4. **Export a `Load…()` anchor** and call it from the package index. 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.
+
+---
+
+## Result codes
+
+| Code | `Success` | Meaning |
+|---|:---:|---|
+| `SUCCESS` | ✅ | Served. `Hits` may legitimately be empty |
+| `MISSING_QUERY` | ❌ | `Query` was blank |
+| `NO_PROVIDERS_CONFIGURED` | ❌ | No provider rows at all — a setup problem, not a search failure |
+| `PROVIDER_LOAD_FAILED` | ❌ | The provider list could not be **read** — query failed, entity missing from metadata, or no permission. Distinct from the row above on purpose: a failed read also leaves the list empty, and telling an operator to "add a record" when the read never succeeded sends them to fix configuration that is fine |
+| `NO_ELIGIBLE_PROVIDER` | ❌ | Providers exist, none is available and capable of this request |
+| `PROVIDER_NOT_FOUND` / `_NOT_ACTIVE` / `_UNAVAILABLE` / `_LACKS_CAPABILITY` | ❌ | An explicit `Provider` could not serve — see the table above |
+| `ALL_PROVIDERS_FAILED` | ❌ | Every eligible provider was tried; see `Attempts` |
+| `INVALID_REQUEST` | ❌ | The request itself was rejected; retrying elsewhere cannot help |
+
+`Search()` **never throws** for a search-level failure — branch on `Success`, as with `RunView`.
+Exceptions escaping a driver are caught, recorded as a transient attempt, and failed over.
+
+---
+
+## Setup after the migration
+
+The migration, its CodeGen tail and the Remote Operation's server half are all committed, so a
+local database only needs the schema applied and the metadata seeded:
+
+```bash
+pnpm run mj:migrate                  # creates __mj.WebSearchProvider
+pnpm mj sync push --dir metadata     # seeds the provider rows, the Action, the scopes
+pnpm install && pnpm run build
+```
+
+**Migrate before pushing metadata.** `metadata/web-search-providers/` writes into
+`__mj.WebSearchProvider`, so the table has to exist first. (A different ordering constraint —
+metadata before `mj codegen`, because remote operations generate from rows rather than schema —
+applies when regenerating, not when applying what is already committed.)
+
+Verify before committing:
+
+```bash
+node .github/scripts/check-migration-entityfield-sequence.mjs   # apply-time MAX(Sequence)+1, never a literal
+npm run check:codegen-tail                                      # generated entity/resolvers/form are committed
+```
+
+The PostgreSQL counterpart is **not** authored per-PR — conversion is build-engineer work at release
+time.
+
+---
+
+## Testing
+
+```bash
+cd packages/WebSearchEngine && pnpm test
+```
+
+The selection tests are the ones that matter. Each pins a property with a way of passing while
+broken: conditional failover, an explicit provider never being substituted, and `Attempts` being
+recorded on the **success** path.
+
+---
+
+## Related
+
+- [`guides/SEARCH_OVERVIEW_GUIDE.md`](../../guides/SEARCH_OVERVIEW_GUIDE.md) — which search API to reach for
+- [`@memberjunction/search-engine`](../SearchEngine) — internal search over content MJ owns
+- [`packages/Actions/CLAUDE.md`](../Actions/CLAUDE.md) — why the Action is a thin wrapper

package/dist/BaseWebSearchProvider.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Base class for web search drivers.
+ *
+ * Each driver wraps one external search vendor and normalises its response into
+ * {@link WebSearchHit}. Drivers are discovered at runtime via `@RegisterClass` and the
+ * `MJ: Web Search Providers` metadata entity, whose `DriverClass` column is the registration key.
+ *
+ * @module @memberjunction/web-search-engine
+ */
+import { UserInfo } from '@memberjunction/core';
+import { RegisteredWebSearchProviderInfo, WebSearchCapabilities, WebSearchParams, WebSearchProviderConfig, WebSearchProviderResponse } from './types.js';
+/**
+ * Abstract base for a web search driver.
+ *
+ * Subclasses register with `@RegisterClass(BaseWebSearchProvider, 'DriverClassName')` to become
+ * discoverable by {@link WebSearchEngine}.
+ *
+ * Lifecycle, per provider record, at engine config time:
+ * 1. `WebSearchEngine` loads Active `MJ: Web Search Providers` records
+ * 2. ClassFactory creates an instance from `DriverClass`
+ * 3. {@link Initialize} receives the record's configuration and any decrypted credential values
+ * 4. {@link CheckAvailability} verifies the driver is actually operational
+ * 5. If {@link IsAvailable} is true, the driver joins the selection pool
+ *
+ * A driver that cannot work — no API key, missing optional dependency — must **self-disable in
+ * `CheckAvailability` rather than throw**. An unconfigured vendor is a normal state in a product
+ * shipped to many hosts, not an error, and the engine simply routes around it.
+ */
+export declare abstract class BaseWebSearchProvider {
+    /** What this driver can do. Declared by the class, never read from the database. */
+    abstract readonly Capabilities: WebSearchCapabilities;
+    /** Configuration from the metadata record, set during {@link Initialize}. */
+    protected config: WebSearchProviderConfig | null;
+    private _available;
+    private _unavailableReason;
+    /**
+     * Receive configuration from the provider's metadata record.
+     *
+     * The default stores it; override to do additional setup, and call `super.Initialize(...)`.
+     */
+    Initialize(config: WebSearchProviderConfig, _contextUser: UserInfo): Promise<void>;
+    /**
+     * Determine whether this driver can serve requests, calling {@link MarkAvailable} or
+     * {@link MarkUnavailable} exactly once.
+     *
+     * Must not throw for the ordinary "not configured here" case — see the class note.
+     */
+    abstract CheckAvailability(contextUser: UserInfo): Promise<void>;
+    /** Whether this driver may participate in searches. False until `CheckAvailability` says otherwise. */
+    IsAvailable(): boolean;
+    /** Why this driver is unavailable, for diagnostics. Null when it is available. */
+    get UnavailableReason(): string | null;
+    /** Execute a search. Called only when {@link IsAvailable} is true. */
+    abstract ExecuteSearch(params: WebSearchParams, contextUser: UserInfo): Promise<WebSearchProviderResponse>;
+    /** Mark this driver operational. Call from {@link CheckAvailability}. */
+    protected MarkAvailable(): void;
+    /** Mark this driver unusable, with a reason an administrator can act on. */
+    protected MarkUnavailable(reason: string): void;
+    /**
+     * Read a credential value, preferring the decrypted `MJ: Credentials` record and falling back
+     * to an environment variable.
+     *
+     * The fallback exists because the web search actions this engine supersedes read their keys
+     * from `mj.config.cjs` / the environment, and a host upgrading should not have to migrate its
+     * secrets into the Credential store on the same day it gains the engine.
+     *
+     * @param credentialKey - key within the credential record's decrypted values, e.g. `apiKey`
+     * @param envVarName - environment variable consulted when no credential value is present
+     */
+    protected GetSecret(credentialKey: string, envVarName: string): string | undefined;
+    /** Read a non-secret setting from the record's `ProviderConfig` JSON. */
+    protected GetConfigValue<T>(key: string): T | undefined;
+    /**
+     * The effective result cap: the caller's request, bounded by the metadata override (when set)
+     * and then by the vendor's own hard cap.
+     *
+     * Clamped rather than rejected — a caller asking for 50 wants as many as possible, and most
+     * vendors reject the whole request when asked for more than they serve.
+     */
+    protected ResolveMaxResults(requested: number | undefined, fallback?: number): number;
+    /**
+     * Enumerate every registered driver with its capabilities, for admin UI dropdowns.
+     *
+     * Instantiates each registration to read `Capabilities`, so a driver's constructor must stay
+     * side-effect free.
+     */
+    static GetAvailableProviders(): RegisteredWebSearchProviderInfo[];
+}
+//# sourceMappingURL=BaseWebSearchProvider.d.ts.map

package/dist/BaseWebSearchProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseWebSearchProvider.d.ts","sourceRoot":"","sources":["../src/BaseWebSearchProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAY,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EACH,+BAA+B,EAC/B,qBAAqB,EACrB,eAAe,EACf,uBAAuB,EACvB,yBAAyB,EAC5B,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,qBAAqB;IACvC,oFAAoF;IACpF,kBAAyB,YAAY,EAAE,qBAAqB,CAAC;IAE7D,6EAA6E;IAC7E,SAAS,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAAQ;IAExD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,kBAAkB,CAAuB;IAEjD;;;;OAIG;IACU,UAAU,CAAC,MAAM,EAAE,uBAAuB,EAAE,YAAY,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/F;;;;;OAKG;aACa,iBAAiB,CAAC,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAEvE,uGAAuG;IAChG,WAAW,IAAI,OAAO;IAI7B,kFAAkF;IAClF,IAAW,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAE5C;IAED,sEAAsE;aACtD,aAAa,CACzB,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC,yBAAyB,CAAC;IAErC,yEAAyE;IACzE,SAAS,CAAC,aAAa,IAAI,IAAI;IAK/B,4EAA4E;IAC5E,SAAS,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK/C;;;;;;;;;;OAUG;IACH,SAAS,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IASlF,yEAAyE;IACzE,SAAS,CAAC,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAKvD;;;;;;OAMG;IACH,SAAS,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,SAAK,GAAG,MAAM;IAMjF;;;;;OAKG;WACW,qBAAqB,IAAI,+BAA+B,EAAE;CA+B3E"}