autoicd-js 0.5.1 → 0.7.0

package/README.md

@@ -4,7 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.5+-blue.svg)](https://www.typescriptlang.org/)
 
-Official TypeScript SDK for the [AutoICD API](https://autoicdapi.com) — clinical text to ICD-10-CM diagnosis codes, powered by AI and medical NLP.
+Official TypeScript SDK for the [AutoICD API](https://autoicdapi.com) — AI medical coding that converts clinical text to ICD-10-CM, ICD-11, and ICF codes using medical NLP. Automate ICD-10 coding, ICF functioning classification, and disability assessment in your application.
 
 Zero dependencies. Works in **Node.js 18+**, **Deno**, **Bun**, and **edge runtimes**.
 
@@ -16,8 +16,11 @@ Zero dependencies. Works in **Node.js 18+**, **Deno**, **Bun**, and **edge runti
 
 | | |
 |---|---|
-| **AI-Powered ICD-10 Coding** | Clinical NLP extracts diagnoses from free-text notes and maps them to ICD-10-CM codes — no manual lookup required |
+| **AI-Powered ICD-10, ICD-11 & ICF Coding** | Clinical NLP extracts diagnoses from free-text notes and maps them to ICD-10-CM, ICD-11, or ICF codes — no manual lookup required |
+| **Chart Audit with HCC Gap Capture** | Find missed HCCs, unsupported codes, and specificity upgrades with RAF-weighted revenue estimates (CMS v22 + v28 PY2026). Every finding carries evidence spans |
 | **74,000+ ICD-10-CM Codes** | Full 2025 code set enriched with SNOMED CT synonyms for comprehensive matching |
+| **ICD-11 Support** | Search and look up ICD-11 codes, with full ICD-10 ↔ ICD-11 crosswalk mappings |
+| **ICF Functioning Codes** | Code clinical text to WHO ICF categories, search 1,400+ codes, and access Core Sets for 12+ conditions |
 | **Negation & Context Detection** | Knows the difference between "patient has diabetes" and "patient denies diabetes" — flags negated, historical, uncertain, and family-history mentions |
 | **PHI De-identification** | HIPAA-compliant anonymization of names, dates, SSNs, phone numbers, emails, addresses, MRNs, and ages |
 | **Confidence Scoring** | Every code match includes a similarity score and confidence level so you can set your own acceptance thresholds |
@@ -68,6 +71,51 @@ for (const entity of result.entities) {
 
 ## Features
 
+### Chart Audit (HCC gap capture, RADV defense, specificity, denial risk)
+
+Audit a chart to surface coding gaps, unsupported codes, specificity upgrades, and denial-risk flags in a single call. Every finding carries extractive evidence spans pointing back to the source text, and HCC gaps include RAF-weighted revenue estimates using the CMS PY2026 V22 and V28 community models.
+
+```ts
+const audit = await autoicd.audit({
+  text:
+    "68yo M, type 2 diabetes stable on metformin, chronic systolic heart failure " +
+    "on furosemide, edema controlled. A1c 7.4 today.",
+  codes: [{ code: "E11.9", kind: "icd10" }],
+  capabilities: ["hcc", "radv", "specificity", "denial", "problem_list"],
+  context: {
+    patient: { coverage: "medicare_advantage" },
+    hcc_model: "both",
+  },
+});
+
+console.log(`Missed revenue: $${audit.totals.estimated_revenue_recovery.toFixed(0)}`);
+console.log(`RADV exposure:  $${audit.totals.radv_exposure.toFixed(0)}`);
+
+for (const m of audit.missed) {
+  console.log(
+    `MISSED ${m.code} (${m.hcc_category ?? "non-HCC"} ${m.hcc_model ?? ""}) ` +
+    `→ $${m.estimated_revenue?.toFixed(0) ?? 0}: ${m.description}`
+  );
+  for (const span of m.evidence) {
+    console.log(`    evidence: "${span.quote}" [${span.start}-${span.end}]`);
+  }
+}
+```
+
+| Capability | What it surfaces |
+|---|---|
+| `hcc` | Missed HCC codes with `hcc_category`, `raf_weight`, `estimated_revenue` per v22/v28 model |
+| `radv` | Submitted codes with no supporting documentation, with `what_would_support_it` guidance and exposure dollars |
+| `specificity` | Upgrade opportunities from unspecified to more specific child codes |
+| `denial` | Documentation-quality risk flags (missing laterality, missing duration, age/sex mismatches) |
+| `problem_list` | Deduplicated active-conditions list with status (active/historical) and evidence |
+
+Default behavior runs all five capabilities. Pass `capabilities: ["hcc"]` to run a targeted audit.
+
+> **`hcc_model`:** use `"v22"`, `"v28"`, or `"both"` (default). CMS PY2026 MA payment uses V22 and V28 as the two main community models. V24 is the ESRD-specific model and is not accepted here.
+
+Read more about the Audit endpoint at [autoicdapi.com/audit](https://autoicdapi.com/audit).
+
 ### Automated ICD-10 Medical Coding
 
 Extract diagnosis entities from clinical notes and map them to ICD-10-CM codes. Each entity includes ranked candidates with confidence scores, negation status, and context flags.
@@ -106,10 +154,10 @@ const result = await autoicd.code(
 Search the full ICD-10-CM 2025 code set by description. Perfect for building code lookup UIs, autocomplete fields, and validation workflows.
 
 ```ts
-const results = await autoicd.codes.search("diabetes mellitus");
+const results = await autoicd.icd10.search("diabetes mellitus");
 // results.codes → [{ code: "E11.9", short_description: "...", long_description: "...", is_billable: true }, ...]
 
-const results = await autoicd.codes.search("heart failure", { limit: 5 });
+const results = await autoicd.icd10.search("heart failure", { limit: 5 });
 ```
 
 ### ICD-10 Code Details
@@ -117,7 +165,7 @@ const results = await autoicd.codes.search("heart failure", { limit: 5 });
 Get full details for any ICD-10-CM code — descriptions, billable status, synonyms, hierarchy, and chapter classification.
 
 ```ts
-const detail = await autoicd.codes.get("E11.9");
+const detail = await autoicd.icd10.get("E11.9");
 console.log(detail.code);              // "E11.9"
 console.log(detail.long_description);  // "Type 2 diabetes mellitus without complications"
 console.log(detail.is_billable);       // true
@@ -125,6 +173,71 @@ console.log(detail.synonyms.snomed);   // ["Diabetes mellitus type 2", ...]
 console.log(detail.chapter?.title);    // "Endocrine, Nutritional and Metabolic Diseases"
 ```
 
+### ICD-11 Code Search
+
+Search the ICD-11 code set by description. The AutoICD API includes the full WHO ICD-11 MMS hierarchy.
+
+```ts
+const results = await autoicd.icd11.search("diabetes mellitus");
+// results.codes → [{ code: "5A11", short_description: "...", foundation_uri: "..." }, ...]
+
+const results = await autoicd.icd11.search("heart failure", { limit: 5 });
+```
+
+### ICD-11 Code Details & Crosswalk
+
+Get full details for any ICD-11 code — descriptions, Foundation URI, hierarchy, synonyms, and ICD-10 crosswalk mappings.
+
+```ts
+const detail = await autoicd.icd11.get("5A11");
+console.log(detail.code);              // "5A11"
+console.log(detail.short_description); // "Type 2 diabetes mellitus"
+console.log(detail.foundation_uri);    // "http://id.who.int/icd/entity/1691003785"
+console.log(detail.chapter?.title);    // "Endocrine, nutritional or metabolic diseases"
+
+// ICD-10 crosswalk
+for (const mapping of detail.icd10_mappings) {
+  console.log(`${mapping.code} — ${mapping.description} (${mapping.mapping_type})`);
+  // "E11.9 — Type 2 diabetes mellitus without complications (equivalent)"
+}
+```
+
+### ICD-10 → ICD-11 Crosswalk
+
+ICD-10 code details now include ICD-11 crosswalk mappings when available:
+
+```ts
+const detail = await autoicd.icd10.get("E11.9");
+for (const mapping of detail.icd11_mappings ?? []) {
+  console.log(`${mapping.code} — ${mapping.description}`);
+  // "5A11 — Type 2 diabetes mellitus"
+}
+```
+
+### ICF Functioning Codes
+
+Code clinical text to WHO ICF categories, look up codes, search, and access ICF Core Sets for 12+ conditions.
+
+```typescript
+// Code clinical text to ICF categories
+const icf = await client.icf.code("Patient with stroke and hemiplegia");
+console.log(icf.results[0].codes);
+// [{ code: "b730", description: "Muscle power functions", component: "b", ... }]
+
+// Look up an ICF code
+const code = await client.icf.lookup("d450");
+console.log(code.title); // "Walking"
+console.log(code.definition); // "Moving along a surface on foot..."
+
+// Search ICF codes
+const results = await client.icf.search("mobility");
+
+// Get ICF Core Set for a diagnosis
+const coreSet = await client.icf.coreSet("E11.9");
+console.log(coreSet.conditionName); // "Diabetes Mellitus"
+console.log(coreSet.brief); // [{ code: "b530", title: "Weight maintenance functions", ... }]
+```
+
 ### PHI De-identification
 
 Strip protected health information from clinical notes before storage or analysis. HIPAA-compliant de-identification for names, dates, SSNs, phone numbers, emails, addresses, MRNs, and ages.
@@ -235,8 +348,14 @@ Full REST API documentation at [autoicdapi.com/docs](https://autoicdapi.com/docs
 |--------|-------------|
 | `autoicd.code(text, options?)` | Code clinical text to ICD-10-CM diagnoses |
 | `autoicd.anonymize(text)` | De-identify PHI/PII in clinical text |
-| `autoicd.codes.search(query, options?)` | Search ICD-10-CM codes by description |
-| `autoicd.codes.get(code)` | Get details for an ICD-10-CM code |
+| `autoicd.icd10.search(query, options?)` | Search ICD-10-CM codes by description |
+| `autoicd.icd10.get(code)` | Get details for an ICD-10-CM code (incl. ICD-11 crosswalk) |
+| `autoicd.icd11.search(query, options?)` | Search ICD-11 codes by description |
+| `autoicd.icd11.get(code)` | Get details for an ICD-11 code (incl. ICD-10 crosswalk) |
+| `autoicd.icf.code(text, options?)` | Code clinical text to ICF functioning categories |
+| `autoicd.icf.lookup(code)` | Get details for an ICF code |
+| `autoicd.icf.search(query, options?)` | Search ICF codes by keyword |
+| `autoicd.icf.coreSet(icd10Code)` | Get ICF Core Set for an ICD-10 diagnosis |
 
 ---
 
@@ -255,6 +374,14 @@ import type {
   AnonymizeResponse,
   PIIEntity,
   RateLimit,
+  ICD11CodeDetail,
+  ICD11CodeDetailFull,
+  ICD11CodeSearchResponse,
+  CrosswalkMapping,
+  ICFCodingResponse,
+  ICFCodeDetail,
+  ICFCodeSearchResponse,
+  ICFCoreSetResponse,
 } from "autoicd";
 ```
 
@@ -272,6 +399,8 @@ import type {
 - [AutoICD API](https://autoicdapi.com) — Homepage and API key management
 - [API Documentation](https://autoicdapi.com/docs) — Full REST API reference
 - [ICD-10-CM Code Directory](https://autoicdapi.com/icd10) — Browse all 74,000+ diagnosis codes
+- [ICD-11 Code Directory](https://autoicdapi.com/icd11) — Browse the WHO ICD-11 MMS hierarchy
+- [ICD-10 ↔ ICD-11 Crosswalk](https://autoicdapi.com/icd10-to-icd11) — Map codes between revisions
 - [ICD-10 Codes by Condition](https://autoicdapi.com/icd10/condition) — Find codes for common conditions
 - [Python SDK](https://pypi.org/project/autoicd/) — `pip install autoicd`
 - [MCP Server](https://www.npmjs.com/package/autoicd-mcp) — For Claude Desktop, Cursor, VS Code