![\"uae-news-digest](\"https://raw.githubusercontent.com/drakulavich/uae-news-digest/main/docs/logo.png\"){kind=logo}
\n\n \n
\n ![\"CI\"](\"https://github.com/drakulavich/uae-news-digest/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"npm](\"https://img.shields.io/npm/v/@drakulavich/uae-news-digest\")
![\"License:](\"https://img.shields.io/badge/License-MIT-blue.svg\"){kind=icon}
\n ![\"Bun\"](\"https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun\"){kind=icon}
Wake up to the UAE without opening ten news tabs.
\nuae-news-digest turns Google News RSS into a ranked, deduplicated terminal briefing with clean JSON for scripts and agents.
\n ![\"uae-news-digest](\"https://github.com/drakulavich/uae-news-digest/raw/main/assets/demo.gif\")
\n
` | | DeepL target language (e.g. `DE`, `FR`, `JA`). Requires `DEEPL_AUTH_KEY` |\n| `--state-file ` | `./seen_titles.txt` | Seen-items state file |\n| `--timeout-ms ` | `15000` | RSS fetch timeout |\n| `--dry-run` | `false` | Preview without updating state |\n| `--json` | `false` | Output as JSON (agent-friendly envelope) |\n\n### Subcommands\n\n| Command | Description |\n|---------|-------------|\n| `manifest` | Print a machine-readable tool descriptor as JSON |\n| `healthcheck [--rss-url ]` | Smoke-test the first topic's feed (or `--rss-url`); prints `{ok, version, latencyMs}` |\n| `config print-default` | Print the built-in config as JSON, ready to copy into `digest.config.json` |\n| `config validate [path]` | Validate a config file (default: the auto-detected one); prints `ok` or every issue with its JSON path |\n\n### Exit codes\n\n`0` success (a topic may still have failed β see warnings). `1` a usage, config, network, or timeout error, or no topic could be fetched.\n\n## What You Get\n\n```\nπ¦πͺ UAE digest β 2026-09-05\n\nπ° UAE\n π‘οΈ UAE intercepts 79 Iranian strike assets (The National, 2h ago)\n π Dubai property sales drop more than 30% (Anadolu AjansΔ±, 5h ago)\n β΄οΈ Container ship incident at Khor Fakkan (Reuters, 3h ago)\n βοΈ Abu Dhabi airport reopens after rain (Khaleej Times, 1h ago)\n π§οΈ Unstable weather hits some emirates (Gulf News, 4h ago)\n π’οΈ Oil prices: OPEC+ mulls output increase (CNBC, 6h ago)\n```\n\nAnd when you need structured output:\n\n```bash\nuae-news-digest --json | jq '.items[].title'\n```\n\n## Signal filter\n\nEvery run automatically surfaces headlines that materially affect an expat family in the UAE across four areas:\n\n- **Safety / threats** β missiles, drones, airspace closures, evacuation alerts, storms\n- **Money / daily life** β rent, fees, fuel prices, salary, fines, subsidies\n- **Rules / visas / documents** β visa changes, new laws, permit and licence updates\n- **Logistics / infrastructure** β flight disruptions, road closures, metro outages\n\nItems that score above the threshold are pulled into a `π¨ Important` block printed **at the top** of the digest, deduplicated from the regular listing below. Each important line shows a `[signals]` marker that explains why it surfaced. PR puff (launches, awards, \"world's first/tallest/largest\", festivals, and similar) is penalised and pushed down.\n\nThis is a heuristic β no API key required, always on.\n\n**Example output:**\n\n```\nπ¦πͺ UAE digest β 2025-11-14\n\nπ¨ Important\n π‘οΈ UAE intercepts Iranian missile barrage (The National, 1h ago) [missile, airspace] β UAE Security\n βοΈ Dubai airport closes Terminal 2 for maintenance (Gulf News, 3h ago) [flight] β Travel\n\nπ° UAE economy\n π OPEC+ weighs output cut for Q1 (Reuters, 4h ago)\n ...\n```\n\n### Topic `match` / `matchMode`\n\nGoogle News sometimes returns loosely-matched articles for a query. Add optional `match` and `matchMode` keys to any topic to require real keyword matches in the article title:\n\n```jsonc\n{\n \"topics\": [\n {\n \"slug\": \"schools\",\n \"name\": \"Schools\",\n \"query\": \"school fees Dubai\",\n \"match\": [\"school\", \"fees\"],\n \"matchMode\": \"all\"\n }\n ]\n}\n```\n\n| Key | Type | Default | Description |\n|-----|------|---------|-------------|\n| `match` | `string[]` | β | Keywords that must appear in the article title. Omit to keep existing behaviour. |\n| `matchMode` | `\"all\"` \\| `\"any\"` \\| `` | `\"all\"` | `\"all\"` β every term must match; `\"any\"` β at least one; a positive integer `N` β at least N terms. |\n\nWhen articles are dropped for failing the keyword filter, a warning reports how many were dropped (visible in non-JSON mode on stderr).\n\n### Agent workflow (key-free smart pass)\n\n`--json` enriches every item with `importance`, `tier` (`breaking` | `impact` | `neutral` | `fluff`), `signals`, and `matchedTerms`. Pipe that to an LLM with the ready-made filter criterion:\n\n```bash\nuae-news-digest --prompt # print the filter criterion\nuae-news-digest --json --dry-run | claude \"$(uae-news-digest --prompt)\"\n```\n\n`--dry-run` keeps the seen-items state file untouched, so an ad-hoc agent-filter pass doesn't mark those articles as seen and hide them from the next real digest. Drop it when this pipe _is_ the scheduled run.\n\nThe agent can drop noise reproducibly based solely on the structured metadata β no extra API key, no custom prompt engineering required.\n\n`--prompt` output:\n\n> You are a news filter for an expat family in the UAE. Keep only what materially affects safety, money, rules/visas, or logistics. Drop PR, launches, awards, rankings, and 'world's first/tallest/largest'.\n\n## Topics Mode\n\nWithout a config, the built-in UAE config runs (one topic). For per-topic digests (e.g. economy, real estate, regional politics), create a `digest.config.json` file:\n\n```json\n{\n \"locale\": { \"hl\": \"en\", \"gl\": \"AE\", \"ceid\": \"AE:en\" },\n \"topics\": [\n {\n \"slug\": \"economy\",\n \"name\": \"UAE economy\",\n \"emoji\": \"π°\",\n \"query\": \"(UAE OR Emirates) AND (economy OR GDP OR inflation OR ADNOC OR non-oil)\",\n \"limit\": 5\n },\n {\n \"slug\": \"realty\",\n \"name\": \"Real estate\",\n \"emoji\": \"π \",\n \"query\": \"(Dubai OR \\\"Abu Dhabi\\\") AND (\\\"real estate\\\" OR property OR Emaar OR Aldar)\",\n \"limit\": 4\n },\n {\n \"slug\": \"chocolate\",\n \"name\": \"Dubai chocolate\",\n \"emoji\": \"π«\",\n \"query\": \"\\\"Dubai chocolate\\\" OR pistachio OR kunafa\",\n \"limit\": 3\n }\n ]\n}\n```\n\nHeuristics (skip list, source tiers, keyword boosts, dedupe synonyms, importance markers, emoji rules) also live in this file. A config without those sections runs neutral. Start from the built-in UAE set with `uae-news-digest config print-default > digest.config.json`, then edit it; run `uae-news-digest config validate` to check it against the schema before using it.\n\nEach topic builds its Google News RSS URL from `query` and `locale`. Add `feedUrl` to a topic to fetch that exact RSS URL instead β useful for non-Google feeds or deterministic tests.\n\nThe CLI looks for the config in this order:\n\n1. `--config ` (explicit override)\n2. `./digest.config.json` (current working directory)\n3. `$XDG_CONFIG_HOME/uae-news-digest/topics.json` (falls back to `~/.config/uae-news-digest/topics.json`)\n\nWithout a config the built-in UAE config runs. The CLI fetches each topic in parallel and renders one section per topic (a single-topic config still prints its heading). A story already selected by an earlier topic is not repeated in a later one (exact-key match; fuzzy near-duplicate detection runs within each topic), so the topic order in the config sets priority.\n\n`--target-lang` translates all section titles in a single DeepL batch. `--limit`, when given, must be a positive integer and overrides every topic's per-topic limit for the run.\n\nThe example `query` strings above are starting points, not optimal β iterate them against real Google News output.\n\n### JSON output\n\n```json\n{\n \"tool\": \"uae-news-digest\",\n \"version\": \"...\",\n \"generatedAt\": \"2026-09-05T06:00:00.000Z\",\n \"query\": { \"hours\": 36, \"limit\": null, \"targetLang\": null },\n \"topics\": [\n { \"slug\": \"economy\", \"name\": \"UAE economy\", \"count\": 5 },\n { \"slug\": \"realty\", \"name\": \"Real estate\", \"count\": 4 },\n { \"slug\": \"chocolate\", \"name\": \"Dubai chocolate\", \"count\": 1 }\n ],\n \"count\": 10,\n \"warnings\": [],\n \"items\": [\n {\n \"topic\": \"economy\",\n \"title\": \"...\",\n \"translatedTitle\": null,\n \"source\": \"...\",\n \"url\": \"...\",\n \"publishedAt\": \"...\",\n \"hoursAgo\": 4,\n \"score\": 0,\n \"importance\": 0,\n \"tier\": \"neutral\",\n \"signals\": [],\n \"matchedTerms\": []\n }\n ]\n}\n```\n\nItems are emitted as a flat list in section order; each carries its `topic` slug so consumers can group. `query.limit` is `null` unless `--limit` was passed.\n\n## Programmatic API\n\n```typescript\nimport { loadConfig, DEFAULT_CONFIG, runDigest, renderText, toJson } from \"@drakulavich/uae-news-digest/core\";\n\nconst config = await loadConfig(\"./digest.config.json\"); // or DEFAULT_CONFIG for the built-in UAE set\nconst now = new Date();\nconst result = await runDigest({\n config,\n seenKeys: new Set(),\n hours: 36,\n now,\n fetchText: (url) => fetch(url).then((r) => r.text()),\n});\nconsole.log(renderText(result, config, now));\n```\n\nThe `/core` entry point exports `runDigest`, `renderText`, `toJson`, `loadConfig`, `resolveConfigPath`, `parseConfig`, `DEFAULT_CONFIG`, `parseRss`, plus the Seen-item state helpers (`readSeenKeys`, `writeSeenKeys`, `DEFAULT_STATE_FILE`) and DeepL helpers (`translateDeepL`, `DEEPL_API_URL`) β the same filtering, scoring, deduplication, translation fallback, and rendering logic the CLI uses, without spawning a process.\n\nAlready holding the RSS XML? Pass `fetchText: async () => xml` and `runDigest` never touches the network β the packed-package smoke test runs exactly that way.\n\n## How It Works\n\n```\nuae-news-digest --hours 12 --limit 10\n β\n βββ Config ββββββββ topics (query + locale) β one Google News RSS URL each (or feedUrl)\n β\n βββ Fetch RSS βββββ Google News RSS feed per topic\n β\n βββ Filter ββββββββ skip: opinion, tabloids, sports, travel\n β\n βββ Score βββββββββ +3 preferred source, +2 UAE mention, +2 priority topic\n β\n βββ Deduplicate βββ exact key match + Jaccard fuzzy (threshold 0.45)\n β\n βββ Translate βββββ DeepL API (optional, when --target-lang set)\n β\n βββ Render ββββββββ display flag/name header + per-item emoji + title + source + hours ago\n```\n\nState file (`seen_titles.txt`) tracks seen articles so scheduled runs do not repeat the same briefing forever.\n\n`healthcheck` probes the first topic's feed from the resolved config (`--config`, `./digest.config.json`, XDG, or the built-in default), honouring `--timeout-ms` (default `15000`). For deterministic smoke tests against a fixed feed, pass `healthcheck --rss-url `.\n\n## Requirements\n\n- [Bun](https://bun.sh) >= 1.3 (CI pins 1.3.14).\n- CI validates Linux and macOS. Windows is not a supported target yet.\n\n## License\n\nMade with ππ©΅ Published under MIT License.\n","readmeFilename":"README.md"}