register(): hooks and filters
Hooks react after the fact and never break the caller; filters run before the fact and may change a value or veto an action.
Hooks (fire-and-forget)
Two kinds exist: the four legacy typed hooks (invoice.sent, order.paid, post.published, maintenance.tick) and every webhook event name, whose payload is the same data a webhook receiver gets (Record<string, unknown>). List the names in module.json → hooks too — undeclared handlers are never called. A throwing handler is logged and never affects the caller or other plugins.
import { prisma } from "@/lib/prisma";
import { definePlugin, getPluginSettings } from "@/lib/plugins/sdk";
import { plan } from "./logic";
const ID = "site-visits";
type Settings = { autoPlan: boolean; leadDays: number; slot: "morning" | "afternoon" };
export function register() {
return definePlugin({
hooks: {
// event hook: payload = the webhook data of quotation.sent
"quotation.sent": async (payload, ctx) => {
const s = await getPluginSettings<Settings>(ID);
if (!s.autoPlan || typeof payload.id !== "string") return;
const exists = await prisma.siteVisit.findFirst({ where: { quotationId: payload.id } });
if (exists) return; // idempotent
await prisma.siteVisit.create({
data: { quotationId: payload.id, customerName: String(payload.customerName ?? "Customer"), plannedAt: plan(new Date(), Number(s.leadDays) || 2), slot: s.slot },
});
ctx.log("planned a visit for quotation " + String(payload.number));
},
// legacy typed hook: payload is typed (invoiceId, number, customerEmail, total, currency, userId)
"invoice.sent": async (payload, ctx) => {
ctx.log("invoice " + payload.number + " sent");
},
},
});
}Dates arrive as ISO strings or Date objects depending on the emitter — always coerce: new Date(String(payload.startAt)). hookFields(name) from the SDK returns a hook's field names at runtime.
The example above reads the database directly, which a self-hosted plugin may do. A marketplace plugin may use only the SDK — the same hook written for the marketplace keeps counters in its own store:
import { definePlugin, getPluginSettings, pluginStore } from "@/lib/plugins/sdk";
import { EMPTY_PULSE, countBooking, type PulseState } from "./pulse";
export function register() {
const store = pluginStore("booking-pulse"); // always your own id, as a literal
return definePlugin({
hooks: {
"appointment.booked": async (payload, ctx) => {
const s = await getPluginSettings<{ countStaffBookings: boolean }>("booking-pulse");
const source = String(payload.source ?? "admin");
if (source !== "web" && !s.countStaffBookings) return;
const state = await store.get<PulseState>("pulse", EMPTY_PULSE);
await store.set("pulse", countBooking(state, String(payload.startAt ?? ""), source));
ctx.log(`booking-pulse: counted a ${source} booking`);
},
},
});
}Filters (before the fact)
| Filter | Value | Status |
|---|---|---|
invoice.beforeIssue | GateDecision { warnings, abort } — abort stops issuing and the user sees the reason | wired |
email.beforeSend | OutgoingMail — change subject / html / text / headers, or skip: true (ignored for essential mail); the recipient cannot change | wired |
dashboard.widgets | string[] widget ids — remove ids to hide widgets for a user (adding is not supported) | wired (remove only) |
quotation.beforeSend, order.beforeConfirm | GateDecision | declared, not called yet |
filters: {
"invoice.beforeIssue": async (decision, ctx) => {
if (ctx.invoice.total > 50_000_00) decision.warnings.push("Large invoice " + ctx.invoice.number);
if (ctx.invoice.total > 500_000_00) decision.abort = "Invoices above 500,000 need approval first.";
return decision;
},
"email.beforeSend": async (mail) =>
mail.event === "invoice.sent" ? { ...mail, subject: "[Action required] " + mail.subject } : undefined,
},invoice.beforeIssue runs inside the issuing transaction) and never throw for business reasons — set abort or warnings instead.Written from: docs/PLUGIN-DEVELOPER-GUIDE.md, src/lib/plugins/types.ts, src/lib/plugins/filters.ts, src/lib/plugins/sdk.ts, modules/example-checklist/src/index.ts, docs/DEVELOPERS/PLUGIN-SDK.md, examples/marketplace/plugin-booking-pulse/src/index.ts