Add comprehensive SSID validation and improve authentication error messages

Co-authored-by: theshadow76 <59869868+theshadow76@users.noreply.github.com>

Author: Copilot

README.md

@@ -73,9 +73,39 @@ Example SSID format:
 
 If you are unable to find it, try running the automatic SSID scraper under the `tools` folder.
 
-## Comon errors
+## Common errors
 
-### Traceback:
+### Authentication timeout or connection immediately closes
+
+If you see errors like:
+```
+WARNING | pocketoptionapi_async.websocket_client:receive_messages:395 - WebSocket connection closed
+WARNING | pocketoptionapi_async.client:_start_regular_connection:245 - Failed to connect to region DEMO: Authentication timeout
+```
+
+**Solution**: Your SSID is likely in the wrong format or is expired. Make sure you are using the **complete SSID format**, not just the session ID:
+
+✅ **Correct format:**
+```python
+SSID = '42["auth",{"session":"n1p5ah5u8t9438rbunpgrq0hlq","isDemo":1,"uid":84402008,"platform":1}]'
+```
+
+❌ **Wrong format (just the session):**
+```python
+SSID = 'dxxxxxxxxxxxxxxxxxxxxxxxxxxxx'  # This won't work!
+```
+
+To get the correct SSID:
+1. Open PocketOption in your browser
+2. Open Developer Tools (F12)
+3. Go to Network tab
+4. Filter by "WS" (WebSocket)
+5. Look for a message that starts with `42["auth",`
+6. Copy the **entire message** including the `42["auth",{...}]` part
+
+### Websockets version error
+
+## Traceback:
 ```
 2025-07-13 15:25:16.531 | INFO     | pocketoptionapi_async.client:__init__:130 - Initialized PocketOption client (demo=True, uid=105754921, persistent=False) with enhanced monitoring
 2025-07-13 15:25:16.532 | INFO     | pocketoptionapi_async.client:connect:162 - Connecting to PocketOption...

pocketoptionapi_async/client.py

@@ -78,14 +78,10 @@ def __init__(
         if not enable_logging:
             logger.remove()
             logger.add(lambda msg: None, level="CRITICAL")  # Disable most logging
-        # Parse SSID if it's a complete auth message
+        
+        # Validate and parse SSID
         self._original_demo = None  # Store original demo value from SSID
-        if ssid.startswith('42["auth",'):
-            self._parse_complete_ssid(ssid)
-        else:
-            # Treat as raw session ID
-            self.session_id = ssid
-            self._complete_ssid = None
+        self._validate_and_parse_ssid(ssid)
 
         # Core components
         self._websocket = AsyncWebSocketClient()
@@ -656,6 +652,39 @@ def get_connection_stats(self) -> Dict[str, Any]:
 
         return stats  # Private methods
 
+    def _validate_and_parse_ssid(self, ssid: str) -> None:
+        """Validate and parse SSID format"""
+        if not ssid or not isinstance(ssid, str):
+            raise InvalidParameterError(
+                "SSID must be a non-empty string. "
+                "Expected format: 42[\"auth\",{\"session\":\"...\",\"isDemo\":1,\"uid\":0,\"platform\":1}]"
+            )
+        
+        ssid = ssid.strip()
+        
+        # Check if it's a complete SSID format
+        if ssid.startswith('42["auth",'):
+            self._parse_complete_ssid(ssid)
+            # Validate that we got a session ID
+            if not self.session_id or len(self.session_id) < 10:
+                raise InvalidParameterError(
+                    f"Invalid SSID format - session ID is too short or missing. "
+                    f"Please ensure your SSID is in the correct format: "
+                    f"42[\"auth\",{{\"session\":\"your_session_id\",\"isDemo\":1,\"uid\":12345,\"platform\":1}}]. "
+                    f"You can get this from browser DevTools (F12) -> Network tab -> WS filter -> "
+                    f"look for authentication message starting with 42[\"auth\","
+                )
+        else:
+            # Treat as raw session ID
+            if len(ssid) < 10:
+                logger.warning(
+                    f"Raw session ID appears to be too short ({len(ssid)} chars). "
+                    f"If you're having connection issues, please use the complete SSID format: "
+                    f"42[\"auth\",{{\"session\":\"your_session\",\"isDemo\":1,\"uid\":12345,\"platform\":1}}]"
+                )
+            self.session_id = ssid
+            self._complete_ssid = None
+
     def _format_session_message(self) -> str:
         """Format session authentication message"""
         # Always create auth message from components using constructor parameters
@@ -683,41 +712,80 @@ def _parse_complete_ssid(self, ssid: str) -> None:
                 data = json.loads(json_part)
 
                 self.session_id = data.get("session", "")
+                if not self.session_id:
+                    raise InvalidParameterError(
+                        "SSID is missing the 'session' field. "
+                        "Expected format: 42[\"auth\",{\"session\":\"your_session\",\"isDemo\":1,\"uid\":12345,\"platform\":1}]"
+                    )
+                
                 # Store original demo value from SSID, but don't override the constructor parameter
                 self._original_demo = bool(data.get("isDemo", 1))
                 # Keep the is_demo value from constructor - don't override it
                 self.uid = data.get("uid", 0)
                 self.platform = data.get("platform", 1)
                 # Don't store complete SSID - we'll reconstruct it with correct demo value
                 self._complete_ssid = None
+            else:
+                raise InvalidParameterError(
+                    "Could not parse SSID - JSON object not found. "
+                    "Expected format: 42[\"auth\",{\"session\":\"your_session\",\"isDemo\":1,\"uid\":12345,\"platform\":1}]"
+                )
+        except json.JSONDecodeError as e:
+            raise InvalidParameterError(
+                f"Invalid SSID format - JSON parsing failed: {e}. "
+                f"Expected format: 42[\"auth\",{{\"session\":\"your_session\",\"isDemo\":1,\"uid\":12345,\"platform\":1}}]"
+            )
+        except InvalidParameterError:
+            raise  # Re-raise our custom errors
         except Exception as e:
-            logger.warning(f"Failed to parse SSID: {e}")
-            self.session_id = ssid
-            self._complete_ssid = None
+            raise InvalidParameterError(
+                f"Failed to parse SSID: {e}. "
+                f"Expected format: 42[\"auth\",{{\"session\":\"your_session\",\"isDemo\":1,\"uid\":12345,\"platform\":1}}]"
+            )
 
     async def _wait_for_authentication(self, timeout: float = 10.0) -> None:
         """Wait for authentication to complete (like old API)"""
         auth_received = False
+        auth_error = None
 
         def on_auth(data):
             nonlocal auth_received
             auth_received = True
+        
+        def on_auth_error(data):
+            nonlocal auth_error
+            auth_error = data.get("message", "Unknown authentication error")
 
-        # Add temporary handler
+        # Add temporary handlers
         self._websocket.add_event_handler("authenticated", on_auth)
+        self._websocket.add_event_handler("auth_error", on_auth_error)
 
         try:
             # Wait for authentication
             start_time = time.time()
-            while not auth_received and (time.time() - start_time) < timeout:
+            while not auth_received and not auth_error and (time.time() - start_time) < timeout:
                 await asyncio.sleep(0.1)
 
+            if auth_error:
+                raise AuthenticationError(
+                    f"Authentication failed: {auth_error}. "
+                    f"Please verify your SSID is correct. "
+                    f"SSID should be in format: 42[\"auth\",{{\"session\":\"your_session\",\"isDemo\":1,\"uid\":12345,\"platform\":1}}]. "
+                    f"Get it from browser DevTools (F12) -> Network tab -> WS filter -> look for message starting with 42[\"auth\","
+                )
+            
             if not auth_received:
-                raise AuthenticationError("Authentication timeout")
+                raise AuthenticationError(
+                    "Authentication timeout - server did not respond to authentication request. "
+                    "This usually means your SSID is invalid or expired. "
+                    "Please get a fresh SSID from browser DevTools (F12) -> Network tab -> WS filter -> "
+                    "look for authentication message starting with 42[\"auth\",{\"session\":\"...\",..."
+                )
 
         finally:
-            # Remove temporary handler
+            # Remove temporary handlers
             self._websocket.remove_event_handler("authenticated", on_auth)
+            self._websocket.remove_event_handler("auth_error", on_auth_error)
 
     async def _initialize_data(self) -> None:
         """Initialize client data after connection"""

pocketoptionapi_async/websocket_client.py

@@ -582,8 +582,11 @@ async def _process_message(self, message) -> None:
                 await self._handle_json_message(data)
 
             elif message.startswith("42") and "NotAuthorized" in message:
-                logger.error("Authentication failed: Invalid SSID")
-                await self._emit_event("auth_error", {"message": "Invalid SSID"})
+                logger.error(
+                    "Authentication failed: Server rejected SSID. "
+                    "Please verify your SSID is correct and not expired."
+                )
+                await self._emit_event("auth_error", {"message": "Invalid or expired SSID - Server returned NotAuthorized"})
 
         except Exception as e:
             logger.error(f"Error processing message: {e}")
@@ -611,8 +614,11 @@ async def _handle_json_message_wrapper(self, message: str) -> None:
     async def _handle_auth_message(self, message: str) -> None:
         """Handle authentication message"""
         if "NotAuthorized" in message:
-            logger.error("Authentication failed: Invalid SSID")
-            await self._emit_event("auth_error", {"message": "Invalid SSID"})
+            logger.error(
+                "Authentication failed: Server rejected SSID. "
+                "Please verify your SSID is correct and not expired."
+            )
+            await self._emit_event("auth_error", {"message": "Invalid or expired SSID - Server returned NotAuthorized"})
 
     async def _process_message_optimized(self, message) -> None:
         """