@totemsdk/edge-coap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Totem SDK Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @totemsdk/edge-coap
+
+Edge runtime adapter for CoAP — constrained devices, RFC 7252, UDP transport.
+
+## Install
+
+```bash
+npm install @totemsdk/edge-coap
+```
+
+## Design
+
+This package does **not** import `dgram`, `coap`, or any UDP library. All network behaviour is injected via `CoapTransportPort`. The package handles CoAP framing (CON/NON/ACK/RST, options, tokens) and request/response matching.
+
+## Quick start
+
+```ts
+import { createEdgeRuntime, createEdgeDevice, createCapabilitySet } from '@totemsdk/edge';
+import { createCoapGateway, createCoapSensorBridge } from '@totemsdk/edge-coap';
+import type { CoapTransportPort } from '@totemsdk/edge-coap';
+
+// 1. Implement CoapTransportPort
+const transport: CoapTransportPort = {
+  async bind(port) { /* bind UDP socket */ },
+  async close() { /* close socket */ },
+  async send(host, port, message) { /* send UDP datagram */ },
+  onMessage(handler) { /* register inbound handler */ return () => {}; },
+  onError(handler) { /* register error handler */ return () => {}; },
+};
+
+// 2. Wire into Edge runtime
+const runtime = createEdgeRuntime({
+  deviceId: 'coap-gateway-01',
+  capabilities: createCapabilitySet(['transport:coap', 'proof:create']),
+  ports: { /* proof port */ },
+});
+
+// 3. Create gateway
+const gateway = createCoapGateway({ runtime, transport, localPort: 5683 });
+await gateway.start();
+
+// 4. GET a resource
+const result = await gateway.get(['sensors', 'temperature'], '192.168.1.100', 5683);
+console.log(result.data?.payload);
+
+// 5. POST to a resource
+await gateway.post(['actuators', 'valve'], new TextEncoder().encode('open'), '192.168.1.101', 5683);
+
+// 6. Or use the sensor bridge for automated polling
+const bridge = createCoapSensorBridge({
+  runtime,
+  transport,
+  gateway,
+  bindings: [
+    { sensorId: 'temp-1', path: ['sensors', 'temperature'], host: '192.168.1.100', port: 5683, intervalMs: 5000 },
+  ],
+});
+await bridge.start();
+```
+
+## Transport port
+
+| Method | Description |
+|--------|-------------|
+| `bind(port)` | Bind UDP socket to local port |
+| `close()` | Close the socket |
+| `send(host, port, message)` | Send CoAP message bytes to remote endpoint |
+| `onMessage(handler)` | Register handler for inbound messages with remote address |
+| `onError(handler)` | Register handler for socket errors |
+
+## Supported methods
+
+| Method | Gateway method |
+|--------|---------------|
+| GET | `get(path, host, port)` |
+| POST | `post(path, payload, host, port)` |
+
+## Capabilities
+
+- `transport:coap` — required for CoAP transport
+
+## License
+
+MIT

package/dist/gateway.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CoAP Edge Gateway — wires a CoapTransportPort into an EdgeRuntime.
+ */
+import type { EdgeRuntime, EdgeOperationResult } from '@totemsdk/edge';
+import type { CoapTransportPort } from './transport.js';
+export interface CoapGatewayConfig {
+    runtime: EdgeRuntime;
+    transport: CoapTransportPort;
+    localPort: number;
+}
+export interface CoapGateway {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    readonly status: 'stopped' | 'running' | 'error';
+    get(path: string[], host: string, port: number): Promise<EdgeOperationResult<{
+        payload: Uint8Array;
+    }>>;
+    post(path: string[], payload: Uint8Array, host: string, port: number): Promise<EdgeOperationResult<{
+        payload: Uint8Array;
+    }>>;
+}
+export declare function createCoapGateway(config: CoapGatewayConfig): CoapGateway;

