@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/types/proto/esp_rmaker_chal_resp.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Generated by the protoc-gen-ts.  DO NOT EDIT!
+ * compiler version: 5.29.3
+ * source: esp_rmaker_chal_resp.proto
+ * git: https://github.com/thesayyn/protoc-gen-ts */
+import * as pb_1 from "google-protobuf";
+export declare namespace rmaker_misc {
+    enum RMakerMiscStatus {
+        Success = 0,
+        Fail = 1,
+        InvalidParam = 2
+    }
+    enum RMakerMiscMsgType {
+        TypeCmdChallengeResponse = 0,
+        TypeRespChallengeResponse = 1,
+        TypeCmdGetNodeID = 2,
+        TypeRespGetNodeID = 3
+    }
+    class CmdCRPayload extends pb_1.Message {
+        #private;
+        constructor(data?: any[] | {
+            payload?: Uint8Array;
+        });
+        get payload(): Uint8Array;
+        set payload(value: Uint8Array);
+        static fromObject(data: {
+            payload?: Uint8Array;
+        }): CmdCRPayload;
+        toObject(): {
+            payload?: Uint8Array;
+        };
+        serialize(): Uint8Array;
+        serialize(w: pb_1.BinaryWriter): void;
+        static deserialize(bytes: Uint8Array | pb_1.BinaryReader): CmdCRPayload;
+        serializeBinary(): Uint8Array;
+        static deserializeBinary(bytes: Uint8Array): CmdCRPayload;
+    }
+    class RespCRPayload extends pb_1.Message {
+        #private;
+        constructor(data?: any[] | {
+            payload?: Uint8Array;
+            node_id?: string;
+        });
+        get payload(): Uint8Array;
+        set payload(value: Uint8Array);
+        get node_id(): string;
+        set node_id(value: string);
+        static fromObject(data: {
+            payload?: Uint8Array;
+            node_id?: string;
+        }): RespCRPayload;
+        toObject(): {
+            payload?: Uint8Array;
+            node_id?: string;
+        };
+        serialize(): Uint8Array;
+        serialize(w: pb_1.BinaryWriter): void;
+        static deserialize(bytes: Uint8Array | pb_1.BinaryReader): RespCRPayload;
+        serializeBinary(): Uint8Array;
+        static deserializeBinary(bytes: Uint8Array): RespCRPayload;
+    }
+    class CmdGetNodeIDPayload extends pb_1.Message {
+        #private;
+        constructor(data?: any[] | {});
+        static fromObject(data: {}): CmdGetNodeIDPayload;
+        toObject(): {};
+        serialize(): Uint8Array;
+        serialize(w: pb_1.BinaryWriter): void;
+        static deserialize(bytes: Uint8Array | pb_1.BinaryReader): CmdGetNodeIDPayload;
+        serializeBinary(): Uint8Array;
+        static deserializeBinary(bytes: Uint8Array): CmdGetNodeIDPayload;
+    }
+    class RespGetNodeIDPayload extends pb_1.Message {
+        #private;
+        constructor(data?: any[] | {
+            node_id?: string;
+        });
+        get node_id(): string;
+        set node_id(value: string);
+        static fromObject(data: {
+            node_id?: string;
+        }): RespGetNodeIDPayload;
+        toObject(): {
+            node_id?: string;
+        };
+        serialize(): Uint8Array;
+        serialize(w: pb_1.BinaryWriter): void;
+        static deserialize(bytes: Uint8Array | pb_1.BinaryReader): RespGetNodeIDPayload;
+        serializeBinary(): Uint8Array;
+        static deserializeBinary(bytes: Uint8Array): RespGetNodeIDPayload;
+    }
+    class RMakerMiscPayload extends pb_1.Message {
+        #private;
+        constructor(data?: any[] | ({
+            msg?: RMakerMiscMsgType;
+            status?: RMakerMiscStatus;
+        } & (({
+            cmdChallengeResponsePayload?: CmdCRPayload;
+            respChallengeResponsePayload?: never;
+            cmdGetNodeIDPayload?: never;
+            respGetNodeIDPayload?: never;
+        } | {
+            cmdChallengeResponsePayload?: never;
+            respChallengeResponsePayload?: RespCRPayload;
+            cmdGetNodeIDPayload?: never;
+            respGetNodeIDPayload?: never;
+        } | {
+            cmdChallengeResponsePayload?: never;
+            respChallengeResponsePayload?: never;
+            cmdGetNodeIDPayload?: CmdGetNodeIDPayload;
+            respGetNodeIDPayload?: never;
+        } | {
+            cmdChallengeResponsePayload?: never;
+            respChallengeResponsePayload?: never;
+            cmdGetNodeIDPayload?: never;
+            respGetNodeIDPayload?: RespGetNodeIDPayload;
+        }))));
+        get msg(): RMakerMiscMsgType;
+        set msg(value: RMakerMiscMsgType);
+        get status(): RMakerMiscStatus;
+        set status(value: RMakerMiscStatus);
+        get cmdChallengeResponsePayload(): CmdCRPayload;
+        set cmdChallengeResponsePayload(value: CmdCRPayload);
+        get has_cmdChallengeResponsePayload(): boolean;
+        get respChallengeResponsePayload(): RespCRPayload;
+        set respChallengeResponsePayload(value: RespCRPayload);
+        get has_respChallengeResponsePayload(): boolean;
+        get cmdGetNodeIDPayload(): CmdGetNodeIDPayload;
+        set cmdGetNodeIDPayload(value: CmdGetNodeIDPayload);
+        get has_cmdGetNodeIDPayload(): boolean;
+        get respGetNodeIDPayload(): RespGetNodeIDPayload;
+        set respGetNodeIDPayload(value: RespGetNodeIDPayload);
+        get has_respGetNodeIDPayload(): boolean;
+        get payload(): "cmdChallengeResponsePayload" | "respChallengeResponsePayload" | "cmdGetNodeIDPayload" | "respGetNodeIDPayload" | "none";
+        static fromObject(data: {
+            msg?: RMakerMiscMsgType;
+            status?: RMakerMiscStatus;
+            cmdChallengeResponsePayload?: ReturnType<typeof CmdCRPayload.prototype.toObject>;
+            respChallengeResponsePayload?: ReturnType<typeof RespCRPayload.prototype.toObject>;
+            cmdGetNodeIDPayload?: ReturnType<typeof CmdGetNodeIDPayload.prototype.toObject>;
+            respGetNodeIDPayload?: ReturnType<typeof RespGetNodeIDPayload.prototype.toObject>;
+        }): RMakerMiscPayload;
+        toObject(): {
+            msg?: RMakerMiscMsgType;
+            status?: RMakerMiscStatus;
+            cmdChallengeResponsePayload?: ReturnType<typeof CmdCRPayload.prototype.toObject>;
+            respChallengeResponsePayload?: ReturnType<typeof RespCRPayload.prototype.toObject>;
+            cmdGetNodeIDPayload?: ReturnType<typeof CmdGetNodeIDPayload.prototype.toObject>;
+            respGetNodeIDPayload?: ReturnType<typeof RespGetNodeIDPayload.prototype.toObject>;
+        };
+        serialize(): Uint8Array;
+        serialize(w: pb_1.BinaryWriter): void;
+        static deserialize(bytes: Uint8Array | pb_1.BinaryReader): RMakerMiscPayload;
+        serializeBinary(): Uint8Array;
+        static deserializeBinary(bytes: Uint8Array): RMakerMiscPayload;
+    }
+}

