API Contracts

// @/platform/clinical
export async function getResidentialEpisodeContext(params: {
  organizationId: string;
  episodeId: string;
}): Promise<{
  status: 'pending' | 'clinically_active' | 'discharged' | 'cancelled';
  locValue: string | null;        // null when CL-11 SUD consent absent/revoked (redacted, not omitted)
  assessmentCompleted: boolean;
  assessmentDueDate: string;
  initialPlanDueDate: string;
} | null>;                        // null only if the episode is inaccessible/not found

interface LmsAdapter {
  vendor: 'relias' | 'healthstream' | 'cornerstone' | 'adp_learning' | 'workday_learning';
  pullCompletions(orgId: string, since: Date): Promise<ExternalCompletion[]>;
  pushEnrollment(orgId: string, e: EnrollmentInput): Promise<{ external_id: string }>;
}

interface ExternalCompletion {
  external_completion_id: string;
  external_user_id: string;       // resolved to hr_employees.id via integration mapping
  external_course_id: string;     // resolved to gr_training_courses.id via integration mapping
  completed_at: string;
  ceu_credits?: number;
  raw: unknown;                    // vendor payload, audit copy
}

interface JurisdictionProfile {
  profile_id: string;           // UUID of effective profile
  state_code: string;           // e.g., "AZ", "CA", "US"
  program_code: string;         // e.g., "az-ahcccs", "ca-medi-cal", "us-federal-baseline"
  display_name: string;         // e.g., "Arizona AHCCCS"
  clinical: ClinicalRules;      // Merged clinical rule pack
  billing: BillingRules;        // Merged billing rule pack
  compliance: ComplianceRules;  // Merged compliance rule pack
}

import { useJurisdictionProfile } from '@/platform/jurisdiction';

const { data: profile, isLoading, error } = useJurisdictionProfile(siteId?);
// Accesses: profile?.clinical, profile?.billing, profile?.compliance

import { getJurisdictionProfile } from '../_shared/jurisdiction.ts';

const profile = await getJurisdictionProfile(supabaseClient, orgId, siteId?);

{
  organization_id: uuid;
  connection_id: uuid;
  capabilities?: ('directory' | 'gmail' | 'calendar' | 'drive' | 'chat' | 'licensing' | 'reports')[];
}

{
  success: boolean;
  connection_id: uuid;
  tested_capabilities: {
    capability: string;
    status: 'ok' | 'failed';
    error_code?: string;
  }[];
  correlation_id: string;
}

{
  organization_id: uuid;
  connection_id: uuid;
  sync_mode: 'full' | 'incremental';
}

{
  sync_id: uuid;
  users_synced: number;
  groups_synced: number;
  org_units_synced: number;
  errors: number;
  correlation_id: string;
}

{
  organization_id: uuid;
  employee_id: uuid;
  profile_id?: uuid;
  department_id?: uuid;
  position_id?: uuid;
  correlation_id: string;
}

{
  success: boolean;
  google_user_id?: string;
  link_id?: uuid;
  error?: string;
  correlation_id: string;
}

{
  organization_id: uuid;
  employee_id: uuid;
  termination_date: timestamp;
  correlation_id: string;
}

{
  success: boolean;
  user_suspended: boolean;
  licenses_revoked: number;
  groups_removed: number;
  drive_transfer_queued: boolean;
  correlation_id: string;
}

{
  organization_id: uuid;
  from: string;
  to: string[];
  cc?: string[];
  bcc?: string[];
  subject: string;
  body_html: string;
  body_text?: string;
  attachments?: { filename: string; content: string; mime_type: string }[];
  correlation_id?: string;
}

{
  success: boolean;
  message_id?: string;
  error?: string;
  correlation_id: string;
}

{
  organization_id: uuid;
  action: 'create' | 'update' | 'delete' | 'query_freebusy';
  event_data?: {
    summary: string;
    start: timestamp;
    end: timestamp;
    attendees?: string[];
    description?: string;
    create_meet?: boolean;
  };
  freebusy_query?: {
    calendar_ids: string[];
    time_min: timestamp;
    time_max: timestamp;
  };
  correlation_id?: string;
}

