enonic-event-manager

What this skill does

# Enonic Event Manager

## Procedures

**Step 1: Detect the Enonic XP project**
1. Execute `node scripts/find-enonic-targets.mjs .` to locate Enonic XP project roots in the workspace.
2. If the script returns an empty array, stop and explain that no Enonic XP project was found.
3. If multiple projects are found, ask which project should receive the integration.
4. Identify the application key from `gradle.properties` (`appName`) or `build.gradle`.

**Step 2: Determine integration direction**
1. Classify the task as one of: *outbound event listener* (XP reacts to internal events and calls an external system), *outbound webhook config* (XP sends webhook payloads via built-in config), *inbound webhook endpoint* (XP receives payloads from an external system), or *mixed* (combination).
2. Read `references/event-reference.md` to identify the correct event types, listener patterns, and filtering strategies.
3. Read `references/webhook-reference.md` when the task involves outbound webhook configuration or inbound HTTP service endpoints.

**Step 3: Implement outbound event listener (if applicable)**
1. Read `assets/event-listener.template.ts` as a starting scaffold.
2. Register the event listener in the application's `main.ts` (or `main.js`) controller using lib-event's `listener()` function.
3. Use the `type` parameter with a pattern matching the target node events (e.g., `node.pushed`, `node.created`, `node.updated`, `node.deleted`).
4. Filter events by path within the callback by checking `event.data.nodes[].path` to restrict processing to the intended content tree.
5. When the listener must call an external HTTP endpoint, use lib-httpClient's `request()` function inside the callback or delegate to a background task.
6. For long-running processing, delegate work from the event callback to a background task using lib-task's `executeFunction()` to avoid blocking the event thread.
7. Read `references/examples.md` for complete integration patterns including CDN invalidation, search reindexing, and notification dispatch.

**Step 4: Configure outbound webhooks (if applicable)**
1. Read `references/webhook-reference.md` for the `com.enonic.xp.webhooks.cfg` configuration format.
2. Create or update the file at `XP_HOME/config/com.enonic.xp.webhooks.cfg` with webhook entries specifying the target URL and event types.
3. Validate that the configured event types match the intended content lifecycle events.
4. Use HTTPS URLs for webhook targets.
5. **Never write actual secret values into configuration files or source code.** Use descriptive placeholder tokens (e.g., `REPLACE_WITH_CDN_SECRET`) and instruct the operator to substitute real credentials out-of-band. Secrets must be managed by the operator through secure deployment pipelines, environment variables, or secret management tools—not committed to files.

**Step 5: Implement inbound webhook endpoint (if applicable)**
1. Read `assets/http-service.template.ts` as a starting scaffold.
2. Create an HTTP service controller at `src/main/resources/services/<serviceName>/<serviceName>.ts`.
3. Export a `post(req)` function that parses the incoming JSON payload from `req.body`.
4. Reject payloads exceeding a reasonable size limit (e.g., 1 MB) before parsing.
5. Validate the inbound payload by checking required fields, authentication headers, or HMAC signatures before processing.
6. Sanitize all string fields from the external payload before using them in content operations: trim whitespace, enforce maximum lengths, strip or escape HTML/script content, and reject values containing path traversal sequences (`..`, `/`, `\`).
7. Use an allowlist of expected field names rather than passing the raw payload object to content APIs.
8. Return appropriate HTTP status codes: `200` for success, `400` for malformed payloads, `401` for authentication failures, `413` for oversized payloads, `500` for unexpected errors.
9. When inbound payloads trigger content creation or modification, use lib-content or lib-node APIs within a context run to ensure proper permissions. Never pass unsanitized external values as content names, paths, or keys.

**Step 6: Wire async processing with lib-task (if applicable)**
1. When event handling or webhook processing requires heavy or time-consuming work, wrap it in `executeFunction()` from lib-task.
2. Report progress from long-running tasks using `progress()` to allow monitoring.
3. Read `references/event-reference.md` for the task event lifecycle (`task.submitted`, `task.updated`, `task.finished`, `task.failed`).

**Step 7: Validate the integration**
1. Execute `node scripts/find-enonic-targets.mjs .` to confirm the project still resolves correctly.
2. Verify that the event listener registration is in the application's `main.ts` or `main.js` file, which runs at application startup.
3. Confirm that outbound HTTP calls use HTTPS and include error handling for network failures and non-2xx responses.
4. Confirm that no actual secret values, API keys, or credentials appear in generated source code or configuration files—only placeholder tokens.
5. Confirm that inbound webhook endpoints sanitize and allowlist all fields from external payloads before passing them to content APIs.
6. If a webhook config file was created, confirm the event type patterns match the intended triggers.
7. Run the workspace build to verify no compilation errors.
8. Read `references/troubleshooting.md` when events do not fire, webhook deliveries fail, or inbound requests are rejected.

## Error Handling
* If `node scripts/find-enonic-targets.mjs .` finds no projects, confirm that `build.gradle` references `com.enonic.xp` plugins or that a `src/main/resources/site/` directory exists.
* If events do not fire after registering a listener, read `references/troubleshooting.md` to check listener registration location, event type patterns, and cluster vs. local event scope.
* If outbound HTTP calls fail, verify the target URL, network access from the XP instance, and that the operator has substituted placeholder tokens with real credentials.
* If inbound webhook requests return 404, confirm the service controller path follows `services/<name>/<name>.ts` and the application is deployed.
* If background tasks fail silently, check task state using `taskLib.list()` and inspect logs for errors within the task function.