@glion/mllp-client 0.16.0

package/dist/core/acknowledgment.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Acknowledgment parsing for the MLLP client.
+ *
+ * This module owns three things:
+ *
+ * 1. The {@link Acknowledgment} interface — a structured view of an ACK message
+ *    exposing the fields callers most often need (MSA-1/2/3, ERR-3/4) without
+ *    forcing them to walk the AST themselves.
+ * 2. {@link parseAck} — turns a raw wire-format ACK string into an
+ *    {@link Acknowledgment}, or throws {@link MllpClientError} when the payload
+ *    is not a recognisable ACK.
+ * 3. {@link throwOnNak} — inspects an {@link Acknowledgment} and throws the
+ *    matching `AckException` subclass when MSA-1 indicates a NAK.
+ *
+ * Both helpers are internal to the package — only the {@link Acknowledgment}
+ * type is re-exported from `@glion/mllp-client`. Application code interacts
+ * with parsed acknowledgments through the return value (and thrown errors)
+ * of `MllpClient.send()`.
+ *
+ * The HL7v2 ACK structure used here (Section 2.9.2 of the HL7v2 standard):
+ *
+ * MSH | header (sender, receiver, timestamp, message control id) MSA |
+ * acknowledgment code (MSA-1), original control id (MSA-2), text (MSA-3) ERR |
+ * optional error segment with HL7 condition code (ERR-3) and severity (ERR-4)
+ *
+ * @module
+ */
+import type { AckCodeValue } from "@glion/ack";
+import type { Root } from "@glion/ast";
+/**
+ * An HL7v2 acknowledgment message returned by an MLLP receiver, with
+ * structured access to the fields callers most often need.
+ *
+ * Returned by `MllpClient.send()` on AA/CA. On NAK (AE/AR/CE/CR) an
+ * `AckException` is thrown instead — the same shape is available there
+ * via `error.message` (MSA-3), `error.errorCode` (ERR-3), `error.severity`
+ * (ERR-4), and `error.raw` (the wire ACK).
+ */
+export interface Acknowledgment {
+    /** The raw HL7v2 ACK message as received from the wire. */
+    readonly raw: string;
+    /**
+     * The full ACK message AST, typed against `@glion/ast`. Use for
+     * advanced inspection beyond the structured fields below; consumers
+     * that walk the tree should install `@glion/ast` for the type.
+     */
+    readonly tree: Root;
+    /**
+     * MSA-1 acknowledgment code.
+     *
+     * Typed as the standard {@link AckCodeValue} union (`AA`, `AE`, `AR`,
+     * `CA`, `CE`, `CR`) widened with an opaque `string` escape hatch — the
+     * `(string & {})` form preserves auto-completion for the standard
+     * codes while still accepting vendor-specific values that real
+     * receivers occasionally send.
+     */
+    readonly code: AckCodeValue | (string & {});
+    /** MSA-2 message control ID — references the original message's MSH-10. */
+    readonly controlId: string;
+    /** MSA-3 text message. Typically populated on NAK; optional on accept ACKs. */
+    readonly textMessage: string | undefined;
+    /**
+     * ERR-3 HL7 error condition code (Table 0357). Present when an ERR segment is
+     * included.
+     */
+    readonly errorCode: string | undefined;
+    /** ERR-4 severity (Table 0516). Present when an ERR segment is included. */
+    readonly severity: string | undefined;
+}
+/**
+ * Returns `true` for any acknowledgment code that should terminate the
+ * client's read loop. Intermediate codes (CA) return `false`; every
+ * other code — including vendor-specific values — is treated as final
+ * to avoid hanging on responses we do not recognise.
+ */
+export declare function isFinalAckCode(code: string): boolean;
+/**
+ * Parse a raw ACK frame string into an {@link Acknowledgment}.
+ *
+ * Field extraction is delegated to `@glion/util-query`'s `value()` helper —
+ * this is the same path used elsewhere in the Glion stack and avoids
+ * hand-rolling AST traversal here.
+ *
+ * Throws `MllpClientError(MALFORMED_ACK)` when:
+ *
+ * - The parser fails to produce a tree (malformed HL7v2), or
+ * - MSA-1 is missing (the message is not a valid acknowledgment).
+ *
+ * Other missing fields (MSA-3, ERR-3, ERR-4) are not fatal — they are
+ * exposed as `undefined` because real-world ACKs frequently omit them.
+ */
+export declare function parseAck(raw: string): Acknowledgment;
+/**
+ * Inspect an {@link Acknowledgment} and throw the matching `AckException`
+ * subclass when MSA-1 indicates a NAK. Returns the acknowledgment unchanged
+ * on AA/CA.
+ *
+ * The thrown exception mirrors the receiver-side exception types — a
+ * caller that already handles `AckApplicationError` from a server's
+ * middleware can reuse the same `catch` blocks here.
+ */
+export declare function throwOnNak(ack: Acknowledgment): Acknowledgment;
+//# sourceMappingURL=acknowledgment.d.ts.map

