@memberjunction/server 3.4.0 → 4.0.0

package/dist/rest/RESTEndpointHandler.js

@@ -2,31 +2,55 @@ import express from 'express';
 import { CompositeKey, EntityDeleteOptions, LogError, Metadata } from '@memberjunction/core';
 import { EntityCRUDHandler } from './EntityCRUDHandler.js';
 import { ViewOperationsHandler } from './ViewOperationsHandler.js';
+/**
+ * RESTEndpointHandler provides REST API functionality for MemberJunction entities
+ * This class handles request routing and processing for a /rest endpoint that exposes
+ * entity operations via REST instead of GraphQL
+ */
 export class RESTEndpointHandler {
-    router;
-    options;
     constructor(options = {}) {
         this.router = express.Router();
         this.options = options;
         this.setupRoutes();
     }
+    /**
+     * Helper to safely extract a string from Express route params
+     * Express 5.x types params as string | string[] | undefined
+     */
+    getStringParam(param) {
+        if (Array.isArray(param)) {
+            return param[0] || '';
+        }
+        return param || '';
+    }
+    /**
+     * Determines if an entity is allowed based on include/exclude lists
+     * with support for wildcards and schema-level filtering
+     * @param entityName The name of the entity to check
+     * @returns True if the entity is allowed, false otherwise
+     */
     isEntityAllowed(entityName) {
         const name = entityName.toLowerCase();
         const md = new Metadata();
         const entity = md.Entities.find(e => e.Name.toLowerCase() === name);
+        // If entity not found in metadata, don't allow it
         if (!entity) {
             return false;
         }
         const schemaName = entity.SchemaName.toLowerCase();
+        // 1. Check schema exclusions first (these take highest precedence)
         if (this.options.excludeSchemas && this.options.excludeSchemas.length > 0) {
             if (this.options.excludeSchemas.some(schema => schema.toLowerCase() === schemaName)) {
                 return false;
             }
         }
+        // 2. Check entity exclusions next (these override entity inclusions)
         if (this.options.excludeEntities && this.options.excludeEntities.length > 0) {
+            // Check for direct match
             if (this.options.excludeEntities.includes(name)) {
                 return false;
             }
+            // Check for wildcard matches
             for (const pattern of this.options.excludeEntities) {
                 if (pattern.includes('*')) {
                     const regex = new RegExp('^' + pattern.toLowerCase().replace(/\*/g, '.*') + '$');
@@ -36,15 +60,19 @@ export class RESTEndpointHandler {
                 }
             }
         }
+        // 3. Check schema inclusions (if specified, only entities from these schemas are allowed)
         if (this.options.includeSchemas && this.options.includeSchemas.length > 0) {
             if (!this.options.includeSchemas.some(schema => schema.toLowerCase() === schemaName)) {
                 return false;
             }
         }
+        // 4. Check entity inclusions
         if (this.options.includeEntities && this.options.includeEntities.length > 0) {
+            // Check for direct match
             if (this.options.includeEntities.includes(name)) {
                 return true;
             }
+            // Check for wildcard matches
             for (const pattern of this.options.includeEntities) {
                 if (pattern.includes('*')) {
                     const regex = new RegExp('^' + pattern.toLowerCase().replace(/\*/g, '.*') + '$');
@@ -53,41 +81,61 @@ export class RESTEndpointHandler {
                     }
                 }
             }
+            // If include list is specified but no matches found, entity is not allowed
             return false;
         }
+        // By default, allow all entities
         return true;
     }
+    /**
+     * Set up all the API routes for the REST endpoints
+     */
     setupRoutes() {
+        // Middleware to extract MJ user
         this.router.use(this.extractMJUser);
+        // Middleware to check entity allowlist/blocklist
         this.router.use('/entities/:entityName', this.checkEntityAccess.bind(this));
         this.router.use('/views/:entityName', this.checkEntityAccess.bind(this));
         this.router.use('/metadata/entities/:entityName', this.checkEntityAccess.bind(this));
         this.router.use('/users/:userId/favorites/:entityName', this.checkEntityAccess.bind(this));
+        // Entity collection operations
         this.router.get('/entities/:entityName', this.getEntityList.bind(this));
         this.router.post('/entities/:entityName', this.createEntity.bind(this));
+        // Individual entity operations
         this.router.get('/entities/:entityName/:id', this.getEntity.bind(this));
         this.router.put('/entities/:entityName/:id', this.updateEntity.bind(this));
         this.router.delete('/entities/:entityName/:id', this.deleteEntity.bind(this));
+        // Record changes and dependencies
         this.router.get('/entities/:entityName/:id/changes', this.getRecordChanges.bind(this));
         this.router.get('/entities/:entityName/:id/dependencies', this.getRecordDependencies.bind(this));
         this.router.get('/entities/:entityName/:id/name', this.getEntityRecordName.bind(this));
+        // View operations
         this.router.post('/views/:entityName', this.runView.bind(this));
         this.router.post('/views/batch', this.runViews.bind(this));
         this.router.get('/views/entity', this.getViewEntity.bind(this));
+        // Metadata endpoints
         this.router.get('/metadata/entities', this.getEntityMetadata.bind(this));
         this.router.get('/metadata/entities/:entityName', this.getEntityFieldMetadata.bind(this));
+        // Views metadata
         this.router.get('/views/:entityName/metadata', this.getViewsMetadata.bind(this));
+        // User operations
         this.router.get('/users/current', this.getCurrentUser.bind(this));
         this.router.get('/users/:userId/favorites/:entityName/:id', this.getRecordFavoriteStatus.bind(this));
         this.router.put('/users/:userId/favorites/:entityName/:id', this.setRecordFavoriteStatus.bind(this));
         this.router.delete('/users/:userId/favorites/:entityName/:id', this.removeRecordFavoriteStatus.bind(this));
+        // Transaction operations
         this.router.post('/transactions', this.executeTransaction.bind(this));
+        // Reports and queries
         this.router.get('/reports/:reportId', this.runReport.bind(this));
         this.router.post('/queries/run', this.runQuery.bind(this));
+        // Error handling
         this.router.use(this.errorHandler);
     }
+    /**
+     * Middleware to check entity access based on include/exclude lists
+     */
     checkEntityAccess(req, res, next) {
-        const entityName = req.params.entityName;
+        const entityName = this.getStringParam(req.params.entityName);
         if (!entityName) {
             next();
             return;
@@ -101,11 +149,19 @@ export class RESTEndpointHandler {
         }
         next();
     }
+    /**
+     * Middleware to extract MJ user from request
+     */
     async extractMJUser(req, res, next) {
         try {
+            // If authentication middleware has already set req.user with basic info
             if (req['user']) {
+                // Get the full MemberJunction user
                 const md = new Metadata();
                 const userInfo = req['user'];
+                // Get user info based on email or ID
+                // Note: The actual implementation here would depend on how the MemberJunction core handles user lookup
+                // This is a simplification that would need to be implemented properly
                 req['mjUser'] = userInfo;
                 if (!req['mjUser']) {
                     res.status(401).json({ error: 'User not found in MemberJunction' });
@@ -122,6 +178,9 @@ export class RESTEndpointHandler {
             next(error);
         }
     }
+    /**
+     * Error handling middleware
+     */
     errorHandler(err, req, res, next) {
         LogError(err);
         if (err.name === 'UnauthorizedError') {
@@ -130,9 +189,13 @@ export class RESTEndpointHandler {
         }
         res.status(500).json({ error: err?.message || 'Internal server error' });
     }
+    /**
+     * Get the current user
+     */
     async getCurrentUser(req, res) {
         try {
             const user = req['mjUser'];
+            // Return user info without sensitive data
             res.json({
                 ID: user.ID,
                 Name: user.Name,
@@ -152,11 +215,15 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Lists entities with optional filtering
+     */
     async getEntityList(req, res) {
         try {
-            const { entityName } = req.params;
+            const entityName = this.getStringParam(req.params.entityName);
             const { filter, orderBy, fields, maxRows, startRow } = req.query;
             const user = req['mjUser'];
+            // Convert the request to a RunViewParams object
             const params = {
                 EntityName: entityName,
                 ExtraFilter: filter,
@@ -173,10 +240,14 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Get a single entity by ID
+     */
     async getEntity(req, res) {
         try {
-            const { entityName, id } = req.params;
-            const { include } = req.query;
+            const entityName = this.getStringParam(req.params.entityName);
+            const id = this.getStringParam(req.params.id);
+            const { include } = req.query; // Optional related entities to include
             const user = req['mjUser'];
             const relatedEntities = include ? include.split(',') : null;
             const result = await EntityCRUDHandler.getEntity(entityName, id, relatedEntities, user);
@@ -192,9 +263,12 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Create a new entity
+     */
     async createEntity(req, res) {
         try {
-            const { entityName } = req.params;
+            const entityName = this.getStringParam(req.params.entityName);
             const entityData = req.body;
             const user = req['mjUser'];
             const result = await EntityCRUDHandler.createEntity(entityName, entityData, user);
@@ -213,9 +287,13 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Update an existing entity
+     */
     async updateEntity(req, res) {
         try {
-            const { entityName, id } = req.params;
+            const entityName = this.getStringParam(req.params.entityName);
+            const id = this.getStringParam(req.params.id);
             const updateData = req.body;
             const user = req['mjUser'];
             const result = await EntityCRUDHandler.updateEntity(entityName, id, updateData, user);
@@ -234,11 +312,16 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Delete an entity
+     */
     async deleteEntity(req, res) {
         try {
-            const { entityName, id } = req.params;
+            const entityName = this.getStringParam(req.params.entityName);
+            const id = this.getStringParam(req.params.id);
             const options = req.query.options ? JSON.parse(req.query.options) : {};
             const user = req['mjUser'];
+            // Convert options to EntityDeleteOptions
             const deleteOptions = new EntityDeleteOptions();
             if (options.SkipEntityAIActions !== undefined)
                 deleteOptions.SkipEntityAIActions = !!options.SkipEntityAIActions;
@@ -259,14 +342,23 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Get record changes for an entity
+     */
     async getRecordChanges(req, res) {
         try {
-            const { entityName, id } = req.params;
+            const entityName = this.getStringParam(req.params.entityName);
+            const id = this.getStringParam(req.params.id);
             const user = req['mjUser'];
+            // Get the entity object
             const md = new Metadata();
             const entity = await md.GetEntityObject(entityName, user);
+            // Create a composite key
             const compositeKey = this.createCompositeKey(entity.EntityInfo, id);
-            const changes = [];
+            // Use a direct approach for getting record changes
+            // Note: This is a simplification. The actual implementation may need to be adjusted
+            // based on how the MemberJunction core handles record changes
+            const changes = []; // This would be populated with actual record changes
             res.json(changes);
         }
         catch (error) {
@@ -274,14 +366,23 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Get record dependencies for an entity
+     */
     async getRecordDependencies(req, res) {
         try {
-            const { entityName, id } = req.params;
+            const entityName = this.getStringParam(req.params.entityName);
+            const id = this.getStringParam(req.params.id);
             const user = req['mjUser'];
+            // Get the entity object
             const md = new Metadata();
             const entity = await md.GetEntityObject(entityName, user);
+            // Create a composite key
             const compositeKey = this.createCompositeKey(entity.EntityInfo, id);
-            const dependencies = [];
+            // Use a direct approach for getting record dependencies
+            // Note: This is a simplification. The actual implementation may need to be adjusted
+            // based on how the MemberJunction core handles record dependencies
+            const dependencies = []; // This would be populated with actual record dependencies
             res.json(dependencies);
         }
         catch (error) {
@@ -289,14 +390,22 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Get entity record name
+     */
     async getEntityRecordName(req, res) {
         try {
-            const { entityName, id } = req.params;
+            const entityName = this.getStringParam(req.params.entityName);
+            const id = this.getStringParam(req.params.id);
             const user = req['mjUser'];
+            // Get the entity object
             const md = new Metadata();
             const entity = await md.GetEntityObject(entityName, user);
+            // Create a composite key
             const compositeKey = this.createCompositeKey(entity.EntityInfo, id);
-            const recordName = "Record Name";
+            // Use a direct approach for getting entity record name
+            // Note: This is a simplification. The actual implementation may need to be adjusted
+            const recordName = "Record Name"; // This would be populated with the actual record name
             res.json({ recordName });
         }
         catch (error) {
@@ -304,11 +413,15 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Run a view
+     */
     async runView(req, res) {
         try {
-            const { entityName } = req.params;
+            const entityName = this.getStringParam(req.params.entityName);
             const viewParams = req.body;
             const user = req['mjUser'];
+            // Create RunViewParams from the request body
             const params = {
                 EntityName: entityName,
                 ...viewParams
@@ -326,6 +439,9 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Run multiple views in batch
+     */
     async runViews(req, res) {
         try {
             const { params } = req.body;
@@ -334,7 +450,10 @@ export class RESTEndpointHandler {
                 res.status(400).json({ error: 'params must be an array of RunViewParams' });
                 return;
             }
+            // Filter out any views for entities that aren't allowed
+            // using our enhanced entity filtering with wildcards and schema support
             const filteredParams = params.filter(p => this.isEntityAllowed(p.EntityName));
+            // If all requested entities were filtered out, return an error
             if (filteredParams.length === 0 && params.length > 0) {
                 res.status(403).json({
                     error: 'None of the requested entities are allowed through the REST API',
@@ -355,6 +474,9 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Get entity for a view
+     */
     async getViewEntity(req, res) {
         try {
             const { ViewID, ViewName } = req.query;
@@ -363,7 +485,8 @@ export class RESTEndpointHandler {
                 res.status(400).json({ error: 'Either ViewID or ViewName must be provided' });
                 return;
             }
-            const entityName = "SampleEntity";
+            // Placeholder implementation - this would need to be implemented to lookup view metadata
+            const entityName = "SampleEntity"; // This would be determined by looking up the view
             res.json({ entityName });
         }
         catch (error) {
@@ -371,14 +494,20 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Get metadata for all entities
+     */
     async getEntityMetadata(req, res) {
         try {
             const user = req['mjUser'];
+            // Filter entities based on user permissions and REST API configuration
             const md = new Metadata();
             const entities = md.Entities.filter(e => {
+                // First check if entity is allowed based on configuration
                 if (!this.isEntityAllowed(e.Name)) {
                     return false;
                 }
+                // Then check user permissions
                 const permissions = e.GetUserPermisions(user);
                 return permissions.CanRead;
             });
@@ -400,9 +529,12 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Get field metadata for a specific entity
+     */
     async getEntityFieldMetadata(req, res) {
         try {
-            const { entityName } = req.params;
+            const entityName = this.getStringParam(req.params.entityName);
             const user = req['mjUser'];
             const md = new Metadata();
             const entity = md.Entities.find(e => e.Name === entityName);
@@ -410,6 +542,7 @@ export class RESTEndpointHandler {
                 res.status(404).json({ error: `Entity '${entityName}' not found` });
                 return;
             }
+            // Check if user can read this entity
             const permissions = entity.GetUserPermisions(user);
             if (!permissions.CanRead) {
                 res.status(403).json({ error: 'Permission denied' });
@@ -435,11 +568,16 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Get metadata about available views for an entity
+     */
     async getViewsMetadata(req, res) {
         try {
-            const { entityName } = req.params;
+            const entityName = this.getStringParam(req.params.entityName);
             const user = req['mjUser'];
-            const views = [];
+            // This would need to be implemented to retrieve available views
+            // Placeholder implementation
+            const views = []; // Would need to query available views for this entity
             res.json(views);
         }
         catch (error) {
@@ -447,14 +585,23 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Get favorite status for a record
+     */
     async getRecordFavoriteStatus(req, res) {
         try {
-            const { userId, entityName, id } = req.params;
+            const userId = this.getStringParam(req.params.userId);
+            const entityName = this.getStringParam(req.params.entityName);
+            const id = this.getStringParam(req.params.id);
             const user = req['mjUser'];
+            // Get the entity object
             const md = new Metadata();
             const entity = await md.GetEntityObject(entityName, user);
+            // Create a composite key
             const compositeKey = this.createCompositeKey(entity.EntityInfo, id);
-            const isFavorite = false;
+            // Use a direct approach for getting favorite status
+            // Note: This is a simplification. The actual implementation may need to be adjusted
+            const isFavorite = false; // This would be populated with the actual favorite status
             res.json({ isFavorite });
         }
         catch (error) {
@@ -462,13 +609,23 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Set favorite status for a record
+     */
     async setRecordFavoriteStatus(req, res) {
         try {
-            const { userId, entityName, id } = req.params;
+            const userId = this.getStringParam(req.params.userId);
+            const entityName = this.getStringParam(req.params.entityName);
+            const id = this.getStringParam(req.params.id);
             const user = req['mjUser'];
+            // Get the entity object
             const md = new Metadata();
             const entity = await md.GetEntityObject(entityName, user);
+            // Create a composite key
             const compositeKey = this.createCompositeKey(entity.EntityInfo, id);
+            // Use a direct approach for setting favorite status
+            // Note: This is a simplification. The actual implementation may need to be adjusted
+            // This would set the favorite status to true
             res.status(204).send();
         }
         catch (error) {
@@ -476,13 +633,23 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Remove favorite status for a record
+     */
     async removeRecordFavoriteStatus(req, res) {
         try {
-            const { userId, entityName, id } = req.params;
+            const userId = this.getStringParam(req.params.userId);
+            const entityName = this.getStringParam(req.params.entityName);
+            const id = this.getStringParam(req.params.id);
             const user = req['mjUser'];
+            // Get the entity object
             const md = new Metadata();
             const entity = await md.GetEntityObject(entityName, user);
+            // Create a composite key
             const compositeKey = this.createCompositeKey(entity.EntityInfo, id);
+            // Use a direct approach for setting favorite status
+            // Note: This is a simplification. The actual implementation may need to be adjusted
+            // This would set the favorite status to false
             res.status(204).send();
         }
         catch (error) {
@@ -490,8 +657,12 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Execute a transaction
+     */
     async executeTransaction(req, res) {
         try {
+            // Placeholder implementation - this would need to be implemented to handle transactions
             res.status(501).json({ error: 'Not implemented' });
         }
         catch (error) {
@@ -499,8 +670,12 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Run a report
+     */
     async runReport(req, res) {
         try {
+            // Placeholder implementation - this would need to be implemented to run reports
             res.status(501).json({ error: 'Not implemented' });
         }
         catch (error) {
@@ -508,8 +683,12 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Run a query
+     */
     async runQuery(req, res) {
         try {
+            // Placeholder implementation - this would need to be implemented to run queries
             res.status(501).json({ error: 'Not implemented' });
         }
         catch (error) {
@@ -517,19 +696,29 @@ export class RESTEndpointHandler {
             res.status(500).json({ error: error?.message || 'Unknown error' });
         }
     }
+    /**
+     * Helper method to create a composite key from an ID
+     */
     createCompositeKey(entityInfo, id) {
         if (entityInfo.PrimaryKeys.length === 1) {
+            // Single primary key
             const primaryKeyField = entityInfo.PrimaryKeys[0].Name;
             const compositeKey = new CompositeKey();
+            // Use key-value pairs instead of SetValue
             compositeKey.KeyValuePairs = [
                 { FieldName: primaryKeyField, Value: id }
             ];
             return compositeKey;
         }
         else {
+            // Composite primary key
+            // This is a simplification - in a real implementation, we would need to handle composite keys properly
             throw new Error('Composite primary keys are not supported in this implementation');
         }
     }
+    /**
+     * Get the Express router with all configured routes
+     */
     getRouter() {
         return this.router;
     }