Construire une intégration NPHIES FHIR en TypeScript : éligibilité, réclamations et suivi des rejets

mkdir nphies-client && cd nphies-client
npm init -y
npm install undici zod pino
npm install -D typescript tsx @types/node
npx tsc --init --target es2022 --module node16 --strict

// src/terminology.ts
 
/** Espaces de noms canoniques NPHIES, selon le guide Healthcare Financial Services. */
export const NPHIES = {
  CS: 'http://nphies.sa/terminology/CodeSystem',
  SD: 'http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition',
} as const;
 
/** Codes d'événement de message — ils sélectionnent le type de transaction. */
export const MessageEvent = {
  EligibilityRequest: 'eligibility-request',
  EligibilityResponse: 'eligibility-response',
  PriorAuthRequest: 'priorauth-request',
  PriorAuthResponse: 'priorauth-response',
  ClaimRequest: 'claim-request',
  ClaimResponse: 'claim-response',
  PollRequest: 'poll-request',
  PollResponse: 'poll-response',
} as const;
 
export type MessageEventCode =
  (typeof MessageEvent)[keyof typeof MessageEvent];

// src/envelope.ts
import { NPHIES, type MessageEventCode } from './terminology.js';
 
export interface ParticipantConfig {
  /** Votre licence d'établissement, telle que délivrée à l'onboarding. */
  providerLicense: string;
  providerBaseUrl: string;
  /** L'identifiant de licence de l'assureur pour cette transaction. */
  insurerLicense: string;
}
 
interface BundleEntry {
  fullUrl: string;
  resource: Record<string, unknown>;
}
 
/**
 * Construit un bundle de message NPHIES.
 *
 * Le MessageHeader est généré en interne et toujours placé en tête,
 * de sorte que les appelants ne peuvent pas le réordonner par accident.
 */
export function buildMessageBundle(opts: {
  event: MessageEventCode;
  /** La ressource visée par le MessageHeader via focus. */
  focus: BundleEntry;
  /** Toutes les ressources de support : Patient, Coverage, Organizations, etc. */
  supporting: BundleEntry[];
  participants: ParticipantConfig;
  bundleId: string;
  timestamp: string;
}) {
  const { event, focus, supporting, participants, bundleId, timestamp } = opts;
  const headerUrl = `urn:uuid:${bundleId}-hdr`;
 
  const messageHeader: BundleEntry = {
    fullUrl: headerUrl,
    resource: {
      resourceType: 'MessageHeader',
      id: `${bundleId}-hdr`,
      meta: { profile: [`${NPHIES.SD}/message-header`] },
      eventCoding: {
        system: `${NPHIES.CS}/ksa-message-events`,
        code: event,
      },
      destination: [
        {
          endpoint: `http://nphies.sa/license/payer-license/${participants.insurerLicense}`,
          receiver: {
            type: 'Organization',
            identifier: {
              system: 'http://nphies.sa/license/payer-license',
              value: participants.insurerLicense,
            },
          },
        },
      ],
      sender: {
        type: 'Organization',
        identifier: {
          system: 'http://nphies.sa/license/provider-license',
          value: participants.providerLicense,
        },
      },
      source: { endpoint: participants.providerBaseUrl },
      // focus indique au destinataire quelle ressource est le sujet du message
      focus: [{ reference: focus.fullUrl }],
    },
  };
 
  return {
    resourceType: 'Bundle' as const,
    id: bundleId,
    meta: { profile: [`${NPHIES.SD}/bundle`] },
    type: 'message' as const,
    timestamp,
    // L'en-tête est placé en tête ici, sans condition.
    entry: [messageHeader, focus, ...supporting],
  };
}

// src/transport.ts
import { Agent, request } from 'undici';
import { readFileSync } from 'node:fs';
import pino from 'pino';
 
const log = pino({ name: 'nphies-transport' });
 
