@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/types/types/tsData.d.ts

@@ -0,0 +1,222 @@
+/**
+ * ESP RainMaker Neo time-series type definitions.
+ *
+ * Public (camelCase) types used by the node-level (`getCustomParam*TSData`)
+ * and param-level (`get*TSData`) method APIs, plus the raw (snake_case)
+ * response shapes of the backend timeseries endpoints.
+ */
+/**
+ * Aggregation windows supported by the timeseries aggregates API.
+ */
+export type ESPRMNeoTSAggregationWindow = "hourly" | "daily" | "weekly" | "monthly";
+/**
+ * Options for time-series data queries.
+ *
+ * Raw queries (`getRawTSData`): `startTs` is required (Unix ms; seconds are
+ * also accepted by the backend), `endTs` defaults to now.
+ * Aggregate queries (`getTSData`): `window` is required. Provide either no
+ * date (current live window), `date` (single completed window), or
+ * `startDate` + `endDate` (paginated range of completed windows).
+ */
+export interface ESPRMNeoTSDataOptions {
+    /** Range start, Unix timestamp in milliseconds (raw queries; required). */
+    startTs?: number;
+    /** Range end, Unix timestamp in milliseconds (raw queries; defaults to now). */
+    endTs?: number;
+    /** Aggregation window (aggregate queries; required). */
+    window?: ESPRMNeoTSAggregationWindow;
+    /** Single completed window: `YYYY-MM-DD` (or `YYYY-MM-DDTHH` for hourly). */
+    date?: string;
+    /** Range of completed windows: start date `YYYY-MM-DD` (with `endDate`). */
+    startDate?: string;
+    /** Range of completed windows: end date `YYYY-MM-DD` (with `startDate`). */
+    endDate?: string;
+    /** Page size (backend default 20). */
+    pageSize?: number;
+    /** Opaque pagination token from a previous result's `nextKey`. */
+    startKey?: string;
+    /** Overrides the param's `data_type` sent to the backend (rarely needed). */
+    dataType?: string;
+    /**
+     * Overrides the backend param key entirely, skipping the node-config
+     * lookup. Required for data models the config lookup cannot resolve —
+     * e.g. Matter attributes, whose key is `"0x<ep>.0x<cluster>.0x<attr>"`
+     * in lowercase, unpadded hex — the exact format the firmware publishes.
+     * Must be paired with `dataType`, since a Matter node config carries no
+     * data types.
+     */
+    key?: string;
+}
+/**
+ * A single time-series data point.
+ */
+export interface ESPRMNeoTSDataPoint {
+    /** Unix timestamp in milliseconds. */
+    timestamp: number;
+    /** Reported param value; its type matches `dataType`. */
+    value: unknown;
+    /** Backend data type of the value (`bool` | `int` | `float` | `string`). */
+    dataType?: string;
+    /** IANA timezone reported by the device for this point. */
+    timezone?: string;
+    /** True when the param is cumulative (e.g. an energy meter reading). */
+    cumulative?: boolean;
+}
+/**
+ * Statistics of one aggregation window.
+ * For cumulative params, use `cumulativeValue` (consumption within the
+ * window) rather than `sum`.
+ */
+export interface ESPRMNeoTSWindowAggregate {
+    /** Number of samples in the window. */
+    count?: number;
+    /** Sum of the sample values. */
+    sum?: number;
+    /** Minimum sample value in the window. */
+    min?: number;
+    /** Maximum sample value in the window. */
+    max?: number;
+    /** Average of the sample values. */
+    average?: number;
+    /** First sample value in the window. */
+    firstValue?: number;
+    /** Last sample value in the window. */
+    lastValue?: number;
+    /** Consumption within the window (cumulative params only). */
+    cumulativeValue?: number;
+    /** RFC3339 window start. */
+    windowStart?: string;
+    /** RFC3339 window end. */
+    windowEnd?: string;
+    /** `"completed"` for archived historical windows. */
+    status?: string;
+    /** Backend stats not yet modeled here are passed through by the transform. */
+    [key: string]: unknown;
+}
+/**
+ * One aggregate entry (per parameter, per window/date).
+ */
+export interface ESPRMNeoTSAggregateEntry {
+    /** Backend parameter identity, `"<node_id>.<key>.<data_type>"`. */
+    parameter?: string;
+    /** True when the param is cumulative (e.g. an energy meter). */
+    isCumulative?: boolean;
+    /** Window key/date of this entry (historical range results). */
+    date?: string;
+    /** Aggregates keyed by window type. */
+    windows: Partial<Record<ESPRMNeoTSAggregationWindow, ESPRMNeoTSWindowAggregate>>;
+    /** Backend fields not yet modeled here are passed through by the transform. */
+    [key: string]: unknown;
+}
+/**
+ * Time-series data result.
+ * Raw/latest queries populate `data`; aggregate queries populate `aggregates`.
+ */
+export interface ESPRMNeoTSDataResult {
+    /** Data points, newest first (raw/latest queries; empty for aggregates). */
+    data: ESPRMNeoTSDataPoint[];
+    /** Aggregate entries (aggregate queries only). */
+    aggregates?: ESPRMNeoTSAggregateEntry[];
+    /** Pass back as `startKey` to fetch the next page; absent on the last page. */
+    nextKey?: string;
+    /** Number of items in this page, as reported by the backend. */
+    pageTotal?: number;
+    /** True when more pages exist (see {@link ESPRMNeoTSDataResult.fetchNext}). */
+    hasNext?: boolean;
+    /** Resolves the next page with the same query; set only when `hasNext`. */
+    fetchNext?: () => Promise<ESPRMNeoTSDataResult>;
+}
+/**
+ * Raw API time-series sample (snake_case). The backend emits `key`; older
+ * swagger examples show `name` — both are tolerated.
+ */
+export interface ESPRMNeoTSDataPointAPI {
+    /** Backend param key, `"<device_id>.<param_id>"`. */
+    key?: string;
+    /** Legacy alias of `key` (older swagger examples). */
+    name?: string;
+    /** Backend data type of `value` (`bool` | `int` | `float` | `string`). */
+    dt?: string;
+    /** Unix timestamp in milliseconds. */
+    ts: number;
+    /** Reported param value; its type matches `dt`. */
+    value: unknown;
+    /** IANA timezone reported by the device for this sample. */
+    tz?: string;
+    /** True when the param is cumulative (e.g. an energy meter reading). */
+    cumulative?: boolean;
+}
+/**
+ * Raw API response of GET .../timeseries/raw (snake_case).
+ */
+export interface ESPRMNeoTSRawDataResponseAPI {
+    /** Samples, newest first. */
+    data?: ESPRMNeoTSDataPointAPI[];
+    /** Number of items in this page. */
+    page_total?: number;
+    /** Pagination token for the next page; absent on the last page. */
+    next_key?: string;
+}
+/**
+ * Raw API response of GET .../timeseries/latest (snake_case).
+ * Note: `data` is a single object, not an array.
+ */
+export interface ESPRMNeoTSLatestDataResponseAPI {
+    /** Most recent sample; absent when the param has no data yet. */
+    data?: ESPRMNeoTSDataPointAPI;
+}
+/**
+ * Raw API window aggregate (snake_case).
+ */
+export interface ESPRMNeoTSWindowAggregateAPI {
+    /** Number of samples in the window. */
+    count?: number;
+    /** Sum of the sample values. */
+    sum?: number;
+    /** Minimum sample value in the window. */
+    min?: number;
+    /** Maximum sample value in the window. */
+    max?: number;
+    /** Average of the sample values. */
+    average?: number;
+    /** First sample value in the window. */
+    first_value?: number;
+    /** Last sample value in the window. */
+    last_value?: number;
+    /** Consumption within the window (cumulative params only). */
+    cumulative_value?: number;
+    /** RFC3339 window start. */
+    window_start?: string;
+    /** RFC3339 window end. */
+    window_end?: string;
+    /** `"completed"` for archived historical windows. */
+    status?: string;
+    /** Lets the transform's rest-spread carry unmodeled backend stats through. */
+    [key: string]: unknown;
+}
+/**
+ * Raw API aggregate entry (snake_case).
+ */
+export interface ESPRMNeoTSAggregateEntryAPI {
+    /** Backend parameter identity, `"<node_id>.<key>.<data_type>"`. */
+    parameter?: string;
+    /** True when the param is cumulative (e.g. an energy meter). */
+    is_cumulative?: boolean;
+    /** Window key/date of this entry (historical range results). */
+    date?: string;
+    /** Aggregates keyed by window type. */
+    windows?: Record<string, ESPRMNeoTSWindowAggregateAPI>;
+    /** Lets the transform's rest-spread carry unmodeled backend fields through. */
+    [key: string]: unknown;
+}
+/**
+ * Raw API response of GET .../timeseries/aggregates (snake_case).
+ */
+export interface ESPRMNeoTSAggregatesResponseAPI {
+    /** One entry per parameter, per window/date. */
+    aggregates?: ESPRMNeoTSAggregateEntryAPI[];
+    /** Number of items in this page. */
+    page_total?: number;
+    /** Pagination token for the next page; absent on the last page. */
+    next_key?: string;
+}

