@labacacia/nps-sdk 1.0.0-alpha.3 → 1.0.0-alpha.5

package/dist/ncp/preamble.js

@@ -0,0 +1,74 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * NCP native-mode connection preamble — the 8-byte ASCII constant
+ * `"NPS/1.0\n"` that every native-mode client MUST emit immediately
+ * after the transport handshake and before its first HelloFrame.
+ * Defined by NPS-RFC-0001 and NPS-1 NCP §2.6.1.
+ *
+ * HTTP-mode connections do not use the preamble.
+ */
+export const PREAMBLE_LITERAL = "NPS/1.0\n";
+export const PREAMBLE_LENGTH = 8;
+export const PREAMBLE_BYTES = new TextEncoder().encode(PREAMBLE_LITERAL);
+/** Validation timeout in milliseconds (NPS-RFC-0001 §4.1). */
+export const PREAMBLE_READ_TIMEOUT_MS = 10_000;
+/** Maximum delay before closing after a mismatch, in milliseconds. */
+export const PREAMBLE_CLOSE_DEADLINE_MS = 500;
+export const PREAMBLE_ERROR_CODE = "NCP-PREAMBLE-INVALID";
+export const PREAMBLE_STATUS_CODE = "NPS-PROTO-PREAMBLE-INVALID";
+export class NcpPreambleInvalidError extends Error {
+    errorCode = PREAMBLE_ERROR_CODE;
+    statusCode = PREAMBLE_STATUS_CODE;
+    constructor(reason) {
+        super(reason);
+        this.name = "NcpPreambleInvalidError";
+    }
+}
+/**
+ * Returns `true` iff `buf` starts with the 8-byte NPS/1.0 preamble.
+ * Safe to call with shorter buffers.
+ */
+export function preambleMatches(buf) {
+    if (buf.length < PREAMBLE_LENGTH)
+        return false;
+    for (let i = 0; i < PREAMBLE_LENGTH; i++) {
+        if (buf[i] !== PREAMBLE_BYTES[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Validates a presumed-preamble buffer.
+ * Returns `{ valid: true, reason: "" }` on success or `{ valid: false, reason }` on failure.
+ */
+export function tryValidatePreamble(buf) {
+    if (buf.length < PREAMBLE_LENGTH) {
+        return { valid: false, reason: `short read (${buf.length}/${PREAMBLE_LENGTH} bytes); peer is not speaking NCP` };
+    }
+    if (!preambleMatches(buf)) {
+        // "NPS/" = 0x4E 0x50 0x53 0x2F
+        const isNps = buf[0] === 0x4e && buf[1] === 0x50 && buf[2] === 0x53 && buf[3] === 0x2f;
+        if (isNps) {
+            return { valid: false, reason: "future-major-version NPS preamble; close with NPS-PREAMBLE-UNSUPPORTED-VERSION diagnostic" };
+        }
+        return { valid: false, reason: "preamble mismatch; peer is not speaking NPS/1.x" };
+    }
+    return { valid: true, reason: "" };
+}
+/**
+ * Validates a presumed-preamble buffer, throwing {@link NcpPreambleInvalidError} on mismatch.
+ */
+export function validatePreamble(buf) {
+    const { valid, reason } = tryValidatePreamble(buf);
+    if (!valid)
+        throw new NcpPreambleInvalidError(reason);
+}
+/**
+ * Writes the preamble bytes to `writer`.
+ * `writer` must expose a `write(buf: Uint8Array): void` method (e.g. Node.js `net.Socket`).
+ */
+export function writePreamble(writer) {
+    writer.write(PREAMBLE_BYTES);
+}
+//# sourceMappingURL=preamble.js.map

package/dist/ncp/preamble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preamble.js","sourceRoot":"","sources":["../../src/ncp/preamble.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,sCAAsC;AAEtC;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAC5C,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AACjC,MAAM,CAAC,MAAM,cAAc,GAAe,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;AACrF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAC/C,sEAAsE;AACtE,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAE9C,MAAM,CAAC,MAAM,mBAAmB,GAAI,sBAAsB,CAAC;AAC3D,MAAM,CAAC,MAAM,oBAAoB,GAAG,4BAA4B,CAAC;AAEjE,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACvC,SAAS,GAAI,mBAAmB,CAAC;IACjC,UAAU,GAAG,oBAAoB,CAAC;IAE3C,YAAY,MAAc;QACxB,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAe;IAC7C,IAAI,GAAG,CAAC,MAAM,GAAG,eAAe;QAAE,OAAO,KAAK,CAAC;IAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,eAAe,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,cAAc,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACjD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAe;IACjD,IAAI,GAAG,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACjC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,GAAG,CAAC,MAAM,IAAI,eAAe,mCAAmC,EAAE,CAAC;IACnH,CAAC;IACD,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,+BAA+B;QAC/B,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;QACvF,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,2FAA2F,EAAE,CAAC;QAC/H,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,iDAAiD,EAAE,CAAC;IACrF,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAe;IAC9C,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IACnD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAwC;IACpE,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;AAC/B,CAAC"}

package/dist/ncp/registry.js

@@ -0,0 +1,13 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+import { FrameType } from "../core/frames.js";
+import { AnchorFrame, CapsFrame, DiffFrame, ErrorFrame, HelloFrame, StreamFrame } from "./frames.js";
+export function registerNcpFrames(registry) {
+    registry.register(FrameType.ANCHOR, AnchorFrame);
+    registry.register(FrameType.DIFF, DiffFrame);
+    registry.register(FrameType.STREAM, StreamFrame);
+    registry.register(FrameType.CAPS, CapsFrame);
+    registry.register(FrameType.HELLO, HelloFrame);
+    registry.register(FrameType.ERROR, ErrorFrame);
+}
+//# sourceMappingURL=registry.js.map

package/dist/ncp/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/ncp/registry.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,sCAAsC;AAGtC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAErG,MAAM,UAAU,iBAAiB,CAAC,QAAuB;IACvD,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAI,SAAS,CAAC,CAAC;IAC/C,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAI,SAAS,CAAC,CAAC;IAC/C,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAG,UAAU,CAAC,CAAC;IAChD,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAG,UAAU,CAAC,CAAC;AAClD,CAAC"}

package/dist/ncp/stream-manager.js

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// StreamManager — Concurrent stream tracking, sequence validation, flow control
+// NPS-1 §4.3, §7.3
+import { NcpError } from "../core/frame-header.js";
+import { NCP_ERROR_CODES } from "./ncp-error-codes.js";
+/**
+ * Manages concurrent StreamFrame streams.
+ *
+ * - Tracks active streams by stream_id
+ * - Validates sequential seq numbers
+ * - Enforces max concurrent stream limit (NPS-1 §7.3, default 32)
+ * - Detects early termination via error_code
+ * - Enforces window-based flow control on outgoing streams (NCP-S-07–11)
+ */
+export class StreamManager {
+    streams = new Map();
+    outgoing = new Map();
+    maxConcurrent;
+    constructor(options) {
+        this.maxConcurrent = options?.maxConcurrent ?? 32;
+    }
+    /**
+     * Receive a StreamFrame chunk.
+     *
+     * @returns true if stream is complete (is_last=true or error_code set).
+     * @throws {NcpError} NCP-STREAM-LIMIT-EXCEEDED if too many concurrent streams.
+     * @throws {NcpError} NCP-STREAM-NOT-FOUND if frame.seq > 0 for a stream that was never opened.
+     * @throws {NcpError} NPS-CLIENT-CONFLICT if the stream_id was already completed (stream-id reuse; see test_cases NCP-S-04).
+     * @throws {NcpError} NCP-STREAM-SEQ-GAP if sequence number is not expected.
+     */
+    receive(frame) {
+        let stream = this.streams.get(frame.stream_id);
+        if (!stream) {
+            // A stream is opened only by seq=0. Any other seq on an unknown stream_id
+            // means the opener was never seen (NCP-S-13: unknown stream_id).
+            if (frame.seq !== 0) {
+                throw new NcpError(NCP_ERROR_CODES.NCP_STREAM_NOT_FOUND, `Unknown stream_id ${frame.stream_id} — first frame must have seq=0`);
+            }
+            // New stream — check concurrent limit
+            if (this.streams.size >= this.maxConcurrent) {
+                throw new NcpError(NCP_ERROR_CODES.NCP_STREAM_LIMIT_EXCEEDED, `Max concurrent streams (${this.maxConcurrent}) exceeded`);
+            }
+            stream = {
+                streamId: frame.stream_id,
+                expectedSeq: 0,
+                chunks: [],
+                completed: false,
+            };
+            this.streams.set(frame.stream_id, stream);
+        }
+        // Reject writes to completed streams. Per test_cases NCP-S-04, the spec does
+        // not assign a dedicated NCP code for stream-id reuse; interim mapping uses
+        // the NPS-level NPS-CLIENT-CONFLICT until a spec-side code is added.
+        if (stream.completed) {
+            throw new NcpError("NPS-CLIENT-CONFLICT", `Stream ${frame.stream_id} is already completed — cannot reuse stream_id`);
+        }
+        // Sequence validation
+        if (frame.seq !== stream.expectedSeq) {
+            // Duplicate detection — same seq as last accepted
+            if (frame.seq < stream.expectedSeq) {
+                // Ignore duplicate (idempotent)
+                return false;
+            }
+            throw new NcpError(NCP_ERROR_CODES.NCP_STREAM_SEQ_GAP, `Expected seq ${stream.expectedSeq}, got ${frame.seq} on stream ${frame.stream_id}`);
+        }
+        stream.chunks.push(frame.data);
+        stream.expectedSeq = frame.seq + 1;
+        // Early termination via error_code
+        if (frame.error_code) {
+            stream.completed = true;
+            stream.errorCode = frame.error_code;
+            return true;
+        }
+        // Normal completion
+        if (frame.is_last) {
+            stream.completed = true;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Send a StreamFrame on an outgoing stream, enforcing window-based flow control.
+     *
+     * - seq=0 with window_size initialises remainingWindow (no decrement for opening frame).
+     * - Subsequent sends decrement remainingWindow when flow control is active.
+     * - Throws NCP-STREAM-WINDOW-OVERFLOW when remainingWindow === 0.
+     *
+     * @throws {NcpError} NCP-STREAM-WINDOW-OVERFLOW if window is exhausted.
+     */
+    send(frame) {
+        let out = this.outgoing.get(frame.stream_id);
+        if (!out) {
+            out = {
+                streamId: frame.stream_id,
+                remainingWindow: undefined,
+                paused: false,
+            };
+            this.outgoing.set(frame.stream_id, out);
+        }
+        // Opening frame: initialise window from window_size if provided.
+        if (frame.seq === 0 && frame.window_size !== undefined) {
+            out.remainingWindow = frame.window_size;
+            return; // opening frame does not consume a window slot
+        }
+        // Flow control check for subsequent frames.
+        if (out.remainingWindow !== undefined) {
+            if (out.remainingWindow === 0) {
+                throw new NcpError(NCP_ERROR_CODES.NCP_STREAM_WINDOW_OVERFLOW, `Window exhausted on stream ${frame.stream_id}`);
+            }
+            out.remainingWindow -= 1;
+        }
+    }
+    /**
+     * Update the send window for a stream.
+     *
+     * Called when a reverse-direction StreamFrame arrives with data=[] and window_size set.
+     * Replaces remainingWindow with new_size. Sets paused=true when new_size === 0.
+     */
+    updateWindow(streamId, newSize) {
+        let out = this.outgoing.get(streamId);
+        if (!out) {
+            out = {
+                streamId,
+                remainingWindow: newSize,
+                paused: newSize === 0,
+            };
+            this.outgoing.set(streamId, out);
+            return;
+        }
+        out.remainingWindow = newSize;
+        out.paused = newSize === 0;
+    }
+    /**
+     * Returns true when the outgoing stream is paused (window=0 was received).
+     * Resumes (returns false) once a non-zero window update arrives.
+     */
+    isPaused(streamId) {
+        return this.outgoing.get(streamId)?.paused ?? false;
+    }
+    /** Get reassembled data for a completed stream. */
+    getData(streamId) {
+        const stream = this.streams.get(streamId);
+        if (!stream || !stream.completed)
+            return null;
+        return stream.chunks.flat();
+    }
+    /** Get error code if stream terminated with error. */
+    getError(streamId) {
+        return this.streams.get(streamId)?.errorCode;
+    }
+    /** Number of active (non-completed) streams. */
+    get activeCount() {
+        let count = 0;
+        for (const s of this.streams.values()) {
+            if (!s.completed)
+                count++;
+        }
+        return count;
+    }
+}
+//# sourceMappingURL=stream-manager.js.map

package/dist/ncp/stream-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-manager.js","sourceRoot":"","sources":["../../src/ncp/stream-manager.ts"],"names":[],"mappings":"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"}

package/dist/ndp/dns-txt.d.ts

@@ -0,0 +1,35 @@
+import type { NdpResolveResult } from "./frames.js";
+export declare const DNS_TXT_DEFAULT_TTL = 300;
+/**
+ * Extract the hostname from an NWP target URI.
+ * e.g. "nwp://api.example.com/products" → "api.example.com"
+ */
+export declare function extractHostFromTarget(target: string): string | undefined;
+/**
+ * Parse one TXT record (array of string chunks) into an NdpResolveResult.
+ *
+ * Expected format (chunks joined with a single space):
+ *   v=nps1 type=<type> port=<port> nid=<nid> fp=sha256:<fingerprint>
+ *
+ * Rules:
+ *  - `v` MUST be present and equal to "nps1"
+ *  - `nid` MUST be present
+ *  - `port` defaults to 17433 when absent
+ *  - `fp` is mapped to certFingerprint
+ */
+export declare function parseNpsTxtRecord(parts: string[], host: string): NdpResolveResult | undefined;
+/**
+ * Abstraction over DNS TXT lookups.
+ * The default implementation uses Node's `dns.promises`; pass a mock in tests.
+ */
+export interface DnsTxtLookup {
+    resolveTxt(hostname: string): Promise<string[][]>;
+}
+/**
+ * System DNS TXT resolver backed by Node's built-in `dns.promises`.
+ * The dynamic `import()` keeps browser bundles from failing at parse time.
+ */
+export declare class SystemDnsTxtLookup implements DnsTxtLookup {
+    resolveTxt(hostname: string): Promise<string[][]>;
+}
+//# sourceMappingURL=dns-txt.d.ts.map

package/dist/ndp/dns-txt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns-txt.d.ts","sourceRoot":"","sources":["../../src/ndp/dns-txt.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,EAAE,MAAM,GACX,gBAAgB,GAAG,SAAS,CAgC9B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;CACnD;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IAC/C,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CAIxD"}

package/dist/ndp/dns-txt.js

@@ -0,0 +1,67 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+export const DNS_TXT_DEFAULT_TTL = 300;
+/**
+ * Extract the hostname from an NWP target URI.
+ * e.g. "nwp://api.example.com/products" → "api.example.com"
+ */
+export function extractHostFromTarget(target) {
+    if (!target.startsWith("nwp://"))
+        return undefined;
+    const rest = target.slice("nwp://".length);
+    const slashIdx = rest.indexOf("/");
+    const host = slashIdx === -1 ? rest : rest.slice(0, slashIdx);
+    return host.length > 0 ? host : undefined;
+}
+/**
+ * Parse one TXT record (array of string chunks) into an NdpResolveResult.
+ *
+ * Expected format (chunks joined with a single space):
+ *   v=nps1 type=<type> port=<port> nid=<nid> fp=sha256:<fingerprint>
+ *
+ * Rules:
+ *  - `v` MUST be present and equal to "nps1"
+ *  - `nid` MUST be present
+ *  - `port` defaults to 17433 when absent
+ *  - `fp` is mapped to certFingerprint
+ */
+export function parseNpsTxtRecord(parts, host) {
+    const joined = parts.join(" ");
+    const kv = new Map();
+    for (const token of joined.split(/\s+/)) {
+        const eq = token.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = token.slice(0, eq);
+        const val = token.slice(eq + 1);
+        kv.set(key, val);
+    }
+    if (kv.get("v") !== "nps1")
+        return undefined;
+    const nid = kv.get("nid");
+    if (!nid)
+        return undefined;
+    const rawPort = kv.get("port");
+    const port = rawPort !== undefined ? Number(rawPort) : 17433;
+    const fp = kv.get("fp");
+    const result = {
+        host,
+        port,
+        ttl: DNS_TXT_DEFAULT_TTL,
+    };
+    if (fp !== undefined) {
+        result.certFingerprint = fp;
+    }
+    return result;
+}
+/**
+ * System DNS TXT resolver backed by Node's built-in `dns.promises`.
+ * The dynamic `import()` keeps browser bundles from failing at parse time.
+ */
+export class SystemDnsTxtLookup {
+    async resolveTxt(hostname) {
+        const { promises: dns } = await import("node:dns");
+        return dns.resolveTxt(hostname);
+    }
+}
+//# sourceMappingURL=dns-txt.js.map

package/dist/ndp/dns-txt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns-txt.js","sourceRoot":"","sources":["../../src/ndp/dns-txt.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,sCAAsC;AAItC,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IACnD,MAAM,IAAI,GAAO,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,IAAI,GAAO,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAe,EACf,IAAY;IAEZ,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,EAAE,GAAO,IAAI,GAAG,EAAkB,CAAC;IAEzC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,SAAS;QACxB,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAChC,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACnB,CAAC;IAED,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,MAAM;QAAE,OAAO,SAAS,CAAC;IAE7C,MAAM,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAE3B,MAAM,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAM,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAChE,MAAM,EAAE,GAAQ,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAE7B,MAAM,MAAM,GAAqB;QAC/B,IAAI;QACJ,IAAI;QACJ,GAAG,EAAE,mBAAmB;KACzB,CAAC;IAEF,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,MAAM,CAAC,eAAe,GAAG,EAAE,CAAC;IAC9B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAUD;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IAC7B,KAAK,CAAC,UAAU,CAAC,QAAgB;QAC/B,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QACnD,OAAO,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;CACF"}

package/dist/ndp/frames.js

@@ -0,0 +1,87 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+import { EncodingTier, FrameType } from "../core/frames.js";
+export class AnnounceFrame {
+    nid;
+    addresses;
+    capabilities;
+    ttl;
+    timestamp;
+    signature;
+    nodeType;
+    frameType = FrameType.ANNOUNCE;
+    preferredTier = EncodingTier.MSGPACK;
+    constructor(nid, addresses, capabilities, ttl, timestamp, signature, nodeType) {
+        this.nid = nid;
+        this.addresses = addresses;
+        this.capabilities = capabilities;
+        this.ttl = ttl;
+        this.timestamp = timestamp;
+        this.signature = signature;
+        this.nodeType = nodeType;
+    }
+    unsignedDict() {
+        return {
+            nid: this.nid,
+            addresses: this.addresses,
+            capabilities: this.capabilities,
+            ttl: this.ttl,
+            timestamp: this.timestamp,
+            node_type: this.nodeType ?? null,
+        };
+    }
+    toDict() {
+        return { ...this.unsignedDict(), signature: this.signature };
+    }
+    static fromDict(data) {
+        return new AnnounceFrame(data["nid"], data["addresses"], data["capabilities"], data["ttl"], data["timestamp"], data["signature"], data["node_type"] ?? undefined);
+    }
+}
+export class ResolveFrame {
+    target;
+    requesterNid;
+    resolved;
+    frameType = FrameType.RESOLVE;
+    preferredTier = EncodingTier.MSGPACK;
+    constructor(target, requesterNid, resolved) {
+        this.target = target;
+        this.requesterNid = requesterNid;
+        this.resolved = resolved;
+    }
+    toDict() {
+        return {
+            target: this.target,
+            requester_nid: this.requesterNid ?? null,
+            resolved: this.resolved ?? null,
+        };
+    }
+    static fromDict(data) {
+        return new ResolveFrame(data["target"], data["requester_nid"] ?? undefined, data["resolved"] ?? undefined);
+    }
+}
+export class GraphFrame {
+    seq;
+    initialSync;
+    nodes;
+    patch;
+    frameType = FrameType.GRAPH;
+    preferredTier = EncodingTier.MSGPACK;
+    constructor(seq, initialSync, nodes, patch) {
+        this.seq = seq;
+        this.initialSync = initialSync;
+        this.nodes = nodes;
+        this.patch = patch;
+    }
+    toDict() {
+        return {
+            seq: this.seq,
+            initial_sync: this.initialSync,
+            nodes: this.nodes ?? null,
+            patch: this.patch ?? null,
+        };
+    }
+    static fromDict(data) {
+        return new GraphFrame(data["seq"], data["initial_sync"], data["nodes"] ?? undefined, data["patch"] ?? undefined);
+    }
+}
+//# sourceMappingURL=frames.js.map

package/dist/ndp/frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.js","sourceRoot":"","sources":["../../src/ndp/frames.ts"],"names":[],"mappings":"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"}

package/dist/ndp/index.d.ts

@@ -2,4 +2,5 @@ export * from "./frames.js";
 export * from "./registry.js";
 export * from "./ndp-registry.js";
 export * from "./validator.js";
+export * from "./dns-txt.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ndp/index.ts"],"names":[],"mappings":"AAGA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ndp/index.ts"],"names":[],"mappings":"AAGA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC"}