@matter/thread-br-client 0.0.1

package/dist/esm/otbr-rest/OtbrRestCapability.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/otbr-rest/OtbrRestCapability.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;",
+  "names": []
+}

package/dist/esm/otbr-rest/OtbrRestClient.d.ts

@@ -0,0 +1,257 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { OperationalDataset } from "../dataset/OperationalDataset.js";
+export interface OtbrLeaderData {
+    partitionId: number;
+    weighting: number;
+    dataVersion: number;
+    stableDataVersion: number;
+    leaderRouterId: number;
+}
+export interface OtbrNodeInfo {
+    baId: Uint8Array;
+    state: string;
+    numOfRouter: number;
+    rlocAddress: string;
+    extAddress: Uint8Array;
+    networkName: string;
+    rloc16: number;
+    leaderData: OtbrLeaderData;
+    extPanId: Uint8Array;
+}
+export interface OtbrDatasetHex {
+    activeHex?: string;
+    pendingHex?: string;
+}
+/**
+ * A joiner entry to add to the on-BR commissioner via `POST /node/commissioner/joiner`.
+ *
+ * `pskd` (the joiner passphrase) is required; provide at most one of `eui64`
+ * (EUI-64 hex, or `"*"` for any device) or `discerner` (OpenThread joiner
+ * discerner, e.g. `"0x123/12"`).
+ */
+export interface OtbrJoiner {
+    pskd: string;
+    eui64?: string;
+    discerner?: string;
+    timeoutSeconds?: number;
+}
+export interface OtbrRestClientOptions {
+    host: string;
+    port?: number;
+    timeoutMs?: number;
+}
+/**
+ * Thin HTTP client for the OpenThread Border Router (OTBR) REST API.
+ *
+ * Wraps the OTBR REST endpoints under `/node` and `/diagnostics`. All methods
+ * reject with {@link OtbrRestError} on network failure or a response that
+ * violates the expected shape. IPv6 host literals are bracket-escaped
+ * automatically; bare IPv4 hosts and hostnames are passed through unchanged.
+ *
+ * @example
+ * ```ts
+ * const client = new OtbrRestClient({ host: "fd12::1" });
+ * const info = await client.getNode();
+ * ```
+ */
+export declare class OtbrRestClient {
+    #private;
+    /**
+     * @param opts - Connection parameters; `host` is required.
+     */
+    constructor(opts: OtbrRestClientOptions);
+    get baseUrl(): string;
+    /**
+     * Fetch the current node summary from the OTBR `/node` endpoint.
+     *
+     * @returns Parsed node info with typed fields (binary fields as `Uint8Array`).
+     * @throws {@link OtbrRestError} with code `"rest_unreachable"` on network error or timeout.
+     * @throws {@link OtbrRestError} with code `"rest_protocol"` when the response is
+     *   not a valid JSON object or a required field is missing or has the wrong type.
+     */
+    getNode(): Promise<OtbrNodeInfo>;
+    /**
+     * Fetch the raw diagnostics array from the OTBR `/diagnostics` endpoint.
+     *
+     * The response is returned as-is — callers are responsible for interpreting
+     * the per-node objects. Use `OtbrRestDiagnosticSource` for a typed interface
+     * that translates this payload into `DiagnosticResponse` values.
+     *
+     * @returns Array of raw node diagnostic objects as returned by the BR.
+     * @throws {@link OtbrRestError} with code `"rest_unreachable"` on network error or timeout.
+     * @throws {@link OtbrRestError} with code `"rest_protocol"` when the response is not a JSON array.
+     */
+    getDiagnostics(): Promise<unknown[]>;
+    /**
+     * Fetch the active and pending dataset hex strings from the OTBR REST API.
+     *
+     * Each dataset is fetched independently from `/node/dataset/active` and
+     * `/node/dataset/pending`. A `204 No Content` response means the dataset is
+     * absent, in which case the corresponding field is omitted from the result.
+     *
+     * @returns Object with `activeHex` and/or `pendingHex` hex strings; fields
+     *   are absent when the BR has no dataset of that type.
+     * @throws {@link OtbrRestError} with code `"rest_unreachable"` on network error or timeout.
+     * @throws {@link OtbrRestError} with code `"rest_protocol"` on a non-2xx HTTP status.
+     */
+    getDataset(): Promise<OtbrDatasetHex>;
+    /**
+     * Fetch the node role from `/node/state` (e.g. `"router"`, `"leader"`, `"child"`, `"disabled"`).
+     *
+     * @throws {@link OtbrRestError} `"rest_unreachable"` on network error, `"rest_protocol"` on a
+     *   non-string body.
+     */
+    getState(): Promise<string>;
+    /**
+     * Fetch the Thread network name from `/node/network-name`.
+     */
+    getNetworkName(): Promise<string>;
+    /**
+     * Fetch the node's Routing Locator (RLOC) IPv6 address from `/node/rloc`.
+     */
+    getRloc(): Promise<string>;
+    /**
+     * Fetch the 16-bit RLOC from `/node/rloc16`.
+     */
+    getRloc16(): Promise<number>;
+    /**
+     * Fetch the number of routers in the Thread network from `/node/num-of-router`.
+     */
+    getNumOfRouter(): Promise<number>;
+    /**
+     * Fetch the 8-byte IEEE EUI-64 extended address from `/node/ext-address`.
+     */
+    getExtAddress(): Promise<Uint8Array>;
+    /**
+     * Fetch the 8-byte Extended PAN ID from `/node/ext-panid`.
+     */
+    getExtPanId(): Promise<Uint8Array>;
+    /**
+     * Fetch the 16-byte Border Agent ID from `/node/ba-id`.
+     *
+     * @throws {@link OtbrRestError} `"rest_unsupported"` on older firmware that lacks this endpoint (404).
+     */
+    getBorderAgentId(): Promise<Uint8Array>;
+    /**
+     * Fetch the leader data record from `/node/leader-data`.
+     */
+    getLeaderData(): Promise<OtbrLeaderData>;
+    /**
+     * Fetch and decode the active Operational Dataset from `/node/dataset/active`.
+     *
+     * @returns The decoded dataset, or `undefined` when the BR has no active dataset (204).
+     */
+    getActiveDataset(): Promise<OperationalDataset | undefined>;
+    /**
+     * Fetch and decode the pending Operational Dataset from `/node/dataset/pending`.
+     *
+     * @returns The decoded dataset, or `undefined` when the BR has no pending dataset (204).
+     */
+    getPendingDataset(): Promise<OperationalDataset | undefined>;
+    /**
+     * Fetch the RCP/co-processor version string from `/node/coprocessor/version`.
+     *
+     * @throws {@link OtbrRestError} `"rest_unsupported"` on older firmware that lacks this endpoint (404).
+     */
+    getCoprocessorVersion(): Promise<string>;
+    /**
+     * Fetch the on-BR commissioner state from `/node/commissioner/state`.
+     *
+     * @throws {@link OtbrRestError} `"rest_unsupported"` on firmware without a built-in commissioner (404).
+     */
+    getCommissionerState(): Promise<string>;
+    /**
+     * Fetch the list of pending joiners from `/node/commissioner/joiner`.
+     *
+     * The entries are returned as-is (keys normalized to camelCase); callers
+     * interpret the per-joiner objects.
+     *
+     * @throws {@link OtbrRestError} `"rest_unsupported"` on firmware without a built-in commissioner (404).
+     */
+    getJoiners(): Promise<unknown[]>;
+    /**
+     * Enable or disable the Thread interface via `PUT /node/state`.
+     *
+     * @throws {@link OtbrRestError} `"rest_conflict"` when the BR rejects the transition (409).
+     */
+    setState(enable: boolean): Promise<void>;
+    /**
+     * Set the active Operational Dataset via `PUT /node/dataset/active`.
+     *
+     * @param dataset - An {@link OperationalDataset} (encoded to TLV hex) or a raw TLV hex string.
+     * @throws {@link OtbrRestError} `"rest_conflict"` when Thread is active and the active
+     *   dataset cannot be replaced in place (409) — use {@link setPendingDataset} instead.
+     */
+    setActiveDataset(dataset: OperationalDataset | string): Promise<void>;
+    /**
+     * Clear the active Operational Dataset via `DELETE /node/dataset/active`.
+     */
+    deleteActiveDataset(): Promise<void>;
+    /**
+     * Set the pending Operational Dataset via `PUT /node/dataset/pending`.
+     *
+     * @param dataset - An {@link OperationalDataset} (encoded to TLV hex) or a raw TLV hex string.
+     */
+    setPendingDataset(dataset: OperationalDataset | string): Promise<void>;
+    /**
+     * Clear the pending Operational Dataset via `DELETE /node/dataset/pending`.
+     */
+    deletePendingDataset(): Promise<void>;
+    /**
+     * Factory-reset the Thread node via `DELETE /node`.
+     *
+     * @throws {@link OtbrRestError} `"rest_not_allowed"` when the firmware disallows factory reset (405);
+     *   `"rest_conflict"` when the interface is in a state that forbids it (409).
+     */
+    factoryReset(): Promise<void>;
+    /**
+     * Enable or disable the on-BR commissioner via `PUT /node/commissioner/state`.
+     *
+     * @throws {@link OtbrRestError} `"rest_conflict"` when the BR is not active (409);
+     *   `"rest_unsupported"` on firmware without a built-in commissioner (404).
+     */
+    setCommissionerState(enable: boolean): Promise<void>;
+    /**
+     * Add a joiner to the on-BR commissioner via `POST /node/commissioner/joiner`.
+     *
+     * Provide at most one of `eui64` or `discerner`; omit both to match any device.
+     *
+     * @throws {@link ImplementationError} when both `eui64` and `discerner` are provided.
+     * @throws {@link OtbrRestError} `"rest_conflict"` when the commissioner is not active (409).
+     */
+    addJoiner(joiner: OtbrJoiner): Promise<void>;
+    /**
+     * Remove a joiner from the on-BR commissioner via `DELETE /node/commissioner/joiner`.
+     *
+     * @param joinerId - EUI-64 hex, a discerner (`"0x…/len"`), or `"*"` to remove all joiners.
+     * @throws {@link OtbrRestError} `"rest_conflict"` when the commissioner is not active (409).
+     */
+    removeJoiner(joinerId: string): Promise<void>;
+    /**
+     * POST an action body to the OTBR `/api/actions` endpoint.
+     *
+     * Only available on camelCase (post-2024) OTBR builds — callers must guard
+     * on `OtbrRestCapability.keyFormat === "camel"` before calling this method.
+     *
+     * @param body - The action payload (e.g. `{ action: "resetNetworkDiagCounterTask" }`).
+     * @throws {@link OtbrRestError} with code `"rest_unreachable"` on network error.
+     * @throws {@link OtbrRestError} with code `"rest_protocol"` on a non-2xx response.
+     */
+    resetDiagnosticCounters(body: Record<string, unknown>): Promise<void>;
+    /**
+     * POST a `getEnergyScanTask` action to the OTBR `/api/actions` endpoint.
+     *
+     * Only available on camelCase (post-2024) OTBR builds — callers must guard
+     * on `OtbrRestCapability.keyFormat === "camel"` before calling this method.
+     *
+     * @param body - The action payload (e.g. `{ action: "getEnergyScanTask" }`).
+     * @throws {@link OtbrRestError} with code `"rest_unreachable"` on network error.
+     * @throws {@link OtbrRestError} with code `"rest_protocol"` on a non-2xx response.
+     */
+    getEnergyScanTask(body: Record<string, unknown>): Promise<void>;
+}
+//# sourceMappingURL=OtbrRestClient.d.ts.map

package/dist/esm/otbr-rest/OtbrRestClient.d.ts.map

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