package/dist/types/utils/authUtils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns true when `username` looks like an E.164 phone number (leading `+`).
+ * Used by sign-up / confirm flows to choose `phone_number` vs `email`.
+ */
+export declare function isPhoneUsername(username: string): boolean;
+/**
+ * Maps a username to the signup/verify identity fields expected by the User API.
+ *
+ * Phone usernames (leading `+`) become `phone_number`; everything else becomes `email`.
+ */
+export declare function signupIdentityFromUsername(username: string): {
+    email?: string;
+    phone_number?: string;
+};

package/dist/types/utils/awsShadowTopics.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Builds the base shadow topic path for a node.
+ *
+ * @param nodeId - The device/node identifier
+ * @param shadowName - The named shadow (e.g. params-groupId-subgroupId)
+ * @returns Topic path: $aws/things/{nodeId}/shadow/name/{shadowName}
+ */
+export declare function buildShadowBase(nodeId: string, shadowName: string): string;
+/**
+ * Builds all wildcard topics for a named shadow (any thing / node id).
+ */
+export declare function buildShadowGroupWildcardTopics(shadowName: string): string[];
+/**
+ * RainMaker user params channel (publish / optional subscribe).
+ * @see rainmaker/nodes/{nodeId}/user/{shadowName}/params
+ */
+export declare function buildRainMakerUserParamsTopic(nodeId: string, shadowName: string): string;
+/**
+ * RainMaker **group control** topic (multicast to all nodes in a group or subgroup).
+ *
+ * - Broadcast (all devices in the group):
+ *   `rainmaker/nodes/groups/<groupId>/control`
+ * - Single subgroup:
+ *   `rainmaker/nodes/groups/<groupId>/subgroups/<subgroupId>/control`
+ *
+ * @param groupId - Primary group id (`pgrp`)
+ * @param subgroupId - Optional subgroup id; when set, targets that subgroup only
+ */
+export declare function buildGroupControlParamsTopic(groupId: string, subgroupId?: string): string;
+/**
+ * Extracts device params from a shadow GET/accepted document.
+ * Prefers `state.reported.params` when present; otherwise `state.reported`.
+ * Always returns an object (`{}` when absent / non-object).
+ */
+export declare function getReportedParamsFromShadowDocument(parsed: unknown): Record<string, unknown>;
+/**
+ * Normalizes a live shadow MQTT payload for param listeners.
+ *
+ * - `/update/documents`: returns `current` (full shadow doc with previous+current
+ *   envelope unwrapped so callers see the usual `{ state, metadata, version }` shape).
+ * - Other topics: returns the parsed payload as received.
+ * Always returns an object (`{}` when absent / non-object).
+ */
+export declare function getReportedParamsFromShadowLiveMessage<T extends Record<string, unknown> = Record<string, unknown>>(topic: string, parsed: unknown): T;
+/**
+ * Extracts the nodeId from an AWS IoT shadow topic.
+ * Topic format: $aws/things/NODE_ID/shadow/name/SHADOW_NAME/...
+ *
+ * @param topic - The MQTT topic string
+ * @returns The nodeId, or null if topic format is invalid
+ */
+export declare function extractNodeIdFromTopic(topic: string): string | null;
+/**
+ * Safely parses a shadow message buffer to JSON.
+ *
+ * @param message - Raw MQTT payload buffer
+ * @returns Parsed shadow document, or null on parse error
+ */
+export declare function parseShadowMessage(message: Buffer): {
+    state?: {
+        reported?: unknown;
+        desired?: unknown;
+    };
+} | null;
+/**
+ * Extracts the full state object from a parsed shadow payload.
+ *
+ * @param parsed - Parsed shadow document (or null)
+ * @returns The state object (reported + desired), or `{}` when absent / non-object
+ */
+export declare function getStateFromPayload<T extends Record<string, unknown> = Record<string, unknown>>(parsed: unknown): T;
+/**
+ * Builds the JSON payload for a shadow update (desired state).
+ *
+ * @param desiredParams - The desired state parameters to set
+ * @returns JSON string for MQTT publish
+ */
+export declare function buildShadowUpdatePayload(desiredParams: unknown): string;

