@memberjunction/actions-base 4.0.0 → 4.2.0

package/README.md

@@ -1,15 +1,8 @@
 # @memberjunction/actions-base
 
-Base classes and interfaces for the MemberJunction Actions framework. This library provides the foundational components for implementing and executing actions across both server and client environments.
+Base classes, interfaces, and metadata engines for the MemberJunction Actions framework. This package provides the foundational layer that both server-side (`@memberjunction/actions`) and client-side action implementations build upon. It handles action metadata loading, parameter modeling, result types, and extended entity classes with lazy-loaded relationships.
 
-## Overview
-
-The Actions framework in MemberJunction provides a flexible, metadata-driven system for executing business logic and operations. This base package contains the core classes and interfaces that enable:
-
-- **Action Engine**: Core engine for loading, configuring, and executing actions
-- **Entity Actions**: Actions that operate on specific entities with various invocation contexts
-- **Code Generation**: Support for dynamically generated action code with library management
-- **Execution Logging**: Built-in logging and result tracking for all action executions
+For the broader Actions design philosophy -- including when to use Actions vs. direct class imports, and the "thin wrapper" principle -- see the [parent Actions CLAUDE.md](../CLAUDE.md).
 
 ## Installation
 
@@ -17,347 +10,308 @@ The Actions framework in MemberJunction provides a flexible, metadata-driven sys
 npm install @memberjunction/actions-base
 ```
 
-## Core Components
-
-### ActionEngineBase
+## Architecture
+
+The package is organized into two parallel engine hierarchies: one for general-purpose **Actions** and one for **Entity Actions** (actions bound to a specific entity). Both engines are singletons that extend `BaseEngine` from `@memberjunction/core` and load their metadata via `Config()`.
+
+```mermaid
+graph TD
+    subgraph BasePackage["@memberjunction/actions-base"]
+        AEB["ActionEngineBase\n(singleton)"]
+        EAEB["EntityActionEngineBase\n(singleton)"]
+        AEX["ActionEntityExtended"]
+        EAEX["EntityActionEntityExtended"]
+        RAP["RunActionParams<TContext>"]
+        AR["ActionResult / ActionResultSimple"]
+        AP["ActionParam"]
+        GC["GeneratedCode"]
+        EAIP["EntityActionInvocationParams"]
+        EAR["EntityActionResult"]
+    end
+
+    subgraph CoreDeps["Dependencies"]
+        BE["BaseEngine\n(@memberjunction/core)"]
+        CE["Entity classes\n(@memberjunction/core-entities)"]
+        RC["@RegisterClass\n(@memberjunction/global)"]
+    end
+
+    AEB -->|extends| BE
+    EAEB -->|extends| BE
+    AEX -->|extends| CE
+    EAEX -->|extends| CE
+    AEX -->|registered via| RC
+    EAEX -->|registered via| RC
+    AEB -->|manages| AEX
+    EAEB -->|manages| EAEX
+
+    style BasePackage fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style CoreDeps fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style AEB fill:#7c5295,stroke:#563a6b,color:#fff
+    style EAEB fill:#7c5295,stroke:#563a6b,color:#fff
+    style AEX fill:#b8762f,stroke:#8a5722,color:#fff
+    style EAEX fill:#b8762f,stroke:#8a5722,color:#fff
+```
 
-The singleton base class that manages all action metadata and provides the foundation for action execution.
+### Data Flow: Config and Execution
 
-```typescript
-import { ActionEngineBase } from '@memberjunction/actions-base';
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant AEB as ActionEngineBase
+    participant DB as Database (via RunView)
+    participant AEX as ActionEntityExtended
 
-// Get the singleton instance
-const actionEngine = ActionEngineBase.Instance;
+    Caller->>AEB: Config(forceRefresh, contextUser)
+    AEB->>DB: RunViews (batch load 6 entity types)
+    DB-->>AEB: Actions, Categories, Filters, Params, ResultCodes, Libraries
+    AEB-->>Caller: Metadata ready
 
-// Configure the engine (required before use)
-await actionEngine.Config(false, userInfo);
+    Caller->>AEB: Actions (getter)
+    AEB-->>Caller: ActionEntityExtended[]
 
