@cosyte/mllp 0.0.1 → 0.0.2

package/dist/ack-from-hl7/index.mjs

@@ -16,13 +16,13 @@ var MllpFramingError = class _MllpFramingError extends Error {
   /**
    * Up to 64 bytes copied from around the anomaly.
    *
-   * This is a **copied** Buffer — isolated from the source buffer so it remains
+   * This is a **copied** Buffer, isolated from the source buffer so it remains
    * valid after the underlying buffer is reused or overwritten.
    *
    * **PHI contract (MLLP-9):** the decoder only ever populates this with the single
    * framing-boundary byte that violated the frame structure (whose hex value the
-   * `message` already discloses) — never a run of payload content bytes. For anomalies
-   * whose fault is not a specific byte (`MLLP_FRAME_TOO_LARGE` — the accumulated size),
+   * `message` already discloses), never a run of payload content bytes. For anomalies
+   * whose fault is not a specific byte (`MLLP_FRAME_TOO_LARGE`, the accumulated size),
    * the snippet is **empty**: a payload slice on a public error field would leak a
    * field-body slice of clinical content. Callers constructing this directly are
    * responsible for the same discipline.
@@ -104,9 +104,9 @@ var UNSAFE_FIELD_SEPARATORS = /* @__PURE__ */ new Set([
   SEGMENT_SEPARATOR_CR,
   SEGMENT_SEPARATOR_LF,
   11,
-  // VT — MLLP start block
+  // VT, MLLP start block
   28
-  // FS — MLLP end block
+  // FS, MLLP end block
 ]);
 function isMshSegmentAt(buf, i) {
   return i + 3 < buf.length && buf[i] === ASCII_M && buf[i + 1] === ASCII_S && buf[i + 2] === ASCII_H && !UNSAFE_FIELD_SEPARATORS.has(buf[i + 3]);
@@ -205,7 +205,7 @@ var MllpPeerMissingError = class _MllpPeerMissingError extends Error {
    */
   constructor(cause) {
     super(
-      `${PEER_PACKAGE_NAME} is required by ${SUBPATH_NAME} but is not installed. ${PEER_PACKAGE_NAME} is an optional peer dependency of @cosyte/mllp \u2014 install it alongside @cosyte/mllp to use ${SUBPATH_NAME}: \`npm install ${PEER_PACKAGE_NAME}\` (or the equivalent for your package manager).`,
+      `${PEER_PACKAGE_NAME} is required by ${SUBPATH_NAME} but is not installed. ${PEER_PACKAGE_NAME} is an optional peer dependency of @cosyte/mllp, install it alongside @cosyte/mllp to use ${SUBPATH_NAME}: \`npm install ${PEER_PACKAGE_NAME}\` (or the equivalent for your package manager).`,
       { cause }
     );
     if (Error.captureStackTrace) {
@@ -246,8 +246,16 @@ function loadHl7Peer(requireFn) {
 // src/ack-from-hl7/build.ts
 var MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
 var MLLP_ACK_CONTROL_ID_NOT_VERBATIM = "MLLP_ACK_CONTROL_ID_NOT_VERBATIM";
+var MLLP_ACK_CONTROL_ID_UNVERIFIABLE = "MLLP_ACK_CONTROL_ID_UNVERIFIABLE";
 var BYTES_INBOUND_ENCODING = "latin1";
 var TEXT_INBOUND_ENCODING = "utf8";
+var SERIALIZABLE_ACK_ENCODINGS = /* @__PURE__ */ new Set([
+  "utf8",
+  "utf-8",
+  "ascii",
+  "latin1",
+  "binary"
+]);
 function assertKnownAckCode(peer, code) {
   const known = Object.values(peer.ACK_CODES);
   if (typeof code !== "string" || !known.includes(code)) {
@@ -260,6 +268,12 @@ function resolveEncoding(inbound, options) {
   if (options.encoding !== void 0) return options.encoding;
   return Buffer.isBuffer(inbound) ? BYTES_INBOUND_ENCODING : TEXT_INBOUND_ENCODING;
 }
+function assertSerializableAckEncoding(encoding) {
+  if (SERIALIZABLE_ACK_ENCODINGS.has(encoding.toLowerCase())) return;
+  throw new TypeError(
+    `buildMllpAck: encoding ${JSON.stringify(encoding)} is not a serializable ACK codec. Serializing an ACK to a non-text codec (base64/base64url/hex/utf16le/ucs2) produces a wholesale-garbage frame the receiver cannot parse, on a Buffer inbound it also garbles the inbound decode, so it can never correlate. Use a text codec ("utf8", "ascii", or "latin1"); on a Buffer, "latin1" is byte-verbatim and is the default.`
+  );
+}
 function inboundBytes(inbound, encoding) {
   if (Buffer.isBuffer(inbound)) return inbound;
   if (typeof inbound === "string") return Buffer.from(inbound, encoding);
@@ -275,7 +289,23 @@ function verifyVerbatimEcho(ackPayload, inboundRaw) {
   const echoed = echoedId === null ? "absent" : `${String(echoedId.length)} bytes`;
   return {
     code: MLLP_ACK_CONTROL_ID_NOT_VERBATIM,
-    message: `ACK does not echo the inbound MSH-10 verbatim (HL7 v2.5.1 \xA72.9.2.2): inbound MSH-10 is ${inboundLen} bytes, emitted MSA-2 is ${echoed}, and they differ. The sender keys its in-flight store on the inbound bytes, so it will NOT match this ACK (ACK timeout -> resend -> duplicate message). Field values are withheld \u2014 MSH-10 is inbound payload content and this warning goes to a log; compare your inbound payload against MllpAck.payload to see the bytes.`
+    message: `ACK does not echo the inbound MSH-10 verbatim (HL7 v2.5.1 \xA72.9.2.2): inbound MSH-10 is ${inboundLen} bytes, emitted MSA-2 is ${echoed}, and they differ. The sender keys its in-flight store on the inbound bytes, so it will NOT match this ACK (ACK timeout -> resend -> duplicate message). Field values are withheld, MSH-10 is inbound payload content and this warning goes to a log; compare your inbound payload against MllpAck.payload to see the bytes.`
+  };
+}
+function verifyTextInboundEcho(controlId, inbound) {
+  if (Buffer.isBuffer(inbound)) return null;
+  if (controlId === "") return null;
+  let hasNonAscii = false;
+  for (let i = 0; i < controlId.length; i++) {
+    if (controlId.charCodeAt(i) > 127) {
+      hasNonAscii = true;
+      break;
+    }
+  }
+  if (!hasNonAscii) return null;
+  return {
+    code: MLLP_ACK_CONTROL_ID_UNVERIFIABLE,
+    message: `ACK's byte-verbatim echo of MSH-10 (HL7 v2.5.1 \xA72.9.2.2) cannot be verified: the inbound was decoded text (a string or Hl7Message), not raw bytes, so its wire bytes are gone and the ${String(controlId.length)}-code-unit MSA-2 control ID holds a non-ASCII code unit the decode/encode codec could have altered (a lossy override such as ascii can even mask it into the ASCII byte range). It may not correlate at the sender (ACK timeout -> resend -> duplicate message). Pass the raw payload Buffer to get the byte-level guarantee. Field values are withheld, MSH-10 is inbound payload content and this warning goes to a log.`
   };
 }
 function toMllpAck(params) {
@@ -285,7 +315,13 @@ function toMllpAck(params) {
     allowDelimiterBytesInPayload: options.allowDelimiterBytesInPayload ?? false
   });
   const echoWarning = verifyVerbatimEcho(payload, params.verifyAgainst);
-  const allWarnings = echoWarning === null ? warnings : [...warnings, echoWarning];
+  const echoedControlId = ack.segments("MSA")[0]?.field(2).text ?? "";
+  const unverifiableWarning = params.inbound === void 0 ? null : verifyTextInboundEcho(echoedControlId, params.inbound);
+  const allWarnings = [
+    ...warnings,
+    ...echoWarning === null ? [] : [echoWarning],
+    ...unverifiableWarning === null ? [] : [unverifiableWarning]
+  ];
   const result = {
     frame,
     payload,
@@ -316,11 +352,12 @@ function buildUnparseableFallback(peer, requestedCode, fatalCode, options, encod
     warnings,
     options,
     encoding,
-    // MSA-2 is INTENTIONALLY empty here — the inbound could not be parsed, so there is no
-    // control id to echo and we refuse to fabricate one. Running the verbatim check would
-    // report that deliberate choice as a violation; `MLLP_ACK_INBOUND_UNPARSEABLE` (above)
+    // MSA-2 is INTENTIONALLY empty here, the inbound could not be parsed, so there is no
+    // control id to echo and we refuse to fabricate one. Running either echo check would
+    // report that deliberate choice as a problem; `MLLP_ACK_INBOUND_UNPARSEABLE` (above)
     // is the accurate warning for this case, and it is already attached.
-    verifyAgainst: void 0
+    verifyAgainst: void 0,
+    inbound: void 0
   });
 }
 function resolveInbound(peer, inbound, encoding) {
@@ -337,6 +374,7 @@ function buildMllpAck(inbound, options) {
   const peer = loadHl7Peer();
   assertKnownAckCode(peer, options.code);
   const encoding = resolveEncoding(inbound, options);
+  assertSerializableAckEncoding(encoding);
   let msg;
   try {
     msg = resolveInbound(peer, inbound, encoding);
@@ -368,7 +406,8 @@ function buildMllpAck(inbound, options) {
     warnings,
     options,
     encoding,
-    verifyAgainst: inboundBytes(inbound, encoding)
+    verifyAgainst: inboundBytes(inbound, encoding),
+    inbound
   });
 }
 function buildAckAA(inbound, options) {
@@ -395,6 +434,6 @@ function detectMode(inbound) {
   return peer.detectAckMode(msg);
 }
 
-export { MLLP_ACK_CONTROL_ID_NOT_VERBATIM, MLLP_ACK_INBOUND_UNPARSEABLE, MllpPeerMissingError, buildAckAA, buildAckAE, buildAckAR, buildAckCA, buildAckCE, buildAckCR, buildMllpAck, detectMode, loadHl7Peer };
+export { MLLP_ACK_CONTROL_ID_NOT_VERBATIM, MLLP_ACK_CONTROL_ID_UNVERIFIABLE, MLLP_ACK_INBOUND_UNPARSEABLE, MllpPeerMissingError, buildAckAA, buildAckAE, buildAckAR, buildAckCA, buildAckCE, buildAckCR, buildMllpAck, detectMode, loadHl7Peer };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map