Files
T
2026-07-08 16:15:37 +02:00

109 lines
3.6 KiB
TypeScript

/**
* 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.<name>` 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.<name>` 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<PluginHookJsonValue>;
export class PluginHookValidationError extends Error {
public override readonly name = "PluginHookValidationError";
public readonly hookName: string;
public readonly issues: ReadonlyArray<z.ZodIssue>;
constructor(hookName: string, issues: ReadonlyArray<z.ZodIssue>) {
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<unknown>;
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<TPayload>(
tx: unknown,
def: PluginHookDefinition<TPayload>,
payload: TPayload,
publish: PluginHookOutboxPublisher,
options: EmitPluginHookOptions = {}
): Promise<void> {
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,
});
}