-// Access action metadata
-const allActions = actionEngine.Actions;
-const coreActions = actionEngine.CoreActions;
-const actionParams = actionEngine.ActionParams;
-const actionFilters = actionEngine.ActionFilters;
+    Caller->>AEX: ResultCodes (getter, lazy)
+    AEX->>AEB: ActionResultCodes (filtered by ActionID)
+    AEB-->>AEX: ActionResultCodeEntity[]
+    AEX-->>Caller: Cached result codes
 ```
 
-### EntityActionEngineBase
+## Exports
 
-Manages entity-specific actions and their various invocation contexts (single record, view-based, list-based).
+### Engine Classes
 
-```typescript
-import { EntityActionEngineBase } from '@memberjunction/actions-base';
-
-// Get the singleton instance
-const entityActionEngine = EntityActionEngineBase.Instance;
+| Export | Description |
+|--------|-------------|
+| `ActionEngineBase` | Singleton engine that loads and caches all action metadata (actions, categories, filters, params, result codes, libraries). Subclassed by server/client implementations. |
+| `EntityActionEngineBase` | Singleton engine for entity-bound actions. Loads entity actions, invocation types, filters, invocations, and params. |
 
-// Configure the engine
-await entityActionEngine.Config(false, userInfo);
+### Extended Entity Classes
 
-// Get actions for a specific entity
-const customerActions = entityActionEngine.GetActionsByEntityName('Customers', 'Active');
-
-// Get actions by invocation type
-const viewActions = entityActionEngine.GetActionsByEntityNameAndInvocationType(
-    'Orders', 
-    'View', 
-    'Active'
-);
-```
+| Export | Description |
+|--------|-------------|
+| `ActionEntityExtended` | Extends `ActionEntity` with lazy-loaded `ResultCodes`, `Params`, `Libraries`, plus computed `IsCoreAction` and `ProgrammaticName` properties. Registered as `'Actions'` in the MJ class factory. |
+| `EntityActionEntityExtended` | Extends `EntityActionEntity` with lazy-loaded `Filters`, `Invocations`, and `Params`. Registered as `'Entity Actions'` in the MJ class factory. |
 
-## Action Types and Models
+### Parameter and Result Types
 
-### ActionParam
+| Export | Description |
+|--------|-------------|
+| `RunActionParams<TContext>` | Configuration object for running an action. Includes the action entity, context user, filters, parameters, and an optional generic-typed `Context` for runtime-specific data. |
+| `ActionParam` | Key-value parameter with `Name`, `Value`, and `Type` (`'Input'` / `'Output'` / `'Both'`). |
+| `ActionResult` | Full result from engine execution, including `Success`, `Result` (result code entity), `LogEntry`, `Message`, and output `Params`. |
+| `ActionResultSimple` | Lightweight result returned by individual action implementations: `Success`, `ResultCode` (string), optional `Message` and `Params`. |
+| `EntityActionInvocationParams` | Parameters for invoking an entity action, including invocation type and one of `EntityObject`, `ViewID`, or `ListID`. |
+| `EntityActionResult` | Result from entity action execution with same structure as `ActionResult`. |
 
-Represents input/output parameters for actions:
+### Code Generation Support
 
-```typescript
-import { ActionParam } from '@memberjunction/actions-base';
+| Export | Description |
+|--------|-------------|
+| `GeneratedCode` | Container for AI-generated action code, including `Success`, `Code`, `LibrariesUsed`, `Comments`, and `ErrorMessage`. |
+| `ActionLibrary` | Library reference used in generated code: `LibraryName` and `ItemsUsed` (array of imported items). |
 
-const param: ActionParam = {
-    Name: 'CustomerID',
-    Value: '12345',
-    Type: 'Input' // 'Input' | 'Output' | 'Both'
-};
-```
+## Usage
 
-### RunActionParams
+### Configuring the Action Engine
 
-Configuration for running an action:
+Both engines must be configured before use. `Config()` loads metadata from the database and caches it. Pass `forceRefresh: true` to reload after metadata changes.
 
 ```typescript
