Skip to main content

ESPCDFUser

ESPCDFUser represents the authenticated user in CDF. It is the entry point for all user-level operations: profile management, group and node data fetching, device provisioning, and logout.

The entity is set automatically when userStore.auth.login succeeds or userStore.restoreSession finds an existing session. UI code obtains it from userStore.user; it should never be constructed directly.

Most mutating methods use runAndEmit — synchronizers receive the operation result and apply any observable store updates automatically. A small set of helpers are pass-throughs to operations without emitting (noted where relevant).

Properties​

PropertyTypeDescription
identifierstringAdaptor that constructed this entity
userInfoESPCDFUserInfoProfile fields for UI
customDataRecord<string, any> | undefinedOptional custom bag from cloud
operationsESPCDFUserOperationSDK-facing function object (not deeply observed)
_rawanyOriginal SDK user; adaptor layer only
eventsESPCDFOperationEventEmitter<ESPCDFUser, ESPCDFUserOperationType>Operation lifecycle for synchronizers
__storeCallbacksGroupStoreCallbacks | undefinedInternal bridge into stores (set by store layer)

Common Workflows​

Access the current user​

import { initCDF } from "@espressif/rainmaker-base-cdf";

const espCDF = await initCDF({ sdkAdaptorRegistry });
const user = espCDF.userStore.user;

if (!user) {
  // Not signed in — show login screen
}

Fetch and update profile​

const user = espCDF.userStore.user!;

// Read profile
const info = await user.getUserInfo();
console.log(info.name, info.email);

// Update display name
await user.updateName("Alex Smith");

// Update profile fields
await user.updateUserInfo({ name: "Alex", phone: "+1..." });

// Change password
await user.changePassword(oldPassword, newPassword);

// Set timezone
await user.setTimeZone("America/New_York");

Read and write custom data​

const data = await user.getCustomData();
await user.setCustomData({ theme: "dark", region: "EU" });

Fetch groups and nodes​

Groups are the entry point for the device hierarchy. After getGroups, GroupStore is populated automatically via UserStoreSynchronizer.

const user = espCDF.userStore.user!;

// Populates GroupStore
await user.getGroups();

// Create a new group
const group = await user.createGroup({ name: "Kitchen", type: "room" } as any);

// Load a single node by ID
const node = await user.getNodeDetails("node-id-uuid");

Batch set params across nodes​

await user.setMultipleNodesParams([
  { nodeId: "n1", payload: { Power: true } },
  { nodeId: "n2", payload: { Brightness: 80 } },
]);

Group sharing requests​

// Issued requests (requests this user sent)
const issued = await user.getIssuedGroupSharingRequests(20);

// Received requests (invitations waiting for action)
const received = await user.getReceivedGroupSharingRequests(20);

Sign out​

logout ends the session and emits "logout" so UserStoreSynchronizer clears all stores.

try {
  await user.logout();
} catch (e) {
  console.error("Logout failed", e);
}

Account deletion​

// Step 1 — request a deletion verification code
await user.requestAccountDeletion();

// Step 2 — confirm with the code received
await user.confirmAccountDeletion(verificationCode);

Error Handling​

All runAndEmit methods re-throw on failure so the caller can handle the error, while still emitting the failure event so synchronizers can log without applying partial state:

try {
  await user.getUserInfo();
} catch (e) {
  // Handle error in UI — no partial store update will occur
  showErrorBanner("Failed to load profile");
}

Provisioning and device discovery​

Device search and provisioning are pass-throughs that rely on the active adaptor's native transport (BLE / SoftAP):

// Discover nearby BLE devices
const list = await user.searchESPDevices("ESP_", "ble");
const bleList = await user.searchESPBLEDevices(customerId);

// Create a provisioning handle
const provDevice = await user.createProvisioningDevice(
  "My device",
  "ble",
);

See ESPCDFProvisioningDevice for provisioning flows.

Home orchestration helpers​

// Populate GroupStore and select the primary home in one call
// Requires adaptor operations + GroupStoreCallbacks wired by UserStore
await user.syncHomeWithNodes();

await user.setCurrentHome(homeGroup);

const newHome = await user.createHome({ name: "Beach House", nodeIds: [] } as any);

const node = await user.addDevice({ /* AddDeviceParams */ } as any);

Real-time node update subscription​

Typically called internally by UserStoreSynchronizer after login. For custom subscription handling:

await user.subscribeToNodeUpdates({ /* ESPCDFSubscribeToNodeUpdatesRequestParams */ } as any);
await user.unsubscribeFromNodeUpdates();

Matter helpers​

Available when the Matter adaptor is active:

const fabrics = await user.getGroupsAndFabrics();
const updated = await user.prepareFabricForMatterCommissioning(fabricGroup);

const ok = await user.isUserNocAvailableForFabric(fabricId);
await user.storePrecommissionInfo({ /* ESPCDFMatterPrecommissionInfo */ } as any);

On this page