@cosyte/x12 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-10-07
+
+**What 0.1.1 means for you.** The 271 now reads and builds the procedure a benefit line applies to
+(EB-13), which dental payers use for per-procedure coinsurance, frequency, age and maximum limits.
+If you build an `X12EligibilityBenefit` object literal yourself, such as a test double, add
+`procedure: undefined` to it. Code that reads benefits from `get271` needs no change.
+
+### Added
+
+- **271 EB-13 read.** Each benefit's `procedure` carries the qualifier (EB-13-1), the code
+  (EB-13-2), up to four modifiers in transmitted order (EB-13-3 to EB-13-6) and the description
+  (EB-13-7) when the sender sent one, and is `undefined` when EB-13 is absent or has no qualifier.
+  Components are split on the component separator the interchange declares in ISA-16. New
+  package-root type export: `X12EligibilityProcedure`.
+- **271 EB-13 emit.** A 271 benefit takes an optional `procedure` (`Build271ProcedureSpec`, a new
+  package-root type export) with a qualifier, a code and modifiers, written as one composite. The
+  builder refuses an empty qualifier or code, an empty modifier, and more than four modifiers: a
+  fifth would land in the description position, and an empty one would shift later modifiers on
+  read. The description is not written.
+- The 270 reader's EQ-02 procedure decodes exactly as before and now shares its decoder with the 271.
+
+## [0.1.0] - 2026-09-25
+
 **What 0.1 means for you.** This release is the first whose public API we treat as settled: the
 exported readers, builders, types and warning codes are the surface we keep stable, and the warning
 registry only ever gains codes. It covers typed read and typed emit for 270, 271, 276, 277 and
@@ -1929,7 +1952,7 @@ required control number and this builder never invents one, so nothing is emitte
   composite. Escaping against a guessed delimiter set is a value corruption rather than a safe
   default: `unescapeRelease` preserves `?X` verbatim for any `X` outside the reader's declared set,
   so a value released against the wrong delimiter comes back carrying a stray `?`. The defaults are
-  unchanged and are the cosyte archetype, which this function cannot verify, so state the separators
+  unchanged and are the Cosyte archetype, which this function cannot verify, so state the separators
   if you embed a TA1 in an envelope that declares different ones.
 
   **A non-string element now refuses** with `AckBuildError` and the existing `X12_ACK_INVALID_SPEC`
@@ -3020,7 +3043,7 @@ string, …` - which `esc` cannot, being unary.
 
 - **Em-dash brand gate in CI (`scripts/check-no-emdash.sh`, `pnpm check:no-emdash`,
   `.github/workflows/no-emdash.yml`; `EMDASH-CONFORMANCE`).** The founder directive of 2026-07-24
-  (`knowledgebase/06-brand/voice-and-tone.md`) bans `U+2014` outright across every cosyte surface
+  (`knowledgebase/06-brand/voice-and-tone.md`) bans `U+2014` outright across every Cosyte surface
   and names commit messages explicitly, and the meta-repo's `documentation/conventions.md` has
   described the rule as CI-gated; x12 was one of the repos where it was not. This ports
   `knowledgebase`'s scanner (the text-only variant, correct here because x12 tracks no binaries:
@@ -3115,7 +3138,7 @@ string, …` - which `esc` cannot, being unary.
 ### Added
 
 - **Trademark notice (`TRADEMARKS.md`).** This package names third-party systems to describe what it
-  interoperates with; the notice records that cosyte is not affiliated with, endorsed by, or
+  interoperates with; the notice records that Cosyte is not affiliated with, endorsed by, or
   sponsored by any of them, that every reference is descriptive, and that the built-in profiles are
   authored from public sources only. Added to `files` so it ships inside the published tarball, not
   just on GitHub. Documentation only, no runtime or API change.
@@ -3769,7 +3792,7 @@ EV/SS`), and HL-04 has-child flag from the nested input tree, so an
     helper). The `X12ClaimNote` JSDoc explicitly flags NTE-02 as
     PHI-bearing (provider-supplied free text). Every Phase 5 fixture
     is synthetic (test names `TEST PATIENT` / `SUB LAST` / `PATIENT