-import { RunActionParams } from '@memberjunction/actions-base';
-
-const runParams: RunActionParams = {
-    Action: actionEntity,
-    ContextUser: userInfo,
-    SkipActionLog: false, // Optional
-    Filters: [], // Optional filters to run before action
-    Params: [
-        { Name: 'Input1', Value: 'test', Type: 'Input' }
-    ]
-};
-```
-
-#### Type-Safe Context Support (New in v2.51.0)
+import { ActionEngineBase } from '@memberjunction/actions-base';
+import { UserInfo } from '@memberjunction/core';
 
-RunActionParams now supports type-safe context propagation:
+async function initialize(contextUser: UserInfo) {
+    const engine = ActionEngineBase.Instance;
 
-```typescript
-import { RunActionParams } from '@memberjunction/actions-base';
+    // Initial load -- metadata cached in GlobalObjectStore
+    await engine.Config(false, contextUser);
 
-// Define your context type
-interface MyActionContext {
-    apiEndpoint: string;
-    apiKey: string;
-    environment: 'dev' | 'staging' | 'prod';
-    featureFlags: Record<string, boolean>;
+    // Access loaded metadata
+    const allActions = engine.Actions;          // ActionEntityExtended[]
+    const coreActions = engine.CoreActions;     // Only core MJ actions
+    const categories = engine.ActionCategories; // ActionCategoryEntity[]
+    const params = engine.ActionParams;         // ActionParamEntity[]
+    const filters = engine.ActionFilters;       // ActionFilterEntity[]
+    const resultCodes = engine.ActionResultCodes;
+    const libraries = engine.ActionLibraries;
 }
-
-// Create typed parameters
-const runParams = new RunActionParams<MyActionContext>();
-runParams.Action = actionEntity;
-runParams.ContextUser = userInfo;
-runParams.Params = [
-    { Name: 'customerID', Value: 'CUST123', Type: 'Input' },
-    { Name: 'orderAmount', Value: 150.00, Type: 'Input' }
-];
-
-// Set typed context
-runParams.Context = {
-    apiEndpoint: 'https://api.example.com',
-    apiKey: process.env.API_KEY,
-    environment: 'prod',
-    featureFlags: {
-        newFeature: true,
-        betaAccess: false
-    }
-};
 ```
 
-The context object is:
-- **Separate from parameters**: Not stored in the database or included in logs
-- **Runtime-specific**: For environment configuration, credentials, and session data
-- **Type-safe**: Full TypeScript support when using generics
-- **Propagated automatically**: Flows from agents to actions in the execution hierarchy
-
-### ActionResult
-
-The result object returned from action execution:
+### Configuring the Entity Action Engine
 
 ```typescript
-import { ActionResult } from '@memberjunction/actions-base';
-
-// ActionResult contains:
-// - Success: boolean indicating if action succeeded
-// - Result: ActionResultCodeEntity with the specific result code
-// - LogEntry: ActionExecutionLogEntity for tracking
-// - Message: Optional message about the outcome
-// - Params: All parameters including outputs
-```
-
-### EntityActionInvocationParams
-
-Parameters for invoking entity-specific actions:
+import { EntityActionEngineBase } from '@memberjunction/actions-base';
 
-```typescript
-import { EntityActionInvocationParams } from '@memberjunction/actions-base';
-
-const invocationParams: EntityActionInvocationParams = {
-    EntityAction: entityActionExtended,
-    InvocationType: invocationTypeEntity,
-    ContextUser: userInfo,
-    // One of these based on invocation type:
-    EntityObject: customerEntity, // For single record
-    ViewID: 'view-123', // For view-based
-    ListID: 'list-456' // For list-based
-};
-```
+async function initEntityActions(contextUser: UserInfo) {
+    const engine = EntityActionEngineBase.Instance;
+    await engine.Config(false, contextUser);
 
-## Extended Entity Classes
+    // All entity actions
+    const entityActions = engine.EntityActions; // EntityActionEntityExtended[]
 
-### ActionEntityExtended
+    // Filter by entity name and status
+    const customerActions = engine.GetActionsByEntityName('Customers', 'Active');
 
-Enhanced action entity with additional functionality:
+    // Filter by entity name and invocation type
+    const viewActions = engine.GetActionsByEntityNameAndInvocationType(
+        'Orders',
+        'View',
+        'Active'
+    );
 
-```typescript
-import { ActionEntityExtended } from '@memberjunction/actions-base';
-
-// Provides additional properties:
-const action = actionEngine.Actions[0] as ActionEntityExtended;
-console.log(action.IsCoreAction); // true if core MJ action
-console.log(action.ProgrammaticName); // Code-friendly name
-console.log(action.ResultCodes); // Possible result codes
-console.log(action.Params); // Action parameters
-console.log(action.Libraries); // Required libraries
+    // Filter by entity ID
+    const byId = engine.GetActionsByEntityID('some-entity-uuid');
+}
 ```
 
-### EntityActionEntityExtended
+### Working with ActionEntityExtended
 
-Enhanced entity action with related data:
+The extended entity class provides lazy-loaded related data and computed properties.
 
 ```typescript
