@totemsdk/edge-coap 0.1.0 → 0.3.0

package/dist/cjs/sensor-bridge.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * CoAP Sensor Bridge — maps CoAP resources and RFC 7641 observations to Edge
+ * proof inputs. CBOR payloads (content-format 60) are decoded into structured
+ * claims; malformed CBOR is not signed as sensor data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPLICATION_CBOR = void 0;
+exports.createCoapSensorBridge = createCoapSensorBridge;
+const cbor_js_1 = require("./cbor.js");
+exports.APPLICATION_CBOR = 60;
+function createCoapSensorBridge(config) {
+    const timers = [];
+    const observations = [];
+    let running = false;
+    function claimsFor(binding, data, receivedAt = Date.now()) {
+        const claim = {
+            sensorId: binding.sensorId,
+            path: binding.path.join('/'),
+            dataType: binding.dataType ?? 'coap-observation',
+            payload: data.payload,
+            timestamp: receivedAt,
+        };
+        if (data.contentFormat !== undefined)
+            claim.contentFormat = data.contentFormat;
+        if (data.observe !== undefined)
+            claim.observe = data.observe;
+        if (data.contentFormat === exports.APPLICATION_CBOR) {
+            try {
+                claim.cbor = (0, cbor_js_1.decodeCbor)(data.payload);
+            }
+            catch {
+                // Do not sign a payload that claims to be CBOR but does not decode.
+                return undefined;
+            }
+        }
+        return claim;
+    }
+    async function emitProof(binding, data, receivedAt) {
+        const proof = config.runtime.ports.proof;
+        if (!proof)
+            return;
+        const claim = claimsFor(binding, data, receivedAt);
+        if (!claim)
+            return;
+        await proof.createProof({ subject: `sensor:${binding.sensorId}`, claims: [claim] });
+    }
+    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 && result.data)
+                await emitProof(binding, result.data);
+        }
+        catch { /* non-fatal */ }
+    }
+    async function observeBinding(binding) {
+        const gw = config.gateway;
+        if (!gw)
+            return false;
+        const result = await gw.observe(binding.path, binding.host, binding.port, (notification) => {
+            void emitProof(binding, notification, notification.receivedAt).catch(() => { });
+        });
+        if (!result.ok || !result.data)
+            return false;
+        observations.push(result.data);
+        return true;
+    }
+    return {
+        async start() {
+            if (running)
+                return;
+            for (const binding of config.bindings) {
+                if (binding.observe) {
+                    const registered = await observeBinding(binding).catch(() => false);
+                    if (registered)
+                        continue;
+                }
+                await pollBinding(binding);
+                timers.push(setInterval(() => pollBinding(binding), binding.intervalMs));
+            }
+            running = true;
+        },
+        async stop() {
+            for (const timer of timers)
+                clearInterval(timer);
+            timers.length = 0;
+            const active = observations.splice(0);
+            await Promise.all(active.map((observation) => observation.cancel().catch(() => { })));
+            running = false;
+        },
+        async poll() {
+            for (const binding of config.bindings)
+                await pollBinding(binding);
+        },
+    };
+}

package/dist/cjs/transport.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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' | 'FETCH';
+export interface CoapBlockOption {
+    /** Block number. */
+    num: number;
+    /** More blocks follow. */
+    more: boolean;
+    /** Size exponent: block size is 2^(sizeExponent + 4), 16..1024 bytes. */
+    sizeExponent: number;
+}
+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[];
+    /** Uri-Host option (3). Defaults to the destination address when absent. */
+    uriHost?: string;
+    /** Uri-Port option (7). Defaults to the destination port when absent. */
+    uriPort?: number;
+    /** Uri-Query options (15), in order. */
+    uriQuery?: string[];
+    /** Payload bytes. */
+    payload: Uint8Array;
+    /** Content-Format option (12), e.g. 0 text/plain, 60 application/cbor. */
+    contentFormat?: number;
+    /** Accept option (17). */
+    accept?: number;
+    /** Observe option (6): 0 register, 1 deregister, otherwise notification sequence. */
+    observe?: number;
+    /** OSCORE option (9) bytes, passed through without interpretation. */
+    oscore?: Uint8Array;
+    /** Block1 option (27) for blockwise requests. */
+    block1?: CoapBlockOption;
+    /** Block2 option (23) for blockwise responses. */
+    block2?: CoapBlockOption;
+    /** Size2 option (28): total response body size hint. */
+    size2?: number;
+    /** Size1 option (60): total request body size hint. */
+    size1?: number;
+    /** Remote endpoint. */
+    remote: {
+        host: string;
+        port: number;
+    };
+    /** Timestamp of receipt. */
+    receivedAt: number;
+}

