pushframe 5.0.0__py3-none-any.whl

pushframe/models/asset.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, model_validator
+
+from pushframe.models.meta import make_partial
+from pushframe.models.user import User
+from pushframe.utils.dt import parse_aura_dt
+
+
+class AssetPadding(BaseModel):
+    top: float
+    right: float
+    bottom: float
+    left: float
+
+
+class AssetSetting(BaseModel):
+    added_by_id: str
+    asset_id: str
+    created_at: str
+    frame_id: str
+    hidden: bool
+    id: str
+    last_impression_at: str
+    reason: str  # TODO: Have only seen "user"
+    selected: bool
+    updated_at: str
+    updated_selected_at: str
+
+
+class Asset(BaseModel):
+    auto_landscape_16_10_rect: Optional[str] = None
+    auto_portrait_4_5_rect: Optional[str] = None
+    burst_id: Any
+    burst_selection_types: Any
+    colorized_file_name: Optional[str] = None
+    # Optional with a None default, not required: whether the live
+    # `/frames/{id}/assets.json` payload sends this field at all is
+    # currently unknown (pydantic silently drops undeclared keys, so its
+    # prior absence here proved nothing either way). Declaring it Optional
+    # makes the value visible when the server does send it and None when it
+    # does not -- additive, and cannot break any existing caller (Phase 11
+    # Plan 03, D-15).
+    created_at: Optional[str] = None
+    created_at_on_client: Optional[str] = None
+    # data_uti/file_name/good_resolution/height/width/upload_priority/taken_at/
+    # uploaded_at are Optional because the live API returns assets that are still
+    # mid-server-side-processing (a freshly-uploaded placeholder): source_id,
+    # local_identifier, user and selected are populated, but the processed
+    # content metadata (dimensions, filenames, dates, data_uti) is null and
+    # good_resolution is omitted entirely until processing completes. See
+    # .planning/debug/resolved/inspect-asset-null-fields.md.
+    data_uti: Optional[str] = None
+    duplicate_of_id: Optional[str] = None
+    duration: Optional[float] = None
+    duration_unclipped: Optional[float] = None
+    exif_orientation: int
+    favorite: Optional[bool] = None
+    file_name: Optional[str] = None
+    glaciered_at: str
+    good_resolution: Optional[bool] = None
+    handled_at: Optional[str] = None
+    hdr: Optional[bool] = None
+    height: Optional[int] = None
+    horizontal_accuracy: Optional[float] = None
+    id: str
+    ios_media_subtypes: Optional[int] = None
+    is_live: Optional[bool] = None
+    is_subscription: bool
+    landscape_16_10_url: Optional[str] = None
+    landscape_16_10_url_padding: Optional[AssetPadding] = None
+    landscape_rect: Optional[str] = None
+    landscape_url: Optional[str] = None
+    landscape_url_padding: Optional[AssetPadding] = None
+    live_photo_off: Optional[bool] = None
+    local_identifier: str
+    location: Optional[list[float]] = None  # Lat/Long, seems to default to (-77.8943033, 34.1978216)
+    location_name: Optional[str] = None
+    md5_hash: Optional[str] = None
+    minibar_landscape_url: Optional[str] = None
+    minibar_portrait_url: Optional[str] = None
+    minibar_url: Optional[str] = None
+    modified_at: Optional[str] = None
+    orientation: Optional[int] = None
+    original_file_name: Optional[str] = None
+    panorama: Optional[bool] = None
+    portrait_4_5_url: Optional[str] = None
+    portrait_4_5_url_padding: Optional[AssetPadding] = None
+    portrait_rect: Optional[str] = None
+    portrait_url: Optional[str] = None
+    portrait_url_padding: Optional[AssetPadding] = None
+    raw_file_name: Optional[str] = None
+    represents_burst: Any
+    rotation_cw: int
+    selected: bool
+    source_id: str
+    taken_at: Optional[str] = None
+    taken_at_granularity: Any
+    taken_at_user_override_at: Optional[str] = None
+    thumbnail_url: Optional[str] = None
+    unglacierable: Optional[bool] = None
+    upload_priority: Optional[int] = None
+    uploaded_at: Optional[str] = None
+    user: User
+    user_id: str
+    user_landscape_16_10_rect: Optional[str] = None
+    user_landscape_rect: Optional[str] = None
+    user_portrait_4_5_rect: Optional[str] = None
+    user_portrait_rect: Optional[str] = None
+    video_clip_excludes_audio: Optional[bool] = None
+    video_clip_start: Any
+    video_clipped_by_user_at: Optional[str] = None
+    video_file_name: Optional[str] = None
+    video_url: Optional[str] = None
+    widget_url: Optional[str] = None
+    width: Optional[int] = None
+
+    @property
+    def taken_at_dt(self):
+        # taken_at is None for an unprocessed placeholder asset (see the field
+        # comment above); parse_aura_dt(None) would raise, and the CLI reads
+        # this property for every listed asset (cli.py inspect/sync), so return
+        # None rather than crash on a not-yet-processed asset.
+        if self.taken_at is None:
+            return None
+        return parse_aura_dt(self.taken_at)
+
+    # `is_local_asset` (formerly `return self.id is None`) was removed:
+    # `id` above is a required `str`, so any `Asset` built through normal
+    # validated construction (the only path used by `FrameApi.get_assets`/
+    # `AssetApi.get_asset_by_local_identifier`) can never have `id=None`.
+    # The property was always `False` and its dependent branches in
+    # `AssetApi` were unreachable dead code. `Asset` (as opposed to
+    # `AssetPartial`) always represents a server-hydrated asset with a
+    # real `id`.
+
+
+class AssetPartialId(BaseModel):
+    id: Optional[str] = None
+    local_identifier: Optional[str] = None
+    user_id: Optional[str] = None
+
+    @model_validator(mode='after')
+    def check_id_or_local_id(self) -> 'AssetPartialId':
+        if not self.id and not self.local_identifier:
+            raise ValueError('Either id or local_identifier is required')
+        return self
+
+    def to_request_format(self):
+        # 'user_id': user_id # in the iphone version user_id is not passed in
+        if self.id:
+            return {'asset_id': self.id}
+        else:
+            return {'asset_local_identifier': self.local_identifier}
+
+
+AssetPartial = make_partial(Asset, "AssetPartial")

