steamsift 0.1.0__tar.gz

steamsift-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sift contributors
+
+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.

steamsift-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: steamsift
+Version: 0.1.0
+Summary: Steam deals, sifted: every discount checked against two years of prices. HOT, GREAT, OK, MEH or NOPE.
+Author: sa1ntsinner
+License-Expression: MIT
+Project-URL: Homepage, https://sa1ntsinner.github.io/sift/
+Project-URL: Source, https://github.com/sa1ntsinner/sift
+Project-URL: Issues, https://github.com/sa1ntsinner/sift/issues
+Keywords: steam,deals,sale,wishlist,recommendations,telegram,cli,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Russian
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: keyring>=24.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: textual>=1.0
+Requires-Dist: textual-image>=0.8
+Requires-Dist: pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pyyaml>=6; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sa1ntsinner/sift/main/assets/sift-wordmark.png" alt="sift" width="200" />
+</p>
+
+<p align="center"><em>Steam has thousands of discounts. sift tells you which ones are worth it.</em></p>
+
+<p align="center">
+  <a href="https://sa1ntsinner.github.io/sift/"><img src="https://img.shields.io/badge/website-sift-2bff88?style=flat" alt="Website" /></a>
+  &nbsp;
+  <a href="https://github.com/sa1ntsinner/sift/releases/latest"><img src="https://img.shields.io/github/v/release/sa1ntsinner/sift?style=flat&color=24292f" alt="Latest release" /></a>
+  &nbsp;
+  <img src="https://img.shields.io/badge/Windows%20·%20macOS%20·%20Linux-24292f?style=flat" alt="Windows, macOS, Linux" />
+  &nbsp;
+  <a href="https://pypi.org/project/steamsift/"><img src="https://img.shields.io/pypi/v/steamsift?style=flat&color=24292f&label=pypi" alt="PyPI" /></a>
+  &nbsp;
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-24292f?style=flat" alt="MIT license" /></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sa1ntsinner/sift/main/assets/sift.gif" alt="sift in a terminal: a list of Steam deals with a verdict on each, the filter panel and the wishlist" width="100%" />
+</p>
+
+sift is a free terminal app for Steam deals. It reads two years of Steam prices for every discount, checks how often
+the game goes on sale, whether the base price was just raised, whether a big sale is days away and what your Steam
+Family already owns, and gives each deal one word.
+
+Most "record lows" on Steam come back every five or six weeks. sift tells those apart from the prices that rarely
+show up, so you buy the right game at the right moment and skip the rest.
+
+## Verdicts
+
+| | |
+|---|---|
+| **HOT** | A price that rarely comes back: a rare record, the lowest in two years, or a cheaper bundle. |
+| **GREAT** | A record price, but it returns every few weeks. Buy it when you will play it. |
+| **OK** | An ordinary discount for this game. |
+| **MEH** | It has been 12–30% cheaper, or a big Steam sale is under three weeks away. |
+| **NOPE** | It has been much cheaper, or the base price went up just before the sale. |
+
+Prices are compared in what you pay, not in percent: $15 at −60% is not a record if the game once sold for $5.
+
+## Install
+
+**Download** one file from the [latest release](https://github.com/sa1ntsinner/sift/releases/latest):
+`sift-windows-x64.exe`, `sift-macos-arm64` or `sift-linux-x64`. Nothing else to install.
+
+**Or with Python 3.11+**
+
+```bash
+uv tool install steamsift      # or: pipx install steamsift
+sift
+```
+
+## First run
+
+`sift` opens a three-minute setup. It can look on your computer for your Steam account and Steam Family (only Steam's
+own files, nothing is sent anywhere). You paste two free keys, and sift picks them up from the clipboard as soon as you
+copy them:
+
+| | where | |
+|---|---|---|
+| Steam Web API key | [steamcommunity.com/dev/apikey](https://steamcommunity.com/dev/apikey) | domain: `localhost` · confirm in the Steam mobile app |
+| IsThereAnyDeal API key | [isthereanydeal.com/apps/my](https://isthereanydeal.com/apps/my/) | Register app → copy the API key · optional, but it powers the verdicts |
+
+Steam only issues API keys to accounts that have spent at least $5 and use Steam Guard Mobile.
+
+## Using it
+
+The app has four tabs (Deals · Wishlist · Discover · DLC), a verdict on every row and the game's two-year sale history
+next to it. Everything works from the keyboard:
+
+| key | | key | |
+|---|---|---|---|
+| `↑ ↓` `j k` | move | `/` | search |
+| `enter` | open in Steam | `f` | filters, saved filters, hidden games |
+| `1–4` `← →` | tabs | `s` | sort |
+| `x` | hide: not for me | `u` | undo |
+| `i` | price history on IsThereAnyDeal | `?` | every key |
+
+The same filters work as flags, so a search can be one line:
+
+```bash
+sift --hot -b 10              # only HOT deals under 10 in your store's currency
+sift -g roguelike --deck      # roguelikes that run on the Steam Deck
+sift macro add cheap -b 2 --lowest && sift cheap
+sift info "hollow knight"     # price, history and verdict for one game
+sift --print                  # a plain table for scripts; sift -J prints JSON
+```
+
+## Alerts
+
+`sift notify setup telegram` (or `discord`, `ntfy`, `desktop`, `email`) sends a few cards a day: HOT prices, your own
+price targets and wishlist records that are about to end. Never the whole sale.
+
+Run it on a schedule with `sift notify enable`, keep it running with `sift watch`, or run it in the cloud with
+[GitHub Actions](packaging/github-actions/sift.yml) or [Docker](compose.yaml) while your PC is off.
+
+## What it knows
+
+- **Your store.** Prices in the currency Steam charges you, in whichever Steam region your account is in.
+- **Your Steam Family.** Shared games stay out of the list, or show with a blue mark if you want them.
+- **Your library.** Owned and hidden games never show up; DLC is listed for the games you own.
+- **Your taste, second.** Deals come first; your play history breaks ties and fills the Discover tab.
+
+Everything stays on your computer: keys in the system keychain, settings in a local file. sift talks only to Steam and
+IsThereAnyDeal.
+
+## More
+
+`sift doctor` checks keys, privacy settings, region and family. `sift config help` lists every setting.
+`sift calendar` shows the Steam sales ahead. The app speaks English and Russian (`sift config set lang ru`).
+
+---
+
+<p align="center"><sub>MIT license · not affiliated with Valve · price history from <a href="https://isthereanydeal.com">IsThereAnyDeal</a></sub></p>

steamsift-0.1.0/README.md

@@ -0,0 +1,115 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sa1ntsinner/sift/main/assets/sift-wordmark.png" alt="sift" width="200" />
+</p>
+
+<p align="center"><em>Steam has thousands of discounts. sift tells you which ones are worth it.</em></p>
+
+<p align="center">
+  <a href="https://sa1ntsinner.github.io/sift/"><img src="https://img.shields.io/badge/website-sift-2bff88?style=flat" alt="Website" /></a>
+  &nbsp;
+  <a href="https://github.com/sa1ntsinner/sift/releases/latest"><img src="https://img.shields.io/github/v/release/sa1ntsinner/sift?style=flat&color=24292f" alt="Latest release" /></a>
+  &nbsp;
+  <img src="https://img.shields.io/badge/Windows%20·%20macOS%20·%20Linux-24292f?style=flat" alt="Windows, macOS, Linux" />
+  &nbsp;
+  <a href="https://pypi.org/project/steamsift/"><img src="https://img.shields.io/pypi/v/steamsift?style=flat&color=24292f&label=pypi" alt="PyPI" /></a>
+  &nbsp;
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-24292f?style=flat" alt="MIT license" /></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sa1ntsinner/sift/main/assets/sift.gif" alt="sift in a terminal: a list of Steam deals with a verdict on each, the filter panel and the wishlist" width="100%" />
+</p>
+
+sift is a free terminal app for Steam deals. It reads two years of Steam prices for every discount, checks how often
+the game goes on sale, whether the base price was just raised, whether a big sale is days away and what your Steam
+Family already owns, and gives each deal one word.
+
+Most "record lows" on Steam come back every five or six weeks. sift tells those apart from the prices that rarely
+show up, so you buy the right game at the right moment and skip the rest.
+
+## Verdicts
+
+| | |
+|---|---|
+| **HOT** | A price that rarely comes back: a rare record, the lowest in two years, or a cheaper bundle. |
+| **GREAT** | A record price, but it returns every few weeks. Buy it when you will play it. |
+| **OK** | An ordinary discount for this game. |
+| **MEH** | It has been 12–30% cheaper, or a big Steam sale is under three weeks away. |
+| **NOPE** | It has been much cheaper, or the base price went up just before the sale. |
+
+Prices are compared in what you pay, not in percent: $15 at −60% is not a record if the game once sold for $5.
+
+## Install
+
+**Download** one file from the [latest release](https://github.com/sa1ntsinner/sift/releases/latest):
+`sift-windows-x64.exe`, `sift-macos-arm64` or `sift-linux-x64`. Nothing else to install.
+
+**Or with Python 3.11+**
+
+```bash
+uv tool install steamsift      # or: pipx install steamsift
+sift
+```
+
+## First run
+
+`sift` opens a three-minute setup. It can look on your computer for your Steam account and Steam Family (only Steam's
+own files, nothing is sent anywhere). You paste two free keys, and sift picks them up from the clipboard as soon as you
+copy them:
+
+| | where | |
+|---|---|---|
+| Steam Web API key | [steamcommunity.com/dev/apikey](https://steamcommunity.com/dev/apikey) | domain: `localhost` · confirm in the Steam mobile app |
+| IsThereAnyDeal API key | [isthereanydeal.com/apps/my](https://isthereanydeal.com/apps/my/) | Register app → copy the API key · optional, but it powers the verdicts |
+
+Steam only issues API keys to accounts that have spent at least $5 and use Steam Guard Mobile.
+
+## Using it
+
+The app has four tabs (Deals · Wishlist · Discover · DLC), a verdict on every row and the game's two-year sale history
+next to it. Everything works from the keyboard:
+
+| key | | key | |
+|---|---|---|---|
+| `↑ ↓` `j k` | move | `/` | search |
+| `enter` | open in Steam | `f` | filters, saved filters, hidden games |
+| `1–4` `← →` | tabs | `s` | sort |
+| `x` | hide: not for me | `u` | undo |
+| `i` | price history on IsThereAnyDeal | `?` | every key |
+
+The same filters work as flags, so a search can be one line:
+
+```bash
+sift --hot -b 10              # only HOT deals under 10 in your store's currency
+sift -g roguelike --deck      # roguelikes that run on the Steam Deck
+sift macro add cheap -b 2 --lowest && sift cheap
+sift info "hollow knight"     # price, history and verdict for one game
+sift --print                  # a plain table for scripts; sift -J prints JSON
+```
+
+## Alerts
+
+`sift notify setup telegram` (or `discord`, `ntfy`, `desktop`, `email`) sends a few cards a day: HOT prices, your own
+price targets and wishlist records that are about to end. Never the whole sale.
+
+Run it on a schedule with `sift notify enable`, keep it running with `sift watch`, or run it in the cloud with
+[GitHub Actions](packaging/github-actions/sift.yml) or [Docker](compose.yaml) while your PC is off.
+
+## What it knows
+
+- **Your store.** Prices in the currency Steam charges you, in whichever Steam region your account is in.
+- **Your Steam Family.** Shared games stay out of the list, or show with a blue mark if you want them.
+- **Your library.** Owned and hidden games never show up; DLC is listed for the games you own.
+- **Your taste, second.** Deals come first; your play history breaks ties and fills the Discover tab.
+
+Everything stays on your computer: keys in the system keychain, settings in a local file. sift talks only to Steam and
+IsThereAnyDeal.
+
+## More
+
+`sift doctor` checks keys, privacy settings, region and family. `sift config help` lists every setting.
+`sift calendar` shows the Steam sales ahead. The app speaks English and Russian (`sift config set lang ru`).
+
+---
+
+<p align="center"><sub>MIT license · not affiliated with Valve · price history from <a href="https://isthereanydeal.com">IsThereAnyDeal</a></sub></p>

steamsift-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=69.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "steamsift"
+version = "0.1.0"
+description = "Steam deals, sifted: every discount checked against two years of prices. HOT, GREAT, OK, MEH or NOPE."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "sa1ntsinner" }]
+keywords = ["steam", "deals", "sale", "wishlist", "recommendations", "telegram", "cli", "tui"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Natural Language :: English",
+    "Natural Language :: Russian",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Games/Entertainment",
+]
+dependencies = [
+    "rich>=13.0.0",
+    "requests>=2.28.0",
+    "python-dotenv>=1.0.0",
+    "platformdirs>=4.0",
+    "keyring>=24.0",
+    "tomli-w>=1.0",
+    "textual>=1.0",
+    "textual-image>=0.8",
+    "pillow>=10.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pyyaml>=6", "build", "twine"]
+
+[project.urls]
+Homepage = "https://sa1ntsinner.github.io/sift/"
+Source = "https://github.com/sa1ntsinner/sift"
+Issues = "https://github.com/sa1ntsinner/sift/issues"
+
+[project.scripts]
+sift = "steamsift.cli:entry"
+steamsift = "steamsift.cli:entry"
+ss = "steamsift.cli:entry"
+
+[tool.setuptools]
+packages = ["steamsift", "steamsift.notify", "steamsift.tui"]
+
+[tool.setuptools.package-data]
+steamsift = ["data/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

steamsift-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

steamsift-0.1.0/steamsift/__init__.py

@@ -0,0 +1,3 @@
+"""sift — taste-aware Steam deals for you and your Steam Family."""
+
+__version__ = "0.1.0"

steamsift-0.1.0/steamsift/__main__.py

@@ -0,0 +1,4 @@
+from .cli import entry
+
+if __name__ == "__main__":
+    entry()

steamsift-0.1.0/steamsift/autodetect.py

@@ -0,0 +1,106 @@
+"""What setup can find on this computer, only when the user agrees: Steam accounts, Steam Family, keys.
+
+Nothing is sent anywhere. We read Steam's own text files (config/loginusers.vdf, userdata/*/localconfig.vdf)
+and, while a key step is open, the clipboard, so a key copied from the browser fills itself in.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+
+from .localsteam import ci_get, family_from_client, parse_vdf, steam_roots
+
+STEAM_KEY = re.compile(r"\b[0-9A-F]{32}\b")
+ITAD_KEY = re.compile(r"\b[0-9a-f]{40}\b")
+
+
+@dataclass
+class Account:
+    steam_id: str
+    persona: str
+    recent: bool = False
+    stamp: int = 0
+
+
+@dataclass
+class Found:
+    steam_root: str = ""
+    accounts: list[Account] = field(default_factory=list)
+    family: dict = field(default_factory=dict)
+
+    @property
+    def account(self) -> Account | None:
+        return self.accounts[0] if self.accounts else None
+
+
+def accounts() -> list[Account]:
+    """Accounts that signed in to Steam on this PC, the one used last first."""
+    out: dict[str, Account] = {}
+    for root in steam_roots():
+        path = root / "config" / "loginusers.vdf"
+        try:
+            users = ci_get(parse_vdf(path.read_text(encoding="utf-8", errors="ignore")), "users") or {}
+        except OSError:
+            continue
+        for sid, u in users.items() if isinstance(users, dict) else []:
+            if not (isinstance(u, dict) and str(sid).isdigit() and len(str(sid)) == 17):
+                continue
+            stamp = ci_get(u, "Timestamp") or "0"
+            out.setdefault(sid, Account(sid, ci_get(u, "PersonaName") or "", ci_get(u, "MostRecent") == "1",
+                                        int(stamp) if str(stamp).isdigit() else 0))
+    return sorted(out.values(), key=lambda a: (not a.recent, -a.stamp))
+
+
+def scan() -> Found:
+    roots = steam_roots()
+    found = Found(steam_root=str(roots[0]) if roots else "", accounts=accounts())
+    if found.account:
+        found.family = family_from_client(found.account.steam_id)
+    return found
+
+
+def clipboard_text() -> str:
+    """The clipboard as text, or '' when it can't be read (no display, no tool, not text)."""
+    try:
+        if sys.platform == "win32":
+            return _windows_clipboard()
+        for cmd in (["pbpaste"], ["wl-paste", "--no-newline"], ["xclip", "-selection", "clipboard", "-o"],
+                    ["xsel", "--clipboard", "--output"]):
+            if shutil.which(cmd[0]):
+                return subprocess.run(cmd, capture_output=True, text=True, timeout=2).stdout
+    except (OSError, subprocess.SubprocessError, ValueError):
+        pass
+    return ""
+
+
+def _windows_clipboard() -> str:
+    import ctypes
+    from ctypes import wintypes
+    user32, kernel32 = ctypes.windll.user32, ctypes.windll.kernel32
+    user32.GetClipboardData.restype = wintypes.HANDLE
+    kernel32.GlobalLock.argtypes = [wintypes.HGLOBAL]
+    kernel32.GlobalLock.restype = wintypes.LPVOID
+    kernel32.GlobalUnlock.argtypes = [wintypes.HGLOBAL]
+    CF_UNICODETEXT = 13
+    if not user32.OpenClipboard(None):
+        return ""
+    try:
+        handle = user32.GetClipboardData(CF_UNICODETEXT)
+        if not handle:
+            return ""
+        ptr = kernel32.GlobalLock(handle)
+        try:
+            return ctypes.wstring_at(ptr) if ptr else ""
+        finally:
+            kernel32.GlobalUnlock(handle)
+    finally:
+        user32.CloseClipboard()
+
+
+def key_in(text: str, kind: str) -> str:
+    """The first Steam (32 hex, upper case) or ITAD (40 hex, lower case) key in `text`."""
+    m = (STEAM_KEY if kind == "steam" else ITAD_KEY).search(text or "")
+    return m.group(0) if m else ""

steamsift-0.1.0/steamsift/calendar.py

@@ -0,0 +1,145 @@
+"""Steam sale calendar, parsed from Valve's public partner page (seasonal sales + themed fests).
+
+Used for "wait — the Summer Sale starts in 9 days" hints and for fests matching your taste.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import html as htmllib
+import re
+from dataclasses import dataclass, field
+
+from .db import DAY, Cache
+from .net import SESSION
+
+URL = "https://partner.steamgames.com/doc/marketing/upcoming_events"
+_cache = Cache("calendar")
+
+# Themed fests -> the Steam tags whose games usually get discounted during them.
+FEST_TAGS: dict[str, list[str]] = {
+    "Racing Fest": ["Racing", "Driving", "Automobile Sim"],
+    "Steam Scream": ["Horror", "Psychological Horror", "Survival Horror"],
+    "Real-Time Strategy Fest": ["RTS", "Strategy"],
+    "Fighting Fest": ["Fighting", "2D Fighter", "3D Fighter", "Beat 'em up"],
+    "Rhythm Fest": ["Rhythm", "Music"],
+    "Couch Co-Op Fest": ["Local Co-Op", "Local Multiplayer"],
+    "Cooking Fest": ["Cooking"],
+    "Shop Keeper Fest": ["Management", "Economy"],
+    "Dinos vs. Robots Fest": ["Dinosaurs", "Robots", "Mechs"],
+    "Witch Fest": ["Magic", "Witch"],
+    "Mountaineering Fest": ["Climbing"],
+    "Medieval Fest": ["Medieval"],
+    "Auto-Battler RPG Fest": ["Auto Battler"],
+    "Survival Fest": ["Survival"],
+    "Open World Survival Craft Fest": ["Open World Survival Craft"],
+    "Simulation Fest": ["Simulation"],
+    "Puzzle Fest": ["Puzzle"],
+    "Sports Fest": ["Sports"],
+    "Strategy Fest": ["Strategy"],
+}
+
+_MONTHS = {m: i for i, m in enumerate(
+    ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"], 1)}
+
+
+@dataclass
+class Event:
+    name: str
+    kind: str                  # "sale" (seasonal, store-wide) | "fest" (themed)
+    start: dt.date
+    end: dt.date
+    tags: list[str] = field(default_factory=list)
+
+    def to_json(self) -> dict:
+        return {"name": self.name, "kind": self.kind, "start": self.start.isoformat(),
+                "end": self.end.isoformat(), "tags": self.tags}
+
+    @classmethod
+    def from_json(cls, d: dict) -> "Event":
+        return cls(d["name"], d["kind"], dt.date.fromisoformat(d["start"]), dt.date.fromisoformat(d["end"]),
+                   d.get("tags", []))
+
+
+def _date(text: str) -> dt.date | None:
+    m = re.match(r"(\d{1,2})\s+([A-Za-z]+),?\s+(\d{4})", text.strip())
+    if not m:
+        return None
+    month = _MONTHS.get(m.group(2)[:3].lower())
+    return dt.date(int(m.group(3)), month, int(m.group(1))) if month else None
+
+
+def _plain(fragment: str) -> str:
+    return re.sub(r"\s+", " ", htmllib.unescape(re.sub(r"<[^>]+>", " ", fragment))).strip()
+
+
+def parse(page: str) -> list[Event]:
+    events: list[Event] = []
+    text = _plain(page)
+    for m in re.finditer(r"(Spring|Summer|Autumn|Winter) Sale (\d{4})\s*\|?\s*(\d{1,2} [A-Za-z]+,? \d{4})\s*[-–]\s*"
+                         r"(\d{1,2} [A-Za-z]+,? \d{4})", text):
+        start, end = _date(m.group(3)), _date(m.group(4))
+        if start and end:
+            events.append(Event(f"Steam {m.group(1)} Sale", "sale", start, end))
+
+    # Themed fests live in tables that follow "<year> Fests" headings.
+    year = None
+    for m in re.finditer(r"(20\d\d) Fests|<tr[^>]*>(.*?)</tr>", page, re.S):
+        if m.group(1):
+            year = int(m.group(1))
+            continue
+        if year is None:
+            continue
+        cells = [_plain(c) for c in re.findall(r"<t[dh][^>]*>(.*?)</t[dh]>", m.group(2), re.S)]
+        if len(cells) < 2:
+            continue
+        d = re.match(r"([A-Za-z]{3})[a-z]*\.? (\d{1,2})\s*[-–]?\s*(?:([A-Za-z]{3})[a-z]*\.? )?(\d{1,2})$", cells[0])
+        if not d:
+            continue
+        m1, d1 = _MONTHS.get(d.group(1).lower()), int(d.group(2))
+        m2, d2 = _MONTHS.get((d.group(3) or d.group(1)).lower()), int(d.group(4))
+        if not m1 or not m2:
+            continue
+        start = dt.date(year, m1, d1)
+        end = dt.date(year + (1 if m2 < m1 else 0), m2, d2)
+        name = cells[1]
+        tags = next((v for k, v in FEST_TAGS.items() if k.lower() in name.lower()), [])
+        events.append(Event(name, "fest", start, end, tags))
+
+    uniq = {(e.name, e.start): e for e in events}
+    return sorted(uniq.values(), key=lambda e: e.start)
+
+
+def events() -> list[Event]:
+    cached = _cache.get("events", 7 * DAY)
+    if cached is not None:
+        return [Event.from_json(e) for e in cached]
+    try:
+        r = SESSION.get(URL, timeout=15)
+        evs = parse(r.text) if r.status_code == 200 else []
+    except Exception:  # noqa: BLE001 - the calendar is a nice-to-have
+        evs = []
+    if evs:
+        _cache.set("events", [e.to_json() for e in evs])
+    return evs
+
+
+def current_sale(today: dt.date | None = None, evs: list[Event] | None = None) -> Event | None:
+    today = today or dt.date.today()
+    return next((e for e in (evs if evs is not None else events())
+                 if e.kind == "sale" and e.start <= today <= e.end), None)
+
+
+def next_sale(today: dt.date | None = None, within_days: int = 45, evs: list[Event] | None = None) -> Event | None:
+    today = today or dt.date.today()
+    return next((e for e in (evs if evs is not None else events())
+                 if e.kind == "sale" and today < e.start <= today + dt.timedelta(days=within_days)), None)
+
+
+def fests_for(taste_tags: list[str], today: dt.date | None = None, within_days: int = 60,
+              evs: list[Event] | None = None) -> list[Event]:
+    """Upcoming or running themed fests whose tags overlap your strongest taste tags."""
+    today = today or dt.date.today()
+    want = {t.lower() for t in taste_tags}
+    return [e for e in (evs if evs is not None else events())
+            if e.kind == "fest" and e.end >= today and e.start <= today + dt.timedelta(days=within_days)
+            and want & {t.lower() for t in e.tags}]