@matter/thread-br-client 0.0.1

package/dist/cjs/coap/CoapMessage.js

@@ -0,0 +1,182 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var CoapMessage_exports = {};
+__export(CoapMessage_exports, {
+  CoapError: () => CoapError,
+  CoapMessage: () => CoapMessage
+});
+module.exports = __toCommonJS(CoapMessage_exports);
+var import_general = require("@matter/general");
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class CoapError extends import_general.MatterError {
+}
+const VERSION = 1;
+const OPTION_URI_PATH = 11;
+const PAYLOAD_MARKER = 255;
+const TYPE_TO_BITS = { CON: 0, NON: 1, ACK: 2, RST: 3 };
+const BITS_TO_TYPE = ["CON", "NON", "ACK", "RST"];
+function encodeCode(code) {
+  const match = /^(\d)\.(\d{2})$/.exec(code);
+  if (match === null) {
+    throw new CoapError(`Invalid CoAP code "${code}"`);
+  }
+  const cls = Number(match[1]);
+  const detail = Number(match[2]);
+  if (cls > 7 || detail > 31) {
+    throw new CoapError(`CoAP code "${code}" out of range (class 0-7, detail 0-31)`);
+  }
+  return cls << 5 | detail;
+}
+function decodeCode(byte) {
+  const cls = byte >> 5;
+  const detail = byte & 31;
+  return `${cls}.${detail.toString().padStart(2, "0")}`;
+}
+function encodeExtension(value) {
+  if (value < 13) {
+    return { nibble: value, extension: [] };
+  }
+  if (value < 269) {
+    return { nibble: 13, extension: [value - 13] };
+  }
+  const extended = value - 269;
+  return { nibble: 14, extension: [extended >> 8 & 255, extended & 255] };
+}
+function pushAll(out, bytes) {
+  for (const b of bytes) {
+    out.push(b);
+  }
+}
+function encodeOption(out, delta, value) {
+  const d = encodeExtension(delta);
+  const l = encodeExtension(value.length);
+  out.push(d.nibble << 4 | l.nibble);
+  pushAll(out, d.extension);
+  pushAll(out, l.extension);
+  pushAll(out, value);
+}
+var CoapMessage;
+((CoapMessage2) => {
+  function encode(msg) {
+    const tokenLength = msg.token.length;
+    if (tokenLength > 8) {
+      throw new CoapError(`CoAP token too long: ${tokenLength} (max 8)`);
+    }
+    const out = new Array();
+    out.push(VERSION << 6 | TYPE_TO_BITS[msg.type] << 4 | tokenLength);
+    out.push(encodeCode(msg.code));
+    out.push(msg.messageId >> 8 & 255, msg.messageId & 255);
+    pushAll(out, msg.token);
+    if (msg.uriPath !== void 0) {
+      let lastOptionNumber = 0;
+      for (const segment of msg.uriPath) {
+        encodeOption(out, OPTION_URI_PATH - lastOptionNumber, import_general.Bytes.of(import_general.Bytes.fromString(segment)));
+        lastOptionNumber = OPTION_URI_PATH;
+      }
+    }
+    if (msg.payload.length > 0) {
+      out.push(PAYLOAD_MARKER);
+      pushAll(out, msg.payload);
+    }
+    return Uint8Array.from(out);
+  }
+  CoapMessage2.encode = encode;
+  function decode(bytes) {
+    if (bytes.length < 4) {
+      throw new CoapError(`CoAP message too short: ${bytes.length} bytes`);
+    }
+    const version = bytes[0] >> 6;
+    if (version !== VERSION) {
+      throw new CoapError(`Unsupported CoAP version ${version}`);
+    }
+    const type = BITS_TO_TYPE[bytes[0] >> 4 & 3];
+    const tokenLength = bytes[0] & 15;
+    if (tokenLength > 8) {
+      throw new CoapError(`Invalid CoAP token length ${tokenLength}`);
+    }
+    const code = decodeCode(bytes[1]);
+    const messageId = bytes[2] << 8 | bytes[3];
+    let pos = 4;
+    if (pos + tokenLength > bytes.length) {
+      throw new CoapError("CoAP token exceeds message length");
+    }
+    const token = bytes.slice(pos, pos + tokenLength);
+    pos += tokenLength;
+    const readExtension = (nibble) => {
+      if (nibble < 13) {
+        return nibble;
+      }
+      if (nibble === 13) {
+        if (pos >= bytes.length) {
+          throw new CoapError("Truncated CoAP option (1-byte extension)");
+        }
+        return bytes[pos++] + 13;
+      }
+      if (nibble === 14) {
+        if (pos + 2 > bytes.length) {
+          throw new CoapError("Truncated CoAP option (2-byte extension)");
+        }
+        const value = (bytes[pos] << 8 | bytes[pos + 1]) + 269;
+        pos += 2;
+        return value;
+      }
+      throw new CoapError("Reserved CoAP option nibble 15");
+    };
+    const uriPath = new Array();
+    let optionNumber = 0;
+    let payload = new Uint8Array();
+    while (pos < bytes.length) {
+      const header = bytes[pos];
+      if (header === PAYLOAD_MARKER) {
+        pos++;
+        payload = bytes.slice(pos);
+        if (payload.length === 0) {
+          throw new CoapError("CoAP payload marker with no payload");
+        }
+        break;
+      }
+      pos++;
+      const delta = readExtension(header >> 4);
+      const length = readExtension(header & 15);
+      optionNumber += delta;
+      if (pos + length > bytes.length) {
+        throw new CoapError("CoAP option value exceeds message length");
+      }
+      const value = bytes.slice(pos, pos + length);
+      pos += length;
+      if (optionNumber === OPTION_URI_PATH) {
+        uriPath.push(import_general.Bytes.toString(value));
+      }
+    }
+    return {
+      type,
+      code,
+      messageId,
+      token,
+      uriPath: uriPath.length > 0 ? uriPath : void 0,
+      payload
+    };
+  }
+  CoapMessage2.decode = decode;
+})(CoapMessage || (CoapMessage = {}));
+//# sourceMappingURL=CoapMessage.js.map

