Node Sharing

Node sharing allows you to share access to your nodes with other users, enabling collaborative device management.

Overview

Node sharing in RainMaker enables you to:

• Share nodes with other users
• Remove sharing for specific users
• Transfer node ownership to another user

Share Node

Share a node with another user using the shareWith method.

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

  const requestId = await node.shareWith(shareRequest);
  console.log("Node sharing request created:", requestId);
} catch (error) {
  console.error("Error sharing node:", error);
}

ShareWithRequest Interface

The shareWith method requires a ShareWithRequest object with the following properties:

Property	Type	Required	Description
username*	string	Yes	The username of the user to share the node with.
makePrimary	boolean	No	Whether to make the shared user a primary user.
metadata	Record<string, any>	No	Optional metadata associated with the sharing request.

Example: Basic Sharing

try {
  const shareRequest = {
    username: "family_member@example.com",
  };

  const requestId = await node.shareWith(shareRequest);
  console.log("Sharing request created with ID:", requestId);
} catch (error) {
  console.error("Error sharing node:", error);
}

Example: Share with Primary User

try {
  const shareRequest = {
    username: "admin@example.com",
    makePrimary: true,
    metadata: {
      role: "administrator",
      accessLevel: "full",
    },
  };

  const requestId = await node.shareWith(shareRequest);
  console.log("Node shared as primary user:", requestId);
} catch (error) {
  console.error("Error sharing node:", error);
}

Example: Share with Metadata

try {
  const shareRequest = {
    username: "guest@example.com",
    makePrimary: false,
    metadata: {
      purpose: "temporary_access",
      expiryDate: "2024-12-31",
      permissions: ["read", "control"],
    },
  };

  const requestId = await node.shareWith(shareRequest);
  console.log("Node shared with metadata:", requestId);
} catch (error) {
  console.error("Error sharing node:", error);
}

Remove Sharing

Remove sharing of the current node for a specified user using the removeSharingFor method.

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

removeSharingFor API

Parameter	Type	Description
username*	string	The username of the user for whom the sharing is to be removed.

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

Example: Remove Sharing

try {
  const username = "former_user@example.com";
  const response = await node.removeSharingFor(username);

  if (response.status === "success") {
    console.log("Sharing removed successfully for:", username);
  }
} catch (error) {
  console.error("Error removing sharing:", error);
}

Transfer Node

Create a transfer request to transfer the current node to a specified user using the transferNode method. This transfers ownership of the node to another user.

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

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

TransferNodeRequest Interface

The transferNode method requires a TransferNodeRequest object with the following properties:

Property	Type	Required	Description
toUserName*	string	Yes	The username of the user to transfer the node to.
selfToSecondary	boolean	No	Whether to make the current owner a secondary user after transfer.

Returns: Promise<string> - A promise that resolves to a requestId upon successful transfer request creation.

Example: Basic Transfer

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

  const requestId = await node.transferNode(transferRequest);
  console.log("Transfer request created with ID:", requestId);
} catch (error) {
  console.error("Error transferring node:", error);
}

Example: Transfer with Self as Secondary

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

  const requestId = await node.transferNode(transferRequest);
  console.log(
    "Node transfer request created. You will remain as secondary user:",
    requestId
  );
} catch (error) {
  console.error("Error transferring node:", error);
}

Example: Complete Transfer Workflow

try {
  // Step 1: Create transfer request
  const transferRequest = {
    toUserName: "new_owner@example.com",
    selfToSecondary: false,
  };

  const requestId = await node.transferNode(transferRequest);
  console.log("Transfer request created:", requestId);

  // Note: The new owner will need to accept the transfer request
  // After acceptance, ownership will be transferred
} catch (error) {
  console.error("Error in transfer workflow:", error);
}

Managing Sharing Requests

Node sharing requests can be managed using the ESPNodeSharingRequest 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 Node Sharing Requests

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

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

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

getReceivedNodeSharingRequests API

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

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

Get Issued Node Sharing Requests

Fetch node sharing requests that you sent to other users using the getIssuedNodeSharingRequests method.

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

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

getIssuedNodeSharingRequests API

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

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

Accept Sharing Request

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

try {
  // Get received sharing requests
  const response = await user.getReceivedNodeSharingRequests();
  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 node sharing request that was sent to you using the decline method.

try {
  // Get received sharing requests
  const response = await user.getReceivedNodeSharingRequests();
  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 node 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 user.getIssuedNodeSharingRequests();
  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 a node
try {
  const shareRequest = {
    username: "recipient@example.com",
    makePrimary: false,
    metadata: {
      description: "Sharing smart home device",
    },
  };

  const requestId = await node.shareWith(shareRequest);
  console.log("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 user.getIssuedNodeSharingRequests();
  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 user.getReceivedNodeSharingRequests();
  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("Metadata:", incomingRequest.metadata);
  }
} catch (error) {
  console.error("Error fetching received requests:", error);
}

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

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

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

// Alternative: Recipient declines the sharing request
try {
  const response = await user.getReceivedNodeSharingRequests();
  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 user.getIssuedNodeSharingRequests(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(`   Node IDs: ${request.nodeIDs.join(", ")}`);
    console.log(`   Status: ${request.status}`);
  });

  // 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);
}