package/dist/types/proto/esp_rmaker_claim.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Enum representing the status of a claiming operation.
+ */
+export declare enum RMakerClaimStatus {
+    Success = 0,
+    Fail = 1,
+    InvalidParam = 2,
+    InvalidState = 3,
+    NoMemory = 4
+}
+/**
+ * Enum representing the message types for claiming operations.
+ */
+export declare enum RMakerClaimMsgType {
+    TypeCmdClaimStart = 0,
+    TypeRespClaimStart = 1,
+    TypeCmdClaimInit = 2,
+    TypeRespClaimInit = 3,
+    TypeCmdClaimVerify = 4,
+    TypeRespClaimVerify = 5,
+    TypeCmdClaimAbort = 6,
+    TypeRespClaimAbort = 7
+}
+/**
+ * Interface representing a payload buffer for claiming data transfer.
+ */
+export interface PayloadBuf {
+    /** Offset for chunked data transfer */
+    offset: number;
+    /** The payload data as Uint8Array */
+    payload: Uint8Array;
+    /** Total length of the data being transferred */
+    totalLen: number;
+}
+/**
+ * Interface representing a response payload from the device.
+ */
+export interface RespPayload {
+    /** Status of the operation */
+    status: RMakerClaimStatus;
+    /** Buffer containing response data */
+    buf?: PayloadBuf;
+}
+/**
+ * Interface representing a claiming payload message.
+ */
+export interface RMakerClaimPayload {
+    /** Message type */
+    msg: RMakerClaimMsgType;
+    /** Command payload (for commands sent to device) */
+    cmdPayload?: PayloadBuf;
+    /** Response payload (for responses from device) */
+    respPayload?: RespPayload;
+}
+/**
+ * Helper class for encoding/decoding claiming protobuf messages.
+ * This is a simplified implementation that creates/parses the proto format.
+ */
+export declare class ClaimingProtoHelper {
+    /**
+     * Creates a ClaimStart command payload.
+     * Android sends: msg=TypeCmdClaimStart + empty cmdPayload
+     * @returns Uint8Array payload
+     */
+    static createClaimStartRequest(): Uint8Array;
+    /**
+     * Creates a ClaimInit command payload with data from cloud.
+     * @param data - The data string to send (from cloud initiate response)
+     * @returns Uint8Array payload
+     */
+    static createClaimInitRequest(data: string): Uint8Array;
+    /**
+     * Creates a ClaimInit request to get more CSR data (continuation request).
+     * @returns Uint8Array payload
+     */
+    static createClaimInitContinueRequest(): Uint8Array;
+    /**
+     * Creates a ClaimVerify command payload with certificate data.
+     * @param certificateData - The certificate string to send
+     * @param offset - Current offset for chunked transfer
+     * @param chunkSize - Size of each chunk
+     * @returns Uint8Array payload
+     */
+    static createClaimVerifyRequest(certificateData: string, offset: number, chunkSize: number): Uint8Array;
+    /**
+     * Creates a ClaimAbort command payload.
+     * @returns Uint8Array payload
+     */
+    static createClaimAbortRequest(): Uint8Array;
+    /**
+     * Parses a claiming response from the device.
+     * @param data - The response data as Uint8Array
+     * @returns Parsed RMakerClaimPayload
+     */
+    static parseClaimResponse(data: Uint8Array): RMakerClaimPayload;
+    /**
+     * Extracts the payload string from a response.
+     * @param response - The parsed response
+     * @returns The payload as a string, or empty string if not available
+     */
+    static extractPayloadString(response: RMakerClaimPayload): string;
+    /**
+     * Gets the offset from a response.
+     * @param response - The parsed response
+     * @returns The offset value
+     */
+    static getOffset(response: RMakerClaimPayload): number;
+    /**
+     * Gets the total length from a response.
+     * @param response - The parsed response
+     * @returns The total length value
+     */
+    static getTotalLen(response: RMakerClaimPayload): number;
+    /**
+     * Checks if the response indicates success.
+     * @param response - The parsed response
+     * @returns true if status is Success
+     */
+    static isSuccess(response: RMakerClaimPayload): boolean;
+    /**
+     * Returns the device's status as its enum name, for diagnostics. The device
+     * distinguishes causes here: `InvalidParam` for a payload it rejected,
+     * `InvalidState` for a request out of order, `NoMemory` for an oversized
+     * fragment.
+     *
+     * @param response - The parsed response
+     * @returns The status name, or "Unknown" when absent
+     */
+    static getStatus(response: RMakerClaimPayload): string;
+    private static encodeVarint;
+    private static readVarint;
+    private static encodePayloadBuf;
+    private static encodeClaimPayload;
+    private static parseRespPayload;
+    private static parsePayloadBuf;
+}