{
  success: boolean;
  event_id?: string;
  meet_link?: string;
  freebusy?: Record<string, { busy: { start: timestamp; end: timestamp }[] }>;
  error?: string;
  correlation_id: string;
}

{
  organization_id: uuid;
  connection_id: uuid;
  action: 'sync_metadata' | 'create_folder' | 'share_resource';
  resource_data?: {
    name?: string;
    parent_id?: string;
    permissions?: { email: string; role: string }[];
  };
  correlation_id?: string;
}

{
  success: boolean;
  resource_id?: string;
  resources_synced?: number;
  error?: string;
  correlation_id: string;
}

{
  organization_id: uuid;
  connection_id: uuid;
  report_types?: ('admin' | 'login' | 'drive' | 'calendar')[];
  start_time?: timestamp;
  end_time?: timestamp;
}

{
  success: boolean;
  reports_ingested: number;
  events_processed: number;
  correlation_id: string;
}

{
  organization_id: uuid;
  connection_id: uuid;
  space_id: string;
  message: {
    text: string;
    cards?: unknown[];
  };
  correlation_id?: string;
}

{
  success: boolean;
  message_id?: string;
  error?: string;
  correlation_id: string;
}

{
  organizations_processed: number;
  alerts_sent: number;
  errors: number;
}

{
  claim_id: string;              // UUID — pm_claims.id
  claim_lines: Array<{
    line_number: number;
    date_of_service: string;     // ISO 8601 date
    units: number;
    service_type: string;        // e.g., 'residential', 'php', 'iop'
  }>;
  organization_id: string;       // UUID — tenant context
}

{
  valid: boolean;                // Overall validation result
  results: Array<{
    line_number: number;
    status: 'pass' | 'fail';
    reason?: string;             // e.g., 'no_active_auth', 'units_exceeded', 'date_outside_auth'
    authorization_id?: string;   // UUID of matching auth (if found)
  }>;
}

{
  error: {
    code: string;           // Canonical error code
    message: string;        // User-friendly error message
    details?: any;          // Optional additional context
  }
}

{
  "presenting_problem": true,
  "history_of_present_illness": true,
  "medical_history": false,
  "mental_health_history": true,
  "substance_use_history": true,
  "social_history": false,
  "preliminary_diagnoses": true,
  "sdoh_screening_completed": true
}

GET /api/v1/fa/episode-balance?episode_id={episode_id}&as_of_date={date}
Authorization: Bearer {jwt_token}

{
  episode_id: uuid;
  organization_id: uuid;
  site_id?: uuid;
  current_balance: number;              // Balance as of as_of_date
  past_due_balance: number;              // Amount past due (>30 days)
  last_payment_date?: date;             // Most recent payment date
  last_payment_amount?: number;         // Most recent payment amount
  payment_status: 'current' | 'past_due' | 'paid_in_full' | 'delinquent';
  total_charged: number;                 // Total charges for episode
  total_paid: number;                    // Total payments received
  account_status: 'active' | 'closed' | 'on_hold';
  payment_history: [{
    payment_id: uuid;
    payment_date: date;
    amount: number;
    method: 'check' | 'ach' | 'card' | 'cash' | 'other';
    reference_number?: string;
  }];
  next_payment_due_date?: date;          // Next scheduled payment
  next_payment_due_amount?: number;      // Next scheduled payment amount
}

{
  error: {
    code: 'EPISODE_NOT_FOUND' | 'ACCESS_DENIED' | 'INVALID_DATE' | 'SERVER_ERROR';
    message: string;                      // Human-readable error message
    details?: {
      episode_id?: uuid;                 // Episode ID that was queried
      organization_id?: uuid;             // Organization context
    };
  }
}

{
  organization_id: uuid;
  tax_year_id: uuid;
  form_type?: '1099-MISC' | '1099-NEC' | 'both';
}

{
  generated_count: number;
  forms: [{
    form_id: uuid;
    vendor_id: uuid;
    vendor_name: string;
    total_payments: number;
  }];
}