package/dist/types/utils/awsSigv4Utils.d.ts

@@ -0,0 +1,53 @@
+export interface GenerateSigV4AuthHeaderParams {
+    accessKey: string;
+    secretKey: string;
+    timestamp: string;
+    dateStamp: string;
+    region: string;
+    service: string;
+    method: string;
+    canonicalURI: string;
+    canonicalQueryString: string;
+    requestHeaders: Record<string, string>;
+    signedHeaders: string;
+    payloadHash: string;
+}
+/**
+ * Generates the full AWS SigV4 Authorization header for HTTP requests.
+ * Consolidates canonical request, string-to-sign, signature calculation, and header building.
+ */
+export declare function generateSigV4AuthHeader(params: GenerateSigV4AuthHeaderParams): string;
+/**
+ * Builds the AWS Signature Version 4 Authorization header value for HTTP requests.
+ */
+export declare function createAuthorizationHeader(accessKey: string, dateStamp: string, regionName: string, serviceName: string, signature: string, signedHeaders: string): string;
+/** Parameters for AWS IoT Core MQTT-over-WebSocket presigned URL (SigV4, service `iotdevicegateway`). */
+export interface IotDeviceGatewayMqttSignedUrlParams {
+    accessKey: string;
+    secretKey: string;
+    sessionToken?: string;
+    /** IoT endpoint hostname only, e.g. `xxxx-ats.iot.ap-south-1.amazonaws.com` */
+    host: string;
+    awsRegion: string;
+    /** Presigned URL lifetime in seconds. Default 86400 (24h). */
+    expiresSeconds?: number;
+    /** MQTT WebSocket path; default `/mqtt`. */
+    canonicalUri?: string;
+}
+/**
+ * Builds the SigV4 canonical query string from parsed query parameters: each
+ * name and value URI-encoded (RFC 3986, including `!'()*`), pairs sorted by
+ * encoded name then encoded value (code-point order, per the SigV4 spec).
+ *
+ * API Gateway canonicalizes the incoming query string this way before
+ * verifying the signature, so signing the raw (unsorted) query string breaks
+ * every request whose parameters are not already in sorted order.
+ */
+export declare function buildCanonicalQueryString(searchParams: URLSearchParams): string;
+/**
+ * Builds a presigned `wss://` URL for AWS IoT Core MQTT over WebSocket using
+ * query-string SigV4 (service `iotdevicegateway`, signed headers: `host`).
+ *
+ * Same signing flow as HTTP SigV4 in this module (`calculateSignature`, canonical request layout).
+ */
+export declare function generateIotDeviceGatewayMqttSignedUrl(params: IotDeviceGatewayMqttSignedUrlParams): string;