package/dist/types/proto/esp_rmaker_user_mapping.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Generated by the protoc-gen-ts.  DO NOT EDIT!
+ * compiler version: 5.28.2
+ * source: esp_rmaker_user_mapping.proto
+ * git: https://github.com/thesayyn/protoc-gen-ts */
+import * as pb_1 from "google-protobuf";
+export declare namespace rainmaker {
+    enum RMakerConfigStatus {
+        Success = 0,
+        InvalidParam = 1,
+        InvalidState = 2
+    }
+    enum RMakerConfigMsgType {
+        TypeCmdSetUserMapping = 0,
+        TypeRespSetUserMapping = 1
+    }
+    class CmdSetUserMapping extends pb_1.Message {
+        #private;
+        constructor(data?: any[] | {
+            UserID?: string;
+            SecretKey?: string;
+        });
+        get UserID(): string;
+        set UserID(value: string);
+        get SecretKey(): string;
+        set SecretKey(value: string);
+        static fromObject(data: {
+            UserID?: string;
+            SecretKey?: string;
+        }): CmdSetUserMapping;
+        toObject(): {
+            UserID?: string;
+            SecretKey?: string;
+        };
+        serialize(): Uint8Array;
+        serialize(w: pb_1.BinaryWriter): void;
+        static deserialize(bytes: Uint8Array | pb_1.BinaryReader): CmdSetUserMapping;
+        serializeBinary(): Uint8Array;
+        static deserializeBinary(bytes: Uint8Array): CmdSetUserMapping;
+    }
+    class RespSetUserMapping extends pb_1.Message {
+        #private;
+        constructor(data?: any[] | {
+            Status?: RMakerConfigStatus;
+            NodeId?: string;
+        });
+        get Status(): RMakerConfigStatus;
+        set Status(value: RMakerConfigStatus);
+        get NodeId(): string;
+        set NodeId(value: string);
+        static fromObject(data: {
+            Status?: RMakerConfigStatus;
+            NodeId?: string;
+        }): RespSetUserMapping;
+        toObject(): {
+            Status?: RMakerConfigStatus;
+            NodeId?: string;
+        };
+        serialize(): Uint8Array;
+        serialize(w: pb_1.BinaryWriter): void;
+        static deserialize(bytes: Uint8Array | pb_1.BinaryReader): RespSetUserMapping;
+        serializeBinary(): Uint8Array;
+        static deserializeBinary(bytes: Uint8Array): RespSetUserMapping;
+    }
+    class RMakerConfigPayload extends pb_1.Message {
+        #private;
+        constructor(data?: any[] | ({
+            msg?: RMakerConfigMsgType;
+        } & ({
+            cmd_set_user_mapping?: CmdSetUserMapping;
+            resp_set_user_mapping?: never;
+        } | {
+            cmd_set_user_mapping?: never;
+            resp_set_user_mapping?: RespSetUserMapping;
+        })));
+        get msg(): RMakerConfigMsgType;
+        set msg(value: RMakerConfigMsgType);
+        get cmd_set_user_mapping(): CmdSetUserMapping;
+        set cmd_set_user_mapping(value: CmdSetUserMapping);
+        get has_cmd_set_user_mapping(): boolean;
+        get resp_set_user_mapping(): RespSetUserMapping;
+        set resp_set_user_mapping(value: RespSetUserMapping);
+        get has_resp_set_user_mapping(): boolean;
+        get payload(): "cmd_set_user_mapping" | "resp_set_user_mapping" | "none";
+        static fromObject(data: {
+            msg?: RMakerConfigMsgType;
+            cmd_set_user_mapping?: ReturnType<typeof CmdSetUserMapping.prototype.toObject>;
+            resp_set_user_mapping?: ReturnType<typeof RespSetUserMapping.prototype.toObject>;
+        }): RMakerConfigPayload;
+        toObject(): {
+            msg?: RMakerConfigMsgType;
+            cmd_set_user_mapping?: ReturnType<typeof CmdSetUserMapping.prototype.toObject>;
+            resp_set_user_mapping?: ReturnType<typeof RespSetUserMapping.prototype.toObject>;
+        };
+        serialize(): Uint8Array;
+        serialize(w: pb_1.BinaryWriter): void;
+        static deserialize(bytes: Uint8Array | pb_1.BinaryReader): RMakerConfigPayload;
+        serializeBinary(): Uint8Array;
+        static deserializeBinary(bytes: Uint8Array): RMakerConfigPayload;
+    }
+}

