Skip to main content

Manage groups

Creating groups and subgroups, renaming and deleting them, and moving nodes between them. These are the lifecycle and membership methods on ESPRMNeoUser and ESPRMNeoGroup; access for other users is covered in Sharing.

Create​

const home = await user.createGroup("Home");
const livingRoom = await home.createSubGroup("Living Room");

user.createGroup(groupName) returns Promise<ESPRMNeoGroup>, a new root group owned by the caller.

group.createSubGroup(name) returns Promise<ESPRMNeoGroup>, a child with parentId set to this group's ID. Subgroups nest under a root group, which is the usual home-and-rooms shape.

Read​

const groups = await user.getGroups();
const nodes = await home.getNodes();
const node = await home.getNode("<node-id>");

user.getGroups() returns the root groups with their subgroups populated.

group.getNodes(options?) returns Promise<ESPRMNeoNode[]>, and group.getNode(nodeId, options?) returns a single Promise<ESPRMNeoNode>. Both take a cache option that defaults to true:

  • cache: true reads each node's configuration from local storage when present
  • cache: false always fetches from the cloud and refreshes local storage

getNodes() forwards its options to each getNode() call, so a list of twenty nodes with cache: false is twenty cloud fetches. Prefer the default for list screens and force a refresh only where the user asked for one.

getNode() throws ESPAPICallValidationError when no configuration can be resolved from either source.

Rename​

await home.updateName("Beach House");

updateName(newName) returns Promise<ESPAPIResponse>. It works on both root groups and subgroups, addressing whichever this instance is.

The call does not mutate groupName on the instance you are holding; re-read the group if your UI renders from it.

Add and remove nodes​

await livingRoom.addNode("<node-id>");
await livingRoom.removeNode("<node-id>");

addNode(nodeId) returns Promise<ESPAPIResponse> and is subgroup-only; it throws ESPAPICallValidationError on a root group, and also when the node is already present. A node enters a root group by being provisioned into it.

removeNode(nodeId) returns Promise<ESPAPIResponse> and means different things by level:

Called onEffect
Root groupFull disassociation from the account
SubgroupRemoved from that subgroup only

Removing a node from a root group is the same disassociation node.delete() performs. Removing it from a subgroup leaves it in the root group, still owned and still controllable.

Delete​

await livingRoom.delete();

delete() returns Promise<ESPAPIResponse> and addresses the group or subgroup this instance represents.

The instance is stale after a delete

Discard the object and drop it from your caches. For a subgroup, also remove it from its parent's subgroups array; the SDK cannot reach the parent from the child, so nothing does that for you.

Leave​

await home.leave();

leave() returns Promise<ESPAPIResponse> and removes the calling user from the group or subgroup. Use it rather than removeMember() with your own user ID, which is rejected.

The last remaining primary user cannot leave (a group must always keep at least one owner) so this fails for a sole owner. Transfer ownership by sharing with accessType: "primary" first; see Sharing.

Method summary​

MethodReturns
user.createGroup(groupName)ESPRMNeoGroup
group.createSubGroup(name)ESPRMNeoGroup
group.getNodes(options?)ESPRMNeoNode[]
group.getNode(nodeId, options?)ESPRMNeoNode
group.updateName(newName)ESPAPIResponse
group.addNode(nodeId)ESPAPIResponse
group.removeNode(nodeId)ESPAPIResponse
group.delete()ESPAPIResponse
group.leave()ESPAPIResponse