@cosyte/mllp 0.0.1

package/dist/ack-from-hl7/index.d.ts

@@ -0,0 +1,425 @@
+import { AckCode, AckErrorDetail, Hl7Message, AckMode, BuildAckOptions, Hl7ParseError, FATAL_CODES, ACK_CODES } from '@cosyte/hl7';
+export { AckCode, AckErrorDetail, AckMode } from '@cosyte/hl7';
+
+/**
+ * `buildMllpAck` — a THIN transport adapter over `@cosyte/hl7`'s `buildAck`.
+ *
+ * `@cosyte/hl7` owns ACK **content** (MSH/MSA/ERR construction, the fail-safe
+ * no-correlation downgrade); this module owns **transport policy**: accepting
+ * raw inbound bytes (or an already-parsed message), tolerating an unparseable
+ * inbound without ever fabricating a positive disposition, and framing the
+ * result into a ready-to-write MLLP `Buffer` via `encodeFrame`.
+ *
+ * @example
+ * ```typescript
+ * import { buildAckAA } from '@cosyte/mllp/ack-from-hl7';
+ * const { frame } = buildAckAA(inboundBuffer);
+ * socket.write(frame);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A single ACK-generation warning, surfaced by {@link buildMllpAck}.
+ *
+ * `code` is either an upstream `@cosyte/hl7` warning code passed through
+ * verbatim (e.g. `"ACK_NO_CORRELATION_ID"`) or the one `mllp`-owned code,
+ * {@link MLLP_ACK_INBOUND_UNPARSEABLE}.
+ *
+ * @example
+ * ```typescript
+ * import { buildAckAA } from '@cosyte/mllp/ack-from-hl7';
+ * const { warnings } = buildAckAA(inbound);
+ * for (const w of warnings) console.warn(w.code, w.message);
+ * ```
+ */
+interface MllpAckWarning {
+    readonly code: string;
+    readonly message: string;
+}
+/**
+ * Warning code emitted when the inbound message could not be parsed at all
+ * (a fatal `Hl7ParseError`) and {@link buildMllpAck} fell back to a minimal,
+ * uncorrelated ACK rather than fabricating a positive disposition.
+ *
+ * @example
+ * ```typescript
+ * import { MLLP_ACK_INBOUND_UNPARSEABLE, buildAckAA } from '@cosyte/mllp/ack-from-hl7';
+ * const { warnings } = buildAckAA("not hl7 at all");
+ * warnings.some((w) => w.code === MLLP_ACK_INBOUND_UNPARSEABLE); // true
+ * ```
+ */
+declare const MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
+/**
+ * Warning code emitted when the built ACK's MSA-2 bytes are **not** byte-identical
+ * to the inbound MSH-10 bytes — i.e. the ACK does not echo the message control ID
+ * verbatim, as HL7 v2.5.1 §2.9.2.2 requires.
+ *
+ * This is a **correlation failure**, and the reason it is a loud warning rather
+ * than a silent success: the sender keys its in-flight store on the MSH-10 bytes
+ * it put on the wire. An ACK whose MSA-2 differs by even one byte will not match
+ * that key, so the send is never settled → ACK timeout → resend → **duplicate
+ * clinical message**. Emitting the ACK anyway (rather than throwing) is the
+ * fail-safe choice — a mismatched ACK still tells the peer *something* — but the
+ * mismatch must never pass unremarked.
+ *
+ * `buildMllpAck` verifies this on every build, against the very same byte-level
+ * scanners the `@cosyte/mllp` client uses to correlate (`src/internal/control-id.ts`).
+ *
+ * **The verification is meaningful for a `Buffer` inbound, and only for a `Buffer`.**
+ * A `Buffer` *is* the wire bytes, so comparing the ACK to it is a real byte-level check
+ * and a clean result means a `@cosyte/mllp` sender will match this ACK. A
+ * `string`/`Hl7Message` inbound has **already been decoded** before this module sees it:
+ * the only thing left to compare against is that same text, encoded with the same codec,
+ * so the codec cancels on both sides and a codec-induced mismatch is **structurally
+ * invisible** — it warns about nothing. See {@link BuildMllpAckOptions.encoding}. Pass a
+ * `Buffer` if you want this guarantee to mean anything.
+ *
+ * Two known ways to provoke it, both documented in the package limitations:
+ *
+ *   1. Overriding {@link BuildMllpAckOptions.encoding} to a codec that cannot
+ *      round-trip the inbound bytes (`"utf8"`/`"ascii"` against a high-bit,
+ *      8859/1-charset control ID). The default never does this.
+ *   2. An inbound that declares **non-default encoding characters** (MSH-1/MSH-2).
+ *      `@cosyte/hl7`'s `buildMessage` always emits the HL7 default `|^~\&`, so an
+ *      inbound MSH-10 of `ID#X` under a `#` component separator is re-delimited to
+ *      `ID^X` in MSA-2 — different bytes, unmatchable key. Use `buildRawAck` (root
+ *      export), which echoes the inbound's own MSH-1/MSH-2, if you must serve such
+ *      a peer.
+ *
+ * @example
+ * ```typescript
+ * import { MLLP_ACK_CONTROL_ID_NOT_VERBATIM, buildAckAA } from '@cosyte/mllp/ack-from-hl7';
+ * const { warnings } = buildAckAA(inbound, { encoding: "ascii" });
+ * if (warnings.some((w) => w.code === MLLP_ACK_CONTROL_ID_NOT_VERBATIM)) {
+ *   // this ACK will NOT correlate at the sender — investigate before shipping it
+ * }
+ * ```
+ */
+declare const MLLP_ACK_CONTROL_ID_NOT_VERBATIM = "MLLP_ACK_CONTROL_ID_NOT_VERBATIM";
+/**
+ * Options for {@link buildMllpAck} and its six convenience wrappers.
+ *
+ * @example
+ * ```typescript
+ * import type { BuildMllpAckOptions } from '@cosyte/mllp/ack-from-hl7';
+ * const opts: BuildMllpAckOptions = { code: "AE", error: { conditionCode: "101" } };
+ * ```
+ */
+interface BuildMllpAckOptions {
+    /** Required acknowledgment disposition to emit in MSA-1 (HL7 Table 0008). */
+    readonly code: AckCode;
+    /** Optional error detail; one entry emits one ERR segment. */
+    readonly error?: AckErrorDetail | readonly AckErrorDetail[];
+    /**
+     * The codec used to move the ACK between bytes and text — **both** directions,
+     * as a single symmetric choice. It decodes a raw-`Buffer` `inbound` on the way in
+     * and encodes the serialized ACK on the way out, so the ACK is emitted in the same
+     * codec the inbound was read in.
+     *
+     * That symmetry is the whole point, and it is what makes MSA-2 echo MSH-10
+     * **verbatim** (HL7 v2.5.1 §2.9.2.2). Decoding in one codec and encoding in another
+     * corrupts every non-ASCII byte it round-trips: a `latin1`-decoded `0x8B` re-encoded
+     * as `utf8` goes out as the two bytes `0xC2 0x8B`, which is a *different control ID*
+     * — and the sender, which keyed its in-flight store on `0x8B`, cannot match the ACK.
+     *
+     * **Defaults, by inbound type:**
+     *
+     * - `Buffer` → **`"latin1"`**. We own the decode, and `latin1` is the only codec
+     *   that round-trips arbitrary bytes losslessly, so MSA-2 is byte-verbatim for any
+     *   charset — including an MSH-18 of `8859/1` with high-bit bytes in the control ID.
+     * - `string` / `Hl7Message` → **`"utf8"`**. The caller already decoded; we re-encode
+     *   with the JS-native codec.
+     *
+     * **Override with care, and only on a `Buffer`.** Any value other than `"latin1"` on a
+     * raw-`Buffer` inbound gives up the verbatim guarantee for non-ASCII bytes (`"ascii"`
+     * masks the high bit; `"utf8"` folds invalid sequences onto `U+FFFD`). On a `Buffer`,
+     * `buildMllpAck` **checks** the result and emits {@link MLLP_ACK_CONTROL_ID_NOT_VERBATIM}
+     * if the echo did not survive, so a bad override there is loud rather than silent — but
+     * it is still a broken ACK. Set this only when the receiving system genuinely demands a
+     * specific codec.
+     *
+     * **On a `string` / `Hl7Message` inbound the check cannot see a codec problem at all.**
+     * The wire bytes were decoded to text *before* this function saw them, so there is
+     * nothing left to compare the ACK against except that same text — the codec cancels on
+     * both sides and the comparison is a tautology. Concretely,
+     * `buildAckAA(payload.toString("latin1"))` on a high-bit control ID (`0x8B`, legal under
+     * an `MSH-18` of `8859/1`) re-encodes it as the two `utf8` bytes `0xC2 0x8B`, emits a
+     * **different** control ID, and warns about **nothing** — the sender cannot correlate it.
+     * This is not a hole the guard can be grown to cover; the bytes are gone by then.
+     *
+     * **`Buffer` is the byte-safe path.** Pass the raw payload. It is what the server hands
+     * you, it is what the `Buffer`-first API rule exists for, and it is the only input for
+     * which the verbatim guarantee — or a warning that it broke — actually means anything.
+     */
+    readonly encoding?: BufferEncoding;
+    /**
+     * Passthrough to `encodeFrame`'s `allowDelimiterBytesInPayload`. Defaults
+     * to `false` (strict — throws if the serialized ACK somehow contains a
+     * VT/FS byte, which a spec-clean `@cosyte/hl7` emit never does).
+     */
+    readonly allowDelimiterBytesInPayload?: boolean;
+}
+/**
+ * Result of {@link buildMllpAck} — a ready-to-write MLLP frame plus the
+ * metadata needed to log or assert on what was actually emitted. Frozen
+ * (including the `warnings` array) so subscribers cannot mutate shared state.
+ *
+ * @example
+ * ```typescript
+ * import { buildAckAA } from '@cosyte/mllp/ack-from-hl7';
+ * const ack = buildAckAA(inbound);
+ * socket.write(ack.frame);
+ * console.log(ack.code, ack.correlationId);
+ * ```
+ */
+interface MllpAck {
+    /** `VT + payload + FS + CR`, ready to write to a socket. */
+    readonly frame: Buffer;
+    /** The serialized ACK, unframed. */
+    readonly payload: Buffer;
+    /** The built ACK `Hl7Message`. */
+    readonly ack: Hl7Message;
+    /** The disposition the caller asked for. */
+    readonly requestedCode: AckCode;
+    /** The disposition MSA-1 actually carries (post fail-safe downgrade). */
+    readonly code: AckCode;
+    /** Inbound MSH-10, echoed in MSA-2. `undefined` when unfindable. */
+    readonly correlationId: string | undefined;
+    /** Detected from inbound MSH-15/16. `undefined` when inbound unparseable. */
+    readonly mode: AckMode | undefined;
+    /** Warnings collected while building the ACK. */
+    readonly warnings: readonly MllpAckWarning[];
+}
+/**
+ * Build a framed MLLP ACK from an inbound HL7 v2 message — the core
+ * `ack-from-hl7` adapter. `inbound` may be an already-parsed `Hl7Message`, or
+ * raw bytes/text to parse first.
+ *
+ * Behavior:
+ * - **Fatally unparseable inbound** (`Hl7ParseError`) — never emits a
+ *   positive code: `AA`→`AE`, `CA`→`CE`; other codes pass through. MSA-2 is
+ *   empty, `correlationId` and `mode` are `undefined`, and `warnings`
+ *   contains one {@link MLLP_ACK_INBOUND_UNPARSEABLE} entry naming the fatal
+ *   code — never any inbound payload bytes.
+ * - **Normal path** — detects the ack mode from inbound MSH-15/16, delegates
+ *   to `@cosyte/hl7`'s `buildAck` (which applies its own no-correlation
+ *   fail-safe), and forwards `buildAck`'s own warnings (mapped to
+ *   `{ code, message }`). Inbound parse warnings are NOT forwarded — they are
+ *   the caller's concern if they parsed the inbound themselves.
+ *
+ * @throws {MllpPeerMissingError} when `@cosyte/hl7` is not installed.
+ * @throws {TypeError} when `options.code` is not a known HL7 Table 0008 code.
+ *
+ * @example
+ * ```typescript
+ * import { buildMllpAck } from '@cosyte/mllp/ack-from-hl7';
+ * const ack = buildMllpAck(inboundBuffer, { code: "AA" });
+ * socket.write(ack.frame);
+ * ```
+ */
+declare function buildMllpAck(inbound: Hl7Message | Buffer | string, options: BuildMllpAckOptions): MllpAck;
+/**
+ * Build an `AA` (Application Accept) MLLP ACK.
+ *
+ * @example
+ * ```typescript
+ * import { buildAckAA } from '@cosyte/mllp/ack-from-hl7';
+ * socket.write(buildAckAA(inboundBuffer).frame);
+ * ```
+ */
+declare function buildAckAA(inbound: Hl7Message | Buffer | string, options?: Omit<BuildMllpAckOptions, "code">): MllpAck;
+/**
+ * Build an `AE` (Application Error) MLLP ACK.
+ *
+ * @example
+ * ```typescript
+ * import { buildAckAE } from '@cosyte/mllp/ack-from-hl7';
+ * socket.write(buildAckAE(inboundBuffer, { error: { conditionCode: "101" } }).frame);
+ * ```
+ */
+declare function buildAckAE(inbound: Hl7Message | Buffer | string, options?: Omit<BuildMllpAckOptions, "code">): MllpAck;
+/**
+ * Build an `AR` (Application Reject) MLLP ACK.
+ *
+ * @example
+ * ```typescript
+ * import { buildAckAR } from '@cosyte/mllp/ack-from-hl7';
+ * socket.write(buildAckAR(inboundBuffer, { error: { conditionCode: "200" } }).frame);
+ * ```
+ */
+declare function buildAckAR(inbound: Hl7Message | Buffer | string, options?: Omit<BuildMllpAckOptions, "code">): MllpAck;
+/**
+ * Build a `CA` (Commit Accept) MLLP ACK (enhanced mode).
+ *
+ * @example
+ * ```typescript
+ * import { buildAckCA } from '@cosyte/mllp/ack-from-hl7';
+ * socket.write(buildAckCA(inboundBuffer).frame);
+ * ```
+ */
+declare function buildAckCA(inbound: Hl7Message | Buffer | string, options?: Omit<BuildMllpAckOptions, "code">): MllpAck;
+/**
+ * Build a `CE` (Commit Error) MLLP ACK (enhanced mode).
+ *
+ * @example
+ * ```typescript
+ * import { buildAckCE } from '@cosyte/mllp/ack-from-hl7';
+ * socket.write(buildAckCE(inboundBuffer, { error: { conditionCode: "101" } }).frame);
+ * ```
+ */
+declare function buildAckCE(inbound: Hl7Message | Buffer | string, options?: Omit<BuildMllpAckOptions, "code">): MllpAck;
+/**
+ * Build a `CR` (Commit Reject) MLLP ACK (enhanced mode).
+ *
+ * @example
+ * ```typescript
+ * import { buildAckCR } from '@cosyte/mllp/ack-from-hl7';
+ * socket.write(buildAckCR(inboundBuffer, { error: { conditionCode: "200" } }).frame);
+ * ```
+ */
+declare function buildAckCR(inbound: Hl7Message | Buffer | string, options?: Omit<BuildMllpAckOptions, "code">): MllpAck;
+/**
+ * Detect the HL7 acknowledgment mode (`"original"` vs `"enhanced"`) of an
+ * inbound message, from MSH-15/16. Named `detectMode` (not `detectAckMode`)
+ * to avoid colliding with the peer's own `detectAckMode` export for callers
+ * who import both from `@cosyte/hl7` and `@cosyte/mllp/ack-from-hl7`.
+ *
+ * `inbound` may be an already-parsed `Hl7Message`, or raw bytes/text to parse
+ * first. A fatal parse failure rethrows the `Hl7ParseError` as-is — unlike
+ * {@link buildMllpAck}, there is no ACK to build here, so there is no
+ * fallback to construct.
+ *
+ * **Module-realm note:** this adapter loads `@cosyte/hl7` lazily via
+ * `createRequire` (see `peer.ts`). If your code ALSO does
+ * `import { Hl7ParseError } from "@cosyte/hl7"` directly, Node's module
+ * resolution can — depending on your bundler/runtime — hand you a distinct
+ * module instance than the one this adapter loaded, in which case
+ * `caught instanceof Hl7ParseError` (your import) may be `false` even though
+ * `caught.name === "Hl7ParseError"` and `caught.code` is a valid HL7 fatal
+ * code (`NO_MSH_SEGMENT` / `MSH_TOO_SHORT` / `INVALID_ENCODING_CHARACTERS` /
+ * `EMPTY_INPUT`). Prefer narrowing on `.code`/`.name`, or obtain the exact
+ * class via this subpath's own `loadHl7Peer().Hl7ParseError`.
+ *
+ * @throws {MllpPeerMissingError} when `@cosyte/hl7` is not installed.
+ * @throws {Hl7ParseError} when `inbound` is raw bytes/text that fails to parse.
+ *
+ * @example
+ * ```typescript
+ * import { detectMode } from '@cosyte/mllp/ack-from-hl7';
+ * detectMode(inboundBuffer); // "original" | "enhanced"
+ * ```
+ */
+declare function detectMode(inbound: Hl7Message | Buffer | string): AckMode;
+
+/**
+ * Lazy loader for the optional `@cosyte/hl7` peer dependency.
+ *
+ * `@cosyte/mllp` ships **zero runtime dependencies**; `@cosyte/hl7` is an
+ * optional peer dep referenced only from this `/ack-from-hl7` subpath. To keep
+ * the rest of the package fully dependency-free, the peer is required lazily —
+ * on first call into `ack-from-hl7` — via `createRequire`, not at module load
+ * time. The public API of this subpath stays synchronous throughout.
+ *
+ * @example
+ * ```typescript
+ * import { loadHl7Peer } from '@cosyte/mllp/ack-from-hl7';
+ * const hl7 = loadHl7Peer(); // throws MllpPeerMissingError if not installed
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The subset of the `@cosyte/hl7` runtime surface the `ack-from-hl7` adapter
+ * consumes. Kept narrow and typed via `import type` (erased at compile time)
+ * so the runtime dependency stays fully lazy — only the shape is known
+ * statically, the values are resolved via `require()` at first call.
+ *
+ * @example
+ * ```typescript
+ * import type { Hl7Peer } from '@cosyte/mllp/ack-from-hl7';
+ * function useAck(peer: Hl7Peer) {
+ *   return peer.buildAck;
+ * }
+ * ```
+ */
+interface Hl7Peer {
+    readonly parseHL7: (raw: string | Buffer) => Hl7Message;
+    readonly buildAck: (inbound: Hl7Message, options: BuildAckOptions) => Hl7Message;
+    readonly detectAckMode: (inbound: Hl7Message) => "original" | "enhanced";
+    readonly buildMessage: (init: {
+        readonly type: string;
+    }) => Hl7Message;
+    /**
+     * The peer's own `Hl7Message` class. Exposed (not just used as a type) so
+     * callers can detect a cross-realm instance — see the dual-package-hazard
+     * note on `resolveInbound` in `build.ts`. Typed as `abstract new` (rather
+     * than a concrete constructor signature) purely so TypeScript accepts it as
+     * an `instanceof` right-hand side without also implying callers can `new`
+     * it directly with arbitrary args.
+     */
+    readonly Hl7Message: abstract new (...args: never[]) => Hl7Message;
+    readonly Hl7ParseError: typeof Hl7ParseError;
+    readonly FATAL_CODES: typeof FATAL_CODES;
+    readonly ACK_CODES: typeof ACK_CODES;
+    /**
+     * The peer's fail-safe downgrade primitive (`AA`→`AE`, `CA`→`CE`, everything
+     * else unchanged) — the single upstream source of truth for the pair; this
+     * adapter never carries its own copy of the mapping.
+     */
+    readonly downgradePositiveAck: (code: AckCode) => AckCode;
+}
+/**
+ * Thrown when `@cosyte/hl7` — the optional peer dependency required by
+ * `@cosyte/mllp/ack-from-hl7` — cannot be resolved at runtime.
+ *
+ * `@cosyte/hl7` is declared as an optional peer dependency, so a consumer of
+ * the root `@cosyte/mllp` entry point is never forced to install it. Only
+ * code that imports from the `/ack-from-hl7` subpath needs it, and only once
+ * that code actually runs (the loader is lazy).
+ *
+ * @example
+ * ```typescript
+ * import { buildAckAA, MllpPeerMissingError } from '@cosyte/mllp/ack-from-hl7';
+ * try {
+ *   buildAckAA(inboundBuffer);
+ * } catch (err) {
+ *   if (err instanceof MllpPeerMissingError) {
+ *     console.error(err.message); // explains how to install @cosyte/hl7
+ *   }
+ * }
+ * ```
+ */
+declare class MllpPeerMissingError extends Error {
+    readonly name: "MllpPeerMissingError";
+    /** Stable machine-readable code identifying this error class. */
+    readonly code: "MLLP_PEER_MISSING";
+    /**
+     * Construct an `MllpPeerMissingError`.
+     *
+     * @param cause - The original module-resolution error, preserved for debugging.
+     */
+    constructor(cause: unknown);
+}
+/**
+ * Load the `@cosyte/hl7` peer module, caching the result for subsequent
+ * calls. The public adapter functions in `build.ts` call this internally —
+ * most consumers never call it directly.
+ *
+ * @param requireFn - Injectable `require`-like function, used by tests to
+ *   simulate a missing peer without actually uninstalling it. Defaults to a
+ *   real `createRequire(import.meta.url)`.
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * import { loadHl7Peer } from '@cosyte/mllp/ack-from-hl7';
+ * const hl7 = loadHl7Peer();
+ * const ack = hl7.buildAck(hl7.parseHL7(raw), { code: "AA" });
+ * ```
+ */
+declare function loadHl7Peer(requireFn?: (id: string) => unknown): Hl7Peer;
+
+export { type BuildMllpAckOptions, type Hl7Peer, MLLP_ACK_CONTROL_ID_NOT_VERBATIM, MLLP_ACK_INBOUND_UNPARSEABLE, type MllpAck, type MllpAckWarning, MllpPeerMissingError, buildAckAA, buildAckAE, buildAckAR, buildAckCA, buildAckCE, buildAckCR, buildMllpAck, detectMode, loadHl7Peer };