@meshcore-cz/meshpkt 0.1.0 → 0.1.2

package/README.md

@@ -1,25 +1,202 @@
 # @meshcore-cz/meshpkt
 
+[![npm](https://img.shields.io/npm/v/@meshcore-cz/meshpkt)](https://www.npmjs.com/package/@meshcore-cz/meshpkt)
+[![Go Reference](https://pkg.go.dev/badge/github.com/meshcore-cz/meshpkt.svg)](https://pkg.go.dev/github.com/meshcore-cz/meshpkt)
+
 MeshCore radio packet codec for JavaScript and TypeScript, powered by WebAssembly.
 
+> **Early development.** This package is a work in progress. APIs may change before v1.0 — pin to a specific version in production.
+
+- **npm:** [npmjs.com/package/@meshcore-cz/meshpkt](https://www.npmjs.com/package/@meshcore-cz/meshpkt)
+- **Go source & docs:** [pkg.go.dev/github.com/meshcore-cz/meshpkt](https://pkg.go.dev/github.com/meshcore-cz/meshpkt)
+
 ## Install
 
 ```sh
 npm install @meshcore-cz/meshpkt
-````
+```
 
-## Usage
+## Quick start
 
 ```ts
 import { load } from "@meshcore-cz/meshpkt";
 
 const meshpkt = await load();
+```
+
+`load()` fetches and initialises the bundled TinyGo WASM module. Call it once; subsequent calls return the same promise. All methods are synchronous after that.
+
+## Error handling
+
+Every method returns either the typed result or `{ error: string }`. The `"error"` key is the reliable way to distinguish them:
 
-const envelope = meshpkt.decodeEnvelope(
-  "your-hex-encoded-meshcore-packet"
+```ts
+const result = meshpkt.decodeEnvelope(hex);
+if ("error" in result) {
+  console.error("decode failed:", result.error);
+} else {
+  console.log(result.type, result.hopCount);
+}
+```
+
+---
+
+## Examples
+
+### Decode a packet from the air
+
+```ts
+const env = meshpkt.decodeEnvelope(
+  "15453287568f06bf2d5ad94765d9aaa4aef45a465a5a84142b5abb55eafe11980bc7b891"
 );
 
-console.log(envelope);
+if ("error" in env) throw new Error(env.error);
+
+console.log(env.route);       // "FLOOD"
+console.log(env.type);        // "ADVERT"
+console.log(env.hopCount);    // 5
+console.log(env.hops);        // ["3287", "568f", "06bf", "2d5a", "d947"]
+console.log(env.payloadHex);  // raw payload, pass to a decode* call below
+```
+
+---
+
+### Channel (GRP_TXT) messages
+
+```ts
+// Encode — by channel name
+const pkt = meshpkt.encodeGroupText("#general", "Alice", "Hello mesh!");
+if ("error" in pkt) throw new Error(pkt.error);
+console.log(pkt.hex); // ready to send over the radio link
+
+// Encode — by pre-shared secret (16 bytes hex)
+const secret = meshpkt.deriveChannelSecret("#general");
+if ("error" in secret) throw new Error(secret.error);
+const pkt2 = meshpkt.encodeGroupTextSecret(secret.hex, "Alice", "Hello mesh!");
+
+// Decode — extract payload first, then decrypt
+const env = meshpkt.decodeEnvelope(rawHex);
+if ("error" in env || env.type !== "GRP_TXT") return;
+
+const msg = meshpkt.decodeGroupText(env.payloadHex, "#general");
+if ("error" in msg) throw new Error(msg.error);
+
+console.log(msg.sender);    // "Alice"
+console.log(msg.text);      // "Hello mesh!"
+console.log(new Date(msg.timestamp * 1000));
+```
+
+---
+
+### Direct (TXT_MSG) messages
+
+```ts
+// Generate a keypair (or load an existing one)
+const kp = meshpkt.generateKeypair();
+if ("error" in kp) throw new Error(kp.error);
+// kp.privateKey / kp.publicKey — 64-char hex strings
+
+// Encode
+const pkt = meshpkt.encodeDirectText(myPrivKey, peerPubKey, "Hey, direct!");
+if ("error" in pkt) throw new Error(pkt.error);
+
+// Decode
+const env = meshpkt.decodeEnvelope(rawHex);
+if ("error" in env || env.type !== "TXT_MSG") return;
+
+const msg = meshpkt.decodeDirectText(env.payloadHex, myPrivKey, peerPubKey);
+if ("error" in msg) throw new Error(msg.error);
+
+console.log(msg.text);     // "Hey, direct!"
+console.log(msg.destHash); // first-byte hash of recipient's public key
+```
+
+---
+
+### Node advertisements (ADVERT)
+
+The signature is verified automatically. `decodeAdvert` returns `{ error }` if
+the packet carries a non-zero signature that does not verify — tampered data is
+rejected before you ever see the fields.
+
+```ts
+const env = meshpkt.decodeEnvelope(rawHex);
+if ("error" in env || env.type !== "ADVERT") return;
+
+const adv = meshpkt.decodeAdvert(env.payloadHex);
+if ("error" in adv) throw new Error(adv.error); // also catches bad signatures
+
+console.log(adv.name);        // "CZ.NIC Repeater"
+console.log(adv.publicKey);   // 64-char hex — treat this as the stable identity
+console.log(adv.nodeType);    // 2 = repeater
+console.log(adv.sigVerified); // true = Ed25519 signature verified
+                              // false = all-zero signature (unsigned packet)
+if (adv.hasGPS) {
+  console.log(adv.lat, adv.lon);
+}
+```
+
+> **Note:** `sigVerified: true` proves the holder of `publicKey` signed exactly
+> this name and these coordinates. It does not prove the name is unique — use
+> `publicKey` as the stable identity, and treat the name as a signed label.
+
+---
+
+### Key utilities
+
+```ts
+// Generate a fresh X25519 keypair
+const kp = meshpkt.generateKeypair();
+if ("error" in kp) throw new Error(kp.error);
+console.log(kp.publicKey);  // 64-char hex
+console.log(kp.privateKey); // 64-char hex
+
+// Derive a channel PSK from its name
+const secret = meshpkt.deriveChannelSecret("#ops");
+if ("error" in secret) throw new Error(secret.error);
+console.log(secret.hex);    // 32-char hex (16 bytes)
+
+// Compute X25519 shared secret for direct-message crypto
+const shared = meshpkt.sharedSecret(myPrivKey, peerPubKey);
+if ("error" in shared) throw new Error(shared.error);
+console.log(shared.hex);    // 64-char hex (32 bytes; use first 16 as AES key)
+```
+
+---
+
+### Loader options
+
+By default `load()` resolves the `.wasm` and `wasm_exec.js` files relative to the package using `import.meta.url`. Override either URL when your bundler places assets elsewhere:
+
+```ts
+const meshpkt = await load({
+  wasmURL:     new URL("/assets/meshpkt.wasm",    import.meta.url),
+  wasmExecURL: new URL("/assets/wasm_exec.js",    import.meta.url),
+});
+```
+
+---
+
+## TypeScript types
+
+All result interfaces are re-exported from the package root:
+
+```ts
+import type {
+  Envelope,
+  GroupTextPayload,
+  DirectTextPayload,
+  AdvertPayload,
+  GrpDataPayload,
+  AckPayload,
+  ReqPayload,
+  ResponsePayload,
+  PathPayload,
+  AnonReqPayload,
+  ControlPayload,
+  KeypairResult,
+  ErrResult,
+} from "@meshcore-cz/meshpkt";
 ```
 
-The package includes the TinyGo WebAssembly module and generated TypeScript types.
+The `RouteTypes` and `PayloadTypes` constant arrays (code + label) are also exported for building UI dropdowns or switch statements.

package/dist/wasm.gen.d.ts

@@ -41,6 +41,7 @@ export interface AdvertPayload {
     hasGPS: boolean;
     lat?: number;
     lon?: number;
+    sigVerified: boolean;
 }
 export interface AckPayload {
     crc: number;
@@ -87,6 +88,23 @@ export interface ControlPayload {
     discoverSNR?: number;
     discoverPubKey?: string;
 }
+export interface TracePayload {
+    tag: number;
+    authCode: number;
+    flags: number;
+    hashWidth: number;
+    routeHashes: string[];
+    snrs: string[];
+    hopCount: number;
+}
+export interface MultipartPayload {
+    remaining: number;
+    innerType: string;
+    innerTypeCode: number;
+    innerPayloadHex: string;
+    ackCrc?: number;
+    ackCrcHex?: string;
+}
 export interface KeypairResult {
     publicKey: string;
     privateKey: string;
@@ -97,11 +115,13 @@ export interface MeshcoreWasm {
     encodeGrpData(channelName: string, dataType: number, data: string): HexResult | ErrResult;
     encodeGrpDataSecret(secret: string, dataType: number, data: string): HexResult | ErrResult;
     encodeDirectText(privKey: string, peerPubKey: string, text: string): HexResult | ErrResult;
-    encodeAdvert(pubKey: string, signature: string, name: string, hasGPS: number, lat: unknown, lon: unknown): HexResult | ErrResult;
+    encodeAdvert(pubKey: string, signature: string, name: string, hasGPS: number, lat: number, lon: number): HexResult | ErrResult;
     encodeAck(crc: number): HexResult | ErrResult;
     encodeReq(privKey: string, peerPubKey: string, reqType: number, data: string): HexResult | ErrResult;
     encodeAnonReq(destPubKey: string, myPrivKey: string, data: string): HexResult | ErrResult;
     encodeDiscoverReq(typeFilter: number, tag: number, since: number, prefixOnly: number): HexResult | ErrResult;
+    encodeTrace(tag: number, authCode: number, flags: number, routeHashes: string): HexResult | ErrResult;
+    encodeMultipartAck(remaining: number, crc: number): HexResult | ErrResult;
     encodeRaw(route: number, payloadType: number, version: number, pathHashSize: number, payload: string): HexResult | ErrResult;
     decodeEnvelope(packet: string): Envelope | ErrResult;
     decodeGroupText(payload: string, channelName: string): GroupTextPayload | ErrResult;
@@ -116,11 +136,13 @@ export interface MeshcoreWasm {
     decodePath(payload: string, privKey: string, peerPubKey: string): PathPayload | ErrResult;
     decodeAnonReq(payload: string, myPrivKey: string): AnonReqPayload | ErrResult;
     decodeControl(payload: string): ControlPayload | ErrResult;
+    decodeTrace(packet: string): TracePayload | ErrResult;
+    decodeMultipart(payload: string): MultipartPayload | ErrResult;
     generateKeypair(): KeypairResult | ErrResult;
     deriveChannelSecret(channelName: string): HexResult | ErrResult;
     sharedSecret(privKey: string, peerPubKey: string): HexResult | ErrResult;
 }
-export declare const meshcoreOpNames: readonly ["encodeGroupText", "encodeGroupTextSecret", "encodeGrpData", "encodeGrpDataSecret", "encodeDirectText", "encodeAdvert", "encodeAck", "encodeReq", "encodeAnonReq", "encodeDiscoverReq", "encodeRaw", "decodeEnvelope", "decodeGroupText", "decodeGroupTextSecret", "decodeDirectText", "decodeAdvert", "decodeAck", "decodeGrpData", "decodeGrpDataSecret", "decodeReq", "decodeResponse", "decodePath", "decodeAnonReq", "decodeControl", "generateKeypair", "deriveChannelSecret", "sharedSecret"];
+export declare const meshcoreOpNames: readonly ["encodeGroupText", "encodeGroupTextSecret", "encodeGrpData", "encodeGrpDataSecret", "encodeDirectText", "encodeAdvert", "encodeAck", "encodeReq", "encodeAnonReq", "encodeDiscoverReq", "encodeTrace", "encodeMultipartAck", "encodeRaw", "decodeEnvelope", "decodeGroupText", "decodeGroupTextSecret", "decodeDirectText", "decodeAdvert", "decodeAck", "decodeGrpData", "decodeGrpDataSecret", "decodeReq", "decodeResponse", "decodePath", "decodeAnonReq", "decodeControl", "decodeTrace", "decodeMultipart", "generateKeypair", "deriveChannelSecret", "sharedSecret"];
 export declare const RouteTypes: readonly [{
     readonly code: 0;
     readonly label: "TRANSPORT_FLOOD";
@@ -174,3 +196,42 @@ export declare const PayloadTypes: readonly [{
     readonly code: 15;
     readonly label: "RAW_CUSTOM";
 }];
+export interface ParamMeta {
+    name: string;
+    kind: string;
+    label: string;
+    placeholder: string;
+    optional: boolean;
+    choices: {
+        value: number;
+        label: string;
+    }[];
+    showWhen: string;
+    showValue: number;
+    group: string;
+    action: string;
+    widget: string;
+    autoFill: string;
+    secret: boolean;
+}
+export interface ResultMeta {
+    name: string;
+    kind: string;
+    optional: boolean;
+    label: string;
+}
+export interface OpMeta {
+    name: string;
+    category: string;
+    label: string;
+    tabGroup: string;
+    tabGroupLabel: string;
+    tabGroupSub: string;
+    tabGroupDoc: string;
+    tabLabel: string;
+    packetType: string;
+    params: ParamMeta[];
+    result: ResultMeta[];
+    resultTypeName: string;
+}
+export declare const OpMetas: OpMeta[];