@atmosx/event-product-parser 2.0.16 → 3.0.1

package/README.md

@@ -1,7 +1,6 @@
-<h1 style='font-size: 65px'; align="center">🌪️ AtmosphericX - Event Product Parser ⚠️</h1>
+# Project AtmosphericX - Event Product Parser (v3.0.0)
+
 <div align="center">
-  	<p align = "center">This repository contains the primary parser for AtmosphericX's NOAA Weather Wire Service (NWWS) and National Weather Service (NWS) API. It is designed to handle real time weather alerts and messages from the National Weather Service, using both XMPP (NWWS) and direct API access (Slower). This parser is intended for developers who want to integrate real time weather alerts, watches, warnings, and forecast data from the NWS seamlessly into their applications or services. It is not recommended for users without basic programming knowledge. If you wish to access NOAA weather data without programming, consider using our end-user project, which leverages this parser and provides an easy-to-use interface for tracking weather alerts.</small></p>
-  	<p align = "center">Documentation written by @k3yomi</p>
 	<div align="center" style="border: none;">
 		<img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/AtmosphericX/event-product-parser">
 		<img alt="GitHub forks" src="https://img.shields.io/github/forks/AtmosphericX/event-product-parser">
@@ -10,243 +9,308 @@
 	</div>
 </div>
 
