unstrap 0.1.0__tar.gz

unstrap-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Real watch captures contain personal data (GPS, health). Never commit.
+fixtures/capture-*/
+data/
+
+# Build / tooling
+node_modules/
+.venv/
+.wrangler/
+dist/
+target/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+.claude/settings.local.json
+.tools/
+.dev.vars

unstrap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SweatStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unstrap-0.1.0/Makefile

@@ -0,0 +1,15 @@
+# Client (Python). `check` runs on the oldest and newest supported Python.
+PYTHONS ?= 3.10 3.14
+export UV_PYTHON_PREFERENCE := only-managed
+.PHONY: check lint test
+
+check: lint
+	@for py in $(PYTHONS); do \
+	  echo "== pytest on Python $$py"; \
+	  uv run --python $$py --isolated --group dev pytest || exit 1; \
+	done
+
+lint:
+	uv run --group dev ruff check .
+	uv run --group dev ruff format --check .
+	uv run --group dev mypy

unstrap-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: unstrap
+Version: 0.1.0
+Summary: Your watch data, set free. Copies everything your Garmin watch records, straight off the watch over USB.
+Author: SweatStack
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28
+Description-Content-Type: text/markdown
+
+# unstrap
+
+Your watch data, set free. Plug in your Garmin watch and run:
+
+```sh
+uvx unstrap
+```
+
+See the project README for how it works.

unstrap-0.1.0/README.md

@@ -0,0 +1,9 @@
+# unstrap
+
+Your watch data, set free. Plug in your Garmin watch and run:
+
+```sh
+uvx unstrap
+```
+
+See the project README for how it works.

unstrap-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "unstrap"
+version = "0.1.0"
+description = "Your watch data, set free. Copies everything your Garmin watch records, straight off the watch over USB."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "SweatStack" }]
+classifiers = [
+  "Environment :: Console",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+]
+dependencies = ["httpx>=0.28,<1"]
+
+[project.scripts]
+unstrap = "unstrap.cli:main"
+
+[build-system]
+# <1.32: hatchling 1.32 writes Metadata-Version 2.5, which the PyPI publish action's twine rejects.
+requires = ["hatchling>=1.27,<1.32"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.13", "mypy>=1.18", "unstrap-synth", "jsonschema>=4.23", "types-jsonschema"]
+
+[tool.uv.sources]
+unstrap-synth = { path = "../fixtures/synth", editable = true }
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "PL", "PT"]
+ignore = ["PLR2004"]
+
+[tool.ruff.lint.per-file-ignores]
+# A test double that mirrors a CLI's whole command surface in one dispatcher.
+"tests/fake_mtp_rs.py" = ["PLR0912", "PLR0915"]
+"tests/fake_server.py" = ["PLR0911", "PLR0912"]
+
+[tool.ruff.lint.pylint]
+# Keyword-only parameters and early-return error mapping read fine at these sizes.
+max-args = 8
+max-returns = 10
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

unstrap-0.1.0/schema/report.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unstrap.sweatstack.no/schema/report.json",
+  "title": "unstrap sync --json report",
+  "description": "Machine-readable result of one sync (consumed by e.g. the Raspberry Pi box). Additive changes only.",
+  "type": "object",
+  "required": [
+    "unit_id",
+    "usb_serial",
+    "listed",
+    "read",
+    "uploaded",
+    "uploaded_bytes",
+    "store",
+    "status",
+    "store_status",
+    "unrecorded",
+    "errors",
+    "seconds",
+    "changed"
+  ],
+  "properties": {
+    "unit_id": {
+      "type": "string",
+      "pattern": "^[0-9]{1,10}$"
+    },
+    "usb_serial": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{12}$"
+    },
+    "product": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "listed": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "read": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "uploaded": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "uploaded_bytes": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "store": {
+      "enum": [
+        "new",
+        "existing"
+      ]
+    },
+    "status": {
+      "enum": [
+        "ok",
+        "partial"
+      ]
+    },
+    "store_status": {
+      "enum": [
+        "claimed",
+        "unclaimed"
+      ]
+    },
+    "owner_hint": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "retention_days": {
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "unrecorded": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "saved": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "seconds": {
+      "type": "number",
+      "minimum": 0
+    },
+    "changed": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Mutable files rewritten on the watch during the sync; included next time."
+    }
+  },
+  "additionalProperties": false
+}

unstrap-0.1.0/src/unstrap/__init__.py

@@ -0,0 +1,3 @@
+"""Unstrap: copy Garmin watch data off the watch over USB (MTP) and upload it."""
+
+__version__ = "0.1.0"

unstrap-0.1.0/src/unstrap/api.py

