Janady13/missionmatch / frontend/src/lib/workflow.ts

1import { request, csrfForUpload } from './api' 2 3// THE RECRUITER'S DAILY SURFACES: search, saved searches, lists, bulk actions, who is working what, 4// candidate documents, correspondence, and duplicate merge. 5// 6// One domain module rather than seven, because a recruiter's screen touches most of them at once and seven 7// files of six lines each is filing rather than structure. 8 9export interface CandidateQuery { 10 text?: string 11 clearance_levels?: string[] 12 clearance_status?: string[] 13 skills?: string[] 14 location?: string 15 available?: boolean 16 remote?: boolean 17 relocatable?: boolean 18 min_years?: number 19 max_years?: number 20 owner_user_id?: string 21 unowned?: boolean 22 list_id?: string 23 exclude_list_id?: string 24 clearance_expiring_days?: number 25 access_postures?: string[] 26 limit?: number 27 offset?: number 28} 29 30// CandidateSearchRow mirrors the server's result row, which is a DELIBERATE SUBSET of the stored candidate 31// rather than the whole record. The server used to return the table row verbatim, which shipped the resume 32// embedding and the search index on every line of a two hundred row page, and shipped the email address 33// regardless of the organization's contact setting. 34export interface CandidateSearchRow { 35 id: string 36 full_name: string 37 headline?: string 38 clearance_level: string 39 clearance_poly?: string 40 clearance_status: string 41 years_experience: number 42 location?: string 43 remote: boolean 44 relocatable: boolean 45 available: boolean 46 source: string 47 owner_user_id?: string 48 email?: string 49 // contact_redacted distinguishes "hidden from you" from "never captured". Without it a missing email 50 // renders the same either way, and a recruiter goes looking for an address that was there all along. 51 contact_redacted?: boolean 52 // The break in access posture: whether this cleared person can still be reinstated on a new sponsor's 53 // paperwork, or has passed the twenty four month line and now needs an investigation. 54 access?: AccessIntel 55} 56 57// AccessIntel mirrors intelligence.AccessIntel. It is an INDICATOR derived from dates somebody entered, never 58// an eligibility determination: that belongs to the hiring client's facility security officer through DISS. 59export interface AccessIntel { 60 posture: 'in_access' | 'reinstatable' | 'closing' | 'investigation_likely' | 'unknown' 61 label: string 62 detail: string 63 months_out_of_access?: number 64 days_left_in_window?: number 65 adjudication_stale?: boolean 66} 67 68// The postures, with what each one means for a desk. unknown is deliberately worded as a gap in the RECORD 69// rather than a problem with the person, because most benches start there and a product that painted its 70// whole dataset as risky would be crying wolf. 71export const ACCESS_POSTURES: { value: string; label: string; hint: string }[] = [ 72 { value: 'in_access', label: 'In access', hint: 'currently sponsored, no clock running' }, 73 { value: 'reinstatable', label: 'Reinstatable', hint: 'inside the 24 month window' }, 74 { value: 'closing', label: 'Window closing', hint: '90 days or less left of the window' }, 75 { value: 'investigation_likely', label: 'Needs an investigation', hint: 'past the window, or a stale adjudication' }, 76 { value: 'unknown', label: 'Not known', hint: 'nobody has recorded their access history' }, 77] 78 79// The colour each posture wears. Unknown is MUTED, never a warning colour. 80export function accessColor(p: string): string { 81 if (p === 'in_access') return 'var(--color-ok)' 82 if (p === 'reinstatable') return 'var(--color-blue-soft)' 83 if (p === 'closing') return 'var(--color-warn)' 84 if (p === 'investigation_likely') return 'var(--color-risk)' 85 return 'var(--color-faint)' 86} 87 88export interface CandidateSearchResult<T> { 89 candidates: T[] 90 total: number 91 limit: number 92 offset: number 93 // scope_applied tells the screen that record scope narrowed this answer, so a short list can be EXPLAINED 94 // rather than read as an empty bench. Without it the interface would have to guess, and a recruiter who 95 // sees nothing assumes the system is broken. 96 scope_applied: boolean 97} 98 99export interface SavedSearch { 100 id: string 101 name: string 102 visibility: 'private' | 'shared' 103 pinned: boolean 104 owner_user_id: string 105 owner_name?: string 106 criteria: CandidateQuery 107 last_run_at?: string 108 created_at: string 109} 110 111export interface CandidateList { 112 id: string 113 name: string 114 description?: string 115 purpose: 'shortlist' | 'bench' | 'pipeline' | 'do_not_contact' | 'other' 116 visibility: 'private' | 'shared' 117 status: 'active' | 'archived' 118 owner_user_id?: string 119 owner_name?: string 120 members?: number 121 created_at?: string 122} 123 124export interface BulkResult { 125 requested: number 126 applied: number 127 skipped: number 128 note?: string 129} 130 131export interface WorkClaim { 132 id: string 133 entity_type: string 134 entity_id: string 135 user_id: string 136 user_name: string 137 activity: string 138 note: string 139 claimed_at: string 140 expires_at: string 141 mine: boolean 142} 143 144export interface WorkTouch { 145 user_id: string 146 user_name: string 147 last_seen_at: string 148 mine: boolean 149} 150 151export interface WorkActivity { 152 entity_type: string 153 entity_id: string 154 claim: WorkClaim | null 155 touches: WorkTouch[] 156 desk_owner_user_id?: string 157 desk_owner_name?: string 158 visible_to_you: boolean 159 claim_required: boolean 160} 161 162export interface CandidateDocument { 163 id: string 164 candidate_id: string 165 document_type: string 166 file_name: string 167 media_type: string 168 size_bytes: number 169 sha256: string 170 uploaded_by_name?: string 171 is_current: boolean 172 created_at: string 173} 174 175export interface Message { 176 id: string 177 candidate_id?: string 178 contact_id?: string 179 to_address: string 180 from_address: string 181 subject: string 182 body: string 183 status: 'queued' | 'sent' | 'failed' 184 error_text?: string 185 sent_by_name?: string 186 created_at: string 187 sent_at?: string 188} 189 190export interface MessageTemplate { 191 id: string 192 name: string 193 audience: 'candidate' | 'contact' 194 subject: string 195 body: string 196 status: 'active' | 'archived' 197} 198 199export interface DuplicatePair { 200 a_id: string 201 a_name: string 202 b_id: string 203 b_name: string 204 reason: string 205 strength: 'strong' | 'weak' 206} 207 208export interface MergeResult { 209 kept_id: string 210 merged_id: string 211 moved: Record<string, number> 212 dropped?: Record<string, number> 213 retained_on_the_merged_record?: string[] 214 note?: string 215} 216 217export const workflowApi = { 218 // ---- search ---- 219 search: <T>(q: CandidateQuery) => 220 request<CandidateSearchResult<T>>('/candidates/search', { 221 method: 'POST', 222 body: JSON.stringify(q), 223 }), 224 225 savedSearches: () => request<{ saved_searches: SavedSearch[]; count: number }>('/saved-searches'), 226 saveSearch: (name: string, criteria: CandidateQuery, visibility: 'private' | 'shared', pinned: boolean) => 227 request<{ id: string }>('/saved-searches', { 228 method: 'POST', 229 body: JSON.stringify({ name, criteria, visibility, pinned }), 230 }), 231 runSavedSearch: <T>(id: string, limit = 50, offset = 0) => 232 request<CandidateSearchResult<T>>( 233 `/saved-searches/${encodeURIComponent(id)}/run?limit=${limit}&offset=${offset}`, 234 { method: 'POST' }, 235 ), 236 deleteSavedSearch: (id: string) => 237 request<{ deleted: boolean }>(`/saved-searches/${encodeURIComponent(id)}`, { method: 'DELETE' }), 238 239 // ---- lists ---- 240 lists: () => request<{ lists: CandidateList[]; count: number }>('/candidate-lists'), 241 listsForCandidate: (id: string) => 242 request<{ lists: CandidateList[]; count: number }>(`/candidates/${encodeURIComponent(id)}/lists`), 243 createList: (name: string, purpose: string, description = '') => 244 request<{ id: string }>('/candidate-lists', { 245 method: 'POST', 246 body: JSON.stringify({ name, purpose, description }), 247 }), 248 addToList: (listId: string, candidate_ids: string[], note = '') => 249 request<BulkResult>(`/candidate-lists/${encodeURIComponent(listId)}/members`, { 250 method: 'POST', 251 body: JSON.stringify({ candidate_ids, note }), 252 }), 253 removeFromList: (listId: string, candidate_ids: string[]) => 254 request<BulkResult>(`/candidate-lists/${encodeURIComponent(listId)}/members`, { 255 method: 'DELETE', 256 body: JSON.stringify({ candidate_ids }), 257 }), 258 bulkAssignOwner: (candidate_ids: string[], owner_user_id: string | null) => 259 request<BulkResult>('/candidates/bulk/owner', { 260 method: 'POST', 261 body: JSON.stringify({ candidate_ids, owner_user_id }), 262 }), 263 264 // ---- who is working what ---- 265 workActivity: (type: string, id: string) => 266 request<WorkActivity>(`/work/${type}/${encodeURIComponent(id)}`), 267 // touch is the call a detail screen makes on open: it records the visit AND returns the activity, so a 268 // page load is one request rather than two. 269 touch: (type: string, id: string) => 270 request<WorkActivity>(`/work/${type}/${encodeURIComponent(id)}/touch`, { method: 'POST' }), 271 claim: (type: string, id: string, activity: string, note: string, steal = false) => 272 request<WorkActivity>(`/work/${type}/${encodeURIComponent(id)}/claim`, { 273 method: 'POST', 274 body: JSON.stringify({ activity, note, steal }), 275 }), 276 release: (type: string, id: string) => 277 request<WorkActivity>(`/work/${type}/${encodeURIComponent(id)}/claim`, { method: 'DELETE' }), 278 myClaims: () => request<{ claims: WorkClaim[]; count: number }>('/work/mine'), 279 280 // ---- candidate documents ---- 281 documents: (candidateId: string) => 282 request<{ documents: CandidateDocument[]; count: number }>( 283 `/candidates/${encodeURIComponent(candidateId)}/documents`, 284 ), 285 supersedeDocument: (docId: string) => 286 request<{ superseded: boolean }>(`/candidate-documents/${encodeURIComponent(docId)}/supersede`, { 287 method: 'POST', 288 }), 289 // The download is a browser navigation rather than a fetch, so the session cookie rides along and the 290 // Content-Disposition attachment header does its job. Fetching it into memory would defeat both. 291 documentURL: (docId: string) => `/api/candidate-documents/${encodeURIComponent(docId)}/content`, 292 293 // ---- correspondence ---- 294 templates: () => 295 request<{ templates: MessageTemplate[]; count: number; placeholders: string[] }>('/message-templates'), 296 createTemplate: (t: Omit<MessageTemplate, 'id' | 'status'>) => 297 request<{ id: string }>('/message-templates', { method: 'POST', body: JSON.stringify(t) }), 298 previewMessage: (v: { candidate_id?: string; contact_id?: string; template_id?: string; subject?: string; body?: string }) => 299 request<{ to_address: string; subject: string; body: string; sendable: boolean; note: string }>( 300 '/message-templates/preview', 301 { method: 'POST', body: JSON.stringify(v) }, 302 ), 303 sendMessage: (v: { candidate_id?: string; contact_id?: string; template_id?: string; subject?: string; body?: string; requisition_id?: string }) => 304 request<Message>('/messages', { method: 'POST', body: JSON.stringify(v) }), 305 candidateMessages: (id: string) => 306 request<{ messages: Message[]; count: number }>(`/candidates/${encodeURIComponent(id)}/messages`), 307 308 // ---- duplicates ---- 309 duplicates: () => 310 request<{ duplicates: DuplicatePair[]; count: number; note: string }>('/candidates/duplicates'), 311 merge: (keep_id: string, merge_id: string, reason: string) => 312 request<MergeResult>('/candidates/merge', { 313 method: 'POST', 314 body: JSON.stringify({ keep_id, merge_id, reason }), 315 }), 316} 317 318// uploadCandidateDocument uses XMLHttpRequest rather than fetch for the same reason the opportunity document 319// intake does: fetch has no upload progress event, and a recruiter attaching a scanned certification over a 320// hotel connection needs to see that something is happening. It still sends the double submit token, taken 321// from the one place that knows how the token is obtained. 322export async function uploadCandidateDocument( 323 candidateId: string, 324 file: File, 325 documentType: string, 326 onProgress?: (pct: number) => void, 327): Promise<CandidateDocument> { 328 const token = await csrfForUpload() 329 const form = new FormData() 330 form.append('document_type', documentType) 331 form.append('file', file) 332 return new Promise((resolve, reject) => { 333 const xhr = new XMLHttpRequest() 334 xhr.open('POST', `/api/candidates/${encodeURIComponent(candidateId)}/documents`) 335 xhr.setRequestHeader('X-CSRF-Token', token) 336 xhr.withCredentials = true 337 xhr.upload.onprogress = (e) => { 338 if (e.lengthComputable && onProgress) onProgress(Math.round((e.loaded / e.total) * 100)) 339 } 340 xhr.onload = () => { 341 let body: unknown 342 try { 343 body = JSON.parse(xhr.responseText) 344 } catch { 345 body = null 346 } 347 if (xhr.status >= 200 && xhr.status < 300) { 348 resolve(body as CandidateDocument) 349 return 350 } 351 // The server's own sentence is surfaced. "That file type is not accepted, send a PDF, Word document, 352 // RTF, text or image" is actionable; "upload failed" is not. 353 const msg = (body as { error?: string } | null)?.error ?? `upload failed (${xhr.status})` 354 reject(new Error(msg)) 355 } 356 xhr.onerror = () => reject(new Error('the upload could not reach the server')) 357 xhr.send(form) 358 }) 359} 360 361export const LIST_PURPOSES: { value: CandidateList['purpose']; label: string; hint: string }[] = [ 362 { value: 'shortlist', label: 'Shortlist', hint: 'people put forward for one thing' }, 363 { value: 'bench', label: 'Bench', hint: 'people available now' }, 364 { value: 'pipeline', label: 'Pipeline', hint: 'people being worked' }, 365 // Named separately because it is a compliance artefact, not a convenience. The interface treats it 366 // differently rather than trusting somebody to read the title. 367 { value: 'do_not_contact', label: 'Do not contact', hint: 'people who asked not to be approached' }, 368 { value: 'other', label: 'Other', hint: '' }, 369] 370 371export const CLAIM_ACTIVITIES = ['working', 'screening', 'submitting', 'interviewing', 'negotiating'] as const 372