const agent = new Agent({
  connect: {
    cert: readFileSync(requireEnv('NPHIES_CLIENT_CERT_PATH')),
    key: readFileSync(requireEnv('NPHIES_CLIENT_KEY_PATH')),
    // Ne désactivez jamais la vérification du certificat, pas même en
    // environnement de test. Si le handshake échoue, réparez la chaîne
    // de confiance.
    rejectUnauthorized: true,
  },
  // Le store-and-forward implique que des réponses lentes sont normales.
  headersTimeout: 60_000,
  bodyTimeout: 60_000,
});
 
function requireEnv(name: string): string {
  const v = process.env[name];
  if (!v) throw new Error(`Missing required environment variable: ${name}`);
  return v;
}
 
export interface TransportResult {
  status: number;
  body: unknown;
}
 
export async function processMessage(
  bundle: unknown,
  correlationId: string,
): Promise<TransportResult> {
  const base = requireEnv('NPHIES_BASE_URL');
  const started = Date.now();
 
  const res = await request(`${base}/$process-message`, {
    dispatcher: agent,
    method: 'POST',
    headers: {
      'content-type': 'application/fhir+json',
      accept: 'application/fhir+json',
    },
    body: JSON.stringify(bundle),
  });
 
  const body = await res.body.json().catch(() => null);
 
  log.info(
    { correlationId, status: res.statusCode, ms: Date.now() - started },
    'process-message completed',
  );
 
  return { status: res.statusCode, body };
}

// src/eligibility.ts
import { randomUUID } from 'node:crypto';
import { buildMessageBundle, type ParticipantConfig } from './envelope.js';
import { MessageEvent, NPHIES } from './terminology.js';
import { processMessage } from './transport.js';
 
export type EligibilityPurpose = 'validation' | 'benefit' | 'discovery';
 
export async function checkEligibility(input: {
  purpose: EligibilityPurpose;
  /** Numéro d'identité nationale ou d'Iqama du patient. */
  patientIdentifier: string;
  patientId: string;
  coverageId: string;
  memberId: string;
  /** Date ISO, ex. "2026-08-07" — la date de service. */
  servicedDate: string;
  participants: ParticipantConfig;
}) {
  const bundleId = randomUUID();
  const reqUrl = `urn:uuid:${randomUUID()}`;
  const patientUrl = `urn:uuid:${randomUUID()}`;
  const coverageUrl = `urn:uuid:${randomUUID()}`;
 
  const focus = {
    fullUrl: reqUrl,
    resource: {
      resourceType: 'CoverageEligibilityRequest',
      id: bundleId,
      meta: { profile: [`${NPHIES.SD}/eligibility-request`] },
      identifier: [
        {
          system: `${input.participants.providerBaseUrl}/eligibility`,
          value: bundleId,
        },
      ],
      status: 'active',
      // purpose est un tableau — demander plusieurs finalités est légitime.
      purpose: [input.purpose],
      patient: { reference: patientUrl },
      servicedDate: input.servicedDate,
      created: new Date().toISOString(),
      provider: {
        identifier: {
          system: 'http://nphies.sa/license/provider-license',
          value: input.participants.providerLicense,
        },
      },
      insurer: {
        identifier: {
          system: 'http://nphies.sa/license/payer-license',
          value: input.participants.insurerLicense,
        },
      },
      insurance: [{ coverage: { reference: coverageUrl } }],
    },
  };
 
  const supporting = [
    {
      fullUrl: patientUrl,
      resource: {
        resourceType: 'Patient',
        id: input.patientId,
        meta: { profile: [`${NPHIES.SD}/patient`] },
        identifier: [
          {
            type: {
              coding: [
                {
                  system: 'http://terminology.hl7.org/CodeSystem/v2-0203',
                  code: 'NI',
                },
              ],
            },
            system: 'http://nphies.sa/identifier/iqama',
            value: input.patientIdentifier,
          },
        ],
      },
    },
    {
      fullUrl: coverageUrl,
      resource: {
        resourceType: 'Coverage',
        id: input.coverageId,
        meta: { profile: [`${NPHIES.SD}/coverage`] },
        status: 'active',
        subscriberId: input.memberId,
        beneficiary: { reference: patientUrl },
        relationship: {
          coding: [
            {
              system:
                'http://terminology.hl7.org/CodeSystem/subscriber-relationship',
              code: 'self',
            },
          ],
        },
        payor: [
          {
            identifier: {
              system: 'http://nphies.sa/license/payer-license',
              value: input.participants.insurerLicense,
            },
          },
        ],
      },
    },
  ];
 
  const bundle = buildMessageBundle({
    event: MessageEvent.EligibilityRequest,
    focus,
    supporting,
    participants: input.participants,
    bundleId,
    timestamp: new Date().toISOString(),
  });
 
  return { bundleId, result: await processMessage(bundle, bundleId) };
}