package/dist/types/services/ESPRMNeoAPIManager.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Dependencies required to construct the base API manager. Passed explicitly
+ * at init time; the class does not reach back into {@link ESPRMNeoBase}.
+ */
+export interface ESPRMNeoAPIManagerInit {
+    /**
+     * Fully-resolved User API base URL, e.g.
+     * "https://api.rainmaker.espressif.com/prod". Trailing slash is normalised.
+     */
+    userApiBase: string;
+}
+/**
+ * Base API manager: plain HTTP calls with no signing.
+ * Use for unauthenticated endpoints (e.g. token/refresh) and endpoints that
+ * carry a Cognito bearer token in the `Authorization` header.
+ * ESPSigV4APIManager extends this and adds SigV4 for authenticated calls.
+ */
+export declare class ESPRMNeoAPIManager {
+    /**
+     * `protected` (not `private`) so `ESPSigV4APIManager` can `extends` this
+     * class and call `super()`. External construction is blocked by the class
+     * itself not being publicly exported from `services/export.ts`.
+     */
+    protected constructor();
+    /**
+     * Friend-access hook used only by {@link initializeAPIManager} in this
+     * module.
+     *
+     * @internal
+     */
+    static _construct(): ESPRMNeoAPIManager;
+    /**
+     * Returns the singleton constructed by SDK bootstrap.
+     *
+     * @throws {Error} If the SDK has not been configured.
+     */
+    static getInstance(): ESPRMNeoAPIManager;
+    /**
+     * POST to the User API base with no authentication (e.g. token/refresh).
+     * Overridden by subclasses that need signing.
+     */
+    postUserApi<T>(path: string, data?: unknown): Promise<T>;
+    /**
+     * POST to the User API base with a Cognito Bearer token
+     * (`CognitoAuthorizer` / `cognito_user_pools`).
+     */
+    postUserApiWithBearer<T>(path: string, data: unknown, bearerToken: string): Promise<T>;
+    /**
+     * PUT to the User API base with a Cognito Bearer token.
+     */
+    putUserApiWithBearer<T>(path: string, data: unknown, bearerToken: string): Promise<T>;
+    /**
+     * GET from the User API base with a Cognito Bearer token.
+     */
+    getUserApiWithBearer<T>(path: string, bearerToken: string): Promise<T>;
+    /** Orchestrates fetch + parse for User API calls. */
+    protected request<T>(method: string, path: string, headers: Record<string, string>, data?: unknown): Promise<T>;
+    /** DRY: JSON headers with optional Bearer token. */
+    private jsonHeaders;
+    /** SRP: Builds full User API URL from path. */
+    private buildApiUrl;
+    /** SRP: Pure fetch only — returns raw Response. */
+    private sendRequest;
+    /** SRP: Parses Response to JSON and throws on HTTP error. */
+    private parseJsonResponse;
+    /** SRP: Handles network errors (rethrows API errors with status). */
+    private handleRequestError;
+}
+/**
+ * SDK bootstrap hook. Called by {@link ESPRMNeoBase.configure}. Caches the
+ * User API base and constructs the singleton. Not re-exported through the
+ * public SDK barrel.
+ *
+ * @internal
+ * @throws {Error} If already initialized.
+ */
+export declare function initializeAPIManager(init: ESPRMNeoAPIManagerInit): void;
+/**
+ * Test-only hook to reset the singleton and cached base URL between test
+ * cases. Not re-exported.
+ *
+ * @internal
+ */
+export declare function _resetAPIManagerForTests(): void;

