ATS Integration Contracts

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