package/dist/types/utils/awsUtils.d.ts

@@ -0,0 +1,48 @@
+import { ESPAWSCredentials } from "../types/input";
+/** Wire-format response from POST /v1/user/credentials. */
+export type TemporaryCredentialsApiResponse = {
+    access_key_id?: string;
+    secret_access_key?: string;
+    session_token?: string;
+    expiration?: number;
+    message?: string;
+    error?: string;
+};
+/**
+ * Builds a full URL on the main RainMaker API gateway (not the User API).
+ * /v1/user/credentials uses CognitoAuthorizer but lives on the main API.
+ */
+export declare function buildMainApiUrl(path: string): string;
+/** URL for POST /v1/user/credentials. */
+export declare function buildUserCredentialsUrl(): string;
+/**
+ * Extends the Cognito session using the stored refresh token.
+ * @throws {ESPTokenError} When no refresh token is stored.
+ */
+export declare function refreshUserSession(): Promise<void>;
+/**
+ * Ensures a non-expired ID token is available before calling the credentials API.
+ * Refreshes the session when the stored ID token is expired or undecodable.
+ * @throws {ESPTokenError} When the ID token is missing or session refresh fails.
+ */
+export declare function ensureValidIdToken(): Promise<void>;
+/**
+ * Best-effort error string from a credentials API response.
+ */
+export declare function parseCredentialsErrorMessage(response: Response, data: TemporaryCredentialsApiResponse | null, responseText: string): string;
+/** True when the credentials API rejected the request due to an expired token. */
+export declare function isExpiredTokenAuthError(status: number, message: string): boolean;
+/**
+ * Maps a credentials API payload to {@link ESPAWSCredentials}.
+ * @throws {Error} When required credential fields are missing.
+ */
+export declare function extractTemporaryCredentials(data: TemporaryCredentialsApiResponse | null): ESPAWSCredentials;
+/**
+ * POSTs /v1/user/credentials with the access token as Bearer auth and the
+ * ID token in the body. Both must come from the same sign-in.
+ */
+export declare function postUserCredentials(url: string): Promise<{
+    response: Response;
+    data: TemporaryCredentialsApiResponse | null;
+    responseText: string;
+}>;

