Share Groups

This section covers operations to share groups with other users and manage sharing requests. These operations can be performed using either the ESPRMUser instance (for user-level operations) or an ESPRMGroup instance (for group-level operations).

note

To get the user instance, use ESPRMAuth.getLoggedInUser method:

try {
  const authInstance = ESPRMBase.getAuthInstance();
  const userInstance = await authInstance.getLoggedInUser();

  if (userInstance) {
    // Use userInstance for group operations
  } else {
    console.log("No user is currently logged in");
  }
} catch (error) {
  console.error("Error getting logged in user:", error);
}

User-Level Operations

Share Groups

To share one or more groups with another user, use the shareGroups method.

try {
  const shareRequest = {
    username: "target_username",
    groupIds: ["group_id_1", "group_id_2"],
    makePrimary: false,
    metadata: {
      description: "Shared for home automation access",
    },
  };

  const requestId = await userInstance.shareGroups(shareRequest);
  console.log("Group sharing request created:", requestId);
} catch (error) {
  console.error("Error sharing groups:", error);
}

Transfer Groups

To transfer ownership of one or more groups to another user, use the transferGroups method.

try {
  const transferRequest = {
    toUserName: "new_owner@example.com",
    groupIds: ["group_id_1", "group_id_2"],
    selfToSecondary: false,
  };

  const requestId = await userInstance.transferGroups(transferRequest);
  console.log("Group transfer request created:", requestId);
} catch (error) {
  console.error("Error transferring groups:", error);
}

Get Issued Group Sharing Requests

To retrieve group sharing requests that you have issued, use the getIssuedGroupSharingRequests method.

try {
  const response = await userInstance.getIssuedGroupSharingRequests(10);
  console.log("Issued sharing requests:", response.sharedRequests);
  console.log("Has more requests:", response.hasNext);
} catch (error) {
  console.error("Error getting issued sharing requests:", error);
}

Get Received Group Sharing Requests

To retrieve group sharing requests that you have received, use the getReceivedGroupSharingRequests method.

try {
  const response = await userInstance.getReceivedGroupSharingRequests(10);
  console.log("Received sharing requests:", response.sharedRequests);
  console.log("Has more requests:", response.hasNext);
} catch (error) {
  console.error("Error getting received sharing requests:", error);
}

Group-Level Operations

Share Group

To share the current group with another user, use the share method.

try {
  const shareRequest = {
    username: "target_username",
    makePrimary: false,
    metadata: {
      description: "Shared for home automation access",
    },
  };

  const requestId = await group.share(shareRequest);
  console.log("Group sharing request created:", requestId);
} catch (error) {
  console.error("Error sharing group:", error);
}

Transfer Group

To transfer the current group to another user, use the transfer method.

try {
  const transferRequest = {
    toUserName: "new_owner@example.com",
    selfToSecondary: false,
  };

  const requestId = await group.transfer(transferRequest);
  console.log("Group transfer request created:", requestId);
} catch (error) {
  console.error("Error transferring group:", error);
}

Remove Sharing For

To remove sharing permissions for a specified user in the current group, use the removeSharingFor method.

try {
  const username = "target_username";
  const response = await group.removeSharingFor(username);
  console.log("Sharing removed successfully:", response);
} catch (error) {
  console.error("Error removing sharing:", error);
}

Get Sharing Info

To retrieve sharing information for the current group, use the getSharingInfo method.

try {
  const sharingInfo = await group.getSharingInfo({
    groupId: group.id,
    subGroups: true,
    parentGroups: true,
    metadata: true,
  });
  console.log("Sharing information:", sharingInfo);
} catch (error) {
  console.error("Error getting sharing info:", error);
}

Managing Sharing Requests

Group sharing requests can be managed using the ESPGroupSharingRequest class. There are two types of sharing requests:

• Received Requests: Invitations sent to you by other users
• Issued Requests: Invitations you sent to other users

Get Received Group Sharing Requests

Fetch group sharing requests that were sent to you (invitations you received) using the getReceivedGroupSharingRequests method.

try {
  // Get all received sharing requests with optional pagination
  const response = await userInstance.getReceivedGroupSharingRequests();

  console.log("Received requests:", response.sharedRequests);
  console.log("Has more requests:", response.hasNext);
} catch (error) {
  console.error("Error fetching received requests:", error);
}

getReceivedGroupSharingRequests API

Parameter	Type	Required	Description
count	number	No	The number of results to fetch per request. If not provided, the default value is used.

Returns: Promise<ESPGroupSharingResponse> - A promise that resolves to a paginated response containing received group sharing requests.

Get Issued Group Sharing Requests

Fetch group sharing requests that you sent to other users using the getIssuedGroupSharingRequests method.

try {
  // Get all issued sharing requests with optional pagination
  const response = await userInstance.getIssuedGroupSharingRequests();

  console.log("Issued requests:", response.sharedRequests);
  console.log("Has more requests:", response.hasNext);
} catch (error) {
  console.error("Error fetching issued requests:", error);
}

getIssuedGroupSharingRequests API

Parameter	Type	Required	Description
count	number	No	The number of results to fetch per request. If not provided, the default value is used.

Returns: Promise<ESPGroupSharingResponse> - A promise that resolves to a paginated response containing issued group sharing requests.

Accept Sharing Request

Accept a group sharing request that was sent to you using the accept method.

try {
  // Get received sharing requests
  const response = await userInstance.getReceivedGroupSharingRequests();
  const receivedRequests = response.sharedRequests;

  // Find and accept a specific request
  const requestToAccept = receivedRequests.find((req) => req.id === requestId);

  if (requestToAccept) {
    const acceptResponse = await requestToAccept.accept();
    console.log("Sharing request accepted:", acceptResponse);
  }
} catch (error) {
  console.error("Error accepting sharing request:", error);
}