-CHILD`; sequential member IDs `MEMBER001`–`MEMBER011` etc.; NPI-
+CHILD`; sequential member IDs `MEMBER001` to `MEMBER011` etc.; NPI-
     shaped sequential numbers; obvious test addresses) and matches
     the established 835 fixture conventions.
   - **Known limitations after this phase** (deliberate v1 scope; none
@@ -3957,7 +3980,7 @@ refresh:code-lists` arrives in Phase 10); no per-payer profile
 
 - **Phase 3: 999 + TA1 acknowledgments (TR3 005010X231A1).** Two
   pure-function ack surfaces ship side-by-side; neither auto-sends, opens
-  a socket, or touches the filesystem. The cosyte ack archetype: the
+  a socket, or touches the filesystem. The Cosyte ack archetype: the
   library MECHANICALLY builds the disposition it is told and REFUSES to
   fabricate an Accept against a non-empty error list. Mirrors hl7's
   upcoming `buildAck` boundary and mllp's commit-contract pattern.
@@ -3978,7 +4001,7 @@ refresh:code-lists` arrives in Phase 10); no per-payer profile
     a TA1 inside an open functional group is still flagged as unexpected
     (non-spec). `parseTA1(interchange)` returns the typed `X12AckTA1`
     for the first captured TA1 (or `undefined`). `buildTA1(spec)` emits
-    a fixed-position 5-element `Ta1Segment` (`TA101`–`TA105`). Caller
+    a fixed-position 5-element `Ta1Segment` (`TA101` to `TA105`). Caller
     wraps it in their preferred envelope. Both standalone TA1-only
     interchanges (ISA → TA1 → IEA, no GS) and embedded TA1s round-trip.
   - **Safety guards (refused via `AckBuildError`):** `build999` refuses
@@ -3997,7 +4020,7 @@ refresh:code-lists` arrives in Phase 10); no per-payer profile
     `IK3_SYNTAX_ERROR_CODES` (code list 716, 13 codes),
     `IK4_SYNTAX_ERROR_CODES` (code list 723, 18 codes),
     `TA1_ACK_CODES` (code list I13: `A`/`E`/`R`),
-    `TA1_NOTE_CODES` (code list I18: `000`–`028`). String-literal
+    `TA1_NOTE_CODES` (code list I18: `000` to `028`). String-literal
     unions are exported for exhaustive narrowing. The helper
     `isAcceptDisposition(code)` returns true for `A`/`E`/`P` and false
     for the four reject codes.
@@ -4142,7 +4165,7 @@ safety` test blocks assert no SSN / ISO-date / long-digit-run
 
 ### Changed
 
-- Migrated onto the shared cosyte engineering standard (Phase E). The toolchain
+- Migrated onto the shared Cosyte engineering standard (Phase E). The toolchain
   is now inherited from the published `@cosyte/*` config packages instead of
   per-repo copies: `tsup.config.ts` uses `cosyteTsup`, `vitest.config.ts` uses
   `cosyteVitest`, and `eslint.config.js` is the three-line `cosyte` wrapper.

package/KNOWN-LIMITATIONS.md

@@ -672,7 +672,7 @@ model.
     nothing else - `buildTA1` still emits no terminator. Escaping against a guessed set is a value
     corruption rather than a safe default: `unescapeRelease` preserves `?X` verbatim for any `X`
     outside the declared set, so a value released against the wrong delimiter comes back carrying a
-    stray `?`. **The defaults are the cosyte archetype and this function cannot verify them** - if
+    stray `?`. **The defaults are the Cosyte archetype and this function cannot verify them** - if
     you embed a TA1 in an envelope that declares different separators, state them.
   - **A non-string element now REFUSES** with `AckBuildError` / `X12_ACK_INVALID_SPEC`, and that is a
     prerequisite rather than a bonus. Releasing a value means routing it through the escape helper,
