Claims Management & Submission — Integration

interface ClaimSubmittedPayload {
  event_name: 'claim_submitted';
  organization_id: string;           // UUID — tenant
  payload: {
    claim_id: string;                 // UUID — pm_claims.id
    claim_number: string;             // Generated claim number (e.g., "CLM-20260222-001")
    patient_id: string;               // UUID — pm_patients.id
    payer_id: string;                 // UUID — pm_payers.id
    claim_type: 'professional_837p' | 'institutional_837i';
    total_charge: number;             // Sum of line charges (USD cents)
    line_count: number;               // Count of pm_claim_lines for this claim
    submitted_by: string;             // UUID — auth.uid() of submitting user
  };
}

interface ClaimStatusChangedPayload {
  event_name: 'claim_status_changed';
  organization_id: string;           // UUID — tenant
  payload: {
    claim_id: string;                 // UUID — pm_claims.id
    claim_number: string;             // Claim number
    patient_id: string;               // UUID — pm_patients.id
    payer_id: string;                 // UUID — pm_payers.id
    previous_status: ClaimStatus;
    new_status: ClaimStatus;
    denial_codes?: DenialCode[];      // Present when new_status is 'denied'
    paid_amount?: number;             // Present when new_status is 'paid' (USD cents)
    changed_by: string;               // UUID — auth.uid()
  };
}

type ClaimStatus =
  | 'draft'
  | 'scrubbed'
  | 'submitted'
  | 'accepted'
  | 'rejected'
  | 'paid'
  | 'denied'
  | 'appealed'
  | 'adjusted';

interface DenialCode {
  carc: string;                       // Claim Adjustment Reason Code (e.g., "CO-45")
  rarc?: string;                      // Remittance Advice Remark Code
  group_code: 'CO' | 'PR' | 'OA' | 'PI'; // CARC group
  amount?: number;                    // Adjustment amount (USD cents)
}

draft → scrubbed
scrubbed → submitted | draft
submitted → accepted | rejected
accepted → paid | denied
rejected → draft
paid → adjusted
denied → appealed | draft
appealed → paid | denied
adjusted → (terminal)

SELECT id, organization_id, patient_id, provider_id, service_date,
       cpt_code, units, modifiers, place_of_service,
       diagnosis_codes, fee_schedule_id, amount
FROM pm_charges
WHERE organization_id = :org_id
  AND status = 'approved'
  AND claim_id IS NULL           -- not yet linked to a claim
  AND deleted_at IS NULL
ORDER BY service_date, patient_id;

SELECT c.id, c.claim_number, c.patient_id, c.payer_id, c.total_charge,
       c.status, c.paid_amount, c.adjustment_amount, c.patient_responsibility,
       cl.id AS line_id, cl.line_number, cl.cpt_code, cl.charge_amount,
       cl.paid_amount AS line_paid, cl.adjustment_amount AS line_adjustment
FROM pm_claims c
JOIN pm_claim_lines cl ON cl.claim_id = c.id AND cl.organization_id = c.organization_id
WHERE c.organization_id = :org_id
  AND c.status IN ('submitted', 'accepted')
  AND c.claim_number = :claim_number   -- matched from ERA/835
  AND c.deleted_at IS NULL;

interface ScrubResult {
  passed: boolean;                    // true if zero errors
  errors: ScrubError[];               // blocking — must fix before submission
  warnings: ScrubError[];             // advisory — can submit with warnings
}

interface ScrubError {
  code: string;                       // e.g., "MISSING_NPI", "EXPIRED_AUTH"
  field: string;                      // e.g., "billing_provider_npi"
  message: string;                    // Human-readable description
  line_number?: number;               // Specific claim line, if applicable
}