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

package/dist/custom/web/brave-search.action.js

@@ -0,0 +1,285 @@
+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 BraveSearchAction_1;
+import { BaseAction } from "@memberjunction/actions";
+import { RegisterClass } from "@memberjunction/global";
+import { HttpGet, IsHttpError } from "@memberjunction/network-utils";
+import { getApiIntegrationsConfig } from "../../config.js";
+/**
+ * Action that searches the web through the Brave Search API.
+ *
+ * Brave matters here for a reason that is structural rather than qualitative: it
+ * serves results from **its own index** (40B+ pages) rather than reselling
+ * Google's or Bing's. Every SERP-proxy vendor — and every product built on the
+ * Google Custom Search JSON API, which is discontinued on 2027-01-01 — depends on
+ * a search engine continuing to permit that access. Brave does not, so it fails
+ * independently of the rest of this package's web-search actions. That is the
+ * whole point of adding it.
+ *
+ * Its output shape is deliberately `title` / `url` / `snippet`, which is the shape
+ * `Google Custom Search` returns today, so callers migrating off that action are
+ * making a rename rather than a rewrite.
+ *
+ * Authentication is the `X-Subscription-Token` header. Brave requires
+ * `Accept: application/json` and returns gzip, which `fetch` negotiates itself.
+ *
+ * @example
+ * ```typescript
+ * // Basic search
+ * await runAction({
+ *   ActionName: 'Brave Search',
+ *   Params: [{ Name: 'Query', Value: 'association management software trends' }]
+ * });
+ *
+ * // Recent results only, more of them
+ * await runAction({
+ *   ActionName: 'Brave Search',
+ *   Params: [
+ *     { Name: 'Query',     Value: 'nonprofit membership dues changes' },
+ *     { Name: 'Freshness', Value: 'pw' },
+ *     { Name: 'Count',     Value: 20 }
+ *   ]
+ * });
+ *
+ * // Second page, UK results, with the extra per-page snippets
+ * await runAction({
+ *   ActionName: 'Brave Search',
+ *   Params: [
+ *     { Name: 'Query',         Value: 'charity commission filing deadlines' },
+ *     { Name: 'Country',       Value: 'GB' },
+ *     { Name: 'Offset',        Value: 1 },
+ *     { Name: 'ExtraSnippets', Value: true }
+ *   ]
+ * });
+ * ```
+ */
+let BraveSearchAction = class BraveSearchAction extends BaseAction {
+    static { BraveSearchAction_1 = this; }
+    static { this.ENDPOINT = 'https://api.search.brave.com/res/v1/web/search'; }
+    /** Brave's cap on results per request. */
+    static { this.MAX_COUNT = 20; }
+    static { this.DEFAULT_COUNT = 10; }
+    /** Brave's cap on the pagination offset (in pages, not results). */
+    static { this.MAX_OFFSET = 9; }
+    /** Brave rejects queries longer than this outright. */
+    static { this.MAX_QUERY_CHARS = 400; }
+    static { this.SAFESEARCH_VALUES = ['off', 'moderate', 'strict']; }
+    /** `pd`/`pw`/`pm`/`py` = past day/week/month/year. Brave also accepts a date range. */
+    static { this.FRESHNESS_CODES = ['pd', 'pw', 'pm', 'py']; }
+    static { this.FRESHNESS_RANGE = /^\d{4}-\d{2}-\d{2}to\d{4}-\d{2}-\d{2}$/; }
+    /**
+     * Executes the Brave search.
+     *
+     * @param params - The action parameters containing:
+     *   - Query: Search query text (required, max 400 characters)
+     *   - Count: 1-20 results (default 10)
+     *   - Offset: Page offset 0-9 (default 0) — pages, not results
+     *   - Country: 2-letter country code for localisation, e.g. 'US', 'GB'
+     *   - SearchLang: Language code for results, e.g. 'en'
+     *   - SafeSearch: 'off' | 'moderate' (default) | 'strict'
+     *   - Freshness: 'pd' | 'pw' | 'pm' | 'py', or 'YYYY-MM-DDtoYYYY-MM-DD'
+     *   - ExtraSnippets: Return additional snippets per result (default false).
+     *     Brave gates this on plan tier, so it is off unless asked for
+     *
+     * @returns Structured web results with titles, URLs and snippets
+     */
+    async InternalRunAction(params) {
+        const query = this.getStringParam(params, 'query');
+        if (!query) {
+            return this.createErrorResult("Query parameter is required", "MISSING_QUERY");
+        }
+        // Rejected rather than truncated: silently cutting a query changes what was
+        // asked and returns confident results for a different question.
+        if (query.length > BraveSearchAction_1.MAX_QUERY_CHARS) {
+            return this.createErrorResult(`Query is ${query.length} characters; Brave's limit is ${BraveSearchAction_1.MAX_QUERY_CHARS}`, "QUERY_TOO_LONG");
+        }
+        const apiKey = getApiIntegrationsConfig().braveApiKey;
+        if (!apiKey) {
+            return this.createErrorResult("Brave Search API key not found. Set braveApiKey in mj.config.cjs or the BRAVE_SEARCH_API_KEY environment variable", "MISSING_API_KEY");
+        }
+        const safeSearch = (this.getStringParam(params, 'safesearch') || 'moderate').toLowerCase();
+        if (!BraveSearchAction_1.SAFESEARCH_VALUES.includes(safeSearch)) {
+            return this.createErrorResult(`SafeSearch must be one of ${BraveSearchAction_1.SAFESEARCH_VALUES.join(', ')} (got '${safeSearch}')`, "INVALID_SAFESEARCH");
+        }
+        const freshness = this.getStringParam(params, 'freshness')?.toLowerCase();
+        if (freshness && !this.isValidFreshness(freshness)) {
+            return this.createErrorResult(`Freshness must be one of ${BraveSearchAction_1.FRESHNESS_CODES.join(', ')} or a 'YYYY-MM-DDtoYYYY-MM-DD' range (got '${freshness}')`, "INVALID_FRESHNESS");
+        }
+        // Clamped rather than rejected, matching Tavily Search: a caller asking for 50
+        // results wants as many as possible, and Brave rejects the whole request above its cap.
+        const count = this.clamp(this.getNumericParam(params, 'count', BraveSearchAction_1.DEFAULT_COUNT), 1, BraveSearchAction_1.MAX_COUNT);
+        const offset = this.clamp(this.getNumericParam(params, 'offset', 0), 0, BraveSearchAction_1.MAX_OFFSET);
+        const extraSnippets = this.getBooleanParam(params, 'extrasnippets', false);
+        const requestQuery = { q: query, count, offset, safesearch: safeSearch };
+        if (freshness) {
+            requestQuery.freshness = freshness;
+        }
+        const country = this.getStringParam(params, 'country');
+        if (country) {
+            requestQuery.country = country.toUpperCase();
+        }
+        const searchLang = this.getStringParam(params, 'searchlang');
+        if (searchLang) {
+            requestQuery.search_lang = searchLang.toLowerCase();
+        }
+        if (extraSnippets) {
+            requestQuery.extra_snippets = 'true';
+        }
+        try {
+            const response = await HttpGet(BraveSearchAction_1.ENDPOINT, {
+                Query: requestQuery,
+                Headers: {
+                    'X-Subscription-Token': apiKey,
+                    'Accept': 'application/json'
+                },
+                Timeout: 15000
+            });
+            if (!response.Data) {
+                return this.createErrorResult("Empty response from Brave Search API", "EMPTY_RESPONSE");
+            }
+            const results = (response.Data.web?.results ?? []).map((item) => {
+                const mapped = {
+                    title: item.title ?? '',
+                    url: item.url ?? '',
+                    snippet: item.description ?? '',
+                    displayUrl: item.meta_url?.netloc ?? item.meta_url?.hostname ?? '',
+                };
+                if (item.age) {
+                    mapped.age = item.age;
+                }
+                if (item.page_age) {
+                    mapped.pageAge = item.page_age;
+                }
+                if (item.extra_snippets && item.extra_snippets.length > 0) {
+                    mapped.extraSnippets = item.extra_snippets;
+                }
+                return mapped;
+            });
+            // Brave rewrites some queries (spelling, synonyms) and reports it here. A caller
+            // debugging unexpected results needs to know the engine searched for something else.
+            const alteredQuery = response.Data.query?.altered;
+            this.addOutputParam(params, 'Results', results);
+            this.addOutputParam(params, 'ResultCount', results.length);
+            this.addOutputParam(params, 'SearchResultDetails', {
+                query,
+                alteredQuery,
+                count,
+                offset,
+                safeSearch,
+                freshness,
+                results,
+            });
+            // Zero results is a real answer to a narrow query, not a failure — a caller
+            // that treats it as one would retry a query that will keep returning nothing.
+            return {
+                Success: true,
+                ResultCode: "SUCCESS",
+                Message: results.length === 0
+                    ? `Brave returned no results for '${query}'.`
+                    : `Brave returned ${results.length} result(s) for '${query}'.`
+            };
+        }
+        catch (error) {
+            // Status 0 is HttpError's "the request never produced a response" — a timeout or a
+            // network failure. That is not an API answer, so it falls through to SEARCH_FAILED
+            // rather than being dressed up as an API_ERROR with no status.
+            if (IsHttpError(error) && error.Status > 0) {
+                return this.mapHttpError(error);
+            }
+            return this.createErrorResult(`Failed to perform Brave search: ${error instanceof Error ? error.message : String(error)}`, "SEARCH_FAILED");
+        }
+    }
+    mapHttpError(error) {
+        const status = error.Status;
+        const detail = this.describeErrorBody(error.Data) || error.message;
+        if (status === 401 || status === 403) {
+            return this.createErrorResult(`Brave rejected the API key (HTTP ${status}): ${detail}`, "INVALID_API_KEY");
+        }
+        if (status === 429) {
+            // Brave meters by plan and, since it retired its free tier in early 2026,
+            // bills overage against a stored card. A 429 here is a spend signal, not
+            // just a pacing one, so it is surfaced distinctly rather than retried.
+            return this.createErrorResult(`Brave rate limit or plan quota exceeded: ${detail}`, "RATE_LIMITED");
+        }
+        if (status === 422) {
+            return this.createErrorResult(`Brave rejected the request parameters (HTTP 422): ${detail}`, "INVALID_REQUEST");
+        }
+        if (status === 400) {
+            return this.createErrorResult(`Brave rejected the request (HTTP 400): ${detail}`, "INVALID_REQUEST");
+        }
+        return this.createErrorResult(`Brave API error: ${detail}`, "API_ERROR");
+    }
+    /** Pull whatever explanation the error body carries, without assuming a shape. */
+    describeErrorBody(data) {
+        if (typeof data === 'string')
+            return data.slice(0, 500);
+        if (data && typeof data === 'object') {
+            const record = data;
+            // Brave nests its explanation as { error: { detail: '…' } } on 422s.
+            const error = record.error;
+            if (error && typeof error === 'object') {
+                const nested = error;
+                for (const key of ['detail', 'message', 'code']) {
+                    const value = nested[key];
+                    if (typeof value === 'string' && value.length > 0)
+                        return value;
+                }
+            }
+            for (const key of ['detail', 'message', 'error']) {
+                const value = record[key];
+                if (typeof value === 'string' && value.length > 0)
+                    return value;
+            }
+        }
+        return '';
+    }
+    isValidFreshness(value) {
+        if (BraveSearchAction_1.FRESHNESS_CODES.includes(value)) {
+            return true;
+        }
+        return BraveSearchAction_1.FRESHNESS_RANGE.test(value);
+    }
+    clamp(value, min, max) {
+        return Math.min(Math.max(Math.floor(value), min), max);
+    }
+    getStringParam(params, paramName) {
+        const param = params.Params.find(p => p.Name.trim().toLowerCase() === paramName.toLowerCase());
+        if (param?.Value === undefined || param?.Value === null)
+            return undefined;
+        const value = String(param.Value).trim();
+        return value.length > 0 ? value : undefined;
+    }
+    getBooleanParam(params, paramName, defaultValue) {
+        const param = params.Params.find(p => p.Name.trim().toLowerCase() === paramName.toLowerCase());
+        if (param?.Value === undefined || param?.Value === null)
+            return defaultValue;
+        if (typeof param.Value === 'boolean')
+            return param.Value;
+        return String(param.Value).trim().toLowerCase() === 'true';
+    }
+    getNumericParam(params, paramName, defaultValue) {
+        const param = params.Params.find(p => p.Name.trim().toLowerCase() === paramName.toLowerCase());
+        if (param?.Value === undefined || param?.Value === null || param.Value === '')
+            return defaultValue;
+        const num = Number(param.Value);
+        return isNaN(num) ? defaultValue : num;
+    }
+    addOutputParam(params, name, value) {
+        params.Params.push({ Name: name, Type: 'Output', Value: value });
+    }
+    createErrorResult(message, code) {
+        return { Success: false, Message: message, ResultCode: code };
+    }
+};
+BraveSearchAction = BraveSearchAction_1 = __decorate([
+    RegisterClass(BaseAction, "Brave Search")
+], BraveSearchAction);
+export { BraveSearchAction };
+export function LoadBraveSearchAction() {
+    // Referenced by consumers to keep this registration from being tree-shaken.
+}
+//# sourceMappingURL=brave-search.action.js.map

