@dakkitor/api-contracts 1.1.153 → 1.4.0

package/dist/curated-worker-leads/candidate-coordination.contract.js

@@ -0,0 +1,921 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CandidatePhoneCancellationReasonSchema = exports.CandidateContactHistoryResponseSchema = exports.CandidateContactHistoryQuerySchema = exports.CandidateContactHistoryItemSchema = exports.CandidateContactHistoryOutcomeSchema = exports.ContactCompletionResultSchema = exports.StaleContactJobConflictResponseSchema = exports.StaleContactJobConflictDetailsSchema = exports.ConfirmWhatsAppSentBodySchema = exports.AttachContactSessionJobsBodySchema = exports.AlternativeContactJobSchema = exports.ContactSessionSummarySchema = exports.ContactSessionJobSchema = exports.ContactJobSummarySchema = exports.ContactSessionStatusSchema = exports.CandidateContactChannelSchema = exports.ContactFeedbackDataSchema = exports.MultiJobContactCompletionSchema = exports.NonConnectedContactCompletionSchema = exports.FollowUpContactCompletionSchema = exports.ConnectedContactCompletionSchema = exports.ContactJobResultEntrySchema = exports.ContactJobPreviousContextSchema = exports.PreviousPhoneJobResultSchema = exports.ContactJobResultSchema = exports.ContactWorkerStateSchema = exports.ContactConnectionResultSchema = exports.CompletePhoneCallBodySchema = exports.DO_NOT_CONTACT_REASON_MAX_LENGTH = exports.DO_NOT_CONTACT_REASON_MIN_LENGTH = exports.NotInterestedReasonSchema = exports.PhoneCallOutcomeSchema = exports.CandidateCoordinationChangedSchema = exports.CandidateCoordinationChangedReasonSchema = exports.JobCandidatePresenceChangedSchema = exports.CandidateCoordinationStateSchema = exports.CandidateContactRestrictionSchema = exports.PhoneOwnershipSchema = exports.PhoneOwnershipOutcomeSchema = exports.CoordinationLeaseSchema = exports.CoordinationLeaseKindSchema = exports.CandidateCoordinationConflictErrorSchema = exports.EditLeaseHeartbeatBodySchema = exports.CandidateCoordinationConflictDetailsSchema = exports.CandidateCoordinationConflictKindSchema = exports.CoordinationUserSummarySchema = exports.CanonicalWorkerRefSchema = exports.CanonicalWorkerKindSchema = exports.CANDIDATE_COORDINATION_CHANGED_EVENT = exports.JOB_CANDIDATE_PRESENCE_CHANGED_EVENT = void 0;
+exports.candidateCoordinationContract = exports.CandidateCoordinationSnapshotSchema = exports.CandidatePresenceSnapshotSchema = exports.CancelPhoneCallResponseSchema = exports.PhoneCallOutcomeResponseSchema = exports.PhoneRevealResponseSchema = exports.ActivePhoneCallResponseSchema = exports.ActivePhoneCallSchema = exports.StartPhoneCallResponseSchema = exports.CandidateRefPathSchema = void 0;
+const zod_openapi_1 = require("@anatine/zod-openapi");
+const core_1 = require("@ts-rest/core");
+const zod_1 = require("zod");
+const error_schemas_1 = require("../common/error-schemas");
+const jobs_contract_1 = require("../jobs/jobs.contract");
+const common_schemas_1 = require("../common/common-schemas");
+(0, zod_openapi_1.extendZodWithOpenApi)(zod_1.z);
+const c = (0, core_1.initContract)();
+exports.JOB_CANDIDATE_PRESENCE_CHANGED_EVENT = 'job.candidate-presence.changed';
+exports.CANDIDATE_COORDINATION_CHANGED_EVENT = 'candidate.coordination.changed';
+exports.CanonicalWorkerKindSchema = zod_1.z.enum(['WORKER', 'CURATED_WORKER']);
+// Deliberately untitled: this shape is reused through optional/nullable
+// wrappers in HTTP and SSE payloads.
+exports.CanonicalWorkerRefSchema = zod_1.z.object({
+    kind: exports.CanonicalWorkerKindSchema,
+    id: zod_1.z.string().uuid(),
+});
+exports.CoordinationUserSummarySchema = zod_1.z.object({
+    id: zod_1.z.string().uuid(),
+    firstName: zod_1.z.string(),
+    lastName: zod_1.z.string().nullable(),
+});
+exports.CandidateCoordinationConflictKindSchema = zod_1.z.enum([
+    'EDIT_LEASE',
+    'PHONE_CALL',
+    'PHONE_OWNERSHIP',
+]);
+// Deliberately untitled because ErrorResponseSchema.details wraps this shape.
+exports.CandidateCoordinationConflictDetailsSchema = zod_1.z.object({
+    conflictKind: exports.CandidateCoordinationConflictKindSchema,
+    holder: exports.CoordinationUserSummarySchema,
+    expiresAt: zod_1.z.string().datetime(),
+    sameUser: zod_1.z.boolean().optional(),
+});
+exports.EditLeaseHeartbeatBodySchema = zod_1.z.object({
+    clientId: zod_1.z.string().uuid(),
+    takeover: zod_1.z.boolean().optional().default(false),
+});
+exports.CandidateCoordinationConflictErrorSchema = error_schemas_1.ErrorResponseSchema.extend({
+    code: zod_1.z.literal('CANDIDATE_COORDINATION_CONFLICT'),
+    details: exports.CandidateCoordinationConflictDetailsSchema,
+});
+exports.CoordinationLeaseKindSchema = zod_1.z.enum(['CALLING', 'EDITING']);
+exports.CoordinationLeaseSchema = zod_1.z.object({
+    id: zod_1.z.string().uuid(),
+    kind: exports.CoordinationLeaseKindSchema,
+    holder: exports.CoordinationUserSummarySchema,
+    startedAt: zod_1.z.string().datetime(),
+    expiresAt: zod_1.z.string().datetime(),
+});
+exports.PhoneOwnershipOutcomeSchema = zod_1.z.enum([
+    'CONNECTED',
+    'INTERESTED',
+    'NO_ANSWER',
+    'BUSY',
+]);
+exports.PhoneOwnershipSchema = zod_1.z.object({
+    id: zod_1.z.string().uuid(),
+    owner: exports.CoordinationUserSummarySchema,
+    sourceJobId: zod_1.z.string().uuid(),
+    outcome: exports.PhoneOwnershipOutcomeSchema,
+    acquiredAt: zod_1.z.string().datetime(),
+    expiresAt: zod_1.z.string().datetime(),
+    // Optional so rolling deploys stay compatible in BOTH directions: an older
+    // web treats the reservation as candidate-wide (locks, today's behaviour),
+    // and a newer web seeing `undefined` from an older API does the same. Both
+    // fail safe toward locking.
+    exclusivity: zod_1.z.enum(['GLOBAL', 'SOURCE_JOB']).optional(),
+    // Jobs a SOURCE_JOB reservation covers. Empty/absent for GLOBAL.
+    coveredJobIds: zod_1.z.array(zod_1.z.string().uuid()).optional(),
+});
+exports.CandidateContactRestrictionSchema = zod_1.z.object({
+    scope: zod_1.z.enum(['NOT_LOOKING', 'DO_NOT_CONTACT']),
+    until: zod_1.z.string().datetime().nullable(),
+    setBy: exports.CoordinationUserSummarySchema,
+});
+exports.CandidateCoordinationStateSchema = zod_1.z.object({
+    canonicalWorker: exports.CanonicalWorkerRefSchema,
+    callingClaim: exports.CoordinationLeaseSchema.nullable(),
+    editLease: exports.CoordinationLeaseSchema.nullable(),
+    phoneOwnership: exports.PhoneOwnershipSchema.nullable(),
+    // Present on the outcome event that removes a worker from the current
+    // candidate set. Optional keeps rolling deployments compatible with older
+    // API/web instances; a page refresh naturally removes the ineligible row.
+    contactRestriction: exports.CandidateContactRestrictionSchema.optional(),
+});
+exports.JobCandidatePresenceChangedSchema = zod_1.z.object({
+    jobId: zod_1.z.string().uuid(),
+    activeAgentCount: zod_1.z.number().int().min(0),
+});
+exports.CandidateCoordinationChangedReasonSchema = zod_1.z.enum([
+    'CALL_STARTED',
+    'OUTCOME',
+    'INVALID_NUMBER',
+    'EDIT',
+    'RELEASE',
+    'EXPIRY',
+    'ADMIN_OVERRIDE',
+]);
+exports.CandidateCoordinationChangedSchema = zod_1.z.object({
+    canonicalWorker: exports.CanonicalWorkerRefSchema,
+    sourceJobId: zod_1.z.string().uuid().optional(),
+    state: exports.CandidateCoordinationStateSchema,
+    reason: exports.CandidateCoordinationChangedReasonSchema,
+});
+exports.PhoneCallOutcomeSchema = zod_1.z.enum([
+    'INTERESTED',
+    'NO_ANSWER',
+    'BUSY',
+    'NOT_INTERESTED',
+    'INVALID_NUMBER',
+]);
+exports.NotInterestedReasonSchema = zod_1.z.enum([
+    'RATE',
+    'DISTANCE',
+    'TRANSPORT_COST',
+    'OTHER',
+]);
+const OptionalCallNoteSchema = zod_1.z.string().trim().max(500).nullable().optional();
+exports.DO_NOT_CONTACT_REASON_MIN_LENGTH = 20;
+exports.DO_NOT_CONTACT_REASON_MAX_LENGTH = 300;
+const InterestedPhoneCallCompletionSchema = zod_1.z
+    .object({
+    outcome: zod_1.z.literal('INTERESTED'),
+    jobSeeking: zod_1.z
+        .object({
+        offerOpenness: zod_1.z.enum(['ACTIVELY_LOOKING', 'OPEN']),
+        offerNote: OptionalCallNoteSchema,
+    })
+        .strict(),
+})
+    .strict();
+const SimplePhoneCallCompletionSchema = zod_1.z
+    .object({
+    outcome: zod_1.z.enum(['NO_ANSWER', 'BUSY', 'INVALID_NUMBER']),
+})
+    .strict();
+const JobSpecificNotInterestedCompletionSchema = zod_1.z
+    .object({
+    outcome: zod_1.z.literal('NOT_INTERESTED'),
+    scope: zod_1.z.literal('THIS_JOB'),
+    reason: exports.NotInterestedReasonSchema,
+    comment: zod_1.z.string().trim().max(500).optional(),
+})
+    .strict()
+    .superRefine((data, ctx) => {
+    if (data.reason === 'OTHER' && !data.comment?.trim()) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['comment'],
+            message: 'A comment is required when the reason is Other',
+        });
+    }
+});
+const TemporarilyNotLookingCompletionSchema = zod_1.z
+    .object({
+    outcome: zod_1.z.literal('NOT_INTERESTED'),
+    scope: zod_1.z.literal('NOT_LOOKING'),
+    doNotContactDays: zod_1.z.union([zod_1.z.literal(7), zod_1.z.literal(14), zod_1.z.literal(30)]),
+    offerNote: OptionalCallNoteSchema,
+})
+    .strict();
+const DoNotContactCompletionSchema = zod_1.z
+    .object({
+    outcome: zod_1.z.literal('NOT_INTERESTED'),
+    scope: zod_1.z.literal('DO_NOT_CONTACT'),
+    reason: zod_1.z
+        .string()
+        .trim()
+        .min(exports.DO_NOT_CONTACT_REASON_MIN_LENGTH, `Reason must be at least ${exports.DO_NOT_CONTACT_REASON_MIN_LENGTH} characters`)
+        .max(exports.DO_NOT_CONTACT_REASON_MAX_LENGTH, `Reason must be at most ${exports.DO_NOT_CONTACT_REASON_MAX_LENGTH} characters`),
+})
+    .strict();
+exports.CompletePhoneCallBodySchema = zod_1.z.union([
+    InterestedPhoneCallCompletionSchema,
+    SimplePhoneCallCompletionSchema,
+    JobSpecificNotInterestedCompletionSchema,
+    TemporarilyNotLookingCompletionSchema,
+    DoNotContactCompletionSchema,
+]);
+exports.ContactConnectionResultSchema = zod_1.z.enum([
+    'CONNECTED',
+    'NO_ANSWER',
+    'BUSY',
+    'INVALID_NUMBER',
+]);
+const ContactWorkerNoteSchema = zod_1.z
+    .string()
+    .trim()
+    .max(500)
+    .nullable()
+    .optional();
+exports.ContactWorkerStateSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('ACTIVELY_LOOKING'),
+        note: ContactWorkerNoteSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('OPEN_TO_OFFERS'),
+        note: ContactWorkerNoteSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('NOT_LOOKING'),
+        days: zod_1.z.union([zod_1.z.literal(7), zod_1.z.literal(14), zod_1.z.literal(30)]),
+        note: ContactWorkerNoteSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('DO_NOT_CONTACT'),
+        reason: zod_1.z
+            .string()
+            .trim()
+            .min(exports.DO_NOT_CONTACT_REASON_MIN_LENGTH)
+            .max(exports.DO_NOT_CONTACT_REASON_MAX_LENGTH),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('NOT_CONFIRMED'),
+        note: ContactWorkerNoteSchema,
+    })
+        .strict(),
+]);
+const ContactJobChannelSchema = zod_1.z.enum(['PHONE', 'WHATSAPP']);
+const ContactJobNoteSchema = zod_1.z.string().trim().max(500).optional();
+exports.ContactJobResultSchema = zod_1.z
+    .union([
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('OFFER_SENT'),
+        channel: ContactJobChannelSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('DISCUSSED'),
+        channel: ContactJobChannelSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('INTERESTED'),
+        channel: ContactJobChannelSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('NOT_INTERESTED'),
+        channel: ContactJobChannelSchema,
+        reason: exports.NotInterestedReasonSchema,
+        note: ContactJobNoteSchema,
+    })
+        .strict(),
+])
+    .superRefine((data, ctx) => {
+    if (data.kind === 'NOT_INTERESTED' &&
+        data.reason === 'OTHER' &&
+        !data.note?.trim()) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['note'],
+            message: 'A note is required when the reason is Other',
+        });
+    }
+});
+/** Read-only projection of an earlier completed phone response for one job.
+ *  Built from the existing result kinds rather than a new business enum, but
+ *  deliberately without the optional decline note: historical notes stay
+ *  confined to Contact History (design §5.2). The channel is the literal
+ *  PHONE so a WhatsApp-channel row can never render as "Your previous call". */
+exports.PreviousPhoneJobResultSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('INTERESTED'),
+        channel: zod_1.z.literal('PHONE'),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('DISCUSSED'),
+        channel: zod_1.z.literal('PHONE'),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('OFFER_SENT'),
+        channel: zod_1.z.literal('PHONE'),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('NOT_INTERESTED'),
+        channel: zod_1.z.literal('PHONE'),
+        reason: exports.NotInterestedReasonSchema,
+    })
+        .strict(),
+]);
+/** Two independent historical signals for one job on the active-call pivot:
+ *  the current viewer's own latest phone response, and the team's latest
+ *  WhatsApp outreach. A non-optional object with nullable members keeps
+ *  attached session jobs and unattached alternatives on one rendering shape. */
+exports.ContactJobPreviousContextSchema = zod_1.z
+    .object({
+    phone: zod_1.z
+        .object({
+        contactedAt: zod_1.z.string().datetime(),
+        result: exports.PreviousPhoneJobResultSchema,
+    })
+        .strict()
+        .nullable(),
+    whatsapp: zod_1.z
+        .object({
+        contactedAt: zod_1.z.string().datetime(),
+        agent: exports.CoordinationUserSummarySchema,
+    })
+        .strict()
+        .nullable(),
+})
+    .strict();
+exports.ContactJobResultEntrySchema = zod_1.z
+    .object({
+    jobId: zod_1.z.string().uuid(),
+    result: exports.ContactJobResultSchema.optional(),
+    offerSentViaWhatsApp: zod_1.z.literal(true).optional(),
+})
+    .strict()
+    .refine((entry) => entry.result || entry.offerSentViaWhatsApp, {
+    message: 'A worker response or WhatsApp offer is required',
+});
+const rejectDuplicateIds = (ids, ctx, path) => {
+    if (new Set(ids).size !== ids.length) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: [path],
+            message: 'Duplicate job IDs are not allowed',
+        });
+    }
+};
+exports.ConnectedContactCompletionSchema = zod_1.z
+    .object({
+    connection: zod_1.z.literal('CONNECTED'),
+    workerState: exports.ContactWorkerStateSchema,
+    jobs: zod_1.z.array(exports.ContactJobResultEntrySchema).max(20),
+})
+    .strict()
+    .superRefine((data, ctx) => rejectDuplicateIds(data.jobs.map((entry) => entry.jobId), ctx, 'jobs'));
+/** The only result a follow-up (didn't answer / can't talk) may record: the
+ *  agent sent the job by WhatsApp. A worker who never responded cannot have a
+ *  DISCUSSED/NOT_INTERESTED response (spec §3). */
+const FollowUpJobResultSchema = zod_1.z
+    .object({ kind: zod_1.z.literal('OFFER_SENT'), channel: zod_1.z.literal('WHATSAPP') })
+    .strict();
+exports.FollowUpContactCompletionSchema = zod_1.z
+    .object({
+    connection: zod_1.z.enum(['NO_ANSWER', 'BUSY']),
+    jobs: zod_1.z
+        .array(zod_1.z
+        .object({ jobId: zod_1.z.string().uuid(), result: FollowUpJobResultSchema })
+        .strict())
+        .max(20)
+        .optional(),
+})
+    .strict()
+    .superRefine((data, ctx) => {
+    if (data.jobs) {
+        rejectDuplicateIds(data.jobs.map((entry) => entry.jobId), ctx, 'jobs');
+    }
+});
+const InvalidNumberContactCompletionSchema = zod_1.z
+    .object({ connection: zod_1.z.literal('INVALID_NUMBER') })
+    .strict();
+/** Kept as an export for existing consumers; now a union of the two
+ *  non-connected shapes. */
+exports.NonConnectedContactCompletionSchema = zod_1.z.union([
+    exports.FollowUpContactCompletionSchema,
+    InvalidNumberContactCompletionSchema,
+]);
+exports.MultiJobContactCompletionSchema = zod_1.z.union([
+    exports.ConnectedContactCompletionSchema,
+    exports.FollowUpContactCompletionSchema,
+    InvalidNumberContactCompletionSchema,
+]);
+exports.ContactFeedbackDataSchema = zod_1.z.union([
+    exports.MultiJobContactCompletionSchema,
+    exports.CompletePhoneCallBodySchema,
+]);
+exports.CandidateContactChannelSchema = zod_1.z.enum(['PHONE', 'WHATSAPP']);
+exports.ContactSessionStatusSchema = zod_1.z.enum([
+    'ACTIVE',
+    'COMPLETED',
+    'CANCELLED',
+    'EXPIRED',
+]);
+exports.ContactJobSummarySchema = zod_1.z
+    .object({
+    id: zod_1.z.string().uuid(),
+    description: zod_1.z.string(),
+    tradeName: zod_1.z.string().nullable(),
+    postcode: zod_1.z.string().nullable(),
+    distanceKm: zod_1.z.number().nullable(),
+    driveMinutes: zod_1.z.number().nullable(),
+    transitMinutes: zod_1.z.number().nullable(),
+    pay: jobs_contract_1.PaySchema,
+    hours: zod_1.z.number().nullable(),
+    positionsAvailable: zod_1.z.number().int().min(0),
+    startDate: jobs_contract_1.JobStartDateSchema.nullable(),
+    previousContact: exports.ContactJobPreviousContextSchema,
+})
+    .strict();
+exports.ContactSessionJobSchema = zod_1.z
+    .object({
+    jobId: zod_1.z.string().uuid(),
+    subjectKind: zod_1.z.enum(['OWNED', 'CURATED']),
+    subjectId: zod_1.z.string().uuid(),
+    isPrimary: zod_1.z.boolean(),
+    attachedAt: zod_1.z.string().datetime(),
+    job: exports.ContactJobSummarySchema,
+})
+    .strict();
+exports.ContactSessionSummarySchema = zod_1.z
+    .object({
+    revealSessionId: zod_1.z.string().uuid(),
+    channel: exports.CandidateContactChannelSchema,
+    status: exports.ContactSessionStatusSchema,
+    candidate: zod_1.z
+        .object({
+        subjectKind: zod_1.z.enum(['OWNED', 'CURATED']),
+        subjectId: zod_1.z.string().uuid(),
+        canonicalWorker: exports.CanonicalWorkerRefSchema,
+        firstName: zod_1.z.string(),
+        lastName: zod_1.z.string().nullable(),
+    })
+        .strict(),
+    jobs: zod_1.z.array(exports.ContactSessionJobSchema).max(20),
+    startedAt: zod_1.z.string().datetime(),
+    expiresAt: zod_1.z.string().datetime(),
+})
+    .strict();
+exports.AlternativeContactJobSchema = zod_1.z
+    .object({
+    jobId: zod_1.z.string().uuid(),
+    subjectKind: zod_1.z.enum(['OWNED', 'CURATED']),
+    subjectId: zod_1.z.string().uuid(),
+    job: exports.ContactJobSummarySchema,
+})
+    .strict();
+const ContactMatchTupleSchema = zod_1.z
+    .object({
+    subjectKind: zod_1.z.enum(['OWNED', 'CURATED']),
+    subjectId: zod_1.z.string().uuid(),
+    jobId: zod_1.z.string().uuid(),
+})
+    .strict();
+const SelectedContactJobsSchema = zod_1.z
+    .array(ContactMatchTupleSchema)
+    .max(19)
+    .superRefine((jobs, ctx) => rejectDuplicateIds(jobs.map((entry) => entry.jobId), ctx, 'selectedJobs'));
+exports.AttachContactSessionJobsBodySchema = zod_1.z
+    .object({
+    jobs: zod_1.z.array(ContactMatchTupleSchema).min(1).max(20),
+})
+    .strict()
+    .superRefine((data, ctx) => rejectDuplicateIds(data.jobs.map((entry) => entry.jobId), ctx, 'jobs'));
+exports.ConfirmWhatsAppSentBodySchema = zod_1.z
+    .object({
+    jobIds: zod_1.z.array(zod_1.z.string().uuid()).min(1).max(20),
+    /**
+     * Jobs whose "already sent by X" history the agent was shown and chose to
+     * message anyway. The server waives its duplicate-outreach guard for
+     * exactly these, so a client can never widen the waiver past what it
+     * displayed — an id here that isn't in `jobIds` is a client bug, and is
+     * rejected rather than ignored.
+     */
+    allowDuplicateJobIds: zod_1.z.array(zod_1.z.string().uuid()).max(20).optional(),
+})
+    .strict()
+    .superRefine((data, ctx) => {
+    rejectDuplicateIds(data.jobIds, ctx, 'jobIds');
+    if (!data.allowDuplicateJobIds)
+        return;
+    rejectDuplicateIds(data.allowDuplicateJobIds, ctx, 'allowDuplicateJobIds');
+    const submitted = new Set(data.jobIds);
+    for (const jobId of data.allowDuplicateJobIds) {
+        if (submitted.has(jobId))
+            continue;
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['allowDuplicateJobIds'],
+            message: 'allowDuplicateJobIds must be a subset of jobIds',
+        });
+        return;
+    }
+});
+exports.StaleContactJobConflictDetailsSchema = zod_1.z
+    .object({
+    kind: zod_1.z.literal('STALE_CONTACT_JOB'),
+    jobId: zod_1.z.string().uuid(),
+    reason: zod_1.z.enum(['CLOSED', 'FULL', 'INELIGIBLE', 'SUPPRESSED', 'RESERVED']),
+})
+    .strict();
+exports.StaleContactJobConflictResponseSchema = error_schemas_1.ErrorResponseSchema.extend({
+    details: exports.StaleContactJobConflictDetailsSchema,
+});
+exports.ContactCompletionResultSchema = zod_1.z.object({
+    state: exports.CandidateCoordinationStateSchema,
+    affectedJobIds: zod_1.z.array(zod_1.z.string().uuid()),
+    contactRestriction: exports.CandidateContactRestrictionSchema.optional(),
+    /** WhatsApp completion only: submitted jobs skipped because they went stale
+     *  between marking and submission. The recorded jobs (affectedJobIds) still
+     *  committed and the session completed (design 2026-07-23 §8). */
+    staleJobIds: zod_1.z.array(zod_1.z.string().uuid()).optional(),
+});
+/**
+ * A normalized result shown in the current user's candidate-contact history.
+ * WhatsApp starts in AWAITING_FEEDBACK and can be updated later; phone calls
+ * already collect their result as part of the call workflow.
+ */
+exports.CandidateContactHistoryOutcomeSchema = zod_1.z.enum([
+    'AWAITING_FEEDBACK',
+    'INTERESTED',
+    'NO_ANSWER',
+    'BUSY',
+    'NOT_INTERESTED',
+    'INVALID_NUMBER',
+]);
+exports.CandidateContactHistoryItemSchema = zod_1.z.object({
+    id: zod_1.z.string().uuid(),
+    agentId: zod_1.z.string().uuid(),
+    agent: zod_1.z
+        .object({
+        id: zod_1.z.string().uuid(),
+        firstName: zod_1.z.string(),
+        lastName: zod_1.z.string().nullable(),
+    })
+        .optional(),
+    subjectKind: zod_1.z.enum(['OWNED', 'CURATED']),
+    subjectId: zod_1.z.string().uuid(),
+    worker: zod_1.z.object({
+        firstName: zod_1.z.string(),
+        lastName: zod_1.z.string().nullable(),
+        postcode: zod_1.z.string().nullable(),
+    }),
+    job: zod_1.z.object({
+        id: zod_1.z.string().uuid(),
+        tradeName: zod_1.z.string().nullable(),
+        postcode: zod_1.z.string().nullable(),
+        firstAgent: zod_1.z
+            .object({
+            id: zod_1.z.string().uuid(),
+            firstName: zod_1.z.string(),
+            lastName: zod_1.z.string().nullable(),
+        })
+            .nullable(),
+    }),
+    channel: exports.CandidateContactChannelSchema,
+    contactedAt: zod_1.z.string().datetime(),
+    outcome: exports.CandidateContactHistoryOutcomeSchema,
+    feedbackAt: zod_1.z.string().datetime().nullable(),
+    feedback: exports.ContactFeedbackDataSchema.nullable(),
+    contactSessionId: zod_1.z.string().uuid().nullable().optional(),
+    connection: exports.ContactConnectionResultSchema.optional(),
+    workerState: exports.ContactWorkerStateSchema.nullable().optional(),
+    jobResult: exports.ContactJobResultSchema.nullable().optional(),
+    canRecordFeedback: zod_1.z.boolean(),
+});
+exports.CandidateContactHistoryQuerySchema = zod_1.z.object({
+    page: zod_1.z.coerce.number().int().min(1).optional(),
+    limit: zod_1.z.coerce.number().int().min(1).max(50).optional(),
+    contactedById: zod_1.z.string().uuid().optional(),
+    status: zod_1.z.enum(['ALL', 'PENDING', 'COMPLETED']).optional(),
+    channel: exports.CandidateContactChannelSchema.optional(),
+    worker: zod_1.z
+        .object({
+        name: common_schemas_1.NameFilterSchema.optional(),
+        phone: zod_1.z.string().trim().max(30).optional(),
+        postcode: zod_1.z.string().trim().max(16).optional(),
+    })
+        .optional(),
+    job: zod_1.z
+        .object({
+        location: common_schemas_1.LocationFilterSchema.optional(),
+        tradeId: zod_1.z.string().uuid().optional(),
+        userId: zod_1.z.string().uuid().optional(),
+    })
+        .optional(),
+});
+exports.CandidateContactHistoryResponseSchema = zod_1.z.object({
+    items: zod_1.z.array(exports.CandidateContactHistoryItemSchema),
+    total: zod_1.z.number().int().min(0),
+    hasMore: zod_1.z.boolean(),
+    totalPages: zod_1.z.number().int().min(0),
+});
+exports.CandidatePhoneCancellationReasonSchema = zod_1.z.enum([
+    'ACCIDENTAL_REVEAL',
+    'INTERRUPTED',
+    'WRONG_CANDIDATE_OR_JOB',
+    'TECHNICAL_PROBLEM',
+]);
+exports.CandidateRefPathSchema = zod_1.z.object({
+    jobId: zod_1.z.string().uuid(),
+    subjectKind: zod_1.z.enum(['OWNED', 'CURATED']),
+    subjectId: zod_1.z.string().uuid(),
+});
+exports.StartPhoneCallResponseSchema = zod_1.z.object({
+    callSessionId: zod_1.z.string().uuid(),
+    outcomeAvailableAt: zod_1.z.record(exports.PhoneCallOutcomeSchema, zod_1.z.string().datetime()),
+    state: exports.CandidateCoordinationStateSchema,
+});
+exports.ActivePhoneCallSchema = zod_1.z.object({
+    callSessionId: zod_1.z.string().uuid(),
+    revealSessionId: zod_1.z.string().uuid(),
+    startedAt: zod_1.z.string().datetime(),
+    expiresAt: zod_1.z.string().datetime(),
+    outcomeAvailableAt: zod_1.z.record(exports.PhoneCallOutcomeSchema, zod_1.z.string().datetime()),
+    candidate: zod_1.z.object({
+        subjectKind: zod_1.z.enum(['OWNED', 'CURATED']),
+        subjectId: zod_1.z.string().uuid(),
+        canonicalWorker: exports.CanonicalWorkerRefSchema,
+        firstName: zod_1.z.string(),
+        lastName: zod_1.z.string().nullable(),
+    }),
+    job: zod_1.z.object({
+        id: zod_1.z.string().uuid(),
+        description: zod_1.z.string(),
+        tradeName: zod_1.z.string().nullable(),
+        postcode: zod_1.z.string().nullable(),
+    }),
+    phoneNumber: common_schemas_1.PhoneNumberResponseSchema,
+});
+exports.ActivePhoneCallResponseSchema = zod_1.z.object({
+    call: exports.ActivePhoneCallSchema.nullable(),
+});
+exports.PhoneRevealResponseSchema = zod_1.z.object({
+    revealSessionId: zod_1.z.string().uuid(),
+    expiresAt: zod_1.z.string().datetime(),
+    channel: exports.CandidateContactChannelSchema,
+    phoneNumbers: zod_1.z.array(common_schemas_1.PhoneNumberResponseSchema),
+    call: exports.StartPhoneCallResponseSchema.nullable(),
+    quota: zod_1.z.object({
+        remaining: zod_1.z.number().int().min(0),
+        resetsAt: zod_1.z.string().datetime(),
+    }),
+});
+exports.PhoneCallOutcomeResponseSchema = zod_1.z.object({
+    state: exports.CandidateCoordinationStateSchema,
+});
+exports.CancelPhoneCallResponseSchema = zod_1.z.object({
+    state: exports.CandidateCoordinationStateSchema,
+    cancellation: zod_1.z.object({
+        count30Minutes: zod_1.z.number().int().min(0),
+        cooldownUntil: zod_1.z.string().datetime().nullable(),
+    }),
+});
+exports.CandidatePresenceSnapshotSchema = zod_1.z.object({
+    jobs: zod_1.z.array(exports.JobCandidatePresenceChangedSchema),
+});
+exports.CandidateCoordinationSnapshotSchema = zod_1.z.object({
+    candidates: zod_1.z.array(exports.CandidateCoordinationStateSchema),
+});
+exports.candidateCoordinationContract = c.router({
+    heartbeatPresence: {
+        method: 'PUT',
+        path: '/jobs/:jobId/candidate-presence',
+        pathParams: zod_1.z.object({ jobId: zod_1.z.string().uuid() }),
+        body: zod_1.z.object({ clientId: zod_1.z.string().uuid() }),
+        responses: {
+            200: exports.JobCandidatePresenceChangedSchema,
+            403: error_schemas_1.ErrorResponseSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Enter or renew focused presence on a job candidates page',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    leavePresence: {
+        method: 'DELETE',
+        path: '/jobs/:jobId/candidate-presence',
+        pathParams: zod_1.z.object({ jobId: zod_1.z.string().uuid() }),
+        body: zod_1.z.object({ clientId: zod_1.z.string().uuid() }),
+        responses: { 200: exports.JobCandidatePresenceChangedSchema },
+        summary: 'Leave a job candidates page presence set',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    presenceSnapshot: {
+        method: 'GET',
+        // Keep the literal route deeper than /v2/jobs/:id so Express cannot
+        // interpret "candidate-presence" as the UUID job id.
+        path: '/jobs/candidate-presence/snapshot',
+        query: zod_1.z.object({ jobIds: zod_1.z.string().min(1) }),
+        responses: { 200: exports.CandidatePresenceSnapshotSchema },
+        summary: 'Batch current candidate-page presence for jobs',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    coordinationSnapshot: {
+        method: 'GET',
+        path: '/jobs/:jobId/candidate-coordination',
+        pathParams: zod_1.z.object({ jobId: zod_1.z.string().uuid() }),
+        query: zod_1.z.object({
+            ownedIds: zod_1.z.string().optional(),
+            curatedIds: zod_1.z.string().optional(),
+        }),
+        responses: { 200: exports.CandidateCoordinationSnapshotSchema },
+        summary: 'Current calling/edit/ownership state for a job candidate page',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    heartbeatEditLease: {
+        method: 'PUT',
+        path: '/candidate-coordination/:kind/:id/edit-lease',
+        pathParams: zod_1.z.object({
+            kind: exports.CanonicalWorkerKindSchema,
+            id: zod_1.z.string().uuid(),
+        }),
+        body: exports.EditLeaseHeartbeatBodySchema,
+        responses: {
+            200: exports.CandidateCoordinationStateSchema,
+            403: error_schemas_1.ErrorResponseSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+            409: exports.CandidateCoordinationConflictErrorSchema,
+        },
+        summary: 'Acquire or renew a worker editing lease',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    releaseEditLease: {
+        method: 'DELETE',
+        path: '/candidate-coordination/:kind/:id/edit-lease',
+        pathParams: zod_1.z.object({
+            kind: exports.CanonicalWorkerKindSchema,
+            id: zod_1.z.string().uuid(),
+        }),
+        body: zod_1.z.object({ clientId: zod_1.z.string().uuid() }),
+        responses: { 200: exports.CandidateCoordinationStateSchema },
+        summary: 'Release a worker editing lease',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    revealPhone: {
+        method: 'POST',
+        path: '/jobs/:jobId/candidates/:subjectKind/:subjectId/phone-reveal',
+        pathParams: exports.CandidateRefPathSchema,
+        body: zod_1.z
+            .object({
+            channel: exports.CandidateContactChannelSchema,
+            selectedJobs: SelectedContactJobsSchema.optional(),
+            /**
+             * Set when the agent was shown this job's existing WhatsApp outreach
+             * and chose to message again. Only waives the early reveal-time
+             * warning; every job still clears the authoritative duplicate check
+             * at confirm time via `allowDuplicateJobIds`.
+             */
+            allowDuplicateWhatsApp: zod_1.z.boolean().optional(),
+        })
+            .strict(),
+        responses: {
+            200: exports.PhoneRevealResponseSchema,
+            403: error_schemas_1.ErrorResponseSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+            409: error_schemas_1.ErrorResponseSchema,
+            429: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Declare contact intent, then reveal candidate phone numbers',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    activeContactSession: {
+        method: 'GET',
+        path: '/contact-sessions/active',
+        responses: {
+            200: zod_1.z.object({ session: exports.ContactSessionSummarySchema.nullable() }),
+            403: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Recover the current user active contact session',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    contactSessionAlternatives: {
+        method: 'GET',
+        path: '/contact-sessions/:revealSessionId/alternatives',
+        pathParams: zod_1.z.object({ revealSessionId: zod_1.z.string().uuid() }),
+        responses: {
+            200: zod_1.z.array(exports.AlternativeContactJobSchema),
+            403: error_schemas_1.ErrorResponseSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+            409: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'List ranked redacted alternatives for a contact session',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    attachContactSessionJobs: {
+        method: 'POST',
+        path: '/contact-sessions/:revealSessionId/jobs',
+        pathParams: zod_1.z.object({ revealSessionId: zod_1.z.string().uuid() }),
+        body: exports.AttachContactSessionJobsBodySchema,
+        responses: {
+            200: exports.ContactSessionSummarySchema,
+            403: error_schemas_1.ErrorResponseSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+            409: zod_1.z.union([
+                exports.StaleContactJobConflictResponseSchema,
+                error_schemas_1.ErrorResponseSchema,
+            ]),
+        },
+        summary: 'Attach revalidated discussed jobs to a contact session',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    confirmWhatsAppSent: {
+        method: 'POST',
+        path: '/contact-sessions/:revealSessionId/whatsapp-sent',
+        pathParams: zod_1.z.object({ revealSessionId: zod_1.z.string().uuid() }),
+        body: exports.ConfirmWhatsAppSentBodySchema,
+        responses: {
+            200: exports.ContactCompletionResultSchema,
+            403: error_schemas_1.ErrorResponseSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+            409: zod_1.z.union([
+                exports.StaleContactJobConflictResponseSchema,
+                error_schemas_1.ErrorResponseSchema,
+            ]),
+        },
+        summary: 'Confirm WhatsApp delivery for attached contact-session jobs',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    activePhoneCall: {
+        method: 'GET',
+        path: '/candidate-phone-calls/active',
+        responses: { 200: exports.ActivePhoneCallResponseSchema },
+        summary: 'Recover the current user active phone call and its context',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    contactHistory: {
+        method: 'GET',
+        path: '/candidate-contacts/history',
+        query: exports.CandidateContactHistoryQuerySchema,
+        responses: { 200: exports.CandidateContactHistoryResponseSchema },
+        summary: 'Ability-scoped job-candidate contact history, including delayed WhatsApp feedback',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    recordWhatsAppFeedback: {
+        method: 'POST',
+        path: '/candidate-contacts/:contactEventId/whatsapp-feedback',
+        pathParams: zod_1.z.object({ contactEventId: zod_1.z.string().uuid() }),
+        body: exports.CompletePhoneCallBodySchema,
+        responses: {
+            200: exports.CandidateContactHistoryItemSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+            409: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Record or update feedback received after a WhatsApp contact',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    recordContactFeedback: {
+        method: 'POST',
+        path: '/candidate-contacts/:contactEventId/feedback',
+        pathParams: zod_1.z.object({ contactEventId: zod_1.z.string().uuid() }),
+        body: exports.CompletePhoneCallBodySchema,
+        responses: {
+            200: exports.CandidateContactHistoryItemSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+            409: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Record or revise feedback for a phone or WhatsApp contact',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    completePhoneCall: {
+        method: 'POST',
+        path: '/candidate-phone-calls/:callSessionId/outcome',
+        pathParams: zod_1.z.object({ callSessionId: zod_1.z.string().uuid() }),
+        body: exports.ContactFeedbackDataSchema,
+        responses: {
+            200: exports.ContactCompletionResultSchema,
+            403: error_schemas_1.ErrorResponseSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+            409: zod_1.z.union([
+                exports.StaleContactJobConflictResponseSchema,
+                error_schemas_1.ErrorResponseSchema,
+            ]),
+        },
+        summary: 'Record a call outcome and transition ownership',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    cancelPhoneCall: {
+        method: 'DELETE',
+        path: '/candidate-phone-calls/:callSessionId',
+        pathParams: zod_1.z.object({ callSessionId: zod_1.z.string().uuid() }),
+        body: zod_1.z
+            .object({ reason: exports.CandidatePhoneCancellationReasonSchema })
+            .strict(),
+        responses: { 200: exports.CancelPhoneCallResponseSchema },
+        summary: 'Cancel, audit, and release a short calling claim',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+    markPhoneInvalid: {
+        method: 'POST',
+        path: '/candidate-phone-reveals/:revealSessionId/numbers/:phoneNumberId/invalid',
+        pathParams: zod_1.z.object({
+            revealSessionId: zod_1.z.string().uuid(),
+            phoneNumberId: zod_1.z.string().uuid(),
+        }),
+        body: zod_1.z.object({}).strict(),
+        responses: {
+            200: exports.PhoneCallOutcomeResponseSchema,
+            403: error_schemas_1.ErrorResponseSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+            409: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Report one revealed phone number invalid and release ownership',
+        metadata: { tags: ['Candidate Coordination'] },
+    },
+}, {
+    pathPrefix: '/v2',
+    commonResponses: {
+        400: error_schemas_1.ErrorResponseSchema,
+        401: error_schemas_1.ErrorResponseSchema,
+        500: error_schemas_1.ErrorResponseSchema,
+    },
+});