@memberjunction/core-actions 5.38.0 → 5.40.0

package/dist/custom/ai/run-cluster-analysis.action.d.ts

@@ -0,0 +1,49 @@
+import { ActionResultSimple, RunActionParams } from '@memberjunction/actions-base';
+import { BaseAction } from '@memberjunction/actions';
+/**
+ * Action: "Run Cluster Analysis"
+ *
+ * Thin wrapper over {@link ClusteringEngine.RunPipeline}. Fetches embedding
+ * vectors for an entity / entity document, clusters them (KMeans or DBSCAN),
+ * projects them to 2D/3D, optionally names clusters with an LLM, and — when a
+ * `PersistAs` name is supplied — persists the result to `MJ: Cluster Analysis`.
+ *
+ * All business logic lives in the engine; this action only maps params and
+ * returns a summary.
+ *
+ * Parameters (Input):
+ *  - EntityID: ID of the entity to cluster (alternative to EntityDocumentID).
+ *  - EntityDocumentID: specific Entity Document supplying vectors.
+ *  - Algorithm: 'kmeans' (default) or 'dbscan'.
+ *  - K: number of clusters for KMeans (default 4).
+ *  - Epsilon: DBSCAN neighbourhood radius (default 0.3).
+ *  - MinPoints: DBSCAN minimum points (default 3).
+ *  - DistanceMetric: 'cosine' (default) | 'euclidean' | 'dotproduct'.
+ *  - MaxRecords: max records to fetch (default 500).
+ *  - Filter: optional SQL filter applied to the source records.
+ *  - NameClusters: 'true' to run LLM cluster naming (default false).
+ *  - PersistAs: when set, the analysis is saved with this name.
+ *
+ * Output params: AnalysisID (when persisted), ClusterCount, RecordCount, SilhouetteScore.
+ */
+export declare class RunClusterAnalysisAction extends BaseAction {
+    protected InternalRunAction(params: RunActionParams): Promise<ActionResultSimple>;
+    /** Build a {@link ClusterConfig} from the action params. */
+    private buildConfig;
+    /** Persist the analysis when a PersistAs name is supplied; return its ID or null. */
+    private maybePersist;
+    /** Add output params summarizing the run. */
+    private addOutputs;
+    /** Build a human-readable summary message. */
+    private buildSummary;
+    /** Coerce the engine metric onto the supported union, defaulting to cosine. */
+    private normalizeMetric;
+    private findParam;
+    private getString;
+    private getNumber;
+    private getBoolean;
+    private addOutput;
+}
+/** Tree-shaking prevention — call from index to keep the @RegisterClass alive. */
+export declare function LoadRunClusterAnalysisAction(): void;
+//# sourceMappingURL=run-cluster-analysis.action.d.ts.map

package/dist/custom/ai/run-cluster-analysis.action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-cluster-analysis.action.d.ts","sourceRoot":"","sources":["../../../src/custom/ai/run-cluster-analysis.action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAe,MAAM,8BAA8B,CAAC;AAChG,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAYrD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBACa,wBAAyB,SAAQ,UAAU;cACpC,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAyCvF,4DAA4D;IAC5D,OAAO,CAAC,WAAW;IAkBnB,qFAAqF;YACvE,YAAY;IAkB1B,6CAA6C;IAC7C,OAAO,CAAC,UAAU;IASlB,8CAA8C;IAC9C,OAAO,CAAC,YAAY;IAcpB,+EAA+E;IAC/E,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,SAAS;CASpB;AAED,kFAAkF;AAClF,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD"}

package/dist/custom/ai/run-cluster-analysis.action.js

