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

package/dist/BaseWebSearchProvider.js

@@ -0,0 +1,130 @@
+/**
+ * @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 { LogError } from '@memberjunction/core';
+import { MJGlobal } from '@memberjunction/global';
+/**
+ * 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 class BaseWebSearchProvider {
+    constructor() {
+        /** Configuration from the metadata record, set during {@link Initialize}. */
+        this.config = null;
+        this._available = false;
+        this._unavailableReason = null;
+    }
+    /**
+     * Receive configuration from the provider's metadata record.
+     *
+     * The default stores it; override to do additional setup, and call `super.Initialize(...)`.
+     */
+    async Initialize(config, _contextUser) {
+        this.config = config;
+    }
+    /** Whether this driver may participate in searches. False until `CheckAvailability` says otherwise. */
+    IsAvailable() {
+        return this._available;
+    }
+    /** Why this driver is unavailable, for diagnostics. Null when it is available. */
+    get UnavailableReason() {
+        return this._available ? null : this._unavailableReason;
+    }
+    /** Mark this driver operational. Call from {@link CheckAvailability}. */
+    MarkAvailable() {
+        this._available = true;
+        this._unavailableReason = null;
+    }
+    /** Mark this driver unusable, with a reason an administrator can act on. */
+    MarkUnavailable(reason) {
+        this._available = false;
+        this._unavailableReason = reason;
+    }
+    /**
+     * 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
+     */
+    GetSecret(credentialKey, envVarName) {
+        const fromCredential = this.config?.CredentialValues?.[credentialKey];
+        if (typeof fromCredential === 'string' && fromCredential.trim().length > 0) {
+            return fromCredential.trim();
+        }
+        const fromEnv = process.env[envVarName];
+        return fromEnv && fromEnv.trim().length > 0 ? fromEnv.trim() : undefined;
+    }
+    /** Read a non-secret setting from the record's `ProviderConfig` JSON. */
+    GetConfigValue(key) {
+        const value = this.config?.ProviderConfig?.[key];
+        return value === undefined ? undefined : value;
+    }
+    /**
+     * 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.
+     */
+    ResolveMaxResults(requested, fallback = 10) {
+        const asked = Math.floor(requested ?? this.config?.MaxResultsOverride ?? fallback);
+        const metadataCap = this.config?.MaxResultsOverride ?? Number.MAX_SAFE_INTEGER;
+        return Math.min(Math.max(asked, 1), metadataCap, this.Capabilities.MaxResultsCap);
+    }
+    /**
+     * 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() {
+        const registrations = MJGlobal.Instance.ClassFactory.GetAllRegistrations(BaseWebSearchProvider);
+        const result = [];
+        // The same class loaded through two module paths registers twice; dedupe by key so the
+        // admin dropdown does not show a driver more than once.
+        const seen = new Set();
+        for (const registration of registrations ?? []) {
+            const key = registration.Key;
+            if (!key || seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            try {
+                const instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseWebSearchProvider, key);
+                if (instance) {
+                    result.push({ DriverClass: key, Capabilities: instance.Capabilities });
+                }
+            }
+            catch (e) {
+                // One malformed registration must not blank the whole catalog the admin UI reads.
+                LogError(`BaseWebSearchProvider.GetAvailableProviders: could not instantiate "${key}"`, undefined, e);
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=BaseWebSearchProvider.js.map

package/dist/BaseWebSearchProvider.js.map

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

package/dist/WebSearchEngine.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Metadata-driven web search with priority failover.
+ *
+ * The engine loads Active `MJ: Web Search Providers` records, instantiates each one's driver via
+ * ClassFactory, and serves a search from the highest-priority driver that is available and capable.
+ *
+ * @module @memberjunction/web-search-engine
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { BaseSingleton } from '@memberjunction/global';
+import { RegisteredWebSearchProviderInfo, WebSearchParams, WebSearchResult } from './types.js';
+/**
+ * Singleton engine that routes a web search to a configured external provider.
+ *
+ * ## Selection
+ *
+ * **With an explicit `Provider`** the engine resolves it by `Name` or `DriverClass` and then
+ * fails closed with a specific code — it never substitutes another vendor. The caller asked for
+ * a particular thing; quietly serving something else turns a deliberate choice into an invisible
+ * one.
+ *
+ * **Without one** it filters to Active, available and capability-satisfying drivers, orders by
+ * `Priority` ascending, and tries each in turn. A `transient` failure (rate limit, 5xx, timeout)
+ * moves to the next driver; a `permanent` failure stops the run, because a request every
+ * provider will reject should not cost five paid API calls and bury its own error message.
+ *
+ * Zero hits is a **success**. A narrow query legitimately matches nothing, and treating that as
+ * failure makes the engine retry a query that will keep returning nothing.
+ *
+ * @example
+ * ```typescript
+ * await WebSearchEngine.Instance.Config(false, contextUser);
+ * const result = await WebSearchEngine.Instance.Search(
+ *     { Query: 'association management trends', MaxResults: 10 },
+ *     contextUser,
+ * );
+ * if (result.Success) {
+ *     for (const hit of result.Hits) console.log(hit.Title, hit.URL);
+ * }
+ * ```
+ */
+export declare class WebSearchEngine extends BaseSingleton<WebSearchEngine> {
+    /** Entity holding the provider records. */
+    private static readonly PROVIDER_ENTITY;
+    private _entries;
+    private _loaded;
+    /**
+     * Why the last provider load failed, or null if it succeeded. Held as state rather than
+     * only logged: the log line fires once, at load, while callers keep arriving afterwards —
+     * so without this the engine answers every later search with "nothing is configured" for
+     * what was a read failure.
+     */
+    private _loadError;
+    private _loading;
+    private _provider;
+    constructor();
+    static get Instance(): WebSearchEngine;
+    /** Providers currently loaded and available, in priority order. */
+    get AvailableProviders(): readonly {
+        Name: string;
+        DriverClass: string;
+        Priority: number;
+    }[];
+    /** Every registered driver with its capabilities, for admin UI. */
+    GetRegisteredDrivers(): RegisteredWebSearchProviderInfo[];
+    /**
+     * Load provider metadata and initialise every driver. Cheap no-op once loaded.
+     *
+     * Concurrent callers share one in-flight load rather than each issuing their own RunView —
+     * an agent fan-out can call `Config` from a dozen places in the same tick.
+     *
+     * @param forceRefresh - reload even if already configured (after an admin edits providers)
+     */
+    Config(forceRefresh: boolean, contextUser: UserInfo, provider?: IMetadataProvider): Promise<void>;
+    /**
+     * Run a web search.
+     *
+     * Never throws for a search-level failure — inspect `Success` and `ResultCode`, as with
+     * `RunView`. Exceptions escaping a driver are caught and recorded as attempts.
+     */
+    Search(params: WebSearchParams, contextUser: UserInfo): Promise<WebSearchResult>;
+    /** Try each candidate in order, honouring the transient/permanent distinction. */
+    private runCandidates;
+    /**
+     * Resolve an explicitly requested provider, or describe precisely why it cannot serve.
+     *
+     * Each rejection is a distinct code so a caller can tell "you never configured this" from
+     * "its key is missing" from "it cannot do answers" — three different fixes.
+     */
+    private resolveExplicit;
+    /** Providers that loaded but cannot serve, keyed by lowercased name and driver class. */
+    private _unavailable;
+    /** Eligible providers in priority order, or a failure describing why none qualified. */
+    private resolveByPriority;
+    private fail;
+    private summarise;
+    /** Load provider records, instantiate drivers, and keep the ones that are operational. */
+    private loadProviders;
+    /** Instantiate, configure and availability-check one provider record. */
+    private initializeProvider;
+    /** Remember why a configured provider is not serving, so an explicit request can say so. */
+    private recordUnavailable;
+    private parseProviderConfig;
+    /** Decrypt the linked credential, when one is set. Null when absent or unreadable. */
+    private resolveCredentialValues;
+}
+//# sourceMappingURL=WebSearchEngine.d.ts.map

