mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/accounts/routes.py

@@ -0,0 +1,212 @@
+"""The profiles API (Settings › Profiles), registered under /api/accounts (api_routes, seam S3)."""
+
+import re
+
+from .. import harness_api
+from ..api_errors import APIError
+from ..api_routes import Request, Response, Route, register
+from .store import AccountNotFound, AmbiguousAccount, display, resolve, store_for
+
+KEY = re.compile(r"[A-Za-z0-9_.:-]{1,100}")
+MAX_RUN_ACCOUNTS = 20
+RUN_FIELDS = frozenset({"accounts", "goal", "appId", "engine", "outputFormat"})
+NOT_HERE = "Change your profiles in Mobster on your Mac, in Settings › Profiles."
+
+
+def _writable(request):
+    if request.origin in ("remote", "mcp"):
+        raise APIError(NOT_HERE, 403, "not_here")
+
+
+def _device(runtime, value):
+    """(id, name) of the phone ``value`` names, or None for null. ValueError when no phone has that name."""
+    if value is None:
+        return None
+    fleet = getattr(runtime, "fleet", None)
+    if fleet is None:
+        raise ValueError("This Mobster runs every task on one phone. Leave the profile's phone out.")
+    try:
+        phone = fleet.find(value)
+    except LookupError as error:
+        raise ValueError(str(error)) from None
+    return phone.id, phone.name
+
+
+def public(account):
+    return {**account, "display": display(account)}
+
+
+def list_accounts(request: Request):
+    return Response.json({"accounts": [public(a) for a in store_for(request.runtime).all()]})
+
+
+def _remember(account):
+    """A saved profile's voice and signature are memory facts, edited where the profile is (memory/writer.py)."""
+    from ..memory import writer
+    writer.from_profile(account)
+
+
+def add_account(request: Request):
+    _writable(request)
+    body = request.body or {}
+    device = _device(request.runtime, body.get("device")) if isinstance(body, dict) else None
+    account = store_for(request.runtime).add(body, device)
+    _remember(account)
+    return Response.json({"account": public(account)}, 201)
+
+
+def edit_account(request: Request):
+    _writable(request)
+    body = request.body or {}
+    device = _device(request.runtime, body.get("device")) if isinstance(body, dict) and "device" in body else None
+    try:
+        account = store_for(request.runtime).update(request.params["id"], body, device)
+    except AccountNotFound as error:
+        raise APIError(str(error), 404, "account_not_found") from None
+    _remember(account)
+    return Response.json({"account": public(account)})
+
+
+def delete_account(request: Request):
+    _writable(request)
+    try:
+        store_for(request.runtime).remove(request.params["id"])
+    except AccountNotFound as error:
+        raise APIError(str(error), 404, "account_not_found") from None
+    from ..memory import writer
+    writer.profile_removed(request.params["id"])
+    return Response.json({"deleted": True})
+
+
+def _key(request):
+    headers = request.headers
+    values = headers.get_all("Idempotency-Key", []) if hasattr(headers, "get_all") else (
+        [headers["Idempotency-Key"]] if headers.get("Idempotency-Key") else [])
+    if not values:
+        return None
+    if len(values) > 1 or not KEY.fullmatch(values[0]):
+        raise ValueError("Invalid Idempotency-Key")
+    return values[0]
+
+
+def run_accounts(request: Request):
+    """One task per account."""
+    runtime, body = request.runtime, request.body or {}
+    if not isinstance(body, dict) or set(body) - RUN_FIELDS:
+        raise ValueError("A task for several profiles has accounts, goal, and optionally appId, engine and "
+                         "outputFormat")
+    names = body.get("accounts")
+    if not isinstance(names, list) or not 1 <= len(names) <= MAX_RUN_ACCOUNTS:
+        raise ValueError(f"accounts is a list of 1 to {MAX_RUN_ACCOUNTS} profiles")
+    stored = store_for(runtime).all()
+    chosen = []
+    for name in names:
+        try:
+            account = resolve(stored, name)
+        except (AccountNotFound, AmbiguousAccount) as error:
+            raise APIError(str(error), 404 if isinstance(error, AccountNotFound) else 400,
+                           "account_not_found" if isinstance(error, AccountNotFound) else "account_ambiguous") from None
+        if all(account["id"] != other["id"] for other in chosen):
+            chosen.append(account)
+    by_phone = {}
+    for account in chosen:
+        by_phone.setdefault(account.get("device") or "", []).append(account)
+    for together in by_phone.values():
+        if len(together) > 1:
+            where = together[0].get("deviceName") or "your default phone"
+            listed = " and ".join(display(a) for a in together)
+            raise APIError(f"{listed} are both on {where}, and a phone runs one task at a time. Run them one after "
+                           "the other, or move one profile to another phone.", 409, "same_phone")
+    key = _key(request)
+    origin = request.origin if request.origin in harness_api.ORIGINS else "api"
+    rows = []
+    for account in chosen:
+        try:
+            created = runtime.create(body.get("appId"), body.get("goal"), "live",
+                                     f"{key}:{account['id']}" if key else None,
+                                     output_format=body.get("outputFormat", "auto"), engine=body.get("engine"),
+                                     extras={"account": account["id"]}, origin=origin)
+        except APIError as error:
+            rows.append({"account": account["id"], "display": display(account), "error": str(error),
+                         "code": error.code})
+            continue
+        except ValueError as error:
+            if len(chosen) == 1:
+                raise
+            rows.append({"account": account["id"], "display": display(account), "error": str(error),
+                         "code": "invalid"})
+            continue
+        run = created[0] if isinstance(created, tuple) else created
+        rows.append({"account": account["id"], "display": display(account), "run": run.public(include_events=False)})
+    started = any("run" in row for row in rows)
+    return Response.json({"runs": rows}, 201 if started else 409)
+
+
+def _pacing_answer(request, profile):
+    from .pacing import pacing_for
+    pacing = pacing_for(request.runtime)
+    return {**pacing.settings(profile), "today": pacing.today(profile)}
+
+
+def _known(request):
+    profile = request.params["id"]
+    if store_for(request.runtime).get(profile) is None:
+        raise APIError("No profile has that id. Add it in Settings › Profiles.", 404, "account_not_found")
+    return profile
+
+
+def get_pacing(request):
+    return Response.json({"pacing": _pacing_answer(request, _known(request))})
+
+
+def save_pacing(request):
+    from .pacing import PacingError, pacing_for
+    _writable(request)
+    profile = _known(request)
+    try:
+        pacing_for(request.runtime).save(profile, request.body or {})
+    except PacingError as error:
+        raise APIError(str(error), 400, "invalid") from None
+    return Response.json({"pacing": _pacing_answer(request, profile)})
+
+
+def resume_profile(request):
+    from .pacing import pacing_for
+    _writable(request)
+    profile = _known(request)
+    pacing_for(request.runtime).resume(profile)
+    return Response.json({"pacing": _pacing_answer(request, profile)})
+
+
+def get_stats(request):
+    from ..packs.register import all_packs
+    from . import stats
+    app = request.params["app"]
+    if app not in {pack.key for pack in all_packs()}:
+        raise APIError(f"There is no {app} pack. Use one of: " + ", ".join(p.key for p in all_packs()) + ".", 404,
+                       "stats_unknown_app")
+    try:
+        days = int((request.query.get("days") or ["30"])[0])
+    except ValueError:
+        days = 0
+    if not 1 <= days <= 365:
+        raise APIError("days is a number from 1 to 365.", 400, "invalid")
+    return Response.json(stats.series(store_for(request.runtime).data_dir, app, request.params["handle"], days))
+
+
+ROUTES = (
+    Route("accounts", "GET", "/api/accounts", list_accounts, body="none"),
+    Route("accounts", "POST", "/api/accounts", add_account),
+    Route("accounts", "POST", "/api/accounts/runs", run_accounts, idempotency=True),
+    Route("accounts", "POST", "/api/accounts/{id}", edit_account),
+    Route("accounts", "GET", "/api/accounts/{id}/pacing", get_pacing, body="none"),
+    Route("accounts", "POST", "/api/accounts/{id}/pacing", save_pacing),
+    Route("accounts", "POST", "/api/accounts/{id}/resume", resume_profile, body="none"),
+    Route("accounts", "GET", "/api/accounts/{app}/{handle}/stats", get_stats, body="none"),
+    Route("accounts", "DELETE", "/api/accounts/{id}", delete_account, body="none"),
+)
+
+
+def register_routes():
+    for route in ROUTES:
+        register(route)