-import { EntityActionEntityExtended } from '@memberjunction/actions-base';
+import { ActionEngineBase, ActionEntityExtended } from '@memberjunction/actions-base';
 
-// Provides lazy-loaded related data:
-const entityAction = entityActionEngine.EntityActions[0] as EntityActionEntityExtended;
-console.log(entityAction.Filters); // Associated filters
-console.log(entityAction.Invocations); // Invocation configurations
-console.log(entityAction.Params); // Action parameters
-```
-
-## Code Generation Support
+const engine = ActionEngineBase.Instance;
+await engine.Config(false, contextUser);
 
-The framework includes support for generated code with library tracking:
+const action: ActionEntityExtended = engine.Actions[0];
 
-```typescript
-import { GeneratedCode, ActionLibrary } from '@memberjunction/actions-base';
+// Computed properties
+console.log(action.IsCoreAction);     // boolean -- is this a core MJ action?
+console.log(action.ProgrammaticName); // Code-safe version of action name
 
-// GeneratedCode structure
-const generatedCode: GeneratedCode = {
-    Success: true,
-    Code: 'function execute() { ... }',
-    LibrariesUsed: [
-        {
-            LibraryName: 'lodash',
-            ItemsUsed: ['map', 'filter']
-        }
-    ],
-    Comments: 'Processes customer data',
-    ErrorMessage: undefined
-};
+// Lazy-loaded relationships (cached after first access)
+const resultCodes = action.ResultCodes; // ActionResultCodeEntity[]
+const params = action.Params;           // ActionParamEntity[]
+const libraries = action.Libraries;     // ActionLibraryEntity[]
 ```
 
-## Usage Examples
+### Building RunActionParams with Type-Safe Context
 
-### Basic Action Engine Configuration
+`RunActionParams` supports a generic `TContext` parameter for propagating runtime-specific data (API keys, environment config, feature flags) that is separate from action parameters and not persisted to logs.
 
 ```typescript
-import { ActionEngineBase } from '@memberjunction/actions-base';
+import { RunActionParams, ActionParam } from '@memberjunction/actions-base';
+import { ActionEntity } from '@memberjunction/core-entities';
 import { UserInfo } from '@memberjunction/core';
 
