heartland-scoring

HEARTLAND Risk Score engine — a pragmatic, dependency-free TypeScript implementation of the risk stratification heuristic from the HEARTLAND Protocol for primary care-led heart failure management in rural and resource-limited settings.

Not a medical device. Intended for healthcare professionals as a clinical decision support resource. Does not provide medical diagnoses or treatment recommendations. Not FDA-cleared, not HIPAA-certified. See LICENSE for the full disclaimer.

Why this package?

The HEARTLAND Protocol publishes a clinical implementation toolkit for rural heart failure management. Existing risk scores (MAGGIC, GWTG-HF, SHFM) are prognostic and omit distance to care and social support — two variables with robust prognostic relevance in rural US settings. HEARTLAND fills that gap with 10 binary variables, a 0-18 score, 3 tiers, and explicit care pathways.

This package lets EHR vendors, clinical decision support platforms, research tools, and custom dashboards compute the score programmatically without adopting the full reference application.

Installation

npm install heartland-scoring
# optionally, for runtime input validation:
npm install zod

Zod is an optional peer dependency. Only needed if you import riskInputSchema. Core scoring has zero runtime dependencies.

Quick start

import { calculateRiskScore } from 'heartland-scoring';

const result = calculateRiskScore({
  ageOver75: true,
  priorHfHospitalization: true,
  egfrBelow45: false,
  elevatedNatriuretic: true,
  sbpBelow100: false,
  diabetes: true,
  lvefBelow30: true,
  ckmStage3or4: false,
  distanceOver50Miles: true,
  livesAloneOrLimitedSupport: true,
});

console.log(result.totalScore);              // 14
console.log(result.tier);                    // 'high'
console.log(result.tierLabel);               // 'High'
console.log(result.carePathway.followUp);    // 'Cardiology input before discharge; 48-hour phone follow-up'
console.log(result.breakdown);               // per-variable contribution array

Risk variables (Protocol v3.3, Table 1)

|-|-|-|-| | Variable | Points | Category | Key | |-|-|-|-| | Age ≥ 75 years | 2 | Clinical | ageOver75 | | Prior HF hospitalization within 6 months | 3 | Clinical | priorHfHospitalization | | eGFR < 45 mL/min/1.73m² | 2 | Laboratory | egfrBelow45 | | BNP ≥ 500 pg/mL or NT-proBNP ≥ 1500 pg/mL | 2 | Laboratory | elevatedNatriuretic | | SBP < 100 mmHg at admission | 2 | Clinical | sbpBelow100 | | Diabetes mellitus | 1 | Comorbidity | diabetes | | LVEF < 30% | 2 | Cardiac | lvefBelow30 | | CKM Stage 3 or 4 | 2 | Comorbidity | ckmStage3or4 | | Distance to cardiology > 50 miles | 1 | Social/Geographic | distanceOver50Miles | | Lives alone or limited social support | 1 | Social/Geographic | livesAloneOrLimitedSupport |

Maximum score: 18 points.

Tiers and care pathways

|-|-|-|-|-| | Score | Tier | Follow-up | Monitoring | Support | |-|-|-|-|-| | 0–4 | low | PCP within 14 days | Basic self-monitoring | Standard discharge | | 5–8 | moderate | PCP within 7 days; 72h telehealth check | Home monitoring | Enhanced bundle | | ≥ 9 | high | Cardiology input before discharge; 48h phone follow-up | CHW or equivalent support | Intensive bundle |

API reference

calculateRiskScore(input: RiskInput): RiskResult

Computes the total score, tier, care pathway, and per-variable breakdown.

classifyTier(score: number): RiskTier

Maps a numeric score (0-18) to a tier ('low' | 'moderate' | 'high').

RISK_VARIABLES: RiskVariable[]

The canonical list of 10 variables with labels, point values, descriptions, and categories. Useful for building forms and documentation programmatically.

TIER_THRESHOLDS: Record<RiskTier, { min: number; max: number }>

Machine-readable tier boundaries.

CARE_PATHWAYS: Record<RiskTier, CarePathway>

Full care pathway text per tier (follow-up, monitoring, support, description).

COMPARISON_TABLE_DATA

Feature-by-feature comparison with MAGGIC, GWTG-HF, and SHFM — useful for publications and internal justification documents.

TIER_COLORS (optional, Tailwind-specific)

Tailwind CSS utility classes per tier (bg, border, badge, text). Ignore this export if you're not using Tailwind.

riskInputSchema (optional, requires zod)

Zod schema for runtime validation of a RiskInput. All fields default to false.

import { riskInputSchema } from 'heartland-scoring';

const parsed = riskInputSchema.parse({ ageOver75: true, diabetes: true });
// parsed has all 10 fields, missing ones defaulted to false

TypeScript types

import type {
  RiskInput,
  RiskTier,
  RiskResult,
  CarePathway,
  ScoreBreakdown,
  RiskVariable,
  RiskInputForm,         // z.output<typeof riskInputSchema>
  RiskInputFormInput,    // z.input<typeof riskInputSchema>
} from 'heartland-scoring';

Module format

• ESM: import { calculateRiskScore } from 'heartland-scoring'
• CJS: const { calculateRiskScore } = require('heartland-scoring')
• TypeScript declarations included for both.

Clinical source

• Protocol: HEARTLAND Protocol v3.3 — Heart failure Evidence-based Access in Rural Treatment, Linking Advanced Network Delivery.
• Publication: Cureus (peer-reviewed, indexed PubMed/PMC/Scopus/Google Scholar).
• Archival DOI: 10.5281/zenodo.18566403
• Author: Vicky Muller Ferreira, MD (ORCID 0009-0009-1099-5690)
• Reference application: heartland-app

Citation

If you use this package in research or clinical work, please cite:

@software{heartland_scoring_2026,
  author       = {Muller Ferreira, Vicky},
  title        = {heartland-scoring: Risk Score Engine for Rural
                  Heart Failure Management},
  year         = 2026,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.18566403},
  url          = {https://github.com/vickymuller-md/heartland-scoring}
}

Status

The HEARTLAND Risk Stratification Framework is a pragmatic heuristic derived from the published protocol. It has not yet been validated against prospective clinical outcomes data. Formal validation is an explicit next step defined in the research roadmap. Treat the score as decision-support guidance, not as a validated prognostic tool.

License

MIT — with an explicit "not a medical device" notice.

Contributing

Issues and pull requests welcome at github.com/vickymuller-md/heartland-scoring. Clinical logic changes must cite the corresponding section of Protocol v3.3 or propose a protocol amendment.