// src/outcome.ts
 
export type TransactionOutcome =
  | { layer: 'transport'; ok: false; status: number }
  | { layer: 'validation'; ok: false; issues: ValidationIssue[] }
  | { layer: 'pending'; ok: true; reason: 'nphies-generated' | 'queued' }
  | { layer: 'adjudication'; ok: true; outcome: 'complete' | 'partial' }
  | { layer: 'adjudication'; ok: false; outcome: 'error'; denials: Denial[] };
 
export interface ValidationIssue {
  severity: string;
  code: string;
  details?: string;
}
 
export interface Denial {
  itemSequence?: number;
  code: string;
  display?: string;
}
 
interface FhirBundle {
  meta?: { tag?: Array<{ system?: string; code?: string }> };
  entry?: Array<{ resource?: Record<string, any> }>;
}
 
function findResource(bundle: FhirBundle, type: string) {
  return bundle.entry?.find((e) => e.resource?.resourceType === type)?.resource;
}
 
export function classifyOutcome(
  status: number,
  body: unknown,
): TransactionOutcome {
  if (status !== 200) return { layer: 'transport', ok: false, status };
 
  const bundle = body as FhirBundle;
 
  // Couche 2 : NPHIES a rejeté le message lui-même.
  const oo = findResource(bundle, 'OperationOutcome');
  if (oo) {
    return {
      layer: 'validation',
      ok: false,
      issues: (oo.issue ?? []).map((i: any) => ({
        severity: i.severity,
        code: i.code,
        details: i.details?.text,
      })),
    };
  }
 
  // Cas particulier : NPHIES a répondu à la place de l'assureur.
  const isNphiesGenerated = bundle.meta?.tag?.some((t) =>
    t.system?.includes('nphies.sa'),
  );
  if (isNphiesGenerated) {
    return { layer: 'pending', ok: true, reason: 'nphies-generated' };
  }
 
  const claimResponse = findResource(bundle, 'ClaimResponse');
  if (!claimResponse) {
    // Les réponses d'éligibilité et autres non-réclamations arrivent ici.
    return { layer: 'adjudication', ok: true, outcome: 'complete' };
  }
 
  // "queued" signifie : l'adjudication n'a pas encore eu lieu. Interrogez.
  if (claimResponse.outcome === 'queued') {
    return { layer: 'pending', ok: true, reason: 'queued' };
  }
 
  if (claimResponse.outcome === 'error') {
    return {
      layer: 'adjudication',
      ok: false,
      outcome: 'error',
      denials: extractDenials(claimResponse),
    };
  }
 
  return {
    layer: 'adjudication',
    ok: true,
    outcome: claimResponse.outcome === 'partial' ? 'partial' : 'complete',
  };
}
 
