@veilux/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -10,4 +10,5 @@ export * from "./encoding.js";
 export * from "./identity.js";
 export * from "./client.js";
 export * from "./ids.js";
+export * from "./subscription.js";
 export * as builders from "./builders.js";

package/dist/index.js

@@ -10,4 +10,5 @@ export * from "./encoding.js";
 export * from "./identity.js";
 export * from "./client.js";
 export * from "./ids.js";
+export * from "./subscription.js";
 export * as builders from "./builders.js";

package/dist/subscription.d.ts

@@ -0,0 +1,28 @@
+import type { BlockNotification } from "./types.js";
+export interface Subscription {
+    /** Close the underlying WebSocket and stop receiving notifications. */
+    close(): void;
+}
+export interface SubscribeHandlers {
+    /** Called for every committed block. */
+    onBlock?: (block: BlockNotification) => void;
+    /** Called once the subscription is established. */
+    onOpen?: () => void;
+    /** Called on socket error. */
+    onError?: (err: unknown) => void;
+    /** Called when the socket closes. */
+    onClose?: () => void;
+}
+/**
+ * Subscribe to real-time block notifications over WebSocket.
+ *
+ * Works in the browser and in Node.js 20+ (both expose a global `WebSocket`).
+ *
+ * ```ts
+ * const sub = subscribeBlocks("ws://127.0.0.1:8646", {
+ *   onBlock: (b) => console.log("new block", b.height, b.hash),
+ * });
+ * // later: sub.close();
+ * ```
+ */
+export declare function subscribeBlocks(wsUrl: string, handlers: SubscribeHandlers): Subscription;

package/dist/subscription.js

@@ -0,0 +1,40 @@
+/**
+ * Subscribe to real-time block notifications over WebSocket.
+ *
+ * Works in the browser and in Node.js 20+ (both expose a global `WebSocket`).
+ *
+ * ```ts
+ * const sub = subscribeBlocks("ws://127.0.0.1:8646", {
+ *   onBlock: (b) => console.log("new block", b.height, b.hash),
+ * });
+ * // later: sub.close();
+ * ```
+ */
+export function subscribeBlocks(wsUrl, handlers) {
+    const WS = typeof WebSocket !== "undefined" ? WebSocket : globalThis.WebSocket;
+    if (!WS) {
+        throw new Error("No global WebSocket available. On older Node, pass a polyfill via globalThis.WebSocket.");
+    }
+    const ws = new WS(wsUrl);
+    ws.onopen = () => handlers.onOpen?.();
+    ws.onerror = (e) => handlers.onError?.(e);
+    ws.onclose = () => handlers.onClose?.();
+    ws.onmessage = (ev) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data));
+        }
+        catch {
+            return;
+        }
+        const msg = parsed;
+        if (msg.type === "block" && handlers.onBlock) {
+            handlers.onBlock(msg);
+        }
+    };
+    return {
+        close() {
+            ws.close();
+        },
+    };
+}

package/dist/types.d.ts

@@ -56,6 +56,16 @@ export interface StateResult {
 export interface EstimateResult {
     cost: number;
 }
+/** Real-time notification pushed over WebSocket when a block is committed. */
+export interface BlockNotification {
+    type: "block";
+    height: number;
+    hash: string;
+    state_root: string;
+    command_count: number;
+    event_count: number;
+    timestamp: number;
+}
 export declare const RPC_METHODS: {
     readonly nodeInfo: "veilux_nodeInfo";
     readonly submit: "veilux_submit";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veilux/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "VEILUX TypeScript SDK — build, sign, and submit commands to a VEILUX node",
   "license": "MIT",
   "author": "nathan <nathan@winnode.xyz>",