Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/form-widget/src/routing.ts
T

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;
}