@dakkitor/api-contracts 1.7.0 → 1.8.0

package/dist/document-intake/document-intake.automation.spec.js

@@ -0,0 +1,469 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const bun_test_1 = require("bun:test");
+const DocumentIntakeContract = __importStar(require("./document-intake.contract"));
+const document_intake_contract_1 = require("./document-intake.contract");
+const RECORD_ID = '11111111-1111-4111-8111-111111111111';
+const FILE_ID = '22222222-2222-4222-8222-222222222222';
+const SUBJECT_ID = '33333333-3333-4333-8333-333333333333';
+const AUTO_DECISION = {
+    outcome: 'AUTO_APPLY',
+    reasonCodes: [],
+    policyVersion: 'document-auto-apply-v1',
+    mode: 'LIVE',
+    evaluatedSourceHash: 'a'.repeat(64),
+    evaluatedAt: '2026-08-16T12:00:00.000Z',
+};
+const FIELD_DECISION = {
+    field: 'firstName',
+    status: 'ELIGIBLE',
+    confidences: [0.95, 1],
+    evidenceTags: [['HOLDER_IDENTITY_PANEL'], ['HOLDER_IDENTITY_PANEL']],
+    validationReasons: [],
+};
+const EXTRACTED_FIELDS = {
+    documentType: 'qualification_certificate',
+    firstName: null,
+    lastName: null,
+    dateOfBirth: null,
+    expiryDate: null,
+    issueDate: null,
+    referenceNumber: null,
+    shareCode: null,
+    nino: null,
+    nationality: null,
+    confidence: 0,
+};
+const PARTIAL_READING = {
+    readingOrdinal: 1,
+    reading: {
+        documentType: {
+            value: 'cscs_card',
+            confidence: 0.99,
+            evidence: ['HOLDER_IDENTITY_PANEL'],
+        },
+        firstName: { value: 'Bounded', confidence: 0.98, evidence: [] },
+        lastName: { value: null, confidence: 0.7, evidence: [] },
+        dateOfBirth: { value: null, confidence: 0.7, evidence: [] },
+        expiryDate: {
+            value: '2027-01-01',
+            confidence: 0.97,
+            evidence: ['REGISTRATION_AND_EXPIRY_PANEL'],
+        },
+        issueDate: { value: null, confidence: 0.7, evidence: [] },
+        referenceNumber: { value: null, confidence: 0.7, evidence: [] },
+        shareCode: { value: null, confidence: 0.7, evidence: [] },
+        nino: { value: null, confidence: 0.7, evidence: [] },
+        nationality: { value: null, confidence: 0.7, evidence: [] },
+        qualificationName: { value: null, confidence: 0.7, evidence: [] },
+        qualificationTypeName: {
+            value: null,
+            confidence: 0.7,
+            evidence: [],
+        },
+        qualificationIssuerText: {
+            value: null,
+            confidence: 0.7,
+            evidence: [],
+        },
+        qualificationCardColour: {
+            value: null,
+            confidence: 0.7,
+            evidence: [],
+        },
+        qualificationRoleText: {
+            value: null,
+            confidence: 0.7,
+            evidence: [],
+        },
+        cardSide: { value: null, confidence: 0.7, evidence: [] },
+        cardLayout: 'SINGLE_FACE',
+    },
+};
+const INTAKE_RECORD = {
+    id: RECORD_ID,
+    fileId: FILE_ID,
+    workerId: SUBJECT_ID,
+    curatedWorkerId: null,
+    classification: 'qualification_certificate',
+    destinationSuggested: 'QUALIFICATION',
+    destinationFinal: null,
+    extracted: null,
+    confidence: 0,
+    overridden: false,
+    status: 'PENDING_CONFIRM',
+};
+const BACKFILL_SUBJECT_DOCUMENT = {
+    recordId: RECORD_ID,
+    fileId: FILE_ID,
+    originalName: null,
+    mimeType: null,
+    sourceType: 'QUALIFICATION_PROOF',
+    sourceId: RECORD_ID,
+    actor: 'HUMAN',
+    status: 'PENDING_CONFIRM',
+    reviewable: true,
+    evaluatedAt: null,
+    currentlyFiledAs: 'QUALIFICATION',
+    classification: 'qualification_certificate',
+    destinationSuggested: 'QUALIFICATION',
+    confidence: 0,
+    extracted: null,
+    currentQualificationId: null,
+    currentQualificationName: null,
+    sourceRow: null,
+    createdAt: '2026-08-16T12:00:00.000Z',
+};
+const BACKFILL_AUDIT_RECORD = {
+    recordId: RECORD_ID,
+    fileId: FILE_ID,
+    workerId: SUBJECT_ID,
+    curatedWorkerId: null,
+    subjectName: 'Worker',
+    originalName: null,
+    sourceType: 'QUALIFICATION_PROOF',
+    sourceId: RECORD_ID,
+    actor: 'HUMAN',
+    status: 'PENDING_CONFIRM',
+    classification: 'qualification_certificate',
+    confidence: 0,
+    failureKind: null,
+    evaluatedAt: null,
+    createdAt: '2026-08-16T12:00:00.000Z',
+    supersedesRecordId: null,
+    supersededByRecordId: null,
+    isCurrent: true,
+    extractorFingerprint: null,
+    evaluationFingerprint: null,
+};
+const automationExports = DocumentIntakeContract;
+const automationSchema = (name) => {
+    const schema = automationExports[name];
+    (0, bun_test_1.expect)(schema).toBeDefined();
+    return schema;
+};
+(0, bun_test_1.describe)('document intake consensus contract', () => {
+    (0, bun_test_1.it)('accepts exact qualification sources and source slots', () => {
+        (0, bun_test_1.expect)(document_intake_contract_1.IntakeSourceTypeSchema.parse('CURATED_QUALIFICATION_PROOF')).toBe('CURATED_QUALIFICATION_PROOF');
+        (0, bun_test_1.expect)(automationSchema('IntakeSourceSlotSchema').options).toEqual([
+            'PRIMARY',
+            'BACK',
+        ]);
+    });
+    (0, bun_test_1.it)('accepts every field-decision status', () => {
+        for (const status of [
+            'ELIGIBLE',
+            'ABSENT',
+            'ONE_SIDED',
+            'LOW_CONFIDENCE',
+            'DISAGREEMENT',
+            'INVALID',
+        ]) {
+            (0, bun_test_1.expect)(automationSchema('DocumentFieldDecisionStatusSchema').parse(status)).toBe(status);
+        }
+    });
+    (0, bun_test_1.it)('accepts every automatic outcome and reason', () => {
+        for (const outcome of [
+            'AUTO_APPLY',
+            'HUMAN_REVIEW_CONFLICT',
+            'HUMAN_REVIEW_INCOMPLETE_CONSENSUS',
+            'HUMAN_REVIEW_LOW_CONFIDENCE',
+            'HUMAN_REVIEW_DESTINATION',
+            'HUMAN_REVIEW_NINO_OWNERSHIP',
+            'HUMAN_REVIEW_OCCUPIED_SLOT',
+            'HUMAN_REVIEW_UNSUPPORTED_CARD_SCHEME',
+            'NO_CHANGE',
+            'SHADOW_ONLY',
+        ]) {
+            (0, bun_test_1.expect)(automationSchema('DocumentAutoDecisionOutcomeSchema').parse(outcome)).toBe(outcome);
+        }
+        for (const reason of [
+            'FIELD_CONFLICT',
+            'INCOMPLETE_CONSENSUS',
+            'LOW_CONFIDENCE',
+            'INVALID_VALUE',
+            'DESTINATION_AMBIGUOUS',
+            'NINO_OWNED_BY_ANOTHER_IDENTITY',
+            'QUALIFICATION_AMBIGUOUS',
+            'TARGET_SLOT_OCCUPIED',
+            'CARD_SCHEME_UNSUPPORTED',
+            'CARD_SIDE_AMBIGUOUS',
+            'MULTIPLE_CARD_FACES',
+            'SOURCE_CHANGED',
+            'AUTO_APPLY_DISABLED',
+            'AUTO_OVERWRITE_DISABLED',
+            'NO_CHANGE',
+        ]) {
+            (0, bun_test_1.expect)(automationSchema('DocumentAutoDecisionReasonSchema').parse(reason)).toBe(reason);
+        }
+    });
+    (0, bun_test_1.it)('accepts a privacy-safe policy fingerprint while preserving legacy decisions', () => {
+        const schema = automationSchema('DocumentAutoDecisionSchema');
+        (0, bun_test_1.expect)(schema.parse(AUTO_DECISION)).toEqual(AUTO_DECISION);
+        (0, bun_test_1.expect)(schema.parse({ ...AUTO_DECISION, policyFingerprint: 'b'.repeat(64) })).toEqual({ ...AUTO_DECISION, policyFingerprint: 'b'.repeat(64) });
+        (0, bun_test_1.expect)(schema.safeParse({ ...AUTO_DECISION, policyFingerprint: 'CSCS' }).success).toBe(false);
+    });
+    (0, bun_test_1.it)('parses controlled field decisions and rejects out-of-range confidences', () => {
+        (0, bun_test_1.expect)(automationSchema('DocumentFieldDecisionSchema').parse(FIELD_DECISION)).toEqual(FIELD_DECISION);
+        (0, bun_test_1.expect)(automationSchema('DocumentFieldDecisionSchema').safeParse({
+            ...FIELD_DECISION,
+            confidences: [-0.01, 1],
+        }).success).toBe(false);
+        (0, bun_test_1.expect)(automationSchema('DocumentFieldDecisionSchema').safeParse({
+            ...FIELD_DECISION,
+            confidences: [0.95, 1.01],
+        }).success).toBe(false);
+    });
+    (0, bun_test_1.it)('rejects out-of-range confidences on every exposed document response', () => {
+        const responseSchemas = [
+            { schema: document_intake_contract_1.ExtractedDocumentFieldsSchema, value: EXTRACTED_FIELDS },
+            { schema: document_intake_contract_1.IntakeRecordResponseSchema, value: INTAKE_RECORD },
+            {
+                schema: document_intake_contract_1.BackfillSubjectDocumentSchema,
+                value: BACKFILL_SUBJECT_DOCUMENT,
+            },
+            { schema: document_intake_contract_1.BackfillAuditRecordSchema, value: BACKFILL_AUDIT_RECORD },
+        ];
+        for (const confidence of [-0.1, 1.1]) {
+            for (const { schema, value } of responseSchemas) {
+                (0, bun_test_1.expect)(schema.safeParse({ ...value, confidence }).success).toBe(false);
+            }
+        }
+    });
+    (0, bun_test_1.it)('defaults omitted legacy source and review metadata', () => {
+        const intake = document_intake_contract_1.IntakeRecordResponseSchema.parse(INTAKE_RECORD);
+        (0, bun_test_1.expect)(intake.sourceSlot).toBe('PRIMARY');
+        (0, bun_test_1.expect)(intake.requiresIdentityReview).toBe(false);
+        const queue = document_intake_contract_1.BackfillSubjectSummarySchema.parse({
+            subjectType: 'CURATED_WORKER',
+            subjectId: SUBJECT_ID,
+            subjectName: 'Worker',
+            documentCount: 1,
+            pendingKinds: ['FILL'],
+            oldestDocumentAt: '2026-08-16T12:00:00.000Z',
+        });
+        (0, bun_test_1.expect)(queue.reviewReasons).toEqual([]);
+        const detail = document_intake_contract_1.BackfillSubjectDocumentSchema.parse(BACKFILL_SUBJECT_DOCUMENT);
+        (0, bun_test_1.expect)(detail.sourceSlot).toBe('PRIMARY');
+        (0, bun_test_1.expect)(detail.requiresIdentityReview).toBe(false);
+        const history = document_intake_contract_1.BackfillAuditRecordSchema.parse(BACKFILL_AUDIT_RECORD);
+        (0, bun_test_1.expect)(history.sourceSlot).toBe('PRIMARY');
+        (0, bun_test_1.expect)(history.reviewReasons).toEqual([]);
+        (0, bun_test_1.expect)(history.requiresIdentityReview).toBe(false);
+    });
+    (0, bun_test_1.it)('parses queue review reasons without exposing extracted values', () => {
+        const parsed = document_intake_contract_1.BackfillSubjectSummarySchema.parse({
+            subjectType: 'CURATED_WORKER',
+            subjectId: SUBJECT_ID,
+            subjectName: 'Worker',
+            documentCount: 1,
+            pendingKinds: ['FILL'],
+            oldestDocumentAt: '2026-08-16T12:00:00.000Z',
+            reviewReasons: ['CARD_SIDE_AMBIGUOUS'],
+            extracted: { firstName: 'Must not survive queue parsing' },
+            partialReading: PARTIAL_READING,
+        });
+        (0, bun_test_1.expect)(parsed).not.toHaveProperty('extracted');
+        (0, bun_test_1.expect)(parsed).not.toHaveProperty('partialReading');
+        (0, bun_test_1.expect)(parsed.reviewReasons).toEqual(['CARD_SIDE_AMBIGUOUS']);
+    });
+    (0, bun_test_1.it)('exposes one bounded partial reading only on authorized detail and history', () => {
+        for (const [schema, value] of [
+            [document_intake_contract_1.BackfillSubjectDocumentSchema, BACKFILL_SUBJECT_DOCUMENT],
+            [document_intake_contract_1.BackfillAuditRecordSchema, BACKFILL_AUDIT_RECORD],
+        ]) {
+            const parsed = schema.parse({
+                ...value,
+                partialReading: PARTIAL_READING,
+            });
+            (0, bun_test_1.expect)(parsed).toHaveProperty('partialReading', PARTIAL_READING);
+            (0, bun_test_1.expect)(schema.safeParse({
+                ...value,
+                partialReading: {
+                    ...PARTIAL_READING,
+                    reading: {
+                        ...PARTIAL_READING.reading,
+                        firstName: {
+                            value: 'Unbounded',
+                            confidence: 1.1,
+                            evidence: [],
+                        },
+                    },
+                },
+            }).success).toBe(false);
+            (0, bun_test_1.expect)(schema.safeParse({
+                ...value,
+                partialReading: {
+                    ...PARTIAL_READING,
+                    reading: {
+                        ...PARTIAL_READING.reading,
+                        cardSide: {
+                            value: 'front',
+                            confidence: 0.9,
+                            evidence: ['raw provider prose'],
+                        },
+                    },
+                },
+            }).success).toBe(false);
+        }
+    });
+    (0, bun_test_1.it)('parses nullable automation metadata on detail and history records', () => {
+        const detail = document_intake_contract_1.BackfillSubjectDocumentSchema.parse({
+            recordId: RECORD_ID,
+            fileId: FILE_ID,
+            originalName: null,
+            mimeType: null,
+            sourceType: 'QUALIFICATION_PROOF',
+            sourceId: RECORD_ID,
+            sourceSlot: 'PRIMARY',
+            actor: 'HUMAN',
+            status: 'VERIFIED_NO_CHANGE',
+            reviewable: false,
+            evaluatedAt: null,
+            currentlyFiledAs: 'QUALIFICATION',
+            classification: 'qualification_certificate',
+            destinationSuggested: 'QUALIFICATION',
+            confidence: null,
+            extracted: {
+                documentType: 'qualification_certificate',
+                firstName: null,
+                lastName: null,
+                dateOfBirth: null,
+                expiryDate: null,
+                issueDate: null,
+                referenceNumber: null,
+                shareCode: null,
+                nino: null,
+                nationality: null,
+                confidence: 0,
+            },
+            fieldDecisions: [],
+            requiresIdentityReview: false,
+            currentQualificationId: null,
+            currentQualificationName: null,
+            sourceRow: null,
+            createdAt: '2026-08-16T12:00:00.000Z',
+        });
+        (0, bun_test_1.expect)(detail).not.toHaveProperty('autoDecision');
+        (0, bun_test_1.expect)(detail.fieldDecisions).toEqual([]);
+        const history = document_intake_contract_1.BackfillAuditRecordSchema.parse({
+            recordId: RECORD_ID,
+            fileId: FILE_ID,
+            workerId: SUBJECT_ID,
+            curatedWorkerId: null,
+            subjectName: 'Worker',
+            originalName: null,
+            sourceType: 'CURATED_QUALIFICATION_PROOF',
+            sourceId: RECORD_ID,
+            sourceSlot: 'PRIMARY',
+            actor: 'AUTOMATIC',
+            status: 'APPLIED',
+            classification: 'cscs_card',
+            confidence: 1,
+            failureKind: null,
+            reviewReasons: [],
+            autoDecision: AUTO_DECISION,
+            fieldDecisions: [FIELD_DECISION],
+            consensusVersion: 'consensus-v1',
+            requiresIdentityReview: false,
+            evaluatedAt: '2026-08-16T12:00:00.000Z',
+            createdAt: '2026-08-16T12:00:00.000Z',
+            supersedesRecordId: null,
+            supersededByRecordId: null,
+            isCurrent: true,
+            extractorFingerprint: 'extractor-v1',
+            evaluationFingerprint: 'evaluation-v1',
+        });
+        (0, bun_test_1.expect)(automationSchema('DocumentAutoDecisionSchema').parse(history.autoDecision)).toEqual(AUTO_DECISION);
+    });
+    (0, bun_test_1.it)('requires legacy final-actor metadata to be omitted rather than fabricated as null', () => {
+        (0, bun_test_1.expect)(document_intake_contract_1.BackfillSubjectDocumentSchema.safeParse({
+            ...BACKFILL_SUBJECT_DOCUMENT,
+            actor: null,
+        }).success).toBe(false);
+        (0, bun_test_1.expect)(document_intake_contract_1.BackfillAuditRecordSchema.safeParse({
+            ...BACKFILL_AUDIT_RECORD,
+            actor: null,
+        }).success).toBe(false);
+    });
+    (0, bun_test_1.it)('exposes only exact source/target provenance, not document values, for authorized detail and history records', () => {
+        const provenance = {
+            before: {
+                kind: 'QUALIFICATION',
+                id: RECORD_ID,
+                slot: 'BACK',
+                fileId: null,
+            },
+            after: {
+                kind: 'QUALIFICATION',
+                id: SUBJECT_ID,
+                slot: 'PRIMARY',
+                fileId: FILE_ID,
+            },
+        };
+        (0, bun_test_1.expect)(automationSchema('DocumentMutationProvenanceSchema').parse(provenance)).toEqual(provenance);
+        (0, bun_test_1.expect)(automationSchema('DocumentReviewActorSchema').options).toEqual([
+            'HUMAN',
+            'AUTOMATIC',
+        ]);
+    });
+    (0, bun_test_1.it)('bounds authorized before/after audit changes to known document fields and preserves stored extraction metadata', () => {
+        const parsed = automationSchema('DocumentAuditChangeSchema').parse({
+            field: 'fileId',
+            slot: 'BACK',
+            from: null,
+            to: FILE_ID,
+        });
+        (0, bun_test_1.expect)(parsed).toMatchObject({ field: 'fileId', slot: 'BACK' });
+        (0, bun_test_1.expect)(automationSchema('DocumentAuditChangeSchema').safeParse({
+            field: 'unbounded_private_key',
+            from: 'before',
+            to: 'after',
+        }).success).toBe(false);
+        const detail = document_intake_contract_1.BackfillSubjectDocumentSchema.parse({
+            ...BACKFILL_SUBJECT_DOCUMENT,
+            actor: 'AUTOMATIC',
+            requiresIdentityReview: true,
+            auditChanges: [{ field: 'firstName', from: 'Before', to: 'After' }],
+            extractionModel: 'gemini-3.1-flash-lite',
+            promptVersion: '2026-08-16.1',
+        });
+        (0, bun_test_1.expect)(detail.requiresIdentityReview).toBe(true);
+        (0, bun_test_1.expect)(detail.auditChanges).toHaveLength(1);
+        (0, bun_test_1.expect)(detail.extractionModel).toBe('gemini-3.1-flash-lite');
+        (0, bun_test_1.expect)(detail.promptVersion).toBe('2026-08-16.1');
+    });
+});

