Pre-Release (Version 0.3) - UI Preperations and fixes

Author: agamsol

README.md

@@ -1,5 +1,5 @@
-# Android SMS API Gateway 0.2 *(Pre-Release)*
-![Version](https://img.shields.io/badge/Version-0.2_(Pre--Release)-orange)
+# Android SMS API Gateway 0.3 *(Pre-Release)*
+![Version](https://img.shields.io/badge/Version-0.3_(Pre--Release)-orange)
 ![Python](https://img.shields.io/badge/Python-3.13+-blue?logo=python&logoColor=white)
 ![FastAPI](https://img.shields.io/badge/FastAPI-Powered-009688?logo=fastapi&logoColor=white)
 ![Maintained](https://img.shields.io/badge/Maintained-Yes-brightgreen)
@@ -30,7 +30,7 @@ This application transforms any Android device into a dedicated, self-hosted **S
     - [Trigger the QR Code](#trigger-the-qr-code)
     - [Pairing Instructions](#pairing-instructions)
     - [Verify Connection](#verify-connection)
-- [Whats New In 0.2](#whats-new-in-02-pre-release)
+- [Whats New In 0.3](#whats-new-in-03-pre-release)
 
 ---
 
@@ -280,19 +280,18 @@ After scanning, the pairing process completes automatically. You can confirm suc
 * Checking the terminal logs for a "Successfully Paired" message.
 * Calling the `GET /adb/list-devices` endpoint to verify your device appears with the status `authorized`.
 
-# What's New in 0.2 (Pre-release)
+# What's New in 0.3 (Pre-release)
 #### Features & Improvements
 
-- Added a new API route to support pairing devices via a 6-digit code, offering an alternative to QR code scanning.
+- Added a route to get and list all conversations on the device
 
-- Replaced the embedded ADB binary with the system-level android-tools-adb package. This improves stability and compatibility across different container environments.
+- Added a route to list all users
 
-#### Bug Fixes
-
-- Fixed major bugs that made delete-account endpoint not to work
+- `GET /auth/@me` now returns how many messages are left for the current month
 
-- Resolved connectivity issues preventing successful wireless device pairing in Dockerized environments.
+> **_P.S. Parts of this release are preperations for the UI Interface which is coming VERY soon!_**
 
-- Fixed an issue where remember_me tokens were not persisting correctly; tokens now utilize a 10-year expiration for long-term sessions.
+#### Bug Fixes
 
-- Corrected username validator logic and pattern. Usernames can now be 3–32 characters long, include numbers and hyphens (previously restricted to 10 characters maximum and no numbers were allowed).
+- Timeout handling for ADB `POST /adb/connect-device` - trace back to client
+- `device_id` was limited to 35 characters (raised to 99) - code pairing devices have longer names than 35 characters

build.cmd

@@ -1,2 +1,2 @@
 :: local use
-docker build --no-cache -t android-sms-api:0.2 -t android-sms-api:latest .
+docker build --no-cache -t android-sms-api:0.3 -t android-sms-api:latest .

models/adb.py

@@ -89,7 +89,7 @@ class AdbPairDeviceWithCodeRequest(BaseModel):
 
 
 class AdbConnectDeviceRequest(BaseModel):
-    device_id: str
+    device_id: Optional[str] = Field(None, min_length=4, max_length=99, description="The unique identifier (serial) of the Android device. If omitted, a random available device will be selected.", examples=[None])
 
 
 class AdbConnectDeviceResponse(AdbConnectDeviceRequest, AdbDetailResponse):
@@ -100,8 +100,7 @@ class AdbConnectDeviceResponse(AdbConnectDeviceRequest, AdbDetailResponse):
 # description="Must start with 05x (10 digits) or 9725x (12 digits). Allowed providers: 0,2,3,4,5,8."
 
 
-class AdbSendTextMessageRequest(BaseModel):
-    device_id: Optional[str] = Field(None, min_length=4, max_length=35, description="The unique identifier (serial) of the Android device. If omitted, a random available device will be selected.", examples=[None])
+class AdbSendTextMessageRequest(AdbConnectDeviceRequest):
     phone_number: str = Field(..., pattern=r"^\+[1-9]\d{1,14}$")
     message: str
 
@@ -122,3 +121,16 @@ class AdbProcessResult(BaseModel):
     returncode: int = Field(..., description="Exit status of the process (0 usually means success)")
     stdout: str = Field(..., description="Standard output from the command")
     stderr: str = Field(..., description="Standard error from the command")
+
+
+class AdbMessage(BaseModel):
+    id: str = Field(..., description="The unique message ID")
+    address: Optional[str] = Field(None, description="The phone number or address associated with the message")
+    body: str = Field(..., description="The content of the message")
+    date: Optional[int] = Field(None, description="The timestamp of the message")
+    type: Literal['sent', 'received', 'unknown'] = Field(..., description="The type of the message")
+
+
+class AdbConversation(BaseModel):
+    phone_number: str = Field(..., description="The phone number associated with the messages")
+    messages: list[AdbMessage] = Field(..., description="List of messages exchanged with this phone number")

models/authentication.py

@@ -56,6 +56,7 @@ def validate_password(cls, passwd: str) -> str:
 class AdditionalAccountData(BaseUser):
     messages_limit: int = 50
     administrator: bool = False
+    messages_left: Optional[int] = None
 
 
 class Token(BaseModel):
@@ -118,3 +119,14 @@ class MessageLimitUpdateResponse(AccountConfirmationResponse):
 
 class UpdateMessageLimitRequest(BaseUser):
     messages_limit: int = Field(50, ge=0, description="New monthly message limit for the user")
+
+
+class UserStats(BaseUser):
+    messages_limit: int
+    current_usage: int
+    administrator: bool
+
+
+class UserListResponse(BaseModel):
+    users: list[UserStats]
+

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Android-SMS-API"
-version = "0.2"
+version = "0.3"
 description = "Turn your Android phone into a programmable SMS server. A lightweight HTTP API wrapper around ADB for sending text messages over cellular network"
 readme = "README.md"
 requires-python = ">=3.13"

routes/adb.py

@@ -1,6 +1,7 @@
 import os
 import time
-from typing import Annotated
+import subprocess
+from typing import Annotated, Optional
 from dotenv import load_dotenv
 from utils.database import SQLiteDb
 from fastapi.responses import StreamingResponse
@@ -9,7 +10,7 @@
 from fastapi import Depends, HTTPException, status, APIRouter
 from utils.adb import Adb, DeviceUnavailable, DeviceConnectionError
 from routes.authentication import authenticate_with_token, AdditionalAccountData, MUST_BE_ADMINISTRATOR_EXCEPTION
-from models.adb import AdbListDevices, AdbDetailResponse, AdbConnectDeviceRequest, AdbConnectDeviceResponse, AdbSendTextMessageRequest, AdbMessageSentResponse, AdbShellExecuteRequest, AdbProcessResult, AdbPairDeviceWithCodeRequest, execution_route_enabled, ADB_QR_PAIRING_INSTRUCTIONS, ADB_PAIRING_INSTRUCTIONS
+from models.adb import AdbListDevices, AdbDetailResponse, AdbConnectDeviceRequest, AdbConnectDeviceResponse, AdbSendTextMessageRequest, AdbMessageSentResponse, AdbShellExecuteRequest, AdbProcessResult, AdbPairDeviceWithCodeRequest, execution_route_enabled, ADB_QR_PAIRING_INSTRUCTIONS, ADB_PAIRING_INSTRUCTIONS, AdbMessage, AdbConversation
 
 load_dotenv()
 
@@ -45,6 +46,25 @@ async def adb_list_devices(
     return devices_list
 
 
+@router.get(
+    "/list-messages",
+    summary="List all SMS messages from a connected device",
+    status_code=status.HTTP_200_OK,
+    response_model=list[AdbConversation]
+)
+async def adb_list_messages(
+    account: Annotated[AdditionalAccountData, Depends(authenticate_with_token)],
+    device_id: Optional[str] = None
+):
+
+    if not account.administrator:
+        raise MUST_BE_ADMINISTRATOR_EXCEPTION
+
+    messages = await adb.list_messages(device_id=device_id)
+
+    return messages
+
+
 @router.get(
     "/qr-pair-device",
     summary="Pairing a new Android device over the network via QR code",
@@ -134,17 +154,24 @@ async def adb_connect_device(
 
     response_detail = "ADB Error while connecting to device!"
 
-    device = await adb.connect_device(body.device_id)
+    try:
+        device = await adb.connect_device(body.device_id)
 
-    if "connected" in device.stdout or "already" in device.stdout:
+        if "connected" in device.stdout or "already" in device.stdout:
 
-        response_detail = "ADB is now connected to device"
+            response_detail = "ADB is now connected to device"
 
-    return AdbConnectDeviceResponse(
-        detail=response_detail,
-        device_id=body.device_id,
-        adb_output=device.stdout
-    )
+        return AdbConnectDeviceResponse(
+            detail=response_detail,
+            device_id=body.device_id,
+            adb_output=device.stdout
+        )
+
+    except subprocess.TimeoutExpired:
+        raise HTTPException(
+            status_code=status.HTTP_504_GATEWAY_TIMEOUT,
+            detail="The connection attempt to the device timed out."
+        )
 
 
 @router.post(

routes/authentication.py

@@ -3,7 +3,7 @@
 from typing import Annotated
 from fastapi import Depends, HTTPException, status, APIRouter
 from fastapi.security import OAuth2PasswordBearer
-from models.authentication import CreateUser, Token, AdditionalAccountData, CreateUserParams, LoginObtainToken, login_obtain_token, AccountConfirmationResponse, BaseUser, MUST_BE_ADMINISTRATOR_EXCEPTION, ResetAccountPasswordRequest, UpdateMessageLimitRequest, MessageLimitUpdateResponse, generate_random_password
+from models.authentication import CreateUser, Token, AdditionalAccountData, CreateUserParams, LoginObtainToken, login_obtain_token, AccountConfirmationResponse, BaseUser, MUST_BE_ADMINISTRATOR_EXCEPTION, ResetAccountPasswordRequest, UpdateMessageLimitRequest, MessageLimitUpdateResponse, generate_random_password, UserListResponse, UserStats
 from utils.models.database import User_Model
 from utils.database import SQLiteDb
 from utils.secure import JWToken, Hash
@@ -62,8 +62,13 @@ async def authenticate_with_token(
     if user is None:
         raise credentials_exception
 
+    messages_count = db_helper.count_messages(user['username'])
+
+    messages_left = user['messages_limit'] - messages_count
+
     return AdditionalAccountData(
-        **user
+        **user,
+        messages_left=messages_left
     )
 
 
@@ -80,6 +85,45 @@ async def get_current_user(
     return current_user
 
 
+@router.get(
+    "/list-users",
+    response_model=UserListResponse,
+    status_code=status.HTTP_200_OK,
+    tags=["Account Management"]
+)
+async def list_users(
+    token: Annotated[AdditionalAccountData, Depends(authenticate_with_token)]
+):
+
+    if not token.administrator:
+        raise MUST_BE_ADMINISTRATOR_EXCEPTION
+
+    users = db_helper.get_all_users()
+    user_stats_list = []
+
+    user_stats_list.append(UserStats(
+        username=ADMIN_USERNAME,
+        messages_limit=0,
+        current_usage=db_helper.count_messages(ADMIN_USERNAME),
+        administrator=True
+    ))
+
+    for user in users:
+
+        usage = db_helper.count_messages(user['username'])
+
+        user_stats = UserStats(
+            username=user['username'],
+            messages_limit=user['messages_limit'],
+            current_usage=usage,
+            administrator=user['administrator']
+        )
+
+        user_stats_list.append(user_stats)
+    
+    return UserListResponse(users=user_stats_list)
+
+
 @router.post(
     "/login",
     response_model=Token,

utils/adb.py

@@ -4,6 +4,7 @@
 import shutil
 import subprocess
 from typing import Optional
+from collections import defaultdict
 from pydantic import IPvAnyAddress
 from utils.logger import create_logger
 
@@ -243,3 +244,70 @@ async def send_text_message(self, phone_number: str, message: str, device_name:
 
         log.error(f"SMS command failed. Device: {device_name}, Output: {parcel.stdout.strip()}")
         return False, str(device_name)
+
+    async def list_messages(self, device_id: Optional[str] = None) -> list[dict]:
+
+        log.debug(f"Listing messages for device: {device_id}")
+
+        command = []
+        if device_id:
+            command.extend(["-s", device_id])
+
+        command.extend(["shell", "content", "query", "--uri", "content://sms/", "--projection", "_id:address:body:date:type"])
+
+        process = await self.adb_execute(command)
+
+        if process.returncode != 0:
+            log.error(f"Failed to list messages. Output: {process.stderr}")
+            return []
+
+        output = process.stdout
+        grouped_messages = defaultdict(list)
+        row_pattern = re.compile(r"Row: \d+ (.*)")
+
+        for line in output.strip().split('\n'):
+            match = row_pattern.search(line)
+            if not match: continue
+
+            fields_str = match.group(1)
+            parts = re.split(r', (?=\w+=)', fields_str)
+
+            row_data = {}
+            for part in parts:
+                if '=' in part:
+                    key, val = part.split('=', 1)
+                    row_data[key.strip()] = val.strip()
+
+            msg_type = row_data.get('type', '1')
+            if msg_type == '1':
+                msg_type_str = 'received'
+            elif msg_type == '2':
+                msg_type_str = 'sent'
+            else:
+                msg_type_str = 'unknown'
+
+            try:
+                date_val = int(row_data.get('date', 0))
+            except ValueError:
+                date_val = None
+
+            msg_entry = {
+                "type": msg_type_str,
+                "body": row_data.get('body', ''),
+                "date": date_val,
+                "id": row_data.get('_id'),
+                "address": row_data.get('address')
+            }
+            address = row_data.get('address', 'Unknown')
+            grouped_messages[address].append(msg_entry)
+
+        conversations = []
+        for address, msgs in grouped_messages.items():
+
+            msgs.sort(key=lambda x: x['date'] or 0)
+            conversations.append({
+                "phone_number": address,
+                "messages": msgs
+            })
+
+        return conversations

utils/database.py

@@ -103,6 +103,14 @@ def get_user(self, username: str):
 
         return query
 
+    def get_all_users(self):
+
+        log.debug("Fetching all users")
+        cursor = self.conn.cursor()
+        cursor.execute(f"SELECT * FROM {self.users_table_name}")
+
+        return cursor.fetchall()
+
     def insert_user(self, user_model: User_Model):
 
         data = user_model.model_dump(mode="json")