package/dist/core/acknowledgment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acknowledgment.d.ts","sourceRoot":"","sources":["../../src/core/acknowledgment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAWH,OAAO,KAAK,EACV,YAAY,EAKb,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAUvC;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB;;;;;;;;OAQG;IAEH,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAgCD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAmBpD;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,cAAc,CAK9D"}

package/dist/core/client.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Runtime-free core of `@glion/mllp-client`.
+ *
+ * This module owns {@link MllpClient}, the class application code
+ * instantiates to send HL7v2 messages and receive acknowledgments.
+ * The class is **transport-agnostic**: it composes a Web-Streams
+ * pipeline (`socket → decoder → ack-parser`) and consumes parsed
+ * acknowledgments from the readable side. It does **not** know how
+ * to open a TCP/TLS connection. That concern is supplied by a
+ * {@link MllpConnect} function passed in via
+ * {@link MllpClientOptions.connect}. Per-runtime adapters
+ * (`@glion/mllp-client/node`, `/deno`, `/workers`) ship pre-wired
+ * `MllpClient` subclasses so the common case stays a single import.
+ *
+ * Each call to `client.send()` performs one short-lived round trip:
+ *
+ *     ┌─────────────┐  ① connect       ┌──────────┐
+ *     │   client    │ ───────────────▶ │  duplex  │
+ *     │             │                  └────┬─────┘
+ *     │             │  ② write MLLP frame   │
+ *     │             │ ─────────────────────▶│  <VT> ... <FS><CR>
+ *     │             │                       │
+ *     │             │  ③ read frames via    │
+ *     │             │     decoder + parser  │
+ *     │             │ ◀─────────────────────│  <VT> ACK <FS><CR> ...
+ *     │             │                  ┌────┴─────┐
+ *     │             │  ④ close + parse │  duplex  │ closed
+ *     └─────────────┘                  └──────────┘
+ *
+ * The four phases share a single deadline ({@link MllpClientOptions.timeout}).
+ * If any phase exceeds the budget, the duplex is closed and a typed
+ * `MllpClientError(TIMEOUT)` is thrown. Connections are deliberately
+ * **not** pooled or reused — each `send()` opens its own duplex.
+ *
+ * @module
+ */
+import type { Acknowledgment } from "./acknowledgment";
+import type { MllpConnect } from "./connect";
+/**
+ * TLS configuration for an MLLP client connection.
+ *
+ * Mirrors the relevant subset of TLS options across runtimes. When
+ * this object is provided to {@link MllpClientOptions.tls}, the
+ * runtime adapter establishes a TLS connection (rather than plain
+ * TCP). Server certificates are **always** verified unless
+ * {@link insecure} is explicitly set to `true`.
+ *
+ * Not every runtime adapter supports every field — `passphrase` and
+ * mutual-TLS material (`cert`/`key`) are honoured by the Node
+ * adapter; Cloudflare Workers and Deno expose a smaller subset.
+ * Adapters silently ignore fields they cannot use.
+ */
+export interface MllpClientTlsOptions {
+    /** Trusted CA certificate(s) for verifying the server. */
+    ca?: string | Uint8Array;
+    /** Client certificate for mutual TLS. */
+    cert?: string | Uint8Array;
+    /** Client private key for mutual TLS. */
+    key?: string | Uint8Array;
+    /** Passphrase for the private key, if encrypted. */
+    passphrase?: string;
+    /**
+     * Override the server name used for SNI and certificate
+     * verification. Defaults to {@link MllpClientOptions.host}.
+     *
+     * Setting this to anything other than the real server hostname
+     * effectively disables strict hostname verification — use only
+     * when SNI multiplexing requires a different name from the
+     * connection target.
+     */
+    servername?: string;
+    /**
+     * Disable server-certificate verification.
+     *
+     * **DO NOT enable this in production.** When set to `true` the
+     * client accepts self-signed, expired, and otherwise invalid
+     * certificates, making the connection vulnerable to active
+     * man-in-the-middle attacks. The option exists so that local
+     * development and integration tests can connect to throwaway
+     * servers — never as a workaround for real certificate problems.
+     *
+     * Only the literal value `true` opts out. There is no `false`
+     * form because the secure default is non-negotiable.
+     */
+    insecure?: true;
+}
+/**
+ * Configuration for an {@link MllpClient}. All fields are immutable
+ * once the client is constructed; create a new client to change
+ * them.
+ *
+ * Application code that imports from `@glion/mllp-client/node`,
+ * `/deno`, or `/workers` does **not** need to pass `connect` — the
+ * runtime adapter provides it.
+ */
+export interface MllpClientOptions {
+    /** Hostname or IP of the MLLP server. */
+    host: string;
+    /** TCP port of the MLLP server. */
+    port: number;
+    /**
+     * Function that opens a connection to the receiver and returns a
+     * Web-Streams duplex. Runtime adapters supply this for you.
+     */
+    connect: MllpConnect;
+    /**
+     * Maximum total milliseconds for the connect → write → read-ACK
+     * round trip. The same budget covers all phases — if connecting
+     * consumes 4s of a 10s budget, the remaining 6s is what's left to
+     * receive the ACK.
+     *
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Maximum bytes accepted for an inbound ACK frame. When omitted,
+     * no limit is enforced. Set this when receiving from untrusted
+     * peers to cap memory use from a malicious or malformed stream.
+     */
+    maxAckSize?: number;
+    /**
+     * TLS configuration. **Defaults to `true`** — HL7v2 messages
+     * commonly carry PHI, so the secure default is TLS-on. Callers
+     * who genuinely want plain TCP (e.g. trusted hospital intranet,
+     * or a TLS terminator hop in front of the receiver) must opt out
+     * explicitly with `tls: false`.
+     *
+     * @example
+     *   ```ts
+     *   // TLS on, defaults (system trust, hostname verification)
+     *   new MllpClient({ host, port });
+     *
+     *   // Same — explicit form
+     *   new MllpClient({ host, port, tls: true });
+     *
+     *   // TLS with config (mutual TLS, custom CA, SNI override, ...)
+     *   new MllpClient({ host, port, tls: { servername: "h" } });
+     *
+     *   // Plain TCP — caller takes the security trade-off explicitly
+     *   new MllpClient({ host, port, tls: false });
+     *   ```;
+     *
+     * @default true
+     */
+    tls?: boolean | MllpClientTlsOptions;
+}
+/**
+ * Construction options accepted by the **runtime adapters'**
+ * `MllpClient` subclasses (`@glion/mllp-client/node`, `/deno`,
+ * `/workers`). Identical to {@link MllpClientOptions} except that
+ * `connect` is omitted — the adapter binds it for you.
+ */
+export type BoundMllpClientOptions = Omit<MllpClientOptions, "connect">;
+/**
+ * HL7v2 acknowledgment level the send waits for. Mirrors the two
+ * acknowledgment levels in HL7v2 §2.9.2.
+ *
+ * - `"OnApplication"` (default) — return when the receiver's application-level
+ *   ACK arrives (`AA`/`AE`/`AR`). Intermediate `CA` (Commit Accept) frames sent
+ *   by enhanced-mode receivers are surfaced via iteration but do not resolve
+ *   the send. Use this when "did the receiver successfully process my message?"
+ *   is the question.
+ * - `"OnCommit"` — return on the first frame regardless of code, typically a
+ *   commit-level ACK (`CA`/`CE`/`CR`). The send resolves as soon as the
+ *   receiver confirms receipt of the message; later processing-level frames are
+ *   not observed because the connection is closed once the resolving frame
+ *   arrives. Use this for receivers that only send commit-level ACKs (basic
+ *   mode) or when the caller wants the commit confirmation without waiting for
+ *   the processing result.
+ */
+export type SendMode = "OnApplication" | "OnCommit";
+/**
+ * Per-call options accepted by {@link MllpClient.send}.
+ */
+export interface SendOptions {
+    /**
+     * Cancel the in-flight `send()` from outside. Composed with the
+     * client's internal `timeout` deadline via `AbortSignal.any`, so
+     * either source aborts the send.
+     *
+     * Typical use: tie a batch of `send()`s to an app-shutdown
+     * `AbortController` so they all cancel cleanly when the process
+     * exits.
+     *
+     * When this signal aborts, the resulting `MllpClientError` has
+     * `code: TIMEOUT` and forwards the caller's `signal.reason` as
+     * its `cause` (when the reason is itself an `Error`).
+     */
+    signal?: AbortSignal;
+    /**
+     * HL7v2 acknowledgment level to wait for. See {@link SendMode}.
+     *
+     * @default "OnApplication"
+     */
+    mode?: SendMode;
+}
+/**
+ * Runtime-free MLLP client. Instantiate via a runtime adapter
+ * (`@glion/mllp-client/node`, `/deno`, `/workers`) for the common
+ * case.
+ *
+ * **TLS-on by default.** `MllpClientOptions.tls` defaults to `true`;
+ * pass `tls: false` for plain TCP. See {@link MllpClientOptions.tls}.
+ *
+ * @example
+ *   Send a message and read the ACK on Node:
+ *
+ *   ```ts
+ *   import { MllpClient } from "@glion/mllp-client/node";
+ *
+ *   const client = new MllpClient({ host: "127.0.0.1", port: 2575 });
+ *   const ack = await client.send(rawHl7Message);
+ *   console.log(ack.code, ack.controlId); // "AA" "MSG001"
+ *   ```
+ */
+export declare class MllpClient {
+    #private;
+    constructor(options: MllpClientOptions);
+    /** The host this client connects to. */
+    get host(): string;
+    /** The port this client connects to. */
+    get port(): number;
+    /**
+     * Send a single HL7v2 message and resolve with the resolving accept ACK.
+     *
+     * Throws:
+     *
+     * - {@link MllpClientError} for transport failures. `code` identifies the mode:
+     *   `INVALID_INPUT`, `CONNECTION_REFUSED`, `TIMEOUT`, `CONNECTION_CLOSED`,
+     *   `MALFORMED_FRAME`, or `MALFORMED_ACK`.
+     * - An `AckException` subclass from `@glion/ack` (`AckApplicationError`,
+     *   `AckApplicationReject`, `AckCommitError`, `AckCommitReject`) when MSA-1 ∈
+     *   {AE, AR, CE, CR}. The thrown exception's `raw` attribute holds the
+     *   wire-format ACK.
+     *
+     * To observe each accept ACK as it arrives (e.g. seeing the
+     * intermediate `CA` frame in HL7v2 enhanced mode), use
+     * {@link MllpClient.stream} instead.
+     */
+    send(message: string | Uint8Array, options?: SendOptions): Promise<Acknowledgment>;
+    /**
+     * Send a single HL7v2 message and yield each accept ACK as it
+     * arrives. The iterable completes after the resolving frame.
+     *
+     * In HL7v2 enhanced mode the iterable yields `CA` then the
+     * application-level ACK; in basic mode it yields a single
+     * application-level ACK. NAK codes (`AE`/`AR`/`CE`/`CR`) throw the
+     * matching `AckException` from the iterator with the wire-format
+     * ACK on `error.raw`.
+     *
+     * Use {@link MllpClient.send} for the simple "give me the resolving
+     * answer" case.
+     */
+    stream(message: string | Uint8Array, options?: SendOptions): AsyncIterable<Acknowledgment>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/core/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAS7C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,EAAE,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IACzB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC3B,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC1B,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,OAAO,EAAE,WAAW,CAAC;IACrB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,GAAG,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,QAAQ,GAAG,eAAe,GAAG,UAAU,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAaD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,UAAU;;gBAQT,OAAO,EAAE,iBAAiB;IAmBtC,wCAAwC;IACxC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,wCAAwC;IACxC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;;;;;;;;;OAgBG;IACG,IAAI,CACR,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,cAAc,CAAC;IAmB1B;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,OAAO,GAAE,WAAgB,GACxB,aAAa,CAAC,cAAc,CAAC;CA+GjC"}

package/dist/core/connect.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Public types for the runtime-free core of `@glion/mllp-client`.
+ *
+ * These types describe the shape of the pluggable transport that the
+ * client uses to read and write bytes on the wire. The core does not
+ * import any runtime-specific module — every connection is opened by
+ * a {@link MllpConnect} function the caller supplies. Per-runtime
+ * adapters (`@glion/mllp-client/node`, `/deno`, `/workers`) ship
+ * pre-wired implementations so most callers never write a `connect`
+ * function themselves.
+ *
+ * @module
+ */
+import type { MllpClientTlsOptions } from "./client";
+/**
+ * Connect to an MLLP receiver and return a {@link MllpDuplexStream}
+ * over which the client will write the framed message and read the
+ * acknowledgment.
+ *
+ * Implementations must:
+ *
+ * - Resolve once the underlying transport is ready for I/O (TCP `connect` has
+ *   fired, or the TLS handshake has completed when `tls` is set).
+ * - Reject with a thrown `Error` if the connection cannot be established. The
+ *   client maps native errors into typed `MllpClientError` instances.
+ * - Honour `signal` if the caller passes one — abort the connect attempt and
+ *   reject when the signal aborts. Future revisions of the client may pass a
+ *   signal here to enforce the connect-phase deadline.
+ *
+ * The returned duplex must remain usable until {@link MllpDuplexStream.close}
+ * is called.
+ */
+export type MllpConnect = (params: MllpConnectParams) => Promise<MllpDuplexStream>;
+/**
+ * Parameters supplied to a {@link MllpConnect} implementation.
+ */
+export interface MllpConnectParams {
+    /** Hostname or IP of the receiver. */
+    host: string;
+    /** TCP port of the receiver. */
+    port: number;
+    /**
+     * TLS configuration. When set, the connector should establish a TLS
+     * connection (rather than plain TCP).
+     */
+    tls?: MllpClientTlsOptions;
+    /**
+     * Optional abort signal. Implementations should listen for `abort`
+     * and tear the partial connection down so that the client's deadline
+     * fires cleanly.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * A Web-Streams duplex over which the client reads and writes bytes.
+ *
+ * The runtime adapters wrap their native socket types into this shape.
+ * The core has no awareness of the underlying transport — TCP, TLS,
+ * a WebSocket bridge, or an in-memory pipe (for tests) all work
+ * provided they expose Web Streams.
+ */
+export interface MllpDuplexStream {
+    /** Inbound byte stream from the receiver. */
+    readonly readable: ReadableStream<Uint8Array>;
+    /** Outbound byte stream to the receiver. */
+    readonly writable: WritableStream<Uint8Array>;
+    /**
+     * Tear the connection down. The client calls `close()` both from
+     * the abort signal handler (to interrupt pending I/O) and from a
+     * `finally` block (final cleanup).
+     *
+     * Implementations **must**:
+     *
+     * - Be **idempotent** — `close()` may be called multiple times on the same
+     *   duplex (typically twice: once from the abort handler when the signal
+     *   fires, once from the `finally` block as the generator unwinds).
+     * - **Resolve, never reject.** The client does **not** wrap `close()` in
+     *   `try/catch` — error handling for cleanup belongs at the adapter layer,
+     *   where each runtime knows what its socket primitives can fail with. A
+     *   rejection from the abort handler would surface as an unhandled promise
+     *   rejection; a rejection from the `finally` block would replace any
+     *   in-flight error (NAK exception, transport error) with a confusing
+     *   close-time error. Adapters must absorb their own idempotency and teardown
+     *   errors internally and resolve cleanly.
+     * - **Propagate the close into the readable side** so that any pending
+     *   `reader.read()` settles. Real sockets do this naturally via the
+     *   underlying transport's close. Test fakes must close their readable
+     *   controller from inside `close()` to honour the same contract.
+     *
+     * The return type is `Promise<void>` so that adapters whose underlying
+     * transport has async destruction (e.g. Cloudflare Workers'
+     * `socket.close()`) can model it honestly. Adapters with sync teardown
+     * (e.g. Node's `socket.destroy()`) wrap as a trivially-resolving async
+     * function. The client awaits `close()` in `finally` blocks so resource
+     * release is observable; the abort handler fires-and-forgets via
+     * `void duplex.close()` since the abort path does not need to await
+     * teardown.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=connect.d.ts.map

package/dist/core/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/core/connect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAErD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,MAAM,EAAE,iBAAiB,KACtB,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/B;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,GAAG,CAAC,EAAE,oBAAoB,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAC9C,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAC9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/core/errors.d.ts

@@ -0,0 +1,81 @@
+import { MllpError } from "@glion/mllp-transport";
+import type { MllpErrorOptions } from "@glion/mllp-transport";
+/**
+ * Machine-readable codes for `MllpClient` transport failures.
+ *
+ * These cover everything that can go wrong between the moment
+ * `MllpClient.send()` is called and the moment a complete ACK frame
+ * has been decoded — i.e. everything that is not an HL7v2
+ * application-level NAK. NAK responses (MSA-1 ∈ {AE, AR, CE, CR})
+ * surface as `AckException` subclasses thrown directly from
+ * `@glion/ack`, not as transport errors.
+ */
+export declare const MllpClientErrorCode: {
+    /** No ACK arrived within the configured `timeout`. */
+    /** The peer closed the connection before a complete ACK arrived. */
+    readonly CONNECTION_CLOSED: "CONNECTION_CLOSED";
+    /** TCP connection could not be established (refused, DNS, routing). */
+    readonly CONNECTION_REFUSED: "CONNECTION_REFUSED";
+    /**
+     * The caller passed a payload that could not be MLLP-encoded —
+     * typically because it was not a `string` or `Uint8Array`. Also
+     * surfaced when constructor options fail validation (bad
+     * host/port/timeout/etc). Thrown before any socket is opened, so
+     * no connection is made and no resources need cleanup.
+     */
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly MALFORMED_ACK: "MALFORMED_ACK";
+    /** The remote sent bytes that did not form a valid MLLP frame. */
+    readonly MALFORMED_FRAME: "MALFORMED_FRAME";
+    /** A frame was received but could not be parsed as a valid HL7v2 ACK. */
+    readonly TIMEOUT: "TIMEOUT";
+    /**
+     * TLS handshake failed — typically because of certificate
+     * verification, hostname mismatch, expired cert, untrusted CA, or
+     * a TLS protocol error. Distinct from `CONNECTION_REFUSED` (the
+     * TCP connection succeeded but the TLS upgrade failed) so
+     * operators can identify TLS misconfiguration quickly in
+     * healthcare deployments where it is a recurring incident class.
+     */
+    readonly TLS_HANDSHAKE_FAILED: "TLS_HANDSHAKE_FAILED";
+};
+export type MllpClientErrorCode = (typeof MllpClientErrorCode)[keyof typeof MllpClientErrorCode];
+/**
+ * Error thrown by `MllpClient.send()` for transport-level failures.
+ *
+ * Extends {@link MllpError} so callers can catch any MLLP error —
+ * server- or client-side — with a single `instanceof MllpError`
+ * check. The {@link MllpClientErrorCode | code} field discriminates
+ * the failure mode for typed handling.
+ *
+ * Application-level NAK responses are **not** thrown as
+ * `MllpClientError`; they are thrown as `AckException` subclasses
+ * from `@glion/ack`. A typical `catch` block handles both:
+ *
+ * ```ts
+ * import { AckException } from "@glion/ack";
+ * import { MllpClientError } from "@glion/mllp-client";
+ *
+ * try {
+ *   await client.send(message);
+ * } catch (error) {
+ *   if (error instanceof AckException) {
+ *     // Application-level NAK.
+ *   } else if (error instanceof MllpClientError) {
+ *     // Transport-level failure.
+ *   }
+ * }
+ * ```
+ */
+export declare class MllpClientError extends MllpError {
+    /**
+     * Narrowed view of the inherited `MllpError.code` field. `declare`
+     * keeps the runtime value (set by the base constructor) while
+     * exposing the discriminated {@link MllpClientErrorCode} union to
+     * TypeScript — callers can `switch` on `error.code` with full
+     * exhaustiveness checking.
+     */
+    readonly code: MllpClientErrorCode;
+    constructor(code: MllpClientErrorCode, message: string, options?: MllpErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;IAC9B,sDAAsD;IACtD,oEAAoE;;IAEpE,uEAAuE;;IAEvE;;;;;;OAMG;;;IAGH,kEAAkE;;IAElE,yEAAyE;;IAEzE;;;;;;;OAOG;;CAEK,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAC7B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC5C;;;;;;OAMG;IACH,SAAiB,IAAI,EAAE,mBAAmB,CAAC;gBAGzC,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,gBAAgB;CAK7B"}

package/dist/core/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Runtime-free entry point of `@glion/mllp-client`.
+ *
+ * Use this when you need to run the client in a non-standard runtime
+ * (for example, in a browser via a WebSocket-to-MLLP gateway, or
+ * with an in-memory pipe for tests). Construction requires you to
+ * supply your own {@link MllpConnect} function.
+ *
+ * For the common case (Node, Bun, Deno, Cloudflare Workers), prefer
+ * the per-runtime adapters which ship a pre-wired connector:
+ *
+ * - `@glion/mllp-client` — Node and Bun (default entry)
+ * - `@glion/mllp-client/deno` — Deno
+ * - `@glion/mllp-client/workers` — Cloudflare Workers
+ *
+ * @module
+ */
+export type { Acknowledgment } from "./acknowledgment";
+export { MllpClient } from "./client";
+export type { BoundMllpClientOptions, MllpClientOptions, MllpClientTlsOptions, SendMode, SendOptions, } from "./client";
+export type { MllpConnect, MllpConnectParams, MllpDuplexStream, } from "./connect";
+export { MllpClientError, MllpClientErrorCode } from "./errors";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EACV,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,QAAQ,EACR,WAAW,GACZ,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,2 @@
+import { i as MllpClientErrorCode, r as MllpClientError, t as MllpClient } from "../client.js";
+export { MllpClient, MllpClientError, MllpClientErrorCode };

package/dist/core/internal/ack-parser-stream.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `TransformStream<DecodedMessage, Acknowledgment>` that parses each
+ * decoded MLLP frame as an HL7v2 acknowledgment. Internal to
+ * `@glion/mllp-client`.
+ *
+ * On a malformed ACK the transform errors the readable with the
+ * typed `MllpClientError(MALFORMED_ACK)` from {@link parseAck}.
+ * Downstream `for await ... of` consumers reject with that error;
+ * `MllpClient.send()` translates it at its single catch site.
+ *
+ * @module
+ */
+import type { DecodedMessage } from "@glion/mllp-transport";
+import type { Acknowledgment } from "../acknowledgment";
+/**
+ * Build a transform that consumes decoded MLLP frames and produces
+ * parsed `Acknowledgment` objects. A parse failure errors the
+ * readable side rather than enqueuing — the consumer's `for await`
+ * loop rejects with the typed error.
+ */
+export declare function createAckParserStream(): TransformStream<DecodedMessage, Acknowledgment>;
+//# sourceMappingURL=ack-parser-stream.d.ts.map

package/dist/core/internal/ack-parser-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ack-parser-stream.d.ts","sourceRoot":"","sources":["../../../src/core/internal/ack-parser-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CACtD,cAAc,EACd,cAAc,CACf,CAUA"}

package/dist/core/internal/subscribe-abort.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Subscribe to an `AbortSignal` and run a callback once if it
+ * aborts. Returns a disposer that unsubscribes — call it from a
+ * `finally` block so we never leak listeners.
+ *
+ * If the signal is already aborted at subscription time, the
+ * callback fires synchronously and the returned disposer is a
+ * no-op. This collapses the "aborted vs aborting" branch every
+ * caller would otherwise need to write by hand.
+ *
+ * Internal to `@glion/mllp-client`.
+ *
+ * @module
+ */
+/**
+ * Subscribe `onAbort` to fire once when `signal` aborts. Returns a
+ * disposer that removes the listener.
+ *
+ * @example
+ *   ```ts
+ *   const dispose = subscribeAbort(signal, () => socket.destroy());
+ *   try {
+ *     await waitForReady(socket);
+ *   } finally {
+ *     dispose();
+ *   }
+ *   ```;
+ */
+export declare function subscribeAbort(signal: AbortSignal, onAbort: () => void): () => void;
+//# sourceMappingURL=subscribe-abort.d.ts.map

package/dist/core/internal/subscribe-abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscribe-abort.d.ts","sourceRoot":"","sources":["../../../src/core/internal/subscribe-abort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,IAAI,GAClB,MAAM,IAAI,CAOZ"}