@labacacia/nps-sdk 1.0.0-alpha.6 → 1.0.0-alpha.7

package/dist/core/codec.d.ts

@@ -0,0 +1,32 @@
+import { EncodingTier, FrameHeader, FrameType } from "./frames.js";
+import type { FrameRegistry } from "./registry.js";
+export interface NpsFrame {
+    readonly frameType: FrameType;
+    readonly preferredTier: EncodingTier;
+    toDict(): Record<string, unknown>;
+}
+export declare class Tier1JsonCodec {
+    encode(frame: NpsFrame): Uint8Array;
+    decode(frameType: FrameType, payload: Uint8Array, registry: FrameRegistry): NpsFrame;
+}
+export declare class Tier2MsgPackCodec {
+    encode(frame: NpsFrame): Uint8Array;
+    decode(frameType: FrameType, payload: Uint8Array, registry: FrameRegistry): NpsFrame;
+}
+export declare class NpsFrameCodec {
+    private readonly _registry;
+    private readonly _maxPayload;
+    private readonly _json;
+    private readonly _msgpack;
+    constructor(registry: FrameRegistry, options?: {
+        maxPayload?: number;
+    });
+    encode(frame: NpsFrame, options?: {
+        overrideTier?: EncodingTier;
+    }): Uint8Array;
+    decode(wire: Uint8Array): NpsFrame;
+    static peekHeader(wire: Uint8Array): FrameHeader;
+    private _buildFlags;
+    private _selectCodec;
+}
+//# sourceMappingURL=codec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/core/codec.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,YAAY,EAEZ,WAAW,EACX,SAAS,EACV,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,YAAY,CAAC;IACrC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAID,qBAAa,cAAc;IACzB,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU;IAWnC,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,GAAG,QAAQ;CAYrF;AAID,qBAAa,iBAAiB;IAC5B,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU;IAUnC,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,GAAG,QAAQ;CAWrF;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;gBAExC,QAAQ,EAAE,aAAa,EAAE,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO;IAO1E,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,YAAY,CAAA;KAAO,GAAG,UAAU;IAiClF,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ;IAOlC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW;IAMhD,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,YAAY;CAKrB"}

package/dist/core/codec.js

