Sample plugins

This guide describes the example plugins in examples/plugins: what each does, what it registers and what its tests cover. Read it alongside the Plugin SDK when you write your own plugin.

All samples are trusted-catalog plugins with admin-only routes.

#Audit Trace

Records command lifecycle activity for operators.

Module: examples/plugins/audit-trace.plugin.ts

Registers:

• beforeCommand, afterCommand and beforeAiCommand hooks.
• An admin health route.
• An Operations admin menu item.

Tests check that it:

• Loads when trusted and enabled.
• Does not run when disabled.
• Exposes its health route only under the admin plugin route space.
• Does not block the request when a hook times out.

#SEO Metadata

Adds an SEO field type and AI-assisted metadata generation for entries.

Module: examples/plugins/seo-metadata.plugin.ts

Registers:

• A custom seo-preview field type.
• An AI tool that generates updateEntry commands.
• A Content admin menu item.
• An admin health route.

Tests check that:

• The field type appears in the loaded plugin fields.
• The AI tool produces valid command envelopes.
• Duplicate AI tool names are ignored or rejected deterministically.
• Unsafe admin menu paths are blocked.

#Preview Revalidation

Helps frontends refresh their cache after a publish.

Module: examples/plugins/preview-revalidation.plugin.ts

Registers:

• An afterCommand hook for the publish lifecycle.
• An admin health route.
• An admin dry-run route: /api/admin/plugins/preview-revalidation/dry-run.

The dry run checks the destination against the webhook destination policy and signs the request with the existing webhook HMAC signer (signPayload). It never returns the signing secret. Retries and queue dispatch stay with the regular webhook delivery system. See Webhooks.

Tests check that it:

• Signs dry-run requests.
• Does not return the signing secret.
• Rejects untrusted destinations.
• Registers no public plugin route.

#Form Capture (not built)

A form submission plugin is planned but not built, because it needs a public route and EdgeCMS does not load public plugin routes. It waits for a reviewed public plugin namespace with tenant isolation, auth policy, cache behavior and route-prefix tests.

Planned scope:

• A public, validation-only submission route, mounted under the tenant route group /api/tenants/:tenantSlug.
• Payload validation for formId, email and fields.
• Optional Turnstile validation.
• Submissions stored as entries or in a plugin-owned table.
• A webhook on each submission.
• An admin settings and status page.

Its tests will need to check that it rejects invalid payloads, stays blocked until the public namespace is approved, keeps the tenant route-group context, and cannot reach the admin namespace from the public route.

#What every sample needs

• A trusted catalog entry.
• Focused tests.
• An admin panel status: loaded, disabled or blocked.
• Docs covering setup, behavior and how to verify it.
• An example module or spec under examples/plugins.
• Routes described with PluginRouteDescriptor when they are documented.
• No shared abstraction across plugins unless two plugins already use it.