/** Extrait les motifs de rejet au niveau ligne ET au niveau en-tête. */
export function extractDenials(claimResponse: any): Denial[] {
  const denials: Denial[] = [];
 
  for (const item of claimResponse.item ?? []) {
    for (const adj of item.adjudication ?? []) {
      for (const coding of adj.reason?.coding ?? []) {
        denials.push({
          itemSequence: item.itemSequence,
          code: coding.code,
          display: coding.display,
        });
      }
    }
  }
 
  // Les erreurs d'en-tête concernent toute la réclamation, pas une ligne.
  for (const err of claimResponse.error ?? []) {
    for (const coding of err.code?.coding ?? []) {
      denials.push({ code: coding.code, display: coding.display });
    }
  }
 
  return denials;
}

// src/claim.ts
import { randomUUID } from 'node:crypto';
import { buildMessageBundle, type ParticipantConfig } from './envelope.js';
import { MessageEvent, NPHIES } from './terminology.js';
import { processMessage } from './transport.js';
import { classifyOutcome } from './outcome.js';
 
export interface ClaimLine {
  sequence: number;
  /** Code d'acte ou de service issu du système de codes NPHIES applicable. */
  code: string;
  codeSystem: string;
  quantity: number;
  unitPrice: number;
  /** Numéros de séquence des diagnostics justifiant cette ligne. */
  diagnosisSequence: number[];
}
 
export interface ClaimDiagnosis {
  sequence: number;
  /** Code ICD-10-AM. */
  code: string;
  type: 'principal' | 'secondary';
}
 
export async function submitClaim(input: {
  patientRef: string;
  coverageRef: string;
  claimType: 'institutional' | 'professional' | 'pharmacy' | 'oral' | 'vision';
  subType: 'ip' | 'op';
  use: 'claim' | 'preauthorization';
  diagnoses: ClaimDiagnosis[];
  lines: ClaimLine[];
  supporting: Array<{ fullUrl: string; resource: Record<string, unknown> }>;
  participants: ParticipantConfig;
}) {
  const bundleId = randomUUID();
  const claimUrl = `urn:uuid:${randomUUID()}`;
 
  const total = input.lines.reduce(
    (sum, l) => sum + l.quantity * l.unitPrice,
    0,
  );
 
  const focus = {
    fullUrl: claimUrl,
    resource: {
      resourceType: 'Claim',
      id: bundleId,
      meta: { profile: [`${NPHIES.SD}/${input.claimType}-claim`] },
      identifier: [
        {
          system: `${input.participants.providerBaseUrl}/claim`,
          value: bundleId,
        },
      ],
      status: 'active',
      type: {
        coding: [
          {
            system: 'http://terminology.hl7.org/CodeSystem/claim-type',
            code: input.claimType,
          },
        ],
      },
      subType: {
        coding: [
          { system: `${NPHIES.CS}/claim-subtype`, code: input.subType },
        ],
      },
      use: input.use,
      patient: { reference: input.patientRef },
      created: new Date().toISOString(),
      insurer: {
        identifier: {
          system: 'http://nphies.sa/license/payer-license',
          value: input.participants.insurerLicense,
        },
      },
      provider: {
        identifier: {
          system: 'http://nphies.sa/license/provider-license',
          value: input.participants.providerLicense,
        },
      },
      priority: {
        coding: [
          {
            system: 'http://terminology.hl7.org/CodeSystem/processpriority',
            code: 'normal',
          },
        ],
      },
      diagnosis: input.diagnoses.map((d) => ({
        sequence: d.sequence,
        diagnosisCodeableConcept: {
          coding: [{ system: `${NPHIES.CS}/diagnosis-icd-10-am`, code: d.code }],
        },
        type: [
          {
            coding: [
              { system: `${NPHIES.CS}/diagnosis-type`, code: d.type },
            ],
          },
        ],
      })),
      insurance: [
        {
          sequence: 1,
          focal: true,
          coverage: { reference: input.coverageRef },
        },
      ],
      item: input.lines.map((l) => ({
        sequence: l.sequence,
        diagnosisSequence: l.diagnosisSequence,
        productOrService: {
          coding: [{ system: l.codeSystem, code: l.code }],
        },
        quantity: { value: l.quantity },
        unitPrice: { value: l.unitPrice, currency: 'SAR' },
        net: { value: l.quantity * l.unitPrice, currency: 'SAR' },
      })),
      total: { value: total, currency: 'SAR' },
    },
  };
 
  const bundle = buildMessageBundle({
    event:
      input.use === 'preauthorization'
        ? MessageEvent.PriorAuthRequest
        : MessageEvent.ClaimRequest,
    focus,
    supporting: input.supporting,
    participants: input.participants,
    bundleId,
    timestamp: new Date().toISOString(),
  });
 
  const { status, body } = await processMessage(bundle, bundleId);
  return { bundleId, outcome: classifyOutcome(status, body), raw: body };
}

