Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/worker/src/jobs/form-submission-route.ts
T

409 lines
13 KiB
TypeScript

/**
* Form-Widget submission-routing worker handler (Phase 05 #58).
*
* Subscribes to the `outbox.form-submission-route` BullMQ queue (populated
* by the outbox dispatcher when `eventType` starts with `form.submission.`).
*
* The submission API ({@link
* apps/web/app/routes/api.embed.forms.$formKey.submit.tsx}) already
* persists every payload as a generic `FormSubmission` row. This worker
* runs the *follow-up* side-effect — depending on `targetType`:
*
* - `generic` → no-op (the row is already stored)
* - `crm-contact` → create a CRM contact via `CrmService.createContact`
* using the form's `fieldMapping`
* - `entity-row` → create a row in `targetEntityId` via `RowsApi.create`
*
* On success the worker:
* - updates `FormSubmission.status` to `routed-to-crm` /
* `routed-to-entity` / `processed` (for generic), and
* - writes the target reference (e.g. created row id) to
* `FormSubmission.result`.
*
* Failures are NOT silently swallowed:
* - `FormSubmission.status` becomes `route-failed`
* - `FormSubmission.result.error` carries the redacted message
* - the error is re-thrown so the BullMQ retry machinery + Sentry
* reporter both see it.
*
* Idempotency: routing relies on the outbox dispatch-key
* (`form-submission:<id>`) to avoid duplicate delivery. The worker
* itself short-circuits when it sees a non-`received` status, which
* makes manual replays safe.
*/
import { applyFieldMapping } from "@toolctrl/form-widget";
export const FORM_SUBMISSION_ROUTE_QUEUE = "outbox.form-submission-route" as const;
/** Routing-status values written back to `FormSubmission.status`. */
export type FormSubmissionRoutingStatus =
| "received"
| "processed"
| "routed-to-crm"
| "routed-to-entity"
| "route-failed";
export interface FormSubmissionRouteJobData {
readonly outboxEventId?: string;
readonly tenantId: string;
readonly eventType: string;
readonly payload: {
readonly submissionId: string;
readonly formId: string;
readonly tenantId: string;
readonly targetType: "generic" | "crm-contact" | "entity-row";
readonly targetEntityId: string | null;
readonly fieldMapping: Record<string, string>;
readonly webhookUrl: string | null;
readonly notifyEmails?: readonly string[];
readonly values: Record<string, unknown>;
};
}
export interface FormSubmissionStore {
/**
* Mark a submission row with routing result. Implementations are
* expected to issue a single Prisma `update` keyed by submissionId.
*/
markRouted(input: {
submissionId: string;
tenantId: string;
status: FormSubmissionRoutingStatus;
result: Record<string, unknown>;
}): Promise<void>;
/**
* Look up the current row so we can short-circuit replays / re-runs.
* `null` ⇒ submission was deleted; we no-op and log.
*/
load(submissionId: string): Promise<{ status: string; tenantId: string } | null>;
}
/**
* CRM adapter — accepts a flat key/value record produced by
* `applyFieldMapping`. We don't bind to a specific CRM signature here
* (Phase 05's CRM lives in apps/web). The bootstrap wires a thin
* adapter that forwards to `CrmService.createContact`.
*/
export interface CrmContactCreator {
createContact(input: {
tenantId: string;
values: Record<string, unknown>;
}): Promise<{ id: string }>;
}
export interface EntityRowCreator {
createRow(input: {
tenantId: string;
entityId: string;
values: Record<string, unknown>;
}): Promise<{ id: string }>;
}
export interface FormSubmissionRouteLogger {
info?: (record: Record<string, unknown>, message?: string) => void;
warn?: (record: Record<string, unknown>, message?: string) => void;
error: (record: Record<string, unknown>, message?: string) => void;
}
export interface FormSubmissionRouteReporter {
captureException?: (error: unknown, context?: Record<string, unknown>) => void;
}
export interface FormSubmissionRouteDependencies {
readonly store: FormSubmissionStore;
readonly crm?: CrmContactCreator;
readonly entity?: EntityRowCreator;
readonly logger?: FormSubmissionRouteLogger;
readonly reporter?: FormSubmissionRouteReporter;
/**
* Optional callback fired after routing succeeds, used by the bootstrap
* to publish webhook + notify-email follow-up outbox events. Kept as a
* dependency so this handler stays free of DB / Prisma imports.
*/
readonly emitFollowUps?: (followUp: {
submissionId: string;
formId: string;
tenantId: string;
targetType: FormSubmissionRouteJobData["payload"]["targetType"];
target: { id: string | null };
webhookUrl: string | null;
notifyEmails: readonly string[];
values: Record<string, unknown>;
}) => Promise<void>;
}
export interface FormSubmissionRouteJobResult {
readonly submissionId: string;
readonly status: FormSubmissionRoutingStatus;
readonly target: { id: string | null };
}
export class FormSubmissionRouteJobError extends Error {
override readonly name = "FormSubmissionRouteJobError";
readonly code:
| "INVALID_PAYLOAD"
| "INVALID_EVENT_TYPE"
| "TENANT_MISMATCH"
| "MISSING_CRM_ADAPTER"
| "MISSING_ENTITY_ADAPTER"
| "MISSING_TARGET_ENTITY";
constructor(message: string, code: FormSubmissionRouteJobError["code"]) {
super(message);
this.code = code;
}
}
export function parseFormSubmissionRouteJob(data: unknown): FormSubmissionRouteJobData {
if (!data || typeof data !== "object") {
throw new FormSubmissionRouteJobError(
"form-submission-route job missing data envelope",
"INVALID_PAYLOAD",
);
}
const envelope = data as Record<string, unknown>;
const eventType = typeof envelope.eventType === "string" ? envelope.eventType : "";
if (!eventType.startsWith("form.submission.")) {
throw new FormSubmissionRouteJobError(
`form-submission-route rejected eventType ${JSON.stringify(eventType)}`,
"INVALID_EVENT_TYPE",
);
}
const tenantId = typeof envelope.tenantId === "string" ? envelope.tenantId : "";
if (!tenantId) {
throw new FormSubmissionRouteJobError(
"form-submission-route job missing tenantId",
"INVALID_PAYLOAD",
);
}
const rawPayload = envelope.payload;
if (!rawPayload || typeof rawPayload !== "object") {
throw new FormSubmissionRouteJobError(
"form-submission-route job missing payload",
"INVALID_PAYLOAD",
);
}
const p = rawPayload as Record<string, unknown>;
const submissionId = typeof p.submissionId === "string" ? p.submissionId : "";
const formId = typeof p.formId === "string" ? p.formId : "";
const targetType = p.targetType;
if (!submissionId || !formId) {
throw new FormSubmissionRouteJobError(
"form-submission-route payload missing submissionId/formId",
"INVALID_PAYLOAD",
);
}
if (targetType !== "generic" && targetType !== "crm-contact" && targetType !== "entity-row") {
throw new FormSubmissionRouteJobError(
`form-submission-route payload has invalid targetType ${JSON.stringify(targetType)}`,
"INVALID_PAYLOAD",
);
}
const fieldMapping =
p.fieldMapping && typeof p.fieldMapping === "object"
? (p.fieldMapping as Record<string, string>)
: {};
const values =
p.values && typeof p.values === "object" ? (p.values as Record<string, unknown>) : {};
const notifyEmails = Array.isArray(p.notifyEmails)
? (p.notifyEmails.filter((v) => typeof v === "string") as string[])
: [];
const payloadTenantId = typeof p.tenantId === "string" ? p.tenantId : tenantId;
if (payloadTenantId !== tenantId) {
throw new FormSubmissionRouteJobError(
"form-submission-route tenantId mismatch between envelope and payload",
"TENANT_MISMATCH",
);
}
return {
outboxEventId: typeof envelope.outboxEventId === "string" ? envelope.outboxEventId : undefined,
tenantId,
eventType,
payload: {
submissionId,
formId,
tenantId: payloadTenantId,
targetType,
targetEntityId: typeof p.targetEntityId === "string" ? p.targetEntityId : null,
fieldMapping,
webhookUrl: typeof p.webhookUrl === "string" ? p.webhookUrl : null,
notifyEmails,
values,
},
};
}
function redactErrorMessage(message: string): string {
// Cap length to 500 chars and strip obvious secret-shaped substrings.
const capped = message.length > 500 ? `${message.slice(0, 480)}… (truncated)` : message;
return capped
.replace(/(authorization\s*:\s*Bearer\s+)\S+/gi, "$1[redacted]")
.replace(/(password|secret|token|api[_-]?key)(\s*[=:]\s*)\S+/gi, "$1$2[redacted]");
}
export async function runFormSubmissionRouteJob(
data: unknown,
deps: FormSubmissionRouteDependencies,
): Promise<FormSubmissionRouteJobResult> {
const job = parseFormSubmissionRouteJob(data);
const { submissionId, formId, tenantId, targetType, targetEntityId, fieldMapping, values } =
job.payload;
const existing = await deps.store.load(submissionId);
if (!existing) {
deps.logger?.warn?.(
{ op: "form-submission-route.missing", submissionId, formId },
"submission row not found — skipping",
);
return { submissionId, status: "processed", target: { id: null } };
}
if (existing.status !== "received") {
deps.logger?.info?.(
{ op: "form-submission-route.skipped", submissionId, status: existing.status },
"submission already routed — skipping replay",
);
return {
submissionId,
status: existing.status as FormSubmissionRoutingStatus,
target: { id: null },
};
}
if (existing.tenantId !== tenantId) {
throw new FormSubmissionRouteJobError(
"form-submission-route loaded a submission for a different tenant",
"TENANT_MISMATCH",
);
}
let routedTarget: { id: string | null } = { id: null };
let newStatus: FormSubmissionRoutingStatus = "processed";
try {
if (targetType === "generic") {
newStatus = "processed";
} else if (targetType === "crm-contact") {
if (!deps.crm) {
throw new FormSubmissionRouteJobError(
"CRM adapter not configured",
"MISSING_CRM_ADAPTER",
);
}
const mapped = applyFieldMapping({ payload: values, fieldMapping });
const contact = await deps.crm.createContact({ tenantId, values: mapped });
routedTarget = { id: contact.id };
newStatus = "routed-to-crm";
} else if (targetType === "entity-row") {
if (!targetEntityId) {
throw new FormSubmissionRouteJobError(
"entity-row routing requires targetEntityId",
"MISSING_TARGET_ENTITY",
);
}
if (!deps.entity) {
throw new FormSubmissionRouteJobError(
"Entity adapter not configured",
"MISSING_ENTITY_ADAPTER",
);
}
const mapped = applyFieldMapping({ payload: values, fieldMapping });
const row = await deps.entity.createRow({
tenantId,
entityId: targetEntityId,
values: mapped,
});
routedTarget = { id: row.id };
newStatus = "routed-to-entity";
}
await deps.store.markRouted({
submissionId,
tenantId,
status: newStatus,
result: { target: targetType, targetId: routedTarget.id },
});
deps.logger?.info?.(
{
op: "form-submission-route.routed",
submissionId,
formId,
targetType,
targetId: routedTarget.id,
status: newStatus,
},
"submission routed",
);
if (deps.emitFollowUps) {
try {
await deps.emitFollowUps({
submissionId,
formId,
tenantId,
targetType,
target: routedTarget,
webhookUrl: job.payload.webhookUrl,
notifyEmails: job.payload.notifyEmails ?? [],
values,
});
} catch (err) {
// Follow-up emission MUST NOT fail the route job; the row is
// already routed. We log + capture so ops can backfill.
const msg = err instanceof Error ? err.message : String(err);
deps.logger?.warn?.(
{
op: "form-submission-route.followup-failed",
submissionId,
err: redactErrorMessage(msg),
},
"follow-up emission failed (non-fatal)",
);
deps.reporter?.captureException?.(err, {
component: "form-submission-route",
op: "emit-follow-ups",
submissionId,
});
}
}
return { submissionId, status: newStatus, target: routedTarget };
} catch (err) {
const message = redactErrorMessage(err instanceof Error ? err.message : String(err));
deps.logger?.error(
{
op: "form-submission-route.failed",
submissionId,
formId,
targetType,
err: message,
},
"submission routing failed",
);
deps.reporter?.captureException?.(err, {
component: "form-submission-route",
op: "route",
submissionId,
formId,
targetType,
});
try {
await deps.store.markRouted({
submissionId,
tenantId,
status: "route-failed",
result: { target: targetType, error: message },
});
} catch (markErr) {
deps.logger?.error(
{
op: "form-submission-route.mark-failed-error",
submissionId,
err: markErr instanceof Error ? redactErrorMessage(markErr.message) : String(markErr),
},
"could not mark submission as failed",
);
}
throw err;
}
}