@memberjunction/core-actions 6.1.2 → 6.2.0-edge.0

package/dist/custom/web/web-search.action.d.ts

@@ -1,66 +1,82 @@
 import { ActionResultSimple, RunActionParams } from "@memberjunction/actions-base";
 import { BaseAction } from "@memberjunction/actions";
 /**
- * Action that performs web search using DuckDuckGo's Instant Answer API
- * Returns search results with titles, URLs, and snippets
+ * Action that performs a web search through whichever provider the administrator has configured.
+ *
+ * This is the **provider-neutral entry point** agents should bind to. It holds no vendor logic of
+ * its own: it extracts parameters, hands them to {@link WebSearchEngine}, and maps the result
+ * back. Which vendor actually serves the request — Brave, Tavily, Perplexity, or a fallback when
+ * the first choice is rate-limited — is decided by the `MJ: Web Search Providers` records and
+ * their `Priority`, not by the caller and not by the agent.
+ *
+ * That is the point. An LLM choosing between named vendor actions is making an infrastructure
+ * decision it has no information for: it cannot know which key is configured, which is cheaper,
+ * or which is rate-limited right now. Swapping vendors here is a metadata edit, with no change to
+ * any agent.
+ *
+ * `Provider` is the escape hatch for a caller who genuinely knows better. When set, the engine
+ * **fails rather than substituting** — a silent substitution is how you discover months later
+ * that a deliberate choice stopped being honoured.
  *
  * @example
  * ```typescript
- * // Basic web search
+ * // Let the administrator's priority order decide
+ * await runAction({
+ *   ActionName: 'Web Search',
+ *   Params: [{ Name: 'Query', Value: 'association management trends' }]
+ * });
+ *
+ * // Recent results from two domains, with a synthesized answer
  * await runAction({
  *   ActionName: 'Web Search',
- *   Params: [{
- *     Name: 'SearchTerms',
- *     Value: 'TypeScript programming'
- *   }]
+ *   Params: [
+ *     { Name: 'Query',          Value: 'IRS Form 990 filing changes' },
+ *     { Name: 'Freshness',      Value: 'month' },
+ *     { Name: 'IncludeDomains', Value: ['irs.gov', 'councilofnonprofits.org'] },
+ *     { Name: 'IncludeAnswer',  Value: true }
+ *   ]
  * });
  *
- * // Search with custom result count
+ * // Pin one vendor — fails if it is not available rather than using another
  * await runAction({
  *   ActionName: 'Web Search',
- *   Params: [{
- *     Name: 'SearchTerms',
- *     Value: 'machine learning tutorials'
- *   }, {
- *     Name: 'MaxResults',
- *     Value: 15
- *   }]
+ *   Params: [
+ *     { Name: 'Query',    Value: 'quantum error correction 2026' },
+ *     { Name: 'Provider', Value: 'Brave' }
+ *   ]
  * });
  * ```
  */
 export declare class WebSearchAction extends BaseAction {
+    private static readonly FRESHNESS_WINDOWS;
+    private static readonly SAFE_SEARCH_VALUES;
     /**
-     * Executes the web search using DuckDuckGo's API
+     * Executes the search.
      *
      * @param params - The action parameters containing:
-     *   - SearchTerms: Keywords to search for (required)
-     *   - MaxResults: Maximum number of results to return (default: 10, max: 30)
-     *   - Region: Regional search preference (default: 'us-en')
-     *   - SafeSearch: Safe search level - 'strict', 'moderate', 'off' (default: 'moderate')
-     *   - DisableQueueing: If true, fails immediately when rate limited instead of queueing (default: false)
+     *   - Query: Search query text (required)
+     *   - MaxResults: Desired result count, clamped to the serving provider's cap (default 10)
+     *   - Provider: Pin to one provider by Name or DriverClass. Fails if unavailable
+     *   - IncludeDomains / ExcludeDomains: Array or comma-separated domain lists
+     *   - Freshness: 'day' | 'week' | 'month' | 'year'
+     *   - Country: Two-letter country code, e.g. 'US'
+     *   - Language: Language code, e.g. 'en'
+     *   - SafeSearch: 'off' | 'moderate' | 'strict' (default 'moderate')
+     *   - IncludeAnswer: Also return a synthesized answer, restricting provider selection
      *
-     * @returns Web search results with titles, URLs, and snippets
+     * @returns Normalised results plus which provider served them
      */
     protected InternalRunAction(params: RunActionParams): Promise<ActionResultSimple>;
+    private getStringParam;
+    private getBooleanParam;
+    private getOptionalNumericParam;
     /**
-     * Parses DuckDuckGo Instant Answer API JSON response
-     */
-    private parseInstantResults;
-    /**
-     * Extracts domain from URL
-     */
-    private extractDomain;
-    /**
-     * Parses DuckDuckGo HTML search results
-     */
-    private parseSearchResults;
-    /**
-     * Decodes DuckDuckGo URL redirects
-     */
-    private decodeUrl;
-    /**
-     * Strips HTML tags and decodes entities
+     * A list param, accepted as a real array or as a comma-separated string — both forms arrive
+     * in practice, from agent input mappings and from humans respectively.
      */
-    private stripHtml;
+    private getStringArrayParam;
+    private addOutputParam;
+    private createErrorResult;
 }
+export declare function LoadWebSearchAction(): void;
 //# sourceMappingURL=web-search.action.d.ts.map

package/dist/custom/web/web-search.action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web-search.action.d.ts","sourceRoot":"","sources":["../../../src/custom/web/web-search.action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBACa,eAAgB,SAAQ,UAAU;IAE3C;;;;;;;;;;;OAWG;cACa,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0MvF;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAkE3B;;OAEG;IACH,OAAO,CAAC,aAAa;IAQrB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA+H1B;;OAEG;IACH,OAAO,CAAC,SAAS;IAcjB;;OAEG;IACH,OAAO,CAAC,SAAS;CAYpB"}
+{"version":3,"file":"web-search.action.d.ts","sourceRoot":"","sources":["../../../src/custom/web/web-search.action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AASrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBACa,eAAgB,SAAQ,UAAU;IAC3C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAA6C;IACtF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAA0C;IAEpF;;;;;;;;;;;;;;;OAeG;cACa,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA4EvF,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,uBAAuB;IAO/B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,iBAAiB;CAG5B;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}