跳到正文
14 天免费试用,无需银行卡9 种语言176 种业务类型 · 50 个应用
ZH· USD
试用在线演示免费试用

此页面暂无简体中文版本,现以英文显示。

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.

  • about 10 min

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.

modules/site-visits/src/index.ts
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:

examples/marketplace/plugin-booking-pulse/src/index.ts (abridged)
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)

FilterValueStatus
invoice.beforeIssueGateDecision { warnings, abort } — abort stops issuing and the user sees the reasonwired
email.beforeSendOutgoingMail — change subject / html / text / headers, or skip: true (ignored for essential mail); the recipient cannot changewired
dashboard.widgetsstring[] widget ids — remove ids to hide widgets for a user (adding is not supported)wired (remove only)
quotation.beforeSend, order.beforeConfirmGateDecisiondeclared, not called yet
Filters in register()
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,
},
Filters chain in install order and must be fast (< 500 ms; a handler slower than 2 s is abandoned), read-only (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