mobile_agent/accounts/routing.py

@@ -0,0 +1,69 @@
+"""A task that names a profile (an account in the code): its run field, and where it runs."""
+
+import hashlib
+import json
+from types import MappingProxyType
+
+from .context import fill
+from .store import AccountNotFound, AmbiguousAccount, display, resolve, store_for
+
+SMART_ONLY = ("A task for a profile runs on Mobster's agent, which confirms the profile on screen before it posts. "
+              "Choose Mobster, or leave the profile out.")
+
+
+def validate(value, runtime):
+    if isinstance(value, dict):
+        value = value.get("id")
+    try:
+        account = resolve(store_for(runtime).all(), value)
+    except (AccountNotFound, AmbiguousAccount) as error:
+        raise ValueError(str(error)) from None
+    return {"id": account["id"], "handle": account["handle"], "app": dict(account["app"]),
+            "device": account.get("device"), "deviceName": account.get("deviceName")}
+
+
+def capture(runtime, account):
+    """Detach the selected writing context from the editable profile at admission."""
+    stored = store_for(runtime).get(account["id"])
+    if stored is None:
+        raise ValueError("This profile was removed. Choose a saved profile again.")
+    identity = ("id", "handle", "app", "device", "deviceName")
+    if any(stored.get(key) != account.get(key) for key in identity):
+        raise ValueError("This profile changed while the task was starting. Choose it again.")
+    selected = {key: stored.get(key) for key in identity}
+    selected.update(notes=stored.get("notes") or "", signature=stored.get("signature") or "",
+                    links=stored.get("links") or [], variables=stored.get("variables") or {})
+    fingerprint = digest(selected)
+    frozen = MappingProxyType({**selected, "app": MappingProxyType(dict(selected["app"])),
+                               "links": tuple(MappingProxyType(dict(link)) for link in selected["links"]),
+                               "variables": MappingProxyType(dict(selected["variables"]))})
+    return frozen, fingerprint
+
+
+def digest(account):
+    plain = {**account, "app": dict(account["app"]), "links": [dict(link) for link in account["links"]],
+             "variables": dict(account["variables"])}
+    return hashlib.sha256(json.dumps(plain, sort_keys=True, ensure_ascii=True,
+                                     allow_nan=False).encode()).hexdigest()
+
+
+def route(runtime, account, goal, device):
+    """(goal, device) for a task as ``account``. ValueError when the task names another phone."""
+    stored = account
+    wanted = stored.get("device")
+    if wanted and device is not None:
+        fleet = getattr(runtime, "fleet", None)
+        named = None
+        if fleet is not None:
+            try:
+                named = fleet.find(device).id
+            except LookupError:
+                named = None
+        if named != wanted:
+            where = stored.get("deviceName") or "another phone"
+            raise ValueError(f"{display(stored)} is on {where}. Leave the phone out and Mobster uses that one, or "
+                             "change the profile's phone in Settings › Profiles.")
+    if (wanted and device is None and getattr(runtime, "fleet", None) is not None
+            and getattr(runtime, "pool", 1) is None):
+        device = wanted
+    return fill(goal, stored), device

