posthorn 0.1.0__tar.gz

posthorn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drew Vandagriff (DREW-V)
+
+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.

posthorn-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: posthorn
+Version: 0.1.0
+Summary: Lightweight configurable job posting scanner and alerting. Work smarter, not harder
+Author-email: Drew Vandagriff <vandagriff.drew@gmail.com>
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: Pytest
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4>=4.15.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pytz>=2026.4
+Provides-Extra: test
+Requires-Dist: pytest>=9.1.0; extra == "test"
+Requires-Dist: pytest-cov>=7.1.0; extra == "test"
+Requires-Dist: pytest-mock>=3.15.0; extra == "test"
+Requires-Dist: responses>=0.26.0; extra == "test"
+Requires-Dist: respx>=0.23.0; extra == "test"
+Requires-Dist: freezegun>=1.5.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.16.0; extra == "dev"
+Requires-Dist: mypy>=2.3.0; extra == "dev"
+Requires-Dist: pre-commit>=4.6.0; extra == "dev"
+Requires-Dist: build>=1.6.0; extra == "dev"
+Requires-Dist: twine>=7.0.0; extra == "dev"
+Requires-Dist: ipython>=9.17.0; extra == "dev"
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=0.10.0; extra == "duckdb"
+Provides-Extra: postgresql
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgresql"
+Requires-Dist: asyncpg>=0.31.0; extra == "postgresql"
+Dynamic: license-file
+
+<div align="center">
+  <img src=".github/images/icon.png" alt="Posthorn Logo" width="220"/>
+  
+  <h1>Posthorn</h1>
+  <p><b>An extensible, async-first job monitoring and alerting daemon.</b></p>
+</div>
+
+<br/>
+
+## ⚡ Core Philosophy
+
+Posthorn is a lightweight, strictly-typed Python background service designed to poll job boards, filter for specific campaigns, and push early-warning alerts to webhooks or chat platforms. Built on modern Python concurrency, it relies on an embedded DuckDB state machine to enforce absolute idempotency—guaranteeing that a matched job is alerted on exactly once, even across overlapping sweeps or network failures.
+
+## ⚡ Core Philosophy
+
+* **Performance over Gimmicks:** Zero heavy headless browsers. Polling relies purely on `httpx` and lightweight `BeautifulSoup4` HTML parsing.
+* **Structural Subtyping:** Core architecture relies entirely on `typing.Protocol`. Adapters for new job boards or carriers duck-type perfectly into the orchestrator without rigid inheritance hierarchies.
+* **Strict Idempotency:** The DuckDB backend maintains a transactional state machine (`DISCOVERED` -> `ALERT_QUEUED` -> `ALERT_SENT`), acting as an airlock against duplicate alerts and race conditions.
+* **Type-Safe & Tested:** 100% Pyright/Mypy compliant, backed by a comprehensive `pytest-asyncio` test suite utilizing memory-resident database fixtures.
+
+---
+
+## 🏗 Architecture
+
+Posthorn is built around three interchangeable layers orchestrated by the main `Posthorn` daemon loop:
+
+1. **Job Boards (`JobBoard` Protocol):** Inbound data adapters.
+* *Included:* `LinkedIn`, `Indeed`, `ZipRecruiter`.
+
+
+2. **Alert Carriers (`AlertCarrier` Protocol):** Outbound notification dispatchers.
+* *Included:* `Discord` (Rich Webhooks), `Telegram`.
+
+
+3. **State Database:** The idempotency lock and metrics tracker.
+* *Included:* `DuckDB`.
+
+
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+Posthorn is designed to be deployed into modern, isolated Python environments. We recommend using Astral's `uv`:
+
+```bash
+uv pip install posthorn
+
+```
+
+### Example Usage: The "Telelink" Daemon
+
+Wiring up an alerting daemon requires simply declaring your carriers, boards, and campaigns, then awaiting the `run()` loop.
+
+```python
+import asyncio
+
+import posthorn as horn
+from posthorn.adapters import LinkedIn, Telegram
+
+async def main():
+    app = horn.Posthorn(
+        # 1. Define where alerts should go
+        alert_carrier=Telegram(
+            bot_token="YOUR_BOT_TOKEN",
+            chat_id="YOUR_CHAT_ID",
+        ),
+        
+        # 2. Define which platforms to scrape
+        job_boards=horn.JobBoardManager([
+            LinkedIn(),
+        ]),
+        
+        # 3. Define your target campaigns
+        campaigns=horn.CampaignManager([
+            horn.Campaign(
+                name="EdgeAI-Engineer",
+                keywords=["Edge AI", "Engineer", "Rust", "Python"],
+                locations=["Remote", "Richardson, TX"]
+            ),
+            horn.Campaign(
+                name="Data-Architect",
+                keywords=["Data Architect", "Data Engineering"],
+                locations=["Remote", "Dallas, TX"]
+            ),
+        ]),
+    )
+    
+    # Fire up the daemon loop (defaults to a 15-minute sweep interval)
+    await app.run(interval_seconds=900)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
+---
+
+## 🛠 Extending Posthorn
+
+Adding a custom integration is as simple as fulfilling a Protocol. No subclassing required.
+
+### Custom Alert Carrier
+
+Just implement a `.name` property and an `async def dispatch()` method.
+
+```python
+class SlackCarrier:
+    @property
+    def name(self) -> str:
+        return "slack"
+
+    async def dispatch(self, job: JobPost, campaign: Campaign) -> None:
+        payload = {"text": f"New match for {campaign.name}: {job.title} at {job.company}\n{job.url}"}
+        async with httpx.AsyncClient() as client:
+            await client.post(SLACK_WEBHOOK_URL, json=payload)
+
+```
+
+---
+
+## 🧪 Development & Testing
+
+Posthorn utilizes `pytest` with `pytest-asyncio` for its testing framework. The suite is designed to run locally with zero infrastructure footprint by injecting a transient, in-memory DuckDB database into the test context.
+
+```bash
+# Install development dependencies
+uv sync --dev
+
+# Run the test suite
+uv run pytest -v
+
+```
+
+---
+
+## 📝 License
+
+MIT License. Build, extend, and deploy.
+
+----
+
+Made with ♥️ by
+```py
+DREW-V := {
+  "Simplicity in the Architecture",
+  "Efficiency in the Engineering",
+  "Purity in the Science",
+  "Audacity in the Art",
+  "Life in the Logic"
+}
+```

posthorn-0.1.0/README.md

@@ -0,0 +1,154 @@
+<div align="center">
+  <img src=".github/images/icon.png" alt="Posthorn Logo" width="220"/>
+  
+  <h1>Posthorn</h1>
+  <p><b>An extensible, async-first job monitoring and alerting daemon.</b></p>
+</div>
+
+<br/>
+
+## ⚡ Core Philosophy
+
+Posthorn is a lightweight, strictly-typed Python background service designed to poll job boards, filter for specific campaigns, and push early-warning alerts to webhooks or chat platforms. Built on modern Python concurrency, it relies on an embedded DuckDB state machine to enforce absolute idempotency—guaranteeing that a matched job is alerted on exactly once, even across overlapping sweeps or network failures.
+
+## ⚡ Core Philosophy
+
+* **Performance over Gimmicks:** Zero heavy headless browsers. Polling relies purely on `httpx` and lightweight `BeautifulSoup4` HTML parsing.
+* **Structural Subtyping:** Core architecture relies entirely on `typing.Protocol`. Adapters for new job boards or carriers duck-type perfectly into the orchestrator without rigid inheritance hierarchies.
+* **Strict Idempotency:** The DuckDB backend maintains a transactional state machine (`DISCOVERED` -> `ALERT_QUEUED` -> `ALERT_SENT`), acting as an airlock against duplicate alerts and race conditions.
+* **Type-Safe & Tested:** 100% Pyright/Mypy compliant, backed by a comprehensive `pytest-asyncio` test suite utilizing memory-resident database fixtures.
+
+---
+
+## 🏗 Architecture
+
+Posthorn is built around three interchangeable layers orchestrated by the main `Posthorn` daemon loop:
+
+1. **Job Boards (`JobBoard` Protocol):** Inbound data adapters.
+* *Included:* `LinkedIn`, `Indeed`, `ZipRecruiter`.
+
+
+2. **Alert Carriers (`AlertCarrier` Protocol):** Outbound notification dispatchers.
+* *Included:* `Discord` (Rich Webhooks), `Telegram`.
+
+
+3. **State Database:** The idempotency lock and metrics tracker.
+* *Included:* `DuckDB`.
+
+
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+Posthorn is designed to be deployed into modern, isolated Python environments. We recommend using Astral's `uv`:
+
+```bash
+uv pip install posthorn
+
+```
+
+### Example Usage: The "Telelink" Daemon
+
+Wiring up an alerting daemon requires simply declaring your carriers, boards, and campaigns, then awaiting the `run()` loop.
+
+```python
+import asyncio
+
+import posthorn as horn
+from posthorn.adapters import LinkedIn, Telegram
+
+async def main():
+    app = horn.Posthorn(
+        # 1. Define where alerts should go
+        alert_carrier=Telegram(
+            bot_token="YOUR_BOT_TOKEN",
+            chat_id="YOUR_CHAT_ID",
+        ),
+        
+        # 2. Define which platforms to scrape
+        job_boards=horn.JobBoardManager([
+            LinkedIn(),
+        ]),
+        
+        # 3. Define your target campaigns
+        campaigns=horn.CampaignManager([
+            horn.Campaign(
+                name="EdgeAI-Engineer",
+                keywords=["Edge AI", "Engineer", "Rust", "Python"],
+                locations=["Remote", "Richardson, TX"]
+            ),
+            horn.Campaign(
+                name="Data-Architect",
+                keywords=["Data Architect", "Data Engineering"],
+                locations=["Remote", "Dallas, TX"]
+            ),
+        ]),
+    )
+    
+    # Fire up the daemon loop (defaults to a 15-minute sweep interval)
+    await app.run(interval_seconds=900)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
+---
+
+## 🛠 Extending Posthorn
+
+Adding a custom integration is as simple as fulfilling a Protocol. No subclassing required.
+
+### Custom Alert Carrier
+
+Just implement a `.name` property and an `async def dispatch()` method.
+
+```python
+class SlackCarrier:
+    @property
+    def name(self) -> str:
+        return "slack"
+
+    async def dispatch(self, job: JobPost, campaign: Campaign) -> None:
+        payload = {"text": f"New match for {campaign.name}: {job.title} at {job.company}\n{job.url}"}
+        async with httpx.AsyncClient() as client:
+            await client.post(SLACK_WEBHOOK_URL, json=payload)
+
+```
+
+---
+
+## 🧪 Development & Testing
+
+Posthorn utilizes `pytest` with `pytest-asyncio` for its testing framework. The suite is designed to run locally with zero infrastructure footprint by injecting a transient, in-memory DuckDB database into the test context.
+
+```bash
+# Install development dependencies
+uv sync --dev
+
+# Run the test suite
+uv run pytest -v
+
+```
+
+---
+
+## 📝 License
+
+MIT License. Build, extend, and deploy.
+
+----
+
+Made with ♥️ by
+```py
+DREW-V := {
+  "Simplicity in the Architecture",
+  "Efficiency in the Engineering",
+  "Purity in the Science",
+  "Audacity in the Art",
+  "Life in the Logic"
+}
+```

