/** * Submission-routing resolver. A form can route inbound submissions to one * of three targets: * * - `generic` — store as FormSubmission row only (default) * - `crm-contact` — upsert a CRM contact using mapped fields * - `entity-row` — create a row in a tenant-defined entity * * The resolver here is pure: it just describes the target. The actual * write happens in the submission route / worker handler. */ export type SubmissionTargetType = "generic" | "crm-contact" | "entity-row"; export interface SubmissionTargetDescriptor { readonly type: SubmissionTargetType; readonly entityId: string | null; readonly fieldMapping: Readonly>; } export interface ResolveSubmissionTargetInput { readonly targetType?: string | null; readonly targetEntityId?: string | null; readonly fieldMapping?: Record | null; } const VALID_TARGETS: ReadonlySet = new Set(["generic", "crm-contact", "entity-row"]); function isValidTarget(value: unknown): value is SubmissionTargetType { return typeof value === "string" && (VALID_TARGETS as Set).has(value); } export function resolveSubmissionTarget(input: ResolveSubmissionTargetInput): SubmissionTargetDescriptor { const type: SubmissionTargetType = isValidTarget(input.targetType) ? input.targetType : "generic"; if (type === "entity-row" && !input.targetEntityId) { // misconfigured form — fall back to generic so submissions still land somewhere return { type: "generic", entityId: null, fieldMapping: Object.freeze({}) }; } return { type, entityId: input.targetEntityId ?? null, fieldMapping: Object.freeze({ ...(input.fieldMapping ?? {}) }), }; } /** * Field-mapping helper used by the worker when routing a form submission * to a CRM contact / tenant-entity row. * * `payload` is the raw key/value map the user filled in, where the keys * are the form-field keys (e.g. `firstName`, `email_address`). * `fieldMapping` maps form-field keys to target property keys (e.g. * `{ "email_address": "email", "firstName": "first_name" }`). * * Behaviour: * - When `fieldMapping` is empty/undefined the helper passes the payload * through unchanged (1:1 mapping). This is the legitimate path for * "the form fields are already named to match the entity columns". * - Unmapped form fields are dropped. Targets typically have a fixed * column schema, so silently dropping is safer than forwarding stray * data that the entity row API would reject. * - When two form fields map to the same target column the later one * wins. The form-builder UI should warn on duplicate target keys; we * don't throw because reconfiguring a form must not break in-flight * submissions. * - Null/undefined values are forwarded as-is so the receiver can * distinguish "not provided" from "empty string". * * The helper is intentionally synchronous & dependency-free: it runs in * the worker handler hot path and must not touch DB / network. */ export interface ApplyFieldMappingInput { readonly payload: Readonly> | null | undefined; readonly fieldMapping?: Readonly> | null; } export function applyFieldMapping(input: ApplyFieldMappingInput): Record { const payload = input.payload ?? {}; const mapping = input.fieldMapping ?? {}; if (Object.keys(mapping).length === 0) { // No mapping configured → forward every form field 1:1. return { ...payload }; } const out: Record = {}; for (const [sourceKey, targetKey] of Object.entries(mapping)) { if (typeof targetKey !== "string" || targetKey.length === 0) continue; if (!Object.prototype.hasOwnProperty.call(payload, sourceKey)) continue; out[targetKey] = (payload as Record)[sourceKey]; } return out; }