package/dist/types/services/ESPRMNeoHelpers/BinaryWriter.d.ts

@@ -0,0 +1,5 @@
+export declare class BinaryWriter {
+    private buffer;
+    write(bytes: Uint8Array): void;
+    bytes(): Uint8Array;
+}

package/dist/types/services/ESPRMNeoHelpers/ChallengeResponseHelper.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Response from parsing device challenge-response.
+ */
+export interface DeviceChallengeResponse {
+    success: boolean;
+    nodeId?: string;
+    signedChallenge?: string;
+    error?: string;
+}
+/**
+ * Challenge-response helper for ESP RainMaker provisioning flow.
+ * Handles protobuf creation, device communication, and response parsing.
+ */
+export declare class ChallengeResponseHelper {
+    /**
+     * Creates a challenge request payload using the esp_rmaker_chal_resp proto.
+     */
+    static createChallengeRequest(challenge: string): Uint8Array;
+    /**
+     * Parses the device response from challenge-response protocol.
+     */
+    static parseDeviceResponse(responseData: Uint8Array): DeviceChallengeResponse;
+    /**
+     * Validates challenge response format (success, nodeId, signedChallenge as hex).
+     */
+    static validateChallengeResponse(response: DeviceChallengeResponse): boolean;
+    /**
+     * Returns true when device version info advertises challenge-response (`ch_resp`).
+     */
+    static checkChallengeResponseCapability(versionInfo: {
+        [key: string]: unknown;
+    }): boolean;
+}