// Generate 1099 forms
const { data: { session } } = await supabase.auth.getSession();
if (!session) throw new Error('Not authenticated');

const response = await fetch('/api/v1/fa/tax/1099/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${session.access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    organization_id: session.user.user_metadata.organization_id,
    tax_year_id: taxYearId,
    form_type: 'both',
  }),
});

if (!response.ok) {
  const error = await response.json();
  if (error.error?.code === 'ACCESS_DENIED') {
    throw new Error('Access denied: organization not accessible');
  }
  throw new Error(error.error?.message || 'Failed to generate 1099 forms');
}

const result = await response.json();

{
  asset_id: uuid;
  asset_name: string;
  total_depreciation: number;
  depreciation_history: [{
    depreciation_month: date;
    depreciation_amount: number;
    journal_entry_id: uuid;
  }];
}

{
  organization_id: uuid;
  depreciation_month: date; // YYYY-MM-01 format
  asset_ids?: uuid[]; // Optional: specific assets, otherwise all active
}

{
  processed_count: number;
  total_depreciation: number;
  journal_entries_created: number;
  assets: [{
    asset_id: uuid;
    depreciation_amount: number;
    journal_entry_id: uuid;
  }];
}

// Process monthly depreciation
const { data: { session } } = await supabase.auth.getSession();
if (!session) throw new Error('Not authenticated');

const response = await fetch('/api/v1/fa/assets/depreciation/process', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${session.access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    organization_id: session.user.user_metadata.organization_id,
    depreciation_month: '2026-01-01',
  }),
});

if (!response.ok) {
  const error = await response.json();
  if (error.error?.code === 'ACCESS_DENIED') {
    throw new Error('Access denied: organization not accessible');
  }
  throw new Error(error.error?.message || 'Failed to process depreciation');
}

const result = await response.json();

{
  approved: boolean;
  comments?: string;
  approved_amount?: number;
}

{
  expense_report_id: uuid;
  status: 'approved' | 'rejected';
  approved_at: timestamp;
}

// Approve expense report
const response = await fetch(`/api/v1/fa/expenses/reports/${reportId}/approve`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${session.access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    approved: true,
    comments: 'Approved per policy',
    approved_amount: 150.00,
  }),
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error?.message || 'Failed to approve expense report');
}

const result = await response.json();

{
  project_id: uuid;
  project_name: string;
  period_start: date;
  period_end: date;
  budget_total: number;
  actual_total: number;
  variance: number;
  variance_percentage: number;
  by_account: [{
    account_id: uuid;
    account_name: string;
    budget_amount: number;
    actual_amount: number;
    variance: number;
  }];
}

{
  organization_id: uuid;
  position_date: date;
  operating_cash: number;
  payroll_cash: number;
  reserve_cash: number;
  grant_cash: number;
  other_cash: number;
  total_cash: number;
  cash_by_fund: Record<string, number>;
}

// FA-14: Cash Position query
import { useQuery } from '@tanstack/react-query';
import { supabase } from '@/integrations/supabase/client';

export function useCashPosition(asOfDate?: Date) {
  return useQuery({
    queryKey: ['cash-position', asOfDate],
    queryFn: async () => {
      const { data: { session } } = await supabase.auth.getSession();
      if (!session) throw new Error('Not authenticated');

      const params = new URLSearchParams();
      if (asOfDate) {
        params.append('as_of_date', asOfDate.toISOString().split('T')[0]);
      }

      const response = await fetch(
        `/api/v1/fa/cash/position?${params.toString()}`,
        {
          headers: {
            Authorization: `Bearer ${session.access_token}`,
            'Content-Type': 'application/json',
          },
        }
      );

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.error?.message || 'Failed to fetch cash position');
      }

      return response.json();
    },
  });
}

{
  organization_id: uuid;
  position_date: date;
  operating_cash?: number;
  payroll_cash?: number;
  reserve_cash?: number;
  grant_cash?: number;
  other_cash?: number;
  cash_by_fund?: Record<string, number>;
}

