@cosyte/x12 0.0.1 → 0.0.3

package/README.md

@@ -1,24 +1,29 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://cosyte.com/tile/cosyte-lockup-tile-on-dark-1200x300.png">
+  <img alt="Cosyte: a plus mark set in two overlapping rounded squares, one solid and one outlined, beside the Cosyte wordmark" src="https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png">
+</picture>
+
 # @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.
+> Parse real-world, vendor-quirky ASC X12 healthcare EDI (835 remits, 837 claims, 271 eligibility responses, 277/277CA status, 278, 820, 834, 999/TA1) and pull the fields you need without reading a TR3.
 
 [![npm version](https://img.shields.io/npm/v/@cosyte/x12.svg)](https://www.npmjs.com/package/@cosyte/x12)
 [![CI](https://img.shields.io/github/actions/workflow/status/cosyte/x12/ci.yml?branch=main&label=CI)](https://github.com/cosyte/x12/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
 
-A developer-focused ASC X12 EDI parser and utility library for Node.js and TypeScript — the payer-side sibling of [`@cosyte/hl7`](https://github.com/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.
+A developer-focused ASC X12 EDI parser and utility library for Node.js and TypeScript: the payer-side sibling of [`@cosyte/hl7`](https://github.com/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: every domain builder emits spec-clean X12 by construction, and the general serializer does so on request.
 
-> **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.
+> **Status:** pre-alpha, **published on npm** from a public repo, on the `0.0.x`-until-first-alpha ladder. `npm view @cosyte/x12 version` is the source of truth for the current version and this page does not restate it; the badge above is a convenience, not the record. Typed **read** and **emit** support is complete for 271, 277/277CA, 278 (request + response), 820, 834, 835, 837P/I/D, 999, and TA1: every one of those has both a per-transaction reader and a matching domain builder, on top of a general serializer and interchange builder. The **270** and **276** inquiry directions do not: they parse into segments and dot-paths like any other X12, but nothing decodes them into a typed model yet. Pre-alpha means the public API may still move before `0.1`. Pin an exact version.
 
 ## Quickstart
 
 ```bash
-# pnpm (recommended) — also works with: npm install @cosyte/x12  |  yarn add @cosyte/x12
+# 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:
+Parse an 835 remittance advice and read the money, three lines of useful output, no TR3 lookup:
 
 ```ts
 import { parseX12, get835 } from "@cosyte/x12";
@@ -27,25 +32,30 @@ 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)
+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 `parseFloat`s** 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.
+- **Typed read + emit, per transaction**: 271, 277/277CA, 278, 820, 834, 835, 837P/I/D, plus 999/TA1 acknowledgments. Per-transaction helpers (`get835`, `get837Claims`, `get271Eligibility`, …) and a matching domain builder for each (`build835`, `build837P/I/D`, `build271`, …). The 270 and 276 inquiries parse as generic segments; they have no typed model yet.
+- **Postel's Law**: a lenient parser (deviations → warnings with a stable code + positional context) and a conservative serializer. `serializeX12` is byte-faithful by default; `{ specClean: true }` reconciles the envelope, and `{ specClean: true, recomputeCounts: true }` also emits the corrected counts (`recomputeCounts` does nothing on its own). A mismatch is always warned, never silently corrected. 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 `parseFloat`s** 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, warning messages that carry a code and a position but never patient data, and builder refusals that carry structural locators and numeric totals only. **The one deliberate exception:** `X12ParseError.snippet` is a bounded (≤ 64 character) copy of the offending input, so on real traffic it can carry PHI. The library does not redact it. Redact at your call site, or log `err.code` and `err.position` instead.
 
 See the [**Cookbook**](./docs-content/cookbook.md) for task-oriented recipes (post an 835, route 277CA rejections, round-trip a 271, walk an 837, read a 999) and [**KNOWN-LIMITATIONS.md**](./KNOWN-LIMITATIONS.md) for the honest do-not-over-trust list.
 
+## Trademarks
+
+Availity and Blue Cross Blue Shield are trademarks of their respective owners. cosyte is not affiliated with, endorsed by, or
+sponsored by any of them. The names identify the trading partners whose companion-guide deviations the built-in profiles accommodate. See [TRADEMARKS.md](./TRADEMARKS.md).
+
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT. See [LICENSE](./LICENSE).
 
 Built by [Cosyte](https://cosyte.com).

package/TRADEMARKS.md

@@ -0,0 +1,31 @@
+# Trademarks
+
+`@cosyte/x12` is an independent open-source project. cosyte is **not affiliated with, endorsed by,
+or sponsored by** any company named in this repository or its documentation.
+
+## Why these names appear
+
+Clearinghouses and payers publish companion guides that deviate from the base X12 implementation
+guide. A profile records whose deviation it accommodates, which cannot be said without naming
+them.
+
+Every reference is **descriptive**: it identifies whose companion-guide deviation a profile accommodates, and nothing more. Naming a system is the only way to say
+whether a library works with it.
+
+## Where the profiles come from
+
+The built-in profiles are authored through this package's own public `defineProfile()` API and are
+grounded in **synthetic** fixtures written from scratch. No real payer or clearinghouse file was
+used to produce them. They are descriptive only: selecting a profile never changes a correct
+parse. They embed no privileged, confidential, or reverse-engineered material.
+
+## Names referenced
+
+| Name                          | Where it appears                                                                              |
+| ----------------------------- | --------------------------------------------------------------------------------------------- |
+| Availity                      | `profiles.availity`: a built-in profile name                                                  |
+| Blue Cross Blue Shield (BCBS) | `profiles.bcbsCommon`: a built-in profile name, and descriptive use in documentation examples |
+
+All product names, logos, and brands are the property of their respective owners. Use of a name here
+does not imply any affiliation with, or endorsement by, its owner. If you own one of these marks and
+would like a reference changed, please open an issue.