package/dist/types/services/ESPRMNeoHelpers/ChannelRegistration.d.ts

@@ -0,0 +1,14 @@
+import { ESPRMNeoSubscriptionManager } from "../ESPRMNeoSubscriptionManager";
+/**
+ * Registers the MQTT subscription channel with the manager (idempotent) and,
+ * if no global order has been set yet, makes MQTT the default channel.
+ *
+ * This runs **synchronously** on purpose: `registerChannel` adds the channel to
+ * the manager's map before its first `await`, so by the time this function sets
+ * the global order the channel is already present. Doing it synchronously avoids
+ * the order-clobber race that consumer apps had to defend against (where an
+ * async registration reset the channel order after the app had configured it).
+ *
+ * @param manager - The subscription manager to register the MQTT channel on.
+ */
+export declare function registerMqttChannelIfNeeded(manager: ESPRMNeoSubscriptionManager): void;

package/dist/types/services/ESPRMNeoHelpers/CheckTokenExpiry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Checks if the given token has expired.
+ *
+ * @param token - The token to check.
+ * @returns True if the token has expired, false otherwise.
+ */
+declare const isTokenExpired: (token: string) => boolean;
+export { isTokenExpired };

package/dist/types/services/ESPRMNeoHelpers/ClaimingHelper.d.ts

