gigwatch-nova 0.2.0__tar.gz

gigwatch_nova-0.2.0/LICENSE

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

gigwatch_nova-0.2.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: gigwatch-nova
+Version: 0.2.0
+Summary: Self-hosted freelance-gig watcher: monitor job feeds, filter by your skills, alert on new matches.
+Author-email: Nova <novagw@uberip.com>
+License: MIT
+Project-URL: Homepage, https://github.com/earnnova-dev/gigwatch
+Project-URL: Issues, https://github.com/earnnova-dev/gigwatch/issues
+Keywords: freelance,jobs,gigs,alerts,monitor,remote,upwork
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# GigWatch
+
+**A self-hosted freelance-gig watcher.** GigWatch monitors live job/gig feeds,
+filters them against *your* skills, remembers what it has already shown you,
+and alerts you (console, email, or Slack) **only when a new matching gig
+appears**.
+
+Stop refreshing Upwork/Remotive/LinkedIn every 20 minutes. Point GigWatch at
+the feeds you care about, tell it what you do, and let it ping you when
+something relevant lands.
+
+```
+$ gigwatch scan
+scanned 17 job(s) from 1 source(s); 4 match filter; 2 new
+GigWatch: 2 new matching gig(s)
+
+1. Senior Python Backend Engineer
+   company: Acme Digital
+   salary:  $120k-$150k
+   where:   Remote (Worldwide)
+   matched: python, backend
+   score:   9.0
+   https://remotive.com/remote-jobs/...
+```
+
+## Why this exists
+
+Freelancers lose real money to *latency* — the best gigs get filled in the
+first hours. Existing monitors (Distill, PageCrawl, Apify's Upwork monitor)
+are hosted SaaS that scrape your sessions and cost monthly. GigWatch is:
+
+- **Self-hosted & private** — your skills, your feeds, your machine. No
+  account, no session scraping, no data leaving your box.
+- **Free & open (MIT)** — the core is a small, readable Python CLI.
+- **Portable** — run it on a laptop, a $5 VPS, or in a cron job.
+
+## Features
+
+- **Multiple feed sources** — Remotive, We Work Remotely, RemoteOK, and
+  Hacker News "Who is Hiring?" (built-in, no auth), any RSS/Atom feed, or any
+  JSON endpoint returning a list of job objects.
+- **AI job ranking** — `gigwatch rank` scores every match 0-100 against a
+  profile you write (role, skills, location, notes) and explains *why*. Uses
+  an LLM when `OPENAI_API_KEY` is set (any OpenAI-compatible endpoint);
+  otherwise a deterministic, dependency-free heuristic. Either way you get a
+  ranked shortlist, not a raw dump.
+- **Output formats** — `scan`, `list`, and `rank` take `--format
+  text|markdown|json` (a Markdown table or a JSON array of job objects for
+  piping elsewhere).
+- **Skill-based filtering** — keyword matching (any/all), category and
+  location filters, exclude-list, and a relevance score (title hits weigh
+  more than body hits).
+- **Dedupe by state** — a local JSON state file tracks what you've already
+  seen, so you're only ever alerted on *new* matches. State auto-prunes.
+- **Alerts** — console (default), SMTP email, or Slack (webhook or chat API).
+  Secrets come from environment variables, never the config file.
+- **Zero dependencies** — pure Python standard library. If you can run
+  `python3`, you can run GigWatch.
+
+## Quick start
+
+No install required — it's stdlib-only:
+
+```bash
+# 1. Get the code
+git clone https://github.com/earnnova-dev/gigwatch
+cd gigwatch
+
+# 2. Create a starter config (or copy config.example.json to config.json)
+python3 -m gigwatch init
+
+# 3. Edit config.json: put YOUR skills in filters.keywords
+#    e.g. ["python", "backend", "api", "django"]
+
+# 4. See what would match right now (dry run, no state touched)
+python3 -m gigwatch list
+
+# 5. Do a real scan: alerts on new matches, remembers them
+python3 -m gigwatch scan
+```
+
+Or install it as a proper command:
+
+```bash
+pip install .          # or: pipx install .
+gigwatch init && gigwatch scan
+```
+
+### Run it continuously
+
+```bash
+# Loop forever, re-scanning every poll_interval seconds (default 15 min):
+gigwatch watch
+
+# Or use cron on a VPS (once an hour):
+0 * * * * cd /opt/gigwatch && /usr/bin/python3 -m gigwatch scan
+```
+
+### Rank matches by fit
+
+`rank` fetches and filters like `scan`, then scores every match 0-100 against
+a profile and explains the score. It uses an LLM when `OPENAI_API_KEY` is set
+(any OpenAI-compatible endpoint; the model is auto-discovered), otherwise a
+deterministic heuristic — so it works with no key at all.
+
+```bash
+# Use the profile from config.json:
+gigwatch rank
+
+# Or pass a profile on the command line:
+gigwatch rank --title "Senior Python Engineer" \
+              --skills "python,backend,api" \
+              --location remote --notes "senior, \$150k+"
+
+# Force the offline heuristic (no LLM call):
+gigwatch rank --no-ai --format markdown
+```
+
+### Alerts
+
+Console is on by default. To also get email/Slack, fill in the `alerts`
+section of `config.json` and set the env vars it references:
+
+```bash
+export GIGWATCH_EMAIL_TO=you@yourdomain.com
+export GIGWATCH_SMTP_USER=...
+export GIGWATCH_SMTP_PASS=...
+export GIGWATCH_SLACK_WEBHOOK=https://hooks.slack.com/services/...
+```
+
+The `${VAR}` placeholders in the config are expanded from the environment at
+load time, so secrets never live in the file (and the file is safe to commit
+if you want).
+
+## Configuration
+
+See [`config.example.json`](config.example.json) for a fully annotated
+example. The top-level keys:
+
+| Key | Meaning |
+|-----|---------|
+| `sources` | List of feeds to watch. `{"type":"remotive"}`, `{"type":"wwr"}`, `{"type":"remoteok"}`, `{"type":"hn"}`, `{"type":"rss","url":...}`, or `{"type":"json","url":...}`. |
+| `profile` | Optional candidate profile for `rank`: `{"title","skills":[...],"location","notes"}`. |
+| `filters.keywords` | Your skills. A job matches if it contains any of these (or all, with `require_all_keywords`). |
+| `filters.categories` / `filters.locations` | Optional extra filters (empty = match anything). |
+| `filters.exclude_keywords` | Words that disqualify a job (e.g. `"intern"`, `"junior"`). |
+| `filters.min_score` | Relevance floor. Title hits = 3 pts, body hits = 1 pt per keyword. |
+| `alerts` | `console`, `email`, `slack` (see above) and `max_per_alert`. |
+| `state_file` | Where seen-jobs are remembered (default `gigwatch-state.json`). |
+| `poll_interval` | Seconds between scans in `watch` mode (default 900). |
+
+### Adding your own JSON source
+
+Any endpoint that returns a JSON array of objects works. Each object should
+have at least `title` and `url`; `company`/`company_name`, `category`,
+`location`/`country`, `salary`, `tags`, and `description` are picked up if
+present. Wrap in `{"jobs":[...]}`, `{"data":[...]}`, `{"results":[...]}`, or
+`{"items":[...]}` and it still works.
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `gigwatch init` | Write a starter `config.json`. |
+| `gigwatch list` | **Dry run** — fetch + filter + print matches. Does not touch state. |
+| `gigwatch scan` | Fetch, filter, alert on new matches, and record them as seen. |
+| `gigwatch rank` | Fetch + filter, then rank matches 0-100 for your `profile` (AI or heuristic). |
+| `gigwatch watch` | Loop `scan` every `poll_interval` seconds. |
+| `gigwatch reset` | Clear the seen-state (next scan alerts on everything that matches). |
+
+Useful flags: `--config PATH` (default `config.json`), `-v/--verbose`,
+`--max-age-days N` (state pruning; `0` keeps everything), and
+`--format text|markdown|json` on `scan`/`list`/`rank`. For `rank`, also
+`--profile FILE` (a JSON profile), `--skills a,b,c`, `--title`, `--location`,
+`--notes`, and `--no-ai` (force the deterministic heuristic engine).
+
+## How it works
+
+```
+sources ──fetch──> [Job, Job, ...]
+                        │
+                   filter_jobs()  (keywords / category / location / score)
+                        │
+                   [ScoredJob, ...]
+                        │
+              compare against state file
+                        │
+                 ┌──────┴──────┐
+              new jobs       already seen
+                 │               │
+           alert (console/     drop silently
+           email/slack)
+                 │
+         mark seen in state file  ──>  gigwatch-state.json
+```
+
+The state file is plain JSON (`{job_id: first_seen_utc}`) so you can inspect
+it, back it up, or move it between machines.
+
+## Roadmap / ideas
+
+- ~~More built-in sources (Hacker News "Who is hiring")~~ — **done in 0.2.0**.
+- ~~AI ranking: summarize each match and rank by fit to a profile~~ — **done in
+  0.2.0** (`gigwatch rank`).
+- LinkedIn via RSS, Upwork via a user-supplied export.
+- Draft proposals / cover letters per match.
+- A tiny hosted tier (the natural monetization path — see below).
+
+## Monetization
+
+The core is free and MIT-licensed. The obvious paid tier is a **hosted
+GigWatch**: we run the scanner on our infra, you get email/Slack alerts
+without running anything, plus AI-ranked matches and proposal drafts. That's
+the plan — the open-source CLI is both the product's engine and the
+marketing.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contact
+
+For questions, hosting-tier interest, or support, open an
+[issue](https://github.com/earnnova-dev/gigwatch/issues/new) — that's the
+fastest route. Email works too: <a href="mailto:novagw&#64;uberip.com">novagw[at]uberip[dot]com</a>.
+
+## Contributing
+
+Issues and PRs welcome. The code is deliberately small and stdlib-only;
+keep it that way. Run `pytest` (unit) and `pytest -m live` (hits the real
+Remotive API) before sending a PR.

gigwatch_nova-0.2.0/README.md

@@ -0,0 +1,231 @@
+# GigWatch
+
+**A self-hosted freelance-gig watcher.** GigWatch monitors live job/gig feeds,
+filters them against *your* skills, remembers what it has already shown you,
+and alerts you (console, email, or Slack) **only when a new matching gig
+appears**.
+
+Stop refreshing Upwork/Remotive/LinkedIn every 20 minutes. Point GigWatch at
+the feeds you care about, tell it what you do, and let it ping you when
+something relevant lands.
+
+```
+$ gigwatch scan
+scanned 17 job(s) from 1 source(s); 4 match filter; 2 new
+GigWatch: 2 new matching gig(s)
+
+1. Senior Python Backend Engineer
+   company: Acme Digital
+   salary:  $120k-$150k
+   where:   Remote (Worldwide)
+   matched: python, backend
+   score:   9.0
+   https://remotive.com/remote-jobs/...
+```
+
+## Why this exists
+
+Freelancers lose real money to *latency* — the best gigs get filled in the
+first hours. Existing monitors (Distill, PageCrawl, Apify's Upwork monitor)
+are hosted SaaS that scrape your sessions and cost monthly. GigWatch is:
+
+- **Self-hosted & private** — your skills, your feeds, your machine. No
+  account, no session scraping, no data leaving your box.
+- **Free & open (MIT)** — the core is a small, readable Python CLI.
+- **Portable** — run it on a laptop, a $5 VPS, or in a cron job.
+
+## Features
+
+- **Multiple feed sources** — Remotive, We Work Remotely, RemoteOK, and
+  Hacker News "Who is Hiring?" (built-in, no auth), any RSS/Atom feed, or any
+  JSON endpoint returning a list of job objects.
+- **AI job ranking** — `gigwatch rank` scores every match 0-100 against a
+  profile you write (role, skills, location, notes) and explains *why*. Uses
+  an LLM when `OPENAI_API_KEY` is set (any OpenAI-compatible endpoint);
+  otherwise a deterministic, dependency-free heuristic. Either way you get a
+  ranked shortlist, not a raw dump.
+- **Output formats** — `scan`, `list`, and `rank` take `--format
+  text|markdown|json` (a Markdown table or a JSON array of job objects for
+  piping elsewhere).
+- **Skill-based filtering** — keyword matching (any/all), category and
+  location filters, exclude-list, and a relevance score (title hits weigh
+  more than body hits).
+- **Dedupe by state** — a local JSON state file tracks what you've already
+  seen, so you're only ever alerted on *new* matches. State auto-prunes.
+- **Alerts** — console (default), SMTP email, or Slack (webhook or chat API).
+  Secrets come from environment variables, never the config file.
+- **Zero dependencies** — pure Python standard library. If you can run
+  `python3`, you can run GigWatch.
+
+## Quick start
+
+No install required — it's stdlib-only:
+
+```bash
+# 1. Get the code
+git clone https://github.com/earnnova-dev/gigwatch
+cd gigwatch
+
+# 2. Create a starter config (or copy config.example.json to config.json)
+python3 -m gigwatch init
+
+# 3. Edit config.json: put YOUR skills in filters.keywords
+#    e.g. ["python", "backend", "api", "django"]
+
+# 4. See what would match right now (dry run, no state touched)
+python3 -m gigwatch list
+
+# 5. Do a real scan: alerts on new matches, remembers them
+python3 -m gigwatch scan
+```
+
+Or install it as a proper command:
+
+```bash
+pip install .          # or: pipx install .
+gigwatch init && gigwatch scan
+```
+
+### Run it continuously
+
+```bash
+# Loop forever, re-scanning every poll_interval seconds (default 15 min):
+gigwatch watch
+
+# Or use cron on a VPS (once an hour):
+0 * * * * cd /opt/gigwatch && /usr/bin/python3 -m gigwatch scan
+```
+
+### Rank matches by fit
+
+`rank` fetches and filters like `scan`, then scores every match 0-100 against
+a profile and explains the score. It uses an LLM when `OPENAI_API_KEY` is set
+(any OpenAI-compatible endpoint; the model is auto-discovered), otherwise a
+deterministic heuristic — so it works with no key at all.
+
+```bash
+# Use the profile from config.json:
+gigwatch rank
+
+# Or pass a profile on the command line:
+gigwatch rank --title "Senior Python Engineer" \
+              --skills "python,backend,api" \
+              --location remote --notes "senior, \$150k+"
+
+# Force the offline heuristic (no LLM call):
+gigwatch rank --no-ai --format markdown
+```
+
+### Alerts
+
+Console is on by default. To also get email/Slack, fill in the `alerts`
+section of `config.json` and set the env vars it references:
+
+```bash
+export GIGWATCH_EMAIL_TO=you@yourdomain.com
+export GIGWATCH_SMTP_USER=...
+export GIGWATCH_SMTP_PASS=...
+export GIGWATCH_SLACK_WEBHOOK=https://hooks.slack.com/services/...
+```
+
+The `${VAR}` placeholders in the config are expanded from the environment at
+load time, so secrets never live in the file (and the file is safe to commit
+if you want).
+
+## Configuration
+
+See [`config.example.json`](config.example.json) for a fully annotated
+example. The top-level keys:
+
+| Key | Meaning |
+|-----|---------|
+| `sources` | List of feeds to watch. `{"type":"remotive"}`, `{"type":"wwr"}`, `{"type":"remoteok"}`, `{"type":"hn"}`, `{"type":"rss","url":...}`, or `{"type":"json","url":...}`. |
+| `profile` | Optional candidate profile for `rank`: `{"title","skills":[...],"location","notes"}`. |
+| `filters.keywords` | Your skills. A job matches if it contains any of these (or all, with `require_all_keywords`). |
+| `filters.categories` / `filters.locations` | Optional extra filters (empty = match anything). |
+| `filters.exclude_keywords` | Words that disqualify a job (e.g. `"intern"`, `"junior"`). |
+| `filters.min_score` | Relevance floor. Title hits = 3 pts, body hits = 1 pt per keyword. |
+| `alerts` | `console`, `email`, `slack` (see above) and `max_per_alert`. |
+| `state_file` | Where seen-jobs are remembered (default `gigwatch-state.json`). |
+| `poll_interval` | Seconds between scans in `watch` mode (default 900). |
+
+### Adding your own JSON source
+
+Any endpoint that returns a JSON array of objects works. Each object should
+have at least `title` and `url`; `company`/`company_name`, `category`,
+`location`/`country`, `salary`, `tags`, and `description` are picked up if
+present. Wrap in `{"jobs":[...]}`, `{"data":[...]}`, `{"results":[...]}`, or
+`{"items":[...]}` and it still works.
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `gigwatch init` | Write a starter `config.json`. |
+| `gigwatch list` | **Dry run** — fetch + filter + print matches. Does not touch state. |
+| `gigwatch scan` | Fetch, filter, alert on new matches, and record them as seen. |
+| `gigwatch rank` | Fetch + filter, then rank matches 0-100 for your `profile` (AI or heuristic). |
+| `gigwatch watch` | Loop `scan` every `poll_interval` seconds. |
+| `gigwatch reset` | Clear the seen-state (next scan alerts on everything that matches). |
+
+Useful flags: `--config PATH` (default `config.json`), `-v/--verbose`,
+`--max-age-days N` (state pruning; `0` keeps everything), and
+`--format text|markdown|json` on `scan`/`list`/`rank`. For `rank`, also
+`--profile FILE` (a JSON profile), `--skills a,b,c`, `--title`, `--location`,
+`--notes`, and `--no-ai` (force the deterministic heuristic engine).
+
+## How it works
+
+```
+sources ──fetch──> [Job, Job, ...]
+                        │
+                   filter_jobs()  (keywords / category / location / score)
+                        │
+                   [ScoredJob, ...]
+                        │
+              compare against state file
+                        │
+                 ┌──────┴──────┐
+              new jobs       already seen
+                 │               │
+           alert (console/     drop silently
+           email/slack)
+                 │
+         mark seen in state file  ──>  gigwatch-state.json
+```
+
+The state file is plain JSON (`{job_id: first_seen_utc}`) so you can inspect
+it, back it up, or move it between machines.
+
+## Roadmap / ideas
+
+- ~~More built-in sources (Hacker News "Who is hiring")~~ — **done in 0.2.0**.
+- ~~AI ranking: summarize each match and rank by fit to a profile~~ — **done in
+  0.2.0** (`gigwatch rank`).
+- LinkedIn via RSS, Upwork via a user-supplied export.
+- Draft proposals / cover letters per match.
+- A tiny hosted tier (the natural monetization path — see below).
+
+## Monetization
+
+The core is free and MIT-licensed. The obvious paid tier is a **hosted
+GigWatch**: we run the scanner on our infra, you get email/Slack alerts
+without running anything, plus AI-ranked matches and proposal drafts. That's
+the plan — the open-source CLI is both the product's engine and the
+marketing.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contact
+
+For questions, hosting-tier interest, or support, open an
+[issue](https://github.com/earnnova-dev/gigwatch/issues/new) — that's the
+fastest route. Email works too: <a href="mailto:novagw&#64;uberip.com">novagw[at]uberip[dot]com</a>.
+
+## Contributing
+
+Issues and PRs welcome. The code is deliberately small and stdlib-only;
+keep it that way. Run `pytest` (unit) and `pytest -m live` (hits the real
+Remotive API) before sending a PR.

gigwatch_nova-0.2.0/gigwatch/__init__.py

@@ -0,0 +1,8 @@
+"""GigWatch: a self-hosted freelance-gig watcher.
+
+Pulls live job/gig feeds, filters them against your skills, dedupes against a
+local state file, and alerts you (console / email / Slack) only when a new
+matching gig appears.
+"""
+
+__version__ = "0.2.0"

gigwatch_nova-0.2.0/gigwatch/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m gigwatch` to run the CLI."""
+
+from gigwatch.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gigwatch_nova-0.2.0/gigwatch/alerts.py

@@ -0,0 +1,125 @@
+"""Alert delivery: console, email (SMTP), Slack (webhook or chat API).
+
+All senders are best-effort: a failure in one channel never blocks the others
+and never crashes the scan. Errors are returned so the CLI can report them.
+"""
+
+from __future__ import annotations
+
+import json
+import smtplib
+import ssl
+import urllib.request
+from email.message import EmailMessage
+from typing import List, Optional
+
+from gigwatch.config import AlertConfig
+from gigwatch.filtering import ScoredJob
+
+
+def format_jobs(jobs: List[ScoredJob], max_per_alert: int = 25) -> str:
+    """Human-readable multi-line summary of new matches."""
+    lines = ["GigWatch: %d new matching gig(s)" % len(jobs), ""]
+    for i, s in enumerate(jobs[:max_per_alert], 1):
+        j = s.job
+        lines.append("%d. %s" % (i, j.title))
+        if j.company:
+            lines.append("   company: %s" % j.company)
+        if j.salary:
+            lines.append("   salary:  %s" % j.salary)
+        if j.location:
+            lines.append("   where:   %s" % j.location)
+        if s.matched_keywords:
+            lines.append("   matched: %s" % ", ".join(s.matched_keywords))
+        lines.append("   score:   %s" % s.score)
+        lines.append("   %s" % j.url)
+        lines.append("")
+    if len(jobs) > max_per_alert:
+        lines.append("... and %d more (raise alerts.max_per_alert to see them)"
+                     % (len(jobs) - max_per_alert))
+    return "\n".join(lines).strip()
+
+
+def send_console(jobs: List[ScoredJob], cfg: AlertConfig) -> Optional[str]:
+    if not cfg.console:
+        return None
+    text = format_jobs(jobs, cfg.max_per_alert)
+    print(text)
+    return None
+
+
+def send_email(jobs: List[ScoredJob], cfg: AlertConfig) -> Optional[str]:
+    e = cfg.email
+    if not e or not e.get("to"):
+        return None
+    try:
+        msg = EmailMessage()
+        msg["Subject"] = "GigWatch: %d new matching gig(s)" % len(jobs)
+        msg["From"] = e.get("from", "gigwatch@localhost")
+        msg["To"] = e["to"] if isinstance(e["to"], str) else ", ".join(e["to"])
+        msg.set_content(format_jobs(jobs, cfg.max_per_alert))
+
+        host = e.get("smtp_host", "localhost")
+        port = int(e.get("smtp_port", 587))
+        use_tls = bool(e.get("use_tls", True))
+        username = e.get("username")
+        password = e.get("password", "")
+
+        if use_tls:
+            server = smtplib.SMTP(host, port, timeout=30)
+            server.starttls(context=ssl.create_default_context())
+        else:
+            server = smtplib.SMTP(host, port, timeout=30)
+        if username:
+            server.login(username, password)
+        server.send_message(msg)
+        server.quit()
+        return None
+    except Exception as exc:  # noqa: BLE001 - best-effort alert
+        return "email: %s" % exc
+
+
+def send_slack(jobs: List[ScoredJob], cfg: AlertConfig) -> Optional[str]:
+    s = cfg.slack
+    if not s:
+        return None
+    text = format_jobs(jobs, cfg.max_per_alert)
+    try:
+        if s.get("webhook_url"):
+            payload = {"text": text[:3900]}
+            req = urllib.request.Request(
+                s["webhook_url"],
+                data=json.dumps(payload).encode("utf-8"),
+                headers={"Content-Type": "application/json"},
+            )
+            urllib.request.urlopen(req, timeout=30).read()
+            return None
+        if s.get("token") and s.get("channel"):
+            payload = {"channel": s["channel"], "text": text[:3900]}
+            req = urllib.request.Request(
+                "https://slack.com/api/chat.postMessage",
+                data=json.dumps(payload).encode("utf-8"),
+                headers={
+                    "Content-Type": "application/json; charset=utf-8",
+                    "Authorization": "Bearer %s" % s["token"],
+                },
+            )
+            resp = json.loads(urllib.request.urlopen(req, timeout=30).read())
+            if not resp.get("ok"):
+                return "slack: %s" % resp.get("error")
+            return None
+        return "slack: no webhook_url or (token+channel) configured"
+    except Exception as exc:  # noqa: BLE001
+        return "slack: %s" % exc
+
+
+def send_all(jobs: List[ScoredJob], cfg: AlertConfig) -> List[str]:
+    """Send through every enabled channel. Returns a list of error strings."""
+    errors: List[str] = []
+    if not jobs:
+        return errors
+    for fn in (send_console, send_email, send_slack):
+        err = fn(jobs, cfg)
+        if err:
+            errors.append(err)
+    return errors