package/dist/types/utils/baseUtils.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Internal helpers for {@link ESPRMNeoBase} configure / dispose / validation.
+ *
+ * Not part of the public SDK barrel — used only by the base facade so
+ * lifecycle orchestration stays out of the class body.
+ */
+import { ESPRMNeoAuth } from "../ESPRMNeoAuth";
+import { ESPRMNeoBaseConfig } from "../types/input";
+import { ESPStorageAdapter } from "../types/storage";
+import { ESPProvisionAdapterInterface } from "../types/provision";
+import type { ESPLocalControlAdapterInterface } from "../types/localControl";
+import type { ESPLocalDiscoveryAdapterInterface } from "../types/discovery";
+import { ESPRMNeoSubscriptionManager } from "../services/ESPRMNeoSubscriptionManager";
+import { ESPTransportMode } from "../types/transport";
+import { ConfigErrorCodes } from "./constants";
+/**
+ * {@link ConfigErrorCodes} values accepted by {@link assertAdapterProvided}.
+ */
+export type AdapterConfigErrorCode = typeof ConfigErrorCodes.INVALID_STORAGE_ADAPTER | typeof ConfigErrorCodes.INVALID_PROVISION_ADAPTER | typeof ConfigErrorCodes.INVALID_LOCAL_CONTROL_ADAPTER | typeof ConfigErrorCodes.INVALID_LOCAL_DISCOVERY_ADAPTER | typeof ConfigErrorCodes.INVALID_MQTT_ADAPTER;
+/**
+ * Optional adapters taken from {@link ESPRMNeoBaseConfig} at configure time.
+ */
+export interface ESPRMNeoBaseAdapters {
+    /** Custom key/value storage; when omitted, storage uses its default adapter. */
+    storage?: ESPStorageAdapter;
+    /** SoftAP / BLE provisioning implementation supplied by the host app. */
+    provision?: ESPProvisionAdapterInterface;
+    /** LAN `esp_local_ctrl` transport implementation. */
+    localControl?: ESPLocalControlAdapterInterface;
+    /** LAN / mDNS discovery implementation. */
+    localDiscovery?: ESPLocalDiscoveryAdapterInterface;
+}
+/**
+ * Removes a single trailing `/` from a URL or path segment.
+ *
+ * @param url - Absolute URL or path that may end with a slash.
+ * @returns The same string without a trailing slash.
+ */
+export declare function stripTrailingSlash(url: string): string;
+/**
+ * Resolves and normalizes the User/auth API base URL.
+ *
+ * @param config - SDK configuration; `userApiBase` is required.
+ * @returns Normalized User/auth API base (no trailing slash).
+ * @throws {ESPConfigError} With {@link ConfigErrorCodes.INVALID_USER_API_BASE}
+ *   when `userApiBase` is missing or empty.
+ */
+export declare function resolveUserApiBase(config: ESPRMNeoBaseConfig): string;
+/**
+ * Reads optional adapters from config without writing {@link ESPRMNeoBase} statics.
+ * The caller assigns the returned values onto Base fields.
+ *
+ * @param config - SDK configuration from {@link ESPRMNeoBase.configure}.
+ * @returns Adapter bag (any field may be `undefined` if not supplied).
+ */
+export declare function extractAdaptersFromConfig(config: ESPRMNeoBaseConfig): ESPRMNeoBaseAdapters;
+/**
+ * Initializes {@link ESPRMNeoMqtt} and {@link NodeMQTTOrchestrator} when
+ * `config.mqttAdapter` is present. No-op when MQTT is not configured.
+ *
+ * @param config - SDK configuration from {@link ESPRMNeoBase.configure}.
+ * @throws {Error} If MQTT / orchestrator are already initialized (call
+ *   {@link disposePeerSingletons} first).
+ */
+export declare function initializeMqttIfConfigured(config: ESPRMNeoBaseConfig): void;
+/**
+ * Initializes storage, the User API manager, and the SigV4 API manager.
+ *
+ * @param config - SDK configuration (provides `baseUrl`, `awsRegion`, User API base).
+ * @param storageAdapter - Optional custom storage; when omitted, storage uses its default.
+ * @throws {Error} If an API manager is already initialized (call
+ *   {@link disposePeerSingletons} first).
+ */
+export declare function initializeApiStack(config: ESPRMNeoBaseConfig, storageAdapter?: ESPStorageAdapter): void;
+/**
+ * Creates an {@link ESPRMNeoSubscriptionManager} and, when MQTT is configured,
+ * registers the default MQTT channel synchronously.
+ *
+ * @param config - SDK configuration (MQTT presence controls channel registration).
+ * @returns A new subscription manager owned by the caller (typically Base).
+ */
+export declare function createSubscriptionManager(config: ESPRMNeoBaseConfig): ESPRMNeoSubscriptionManager;
+/**
+ * Constructs {@link ESPRMNeoAuth} for the given config.
+ * Call only after config validation; the caller retains ownership.
+ *
+ * @param config - Validated SDK configuration.
+ * @returns A new auth instance for the given config.
+ */
+export declare function createAuthInstance(config: ESPRMNeoBaseConfig): ESPRMNeoAuth;
+/**
+ * Resets peer module singletons (subscription channels, MQTT, API managers,
+ * storage) so {@link ESPRMNeoBase.configure} can run again.
+ *
+ * Does **not** clear {@link ESPRMNeoBase} static fields — the caller must do that.
+ *
+ * @param subscriptionManager - Active manager to dispose, or `null` if none.
+ */
+export declare function disposePeerSingletons(subscriptionManager: ESPRMNeoSubscriptionManager | null): void;
+/**
+ * Returns a fresh copy of {@link DEFAULT_TRANSPORT_ORDER} for Base init / reset.
+ *
+ * @returns New array of default transport modes (safe to mutate).
+ */
+export declare function createDefaultTransportOrder(): (ESPTransportMode | string)[];
+/**
+ * Validates and shallow-copies a transport priority order.
+ *
+ * @param order - Non-empty ordered list of {@link ESPTransportMode} values or custom keys.
+ * @returns A copy of `order`.
+ * @throws {ESPConfigError} With {@link ConfigErrorCodes.INVALID_TRANSPORT_ORDER}
+ *   if `order` is missing, empty, or not an array.
+ */
+export declare function copyTransportOrder(order: (ESPTransportMode | string)[]): (ESPTransportMode | string)[];
+/**
+ * Guards Base getters/setters that require a prior {@link ESPRMNeoBase.configure}.
+ *
+ * @param isInitialized - Whether the relevant Base state is present.
+ * @throws {ESPConfigError} With {@link ConfigErrorCodes.SDK_NOT_CONFIGURED}
+ *   when `isInitialized` is false.
+ */
+export declare function assertSdkInitialized(isInitialized: boolean): void;
+/**
+ * Guards adapter setters: the adapter argument must be a non-falsy value.
+ *
+ * @param adapter - Adapter instance supplied by the app.
+ * @param code - Matching adapter {@link ConfigErrorCodes} entry for the error message.
+ * @throws {ESPConfigError} With `code` when `adapter` is missing or falsy.
+ */
+export declare function assertAdapterProvided(adapter: unknown, code: AdapterConfigErrorCode): asserts adapter;
+/**
+ * Logs which optional pieces of {@link ESPRMNeoBaseConfig} are present (debug).
+ *
+ * @param config - SDK configuration about to be applied.
+ */
+export declare function logConfigSummary(config: ESPRMNeoBaseConfig): void;

