@cosyte/x12

Parse real-world, vendor-quirky ASC X12 healthcare EDI — 835 remits, 837 claims, 270/271 eligibility, 276/277 status, 278, 820, 834, 999/TA1 — and pull the fields you need without reading a TR3.

A developer-focused ASC X12 EDI parser and utility library for Node.js and TypeScript — the payer-side sibling of @cosyte/hl7. Zero runtime dependencies, dual ESM/CJS, strict types. Lenient on the way in (vendor deviations become warnings, not exceptions), spec-clean on the way out.

Status: pre-alpha (0.0.x, not yet published to npm). The full v1 read scope (270/271, 276/277/277CA, 278, 820, 834, 835, 837P/I/D, 999, TA1) and emit scope (per-transaction domain builders + a general serializer) are complete and hardened; the first npm publish is gated on the coordinated public launch.

Quickstart

# pnpm (recommended) — also works with: npm install @cosyte/x12  |  yarn add @cosyte/x12
pnpm add @cosyte/x12

Parse an 835 remittance advice and read the money — three lines of useful output, no TR3 lookup:

import { parseX12, get835 } from "@cosyte/x12";

const ix = parseX12(rawEdi); // never throws except on 4 structural fatals
const tx = ix.groups[0]?.transactions.find((t) => t.st.elements[1] === "835");
const remit = tx ? get835(ix.delimiters, tx) : undefined;

remit?.payment.totalActualPayment.toString(); // "450.00" — BigInt-exact, never a float
remit?.claims[0]?.patientControlNumber; // "PT-ACCT-001" — your account number, echoed back
remit?.claims[0]?.serviceLines[0]?.adjustments[0]?.reasonCode; // "1" — CARC (why it was adjusted)

That's the pitch: no schema upload, no spec knowledge. The parser accepts vendor-quirky input by default and flags what it tolerated with stable warning codes; you reach for strict mode, dot-paths, profiles, or the emit builders when you want them.

What's inside

• Every v1 HIPAA transaction, read + emit — 270/271, 276/277/277CA, 278, 820, 834, 835, 837P/I/D, plus 999/TA1 acknowledgments. Per-transaction helpers (get835, get837Claims, get271Eligibility, …) and domain builders (build835, build837P/I/D, build271, …).
• Postel's Law — a lenient parser (deviations → warnings with a stable code + positional context) and a strict, spec-clean serializer with recomputed envelope counts. Only 4 structural failures are ever fatal.
• Money is exact — every monetary/percent/quantity field decodes as X12Decimal (string-backed, BigInt arithmetic). The library never parseFloats an EDI amount.
• Safety-critical fidelity — TRN reassociation traces, 835 balance invariants, 837 HL hierarchy integrity, 834 maintenance types, and 278 certification actions are preserved verbatim and never inferred; ambiguity yields a warning or a typed refusal, never a confident wrong answer.
• PHI-disciplined — synthetic-only fixtures, a PHI commit-gate, and warnings/errors that carry codes and positions but never patient data.

See the Cookbook for task-oriented recipes (post an 835, route 277CA rejections, round-trip a 271, walk an 837, read a 999) and KNOWN-LIMITATIONS.md for the honest do-not-over-trust list.

License

MIT — see LICENSE.

Built by Cosyte.