use-orion

use-orion

React hook for real-time Discord user activity tracking with WebSocket integration.

🚀 Features

• 🔄 Real-time Discord user activity tracking
• ⚡ WebSocket integration for instant updates
• 🎯 TypeScript support with full type definitions
• 🔧 Easy-to-use React hook
• 📱 Lightweight and performant
• 🎮 Spotify, game, and custom status tracking

📦 Installation

npm install use-orion
# or
yarn add use-orion

🔧 Requirements

• Discord Server: User must be in the Discord server where the bot is running
• Dependencies: React 16.8+ and socket.io-client 4.0+

🎯 Usage

Basic Usage

import React from 'react';
import { useOrion } from 'use-orion';

function UserActivity({ userId }: { userId: string }) {
  const { user, loading, error, isConnected } = useOrion(userId);

  if (loading) {
    return <div className="loading">Loading user activity...</div>;
  }

  if (error) {
    return <div className="error">Error: {error}</div>;
  }

  if (!user) {
    return <div className="not-found">User not found in server</div>;
  }

  return (
    <div className="user-activity">
      <h3>{user.username} ({user.status})</h3>

      {user.activities?.spotify && (
        <div className="spotify-activity">
          <h4>🎵 Listening to:</h4>
          <p>{user.activities.spotify.song} by {user.activities.spotify.artist}</p>
          <small>Album: {user.activities.spotify.album}</small>
        </div>
      )}

      {user.activities?.games && user.activities.games.length > 0 && (
        <div className="game-activity">
          <h4>🎮 Playing:</h4>
          {user.activities.games.map((game, index) => (
            <p key={index}>{game.name}</p>
          ))}
        </div>
      )}

      {user.activities?.custom && (
        <div className="custom-status">
          <p>💬 {user.activities.custom}</p>
        </div>
      )}

      <div className="connection-status">
        {isConnected ? '🟢 Connected' : '🔴 Disconnected'}
      </div>
    </div>
  );
}

// Usage
function App() {
  return (
    <UserActivity userId="882582406358515713" />
  );
}

Multiple Users Tracking

import { useOrionMulti } from 'use-orion';

function MultipleUsersTracker() {
  const userIds = ['123456789012345678', '987654321098765432'];
  const { users, loading, error, isConnected } = useOrionMulti(userIds);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div>
      {userIds.map(userId => {
        const user = users[userId];
        if (!user) return <div key={userId}>User {userId} not found</div>;

        return (
          <div key={userId}>
            <h3>{user.username}</h3>
            <p>Status: {user.status}</p>
          </div>
        );
      })}
    </div>
  );
}

🔌 API Reference

useOrion(userId, serverUrl?)

Main hook for tracking a single Discord user.

Parameters

• userId (string): Discord user ID to track (17-19 digits)
• serverUrl (string, optional): WebSocket server URL (default: 'http://localhost:3000')

Returns

{
  user: DiscordUser | null,    // User data or null if not found
  loading: boolean,            // Loading state
  error: string | null,        // Error message or null
  isConnected: boolean         // WebSocket connection status
}

useOrionMulti(userIds, serverUrl?)

Hook for tracking multiple Discord users.

Parameters

• userIds (string[]): Array of Discord user IDs to track
• serverUrl (string, optional): WebSocket server URL

Returns

{
  users: Record<string, DiscordUser | null>,  // Users data indexed by userId
  loading: boolean,
  error: string | null,
  isConnected: boolean
}

📊 Data Structure

DiscordUser Interface

interface DiscordUser {
  id: string;                    // Discord user ID
  username: string;              // Username
  discriminator?: string;        // User discriminator (e.g., "1234")
  avatar?: string;              // Avatar hash
  banner?: string;              // Banner hash
  nickname?: string;            // Server nickname
  status: 'online' | 'idle' | 'dnd' | 'offline' | 'invisible';

  activities?: {
    spotify?: {
      song: string;              // Song name
      artist: string;            // Artist name
      album: string;             // Album name
      duration: number;          // Duration in milliseconds
      startTime: string;         // ISO timestamp
    };
    games?: Array<{
      name: string;              // Game name
      details?: string;          // Game details
      state?: string;            // Game state
      startTime?: string;        // Start timestamp
      largeImage?: string;       // Game image hash
    }>;
    custom?: string;             // Custom status message
  };

  lastSeen?: string;             // Last seen timestamp
  lastUpdated?: string;          // Last update timestamp
  joinedAt?: string;             // Server join date
  roles?: string[];              // User roles
  recentActivities?: Array<{     // Recent activities summary
    name: string;
    totalTime: number;
    sessions: number;
    lastPlayed: string;
  }>;
}

🔧 Setup Instructions

1. Install Discord Bot

• Create a Discord bot at Discord Developer Portal
• Enable these bot permissions:
  • Server Members Intent
  • Presence Intent
  • View Channels
• Invite the bot to your server

2. Setup Activity Tracker Server

• Clone the Discord Activity Tracker repository
• Install dependencies: npm install
• Configure environment variables:

  DISCORD_TOKEN=your_bot_token
  SERVER_ID=your_server_id
  MONGODB_URI=your_mongodb_uri
  

• Start the server: npm run dev

3. Use the Hook

import { useOrion } from 'use-orion';

function MyComponent() {
  const { user, loading, error, isConnected } = useOrion('USER_ID');

  // Your component logic here
}

⚠️ Important Notes

• Server Requirement: Users must be in the same Discord server where the bot is running
• Bot Permissions: Bot needs Server Members Intent and Presence Intent enabled
• Real-time Updates: WebSocket connection provides instant updates when user activities change
• Rate Limiting: The hook automatically handles reconnection and rate limiting
• Error Handling: Built-in error handling for connection issues and invalid user IDs

🐛 Troubleshooting

User not found error

• Ensure the user is in the same Discord server as the bot
• Check that the bot has proper permissions
• Verify the user ID is correct (17-19 digits)

Connection issues

• Check if the Activity Tracker server is running
• Verify the server URL is correct
• Ensure WebSocket connections are allowed in your network

No real-time updates

• Check browser console for WebSocket connection errors
• Verify the bot is online and tracking users
• Ensure the server is configured correctly

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

📞 Support

For support, please create an issue on GitHub or contact the development team.

Note: This package requires the Discord Activity Tracker server to be running. Users must be in the same Discord server where the bot is active for tracking to work.