Fix compatibility with latest MajSoul server config format

README.md

@@ -4,32 +4,95 @@ Python wrappers for Majsoul allow you to interact with their servers from Python
 
 ## For User
 
-1. Install python packages from `requirements.txt`
-2. `python example.py -u username -p password`
+### Installation
 
-This example is working only with **Python3.9+**.
+1. Install Python 3.9 or higher
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
 
-Also, you need to have an account from CN server to run this example, because only accounts from CN server has the ability to login with login and password.
+### Usage
 
-If you want to login to EN or JP servers you need to write your code to authenticate via email code or social network. Protobuf wrapper from this repository contains all needed API objects for that.
+#### Login with username and password (CN server)
+
+```bash
+python example.py -u <username> -p <password>
+```
+
+#### Login with email verification code (EN/JP server)
+
+See `example.py` for reference on how to use email login.
+
+#### Fetch game records
+
+```bash
+python example.py -u <username> -p <password> -l <game_uuid>
+```
+
+### API Example
+
+```python
+import asyncio
+from ms.base import MSRPCChannel
+from ms.rpc import Lobby
+import ms.protocol_pb2 as pb
+
+async def main():
+    # Connect to server
+    channel = MSRPCChannel("wss://route-2.maj-soul.com/gateway")
+    await channel.connect("https://game.maj-soul.com")
+
+    lobby = Lobby(channel)
+
+    # Login
+    req = pb.ReqLogin()
+    req.account = "your_username"
+    req.password = "your_password_hash"
+    req.device.is_browser = True
+    req.gen_access_token = True
+
+    res = await lobby.login(req)
+    print(f"Account ID: {res.account_id}")
+    print(f"Nickname: {res.account.nickname}")
+
+    # Fetch account info
+    req_info = pb.ReqAccountInfo()
+    res_info = await lobby.fetch_account_info(req_info)
+    print(f"Level: {res_info.account.level}")
+
+    await channel.close()
+
+asyncio.run(main())
+```
+
+### Server Support
+
+| Server | Login Method | Notes |
+|--------|-------------|-------|
+| CN (中国) | Username + Password | Primary method |
+| EN (International) | Email verification | Requires email code |
+| JP (日本) | Email verification | Requires email code |
+
+**Note:** Only CN server accounts can use username/password login. EN/JP server accounts require email verification or OAuth2 login.
 
 ## For Developer
 
 ### Requirements
 
-1. Install python packages from `requerements.txt`
-1. Install protobuf compiler `sudo apt install protobuf-compiler`
+1. Install Python packages from `requirements.txt`
+2. Install protobuf compiler: `sudo apt install protobuf-compiler`
 
 ### How to update protocol files to the new version
 
-It was tested on Ubuntu.
+Tested on Ubuntu:
 
 1. Download the new `liqi.json` file from MS (find it in the network tab of your browser) and put it to `ms/liqi.json`
-1. `python generate_proto_file.py`
-1. `protoc --python_out=. protocol.proto`
-1. `chmod +x ms-plugin.py`
-1. `sudo cp ms-plugin.py /usr/bin/ms-plugin.py`
-1. `protoc --custom_out=. --plugin=protoc-gen-custom=ms-plugin.py ./protocol.proto`
+2. `python generate_proto_file.py`
+3. `protoc --python_out=. protocol.proto`
+4. `chmod +x ms-plugin.py`
+5. `sudo cp ms-plugin.py /usr/bin/ms-plugin.py`
+6. `protoc --custom_out=. --plugin=protoc-gen-custom=ms-plugin.py ./protocol.proto`
 
 ### How to release new version
 

example.py

@@ -63,7 +63,18 @@ async def connect():
             config = await res.json()
             logging.info(f"Config: {config}")
 
-            url = config["ip"][0]["region_urls"][1]["url"]
+            # Support both old and new config formats
+            ip_info = config["ip"][0]
+            if "region_urls" in ip_info:
+                # Old format: use region_urls
+                url = ip_info["region_urls"][1]["url"]
+            else:
+                # New format: use gateways
+                gateways = ip_info.get("gateways", [])
+                if gateways:
+                    url = gateways[0]["url"]
+                else:
+                    url = ip_info.get("system_email_url", "")
 
         async with session.get(url + "?service=ws-gateway&protocol=ws&ssl=true") as res:
             servers = await res.json()
@@ -99,12 +110,15 @@ async def login(lobby, username, password, version_to_force):
     req.currency_platforms.append(2)
 
     res = await lobby.login(req)
-    token = res.access_token
-    if not token:
+
+    if res.HasField("error") and res.error.code != 0:
         logging.error("Login Error:")
-        logging.error(res)
+        logging.error(res.error)
         return False
 
+    token = res.access_token
+    logging.info(f"Login successful! Account ID: {res.account_id}, Nickname: {res.account.nickname}")
+
     return True
 
 

requirements.txt

@@ -1,3 +1,6 @@
-protobuf==4.22.3
-websockets==15.0.1
-aiohttp==3.9.0
+# Mahjong Soul API dependencies
+# Requires Python 3.9+
+
+protobuf>=4.22.3
+websockets>=15.0.1
+aiohttp>=3.11.0  # Pre-built wheels for Python 3.9+