package/dist/types/utils/coerce.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Coerces a raw value to a finite number, or `undefined` if it cannot be
+ * parsed (wrong type, NaN, ±Infinity).
+ *
+ * Accepts both `number` and `string` inputs; all other types return `undefined`.
+ */
+export declare function coerceToFiniteNumber(raw: unknown): number | undefined;
+/**
+ * Coerces a raw value to a non-empty string, or `undefined` if the value is
+ * not a string or is an empty string.
+ */
+export declare function coerceToNonEmptyString(raw: unknown): string | undefined;
+/**
+ * Coerces a raw value to a trimmed non-empty string.
+ * - `string` → trimmed; empty after trim → `undefined`
+ * - finite `number` → decimal string (legacy firmware timestamps)
+ * - all other types → `undefined`
+ */
+export declare function coerceToString(raw: unknown): string | undefined;

package/dist/types/utils/common.d.ts

@@ -0,0 +1,15 @@
+/** True if `value` is a member of the given enum. */
+export declare function isEnumValue(value: unknown, enumObj: Record<string, unknown>): boolean;
+/** True if `obj` has no own enumerable keys. */
+export declare function isEmptyObject(obj?: Record<string, unknown>): boolean;
+/**
+ * Coerces `value` to an object. Non-objects become `{}`.
+ */
+export declare function asObject<T extends Record<string, unknown> = Record<string, unknown>>(value: unknown): T;
+/**
+ * Normalizes an optional string or string array into a new `string[]`.
+ * - `string[]` → shallow copy
+ * - non-empty `string` → single-element array
+ * - `undefined` / empty string → `[]`
+ */
+export declare function asStringArray(value?: string | string[]): string[];