/** * Phase 06 #22 — Plugin hook emission helper. * * Wraps `publishOutboxEvent` so host call-sites stay one-line: * * await emitPluginHook(tx, PLUGIN_HOOK_TENANT_CREATED, payload); * * The helper: * 1. Validates the payload against the registered Zod schema. * 2. Publishes a `plugin.hook.` outbox event inside the * surrounding Prisma transaction (atomic with the host write). * 3. Returns the persisted OutboxEvent row so callers can correlate * it in audit logs. * * Bad payloads throw {@link PluginHookValidationError} — callers MUST * either handle it (when the payload is user-derived) or let it * propagate so the host write rolls back. * * Subscriber resolution + fan-out into one outbox row per installed * plugin is intentionally deferred to the worker side: a single * `plugin.hook.` event lands in the outbox queue and the * downstream consumer (worker) expands it into per-plugin invocations. * This keeps the producer path (web request) cheap and avoids * coupling the request thread to the Plugin table. */ import type { z } from "zod"; import { validatePluginHookPayload, type PluginHookDefinition, } from "./registry.js"; /** * JSON-compatible value type, structurally identical to * `Prisma.InputJsonValue` without taking the dependency on * `@hivegrid/db` (which would cycle through the worker bootstrap). */ export type PluginHookJsonValue = | string | number | boolean | null | { [key: string]: PluginHookJsonValue } | ReadonlyArray; export class PluginHookValidationError extends Error { public override readonly name = "PluginHookValidationError"; public readonly hookName: string; public readonly issues: ReadonlyArray; constructor(hookName: string, issues: ReadonlyArray) { super(`Invalid payload for plugin hook '${hookName}': ${JSON.stringify(issues)}`); this.hookName = hookName; this.issues = issues; } } /** * Minimal publish surface — kept identical to the @hivegrid/db helper * so this package does not have to depend on @hivegrid/db directly * (avoids a cycle with the worker bootstrap that pulls plugin-runtime * via @hivegrid/db). */ export type PluginHookOutboxPublisher = ( tx: unknown, args: { tenantId?: string | null; type: string; payload: PluginHookJsonValue; dispatchKey?: string | null; } ) => Promise; export type EmitPluginHookOptions = { tenantId?: string | null; /** * Optional idempotency key. When two writers might emit the same * hook for the same business object (e.g. two onboarding paths both * creating the same tenant) supplying a stable key prevents * duplicate downstream invocations. */ dispatchKey?: string | null; }; /** * Validate + publish a plugin-hook outbox event inside a transaction. * The transaction client is intentionally typed as `unknown` so this * package keeps zero runtime dependency on @hivegrid/db — the caller * (a `.server.ts` file in apps/web) already imports the prisma types * and passes the correct shape. */ export async function emitPluginHook( tx: unknown, def: PluginHookDefinition, payload: TPayload, publish: PluginHookOutboxPublisher, options: EmitPluginHookOptions = {} ): Promise { const validation = validatePluginHookPayload(def, payload); if (!validation.ok) { throw new PluginHookValidationError(def.name, validation.issues); } await publish(tx, { tenantId: options.tenantId ?? null, type: def.outboxEventType, payload: validation.payload as unknown as PluginHookJsonValue, dispatchKey: options.dispatchKey ?? null, }); }