package/dist/WebSearchEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSearchEngine.d.ts","sourceRoot":"","sources":["../src/WebSearchEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACH,iBAAiB,EAIjB,QAAQ,EACX,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,aAAa,EAAY,MAAM,wBAAwB,CAAC;AAEjE,OAAO,EACH,+BAA+B,EAE/B,eAAe,EAEf,eAAe,EAElB,MAAM,SAAS,CAAC;AAgBjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,eAAgB,SAAQ,aAAa,CAAC,eAAe,CAAC;IAC/D,2CAA2C;IAC3C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAA8B;IAErE,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,OAAO,CAAS;IACxB;;;;;OAKG;IACH,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,SAAS,CAAgC;;IAOjD,WAAkB,QAAQ,IAAI,eAAe,CAE5C;IAED,mEAAmE;IACnE,IAAW,kBAAkB,IAAI,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAElG;IAED,mEAAmE;IAC5D,oBAAoB,IAAI,+BAA+B,EAAE;IAIhE;;;;;;;OAOG;IACU,MAAM,CACf,YAAY,EAAE,OAAO,EACrB,WAAW,EAAE,QAAQ,EACrB,QAAQ,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,IAAI,CAAC;IAkBhB;;;;;OAKG;IACU,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,eAAe,CAAC;IAgD7F,kFAAkF;YACpE,aAAa;IA6E3B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IA+BvB,yFAAyF;IACzF,OAAO,CAAC,YAAY,CAAmC;IAEvD,wFAAwF;IACxF,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,IAAI;IAUZ,OAAO,CAAC,SAAS;IAOjB,0FAA0F;YAC5E,aAAa;IAgD3B,yEAAyE;YAC3D,kBAAkB;IAmEhC,4FAA4F;IAC5F,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,mBAAmB;IAa3B,sFAAsF;YACxE,uBAAuB;CA6BxC"}