pushframe/models/frame.py

@@ -0,0 +1,105 @@
+from enum import Enum
+from typing import Optional
+
+import pydantic
+from pydantic import BaseModel
+
+from pushframe.models.meta import make_partial
+from pushframe.models.user import User
+
+
+class Feature(Enum):
+    SKIP_VIDEO_PRELOAD = 'skip_video_preload'
+    UDP_COMMANDS = 'udp_commands'
+    MQTT_ENABLED = 'mqtt_enabled'
+    # The Aura API is undocumented and adds feature flags over time; map any
+    # value we don't recognise to UNKNOWN instead of raising on hydration, so a
+    # newly-added flag can't break the whole read path (live drift, Phase 2).
+    UNKNOWN = 'unknown'
+
+    @classmethod
+    def _missing_(cls, value):
+        return cls.UNKNOWN
+
+
+class Frame(BaseModel):
+    id: str
+    name: str
+    user_id: str
+    software_version: str
+    build_version: str
+    hw_android_version: str
+    created_at: str
+    updated_at: str
+    handled_at: str
+    deleted_at: Optional[str] = None
+    updated_at_on_client: Optional[str] = None
+    orientation: int
+    auto_brightness: bool
+    min_brightness: int
+    max_brightness: int
+    brightness: Optional[int] = None
+    sense_motion: bool
+    default_speed: Optional[str] = None
+    slideshow_interval: int
+    slideshow_auto: bool
+    digits: int
+    contributors: Optional[list[User]] = None
+    contributor_tokens: list[dict]
+    hw_serial: str
+    matting_color: str
+    trim_color: str
+    is_handling: bool
+    calibrations_last_modified_at: str
+    gestures_on: bool
+    portrait_pairing_off: Optional[bool] = None
+    live_photos_on: bool
+    auto_processed_playlist_ids: list[object]  # unknown
+    time_zone: str
+    wifi_network: str
+    cold_boot_at: Optional[str] = None
+    is_charity_water_frame: bool
+    num_assets: int
+    thanks_on: bool
+    frame_queue_url: Optional[str] = None
+    client_queue_url: str
+    scheduled_display_sleep: bool
+    scheduled_display_on_at: Optional[str] = None
+    scheduled_display_off_at: Optional[str] = None
+    forced_wifi_state: Optional[str] = None
+    forced_wifi_recipient_email: Optional[str] = None
+    is_analog_frame: bool
+    control_type: str
+    display_aspect_ratio: str
+    has_claimable_gift: Optional[bool] = None
+    gift_billing_hint: Optional[str] = None
+    locale: str
+    frame_type: Optional[int] = None
+    description: Optional[str] = None
+    representative_asset_id: Optional[str] = None
+    sort_mode: Optional[str] = None
+    email_address: str
+    features: Optional[list[Feature]] = None
+    letterbox_style: Optional[str] = None
+    user: User
+    playlists: list[dict]  # TODO
+    delivered_frame_gift: Optional[dict] = None  # TODO
+    last_feed_item: dict
+    last_impression: Optional[dict] = None
+    last_impression_at: str
+    child_albums: list
+    # The live API stopped returning `smart_adds` on /frames.json and
+    # /frames/{id}.json (live drift, Phase 10). Optional-with-default so an
+    # absent key can't break the whole read path -- same treatment as the
+    # Phase 2 `total_asset_count` -> `num_assets` move.
+    smart_adds: list = pydantic.Field(default_factory=list)
+    recent_assets: list
+
+    def is_portrait(self):
+        return self.orientation == 2 or self.orientation == 3
+
+    def get_frame_type(self):
+        return self.frame_type if self.frame_type else "normal"
+
+
+FramePartial = make_partial(Frame, "FramePartial")

