Add support for option lock message

Author: devinslick

README.md

@@ -121,6 +121,25 @@ Tips:
   - `await device.refresh()` → hydrate cached state
   - `await device.get_location()` → parsed last location
   - `await device.fetch_pictures(n)` + `await device.download_photo(item)`
+  - Commands: `await device.play_sound()`, `await device.take_front_photo()`,
+    `await device.take_rear_photo()`, `await device.lock(message=None)`,
+    `await device.wipe(confirm=True)`
+
+### Example: Lock device with a message
+
+```python
+import asyncio
+from fmd_api import FmdClient, Device
+
+async def main():
+  client = await FmdClient.create("https://fmd.example.com", "alice", "secret")
+  device = Device(client, "alice")
+  # Optional message is sanitized (quotes/newlines removed, whitespace collapsed)
+  await device.lock(message="Lost phone. Please call +1-555-1234")
+  await client.close()
+
+asyncio.run(main())
+```
 
 ## Testing
 

docs/MIGRATE_FROM_V1.md

@@ -75,6 +75,8 @@ client = await FmdClient.create("https://fmd.example.com", "alice", "secret")
 |----|----------------|-------------|-------|
 | `await api.take_picture('back')` | `await client.take_picture('back')` | `await device.take_rear_photo()` | Device method preferred |
 | `await api.take_picture('front')` | `await client.take_picture('front')` | `await device.take_front_photo()` | Device method preferred |
+> Note: `Device.lock(message=None)` now supports passing an optional message string. The server may ignore the
+> message if UI or server versions don't yet consume it, but the base lock command will still be executed.
 
 ### Bluetooth & Audio Settings
 

fmd_api/device.py

@@ -109,10 +109,29 @@ async def download_photo(self, picture_blob_b64: str) -> PhotoResult:
             raise OperationError(f"Failed to decode picture blob: {e}") from e
 
     async def lock(self, message: Optional[str] = None, passcode: Optional[str] = None) -> bool:
-        # The original API supports "lock" command; it does not carry message/passcode in the current client
-        # Implementation preserves original behavior (sends "lock" command).
-        # Extensions can append data if server supports it.
-        return await self.client.send_command("lock")
+        """Lock the device, optionally passing a message (and future passcode).
+
+        Notes:
+        - The public web UI may not expose message/passcode yet, but protocol-level
+          support is expected. We optimistically send a formatted command if a message
+          is provided: "lock <escaped>".
+        - Sanitization: collapse whitespace, limit length, and strip unsafe characters.
+        - If server ignores the payload, the base "lock" still executes.
+        - Passcode argument reserved for potential future support; currently unused.
+        """
+        base = "lock"
+        if message:
+            # Basic sanitization: trim, collapse internal whitespace, remove newlines
+            sanitized = " ".join(message.strip().split())
+            # Remove characters that could break command parsing (quotes/backticks/semicolons)
+            for ch in ['"', "'", "`", ";"]:
+                sanitized = sanitized.replace(ch, "")
+            # Cap length to 120 chars to avoid overly long command payloads
+            if len(sanitized) > 120:
+                sanitized = sanitized[:120]
+            if sanitized:
+                base = f"lock {sanitized}"
+        return await self.client.send_command(base)
 
     async def wipe(self, confirm: bool = False) -> bool:
         if not confirm:

tests/functional/test_commands.py

@@ -5,7 +5,7 @@
 
 Commands:
   ring                    - Make device ring
-  lock                    - Lock device screen
+    lock [message...]       - Lock device screen (optional message)
   camera <front|back>     - Take picture (default: back)
   bluetooth <on|off>      - Set Bluetooth on/off
   dnd <on|off>           - Set Do Not Disturb on/off
@@ -53,7 +53,18 @@ async def main():
             print(f"Ring command sent: {result}")
 
         elif command == "lock":
-            result = await client.send_command("lock")
+            # Optional message; sanitize similar to Device.lock
+            msg = " ".join(sys.argv[2:]) if len(sys.argv) > 2 else None
+            cmd = "lock"
+            if msg:
+                sanitized = " ".join(msg.strip().split())
+                for ch in ['"', "'", "`", ";"]:
+                    sanitized = sanitized.replace(ch, "")
+                if len(sanitized) > 120:
+                    sanitized = sanitized[:120]
+                if sanitized:
+                    cmd = f"lock {sanitized}"
+            result = await client.send_command(cmd)
             print(f"Lock command sent: {result}")
 
         elif command == "camera":

tests/unit/test_lock_message.py

@@ -0,0 +1,71 @@
+import pytest
+from aioresponses import aioresponses, CallbackResult
+
+from fmd_api.client import FmdClient
+from fmd_api.device import Device
+
+
+@pytest.mark.asyncio
+async def test_device_lock_without_message_sends_plain_lock():
+    client = FmdClient("https://fmd.example.com")
+    client.access_token = "token"
+
+    class DummySigner:
+        def sign(self, message_bytes, pad, algo):
+            return b"\xab" * 64
+
+    client.private_key = DummySigner()
+
+    await client._ensure_session()
+    device = Device(client, "test-device")
+
+    with aioresponses() as m:
+        # capture payload via callback
+        captured = {}
+
+        def cb(url, **kwargs):
+            captured["json"] = kwargs.get("json")
+            return CallbackResult(status=200, body="OK")
+
+        m.post("https://fmd.example.com/api/v1/command", callback=cb)
+        try:
+            ok = await device.lock()
+            assert ok is True
+            assert captured["json"]["Data"] == "lock"
+        finally:
+            await client.close()
+
+
+@pytest.mark.asyncio
+async def test_device_lock_with_message_sanitizes_and_sends():
+    client = FmdClient("https://fmd.example.com")
+    client.access_token = "token"
+
+    class DummySigner:
+        def sign(self, message_bytes, pad, algo):
+            return b"\xab" * 64
+
+    client.private_key = DummySigner()
+
+    await client._ensure_session()
+    device = Device(client, "test-device")
+
+    with aioresponses() as m:
+        captured = {}
+
+        def cb(url, **kwargs):
+            captured["json"] = kwargs.get("json")
+            return CallbackResult(status=200, body="OK")
+
+        m.post("https://fmd.example.com/api/v1/command", callback=cb)
+        try:
+            ok = await device.lock("  Hello   world; \n stay 'safe' \"pls\"  ")
+            assert ok is True
+            sent = captured["json"]["Data"]
+            assert sent.startswith("lock ")
+            # Ensure removed quotes/semicolons/newlines and collapsed spaces
+            assert '"' not in sent and "'" not in sent and ";" not in sent and "\n" not in sent
+            assert "  " not in sent
+            assert sent.endswith("Hello world stay safe pls")
+        finally:
+            await client.close()