package/dist/custom/web/brave-search.action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brave-search.action.js","sourceRoot":"","sources":["../../../src/custom/web/brave-search.action.ts"],"names":[],"mappings":";;;;;;;AACA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAa,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAsCxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEI,IAAM,iBAAiB,GAAvB,MAAM,iBAAkB,SAAQ,UAAU;;aACrB,aAAQ,GAAG,gDAAgD,AAAnD,CAAoD;IACpF,0CAA0C;aAClB,cAAS,GAAG,EAAE,AAAL,CAAM;aACf,kBAAa,GAAG,EAAE,AAAL,CAAM;IAC3C,oEAAoE;aAC5C,eAAU,GAAG,CAAC,AAAJ,CAAK;IACvC,uDAAuD;aAC/B,oBAAe,GAAG,GAAG,AAAN,CAAO;aAEtB,sBAAiB,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,CAAU,AAAzC,CAA0C;IACnF,uFAAuF;aAC/D,oBAAe,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,AAApC,CAAqC;aACpD,oBAAe,GAAG,wCAAwC,AAA3C,CAA4C;IAEnF;;;;;;;;;;;;;;;OAeG;IACO,KAAK,CAAC,iBAAiB,CAAC,MAAuB;QACrD,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnD,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,OAAO,IAAI,CAAC,iBAAiB,CAAC,6BAA6B,EAAE,eAAe,CAAC,CAAC;QAClF,CAAC;QACD,4EAA4E;QAC5E,gEAAgE;QAChE,IAAI,KAAK,CAAC,MAAM,GAAG,mBAAiB,CAAC,eAAe,EAAE,CAAC;YACnD,OAAO,IAAI,CAAC,iBAAiB,CACzB,YAAY,KAAK,CAAC,MAAM,iCAAiC,mBAAiB,CAAC,eAAe,EAAE,EAC5F,gBAAgB,CACnB,CAAC;QACN,CAAC;QAED,MAAM,MAAM,GAAG,wBAAwB,EAAE,CAAC,WAAW,CAAC;QACtD,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,OAAO,IAAI,CAAC,iBAAiB,CACzB,mHAAmH,EACnH,iBAAiB,CACpB,CAAC;QACN,CAAC;QAED,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,YAAY,CAAC,IAAI,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;QAC3F,IAAI,CAAC,mBAAiB,CAAC,iBAAiB,CAAC,QAAQ,CAAC,UAAgE,CAAC,EAAE,CAAC;YAClH,OAAO,IAAI,CAAC,iBAAiB,CACzB,6BAA6B,mBAAiB,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,UAAU,IAAI,EACnG,oBAAoB,CACvB,CAAC;QACN,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;QAC1E,IAAI,SAAS,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,CAAC;YACjD,OAAO,IAAI,CAAC,iBAAiB,CACzB,4BAA4B,mBAAiB,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,8CAA8C,SAAS,IAAI,EACnI,mBAAmB,CACtB,CAAC;QACN,CAAC;QAED,+EAA+E;QAC/E,wFAAwF;QACxF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CACpB,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,mBAAiB,CAAC,aAAa,CAAC,EACtE,CAAC,EACD,mBAAiB,CAAC,SAAS,CAC9B,CAAC;QACF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,mBAAiB,CAAC,UAAU,CAAC,CAAC;QACtG,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,CAAC,CAAC;QAE3E,MAAM,YAAY,GAAoC,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;QAC1G,IAAI,SAAS,EAAE,CAAC;YACZ,YAAY,CAAC,SAAS,GAAG,SAAS,CAAC;QACvC,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACvD,IAAI,OAAO,EAAE,CAAC;YACV,YAAY,CAAC,OAAO,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;QACjD,CAAC;QACD,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC7D,IAAI,UAAU,EAAE,CAAC;YACb,YAAY,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;QACxD,CAAC;QACD,IAAI,aAAa,EAAE,CAAC;YAChB,YAAY,CAAC,cAAc,GAAG,MAAM,CAAC;QACzC,CAAC;QAED,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAC1B,mBAAiB,CAAC,QAAQ,EAC1B;gBACI,KAAK,EAAE,YAAY;gBACnB,OAAO,EAAE;oBACL,sBAAsB,EAAE,MAAM;oBAC9B,QAAQ,EAAE,kBAAkB;iBAC/B;gBACD,OAAO,EAAE,KAAK;aACjB,CACJ,CAAC;YAEF,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACjB,OAAO,IAAI,CAAC,iBAAiB,CAAC,sCAAsC,EAAE,gBAAgB,CAAC,CAAC;YAC5F,CAAC;YAED,MAAM,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAyB,EAAE;gBACnF,MAAM,MAAM,GAA0B;oBAClC,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE;oBACvB,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,EAAE;oBACnB,OAAO,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE;oBAC/B,UAAU,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,QAAQ,IAAI,EAAE;iBACrE,CAAC;gBACF,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;oBACX,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;gBAC1B,CAAC;gBACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;oBAChB,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;gBACnC,CAAC;gBACD,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACxD,MAAM,CAAC,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC;gBAC/C,CAAC;gBACD,OAAO,MAAM,CAAC;YAClB,CAAC,CAAC,CAAC;YAEH,iFAAiF;YACjF,qFAAqF;YACrF,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC;YAElD,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;YAChD,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YAC3D,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,qBAAqB,EAAE;gBAC/C,KAAK;gBACL,YAAY;gBACZ,KAAK;gBACL,MAAM;gBACN,UAAU;gBACV,SAAS;gBACT,OAAO;aACV,CAAC,CAAC;YAEH,4EAA4E;YAC5E,8EAA8E;YAC9E,OAAO;gBACH,OAAO,EAAE,IAAI;gBACb,UAAU,EAAE,SAAS;gBACrB,OAAO,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC;oBACzB,CAAC,CAAC,kCAAkC,KAAK,IAAI;oBAC7C,CAAC,CAAC,kBAAkB,OAAO,CAAC,MAAM,mBAAmB,KAAK,IAAI;aACrE,CAAC;QACN,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,mFAAmF;YACnF,mFAAmF;YACnF,+DAA+D;YAC/D,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzC,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;YACpC,CAAC;YACD,OAAO,IAAI,CAAC,iBAAiB,CACzB,mCAAmC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAC3F,eAAe,CAClB,CAAC;QACN,CAAC;IACL,CAAC;IAEO,YAAY,CAAC,KAAgB;QACjC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC;QAEnE,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC,iBAAiB,CACzB,oCAAoC,MAAM,MAAM,MAAM,EAAE,EACxD,iBAAiB,CACpB,CAAC;QACN,CAAC;QACD,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACjB,0EAA0E;YAC1E,yEAAyE;YACzE,uEAAuE;YACvE,OAAO,IAAI,CAAC,iBAAiB,CACzB,4CAA4C,MAAM,EAAE,EACpD,cAAc,CACjB,CAAC;QACN,CAAC;QACD,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC,iBAAiB,CACzB,qDAAqD,MAAM,EAAE,EAC7D,iBAAiB,CACpB,CAAC;QACN,CAAC;QACD,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC,iBAAiB,CACzB,0CAA0C,MAAM,EAAE,EAClD,iBAAiB,CACpB,CAAC;QACN,CAAC;QACD,OAAO,IAAI,CAAC,iBAAiB,CAAC,oBAAoB,MAAM,EAAE,EAAE,WAAW,CAAC,CAAC;IAC7E,CAAC;IAED,kFAAkF;IAC1E,iBAAiB,CAAC,IAAa;QACnC,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACxD,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,IAA+B,CAAC;YAC/C,qEAAqE;YACrE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;YAC3B,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACrC,MAAM,MAAM,GAAG,KAAgC,CAAC;gBAChD,KAAK,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC;oBAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;oBAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;wBAAE,OAAO,KAAK,CAAC;gBACpE,CAAC;YACL,CAAC;YACD,KAAK,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC;gBAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;oBAAE,OAAO,KAAK,CAAC;YACpE,CAAC;QACL,CAAC;QACD,OAAO,EAAE,CAAC;IACd,CAAC;IAEO,gBAAgB,CAAC,KAAa;QAClC,IAAI,mBAAiB,CAAC,eAAe,CAAC,QAAQ,CAAC,KAAyD,CAAC,EAAE,CAAC;YACxG,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,mBAAiB,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzD,CAAC;IAEO,KAAK,CAAC,KAAa,EAAE,GAAW,EAAE,GAAW;QACjD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3D,CAAC;IAEO,cAAc,CAAC,MAAuB,EAAE,SAAiB;QAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;QAC/F,IAAI,KAAK,EAAE,KAAK,KAAK,SAAS,IAAI,KAAK,EAAE,KAAK,KAAK,IAAI;YAAE,OAAO,SAAS,CAAC;QAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAChD,CAAC;IAEO,eAAe,CAAC,MAAuB,EAAE,SAAiB,EAAE,YAAqB;QACrF,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;QAC/F,IAAI,KAAK,EAAE,KAAK,KAAK,SAAS,IAAI,KAAK,EAAE,KAAK,KAAK,IAAI;YAAE,OAAO,YAAY,CAAC;QAC7E,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC,KAAK,CAAC;QACzD,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;IAC/D,CAAC;IAEO,eAAe,CAAC,MAAuB,EAAE,SAAiB,EAAE,YAAoB;QACpF,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;QAC/F,IAAI,KAAK,EAAE,KAAK,KAAK,SAAS,IAAI,KAAK,EAAE,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,KAAK,KAAK,EAAE;YAAE,OAAO,YAAY,CAAC;QACnG,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC;IAC3C,CAAC;IAEO,cAAc,CAAC,MAAuB,EAAE,IAAY,EAAE,KAAc;QACxE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACrE,CAAC;IAEO,iBAAiB,CAAC,OAAe,EAAE,IAAY;QACnD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAClE,CAAC;;AAxQQ,iBAAiB;IAD7B,aAAa,CAAC,UAAU,EAAE,cAAc,CAAC;GAC7B,iBAAiB,CAyQ7B;;AAED,MAAM,UAAU,qBAAqB;IACjC,4EAA4E;AAChF,CAAC"}

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