accept API

Returns: Promise<ESPAPIResponse> - A promise that resolves to a success response upon successful acceptance.

info

Users can only accept invites that are shared with them (received requests).

Decline Sharing Request

Decline a group sharing request that was sent to you using the decline method.

try {
  // Get received sharing requests
  const response = await userInstance.getReceivedGroupSharingRequests();
  const receivedRequests = response.sharedRequests;

  // Find and decline a specific request
  const requestToDecline = receivedRequests.find((req) => req.id === requestId);

  if (requestToDecline) {
    const declineResponse = await requestToDecline.decline();
    console.log("Sharing request declined:", declineResponse);
  }
} catch (error) {
  console.error("Error declining sharing request:", error);
}

decline API

Returns: Promise<ESPAPIResponse> - A promise that resolves to a success response upon successful decline.

info

Users can only decline invites that are shared with them (received requests).

Remove Sharing Request

Remove a group sharing request that you previously sent to another user using the remove method. This is used by the sender to cancel a pending sharing request.

try {
  // Get issued sharing requests
  const response = await userInstance.getIssuedGroupSharingRequests();
  const issuedRequests = response.sharedRequests;

  // Find and remove a specific request
  const requestToRemove = issuedRequests.find((req) => req.id === requestId);

  if (requestToRemove) {
    const removeResponse = await requestToRemove.remove();
    console.log("Sharing request removed:", removeResponse);
  }
} catch (error) {
  console.error("Error removing sharing request:", error);
}

remove API

Returns: Promise<ESPAPIResponse> - A promise that resolves to a success response upon successful removal.

info

Users can only remove requests that are shared by them (issued requests).

Example: Complete Sharing Request Workflow

Here's a complete example showing how sharing requests are managed by both the sender and recipient:

// ==================== SENDER SIDE ====================

// Step 1: Sender shares groups
try {
  const shareRequest = {
    username: "recipient@example.com",
    groupIds: ["group_id_1", "group_id_2"],
    makePrimary: false,
    metadata: {
      description: "Sharing home automation groups",
    },
  };

  const requestId = await userInstance.shareGroups(shareRequest);
  console.log("Group sharing request sent with ID:", requestId);
} catch (error) {
  console.error("Error sending sharing request:", error);
}

// Step 2: Sender can view their issued requests
try {
  const response = await userInstance.getIssuedGroupSharingRequests();
  console.log("My issued requests:", response.sharedRequests);

  // Sender can cancel a request before it's accepted
  const requestToCancel = response.sharedRequests.find(
    (req) => req.id === requestId
  );

  if (requestToCancel) {
    await requestToCancel.remove();
    console.log("Sharing request cancelled");
  }
} catch (error) {
  console.error("Error managing issued requests:", error);
}

// ==================== RECIPIENT SIDE ====================

// Step 1: Recipient checks received sharing requests
try {
  const response = await userInstance.getReceivedGroupSharingRequests();
  console.log("Received sharing requests:", response.sharedRequests);

  // Find the specific request
  const incomingRequest = response.sharedRequests.find(
    (req) => req.id === requestId
  );

  if (incomingRequest) {
    console.log("Found sharing request from:", incomingRequest.username);
    console.log("Groups:", incomingRequest.groupnames);
    console.log("Metadata:", incomingRequest.metadata);
  }
} catch (error) {
  console.error("Error fetching received requests:", error);
}

// Step 2: Recipient accepts the sharing request
try {
  const response = await userInstance.getReceivedGroupSharingRequests();
  const incomingRequest = response.sharedRequests.find(
    (req) => req.id === requestId
  );

  if (incomingRequest) {
    const acceptResponse = await incomingRequest.accept();
    console.log("Sharing request accepted:", acceptResponse);

    // The groups are now accessible to the recipient
    console.log("Group access granted");
  }
} catch (error) {
  console.error("Error accepting sharing request:", error);
}

// Alternative: Recipient declines the sharing request
try {
  const response = await userInstance.getReceivedGroupSharingRequests();
  const incomingRequest = response.sharedRequests.find(
    (req) => req.id === requestId
  );

  if (incomingRequest) {
    const declineResponse = await incomingRequest.decline();
    console.log("Sharing request declined:", declineResponse);
  }
} catch (error) {
  console.error("Error declining sharing request:", error);
}

Example: Managing Issued Requests with Pagination

Fetch and manage issued requests with pagination:

try {
  // Get issued requests with pagination (10 per page)
  const response = await userInstance.getIssuedGroupSharingRequests(10);

  console.log(`Has more requests: ${response.hasNext}`);
  console.log(`Showing ${response.sharedRequests.length} requests`);

  // Display all issued requests
  response.sharedRequests.forEach((request, index) => {
    console.log(`${index + 1}. Request to: ${request.username}`);
    console.log(`   Group IDs: ${request.groupIds.join(", ")}`);
    console.log(`   Group Names: ${request.groupnames.join(", ")}`);
    console.log(`   Status: ${request.status}`);
    console.log(`   Transfer: ${request.transfer}`);
  });

  // Remove pending requests that are older than 7 days
  const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;

  for (const request of response.sharedRequests) {
    if (request.status === "pending" && request.timestamp < sevenDaysAgo) {
      await request.remove();
      console.log(`Removed old request to ${request.username}`);
    }
  }

  // Fetch next page if available
  if (response.hasNext && response.fetchNext) {
    const nextResponse = await response.fetchNext();
    console.log(`Fetched ${nextResponse.sharedRequests.length} more requests`);
  }
} catch (error) {
  console.error("Error managing issued requests:", error);
}