@@ -1555,7 +1555,7 @@ N-char spec limit` refusal, one per emitting module, where the branch fires **be
   2. **Whether an `X12Decimal` carries the SCALE you meant.** `fromString("0.3")` and
      `fromString("0.30")` are both accepted and both emit verbatim. That choice is yours.
   3. **The delimiter set `buildTA1` releases against**, per the paragraph above. It defaults to the
-     cosyte archetype and the function cannot verify it; state the separators on `BuildTA1Options`
+     Cosyte archetype and the function cannot verify it; state the separators on `BuildTA1Options`
      if you embed a TA1 in an envelope that declares different ones.
   4. **`build835`'s balance-equation amounts, which refuse UNTYPED.** `build835` runs its balance
      guard before it builds the escape helper, and that guard calls `X12Decimal` methods on your
@@ -1874,10 +1874,10 @@ N-char spec limit` refusal, one per emitting module, where the branch fires **be
     applied and this package applies none.
 - **No transport.** AS2, SFTP, and MLLP-style delivery are out of scope. This is a parser/serializer,
   not a communications stack.
-- **Published, still pre-alpha.** The package is published on npm as `@cosyte/x12` from a public
-  repo, but it stays on the `0.0.x`-until-first-alpha ladder. `npm view @cosyte/x12 version` is the
-  only source of truth for the current version, so this page does not restate one. Treat the API as
-  pre-alpha and pin the exact version until the first alpha.
+- **Below 1.0.** The package is published on npm as `@cosyte/x12` from a public repo, at `0.1`. Its
+  exported readers, builders, types and warning codes are the surface we keep stable, and below 1.0
+  a breaking change bumps the minor version and is called out in the changelog with its migration.
+  `npm view @cosyte/x12 version` is the only source of truth for the current version.
 - **A 276 hierarchical level whose declared parent does not resolve is left off the returned tree.**
   The 276 reader attaches a level by its own HL-02 and by nothing else, so a pointer naming a level
   that is not present, a pointer naming a level of the wrong kind, and a parent chain that returns

package/README.md

@@ -31,7 +31,7 @@ a stable code instead of failing or guessing.
 
 ## Status
 
-**Version 0.1.0**, published on npm from a public repository.
+**Version 0.1.2**, 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,
 types and warning codes are the surface we keep stable, and the warning registry only ever gains
@@ -179,8 +179,7 @@ Everything ships from one entry point; there are no subpath imports.
   transaction set into a typed one (`get835`, `get837Claims`, `get270Inquiry`, `get271Eligibility`,
   `get276StatusInquiry`, `parse999`, `parseTA1`, and the rest).
 - **Emit.** `serializeX12` and `buildInterchange` are the general path, and every transaction set
-  with a reader also has a domain builder (`build835`, `build837P`, `build271`, and the rest) that
-  layers that guide's own invariants on top.
+  with a reader also has a domain builder (`build835`, `build837P`, `build271`, and the rest).
 - **Errors and warnings.** Parsing is lenient, and only **four** structural failures are ever fatal
   (`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
@@ -295,7 +294,7 @@ 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
+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).

package/TRADEMARKS.md

@@ -1,6 +1,6 @@
 # Trademarks
 
-`@cosyte/x12` is an independent open-source project. cosyte is **not affiliated with, endorsed by,
+`@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

package/dist/index.cjs

@@ -6640,6 +6640,26 @@ function validateHl2(hl, index, expectedParentLevel, position, warnings) {
   }
 }
 
+// src/transactions/shared/procedure.ts
+var FIRST_MODIFIER = 3;
+var LAST_MODIFIER = 6;
+var DESCRIPTION = 7;
+function decodeProcedure(seg, elementIndex, delimiters) {
+  const qualifier = componentOptional(seg, elementIndex, 1, delimiters);
+  if (qualifier === void 0) return void 0;
+  const modifiers = [];
+  for (let p = FIRST_MODIFIER; p <= LAST_MODIFIER; p += 1) {
+    const modifier = componentOptional(seg, elementIndex, p, delimiters);
+    if (modifier !== void 0) modifiers.push(modifier);
+  }
+  return Object.freeze({
+    qualifier,
+    code: componentOptional(seg, elementIndex, 2, delimiters),
+    modifiers: Object.freeze(modifiers),
+    description: componentOptional(seg, elementIndex, DESCRIPTION, delimiters)
+  });
+}
+
 // src/transactions/eligibility/get-270.ts
 var INQUIRY_270 = "270";
 var IMPLEMENTED_GUIDES_270 = implementedGuides(INQUIRY_270);
