93 lines
3.8 KiB
TypeScript
93 lines
3.8 KiB
TypeScript
/**
|
|
* 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<Record<string, string>>;
|
|
}
|
|
|
|
export interface ResolveSubmissionTargetInput {
|
|
readonly targetType?: string | null;
|
|
readonly targetEntityId?: string | null;
|
|
readonly fieldMapping?: Record<string, string> | null;
|
|
}
|
|
|
|
const VALID_TARGETS: ReadonlySet<SubmissionTargetType> = new Set(["generic", "crm-contact", "entity-row"]);
|
|
|
|
function isValidTarget(value: unknown): value is SubmissionTargetType {
|
|
return typeof value === "string" && (VALID_TARGETS as Set<string>).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<Record<string, unknown>> | null | undefined;
|
|
readonly fieldMapping?: Readonly<Record<string, string>> | null;
|
|
}
|
|
|
|
export function applyFieldMapping(input: ApplyFieldMappingInput): Record<string, unknown> {
|
|
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<string, unknown> = {};
|
|
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<string, unknown>)[sourceKey];
|
|
}
|
|
return out;
|
|
}
|