kiosko-plugin-hazards 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Loksly
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,191 @@
1
- # Temporary Holding Version
1
+ # kiosko-plugin-hazards
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Official warnings published by the NWS, tsunami.gov, Taiwan's CWA (via
4
+ NCDR), AEMET, Meteoalarm and GDACS, on your panels: a tsunami warning for
5
+ your coast or a red weather warning for your area takes every screen over
6
+ as a Kiosko alert, with who published it and their instruction as they
7
+ wrote it. A tile lists the latest ones and when each feed last answered.
8
+
9
+ A plugin for [Kiosko](https://github.com/kiosko-lcd/kiosko), the widget mosaic
10
+ for small USB LCD panels. **Optional:** Kiosko doesn't install it.
11
+
12
+ > **Informational. It does not replace official alerts** (your phone's
13
+ > emergency alerts, ES-Alert, WEA, radio and TV). The warnings can reach your
14
+ > panel **minutes after** they are published: Kiosko asks each feed every
15
+ > 1–15 minutes, and your computer has to be on and Kiosko running. This is
16
+ > not an early-warning system: no open feed carries the alerts sent seconds
17
+ > before an earthquake shakes (ShakeAlert, 強震即時警報, 緊急地震速報 and
18
+ > ES-Alert go to phones only). If the ground shakes hard near the coast, go
19
+ > to high ground without waiting for any warning. The plugin is MIT
20
+ > licensed, without warranty; GDACS calls its data "indicative", AEMET is not
21
+ > liable for the use of its data, and naming an authority does not mean it
22
+ > endorses Kiosko.
23
+
24
+ ## Needs
25
+
26
+ Kiosko **0.2.7 or later** for full use: the switch that keeps the source
27
+ running with no tile, and the alert's source and instruction lines. On
28
+ 0.2.0–0.2.6 it loads, but its alerts only run while a tile of it is on some
29
+ page, and show only a title and a line.
30
+
31
+ ## Install
32
+
33
+ ```sh
34
+ npm install --prefix ~/.config/kiosko/plugins kiosko-plugin-hazards
35
+ ```
36
+
37
+ (macOS: `~/Library/Application Support/Kiosko/plugins`, Windows: `%APPDATA%\Kiosko\plugins`.)
38
+
39
+ Then, in the editor:
40
+
41
+ 1. **Settings → Place**: your place. The feeds and the area filter use it.
42
+ 2. **Settings → Data sources → Official warnings**: turn on **Watch for
43
+ alerts without a widget**. No tile is needed for the full-screen alerts.
44
+ 3. Optionally, a **Latest warnings** tile on some page.
45
+ 4. Optionally, a drill (below), to see it work end to end.
46
+
47
+ ## What reaches your panel
48
+
49
+ | Feed (`feeds`) | Published by | What | Asked every | Typical delay | Terms |
50
+ |---|---|---|---|---|---|
51
+ | `nws` | US National Weather Service (api.weather.gov, filtered for your point by the NWS) | Every NWS warning for your point, tsunami ones included | 1 min | not published | Public domain |
52
+ | `tsunami-ntwc` | NOAA National Tsunami Warning Center (tsunami.gov) | Tsunami warnings, advisories, watches and information statements for the US and Canada | 1 min | minutes after the earthquake | Public domain |
53
+ | `tsunami-ptwc` | NOAA Pacific Tsunami Warning Center (tsunami.gov) | The same for Hawaii, the Pacific and the Caribbean | 1 min | minutes | Public domain |
54
+ | `ncdr` | Taiwan's Central Weather Administration and other agencies, via NCDR (民生示警) | Typhoon, rain, wind, cold, earthquake, tsunami… | 1 min (and 3.5 s between requests) | report 5–10 min, tsunami ≈ 20 min | Open Government Data Licence 1.0 (attribution) |
55
+ | `aemet` | AEMET (Meteoalerta) | Spanish weather warnings | 10 min | hours ahead (forecasts) | Free reuse citing © AEMET |
56
+ | `meteoalarm-<country>` | Meteoalarm (the national weather services of Europe) | Weather warnings; no earthquakes or tsunamis | 10 min | as the national service | Terms equivalent to CC BY 4.0, with extra terms for redistribution |
57
+ | `gdacs` | GDACS (UN and European Commission) | Earthquakes, cyclones and floods worldwide, green/orange/red by people exposed | 15 min | tens of minutes | CC BY 4.0; "indicative" |
58
+ | `test` | This plugin | A drill (below) | once | — | — |
59
+
60
+ With `feeds` empty, it picks by your place: **US** `nws`, `tsunami-ntwc`,
61
+ `tsunami-ptwc`; **Taiwan** `ncdr`; **Spain** `aemet`; **Portugal, France,
62
+ Italy, Germany, the UK, Ireland, the Netherlands, Belgium, Austria and
63
+ Switzerland** their Meteoalarm feed and `gdacs`; **elsewhere** `gdacs`.
64
+ `!gdacs` leaves one out; `aemet, gdacs` names them.
65
+
66
+ `customFeeds` takes the Atom, RSS or single-message CAP feed of any other
67
+ alerting authority: the [WMO Register of Alerting Authorities](https://alertingauthority.wmo.int/)
68
+ lists them by country.
69
+
70
+ Each alert and each row names its source. Their licences ask for it, and you
71
+ must know where a warning comes from.
72
+
73
+ ## How a warning becomes an alert
74
+
75
+ The first rule that applies decides:
76
+
77
+ | Warning | Level |
78
+ |---|---|
79
+ | A test or an exercise (`status` Test, Exercise) | Nothing; with `includeTests`, info with **TEST** / **EXERCISE** in front. Never as real. |
80
+ | Cancelled, or "all clear" | The alert goes; "Warning over" (info) for 2 minutes |
81
+ | Tsunami **Warning** for your coast | **critical** |
82
+ | Tsunami Advisory or Watch | warn |
83
+ | Tsunami information statement ("no threat") | The tile only |
84
+ | A colour from the authority (AEMET, Meteoalarm, CWA): red / orange / yellow | `maxWeatherLevel` (warn) / warn / info |
85
+ | Extreme, immediate or expected, observed or likely | **critical** |
86
+ | Severe, immediate or expected, observed or likely | warn (critical if `maxWeatherLevel` is critical) |
87
+ | Extreme or Severe, later or less certain | warn |
88
+ | Moderate | info |
89
+ | Minor, unknown, or already past | The tile only |
90
+ | Earthquake report within `radiusKm` and at least `minMagnitude` | `maxQuakeLevel` (warn) |
91
+ | Earthquake report farther away, orange or red for GDACS | info |
92
+
93
+ Why earthquake reports stay at warn: they say what has already happened. In
94
+ quiet hours only critical goes through, and a report at 3 a.m. should not
95
+ wake the panel to tell you about something that is over. A tsunami warning
96
+ is critical because it is the one thing here that can arrive before the
97
+ danger.
98
+
99
+ A warning is yours when your place is inside its polygon or circle (plus
100
+ `marginKm`), in a zone you chose (`zones`), in the US state of its UGC zone
101
+ codes (tsunami.gov), or in the Taiwan county of its NCDR towns. A warning
102
+ whose area can't be told never takes the screen: the tile counts them and
103
+ asks you to choose zones (Meteoalarm gives only zone codes).
104
+
105
+ Updates replace what they update (same level: same alert, so **Seen** holds;
106
+ a higher level: a new alert); a warning ends when it is cancelled, when it
107
+ expires (when it doesn't say: 30 min for a report, 6 h for a tsunami, 12 h
108
+ for weather) or, in feeds that list what is in force, after two reads in a
109
+ row without it. What the plugin knows is kept in its data folder, so a
110
+ restart neither repeats old warnings nor loses current ones.
111
+
112
+ ## When a feed is down
113
+
114
+ The tile says it in amber ("AEMET: no data since 14:05") and keeps its
115
+ place; it never takes the screen. Without fresh data it doesn't say "no
116
+ warnings", it says "no warnings data". Warnings already open stay until they
117
+ expire.
118
+
119
+ ## Drill
120
+
121
+ Add `test` to `feeds`: once, a tsunami warning marked **TEST** in your area
122
+ goes through the parser, the area filter and the levels like a real one,
123
+ shows critical for 60 seconds and expires. It doesn't come back on a
124
+ restart; take `test` out and put it back for another. To try a CAP file of
125
+ your own, put its `file://` path in `customFeeds`. To see how an alert of
126
+ each level looks on a screen, Kiosko has **Screens → Test alert**.
127
+
128
+ ## Source
129
+
130
+ ### Official warnings — `hazards/alerts`
131
+
132
+ Settings → Data sources.
133
+
134
+ | Option | Type | Default | |
135
+ |---|---|---|---|
136
+ | `feeds` | filter | `[]` | Empty: the ones for your place (above). |
137
+ | `customFeeds` | list of URLs | `[]` | Your own CAP feeds (Atom, RSS, a CAP message, or `file://`). Contacts those hosts or reads those files. |
138
+ | `kinds` | filter | `earthquake, tsunami, weather` | Also `other`. |
139
+ | `events` | filter | `[]` | By the authority's event name (`*Wind*`, `!*Frost*`). |
140
+ | `zones` | filter | `[]` | Zone codes or names for warnings without a shape (`ES239`, `CAZ043`, `桃園市*`). |
141
+ | `marginKm` | km | `0` | Also warnings for areas this close. |
142
+ | `radiusKm` | km | `300` | Earthquake reports nearer than this… |
143
+ | `minMagnitude` | number | `4` | …and at least this big take the screen. |
144
+ | `maxQuakeLevel` | `info` \| `warn` \| `critical` | `warn` | Level of a near earthquake report. |
145
+ | `maxWeatherLevel` | `info` \| `warn` \| `critical` | `warn` | Highest level of a red or a Severe weather warning. |
146
+ | `includeTests` | boolean | `false` | Tests and exercises, as info and marked. |
147
+ | `staleMs` | duration | 15 min | A feed silent this long is shown as down. |
148
+ | `latitude`, `longitude`, `placeName` | advanced | 0, 0, `""` | Another place than Settings'. |
149
+
150
+ ## Widget
151
+
152
+ ### Latest warnings — `hazards/latest`
153
+
154
+ The warnings in force for you and the earthquake reports of the last day,
155
+ the gravest first, each with where, until when (or how long ago) and who
156
+ published it; what is over stays greyed for a day. Below: the feeds that
157
+ are down, the data's age, and the note "Informational · not a substitute for
158
+ official warnings". Preferred 640×462, at least 320×154.
159
+
160
+ | Option | Type | Default | |
161
+ |---|---|---|---|
162
+ | `kinds` | filter | `[]` | Only some kinds (`earthquake` for a tile of earthquakes). |
163
+ | `rows`, `layout` | list options | `0`, `auto` | As in every Kiosko list. |
164
+
165
+ ## What it does on your machine
166
+
167
+ - **Contacts** only the feeds it reads: `api.weather.gov`,
168
+ `www.tsunami.gov`, `alerts.ncdr.nat.gov.tw`, `www.aemet.es`,
169
+ `feeds.meteoalarm.org`, `www.gdacs.org`, and the hosts of your
170
+ `customFeeds`. Conditional requests (ETag, Last-Modified), one request at a
171
+ time per host, waiting when a server asks to (`Retry-After`), and a
172
+ User-Agent that names the plugin and Kiosko, never you. Your place goes to
173
+ the NWS only (its `point=` filter), and only for a place in the US.
174
+ - **Reads** the `file://` paths in `customFeeds`, if any.
175
+ - **Writes** its state (open warnings, messages seen, AEMET's zone shapes)
176
+ in its data folder.
177
+ - No programs, no devices. Sound for alerts, when it comes, will be Kiosko's.
178
+
179
+ The XML reader is its own and small: it refuses any document with a DTD or
180
+ an entity declaration (no XXE, no "billion laughs"), and documents over
181
+ 10 MB (1 MB for one CAP message), 64 levels deep or with 200 000 elements.
182
+ tsunami.gov's XML signatures are not checked yet.
183
+
184
+ ## Testing
185
+
186
+ `npm test` runs against real messages saved from each feed
187
+ (`src/fixtures/`, see its README), plus attacks on the XML reader.
188
+
189
+ ## Licence
190
+
191
+ MIT. The warnings belong to their authorities, under their terms (above).