feat: add battery_replaced_timestamp property to Tile

README.md

@@ -119,6 +119,7 @@ The Tile object comes with several properties:
 - `accuracy`: the location accuracy of the Tile
 - `altitude`: the altitude of the Tile
 - `archetype`: the internal reference string that describes the Tile's "family"
+- `battery_replaced_timestamp`: the timestamp at which the Tile's battery was last replaced
 - `battery_status`: the Tile's battery status (e.g., `NONE`, `LEVEL1`, `LEVEL2`)
 - `dead`: whether the Tile is inactive
 - `firmware_version`: the Tile's firmware version

pytile/tile.py

@@ -69,6 +69,22 @@ def archetype(self) -> str:
         """
         return cast(str, self._tile_data["result"]["archetype"])
 
+    @property
+    def battery_replaced_timestamp(self) -> datetime | None:
+        """Return the timestamp at which the Tile's battery was last replaced.
+
+        Only Tiles with a user-replaceable battery that has been replaced carry this.
+
+        Returns:
+            The timestamp (if it exists).
+        """
+        metadata = self._tile_data["result"].get("metadata") or {}
+        if (replaced_at := metadata.get("battery_replaced_at")) is None:
+            return None
+        return datetime.fromtimestamp(int(replaced_at) / 1000, tz=timezone.utc).replace(
+            tzinfo=None
+        )
+
     @property
     def battery_status(self) -> str | None:
         """Return the battery status.
@@ -250,6 +266,7 @@ def as_dict(self) -> dict[str, Any]:
             "accuracy": self.accuracy,
             "altitude": self.altitude,
             "archetype": self.archetype,
+            "battery_replaced_timestamp": self.battery_replaced_timestamp,
             "battery_status": self.battery_status,
             "dead": self.dead,
             "firmware_version": self.firmware_version,

tests/fixtures/tile_details_response.json

@@ -76,7 +76,8 @@
     "auth_key": "xxxxxxxxxxxxxxxxxxxxxxxx",
     "renewal_status": "NONE",
     "metadata": {
-      "battery_state": "10"
+      "battery_state": "10",
+      "battery_replaced_at": "1590969600000"
     },
     "battery_status": "NONE",
     "serial_number": null,

tests/test_tile.py

@@ -125,6 +125,7 @@ async def test_get_tiles(
             assert tile.accuracy == 13.496111
             assert tile.altitude == 0.4076319168123
             assert tile.archetype == "WALLET"
+            assert tile.battery_replaced_timestamp == datetime(2020, 6, 1, 0, 0)
             assert tile.battery_status == "NONE"
             assert not tile.dead
             assert not tile.lost
@@ -237,6 +238,7 @@ async def test_missing_last_tile_state(
             tile = tiles[TILE_TILE_UUID]
             assert not tile.accuracy
             assert not tile.altitude
+            assert not tile.battery_replaced_timestamp
             assert not tile.last_timestamp
             assert not tile.latitude
             assert not tile.longitude
@@ -296,6 +298,7 @@ async def test_tile_as_dict(
                 "accuracy": 13.496111,
                 "altitude": 0.4076319168123,
                 "archetype": "WALLET",
+                "battery_replaced_timestamp": datetime(2020, 6, 1, 0, 0),
                 "battery_status": "NONE",
                 "dead": False,
                 "firmware_version": "01.12.14.0",