+## What is `@atmosx/event-product-parser`
+This repository contains the primary function to obtain, parse, cache, and deliver products and events from the National Weather Service. There are two primary sources to obtain these products. By default, the repository uses the **National Weather Service API**. However, there is **FULL** support for **NOAA Weather Wire Service (Open Interface)**. This parser is intended for developers who want to integrate real-time weather alerts, watches, warnings, and forecast data from the NWS seamlessly into their applications or services without having to use external APIs from other sources / parsers. If you wish to access data without programming, consider using our end user project, which leverages this parser and provides an easy-to-use interface for tracking weather alerts. See [Documentation](https://atmosphericx.scriptkitty.cafe).
+
 ## Installation (NPM)
 ```bash
-npm install @atmosx/event-product-parser@latest
+npm install @atmosx/event-product-parser
 ```
 
-## Example Usage
-```javascript
-const { AlertManager } = require('@atmosx/product-parser'); // CJS
-import { AlertManager } from '@atmosx/product-parser'; // ESM
-
-const parser = new AlertManager({
-    database: `shapefiles.db`,
-    is_wire: true,
-    journal: true,
-    noaa_weather_wire_service_settings: {
-        reconnection_settings: {
-            enabled: true,
-            interval: 60,
+## Configurations & Usage
+```ts
+const { Manager } = require(`@atmosx/event-product-parser`) // CJS Importing
+import { Manager } from '@atmosx/event-product-parser' // EJS Importing
+
+const Client = new Manager({
+    Database: `shapefiles.db`,
+    EnableWireService: false,
+    EnableJournal: true,
+    NOAAWeatherWireServiceSettings: {
+        ReconnectionSettings: {
+            Enabled: true,
+            ReconnectionInterval: 60,
         },
-        credentials: {
-            username: `username_here`,
-            password: `password_here`,
-            nickname: "AtmosphericX Parser",
+        CredentialSettings: {
+            Username: `username`,
+            Password: `password`,
+            Nickname: "nickname (@atmosx/event-product-parser/3.0)",
         },   
-        cache: {
-            enabled: false,
-            max_db_history: 5000,
-            max_db_cache_size: 1000,
+        CacheSettings: {
+            Enabled: true,
+            MaxDatabaseHistory: 5000,
+            MaxRetentionHistory: 555,
         },
-        preferences: {
-            disable_ugc: false,
-            disable_vtec: false,
-            disable_text: false,
-            cap_only: false,
+        StanzaSettings: {
+            DisableUGC: false,
+            DisableVTEC: false,
+            DisableText: false,
         }
     },
-    national_weather_service_settings: {
-        interval: 15,
-        endpoint: `https://api.weather.gov/alerts/active`,
+    NationalWeatherServiceSettings: {
+        CallbackInterval: 30,
+        EventsEndpoint: `https://api.weather.gov/alerts/active`,
     },
-    global_settings: {
-        parent_events_only: true,
-        better_event_parsing: true,
-        shapefile_coordinates: false,
-        shapefile_skip: 10,
-        filtering: {
-            events: [`Severe Thunderstorm Warning`],
-            filtered_icao: [`KLOT`],
-            ignored_icao: [],
-            ignored_events: [`Xx`, `Test Message`],
-            ugc_filter: [],
-            state_filter: [],
-            check_expired: true,
-            ignore_test_products: true,
+    WebhookSettings: [
+        {
+            webhook: "https://discord.com/api/webhooks/XXXXXXXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", 
+            title: "AtmosphericX - (@atmosx/event-product-parser)", 
+            message: ``, 
+            events: [`Severe Thunderstorm Warning`, `Radar Indicated Tornado Warning`, `*Warning`, `*Thunderstorm*`],
+            rate: 5,
+        }
+    ],
+    GlobalSettings: {
+        EventManagement: true,
+        BetterEventNames: true,
+        DisableGeometryParsing: false,
+        UseShapefileCoordinates: true,
+        SPCWatchesOnly: true,
+        NodeTTL: 60,
+        NodeMinDistance: 120,
+        EventFiltering: {
+            ListeningEvents: [
+                "Tornado Emergency", "PDS Tornado Warning", "Tornado Warning",
+                "Confirmed Tornado Warning", "Radar Indicated Tornado Warning",
+                "Special Marine Warning (TPROB)", "PDS Tornado Watch", "Tornado Watch",
+                "EDS Severe Thunderstorm Warning (TPROB)", "EDS Severe Thunderstorm Warning",
+                "Destructive Severe Thunderstorm Warning (TPROB)", "Destructive Severe Thunderstorm Warning",
+                "Considerable Severe Thunderstorm Warning (TPROB)", "Considerable Severe Thunderstorm Warning",
+                "Severe Thunderstorm Warning (TPROB)", "Severe Thunderstorm Warning",
+                "Severe Thunderstorm Watch",
+                "Flash Flood Emergency", "Flash Flood Warning",
+                "Flash Flood Watch",
+                "Tsunami Warning", "Tsunami Watch",
+                "Tsunami Advisory", "Special Marine Warning",
+                "Earthquake Warning",
+                "Hurricane Warning", "Hurricane Watch",
+                "Tropical Storm Warning",
+                "Winter Storm Warning", "Blizzard Warning",
+                "Ice Storm Warning", "Snow Squall Warning",
+                "Winter Weather Advisory", "Extreme Cold Watch"
+            ],
+            ListeningICAO: [],
+            IgnoredICAO: [],
+            IgnoredEvents: [],
+            ListeningUGC: [],
+            ListeningStates: [],
+            NodeLocationFiltering: false,
+            IgnoreTestProducts: true,
         },
-        eas_settings: {
-            directory: null,
-            intro_wav: null,
+        EASSettings: {
+            ArchiveDirectory: null,
+            IntroWavFile: null,
         }
-    },
+    }
 })
 ```
+### General Settings
+- **Database**: The database file name and location, please make sure to include the `.db` extension.
+- **EnableWireService**: Whether to enable `NOAA Weather Wire Service` within the parser. This requires credentials from [NOAA Weather Wire Service](https://www.weather.gov/nwws/).
+- **EnableJournal**: Whether to output logs without requiring event `listeners`.
+
+### NOAAWeatherWireServiceSettings
+- **ReconnectionSettings**: When the XMPP client gets disconnected or has an error, choose to reconnect to the service again. This contains a reconnection check interval.
+- **CredentialSettings**: The username (nickname) and password that is required for using `NOAA Weather Wire Service`.
+- **CacheSettings**: The ability to use the cache system so when you relaunch the parser, it will have a event retention history of all the stanzas collected.
+- **StanzaSettings**: Modify what type of products metadata you'd like to receive. (UGC, VTEC, RawText)
+
+### NationalWeatherServiceSettings
+- **CallbackInterval**: The interval at which the parser will check for new alerts from the National Weather Service API.
+- **EventsEndpoint**: The URL that directs to the API.
+
+### WebhookSettings
+- **webhook**: The URL of the webhook you want to send messages to.
+- **title**: The title of the message you want to send.
+- **message**: The message content you want to send. You can use placeholders like `<@&role_id>` to mention roles in Discord.
+- **events**: An array of event types that will trigger the webhook when they are received by the parser. If this array is empty, the webhook will be triggered for all events.
+- **rate**: The rate limit in seconds for how often the webhook can be triggered. This is to prevent spamming the webhook with too many messages in a short period of time.
+
+### GlobalSettings
+- **EventManagement**: Whether to enable the event management system which includes filtering, tracking nodes, and custom messages.
+- **BetterEventNames**: Changes events to a more specific version depending on parameters, message types, etc. `(Ex. "Tornado Warning" -> "Observed Tornado Warning")`
+- **DisableGeometryParsing**: Disable automatically appending GeoJSON geometry data to the events to save on memory consumption.
+- **UseShapefileCoordinates**: Whether to use the shapefile database to obtain the coordinates for events with specified UGC zones.
+- **SPCWatchesOnly**: Whether to only listen for SPC watches only (TOR/SVR) (If using the API, this is ignored).
+- **NodeTTL**: How often nodes should be checked per event. (Tracking/Filtering)
+- **NodeMinDistance**: The minimum distance to filter events from the node (Miles)
+- **ListeningEvents**: Events you'd like to listen for. If this array is left empty, it will listen for **ALL** events and products.
+- **ListeningICAO**: ICAO codes for the weather stations you'd like to listen for. Filtering all events that do not contain the codes. `(Ex. ["KLOT", "TORD"])`
+- **IgnoredICAO**: Ignored ICAO codes `(Ex. ["KWNS"])`
+- **IgnoredEvents**: Ignored events / products.
+- **ListeningUGC**: Zones you'd like to listen to `(Ex. ["ILZ001"])`
+- **ListeningStates**: States you'd like to listen to `(Ex. ["IL"])`
+- **NodeLocationFiltering**: If you want tracking nodes to filter out events based on radius. (Miles)\
+- **IgnoreTextProducts**: If you want to ignore test products and events.
+- **ArchiveDirectory**: The directory you'd like to store generated EAS audio files.
+- **IntroWavFile**: The PCM16 bit WAV audio file to append to the EAS message.
+
 
-## NOAA Weather Wire Service (Getting Started)
-To use the NOAA Weather Wire Service (NWWS). You would need to obtain credentials from the National Weather Service. Follow these steps:
-1. Visit the [NOAA NWWS Registration Page](https://www.weather.gov/nwws/nwws_oi_request).
-2. Fill out the registration form with the required information.
-3. Submit the form and wait for approval. You will receive your NWWS credentials via email.
 
 ## Events and Listeners
-> All events are in GeoJSON.
-
-### Event `onEvents`
-Triggered when a batch of new alerts are received and processed.
-```javascript
-parser.on(`onEvents`, (alerts) => {
-    console.log(`Received ${alerts.length} new alerts.`);
-    alerts.forEach(alert => {
-        console.log(`${alert.properties.event} for ${alert.properties.locations}`);
-    });
-});
+
+### Event `onServiceStatus`
+Triggers when an update to the XMPP / API service status occurs.
+```ts
+Client.on(`onServiceStatus`, (xmpp) => {
+	/*
+		message: string
+		data: object
+		type: string
+		error: boolean
+	*/
+})
 ```
-Alternatively, you can listen for single alert events using `onSevereThunderstormWarning` or `onTornadoWarning`, etc.
-```javascript
-parser.on(`onTornadoWarning`, (alert) => {
-    console.log(`Tornado Warning issued for ${alert.properties.locations}`);
-});
+
+### Event `onTestProduct`
+Triggers when a event is labeled as a **test message**. See [`types.event.ts`](./src/@types/type.event.ts) for properties.
+```ts
+Client.on(`onTestProduct`, (product: TypeEvent) => {})
 ```
 
-### Event `onReconnection`
-Triggered when the parser attempts to reconnect to the NWWS service.
-```javascript
-parser.on(`onReconnection`, (data) => {
-    console.log(`Reconnection attempt #${data.reconnects}`);
-});
+### Event `onExpiredProduct`
+Triggers when a event is cancelled, expired, or terminated. See [`types.event.ts`](./src/@types/type.event.ts) for properties.
+```ts
+Client.on(`onExpiredProduct`, (product: TypeEvent) => {})
 ```
 
-### Event `onConnection`
-Triggered when the parser successfully connects to the NWWS service.
-```javascript
-parser.on(`onConnection`, (nickname) => {
-    console.log(`Connected to NWWS service as ${nickname}`);
-});
+### Event `onProductType`
+Supports all events and product, simply append the event name to the end like `onProductTypeRadarIndicatedTornadoWarning` and you will receive the event in the listener.
+This listener returns [`types.event.ts`](./src/@types/type.event.ts).
+```ts
+Client.on(`onProductTypeRadarIndicatedTornadoWarning`, (product: TypeEvent) => {})
 ```
 
-### Event `onOccupant`
-Triggered when a new occupant is detected on the NWWS XMPP service.
-```javascript
-parser.on(`onOccupant`, (data) => {
-    console.log(`New occupant detected: ${data.occupant}`);
-});
+### Event `onFilteredEvent`, `onIgnoredEvent`, `onFilteredICAO`, `onIgnoredICAO`, `onFilteredUGC`, `onFilteredState`
+These events all support [`types.event.ts`](./src/@types/type.event.ts) and are used to filter out events and products based on your settings.
+```ts
+Client.on(`onFilteredEvent`, (product: TypeEvent) => {})
 ```
 
-### Event `onMessage`
-Triggered when a stanza message is validated and received from the XMPP client.
-```javascript
-parser.on(`onMessage`, (data) => {
-    console.log(`Message received from ${data.from}: ${data.message}`);
-});
+### Event `onEventCache`
+When all events in a batch have finished processing, a cache update will trigger allowing you to get a copy of all registered events in a listener. (**GeoJSON**)
+```ts
+Client.on(`onEventCache`, (cache) => {})
 ```
 
-### Event `onTest`
-Triggered when a test message comes in. Ex: Test Tsunami Warning
-```javascript
-parser.on(`onTest`, (alert) => {
-    console.log(`Test alert received for ${alert.properties.locations}`);
-});
+### Event `onNodeAdd`,  `onNodeUpdate`, `onNodeDelete`
+Triggers when a tracking node gets added, updated, or deleted.
+```ts
+Client.on(`onNodeAdd`, (cache) => {
+	/*
+		type: string
+		node: object
+	*/
+})
 ```
 
-### Event `onExpired`
-Triggered when an alert expires.
-```javascript
-parser.on(`onExpired`, (alert) => {
-    console.log(`Alert expired for ${alert.properties.event} for locations of ${alert.properties.locations}`);
-});
+### Event `onStormPredictionWatch`, `onNonStormPredictionWatch`
+Triggers when a SPC watch gets added, updated, or cancelled. This will also add a custom message if using jorunal or the `log` listener.
+```ts
+Client.on(`onProductTypeRadarIndicatedTornadoWarning`, (product: TypeEvent) => {})
 ```
 
-### Event `onFilteredEvent` / `onIgnoredEvent`
-Triggered when an alert is filtered out.
-```javascript
-parser.on(`onFilteredEvent`, (alert) => {
-    console.log(`Alert filtered for ${alert.properties.event}`);
-});
-parser.on(`onIgnoredEvent`, (alert) => {
-    console.log(`Alert ignored for ${alert.properties.event}`);
-});
+### Event `onEventStatus`
+Triggers when a single event gets added, updated, or cancelled. This will also add a custom message if using jorunal or the `log` listener.
+```ts
+Client.on(`onEventStatus`, (cache) => {
+	/*
+		type: string
+		event: <TypeEvent>
+	*/
+})
 ```
 
-### Event `onFilteredICAO` / (`onIgnoredICAO`)
-Triggered when an alert is filtered out based on its ICAO code.
-```javascript
-parser.on(`onFilteredICAO`, (alert) => {
-    console.log(`Alert filtered for ${alert.properties.event}`);
-});
-parser.on(`onIgnoredICAO`, (alert) => {
-    console.log(`Alert ignored for ${alert.properties.event}`);
-});
+### Function `setSettings`
+Allows you to dynamically update parser settings without restarting the service.
+```ts
+import { setSettings } from "@atmosx/event-product-parser"
+setSettings({
+	Database: `NewDatabaseFile.db`
+})
 ```
 
-### Event `onFilteredUGC`
-Triggered when an alert is filtered out based on its UGC zone.
-```javascript
-parser.on(`onFilteredUGC`, (alert) => {
-    console.log(`Alert filtered for ${alert.properties.event}`);
-});
+### Function `getEventGeometry`
+Fetches the `events` geometry (GeoJSON) coordinates table.
+```ts
+import { getEventGeometry } from "@atmosx/event-product-parser"
+const event = {...}
+const geometry = await getEventGeometry(event); // Returns GeoJSON 
 ```
 
-### Event `onFilteredState`
-Triggered when an alert is filtered out based on its state (Abbreviation)
-```javascript
-parser.on(`onFilteredState`, (alert) => {
-    console.log(`Alert filtered for ${alert.properties.event}`);
-});
+### Function `getRandomEvent`
+Fetches a random event from the cache
+```ts
+import { getRandomEvent } from "@atmosx/event-product-parser"
+const event = getRandomEvent(event); // Returns GeoJSON of an event.
 ```
 
-### Event `log`
-Triggered for logging purposes, providing log level and message.
-```javascript
-parser.on(`log`, (message) => {
-    console.log(data.message);
-});
+### Function `getVersion`
+Returns the current version of the parser.
+```ts
+import { getVersion } from "@atmosx/event-product-parser"
+const version = getVersion(); // Returns the current version of the parser.
 ```
 
-## Callbacks and Functions
 
-### Function `setDisplayName(name)`
-Sets the display name for the XMPP client. This requires reconnection to take effect.
-```javascript
-parser.setDisplayName(`My Weather Parser`);
+### Function `getCleanedEvent`
+Removed any `NULL` values from the event itself. Therefore cleaning it up from any properties that are `NULL`.
+```ts
+import { getCleanedEvent } from "@atmosx/event-product-parser"
+const event = {...}
+const cleanedEvent = await getCleanedEvent(event); // Returns cleaned event object.
 ```
 
-### Function `createEasAudio(description, header)`
-Generates an EAS audio file based on the provided description and header. Audio file will be located based on settings provided in the global_settings.eas_settings object.
-If you are running linux, festival is required to use this or it will error out.
-```javascript
-parser.createEasAudio(`This is a test alert`, `EAS Header Info`);
-```
 
-### Function `getAllAlertTypes()`
-Returns an array of all supported alert types by the parser.
-```javascript
-const alertTypes = parser.getAllAlertTypes();
-console.log(alertTypes);
+### Function `startService`
+Starts the event product parser service.
+```ts
+import { startService } from "@atmosx/event-product-parser"
+startService()
 ```
 
-### Function `getEventPolygon(event)`
-Retrieves the geographical polygon for a given event based on its generated geocode and UGC zones. (Returns in GeoJSON format)
-```javascript
-const polygon = await parser.getEventPolygon(event);
-console.log(polygon);
+
+### Function `setNode`
+Sets up a tracking node using an identifier, longitude, and latitude values.
+```ts
+import { setNode } from "@atmosx/event-product-parser"
+setNode({
+	identifier: `TestNode`, 
+	coordinates: {longitude: -122.4194, latitude: 37.7749}, 
+	delete: false
+})
 ```
 
-### Function `searchStanzaDatabase(query)`
-Searches the internal stanza database for messages matching the provided query.
-```javascript
-const results = parser.searchStanzaDatabase(`Tornado Warning`);
-console.log(results);
+
+### Function `getEvents`
+Fetches the list of events from the parser.
+```ts
+import { getEvents } from "@atmosx/event-product-parser"
+const events = getEvents() // Returns in GeoJSON (Similar to the onEventCache listener)
+console.log(events)
 ```
 
-### Function `setSettings({})`
-Dynamically updates the parser settings. Accepts the same configuration object as the constructor.
-```javascript
-parser.setSettings({
-    global_settings: {
-        filtering: {
-            ignored_icao: [`KXYZ`],
-        }
-    }
-});
+
+### Function `getNodes`
+Fetches the list of tracking nodes from the parser.
+```ts
+import { getNodes } from "@atmosx/event-product-parser"
+const nodes = getNodes()
+console.log(nodes)
 ```
 
-### Function `stop()`
-Stops the parser and disconnects from the NWWS service.
-```javascript
-parser.stop();
+### Function `setEasTone`
+Fetches an EAS audio message for an event (Simulated)
+```ts
+import { setEasTone } from "@atmosx/event-product-parser"
+const event = {...}
+await setEasTone(event.properties.description, event.properties.metadata.header)
 ```
 
+## Performance Recommendations
+- Enable cache retention
+- Disable geometry parsing if GeoJSON is unnecessary.
+
 ## References
 [NOAA NWWS Information](https://www.weather.gov/nwws/) | 
 [NWS API Documentation](https://www.weather.gov/documentation/services-web-api) |
@@ -263,6 +327,3 @@ parser.stop();
 
 ## Acknowledgements
 - [k3yomi](https://github.com/k3yomi)
-    - Lead developer @ AtmosphericX and maintainer of this module.
-- [StarflightWx](https://x.com/starflightVR)
-    - For testing and providing feedback (Co-Developer and Spotter @ AtmosphericX)