package/dist/cjs/coap/CoapMessage.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/coap/CoapMessage.ts"],
+  "mappings": "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",
+  "names": ["CoapMessage"]
+}

package/dist/cjs/coap/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export { CoapClient, CoapTimeoutError } from "./CoapClient.js";
+export type { CoapMessage, CoapType } from "./CoapMessage.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/coap/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/coap/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/cjs/coap/index.js

@@ -0,0 +1,31 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var coap_exports = {};
+__export(coap_exports, {
+  CoapClient: () => import_CoapClient.CoapClient,
+  CoapTimeoutError: () => import_CoapClient.CoapTimeoutError
+});
+module.exports = __toCommonJS(coap_exports);
+var import_CoapClient = require("./CoapClient.js");
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+//# sourceMappingURL=index.js.map

package/dist/cjs/coap/index.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/coap/index.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,wBAA6C;AAN7C;AAAA;AAAA;AAAA;AAAA;",
+  "names": []
+}

package/dist/cjs/commissioner/Commissioner.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MatterError, TimeoutError } from "@matter/general";
+import type { CoapClient } from "../coap/CoapClient.js";
+/** Thrown by {@link Commissioner.petition} when the Border Router explicitly rejects the petition. */
+export declare class CommissionerRejectedError extends MatterError {
+    constructor();
+}
+/** Thrown by {@link Commissioner.petition} when the petition is still pending after one retry. */
+export declare class CommissionerTimeoutError extends TimeoutError {
+    constructor();
+}
+/** Thrown by {@link Commissioner.keepAlive} when the Border Router answers with a non-accept state. */
+export declare class CommissionerKeepAliveError extends MatterError {
+}
+export interface CommissionerOpts {
+    /** Override the 30s pending-retry delay. Intended for testing. */
+    pendingRetryDelayMs?: number;
+}
+/**
+ * Thread MeshCoP Commissioner — petitions for, maintains, and releases a
+ * commissioner session over an already-connected CoAP transport.
+ *
+ * Callers should prefer {@link Commissioner.withSession} for the full
+ * petition → keep-alive → release lifecycle. Use `petition`/`keepAlive`/`release`
+ * directly only when finer-grained control is needed.
+ */
+export declare class Commissioner {
+    #private;
+    static readonly COMMISSIONER_ID = "matter-server";
+    /**
+     * @param coap - CoAP transport connected to the target Border Router.
+     * @param opts - Optional overrides (e.g. `pendingRetryDelayMs` for tests).
+     */
+    constructor(coap: CoapClient, opts?: CommissionerOpts);
+    /**
+     * Send a MeshCoP `COMM_PET` (commissioner petition) request.
+     *
+     * When the BR responds `pending`, retries once after `pendingRetryDelayMs`
+     * (default 30 s). Accepts on the first `accept` response.
+     *
+     * @returns The commissioner session ID assigned by the Border Router.
+     * @throws {@link CommissionerRejectedError} when the BR returns `reject` on
+     *   the initial petition or on the retry.
+     * @throws {@link CommissionerTimeoutError} when the BR returns `pending` on
+     *   both the initial petition and the retry.
+     * @throws `Error` on CoAP transport or TLV parse failure.
+     */
+    petition(): Promise<number>;
+    /**
+     * Send a MeshCoP `COMM_KA` (commissioner keep-alive) request.
+     *
+     * Must be called periodically (typically every ~40 s) while the session is
+     * active; the BR will revoke the session if no keep-alive is received within
+     * its timeout window. Prefer {@link Commissioner.withSession}, which schedules
+     * keep-alives automatically.
+     *
+     * @param sessionId - Session ID returned by {@link petition}.
+     * @throws {@link CommissionerKeepAliveError} when the BR rejects the keep-alive; propagates CoAP errors.
+     */
+    keepAlive(sessionId: number): Promise<void>;
+    /**
+     * Send a MeshCoP `COMM_REL` (commissioner release) request.
+     *
+     * Best-effort — CoAP errors are logged at `warn` level and swallowed so a
+     * failed release does not block teardown. The BR will expire the session on
+     * its own if the release is lost.
+     *
+     * @param sessionId - Session ID returned by {@link petition}.
+     */
+    release(sessionId: number): Promise<void>;
+    /**
+     * Run `fn` inside a commissioner session, managing petition, keep-alive, and
+     * release automatically.
+     *
+     * Keep-alive requests fire every ~40 s while `fn` is executing. The session is
+     * released in a `finally` block regardless of whether `fn` resolves or rejects.
+     *
+     * @param fn - Async callback receiving the active session ID.
+     * @returns The value resolved by `fn`.
+     * @throws {@link CommissionerRejectedError} or {@link CommissionerTimeoutError}
+     *   when the petition fails (before `fn` is invoked).
+     */
+    withSession<T>(fn: (sessionId: number) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=Commissioner.d.ts.map

package/dist/cjs/commissioner/Commissioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Commissioner.d.ts","sourceRoot":"","sources":["../../../src/commissioner/Commissioner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAyB,WAAW,EAAyB,YAAY,EAAc,MAAM,iBAAiB,CAAC;AACtH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAQxD,sGAAsG;AACtG,qBAAa,yBAA0B,SAAQ,WAAW;IACtD,cAGC;CACJ;AAED,kGAAkG;AAClG,qBAAa,wBAAyB,SAAQ,YAAY;IACtD,cAGC;CACJ;AAED,uGAAuG;AACvG,qBAAa,0BAA2B,SAAQ,WAAW;CAAG;AAE9D,MAAM,WAAW,gBAAgB;IAC7B,kEAAkE;IAClE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;;IACrB,MAAM,CAAC,QAAQ,CAAC,eAAe,mBAAmB;IAOlD;;;OAGG;IACH,YAAY,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,gBAAgB,EAMpD;IAED;;;;;;;;;;;;OAYG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAwChC;IAED;;;;;;;;;;OAUG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhD;IAED;;;;;;;;OAQG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB9C;IAED;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CActE;CACJ"}

package/dist/cjs/commissioner/Commissioner.js

@@ -0,0 +1,188 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Commissioner_exports = {};
+__export(Commissioner_exports, {
+  Commissioner: () => Commissioner,
+  CommissionerKeepAliveError: () => CommissionerKeepAliveError,
+  CommissionerRejectedError: () => CommissionerRejectedError,
+  CommissionerTimeoutError: () => CommissionerTimeoutError
+});
+module.exports = __toCommonJS(Commissioner_exports);
+var import_general = require("@matter/general");
+var import_meshcopTlvTypes = require("../dataset/meshcopTlvTypes.js");
+var import_BasicTlvCodec = require("../tlv/BasicTlvCodec.js");
+var import_LeadKa = require("./LeadKa.js");
+var import_LeadPet = require("./LeadPet.js");
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = import_general.Logger.get("Commissioner");
+class CommissionerRejectedError extends import_general.MatterError {
+  constructor() {
+    super("Commissioner petition rejected by Border Router");
+    this.name = "CommissionerRejectedError";
+  }
+}
+class CommissionerTimeoutError extends import_general.TimeoutError {
+  constructor() {
+    super("Commissioner petition timed out (still pending after retry)");
+    this.name = "CommissionerTimeoutError";
+  }
+}
+class CommissionerKeepAliveError extends import_general.MatterError {
+}
+class Commissioner {
+  static COMMISSIONER_ID = "matter-server";
+  static #KA_INTERVAL = (0, import_general.Seconds)(40);
+  static #PENDING_RETRY_DELAY = (0, import_general.Seconds)(30);
+  #coap;
+  #pendingRetryDelay;
+  /**
+   * @param coap - CoAP transport connected to the target Border Router.
+   * @param opts - Optional overrides (e.g. `pendingRetryDelayMs` for tests).
+   */
+  constructor(coap, opts) {
+    this.#coap = coap;
+    this.#pendingRetryDelay = opts?.pendingRetryDelayMs !== void 0 ? (0, import_general.Millis)(opts.pendingRetryDelayMs) : Commissioner.#PENDING_RETRY_DELAY;
+  }
+  /**
+   * Send a MeshCoP `COMM_PET` (commissioner petition) request.
+   *
+   * When the BR responds `pending`, retries once after `pendingRetryDelayMs`
+   * (default 30 s). Accepts on the first `accept` response.
+   *
+   * @returns The commissioner session ID assigned by the Border Router.
+   * @throws {@link CommissionerRejectedError} when the BR returns `reject` on
+   *   the initial petition or on the retry.
+   * @throws {@link CommissionerTimeoutError} when the BR returns `pending` on
+   *   both the initial petition and the retry.
+   * @throws `Error` on CoAP transport or TLV parse failure.
+   */
+  async petition() {
+    const response = await this.#coap.request({
+      type: "CON",
+      code: "0.02",
+      uriPath: ["c", "cp"],
+      payload: import_LeadPet.LeadPet.buildRequest(Commissioner.COMMISSIONER_ID)
+    });
+    logger.debug(`[ThreadDiag] COMM_PET response code=${response.code} payloadLen=${response.payload.length}`);
+    const parsed = import_LeadPet.LeadPet.parseResponse(response.payload);
+    if (parsed.state === "accept") {
+      return parsed.sessionId;
+    }
+    if (parsed.state === "reject") {
+      throw new CommissionerRejectedError();
+    }
+    await import_general.Time.sleep("commissioner-pending-retry", this.#pendingRetryDelay);
+    const retryResponse = await this.#coap.request({
+      type: "CON",
+      code: "0.02",
+      uriPath: ["c", "cp"],
+      payload: import_LeadPet.LeadPet.buildRequest(Commissioner.COMMISSIONER_ID)
+    });
+    const retryParsed = import_LeadPet.LeadPet.parseResponse(retryResponse.payload);
+    if (retryParsed.state === "accept") {
+      return retryParsed.sessionId;
+    }
+    if (retryParsed.state === "reject") {
+      throw new CommissionerRejectedError();
+    }
+    throw new CommissionerTimeoutError();
+  }
+  /**
+   * Send a MeshCoP `COMM_KA` (commissioner keep-alive) request.
+   *
+   * Must be called periodically (typically every ~40 s) while the session is
+   * active; the BR will revoke the session if no keep-alive is received within
+   * its timeout window. Prefer {@link Commissioner.withSession}, which schedules
+   * keep-alives automatically.
+   *
+   * @param sessionId - Session ID returned by {@link petition}.
+   * @throws {@link CommissionerKeepAliveError} when the BR rejects the keep-alive; propagates CoAP errors.
+   */
+  async keepAlive(sessionId) {
+    const response = await this.#coap.request({
+      type: "CON",
+      code: "0.02",
+      uriPath: ["c", "ka"],
+      payload: import_LeadKa.LeadKa.buildRequest(sessionId)
+    });
+    const parsed = import_LeadKa.LeadKa.parseResponse(response.payload);
+    if (parsed.state !== "accept") {
+      throw new CommissionerKeepAliveError(`Commissioner keep-alive rejected: state=${parsed.state}`);
+    }
+  }
+  /**
+   * Send a MeshCoP `COMM_REL` (commissioner release) request.
+   *
+   * Best-effort — CoAP errors are logged at `warn` level and swallowed so a
+   * failed release does not block teardown. The BR will expire the session on
+   * its own if the release is lost.
+   *
+   * @param sessionId - Session ID returned by {@link petition}.
+   */
+  async release(sessionId) {
+    try {
+      const sessionBytes = new Uint8Array(2);
+      sessionBytes[0] = sessionId >> 8 & 255;
+      sessionBytes[1] = sessionId & 255;
+      const releasePayload = import_BasicTlvCodec.BasicTlv.encode([
+        { type: import_meshcopTlvTypes.MeshCopTlvType.COMMISSIONER_SESSION_ID, value: sessionBytes },
+        { type: import_meshcopTlvTypes.MeshCopTlvType.COMMISSIONER_ID, value: new TextEncoder().encode(Commissioner.COMMISSIONER_ID) }
+      ]);
+      await this.#coap.request({
+        type: "CON",
+        code: "0.02",
+        uriPath: ["c", "cr"],
+        payload: releasePayload
+      });
+    } catch (err) {
+      logger.warn("Commissioner release failed (best-effort):", err);
+    }
+  }
+  /**
+   * Run `fn` inside a commissioner session, managing petition, keep-alive, and
+   * release automatically.
+   *
+   * Keep-alive requests fire every ~40 s while `fn` is executing. The session is
+   * released in a `finally` block regardless of whether `fn` resolves or rejects.
+   *
+   * @param fn - Async callback receiving the active session ID.
+   * @returns The value resolved by `fn`.
+   * @throws {@link CommissionerRejectedError} or {@link CommissionerTimeoutError}
+   *   when the petition fails (before `fn` is invoked).
+   */
+  async withSession(fn) {
+    const sessionId = await this.petition();
+    const kaInterval = import_general.Time.getPeriodicTimer("commissioner-keepalive", Commissioner.#KA_INTERVAL, () => {
+      void this.keepAlive(sessionId).catch((err) => {
+        logger.warn("Commissioner keep-alive error:", err);
+      });
+    }).start();
+    try {
+      return await fn(sessionId);
+    } finally {
+      kaInterval.stop();
+      await this.release(sessionId);
+    }
+  }
+}
+//# sourceMappingURL=Commissioner.js.map