@@ -0,0 +1,187 @@
+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;
+};
+import { BaseAction } from '@memberjunction/actions';
+import { RegisterClass } from '@memberjunction/global';
+import { LogError } from '@memberjunction/core';
+import { ClusteringEngine, EntityDocumentVectorSource, } from '@memberjunction/clustering-engine';
+/**
+ * Action: "Run Cluster Analysis"
+ *
+ * Thin wrapper over {@link ClusteringEngine.RunPipeline}. Fetches embedding
+ * vectors for an entity / entity document, clusters them (KMeans or DBSCAN),
+ * projects them to 2D/3D, optionally names clusters with an LLM, and — when a
+ * `PersistAs` name is supplied — persists the result to `MJ: Cluster Analysis`.
+ *
+ * All business logic lives in the engine; this action only maps params and
+ * returns a summary.
+ *
+ * Parameters (Input):
+ *  - EntityID: ID of the entity to cluster (alternative to EntityDocumentID).
+ *  - EntityDocumentID: specific Entity Document supplying vectors.
+ *  - Algorithm: 'kmeans' (default) or 'dbscan'.
+ *  - K: number of clusters for KMeans (default 4).
+ *  - Epsilon: DBSCAN neighbourhood radius (default 0.3).
+ *  - MinPoints: DBSCAN minimum points (default 3).
+ *  - DistanceMetric: 'cosine' (default) | 'euclidean' | 'dotproduct'.
+ *  - MaxRecords: max records to fetch (default 500).
+ *  - Filter: optional SQL filter applied to the source records.
+ *  - NameClusters: 'true' to run LLM cluster naming (default false).
+ *  - PersistAs: when set, the analysis is saved with this name.
+ *
+ * Output params: AnalysisID (when persisted), ClusterCount, RecordCount, SilhouetteScore.
+ */
+let RunClusterAnalysisAction = class RunClusterAnalysisAction extends BaseAction {
+    async InternalRunAction(params) {
+        try {
+            const config = this.buildConfig(params);
+            if (!config.EntityID && !config.EntityDocumentID) {
+                return {
+                    Success: false,
+                    ResultCode: 'MISSING_PARAMETER',
+                    Message: "One of 'EntityID' or 'EntityDocumentID' is required.",
+                };
+            }
+            const engine = new ClusteringEngine();
+            const source = new EntityDocumentVectorSource(params.ContextUser, params.Provider);
+            const result = await engine.RunPipeline(config, source, params.ContextUser);
+            if (result.Metrics.RecordCount === 0) {
+                return {
+                    Success: false,
+                    ResultCode: 'NO_VECTORS',
+                    Message: 'No vectors were found for the supplied entity / document / filter.',
+                };
+            }
+            const analysisID = await this.maybePersist(params, engine, result, config);
+            this.addOutputs(params, result, analysisID);
+            return {
+                Success: true,
+                ResultCode: 'SUCCESS',
+                Message: this.buildSummary(result, analysisID),
+            };
+        }
+        catch (error) {
+            LogError(`RunClusterAnalysisAction: ${error}`);
+            return {
+                Success: false,
+                ResultCode: 'UNEXPECTED_ERROR',
+                Message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /** Build a {@link ClusterConfig} from the action params. */
+    buildConfig(params) {
+        const algorithm = this.getString(params, 'algorithm', 'kmeans').toLowerCase();
+        const metric = this.getString(params, 'distancemetric', 'cosine').toLowerCase();
+        return {
+            EntityID: this.getString(params, 'entityid', ''),
+            EntityDocumentID: this.getString(params, 'entitydocumentid', ''),
+            Algorithm: (algorithm === 'dbscan' ? 'dbscan' : 'kmeans'),
+            K: this.getNumber(params, 'k', 4),
+            Epsilon: this.getNumber(params, 'epsilon', 0.3),
+            MinPoints: this.getNumber(params, 'minpoints', 3),
+            DistanceMetric: this.normalizeMetric(metric),
+            MaxRecords: this.getNumber(params, 'maxrecords', 500),
+            Filter: this.getString(params, 'filter', ''),
+            NameClusters: this.getBoolean(params, 'nameclusters', false),
+            Dimensions: 2,
+        };
+    }
+    /** Persist the analysis when a PersistAs name is supplied; return its ID or null. */
+    async maybePersist(params, engine, result, config) {
+        const persistAs = this.getString(params, 'persistas', '');
+        if (!persistAs) {
+            return null;
+        }
+        const user = params.ContextUser;
+        if (!user) {
+            LogError('RunClusterAnalysisAction: PersistAs supplied but no ContextUser available — skipping persistence.');
+            return null;
+        }
+        return engine.SaveAnalysis(result, config, { Name: persistAs, UserID: user.ID }, user, params.Provider);
+    }
+    /** Add output params summarizing the run. */
+    addOutputs(params, result, analysisID) {
+        if (analysisID) {
+            this.addOutput(params, 'AnalysisID', analysisID);
+        }
+        this.addOutput(params, 'ClusterCount', result.Metrics.ClusterCount);
+        this.addOutput(params, 'RecordCount', result.Metrics.RecordCount);
+        this.addOutput(params, 'SilhouetteScore', result.Metrics.SilhouetteScore);
+    }
+    /** Build a human-readable summary message. */
+    buildSummary(result, analysisID) {
+        const m = result.Metrics;
+        const parts = [
+            `Clustered ${m.RecordCount} records into ${m.ClusterCount} clusters`,
+            `silhouette=${m.SilhouetteScore.toFixed(3)}`,
+            `outliers=${m.OutlierCount}`,
+            `time=${m.ComputationTimeMs}ms`,
+        ];
+        if (analysisID) {
+            parts.push(`saved as ${analysisID}`);
+        }
+        return parts.join(', ');
+    }
+    /** Coerce the engine metric onto the supported union, defaulting to cosine. */
+    normalizeMetric(metric) {
+        if (metric === 'euclidean' || metric === 'dotproduct') {
+            return metric;
+        }
+        return 'cosine';
+    }
+    // ---- param helpers -------------------------------------------------
+    findParam(params, name) {
+        return params.Params.find((p) => p.Name.trim().toLowerCase() === name.toLowerCase());
+    }
+    getString(params, name, defaultValue) {
+        const param = this.findParam(params, name);
+        if (!param || param.Value === undefined || param.Value === null) {
+            return defaultValue;
+        }
+        const value = String(param.Value).trim();
+        return value.length > 0 ? value : defaultValue;
+    }
+    getNumber(params, name, defaultValue) {
+        const param = this.findParam(params, name);
+        if (!param || param.Value === undefined || param.Value === null) {
+            return defaultValue;
+        }
+        const parsed = Number(param.Value);
+        return Number.isNaN(parsed) ? defaultValue : parsed;
+    }
+    getBoolean(params, name, defaultValue) {
+        const param = this.findParam(params, name);
+        if (!param || param.Value === undefined || param.Value === null) {
+            return defaultValue;
+        }
+        const value = String(param.Value).trim().toLowerCase();
+        if (value === 'true' || value === '1' || value === 'yes')
+            return true;
+        if (value === 'false' || value === '0' || value === 'no')
+            return false;
+        return defaultValue;
+    }
+    addOutput(params, name, value) {
+        const existing = this.findParam(params, name);
+        if (existing) {
+            existing.Value = value;
+            existing.Type = 'Output';
+        }
+        else {
+            params.Params.push({ Name: name, Type: 'Output', Value: value });
+        }
+    }
+};
+RunClusterAnalysisAction = __decorate([
+    RegisterClass(BaseAction, 'Run Cluster Analysis')
+], RunClusterAnalysisAction);
+export { RunClusterAnalysisAction };
+/** Tree-shaking prevention — call from index to keep the @RegisterClass alive. */
+export function LoadRunClusterAnalysisAction() {
+    // no-op
+}
+//# sourceMappingURL=run-cluster-analysis.action.js.map

package/dist/custom/ai/run-cluster-analysis.action.js.map

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

package/dist/custom/data/search-entity.action.d.ts

@@ -0,0 +1,48 @@
+import { ActionResultSimple, RunActionParams } from "@memberjunction/actions-base";
+import { BaseAction } from "@memberjunction/actions";
+/**
+ * Action wrapper around {@link Metadata.Provider.SearchEntity}: ranked hybrid
+ * (lexical + semantic) search over one entity's records, with permission
+ * filtering. The classic agent prompt-seeding case — swap a 1500-row entity
+ * dump for "here are 10 likely candidates" — is just
+ * `SearchEntity({ entityName: 'MJ: Entities', searchText: userText, options: { topK: 10 } })`.
+ *
+ * ## When to use this Action vs. the others MJ already exposes
+ *
+ * - **Search Entity** (this action): "Find me the N most relevant *records* of
+ *   one entity for this free-text request." Hybrid lexical + semantic ranking,
+ *   backed by an `EntityDocument` of type `Search`. Use for agent prompt
+ *   seeding, in-app "find a customer/invoice/document" UX.
+ * - **Get Entity Details / Get Entity List**: deterministic metadata or row
+ *   reads, no ranking. Use when you already know which entity / which records.
+ * - **Search Query Catalog** / unified `Search` actions (`@memberjunction/ai-search`):
+ *   cross-source search across vectors, full-text, entities, storage — broader
+ *   in scope, slower, requires SearchScope configuration. Use when the agent
+ *   doesn't know which entity to look in.
+ *
+ * Returns a JSON payload of `{ count, results: EntitySearchResult[] }` in the
+ * action `Message`, plus `Count` and `Results` output params.
+ *
+ * @example
+ * ```typescript
+ * await runAction({
+ *   ActionName: 'Search Entity',
+ *   Params: [
+ *     { Name: 'EntityName', Value: 'MJ: Entities' },
+ *     { Name: 'SearchText', Value: 'invoices' },
+ *     { Name: 'TopK', Value: 10 },
+ *     { Name: 'Mode', Value: 'hybrid' }
+ *   ]
+ * });
+ * ```
+ */
+export declare class SearchEntityAction extends BaseAction {
+    protected InternalRunAction(params: RunActionParams): Promise<ActionResultSimple>;
+    private getStringParam;
+    private getNumericParam;
+    private addOutputParam;
+}
+/** Tree-shaking prevention export — called from the package's barrel to keep
+ *  the class registration alive under aggressive bundlers. */
+export declare function LoadSearchEntityAction(): void;
+//# sourceMappingURL=search-entity.action.d.ts.map

package/dist/custom/data/search-entity.action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-entity.action.d.ts","sourceRoot":"","sources":["../../../src/custom/data/search-entity.action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEnF,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBACa,kBAAmB,SAAQ,UAAU;cAE9B,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAqEvF,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,cAAc;CAGzB;AAED;8DAC8D;AAC9D,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/custom/data/search-entity.action.js

@@ -0,0 +1,138 @@
+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;
+};
+import { RegisterClass } from "@memberjunction/global";
+import { BaseAction } from "@memberjunction/actions";
+import { LogError } from "@memberjunction/core";
+/**
+ * Action wrapper around {@link Metadata.Provider.SearchEntity}: ranked hybrid
+ * (lexical + semantic) search over one entity's records, with permission
+ * filtering. The classic agent prompt-seeding case — swap a 1500-row entity
+ * dump for "here are 10 likely candidates" — is just
+ * `SearchEntity({ entityName: 'MJ: Entities', searchText: userText, options: { topK: 10 } })`.
+ *
+ * ## When to use this Action vs. the others MJ already exposes
+ *
+ * - **Search Entity** (this action): "Find me the N most relevant *records* of
+ *   one entity for this free-text request." Hybrid lexical + semantic ranking,
+ *   backed by an `EntityDocument` of type `Search`. Use for agent prompt
+ *   seeding, in-app "find a customer/invoice/document" UX.
+ * - **Get Entity Details / Get Entity List**: deterministic metadata or row
+ *   reads, no ranking. Use when you already know which entity / which records.
+ * - **Search Query Catalog** / unified `Search` actions (`@memberjunction/ai-search`):
+ *   cross-source search across vectors, full-text, entities, storage — broader
+ *   in scope, slower, requires SearchScope configuration. Use when the agent
+ *   doesn't know which entity to look in.
+ *
+ * Returns a JSON payload of `{ count, results: EntitySearchResult[] }` in the
+ * action `Message`, plus `Count` and `Results` output params.
+ *
+ * @example
+ * ```typescript
+ * await runAction({
+ *   ActionName: 'Search Entity',
+ *   Params: [
+ *     { Name: 'EntityName', Value: 'MJ: Entities' },
+ *     { Name: 'SearchText', Value: 'invoices' },
+ *     { Name: 'TopK', Value: 10 },
+ *     { Name: 'Mode', Value: 'hybrid' }
+ *   ]
+ * });
+ * ```
+ */
+let SearchEntityAction = class SearchEntityAction extends BaseAction {
+    async InternalRunAction(params) {
+        try {
+            const entityName = this.getStringParam(params, "EntityName");
+            const searchText = this.getStringParam(params, "SearchText");
+            if (!entityName) {
+                return { Success: false, ResultCode: "MISSING_PARAMETER", Message: "Parameter 'EntityName' is required" };
+            }
+            if (!searchText) {
+                return { Success: false, ResultCode: "MISSING_PARAMETER", Message: "Parameter 'SearchText' is required" };
+            }
+            const mode = this.getStringParam(params, "Mode")?.toLowerCase();
+            const validModes = ['lexical', 'semantic', 'hybrid'];
+            if (mode && !validModes.includes(mode)) {
+                return {
+                    Success: false,
+                    ResultCode: "INVALID_PARAMETER",
+                    Message: `Mode must be one of: ${validModes.join(', ')}`,
+                };
+            }
+            const options = {
+                mode: mode ?? 'hybrid',
+                topK: this.getNumericParam(params, "TopK", 10),
+                minScore: this.getNumericParam(params, "MinScore", 0),
+                rrfK: this.getNumericParam(params, "RRFK", 60),
+                weights: {
+                    lexical: this.getNumericParam(params, "LexicalWeight", 1.0),
+                    semantic: this.getNumericParam(params, "SemanticWeight", 1.0),
+                },
+                entityDocumentId: this.getStringParam(params, "EntityDocumentID"),
+                contextUser: params.ContextUser,
+            };
+            // Always thread the invoking provider through — the action must run
+            // against the same metadata layer the caller is bound to (multi-server
+            // clients, request-scoped server-side providers). Falling back to the
+            // global `new Metadata()` would silently land on the wrong server in
+            // multi-provider scenarios. See CLAUDE.md "Don't Reach for the Global
+            // Metadata Provider in Per-Provider Code Paths".
+            const md = params.Provider;
+            if (!md) {
+                return {
+                    Success: false,
+                    ResultCode: "MISSING_PROVIDER",
+                    Message: "RunActionParams.Provider is required — SearchEntity must run against the caller's metadata provider.",
+                };
+            }
+            const searchParams = { entityName, searchText, options };
+            const results = await md.SearchEntity(searchParams);
+            this.addOutputParam(params, "Count", results.length);
+            this.addOutputParam(params, "Results", results);
+            return {
+                Success: true,
+                ResultCode: "SUCCESS",
+                Message: JSON.stringify({ count: results.length, results }),
+            };
+        }
+        catch (error) {
+            LogError(`SearchEntityAction failed: ${error instanceof Error ? error.message : String(error)}`);
+            return {
+                Success: false,
+                ResultCode: "UNEXPECTED_ERROR",
+                Message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    getStringParam(params, name) {
+        const p = params.Params.find(x => x.Name.trim().toLowerCase() === name.toLowerCase());
+        if (!p || p.Value == null)
+            return undefined;
+        const v = String(p.Value).trim();
+        return v.length > 0 ? v : undefined;
+    }
+    getNumericParam(params, name, defaultValue) {
+        const p = params.Params.find(x => x.Name.trim().toLowerCase() === name.toLowerCase());
+        if (!p || p.Value == null)
+            return defaultValue;
+        const n = Number(p.Value);
+        return Number.isFinite(n) ? n : defaultValue;
+    }
+    addOutputParam(params, name, value) {
+        params.Params.push({ Name: name, Type: "Output", Value: value });
+    }
+};
+SearchEntityAction = __decorate([
+    RegisterClass(BaseAction, "Search Entity")
+], SearchEntityAction);
+export { SearchEntityAction };
+/** Tree-shaking prevention export — called from the package's barrel to keep
+ *  the class registration alive under aggressive bundlers. */
+export function LoadSearchEntityAction() {
+    // intentionally empty
+}
+//# sourceMappingURL=search-entity.action.js.map

package/dist/custom/data/search-entity.action.js.map

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

package/dist/custom/esignature/base-esignature.action.d.ts

@@ -0,0 +1,24 @@
+import { RunActionParams } from '@memberjunction/actions-base';
+import { BaseAction } from '@memberjunction/actions';
+import { SignatureEngine } from '@memberjunction/esignature/server';
+/**
+ * Shared base for the thin eSignature Actions. Each concrete Action extracts its params, ensures the
+ * {@link SignatureEngine} is configured, and delegates to it — Actions are the boundary, the engine
+ * is the substance (per CLAUDE.md Actions philosophy).
+ */
+export declare abstract class BaseSignatureAction extends BaseAction {
+    /** Lazy-config the engine with the action's context user. */
+    protected ensureEngine(params: RunActionParams): Promise<SignatureEngine>;
+    /** Case-insensitive string param lookup; returns undefined when absent/blank. */
+    protected getStringParam(params: RunActionParams, name: string): string | undefined;
+    /** Case-insensitive boolean param with default. */
+    protected getBooleanParam(params: RunActionParams, name: string, defaultValue: boolean): boolean;
+    /**
+     * Case-insensitive param that may already be an object/array or a JSON string. Returns undefined
+     * when absent or unparseable.
+     */
+    protected getObjectParam<T>(params: RunActionParams, name: string): T | undefined;
+    /** Push an output param onto the action's param list. */
+    protected addOutput(params: RunActionParams, name: string, value: unknown): void;
+}
+//# sourceMappingURL=base-esignature.action.d.ts.map

package/dist/custom/esignature/base-esignature.action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-esignature.action.d.ts","sourceRoot":"","sources":["../../../src/custom/esignature/base-esignature.action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEpE;;;;GAIG;AACH,8BAAsB,mBAAoB,SAAQ,UAAU;IACxD,6DAA6D;cAC7C,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAK/E,iFAAiF;IACjF,SAAS,CAAC,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IASnF,mDAAmD;IACnD,SAAS,CAAC,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO;IAchG;;;OAGG;IACH,SAAS,CAAC,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAejF,yDAAyD;IACzD,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;CAOnF"}

package/dist/custom/esignature/base-esignature.action.js

@@ -0,0 +1,68 @@
+import { ActionParam } from '@memberjunction/actions-base';
+import { BaseAction } from '@memberjunction/actions';
+import { SignatureEngine } from '@memberjunction/esignature/server';
+/**
+ * Shared base for the thin eSignature Actions. Each concrete Action extracts its params, ensures the
+ * {@link SignatureEngine} is configured, and delegates to it — Actions are the boundary, the engine
+ * is the substance (per CLAUDE.md Actions philosophy).
+ */
+export class BaseSignatureAction extends BaseAction {
+    /** Lazy-config the engine with the action's context user. */
+    async ensureEngine(params) {
+        await SignatureEngine.Instance.Config(false, params.ContextUser);
+        return SignatureEngine.Instance;
+    }
+    /** Case-insensitive string param lookup; returns undefined when absent/blank. */
+    getStringParam(params, name) {
+        const param = params.Params.find((p) => p.Name.trim().toLowerCase() === name.toLowerCase());
+        if (!param || param.Value == null) {
+            return undefined;
+        }
+        const value = String(param.Value).trim();
+        return value.length > 0 ? value : undefined;
+    }
+    /** Case-insensitive boolean param with default. */
+    getBooleanParam(params, name, defaultValue) {
+        const param = params.Params.find((p) => p.Name.trim().toLowerCase() === name.toLowerCase());
+        if (!param || param.Value == null) {
+            return defaultValue;
+        }
+        if (typeof param.Value === 'boolean') {
+            return param.Value;
+        }
+        const value = String(param.Value).trim().toLowerCase();
+        if (value === 'true' || value === '1' || value === 'yes')
+            return true;
+        if (value === 'false' || value === '0' || value === 'no')
+            return false;
+        return defaultValue;
+    }
+    /**
+     * Case-insensitive param that may already be an object/array or a JSON string. Returns undefined
+     * when absent or unparseable.
+     */
+    getObjectParam(params, name) {
+        const param = params.Params.find((p) => p.Name.trim().toLowerCase() === name.toLowerCase());
+        if (!param || param.Value == null) {
+            return undefined;
+        }
+        if (typeof param.Value === 'string') {
+            try {
+                return JSON.parse(param.Value);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return param.Value;
+    }
+    /** Push an output param onto the action's param list. */
+    addOutput(params, name, value) {
+        const out = new ActionParam();
+        out.Name = name;
+        out.Type = 'Output';
+        out.Value = value;
+        params.Params.push(out);
+    }
+}
+//# sourceMappingURL=base-esignature.action.js.map

package/dist/custom/esignature/base-esignature.action.js.map

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

package/dist/custom/esignature/download-signed-document.action.d.ts

@@ -0,0 +1,15 @@
+import { ActionResultSimple, RunActionParams } from '@memberjunction/actions-base';
+import { BaseSignatureAction } from './base-esignature.action.js';
+/**
+ * Action: "Download Signed Document".
+ *
+ * Downloads the executed/signed document for a completed signature request and records it as a
+ * `Signed`-role document. Thin wrapper over {@link SignatureEngine.DownloadSigned}.
+ *
+ * Inputs: SignatureRequestID (required).
+ * Outputs: DocumentBase64, Filename, ContentType.
+ */
+export declare class DownloadSignedDocumentAction extends BaseSignatureAction {
+    protected InternalRunAction(params: RunActionParams): Promise<ActionResultSimple>;
+}
+//# sourceMappingURL=download-signed-document.action.d.ts.map

package/dist/custom/esignature/download-signed-document.action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download-signed-document.action.d.ts","sourceRoot":"","sources":["../../../src/custom/esignature/download-signed-document.action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D;;;;;;;;GAQG;AACH,qBACa,4BAA6B,SAAQ,mBAAmB;cACjD,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;CA2B1F"}

package/dist/custom/esignature/download-signed-document.action.js

@@ -0,0 +1,50 @@
+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;
+};
+import { RegisterClass } from '@memberjunction/global';
+import { BaseAction } from '@memberjunction/actions';
+import { BaseSignatureAction } from './base-esignature.action.js';
+/**
+ * Action: "Download Signed Document".
+ *
+ * Downloads the executed/signed document for a completed signature request and records it as a
+ * `Signed`-role document. Thin wrapper over {@link SignatureEngine.DownloadSigned}.
+ *
+ * Inputs: SignatureRequestID (required).
+ * Outputs: DocumentBase64, Filename, ContentType.
+ */
+let DownloadSignedDocumentAction = class DownloadSignedDocumentAction extends BaseSignatureAction {
+    async InternalRunAction(params) {
+        const requestId = this.getStringParam(params, 'SignatureRequestID');
+        if (!requestId) {
+            return { Success: false, ResultCode: 'PROVIDER_ERROR', Message: "Parameter 'SignatureRequestID' is required." };
+        }
+        try {
+            const engine = await this.ensureEngine(params);
+            const result = await engine.DownloadSigned(requestId, params.ContextUser);
+            if (!result.Success || !result.document) {
+                const notCompleted = (result.ErrorMessage ?? '').includes('not been sent');
+                return {
+                    Success: false,
+                    ResultCode: notCompleted ? 'NOT_COMPLETED' : 'PROVIDER_ERROR',
+                    Message: result.ErrorMessage ?? 'Download failed.',
+                };
+            }
+            this.addOutput(params, 'DocumentBase64', result.document.bytes.toString('base64'));
+            this.addOutput(params, 'Filename', result.document.filename);
+            this.addOutput(params, 'ContentType', result.document.contentType);
+            return { Success: true, ResultCode: 'OK', Message: `Downloaded ${result.document.filename}.`, Params: params.Params };
+        }
+        catch (e) {
+            return { Success: false, ResultCode: 'PROVIDER_ERROR', Message: e instanceof Error ? e.message : String(e) };
+        }
+    }
+};
+DownloadSignedDocumentAction = __decorate([
+    RegisterClass(BaseAction, 'Download Signed Document')
+], DownloadSignedDocumentAction);
+export { DownloadSignedDocumentAction };
+//# sourceMappingURL=download-signed-document.action.js.map

package/dist/custom/esignature/download-signed-document.action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download-signed-document.action.js","sourceRoot":"","sources":["../../../src/custom/esignature/download-signed-document.action.ts"],"names":[],"mappings":";;;;;;AACA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D;;;;;;;;GAQG;AAEI,IAAM,4BAA4B,GAAlC,MAAM,4BAA6B,SAAQ,mBAAmB;IACvD,KAAK,CAAC,iBAAiB,CAAC,MAAuB;QACrD,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;QACpE,IAAI,CAAC,SAAS,EAAE,CAAC;YACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,OAAO,EAAE,6CAA6C,EAAE,CAAC;QACpH,CAAC;QAED,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC/C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;YAE1E,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACtC,MAAM,YAAY,GAAG,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;gBAC3E,OAAO;oBACH,OAAO,EAAE,KAAK;oBACd,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,gBAAgB;oBAC7D,OAAO,EAAE,MAAM,CAAC,YAAY,IAAI,kBAAkB;iBACrD,CAAC;YACN,CAAC;YAED,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,gBAAgB,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;YACnF,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC7D,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;YACnE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,MAAM,CAAC,QAAQ,CAAC,QAAQ,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QAC1H,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACjH,CAAC;IACL,CAAC;CACJ,CAAA;AA5BY,4BAA4B;IADxC,aAAa,CAAC,UAAU,EAAE,0BAA0B,CAAC;GACzC,4BAA4B,CA4BxC"}