@dakkitor/api-contracts 1.8.0 → 1.9.2

package/dist/curated-worker-leads/contact-history.spec.js

@@ -5,6 +5,13 @@ const ID = '7d5c0f4e-8f60-4bff-b544-000000000001';
 const JOB_ID = '7d5c0f4e-8f60-4bff-b544-000000000002';
 const SUBJECT_ID = '7d5c0f4e-8f60-4bff-b544-000000000003';
 describe('candidate contact history contract', () => {
+    it('rejects an impossible NOT_LOOKING return date', () => {
+        expect(candidate_coordination_contract_1.ContactWorkerStateSchema.safeParse({
+            kind: 'NOT_LOOKING',
+            days: 30,
+            returnDate: '2026-02-31',
+        }).success).toBe(false);
+    });
     it('parses structured worker and job filters', () => {
         expect(candidate_coordination_contract_1.CandidateContactHistoryQuerySchema.parse({
             contactedById: ID,
@@ -62,6 +69,8 @@ describe('candidate contact history contract', () => {
                         },
                     },
                     channel: 'WHATSAPP',
+                    direction: 'OUTBOUND',
+                    durationSeconds: null,
                     contactedAt: '2026-07-17T09:00:00.000Z',
                     outcome: 'AWAITING_FEEDBACK',
                     feedbackAt: null,
@@ -85,5 +94,137 @@ describe('candidate contact history contract', () => {
         expect(candidate_coordination_contract_1.candidateCoordinationContract.contactHistory.method).toBe('GET');
         expect(candidate_coordination_contract_1.candidateCoordinationContract.recordWhatsAppFeedback.method).toBe('POST');
         expect(candidate_coordination_contract_1.candidateCoordinationContract.recordContactFeedback.path).toBe('/v2/candidate-contacts/:contactEventId/feedback');
+        expect(candidate_coordination_contract_1.CompletePhoneCallBodySchema.safeParse({
+            outcome: 'FAILED',
+            scope: 'THIS_JOB',
+            reason: 'DISTANCE',
+        }).success).toBe(false);
+        expect(candidate_coordination_contract_1.ContactConnectionResultSchema.safeParse('FAILED').success).toBe(false);
+    });
+    it('parses job-agnostic Dialpad history outcomes with call metadata', () => {
+        const baseItem = {
+            id: ID,
+            agentId: ID,
+            subjectKind: 'CURATED',
+            subjectId: SUBJECT_ID,
+            viewerWorkerId: null,
+            worker: {
+                firstName: 'Jamie',
+                lastName: 'Taylor',
+                postcode: null,
+            },
+            channel: 'PHONE',
+            contactedAt: '2026-08-21T09:00:00.000Z',
+            feedbackAt: null,
+            feedback: null,
+            canRecordFeedback: false,
+        };
+        expect(candidate_coordination_contract_1.CandidateContactHistoryItemSchema.parse({
+            ...baseItem,
+            job: null,
+            direction: 'INBOUND',
+            durationSeconds: 42,
+            outcome: 'CONNECTED',
+            connection: 'CONNECTED',
+        })).toMatchObject({ job: null, direction: 'INBOUND', outcome: 'CONNECTED' });
+        expect(candidate_coordination_contract_1.CandidateContactHistoryItemSchema.parse({
+            ...baseItem,
+            job: null,
+            direction: 'OUTBOUND',
+            durationSeconds: null,
+            outcome: 'FAILED',
+            connection: 'FAILED',
+        })).toMatchObject({ direction: 'OUTBOUND', outcome: 'FAILED' });
+    });
+    it.each(['PROCESSING', 'NEEDS_REVIEW', 'FEEDBACK_RECORDED'])('projects managed %s status without private artifacts', (managedFeedbackStatus) => {
+        const response = {
+            items: [
+                {
+                    id: ID,
+                    agentId: ID,
+                    subjectKind: 'CURATED',
+                    subjectId: SUBJECT_ID,
+                    viewerWorkerId: null,
+                    worker: {
+                        firstName: 'Jamie',
+                        lastName: 'Taylor',
+                        postcode: null,
+                    },
+                    job: {
+                        id: JOB_ID,
+                        tradeName: null,
+                        postcode: null,
+                        firstAgent: null,
+                    },
+                    channel: 'PHONE',
+                    direction: 'OUTBOUND',
+                    durationSeconds: null,
+                    contactedAt: '2026-08-19T12:00:00.000Z',
+                    outcome: 'AWAITING_FEEDBACK',
+                    feedbackAt: null,
+                    feedback: null,
+                    managedCallId: SUBJECT_ID,
+                    managedFeedbackStatus,
+                    canRecordFeedback: managedFeedbackStatus === 'NEEDS_REVIEW',
+                },
+            ],
+            total: 1,
+            hasMore: false,
+            totalPages: 1,
+        };
+        const parsed = candidate_coordination_contract_1.CandidateContactHistoryResponseSchema.parse(response);
+        expect(parsed.items[0]).toMatchObject({
+            managedCallId: SUBJECT_ID,
+            managedFeedbackStatus,
+        });
+        for (const privateExtra of [
+            { recordingUrl: 'https://private.example.test/recording' },
+            { transcript: 'private transcript' },
+            { analysis: { raw: true } },
+            { unknown: true },
+        ]) {
+            expect(candidate_coordination_contract_1.CandidateContactHistoryResponseSchema.safeParse({
+                ...response,
+                items: [{ ...response.items[0], ...privateExtra }],
+            }).success).toBe(false);
+        }
+        expect(candidate_coordination_contract_1.CandidateContactHistoryResponseSchema.safeParse({
+            ...response,
+            recordingUrl: 'https://private.example.test/recording',
+        }).success).toBe(false);
+    });
+    it('projects managed call presentation fields without relaxing item strictness', () => {
+        const item = {
+            id: ID,
+            agentId: ID,
+            subjectKind: 'CURATED',
+            subjectId: SUBJECT_ID,
+            viewerWorkerId: null,
+            worker: {
+                firstName: 'Jamie',
+                lastName: 'Taylor',
+                postcode: null,
+            },
+            job: {
+                id: JOB_ID,
+                tradeName: null,
+                postcode: null,
+                firstAgent: null,
+            },
+            channel: 'PHONE',
+            direction: 'OUTBOUND',
+            durationSeconds: null,
+            contactedAt: '2026-08-19T12:00:00.000Z',
+            outcome: 'AWAITING_FEEDBACK',
+            feedbackAt: null,
+            feedback: null,
+            managedCallStatus: 'NEEDS_REVIEW',
+            managedHasRecording: true,
+            managedCallSource: 'HISTORICAL_IMPORT',
+            canRecordFeedback: true,
+        };
+        expect(candidate_coordination_contract_1.CandidateContactHistoryItemSchema.safeParse(item).success).toBe(true);
+        expect(candidate_coordination_contract_1.CandidateContactHistoryItemSchema.safeParse({ ...item, unknown: true })
+            .success).toBe(false);
     });
 });

package/dist/curated-worker-leads/job-candidate-cards.spec.js

@@ -67,6 +67,25 @@ describe('JobCandidateCardSchema / OwnedCandidateCardSchema', () => {
         expect(parsed).not.toHaveProperty('email');
         expect(parsed).not.toHaveProperty('nino');
     });
+    it('keeps list ranking metadata out of the card hydration projection', () => {
+        const parsed = jobs_tab_contract_1.JobCandidateCardSchema.parse({
+            id: '7d5c0f4e-8f60-4bff-b544-111111111111',
+            firstName: 'Ana',
+            hasTools: true,
+            hasPpe: true,
+            offerOpenness: 'OPEN',
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            qualifications: [],
+            hasPhoneNumber: true,
+            ranking: {
+                score: 84,
+                rank: 1,
+                reservationOwnerId: '6f8e5c4d-3b2a-4190-8c7d-6e5f4a3b2c1d',
+            },
+        });
+        expect(parsed).not.toHaveProperty('ranking');
+    });
     it('strips sensitive keys nested inside curated candidate data', () => {
         const parsed = jobs_tab_contract_1.JobCandidateCardSchema.parse({
             id: '7d5c0f4e-8f60-4bff-b544-111111111111',

package/dist/curated-worker-leads/job-candidates.spec.js

@@ -36,6 +36,12 @@ describe('JobCandidates schemas', () => {
         qualifications: [],
         hasPhoneNumber: true,
     };
+    it('accepts only UUID candidate snapshot identities', () => {
+        const snapshotId = '00000000-0000-4000-8000-000000000001';
+        expect(jobs_tab_contract_1.jobsTabContract.candidates.query.parse({ page: 2, snapshotId })).toEqual({ page: 2, snapshotId });
+        expect(jobs_tab_contract_1.jobsTabContract.candidates.query.safeParse({ snapshotId: 'shared' })
+            .success).toBe(false);
+    });
     it('parses a full row', () => {
         expect(jobs_tab_contract_1.CandidateRowSchema.parse({
             ...row,
@@ -56,6 +62,163 @@ describe('JobCandidates schemas', () => {
             },
         });
     });
+    it('parses an optional complete call-priority ranking', () => {
+        const parsed = jobs_tab_contract_1.CandidateRowSchema.parse({
+            ...row,
+            ranking: {
+                score: 84,
+                rank: 1,
+                baseFit: 82,
+                continuityBoost: 14.3,
+                confidence: 'MEDIUM',
+                reasons: [
+                    { code: 'PRACTICAL_COMMUTE', routeMinutes: 14 },
+                    { code: 'QUALIFICATIONS_PARTIAL', matched: 2, required: 3 },
+                ],
+                modelVersion: 'candidate-call-priority-v2',
+                computedAt: '2026-08-23T09:00:00.000Z',
+                decisionEvidence: {
+                    proximity: {
+                        score: 0.72,
+                        routeMinutes: 14,
+                        maxTravelMinutes: 50,
+                        distanceKm: 5.2,
+                        driveMinutes: 22,
+                        transitMinutes: 48,
+                    },
+                    qualification: {
+                        score: 0.8,
+                        required: 3,
+                        matched: 2,
+                        explicit: true,
+                    },
+                    reliability: {
+                        score: 0.76,
+                        workerPositiveOutcomes: 6,
+                        workerMatureOutcomes: 7,
+                        tradePositiveOutcomes: 15,
+                        tradeMatureOutcomes: 20,
+                        globalPrior: 0.6,
+                    },
+                    readiness: {
+                        score: 1,
+                        state: 'CURRENT_OPEN',
+                        offerOpenness: 'OPEN',
+                        offerOpennessSetAt: '2026-08-22T09:00:00.000Z',
+                    },
+                    continuity: {
+                        boost: 14.3,
+                        outcome: 'CONNECTED',
+                        acquiredAt: '2026-08-22T08:00:00.000Z',
+                        expiresAt: '2026-08-24T08:00:00.000Z',
+                    },
+                    confidenceFlags: {
+                        qualificationsExplicit: true,
+                        matureReliability: true,
+                        readinessCurrent: true,
+                    },
+                },
+            },
+        });
+        expect(parsed.ranking).toEqual({
+            score: 84,
+            rank: 1,
+            baseFit: 82,
+            continuityBoost: 14.3,
+            confidence: 'MEDIUM',
+            reasons: [
+                { code: 'PRACTICAL_COMMUTE', routeMinutes: 14 },
+                { code: 'QUALIFICATIONS_PARTIAL', matched: 2, required: 3 },
+            ],
+            modelVersion: 'candidate-call-priority-v2',
+            computedAt: '2026-08-23T09:00:00.000Z',
+            decisionEvidence: {
+                proximity: {
+                    score: 0.72,
+                    routeMinutes: 14,
+                    maxTravelMinutes: 50,
+                    distanceKm: 5.2,
+                    driveMinutes: 22,
+                    transitMinutes: 48,
+                },
+                qualification: {
+                    score: 0.8,
+                    required: 3,
+                    matched: 2,
+                    explicit: true,
+                },
+                reliability: {
+                    score: 0.76,
+                    workerPositiveOutcomes: 6,
+                    workerMatureOutcomes: 7,
+                    tradePositiveOutcomes: 15,
+                    tradeMatureOutcomes: 20,
+                    globalPrior: 0.6,
+                },
+                readiness: {
+                    score: 1,
+                    state: 'CURRENT_OPEN',
+                    offerOpenness: 'OPEN',
+                    offerOpennessSetAt: '2026-08-22T09:00:00.000Z',
+                },
+                continuity: {
+                    boost: 14.3,
+                    outcome: 'CONNECTED',
+                    acquiredAt: '2026-08-22T08:00:00.000Z',
+                    expiresAt: '2026-08-24T08:00:00.000Z',
+                },
+                confidenceFlags: {
+                    qualificationsExplicit: true,
+                    matureReliability: true,
+                    readinessCurrent: true,
+                },
+            },
+        });
+    });
+    it('rejects half-populated candidate rankings', () => {
+        expect(jobs_tab_contract_1.CandidateRowSchema.safeParse({
+            ...row,
+            ranking: { score: 84, rank: 1 },
+        }).success).toBe(false);
+    });
+    it('rejects candidate rankings outside their score bounds', () => {
+        expect(jobs_tab_contract_1.CandidateRowSchema.safeParse({
+            ...row,
+            ranking: {
+                score: 101,
+                rank: 1,
+                baseFit: 82,
+                continuityBoost: 14.3,
+                confidence: 'MEDIUM',
+                reasons: [{ code: 'PRACTICAL_COMMUTE', routeMinutes: 14 }],
+                modelVersion: 'candidate-call-priority-v2',
+                computedAt: '2026-08-23T09:00:00.000Z',
+            },
+        }).success).toBe(false);
+    });
+    it('rejects unknown ranking confidence and mismatched reason payloads', () => {
+        const ranking = {
+            score: 84,
+            rank: 1,
+            baseFit: 82,
+            continuityBoost: 14.3,
+            confidence: 'MEDIUM',
+            reasons: [{ code: 'PRACTICAL_COMMUTE', routeMinutes: 14 }],
+            modelVersion: 'candidate-call-priority-v2',
+            computedAt: '2026-08-23T09:00:00.000Z',
+        };
+        expect(jobs_tab_contract_1.CandidateRowSchema.safeParse({
+            ...row,
+            ranking: { ...ranking, confidence: 'UNKNOWN' },
+        }).success).toBe(false);
+        expect(jobs_tab_contract_1.CandidateRowSchema.safeParse({
+            ...row,
+            ranking: {
+                ...ranking,
+                reasons: [{ code: 'PRACTICAL_COMMUTE', matched: 2, required: 3 }],
+            },
+        }).success).toBe(false);
+    });
     it('parses a never-contacted row (nullables)', () => {
         const parsed = jobs_tab_contract_1.CandidateRowSchema.parse({
             ...row,
@@ -81,8 +244,10 @@ describe('JobCandidates schemas', () => {
         const parsed = jobs_tab_contract_1.CandidateRowSchema.parse(row);
         expect(parsed.offerChannels).toBeUndefined();
         expect(parsed.offerContactedAt).toBeUndefined();
+        expect(parsed.ranking).toBeUndefined();
     });
     it('parses the response envelope', () => {
+        const snapshotId = '00000000-0000-4000-8000-000000000001';
         const parsed = jobs_tab_contract_1.JobCandidatesResponseSchema.parse({
             owned: [row],
             curated: [],
@@ -96,10 +261,24 @@ describe('JobCandidates schemas', () => {
             workersContactedByViewerCount: 0,
             workersContactedByOthersCount: 0,
             dismissed: [],
+            orderSnapshot: {
+                snapshotId,
+                mode: 'RANKED',
+                modelVersion: 'candidate-call-priority-v2',
+                computedAt: '2026-08-23T09:00:00.000Z',
+                rankedCandidateCount: 1,
+            },
         });
         expect(parsed.totalOwned).toBe(1);
         expect(parsed.page).toBe(1);
         expect(parsed.cards.own[0]?.id).toBe(row.subjectId);
+        expect(parsed).toMatchObject({
+            orderSnapshot: {
+                snapshotId,
+                mode: 'RANKED',
+                rankedCandidateCount: 1,
+            },
+        });
     });
     it('requires the atomic candidate card projection', () => {
         expect(() => jobs_tab_contract_1.JobCandidatesResponseSchema.parse({