109 lines
3.6 KiB
TypeScript
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,
|
|
});
|
|
}
|