refactor: share ER request validation across HTTP surfaces
This commit is contained in:
@@ -3,22 +3,40 @@ import { NextRequest, NextResponse } from "next/server";
|
||||
import { verifyInternalServiceToken } from "@/src/auth/internal-token";
|
||||
import {
|
||||
EntityResolutionService,
|
||||
type ErCandidateRequest,
|
||||
type ErCandidateResult,
|
||||
type ErRecord,
|
||||
} from "@/src/er/entity-resolution-service";
|
||||
import { parseErCandidateRequest } from "@/src/er/request-validation";
|
||||
import { siaxErrorResponse } from "@/src/http/siax-error-response";
|
||||
import { SiaxError } from "@/src/platform/errors";
|
||||
|
||||
const er = new EntityResolutionService();
|
||||
|
||||
function rawStringField(record: ErRecord, field: string): string | undefined {
|
||||
const value = record.fields[field];
|
||||
if (value === null || value === undefined) return undefined;
|
||||
const normalized = String(value).trim();
|
||||
return normalized || undefined;
|
||||
}
|
||||
|
||||
function stableIdentifier(record: ErRecord, field: string): string | undefined {
|
||||
const value = rawStringField(record, field);
|
||||
if (!value) return undefined;
|
||||
const normalized = value.toUpperCase().replace(/[^A-Z0-9]/g, "");
|
||||
return normalized || undefined;
|
||||
}
|
||||
|
||||
function countryIdentifier(record: ErRecord): string | undefined {
|
||||
const value = rawStringField(record, "registration_country") ?? rawStringField(record, "country");
|
||||
if (!value) return undefined;
|
||||
const normalized = value.toUpperCase().replace(/[^A-Z0-9]/g, "");
|
||||
return normalized || undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Company identity hard rule.
|
||||
*
|
||||
* LEI is globally scoped. National registration numbers are not: they may only
|
||||
* force a decision when both records also carry the same registration country.
|
||||
* Negative identity evidence dominates positive evidence within the same
|
||||
* identifier scope. Formatting punctuation is ignored for stable identifiers.
|
||||
* Company identity hard rule v3.
|
||||
* - LEI is globally scoped.
|
||||
* - National registration numbers are comparable only within the same country.
|
||||
* - Any comparable stable-ID conflict dominates every positive match.
|
||||
*/
|
||||
er.registerHardRule({
|
||||
rule_id: "0pt.company.stable-identifiers.v3",
|
||||
@@ -45,27 +63,6 @@ er.registerHardRule({
|
||||
},
|
||||
});
|
||||
|
||||
function rawStringField(record: ErRecord, field: string): string | undefined {
|
||||
const value = record.fields[field];
|
||||
if (value === null || value === undefined) return undefined;
|
||||
const normalized = String(value).trim();
|
||||
return normalized || undefined;
|
||||
}
|
||||
|
||||
function stableIdentifier(record: ErRecord, field: string): string | undefined {
|
||||
const value = rawStringField(record, field);
|
||||
if (!value) return undefined;
|
||||
const normalized = value.toUpperCase().replace(/[^A-Z0-9]/g, "");
|
||||
return normalized || undefined;
|
||||
}
|
||||
|
||||
function countryIdentifier(record: ErRecord): string | undefined {
|
||||
const value = rawStringField(record, "registration_country") ?? rawStringField(record, "country");
|
||||
if (!value) return undefined;
|
||||
const normalized = value.toUpperCase().replace(/[^A-Z0-9]/g, "");
|
||||
return normalized || undefined;
|
||||
}
|
||||
|
||||
function assertInternal(request: NextRequest): NextResponse | undefined {
|
||||
if (verifyInternalServiceToken(request.headers)) return undefined;
|
||||
return NextResponse.json(
|
||||
@@ -74,101 +71,9 @@ function assertInternal(request: NextRequest): NextResponse | undefined {
|
||||
);
|
||||
}
|
||||
|
||||
function finiteThreshold(value: unknown, field: string, fallback: number): number {
|
||||
if (value === undefined) return fallback;
|
||||
const parsed = Number(value);
|
||||
if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", `${field} must be a finite number between 0 and 1`);
|
||||
}
|
||||
return parsed;
|
||||
}
|
||||
|
||||
function parseRequest(raw: unknown): ErCandidateRequest {
|
||||
if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", "JSON object body is required");
|
||||
}
|
||||
const body = raw as Record<string, unknown>;
|
||||
const tenantId = typeof body.tenant_id === "string" ? body.tenant_id.trim() : "";
|
||||
const projectId = typeof body.project_id === "string" ? body.project_id.trim() : "";
|
||||
if (!tenantId) throw new SiaxError("INVALID_REQUEST", "0pt.er", "tenant_id is required");
|
||||
if (!projectId) throw new SiaxError("INVALID_REQUEST", "0pt.er", "project_id is required");
|
||||
|
||||
if (!Array.isArray(body.records) || body.records.length < 2 || body.records.length > 5_000) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", "records must contain between 2 and 5000 items");
|
||||
}
|
||||
if (
|
||||
!Array.isArray(body.blocking_fields) ||
|
||||
body.blocking_fields.length === 0 ||
|
||||
!body.blocking_fields.every((v) => typeof v === "string" && v.trim().length > 0)
|
||||
) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", "blocking_fields must be a non-empty string array");
|
||||
}
|
||||
if (!Array.isArray(body.compare_fields) || body.compare_fields.length === 0) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", "compare_fields must be a non-empty array");
|
||||
}
|
||||
|
||||
const records: ErRecord[] = body.records.map((value, index) => {
|
||||
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", `records[${index}] must be an object`);
|
||||
}
|
||||
const record = value as Record<string, unknown>;
|
||||
if (typeof record.record_id !== "string" || !record.record_id.trim()) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", `records[${index}].record_id is required`);
|
||||
}
|
||||
if (!record.fields || typeof record.fields !== "object" || Array.isArray(record.fields)) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", `records[${index}].fields must be an object`);
|
||||
}
|
||||
return { record_id: record.record_id.trim(), fields: record.fields as ErRecord["fields"] };
|
||||
});
|
||||
|
||||
if (new Set(records.map((record) => record.record_id)).size !== records.length) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", "record_id values must be unique within the request");
|
||||
}
|
||||
|
||||
const compareFields = body.compare_fields.map((value, index) => {
|
||||
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", `compare_fields[${index}] must be an object`);
|
||||
}
|
||||
const item = value as Record<string, unknown>;
|
||||
if (typeof item.field !== "string" || !item.field.trim()) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", `compare_fields[${index}].field is required`);
|
||||
}
|
||||
const weight = item.weight === undefined ? undefined : Number(item.weight);
|
||||
if (weight !== undefined && (!Number.isFinite(weight) || weight < 0 || weight > 100)) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", `compare_fields[${index}].weight must be between 0 and 100`);
|
||||
}
|
||||
return { field: item.field.trim(), ...(weight !== undefined ? { weight } : {}) };
|
||||
});
|
||||
|
||||
const autoThreshold = finiteThreshold(body.auto_match_threshold, "auto_match_threshold", 0.9);
|
||||
const reviewThreshold = finiteThreshold(body.review_threshold, "review_threshold", 0.6);
|
||||
if (reviewThreshold >= autoThreshold) {
|
||||
throw new SiaxError("INVALID_REQUEST", "0pt.er", "review_threshold must be lower than auto_match_threshold");
|
||||
}
|
||||
|
||||
return {
|
||||
tenant_id: tenantId,
|
||||
project_id: projectId,
|
||||
records,
|
||||
blocking_fields: (body.blocking_fields as string[]).map((value) => value.trim()),
|
||||
compare_fields: compareFields,
|
||||
auto_match_threshold: autoThreshold,
|
||||
review_threshold: reviewThreshold,
|
||||
...(typeof body.correlation_id === "string" && body.correlation_id.trim()
|
||||
? { correlation_id: body.correlation_id.trim() }
|
||||
: {}),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Company/Work boundary: fuzzy similarity is candidate evidence, never identity truth.
|
||||
*
|
||||
* The generic ER engine supports score-based `match` for domains that explicitly
|
||||
* choose that policy. This internal company endpoint is stricter: only a product
|
||||
* hard rule backed by stable identifiers may emit `match`. Any score-only match
|
||||
* is downgraded to `pending_review`, matching the review-gated Python candidate
|
||||
* layer used by Work/CRM/FIT0 and preventing two ER paths from disagreeing about
|
||||
* whether fuzzy similarity is sufficient to link an organization.
|
||||
* Only product hard rules backed by stable identifiers may emit `match` here.
|
||||
*/
|
||||
export function enforceCompanyReviewBoundary(result: ErCandidateResult): ErCandidateResult {
|
||||
const pairs = result.pairs.map((pair) =>
|
||||
@@ -188,7 +93,7 @@ export async function POST(request: NextRequest) {
|
||||
if (denied) return denied;
|
||||
|
||||
try {
|
||||
const result = er.generateCandidates(parseRequest(await request.json()));
|
||||
const result = er.generateCandidates(parseErCandidateRequest(await request.json()));
|
||||
return NextResponse.json(enforceCompanyReviewBoundary(result));
|
||||
} catch (error: unknown) {
|
||||
return siaxErrorResponse(error);
|
||||
|
||||
Reference in New Issue
Block a user