ticktick-focus-client 0.2.0__py3-none-any.whl

ticktick_focus_client/__init__.py

@@ -0,0 +1,46 @@
+"""Read live TickTick focus/pomodoro state.
+
+async with FocusClient(cookie) as tt:
+    print(await tt.current())
+
+    async for state in tt.watch():
+        print(state, tt.health)
+"""
+
+from .client import (
+    AuthError,
+    Domain,
+    FocusClient,
+    TooBusy,
+)
+from .health import FailureReason, Health
+from .state import (
+    FocusKind,
+    FocusState,
+    FocusStatus,
+    PauseLogType,
+    Payload,
+    SessionStatus,
+    derive,
+    parse_time,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AuthError",
+    "Domain",
+    "FailureReason",
+    "FocusClient",
+    "FocusKind",
+    "FocusState",
+    "FocusStatus",
+    "Health",
+    "PauseLogType",
+    "Payload",
+    "SessionStatus",
+    "TooBusy",
+    "__version__",
+    "derive",
+    "parse_time",
+]

ticktick_focus_client/client.py

@@ -0,0 +1,418 @@
+"""Client for TickTick's private focus API.
+
+`FocusClient` does two things: a one-shot read (`current`) and a live feed
+(`watch`) driven by TickTick's push socket. Everything else — where to persist
+the sync checkpoint, what to do with a state change — belongs to the caller.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import urllib.parse
+from collections.abc import AsyncGenerator, Coroutine
+from enum import StrEnum
+from typing import Any, Final, Self
+
+import httpx
+import websockets
+from websockets.asyncio.client import ClientConnection
+
+from .health import FailureReason, Health
+from .state import FocusState, FocusStatus, Payload, derive
+
+log = logging.getLogger(__name__)
+
+
+class Domain(StrEnum):
+    """Which service to talk to. They are the same API under two names."""
+
+    TICKTICK = "ticktick.com"
+    DIDA = "dida365.com"
+    """The Chinese service."""
+
+
+DEFAULT_DEVICE_ID: Final = "0123456789abcdef01234567"
+USER_AGENT: Final = (
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/120.0.0.0 Safari/537.36"
+)
+
+# The web client pings every 540s; match it so idle connections are not reaped.
+PING_INTERVAL: Final = 540
+BACKOFF_START: Final = 2
+BACKOFF_MAX: Final = 300
+TOO_BUSY_DELAY: Final = 2
+# While unauthenticated there is no point hammering; retry on a slow, steady beat.
+AUTH_RETRY_SECONDS: Final = 60
+
+
+class AuthError(RuntimeError):
+    """The session cookie was rejected — it has expired or been revoked."""
+
+
+class TooBusy(RuntimeError):
+    """Server asked us to back off; the client retries after a short delay."""
+
+
+def x_device(device_id: str, websocket_id: str = "") -> str:
+    """The x-device blob the clients send.
+
+    A header on HTTP, a query parameter on the socket.
+    """
+    return json.dumps(
+        {
+            "platform": "web",
+            "os": "Linux",
+            "device": "Chrome 120.0.0.0",
+            "name": "",
+            "version": 6070,
+            "id": device_id,
+            "channel": "website",
+            "campaign": "",
+            "websocket": websocket_id,
+        }
+    )
+
+
+def websocket_url(
+    domain: Domain, device_id: str, language: str, websocket_id: str = ""
+) -> str:
+    qs = urllib.parse.urlencode(
+        {"x-device": x_device(device_id, websocket_id), "hl": language}
+    )
+    return f"wss://wssp.{domain}/web?{qs}"
+
+
+class FocusClient:
+    """Read live TickTick focus state.
+
+    Args:
+        cookie: value of the `t` session cookie from a logged-in web session.
+        domain: `ticktick.com`, or `dida365.com` for the Chinese service.
+        device_id: any 24-char hex-ish id; identifies this client to TickTick.
+        language: the `hl` the socket is opened with.
+        reconcile_seconds: how often `watch` re-reads regardless of pokes.
+        point: sync checkpoint to resume from. Persist `client.point` and hand
+            it back here to pick up where a previous process left off.
+        http: an `httpx.AsyncClient` to borrow. If given, the caller closes it.
+    """
+
+    def __init__(
+        self,
+        cookie: str,
+        *,
+        domain: Domain | str = Domain.TICKTICK,
+        device_id: str = DEFAULT_DEVICE_ID,
+        language: str = "en_US",
+        reconcile_seconds: int = 300,
+        point: int = 0,
+        http: httpx.AsyncClient | None = None,
+    ) -> None:
+        if not cookie or not cookie.strip():
+            raise ValueError("cookie must be a non-empty session cookie value")
+
+        self._cookie = cookie.strip()
+        self._domain = Domain(domain)
+        self._device_id = device_id
+        self._language = language
+        self._reconcile_seconds = reconcile_seconds
+        self._point = int(point)
+        self._http = http or httpx.AsyncClient(timeout=30.0)
+        self._owns_http = http is None
+
+        self._state = FocusState(state=FocusStatus.UNAVAILABLE)
+        self._health = Health()
+        self._sync_now = asyncio.Event()
+        self._watching = False
+
+    # ---- exposed state ----------------------------------------------------
+
+    @property
+    def state(self) -> FocusState:
+        """Last known focus state.
+
+        `UNAVAILABLE` until the first successful read, and whenever the cookie
+        is not working — never `idle`, which would be a claim we cannot make.
+        """
+        if not self._health.can_report_focus:
+            return FocusState(state=FocusStatus.UNAVAILABLE)
+        return self._state
+
+    @property
+    def health(self) -> Health:
+        """Health of the client itself, as opposed to the focus state it carries."""
+        return self._health
+
+    @property
+    def point(self) -> int:
+        """The sync checkpoint, which only ever moves forward.
+
+        Persist it if you want a new process to resume rather than re-read from
+        scratch, and pass it back as `point=`.
+        """
+        return self._point
+
+    # ---- lifecycle --------------------------------------------------------
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        await self.aclose()
+
+    # ---- HTTP -------------------------------------------------------------
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+            "x-device": x_device(self._device_id),
+            "Cookie": f"t={self._cookie}",
+        }
+
+    async def _fetch(self, last_point: int) -> Payload:
+        """Read raw focus state.
+
+        An empty `opList` makes this a pure read: we submit no operations, so
+        there is no way for this to mutate server-side focus history.
+        """
+        resp = await self._http.post(
+            f"https://ms.{self._domain}/focus/batch/focusOp",
+            headers=self._headers(),
+            json={"lastPoint": last_point, "opList": []},
+        )
+
+        if resp.status_code in (401, 403):
+            raise AuthError(f"session cookie rejected (HTTP {resp.status_code})")
+        if resp.status_code == 500:
+            try:
+                if resp.json().get("errorCode") == "too_busy":
+                    raise TooBusy("server busy")
+            except ValueError:
+                pass
+        resp.raise_for_status()
+        data: Payload = resp.json()
+        return data
+
+    async def refresh_account(self) -> Payload:
+        """Read account/subscription info and fold it into `health`.
+
+        Focus sync is gated behind Premium, so this is how you find out that
+        live updates are never going to arrive.
+        """
+        resp = await self._http.get(
+            f"https://api.{self._domain}/api/v2/user/status",
+            headers=self._headers(),
+        )
+        if resp.status_code in (401, 403):
+            raise AuthError(f"session cookie rejected (HTTP {resp.status_code})")
+        resp.raise_for_status()
+        status: Payload = resp.json()
+
+        h = self._health = self._health.with_account(status)
+        if not h.premium:
+            log.warning(
+                "This account is not Premium. TickTick gates cross-device focus sync "
+                "behind Premium, so live updates will not arrive."
+            )
+        elif h.premium_days_remaining is not None and h.premium_days_remaining <= 14:
+            log.warning(
+                "TickTick Premium%s ends in %d day(s) (%s). Focus sync stops working then.",
+                " (free trial)" if h.premium_free_trial else "",
+                h.premium_days_remaining,
+                h.premium_expires,
+            )
+        return status
+
+    # ---- reading ----------------------------------------------------------
+
+    async def current(self) -> FocusState:
+        """Read the live focus state once.
+
+        Raises `AuthError` if the cookie is rejected, and whatever `httpx`
+        raises on a network failure. Use `watch` if you want those reported as
+        health instead.
+        """
+        await self._sync(raise_errors=True)
+        return self.state
+
+    async def _sync(self, *, raise_errors: bool = False) -> None:
+        was_authed = self._health.auth_ok
+        try:
+            try:
+                data = await self._fetch(self._point)
+            except TooBusy:
+                await asyncio.sleep(TOO_BUSY_DELAY)
+                data = await self._fetch(self._point)
+        except AuthError as exc:
+            self._health = self._health.failed(
+                str(exc), FailureReason.AUTH_EXPIRED, auth_ok=False
+            )
+            if raise_errors:
+                raise
+            if was_authed:
+                log.error(
+                    "Session cookie rejected (%s). Reporting unavailable and retrying "
+                    "every %ss.",
+                    exc,
+                    AUTH_RETRY_SECONDS,
+                )
+            return
+        except Exception as exc:
+            self._health = self._health.failed(str(exc))
+            if raise_errors:
+                raise
+            log.error("sync failed: %s", exc)
+            return
+
+        self._state = derive(data.get("current"))
+        self._health = self._health.succeeded()
+        if not was_authed:
+            log.info("Session cookie accepted again; resuming normal reporting.")
+
+        point = int(data.get("point") or 0)
+        self._point = max(self._point, point)
+
+    # ---- watching ---------------------------------------------------------
+
+    async def watch(self) -> AsyncGenerator[FocusState]:
+        """Yield focus state as it changes, driven by TickTick's push socket.
+
+        The first yield is the state at the time of the call. After that a
+        value arrives whenever a read produces something different from the
+        last one yielded — a real change, or a reconcile tick refreshing the
+        elapsed/remaining clocks mid-session.
+
+        Nothing here is fatal: network errors and an expired cookie are
+        reported through `health`, the state goes `UNAVAILABLE`, and the client
+        keeps retrying. Only a genuine bug escapes as an exception.
+        """
+        if self._watching:
+            raise RuntimeError("this client is already being watched")
+        self._watching = True
+
+        queue: asyncio.Queue[FocusState | BaseException] = asyncio.Queue()
+        loops = (self._sync_loop(queue), self._socket_loop(), self._reconcile_loop())
+        tasks = [asyncio.create_task(self._guard(loop, queue)) for loop in loops]
+        try:
+            while True:
+                item = await queue.get()
+                if isinstance(item, BaseException):
+                    raise item
+                yield item
+        finally:
+            self._watching = False
+            for task in tasks:
+                task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    async def _guard(
+        self,
+        loop: Coroutine[Any, Any, None],
+        queue: asyncio.Queue[FocusState | BaseException],
+    ) -> None:
+        """Run a background loop, handing anything unexpected to the consumer."""
+        try:
+            await loop
+        except asyncio.CancelledError:
+            raise
+        except BaseException as exc:  # noqa: BLE001 — re-raised in watch()
+            await queue.put(exc)
+
+    async def _sync_loop(
+        self, queue: asyncio.Queue[FocusState | BaseException]
+    ) -> None:
+        """Serialises syncs so a burst of pokes collapses into one request."""
+        last: FocusState | None = None
+        while True:
+            await self._sync()
+            state = self.state
+            if state != last:
+                last = state
+                await queue.put(state)
+            try:
+                await asyncio.wait_for(
+                    self._sync_now.wait(),
+                    timeout=None if self._health.auth_ok else AUTH_RETRY_SECONDS,
+                )
+            except TimeoutError:
+                pass  # unauthenticated: retry on the slow beat
+            self._sync_now.clear()
+
+    async def _reconcile_loop(self) -> None:
+        """Safety net: re-read periodically in case a poke was missed."""
+        while True:
+            await asyncio.sleep(self._reconcile_seconds)
+            self._sync_now.set()
+
+    async def _socket_loop(self) -> None:
+        backoff = BACKOFF_START
+        while True:
+            try:
+                async with websockets.connect(
+                    websocket_url(self._domain, self._device_id, self._language),
+                    additional_headers={
+                        "Cookie": f"t={self._cookie}",
+                        "Origin": f"https://{self._domain}",
+                    },
+                    open_timeout=30,
+                    ping_interval=None,  # the server expects an app-level ping
+                ) as ws:
+                    log.info("websocket connected")
+                    backoff = BACKOFF_START
+                    self._health = self._health.with_socket(True)
+                    # The socket authenticates with the same cookie, so a
+                    # successful connect means a rotated cookie is already good:
+                    # resync now rather than waiting out the retry beat.
+                    self._sync_now.set()
+                    await ws.send(json.dumps({"type": "ping"}))
+                    pinger = asyncio.create_task(self._ping(ws))
+                    try:
+                        async for raw in ws:
+                            self._on_message(raw)
+                    finally:
+                        pinger.cancel()
+                        with contextlib.suppress(asyncio.CancelledError):
+                            await pinger
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                log.warning(
+                    "websocket disconnected (%s); reconnecting in %ss", exc, backoff
+                )
+            self._health = self._health.with_socket(False)
+            # Fall back on polling while the socket is down — but not while auth
+            # is already known broken, where the slow retry beat covers it.
+            if self._health.auth_ok:
+                self._sync_now.set()
+            await asyncio.sleep(backoff)
+            backoff = min(backoff * 2, BACKOFF_MAX)
+
+    async def _ping(self, ws: ClientConnection) -> None:
+        while True:
+            await asyncio.sleep(PING_INTERVAL)
+            await ws.send(json.dumps({"type": "ping"}))
+
+    def _on_message(self, raw: str | bytes) -> None:
+        try:
+            message = json.loads(raw)
+        except (ValueError, TypeError):
+            log.debug("ignoring non-JSON frame: %r", raw[:120])
+            return
+
+        kind = message.get("type")
+        if kind == "focusSync":
+            log.debug("focusSync poke received")
+            self._sync_now.set()
+        elif kind == "pong":
+            log.debug("pong")
+        elif "wsId" in message:
+            log.debug("socket registered: %s", message["wsId"])
+        else:
+            log.debug("unhandled frame: %s", message)

ticktick_focus_client/health.py

@@ -0,0 +1,106 @@
+"""Health of the client itself, as opposed to the focus state it carries.
+
+Kept separate from FocusState so that "we cannot tell you anything right now"
+never gets confused with "you are not focusing".
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import asdict, dataclass, replace
+from enum import StrEnum
+from typing import Any, Self
+
+from .state import Payload, parse_time
+
+
+class FailureReason(StrEnum):
+    """Why the last read failed."""
+
+    AUTH_EXPIRED = "auth_expired"
+    """The cookie was rejected. Nothing works until it is replaced."""
+    NETWORK = "network"
+    """A transport-level blip. Says nothing about the cookie."""
+
+
+@dataclass(frozen=True, slots=True)
+class Health:
+    auth_ok: bool = True
+    websocket_connected: bool = False
+    last_sync_at: dt.datetime | None = None
+    last_error: str | None = None
+    last_error_at: dt.datetime | None = None
+    failure_reason: FailureReason | None = None
+    consecutive_failures: int = 0
+    premium: bool | None = None
+    premium_free_trial: bool | None = None
+    premium_expires: dt.datetime | None = None
+    premium_days_remaining: int | None = None
+
+    @property
+    def healthy(self) -> bool:
+        """True when we are authenticated and have the push channel up."""
+        return self.auth_ok and self.websocket_connected
+
+    @property
+    def can_report_focus(self) -> bool:
+        """Whether the focus state we hold is trustworthy.
+
+        False means the answer is `unavailable`, not `idle`.
+        """
+        return self.auth_ok
+
+    def as_dict(self) -> dict[str, Any]:
+        """A JSON-safe view: times as ISO 8601, unset fields dropped."""
+        data: dict[str, Any] = {
+            key: value.isoformat() if isinstance(value, dt.datetime) else value
+            for key, value in asdict(self).items()
+            if value is not None
+        }
+        data["healthy"] = self.healthy
+        return data
+
+    # -- transitions ----------------------------------------------------
+
+    def succeeded(self, now: dt.datetime | None = None) -> Self:
+        now = now or dt.datetime.now(dt.UTC)
+        return replace(
+            self,
+            auth_ok=True,
+            last_sync_at=now,
+            last_error=None,
+            last_error_at=None,
+            failure_reason=None,
+            consecutive_failures=0,
+        )
+
+    def failed(
+        self,
+        error: str,
+        reason: FailureReason = FailureReason.NETWORK,
+        auth_ok: bool | None = None,
+        now: dt.datetime | None = None,
+    ) -> Self:
+        now = now or dt.datetime.now(dt.UTC)
+        return replace(
+            self,
+            auth_ok=self.auth_ok if auth_ok is None else auth_ok,
+            last_error=error,
+            last_error_at=now,
+            failure_reason=reason,
+            consecutive_failures=self.consecutive_failures + 1,
+        )
+
+    def with_socket(self, connected: bool) -> Self:
+        return replace(self, websocket_connected=connected)
+
+    def with_account(self, status: Payload, now: dt.datetime | None = None) -> Self:
+        now = now or dt.datetime.now(dt.UTC)
+        expires = parse_time(status.get("proEndDate"))
+        return replace(
+            self,
+            premium=bool(status.get("pro")),
+            premium_free_trial=bool(status.get("freeTrial")),
+            premium_expires=expires,
+            premium_days_remaining=(expires - now).days if expires else None,
+        )