@@ -1,80 +1,112 @@
 import { ActionResultSimple, RunActionParams } from "@memberjunction/actions-base";
 import { BaseAction } from "@memberjunction/actions";
+/** One result from Perplexity's `/search` endpoint, normalised to this package's naming. */
+export interface PerplexitySearchResultItem {
+    title: string;
+    url: string;
+    snippet: string;
+    /** Publication date when Perplexity resolved one. */
+    date?: string;
+    /** When Perplexity last saw the page change. */
+    lastUpdated?: string;
+}
+/** Which Perplexity product a call routes to. */
+export type PerplexitySearchMode = 'search' | 'answer';
 /**
- * Action that performs AI-powered web search using Perplexity's Search API
- * Returns comprehensive search results with citations and related questions
+ * Action that queries Perplexity. It fronts **two different products**, selected
+ * by `Mode`, because they answer different questions and cost different money.
+ *
+ * - **`search` (default)** calls `POST /search`, Perplexity's raw search endpoint.
+ *   It returns ranked `title` / `url` / `snippet` results with no model in the
+ *   loop: sub-second, flat-priced per query, and deterministic enough to cache.
+ *   This is the mode to use when something wants *sources*.
+ * - **`answer`** calls `POST /chat/completions` against the Sonar models. It
+ *   returns synthesised prose plus a flat citation list, takes seconds rather
+ *   than milliseconds, and bills per token. Use it when a caller genuinely wants
+ *   a written answer rather than results to read.
+ *
+ * `search` is the default deliberately. Every caller that omitted `Mode` before
+ * this parameter existed was paying Sonar generation prices, and waiting for
+ * generation latency, to obtain what was usually just a list of links — and
+ * `Citations` is still populated in `search` mode, so callers that only read the
+ * URL list keep working unchanged.
  *
  * @example
  * ```typescript
- * // Basic search with Perplexity
+ * // Structured results — fast, flat-priced (default)
  * await runAction({
  *   ActionName: 'Perplexity Search',
- *   Params: [{
- *     Name: 'Query',
- *     Value: 'latest developments in quantum computing'
- *   }]
+ *   Params: [{ Name: 'Query', Value: 'latest developments in quantum computing' }]
  * });
  *
- * // Search with specific model and parameters
+ * // Structured results, recent only, restricted to two domains
  * await runAction({
  *   ActionName: 'Perplexity Search',
- *   Params: [{
- *     Name: 'Query',
- *     Value: 'climate change research papers 2024'
- *   }, {
- *     Name: 'Model',
- *     Value: 'sonar-pro'
- *   }, {
- *     Name: 'ReturnRelatedQuestions',
- *     Value: true
- *   }, {
- *     Name: 'ReturnImages',
- *     Value: true
- *   }]
+ *   Params: [
+ *     { Name: 'Query',               Value: 'IRS Form 990 filing changes' },
+ *     { Name: 'MaxResults',          Value: 15 },
+ *     { Name: 'SearchRecencyFilter', Value: 'month' },
+ *     { Name: 'SearchDomainFilter',  Value: ['irs.gov', 'councilofnonprofits.org'] }
+ *   ]
  * });
  *
- * // Search with domain filtering
+ * // A written answer with citations — slower, token-billed
  * await runAction({
  *   ActionName: 'Perplexity Search',
- *   Params: [{
- *     Name: 'Query',
- *     Value: 'machine learning tutorials'
- *   }, {
- *     Name: 'SearchDomainFilter',
- *     Value: ['github.com', 'arxiv.org', 'medium.com']
- *   }]
+ *   Params: [
+ *     { Name: 'Query', Value: 'summarise the 2026 nonprofit reporting changes' },
+ *     { Name: 'Mode',  Value: 'answer' },
+ *     { Name: 'Model', Value: 'sonar-pro' }
+ *   ]
  * });
  * ```
  */
 export declare class PerplexitySearchAction extends BaseAction {
+    private static readonly SEARCH_ENDPOINT;
+    private static readonly CHAT_ENDPOINT;
+    /** Perplexity's cap on results per web-search request. */
+    private static readonly MAX_RESULTS;
+    private static readonly DEFAULT_MAX_RESULTS;
+    /** Perplexity's cap on the domain allow/deny list. */
+    private static readonly MAX_DOMAIN_FILTERS;
+    private static readonly RECENCY_VALUES;
     /**
-     * Executes the Perplexity AI search
+     * Executes the Perplexity call.
      *
      * @param params - The action parameters containing:
      *   - Query: Search query text (required)
-     *   - Model: Perplexity model to use (default: 'sonar')
-     *     Options: sonar, sonar-pro, sonar-reasoning-pro, sonar-deep-research
-     *     Note: the legacy llama-3.1-sonar-* identifiers were retired by Perplexity in
-     *     February 2025 and now fail with an invalid-model error.
-     *   - MaxTokens: Maximum tokens in response (default: 1000)
-     *   - Temperature: Sampling temperature 0-2 (default: 0.2)
-     *   - TopP: Nucleus sampling threshold (default: 0.9)
-     *   - ReturnImages: Include images in results (default: false)
-     *   - ReturnRelatedQuestions: Include related questions (default: false)
-     *   - SearchDomainFilter: Array of domains to limit/exclude search (use '-' prefix to exclude)
-     *   - SearchRecencyFilter: Filter by recency - 'day', 'week', 'month', 'year' (optional)
+     *   - Mode: 'search' (default) for structured results, or 'answer' for Sonar prose
+     *   - SearchDomainFilter: Restrict to these domains (max 20) — both modes
+     *   - SearchRecencyFilter: 'hour' | 'day' | 'week' | 'month' | 'year' — both modes
+     *
+     *   `search` mode only:
+     *   - MaxResults: 1-20 (default 10)
+     *   - Country: 2-letter country code for localisation
+     *
+     *   `answer` mode only:
+     *   - Model: 'sonar' (default), 'sonar-pro', 'sonar-reasoning-pro', 'sonar-deep-research'.
+     *     Note the legacy `llama-3.1-sonar-*` identifiers were retired by Perplexity in
+     *     February 2025 and now fail with an invalid-model error
+     *   - MaxTokens, Temperature, TopP
+     *   - ReturnImages, ReturnRelatedQuestions
      *
-     * @returns Search results with content, citations, and related questions
+     * @returns Structured results in `search` mode; prose plus citations in `answer` mode
      */
     protected InternalRunAction(params: RunActionParams): Promise<ActionResultSimple>;
+    /** `POST /search` — structured results, no model in the loop. */
+    private runSearchMode;
+    /** `POST /chat/completions` — Sonar prose plus citations. */
+    private runAnswerMode;
+    private mapHttpError;
     /**
      * Get string parameter value
      */
     private getStringParam;
     /**
-     * Get parameter value (any type)
+     * 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 getParamValue;
+    private getStringArrayParam;
     /**
      * Get boolean parameter value with default
      */

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

@@ -1 +1 @@
-{"version":3,"file":"perplexity-search.action.d.ts","sourceRoot":"","sources":["../../../src/custom/web/perplexity-search.action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAiBrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBACa,sBAAuB,SAAQ,UAAU;IAElD;;;;;;;;;;;;;;;;;;OAkBG;cACa,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6JvF;;OAEG;IACH,OAAO,CAAC,cAAc;IAMtB;;OAEG;IACH,OAAO,CAAC,aAAa;IAKrB;;OAEG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAO5B"}
+{"version":3,"file":"perplexity-search.action.d.ts","sourceRoot":"","sources":["../../../src/custom/web/perplexity-search.action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAiBrD,4FAA4F;AAC5F,MAAM,WAAW,0BAA0B;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAgBD,iDAAiD;AACjD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBACa,sBAAuB,SAAQ,UAAU;IAClD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAsC;IAC7E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAgD;IACrF,0DAA0D;IAC1D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAM;IACzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAM;IACjD,sDAAsD;IACtD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAM;IAChD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAqD;IAE3F;;;;;;;;;;;;;;;;;;;;;OAqBG;cACa,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAoDvF,iEAAiE;YACnD,aAAa;IA4E3B,6DAA6D;YAC/C,aAAa;IA2E3B,OAAO,CAAC,YAAY;IAoBpB;;OAEG;IACH,OAAO,CAAC,cAAc;IAMtB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAO5B"}