@redseat/api 0.0.12 → 0.0.14

package/firebase.md

@@ -1,602 +1,602 @@
-# Firebase Connection and Server Retrieval
-
-This guide explains how to connect to Firebase Realtime Database and retrieve a list of servers stored for a user.
-
-## Prerequisites
-
-### Install Firebase SDK
-
-First, install the Firebase JavaScript SDK:
-
-```bash
-npm install firebase
-# or
-pnpm add firebase
-# or
-yarn add firebase
-```
-
-### Firebase Configuration
-
-You'll need your Firebase project configuration. The configuration typically includes:
-
-- `apiKey`: Your Firebase API key
-- `authDomain`: Your Firebase auth domain
-- `databaseURL`: Your Firebase Realtime Database URL
-- `projectId`: Your Firebase project ID
-- `storageBucket`: Your Firebase storage bucket
-- `messagingSenderId`: Your messaging sender ID
-- `appId`: Your Firebase app ID
-
-These values can be obtained from your Firebase project settings in the Firebase Console.
-
-## Firebase Initialization
-
-### Client-Side Initialization
-
-Create a Firebase initialization file (e.g., `firebase.ts`):
-
-```typescript
-import { initializeApp } from 'firebase/app';
-import { getAuth } from 'firebase/auth';
-import { getDatabase } from 'firebase/database';
-
-// Firebase configuration
-const firebaseConfig = {
-    apiKey: "YOUR_API_KEY",
-    authDomain: "YOUR_AUTH_DOMAIN",
-    databaseURL: "YOUR_DATABASE_URL",
-    projectId: "YOUR_PROJECT_ID",
-    storageBucket: "YOUR_STORAGE_BUCKET",
-    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
-    appId: "YOUR_APP_ID"
-};
-
-// Initialize Firebase
-const app = initializeApp(firebaseConfig);
-
-// Initialize Firebase services
-export const auth = getAuth(app);
-export const firebaseDb = getDatabase(app);
-```
-
-### Server-Side Initialization (Admin SDK)
-
-For server-side operations, use the Firebase Admin SDK:
-
-```typescript
-import admin from 'firebase-admin';
-
-const config = {
-    apiKey: "YOUR_API_KEY",
-    authDomain: "YOUR_AUTH_DOMAIN",
-    databaseURL: "YOUR_DATABASE_URL",
-    projectId: "YOUR_PROJECT_ID",
-    storageBucket: "YOUR_STORAGE_BUCKET",
-    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
-    appId: "YOUR_APP_ID",
-    credential: admin.credential.cert({
-        project_id: "YOUR_PROJECT_ID",
-        private_key: process.env.FIREBASE_PRIVATE_KEY?.replace(/\\n/g, '\n'),
-        client_email: "YOUR_SERVICE_ACCOUNT_EMAIL"
-    })
-};
-
-const firebaseServer = !admin.apps.length 
-    ? admin.initializeApp(config) 
-    : admin.app();
-
-export default firebaseServer;
-```
-
-## Authentication
-
-### Getting User ID Token
-
-To retrieve servers, you need an authenticated user. Here's how to get the user's ID token:
-
-```typescript
-import { auth } from './firebase';
-import { onIdTokenChanged } from 'firebase/auth';
-
-// Listen for auth state changes
-onIdTokenChanged(auth, async (user) => {
-    if (user) {
-        // Get the ID token
-        const idToken = await user.getIdToken();
-        console.log('User ID token:', idToken);
-        console.log('User UID:', user.uid);
-    }
-});
-```
-
-### Manual Token Retrieval
-
-If you already have a user object:
-
-```typescript
-import { auth } from './firebase';
-
-async function getIdToken(forceRefresh = false): Promise<string | undefined> {
-    const user = auth.currentUser;
-    if (user) {
-        return await user.getIdToken(forceRefresh);
-    }
-    return undefined;
-}
-```
-
-## Database Structure
-
-Servers are stored in Firebase Realtime Database at the following path:
-
-```
-users/{userId}/servers
-```
-
-The data structure is an object where:
-- **Keys**: Server IDs (generated by Firebase)
-- **Values**: Server objects with properties like `name`, `id`, `url`, `port`, etc.
-
-Example structure:
-```json
-{
-  "users": {
-    "user123": {
-      "servers": {
-        "server-id-1": {
-          "name": "My Server",
-          "id": "server-id-1",
-          "url": "example.com",
-          "port": 443
-        },
-        "server-id-2": {
-          "name": "Another Server",
-          "id": "server-id-2",
-          "url": "another.example.com"
-        }
-      }
-    }
-  }
-}
-```
-
-## Retrieving Servers
-
-### Client-Side Retrieval
-
-Using the Firebase client SDK:
-
-```typescript
-import { ref, get } from 'firebase/database';
-import { firebaseDb } from './firebase';
-import type { IServer } from './interfaces';
-
-interface IUserServer {
-    name: string;
-    id: string;
-    url?: string;
-    port?: number;
-}
-
-async function getServers(userId: string): Promise<IUserServer[]> {
-    try {
-        // Create a reference to the servers path
-        const serversRef = ref(firebaseDb, `users/${userId}/servers`);
-        
-        // Get the data snapshot
-        const snapshot = await get(serversRef);
-        const serversData = snapshot.val();
-        
-        // Convert object to array
-        // Firebase returns an object with server IDs as keys
-        const serversArray: IUserServer[] = serversData 
-            ? Object.entries(serversData).map<IUserServer>(([id, server]) => ({
-                ...(server as IUserServer),
-                id: id // Ensure ID is set from the key
-            }))
-            : [];
-        
-        return serversArray;
-    } catch (error) {
-        console.error('Error retrieving servers:', error);
-        throw error;
-    }
-}
-```
-
-### Complete Example with Authentication
-
-Here's a complete example that combines authentication and server retrieval:
-
-```typescript
-import { ref, get } from 'firebase/database';
-import { onIdTokenChanged } from 'firebase/auth';
-import { auth, firebaseDb } from './firebase';
-import type { IServer } from './interfaces';
-
-interface IUserServer {
-    name: string;
-    id: string;
-    url?: string;
-    port?: number;
-}
-
-class ServerManager {
-    private servers: IUserServer[] = [];
-    
-    constructor() {
-        // Listen for authentication state changes
-        onIdTokenChanged(auth, async (user) => {
-            if (user) {
-                // User is authenticated, retrieve servers
-                await this.loadServers(user.uid);
-            } else {
-                // User is not authenticated, clear servers
-                this.servers = [];
-            }
-        });
-    }
-    
-    async loadServers(userId: string): Promise<void> {
-        try {
-            const serversRef = ref(firebaseDb, `users/${userId}/servers`);
-            const snapshot = await get(serversRef);
-            const serversData = snapshot.val();
-            
-            this.servers = serversData 
-                ? Object.entries(serversData).map<IUserServer>(([id, server]) => ({
-                    ...(server as IUserServer),
-                    id: id
-                }))
-                : [];
-        } catch (error) {
-            console.error('Error loading servers:', error);
-            throw error;
-        }
-    }
-    
-    getServers(): IUserServer[] {
-        return this.servers;
-    }
-}
-```
-
-### Server-Side Retrieval (Admin SDK)
-
-For server-side operations using the Admin SDK:
-
-```typescript
-import firebaseServer from './firebase-server';
-import type { IServer } from './interfaces';
-
-interface IUserServer {
-    name: string;
-    id: string;
-    url?: string;
-    port?: number;
-}
-
-async function getServers(userId: string): Promise<IUserServer[]> {
-    try {
-        const serversRef = firebaseServer.database().ref(`users/${userId}/servers`);
-        const snapshot = await serversRef.get();
-        const serversData = snapshot.val();
-        
-        const serversArray: IUserServer[] = serversData 
-            ? Object.entries(serversData).map<IUserServer>(([id, server]) => ({
-                ...(server as IUserServer),
-                id: id
-            }))
-            : [];
-        
-        return serversArray;
-    } catch (error) {
-        console.error('Error retrieving servers:', error);
-        throw error;
-    }
-}
-```
-
-### Server-Side with Token Verification
-
-When handling API requests, verify the ID token first:
-
-```typescript
-import firebaseServer from './firebase-server';
-import type { IServer } from './interfaces';
-
-async function getServersForUser(idToken: string): Promise<IUserServer[]> {
-    try {
-        // Verify the ID token
-        const decodedToken = await firebaseServer.auth().verifyIdToken(idToken);
-        const userId = decodedToken.uid;
-        
-        // Retrieve servers for the authenticated user
-        const serversRef = firebaseServer.database().ref(`users/${userId}/servers`);
-        const snapshot = await serversRef.get();
-        const serversData = snapshot.val();
-        
-        const serversArray: IUserServer[] = serversData 
-            ? Object.entries(serversData).map<IUserServer>(([id, server]) => ({
-                ...(server as IUserServer),
-                id: id
-            }))
-            : [];
-        
-        return serversArray;
-    } catch (error) {
-        console.error('Error retrieving servers:', error);
-        throw error;
-    }
-}
-```
-
-## Real-Time Updates
-
-To listen for real-time changes to the servers list:
-
-```typescript
-import { ref, onValue, Unsubscribe } from 'firebase/database';
-import { firebaseDb } from './firebase';
-
-function subscribeToServers(
-    userId: string, 
-    callback: (servers: IUserServer[]) => void
-): Unsubscribe {
-    const serversRef = ref(firebaseDb, `users/${userId}/servers`);
-    
-    return onValue(serversRef, (snapshot) => {
-        const serversData = snapshot.val();
-        const serversArray: IUserServer[] = serversData 
-            ? Object.entries(serversData).map<IUserServer>(([id, server]) => ({
-                ...(server as IUserServer),
-                id: id
-            }))
-            : [];
-        
-        callback(serversArray);
-    }, (error) => {
-        console.error('Error listening to servers:', error);
-    });
-}
-
-// Usage
-const unsubscribe = subscribeToServers(userId, (servers) => {
-    console.log('Servers updated:', servers);
-});
-
-// Cleanup when done
-// unsubscribe();
-```
-
-## TypeScript Interfaces
-
-The `IServer` interface is defined in `packages/api/src/interfaces.ts`:
-
-```typescript
-export interface IServer {
-    id: string;
-    name: string;
-    url: string;
-    port?: number;
-}
-```
-
-For user-specific server data, you may also use:
-
-```typescript
-interface IUserServer {
-    name: string;
-    id: string;
-    url?: string;
-    port?: number;
-}
-```
-
-## Error Handling
-
-Always handle potential errors when working with Firebase:
-
-```typescript
-import { ref, get } from 'firebase/database';
-import { firebaseDb } from './firebase';
-
-async function getServersSafely(userId: string): Promise<IUserServer[]> {
-    try {
-        const serversRef = ref(firebaseDb, `users/${userId}/servers`);
-        const snapshot = await get(serversRef);
-        
-        if (!snapshot.exists()) {
-            console.log('No servers found for user');
-            return [];
-        }
-        
-        const serversData = snapshot.val();
-        return serversData 
-            ? Object.entries(serversData).map<IUserServer>(([id, server]) => ({
-                ...(server as IUserServer),
-                id: id
-            }))
-            : [];
-    } catch (error) {
-        if (error.code === 'PERMISSION_DENIED') {
-            console.error('Permission denied. Check Firebase security rules.');
-        } else if (error.code === 'UNAVAILABLE') {
-            console.error('Firebase service unavailable.');
-        } else {
-            console.error('Unexpected error:', error);
-        }
-        throw error;
-    }
-}
-```
-
-## Security Rules
-
-Ensure your Firebase Realtime Database security rules allow authenticated users to read their own servers:
-
-```json
-{
-  "rules": {
-    "users": {
-      "$uid": {
-        "servers": {
-          ".read": "$uid === auth.uid",
-          ".write": "$uid === auth.uid"
-        }
-      }
-    }
-  }
-}
-```
-
-## Complete Example
-
-Here's a complete, production-ready example:
-
-```typescript
-import { initializeApp } from 'firebase/app';
-import { getAuth, onIdTokenChanged, User } from 'firebase/auth';
-import { getDatabase, ref, get, onValue, Unsubscribe } from 'firebase/database';
-import type { IServer } from './interfaces';
-
-// Firebase configuration
-const firebaseConfig = {
-    apiKey: process.env.FIREBASE_API_KEY,
-    authDomain: process.env.FIREBASE_AUTH_DOMAIN,
-    databaseURL: process.env.FIREBASE_DATABASE_URL,
-    projectId: process.env.FIREBASE_PROJECT_ID,
-    storageBucket: process.env.FIREBASE_STORAGE_BUCKET,
-    messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID,
-    appId: process.env.FIREBASE_APP_ID
-};
-
-const app = initializeApp(firebaseConfig);
-const auth = getAuth(app);
-const db = getDatabase(app);
-
-interface IUserServer extends IServer {
-    name: string;
-}
-
-class FirebaseServerService {
-    private unsubscribeAuth?: () => void;
-    private unsubscribeServers?: Unsubscribe;
-    private servers: IUserServer[] = [];
-    
-    constructor(
-        private onServersChanged?: (servers: IUserServer[]) => void
-    ) {
-        this.initialize();
-    }
-    
-    private initialize(): void {
-        this.unsubscribeAuth = onIdTokenChanged(auth, async (user) => {
-            if (user) {
-                await this.loadServers(user.uid);
-                this.subscribeToServers(user.uid);
-            } else {
-                this.servers = [];
-                this.unsubscribeServers?.();
-                this.onServersChanged?.([]);
-            }
-        });
-    }
-    
-    private async loadServers(userId: string): Promise<void> {
-        try {
-            const serversRef = ref(db, `users/${userId}/servers`);
-            const snapshot = await get(serversRef);
-            
-            if (snapshot.exists()) {
-                const serversData = snapshot.val();
-                this.servers = Object.entries(serversData).map<IUserServer>(
-                    ([id, server]) => ({
-                        ...(server as IUserServer),
-                        id: id
-                    })
-                );
-                this.onServersChanged?.(this.servers);
-            }
-        } catch (error) {
-            console.error('Error loading servers:', error);
-            throw error;
-        }
-    }
-    
-    private subscribeToServers(userId: string): void {
-        const serversRef = ref(db, `users/${userId}/servers`);
-        
-        this.unsubscribeServers = onValue(serversRef, (snapshot) => {
-            if (snapshot.exists()) {
-                const serversData = snapshot.val();
-                this.servers = Object.entries(serversData).map<IUserServer>(
-                    ([id, server]) => ({
-                        ...(server as IUserServer),
-                        id: id
-                    })
-                );
-                this.onServersChanged?.(this.servers);
-            } else {
-                this.servers = [];
-                this.onServersChanged?.([]);
-            }
-        }, (error) => {
-            console.error('Error listening to servers:', error);
-        });
-    }
-    
-    getServers(): IUserServer[] {
-        return this.servers;
-    }
-    
-    async getServersOnce(userId: string): Promise<IUserServer[]> {
-        const serversRef = ref(db, `users/${userId}/servers`);
-        const snapshot = await get(serversRef);
-        
-        if (!snapshot.exists()) {
-            return [];
-        }
-        
-        const serversData = snapshot.val();
-        return Object.entries(serversData).map<IUserServer>(
-            ([id, server]) => ({
-                ...(server as IUserServer),
-                id: id
-            })
-        );
-    }
-    
-    dispose(): void {
-        this.unsubscribeAuth?.();
-        this.unsubscribeServers?.();
-    }
-}
-
-// Usage
-const serverService = new FirebaseServerService((servers) => {
-    console.log('Servers updated:', servers);
-});
-
-// Get current servers
-const currentServers = serverService.getServers();
-
-// Cleanup when done
-// serverService.dispose();
-```
-
-## Summary
-
-To retrieve servers from Firebase:
-
-1. **Install Firebase SDK**: `npm install firebase`
-2. **Initialize Firebase**: Configure and initialize the Firebase app
-3. **Authenticate User**: Get the user's ID token
-4. **Access Database**: Create a reference to `users/{userId}/servers`
-5. **Retrieve Data**: Use `get()` for one-time reads or `onValue()` for real-time updates
-6. **Transform Data**: Convert the Firebase object structure to an array using `Object.entries()`
-7. **Handle Errors**: Implement proper error handling for network and permission issues
-
-The key pattern is converting Firebase's object structure (where keys are server IDs) to an array format suitable for application use.
-
+# Firebase Connection and Server Retrieval
+
+This guide explains how to connect to Firebase Realtime Database and retrieve a list of servers stored for a user.
+
+## Prerequisites
+
+### Install Firebase SDK
+
+First, install the Firebase JavaScript SDK:
+
+```bash
+npm install firebase
+# or
+pnpm add firebase
+# or
+yarn add firebase
+```
+
+### Firebase Configuration
+
+You'll need your Firebase project configuration. The configuration typically includes:
+
+- `apiKey`: Your Firebase API key
+- `authDomain`: Your Firebase auth domain
+- `databaseURL`: Your Firebase Realtime Database URL
+- `projectId`: Your Firebase project ID
+- `storageBucket`: Your Firebase storage bucket
+- `messagingSenderId`: Your messaging sender ID
+- `appId`: Your Firebase app ID
+
+These values can be obtained from your Firebase project settings in the Firebase Console.
+
+## Firebase Initialization
+
+### Client-Side Initialization
+
+Create a Firebase initialization file (e.g., `firebase.ts`):
+
+```typescript
+import { initializeApp } from 'firebase/app';
+import { getAuth } from 'firebase/auth';
+import { getDatabase } from 'firebase/database';
+
+// Firebase configuration
+const firebaseConfig = {
+    apiKey: "YOUR_API_KEY",
+    authDomain: "YOUR_AUTH_DOMAIN",
+    databaseURL: "YOUR_DATABASE_URL",
+    projectId: "YOUR_PROJECT_ID",
+    storageBucket: "YOUR_STORAGE_BUCKET",
+    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
+    appId: "YOUR_APP_ID"
+};
+
+// Initialize Firebase
+const app = initializeApp(firebaseConfig);
+
+// Initialize Firebase services
+export const auth = getAuth(app);
+export const firebaseDb = getDatabase(app);
+```
+
+### Server-Side Initialization (Admin SDK)
+
+For server-side operations, use the Firebase Admin SDK:
+
+```typescript
+import admin from 'firebase-admin';
+
+const config = {
+    apiKey: "YOUR_API_KEY",
+    authDomain: "YOUR_AUTH_DOMAIN",
+    databaseURL: "YOUR_DATABASE_URL",
+    projectId: "YOUR_PROJECT_ID",
+    storageBucket: "YOUR_STORAGE_BUCKET",
+    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
+    appId: "YOUR_APP_ID",
+    credential: admin.credential.cert({
+        project_id: "YOUR_PROJECT_ID",
+        private_key: process.env.FIREBASE_PRIVATE_KEY?.replace(/\\n/g, '\n'),
+        client_email: "YOUR_SERVICE_ACCOUNT_EMAIL"
+    })
+};
+
+const firebaseServer = !admin.apps.length 
+    ? admin.initializeApp(config) 
+    : admin.app();
+
+export default firebaseServer;
+```
+
+## Authentication
+
+### Getting User ID Token
+
+To retrieve servers, you need an authenticated user. Here's how to get the user's ID token:
+
+```typescript
+import { auth } from './firebase';
+import { onIdTokenChanged } from 'firebase/auth';
+
+// Listen for auth state changes
+onIdTokenChanged(auth, async (user) => {
+    if (user) {
+        // Get the ID token
+        const idToken = await user.getIdToken();
+        console.log('User ID token:', idToken);
+        console.log('User UID:', user.uid);
+    }
+});
+```
+
+### Manual Token Retrieval
+
+If you already have a user object:
+
+```typescript
+import { auth } from './firebase';
+
+async function getIdToken(forceRefresh = false): Promise<string | undefined> {
+    const user = auth.currentUser;
+    if (user) {
+        return await user.getIdToken(forceRefresh);
+    }
+    return undefined;
+}
+```
+
+## Database Structure
+
+Servers are stored in Firebase Realtime Database at the following path:
+
+```
+users/{userId}/servers
+```
+
+The data structure is an object where:
+- **Keys**: Server IDs (generated by Firebase)
+- **Values**: Server objects with properties like `name`, `id`, `url`, `port`, etc.
+
+Example structure:
+```json
+{
+  "users": {
+    "user123": {
+      "servers": {
+        "server-id-1": {
+          "name": "My Server",
+          "id": "server-id-1",
+          "url": "example.com",
+          "port": 443
+        },
+        "server-id-2": {
+          "name": "Another Server",
+          "id": "server-id-2",
+          "url": "another.example.com"
+        }
+      }
+    }
+  }
+}
+```
+
+## Retrieving Servers
+
+### Client-Side Retrieval
+
+Using the Firebase client SDK:
+
+```typescript
+import { ref, get } from 'firebase/database';
+import { firebaseDb } from './firebase';
+import type { IServer } from './interfaces';
+
+interface IUserServer {
+    name: string;
+    id: string;
+    url?: string;
+    port?: number;
+}
+
+async function getServers(userId: string): Promise<IUserServer[]> {
+    try {
+        // Create a reference to the servers path
+        const serversRef = ref(firebaseDb, `users/${userId}/servers`);
+        
+        // Get the data snapshot
+        const snapshot = await get(serversRef);
+        const serversData = snapshot.val();
+        
+        // Convert object to array
+        // Firebase returns an object with server IDs as keys
+        const serversArray: IUserServer[] = serversData 
+            ? Object.entries(serversData).map<IUserServer>(([id, server]) => ({
+                ...(server as IUserServer),
+                id: id // Ensure ID is set from the key
+            }))
+            : [];
+        
+        return serversArray;
+    } catch (error) {
+        console.error('Error retrieving servers:', error);
+        throw error;
+    }
+}
+```
+
+### Complete Example with Authentication
+
+Here's a complete example that combines authentication and server retrieval:
+
+```typescript
+import { ref, get } from 'firebase/database';
+import { onIdTokenChanged } from 'firebase/auth';
+import { auth, firebaseDb } from './firebase';
+import type { IServer } from './interfaces';
+
+interface IUserServer {
+    name: string;
+    id: string;
+    url?: string;
+    port?: number;
+}
+
+class ServerManager {
+    private servers: IUserServer[] = [];
+    
+    constructor() {
+        // Listen for authentication state changes
+        onIdTokenChanged(auth, async (user) => {
+            if (user) {
+                // User is authenticated, retrieve servers
+                await this.loadServers(user.uid);
+            } else {
+                // User is not authenticated, clear servers
+                this.servers = [];
+            }
+        });
+    }
+    
+    async loadServers(userId: string): Promise<void> {
+        try {
+            const serversRef = ref(firebaseDb, `users/${userId}/servers`);
+            const snapshot = await get(serversRef);
+            const serversData = snapshot.val();
+            
+            this.servers = serversData 
+                ? Object.entries(serversData).map<IUserServer>(([id, server]) => ({
+                    ...(server as IUserServer),
+                    id: id
+                }))
+                : [];
+        } catch (error) {
+            console.error('Error loading servers:', error);
+            throw error;
+        }
+    }
+    
+    getServers(): IUserServer[] {
+        return this.servers;
+    }
+}
+```
+
+### Server-Side Retrieval (Admin SDK)
+
+For server-side operations using the Admin SDK:
+
+```typescript
+import firebaseServer from './firebase-server';
+import type { IServer } from './interfaces';
+
+interface IUserServer {
+    name: string;
+    id: string;
+    url?: string;
+    port?: number;
+}
+
+async function getServers(userId: string): Promise<IUserServer[]> {
+    try {
+        const serversRef = firebaseServer.database().ref(`users/${userId}/servers`);
+        const snapshot = await serversRef.get();
+        const serversData = snapshot.val();
+        
+        const serversArray: IUserServer[] = serversData 
+            ? Object.entries(serversData).map<IUserServer>(([id, server]) => ({
+                ...(server as IUserServer),
+                id: id
+            }))
+            : [];
+        
+        return serversArray;
+    } catch (error) {
+        console.error('Error retrieving servers:', error);
+        throw error;
+    }
+}
+```
+
+### Server-Side with Token Verification
+
+When handling API requests, verify the ID token first:
+
+```typescript
+import firebaseServer from './firebase-server';
+import type { IServer } from './interfaces';
+
+async function getServersForUser(idToken: string): Promise<IUserServer[]> {
+    try {
+        // Verify the ID token
+        const decodedToken = await firebaseServer.auth().verifyIdToken(idToken);
+        const userId = decodedToken.uid;
+        
+        // Retrieve servers for the authenticated user
+        const serversRef = firebaseServer.database().ref(`users/${userId}/servers`);
+        const snapshot = await serversRef.get();
+        const serversData = snapshot.val();
+        
+        const serversArray: IUserServer[] = serversData 
+            ? Object.entries(serversData).map<IUserServer>(([id, server]) => ({
+                ...(server as IUserServer),
+                id: id
+            }))
+            : [];
+        
+        return serversArray;
+    } catch (error) {
+        console.error('Error retrieving servers:', error);
+        throw error;
+    }
+}
+```
+
+## Real-Time Updates
+
+To listen for real-time changes to the servers list:
+
+```typescript
+import { ref, onValue, Unsubscribe } from 'firebase/database';
+import { firebaseDb } from './firebase';
+
+function subscribeToServers(
+    userId: string, 
+    callback: (servers: IUserServer[]) => void
+): Unsubscribe {
+    const serversRef = ref(firebaseDb, `users/${userId}/servers`);
+    
+    return onValue(serversRef, (snapshot) => {
+        const serversData = snapshot.val();
+        const serversArray: IUserServer[] = serversData 
+            ? Object.entries(serversData).map<IUserServer>(([id, server]) => ({
+                ...(server as IUserServer),
+                id: id
+            }))
+            : [];
+        
+        callback(serversArray);
+    }, (error) => {
+        console.error('Error listening to servers:', error);
+    });
+}
+
+// Usage
+const unsubscribe = subscribeToServers(userId, (servers) => {
+    console.log('Servers updated:', servers);
+});
+
+// Cleanup when done
+// unsubscribe();
+```
+
+## TypeScript Interfaces
+
+The `IServer` interface is defined in `packages/api/src/interfaces.ts`:
+
+```typescript
+export interface IServer {
+    id: string;
+    name: string;
+    url: string;
+    port?: number;
+}
+```
+
+For user-specific server data, you may also use:
+
+```typescript
+interface IUserServer {
+    name: string;
+    id: string;
+    url?: string;
+    port?: number;
+}
+```
+
+## Error Handling
+
+Always handle potential errors when working with Firebase:
+
+```typescript
+import { ref, get } from 'firebase/database';
+import { firebaseDb } from './firebase';
+
+async function getServersSafely(userId: string): Promise<IUserServer[]> {
+    try {
+        const serversRef = ref(firebaseDb, `users/${userId}/servers`);
+        const snapshot = await get(serversRef);
+        
+        if (!snapshot.exists()) {
+            console.log('No servers found for user');
+            return [];
+        }
+        
+        const serversData = snapshot.val();
+        return serversData 
+            ? Object.entries(serversData).map<IUserServer>(([id, server]) => ({
+                ...(server as IUserServer),
+                id: id
+            }))
+            : [];
+    } catch (error) {
+        if (error.code === 'PERMISSION_DENIED') {
+            console.error('Permission denied. Check Firebase security rules.');
+        } else if (error.code === 'UNAVAILABLE') {
+            console.error('Firebase service unavailable.');
+        } else {
+            console.error('Unexpected error:', error);
+        }
+        throw error;
+    }
+}
+```
+
+## Security Rules
+
+Ensure your Firebase Realtime Database security rules allow authenticated users to read their own servers:
+
+```json
+{
+  "rules": {
+    "users": {
+      "$uid": {
+        "servers": {
+          ".read": "$uid === auth.uid",
+          ".write": "$uid === auth.uid"
+        }
+      }
+    }
+  }
+}
+```
+
+## Complete Example
+
+Here's a complete, production-ready example:
+
+```typescript
+import { initializeApp } from 'firebase/app';
+import { getAuth, onIdTokenChanged, User } from 'firebase/auth';
+import { getDatabase, ref, get, onValue, Unsubscribe } from 'firebase/database';
+import type { IServer } from './interfaces';
+
+// Firebase configuration
+const firebaseConfig = {
+    apiKey: process.env.FIREBASE_API_KEY,
+    authDomain: process.env.FIREBASE_AUTH_DOMAIN,
+    databaseURL: process.env.FIREBASE_DATABASE_URL,
+    projectId: process.env.FIREBASE_PROJECT_ID,
+    storageBucket: process.env.FIREBASE_STORAGE_BUCKET,
+    messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID,
+    appId: process.env.FIREBASE_APP_ID
+};
+
+const app = initializeApp(firebaseConfig);
+const auth = getAuth(app);
+const db = getDatabase(app);
+
+interface IUserServer extends IServer {
+    name: string;
+}
+
+class FirebaseServerService {
+    private unsubscribeAuth?: () => void;
+    private unsubscribeServers?: Unsubscribe;
+    private servers: IUserServer[] = [];
+    
+    constructor(
+        private onServersChanged?: (servers: IUserServer[]) => void
+    ) {
+        this.initialize();
+    }
+    
+    private initialize(): void {
+        this.unsubscribeAuth = onIdTokenChanged(auth, async (user) => {
+            if (user) {
+                await this.loadServers(user.uid);
+                this.subscribeToServers(user.uid);
+            } else {
+                this.servers = [];
+                this.unsubscribeServers?.();
+                this.onServersChanged?.([]);
+            }
+        });
+    }
+    
+    private async loadServers(userId: string): Promise<void> {
+        try {
+            const serversRef = ref(db, `users/${userId}/servers`);
+            const snapshot = await get(serversRef);
+            
+            if (snapshot.exists()) {
+                const serversData = snapshot.val();
+                this.servers = Object.entries(serversData).map<IUserServer>(
+                    ([id, server]) => ({
+                        ...(server as IUserServer),
+                        id: id
+                    })
+                );
+                this.onServersChanged?.(this.servers);
+            }
+        } catch (error) {
+            console.error('Error loading servers:', error);
+            throw error;
+        }
+    }
+    
+    private subscribeToServers(userId: string): void {
+        const serversRef = ref(db, `users/${userId}/servers`);
+        
+        this.unsubscribeServers = onValue(serversRef, (snapshot) => {
+            if (snapshot.exists()) {
+                const serversData = snapshot.val();
+                this.servers = Object.entries(serversData).map<IUserServer>(
+                    ([id, server]) => ({
+                        ...(server as IUserServer),
+                        id: id
+                    })
+                );
+                this.onServersChanged?.(this.servers);
+            } else {
+                this.servers = [];
+                this.onServersChanged?.([]);
+            }
+        }, (error) => {
+            console.error('Error listening to servers:', error);
+        });
+    }
+    
+    getServers(): IUserServer[] {
+        return this.servers;
+    }
+    
+    async getServersOnce(userId: string): Promise<IUserServer[]> {
+        const serversRef = ref(db, `users/${userId}/servers`);
+        const snapshot = await get(serversRef);
+        
+        if (!snapshot.exists()) {
+            return [];
+        }
+        
+        const serversData = snapshot.val();
+        return Object.entries(serversData).map<IUserServer>(
+            ([id, server]) => ({
+                ...(server as IUserServer),
+                id: id
+            })
+        );
+    }
+    
+    dispose(): void {
+        this.unsubscribeAuth?.();
+        this.unsubscribeServers?.();
+    }
+}
+
+// Usage
+const serverService = new FirebaseServerService((servers) => {
+    console.log('Servers updated:', servers);
+});
+
+// Get current servers
+const currentServers = serverService.getServers();
+
+// Cleanup when done
+// serverService.dispose();
+```
+
+## Summary
+
+To retrieve servers from Firebase:
+
+1. **Install Firebase SDK**: `npm install firebase`
+2. **Initialize Firebase**: Configure and initialize the Firebase app
+3. **Authenticate User**: Get the user's ID token
+4. **Access Database**: Create a reference to `users/{userId}/servers`
+5. **Retrieve Data**: Use `get()` for one-time reads or `onValue()` for real-time updates
+6. **Transform Data**: Convert the Firebase object structure to an array using `Object.entries()`
+7. **Handle Errors**: Implement proper error handling for network and permission issues
+
+The key pattern is converting Firebase's object structure (where keys are server IDs) to an array format suitable for application use.
+