409 lines
13 KiB
TypeScript
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;
|
|
}
|
|
}
|