easyoref 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,127 @@
+# EasyOref
+
+Israeli civil defense alerts → your family's Telegram chat.
+
+[![CI](https://github.com/mikhailkogan17/EasyOref/actions/workflows/ci.yml/badge.svg)](https://github.com/mikhailkogan17/EasyOref/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![npm](https://img.shields.io/badge/npm-easyoref-CB3837?logo=npm)](https://www.npmjs.com/package/easyoref)
+
+[Русский](docs/readme_ru.md) · [עברית](docs/readme_he.md)
+
+> [!CAUTION]
+> EasyOref **does not replace** official Home Front Command alerts.
+> It **supplements** them — notifying your family abroad.
+> Always follow Home Front Command instructions!
+
+---
+
+## Why
+
+During a rocket attack, your family abroad sees "MISSILES HIT NETANYA" on the news.
+
+They don't know:
+- Is it your neighborhood or 200 km away?
+- Are you safe?
+- Should they worry?
+
+**Nothing solves this today.**
+Alert apps with area filtering — for you in Israel.
+Cell Broadcast alerts — for you in Israel.
+
+---
+
+## Features
+
+- **4 languages** — Russian, English, Hebrew, Arabic
+- **3 alert types** — early warning, siren, all-clear
+- **Custom messages** — your own text and media per alert type
+
+---
+
+## Install
+
+### 1. Install Node.js
+
+<details>
+<summary>Windows</summary>
+
+Download the installer from [nodejs.org](https://nodejs.org/) (LTS, 22+). Run it, click "Next".
+
+</details>
+
+<details>
+<summary>macOS</summary>
+
+```bash
+brew install node
+```
+
+Or download from [nodejs.org](https://nodejs.org/).
+
+</details>
+
+<details>
+<summary>Linux / Raspberry Pi</summary>
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt install -y nodejs
+```
+
+</details>
+
+### 2. Set up Telegram
+
+1. Message [@BotFather](https://t.me/BotFather) → `/newbot` → copy the **token**
+2. Add the bot to your family group chat
+3. Forward any message from that chat to [@userinfobot](https://t.me/userinfobot) → copy the **chat ID**
+
+### 3. Find your city ID
+
+Open [cities.json](https://github.com/eladnava/pikud-haoref-api/blob/master/cities.json), find your city, copy the `id` number.
+
+Example: `"id": 722` = Tel Aviv — South & Jaffa.
+
+### 4. Run setup
+
+```bash
+npx easyoref init
+```
+
+The wizard asks for language, token, chat ID, and city ID. Config is saved to `~/.easyoref/config.yaml`.
+
+### 5. Start the bot
+
+```bash
+npx easyoref
+```
+
+**Done.** The bot will message your chat whenever the Home Front Command issues an alert for your area.
+
+> The bot needs to run 24/7 — on a Raspberry Pi, server, or always-on computer.
+> Guides: [RPi](docs/rpi.md) · [Local](docs/local.md)
+
+---
+
+## Configuration
+
+Config file: `~/.easyoref/config.yaml`. Created by `npx easyoref init`.
+
+Full reference: [`config.yaml.example`](config.yaml.example).
+
+| Key                      | Default | Description                                                                                         |
+| ------------------------ | ------- | --------------------------------------------------------------------------------------------------- |
+| `city_ids`               | —       | **required.** [Find city IDs](https://github.com/eladnava/pikud-haoref-api/blob/master/cities.json) |
+| `telegram.bot_token`     | —       | **required.** Token from @BotFather                                                                 |
+| `telegram.chat_id`       | —       | **required.** Chat ID (negative number)                                                             |
+| `language`               | `ru`    | `ru` `en` `he` `ar`                                                                                 |
+| `alert_types`            | all     | `early` `siren` `incident_over`                                                                     |
+| `gif_mode`               | `none`  | `funny_cats` `assertive` `pikud_haoref` `none`                                                      |
+| `title_override.*`       | —       | Custom title per alert type                                                                         |
+| `description_override.*` | —       | Custom description per alert type                                                                   |
+
+---
+
+## License
+
+[MIT](LICENSE) — Mikhail Kogan, 2026

package/dist/bin.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * EasyOref CLI entrypoint.
+ *
+ *   npx easyoref          — run the bot
+ *   npx easyoref init     — interactive setup wizard
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}

package/dist/bin.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * EasyOref CLI entrypoint.
+ *
+ *   npx easyoref          — run the bot
+ *   npx easyoref init     — interactive setup wizard
+ */
+const command = process.argv[2];
+if (command === "init") {
+    const { init } = await import("./init.js");
+    await init();
+}
+else if (command === "--help" || command === "-h") {
+    console.log(`
+  Usage:
+    easyoref          Start the bot
+    easyoref init     Interactive setup wizard
+    easyoref --help   Show this message
+`);
+}
+else {
+    await import("./bot.js");
+}
+export {};
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAEhC,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;IACvB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;IAC3C,MAAM,IAAI,EAAE,CAAC;AACf,CAAC;KAAM,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;IACpD,OAAO,CAAC,GAAG,CAAC;;;;;CAKb,CAAC,CAAC;AACH,CAAC;KAAM,CAAC;IACN,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;AAC3B,CAAC"}

package/dist/bot.d.ts

@@ -0,0 +1,16 @@
+/**
+ * EasyOref — Real-time Israeli Red Alert Filter Bot
+ *
+ * Architecture:
+ *   oref.org.il API → local filter (area map) → Telegram (grammY)
+ *
+ * Flow:
+ *   1. Poll oref.org.il every 2 seconds for active alerts
+ *   2. Match areas against configured regions (Hebrew names)
+ *   3. Classify alert type: early warning / siren / incident over
+ *   4. If relevant → send calm message to family Telegram chat
+ *
+ * No LLM needed — purely deterministic matching for <1s latency.
+ */
+export {};
+//# sourceMappingURL=bot.d.ts.map

package/dist/bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}