mobile_agent/accounts/screen.py

@@ -0,0 +1,273 @@
+"""Which profile is signed in, read off the screen, and the check before every commit as that profile."""
+
+import re
+import threading
+import time
+
+from .store import display
+
+TOP = .45                      # the top part of the screen a profile's handle sits in (screen fractions)
+MAX_REFUSALS = 3
+# Own-profile controls in the apps' own words (English UI): "Edit profile", "Edit Profile", "Share profile".
+OWN_PROFILE = re.compile(r"^\s*(?:edit|share)\s+profile\b", re.I)
+# Controls only someone else's profile shows.
+OTHER_PROFILE = re.compile(r"^\s*(?:follow|following|follow back|requested|message|subscribe)\s*$", re.I)
+HANDLE_TOKEN = re.compile(r"(?<![A-Za-z0-9_.@-])@([A-Za-z0-9._-]{1,64}?)(?=[^A-Za-z0-9_.-]|\.(?![A-Za-z0-9_-])|$)")
+TITLE_TOKEN = re.compile(r"[A-Za-z0-9._-]{1,64}")
+
+VERBS = {"post": ("post", "posting"), "comment": ("comment", "commenting"), "reply": ("reply", "replying"),
+         "send_message": ("send", "sending"), "react": ("react", "reacting"), "follow": ("follow", "following"),
+         "unfollow": ("unfollow", "unfollowing"), "share": ("share", "sharing"), "delete": ("delete", "deleting")}
+
+
+def _texts(element):
+    return [t for t in (getattr(element, "label", "") or "", getattr(element, "value", "") or "") if t]
+
+
+def _top(element):
+    x, y, w, h = element.rect
+    return y + h / 2 <= TOP
+
+
+def shows(text, handle):
+    """Whether ``text`` names ``handle`` as a whole token, with or without its @ ("acme", "@acme", "acme ✓")."""
+    pattern = r"(?<![A-Za-z0-9_.@-])@?" + re.escape(handle) + r"(?![A-Za-z0-9_-]|\.[A-Za-z0-9_-])"
+    return re.search(pattern, text or "", re.I) is not None
+
+
+def own_profile(snapshot):
+    """Whether ``snapshot`` is the signed-in profile's own page: an own-profile control, and no Follow or Message."""
+    elements = list(getattr(snapshot, "elements", ()) or ())
+    labels = [(e.label or "").strip() for e in elements]
+    return any(OWN_PROFILE.search(l) for l in labels) and not any(OTHER_PROFILE.fullmatch(l) for l in labels if l)
+
+
+def read(snapshot, handle, known=()):
+    """("confirmed", "@acme") | ("mismatch", "@other" or None) | ("unknown", None) for ``handle`` on ``snapshot``."""
+    if not own_profile(snapshot):
+        return "unknown", None
+    top = [e for e in getattr(snapshot, "elements", ()) or () if _top(e)]
+    if any(shows(text, handle) for e in top for text in _texts(e)):
+        return "confirmed", "@" + handle
+    for other in known:
+        if other.casefold() != handle.casefold() and any(shows(t, other) for e in top for t in _texts(e)):
+            return "mismatch", "@" + other
+    for e in top:
+        for text in _texts(e):
+            found = HANDLE_TOKEN.search(text)
+            if found and found.group(1).casefold() != handle.casefold():
+                return "mismatch", "@" + found.group(1)
+    # The navigation bar's title on an own profile is the username (Instagram, Threads).
+    bar = next((e for e in top if e.role == "NavigationBar" and (e.label or "").strip()), None)
+    if bar is not None:
+        title = " ".join(bar.label.split()).split(",")[0].strip()
+        if TITLE_TOKEN.fullmatch(title):
+            return "mismatch", "@" + title
+    return "mismatch", None
+
+
+class AccountCheck:
+    """One run's profile: what was read in its app, and the commit check."""
+
+    def __init__(self, account, known=(), device_name=None, emit=None):
+        self.account = account
+        self.handle = account["handle"]
+        self.bundle = account["app"]["bundleId"]
+        self.app_name = account["app"]["name"]
+        self.known = tuple(known)
+        self.device_name = device_name
+        self.emit = emit or (lambda event: None)
+        self.state, self.shown = "unknown", None
+        # Pacing (accounts/pacing.py) and the run's stop, set by check_for; None in a run without them.
+        self.pacing = None
+        self.cancelled = lambda: False
+        self.on_signal = None   # called with "challenge" or "signed_out" when the screen shows one
+        self.media = None       # content_queue.media_check.MediaCheck for a queued post's task (the queue checks on)
+        self.refusals = 0
+        self.lock = threading.Lock()
+
+    @property
+    def acting_as(self):
+        return display(self.account)
+
+    def look(self, snapshot):
+        """Read ``snapshot`` (in the profile's app only) and keep what it says. Returns (state, shown)."""
+        if getattr(snapshot, "bundle_id", None) != self.bundle:
+            return "unknown", None
+        state, shown = read(snapshot, self.handle, self.known)
+        if state != "confirmed":
+            # A sign-in page or a security check in the profile's app, on a screen that doesn't show the profile: kept
+            # at once for the Phones page and the pre-run check (fleet_health.py), and as an event. The screen's text is
+            # only matched, never followed.
+            from ..fleet_health import classify_screen, snapshot_labels
+            signal = classify_screen(snapshot_labels(snapshot))
+            if signal is not None:
+                self.emit({"event": "account_signal", "account": self.account["id"], "signal": signal})
+                if self.on_signal is not None:
+                    try:
+                        self.on_signal(signal)
+                    except Exception:  # noqa: BLE001 -- keeping a sighting is never part of the run's outcome
+                        pass
+        with self.lock:
+            if state != "unknown":
+                self.state, self.shown = state, shown
+        self.emit({"event": "account_checked", "account": self.account["id"], "state": state})
+        return state, shown
+
+    def commit(self, act, snapshot):
+        """The verdict before a commit ``act`` on ``snapshot``: None (not in the profile's app), {"acting_as"},
+        {"refuse": feedback} or {"stop": reason, "code"}."""
+        if getattr(snapshot, "bundle_id", None) != self.bundle:
+            return None
+        # A later own-profile screen may show a different account. Other screens retain the last check.
+        self.look(snapshot)
+        with self.lock:
+            state, shown = self.state, self.shown
+        if state == "mismatch":
+            return {"stop": self.mismatch_line(act, shown), "code": "account_mismatch"}
+        if state == "confirmed":
+            paced = self.paced(act)
+            if paced is not None:
+                return paced
+            if self.media is not None and act in self.media.POST_ACTS:
+                # A queued post: the app's limited-photos notice ends the task here; otherwise the frontier hands
+                # the screen to ``preview``, and the batch approval answers this Post only when it holds the media.
+                return self.media.stop(snapshot) or {"acting_as": self.acting_as, "preview": self.media.preview}
+            return {"acting_as": self.acting_as}
+        with self.lock:
+            self.refusals += 1
+            if self.refusals >= MAX_REFUSALS:
+                return {"stop": self.unconfirmed_line(act), "code": "account_unconfirmed"}
+        return {"refuse": (f"Refused: confirm the profile first. Open {self.app_name}'s own profile screen (the one "
+                           f"with Edit profile), use CHECK_PROFILE there, and once it confirms @{self.handle}, come "
+                           "back and do this.")}
+
+    def paced(self, act):
+        """The profile's pacing before ``act`` (accounts/pacing.py): None to go on."""
+        if self.pacing is None:
+            return None
+        from .pacing import WAIT_MAX_S
+        try:
+            verdict = self.pacing.check(self.account["id"], act)
+        except Exception:  # noqa: BLE001
+            return {"stop": "Mobster couldn't read this profile's pacing, so it stopped before acting.",
+                    "code": "pacing_unreadable"}
+        if verdict is None:
+            return None
+        if "wait" in verdict and verdict["wait"] <= WAIT_MAX_S:
+            self.emit({"event": "pacing_wait", "account": self.account["id"], "seconds": round(verdict["wait"])})
+            end = time.monotonic() + verdict["wait"]
+            while time.monotonic() < end:
+                if self.cancelled():
+                    return {"stop": "Stopped while waiting for this profile's pace.", "code": "pacing_wait"}
+                time.sleep(min(1.0, end - time.monotonic()))
+            return None
+        if "wait" in verdict:
+            minutes = round(verdict["wait"] / 60)
+            stop = {"stop": f"@{self.handle} {verdict['reason']}; the next can go in {minutes} minutes. Mobster "
+                    "stopped before acting.", "code": "pacing_gap"}
+        else:
+            stop = {"stop": f"@{self.handle}: {verdict['stop']}", "code": verdict.get("code") or "pacing"}
+        if isinstance(verdict.get("until"), (int, float)):
+            stop["until"] = verdict["until"]
+        # The task's record of why it stopped and when the profile may act again (a workflow waits for it).
+        self.emit({"event": "pacing_stop", "account": self.account["id"], "code": stop["code"],
+                   **({"until": stop["until"]} if "until" in stop else {})})
+        return stop
+
+    def mismatch_line(self, act, shown):
+        verb = VERBS.get(act, ("do this", "acting"))
+        who = shown or "another profile"
+        return f"This would {verb[0]} as {who}, not @{self.handle}. Mobster stopped before {verb[1]}."
+
+    def unconfirmed_line(self, act):
+        verb = VERBS.get(act, ("do this", "acting"))[1]
+        where = f" on {self.device_name}" if self.device_name else ""
+        return (f"Mobster couldn't confirm on screen that @{self.handle} is signed in to {self.app_name}, so it "
+                f"stopped before {verb}. Open {self.app_name}{where}, make sure @{self.handle} is the profile signed "
+                f"in, and run the task again.")
+
+
+class CheckAccount:
+    """The CHECK_PROFILE tool (agent_hooks.Skill): reads the screen at hand and says what it shows."""
+
+    op = "CHECK_PROFILE"
+    needs_target = False
+
+    def __init__(self, check):
+        self.check = check
+        self.prompt = (f"- CHECK_PROFILE: confirm the signed-in profile is @{check.handle} in {check.app_name}. Use it "
+                       "on the app's own profile screen (the one with Edit profile) before you post, reply, comment "
+                       "or send a message.")
+
+    def available(self, context):
+        return True
+
+    def prepare(self, context, act, snapshot):
+        from ..agent_hooks import Prepared
+        return Prepared(title=None)
+
+    def perform(self, context, prepared, act, snapshot):
+        from ..agent_hooks import GuardVerdict, SkillResult
+        if getattr(snapshot, "bundle_id", None) != self.check.bundle:
+            return SkillResult(f"This screen isn't {self.check.app_name}. Open {self.check.app_name}'s own profile "
+                               "screen, then use CHECK_PROFILE.")
+        state, shown = self.check.look(snapshot)
+        if state == "confirmed":
+            return SkillResult(f"Confirmed: @{self.check.handle} is the profile signed in to {self.check.app_name}. "
+                               "Go on with the task.")
+        if state == "mismatch":
+            line = (f"{shown or 'Another profile'} is signed in to {self.check.app_name}, not @{self.check.handle}. "
+                    "Mobster stopped before acting as the wrong profile. Switch to "
+                    f"@{self.check.handle} in {self.check.app_name}, then run the task again.")
+            return SkillResult(line, stop=GuardVerdict("stop", "account_mismatch", line))
+        return SkillResult(f"This isn't {self.check.app_name}'s own profile screen (it has no Edit profile, or it "
+                           f"shows Follow or Message). Open the profile tab, then use CHECK_PROFILE.")
+
+
+_checks = {}
+_checks_lock = threading.Lock()
+
+
+def check_for(run_context):
+    """The run's AccountCheck, made once per run from its ``account`` field; None for a run with no profile."""
+    extras = getattr(run_context, "extras", None) or {}
+    account = extras.get("account")
+    if not isinstance(account, dict) or not account.get("id"):
+        return None
+    with _checks_lock:
+        check = _checks.get(run_context.run_id)
+        if check is None:
+            from .store import store_for
+            known = ()
+            try:
+                known = tuple(a["handle"] for a in store_for(run_context.runtime).all()
+                              if a["app"]["bundleId"] == account["app"]["bundleId"] and a["id"] != account["id"])
+            except Exception:  # noqa: BLE001 -- the other handles only name a mismatch better
+                pass
+            check = _checks[run_context.run_id] = AccountCheck(account, known, account.get("deviceName"),
+                                                               emit=run_context.emit)
+            try:
+                from .pacing import pacing_for
+                check.pacing = pacing_for(run_context.runtime)
+            except Exception:  # noqa: BLE001 - a runtime with no data folder (tests): no pacing to keep
+                check.pacing = None
+            check.cancelled = getattr(run_context, "cancelled", None) or (lambda: False)
+            from ..content_queue.media_check import for_run
+            check.media = for_run(run_context)
+            health = getattr(getattr(run_context.runtime, "fleet", None), "health", None)
+            if health is not None:
+                device = run_context.device_id
+                check.on_signal = lambda signal: health.note_screen(account, device, signal)
+        return check
+
+
+def forget(run_id):
+    with _checks_lock:
+        _checks.pop(run_id, None)
+
+
+def commit_check_for(run_context):
+    """The frontier's ``commit_check`` for this run, or None (no profile: the frontier is as before)."""
+    check = check_for(run_context)
+    return check.commit if check is not None else None

