Hooks Reference

Custom hooks live in lib/hooks/ with domain-specific subdirectories. All hooks follow React conventions and use Apollo Client for GraphQL operations.

AI & Automation

Hook	File	Purpose
useAIAgent	useAIAgent.ts	Agent CRUD (create, update, enable/disable, delete) via AI service endpoint
useAIAgentChat	useAIAgentChat.ts	Streaming chat via WebSocket subscription (7 event types)
useAgentDocuments	useAgentDocuments.ts	RAG document upload, categorize, reprocess, priority
useTextRewrite	useTextRewrite.ts	AI-powered text rewriting for descriptions
useTextRewriteClient	useTextRewriteClient.ts	Client-side text rewriting utilities
useSkillCreation	useSkillCreation.ts	Create and manage skill definitions

CV Processing

Hook	File	Purpose
useCvUploadAndParse	useCvUploadAndParse.ts	Upload + parse orchestration (5-min timeout)
useCvExtractionGraphQL	useCvExtractionGraphQL.ts	Subscription-based extraction with real-time progress
useCvProcessorGraphQL	useCvProcessorGraphQL.ts	CV processing via GraphQL subscription
useCvManager	useCvManager.ts	CV lifecycle CRUD operations
useCvWithFaceExtraction	useCvWithFaceExtraction.ts	Combined CV + face photo extraction
useFaceExtraction	useFaceExtraction.ts	Profile photo extraction from documents
useStructuredCvMutations	useStructuredCvMutations.ts	Diff-based save orchestrator (parallel mutations)
useCreateCv	useCreateCv.ts	Create new CV from scratch or template

Payment & Billing

Hook	File	Purpose
useCheckout	useCheckout.ts	Stripe checkout flow (company vs personal routing)
useBillingError	useBillingError.ts	Error detection: INSUFFICIENT_CREDITS, PLAN_LIMIT_EXCEEDED, SUBSCRIPTION_INACTIVE
useCreditCheck	useCreditCheck.ts	Pre-operation balance validation
useCreditBalance	useCreditBalance.ts	Current credit balance (auto-routes company/personal)
useBillingConfig	useBillingConfig.ts	Billing configuration and pricing
useCreditPurchase	useCreditPurchase.ts	Credit pack purchase flow
useSubscriptionStatus	useSubscriptionStatus.ts	Subscription status and feature eligibility

Communication

Hook	File	Purpose
useMessaging	useMessaging.ts	Full messaging: send/edit/delete, conversations, real-time, search
useVoiceChat	useVoiceChat.ts	Nova Sonic voice (10 languages, recording, playback)

Job Processing

Hook	File	Purpose
useJobParsingSubscription	useJobParsingSubscription.ts	Job description parsing via subscription (title, skills, requirements)
useJobExtractionWebSocket	useJobExtractionWebSocket.ts	Legacy WebSocket-based job extraction
useJobs	useJobs.ts	Job listing and management
useJobStatistics	useJobStatistics.ts	Job analytics and stats

Candidate & Talent Management

Hook	File	Purpose
useAddCandidate	useAddCandidate.ts	Candidate addition with pipeline integration
useAddCandidateChannel	useAddCandidateChannel.ts	Add contact channel (email, phone)
useRemoveCandidate	useRemoveCandidate.ts	Remove candidate
useAttachToTalentPool	useAttachToTalentPool.ts	Attach candidate to talent pool
useApplyForJob	useApplyForJob.ts	Job application workflow
useWithdrawApplication	useWithdrawApplication.ts	Withdraw submitted application
useUserJobMatchScore	useUserJobMatchScore.ts	AI compatibility score (user vs job)
useJobCandidates	jobs/useJobCandidates.ts	Pipeline candidates with batch score fetching
useRecommendedTalents	jobs/useRecommendedTalents.ts	Recommended talents with batch scores, 70% filter, loading state
useRecommendedTalentsSafe	useRecommendedTalentsSafe.ts	Recommended talents with NaN-safe error handling
useTalentsInPool	useTalentsInPool.ts	List talents in a pool
useTalentPoolCollaborators	useTalentPoolCollaborators.ts	Manage pool collaborators

Candidate Subdirectory (lib/hooks/candidates/)

Hook	Purpose
useGetCandidates	Fetch candidates with filtering and pagination
useDeleteCandidate	Delete candidate
useUpdateCandidateStatus	Update pipeline status (shortlisted, rejected, hired)
useCompanyCandidatesOnly	Filter to current company's candidates

Company & Contact Management

Hook	File	Purpose
useCompanyBadgeCounts	useCompanyBadgeCounts.ts	Company dashboard badge counts
useBadgeCounts	useBadgeCounts.ts	Global badge count management
useCompanyContacts	useCompanyContacts.ts	Company contact management
useCompanyContactsData	useCompanyContactsData.ts	Contact data with aggregation
useCompanyCandidates	useCompanyCandidates.ts	Company candidate list
useCompanySharelists	useCompanySharelists.ts	Shareable lists management

Subdirectory Hooks

Directory	Hooks	Purpose
companies/	useCreateCompany	Company registration
contacts/	useContactTypes, useDeleteContact	Contact types and deletion
jobs/	useJobCandidates, useRecommendedTalents, useUpdateJob	Job-specific operations
talents/	useCompanyTalents	Company talent management
admin/	useLogStream	Live system log streaming

Score Utilities (lib/utils/score.ts)

Score normalization is centralized — never add local normalizeScore functions in pages or hooks.

Export	Returns	Purpose
normalizeScore(raw)	number	Clamp to 0-100, round. Returns 0 for null/NaN
normalizeScoreNullable(raw)	number | null	Same, but returns null for null/NaN (distinguishes "no score" from "0%")
averageScore(entries)	number	Average an array of { score } entries, skipping non-finite values

See Matching Engine — Frontend Score Handling for full details.

UI Utilities

Hook	File	Purpose
useAutoPageTitle	useAutoPageTitle.ts	Auto-update document title based on context
useCardHighlight	useCardHighlight.ts	Card focus and highlight management
useErrorHandler	useErrorHandler.ts	Centralized error handling with toast
useFileHandling	useFileHandling.ts	File upload, validation, processing
useLocalStorage	useLocalStorage.ts	localStorage wrapper with cross-tab sync
useUnreadMessageCount	useUnreadMessageCount.ts	Unread message count for badges