Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
+408
@@ -0,0 +1,408 @@
|
||||
/**
|
||||
* 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;
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user