// @ts-check
/**
* @import {ExpressRequestAuthorized, ExpressResponse} from '../types.js'
*/
/**
* @fileoverview Action Router
*
* This router defines all endpoints for managing actions:
* - Create actions from templates and triggers
* - Update existing actions
* - Delete actions
* - Get actions by template, trigger, or UID
* - Get multiple actions by UIDs
* - Retrieve missed events for synchronization
*
* Actions are instances of action templates that are triggered by specific events.
* They contain the actual execution data and link templates to triggers.
*
* @module Router/action
* @requires express
* @requires ../utils/requestLogger
* @requires ./action/controller
*/
/**
* @swagger
* components:
* schemas:
* Action:
* type: object
* properties:
* UID:
* type: string
* format: uuid
* description: Unique identifier for the action
* Data:
* type: object
* description: Action data containing configuration and parameters
* Display:
* type: string
* description: Human-readable display name for the action
* UIDTrigger:
* type: string
* format: uuid
* description: UID of the trigger that created this action
* UIDtemplate:
* type: string
* format: uuid
* description: UID of the action template used
* TriggerType:
* type: string
* description: Type of the trigger (e.g., person, group, event)
* ActionTemplate:
* type: object
* properties:
* unique:
* type: string
* enum: [system, trigger]
* description: Uniqueness constraint for the action
* onlyAdmin:
* type: boolean
* description: Whether only admins can create this action
* defaults:
* type: object
* description: Default values for action data
* MissedEvent:
* type: object
* properties:
* Timestamp:
* type: integer
* description: Unix timestamp of the event
* Data:
* type: object
* description: Event data payload
* EventKey:
* type: string
* description: Event identification key
* ApiResponse:
* type: object
* properties:
* success:
* type: boolean
* description: Whether the operation was successful
* result:
* description: Operation result data
* message:
* type: string
* description: Error message (when success is false)
* securitySchemes:
* SessionAuth:
* type: apiKey
* in: cookie
* name: session
* description: Session-based authentication
*/
import express from 'express';
import { requestUpdateLogger } from '../utils/requestLogger.js';
import * as actionController from './action/controller.js';
const action = express();
/**
* @swagger
* /api/kpe20/action/{UIDTemplate}/{UIDTrigger}:
* put:
* summary: Create or update an action from template and trigger
* description: Creates a new action instance based on an action template and trigger. If the template has uniqueness constraints, existing actions may be removed.
* tags: [Actions]
* security:
* - SessionAuth: []
* parameters:
* - name: UIDTemplate
* in: path
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the action template to use
* - name: UIDTrigger
* in: path
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the trigger that initiates this action
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* description: Action configuration data
* additionalProperties: true
* example:
* recipients: ["user1@example.com", "user2@example.com"]
* message: "Custom action message"
* priority: "high"
* responses:
* 200:
* description: Action created successfully
* content:
* application/json:
* schema:
* allOf:
* - $ref: '#/components/schemas/ApiResponse'
* - type: object
* properties:
* result:
* type: object
* properties:
* Data:
* type: object
* description: The created action data
* template:
* $ref: '#/components/schemas/ActionTemplate'
* example:
* success: true
* result:
* Data:
* recipients: ["user1@example.com"]
* message: "Action created"
* template:
* unique: "system"
* onlyAdmin: false
* 400:
* description: Invalid template or trigger UID
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* example:
* success: false
* message: "invalid template UID supplied"
* 401:
* description: Unauthorized - Admin access required for this template
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* example:
* success: false
* message: "user not authorized for this action template. Has to be admin"
* 500:
* description: Internal server error
*/
// @ts-ignore
action.put('/:UIDTemplate/:UIDTrigger', requestUpdateLogger, actionController.createAction);
/**
* @swagger
* /api/kpe20/action/{UID}:
* post:
* summary: Update an existing action
* description: Updates an existing action with new data. Merges the provided data with existing action data.
* tags: [Actions]
* security:
* - SessionAuth: []
* parameters:
* - name: UID
* in: path
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the action to update
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* description: Updated action data
* additionalProperties: true
* example:
* recipients: ["updated@example.com"]
* status: "completed"
* notes: "Action updated"
* responses:
* 200:
* description: Action updated successfully
* content:
* application/json:
* schema:
* allOf:
* - $ref: '#/components/schemas/ApiResponse'
* - type: object
* properties:
* result:
* $ref: '#/components/schemas/Action'
* example:
* success: true
* result:
* UID: "123e4567-e89b-12d3-a456-426614174000"
* Data:
* recipients: ["updated@example.com"]
* status: "completed"
* 400:
* description: Invalid action UID
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* example:
* success: false
* message: "Action not found"
* 500:
* description: Internal server error
*/
// @ts-ignore
action.post('/:UID', requestUpdateLogger, actionController.updateAction);
/**
* @swagger
* /api/kpe20/action/{action}:
* delete:
* summary: Delete an action
* description: Permanently deletes an action by its UID
* tags: [Actions]
* security:
* - SessionAuth: []
* parameters:
* - name: action
* in: path
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the action to delete
* responses:
* 200:
* description: Action deleted successfully
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* example:
* success: true
* result: "Action deleted"
* 400:
* description: Invalid action UID
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* example:
* success: false
* message: "Action not found"
* 500:
* description: Internal server error
*/
// @ts-ignore
action.delete('/:action', requestUpdateLogger, actionController.deleteAction);
/**
* @swagger
* /api/kpe20/action/template/{UIDtemplate}:
* get:
* summary: Get actions by template UID
* description: Retrieves all actions that were created from a specific action template
* tags: [Actions]
* security:
* - SessionAuth: []
* parameters:
* - name: UIDtemplate
* in: path
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the action template
* - name: timestamp
* in: query
* required: false
* schema:
* type: integer
* description: Optional timestamp for historical data (FOR SYSTEM_TIME AS OF)
* responses:
* 200:
* description: Actions retrieved successfully
* content:
* application/json:
* schema:
* allOf:
* - $ref: '#/components/schemas/ApiResponse'
* - type: object
* properties:
* result:
* type: array
* items:
* $ref: '#/components/schemas/Action'
* example:
* success: true
* result: [
* {
* "UID": "123e4567-e89b-12d3-a456-426614174000",
* "UIDtemplate": "987fcdeb-51a2-43d7-8f9e-123456789abc",
* "Display": "Email Notification Action",
* "Data": {"recipients": ["user@example.com"]}
* }
* ]
* 400:
* description: Invalid template UID
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* 500:
* description: Internal server error
*/
// @ts-ignore
action.get('/template/:UIDtemplate', actionController.getActionsByTemplate);
/**
* @swagger
* /api/kpe20/action/trigger/{UIDtrigger}:
* get:
* summary: Get actions by trigger UID
* description: Retrieves all actions that were created by a specific trigger
* tags: [Actions]
* security:
* - SessionAuth: []
* parameters:
* - name: UIDtrigger
* in: path
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the trigger
* responses:
* 200:
* description: Actions retrieved successfully
* content:
* application/json:
* schema:
* allOf:
* - $ref: '#/components/schemas/ApiResponse'
* - type: object
* properties:
* result:
* type: array
* items:
* $ref: '#/components/schemas/Action'
* example:
* success: true
* result: [
* {
* "UID": "123e4567-e89b-12d3-a456-426614174000",
* "UIDTrigger": "456e7890-f12b-34c5-d678-901234567890",
* "Display": "User Registration Action",
* "TriggerType": "person"
* }
* ]
* 400:
* description: Invalid trigger UID
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* 500:
* description: Internal server error
*/
// @ts-ignore
action.get('/trigger/:UIDtrigger', actionController.getActionsByTrigger);
/**
* @swagger
* /api/kpe20/action/{UID}:
* get:
* summary: Get a specific action by UID
* description: Retrieves detailed information about a specific action
* tags: [Actions]
* security:
* - SessionAuth: []
* parameters:
* - name: UID
* in: path
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the action to retrieve
* - name: timestamp
* in: query
* required: false
* schema:
* type: integer
* description: Optional timestamp for historical data (FOR SYSTEM_TIME AS OF)
* responses:
* 200:
* description: Action retrieved successfully
* content:
* application/json:
* schema:
* allOf:
* - $ref: '#/components/schemas/ApiResponse'
* - type: object
* properties:
* result:
* $ref: '#/components/schemas/Action'
* example:
* success: true
* result:
* UID: "123e4567-e89b-12d3-a456-426614174000"
* Display: "Email Notification Action"
* UIDTrigger: "456e7890-f12b-34c5-d678-901234567890"
* UIDtemplate: "789abcde-f012-3456-7890-123456789abc"
* TriggerType: "person"
* Data:
* recipients: ["user@example.com"]
* message: "Welcome to our platform"
* 400:
* description: Invalid action UID
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* example:
* success: false
* message: "Action not found"
* 500:
* description: Internal server error
*/
// @ts-ignore
action.get('/:UID', actionController.getAction);
/**
* @swagger
* /api/kpe20/action:
* post:
* summary: Get multiple actions by UIDs
* description: Retrieves multiple actions by providing an array of action UIDs directly in the request body
* tags: [Actions]
* security:
* - SessionAuth: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: array
* items:
* type: string
* format: uuid
* description: Array of action UIDs to retrieve
* example: [
* "123e4567-e89b-12d3-a456-426614174000",
* "456e7890-f12b-34c5-d678-901234567890"
* ]
* responses:
* 200:
* description: Actions retrieved successfully
* content:
* application/json:
* schema:
* allOf:
* - $ref: '#/components/schemas/ApiResponse'
* - type: object
* properties:
* result:
* type: array
* items:
* $ref: '#/components/schemas/Action'
* example:
* success: true
* result: [
* {
* "UID": "123e4567-e89b-12d3-a456-426614174000",
* "Display": "Email Action",
* "Data": {"recipients": ["user1@example.com"]}
* },
* {
* "UID": "456e7890-f12b-34c5-d678-901234567890",
* "Display": "SMS Action",
* "Data": {"phone": "+1234567890"}
* }
* ]
* 400:
* description: Invalid request body or UIDs
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* 500:
* description: Internal server error
*/
// @ts-ignore
action.post('/', actionController.getMultipleActions);
/**
* @swagger
* /api/kpe20/action/missed/{key}/{timestamp}:
* get:
* summary: Get missed events by key and timestamp
* description: Retrieves events that occurred after the specified timestamp for a specific event key
* tags: [Actions, Events]
* security:
* - SessionAuth: []
* parameters:
* - name: key
* in: path
* required: true
* schema:
* type: string
* description: Event key to filter missed events
* - name: timestamp
* in: path
* required: true
* schema:
* type: integer
* minimum: 0
* description: Unix timestamp - events after this time will be returned
* responses:
* 200:
* description: Missed events retrieved successfully
* content:
* application/json:
* schema:
* allOf:
* - $ref: '#/components/schemas/ApiResponse'
* - type: object
* properties:
* result:
* type: array
* items:
* $ref: '#/components/schemas/MissedEvent'
* example:
* success: true
* result: [
* {
* "Timestamp": 1699564800,
* "EventKey": "user.registered",
* "Data": {"userId": "user123", "email": "user@example.com"}
* }
* ]
* 400:
* description: Invalid key or timestamp
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* 500:
* description: Internal server error
*/
// @ts-ignore
action.get('/missed/:key/:timestamp', actionController.getMissedEventsByKey);
/**
* @swagger
* /api/kpe20/action/missed/{timestamp}:
* post:
* summary: Get missed events by multiple keys and timestamp
* description: Retrieves events that occurred after the specified timestamp for multiple event keys provided directly as array in the request body
* tags: [Actions, Events]
* security:
* - SessionAuth: []
* parameters:
* - name: timestamp
* in: path
* required: true
* schema:
* type: integer
* minimum: 0
* description: Unix timestamp in milliseconds - events after this time will be returned
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: array
* items:
* type: string
* description: Array of event keys to filter missed events
* example: ["user.registered", "user.login", "order.created"]
* responses:
* 200:
* description: Missed events retrieved successfully
* content:
* application/json:
* schema:
* allOf:
* - $ref: '#/components/schemas/ApiResponse'
* - type: object
* properties:
* result:
* type: array
* items:
* $ref: '#/components/schemas/MissedEvent'
* example:
* success: true
* result: [
* {
* "Timestamp": 1699564800,
* "EventKey": "user.registered",
* "Data": {"userId": "user123"}
* },
* {
* "Timestamp": 1699565000,
* "EventKey": "order.created",
* "Data": {"orderId": "order456"}
* }
* ]
* 400:
* description: Invalid timestamp or keys array
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* 500:
* description: Internal server error
*/
// @ts-ignore
action.post('/missed/:timestamp', actionController.getMissedEventsByKeys);
/**
* @swagger
* /api/kpe20/action/missedT/{UIDtemplate}/{timestamp}:
* get:
* summary: Get missed events by template and timestamp
* description: Retrieves events that occurred after the specified timestamp for actions related to a specific action template
* tags: [Actions, Events]
* security:
* - SessionAuth: []
* parameters:
* - name: UIDtemplate
* in: path
* required: true
* schema:
* type: string
* format: uuid
* description: UID of the action template to filter events
* - name: timestamp
* in: path
* required: true
* schema:
* type: integer
* minimum: 0
* description: Unix timestamp - events after this time will be returned
* responses:
* 200:
* description: Missed events retrieved successfully
* content:
* application/json:
* schema:
* allOf:
* - $ref: '#/components/schemas/ApiResponse'
* - type: object
* properties:
* result:
* type: array
* items:
* $ref: '#/components/schemas/MissedEvent'
* example:
* success: true
* result: [
* {
* "Timestamp": 1699564800,
* "EventKey": "template.email.notification",
* "Data": {"templateId": "email-template-123", "recipients": 5}
* }
* ]
* 400:
* description: Invalid template UID or timestamp
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* 500:
* description: Internal server error
*/
// @ts-ignore
action.get('/missedT/:UIDtemplate/:timestamp', actionController.getMissedEventsByTemplate);
/**
* @swagger
* /api/kpe20/action/pattern/{pattern}/{timestamp}:
* get:
* summary: Get missed events by pattern and timestamp
* description: Retrieves events that occurred after the specified timestamp matching a specific pattern
* tags: [Actions, Events]
* security:
* - SessionAuth: []
* parameters:
* - name: pattern
* in: path
* required: true
* schema:
* type: string
* description: Event pattern to match (supports wildcards or regex patterns)
* example: "user.*"
* - name: timestamp
* in: path
* required: true
* schema:
* type: integer
* minimum: 0
* description: Unix timestamp - events after this time will be returned
* responses:
* 200:
* description: Missed events retrieved successfully
* content:
* application/json:
* schema:
* allOf:
* - $ref: '#/components/schemas/ApiResponse'
* - type: object
* properties:
* result:
* type: array
* items:
* $ref: '#/components/schemas/MissedEvent'
* example:
* success: true
* result: [
* {
* "Timestamp": 1699564800,
* "EventKey": "user.registered",
* "Data": {"userId": "user123", "email": "user@example.com"}
* },
* {
* "Timestamp": 1699565000,
* "EventKey": "user.login",
* "Data": {"userId": "user123", "loginTime": "2023-11-09T12:00:00Z"}
* }
* ]
* 400:
* description: Invalid pattern or timestamp
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/ApiResponse'
* 500:
* description: Internal server error
*/
// @ts-ignore
action.get('/pattern/:pattern/:timestamp', actionController.getMissedEventsByPattern);
export default action;