mobile_agent/accounts/stats.py

@@ -0,0 +1,54 @@
+"""An account's numbers over time: one row a day per app and handle, in ``account-stats.json`` beside accounts.json."""
+
+import json
+import os
+import tempfile
+import threading
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+FILE = "account-stats.json"
+KEEP_DAYS = 400
+FIELDS = ("followers", "following", "posts", "likes", "period", "views", "reach", "profile_visits", "follower_change")
+_lock = threading.Lock()
+
+
+def _load(folder):
+    try:
+        data = json.loads((Path(folder) / FILE).read_text())
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def record(folder, app, handle, values, now=None):
+    """Merge ``values`` (any of FIELDS) into today's row for ``app`` and ``handle``;
+    a value of None keeps what is there."""
+    now = now or datetime.now(timezone.utc)
+    key, today = f"{app}/{handle.lstrip('@').casefold()}", now.date().isoformat()
+    with _lock:
+        data = _load(folder)
+        rows = data.setdefault(key, {})
+        row = rows.setdefault(today, {})
+        row.update({k: v for k, v in values.items() if k in FIELDS and v is not None})
+        row["at"] = now.isoformat(timespec="seconds")
+        for old in sorted(rows)[:-KEEP_DAYS]:
+            del rows[old]
+        Path(folder).mkdir(parents=True, exist_ok=True)
+        handle_, temporary = tempfile.mkstemp(prefix=".stats.", suffix=".json", dir=folder)
+        with os.fdopen(handle_, "w") as stream:
+            os.fchmod(stream.fileno(), 0o600)
+            stream.write(json.dumps(data, indent=1) + "\n")
+        os.replace(temporary, Path(folder) / FILE)
+
+
+def series(folder, app, handle, days=30, now=None):
+    """{app, handle, days, snapshots: [{date, at, ...FIELDS}] oldest first, latest: newest snapshot or None}."""
+    now = now or datetime.now(timezone.utc)
+    since = (now - timedelta(days=days)).date().isoformat()
+    handle = handle.lstrip("@").casefold()
+    rows = _load(folder).get(f"{app}/{handle}", {})
+    snapshots = [{"date": day, **{k: row.get(k) for k in ("at",) + FIELDS}} for day, row in sorted(rows.items())
+                 if day >= since]
+    return {"app": app, "handle": handle, "days": days, "snapshots": snapshots,
+            "latest": snapshots[-1] if snapshots else None}