`useConnectionManager`

Overview

The useConnectionManager hook provides a comprehensive solution for managing connection relationships between users. Unlike simple follow relationships, connections are bidirectional and require mutual acceptance - similar to LinkedIn or Facebook connections. This hook manages the complete connection workflow including:

Checking connection status
Sending connection requests (with optional message)
Accepting or declining received requests
Withdrawing sent requests
Disconnecting from established connections
Loading states and optimistic updates

Unlike individual hooks, this manager hook handles the complete connection lifecycle in a single interface, making it ideal for implementing connection buttons and managing connection state throughout your user interface.

Usage Example

import { useConnectionManager } from "@replyke/react-js";

function ConnectionButton({ userId }: { userId: string }) {
  const {
    connectionStatus,
    isLoading,
    sendConnectionRequest,
    acceptConnectionRequest,
    disconnectUser,
  } = useConnectionManager({ userId });

  if (isLoading) {
    return <button disabled>Loading...</button>;
  }

  switch (connectionStatus) {
    case "none":
      return (
        <button onClick={() => sendConnectionRequest()}>
          Connect
        </button>
      );
    case "pending-sent":
      return (
        <button onClick={withdrawConnectionRequest}>
          Cancel Request
        </button>
      );
    case "pending-received":
      return (
        <div>
          <button onClick={acceptConnectionRequest}>Accept</button>
          <button onClick={declineConnectionRequest}>Decline</button>
        </div>
      );
    case "connected":
      return (
        <button onClick={disconnectUser}>
          Disconnect
        </button>
      );
    default:
      return null;
  }
}

// More complex example with message
function UserProfile({ userId }: { userId: string }) {
  const {
    connectionStatus,
    connectionData,
    isLoading,
    sendConnectionRequest,
    acceptConnectionRequest,
    declineConnectionRequest,
    disconnectUser,
  } = useConnectionManager({ userId });

  const handleSendRequest = async () => {
    try {
      await sendConnectionRequest("I'd like to connect with you!");
    } catch (error) {
      console.error("Failed to send request:", error);
    }
  };

  return (
    <div>
      <h2>User Profile</h2>
      <div>
        {isLoading ? (
          <span>Checking connection status...</span>
        ) : (
          <>
            <span>Status: {connectionStatus}</span>
            {connectionStatus === "connected" && connectionData.connectedAt && (
              <p>Connected since: {new Date(connectionData.connectedAt).toLocaleDateString()}</p>
            )}
            {/* Render appropriate buttons based on status */}
          </>
        )}
      </div>
    </div>
  );
}

Parameters & Returns

Parameters

The hook accepts an object with the following field:

Parameter	Type	Required	Description
`userId`	`string`	Yes	The ID of the user to manage connection status for.

Returns

The hook returns an object with the following fields:

Return Value	Type	Description
`connectionStatus`	`ConnectionStatus`	The current connection status (see Connection Status section below).
`connectionId`	`string \| null`	The ID of the connection if one exists, `null` otherwise.
`connectionData`	`ConnectionData`	Additional data about the connection (dates, type).
`isLoading`	`boolean`	Whether the hook is currently loading or performing an operation.
`sendConnectionRequest`	`(message?: string) => Promise<void>`	Function to send a connection request with optional message.
`acceptConnectionRequest`	`() => Promise<void>`	Function to accept a received connection request.
`declineConnectionRequest`	`() => Promise<void>`	Function to decline a received connection request.
`withdrawConnectionRequest`	`() => Promise<void>`	Function to withdraw a sent connection request.
`disconnectUser`	`() => Promise<void>`	Function to disconnect from an established connection.
`removeConnectionSmart`	`() => Promise<void>`	Function to remove connection regardless of current state.
`refreshConnectionStatus`	`() => Promise<void>`	Function to manually refresh the connection status.

Connection Status

The connectionStatus field can have the following values:

Status	Description
`"none"`	No connection exists between users.
`"pending-sent"`	You have sent a connection request that is awaiting response.
`"pending-received"`	You have received a connection request that is awaiting your response.
`"connected"`	Both users are connected.
`"declined-sent"`	Your connection request was declined by the other user.
`"declined-received"`	You declined a connection request from the other user.

Connection Data

The connectionData object contains additional information about the connection:

interface ConnectionData {
  connectionId: string | null;
  connectedAt?: string;      // Date when connection was established
  requestedAt?: string;       // Date when request was initially sent
  createdAt?: string;         // Date when connection record was created
  respondedAt?: string;       // Date when request was responded to
  type?: "sent" | "received"; // Whether you sent or received the request
}

Behavior & Features

Automatic Status Loading

Automatically fetches the current connection status when the hook is initialized
Handles loading states during the initial fetch
Skips loading if the target user is the same as the authenticated user

Connection Request with Message

Send connection requests with an optional personalized message
Message parameter is optional - defaults to no message if not provided

// Send request without message
await sendConnectionRequest();

// Send request with message
await sendConnectionRequest("I'd love to connect and collaborate!");