{
  position_id: uuid;
  organization_id: uuid;
  position_date: date;
  total_cash: number;
  updated_at: timestamp;
}

// Update cash position
const { data: { session } } = await supabase.auth.getSession();
if (!session) throw new Error('Not authenticated');

const response = await fetch('/api/v1/fa/cash/position', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${session.access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    organization_id: session.user.user_metadata.organization_id,
    position_date: '2026-01-15',
    operating_cash: 50000.00,
    payroll_cash: 25000.00,
  }),
});

if (!response.ok) {
  const error = await response.json();
  if (error.error?.code === 'ACCESS_DENIED') {
    throw new Error('Access denied: organization not accessible');
  }
  throw new Error(error.error?.message || 'Failed to update cash position');
}

const result = await response.json();

{
  organization_id: uuid;
  investment_type: string;
  amount: number;
  maturity_date: date;
  interest_rate: number;
  notes?: string;
}

{
  investment_id: uuid;
  investment_number: string;
  organization_id: uuid;
  status: 'active';
  created_at: timestamp;
}

// Create investment
const { data: { session } } = await supabase.auth.getSession();
if (!session) throw new Error('Not authenticated');

const response = await fetch('/api/v1/fa/investments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${session.access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    organization_id: session.user.user_metadata.organization_id,
    investment_type: 'Certificate of Deposit',
    amount: 100000.00,
    maturity_date: '2026-12-31',
    interest_rate: 4.5,
  }),
});

if (!response.ok) {
  const error = await response.json();
  if (error.error?.code === 'ACCESS_DENIED') {
    throw new Error('Access denied: organization not accessible');
  }
  throw new Error(error.error?.message || 'Failed to create investment');
}

const result = await response.json();

{
  fiscal_period_id: uuid;
  project_ids?: uuid[]; // Optional: specific projects, otherwise all active
}

{
  allocation_count: number;
  total_allocated_idc: number;
  allocations: [{
    project_id: uuid;
    project_name: string;
    allocated_idc: number;
    journal_entry_id: uuid;
  }];
}

{
  organization_id: uuid;
  period_start: date;
  period_end: date;
  metrics: {
    total_revenue: number;
    total_expenses: number;
    net_income: number;
    total_cash: number;
  };
  kpis: [{
    kpi_id: uuid;
    kpi_name: string;
    kpi_value: number;
    target_value?: number;
    status: 'on_target' | 'warning' | 'critical';
  }];
  trends: {
    revenue_trend: number[]; // Array of values over time
    expense_trend: number[];
    cash_trend: number[];
  };
}

{
  consolidation_id: uuid;
  fiscal_period_id: uuid;
}

{
  elimination_count: number;
  total_elimination_amount: number;
  eliminations: [{
    elimination_id: uuid;
    intercompany_account_id: uuid;
    elimination_amount: number;
    journal_entry_id: uuid;
  }];
}

{
  recognition_date: date;
  fiscal_period_id: uuid;
  schedule_ids?: uuid[]; // Optional: specific schedules, otherwise all due for the period
}

{
  recognition_count: number;
  total_recognized: number;
  recognitions: [{
    recognition_id: uuid;
    revenue_schedule_id: uuid;
    recognition_amount: number;
    journal_entry_id?: uuid;
    journal_entry_line_id?: uuid;
  }];
}

{
  approval_notes?: string;
}

{
  close_period_id: uuid;
  status: 'locked';
  approved_at: timestamp;
  approved_by: uuid;
}

// RH-01: Query payment status in episode detail view
import { useQuery } from '@tanstack/react-query';
import { supabase } from '@/integrations/supabase/client';

