Patient Domain — Mobile App Integration Guide

{
  "dependencies": {
    "axios": "^1.6.0",
    "@tanstack/react-query": "^5.0.0",
    "@tanstack/react-query-persist-client": "^5.0.0",
    "@react-native-async-storage/async-storage": "^1.21.0",
    "expo-file-system": "~16.0.0",
    "expo-document-picker": "~11.0.0",
    "jwt-decode": "^4.0.0"
  }
}

// lib/api-client.ts
import axios, { AxiosError } from 'axios';
import { getAccessToken, refreshAccessToken } from './auth';

const BASE_URL = process.env.EXPO_PUBLIC_API_URL ?? 'http://localhost:3000';

export const api = axios.create({
  baseURL: `${BASE_URL}/patient`,
  timeout: 15_000,
  headers: { 'Content-Type': 'application/json' },
});

api.interceptors.request.use(async (config) => {
  const token = await getAccessToken();
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

// Refresh-on-401 with single-flight to avoid stampedes
let refreshPromise: Promise<string> | null = null;

api.interceptors.response.use(
  (r) => r,
  async (error: AxiosError) => {
    const original = error.config as typeof error.config & { _retried?: boolean };
    if (error.response?.status === 401 && !original?._retried) {
      original._retried = true;
      refreshPromise ??= refreshAccessToken().finally(() => { refreshPromise = null; });
      const newToken = await refreshPromise;
      original.headers.Authorization = `Bearer ${newToken}`;
      return api.request(original);
    }
    return Promise.reject(error);
  }
);

// lib/api-types.ts
export interface ApiResponse<T> {
  data: T;
  meta: {
    request_id: string;
    total?: number;
    page?: number;
    limit?: number;
    pages?: number;
    fan_out?: number;
  };
}

export interface ApiError {
  data: null;
  error: {
    code: string;
    message: string;
    details?: Array<{ field: string | null; message: string }>;
  };
  meta: { request_id: string };
}

// lib/auth.ts (RN)
import AsyncStorage from '@react-native-async-storage/async-storage';

const ACCESS = '@kulcare/access_token';
const REFRESH = '@kulcare/refresh_token';

export const getAccessToken = () => AsyncStorage.getItem(ACCESS);
export const setTokens = async (access: string, refresh: string) => {
  await AsyncStorage.multiSet([[ACCESS, access], [REFRESH, refresh]]);
};
export const clearTokens = () => AsyncStorage.multiRemove([ACCESS, REFRESH]);

// Helper to unwrap either shape
export async function apiCall<T>(fn: () => Promise<{ data: ApiResponse<T> }>): Promise<T> {
  try {
    const response = await fn();
    return response.data.data;
  } catch (err) {
    if (axios.isAxiosError(err) && err.response?.data?.error) {
      throw new PatientApiError(err.response.data as ApiError, err.response.status);
    }
    throw err;
  }
}

export class PatientApiError extends Error {
  code: string;
  status: number;
  fieldErrors: Record<string, string>;

  constructor(body: ApiError, status: number) {
    super(body.error.message);
    this.code = body.error.code;
    this.status = status;
    this.fieldErrors = {};
    body.error.details?.forEach((d) => {
      if (d.field) this.fieldErrors[d.field] = d.message;
    });
  }
}

// lib/patient-resources.ts
import { api, apiCall, ApiResponse } from './api-client';

export const patientResource = <T, CreateInput, UpdateInput>(resource: string, rootKey: string) => ({
  list: (params?: Record<string, unknown>) =>
    apiCall<T[]>(() => api.get(`/${resource}`, { params })),

  show: (id: string) =>
    apiCall<T>(() => api.get(`/${resource}/${id}`)),

  create: (input: CreateInput) =>
    apiCall<T>(() => api.post(`/${resource}`, { [rootKey]: input })),

  update: (id: string, input: UpdateInput) =>
    apiCall<T>(() => api.patch(`/${resource}/${id}`, { [rootKey]: input })),

  destroy: (id: string) =>
    api.delete(`/${resource}/${id}`), // returns 204, no body

  restore: (id: string) =>
    apiCall<T>(() => api.post(`/${resource}/${id}/restore`)),
});

// lib/vitals.ts
import { patientResource } from './patient-resources';

export interface Vital {
  id: string;
  vital_type: 'blood_pressure' | 'heart_rate' | 'temperature' | 'weight' | 'height'
            | 'blood_glucose' | 'spo2' | 'respiratory_rate' | 'pain_score' | 'bmi';
  value: Record<string, number>;
  unit: string | null;
  measurement_type: 'fasting' | 'post_meal' | 'random' | 'pre_exercise' | 'post_exercise' | null;
  occurred_at: string;
  recorded_at: string;      // alias of occurred_at
  source: Source;
  source_reference: SourceReference | null;
  deleted_at: string | null;
  created_at: string;
  updated_at: string;
}

export interface VitalCreate {
  vital_type: Vital['vital_type'];
  value: Record<string, number>;
  unit?: string;
  measurement_type?: Vital['measurement_type'];
  occurred_at?: string;
  recorded_at?: string;     // backend accepts either
  source?: Source;
  source_reference?: SourceReference;
}

export const vitalsApi = patientResource<Vital, VitalCreate, Partial<VitalCreate>>(
  'vitals', 'vital'
);

Is the patient typing it manually?
├── Yes → source: 'self_reported', source_reference: null
└── No
    ├── From a connected device (Apple Health / Fitbit / BP cuff)?
    │   └── Yes → source: 'device', source_reference: {
    │              type: 'device', vendor: '<apple_health|fitbit|...>',
    │              sample_id: '<vendor-unique-id>'
    │            }
    ├── Patient tapping "save to my records" on a clinical record?
    │   └── Yes → source: 'clinical_imported', source_reference: {
    │              type: 'clinical.observations', id: '<uuid>',
    │              tenant_id: '<uuid>'
    │            }
    └── Imported from an external health record (ABDM, Apple Health export, pharmacy)?
        └── Yes → source: 'external', source_reference: {
                   type: 'abdm', abha_id: '...' | type: 'pharmacy_receipt', ...
                 }

// User taps 'Save to my records' on a clinical observation shown in the timeline
const importClinicalVital = async (clinical: ClinicalObservation) => {
  return vitalsApi.create({
    vital_type: clinical.vital_type,
    value: clinical.value,
    occurred_at: clinical.effective_date_time,
    source: 'clinical_imported',
    source_reference: {
      type: 'clinical.observations',
      id: clinical.id,
      tenant_id: clinical.tenant_id,
    },
  });
};

const deleteVitalWithUndo = (id: string) => {
  vitalsApi.destroy(id);
  showToast('Vital deleted', {
    action: { label: 'Undo', handler: () => vitalsApi.restore(id) },
    duration: 5000,
  });
};

interface BulkVitalsRequest {
  vitals: VitalCreate[];  // each row must have source: 'device' with a sample_id
}

interface BulkVitalsResponse {
  created_count: number;
  skipped_count: number;  // duplicates rejected by the unique index
}

import AppleHealth from 'react-native-health';

async function syncVitals(since: Date) {
  // 1. Pull samples from the device SDK
  const hrSamples = await AppleHealth.getHeartRateSamples({ startDate: since });

  // 2. Map to Patient:: bulk payload — one sample = one row
  const rows = hrSamples.map((s) => ({
    vital_type: 'heart_rate' as const,
    value: { value: s.value },
    unit: 'bpm',
    occurred_at: s.startDate,
    source: 'device' as const,
    source_reference: {
      type: 'device',
      vendor: 'apple_health',
      sample_id: s.uuid,      // HealthKit UUID is vendor-unique
    },
  }));

  if (rows.length === 0) return { created: 0, skipped: 0 };

  // 3. POST to /patient/vitals/bulk — safe to retry
  const res = await apiCall<BulkVitalsResponse>(() =>
    api.post('/vitals/bulk', { vitals: rows })
  );

  return { created: res.created_count, skipped: res.skipped_count };
}

// lib/offline-queue.ts
import AsyncStorage from '@react-native-async-storage/async-storage';
import NetInfo from '@react-native-community/netinfo';

const QUEUE_KEY = '@kulcare/pending_vitals';

export async function enqueueVital(vital: VitalCreate) {
  const queue = JSON.parse((await AsyncStorage.getItem(QUEUE_KEY)) ?? '[]');
  queue.push(vital);
  await AsyncStorage.setItem(QUEUE_KEY, JSON.stringify(queue));
}

export async function flushQueue() {
  const { isConnected } = await NetInfo.fetch();
  if (!isConnected) return;

  const queue: VitalCreate[] = JSON.parse((await AsyncStorage.getItem(QUEUE_KEY)) ?? '[]');
  if (queue.length === 0) return;

  try {
    await api.post('/vitals/bulk', { vitals: queue });
    // On success, clear — even if some were skipped, they're now in the DB.
    await AsyncStorage.removeItem(QUEUE_KEY);
  } catch (err) {
    // Transient error — keep queue for next try. For 422 (bad row), drop bad
    // rows and retry; see §8.
  }
}

// Wire up a listener to flush on reconnect
NetInfo.addEventListener((state) => {
  if (state.isConnected) flushQueue();
});

import { v4 as uuid } from 'uuid';

const manualVital: VitalCreate = {
  vital_type: 'blood_pressure',
  value: { systolic: 120, diastolic: 80 },
  occurred_at: new Date().toISOString(),
  source: 'device',  // treat manual entry as a pseudo-device for idempotency
  source_reference: {
    type: 'device',
    vendor: 'manual_entry',
    sample_id: uuid(),  // stable per-entry id
  },
};

import * as DocumentPicker from 'expo-document-picker';

async function uploadDocument(title: string, documentType: string) {
  const picked = await DocumentPicker.getDocumentAsync({
    type: ['application/pdf', 'image/*'],
    multiple: false,
  });
  if (picked.canceled) return;

  const file = picked.assets[0];
  const formData = new FormData();
  formData.append('document[title]', title);
  formData.append('document[document_type]', documentType);
  formData.append('file', {
    uri: file.uri,
    name: file.name,
    type: file.mimeType ?? 'application/octet-stream',
  } as any);

  const { data } = await api.post<ApiResponse<PatientDocument>>(
    '/documents',
    formData,
    { headers: { 'Content-Type': 'multipart/form-data' } }
  );
  return data.data;  // includes file_url
}

const { file_url } = document;
<Image source={{ uri: file_url, headers: { Authorization: `Bearer ${token}` } }} />;

import * as FileSystem from 'expo-file-system';

async function cacheDocument(doc: PatientDocument) {
  const cachePath = `${FileSystem.cacheDirectory}patient-docs/${doc.id}`;
  const info = await FileSystem.getInfoAsync(cachePath);
  if (info.exists) return cachePath;

  // Re-fetch with a fresh URL
  const fresh = await apiCall<PatientDocument>(() => api.get(`/documents/${doc.id}`));
  const download = await FileSystem.downloadAsync(fresh.file_url!, cachePath);
  return download.uri;
}

type ClinicalResourceType =
  | 'conditions' | 'prescriptions' | 'allergy_intolerances'
  | 'observations' | 'encounters' | 'appointments' | 'documents';

interface ClinicalRecord<T = unknown> {
  id: string;
  type: ClinicalResourceType;
  tenant_id: string;
  occurred_at: string | null;
  data: T;
}

export const clinicalApi = {
  list: (type: ClinicalResourceType, params?: Record<string, unknown>) =>
    apiCall<ClinicalRecord[]>(() => api.get(`/clinical/${type}`, { params })),

  show: (type: ClinicalResourceType, id: string) =>
    apiCall<ClinicalRecord>(() => api.get(`/clinical/${type}/${id}`)),

  timeline: (params?: { limit?: number }) =>
    apiCall<{ timeline: TimelineEntry[]; facilities: FacilitySummary[] }>(() =>
      api.get('/clinical/timeline', { params })
    ),
};

// Shortcut hooks
export const useConditions = () => useQuery({
  queryKey: ['clinical', 'conditions'],
  queryFn: () => clinicalApi.list('conditions'),
});

const { data } = useQuery({
  queryKey: ['clinical', 'timeline'],
  queryFn: () => clinicalApi.timeline({ limit: 50 }),
  staleTime: 60_000,  // clinical data changes rarely; 1-minute stale is fine
});

data?.timeline.map((entry) => {
  // entry.type: 'encounter' | 'prescription' | 'condition' | ...
  // entry.data: resource-specific shape
  // entry.tenant_id: which clinic authored it
});

if (meta.fan_out === 10 && facilities.length > 10) {
  showBanner('Some clinics may not be included. Contact support.');
}

try {
  await vitalsApi.create(input);
} catch (err) {
  if (err instanceof PatientApiError && err.status === 422) {
    // err.fieldErrors: { vital_type: 'is not included in the list', ... }
    setFieldErrors(err.fieldErrors);
    return;
  }
  showToast(err.message);
}

// Standardize on a factory so invalidation is consistent
export const patientKeys = {
  all: ['patient'] as const,

  resources: (resource: string) => [...patientKeys.all, resource] as const,
  resourceList: (resource: string, filters?: Record<string, unknown>) =>
    [...patientKeys.resources(resource), 'list', filters ?? {}] as const,
  resourceDetail: (resource: string, id: string) =>
    [...patientKeys.resources(resource), 'detail', id] as const,

  clinical: ['patient', 'clinical'] as const,
  clinicalList: (type: string, filters?: Record<string, unknown>) =>
    [...patientKeys.clinical, type, 'list', filters ?? {}] as const,
  clinicalDetail: (type: string, id: string) =>
    [...patientKeys.clinical, type, 'detail', id] as const,
  timeline: () => [...patientKeys.clinical, 'timeline'] as const,
};

const queryClient = useQueryClient();

const createVital = useMutation({
  mutationFn: vitalsApi.create,
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: patientKeys.resources('vitals') });
  },
});

const deleteVital = useMutation({
  mutationFn: vitalsApi.destroy,
  onSuccess: (_, id) => {
    queryClient.invalidateQueries({ queryKey: patientKeys.resources('vitals') });
    // Optionally optimistic update — remove from the list cache immediately
  },
});

# Backend on localhost:3000
cd backend && bin/rails s

# Mobile app pointing at local backend
EXPO_PUBLIC_API_URL=http://localhost:3000 pnpm start

Identity::User.create!(email: 'mobile-test-a@example.com', first_name: 'A', last_name: 'Tester')