State Management

Prevents multiple simultaneous operations
Maintains consistent state throughout the component lifecycle
Automatically updates when the target userId changes
Provides detailed connection metadata (dates, type)

Smart Operations

Each operation function is guarded to only work in appropriate states:

sendConnectionRequest: Only works when status is "none" or "declined-received"
acceptConnectionRequest: Only works when status is "pending-received"
declineConnectionRequest: Only works when status is "pending-received"
withdrawConnectionRequest: Only works when status is "pending-sent"
disconnectUser: Only works when status is "connected"
removeConnectionSmart: Works for any status except "none" and "declined-sent"

Error Handling

Gracefully handles errors during status fetching
Defaults to "none" status if fetch fails
Logs errors to console for debugging purposes
Operations throw errors that can be caught by calling code

Implementation Notes

Self-Connection Prevention

The hook automatically prevents users from connecting with themselves:

Skips status loading if userId matches the authenticated user’s ID
Prevents all connection operations when targeting the same user

Loading States

The hook provides loading indication during:

Initial status fetch
Connection request operations
Accept/decline operations
Disconnect operations

Status Refresh

After accepting a connection, the hook automatically refreshes to get updated connection data with timestamps.

Error Scenarios

The hook handles several error scenarios:

Network errors during status fetching or operations
Authentication errors if the user is not logged in
Invalid user IDs that don’t exist in the system
Invalid operations (e.g., trying to accept when not in pending-received state)

All errors are logged to the console, and operations throw errors that you can catch and handle.

Best Practices

Handle Loading States: Always check isLoading before allowing user interactions
Status-Based UI: Render different UI elements based on connectionStatus
Error Feedback: Implement user-visible error feedback for failed operations
Prevent Self-Connect: The hook handles this automatically, but your UI should also reflect this
Connection Messages: Consider prompting users for a message when sending requests

// Good example with proper state handling
function ConnectionButton({ userId }: { userId: string }) {
  const {
    connectionStatus,
    isLoading,
    sendConnectionRequest,
    acceptConnectionRequest,
    withdrawConnectionRequest,
    disconnectUser,
  } = useConnectionManager({ userId });

  const [error, setError] = useState<string | null>(null);

  const handleAction = async (action: () => Promise<void>) => {
    try {
      setError(null);
      await action();
    } catch (err) {
      setError("Operation failed. Please try again.");
    }
  };

  if (isLoading) {
    return <button disabled>Loading...</button>;
  }

  return (
    <div>
      {error && <div className="error">{error}</div>}
      {connectionStatus === "none" && (
        <button onClick={() => handleAction(sendConnectionRequest)}>
          Connect
        </button>
      )}
      {connectionStatus === "pending-sent" && (
        <button onClick={() => handleAction(withdrawConnectionRequest)}>
          Cancel Request
        </button>
      )}
      {connectionStatus === "pending-received" && (
        <div>
          <button onClick={() => handleAction(acceptConnectionRequest)}>
            Accept
          </button>
          <button onClick={() => handleAction(declineConnectionRequest)}>
            Decline
          </button>
        </div>
      )}
      {connectionStatus === "connected" && (
        <button onClick={() => handleAction(disconnectUser)}>
          Disconnect
        </button>
      )}
    </div>
  );
}

Comparison with useFollowManager

Feature	useFollowManager	useConnectionManager
Relationship Type	Unidirectional (follow)	Bidirectional (connection)
Requires Acceptance	No	Yes
Status States	2 (following/not following)	6 (none, pending-sent, pending-received, connected, declined-sent, declined-received)
Can Include Message	No	Yes (optional)
Use Case	Social media feeds, content curation	Professional networks, mutual relationships

React & React Native

Authentication

Users

Relationships

Entities

Entity Lists

Lists

App Notifications

Moderation

useConnectionManager

`useConnectionManager`

Overview

Usage Example

Parameters & Returns

Parameters

Returns

Connection Status

Connection Data

Behavior & Features

Automatic Status Loading

Connection Request with Message

State Management

Smart Operations

Error Handling

Implementation Notes

Self-Connection Prevention

Loading States

Status Refresh

Error Scenarios

Best Practices

Comparison with useFollowManager

​useConnectionManager

​Overview

​Usage Example

​Parameters & Returns

​Parameters

​Returns

​Connection Status

​Connection Data

​Behavior & Features

​Automatic Status Loading

​Connection Request with Message

​State Management

​Smart Operations

​Error Handling

​Implementation Notes

​Self-Connection Prevention

​Loading States

​Status Refresh

​Error Scenarios

​Best Practices

​Comparison with useFollowManager

`useConnectionManager`

Overview

Usage Example

Parameters & Returns

Parameters

Returns

Connection Status

Connection Data

Behavior & Features

Automatic Status Loading

Connection Request with Message

State Management

Smart Operations

Error Handling

Implementation Notes

Self-Connection Prevention

Loading States

Status Refresh

Error Scenarios

Best Practices

Comparison with useFollowManager