-async function initializeActionEngine(user: UserInfo) {
-    const engine = ActionEngineBase.Instance;
-    
-    // Initial configuration
-    await engine.Config(false, user);
-    
-    // Force refresh if needed
-    await engine.Config(true, user);
-    
-    // Access loaded metadata
-    console.log(`Loaded ${engine.Actions.length} actions`);
-    console.log(`Core actions: ${engine.CoreActions.length}`);
+// Define a context type for your environment
+interface ServiceContext {
+    apiEndpoint: string;
+    apiKey: string;
+    environment: 'dev' | 'staging' | 'prod';
+    retryPolicy: {
+        maxRetries: number;
+        backoffMs: number;
+    };
+}
+
+function buildRunParams(
+    action: ActionEntity,
+    user: UserInfo,
+    context: ServiceContext
+): RunActionParams<ServiceContext> {
+    const params = new RunActionParams<ServiceContext>();
+    params.Action = action;
+    params.ContextUser = user;
+    params.Params = [
+        { Name: 'CustomerID', Value: 'CUST-123', Type: 'Input' },
+        { Name: 'OrderTotal', Value: 250.00, Type: 'Input' }
+    ];
+    params.Context = context; // Type-checked against ServiceContext
+    return params;
 }
 ```
 
-### Working with Entity Actions
+### Entity Action Invocation
+
+Entity actions support three invocation modes depending on the context.
 
 ```typescript
-import { EntityActionEngineBase } from '@memberjunction/actions-base';
+import {
+    EntityActionInvocationParams,
+    EntityActionEngineBase
+} from '@memberjunction/actions-base';
 
-async function getEntityActions(entityName: string, user: UserInfo) {
-    const engine = EntityActionEngineBase.Instance;
-    await engine.Config(false, user);
-    
-    // Get all active actions for an entity
-    const actions = engine.GetActionsByEntityName(entityName, 'Active');
-    
-    // Filter by invocation type
-    const singleRecordActions = actions.filter(a => 
-        a.Invocations.some(i => i.InvocationType === 'Single Record')
-    );
-    
-    return singleRecordActions;
+const engine = EntityActionEngineBase.Instance;
+await engine.Config(false, contextUser);
+
+const entityActions = engine.GetActionsByEntityNameAndInvocationType(
+    'Customers',
+    'Single Record',
+    'Active'
+);
+
+if (entityActions.length > 0) {
+    const invocationParams: EntityActionInvocationParams = {
+        EntityAction: entityActions[0],
+        InvocationType: engine.InvocationTypes.find(
+            t => t.Name === 'Single Record'
+        )!,
+        ContextUser: contextUser,
+        EntityObject: customerRecord // BaseEntity instance
+    };
+    // Pass to your engine's run method
 }
 ```
 
-### Action Parameter Handling
+### Category Hierarchy Utilities
+
+`ActionEngineBase` provides methods for navigating the action category tree.
 
 ```typescript
-import { ActionParam } from '@memberjunction/actions-base';
-
-function prepareActionParams(inputs: Record<string, any>): ActionParam[] {
-    return Object.entries(inputs).map(([name, value]) => ({
-        Name: name,
-        Value: value,
-        Type: 'Input'
-    }));
-}
+const engine = ActionEngineBase.Instance;
 
-// Example usage
-const params = prepareActionParams({
-    CustomerID: '123',
-    OrderDate: new Date(),
-    TotalAmount: 150.00
-});
+// Check if a category is under the core actions root
+const isCoreCategory = engine.IsCoreActionCategory(someCategoryId);
+
+// Check if one category is a descendant of another (recursive)
+const isChild = engine.IsChildCategoryOf(childCategoryId, parentCategoryId);
+
+// Look up an action by name
+const action = engine.GetActionByName('Send Email');
 ```
 
-### Using Context in Actions
+### Code Generation Types
 
-Context provides runtime-specific information separate from business parameters:
+The `GeneratedCode` and `ActionLibrary` types support the AI-powered action generation system.
 
 ```typescript
-import { RunActionParams } from '@memberjunction/actions-base';
-
-interface ServiceContext {
-    apiEndpoint: string;
-    apiKey: string;
-    timeout: number;
-    retryPolicy: {
-        maxRetries: number;
-        backoffMs: number;
-    };
-}
+import { GeneratedCode, ActionLibrary } from '@memberjunction/actions-base';
 
-async function executeActionWithContext(
-    action: ActionEntity,
-    businessParams: ActionParam[],
-    context: ServiceContext,
-    user: UserInfo
-) {
-    const runParams = new RunActionParams<ServiceContext>();
-    runParams.Action = action;
-    runParams.ContextUser = user;
-    runParams.Params = businessParams;
-    runParams.Context = context;
-    
-    // The action implementation can access context via this.ContextObject
-    // This is useful for:
-    // - API configurations that vary by environment
-    // - Runtime credentials not stored in metadata
-    // - Session-specific settings
-    // - Feature flags and toggles
-    
-    const result = await actionEngine.RunAction(runParams);
-    return result;
-}
+const generated: GeneratedCode = {
+    Success: true,
+    Code: 'async function execute(params) { /* ... */ }',
+    LibrariesUsed: [
+        { LibraryName: 'lodash', ItemsUsed: ['map', 'filter', 'groupBy'] },
+        { LibraryName: '@memberjunction/core', ItemsUsed: ['RunView'] }
+    ],
+    Comments: 'Aggregates customer orders by region and calculates totals'
+};
 ```
 
-## Dependencies
-
-- `@memberjunction/global`: Global utilities and registration system
-- `@memberjunction/core`: Core MemberJunction interfaces and base classes
-- `@memberjunction/core-entities`: Entity definitions for MemberJunction metadata
+## Key Design Decisions
 
-## Integration with Other MemberJunction Packages
+**Singleton engines** -- Both `ActionEngineBase` and `EntityActionEngineBase` use the MJ `BaseEngine` singleton pattern. Always access them via the static `Instance` getter; never construct them directly.
 
-This package serves as the foundation for:
+**Lazy-loaded relationships** -- `ActionEntityExtended` and `EntityActionEntityExtended` fetch their related data (params, result codes, filters, invocations, libraries) lazily on first property access and cache the result. This avoids loading relationship data for actions that are never inspected.
 
-- `@memberjunction/actions-server`: Server-side action execution implementation
-- `@memberjunction/actions-client`: Client-side action execution
-- Custom action implementations in your applications
+**IgnoreMaxRows on Config** -- The engine overrides `LoadMultipleEntityConfigs` to set `IgnoreMaxRows: true`, ensuring all action metadata records are loaded regardless of entity-level `UserViewMaxRows` settings. Action Params in particular can exceed 1000 records.
 
-## Best Practices
+**Generic context on RunActionParams** -- The `TContext` generic preserves type safety for runtime context data flowing from agents through to action implementations, without polluting the persisted parameter system.
 
-1. **Always Configure Before Use**: Call `Config()` on the engine instances before accessing any metadata
-2. **Use Singleton Instances**: Always use the `.Instance` property to get engine instances
-3. **Handle Async Operations**: All configuration and many operations are asynchronous
-4. **Check Action Status**: Filter actions by status ('Active', 'Pending', 'Disabled') when appropriate
-5. **Validate Parameters**: Ensure all required input parameters are provided before execution
+## Dependencies
 
-## TypeScript Support
+| Package | Purpose |
+|---------|---------|
+| `@memberjunction/global` | `@RegisterClass` decorator and MJ class factory |
+| `@memberjunction/core` | `BaseEngine`, `BaseEntity`, `UserInfo`, `RunView`, `CodeNameFromString` |
+| `@memberjunction/core-entities` | Generated entity classes (`ActionEntity`, `EntityActionEntity`, and all related entities) |
 
-This package is written in TypeScript and provides full type definitions. All classes and interfaces are properly typed for optimal development experience.
+## Related Packages
 
-## License
+| Package | Relationship |
+|---------|-------------|
+| [`@memberjunction/actions`](../Engine) | Server-side engine that extends `ActionEngineBase` with execution, logging, and AI code generation |
+| [`@memberjunction/core-actions`](../CoreActions) | 40+ pre-built action implementations using `BaseAction` from the Engine package |
+| [`@memberjunction/scheduled-actions`](../ScheduledActions) | Cron-based scheduling engine for recurring action execution |
 
-ISC License - see LICENSE file in the root of the repository.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/actions-base",
   "type": "module",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Base Classes for MemberJunction Actions. This library is used on both server and network nodes.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,9 +20,9 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@memberjunction/global": "4.0.0",
-    "@memberjunction/core": "4.0.0",
-    "@memberjunction/core-entities": "4.0.0"
+    "@memberjunction/global": "4.2.0",
+    "@memberjunction/core": "4.2.0",
+    "@memberjunction/core-entities": "4.2.0"
   },
   "repository": {
     "type": "git",