@@ -6968,7 +6988,7 @@ function openInquiry(seg, delimiters) {
   }
   return {
     serviceTypeCodes,
-    procedure: decodeProcedure(seg, delimiters),
+    procedure: decodeProcedure(seg, 2, delimiters),
     coverageLevelCode: elementOptional(seg, 3, delimiters),
     insuranceTypeCode: elementOptional(seg, 4, delimiters),
     diagnosisCodePointers,
@@ -6976,21 +6996,6 @@ function openInquiry(seg, delimiters) {
     dates: []
   };
 }
-function decodeProcedure(seg, delimiters) {
-  const qualifier = componentOptional(seg, 2, 1, delimiters);
-  if (qualifier === void 0) return void 0;
-  const modifiers = [];
-  for (let p = 3; p <= 6; p += 1) {
-    const modifier = componentOptional(seg, 2, p, delimiters);
-    if (modifier !== void 0) modifiers.push(modifier);
-  }
-  return Object.freeze({
-    qualifier,
-    code: componentOptional(seg, 2, 2, delimiters),
-    modifiers: Object.freeze(modifiers),
-    description: componentOptional(seg, 2, 7, delimiters)
-  });
-}
 function freezeInquiry(acc) {
   return Object.freeze({
     serviceTypeCodes: Object.freeze(acc.serviceTypeCodes.slice()),
@@ -7473,7 +7478,7 @@ function emitInquiry(inquiry, body, ctx, locator) {
     refuseHierarchy2
   ).map((s) => ctx.esc(s.code)).join(ctx.repetitionSeparator);
   const procedure = absentIfNull(inquiry.procedure);
-  const procedureElement = procedure === void 0 ? "" : trimComponents([
+  const procedureElement2 = procedure === void 0 ? "" : trimComponents([
     ctx.esc(procedure.qualifier),
     ctx.esc(procedure.code ?? ""),
     ...leafList(procedure.modifiers, `${locator}.procedure.modifiers`).map(ctx.esc),
@@ -7486,7 +7491,7 @@ function emitInquiry(inquiry, body, ctx, locator) {
     ctx.seg([
       "EQ",
       serviceTypeElement,
-      procedureElement,
+      procedureElement2,
       ctx.esc(inquiry.coverageLevelCode ?? ""),
       ctx.esc(inquiry.insuranceTypeCode ?? ""),
       pointerElement
@@ -7997,6 +8002,7 @@ function openBenefit(seg, delimiters, sink) {
     quantity: elementDecimal(seg, 10, delimiters, sink),
     authorizationRequired: elementOptional(seg, 11, delimiters),
     inPlanNetwork: elementOptional(seg, 12, delimiters),
+    procedure: decodeProcedure(seg, 13, delimiters),
     references: [],
     dates: [],
     messages: [],
@@ -8039,6 +8045,7 @@ function freezeBenefit(acc) {
     quantity: acc.quantity,
     authorizationRequired: acc.authorizationRequired,
     inPlanNetwork: acc.inPlanNetwork,
+    procedure: acc.procedure,
     references: Object.freeze(acc.references.slice()),
     dates: Object.freeze(acc.dates.slice()),
     messages: Object.freeze(acc.messages.slice()),
@@ -8104,6 +8111,7 @@ var X279A1_VERSION_RELEASE2 = "005010X279A1";
 var X12_271_FUNCTIONAL_ID = "HB";
 var X12_AGENCY_CODE4 = "X";
 var HL_LEVEL3 = { SOURCE: "20", RECEIVER: "21", SUBSCRIBER: "22", DEPENDENT: "23" };
+var MAX_PROCEDURE_MODIFIERS = 4;
 function build271(spec) {
   const { envelope } = spec;
   enforceStructuralSpec4(spec);
@@ -8124,7 +8132,7 @@ function build271(spec) {
     while (end > 1 && parts[end - 1] === "") end -= 1;
     return parts.slice(0, end).join(elementSeparator) + segmentTerminator;
   };
-  const ctx = { seg, esc, repetitionSeparator };
+  const ctx = { seg, esc, repetitionSeparator, componentSeparator };
   const senderQualifier = envelope.senderQualifier ?? "ZZ";
   const receiverQualifier = envelope.receiverQualifier ?? "ZZ";
   const usageIndicator = envelope.usageIndicator ?? "P";
@@ -8354,7 +8362,8 @@ function emitBenefit(benefit, body, ctx) {
       ctx.esc(benefit.quantityQualifier ?? ""),
       benefit.quantity === void 0 ? "" : escDec3(benefit.quantity, ctx.esc),
       ctx.esc(benefit.authorizationRequired ?? ""),
-      ctx.esc(benefit.inPlanNetwork ?? "")
+      ctx.esc(benefit.inPlanNetwork ?? ""),
+      benefit.procedure === void 0 ? "" : procedureElement(benefit.procedure, ctx)
     ])
   );
   for (const related of benefit.relatedEntities ?? []) emitEntity2(related, body, ctx);
@@ -8364,6 +8373,32 @@ function emitBenefit(benefit, body, ctx) {
     body.push(ctx.seg(["MSG", ctx.esc(message)]));
   }
 }
+function procedureElement(procedure, ctx) {
+  const qualifier = ctx.esc(procedure.qualifier);
+  const code = ctx.esc(procedure.code);
+  if (qualifier === "" || code === "") {
+    refuseSpec4("build271: a benefit procedure (EB-13) requires a non-empty qualifier and code.");
+  }
+  const modifiers = requireCallerArray(
+    procedure.modifiers,
+    "build271: benefit procedure (EB-13) modifiers",
+    refuseSpec4
+  );
+  if (modifiers.length > MAX_PROCEDURE_MODIFIERS) {
+    refuseSpec4(
+      `build271: a benefit procedure (EB-13) carries at most ${String(MAX_PROCEDURE_MODIFIERS)} modifiers; got ${String(modifiers.length)}.`
+    );
+  }
+  const escapedModifiers = [];
+  for (let i = 0; i < modifiers.length; i += 1) {
+    const modifier = ctx.esc(modifiers[i] ?? "");
+    if (modifier === "") {
+      refuseSpec4(`build271: benefit procedure (EB-13) modifier at index ${String(i)} is empty.`);
+    }
+    escapedModifiers.push(modifier);
+  }
+  return [qualifier, code, ...escapedModifiers].join(ctx.componentSeparator);
+}
 function emitTrace2(trace, body, ctx) {
   body.push(
     ctx.seg([
@@ -9347,7 +9382,7 @@ function emitClaim3(claim, body, ctx, locator) {
 }
 function emitServiceLine3(line, body, ctx, locator) {
   const procedure = absentIfNull2(line.procedure);
-  const procedureElement = procedure === void 0 ? "" : ctx.comp([
+  const procedureElement2 = procedure === void 0 ? "" : ctx.comp([
     procedure.qualifier,
     procedure.code ?? "",
     ...leafList2(procedure.modifiers, `${locator}.procedure.modifiers`),
@@ -9356,7 +9391,7 @@ function emitServiceLine3(line, body, ctx, locator) {
   body.push(
     ctx.seg([
       "SVC",
-      procedureElement,
+      procedureElement2,
       line.lineChargeAmount === void 0 ? "" : escDec4(line.lineChargeAmount, ctx.esc),
       "",
       ctx.esc(line.revenueCode ?? ""),
@@ -15360,7 +15395,7 @@ var profiles = Object.freeze({
 });
 
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 
 exports.AAA_CONDITION_LEVELS = AAA_CONDITION_LEVELS;
 exports.AAA_FOLLOW_UP_ACTION_CODES = AAA_FOLLOW_UP_ACTION_CODES;