posthorn-0.1.0/pyproject.toml

@@ -0,0 +1,168 @@
+# ──────────────────────────────────────────────────────────────────────────────
+# Build System
+# ──────────────────────────────────────────────────────────────────────────────
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Project Metadata
+# ──────────────────────────────────────────────────────────────────────────────
+[project]
+name = "posthorn"
+version = "0.1.0"
+description = "Lightweight configurable job posting scanner and alerting. Work smarter, not harder"
+readme = "README.md"
+authors = [
+    {name = "Drew Vandagriff", email = "vandagriff.drew@gmail.com"},
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Framework :: Pytest",
+]
+requires-python = ">=3.11"
+
+# ── Runtime Dependencies ──────────────────────────────────────────────────────
+dependencies = [
+    "beautifulsoup4>=4.15.0",
+    "httpx>=0.28.1",
+    "pytz>=2026.4",
+]
+
+# ── Optional / Extra Dependencies ─────────────────────────────────────────────
+[project.optional-dependencies]
+test = [
+    "pytest>=9.1.0",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.15.0",
+    "responses>=0.26.0",
+    "respx>=0.23.0",
+    "freezegun>=1.5.0",
+]
+dev = [
+    "ruff>=0.16.0",
+    "mypy>=2.3.0",
+    "pre-commit>=4.6.0",
+    "build>=1.6.0",
+    "twine>=7.0.0",
+    "ipython>=9.17.0",
+]
+duckdb = [
+    "duckdb>=0.10.0",
+]
+postgresql = [
+    "psycopg2-binary>=2.9.0",
+    "asyncpg>=0.31.0",
+]
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Package Configuration
+# ──────────────────────────────────────────────────────────────────────────────
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["posthorn*"]
+exclude = ["tests*"]
+
+[tool.setuptools.package-data]
+"posthorn" = ["**/*.json", "**/*.yaml", "**/*.yml", "**/*.toml"]
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Pytest Configuration
+# ──────────────────────────────────────────────────────────────────────────────
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "--strict-markers",
+    "--tb=short",
+    "-v",
+]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+    "duckdb: marks tests that require DuckDB connectivity",
+    "postgres: marks tests that require PostgreSQL connectivity",
+    "leap_year: marks tests for leap year boundary conditions",
+    "dst_transition: marks tests for DST transition edge cases",
+]
+filterwarnings = [
+    "error::DeprecationWarning",
+    "error::PendingDeprecationWarning",
+    "ignore::UserWarning",
+]
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Ruff — Linter & Formatter
+# ──────────────────────────────────────────────────────────────────────────────
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "I",    # isort
+    "W",    # pycodestyle warnings
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "C4",   # flake8-comprehensions
+]
+ignore = [
+    "E501", # line length is handled by formatter
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["posthorn"]
+
+# ──────────────────────────────────────────────────────────────────────────────
+# MyPy — Static Type Checking
+# ──────────────────────────────────────────────────────────────────────────────
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["tests.*"]
+disallow_untyped_defs = false
+ignore_missing_imports = true
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Coverage
+# ──────────────────────────────────────────────────────────────────────────────
+[tool.coverage.run]
+source = ["src/posthorn"]
+omit = [
+    "tests/*",
+    "*/tests/*",
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+fail_under = 0  # bump as tests mature (e.g. 80)
+
+[tool.coverage.html]
+directory = "htmlcov"
+
+[dependency-groups]
+dev = [
+    "pytest-asyncio>=1.4.0",
+]
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Virtual Environment — use uv's lockfile
+# ──────────────────────────────────────────────────────────────────────────────
+# This project uses `uv` for dependency management.
+# Get started: uv sync --all-extras

posthorn-0.1.0/setup.cfg

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

posthorn-0.1.0/src/posthorn/__init__.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from .core import (
+    AlertCarrier,
+    Campaign,
+    CampaignManager,
+    JobBoard,
+    JobBoardManager,
+    JobPost,
+    JobState,
+    Posthorn,
+    StateDB,
+)
+from .sugar import (
+    current_local_datetime,
+    to_datetime,
+)
+
+__all__ = [
+    "AlertCarrier",
+    "JobBoard",
+    "StateDB",
+    "CampaignManager",
+    "JobBoardManager",
+    "Campaign",
+    "JobPost",
+    "JobState",
+    "Posthorn",
+    "current_local_datetime",
+    "to_datetime",
+]

posthorn-0.1.0/src/posthorn/adapters/__init__.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from .alert_carriers import Discord, Telegram
+from .job_boards import Indeed, LinkedIn, ZipRecruiter
+from .state_dbs import DuckDB, PostgresDB
+
+__all__ = [
+    # Alert Carriers
+    "Discord",
+    "Telegram",
+    # Job Boards
+    "Indeed",
+    "LinkedIn",
+    "ZipRecruiter",
+    # State DBs
+    "DuckDB",
+    "PostgresDB",
+]

posthorn-0.1.0/src/posthorn/adapters/alert_carriers/__init__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from .discord import Discord
+from .telegram import Telegram
+
+__all__ = [
+    "Discord",
+    "Telegram",
+]

posthorn-0.1.0/src/posthorn/adapters/alert_carriers/discord.py

@@ -0,0 +1,80 @@
+import logging
+
+import httpx
+
+from ...core.models.campaign_model import Campaign
+from ...core.models.job_post_model import JobPost
+
+logger = logging.getLogger(__name__)
+
+
+class Discord:
+    """
+    Discord webhook alert dispatcher.
+    Structurally fulfills the AlertCarrier protocol.
+    """
+
+    def __init__(self, webhook_url: str) -> None:
+        """
+        Args:
+            webhook_url: The full webhook URL generated from Discord
+                         (Server Settings -> Integrations -> Webhooks).
+        """
+        self.webhook_url = webhook_url
+
+    @property
+    def name(self) -> str:
+        return "discord"
+
+    async def dispatch(self, job: JobPost, campaign: Campaign) -> None:
+        """
+        Transmits the job payload to the configured Discord channel via webhook.
+
+        Raises:
+            RuntimeError: If the HTTP request fails, allowing the orchestrator
+                          to catch the error and transition the DB state to FAILED.
+        """
+        # Using Discord's rich embed format provides a significantly
+        # cleaner UI experience than raw markdown text.
+        payload = {
+            "embeds": [
+                {
+                    "title": job.title,
+                    "url": job.url,
+                    "color": 3447003,  # Posthorn Blue (Hex: #3498DB)
+                    "author": {
+                        "name": f"🚨 New Match: {campaign.name}"
+                    },
+                    "fields": [
+                        {
+                            "name": "Company",
+                            "value": job.company,
+                            "inline": True
+                        },
+                        {
+                            "name": "Board",
+                            "value": job.board,
+                            "inline": True
+                        }
+                    ],
+                    "footer": {
+                        "text": "Posthorn Alerting Daemon"
+                    }
+                }
+            ]
+        }
+
+        # Instantiating the client per-dispatch is optimal for low-frequency sweeps.
+        async with httpx.AsyncClient() as client:
+            try:
+                # Discord requires a standard JSON POST to the webhook endpoint
+                response = await client.post(self.webhook_url, json=payload, timeout=10.0)
+                response.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                error_msg = f"Discord webhook rejected payload (Status {e.response.status_code}): {e.response.text}"
+                logger.error(error_msg)
+                raise RuntimeError(error_msg) from e
+            except httpx.RequestError as e:
+                error_msg = f"Network error connecting to Discord webhook: {e}"
+                logger.error(error_msg)
+                raise RuntimeError(error_msg) from e