package/dist/cjs/commissioner/Commissioner.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/commissioner/Commissioner.ts"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/commissioner/LeadKa.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MatterError } from "@matter/general";
+/** Thrown when a commissioner BR response (LeadKa/LeadPet) cannot be parsed. */
+export declare class CommissionerProtocolError extends MatterError {
+}
+export interface LeadKaResponse {
+    state: "accept" | "reject" | "pending";
+}
+export declare namespace LeadKa {
+    function buildRequest(sessionId: number): Uint8Array;
+    function parseResponse(payload: Uint8Array): LeadKaResponse;
+}
+//# sourceMappingURL=LeadKa.d.ts.map

package/dist/cjs/commissioner/LeadKa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LeadKa.d.ts","sourceRoot":"","sources":["../../../src/commissioner/LeadKa.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAI9C,gFAAgF;AAChF,qBAAa,yBAA0B,SAAQ,WAAW;CAAG;AAE7D,MAAM,WAAW,cAAc;IAC3B,KAAK,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;CAC1C;AAKD,yBAAiB,MAAM,CAAC,CAAC;IACrB,SAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAW1D;IAED,SAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,cAAc,CAYjE;CACJ"}

package/dist/cjs/commissioner/LeadKa.js

@@ -0,0 +1,63 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var LeadKa_exports = {};
+__export(LeadKa_exports, {
+  CommissionerProtocolError: () => CommissionerProtocolError,
+  LeadKa: () => LeadKa
+});
+module.exports = __toCommonJS(LeadKa_exports);
+var import_general = require("@matter/general");
+var import_meshcopTlvTypes = require("../dataset/meshcopTlvTypes.js");
+var import_BasicTlvCodec = require("../tlv/BasicTlvCodec.js");
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class CommissionerProtocolError extends import_general.MatterError {
+}
+const STATE_ACCEPT = 1;
+var LeadKa;
+((LeadKa2) => {
+  function buildRequest(sessionId) {
+    const sessionBytes = new Uint8Array(2);
+    sessionBytes[0] = sessionId >> 8 & 255;
+    sessionBytes[1] = sessionId & 255;
+    return import_BasicTlvCodec.BasicTlv.encode([
+      { type: import_meshcopTlvTypes.MeshCopTlvType.STATE, value: new Uint8Array([STATE_ACCEPT]) },
+      { type: import_meshcopTlvTypes.MeshCopTlvType.COMMISSIONER_SESSION_ID, value: sessionBytes }
+    ]);
+  }
+  LeadKa2.buildRequest = buildRequest;
+  function parseResponse(payload) {
+    const entries = import_BasicTlvCodec.BasicTlv.walk(payload);
+    for (const entry of entries) {
+      if (entry.type === import_meshcopTlvTypes.MeshCopTlvType.STATE) {
+        const byte = entry.value[0];
+        if (byte === 1) return { state: "accept" };
+        if (byte === 255) return { state: "reject" };
+        if (byte === 0) return { state: "pending" };
+        throw new CommissionerProtocolError(`LeadKa: unknown state byte ${byte}`);
+      }
+    }
+    throw new CommissionerProtocolError("LeadKa: response missing STATE TLV");
+  }
+  LeadKa2.parseResponse = parseResponse;
+})(LeadKa || (LeadKa = {}));
+//# sourceMappingURL=LeadKa.js.map