package/dist/WebSearchEngine.js

@@ -0,0 +1,396 @@
+/**
+ * @fileoverview Metadata-driven web search with priority failover.
+ *
+ * The engine loads Active `MJ: Web Search Providers` records, instantiates each one's driver via
+ * ClassFactory, and serves a search from the highest-priority driver that is available and capable.
+ *
+ * @module @memberjunction/web-search-engine
+ */
+import { LogError, LogStatus, RunView, } from '@memberjunction/core';
+import { CredentialEngine } from '@memberjunction/credentials';
+import { BaseSingleton, MJGlobal } from '@memberjunction/global';
+import { BaseWebSearchProvider } from './BaseWebSearchProvider.js';
+/**
+ * Singleton engine that routes a web search to a configured external provider.
+ *
+ * ## Selection
+ *
+ * **With an explicit `Provider`** the engine resolves it by `Name` or `DriverClass` and then
+ * fails closed with a specific code — it never substitutes another vendor. The caller asked for
+ * a particular thing; quietly serving something else turns a deliberate choice into an invisible
+ * one.
+ *
+ * **Without one** it filters to Active, available and capability-satisfying drivers, orders by
+ * `Priority` ascending, and tries each in turn. A `transient` failure (rate limit, 5xx, timeout)
+ * moves to the next driver; a `permanent` failure stops the run, because a request every
+ * provider will reject should not cost five paid API calls and bury its own error message.
+ *
+ * Zero hits is a **success**. A narrow query legitimately matches nothing, and treating that as
+ * failure makes the engine retry a query that will keep returning nothing.
+ *
+ * @example
+ * ```typescript
+ * await WebSearchEngine.Instance.Config(false, contextUser);
+ * const result = await WebSearchEngine.Instance.Search(
+ *     { Query: 'association management trends', MaxResults: 10 },
+ *     contextUser,
+ * );
+ * if (result.Success) {
+ *     for (const hit of result.Hits) console.log(hit.Title, hit.URL);
+ * }
+ * ```
+ */
+export class WebSearchEngine extends BaseSingleton {
+    /** Entity holding the provider records. */
+    static { this.PROVIDER_ENTITY = 'MJ: Web Search Providers'; }
+    // Constructor must be public to satisfy BaseSingleton.getInstance()
+    constructor() {
+        super();
+        this._entries = [];
+        this._loaded = false;
+        /**
+         * Why the last provider load failed, or null if it succeeded. Held as state rather than
+         * only logged: the log line fires once, at load, while callers keep arriving afterwards —
+         * so without this the engine answers every later search with "nothing is configured" for
+         * what was a read failure.
+         */
+        this._loadError = null;
+        this._loading = null;
+        /** Providers that loaded but cannot serve, keyed by lowercased name and driver class. */
+        this._unavailable = new Map();
+    }
+    static get Instance() {
+        return WebSearchEngine.getInstance();
+    }
+    /** Providers currently loaded and available, in priority order. */
+    get AvailableProviders() {
+        return this._entries.map((e) => ({ Name: e.Name, DriverClass: e.DriverClass, Priority: e.Priority }));
+    }
+    /** Every registered driver with its capabilities, for admin UI. */
+    GetRegisteredDrivers() {
+        return BaseWebSearchProvider.GetAvailableProviders();
+    }
+    /**
+     * Load provider metadata and initialise every driver. Cheap no-op once loaded.
+     *
+     * Concurrent callers share one in-flight load rather than each issuing their own RunView —
+     * an agent fan-out can call `Config` from a dozen places in the same tick.
+     *
+     * @param forceRefresh - reload even if already configured (after an admin edits providers)
+     */
+    async Config(forceRefresh, contextUser, provider) {
+        if (provider) {
+            this._provider = provider;
+        }
+        if (this._loaded && !forceRefresh) {
+            return;
+        }
+        if (this._loading && !forceRefresh) {
+            return this._loading;
+        }
+        this._loading = this.loadProviders(contextUser);
+        try {
+            await this._loading;
+        }
+        finally {
+            this._loading = null;
+        }
+    }
+    /**
+     * Run a web search.
+     *
+     * Never throws for a search-level failure — inspect `Success` and `ResultCode`, as with
+     * `RunView`. Exceptions escaping a driver are caught and recorded as attempts.
+     */
+    async Search(params, contextUser) {
+        const attempts = [];
+        const query = params.Query?.trim();
+        if (!query) {
+            return this.fail({ code: 'MISSING_QUERY', message: 'Query is required.' }, attempts);
+        }
+        await this.Config(false, contextUser);
+        // Checked BEFORE the empty-list branch: a failed read also leaves the list empty, and
+        // reporting that as "add a record" sends an operator to fix configuration that is fine.
+        if (this._loadError) {
+            return this.fail({
+                code: 'PROVIDER_LOAD_FAILED',
+                message: `Could not read "${WebSearchEngine.PROVIDER_ENTITY}": ${this._loadError}. ` +
+                    'This is a read failure, not a missing configuration — check that the entity ' +
+                    'exists in metadata and that the caller can read it.',
+            }, attempts);
+        }
+        if (this._entries.length === 0) {
+            return this.fail({
+                code: 'NO_PROVIDERS_CONFIGURED',
+                message: 'No web search providers are configured. Add an Active record to ' +
+                    `"${WebSearchEngine.PROVIDER_ENTITY}" whose DriverClass matches a registered driver.`,
+            }, attempts);
+        }
+        const candidates = params.Provider
+            ? this.resolveExplicit(params)
+            : this.resolveByPriority(params);
+        if ('code' in candidates) {
+            return this.fail(candidates, attempts);
+        }
+        return this.runCandidates(candidates, { ...params, Query: query }, contextUser, attempts);
+    }
+    /** Try each candidate in order, honouring the transient/permanent distinction. */
+    async runCandidates(candidates, params, contextUser, attempts) {
+        for (const entry of candidates) {
+            const startedAt = Date.now();
+            try {
+                const response = await entry.Provider.ExecuteSearch(params, contextUser);
+                const durationMs = Date.now() - startedAt;
+                if (response.Success) {
+                    attempts.push({
+                        ProviderName: entry.Name,
+                        DriverClass: entry.DriverClass,
+                        Succeeded: true,
+                        DurationMs: durationMs,
+                        HitCount: response.Hits.length,
+                    });
+                    return {
+                        Success: true,
+                        ResultCode: 'SUCCESS',
+                        Hits: response.Hits,
+                        Answer: response.Answer,
+                        ProviderUsed: entry.Name,
+                        Attempts: attempts,
+                    };
+                }
+                const failureKind = response.FailureKind ?? 'transient';
+                attempts.push({
+                    ProviderName: entry.Name,
+                    DriverClass: entry.DriverClass,
+                    Succeeded: false,
+                    DurationMs: durationMs,
+                    FailureKind: failureKind,
+                    ErrorMessage: response.ErrorMessage,
+                });
+                // A rejected request is rejected everywhere. Stop rather than paying four more
+                // vendors to tell us the same thing and hiding the real message behind theirs.
+                if (failureKind === 'permanent') {
+                    return this.fail({
+                        code: 'INVALID_REQUEST',
+                        message: `${entry.Name} rejected the request and retrying elsewhere cannot help: ` +
+                            `${response.ErrorMessage ?? 'no detail supplied'}`,
+                    }, attempts);
+                }
+            }
+            catch (e) {
+                // A driver that throws is a bug in that driver, not a reason to fail the search.
+                const message = e instanceof Error ? e.message : String(e);
+                LogError(`WebSearchEngine: driver "${entry.DriverClass}" threw`, undefined, e);
+                attempts.push({
+                    ProviderName: entry.Name,
+                    DriverClass: entry.DriverClass,
+                    Succeeded: false,
+                    DurationMs: Date.now() - startedAt,
+                    FailureKind: 'transient',
+                    ErrorMessage: message,
+                });
+            }
+        }
+        return this.fail({
+            code: 'ALL_PROVIDERS_FAILED',
+            message: `All ${attempts.length} provider(s) failed: ${this.summarise(attempts)}`,
+        }, attempts);
+    }
+    /**
+     * Resolve an explicitly requested provider, or describe precisely why it cannot serve.
+     *
+     * Each rejection is a distinct code so a caller can tell "you never configured this" from
+     * "its key is missing" from "it cannot do answers" — three different fixes.
+     */
+    resolveExplicit(params) {
+        const wanted = params.Provider.trim().toLowerCase();
+        const entry = this._entries.find((e) => e.Name.toLowerCase() === wanted || e.DriverClass.toLowerCase() === wanted);
+        if (!entry) {
+            // _entries holds only Active + available providers, so distinguish the reasons by
+            // re-reading what was loaded rather than reporting a blanket "not found".
+            const known = this._unavailable.get(wanted);
+            if (known) {
+                return { code: known.code, message: known.message };
+            }
+            return {
+                code: 'PROVIDER_NOT_FOUND',
+                message: `No web search provider named "${params.Provider}". Configured and available: ` +
+                    `${this._entries.map((e) => e.Name).join(', ') || '(none)'}.`,
+            };
+        }
+        if (params.IncludeAnswer && !entry.Provider.Capabilities.Answer) {
+            return {
+                code: 'PROVIDER_LACKS_CAPABILITY',
+                message: `Provider "${entry.Name}" cannot produce a synthesized answer (IncludeAnswer was requested).`,
+            };
+        }
+        return [entry];
+    }
+    /** Eligible providers in priority order, or a failure describing why none qualified. */
+    resolveByPriority(params) {
+        const eligible = this._entries.filter((e) => !params.IncludeAnswer || e.Provider.Capabilities.Answer);
+        if (eligible.length === 0) {
+            return {
+                code: 'NO_ELIGIBLE_PROVIDER',
+                message: params.IncludeAnswer
+                    ? 'No available provider can produce a synthesized answer. Configure Tavily or Perplexity, or drop IncludeAnswer.'
+                    : 'No available web search provider.',
+            };
+        }
+        return eligible;
+    }
+    fail(failure, attempts) {
+        return {
+            Success: false,
+            ResultCode: failure.code,
+            Hits: [],
+            Attempts: attempts,
+            ErrorMessage: failure.message,
+        };
+    }
+    summarise(attempts) {
+        return attempts
+            .filter((a) => !a.Succeeded)
+            .map((a) => `${a.ProviderName}: ${a.ErrorMessage ?? 'unknown error'}`)
+            .join(' | ');
+    }
+    /** Load provider records, instantiate drivers, and keep the ones that are operational. */
+    async loadProviders(contextUser) {
+        this._entries = [];
+        this._unavailable = new Map();
+        this._loadError = null;
+        const rv = this._provider
+            ? RunView.FromMetadataProvider(this._provider)
+            : new RunView();
+        // `entity_object` with the generated subclass, matching how SearchEngine types its own
+        // provider records. `Fields` is deliberately absent — it is ignored for entity_object, and
+        // a hand-listed projection is how a column added to the table later goes silently unread.
+        //
+        // Every status is loaded, not just Active. Filtering in SQL made a non-Active provider
+        // indistinguishable from one that was never configured: it reached neither `_entries` nor
+        // `_unavailable`, so pinning it reported PROVIDER_NOT_FOUND and sent an operator looking
+        // for a record that is sitting right there, one column away from working. The table holds
+        // a handful of rows, so reading them all and filtering here costs nothing.
+        const result = await rv.RunView({
+            EntityName: WebSearchEngine.PROVIDER_ENTITY,
+            OrderBy: 'Priority ASC, Name ASC',
+            ResultType: 'entity_object',
+        }, contextUser);
+        // RunView does not throw — branch on Success or the engine silently reports
+        // "no providers configured" for what is actually a database error.
+        if (!result.Success) {
+            this._loadError = result.ErrorMessage || 'the provider view query failed without a message';
+            LogError(`WebSearchEngine: failed to load providers — ${this._loadError}`);
+            this._loaded = true;
+            return;
+        }
+        this._loadError = null;
+        for (const record of result.Results ?? []) {
+            await this.initializeProvider(record, contextUser);
+        }
+        this._loaded = true;
+        LogStatus(`WebSearchEngine: ${this._entries.length} provider(s) available ` +
+            `(${this._entries.map((e) => e.Name).join(', ') || 'none'})`);
+    }
+    /** Instantiate, configure and availability-check one provider record. */
+    async initializeProvider(record, contextUser) {
+        const driverClass = record.DriverClass;
+        // Parked deliberately — remembered with its own code, and never instantiated. Building a
+        // driver for a provider an administrator switched off would run its constructor and
+        // availability check for a row that cannot serve anything.
+        if (record.Status !== 'Active') {
+            this.recordUnavailable(record, {
+                code: 'PROVIDER_NOT_ACTIVE',
+                message: `Provider "${record.Name}" is configured but its Status is "${record.Status}", ` +
+                    'not Active. Set it to Active to bring it into the selection pool.',
+            });
+            return;
+        }
+        try {
+            const driver = MJGlobal.Instance.ClassFactory.CreateInstance(BaseWebSearchProvider, driverClass);
+            if (!driver) {
+                const message = `No registered driver for DriverClass "${driverClass}" (provider "${record.Name}").`;
+                LogError(`WebSearchEngine: ${message}`);
+                this.recordUnavailable(record, { code: 'PROVIDER_UNAVAILABLE', message });
+                return;
+            }
+            const config = {
+                Name: record.Name,
+                ProviderConfig: this.parseProviderConfig(record),
+                CredentialValues: await this.resolveCredentialValues(record, contextUser),
+                MaxResultsOverride: record.MaxResultsOverride ?? null,
+                Priority: record.Priority,
+            };
+            await driver.Initialize(config, contextUser);
+            await driver.CheckAvailability(contextUser);
+            if (driver.IsAvailable()) {
+                this._entries.push({
+                    Name: record.Name,
+                    DriverClass: driverClass,
+                    Priority: record.Priority,
+                    Provider: driver,
+                });
+            }
+            else {
+                this.recordUnavailable(record, {
+                    code: 'PROVIDER_UNAVAILABLE',
+                    message: `Provider "${record.Name}" is Active but not operational: ` +
+                        `${driver.UnavailableReason ?? 'no reason reported'}.`,
+                });
+            }
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            LogError(`WebSearchEngine: failed to initialize "${record.Name}"`, undefined, e);
+            this.recordUnavailable(record, {
+                code: 'PROVIDER_UNAVAILABLE',
+                message: `Provider "${record.Name}" failed to initialize: ${message}`,
+            });
+        }
+    }
+    /** Remember why a configured provider is not serving, so an explicit request can say so. */
+    recordUnavailable(record, failure) {
+        this._unavailable.set(record.Name.toLowerCase(), failure);
+        this._unavailable.set(record.DriverClass.toLowerCase(), failure);
+    }
+    parseProviderConfig(record) {
+        if (!record.ProviderConfig) {
+            return null;
+        }
+        try {
+            return JSON.parse(record.ProviderConfig);
+        }
+        catch {
+            // Bad JSON disables tuning, not the provider — the driver's env fallback still works.
+            LogError(`WebSearchEngine: invalid JSON in ProviderConfig for "${record.Name}"; ignoring it.`);
+            return null;
+        }
+    }
+    /** Decrypt the linked credential, when one is set. Null when absent or unreadable. */
+    async resolveCredentialValues(record, contextUser) {
+        if (!record.CredentialID) {
+            return null;
+        }
+        try {
+            await CredentialEngine.Instance.Config(false, contextUser);
+            const credential = CredentialEngine.Instance.getCredentialById(record.CredentialID);
+            if (!credential) {
+                LogError(`WebSearchEngine: CredentialID ${record.CredentialID} on "${record.Name}" does not resolve.`);
+                return null;
+            }
+            const resolved = await CredentialEngine.Instance.getCredential(credential.Name, {
+                credentialId: record.CredentialID,
+                contextUser,
+                subsystem: 'WebSearch',
+            });
+            return resolved.values ?? null;
+        }
+        catch (e) {
+            // Returning null lets the driver fall back to its environment variable and
+            // self-disable cleanly if that is missing too.
+            LogError(`WebSearchEngine: could not decrypt credential for "${record.Name}"`, undefined, e);
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=WebSearchEngine.js.map

package/dist/WebSearchEngine.js.map

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