ATS Integration Contracts

interface ReferenceCompletedEventPayload {
  event_type: 'hr_reference_completed';
  timestamp: string; // ISO 8601
  organization_id: string; // UUID (required)
  reference_id: string; // UUID (required)
  candidate_id: string; // UUID (required)
  application_id: string; // UUID (required)
  referee_name: string; // (required)
  referee_email: string; // (required)
  referee_relationship: string; // e.g., 'supervisor', 'colleague', 'client'
  reference_rating: number | null; // 1-5 scale (nullable)
  reference_status: 'completed' | 'declined'; // (required)
  completed_at: string; // ISO 8601 (required)
  reference_token: string; // Secure token used for submission
}

interface BackgroundCheckCompletedEventPayload {
  event_type: 'hr_background_check_completed';
  timestamp: string; // ISO 8601
  organization_id: string; // UUID (required)
  background_check_id: string; // UUID (required)
  candidate_id: string; // UUID (required)
  application_id: string; // UUID (required)
  provider: string; // 'checkr' | 'goodhire' (required)
  provider_report_id: string; // External provider's report ID (required)
  background_check_status: 'cleared' | 'flagged' | 'cancelled'; // (required)
  result_summary: string | null; // High-level summary (nullable)
  completion_timestamp: string; // ISO 8601 (required)
  fcra_adverse_action_required: boolean; // FCRA flag (required)
  report_url: string | null; // Link to full report (nullable)
}

interface JobBoardApplicationReceivedEventPayload {
  event_type: 'hr_job_board_application_received';
  timestamp: string; // ISO 8601
  organization_id: string; // UUID (required)
  job_posting_id: string; // UUID - internal posting (required)
  source_board: 'indeed' | 'linkedin' | 'ziprecruiter' | 'other'; // (required)
  external_application_id: string; // Board's application ID (required)
  candidate_email: string; // (required)
  candidate_name: string; // (required)
  candidate_phone: string | null; // (nullable)
  resume_url: string | null; // Link to resume file (nullable)
  cover_letter_text: string | null; // (nullable)
  application_timestamp: string; // ISO 8601 (required)
  source_metadata: Record<string, any> | null; // Board-specific data (nullable)
}

interface CandidateHiredEventPayload {
  event_type: 'candidate_hired';
  timestamp: string; // ISO 8601
  organization_id: string; // UUID
  application_id: string; // UUID
  candidate_id: string; // UUID
  employee_id: string; // UUID - newly created employee
  position_id?: string; // UUID (optional)
  department_id?: string; // UUID (optional)
  site_id?: string | null; // UUID
  hire_date: string; // ISO date
  offer_id: string; // UUID
  hired_by?: string; // UUID - user who accepted offer
}

interface OfferAcceptedEvent {
  event_type: 'offer_accepted';
  timestamp: string; // ISO 8601
  payload: {
    organization_id: string; // UUID
    offer_id: string; // UUID
    candidate_id: string; // UUID
    application_id: string; // UUID
    position_id: string; // UUID
    department_id: string; // UUID
    site_id: string | null; // UUID
    salary_amount: number;
    employment_type: string;
    start_date: string; // ISO date
  };
}

interface InterviewScheduledEvent {
  event_type: 'interview_scheduled';
  timestamp: string; // ISO 8601
  payload: {
    organization_id: string; // UUID
    interview_id: string; // UUID
    application_id: string; // UUID
    candidate_id: string; // UUID
    interviewer_ids: string[]; // UUIDs
    interview_type: 'phone_screen' | 'video' | 'in_person' | 'panel';
    scheduled_at: string; // ISO 8601 datetime
    duration_minutes: number;
    location: string | null;
    video_link: string | null;
  };
}

interface ApplicationReceivedEvent {
  event_type: 'application_received';
  timestamp: string; // ISO 8601
  payload: {
    organization_id: string; // UUID
    application_id: string; // UUID
    candidate_id: string; // UUID
    job_posting_id: string; // UUID
    candidate_email: string;
    candidate_name: string;
    source: 'internal' | 'indeed' | 'linkedin' | 'referral' | 'other';
  };
}

interface CandidateByEmployeeResponse {
  candidate_id: string;
  candidate_name: string;
  application_history: {
    application_id: string;
    job_posting_id: string;
    position_title: string;
    applied_at: string;
    hired_at: string | null;
  }[];
}

interface PipelineMetricsResponse {
  total_open_positions: number;
  total_applications: number;
  applications_by_stage: {
    stage: string;
    count: number;
  }[];
  average_time_to_fill_days: number;
  hire_rate_percentage: number;
}

import { FormEmbed, useFormSubmission } from '@/platform/forms';

// Application form
<FormEmbed 
  formId="hr-ats-application-form"
  onSubmit={handleApplicationSubmit}
  context={{ job_posting_id, organization_id }}
/>

// Interview feedback form
<FormEmbed 
  formId="hr-ats-interview-feedback"
  onSubmit={handleFeedbackSubmit}
  context={{ interview_id, interviewer_id }}
/>

CREATE OR REPLACE FUNCTION hr_create_employee_from_offer(
  p_offer_id UUID
)
RETURNS UUID -- Returns new employee_id
LANGUAGE plpgsql
SECURITY DEFINER
SET search_path = public

CREATE OR REPLACE FUNCTION create_onboarding_from_template(
  _employee_id UUID,
  _template_id UUID,
  _start_date DATE,
  _created_by UUID
)
RETURNS UUID -- Returns new onboarding_instance_id

1. acceptOffer() mutation called
   ↓
2. hr_offers.offer_status updated to 'accepted'
   ↓
3. Database trigger creates hr_employees record (via hr_create_employee_from_offer)
   ↓
4. Frontend publishes hr_employee_hired event (publishCandidateHiredEvent)
   ↓
5. Frontend calls createOnboardingForHire()
   ↓
6. If auto_create_onboarding=true in hr_module_settings:
   - Fetches default_onboarding_template_id
   - Calls create_onboarding_from_template RPC
   - Creates hr_onboarding_instances + hr_onboarding_task_instances
   ↓
7. Query caches invalidated, UI updated