package/dist/cjs/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/dist/codec.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CoAP wire codec (RFC 7252 §3).
+ *
+ * Kept independent of the transport so the encoding can be exercised against
+ * RFC vectors without a socket. Only Uri-Path (option 11) is emitted; Uri-Host
+ * and Uri-Port default to the destination address, so they are not sent.
+ */
+import type { CoapMessage } from './transport.js';
+export declare const URI_HOST_OPTION = 3;
+export declare const OBSERVE_OPTION = 6;
+export declare const URI_PORT_OPTION = 7;
+export declare const OSCORE_OPTION = 9;
+export declare const BLOCK2_OPTION = 23;
+export declare const BLOCK1_OPTION = 27;
+export declare const SIZE2_OPTION = 28;
+export declare const SIZE1_OPTION = 60;
+export declare const URI_PATH_OPTION = 11;
+export declare const CONTENT_FORMAT_OPTION = 12;
+export declare const ACCEPT_OPTION = 17;
+export declare const URI_QUERY_OPTION = 15;
+export declare function tokenToKey(token: Uint8Array): string;
+export declare function encodeCoap(msg: CoapMessage): Uint8Array;
+export declare function decodeCoap(raw: Uint8Array, remote: {
+    host: string;
+    port: number;
+}): CoapMessage;
+export declare function encodeBlock(block: import('./transport.js').CoapBlockOption): number;
+export declare function decodeBlock(value: Uint8Array): import('./transport.js').CoapBlockOption;
+export declare function formatResponseCode(code: number): string;
+export declare function parseResponseCode(code: string): number;

package/dist/codec.js