// src/poll.ts
import { randomUUID } from 'node:crypto';
import { buildMessageBundle, type ParticipantConfig } from './envelope.js';
import { MessageEvent, NPHIES } from './terminology.js';
import { processMessage } from './transport.js';
 
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
async function pollOnce(participants: ParticipantConfig) {
  const bundleId = randomUUID();
  const taskUrl = `urn:uuid:${randomUUID()}`;
 
  const focus = {
    fullUrl: taskUrl,
    resource: {
      resourceType: 'Task',
      id: bundleId,
      meta: { profile: [`${NPHIES.SD}/task`] },
      status: 'requested',
      intent: 'order',
      code: {
        coding: [{ system: `${NPHIES.CS}/task-code`, code: 'poll' }],
      },
      authoredOn: new Date().toISOString(),
      requester: {
        identifier: {
          system: 'http://nphies.sa/license/provider-license',
          value: participants.providerLicense,
        },
      },
      owner: {
        identifier: {
          system: 'http://nphies.sa/license/payer-license',
          value: participants.insurerLicense,
        },
      },
    },
  };
 
  const bundle = buildMessageBundle({
    event: MessageEvent.PollRequest,
    focus,
    supporting: [],
    participants,
    bundleId,
    timestamp: new Date().toISOString(),
  });
 
  return processMessage(bundle, bundleId);
}
 
/**
 * Interroge avec un backoff exponentiel plafonné.
 *
 * Renvoie null quand le budget est épuisé — c'est un résultat légitime
 * signifiant « toujours sans réponse », PAS une erreur à avaler.
 */
export async function pollForResponses(
  participants: ParticipantConfig,
  opts: { maxAttempts?: number; baseDelayMs?: number } = {},
): Promise<unknown | null> {
  const maxAttempts = opts.maxAttempts ?? 6;
  const base = opts.baseDelayMs ?? 5_000;
 
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    if (attempt > 0) {
      // 5 s, 10 s, 20 s, 40 s, 80 s — plafonné à 2 minutes.
      const delay = Math.min(base * 2 ** (attempt - 1), 120_000);
      await sleep(delay);
    }
 
    const { status, body } = await pollOnce(participants);
    if (status === 200 && hasPayload(body)) return body;
  }
 
  return null;
}
 
function hasPayload(body: unknown): boolean {
  const bundle = body as { entry?: unknown[] };
  // Une réponse ne contenant qu'un MessageHeader signifie « rien en attente ».
  return (bundle?.entry?.length ?? 0) > 1;
}

CREATE TABLE claim_submissions (
  bundle_id        UUID PRIMARY KEY,
  claim_identifier TEXT NOT NULL,
  patient_ref      TEXT NOT NULL,
  insurer_license  TEXT NOT NULL,
  submitted_at     TIMESTAMPTZ NOT NULL,
  total_sar        NUMERIC(12,2) NOT NULL,
  -- 'transport' | 'validation' | 'pending' | 'adjudication'
  outcome_layer    TEXT,
  outcome_code     TEXT,
  resolved_at      TIMESTAMPTZ
);
 