@@ -0,0 +1,119 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * NPS frame codec: Tier-1 (JSON) and Tier-2 (MsgPack) encode/decode,
+ * plus the top-level NpsFrameCodec dispatcher.
+ */
+import * as msgpack from "@msgpack/msgpack";
+import { NpsCodecError } from "./exceptions.js";
+import { DEFAULT_MAX_PAYLOAD, EncodingTier, FrameFlags, FrameHeader, } from "./frames.js";
+// ── Tier-1 JSON codec ─────────────────────────────────────────────────────────
+export class Tier1JsonCodec {
+    encode(frame) {
+        try {
+            const json = JSON.stringify(frame.toDict());
+            return new TextEncoder().encode(json);
+        }
+        catch (err) {
+            throw new NpsCodecError(`Tier-1 JSON encode failed for 0x${frame.frameType.toString(16).padStart(2, "0")}: ${String(err)}`);
+        }
+    }
+    decode(frameType, payload, registry) {
+        const cls = registry.resolve(frameType);
+        try {
+            const text = new TextDecoder().decode(payload);
+            const data = JSON.parse(text);
+            return cls.fromDict(data);
+        }
+        catch (err) {
+            throw new NpsCodecError(`Tier-1 JSON decode failed for 0x${frameType.toString(16).padStart(2, "0")}: ${String(err)}`);
+        }
+    }
+}
+// ── Tier-2 MsgPack codec ──────────────────────────────────────────────────────
+export class Tier2MsgPackCodec {
+    encode(frame) {
+        try {
+            return msgpack.encode(frame.toDict());
+        }
+        catch (err) {
+            throw new NpsCodecError(`Tier-2 MsgPack encode failed for 0x${frame.frameType.toString(16).padStart(2, "0")}: ${String(err)}`);
+        }
+    }
+    decode(frameType, payload, registry) {
+        const cls = registry.resolve(frameType);
+        try {
+            const data = msgpack.decode(payload);
+            return cls.fromDict(data);
+        }
+        catch (err) {
+            throw new NpsCodecError(`Tier-2 MsgPack decode failed for 0x${frameType.toString(16).padStart(2, "0")}: ${String(err)}`);
+        }
+    }
+}
+// ── NpsFrameCodec (dispatcher) ────────────────────────────────────────────────
+export class NpsFrameCodec {
+    _registry;
+    _maxPayload;
+    _json = new Tier1JsonCodec();
+    _msgpack = new Tier2MsgPackCodec();
+    constructor(registry, options = {}) {
+        this._registry = registry;
+        this._maxPayload = options.maxPayload ?? DEFAULT_MAX_PAYLOAD;
+    }
+    // ── Encode ────────────────────────────────────────────────────────────────
+    encode(frame, options = {}) {
+        const tier = options.overrideTier ?? frame.preferredTier;
+        const tierCodec = this._selectCodec(tier);
+        let payload;
+        try {
+            payload = tierCodec.encode(frame);
+        }
+        catch (err) {
+            if (err instanceof NpsCodecError)
+                throw err;
+            throw new NpsCodecError(`Encode failed for 0x${frame.frameType.toString(16)}.`);
+        }
+        if (payload.length > this._maxPayload) {
+            throw new NpsCodecError(`Encoded payload for 0x${frame.frameType.toString(16).padStart(2, "0")} exceeds max_frame_payload` +
+                ` (${payload.length} bytes > ${this._maxPayload}). Use StreamFrame (0x03) for large payloads.`);
+        }
+        const useExt = payload.length > DEFAULT_MAX_PAYLOAD;
+        let flags = this._buildFlags(frame, tier);
+        if (useExt)
+            flags |= FrameFlags.EXT;
+        const header = new FrameHeader(frame.frameType, flags, payload.length);
+        const headerBytes = header.toBytes();
+        const wire = new Uint8Array(headerBytes.length + payload.length);
+        wire.set(headerBytes, 0);
+        wire.set(payload, headerBytes.length);
+        return wire;
+    }
+    // ── Decode ────────────────────────────────────────────────────────────────
+    decode(wire) {
+        const header = FrameHeader.parse(wire);
+        const payload = wire.slice(header.headerSize, header.headerSize + header.payloadLength);
+        const codec = this._selectCodec(header.encodingTier);
+        return codec.decode(header.frameType, payload, this._registry);
+    }
+    static peekHeader(wire) {
+        return FrameHeader.parse(wire);
+    }
+    // ── Private ───────────────────────────────────────────────────────────────
+    _buildFlags(frame, tier) {
+        let flags = tier === EncodingTier.JSON ? FrameFlags.TIER1_JSON : FrameFlags.TIER2_MSGPACK;
+        const isStreamFrame = "isLast" in frame;
+        const isFinal = !isStreamFrame || frame.isLast;
+        if (isFinal)
+            flags |= FrameFlags.FINAL;
+        return flags;
+    }
+    _selectCodec(tier) {
+        if (tier === EncodingTier.JSON)
+            return this._json;
+        if (tier === EncodingTier.MSGPACK)
+            return this._msgpack;
+        throw new NpsCodecError(`Unsupported encoding tier: 0x${tier.toString(16).padStart(2, "0")}.`);
+    }
+}
+//# sourceMappingURL=codec.js.map

package/dist/core/codec.js.map

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

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

@@ -0,0 +1,4 @@
+export * from "./ncp-codec.js";
+export { encodeJson, decodeJson } from "./tier1-json-codec.js";
+export { encodeMsgPack, decodeMsgPack } from "./tier2-msgpack-codec.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/codecs/index.ts"],"names":[],"mappings":"AAEA,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC"}