@@ -0,0 +1,339 @@
+/**
+ * CoAP wire codec (RFC 7252 §3).
+ *
+ * Kept independent of the transport so the encoding can be exercised against
+ * RFC vectors without a socket. Only Uri-Path (option 11) is emitted; Uri-Host
+ * and Uri-Port default to the destination address, so they are not sent.
+ */
+export const URI_HOST_OPTION = 3;
+export const OBSERVE_OPTION = 6;
+export const URI_PORT_OPTION = 7;
+export const OSCORE_OPTION = 9;
+export const BLOCK2_OPTION = 23;
+export const BLOCK1_OPTION = 27;
+export const SIZE2_OPTION = 28;
+export const SIZE1_OPTION = 60;
+export const URI_PATH_OPTION = 11;
+export const CONTENT_FORMAT_OPTION = 12;
+export const ACCEPT_OPTION = 17;
+export const URI_QUERY_OPTION = 15;
+const PAYLOAD_MARKER = 0xff;
+const MAX_TOKEN_LENGTH = 8;
+const MAX_OPTION_VALUE = 65804; // 269 + 0xffff
+const METHOD_CODES = { GET: 1, POST: 2, PUT: 3, DELETE: 4, FETCH: 5 };
+const CODE_METHODS = { 1: 'GET', 2: 'POST', 3: 'PUT', 4: 'DELETE', 5: 'FETCH' };
+export function tokenToKey(token) {
+    return Array.from(token).map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+export function encodeCoap(msg) {
+    const tokenLen = msg.token.length;
+    if (tokenLen > MAX_TOKEN_LENGTH)
+        throw new Error('CoAP token exceeds 8 bytes');
+    if (msg.messageId < 0 || msg.messageId > 0xffff)
+        throw new Error('CoAP message id out of range');
+    const entries = [];
+    if (msg.uriHost !== undefined)
+        entries.push({ number: URI_HOST_OPTION, value: new TextEncoder().encode(msg.uriHost) });
+    if (msg.observe !== undefined)
+        entries.push({ number: OBSERVE_OPTION, value: uintToBytes(msg.observe) });
+    if (msg.uriPort !== undefined)
+        entries.push({ number: URI_PORT_OPTION, value: uintToBytes(msg.uriPort) });
+    if (msg.oscore)
+        entries.push({ number: OSCORE_OPTION, value: msg.oscore });
+    for (const segment of msg.path) {
+        if (segment.length === 0)
+            throw new Error('CoAP Uri-Path segment cannot be empty');
+        entries.push({ number: URI_PATH_OPTION, value: new TextEncoder().encode(segment) });
+    }
+    for (const query of msg.uriQuery ?? []) {
+        entries.push({ number: URI_QUERY_OPTION, value: new TextEncoder().encode(query) });
+    }
+    if (msg.contentFormat !== undefined)
+        entries.push({ number: CONTENT_FORMAT_OPTION, value: uintToBytes(msg.contentFormat) });
+    if (msg.accept !== undefined)
+        entries.push({ number: ACCEPT_OPTION, value: uintToBytes(msg.accept) });
+    if (msg.block2)
+        entries.push({ number: BLOCK2_OPTION, value: uintToBytes(encodeBlock(msg.block2)) });
+    if (msg.block1)
+        entries.push({ number: BLOCK1_OPTION, value: uintToBytes(encodeBlock(msg.block1)) });
+    if (msg.size2 !== undefined)
+        entries.push({ number: SIZE2_OPTION, value: uintToBytes(msg.size2) });
+    if (msg.size1 !== undefined)
+        entries.push({ number: SIZE1_OPTION, value: uintToBytes(msg.size1) });
+    // Stable sort keeps repeated Uri-Path segments in path order.
+    entries.sort((a, b) => a.number - b.number);
+    const options = [];
+    let previousOption = 0;
+    for (const entry of entries) {
+        const delta = optionDeltaNibble(entry.number - previousOption);
+        const length = optionLengthNibble(entry.value.length);
+        options.push((delta.nibble << 4) | length.nibble, ...delta.extended, ...length.extended, ...entry.value);
+        previousOption = entry.number;
+    }
+    let code = 0;
+    if (msg.type === 'CON' || msg.type === 'NON') {
+        if (msg.method) {
+            if (METHOD_CODES[msg.method] === undefined)
+                throw new Error('CoAP request requires a method');
+            code = METHOD_CODES[msg.method];
+        }
+        else if (msg.responseCode !== undefined) {
+            code = parseResponseCode(msg.responseCode);
+        }
+        else {
+            throw new Error('CoAP CON/NON message requires a method or response code');
+        }
+    }
+    else if (msg.responseCode !== undefined) {
+        code = parseResponseCode(msg.responseCode);
+    }
+    const marker = msg.payload.length > 0 ? [PAYLOAD_MARKER] : [];
+    const out = new Uint8Array(4 + tokenLen + options.length + marker.length + msg.payload.length);
+    out[0] = 0x40 | ((msgTypeCode(msg.type) & 0x03) << 4) | tokenLen;
+    out[1] = code;
+    out[2] = (msg.messageId >> 8) & 0xff;
+    out[3] = msg.messageId & 0xff;
+    out.set(msg.token, 4);
+    out.set(options, 4 + tokenLen);
+    const payloadOffset = 4 + tokenLen + options.length;
+    if (marker.length)
+        out[payloadOffset] = PAYLOAD_MARKER;
+    out.set(msg.payload, payloadOffset + marker.length);
+    return out;
+}
+export function decodeCoap(raw, remote) {
+    if (raw.length < 4)
+        throw new Error('Truncated CoAP header');
+    const version = (raw[0] >> 6) & 0x03;
+    if (version !== 1)
+        throw new Error(`Unsupported CoAP version ${version}`);
+    const tokenLen = raw[0] & 0x0f;
+    if (tokenLen > MAX_TOKEN_LENGTH)
+        throw new Error('Invalid CoAP token length');
+    if (raw.length < 4 + tokenLen)
+        throw new Error('Truncated CoAP token');
+    const type = typeFromCode((raw[0] >> 4) & 0x03);
+    const code = raw[1];
+    const messageId = ((raw[2] << 8) | raw[3]) & 0xffff;
+    const token = raw.slice(4, 4 + tokenLen);
+    const path = [];
+    const uriQuery = [];
+    let uriHost;
+    let uriPort;
+    let optionNumber = 0;
+    let offset = 4 + tokenLen;
+    let payload = new Uint8Array(0);
+    let contentFormat;
+    let accept;
+    let observe;
+    let oscore;
+    let block1;
+    let block2;
+    let size1;
+    let size2;
+    const seen = new Set();
+    while (offset < raw.length) {
+        if (raw[offset] === PAYLOAD_MARKER) {
+            offset++;
+            if (offset === raw.length)
+                throw new Error('CoAP payload marker without payload');
+            payload = raw.slice(offset);
+            offset = raw.length;
+            break;
+        }
+        const delta = (raw[offset] >> 4) & 0x0f;
+        const length = raw[offset] & 0x0f;
+        offset++;
+        const deltaValue = readExtendedOptionValue(delta, raw, offset);
+        offset = deltaValue.offset;
+        const lengthValue = readExtendedOptionValue(length, raw, offset);
+        offset = lengthValue.offset;
+        optionNumber += deltaValue.value;
+        if (optionNumber > 0xffff)
+            throw new Error('CoAP option number out of range');
+        if (offset + lengthValue.value > raw.length)
+            throw new Error('Truncated CoAP option value');
+        const value = raw.slice(offset, offset + lengthValue.value);
+        if (optionNumber !== URI_PATH_OPTION && optionNumber !== URI_QUERY_OPTION && seen.has(optionNumber)) {
+            throw new Error(`Duplicate CoAP option ${optionNumber}`);
+        }
+        if (optionNumber === URI_HOST_OPTION) {
+            uriHost = new TextDecoder().decode(value);
+        }
+        else if (optionNumber === URI_PORT_OPTION) {
+            uriPort = uintFromBytes(value);
+        }
+        else if (optionNumber === URI_PATH_OPTION) {
+            const segment = new TextDecoder().decode(value);
+            if (segment.length === 0)
+                throw new Error('Empty CoAP Uri-Path segment');
+            path.push(segment);
+        }
+        else if (optionNumber === URI_QUERY_OPTION) {
+            uriQuery.push(new TextDecoder().decode(value));
+        }
+        else if (optionNumber === CONTENT_FORMAT_OPTION) {
+            contentFormat = uintFromBytes(value);
+        }
+        else if (optionNumber === ACCEPT_OPTION) {
+            accept = uintFromBytes(value);
+        }
+        else if (optionNumber === OBSERVE_OPTION) {
+            observe = uintFromBytes(value);
+        }
+        else if (optionNumber === OSCORE_OPTION) {
+            oscore = value.slice();
+        }
+        else if (optionNumber === BLOCK1_OPTION) {
+            block1 = decodeBlock(value);
+        }
+        else if (optionNumber === BLOCK2_OPTION) {
+            block2 = decodeBlock(value);
+        }
+        else if (optionNumber === SIZE1_OPTION) {
+            size1 = uintFromBytes(value);
+        }
+        else if (optionNumber === SIZE2_OPTION) {
+            size2 = uintFromBytes(value);
+        }
+        seen.add(optionNumber);
+        offset += lengthValue.value;
+    }
+    const message = {
+        type,
+        messageId,
+        token,
+        path,
+        payload,
+        remote,
+        receivedAt: Date.now(),
+    };
+    if (uriHost !== undefined)
+        message.uriHost = uriHost;
+    if (uriPort !== undefined)
+        message.uriPort = uriPort;
+    if (uriQuery.length > 0)
+        message.uriQuery = uriQuery;
+    if (contentFormat !== undefined)
+        message.contentFormat = contentFormat;
+    if (accept !== undefined)
+        message.accept = accept;
+    if (observe !== undefined)
+        message.observe = observe;
+    if (oscore !== undefined)
+        message.oscore = oscore;
+    if (block1 !== undefined)
+        message.block1 = block1;
+    if (block2 !== undefined)
+        message.block2 = block2;
+    if (size1 !== undefined)
+        message.size1 = size1;
+    if (size2 !== undefined)
+        message.size2 = size2;
+    const codeClass = code >> 5;
+    if (codeClass === 0) {
+        const method = CODE_METHODS[code];
+        if (method)
+            message.method = method;
+    }
+    else {
+        message.responseCode = formatResponseCode(code);
+    }
+    return message;
+}
+function msgTypeCode(type) {
+    switch (type) {
+        case 'CON': return 0;
+        case 'NON': return 1;
+        case 'ACK': return 2;
+        case 'RST': return 3;
+    }
+}
+function typeFromCode(code) {
+    switch (code & 0x03) {
+        case 0: return 'CON';
+        case 1: return 'NON';
+        case 2: return 'ACK';
+        default: return 'RST';
+    }
+}
+function optionDeltaNibble(value) {
+    if (value <= 12)
+        return { nibble: value, extended: [] };
+    if (value <= 268)
+        return { nibble: 13, extended: [value - 13] };
+    return { nibble: 14, extended: [(value - 269) >> 8, (value - 269) & 0xff] };
+}
+function optionLengthNibble(value) {
+    if (value > MAX_OPTION_VALUE)
+        throw new Error('CoAP option value exceeds 65804 bytes');
+    if (value <= 12)
+        return { nibble: value, extended: [] };
+    if (value <= 268)
+        return { nibble: 13, extended: [value - 13] };
+    return { nibble: 14, extended: [(value - 269) >> 8, (value - 269) & 0xff] };
+}
+function readExtendedOptionValue(nibble, raw, offset) {
+    if (nibble <= 12)
+        return { value: nibble, offset };
+    if (nibble === 13) {
+        if (offset >= raw.length)
+            throw new Error('Truncated CoAP option delta/length');
+        return { value: raw[offset] + 13, offset: offset + 1 };
+    }
+    if (nibble === 14) {
+        if (offset + 1 >= raw.length)
+            throw new Error('Truncated CoAP option delta/length');
+        return { value: ((raw[offset] << 8) | raw[offset + 1]) + 269, offset: offset + 2 };
+    }
+    throw new Error('Invalid CoAP option delta/length nibble');
+}
+export function encodeBlock(block) {
+    if (!Number.isInteger(block.num) || block.num < 0 || block.num > 0xfffff)
+        throw new Error(`Invalid CoAP block number ${block.num}`);
+    if (!Number.isInteger(block.sizeExponent) || block.sizeExponent < 0 || block.sizeExponent > 6) {
+        throw new Error(`Invalid CoAP block size exponent ${block.sizeExponent}`);
+    }
+    return ((block.num & 0xfffff) << 4) | (block.more ? 0x08 : 0) | block.sizeExponent;
+}
+export function decodeBlock(value) {
+    const encoded = uintFromBytes(value);
+    const sizeExponent = encoded & 0x07;
+    if (sizeExponent === 7)
+        throw new Error('Reserved CoAP block size exponent');
+    return { num: encoded >>> 4, more: (encoded & 0x08) !== 0, sizeExponent };
+}
+function uintToBytes(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) {
+        throw new Error(`Invalid CoAP uint option value ${value}`);
+    }
+    if (value === 0)
+        return new Uint8Array(0);
+    const bytes = [];
+    let remaining = value;
+    while (remaining > 0) {
+        bytes.unshift(remaining & 0xff);
+        remaining = Math.floor(remaining / 256);
+    }
+    return Uint8Array.from(bytes);
+}
+function uintFromBytes(value) {
+    if (value.length > 4)
+        throw new Error('CoAP uint option exceeds 4 bytes');
+    let result = 0;
+    for (const byte of value)
+        result = result * 256 + byte;
+    return result;
+}
+export function formatResponseCode(code) {
+    return `${(code >> 5) & 0x07}.${String(code & 0x1f).padStart(2, '0')}`;
+}
+export function parseResponseCode(code) {
+    const match = /^([1-5])\.(\d{2})$/.exec(code);
+    if (!match)
+        throw new Error(`Invalid CoAP response code '${code}'`);
+    const detail = Number(match[2]);
+    if (detail > 31)
+        throw new Error(`Invalid CoAP response code '${code}'`);
+    return (Number(match[1]) << 5) | detail;
+}

