/** * 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:`) 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; readonly webhookUrl: string | null; readonly notifyEmails?: readonly string[]; readonly values: Record; }; } 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; }): Promise; /** * 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; }): Promise<{ id: string }>; } export interface EntityRowCreator { createRow(input: { tenantId: string; entityId: string; values: Record; }): Promise<{ id: string }>; } export interface FormSubmissionRouteLogger { info?: (record: Record, message?: string) => void; warn?: (record: Record, message?: string) => void; error: (record: Record, message?: string) => void; } export interface FormSubmissionRouteReporter { captureException?: (error: unknown, context?: Record) => 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; }) => Promise; } 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; 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; 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) : {}; const values = p.values && typeof p.values === "object" ? (p.values as Record) : {}; 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 { 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; } }