export function useEpisodeBalance(episodeId: string, asOfDate?: Date) {
  return useQuery({
    queryKey: ['episode-balance', episodeId, asOfDate],
    queryFn: async () => {
      const { data: { session } } = await supabase.auth.getSession();
      if (!session) throw new Error('Not authenticated');

      const params = new URLSearchParams({
        episode_id: episodeId,
      });
      if (asOfDate) {
        params.append('as_of_date', asOfDate.toISOString().split('T')[0]);
      }

      const response = await fetch(
        `/api/v1/fa/episode-balance?${params.toString()}`,
        {
          headers: {
            Authorization: `Bearer ${session.access_token}`,
            'Content-Type': 'application/json',
          },
        }
      );

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.error?.message || 'Failed to fetch balance');
      }

      return response.json();
    },
    enabled: !!episodeId,
    staleTime: 5 * 60 * 1000, // 5 minutes
  });
}

GET /api/v1/rh/current-residence?patient_id={patient_id}
Authorization: Bearer {jwt_token}

{
  episode_id: string;
  residence_id: string;
  residence_name: string;
  facility_type: 'recovery_housing' | 'psychiatric_residential' | 'inpatient_unit';
  bed_label: string;
  room_number: string | null;
  unit_label: string | null;   // Non-null for inpatient_unit
  admission_date: string;      // ISO date
} | null  // null if not currently admitted

{
  error: {
    code: string;       // e.g. 'PATIENT_NOT_FOUND', 'FORBIDDEN', 'RATE_LIMIT_EXCEEDED'
    message: string;    // Human-readable description
    resolution?: string; // Suggested remediation for 4xx errors
  };
}

type CurrentResidenceResponse = {
  episode_id: string;
  residence_id: string;
  residence_name: string;
  facility_type: 'recovery_housing' | 'psychiatric_residential' | 'inpatient_unit';
  bed_label: string;
  room_number: string | null;
  unit_label: string | null;
  admission_date: string;
} | null;

type CurrentResidenceError = {
  error: { code: string; message: string; resolution?: string };
};

async function fetchCurrentResidence(
  patientId: string,
  accessToken: string
): Promise<CurrentResidenceResponse> {
  const res = await fetch(
    `${API_BASE}/api/v1/rh/current-residence?patient_id=${encodeURIComponent(patientId)}`,
    { headers: { Authorization: `Bearer ${accessToken}` } }
  );
  if (res.status === 200) return res.json();
  const body = (await res.json()) as CurrentResidenceError;
  if (res.status === 403) throw new Error(body.error?.message ?? 'Forbidden');
  if (res.status === 404) return null;
  if (res.status === 429) {
    const retryAfter = res.headers.get('Retry-After');
    throw new Error(`Rate limited${retryAfter ? `; retry after ${retryAfter}s` : ''}`);
  }
  throw new Error(body.error?.message ?? `Request failed ${res.status}`);
}

// TanStack Query: recommended staleTime/gcTime and retry
const { data } = useQuery({
  queryKey: ['rh', 'current-residence', patientId],
  queryFn: () => fetchCurrentResidence(patientId, session.access_token),
  enabled: !!patientId && !!session?.access_token,
  staleTime: 30_000,
  gcTime: 300_000,
  retry: (failureCount, error) => {
    if (failureCount >= 3) return false;
    // Retry on 429/503/504; respect Retry-After when available
    return /rate limit|503|504/i.test(String(error));
  },
});

pf_has_permission(
  p_user_id UUID,
  p_organization_id UUID,
  p_permission_key TEXT,
  p_site_id UUID DEFAULT NULL
) RETURNS BOOLEAN

1. Check system role permissions (pf_user_roles)
   ↓
2. Check custom role permissions (pf_user_role_assignments → pf_role_permissions)
   ↓
3. If site_id provided, validate site scope from role assignment
   ↓
4. Return TRUE if any role grants the permission, FALSE otherwise

1. Module Permission (PF-30): pf_has_permission('hr.employees.view')
   ↓ (if TRUE)
2. Object Permission (PF-26): pf_object_permissions check
   ↓ (if TRUE)
3. Field Permission (PF-26): pf_field_permissions check

-- Check if user can view employees in org
SELECT pf_has_permission(
  auth.uid(),
  'org-uuid-here',
  'hr.employees.view'
);

-- Check if user can approve bills at specific site
SELECT pf_has_permission(
  auth.uid(),
  'org-uuid-here',
  'fa.bills.approve',
  'site-uuid-here'
);