package/dist/gateway.d.ts

@@ -1,22 +1,76 @@
 /**
  * CoAP Edge Gateway — wires a CoapTransportPort into an EdgeRuntime.
+ *
+ * Requests are CON messages matched to responses by token and remote endpoint
+ * (RFC 7252 §5.3). Confirmable requests are retransmitted with exponential
+ * backoff until acknowledged or until the request deadline expires. An empty
+ * ACK keeps the request pending for a separate response, which is acknowledged
+ * before being handed to the caller.
+ *
+ * RFC 7641 observations keep a token registered after the initial response;
+ * later notifications with a fresh 24-bit Observe sequence are delivered to the
+ * caller and confirmable notifications are acknowledged.
  */
 import type { EdgeRuntime, EdgeOperationResult } from '@totemsdk/edge';
-import type { CoapTransportPort } from './transport.js';
+import type { CoapTransportPort, CoapBlockOption } from './transport.js';
+import type { CoapSecurityPort } from './security.js';
+export interface CoapGatewayTiming {
+    /** Overall request deadline in milliseconds. Default 10_000. */
+    requestTimeoutMs?: number;
+    /** Initial retransmission interval in milliseconds. Default 2_000. */
+    ackTimeoutMs?: number;
+    /** Maximum retransmissions before waiting for the deadline. Default 4. */
+    maxRetransmits?: number;
+}
 export interface CoapGatewayConfig {
     runtime: EdgeRuntime;
     transport: CoapTransportPort;
     localPort: number;
+    timing?: CoapGatewayTiming;
+    /** Optional OSCORE boundary; protected endpoints fail closed without it. */
+    security?: CoapSecurityPort;
+    /** Transparent RFC 7959 blockwise transfer for large payloads. */
+    blockwise?: CoapBlockwiseOptions;
+}
+export interface CoapBlockwiseOptions {
+    /** Enable transparent blockwise transfer. Default true. */
+    enabled?: boolean;
+    /** Preferred block size in bytes (power of two, 16-1024). Default 1024. */
+    blockSize?: number;
+    /** Maximum assembled response body. Default 1 MiB. */
+    maxBodySize?: number;
+}
+export interface CoapResponseData {
+    payload: Uint8Array;
+    /** Content-Format option value, e.g. 0 text/plain or 60 application/cbor. */
+    contentFormat?: number;
+    /** Observe option value (notifications only). */
+    observe?: number;
+    /** Block1 option echoed by the server. */
+    block1?: CoapBlockOption;
+    /** Block2 option describing this response block. */
+    block2?: CoapBlockOption;
+    /** Size1 hint from the server. */
+    size1?: number;
+    /** Size2 hint (total response body size). */
+    size2?: number;
+}
+export interface CoapObservationData extends CoapResponseData {
+    observe: number;
+    receivedAt: number;
+}
+export interface CoapObservation {
+    /** Correlation token as lowercase hex. */
+    readonly token: string;
+    /** Deregister and stop delivering notifications. */
+    cancel(): Promise<void>;
 }
 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;
-    }>>;
+    get(path: string[], host: string, port: number): Promise<EdgeOperationResult<CoapResponseData>>;
+    post(path: string[], payload: Uint8Array, host: string, port: number): Promise<EdgeOperationResult<CoapResponseData>>;
+    observe(path: string[], host: string, port: number, handler: (notification: CoapObservationData) => void): Promise<EdgeOperationResult<CoapObservation>>;
 }
 export declare function createCoapGateway(config: CoapGatewayConfig): CoapGateway;