ticktick_focus_client/state.py

@@ -0,0 +1,190 @@
+"""Turn a raw `current` focus object into a flat, typed state.
+
+Everything here is a pure function of the API payload, so it is unit-testable
+without a network or an account.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass
+from enum import IntEnum, StrEnum
+from typing import Any, Final
+
+Payload = Mapping[str, Any]
+"""A JSON object as it came off the wire — untyped by definition."""
+
+_TIME_FORMATS: Final = ("%Y-%m-%dT%H:%M:%S.%f%z", "%Y-%m-%dT%H:%M:%S%z")
+
+
+class FocusStatus(StrEnum):
+    """What the user is doing, as far as we can tell."""
+
+    IDLE = "idle"
+    FOCUSING = "focusing"
+    PAUSED = "paused"
+    BREAK = "break"
+    UNAVAILABLE = "unavailable"
+    """We cannot currently tell, which is not the same as `IDLE`."""
+
+    @property
+    def in_session(self) -> bool:
+        """True while a session is open — a pause or a break still counts."""
+        return self in (FocusStatus.FOCUSING, FocusStatus.PAUSED, FocusStatus.BREAK)
+
+
+class FocusKind(StrEnum):
+    """Which timer produced a focus record.
+
+    The API spells this as an int in `type`, confirmed against both the
+    documented Open API ("Pomodoro: 0, Timing: 1") and the two runners in the
+    macOS client. Each member carries that int as `api_value`, so the mapping
+    lives in one place and we can hand out the readable name instead.
+    """
+
+    api_value: int
+
+    def __new__(cls, label: str, api_value: int) -> FocusKind:
+        member = str.__new__(cls, label)
+        member._value_ = label
+        member.api_value = api_value
+        return member
+
+    POMODORO = ("pomodoro", 0)
+    STOPWATCH = ("stopwatch", 1)
+
+    @classmethod
+    def parse(cls, value: object) -> FocusKind | None:
+        """Read the API's `type`, tolerating anything unexpected."""
+        return next((kind for kind in cls if kind.api_value == value), None)
+
+
+class SessionStatus(IntEnum):
+    """`status` on a focus record, as observed against the live API.
+
+    Anything but `RUNNING` means the session is over.
+    """
+
+    RUNNING = 0
+    COMPLETED = 1
+    ABANDONED = 2
+    """Ended rather than finished; accompanies `exited: true`."""
+
+
+class PauseLogType(IntEnum):
+    """Entries in `pauseLogs`, which alternate."""
+
+    PAUSED = 0
+    RESUMED = 1
+
+
+def parse_time(value: object) -> dt.datetime | None:
+    """Read one of the API's timestamps, or None if it is missing or malformed."""
+    if not value or not isinstance(value, str):
+        return None
+    text = value.replace("Z", "+0000")
+    for fmt in _TIME_FORMATS:
+        try:
+            return dt.datetime.strptime(text, fmt)
+        except ValueError:
+            continue
+    return None
+
+
+def _is_paused(current: Payload) -> bool:
+    """An odd trailing run of unmatched `PAUSED` entries means we are paused now."""
+    depth = 0
+    for entry in current.get("pauseLogs") or []:
+        if entry.get("type") == PauseLogType.PAUSED:
+            depth += 1
+        else:
+            depth = max(0, depth - 1)
+    return depth > 0
+
+
+def _in_break(current: Payload) -> bool:
+    brk = current.get("focusBreak") or {}
+    if not isinstance(brk, Mapping) or not brk:
+        return False
+    # A break that has started but not ended.
+    return bool(brk.get("startTime")) and not brk.get("endTime")
+
+
+@dataclass(frozen=True, slots=True)
+class FocusState:
+    """A snapshot of what the user is doing, and of the session carrying it."""
+
+    state: FocusStatus
+    focus_type: FocusKind | None = None
+    task_title: str | None = None
+    task_id: str | None = None
+    started_at: dt.datetime | None = None
+    elapsed_seconds: int | None = None
+    remaining_seconds: int | None = None
+    scheduled_end: dt.datetime | None = None
+    """The *projected* finish of a pomodoro, not evidence that it is over."""
+    pomo_count: int | None = None
+    session_id: str | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        """A JSON-safe view: times as ISO 8601, unset fields dropped.
+
+        The enums are `str`/`int` subclasses, so they need no conversion.
+        """
+        return {
+            key: value.isoformat() if isinstance(value, dt.datetime) else value
+            for key, value in asdict(self).items()
+            if value is not None
+        }
+
+
+def derive(current: Payload | None, now: dt.datetime | None = None) -> FocusState:
+    """Collapse a `current` object into a single status plus its details.
+
+    Note that `endTime` is NOT a reliable end-of-session signal: for a pomodoro
+    it holds the *projected* finish (start + configured duration) and is
+    populated while the session is still running. Liveness comes from `status`
+    and `exited` instead.
+    """
+    if not current:
+        return FocusState(state=FocusStatus.IDLE)
+
+    now = now or dt.datetime.now(dt.UTC)
+    status = current.get("status")
+    end = parse_time(current.get("endTime"))
+
+    if current.get("exited"):
+        return FocusState(state=FocusStatus.IDLE)
+    if status is not None and status != SessionStatus.RUNNING:
+        return FocusState(state=FocusStatus.IDLE)
+    if status is None and end is not None and end <= now:
+        # No status to go on; fall back on the clock.
+        return FocusState(state=FocusStatus.IDLE)
+
+    started = parse_time(current.get("startTime"))
+    elapsed = max(0, int((now - started).total_seconds())) if started else None
+    remaining = max(0, int((end - now).total_seconds())) if end else None
+
+    tasks = current.get("focusTasks") or []
+    task: Payload = tasks[-1] if tasks else {}
+
+    if _in_break(current):
+        state = FocusStatus.BREAK
+    elif _is_paused(current):
+        state = FocusStatus.PAUSED
+    else:
+        state = FocusStatus.FOCUSING
+
+    return FocusState(
+        state=state,
+        focus_type=FocusKind.parse(current.get("type")),
+        task_title=task.get("title"),
+        task_id=task.get("id"),
+        started_at=started,
+        elapsed_seconds=elapsed,
+        remaining_seconds=remaining,
+        scheduled_end=end if remaining is not None else None,
+        pomo_count=current.get("pomoCount"),
+        session_id=current.get("id"),
+    )