package/dist/gateway.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * CoAP Edge Gateway — wires a CoapTransportPort into an EdgeRuntime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCoapGateway = createCoapGateway;
+function createCoapGateway(config) {
+    let status = 'stopped';
+    let unsubMsg;
+    let unsubErr;
+    const pending = new Map();
+    let nextId = 0;
+    return {
+        get status() { return status; },
+        async start() {
+            if (status === 'running')
+                return;
+            await config.transport.bind(config.localPort);
+            unsubMsg = config.transport.onMessage((raw, remote) => {
+                try {
+                    const msg = decodeCoap(raw, remote);
+                    if (msg.type === 'ACK' && msg.token.length > 0) {
+                        const tokenId = new DataView(msg.token.buffer, msg.token.byteOffset, 4).getUint32(0, false);
+                        const p = pending.get(tokenId);
+                        if (p) {
+                            clearTimeout(p.timer);
+                            pending.delete(tokenId);
+                            p.resolve(msg.payload);
+                        }
+                    }
+                }
+                catch { /* drop */ }
+            });
+            unsubErr = config.transport.onError(() => { status = 'error'; });
+            status = 'running';
+        },
+        async stop() {
+            unsubMsg?.();
+            unsubErr?.();
+            for (const [, p] of pending) {
+                clearTimeout(p.timer);
+                p.reject(new Error('Gateway stopped'));
+            }
+            pending.clear();
+            await config.transport.close();
+            status = 'stopped';
+        },
+        async get(path, host, port) {
+            return coapRequest(config.transport, 'GET', path, new Uint8Array(0), host, port, pending, nextId++);
+        },
+        async post(path, payload, host, port) {
+            return coapRequest(config.transport, 'POST', path, payload, host, port, pending, nextId++);
+        },
+    };
+}
+async function coapRequest(transport, method, path, payload, host, port, pending, messageId, timeoutMs = 10000) {
+    const token = new Uint8Array(4);
+    new DataView(token.buffer).setUint32(0, messageId, false);
+    const frame = encodeCoap({ type: 'CON', method, messageId, token, path, payload, remote: { host, port }, receivedAt: Date.now() });
+    await transport.send(host, port, frame);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => { pending.delete(messageId); resolve({ ok: false, error: 'CoAP request timed out' }); }, timeoutMs);
+        pending.set(messageId, { resolve: (v) => resolve({ ok: true, data: { payload: v } }), reject: (e) => resolve({ ok: false, error: e.message }), timer });
+    });
+}
+function encodeCoap(msg) {
+    const pathBytes = msg.path.map(p => [11, ...new TextEncoder().encode(p)]).flat();
+    const tokenLen = Math.min(msg.token.length, 8);
+    const header = new Uint8Array(4 + tokenLen);
+    header[0] = 0x40 | (msg.type === 'CON' ? 0 : msg.type === 'NON' ? 0x10 : msg.type === 'ACK' ? 0x20 : 0x30);
+    header[0] |= tokenLen;
+    header[1] = msg.method === 'GET' ? 1 : msg.method === 'POST' ? 2 : msg.method === 'PUT' ? 3 : 4;
+    new DataView(header.buffer).setUint16(2, msg.messageId, false);
+    header.set(msg.token.slice(0, tokenLen), 4);
+    const options = new Uint8Array(pathBytes.length + 1);
+    options.set(new Uint8Array(pathBytes), 0);
+    options[pathBytes.length] = 0xFF;
+    const result = new Uint8Array(header.length + options.length + msg.payload.length);
+    result.set(header);
+    result.set(options, header.length);
+    result.set(msg.payload, header.length + options.length);
+    return result;
+}
+function decodeCoap(raw, remote) {
+    const tokenLen = raw[0] & 0x0F;
+    const typeCode = (raw[0] >> 4) & 0x03;
+    const type = typeCode === 0 ? 'CON' : typeCode === 1 ? 'NON' : typeCode === 2 ? 'ACK' : 'RST';
+    const code = raw[1];
+    const messageId = new DataView(raw.buffer, raw.byteOffset + 2, 2).getUint16(0, false);
+    const token = raw.slice(4, 4 + tokenLen);
+    let offset = 4 + tokenLen;
+    const path = [];
+    while (offset < raw.length && raw[offset] !== 0xFF) {
+        const delta = (raw[offset] >> 4) & 0x0F;
+        const len = raw[offset] & 0x0F;
+        offset++;
+        if (delta === 11)
+            path.push(new TextDecoder().decode(raw.slice(offset, offset + len)));
+        offset += len;
+    }
+    if (offset < raw.length && raw[offset] === 0xFF)
+        offset++;
+    const payload = raw.slice(offset);
+    return { type, messageId, token, path, payload, remote, receivedAt: Date.now() };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { CoapTransportPort, CoapMessage, CoapMessageType, CoapMethod } from './transport.js';
+export { createCoapGateway } from './gateway.js';
+export type { CoapGatewayConfig, CoapGateway } from './gateway.js';
+export { createCoapSensorBridge } from './sensor-bridge.js';
+export type { CoapSensorBinding, CoapSensorBridgeConfig, CoapSensorBridge } from './sensor-bridge.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCoapSensorBridge = exports.createCoapGateway = void 0;
+var gateway_js_1 = require("./gateway.js");
+Object.defineProperty(exports, "createCoapGateway", { enumerable: true, get: function () { return gateway_js_1.createCoapGateway; } });
+var sensor_bridge_js_1 = require("./sensor-bridge.js");
+Object.defineProperty(exports, "createCoapSensorBridge", { enumerable: true, get: function () { return sensor_bridge_js_1.createCoapSensorBridge; } });

package/dist/sensor-bridge.d.ts

@@ -0,0 +1,26 @@
+/**
+ * CoAP Sensor Bridge — maps CoAP resource observations to Edge proof inputs.
+ */
+import type { EdgeRuntime } from '@totemsdk/edge';
+import type { CoapTransportPort } from './transport.js';
+import type { CoapGateway } from './gateway.js';
+export interface CoapSensorBinding {
+    sensorId: string;
+    path: string[];
+    host: string;
+    port: number;
+    intervalMs: number;
+    dataType?: string;
+}
+export interface CoapSensorBridgeConfig {
+    runtime: EdgeRuntime;
+    transport: CoapTransportPort;
+    gateway?: CoapGateway;
+    bindings: CoapSensorBinding[];
+}
+export interface CoapSensorBridge {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    poll(): Promise<void>;
+}
+export declare function createCoapSensorBridge(config: CoapSensorBridgeConfig): CoapSensorBridge;

package/dist/sensor-bridge.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * CoAP Sensor Bridge — maps CoAP resource observations to Edge proof inputs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCoapSensorBridge = createCoapSensorBridge;
+function createCoapSensorBridge(config) {
+    const timers = [];
+    let running = false;
+    async function pollBinding(binding) {
+        try {
+            const gw = config.gateway;
+            if (!gw)
+                return;
+            const result = await gw.get(binding.path, binding.host, binding.port);
+            if (result.ok && config.runtime.ports.proof) {
+                await config.runtime.ports.proof.createProof({
+                    subject: `sensor:${binding.sensorId}`,
+                    claims: [{
+                            sensorId: binding.sensorId,
+                            path: binding.path.join('/'),
+                            dataType: binding.dataType ?? 'coap-observation',
+                            payload: result.data?.payload,
+                            timestamp: Date.now(),
+                        }],
+                });
+            }
+        }
+        catch { /* non-fatal */ }
+    }
+    return {
+        async start() {
+            if (running)
+                return;
+            for (const b of config.bindings) {
+                await pollBinding(b);
+                timers.push(setInterval(() => pollBinding(b), b.intervalMs));
+            }
+            running = true;
+        },
+        async stop() { for (const t of timers)
+            clearInterval(t); timers.length = 0; running = false; },
+        async poll() { for (const b of config.bindings)
+            await pollBinding(b); },
+    };
+}

package/dist/transport.d.ts

@@ -0,0 +1,47 @@
+/**
+ * CoAP transport port — injected by the caller.
+ *
+ * CoAP (RFC 7252) runs over UDP. The caller provides the socket.
+ * Messages are confirmable (CON), non-confirmable (NON),
+ * acknowledgement (ACK), or reset (RST).
+ */
+export interface CoapTransportPort {
+    /** Bind to a local port. */
+    bind(port: number): Promise<void>;
+    /** Close the socket. */
+    close(): Promise<void>;
+    /** Send a CoAP message to a remote endpoint. */
+    send(host: string, port: number, message: Uint8Array): Promise<void>;
+    /** Register a handler for inbound CoAP messages. */
+    onMessage(handler: (message: Uint8Array, remote: {
+        host: string;
+        port: number;
+    }) => void): () => void;
+    /** Register a handler for socket errors. */
+    onError(handler: (err: Error) => void): () => void;
+}
+export type CoapMessageType = 'CON' | 'NON' | 'ACK' | 'RST';
+export type CoapMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+export interface CoapMessage {
+    /** Message type. */
+    type: CoapMessageType;
+    /** Request method (only for CON/NON requests). */
+    method?: CoapMethod;
+    /** Response code (only for ACK responses). */
+    responseCode?: string;
+    /** Message ID for deduplication. */
+    messageId: number;
+    /** Token for request/response matching. */
+    token: Uint8Array;
+    /** URI path (e.g. ["sensors", "temperature"]). */
+    path: string[];
+    /** Payload bytes. */
+    payload: Uint8Array;
+    /** Remote endpoint. */
+    remote: {
+        host: string;
+        port: number;
+    };
+    /** Timestamp of receipt. */
+    receivedAt: number;
+}

package/dist/transport.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * CoAP transport port — injected by the caller.
+ *
+ * CoAP (RFC 7252) runs over UDP. The caller provides the socket.
+ * Messages are confirmable (CON), non-confirmable (NON),
+ * acknowledgement (ACK), or reset (RST).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@totemsdk/edge-coap",
+  "version": "0.1.0",
+  "description": "Edge runtime adapter for CoAP — constrained devices, RFC 7252, UDP transport",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest --passWithNoTests"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "dependencies": {
+    "@totemsdk/edge": "^0.1.3"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": { "node": ">=18.0.0" },
+  "publishConfig": { "access": "public" },
+  "license": "MIT",
+  "author": "Totem SDK",
+  "homepage": "https://totem.ing",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/totem-sdk/totem-sdk.git",
+    "directory": "packages/totem-sdk/packages/edge-coap"
+  },
+  "keywords": ["totem", "totemsdk", "minima", "blockchain", "edge", "coap", "transport"],
+  "bugs": { "url": "https://github.com/totem-sdk/totem-sdk/issues" }
+}