package/{src/core/codecs/index.ts → dist/core/codecs/index.js}

@@ -3,3 +3,4 @@
 export * from "./ncp-codec.js";
 export { encodeJson, decodeJson } from "./tier1-json-codec.js";
 export { encodeMsgPack, decodeMsgPack } from "./tier2-msgpack-codec.js";
+//# sourceMappingURL=index.js.map

package/dist/core/codecs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/codecs/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/core/codecs/ncp-codec.d.ts

@@ -0,0 +1,39 @@
+import { EncodingTier, type FrameHeader } from "../frame-header.js";
+export interface DecodeResult {
+    /** Parsed frame header. */
+    header: FrameHeader;
+    /** Decoded payload object. */
+    payload: unknown;
+    /** Total bytes consumed (header + payload). */
+    bytesConsumed: number;
+}
+export interface EncodeOptions {
+    /** Frame type byte. */
+    frameType: number;
+    /** Encoding tier (default: JSON). */
+    tier?: EncodingTier;
+    /** Set FINAL flag. */
+    final?: boolean;
+    /** Set ENC flag. */
+    encrypted?: boolean;
+    /** Use extended header (for payloads > 64KB). */
+    extended?: boolean;
+}
+export interface CodecOptions {
+    /** Maximum frame payload in bytes (negotiated via CapsFrame). Default: 65535. */
+    maxFramePayload?: number;
+}
+/**
+ * Decode a complete NCP frame from a buffer.
+ *
+ * @returns Decoded header + payload + bytes consumed.
+ * @throws {NcpError} NCP-ENCODING-UNSUPPORTED for reserved tiers.
+ * @throws {NcpError} NCP-FRAME-PAYLOAD-TOO-LARGE if payload exceeds max.
+ * @throws {NcpError} NCP-FRAME-INCOMPLETE if buffer doesn't have enough data.
+ */
+export declare function decodeFrame(buffer: Uint8Array, options?: CodecOptions): DecodeResult;
+/**
+ * Encode a payload into a complete NCP frame (header + payload bytes).
+ */
+export declare function encodeFrame(payload: unknown, options: EncodeOptions): Uint8Array;
+//# sourceMappingURL=ncp-codec.d.ts.map

package/dist/core/codecs/ncp-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ncp-codec.d.ts","sourceRoot":"","sources":["../../../src/core/codecs/ncp-codec.ts"],"names":[],"mappings":"AAMA,OAAO,EAIL,YAAY,EAGZ,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAQ5B,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,sBAAsB;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oBAAoB;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,YAAY,GACrB,YAAY,CA8Cd;AAMD;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,aAAa,GACrB,UAAU,CA+CZ"}

