بناء تكامل نفيس FHIR بلغة TypeScript: الأهلية والمطالبات وتتبّع الرفض

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
 
/** المجالات المعيارية لنفيس، وفق دليل تطبيق الخدمات المالية الصحية. */
export const NPHIES = {
  CS: 'http://nphies.sa/terminology/CodeSystem',
  SD: 'http://nphies.sa/fhir/ksa/nphies-fs/StructureDefinition',
} as const;
 
/** رموز أحداث الرسائل — وهي التي تحدّد نوع المعاملة. */
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 {
  /** ترخيص المنشأة، أي القيمة الصادرة عند التأهيل. */
  providerLicense: string;
  providerBaseUrl: string;
  /** معرّف ترخيص شركة التأمين لهذه المعاملة. */
  insurerLicense: string;
}
 
interface BundleEntry {
  fullUrl: string;
  resource: Record<string, unknown>;
}
 
/**
 * يبني حزمة رسالة نفيس.
 *
 * يُولَّد MessageHeader داخليًا ويُوضع دائمًا في المقدّمة،
 * فلا يستطيع المستدعي إعادة ترتيبه عن طريق الخطأ.
 */
export function buildMessageBundle(opts: {
  event: MessageEventCode;
  /** المورد الذي يشير إليه MessageHeader عبر focus. */
  focus: BundleEntry;
  /** كل مورد داعم: Patient و Coverage والمنظمات وغيرها. */
  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 يخبر المستقبِل بالمورد الذي هو موضوع الرسالة
      focus: [{ reference: focus.fullUrl }],
    },
  };
 
  return {
    resourceType: 'Bundle' as const,
    id: bundleId,
    meta: { profile: [`${NPHIES.SD}/bundle`] },
    type: 'message' as const,
    timestamp,
    // يُوضع الرأس في المقدّمة هنا، دون شرط.
    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')),
    // لا تعطّل التحقّق من الشهادة أبدًا، ولا حتى في البيئة
    // التجريبية. إذا فشلت المصافحة، أصلح سلسلة الثقة.
    rejectUnauthorized: true,
  },
  // التخزين وإعادة التوجيه يعني أن بطء الاستجابة أمر طبيعي لا استثنائي.
  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;
  /** رقم الهوية الوطنية أو الإقامة للمريض. */
  patientIdentifier: string;
  patientId: string;
  coverageId: string;
  memberId: string;
  /** تاريخ ISO، مثل "2026-08-07" — تاريخ الخدمة. */
  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 مصفوفة — قد تطلب أكثر من غرض واحد بشكل مشروع.
      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;
 
  // الطبقة 2: نفيس رفضت الرسالة نفسها.
  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,
      })),
    };
  }
 
  // الحالة الخاصة: نفيس ردّت نيابةً عن شركة التأمين.
  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) {
    // استجابات الأهلية وغير المطالبات تصل إلى هنا.
    return { layer: 'adjudication', ok: true, outcome: 'complete' };
  }
 
  // "queued" تعني أن التسوية لم تحدث بعد. استعلم عنها.
  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',
  };
}
 
/** يستخرج أسباب الرفض من التسوية على مستوى البند وعلى مستوى الرأس معًا. */
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,
        });
      }
    }
  }
 
  // أخطاء مستوى الرأس تنطبق على المطالبة كاملة، لا على بند واحد.
  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: string;
  codeSystem: string;
  quantity: number;
  unitPrice: number;
  /** أرقام تسلسل التشخيصات التي يُبرَّر بها هذا البند. */
  diagnosisSequence: number[];
}
 
export interface ClaimDiagnosis {
  sequence: number;
  /** رمز 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);
}
 
/**
 * يستعلم بتراجع أسّي، مع سقف.
 *
 * يُرجع null عند نفاد الميزانية — وهي نتيجة مشروعة تعني
 * "لا جواب بعد"، وليست خطأً يُبتلع.
 */
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 ثوانٍ، 10، 20، 40، 80 — بسقف دقيقتين.
      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[] };
  // استجابة استعلام تحتوي MessageHeader فقط تعني "لا شيء بالانتظار".
  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 لرفض مستوى الرأس
  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);

-- التقرير الذي لم تحصل عليه الإدارة المالية من قبل.
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');
  });
});