ticktick_focus_client-0.2.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.5
+Name: ticktick-focus-client
+Version: 0.2.0
+Summary: Read live TickTick focus/pomodoro state
+Author-email: Jon Wood <jon@blankpad.net>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=13.0
+Description-Content-Type: text/markdown
+
+# ticktick-focus-client
+
+A small async Python library that reads **live** TickTick focus state from
+TickTick's private API and websocket server.
+
+## Why this exists
+
+TickTick's documented Open API (`/open/v1/focus`) returns **completed** focus
+records only. It has no endpoint for the session you are in right now, so it
+cannot answer "is Jon focusing?".
+
+The desktop and web clients get live state from a separate, undocumented
+channel, which this library speaks:
+
+| Piece | What it does |
+|---|---|
+| `wss://wssp.ticktick.com/web?x-device=…&hl=…` | Push channel. Server sends `{"type":"focusSync"}` when anything changes — a doorbell, carrying no state. Client sends `{"type":"ping"}` on open and every 540 s. |
+| `POST https://ms.ticktick.com/focus/batch/focusOp` | The state. Body `{"lastPoint": <n>, "opList": []}` returns `{"point", "current", "updates"}`. `current` is the live session. |
+
+Sending an empty `opList` argument makes no changes to focus state, this
+client is purely read only. (Although I wouldn't be against adding some
+write support in the future.)
+
+## Usage
+
+```python
+from ticktick_focus_client import FocusClient, FocusStatus
+
+async with FocusClient(cookie) as tt:
+    # One-shot. Raises AuthError if the cookie is rejected.
+    print(await tt.current())
+
+    # Live, driven by the push socket. Never raises for auth or network
+    # trouble — that arrives as state instead.
+    async for state in tt.watch():
+        if state.state is FocusStatus.FOCUSING:
+            print(state.task_title, state.remaining_seconds)
+```
+
+`watch()` yields the first time it has a state, and thereafter whenever a read
+produces something different from the last value yielded — a real change, or a
+reconcile tick refreshing the elapsed/remaining clocks mid-session. Steady idle
+is silent.
+
+### `FocusState`
+
+A frozen dataclass. `state` is a `FocusStatus`, `focus_type` a `FocusKind`,
+`started_at` and `scheduled_end` are `datetime`s, and the rest are
+`task_title`, `task_id`, `elapsed_seconds`, `remaining_seconds`, `pomo_count`
+and `session_id`. `as_dict()` gives a JSON-safe view: times as ISO 8601, unset
+fields dropped.
+
+| Enum | Members |
+|---|---|
+| `FocusStatus` | `IDLE`, `FOCUSING`, `PAUSED`, `BREAK`, `UNAVAILABLE`, plus `.in_session` |
+| `FocusKind` | `POMODORO`, `STOPWATCH`, each carrying the API's int as `.api_value` |
+| `SessionStatus` | `RUNNING`, `COMPLETED`, `ABANDONED` — the API's `status` |
+| `PauseLogType` | `PAUSED`, `RESUMED` — entries in the API's `pauseLogs` |
+
+`FocusStatus` and `FocusKind` are `StrEnum`s, so `state.state == "focusing"`
+holds and `json.dumps` needs no help. `UNAVAILABLE` means "cannot currently
+tell" — before the first successful read, or while the cookie is not working.
+It is never conflated with `IDLE`.
+
+### `client.health`
+
+Health of the client, kept separate from the focus state it carries:
+`auth_ok`, `websocket_connected`, `healthy`, `can_report_focus`,
+`last_sync_at`, `last_error`, `last_error_at`, `consecutive_failures`, a
+`failure_reason` of `AUTH_EXPIRED` or `NETWORK`, plus Premium details once
+`await client.refresh_account()` has run. `as_dict()` behaves as it does on
+`FocusState`.
+
+### `client.point`
+
+The sync checkpoint, which only ever moves forward. Nothing is written to disk;
+persist it yourself and hand it back if you want a new process to resume rather
+than re-read from scratch:
+
+```python
+FocusClient(cookie, point=saved_point)
+```
+
+### Options
+
+| Argument | Default | Notes |
+|---|---|---|
+| `cookie` | — | The `t` session cookie value. Required. |
+| `domain` | `Domain.TICKTICK` | Or `Domain.DIDA` for the Chinese service. Plain strings are accepted and validated. |
+| `device_id` | a fixed placeholder | Any 24-char hex-ish id. |
+| `language` | `en_US` | |
+| `reconcile_seconds` | `300` | Safety-net re-read, in case a poke is missed. |
+| `point` | `0` | Sync checkpoint to resume from. |
+| `http` | — | An `httpx.AsyncClient` to borrow; the caller closes it. |
+
+### Typing
+
+The package ships a `py.typed` marker and checks clean under
+[ty](https://github.com/astral-sh/ty), so the enums and datetimes above reach
+anything built on top of it.
+
+## Requirements
+
+- Python 3.11+
+- **TickTick Premium.** Cross-device focus sync is gated behind it
+  (`focusConf.keepInSync` plus a Premium check). Without it the server does not
+  push and `current` will not track your sessions. (Untested)
+- **"Keep in Sync" enabled** in TickTick's focus settings.
+- A session cookie (see below).
+
+## Getting the session cookie
+
+This endpoint is not covered by the Open API, and an Open API personal token
+(`Authorization: Bearer …`) **will not work** — it belongs to a different auth
+realm. You need the `t` cookie from a logged-in session:
+
+1. Sign in at <https://ticktick.com> in a browser.
+2. DevTools → Application → Cookies → `https://ticktick.com`.
+3. Copy the **Value** of the `t` cookie.
+
+The library takes it as a plain string and never touches the filesystem. Where
+it comes from — a file, a keychain, an environment variable — is yours to
+decide. A cookie that has been rotated means a new client.
+
+## Design notes
+
+- **Push, not poll.** The socket is the trigger; the reconcile timer only
+  covers missed pokes. Sync requests collapse — a burst of pokes causes one read.
+- **`endTime` does not mean "finished".** For a pomodoro it is the *projected*
+  end (start + configured duration) and is present throughout the session.
+  Liveness comes from `status == 0` and `exited == false`; `endTime` is only a
+  fallback when `status` is absent. Getting this wrong reports `idle` mid-session.
+- **Nothing is fatal while watching.** Network errors and expired cookies are
+  reported as state and retried; only a genuine bug escapes the iterator.
+- **Auth failures are distinguished from network failures.** A connection reset
+  does not clear `auth_ok`, so a blip never gets reported as an expired cookie.
+- Reconnects with exponential backoff (2 s → 5 min).
+
+## Caveats
+
+- This uses TickTick's **private API**, which is against their Terms of Service.
+  It can change without notice.
+- Sessions shorter than TickTick's minimum valid duration are discarded by the
+  app and never appear anywhere.
+
+## Tests
+
+```bash
+uv run pytest
+uv run ty check
+```
+
+The state machine is a pure function of the API payload, so the interesting
+logic is covered without network or credentials.

ticktick_focus_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+ticktick_focus_client/__init__.py,sha256=UMEXfST_7KLCPpouawe-O_qxXPuO_3YiaNzkPHdBOPA,757
+ticktick_focus_client/client.py,sha256=Ea0N1FjxiEHrluXItt0SNgYH2gpTdVYZpOAMNAzhJvE,15139
+ticktick_focus_client/health.py,sha256=i83w3Kl9xFEjPKvp9GgwDhiMJa2LLuOMiiC2qPS04so,3454
+ticktick_focus_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ticktick_focus_client/state.py,sha256=L0UsRKwRvgN2gzaNAVKasU_rcpUkX3z9ua3yxMODOj8,6162
+ticktick_focus_client-0.2.0.dist-info/METADATA,sha256=JHHL3bdgcrr6KvOekKMaPU_R0wGimCF9IqTDUnOGL6M,6718
+ticktick_focus_client-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+ticktick_focus_client-0.2.0.dist-info/licenses/LICENSE,sha256=oF5EiJt0G1Xghv93j0Mxo-xRsjUOiJ5hreALRbSHsZk,1052
+ticktick_focus_client-0.2.0.dist-info/RECORD,,

ticktick_focus_client-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ticktick_focus_client-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Jon Wood
+
+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.