package/dist/core/codecs/ncp-codec.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Codec — Top-level encode/decode dispatcher
+// Routes to Tier-1 JSON or Tier-2 MsgPack based on frame header flags.
+import { parseFrameHeader, writeFrameHeader, buildFlags, EncodingTier, NcpError, DEFAULT_MAX_PAYLOAD, } from "../frame-header.js";
+import { encodeJson, decodeJson } from "./tier1-json-codec.js";
+import { encodeMsgPack, decodeMsgPack } from "./tier2-msgpack-codec.js";
+// ---------------------------------------------------------------------------
+// Decode
+// ---------------------------------------------------------------------------
+/**
+ * Decode a complete NCP frame from a buffer.
+ *
+ * @returns Decoded header + payload + bytes consumed.
+ * @throws {NcpError} NCP-ENCODING-UNSUPPORTED for reserved tiers.
+ * @throws {NcpError} NCP-FRAME-PAYLOAD-TOO-LARGE if payload exceeds max.
+ * @throws {NcpError} NCP-FRAME-INCOMPLETE if buffer doesn't have enough data.
+ */
+export function decodeFrame(buffer, options) {
+    const header = parseFrameHeader(buffer);
+    const maxPayload = options?.maxFramePayload ?? DEFAULT_MAX_PAYLOAD;
+    // NCP-F-09: Validate against negotiated max_frame_payload
+    if (header.payloadLength > maxPayload) {
+        throw new NcpError("NCP-FRAME-PAYLOAD-TOO-LARGE", `Payload ${header.payloadLength} exceeds max_frame_payload ${maxPayload}`);
+    }
+    const totalSize = header.headerSize + header.payloadLength;
+    // NCP-F-05: Buffer underrun — not enough data for payload
+    if (buffer.length < totalSize) {
+        throw new NcpError("NCP-FRAME-INCOMPLETE", `Buffer has ${buffer.length} bytes but frame needs ${totalSize}`);
+    }
+    // Extract payload bytes
+    const payloadBytes = buffer.subarray(header.headerSize, header.headerSize + header.payloadLength);
+    // Route to codec by tier
+    let payload;
+    switch (header.tier) {
+        case EncodingTier.Json:
+            payload = decodeJson(payloadBytes);
+            break;
+        case EncodingTier.MsgPack:
+            payload = decodeMsgPack(payloadBytes);
+            break;
+        default:
+            // NCP-E-05: Reserved tiers (0x02, 0x03)
+            throw new NcpError("NCP-ENCODING-UNSUPPORTED", `Unsupported encoding tier: 0x${header.tier.toString(16).padStart(2, "0")}`);
+    }
+    return { header, payload, bytesConsumed: totalSize };
+}
+// ---------------------------------------------------------------------------
+// Encode
+// ---------------------------------------------------------------------------
+/**
+ * Encode a payload into a complete NCP frame (header + payload bytes).
+ */
+export function encodeFrame(payload, options) {
+    const tier = options.tier ?? EncodingTier.Json;
+    // Encode payload
+    let payloadBytes;
+    switch (tier) {
+        case EncodingTier.Json:
+            payloadBytes = encodeJson(payload);
+            break;
+        case EncodingTier.MsgPack:
+            payloadBytes = encodeMsgPack(payload);
+            break;
+        default:
+            throw new NcpError("NCP-ENCODING-UNSUPPORTED", `Unsupported encoding tier for encode: ${tier}`);
+    }
+    // Determine if extended header is needed
+    const needsExtended = options.extended || payloadBytes.length > DEFAULT_MAX_PAYLOAD;
+    const flags = buildFlags({
+        tier,
+        final: options.final,
+        encrypted: options.encrypted,
+        extended: needsExtended,
+    });
+    const header = {
+        frameType: options.frameType,
+        flags,
+        payloadLength: payloadBytes.length,
+        tier,
+        isFinal: options.final ?? false,
+        isEncrypted: options.encrypted ?? false,
+        isExtended: needsExtended,
+        headerSize: needsExtended ? 8 : 4,
+    };
+    // Write frame
+    const frame = new Uint8Array(header.headerSize + payloadBytes.length);
+    writeFrameHeader(header, frame);
+    frame.set(payloadBytes, header.headerSize);
+    return frame;
+}
+//# sourceMappingURL=ncp-codec.js.map

package/dist/core/codecs/ncp-codec.js.map

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

package/dist/core/codecs/tier1-json-codec.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Encode a frame payload to Tier-1 JSON bytes.
+ */
+export declare function encodeJson(payload: unknown): Uint8Array;
+/**
+ * Decode Tier-1 JSON bytes to a parsed object.
+ * @throws {NcpError} NPS-CLIENT-BAD-FRAME on malformed JSON.
+ */
+export declare function decodeJson(bytes: Uint8Array): unknown;
+//# sourceMappingURL=tier1-json-codec.d.ts.map

package/dist/core/codecs/tier1-json-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier1-json-codec.d.ts","sourceRoot":"","sources":["../../../src/core/codecs/tier1-json-codec.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAEvD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAUrD"}

