@cosyte/x12 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -7,8 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Brand lockup on the README, following the reader's colour scheme (ASSETS-P8).** The README now
+  opens with the shared Cosyte lockup, above the `# @cosyte/x12` heading. It is a `<picture>`
+  element: a `<source>` carrying the on-dark cut for `prefers-color-scheme: dark`
+  (`https://cosyte.com/tile/cosyte-lockup-tile-on-dark-1200x300.png`) and an `<img>` carrying the
+  on-light cut as the fallback (`https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png`).
+  Both were verified `200` / `image/png` before landing. On GitHub a dark-mode reader gets the dark
+  cut; on npm the `<img>` is lifted out of the `<picture>` by the surrounding anchor so the light cut
+  renders, which is correct there because npmjs.com has no dark mode. The heading and the blockquote
+  under it are unchanged: the lockup reads "Cosyte" while the heading reads `@cosyte/x12`, so the two
+  strings do not collide and nothing is duplicated. The alt text describes the artwork rather than
+  the package, since that is what a screen reader announces on the npm page and what a reader gets if
+  the image fails to load.
+
+  **Recorded because it changed inside the unreleased window rather than after it.** This entry first
+  landed describing a _per-package_ banner (`cosyte-banner-x12-1200x300.png`), which baked the
+  package name and the tagline into pixels and duplicated the two lines beneath it. It explicitly
+  chose a plain markdown image over an `<img>` or a `<picture>` pair, on the ground that whether
+  npm's markdown sanitizer preserves `<picture>` was unverified. That was an accurate statement of
+  what was known at the time. It has since been measured on a published package page: the sanitizer
+  keeps the `<picture>`, and the anchor wrapper hoists the `<img>` out of it, so the light cut
+  renders. The per-package banner was replaced before any release carried it, so no published
+  version of this package ever had it, and this is written as one change rather than an addition
+  followed by a replacement. The superseded reason is kept here rather than removed, because a
+  record that quietly flips a stated reason is worse than one that shows the correction.
+
 ### Fixed
 
+- **Stale version claim removed from five public pages (ASSETS-P8).** `README.md`,
+  `KNOWN-LIMITATIONS.md`, `docs-content/intro.md`, `docs-content/installation.md`, and
+  `docs-content/troubleshooting.md` all asserted the package was "published on npm at `0.0.1`". The registry says
+  `0.0.2`. The literal was pinned by a previous docs sweep and went stale on the very next release,
+  so it is now removed rather than re-pinned: the npm badge renders the live version on the README,
+  and each page points at `npm view @cosyte/x12 version` as the source of truth. Docs only, no
+  runtime or public-API change.
+- **Scope claim corrected: the 270 and 276 inquiries have no typed model (ASSETS-P8).** The README
+  status line and "What's inside" list, and `docs-content/intro.md`, claimed "the full v1 read scope
+  (270/271, 276/277/277CA, …) and emit scope … are complete". There is no `get270` / `get276` reader
+  and no `build270` / `build276` builder, and no 270 or 276 dispatch anywhere in `src/`;
+  `get271Eligibility` and `get277Status` return `undefined` for any other `ST-01`. The inquiry
+  directions parse into segments and dot-paths like any other X12 input but decode into no typed
+  model. The claim is now stated per transaction on every page that made it: the README status line
+  and "What's inside" list, `docs-content/intro.md` (both the status block **and** the "transaction
+  sets it covers" list under it), `docs-content/spec-notes-transaction-sets.md` (the lead-in and the
+  `270 / 271` + `276 / 277` rows of the reader/builder map), and `docs-content/cookbook.md`, which
+  said the 270 was "a read-only surface" when it has no reader either. The gap is recorded in
+  `KNOWN-LIMITATIONS.md`, `docs-content/troubleshooting.md`, and this repo's `CLAUDE.md`. Docs only,
+  no runtime or public-API change.
+- **Serializer description corrected to its actual defaults (ASSETS-P8).** The README described "a
+  strict, spec-clean serializer with recomputed envelope counts", which reads as default behaviour,
+  and `CLAUDE.md` said the serializer "always emits spec-clean X12". `serializeX12` is byte-faithful
+  by default; `{ specClean: true }` reconciles the envelope, and the corrected counts need
+  `{ specClean: true, recomputeCounts: true }` together, because `recomputeCounts` is inert on its
+  own (`const recompute = specClean && opts.recomputeCounts === true`). A mismatch is always warned
+  and never silently corrected. Docs only, no runtime or public-API change.
+- **PHI claim narrowed to what the library actually guarantees (ASSETS-P8).** The README said
+  "warnings/errors that carry codes and positions but never patient data". Warning messages and
+  builder refusals are PHI-free by construction, but `X12ParseError.snippet` is a bounded (≤ 64
+  character) copy of the offending input, so on real traffic it can carry PHI, and the library does
+  not redact it. That was documented in the source JSDoc and nowhere a consumer reads. The README now
+  states the exception, and it is written up in `KNOWN-LIMITATIONS.md` and
+  `docs-content/troubleshooting.md`. Docs only, no runtime or public-API change.
 - **Developer-docs publish status corrected to the published reality (README-ORG-SWEEP).** The
   docs.cosyte.com pages (`docs-content/intro.md`, `installation.md`, `troubleshooting.md`) and
   `KNOWN-LIMITATIONS.md` still said "not yet published to npm" / "gated on the coordinated public

package/README.md

@@ -1,15 +1,20 @@
+<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, **published on npm at `0.0.1`**, on the `0.0.x`-until-first-alpha ladder, from a public repo. 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. Pre-alpha means the public API may still move before `0.1`. Pin an exact version.
+> **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
 
@@ -36,11 +41,11 @@ That's the pitch: no schema upload, no spec knowledge. The parser accepts vendor
 
 ## 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.
+- **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, and warnings/errors that carry codes and positions but never patient data.
+- **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.
 

package/dist/index.cjs

@@ -9590,7 +9590,7 @@ var profiles = Object.freeze({
 });
 
 // src/index.ts
-var VERSION = "0.0.2";
+var VERSION = "0.0.3";
 
 exports.ACK_BUILD_ERROR_CODES = ACK_BUILD_ERROR_CODES;
 exports.AUTH_278_BUILD_ERROR_CODES = AUTH_278_BUILD_ERROR_CODES;