pushframe/models/meta.py

@@ -0,0 +1,11 @@
+from typing import Optional
+
+from pydantic import BaseModel, create_model
+
+
+def make_partial(model: type[BaseModel], name: str) -> type[BaseModel]:
+    fields = {
+        fname: (Optional[finfo.annotation], None)
+        for fname, finfo in model.model_fields.items()
+    }
+    return create_model(name, __base__=model, **fields)

pushframe/models/person.py

@@ -0,0 +1,24 @@
+from pydantic import BaseModel
+
+
+class Person(BaseModel):
+    id: str
+    created_at: str
+    name: str
+    published_at: str
+    similar_people_ids: list[str]
+    thumb_file_name: str
+    updated_at: str
+    user_id: str
+
+
+class PersonAssetSetting(BaseModel):
+    asset_local_identifier: str
+    created_at: str
+    detected_face_id: str
+    id: str
+    person_id: str
+    source_id: str
+    updated_at: str
+    user_action: str
+    user_action_updated_at: str

pushframe/models/user.py

@@ -0,0 +1,22 @@
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    id: str
+    created_at: str
+    updated_at: str
+    name: str
+    email: str
+    short_id: Optional[str] = None
+    show_push_prompt: bool
+    latest_app_version: Optional[str] = None
+    attribution_id: Optional[str] = None
+    attribution_string: Optional[str] = None
+    test_account: Optional[bool] = None
+    avatar_file_name: Optional[str] = None
+    has_frame: Optional[bool] = None
+    analytics_optout: bool = None
+    admin_account: Optional[bool] = False
+    auth_token: str = None

pushframe/ratelimit.py