package/dist/cjs/commissioner/LeadKa.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/commissioner/LeadKa.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,qBAA4B;AAC5B,6BAA+B;AAC/B,2BAAyB;AARzB;AAAA;AAAA;AAAA;AAAA;AAWO,MAAM,kCAAkC,2BAAY;AAAC;AAO5D,MAAM,eAAe;AAEd,IAAU;AAAA,CAAV,CAAUA,YAAV;AACI,WAAS,aAAa,WAA+B;AACxD,UAAM,eAAe,IAAI,WAAW,CAAC;AACrC,iBAAa,CAAC,IAAK,aAAa,IAAK;AACrC,iBAAa,CAAC,IAAI,YAAY;AAI9B,WAAO,8BAAS,OAAO;AAAA,MACnB,EAAE,MAAM,sCAAe,OAAO,OAAO,IAAI,WAAW,CAAC,YAAY,CAAC,EAAE;AAAA,MACpE,EAAE,MAAM,sCAAe,yBAAyB,OAAO,aAAa;AAAA,IACxE,CAAC;AAAA,EACL;AAXO,EAAAA,QAAS;AAaT,WAAS,cAAc,SAAqC;AAC/D,UAAM,UAAU,8BAAS,KAAK,OAAO;AACrC,eAAW,SAAS,SAAS;AACzB,UAAI,MAAM,SAAS,sCAAe,OAAO;AACrC,cAAM,OAAO,MAAM,MAAM,CAAC;AAC1B,YAAI,SAAS,EAAM,QAAO,EAAE,OAAO,SAAS;AAC5C,YAAI,SAAS,IAAM,QAAO,EAAE,OAAO,SAAS;AAC5C,YAAI,SAAS,EAAM,QAAO,EAAE,OAAO,UAAU;AAC7C,cAAM,IAAI,0BAA0B,8BAA8B,IAAI,EAAE;AAAA,MAC5E;AAAA,IACJ;AACA,UAAM,IAAI,0BAA0B,oCAAoC;AAAA,EAC5E;AAZO,EAAAA,QAAS;AAAA,GAdH;",
+  "names": ["LeadKa"]
+}

package/dist/cjs/commissioner/LeadPet.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface LeadPetResponse {
+    state: "accept" | "reject" | "pending";
+    sessionId?: number;
+}
+export declare namespace LeadPet {
+    function buildRequest(commissionerId: string): Uint8Array;
+    function parseResponse(payload: Uint8Array): LeadPetResponse;
+}
+//# sourceMappingURL=LeadPet.d.ts.map

package/dist/cjs/commissioner/LeadPet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LeadPet.d.ts","sourceRoot":"","sources":["../../../src/commissioner/LeadPet.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,MAAM,WAAW,eAAe;IAC5B,KAAK,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,yBAAiB,OAAO,CAAC,CAAC;IACtB,SAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,UAAU,CAI/D;IAED,SAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,eAAe,CA4BlE;CACJ"}