package/dist/document-intake/document-intake.card-side.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=document-intake.card-side.spec.d.ts.map

package/dist/document-intake/document-intake.card-side.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-intake.card-side.spec.d.ts","sourceRoot":"","sources":["../../contracts/document-intake/document-intake.card-side.spec.ts"],"names":[],"mappings":""}

package/dist/document-intake/document-intake.card-side.spec.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const bun_test_1 = require("bun:test");
+const index_1 = require("../index");
+const BASE_FIELDS = {
+    documentType: 'cscs_card',
+    firstName: null,
+    lastName: null,
+    dateOfBirth: null,
+    expiryDate: null,
+    issueDate: null,
+    referenceNumber: null,
+    shareCode: null,
+    nino: null,
+    nationality: null,
+    confidence: 0.9,
+};
+(0, bun_test_1.describe)('ExtractedDocumentFieldsSchema.cardSide', () => {
+    (0, bun_test_1.it)('accepts "front"', () => {
+        const parsed = index_1.ExtractedDocumentFieldsSchema.parse({
+            ...BASE_FIELDS,
+            cardSide: 'front',
+        });
+        (0, bun_test_1.expect)(parsed.cardSide).toBe('front');
+    });
+    (0, bun_test_1.it)('accepts "back"', () => {
+        const parsed = index_1.ExtractedDocumentFieldsSchema.parse({
+            ...BASE_FIELDS,
+            cardSide: 'back',
+        });
+        (0, bun_test_1.expect)(parsed.cardSide).toBe('back');
+    });
+    (0, bun_test_1.it)('accepts null', () => {
+        const parsed = index_1.ExtractedDocumentFieldsSchema.parse({
+            ...BASE_FIELDS,
+            cardSide: null,
+        });
+        (0, bun_test_1.expect)(parsed.cardSide).toBeNull();
+    });
+    (0, bun_test_1.it)('is optional (omitting it still parses)', () => {
+        const parsed = index_1.ExtractedDocumentFieldsSchema.parse({ ...BASE_FIELDS });
+        (0, bun_test_1.expect)(parsed.cardSide).toBeUndefined();
+    });
+    (0, bun_test_1.it)('rejects any other value', () => {
+        const result = index_1.ExtractedDocumentFieldsSchema.safeParse({
+            ...BASE_FIELDS,
+            cardSide: 'sideways',
+        });
+        (0, bun_test_1.expect)(result.success).toBe(false);
+    });
+});