@@ -0,0 +1,222 @@
+"""Standalone, injectable write-rate-budget + geo pre-flight guard module
+(Phase 09: proactive-write-rate-limiter-geo-guard).
+
+`WriteBudget` is a client-side token bucket that makes the Pushd anti-abuse
+write-lockout structurally hard to hit: callers must `acquire()` tokens
+before issuing a batch of write network calls, either waiting for enough
+tokens to refill or stopping cleanly before ever making the call.
+
+`check_geo` is a pre-flight guard comparing the caller's current exit-IP
+country against the account's expected country -- root-cause mitigation for
+the VPN-geo-mismatch write-lockout this phase's research identified.
+
+This module touches no existing source and has no side effects at import
+time -- it never calls `datetime.utcnow()`, `time.sleep()`, or `httpx`
+directly during any *tested* path. `now`, `sleep`, and `resolver` are all
+injected by the caller (mirroring the `sleep=time.sleep` seam already used
+by `pushframe.sync.execute_plan`), so this module is 100% offline-testable.
+
+`WriteBudget.save()`/`load()` persist ONLY `tokens` + `updated_at` to a
+per-account JSON state file -- never the email, password, or any auth
+token (see the phase's threat register, T-09-02).
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import httpx
+from loguru import logger
+
+
+class BudgetExhausted(Exception):
+    """Raised by `WriteBudget.acquire()` in stop mode (`wait=False`, or a
+    computed `wait_seconds` exceeding `max_wait`) instead of ever making the
+    gated write call. Carries `wait_seconds` so the CLI (Plan 09-02) can
+    print how long a retry would need to wait."""
+
+    def __init__(self, wait_seconds: float):
+        self.wait_seconds = wait_seconds
+        super().__init__(
+            f'Write budget exhausted; would need to wait {wait_seconds:.1f}s '
+            'for enough tokens to refill.'
+        )
+
+
+class GeoMismatchError(Exception):
+    """Raised by `check_geo()` when the resolved exit-IP country does not
+    match the account's expected country. Carries `found` + `expected` so
+    the CLI (Plan 09-02) can print an actionable "switch your VPN" message."""
+
+    def __init__(self, found: str, expected: str):
+        self.found = found
+        self.expected = expected
+        super().__init__(
+            f'VPN/exit IP in {found}, account expects {expected} -- '
+            'switch your VPN and retry.'
+        )
+
+
+@dataclass
+class WriteBudget:
+    """A per-account client-side token bucket gating batches of Pushd write
+    network calls. Mirrors the `ExecutionResult`/`SyncPlan` plain-dataclass
+    style used in `pushframe/sync.py` (pydantic is reserved for API DTOs).
+
+    `path` is a constructor field (never hardcoded internally) so tests
+    always pass a pytest `tmp_path` value and production wiring (Plan 09-02)
+    computes the real `~/.config/pushframe/...` path at the CLI boundary.
+    """
+
+    capacity: float
+    refill_per_min: float
+    path: Path
+    tokens: float = 0.0
+    updated_at: datetime | None = None
+
+    def acquire(self, n, *, wait, max_wait, now, sleep, on_wait=None) -> None:
+        """Refill by elapsed minutes since `updated_at` (clamped to >=0 per
+        the clock-skew/None-updated_at Pitfall 2 fix), cap at `capacity`,
+        then either consume `n` tokens immediately, wait for them (sleeping
+        in 1s steps via the injected `sleep`, surfacing `on_wait(remaining)`
+        each second -- mirrors `execute_plan.interchunk_pause()`), or raise
+        `BudgetExhausted` if `wait=False` or the wait would exceed `max_wait`.
+
+        `now` is a VALUE supplied by the caller, never read internally --
+        this module never calls `datetime.utcnow()`.
+        """
+        elapsed_minutes = max(0.0, (now - (self.updated_at or now)).total_seconds() / 60.0)
+        self.tokens = min(self.capacity, self.tokens + self.refill_per_min * elapsed_minutes)
+        self.updated_at = now
+
+        if self.tokens >= n:
+            self.tokens -= n
+            return
+
+        # WR-03: a non-positive refill rate (e.g. AURA_WRITE_BUDGET_REFILL_PER_MIN=0
+        # to "pause" writes) can never satisfy the deficit -- the wait would be
+        # infinite -- and dividing by it below would raise ZeroDivisionError.
+        # Treat it as an immediate, clean stop instead.
+        if self.refill_per_min <= 0:
+            raise BudgetExhausted(float('inf'))
+
+        wait_seconds = (n - self.tokens) / self.refill_per_min * 60.0
+        if not wait or wait_seconds > max_wait:
+            raise BudgetExhausted(wait_seconds)
+
+        remaining = wait_seconds
+        while remaining > 0:
+            if on_wait:
+                on_wait(remaining)
+            step = 1.0 if remaining >= 1.0 else remaining
+            sleep(step)
+            remaining -= step
+
+        # Waiting `wait_seconds` accrues exactly the deficit (`n - tokens`)
+        # tokens -- reaching `n`, NOT `capacity` (wait_seconds was derived so
+        # the deficit closes exactly). Resetting to `capacity` here would
+        # over-grant `capacity - n` tokens on every wait and defeat the
+        # anti-burst rate limit. Advance `updated_at` by the waited interval
+        # so the next acquire() does not re-count it as fresh elapsed time.
+        self.tokens = min(self.capacity, self.tokens + self.refill_per_min * wait_seconds / 60.0)
+        self.updated_at = self.updated_at + timedelta(seconds=wait_seconds)
+        self.tokens -= n
+
+    def reconcile_tripped(self, now) -> None:
+        """Force the bucket to empty (tokens=0, updated_at=now) after a real
+        anti-abuse trip (`RateLimitError`/`ConsecutiveWriteFailureError`) so
+        the next run's proactive budget reflects reality even though the
+        server-side trip wasn't caused by this bucket running dry."""
+        self.tokens = 0
+        self.updated_at = now
+
+    def save(self) -> None:
+        """Write `tokens` + `updated_at` (isoformat, or null) as JSON to
+        `self.path`, creating parent directories as needed. No path
+        argument -- always writes to the field set at construction, so
+        callers can call a bare `budget.save()`. Persists no credential
+        material (T-09-02).
+
+        WR-02: the write is atomic (temp file in the same dir + `os.replace`)
+        so an interrupted write (Ctrl-C, disk full, crash mid-write) can never
+        leave a truncated JSON file that would brick every subsequent run."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps({
+            'tokens': self.tokens,
+            'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+        })
+        tmp_path = self.path.with_name(self.path.name + '.tmp')
+        tmp_path.write_text(payload)
+        os.replace(tmp_path, self.path)
+
+    @classmethod
+    def load(cls, path: Path, *, capacity: float, refill_per_min: float) -> 'WriteBudget':
+        """Reconstruct a `WriteBudget` from `path`. If `path` does not
+        exist, returns a fresh bucket (tokens=0, updated_at=None) without
+        raising -- the common case for a first-ever run.
+
+        WR-02: a corrupt/truncated state file (bad JSON, missing keys, or an
+        unparseable `updated_at`) also falls back to a fresh bucket with a
+        warning rather than raising -- a single bad file must never brick every
+        subsequent `push` / `sync --apply`."""
+        if not path.exists():
+            return cls(capacity=capacity, refill_per_min=refill_per_min, path=path)
+        try:
+            data = json.loads(path.read_text())
+            tokens = data['tokens']
+            updated_at = datetime.fromisoformat(data['updated_at']) if data['updated_at'] else None
+        except (json.JSONDecodeError, KeyError, TypeError, ValueError):
+            logger.warning(f'Corrupt write-budget state at {path}; starting fresh.')
+            return cls(capacity=capacity, refill_per_min=refill_per_min, path=path)
+        return cls(
+            capacity=capacity, refill_per_min=refill_per_min, path=path,
+            tokens=tokens,
+            updated_at=updated_at,
+        )
+
+
+def _default_resolver() -> str:
+    """Production default resolver for `check_geo`: a bare, short-timeout
+    `httpx.get` to ipinfo.io's unauthenticated legacy endpoint. Deliberately
+    NOT routed through `pushframe.client.Client` -- that abstraction is
+    Pushd-specific (base URL, headers, 429/475 classification) and would be
+    misused here. No retry/backoff (YAGNI) -- `check_geo`'s fail-open
+    default is the correct mitigation for a resolver hiccup.
+
+    Never invoked by this module's own test suite (would violate the
+    100%-offline test requirement) -- tests always inject a fake `resolver`.
+    """
+    response = httpx.get('https://ipinfo.io/json', timeout=4.0)
+    response.raise_for_status()
+    return response.json()['country']
+
+
+def check_geo(expected_country, *, resolver=_default_resolver, fail_open: bool = True):
+    """Pre-flight guard comparing the caller's current exit-IP country
+    (via `resolver()`) against `expected_country`. Raises `GeoMismatchError`
+    on a mismatch; returns None (no-op) on a match or when `expected_country`
+    is falsy (feature disabled/unconfigured -- resolver is not even called).
+
+    Fails OPEN by default (`fail_open=True`): a resolver exception (network
+    error, ipinfo.io outage/throttle) logs a warning and returns None rather
+    than blocking a legitimate write -- mirroring this codebase's existing
+    "best-effort/observational, never gates the primary operation" precedent
+    (`execute_plan`'s SQS poll, `pushframe/sync.py:460-461`). Pass
+    `fail_open=False` to fail CLOSED instead (the resolver's exception
+    propagates).
+    """
+    if not expected_country:
+        return None
+    try:
+        found = resolver()
+    except Exception as e:
+        if fail_open:
+            logger.warning(f'Geo pre-flight resolver failed ({e}); proceeding (fail-open).')
+            return None
+        raise
+    if found.upper() != expected_country.upper():
+        raise GeoMismatchError(found, expected_country)
+    return None