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'
);

import { useQuery } from '@tanstack/react-query';
import { supabase } from '@/integrations/supabase/client';
import { useOrganization } from '@/platform/organizations/OrganizationContext';

export function useHasPermission(permissionKey: string, siteId?: string) {
  const { currentOrganization } = useOrganization();

  return useQuery({
    queryKey: ['permission', permissionKey, currentOrganization?.id, siteId],
    queryFn: async () => {
      const { data, error } = await supabase.rpc('pf_has_permission', {
        p_user_id: (await supabase.auth.getUser()).data.user?.id,
        p_organization_id: currentOrganization?.id,
        p_permission_key: permissionKey,
        p_site_id: siteId ?? null,
      });
      
      if (error) throw error;
      return data as boolean;
    },
    enabled: !!currentOrganization?.id,
    staleTime: 5 * 60 * 1000, // 5 minutes per constitution
    gcTime: 10 * 60 * 1000,   // 10 minutes per constitution
  });
}

GET /api/v1/hr/employees/{employee_id}
Authorization: Bearer {jwt_token}

{
  employee_id: uuid;
  employee_number: string;
  full_name: string;
  job_title: string;
  department: string;
  hire_date: date;
  employment_status: 'active' | 'inactive' | 'terminated';
  contact_email: string;
  contact_phone: string;
}

GET /api/v1/hr/employees?department=Recovery Housing&status=active&page=1&page_size=50
Authorization: Bearer {jwt_token}

{
  employees: [{
    employee_id: uuid;
    employee_number: string;
    full_name: string;
    job_title: string;
    department: string;
    hire_date: date;
    employment_status: 'active' | 'inactive' | 'terminated';
  }];
  total_count: number;
  page: number;
  page_size: number;
  has_next_page: boolean;
}

{
  id: uuid;
  employee_id: uuid;
  plan_id: uuid;
  plan: {
    id: uuid;
    name: string;
    plan_type: string;
    plan_category?: string;
  };
  status: 'pending' | 'approved' | 'active' | 'terminated' | 'cancelled';
  effective_date: date;
  termination_date?: date;
  employee_contribution: number;
  employer_contribution: number;
}

import { useEmployeeBenefitEnrollment } from '@/cores/hr/hooks/useEmployeeBenefitEnrollment';

// In leave request component
const { data: stdEnrollment } = useEmployeeBenefitEnrollment(employeeId, 'std');
const isBenefitsEligible = stdEnrollment?.status === 'active';

[{
  id: uuid;
  leave_policy_id: uuid;
  benefit_plan_id: uuid;
  benefit_plan: {
    id: uuid;
    name: string;
    plan_type: string;
  };
  alignment_status: 'aligned' | 'misaligned' | 'pending' | 'not_applicable';
  alignment_verified_at?: timestamp;
  requires_enrollment: boolean;
  enrollment_impact?: string;
}]

POST /functions/v1/workflow-query-action
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  organization_id: uuid;
  table_name: string;           // Must be in org's whitelist
  select_columns?: string[];    // Columns to return (null = all allowed)
  filters: [{
    column: string;
    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'in' | 'is_null' | 'is_not_null';
    value: any;
  }];
  order_by?: { column: string; direction: 'asc' | 'desc' };
  limit?: number;               // Default: 100, max: from whitelist
  execution_id: uuid;           // For audit logging
}

{
  data: any[];                  // Query results
  count: number;                // Number of rows returned
  query_time_ms: number;        // Query execution time
}

{
  error: {
    code: 'TABLE_NOT_ALLOWED' | 'INVALID_FILTER' | 'QUERY_TIMEOUT' | 'ACCESS_DENIED' | 'SERVER_ERROR';
    message: string;
    details?: {
      table_name?: string;
      organization_id?: uuid;
    };
  }
}

POST /functions/v1/workflow-api-action
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  organization_id: uuid;
  config: {
    connection_id?: string;       // Optional: use saved connection
    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
    url: string;                  // Can use {{variables}}
    headers: Record<string, string>;
    body?: any;                   // JSON or template
    auth: {
      type: 'none' | 'api_key' | 'bearer' | 'basic' | 'oauth2';
      config: any;                // Type-specific auth config
    };
    retry: {
      max_attempts: number;       // 1-5
      backoff: 'linear' | 'exponential';
    };
    timeout_ms: number;           // Default: 30000
  };
  variables: Record<string, any>; // For template resolution
  execution_id: uuid;             // For audit logging
}

{
  status: number;               // HTTP status from external API
  data: any;                    // Parsed response body
  headers: Record<string, string>;
  duration_ms: number;          // Total request time
  retries_attempted: number;    // Number of retry attempts
}

{
  error: {
    code: 'CONNECTION_FAILED' | 'AUTH_FAILED' | 'TIMEOUT' | 'MAX_RETRIES_EXCEEDED' | 'SERVER_ERROR';
    message: string;
    details?: {
      status_code?: number;
      external_error?: string;
      retries_attempted?: number;
    };
  }
}