package/{src/core/codecs/tier1-json-codec.ts → dist/core/codecs/tier1-json-codec.js}

@@ -3,31 +3,26 @@
 //
 // Tier-1 JSON Codec — UTF-8 JSON encode/decode
 // NPS-1 §8
-
 import { NcpError } from "../frame-header.js";
-
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
-
 /**
  * Encode a frame payload to Tier-1 JSON bytes.
  */
-export function encodeJson(payload: unknown): Uint8Array {
-  return encoder.encode(JSON.stringify(payload));
+export function encodeJson(payload) {
+    return encoder.encode(JSON.stringify(payload));
 }
-
 /**
  * Decode Tier-1 JSON bytes to a parsed object.
  * @throws {NcpError} NPS-CLIENT-BAD-FRAME on malformed JSON.
  */
-export function decodeJson(bytes: Uint8Array): unknown {
-  const text = decoder.decode(bytes);
-  try {
-    return JSON.parse(text) as unknown;
-  } catch {
-    throw new NcpError(
-      "NPS-CLIENT-BAD-FRAME",
-      "Malformed JSON payload",
-    );
-  }
+export function decodeJson(bytes) {
+    const text = decoder.decode(bytes);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new NcpError("NPS-CLIENT-BAD-FRAME", "Malformed JSON payload");
+    }
 }
+//# sourceMappingURL=tier1-json-codec.js.map

package/dist/core/codecs/tier1-json-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier1-json-codec.js","sourceRoot":"","sources":["../../../src/core/codecs/tier1-json-codec.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,EAAE;AACF,+CAA+C;AAC/C,WAAW;AAEX,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAClC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAiB;IAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAChB,sBAAsB,EACtB,wBAAwB,CACzB,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/codecs/tier2-msgpack-codec.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Encode a frame payload to Tier-2 MsgPack bytes.
+ */
+export declare function encodeMsgPack(payload: unknown): Uint8Array;
+/**
+ * Decode Tier-2 MsgPack bytes to a parsed object.
+ * @throws {NcpError} NPS-CLIENT-BAD-FRAME on malformed MsgPack.
+ */
+export declare function decodeMsgPack(bytes: Uint8Array): unknown;
+//# sourceMappingURL=tier2-msgpack-codec.d.ts.map

package/dist/core/codecs/tier2-msgpack-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier2-msgpack-codec.d.ts","sourceRoot":"","sources":["../../../src/core/codecs/tier2-msgpack-codec.ts"],"names":[],"mappings":"AASA;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAE1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CASxD"}

package/{src/core/codecs/tier2-msgpack-codec.ts → dist/core/codecs/tier2-msgpack-codec.js}

@@ -3,28 +3,24 @@
 //
 // Tier-2 MsgPack Codec — Binary encode/decode
 // NPS-1 §8
-
 import { encode, decode } from "@msgpack/msgpack";
 import { NcpError } from "../frame-header.js";
-
 /**
  * Encode a frame payload to Tier-2 MsgPack bytes.
  */
-export function encodeMsgPack(payload: unknown): Uint8Array {
-  return encode(payload);
+export function encodeMsgPack(payload) {
+    return encode(payload);
 }
-
 /**
  * Decode Tier-2 MsgPack bytes to a parsed object.
  * @throws {NcpError} NPS-CLIENT-BAD-FRAME on malformed MsgPack.
  */
-export function decodeMsgPack(bytes: Uint8Array): unknown {
-  try {
-    return decode(bytes) as unknown;
-  } catch {
-    throw new NcpError(
-      "NPS-CLIENT-BAD-FRAME",
-      "Malformed MsgPack payload",
-    );
-  }
+export function decodeMsgPack(bytes) {
+    try {
+        return decode(bytes);
+    }
+    catch {
+        throw new NcpError("NPS-CLIENT-BAD-FRAME", "Malformed MsgPack payload");
+    }
 }
+//# sourceMappingURL=tier2-msgpack-codec.js.map

package/dist/core/codecs/tier2-msgpack-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier2-msgpack-codec.js","sourceRoot":"","sources":["../../../src/core/codecs/tier2-msgpack-codec.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,EAAE;AACF,8CAA8C;AAC9C,WAAW;AAEX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,KAAK,CAAY,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAChB,sBAAsB,EACtB,2BAA2B,CAC5B,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/crypto-provider.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Async crypto operations used across NPS protocols.
+ * All keys, IVs, and byte payloads are Uint8Array.
+ */
+export interface CryptoProvider {
+    /** Generate cryptographically secure random bytes. */
+    randomBytes(n: number): Uint8Array;
+    /** Generate an Ed25519 keypair. */
+    ed25519GenerateKeyPair(): Promise<{
+        publicKey: Uint8Array;
+        privateKey: Uint8Array;
+    }>;
+    /** Sign data with an Ed25519 private key. Returns 64-byte signature. */
+    ed25519Sign(privateKey: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+    /** Verify an Ed25519 signature. */
+    ed25519Verify(publicKey: Uint8Array, data: Uint8Array, sig: Uint8Array): Promise<boolean>;
+    /**
+     * AES-256-GCM encrypt.
+     * Returns ciphertext || 16-byte tag (single contiguous buffer, matching
+     * Web Crypto subtle.encrypt output and Python pycryptodome layout).
+     */
+    aesGcmEncrypt(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
+    /**
+     * AES-256-GCM decrypt.
+     * Input is ciphertext || 16-byte tag (same layout as aesGcmEncrypt output).
+     */
+    aesGcmDecrypt(key: Uint8Array, iv: Uint8Array, ciphertextAndTag: Uint8Array): Promise<Uint8Array>;
+    /** PBKDF2-SHA256 key derivation. */
+    pbkdf2Sha256(passphrase: Uint8Array, salt: Uint8Array, iterations: number, keyLen: number): Promise<Uint8Array>;
+}
+//# sourceMappingURL=crypto-provider.d.ts.map

package/dist/core/crypto-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-provider.d.ts","sourceRoot":"","sources":["../../src/core/crypto-provider.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAEnC,mCAAmC;IACnC,sBAAsB,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,UAAU,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;IAErF,wEAAwE;IACxE,WAAW,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAE3E,mCAAmC;IACnC,aAAa,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1F;;;;OAIG;IACH,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAE3F;;;OAGG;IACH,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAElG,oCAAoC;IACpC,YAAY,CACV,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,CAAC,CAAC;CACxB"}

package/dist/core/crypto-provider.js

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// CryptoProvider interface — async crypto abstraction for Node + browser.
+// NPS-3 §10 / Q10 resolution in nps-ts-sdk-step7-plan.
+//
+// Implementations (NodeCryptoProvider, WebCryptoProvider) land at P3
+// alongside NIP tests. This file is structural scaffold only.
+export {};
+//# sourceMappingURL=crypto-provider.js.map

package/dist/core/crypto-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-provider.js","sourceRoot":"","sources":["../../src/core/crypto-provider.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,EAAE;AACF,0EAA0E;AAC1E,uDAAuD;AACvD,EAAE;AACF,qEAAqE;AACrE,8DAA8D"}

package/dist/core/exceptions.d.ts

@@ -0,0 +1,27 @@
+/** Base class for all NPS SDK errors. */
+export declare class NpsError extends Error {
+    constructor(message: string);
+}
+/** Frame parse or structural error. */
+export declare class NpsFrameError extends NpsError {
+    constructor(message: string);
+}
+/** Encode or decode error. */
+export declare class NpsCodecError extends NpsError {
+    constructor(message: string);
+}
+/** Anchor cache miss — requested anchor ID not found. */
+export declare class NpsAnchorNotFoundError extends NpsError {
+    readonly anchorId: string;
+    constructor(anchorId: string, message?: string);
+}
+/** Anchor ID collision — same ID but different schema content. */
+export declare class NpsAnchorPoisonError extends NpsError {
+    readonly anchorId: string;
+    constructor(anchorId: string, message?: string);
+}
+/** Stream-level error (sequence gap, unknown stream ID, etc.). */
+export declare class NpsStreamError extends NpsError {
+    constructor(message: string);
+}
+//# sourceMappingURL=exceptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../../src/core/exceptions.ts"],"names":[],"mappings":"AAMA,yCAAyC;AACzC,qBAAa,QAAS,SAAQ,KAAK;gBACrB,OAAO,EAAE,MAAM;CAI5B;AAED,uCAAuC;AACvC,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,8BAA8B;AAC9B,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,yDAAyD;AACzD,qBAAa,sBAAuB,SAAQ,QAAQ;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBACd,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAK/C;AAED,kEAAkE;AAClE,qBAAa,oBAAqB,SAAQ,QAAQ;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBACd,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAK/C;AAED,kEAAkE;AAClE,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/core/exceptions.js

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NPS exception hierarchy — ported from nps_sdk/core/exceptions.py
+// NPS-1 §6
+/** Base class for all NPS SDK errors. */
+export class NpsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NpsError";
+    }
+}
+/** Frame parse or structural error. */
+export class NpsFrameError extends NpsError {
+    constructor(message) {
+        super(message);
+        this.name = "NpsFrameError";
+    }
+}
+/** Encode or decode error. */
+export class NpsCodecError extends NpsError {
+    constructor(message) {
+        super(message);
+        this.name = "NpsCodecError";
+    }
+}
+/** Anchor cache miss — requested anchor ID not found. */
+export class NpsAnchorNotFoundError extends NpsError {
+    anchorId;
+    constructor(anchorId, message) {
+        super(message ?? `Anchor not found: ${anchorId}`);
+        this.name = "NpsAnchorNotFoundError";
+        this.anchorId = anchorId;
+    }
+}
+/** Anchor ID collision — same ID but different schema content. */
+export class NpsAnchorPoisonError extends NpsError {
+    anchorId;
+    constructor(anchorId, message) {
+        super(message ?? `Anchor poison detected: ${anchorId}`);
+        this.name = "NpsAnchorPoisonError";
+        this.anchorId = anchorId;
+    }
+}
+/** Stream-level error (sequence gap, unknown stream ID, etc.). */
+export class NpsStreamError extends NpsError {
+    constructor(message) {
+        super(message);
+        this.name = "NpsStreamError";
+    }
+}
+//# sourceMappingURL=exceptions.js.map

package/dist/core/exceptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../../src/core/exceptions.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AACpD,EAAE;AACF,mEAAmE;AACnE,WAAW;AAEX,yCAAyC;AACzC,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED,uCAAuC;AACvC,MAAM,OAAO,aAAc,SAAQ,QAAQ;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,8BAA8B;AAC9B,MAAM,OAAO,aAAc,SAAQ,QAAQ;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,yDAAyD;AACzD,MAAM,OAAO,sBAAuB,SAAQ,QAAQ;IACzC,QAAQ,CAAS;IAC1B,YAAY,QAAgB,EAAE,OAAgB;QAC5C,KAAK,CAAC,OAAO,IAAI,qBAAqB,QAAQ,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,kEAAkE;AAClE,MAAM,OAAO,oBAAqB,SAAQ,QAAQ;IACvC,QAAQ,CAAS;IAC1B,YAAY,QAAgB,EAAE,OAAgB;QAC5C,KAAK,CAAC,OAAO,IAAI,2BAA2B,QAAQ,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,kEAAkE;AAClE,MAAM,OAAO,cAAe,SAAQ,QAAQ;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF"}