@memberjunction/core-actions 2.54.0 → 2.56.0

package/dist/custom/utilities/base-file-handler.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseFileHandlerAction = void 0;
+const actions_1 = require("@memberjunction/actions");
+const core_1 = require("@memberjunction/core");
+/**
+ * Base class for actions that handle file inputs from multiple sources
+ * Provides common functionality for loading files from:
+ * - MJ Storage (Document Libraries)
+ * - URLs
+ * - Direct data
+ */
+class BaseFileHandlerAction extends actions_1.BaseAction {
+    /**
+     * Get file content from various sources based on parameters
+     * Priority: FileID > FileURL > Data parameter
+     *
+     * @param params - Action parameters
+     * @param dataParamName - Name of the parameter containing direct data
+     * @param fileParamName - Name of the parameter containing file ID (default: 'FileID')
+     * @param urlParamName - Name of the parameter containing file URL (default: 'FileURL')
+     * @returns Object with content and metadata
+     */
+    async getFileContent(params, dataParamName, fileParamName = 'FileID', urlParamName = 'FileURL') {
+        // Check for FileID first (MJ Storage)
+        const fileIdParam = params.Params.find(p => p.Name.trim().toLowerCase() === fileParamName.toLowerCase());
+        if (fileIdParam?.Value) {
+            return await this.loadFromMJStorage(fileIdParam.Value.toString(), params);
+        }
+        // Check for FileURL
+        const fileUrlParam = params.Params.find(p => p.Name.trim().toLowerCase() === urlParamName.toLowerCase());
+        if (fileUrlParam?.Value) {
+            return await this.loadFromURL(fileUrlParam.Value.toString());
+        }
+        // Check for direct data
+        const dataParam = params.Params.find(p => p.Name.trim().toLowerCase() === dataParamName.toLowerCase());
+        if (dataParam?.Value) {
+            return {
+                content: dataParam.Value.toString(),
+                source: 'direct'
+            };
+        }
+        throw new Error(`No input provided. Please provide ${fileParamName}, ${urlParamName}, or ${dataParamName}`);
+    }
+    /**
+     * Load file from MJ Storage (Document Libraries)
+     */
+    async loadFromMJStorage(fileId, params) {
+        try {
+            const rv = new core_1.RunView();
+            const result = await rv.RunView({
+                EntityName: 'Document Libraries',
+                ExtraFilter: `ID = '${fileId}'`,
+                ResultType: 'entity_object'
+            }, params.ContextUser);
+            if (!result.Success || !result.Results || result.Results.length === 0) {
+                throw new Error(`File not found in Document Libraries: ${fileId}`);
+            }
+            const doc = result.Results[0];
+            // Get the actual file content (this would need implementation based on your storage provider)
+            // For now, returning the file info - actual implementation would fetch from storage
+            return {
+                content: '', // TODO: Implement actual file retrieval based on storage provider
+                fileName: doc.Get('FileName'),
+                mimeType: doc.Get('MimeType'),
+                source: 'storage'
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to load file from storage: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Load file from URL
+     */
+    async loadFromURL(url) {
+        try {
+            // Validate URL
+            const urlObj = new URL(url);
+            if (!['http:', 'https:'].includes(urlObj.protocol)) {
+                throw new Error('Only HTTP and HTTPS URLs are supported');
+            }
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            const contentType = response.headers.get('content-type');
+            const contentDisposition = response.headers.get('content-disposition');
+            let fileName;
+            // Extract filename from content-disposition if available
+            if (contentDisposition) {
+                const match = contentDisposition.match(/filename[^;=\n]*=((['"]).*?\2|[^;\n]*)/);
+                if (match && match[1]) {
+                    fileName = match[1].replace(/['"]/g, '');
+                }
+            }
+            // If no filename from header, extract from URL
+            if (!fileName) {
+                fileName = urlObj.pathname.split('/').pop();
+            }
+            const content = await response.text();
+            return {
+                content,
+                fileName,
+                mimeType: contentType || undefined,
+                source: 'url'
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to load file from URL: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Save file to MJ Storage
+     */
+    async saveToMJStorage(content, fileName, mimeType, params) {
+        try {
+            const md = new core_1.Metadata();
+            const doc = await md.GetEntityObject('Document Libraries', params.ContextUser);
+            if (!doc) {
+                throw new Error('Failed to create Document Library entity');
+            }
+            doc.Set('FileName', fileName);
+            doc.Set('MimeType', mimeType);
+            // TODO: Set appropriate fields based on your Document Libraries schema
+            // doc.Set('FileSize', Buffer.byteLength(content));
+            // doc.Set('StorageProvider', 'default');
+            const saveResult = await doc.Save();
+            if (!saveResult) {
+                throw new Error('Failed to save document to library');
+            }
+            // TODO: Actually store the file content to the storage provider
+            return doc.Get('ID');
+        }
+        catch (error) {
+            throw new Error(`Failed to save file to storage: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Extract parameter value by name (case-insensitive)
+     */
+    getParamValue(params, paramName) {
+        const param = params.Params.find(p => p.Name.trim().toLowerCase() === paramName.toLowerCase());
+        return param?.Value;
+    }
+    /**
+     * Get boolean parameter value with default
+     */
+    getBooleanParam(params, paramName, defaultValue = false) {
+        const value = this.getParamValue(params, paramName);
+        if (value === undefined || value === null)
+            return defaultValue;
+        return String(value).toLowerCase() === 'true';
+    }
+    /**
+     * Get numeric parameter value with default
+     */
+    getNumericParam(params, paramName, defaultValue = 0) {
+        const value = this.getParamValue(params, paramName);
+        if (value === undefined || value === null)
+            return defaultValue;
+        const num = Number(value);
+        return isNaN(num) ? defaultValue : num;
+    }
+}
+exports.BaseFileHandlerAction = BaseFileHandlerAction;
+//# sourceMappingURL=base-file-handler.js.map

package/dist/custom/utilities/base-file-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-file-handler.js","sourceRoot":"","sources":["../../../src/custom/utilities/base-file-handler.ts"],"names":[],"mappings":";;;AAAA,qDAAqD;AAErD,+CAAqE;AAErE;;;;;;GAMG;AACH,MAAsB,qBAAsB,SAAQ,oBAAU;IAC1D;;;;;;;;;OASG;IACO,KAAK,CAAC,cAAc,CAC1B,MAAuB,EACvB,aAAqB,EACrB,gBAAwB,QAAQ,EAChC,eAAuB,SAAS;QAOhC,sCAAsC;QACtC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,aAAa,CAAC,WAAW,EAAE,CAAC,CAAC;QACzG,IAAI,WAAW,EAAE,KAAK,EAAE,CAAC;YACrB,OAAO,MAAM,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,MAAM,CAAC,CAAC;QAC9E,CAAC;QAED,oBAAoB;QACpB,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC;QACzG,IAAI,YAAY,EAAE,KAAK,EAAE,CAAC;YACtB,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjE,CAAC;QAED,wBAAwB;QACxB,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,aAAa,CAAC,WAAW,EAAE,CAAC,CAAC;QACvG,IAAI,SAAS,EAAE,KAAK,EAAE,CAAC;YACnB,OAAO;gBACH,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC,QAAQ,EAAE;gBACnC,MAAM,EAAE,QAAQ;aACnB,CAAC;QACN,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,qCAAqC,aAAa,KAAK,YAAY,QAAQ,aAAa,EAAE,CAAC,CAAC;IAChH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,iBAAiB,CAAC,MAAc,EAAE,MAAuB;QAMnE,IAAI,CAAC;YACD,MAAM,EAAE,GAAG,IAAI,cAAO,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAAa;gBACxC,UAAU,EAAE,oBAAoB;gBAChC,WAAW,EAAE,SAAS,MAAM,GAAG;gBAC/B,UAAU,EAAE,eAAe;aAC9B,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;YAEvB,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACpE,MAAM,IAAI,KAAK,CAAC,yCAAyC,MAAM,EAAE,CAAC,CAAC;YACvE,CAAC;YAED,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAE9B,8FAA8F;YAC9F,oFAAoF;YACpF,OAAO;gBACH,OAAO,EAAE,EAAE,EAAE,kEAAkE;gBAC/E,QAAQ,EAAE,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC;gBAC7B,QAAQ,EAAE,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC;gBAC7B,MAAM,EAAE,SAAS;aACpB,CAAC;QACN,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,qCAAqC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACnH,CAAC;IACL,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,WAAW,CAAC,GAAW;QAMjC,IAAI,CAAC;YACD,eAAe;YACf,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACjD,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC9D,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACf,MAAM,IAAI,KAAK,CAAC,QAAQ,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;YACvE,CAAC;YAED,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YACzD,MAAM,kBAAkB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;YACvE,IAAI,QAA4B,CAAC;YAEjC,yDAAyD;YACzD,IAAI,kBAAkB,EAAE,CAAC;gBACrB,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;gBACjF,IAAI,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;oBACpB,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;gBAC7C,CAAC;YACL,CAAC;YAED,+CAA+C;YAC/C,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACZ,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;YAChD,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YAEtC,OAAO;gBACH,OAAO;gBACP,QAAQ;gBACR,QAAQ,EAAE,WAAW,IAAI,SAAS;gBAClC,MAAM,EAAE,KAAK;aAChB,CAAC;QACN,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,iCAAiC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC/G,CAAC;IACL,CAAC;IAED;;OAEG;IACO,KAAK,CAAC,eAAe,CAC3B,OAAwB,EACxB,QAAgB,EAChB,QAAgB,EAChB,MAAuB;QAEvB,IAAI,CAAC;YACD,MAAM,EAAE,GAAG,IAAI,eAAQ,EAAE,CAAC;YAC1B,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,eAAe,CAAa,oBAAoB,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;YAE3F,IAAI,CAAC,GAAG,EAAE,CAAC;gBACP,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;YAChE,CAAC;YAED,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YAC9B,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YAC9B,uEAAuE;YACvE,mDAAmD;YACnD,yCAAyC;YAEzC,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;YACpC,IAAI,CAAC,UAAU,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;YAC1D,CAAC;YAED,gEAAgE;YAEhE,OAAO,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,mCAAmC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACjH,CAAC;IACL,CAAC;IAED;;OAEG;IACO,aAAa,CAAC,MAAuB,EAAE,SAAiB;QAC9D,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,OAAO,KAAK,EAAE,KAAK,CAAC;IACxB,CAAC;IAED;;OAEG;IACO,eAAe,CAAC,MAAuB,EAAE,SAAiB,EAAE,eAAwB,KAAK;QAC/F,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACpD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,YAAY,CAAC;QAC/D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;IAClD,CAAC;IAED;;OAEG;IACO,eAAe,CAAC,MAAuB,EAAE,SAAiB,EAAE,eAAuB,CAAC;QAC1F,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACpD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,YAAY,CAAC;QAC/D,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC;IAC3C,CAAC;CACJ;AAnMD,sDAmMC"}

package/dist/custom/utilities/index.d.ts

@@ -0,0 +1,3 @@
+export * from './base-file-handler';
+export * from './json-param-helper';
+//# sourceMappingURL=index.d.ts.map

package/dist/custom/utilities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/custom/utilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}

package/dist/custom/utilities/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./base-file-handler"), exports);
+__exportStar(require("./json-param-helper"), exports);
+//# sourceMappingURL=index.js.map

package/dist/custom/utilities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/custom/utilities/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAoC;AACpC,sDAAoC"}

package/dist/custom/utilities/json-param-helper.d.ts

@@ -0,0 +1,33 @@
+import { RunActionParams } from "@memberjunction/actions-base";
+/**
+ * Helper class for handling JSON parameters that can be either objects or strings
+ */
+export declare class JSONParamHelper {
+    /**
+     * Get a parameter value that can be either a JSON object or a JSON string
+     * First checks for the object parameter, then falls back to the string parameter
+     *
+     * @param params - The action parameters
+     * @param paramName - The base parameter name (without String suffix)
+     * @returns The parsed value or undefined
+     */
+    static getJSONParam(params: RunActionParams, paramName: string): any;
+    /**
+     * Check if a JSON parameter exists (either as object or string)
+     *
+     * @param params - The action parameters
+     * @param paramName - The base parameter name (without String suffix)
+     * @returns True if the parameter exists
+     */
+    static hasJSONParam(params: RunActionParams, paramName: string): boolean;
+    /**
+     * Get a required JSON parameter, throwing an error if not found
+     *
+     * @param params - The action parameters
+     * @param paramName - The base parameter name (without String suffix)
+     * @returns The parsed value
+     * @throws Error if parameter is not found
+     */
+    static getRequiredJSONParam(params: RunActionParams, paramName: string): any;
+}
+//# sourceMappingURL=json-param-helper.d.ts.map

package/dist/custom/utilities/json-param-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-param-helper.d.ts","sourceRoot":"","sources":["../../../src/custom/utilities/json-param-helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE/D;;GAEG;AACH,qBAAa,eAAe;IACxB;;;;;;;OAOG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,GAAG;IAoBpE;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAUxE;;;;;;;OAOG;IACH,MAAM,CAAC,oBAAoB,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,GAAG;CAO/E"}

package/dist/custom/utilities/json-param-helper.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSONParamHelper = void 0;
+/**
+ * Helper class for handling JSON parameters that can be either objects or strings
+ */
+class JSONParamHelper {
+    /**
+     * Get a parameter value that can be either a JSON object or a JSON string
+     * First checks for the object parameter, then falls back to the string parameter
+     *
+     * @param params - The action parameters
+     * @param paramName - The base parameter name (without String suffix)
+     * @returns The parsed value or undefined
+     */
+    static getJSONParam(params, paramName) {
+        // First check for the object parameter
+        const objectParam = params.Params.find(p => p.Name.trim().toLowerCase() === paramName.toLowerCase());
+        if (objectParam?.Value !== undefined && objectParam?.Value !== null) {
+            return objectParam.Value;
+        }
+        // Then check for the string parameter
+        const stringParam = params.Params.find(p => p.Name.trim().toLowerCase() === `${paramName}string`.toLowerCase());
+        if (stringParam?.Value !== undefined && stringParam?.Value !== null) {
+            try {
+                return JSON.parse(stringParam.Value.toString());
+            }
+            catch (e) {
+                throw new Error(`Failed to parse ${paramName}String parameter as JSON: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Check if a JSON parameter exists (either as object or string)
+     *
+     * @param params - The action parameters
+     * @param paramName - The base parameter name (without String suffix)
+     * @returns True if the parameter exists
+     */
+    static hasJSONParam(params, paramName) {
+        const objectParam = params.Params.find(p => p.Name.trim().toLowerCase() === paramName.toLowerCase());
+        if (objectParam?.Value !== undefined && objectParam?.Value !== null) {
+            return true;
+        }
+        const stringParam = params.Params.find(p => p.Name.trim().toLowerCase() === `${paramName}string`.toLowerCase());
+        return stringParam?.Value !== undefined && stringParam?.Value !== null;
+    }
+    /**
+     * Get a required JSON parameter, throwing an error if not found
+     *
+     * @param params - The action parameters
+     * @param paramName - The base parameter name (without String suffix)
+     * @returns The parsed value
+     * @throws Error if parameter is not found
+     */
+    static getRequiredJSONParam(params, paramName) {
+        const value = this.getJSONParam(params, paramName);
+        if (value === undefined) {
+            throw new Error(`${paramName} parameter is required (can be provided as ${paramName} object or ${paramName}String)`);
+        }
+        return value;
+    }
+}
+exports.JSONParamHelper = JSONParamHelper;
+//# sourceMappingURL=json-param-helper.js.map

package/dist/custom/utilities/json-param-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-param-helper.js","sourceRoot":"","sources":["../../../src/custom/utilities/json-param-helper.ts"],"names":[],"mappings":";;;AAEA;;GAEG;AACH,MAAa,eAAe;IACxB;;;;;;;OAOG;IACH,MAAM,CAAC,YAAY,CAAC,MAAuB,EAAE,SAAiB;QAC1D,uCAAuC;QACvC,MAAM,WAAW,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;QACrG,IAAI,WAAW,EAAE,KAAK,KAAK,SAAS,IAAI,WAAW,EAAE,KAAK,KAAK,IAAI,EAAE,CAAC;YAClE,OAAO,WAAW,CAAC,KAAK,CAAC;QAC7B,CAAC;QAED,sCAAsC;QACtC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,GAAG,SAAS,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QAChH,IAAI,WAAW,EAAE,KAAK,KAAK,SAAS,IAAI,WAAW,EAAE,KAAK,KAAK,IAAI,EAAE,CAAC;YAClE,IAAI,CAAC;gBACD,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;YACpD,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACT,MAAM,IAAI,KAAK,CAAC,mBAAmB,SAAS,6BAA6B,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC3H,CAAC;QACL,CAAC;QAED,OAAO,SAAS,CAAC;IACrB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,CAAC,MAAuB,EAAE,SAAiB;QAC1D,MAAM,WAAW,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;QACrG,IAAI,WAAW,EAAE,KAAK,KAAK,SAAS,IAAI,WAAW,EAAE,KAAK,KAAK,IAAI,EAAE,CAAC;YAClE,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,GAAG,SAAS,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QAChH,OAAO,WAAW,EAAE,KAAK,KAAK,SAAS,IAAI,WAAW,EAAE,KAAK,KAAK,IAAI,CAAC;IAC3E,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,oBAAoB,CAAC,MAAuB,EAAE,SAAiB;QAClE,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACnD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,GAAG,SAAS,8CAA8C,SAAS,cAAc,SAAS,SAAS,CAAC,CAAC;QACzH,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;CACJ;AA7DD,0CA6DC"}

package/dist/custom/web/duckduckgo-rate-limiter.d.ts

@@ -0,0 +1,85 @@
+export interface RateLimitConfig {
+    maxConcurrent: number;
+    queueTimeout: number;
+    retryDelay: number;
+    maxRetries: number;
+    resetQueueAfterMs: number;
+}
+export interface SearchRequest {
+    url: string;
+    options: RequestInit;
+    disableQueueing?: boolean;
+}
+export interface SearchResponse {
+    response: Response;
+    text: string;
+}
+/**
+ * Adaptive rate limiter for DuckDuckGo searches
+ * - Starts with immediate execution (no queue)
+ * - Activates queue on rate limit errors (202, 403, 429)
+ * - Automatically deactivates queue after success period or when empty
+ */
+export declare class DuckDuckGoRateLimiter {
+    private requestQueue$;
+    private isQueueActive;
+    private lastRateLimitTime;
+    private resetQueueTimer?;
+    private activeRequests;
+    private queuedRequests;
+    private requestCounter;
+    private readonly config;
+    private readonly rateLimitStatusCodes;
+    constructor(config?: Partial<RateLimitConfig>);
+    /**
+     * Process requests through the queue when active
+     */
+    private setupQueueProcessor;
+    /**
+     * Check if queue is empty and deactivate if so
+     */
+    private checkQueueEmpty;
+    /**
+     * Execute a single request attempt
+     */
+    private executeSingleRequest;
+    /**
+     * Execute request with retry logic
+     */
+    private executeRequestWithRetries;
+    /**
+     * Activate the request queue due to rate limiting
+     */
+    private activateQueue;
+    /**
+     * Schedule queue deactivation after successful requests
+     */
+    private scheduleQueueReset;
+    /**
+     * Execute a search request through the rate limiter
+     */
+    search(request: SearchRequest): Promise<SearchResponse>;
+    /**
+     * Get current queue status
+     */
+    getStatus(): {
+        isQueueActive: boolean;
+        activeRequests: number;
+        queuedRequests: number;
+        totalProcessed: number;
+        lastRateLimitTime: number;
+    };
+    /**
+     * Force queue activation (for testing)
+     */
+    forceActivateQueue(): void;
+    /**
+     * Force queue deactivation (for testing)
+     */
+    forceDeactivateQueue(): void;
+}
+/**
+ * Get the singleton rate limiter instance
+ */
+export declare function getDuckDuckGoRateLimiter(config?: Partial<RateLimitConfig>): DuckDuckGoRateLimiter;
+//# sourceMappingURL=duckduckgo-rate-limiter.d.ts.map

package/dist/custom/web/duckduckgo-rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckduckgo-rate-limiter.d.ts","sourceRoot":"","sources":["../../../src/custom/web/duckduckgo-rate-limiter.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,WAAW,CAAC;IACrB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,qBAAa,qBAAqB;IAC9B,OAAO,CAAC,aAAa,CAKhB;IAEL,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,eAAe,CAAC,CAAiB;IACzC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,cAAc,CAAK;IAE3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAMrB;IAEF,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAmB;gBAE5C,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC;IAK7C;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA8B3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAavB;;OAEG;YACW,oBAAoB;IAwBlC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAwCjC;;OAEG;IACH,OAAO,CAAC,aAAa;IAiBrB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAoB1B;;OAEG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IAgD7D;;OAEG;IACH,SAAS,IAAI;QACT,aAAa,EAAE,OAAO,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,iBAAiB,EAAE,MAAM,CAAC;KAC7B;IAUD;;OAEG;IACH,kBAAkB,IAAI,IAAI;IAI1B;;OAEG;IACH,oBAAoB,IAAI,IAAI;CAO/B;AAKD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,qBAAqB,CAKjG"}

package/dist/custom/web/duckduckgo-rate-limiter.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDuckDuckGoRateLimiter = exports.DuckDuckGoRateLimiter = void 0;
+const rxjs_1 = require("rxjs");
+const operators_1 = require("rxjs/operators");
+/**
+ * Adaptive rate limiter for DuckDuckGo searches
+ * - Starts with immediate execution (no queue)
+ * - Activates queue on rate limit errors (202, 403, 429)
+ * - Automatically deactivates queue after success period or when empty
+ */
+class DuckDuckGoRateLimiter {
+    requestQueue$ = new rxjs_1.Subject();
+    isQueueActive = false;
+    lastRateLimitTime = 0;
+    resetQueueTimer;
+    activeRequests = 0;
+    queuedRequests = 0;
+    requestCounter = 0;
+    config = {
+        maxConcurrent: 1, // When queue is active, serialize requests
+        queueTimeout: 30000, // 30 seconds timeout for queued requests
+        retryDelay: 2000, // 2 seconds between retries
+        maxRetries: 4,
+        resetQueueAfterMs: 5000 // Reset queue after 5 seconds of success
+    };
+    rateLimitStatusCodes = [202, 403, 429];
+    constructor(config) {
+        this.config = { ...this.config, ...config };
+        this.setupQueueProcessor();
+    }
+    /**
+     * Process requests through the queue when active
+     */
+    setupQueueProcessor() {
+        // Only process queued requests when queue is active
+        this.requestQueue$.pipe((0, operators_1.concatMap)(({ request, resolver, rejecter, requestId }) => {
+            this.activeRequests++;
+            console.log(`        ⚙️  Processing queued request ${requestId} - Active: ${this.activeRequests}, Remaining in queue: ${this.queuedRequests - 1}`);
+            return this.executeRequestWithRetries(request, requestId).pipe((0, operators_1.tap)({
+                next: (result) => {
+                    this.activeRequests--;
+                    this.queuedRequests--;
+                    console.log(`        ✅ Queued request ${requestId} completed - Remaining in queue: ${this.queuedRequests}`);
+                    resolver(result);
+                    this.checkQueueEmpty();
+                },
+                error: (error) => {
+                    this.activeRequests--;
+                    this.queuedRequests--;
+                    console.log(`        ❌ Queued request ${requestId} failed: ${error.message} - Remaining in queue: ${this.queuedRequests}`);
+                    rejecter(error);
+                    this.checkQueueEmpty();
+                }
+            }), (0, operators_1.catchError)(() => rxjs_1.EMPTY) // Prevent stream termination
+            );
+        })).subscribe();
+    }
+    /**
+     * Check if queue is empty and deactivate if so
+     */
+    checkQueueEmpty() {
+        if (this.isQueueActive && this.queuedRequests === 0 && this.activeRequests === 0) {
+            console.log(`\n        🟢🟢🟢 QUEUE DEACTIVATED 🟢🟢🟢`);
+            console.log(`        Queue is empty - returning to immediate execution mode`);
+            console.log(`        🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢\n`);
+            this.isQueueActive = false;
+            if (this.resetQueueTimer) {
+                clearTimeout(this.resetQueueTimer);
+                this.resetQueueTimer = undefined;
+            }
+        }
+    }
+    /**
+     * Execute a single request attempt
+     */
+    async executeSingleRequest(request, requestId) {
+        const startTime = Date.now();
+        try {
+            const response = await fetch(request.url, request.options);
+            const text = await response.text();
+            const duration = Date.now() - startTime;
+            // Check for rate limit status codes
+            if (this.rateLimitStatusCodes.includes(response.status)) {
+                console.log(`\n        🚨🚨🚨 RATE LIMIT DETECTED 🚨🚨🚨`);
+                console.log(`        Request ${requestId} got ${response.status} status`);
+                console.log(`        URL: ${request.url.substring(0, 100)}...`);
+                console.log(`        Duration: ${duration}ms`);
+                console.log(`        🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨\n`);
+                throw new Error(`Rate limited: ${response.status}`);
+            }
+            return { response, text };
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Execute request with retry logic
+     */
+    executeRequestWithRetries(request, requestId) {
+        let attemptCount = 0;
+        return (0, rxjs_1.from)(this.executeSingleRequest(request, requestId)).pipe((0, operators_1.timeout)(this.config.queueTimeout), (0, operators_1.retry)({
+            count: this.config.maxRetries,
+            delay: (error, retryCount) => {
+                attemptCount = retryCount;
+                // Check if it's a rate limit error
+                const isRateLimit = error.message?.includes('Rate limited');
+                if (isRateLimit) {
+                    const delayMs = this.config.retryDelay * Math.pow(2, retryCount - 1);
+                    console.log(`        ⏳ Rate limit retry ${retryCount}/${this.config.maxRetries} - waiting ${delayMs}ms before retry`);
+                    return (0, rxjs_1.timer)(delayMs);
+                }
+                // For other errors, retry immediately
+                return (0, rxjs_1.timer)(0);
+            }
+        }), (0, operators_1.tap)({
+            next: () => {
+                if (attemptCount > 0) {
+                    console.log(`        ✅ Request ${requestId} succeeded after ${attemptCount} retries`);
+                }
+                this.scheduleQueueReset();
+            }
+        }), (0, operators_1.catchError)((error) => {
+            if (error.message?.includes('Rate limited')) {
+                console.log(`        ❌ Request ${requestId} failed after all retries - still rate limited`);
+            }
+            return (0, rxjs_1.throwError)(() => error);
+        }));
+    }
+    /**
+     * Activate the request queue due to rate limiting
+     */
+    activateQueue() {
+        if (!this.isQueueActive) {
+            console.log(`\n        🔴🔴🔴 QUEUE ACTIVATED 🔴🔴🔴`);
+            console.log(`        Rate limiting detected - all future requests will be queued`);
+            console.log(`        Queue will deactivate when empty or after ${this.config.resetQueueAfterMs}ms of success`);
+            console.log(`        🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴🔴\n`);
+            this.isQueueActive = true;
+            this.lastRateLimitTime = Date.now();
+        }
+        // Cancel any pending queue reset
+        if (this.resetQueueTimer) {
+            clearTimeout(this.resetQueueTimer);
+            this.resetQueueTimer = undefined;
+        }
+    }
+    /**
+     * Schedule queue deactivation after successful requests
+     */
+    scheduleQueueReset() {
+        if (!this.isQueueActive)
+            return;
+        // Clear existing timer
+        if (this.resetQueueTimer) {
+            clearTimeout(this.resetQueueTimer);
+        }
+        // Schedule queue reset
+        this.resetQueueTimer = setTimeout(() => {
+            if (Date.now() - this.lastRateLimitTime >= this.config.resetQueueAfterMs) {
+                console.log(`\n        🟢🟢🟢 QUEUE DEACTIVATED (TIMEOUT) 🟢🟢🟢`);
+                console.log(`        No rate limits for ${this.config.resetQueueAfterMs}ms - returning to immediate execution`);
+                console.log(`        🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢🟢\n`);
+                this.isQueueActive = false;
+                this.resetQueueTimer = undefined;
+            }
+        }, this.config.resetQueueAfterMs);
+    }
+    /**
+     * Execute a search request through the rate limiter
+     */
+    async search(request) {
+        const requestId = `REQ-${++this.requestCounter}`;
+        return new Promise((resolve, reject) => {
+            // If queueing is disabled and queue is active, fail immediately
+            if (request.disableQueueing && this.isQueueActive) {
+                console.log(`        🚫 Request ${requestId} rejected - rate limiting active and queueing disabled`);
+                reject(new Error('Rate limiting active and queueing is disabled'));
+                return;
+            }
+            // If queue is not active, execute immediately
+            if (!this.isQueueActive) {
+                this.activeRequests++;
+                this.executeRequestWithRetries(request, requestId)
+                    .subscribe({
+                    next: (result) => {
+                        this.activeRequests--;
+                        resolve(result);
+                    },
+                    error: (error) => {
+                        this.activeRequests--;
+                        // Check if we got rate limited
+                        if (error.message?.includes('Rate limited')) {
+                            console.log(`        🔄 Request ${requestId} was rate limited, activating queue for future requests`);
+                            this.activateQueue();
+                        }
+                        reject(error);
+                    }
+                });
+            }
+            else {
+                // Queue is active, add to queue
+                console.log(`        📥 Request ${requestId} added to queue (position: ${this.queuedRequests + 1})`);
+                this.queuedRequests++;
+                this.requestQueue$.next({
+                    request,
+                    resolver: resolve,
+                    rejecter: reject,
+                    requestId
+                });
+            }
+        });
+    }
+    /**
+     * Get current queue status
+     */
+    getStatus() {
+        return {
+            isQueueActive: this.isQueueActive,
+            activeRequests: this.activeRequests,
+            queuedRequests: this.queuedRequests,
+            totalProcessed: this.requestCounter,
+            lastRateLimitTime: this.lastRateLimitTime
+        };
+    }
+    /**
+     * Force queue activation (for testing)
+     */
+    forceActivateQueue() {
+        this.activateQueue();
+    }
+    /**
+     * Force queue deactivation (for testing)
+     */
+    forceDeactivateQueue() {
+        this.isQueueActive = false;
+        if (this.resetQueueTimer) {
+            clearTimeout(this.resetQueueTimer);
+            this.resetQueueTimer = undefined;
+        }
+    }
+}
+exports.DuckDuckGoRateLimiter = DuckDuckGoRateLimiter;
+// Singleton instance
+let rateLimiterInstance = null;
+/**
+ * Get the singleton rate limiter instance
+ */
+function getDuckDuckGoRateLimiter(config) {
+    if (!rateLimiterInstance) {
+        rateLimiterInstance = new DuckDuckGoRateLimiter(config);
+    }
+    return rateLimiterInstance;
+}
+exports.getDuckDuckGoRateLimiter = getDuckDuckGoRateLimiter;
+//# sourceMappingURL=duckduckgo-rate-limiter.js.map