CREATE TABLE claim_denials (
  id             BIGSERIAL PRIMARY KEY,
  bundle_id      UUID NOT NULL REFERENCES claim_submissions(bundle_id),
  item_sequence  INT,               -- NULL pour un rejet de niveau en-tête
  denial_code    TEXT NOT NULL,
  denial_display TEXT,
  denied_amount  NUMERIC(12,2),
  recorded_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);
 
CREATE INDEX idx_denials_code ON claim_denials(denial_code);

-- Le rapport que la direction financière n'a jamais eu.
SELECT
  d.denial_code,
  d.denial_display,
  COUNT(*)                  AS occurrences,
  SUM(d.denied_amount)      AS sar_at_risk
FROM claim_denials d
JOIN claim_submissions s ON s.bundle_id = d.bundle_id
WHERE s.submitted_at >= now() - INTERVAL '90 days'
GROUP BY d.denial_code, d.denial_display
ORDER BY sar_at_risk DESC
LIMIT 20;

// src/ledger.ts
import type { TransactionOutcome } from './outcome.js';
 
export async function recordOutcome(
  db: DbClient,
  bundleId: string,
  outcome: TransactionOutcome,
) {
  await db.query(
    `UPDATE claim_submissions
        SET outcome_layer = $2,
            outcome_code  = $3,
            resolved_at   = CASE WHEN $2 = 'pending' THEN NULL ELSE now() END
      WHERE bundle_id = $1`,
    [bundleId, outcome.layer, outcomeCode(outcome)],
  );
 
  if (outcome.layer === 'adjudication' && !outcome.ok) {
    for (const denial of outcome.denials) {
      await db.query(
        `INSERT INTO claim_denials
           (bundle_id, item_sequence, denial_code, denial_display)
         VALUES ($1, $2, $3, $4)`,
        [bundleId, denial.itemSequence ?? null, denial.code, denial.display],
      );
    }
  }
}
 
function outcomeCode(o: TransactionOutcome): string {
  if (o.layer === 'validation') return o.issues[0]?.code ?? 'unknown';
  if (o.layer === 'pending') return o.reason;
  if (o.layer === 'transport') return String(o.status);
  return o.outcome;
}

// tests/envelope.test.ts
import { describe, it, expect } from 'vitest';
import { buildMessageBundle } from '../src/envelope.js';
import { MessageEvent } from '../src/terminology.js';
 
const participants = {
  providerLicense: 'PR-FHIR-TEST',
  providerBaseUrl: 'http://provider.example.sa',
  insurerLicense: 'INS-FHIR-TEST',
};
 
describe('message bundle envelope', () => {
  it('always places MessageHeader first', () => {
    const bundle = buildMessageBundle({
      event: MessageEvent.ClaimRequest,
      focus: { fullUrl: 'urn:uuid:focus', resource: { resourceType: 'Claim' } },
      supporting: [
        { fullUrl: 'urn:uuid:p', resource: { resourceType: 'Patient' } },
      ],
      participants,
      bundleId: 'test-bundle',
      timestamp: '2026-08-07T09:00:00Z',
    });
 
    expect(bundle.entry[0].resource.resourceType).toBe('MessageHeader');
    expect(bundle.type).toBe('message');
  });
 
  it('points MessageHeader.focus at the focus resource', () => {
    const bundle = buildMessageBundle({
      event: MessageEvent.EligibilityRequest,
      focus: {
        fullUrl: 'urn:uuid:elig',
        resource: { resourceType: 'CoverageEligibilityRequest' },
      },
      supporting: [],
      participants,
      bundleId: 'test-bundle-2',
      timestamp: '2026-08-07T09:00:00Z',
    });
 
    const header = bundle.entry[0].resource as any;
    expect(header.focus[0].reference).toBe('urn:uuid:elig');
  });
});