@cosyte/x12 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,11 +1,43 @@
 # Changelog
 
-All notable changes to `@cosyte/x12` will be documented in this file.
+## 0.1.4
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+### Patch Changes
 
-## [Unreleased]
+- ab10959: The README now has Documentation, Support, and Security sections, says CI tests Node.js 22, 24, and 26, and links the full documentation on docs.cosyte.com. No code changes.
+
+## 0.1.3
+
+### Patch Changes
+
+- 17bdb42: Fixed three doc errors: three type comments gave the 835 remit balance with the PLB amounts added, where the parser and `build835` subtract them, the PLB adjustment type said its reason code held the whole composite, and the README named `parseDocumentDate`, which the package does not export.
+
+  The remit balance now reads BPR-02 equals the sum of the claim payments (CLP-04) minus the sum of the PLB amounts, each in its raw sign, on `X12Decimal`, `X12RemitPaymentHeader`, and `X12RemitProviderAdjustment`. The claim and service-line balances on `X12Decimal` and `X12RemitServiceLine` now match the checks too. `X12RemitProviderAdjustment` now says `reasonCode` is the first component of the PLB reason composite (`WO`) and `subCode` the second (`123456`), as the parser stores them. The README, the cookbook, and the date conversion comments now name `checkCarcValidity` and `checkRarcValidity`, the exported date-aware queries that throw an `X12CodeListError` on a document date they refuse. No code, type, or behavior changes.
+
+- dca2a3b: The README and documentation now use US spelling and serial commas, and write pauses without spaced hyphens.
+
+  The README's Status section names the 0.1 release line instead of an exact version, and the version script keeps that line current when a new minor line opens. The README states the Node.js support as 22 or later and tested on 22 and 24, links the license and trademarks files by absolute URL, and points at the organization's contributing guide and code of conduct. Every documentation page now carries a description, page titles say "and" instead of "&", and the sidebar category reads "Core concepts". No code, type, or behavior changes.
+
+## 0.1.2
+
+### Patch Changes
+
+- Doc comments now write number ranges with "to" instead of an en dash.
+
+## Released before this file was generated
+
+Every release section above this heading is written by
+[Changesets](https://github.com/changesets/changesets) from the changesets in `.changeset/`, newest
+release first. The release writes its own version heading, so nothing above this line is maintained
+by hand, and a change is recorded by adding a changeset rather than by editing this file. The 0.1.2
+section was filled in from that release's GitHub release notes when generation was turned on, since
+0.1.2 shipped while this file was still kept by hand and it was never written here.
+
+Everything below this heading was maintained by hand, in the
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format, and is left as it was written. Two
+things were dropped: the preamble above it, which said the file was kept by hand, and an empty
+`[Unreleased]` heading. The `[0.1.0]` section holds every entry written before the first 0.1
+release, the `0.0.x` releases included, which the file never recorded one by one.
 
 ## [0.1.1] - 2026-10-07
 

package/KNOWN-LIMITATIONS.md

@@ -276,7 +276,7 @@ model.
   `X12_837_UNKNOWN_VARIANT` accused a document that was not non-conformant. The reader now recognises
   each base guide and each of its published errata. Sources for every key are named beside the table
   in `src/transactions/claim/get-837.ts` and in
-  `documentation/agent-notes/x12-variant-icr-ungrounded.md`.
+  `documentation/agent-notes.md#x12---grounding-variant_by_icr-x12-variant-icr-ungrounded-2026-08-08`.
   - **🛑 What this changes for a consumer, and it is a behaviour change on already-published
     decoding.** On a file whose `ST-03` is now recognised: `submission.variant` can differ from what
     `0.0.13` read, where the first `SVx` in the body disagreed with the declaration; and

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Cosyte
+Copyright (c) 2026 Cosyte LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -7,12 +7,12 @@
 
 # @cosyte/x12
 
-> Read the money out of an 835, an 837 or a 271 without a TR3 open on your desk.
+> Read the money out of an 835, an 837, or a 271 without a TR3 open on your desk.
 
 [![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/cosyte/x12/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org)
 
 Developer-focused ASC X12 healthcare EDI parser, serializer, and builder for Node.js and TypeScript: lenient on parse, spec-clean on emit.
 
@@ -20,7 +20,7 @@ Developer-focused ASC X12 healthcare EDI parser, serializer, and builder for Nod
 
 Reading an X12 healthcare transaction correctly normally means buying the TR3 implementation guide
 for it and then hand-mapping element positions that no compiler will ever check. This library
-removes that step for the engineer who has one 835 to post, one 271 to answer or one 837 to send,
+removes that step for the engineer who has one 835 to post, one 271 to answer, or one 837 to send,
 and who needs the amounts to be exactly right rather than approximately right. The nearest
 alternatives are a general-purpose EDI translator, which frames segments correctly but knows nothing
 about what CLP-04 means, and a hand-rolled split on the segment terminator, which works until the
@@ -31,17 +31,18 @@ a stable code instead of failing or guessing.
 
 ## Status
 
-**Version 0.1.2**, published on npm from a public repository.
+**The 0.1 line**, published on npm from a public repository.
 
-From `0.1.0` the public API is settled and safe to depend on: the exported readers, builders,
+On the 0.1 line the public API is settled and safe to depend on: the exported readers, builders,
 types and warning codes are the surface we keep stable, and the warning registry only ever gains
 codes. Below 1.0 a breaking change bumps the minor version and is called out in the changelog with
-its migration. On a `0.0.x` version, pin an exact version rather than a range. Typed read and typed
-emit both ship for every transaction set
-this package covers: 270, 271, 276, 277 and 277CA, 278 request and response, 820, 834, 835, 837P,
-837I and 837D, 999 and TA1, each with a reader and a matching domain builder, and the two claims
-attachments guides 45 CFR 162.2002 adopts for the period on and after 26 May 2028: the 277 request
-for additional information (`006020X313`) and the 275 that answers it (`006020X314`). For those two the base X12 006020
+its migration. On an older 0.0 release, pin an exact version rather than a range.
+
+Typed read and typed emit both ship for every transaction set this package covers: 270, 271, 276,
+277 and 277CA, 278 request and response, 820, 834, 835, 837P, 837I and 837D, 999 and TA1, each
+with a reader and a matching domain builder, and the two claims attachments guides 45 CFR 162.2002
+adopts for the period on and after May 26, 2028: the 277 request for additional information
+(`006020X313`) and the 275 that answers it (`006020X314`). For those two the base X12 006020
 structure is typed and no implementation-guide usage is checked, so a qualifier or segment the
 guide requires is carried as sent and never validated; `KNOWN-LIMITATIONS.md` lists what else
 they leave open. `X12_TR3_CONFORMANCE` is the machine-readable answer to which implementation
@@ -60,15 +61,15 @@ pnpm add @cosyte/x12
 
 `npm install @cosyte/x12` and `yarn add @cosyte/x12` work the same way.
 
-Node `>=22.0.0` is the engine floor, and there are zero runtime dependencies. The package ships
-dual ESM and CJS builds with type declarations for both conditions, so `import` and `require` each
-resolve to the artifact meant for them.
+Node.js 22 or later, tested on 22, 24, and 26: the engine floor is `>=22.0.0`, and there are zero
+runtime dependencies. The package ships dual ESM and CJS builds with type declarations for both
+conditions, so `import` and `require` each resolve to the artifact meant for them.
 
 ## Usage
 
 Parse an 835 remittance advice and read the money: the payment total, the claim's
 charge/paid/patient-responsibility split, and the adjustment reason behind the difference. The
-interchange below is synthetic, with a fabricated payer, provider, patient and amounts.
+interchange below is synthetic, with a fabricated payer, provider, patient, and amounts.
 
 ```ts runnable
 import { parseX12, get835 } from "@cosyte/x12";
@@ -139,38 +140,6 @@ warnings 0
 The `groupCode` is what tells you who owes the money (`PR` patient responsibility, `CO` contractual
 obligation, and so on). Read it; never infer it.
 
-## PHI and safety
-
-X12 healthcare transactions carry protected health information, so treat every interchange you hand
-this library as PHI.
-
-**What it does with your document.** It decodes it in memory and nothing else. No socket is opened,
-nothing is written to disk, and nothing is fetched at run time: the bundled code lists are versioned
-data snapshots, so updating one is a release rather than a network call. The acknowledgment builders
-are pure functions and never auto-send.
-
-**What it keeps out of diagnostics.** A warning `message` is a lookup into a frozen registry rather
-than something built from your document, and no warning factory in this library takes a value
-parameter, so no element of yours can reach a diagnostic. The code and the `position` say what and
-where; the bytes stay on the model. `ALL_WARNING_MESSAGES` is exported so you can assert that.
-
-**The one deliberate exception.** `X12ParseError.snippet` on the four structural fatals is a bounded
-copy of the start of the input, so on real traffic it can carry PHI, and it is not redacted. Log
-`err.code` and `err.position` instead, or redact at your call site.
-
-**An attachment refuses to print.** The data of each BDS a 275 carries is read into
-`X12AttachmentData`, whose string, JSON and `util.inspect` forms state its octet count and nothing
-else; `readOctets()` is the one route to the octets.
-
-**Builder refusals are a weaker surface, deliberately.** A `build*` refusal names the control
-number, count or code you passed in, so that you can see what was refused. The rendered fragment is
-bounded by an exported constant, but it is bounded rather than redacted. The two attachments
-builders are the exception and name no value at all. Log `err.code`, not `err.message`, from a
-builder.
-
-**What you still own.** Transport, storage, retention, access control, audit logging, and every log
-line your own code writes. This library makes no HIPAA compliance claim on your behalf.
-
 ## API
 
 Everything ships from one entry point; there are no subpath imports.
@@ -184,7 +153,7 @@ Everything ships from one entry point; there are no subpath imports.
   (`X12_NO_ISA_HEADER`, `X12_ISA_TOO_SHORT`, `X12_INVALID_DELIMITERS`, `X12_EMPTY_INPUT`).
   Everything else arrives on `ix.warnings` as a stable code with positional context, so a tolerated
   deviation is visible rather than silent.
-- **Money.** Every monetary, percent and quantity field decodes as `X12Decimal`, which is
+- **Money.** Every monetary, percent, and quantity field decodes as `X12Decimal`, which is
   string-backed with BigInt arithmetic, and this library never **`parseFloat`s** an EDI amount. A
   slot the sender left empty reads `undefined` rather than zero, so "stated zero" and "stated
   nothing" stay different readings.
@@ -201,7 +170,7 @@ Task-oriented recipes are in the [cookbook](./docs-content/cookbook.md), and
 ### Dates and times
 
 Every typed reader surfaces its dates verbatim, as the qualifier the sender used plus the bytes it
-carried. `toObject`, `toISO` and `toDate` are the three ways to read one, and every `@cosyte/*`
+carried. `toObject`, `toISO`, and `toDate` are the three ways to read one, and every `@cosyte/*`
 parser exports the same three names with the same shapes and the same timezone rule.
 
 ```ts
@@ -247,10 +216,10 @@ than the JavaScript `Date` 0 to 11, so `Object.keys()` of the result tells you t
 `DateTime.fromObject` with no renaming. Neither library is a dependency here; this package still has
 zero of those.
 
-`parseDocumentDate`, which reads the document date for the date-aware code-list queries, keeps its
-own contract and still THROWS on input it refuses. That divergence is deliberate: it answers a
-caller who asked a validity question and could not state the day, while these three read a document
-that was already parsed leniently.
+The date-aware code-list queries, `checkCarcValidity` and `checkRarcValidity`, keep their own
+contract and still THROW an `X12CodeListError` on a document date they refuse. That divergence is
+deliberate: they answer a caller who asked a validity question and could not state the day, while
+these three read a document that was already parsed leniently.
 
 #### Using two @cosyte parsers in one file
 
@@ -269,38 +238,106 @@ A namespace import works too: `import * as x12 from "@cosyte/x12"`, then `x12.to
 ## Compatibility
 
 - **005010 HIPAA transaction sets**, with hooks for the errata revisions the industry actually
-  exchanges. Non-healthcare sets such as 850, 856, 810 and 204, plus EDIFACT, AS2 and SFTP
+  exchanges. Non-healthcare sets such as 850, 856, 810, and 204, plus EDIFACT, AS2, and SFTP
   transport, and pre-005010 revisions, are out of scope.
 - **Vendor deviations become warnings, not exceptions.** Built-in profiles record whose
   companion-guide deviation they accommodate; selecting one never changes an otherwise correct
   parse, and profiles are authored through the same public `defineProfile()` API you have.
 - **Round trips are not byte-exact in general.** `serializeX12` reproduces the segments on the model
-  verbatim, including element padding, composites and `?`-release escapes, but
+  verbatim, including element padding, composites, and `?`-release escapes, but
   **`serialize(parse(s)) === s` is not guaranteed in general**. Line breaks between segments are the
   common case: any run of CR or LF between segments is absorbed at parse, so a pretty-printed file
   emits compact. Most of the constructs that break a round trip are silent, so "my file has no line
   breaks" is not sufficient either. [KNOWN-LIMITATIONS.md](./KNOWN-LIMITATIONS.md) is the canonical
   list.
 
+## Documentation
+
+The full documentation lives at [docs.cosyte.com/x12](https://docs.cosyte.com/x12), built from this
+repository's [`docs-content/`](https://github.com/cosyte/x12/tree/main/docs-content). Start with
+these pages:
+
+- [Quickstart](https://github.com/cosyte/x12/blob/main/docs-content/quickstart.md): read an 835
+  and pull out the payment, each claim's money, and the adjustment reasons.
+- [The 80/20 transaction sets](https://github.com/cosyte/x12/blob/main/docs-content/spec-notes-transaction-sets.md):
+  every transaction set this package covers, with its reader and its builder.
+- [Decimal-exact money](https://github.com/cosyte/x12/blob/main/docs-content/spec-notes-money.md):
+  why every amount is an `X12Decimal` and never a JavaScript number.
+- [Building and serializing X12](https://github.com/cosyte/x12/blob/main/docs-content/emit-and-serialize.md):
+  the emit side, from `serializeX12` to the domain builders.
+- [Cookbook](https://github.com/cosyte/x12/blob/main/docs-content/cookbook.md): recipes for the
+  transactions you get handed, each with the code and what comes back.
+- [Troubleshooting](https://github.com/cosyte/x12/blob/main/docs-content/troubleshooting.md): the
+  error model, the common symptoms, and the boundaries this package states on purpose.
+
+## Support
+
+Questions and ideas go to [Discussions](https://github.com/cosyte/.github/discussions), which
+covers every Cosyte repository. Bug reports and trading-partner quirks go to the
+[issue tracker](https://github.com/cosyte/x12/issues), with a synthetic reproduction and never a
+real interchange. The organization's
+[support guide](https://github.com/cosyte/.github/blob/main/SUPPORT.md) has the rest.
+
+## Security
+
+Report a vulnerability privately, as the
+[security policy](https://github.com/cosyte/.github/blob/main/SECURITY.md) describes, never in a
+public issue.
+
+## PHI and safety
+
+X12 healthcare transactions carry protected health information, so treat every interchange you hand
+this library as PHI.
+
+**What it does with your document.** It decodes it in memory and nothing else. No socket is opened,
+nothing is written to disk, and nothing is fetched at run time: the bundled code lists are versioned
+data snapshots, so updating one is a release rather than a network call. The acknowledgment builders
+are pure functions and never auto-send.
+
+**What it keeps out of diagnostics.** A warning `message` is a lookup into a frozen registry rather
+than something built from your document, and no warning factory in this library takes a value
+parameter, so no element of yours can reach a diagnostic. The code and the `position` say what and
+where; the bytes stay on the model. `ALL_WARNING_MESSAGES` is exported so you can assert that.
+
+**The one deliberate exception.** `X12ParseError.snippet` on the four structural fatals is a bounded
+copy of the start of the input, so on real traffic it can carry PHI, and it is not redacted. Log
+`err.code` and `err.position` instead, or redact at your call site.
+
+**An attachment refuses to print.** The data of each BDS a 275 carries is read into
+`X12AttachmentData`, whose string, JSON, and `util.inspect` forms state its octet count and nothing
+else; `readOctets()` is the one route to the octets.
+
+**Builder refusals are a weaker surface, deliberately.** A `build*` refusal names the control
+number, count, or code you passed in, so that you can see what was refused. The rendered fragment is
+bounded by an exported constant, but it is bounded rather than redacted. The two attachments
+builders are the exception and name no value at all. Log `err.code`, not `err.message`, from a
+builder.
+
+**What you still own.** Transport, storage, retention, access control, audit logging, and every log
+line your own code writes. This library makes no HIPAA compliance claim on your behalf.
+
 ## Contributing
 
-Questions, bug reports and trading-partner quirks all belong in
-[GitHub issues](https://github.com/cosyte/x12/issues).
+Bug reports and trading-partner quirks belong in
+[GitHub issues](https://github.com/cosyte/x12/issues), as Support says above.
 
-Pull requests are welcome. A contribution must clear `pnpm typecheck`, `pnpm lint` and `pnpm test`,
-hold the per-directory coverage floors, pass the PHI commit gate (`pnpm phi-scan`) and the prose
-gates (`pnpm check:no-emdash`, `pnpm check:no-internal-refs`), and carry a changeset. Every fixture
-must be synthetic: never open a pull request carrying a real patient's data.
+Pull requests are welcome. The organization's
+[contributing guide](https://github.com/cosyte/.github/blob/main/CONTRIBUTING.md) and
+[code of conduct](https://github.com/cosyte/.github/blob/main/CODE_OF_CONDUCT.md) apply here. A
+contribution must clear `pnpm typecheck`, `pnpm lint`, and `pnpm test`, hold the per-directory
+coverage floors, pass the PHI commit gate (`pnpm phi-scan`) and the prose gates
+(`pnpm check:no-emdash`, `pnpm check:no-internal-refs`), and carry a changeset. Every fixture must
+be synthetic: never open a pull request carrying a real patient's data.
 
 ## 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).
+[TRADEMARKS.md](https://github.com/cosyte/x12/blob/main/TRADEMARKS.md).
 
 ## License
 
-MIT, copyright Cosyte. See [LICENSE](./LICENSE).
+MIT, Copyright (c) 2026 Cosyte LLC. See [LICENSE](https://github.com/cosyte/x12/blob/main/LICENSE).
 
 Built by [Cosyte](https://cosyte.com).

package/dist/index.cjs

@@ -15395,7 +15395,7 @@ var profiles = Object.freeze({
 });
 
 // src/index.ts
-var VERSION = "0.1.2";
+var VERSION = "0.1.4";
 
 exports.AAA_CONDITION_LEVELS = AAA_CONDITION_LEVELS;
 exports.AAA_FOLLOW_UP_ACTION_CODES = AAA_FOLLOW_UP_ACTION_CODES;