@@ -0,0 +1,141 @@
+import { ClaimCapabilities } from "../../utils/constants";
+/**
+ * Request body for `POST /v1/claim/initiate`. The device's own claim-start fields
+ * are forwarded alongside `mac_addr`.
+ */
+export interface ClaimInitiateRequest extends Record<string, unknown> {
+    /** Device MAC, 12 or 16 hex characters, separators stripped. */
+    mac_addr: string;
+}
+/** Response body from `POST /v1/claim/initiate`. */
+export interface ClaimInitiateResponse {
+    /** 16 uppercase hex characters. Also the IoT Thing name and MQTT client id. */
+    node_id: string;
+    /** Present only under the `device_attested` variant; not yet implemented. */
+    challenge?: string;
+}
+/**
+ * The device's own claim payload, forwarded whole to verify. Firmware sends
+ * request flags alongside the CSR, so extracting only `csr` would drop them.
+ */
+export interface ClaimDevicePayload extends Record<string, unknown> {
+    /** PEM `CERTIFICATE REQUEST` generated by the device. */
+    csr: string;
+}
+/** Request body for `POST /v1/claim/verify`. */
+export interface ClaimVerifyRequest extends Record<string, unknown> {
+    /** Same device MAC as initiate; selects the reservation to resolve. */
+    mac_addr: string;
+    /** PEM `CERTIFICATE REQUEST`, ECDSA P-256, max 8 KB. */
+    csr: string;
+    /** Extra IoT policies to attach, e.g. `s3`, `kvs`, `bridge`. */
+    capabilities?: string[];
+}
+/** Response body from `POST /v1/claim/verify`. */
+export interface ClaimVerifyResponse {
+    node_id: string;
+    /** Device leaf certificate. Only the claiming service can issue this. */
+    certificate: string;
+    /**
+     * Broker host for the device. Optional by design — the claiming service omits
+     * it because the app already knows the deployment's broker, so the SDK fills it
+     * in from `iotEndpoint` before forwarding the payload to the device.
+     */
+    mqtt_host?: string;
+    /** Issuing CA, for the device's trust store. */
+    ca_certificate?: string;
+    /** Credentials-provider endpoint. Forwarded, but the firmware ignores it. */
+    mqtt_cred_host?: string;
+}
+/**
+ * Assisted-claiming cloud calls.
+ *
+ * Both routes live on the deployment's main API and are IAM-authorized like their
+ * neighbours, so they go through {@link ESPSigV4APIManager} and are SigV4-signed
+ * against `baseUrl`. A Cognito JWT is rejected there with
+ * `403 Invalid key=value pair (missing equal-sign) in Authorization header`.
+ *
+ * Both calls are independently retryable: initiate is idempotent per device and
+ * caller, and verify replaces the device's certificate rather than duplicating
+ * the node.
+ */
+export declare class ClaimingHelper {
+    /**
+     * Normalizes a device MAC: separators stripped and upper-cased, so every
+     * spelling of one address resolves to the same reservation.
+     *
+     * @param raw - MAC as reported by the device
+     * @returns Normalized MAC
+     * @throws ESPClaimError when the value is not 12 or 16 hex characters
+     */
+    static normalizeMacAddress(raw: string): string;
+    /**
+     * Reduces a broker endpoint to the bare host the device stores. The device
+     * keeps host and port separately, so a scheme, path or `:port` would be
+     * persisted verbatim into the factory partition and fail to resolve.
+     *
+     * @param raw - Broker endpoint in any form
+     * @returns Host only, or "" when nothing usable remains
+     */
+    static normalizeMqttHost(raw: string): string;
+    /**
+     * Issues a SigV4-signed claiming POST. Signing, credential refresh and retry
+     * come from {@link ESPSigV4APIManager}, which also attaches a failed call's
+     * `{ message }` body to the thrown error as `responseData`.
+     *
+     * @param path - Claiming path, e.g. `/v1/claim/initiate`
+     * @param body - JSON request body
+     * @param claimId - Correlation id for this claim attempt
+     * @returns Parsed JSON response
+     * @throws ESPClaimError when the SDK is unconfigured or the call fails
+     */
+    private static postClaim;
+    /**
+     * Assigns a node ID to the device's MAC address.
+     *
+     * `POST /v1/claim/initiate` — 201 for a new reservation, 200 when one already
+     * existed, returning the same node ID either way. That idempotency is what lets
+     * a factory-erased device come back as the same node.
+     *
+     * @param macAddress - Device MAC, normalized before sending
+     * @param devicePayload - The device's claim-start payload, forwarded whole
+     * @param claimId - Correlation id for this claim attempt
+     * @returns The assigned node ID and any attestation challenge
+     * @throws ESPClaimError when the MAC is invalid or the call fails
+     */
+    static initiateClaim(macAddress: string, devicePayload?: Record<string, unknown>, claimId?: string): Promise<ClaimInitiateResponse>;
+    /**
+     * Exchanges the device's CSR for a signed certificate.
+     *
+     * `POST /v1/claim/verify` — the CSR's subject is ignored; the certificate's
+     * Common Name comes from the reservation. Called again after a factory erase, it
+     * issues a new certificate and deactivates the previous one, node ID unchanged.
+     *
+     * @param macAddress - Same device MAC as initiate
+     * @param devicePayload - The device's claim payload, forwarded whole
+     * @param claimCapability - Optional capability, mapped to extra IoT policies
+     * @param claimId - Correlation id for this claim attempt
+     * @returns The claim response, with `mqtt_host` resolved for the device
+     * @throws ESPClaimError when the call fails or no certificate is returned
+     */
+    static verifyClaim(macAddress: string, devicePayload: ClaimDevicePayload, claimCapability?: ClaimCapabilities, claimId?: string): Promise<ClaimVerifyResponse>;
+    /**
+     * Resolves the broker host to hand the device, normalized to a bare host.
+     *
+     * The app owns this value: the claiming service omits it because the app
+     * already learned the deployment's broker from its config, so the configured
+     * `iotEndpoint` is the normal source and is correct by construction — it is the
+     * broker of the deployment that just issued this certificate. A `mqtt_host` in
+     * the response still wins if one is ever sent.
+     *
+     * Resolved before streaming because the device validates the reassembled
+     * payload only on its final fragment: an absent host surfaces there as a
+     * rejected certificate fragment, with nothing pointing at MQTT.
+     *
+     * @param response - Parsed claim/verify response
+     * @param claimId - Correlation id for this claim attempt
+     * @returns Bare broker host
+     * @throws ESPClaimError when neither source yields a usable host
+     */
+    private static resolveDeviceMqttHost;
+}