@@ -0,0 +1,186 @@
+"""HTTP client for the Unstrap sync API (plan §4). Retries only what is safe to retry."""
+
+from __future__ import annotations
+
+import platform
+import random
+import time
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from unstrap import __version__
+from unstrap.transport import DeviceInfo, RemoteFile
+
+DEFAULT_SERVER = "https://unstrap.sweatstack.no"
+MAX_ATTEMPTS = 5
+
+
+class ApiError(Exception):
+    """The server said no. `message` is meant for people and is printed as-is."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+
+
+class ClientTooOld(ApiError):
+    pass
+
+
+class ServerUnreachable(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class HashedFile:
+    path: str
+    size: int
+    sha256: str
+
+    def as_json(self) -> dict[str, Any]:
+        return {"path": self.path, "size": self.size, "sha256": self.sha256}
+
+
+def user_agent(mtp_rs_version: str | None) -> str:
+    system = f"{platform.system()} {platform.machine()}".strip()
+    return f"unstrap/{__version__} ({system}; mtp-rs/{mtp_rs_version or 'none'})"
+
+
+class Api:
+    def __init__(
+        self,
+        base_url: str = DEFAULT_SERVER,
+        *,
+        agent: str | None = None,
+        client: httpx.Client | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._client = client or httpx.Client(timeout=httpx.Timeout(60.0, connect=15.0))
+        self._agent = agent or user_agent(None)
+        self._sleep = sleep
+
+    def close(self) -> None:
+        self._client.close()
+
+    # -- plumbing ---------------------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        token: str | None = None,
+        json: Any = None,
+        content: bytes | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        h = {"user-agent": self._agent, **(headers or {})}
+        if token:
+            h["authorization"] = f"Bearer {token}"
+        url = f"{self.base_url}/api/v1{path}"
+        last: Exception | None = None
+        for attempt in range(MAX_ATTEMPTS):
+            try:
+                res = self._client.request(method, url, json=json, content=content, headers=h)
+            except httpx.TransportError as e:
+                last = e
+                self._backoff(attempt, None)
+                continue
+            if res.status_code == 429 or res.status_code >= 500:
+                last = ApiError(res.status_code, *_error(res))
+                self._backoff(attempt, res.headers.get("retry-after"))
+                continue
+            if res.status_code >= 400:
+                code, message = _error(res)
+                if res.status_code == 426:
+                    raise ClientTooOld(426, code, message)
+                raise ApiError(res.status_code, code, message)
+            try:
+                data: dict[str, Any] = res.json()
+            except ValueError as e:
+                # E.g. a captive portal or proxy answering in HTML (review M3).
+                raise ServerUnreachable(
+                    f"Unexpected answer from {self.base_url} (a Wi-Fi login page or proxy?)"
+                ) from e
+            return data
+        if isinstance(last, ApiError):
+            raise last
+        raise ServerUnreachable(f"Can't reach {self.base_url}: {last}")
+
+    def _backoff(self, attempt: int, retry_after: str | None) -> None:
+        if attempt + 1 >= MAX_ATTEMPTS:
+            return
+        if retry_after and retry_after.isdigit():
+            delay = min(float(retry_after), 60.0)
+        else:
+            delay = min(2.0**attempt, 30.0) * (0.5 + random.random() / 2)
+        self._sleep(delay)
+
+    # -- endpoints --------------------------------------------------------------------------------
+
+    def healthz(self) -> bool:
+        try:
+            res = self._client.get(f"{self.base_url}/healthz", headers={"user-agent": self._agent})
+        except httpx.TransportError:
+            return False
+        return res.status_code == 200
+
+    def start(self, device: DeviceInfo, listing: Sequence[RemoteFile]) -> dict[str, Any]:
+        dev: dict[str, Any] = {"usb_serial": device.usb_serial, "unit_id": device.unit_id}
+        if device.product:
+            dev["product"] = device.product[:100]
+        if device.firmware:
+            dev["firmware"] = device.firmware[:32]
+        body = {"device": dev, "listing": [{"path": f.path, "size": f.size} for f in listing]}
+        return self._request("POST", "/syncs", json=body)
+
+    def prove(
+        self, sync_id: int, token: str, nonce: str, proofs: list[dict[str, str]]
+    ) -> dict[str, Any]:
+        body = {"nonce": nonce, "proofs": proofs}
+        return self._request("POST", f"/syncs/{sync_id}/prove", token=token, json=body)
+
+    def check(self, sync_id: int, token: str, files: Sequence[HashedFile]) -> list[str]:
+        body = {"files": [f.as_json() for f in files]}
+        res = self._request("POST", f"/syncs/{sync_id}/check", token=token, json=body)
+        return list(res["missing"])
+
+    def put_blob(self, sync_id: int, token: str, file: HashedFile, data: bytes) -> bool:
+        headers = {
+            "unstrap-path": quote(file.path, safe=""),
+            "content-type": "application/octet-stream",
+        }
+        res = self._request(
+            "PUT",
+            f"/syncs/{sync_id}/blobs/{file.sha256}",
+            token=token,
+            content=data,
+            headers=headers,
+        )
+        return bool(res.get("stored"))
+
+    def finish(
+        self,
+        sync_id: int,
+        token: str,
+        files: Sequence[HashedFile],
+        stats: dict[str, int | str | bool],
+        errors: list[str],
+    ) -> dict[str, Any]:
+        body = {"files": [f.as_json() for f in files], "stats": stats, "errors": errors[:100]}
+        return self._request("POST", f"/syncs/{sync_id}/finish", token=token, json=body)
+
+
+def _error(res: httpx.Response) -> tuple[str, str]:
+    try:
+        err = res.json()["error"]
+        return str(err["code"]), str(err["message"])
+    except (ValueError, KeyError, TypeError):
+        return "http_error", f"Server returned HTTP {res.status_code}."