atmosx-nwws-parser 1.0.16

package/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2025 k3yomi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), 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:
+
+1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+2. The author of the software must be credited in all copies or substantial portions of the Software, including but not limited to documentation, README files, and source code comments.
+
+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,88 @@
+# AtmosphericX - NOAA Weather Wire Service Parser
+
+
+This repository contains the primary parser for AtmosphericX's NOAA Weather Wire Service parser. It is designed to handle real time weather alerts and messages from the National Weather Service using XMPP. If you do not know basic programming, this parser is not for you. It is intended for developers who want to integrate alerts from NOAA Weather Wire easily into their applications or services without hassle. If you wish to use NWWS without programming, feel free to use our project where most of this code was used - [AtmosphericX](https://github.com/k3yomi/AtmosphericX).
+
+## Installation Guide
+To install this package, you can use **NPM** (Node Package Manager). Open your terminal and run the following command:
+
+```bash
+npm install atmosx-nwws-parser
+```
+
+## Usage
+```js
+const AtmosXWireParser = require(`atmosx-nwws-parser`); // or require(`@k3y0mi/nwws-parser`);
+```
+
+## Configuration and Initialization
+
+There are several settings you can configure when intializing the parser. Below is the test.js example that shows some of the settings you can use:
+
+```js
+let Client = new AtmosXWireParser({
+    alertSettings: { 
+        onlyCap: false, // Set to true to only receive CAP messages only
+        betterEvents: true, // Set to true to receive better event handling
+        ugcPolygons: false, // Set to true to receive UGC Polygons instead of reading from raw products. 
+        filteredAlerts: [] // Alerts you want to only log, leave empty to receive all alerts (Ex. ["Tornado Warning", "Radar Indicated Tornado Warning"])
+    },
+    xmpp: {
+        reconnect: true, // Set to true to enable automatic reconnection if you lose connection
+        reconnectInterval: 60, // Interval in seconds to attempt reconnection
+    },
+    cacheSettings: {
+        maxMegabytes: 2, // Maximum cache size in megabytes
+        readCache: false, // Set to true if you wish to reupload the cache from earlier
+        cacheDir: `./cache`, // Directory for cache files
+    },
+    authentication: {
+        username: `USERNAME_HERE`, // Your XMPP username
+        password: `PASSWORD_HERE`, // Your XMPP password
+        display: `DISPLAY_NAME` // Display name for your XMPP client
+    },
+    database: `./database.db`, // Path to the SQLite database file (It will be created if it doesn't exist and will be used to store UGC counties and zones.)
+});
+```
+
+
+## Event Handling
+
+You can handle various events emitted by the parser. Here are some examples:
+
+```js
+Client.onEvent(`onAlert`, (alerts: Array) => {});
+Client.onEvent(`onStormReport`, (report: Object) => {});
+Client.onEvent(`onMesoscaleDiscussion`, (discussion: Object) => {});
+Client.onEvent(`onMessage`, (stanza: Object) => {});
+Client.onEvent(`onOccupant`, (occupant: Object) => {});
+Client.onEvent(`onError`, (error: Object) => {});
+Client.onEvent(`onReconnect`, (service: Object) => {});
+
+```
+
+## Functions and Methods
+You can also use various functions provided by the parser. Here are some examples:
+```js
+// Debugging function to create your own alert manually
+Client.forwardCustomStanza(stanza: String, attributes: Object);
+```
+
+```js
+// Function to set the display name of the XMPP client (Will only set upon reconnect)
+Client.setDisplayName(displayName: String);
+```
+
+## Error Handling
+The parser can emit various errors. Here are some common errors you might encounter:
+
+**not-authorized**: This error occurs when the parser is not authorized to connect to the XMPP server. Ensure that your username and password are correct.
+
+**unreachable-host**: This error indicates that the parser cannot reach the XMPP server. Check your internet connection and ensure that the server address is correct.
+
+**service-error**: This error occurs when there is an issue with the XMPP service. It could be due to server maintenance or other issues. You can try reconnecting after some time.
+
+**no-database-dir**: This error occurs when the database directory does not exist. Ensure that the directory specified in the `database` setting exists or create it before running the parser.
+
+## Credits
+This parser is developed and maintained by [K3YOMI](https://github.com/K3YOMI) and the AtmosphericX Team. It is open-source and available for contributions and improvements. If you find any issues or have suggestions, feel free to open an issue or submit a pull request in the repository.

package/bootstrap.js

@@ -0,0 +1,110 @@
+module.exports = {
+    cache: {},
+    settings: {},
+    static: {},
+    packages: {},
+    definitions: {}
+}
+
+module.exports.packages = {
+    fs: require(`fs`),
+    path: require(`path`),
+    events: require(`events`),
+    xmpp: require(`@xmpp/client`),
+    shapefile: require(`shapefile`),
+    xml2js: require(`xml2js`),
+    sqlite3: require(`better-sqlite3`),
+    mStanza: require(`./src/stanza.js`),
+    mVtec: require(`./src/vtec.js`),
+    mUGC: require(`./src/ugc.js`),
+    mText: require(`./src/text.js`),
+    mEvents: require(`./src/events.js`),
+
+}
+
+module.exports.definitions = {
+    events: { "AF": "Ashfall", "AS": "Air Stagnation", "BH": "Beach Hazard", "BW": "Brisk Wind", "BZ": "Blizzard", "CF": "Coastal Flood", "DF": "Debris Flow", "DS": "Dust Storm", "EC": "Extreme Cold", "EH": "Excessive Heat", "XH": "Extreme Heat", "EW": "Extreme Wind", "FA": "Areal Flood", "FF": "Flash Flood", "FG": "Dense Fog", "FL": "Flood", "FR": "Frost", "FW": "Fire Weather", "FZ": "Freeze", "GL": "Gale", "HF": "Hurricane Force Wind", "HT": "Heat", "HU": "Hurricane", "HW": "High Wind", "HY": "Hydrologic", "HZ": "Hard Freeze", "IS": "Ice Storm", "LE": "Lake Effect Snow", "LO": "Low Water", "LS": "Lakeshore Flood", "LW": "Lake Wind", "MA": "Special Marine", "MF": "Dense Fog", "MH": "Ashfall", "MS": "Dense Smoke", "RB": "Small Craft for Rough Bar", "RP": "Rip Current Risk", "SC": "Small Craft", "SE": "Hazardous Seas", "SI": "Small Craft for Winds", "SM": "Dense Smoke", "SQ": "Snow Squall", "SR": "Storm", "SS": "Storm Surge", "SU": "High Surf", "SV": "Severe Thunderstorm", "SW": "Small Craft for Hazardous Seas", "TO": "Tornado", "TR": "Tropical Storm", "TS": "Tsunami", "TY": "Typhoon", "UP": "Heavy Freezing Spray", "WC": "Wind Chill", "WI": "Wind", "WS": "Winter Storm", "WW": "Winter Weather", "ZF": "Freezing Fog", "ZR": "Freezing Rain", "ZY": "Freezing Spray" },
+    actions: { "W": "Warning", "F": "Forecast", "A": "Watch", "O": "Outlook", "Y": "Advisory", "N": "Synopsis", "S": "Statement"},
+    status: { "NEW": "Issued", "CON": "Updated", "EXT": "Extended", "EXA": "Extended", "EXB": "Extended", "UPG": "Upgraded", "COR": "Correction", "ROU": "Routine", "CAN": "Cancelled", "EXP": "Expired" },
+    awips: { SWOMCD: `mesoscale-discussion`, LSR: `local-storm-report`, SPS: `special-weather-statement`, LSR: "local-storm-report"},
+    expressions: {
+        vtec: `[OTEX].(NEW|CON|EXT|EXA|EXB|UPG|CAN|EXP|COR|ROU).[A-Z]{4}.[A-Z]{2}.[WAYSFON].[0-9]{4}.[0-9]{6}T[0-9]{4}Z-[0-9]{6}T[0-9]{4}Z`,
+        wmo: `[A-Z0-9]{6}\\s[A-Z]{4}\\s\\d{6}`,
+        ugc1: `(\\w{2}[CZ](\\d{3}((-|>)\\s?(\n\n)?))+)`,
+        ugc2: `(\\d{6}(-|>)\\s?(\n\n)?)`,
+        dateline: `/\d{3,4}\s*(AM|PM)?\s*[A-Z]{2,4}\s+[A-Z]{3,}\s+[A-Z]{3,}\s+\d{1,2}\s+\d{4}`
+    },
+    tags: {
+        "A LARGE AND EXTREMELY DANGEROUS TORNADO": "Large and Dangerous Tornado",
+        "THIS IS A PARTICULARLY DANGEROUS SITUATION": "Particularly Dangerous Situation",
+        "RADAR INDICATED ROTATION": "Radar Indicated Tornado",
+        "WEATHER SPOTTERS CONFIRMED TORNADO": "Confirmed by Storm Spotters",
+        "A SEVERE THUNDERSTORM CAPABLE OF PRODUCING A TORNADO": "Developing Tornado",
+        "LAW ENFORCEMENT CONFIRMED TORNADO": "Reported by Law Enforcement",
+        "A TORNADO IS ON THE GROUND": "Confirmed Tornado",
+        "WEATHER SPOTTERS REPORTED FUNNEL CLOUD": "Confirmed Funnel Cloud by Storm Spotters",
+        "PUBLIC CONFIRMED TORNADO": "Public reports of Tornado",
+        "RADAR CONFIRMED": "Radar Confirmed",
+        "TORNADO WAS REPORTED BRIEFLY ON THE GROUND": "Tornado no longer on ground",
+        "SPOTTERS INDICATE THAT A FUNNEL CLOUD CONTINUES WITH THIS STORM": "Funnel Cloud Continues",
+        "A TORNADO MAY DEVELOP AT ANY TIME": "Potentional still exists for Tornado to form",
+        "LIFE-THREATENING SITUATION": "Life Threating Situation",
+        "COMPLETE DESTRUCTION IS POSSIBLE": "Extremly Damaging Tornado",
+        "POTENTIALLY DEADLY TORNADO": "Deadly Tornado",
+        "RADAR INDICATED": "Radar Indicated",
+        "HAIL DAMAGE TO VEHICLES IS EXPECTED": "Damaging to Vehicles",
+        "EXPECT WIND DAMAGE": "Wind Damage",
+        "FREQUENT LIGHTNING": "Frequent Lightning",
+        "PEOPLE AND ANIMALS OUTDOORS WILL BE INJURED": "Capable of Injuring People and Animals",
+        "TRAINED WEATHER SPOTTERS": "Confirmed by Storm Spotters",
+        "SOURCE...PUBLIC": "Confirmed by Public",
+        "SMALL CRAFT COULD BE DAMAGED": "Potential Damage to Small Craft",
+        "A TORNADO WATCH REMAINS IN EFFECT": "Active Tornado Watch",
+        "TENNIS BALL SIZE HAIL": "Tennis Ball Size Hail",
+        "BASEBALL SIZE HAIL": "Baseball Size Hail",
+        "GOLF BALL SIZE HAIL": "Golf Ball Size Hail",
+        "QUARTER SIZE HAIL": "Quarter Size Hail",
+        "PING PONG BALL SIZE HAIL": "Ping Pong Ball Size Hail",
+        "NICKEL SIZE HAIL": "Nickel Size Hail",
+        "DOPPLER RADAR.": "Confirmed by Radar",
+        "DOPPLER RADAR AND AUTOMATED GAUGES.": "Confirmed by Radar and Gauges",
+        "FLASH FLOODING CAUSED BY THUNDERSTORMS.": "Caused by Thunderstorm",
+        "SOURCE...EMERGENCY MANAGEMENT.": "Confirmed by Emergency Management",
+        "FLASH FLOODING CAUSED BY HEAVY RAIN.": "Caused by heavy rain",
+        "SOURCE...LAW ENFORCEMENT REPORTED.": "Confirmed by Law Enforcement"
+    },
+    haultingConditions: [
+        { error: "not-authorized", message: "You do not have the proper credentials to access this service.", code: "credential-error"},
+        { error: "unreachable-host", message: "The host could not be reached. Please check your internet connection or the host address.", code: "xmpp-error" },
+        { error: "service-error", message: "An error occurred while connecting to the NOAA Weather Wire Service. Please try again later.", code: "xmpp-error" },
+        { error: "no-database-dir", message: "Database directory is not set. Please set the databaseDir in the metadata.", code: "no-database" },
+        { error: "rapid-reconnect", message: "The client is reconnecting too rapidly. Please wait a moment before trying again.", code: "xmpp-error" }
+    ]
+}
+module.exports.settings = { 
+    alertSettings: {
+        ugcPolygons: false,
+        onlyCap: false,
+        betterEvents: false,
+        filteredAlerts: [],
+    },
+    xmpp: {
+        reconnect: true,
+        reconnectInterval: 60,
+    },
+    cacheSettings: {
+        readCache: false,
+        maxMegabytes: 1,
+        cacheDir: false,
+    },
+    database: module.exports.packages.path.join(process.cwd(), 'shapefiles.db'), 
+};
+module.exports.cache = { 
+    lastStanza: new Date().getTime(), 
+    session: null, 
+    isConnected: false, 
+    attemptingReconnect: false, 
+    totalReconnects: 0 
+};
+
+module.exports.static.events = new module.exports.packages.events.EventEmitter();

package/index.js

@@ -0,0 +1,245 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| '_ ` _ \ / _ \/ __| '_ \| '_ \ / _ \ '__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: k3yomi@GitHub                        
+*/
+
+let loader = require(`./bootstrap.js`);
+
+class NoaaWeatherWireServiceCore { 
+    constructor(metadata={}) {
+        this.packages = loader.packages;
+        this.metadata = metadata;
+        loader.settings = { ...loader.settings, ...metadata };
+        process.on('uncaughtException', (error) => {
+            const hault = loader.definitions.haultingConditions.find(e => error.message.includes(e.error));
+            if (hault) { loader.static.events.emit(`onError`, {error: `${hault ? hault.message : error.message}`, code: hault.code}); return; }
+            loader.static.events.emit(`onError`, { error: error.stack || error.message || `An unknown error occurred`, code: `uncaught-exception` });
+        });
+        this.initializeDatabase([{ id: `C`, file: `USCounties` }, { id: `Z`, file: `ForecastZones` }, { id: `Z`, file: `FireZones` }, { id: `Z`, file: `OffShoreZones` }, { id: `Z`, file: `FireCounties` }, { id: `Z`, file: `Marine` }]);
+        
+        if (loader.settings.cacheSettings.readCache && loader.settings.cacheSettings.cacheDir) {
+            let target = `${loader.settings.cacheSettings.cacheDir}/nwws-raw-category-defaults-raw-vtec.bin`;
+            if (loader.packages.fs.existsSync(target)) {
+                this.forwardCustomStanza(loader.packages.fs.readFileSync(target, 'utf8'), { awipsid: 'alert', category: 'default', raw: true });
+            }
+        }
+        
+        setInterval(() => { 
+            if (loader.settings.cacheSettings.cacheDir) { this.garbageCollect(loader.settings.cacheSettings.maxMegabytes || 1); }
+            if (loader.settings.xmpp.reconnect) { this.isReconnectEligible(loader.settings.xmpp.reconnectInterval) }
+        }, 1 * 1000);
+    }
+
+    /**
+      * @function initializeDatabase
+      * @description Initializes the SQLite database and creates the shapefiles table if it doesn't exist.
+      * This also will read the shapefiles from the specified directory and insert them into the database.
+      *
+      * @param {Array} shapefiles - An array of shapefile objects containing `id` and `file` properties. 
+      */
+
+    initializeDatabase = async function(shapefiles = []) {
+        let { fs, path, sqlite3, shapefile } = loader.packages;
+        if (!fs.existsSync(loader.settings.database)) {
+            fs.writeFileSync(loader.settings.database, '', 'utf8');
+        }
+        let db = new sqlite3(loader.settings.database);
+        let tableExists = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='shapefiles'`).get();
+        if (!tableExists) {
+            db.prepare(`CREATE TABLE shapefiles (id TEXT PRIMARY KEY, location TEXT, geometry TEXT)`).run();
+            console.log(`\n\n[NOTICE] DO NOT CLOSE THIS PROJECT UNTIL THE SHAPEFILES ARE DONE COMPLETING!\n` +
+                `\t THIS COULD TAKE A WHILE DEPENDING ON THE SPEED OF YOUR STORAGE!!\n` +
+                `\t IF YOU CLOSE YOUR PROJECT, THE SHAPEFILES WILL NOT BE CREATED AND YOU WILL NEED TO DELETE ${loader.settings.database} AND RESTART TO CREATE THEM AGAIN!\n\n`);
+            for (let shapefileEntry of shapefiles) {
+                let { file, id: type } = shapefileEntry;
+                let filePath = path.join(__dirname, 'shapefiles', file);
+                let { features } = await shapefile.read(filePath, filePath);
+                console.log(`Creating ${file} shapefile...`);
+                for (let feature of features) {
+                    let { properties, geometry } = feature;
+                    let id, location;
+                    if (properties.FIPS) {
+                        id = `${properties.STATE}${type}${properties.FIPS.substring(2)}`; location = `${properties.COUNTYNAME}, ${properties.STATE}`;
+                    } else if (properties.STATE) {
+                        id = `${properties.STATE}${type}${properties.ZONE}`; location = `${properties.NAME}, ${properties.STATE}`;
+                    } else if (properties.FULLSTAID) {
+                        id = `${properties.ST}${type}-NoZone`; location = `${properties.NAME}, ${properties.STATE}`;
+                    } else {
+                        id = properties.ID; location = properties.NAME;
+                    }
+                    await db.prepare(`INSERT OR REPLACE INTO shapefiles (id, location, geometry) VALUES (?, ?, ?)`).run(id, location, JSON.stringify(geometry));
+                }
+            }
+            console.log(`Shapefiles created successfully!`);
+        }
+        loader.static.db = db;
+        this.initializeSession();
+    }
+
+    /**
+      * @function initializeClient
+      * @description Authenticates the XMPP session for NOAA Weather Wire Service with the provided metadata.
+      *
+      * @param {Object} metadata - The metadata object containing authentication details.
+      * @param {string} metadata.username - The username for the XMPP session.
+      * @param {string} metadata.password - The password for the XMPP session.
+      * @param {string} [metadata.display] - The display name for the XMPP session (optional).
+      */
+
+    initializeClient = function(metadata = {}) { 
+        if (loader.settings.database == null) { throw new Error(`no-database-dir`); }
+        loader.static.session = loader.packages.xmpp.client({ 
+            service: `xmpp://nwws-oi.weather.gov`, 
+            domain: `nwws-oi.weather.gov`, 
+            username: metadata.username || ``,
+            password: metadata.password || ``,
+        })
+    }
+
+    /**
+      * @function initializeSession
+      * @description Creates a new XMPP session for NOAA Weather Wire Service and sets up event listeners for connection and stanza handling.
+      * Also handles reconnection logic if the session is disconnected.
+      */
+
+    initializeSession = function() { 
+        if (this.metadata.authentication.display == undefined) this.metadata.authentication.display = this.metadata.authentication.username || ``;
+        this.initializeClient({ username: this.metadata.authentication.username, password: this.metadata.authentication.password, display: this.metadata.authentication.display });
+        loader.static.session.on(`online`, async () => {
+            if (loader.static.lastConnect && (new Date().getTime() - loader.static.lastConnect) < 10 * 1000) {
+                setTimeout(async () => {
+                    await loader.static.session.stop().catch(() => {});
+                    await loader.static.session.start().catch(() => {});
+                }, 2 * 1000);
+                throw new Error(`rapid-reconnect`);
+            }
+            loader.static.lastConnect = new Date().getTime();
+            loader.cache.isConnected = true;
+            loader.static.session.send(loader.packages.xmpp.xml('presence', { to: `nwws@conference.nwws-oi.weather.gov/${this.metadata.authentication.display}`, xmlns: 'http://jabber.org/protocol/muc' }))
+            loader.static.session.send(loader.packages.xmpp.xml('presence', { to: `nwws@conference.nwws-oi.weather.gov`, type: 'available' }))
+            loader.static.events.emit(`onConnection`, this.metadata.authentication.display);
+            if (loader.cache.attemptingReconnect) {
+                setTimeout(() => { loader.cache.attemptingReconnect = false; }, 15 * 1000);
+            }
+        })
+        loader.static.session.on(`offline`, () => {
+            loader.static.session.stop().catch(() => {});
+            loader.cache.isConnected = false;
+            throw new Error(`unreachable-host`);
+        })
+        loader.static.session.on(`error`, async (error) => {
+            throw new Error(error.message || `service-error`);
+        })
+        loader.static.session.on(`stanza`, (stanza) => {
+            loader.cache.lastStanza = new Date().getTime();
+            if (stanza.is('message')) {
+                let validateStanza = loader.packages.mStanza.newStanza(stanza)
+                if (validateStanza.ignore 
+                    || (validateStanza.isCap && !loader.settings.alertSettings.onlyCap) 
+                    || (!validateStanza.isCap && loader.settings.alertSettings.onlyCap) 
+                    || (validateStanza.isCap && !validateStanza.hasCapArea)) return;
+                loader.packages.mStanza.createNewAlert(validateStanza);
+                loader.static.events.emit(`onMessage`, validateStanza);
+            }
+            if (stanza.is('presence') && stanza.attrs.from && stanza.attrs.from.startsWith('nwws@conference.nwws-oi.weather.gov/')) {
+                let occupant = stanza.attrs.from.split('/').slice(1).join('/');
+                loader.static.events.emit('onOccupant', { occupant, type: stanza.attrs.type === 'unavailable' ? 'unavailable' : 'available' });
+            }
+        })
+        loader.static.session.start();
+    }
+
+    /**
+      * @function isReconnectEligible
+      * @description Checks if the session is eligible for reconnection based on the last stanza time
+      * and attempts to reconnect if necessary.
+      * 
+      * @param {number} [minSeconds=60] - The minimum number of seconds since the last stanza to consider reconnection.
+      */
+
+    isReconnectEligible = async function(minSeconds=60) {
+        if (loader.cache.isConnected && loader.static.session) {
+            let lastStanza = new Date().getTime() - loader.cache.lastStanza;
+            if (lastStanza > minSeconds * 1000) {
+                if (!loader.cache.attemptingReconnect) {
+                    loader.cache.attemptingReconnect = true;
+                    loader.cache.isConnected = false;
+                    loader.cache.totalReconnects += 1;
+                    loader.static.events.emit(`onReconnect`, { reconnects: loader.cache.totalReconnects, lastStanza: lastStanza / 1000, lastName: this.metadata.authentication.display});
+                    await loader.static.session.stop().catch(() => {});
+                    await loader.static.session.start().catch(() => {});
+                } 
+            }
+        }
+        return { message: `Session is not connected or session is not available`, isConnected: loader.cache.isConnected, session: loader.static.session };
+    }
+
+    /**
+      * @function setDisplayName
+      * @description Sets the display name for the XMPP session.
+      * 
+      * @param {string} displayName - The display name to set for the XMPP session.
+      */
+
+    setDisplayName = async function(displayName) {
+        this.metadata.authentication.display = displayName;
+    }
+
+    /**
+      * @function forwardCustomStanza
+      * @description Forwards a custom stanza message to the appropriate event handler.
+      * 
+      * @param {string} message - The custom message to forward.
+      * @param {object} attributes - The attributes of the custom message.
+      */
+
+    forwardCustomStanza = function(stanza, attrs) {
+        let validateStanza = loader.packages.mStanza.newStanza(stanza, { stanza, attrs });
+        loader.packages.mStanza.createNewAlert(validateStanza);
+    }
+
+    /**
+      * @function garbageCollect
+      * @description Deletes files in the database directory that exceed a specified size limit.
+      *
+      * @param {number} [maxMegabytes=1] - The maximum size in megabytes for files to keep. Files larger than this will be deleted.
+      */
+
+    garbageCollect = function(maxMegabytes=1) {
+        if (!loader.settings.cacheSettings.cacheDir) return;
+        let maxBytes = maxMegabytes * 1024 * 1024, directory = loader.settings.cacheSettings.cacheDir
+        let stackFiles = [directory], files = []
+        while (stackFiles.length) {
+            let currentDirectory = stackFiles.pop();
+            loader.packages.fs.readdirSync(currentDirectory).forEach(file => {
+                let filePath = loader.packages.path.join(currentDirectory, file);
+                loader.packages.fs.statSync(filePath).isDirectory() ? stackFiles.push(filePath) : files.push({ file: filePath, size: loader.packages.fs.statSync(filePath).size });
+            });
+        }
+        if (!files.length) return;
+        files.forEach(({ file, size }) => { if (size > maxBytes) { loader.packages.fs.unlinkSync(file); } });
+        return;
+    }
+
+    /**
+      * @function onEvent
+      * @description Registers an event listener for the specified event.
+      * @param {string} event - The name of the event to listen for.
+      * @param {function} listener - The callback function to execute when the event is emitted.
+      */
+
+    onEvent = function(event, listener) {
+        loader.static.events.on(event, listener)
+        return () => { loader.static.events.off(event, listener); };
+    }
+}
+
+module.exports = NoaaWeatherWireServiceCore;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "atmosx-nwws-parser",
+  "version": "1.0.16",
+  "description": "NOAA Weather Wire Parser",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/K3YOMI/atmosx-nwws-parser.git"
+  },
+  "keywords": [
+    "NWWS",
+    "NOAA Weather Wire Service"
+  ],
+  "author": "K3YOMI, Starflight",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/K3YOMI/atmosx-nwws-parser/issues"
+  },
+  "homepage": "https://github.com/K3YOMI/atmosx-nwws-parser#readme",
+  "dependencies": {
+    "@xmpp/client": "^0.7.3",
+    "better-sqlite3": "^11.10.0",
+    "shapefile": "^0.6.6",
+    "xml2js": "^0.6.2"
+  }
+}

package/src/events.js

@@ -0,0 +1,322 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| '_ ` _ \ / _ \/ __| '_ \| '_ \ / _ \ '__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: k3yomi@GitHub                        
+*/
+
+let loader = require(`../bootstrap.js`);
+
+class NoaaWeatherWireServiceEvents { 
+
+    /**
+      * @function onEnhanced
+      * @description Enhances the event details based on the properties of the event.
+      * 
+      * @param {object} event - The event object containing properties to enhance.
+      */
+
+    onEnhanced = function(event) {
+        let tags = [`No tags found`];
+        let eventName = event.properties.event
+        let dmgTheat = event.properties.parameters.thunderstormDamageThreat?.[0] || event.properties.parameters.tornadoDamageThreat?.[0] || `N/A`;
+        let description = event.properties.description.toLowerCase() || `No description available.`;
+        if (description.includes(`flash flood emergency`) && eventName == `Flash Flood Warning`) eventName = `Flash Flood Emergency`;
+        if (description.includes(`particularly dangerous situation`) && eventName == `Tornado Warning` && dmgTheat == `CONSIDERABLE`) eventName = `Particularly Dangerous Situation Tornado Warning`;
+        if (description.includes(`particularly dangerous situation`) && eventName == `Tornado Watch`) eventName = `Particularly Dangerous Situation Tornado Watch`;
+        if (description.includes(`extremely dangerous situation`) && eventName == `Severe Thunderstorm Warning`) eventName = `Extremely Dangerous Situation Severe Thunderstorm Warning`;
+        if (description.includes(`tornado emergency`) && eventName == `Tornado Warning` && dmgTheat == `CATASTROPHIC`) eventName = `Tornado Emergency`;
+        
+        if (eventName == `Tornado Warning`) {
+            eventName = `Radar Indicated Tornado Warning`;
+            if (event.properties.parameters.tornadoDetection == `RADAR INDICATED`) eventName = `Radar Indicated Tornado Warning`;
+            if (event.properties.parameters.tornadoDetection == `OBSERVED`) eventName = `Confirmed Tornado Warning`; 
+        }
+        if (eventName == `Severe Thunderstorm Warning`) {
+            if (dmgTheat == `CONSIDERABLE`) eventName = `Considerable Severe Thunderstorm Warning`;
+            if (dmgTheat == `DESTRUCTIVE`) eventName = `Destructive Severe Thunderstorm Warning`;
+        }
+        if (eventName == `Flash Flood Warning`) {
+            if (dmgTheat == `CONSIDERABLE`) eventName = `Considerable Flash Flood Warning`;
+        }
+        for (let [key, value] of Object.entries(loader.definitions.tags)) {
+            if (event.properties.description.toLowerCase().includes(key.toLowerCase())) {
+                tags = tags.includes(`No tags found`) ? [] : tags;
+                if (!tags.includes(value)) tags.push(value);
+            }
+        }
+        return { event: eventName, tags: tags };
+    }
+
+    /**
+      * @function onFinished
+      * @description onFinishedes the alerts and emits an event with enhanced event details.
+      * 
+      * @param {Array} alerts - An array of alert objects to be onFinisheded.
+      */ 
+
+    onFinished = function(alerts) {
+        if (loader.settings.alertSettings.betterEvents) { 
+            for (let i = 0; i < alerts.length; i++) { 
+                let {event, tags} = this.onEnhanced(alerts[i]);
+                alerts[i].properties.event = event;
+                alerts[i].properties.tags = tags;
+            }
+        }
+        if (loader.settings.alertSettings.filteredAlerts && loader.settings.alertSettings.filteredAlerts.length > 0) {
+            alerts = alerts.filter(alert => loader.settings.alertSettings.filteredAlerts.includes(alert.properties.event));
+        }
+        if (alerts.length === 0) { return; }
+        loader.static.events.emit(`onAlert`, alerts);
+    }
+
+    /**
+      * @function newCapEvent
+      * @description Creates a new CAP event from the provided stanza.
+      * 
+      * @param {object} stanza - The stanza object containing message and attributes.
+      */
+    
+    newCapEvent = async function(stanza) { 
+        let message = stanza.message.substring(stanza.message.indexOf(`<?xml version="1.0"`), stanza.message.length);
+        let data = loader.packages.xml2js.Parser();
+        let result = await data.parseStringPromise(message);
+        let tracking = result.alert.info[0].parameter.find(p => p.valueName[0] == "VTEC")?.value[0] || "N/A";
+        let action = "N/A";
+        if (tracking !== "N/A") {
+            let splitVTEC = tracking.split(".");
+            tracking = `${splitVTEC[2]}-${splitVTEC[3]}-${splitVTEC[4]}-${splitVTEC[5]}`;
+            action = loader.definitions.status[splitVTEC[1]];
+        } else {
+            action = result.alert.msgType[0];
+            tracking = `${result.alert.info[0].parameter.find(p => p.valueName[0] == "WMOidentifier")?.value[0]}-${result.alert.info[0].area[0].geocode.filter(g => g.valueName[0] == "UGC").map(g => g.value[0]).join("-")}`;
+        }
+        let alert = {
+            id: `Wire-${tracking}`,
+            tracking: tracking,
+            action: action,
+            history: [{ description: result.alert.info[0].description[0], action: action, issued: new Date(stanza.attributes.issue) }],
+            properties: {
+                areaDesc: result.alert.info[0].area[0].areaDesc[0],
+                expires: new Date(result.alert.info[0].expires[0]),
+                sent: new Date(result.alert.sent[0]),
+                messageType: action,
+                event: result.alert.info[0].event[0],
+                sender: result.alert.sender[0],
+                senderName: result.alert.info[0].senderName[0],
+                description: result.alert.info[0].description[0],
+                geocode: { UGC: result.alert.info[0].area[0].geocode.filter(g => g.valueName[0] == "UGC").map(g => g.value[0]) },
+                parameters: {
+                    WMOidentifier: [result.alert.info[0].parameter.find(p => p.valueName[0] == "WMOidentifier")?.value[0] || "N/A"],
+                    tornadoDetection: result.alert.info[0].parameter.find(p => p.valueName[0] == "tornadoDetection")?.value[0] || result.alert.info[0].parameter.find(p => p.valueName[0] == "waterspoutDetection")?.value[0] || "N/A",
+                    maxHailSize: result.alert.info[0].parameter.find(p => p.valueName[0] == "maxHailSize")?.value[0] || "N/A",
+                    maxWindGust: result.alert.info[0].parameter.find(p => p.valueName[0] == "maxWindGust")?.value[0] || "N/A",
+                    thunderstormDamageThreat: [result.alert.info[0].parameter.find(p => p.valueName[0] == "thunderstormDamageThreat")?.value[0] || result.alert.info[0].parameter.find(p => p.valueName[0] == "tornadoDamageThreat")?.value[0] || "N/A"],
+                },
+            },
+        };
+        if (result.alert.info[0].area[0].polygon) {
+            alert.geometry = { type: "Polygon", coordinates: [result.alert.info[0].area[0].polygon[0].split(" ").map(coord => { let [lat, lon] = coord.split(",").map(parseFloat); return [lon, lat]; })] };
+        }
+        this.onFinished([alert]);
+    }
+
+    /**
+      * @function newRawProductEvent
+      * @description Creates a new raw product event from the provided stanza.
+      *
+      * @param {object} stanza - The stanza object containing message and attributes.
+      */
+
+    newRawProductEvent = async function(stanza) { 
+        let message = stanza.message.split(/(?=\$\$)/g).map(msg => msg.trim());
+        let defaultWMO = stanza.message.match(new RegExp(loader.definitions.expressions.wmo, 'gimu'));
+        let alerts = []
+        for (let msg of message) {
+            let startTime = new Date().getTime();
+            let mVtec = await loader.packages.mVtec.getVTEC(msg, stanza.attributes);
+            let mUgc = await loader.packages.mUGC.getUGC(msg);
+            if (mVtec && mUgc) {
+                for (let i = 0; i < mVtec.length; i++) {
+                    let vtec = mVtec[i];
+                    if (vtec.wmo) defaultWMO = vtec.wmo;
+                    let getTornado = loader.packages.mText.getString(msg, `TORNADO...`) || loader.packages.mText.getString(msg, `WATERSPOUT...`)
+                    let getHail = loader.packages.mText.getString(msg, `MAX HAIL SIZE...`, [`IN`]) || loader.packages.mText.getString(msg, `HAIL...`, [`IN`]);
+                    let getGusts = loader.packages.mText.getString(msg, `MAX WIND GUST...`) || loader.packages.mText.getString(msg, `WIND...`);
+                    let getThreat = loader.packages.mText.getString(msg, `DAMAGE THREAT...`);
+                    let senderOffice = loader.packages.mText.getOffice(msg) || vtec.tracking.split(`-`)[0];
+                    let getCoordinates = loader.packages.mText.getPolygonCoordinates(msg);
+                    let getDescription = loader.packages.mText.getCleanDescription(msg, vtec);
+                    let alert = { 
+                        hitch: `${new Date().getTime() - startTime}ms`,
+                        id: `Wire-${vtec.tracking}`,
+                        tracking: vtec.tracking,
+                        action: vtec.status,
+                        history: [{description: getDescription, action: vtec.status, issued: new Date(vtec.issued)}],
+                        properties: {
+                            areaDesc: mUgc.locations.join(`; `) || `N/A`,
+                            expires: new Date(vtec.expires) == `Invalid Date` ? new Date(new Date().getTime() + 999999 * 60 * 60 * 1000) : new Date(vtec.expires),
+                            sent: new Date(vtec.issued),
+                            messageType: vtec.status, 
+                            event: vtec.event || `Unknown Event`,
+                            sender: senderOffice,
+                            senderName: `${senderOffice}`,
+                            description: getDescription,
+                            geocode: { 
+                                UGC: mUgc.zones,
+                            },
+                            parameters: {
+                                WMOidentifier: vtec.wmo?.[0] ? [vtec.wmo[0]] : defaultWMO?.[0] ? [defaultWMO[0]] : [`N/A`],
+                                tornadoDetection: getTornado || `N/A`,
+                                maxHailSize: getHail || `N/A`,
+                                maxWindGust: getGusts || `N/A`,
+                                thunderstormDamageThreat: [getThreat || `N/A`],
+                            },
+                        },
+                        geometry: { type: `Polygon`, coordinates: [getCoordinates] }
+                    }
+                    if (loader.settings.alertSettings.ugcPolygons) {
+                        let coordinates = await loader.packages.mUGC.getCoordinates(mUgc.zones);
+                        if (coordinates.length > 0) {
+                            alert.geometry.coordinates = [coordinates];
+                        }
+                    }
+                    alerts.push(alert);
+                }
+            }
+        }
+        this.onFinished(alerts);
+    }
+
+    /**
+      * @function newSpecialEvent
+      * @description Creates a new special weather statement event from the provided stanza.
+      * 
+      * @param {object} stanza - The stanza object containing message and attributes.
+      */
+
+    newSpecialEvent = async function(stanza) { 
+        let message = stanza.message.split(/(?=\$\$)/g).map(msg => msg.trim());
+        let defaultWMO = stanza.message.match(new RegExp(loader.definitions.expressions.wmo, 'gimu'));
+        let alerts = [];
+        for (let msg of message) {
+            let startTime = new Date().getTime();
+            let mUgc = await loader.packages.mUGC.getUGC(msg);
+            if (mUgc) {
+                let getTornado = loader.packages.mText.getString(msg, `TORNADO...`) || loader.packages.mText.getString(msg, `WATERSPOUT...`)
+                let getHail = loader.packages.mText.getString(msg, `MAX HAIL SIZE...`, [`IN`]) || loader.packages.mText.getString(msg, `HAIL...`, [`IN`]);
+                let getGusts = loader.packages.mText.getString(msg, `MAX WIND GUST...`) || loader.packages.mText.getString(msg, `WIND...`);
+                let getThreat = loader.packages.mText.getString(msg, `DAMAGE THREAT...`);
+                let senderOffice = loader.packages.mText.getOffice(msg) || `NWS`;
+                let getCoordinates = loader.packages.mText.getPolygonCoordinates(msg);
+                let getDescription = loader.packages.mText.getCleanDescription(msg, null);
+                let alert = { 
+                    hitch: `${new Date().getTime() - startTime}ms`,
+                    id: `Wire-${defaultWMO ? defaultWMO[0] : `N/A`}-${mUgc.zones.join(`-`)}`,
+                    tracking: `${defaultWMO ? defaultWMO[0] : `N/A`}-${mUgc.zones.join(`-`)}`,
+                    action: `Issued`,
+                    history: [{description: getDescription, action: `Issued`, issued: new Date(stanza.attributes.issue)}],
+                    properties: {
+                        areaDesc: mUgc.locations.join(`; `) || `N/A`,
+                        expires: new Date(new Date().getTime() + 1 * 60 * 60 * 1000),
+                        sent: new Date(stanza.attributes.issue),
+                        messageType: `Issued`,
+                        event: `Special Weather Statement`,
+                        sender: senderOffice,
+                        senderName: `${senderOffice}`,
+                        description: getDescription,
+                        geocode: { 
+                            UGC: mUgc.zones,
+                        },
+                        parameters: {
+                            WMOidentifier: defaultWMO?.[0] ? [defaultWMO[0]] : [`N/A`],
+                            tornadoDetection: getTornado || `N/A`,
+                            maxHailSize: getHail || `N/A`,
+                            maxWindGust: getGusts || `N/A`,
+                            thunderstormDamageThreat: [getThreat || `N/A`],
+                        },
+                    },
+                    geometry: { type: `Polygon`, coordinates: [getCoordinates] }
+                }
+                if (loader.settings.alertSettings.ugcPolygons) {
+                    let coordinates = await loader.packages.mUGC.getCoordinates(mUgc .zones);
+                    if (coordinates.length > 0) {
+                        alert.geometry.coordinates = [coordinates];
+                    }
+                }
+                alerts.push(alert);
+            }
+        }
+        this.onFinished(alerts);
+    }
+
+    /**
+      * @function newMesoscaleDiscussion
+      * @description Creates a new mesoscale discussion event from the provided stanza.
+      *
+      * @param {object} stanza - The stanza object containing message and attributes.
+      */
+
+    newMesoscaleDiscussion = async function(stanza) {
+        let message = stanza.message.split(/(?=\$\$)/g).map(msg => msg.trim());
+        let defaultWMO = stanza.message.match(new RegExp(loader.definitions.expressions.wmo, 'gimu'));
+        for (let msg of message) {
+            let startTime = new Date().getTime();
+            let mUgc = await loader.packages.mUGC.getUGC(msg);
+            if (mUgc) { 
+                let senderOffice = loader.packages.mText.getOffice(msg) || `NWS`;
+                let getDescription = loader.packages.mText.getCleanDescription(msg, null);
+                let tornadoIntensityProbability = loader.packages.mText.getString(msg, `MOST PROBABLE PEAK TORNADO INTENSITY...`)
+                let windIntensityProbability = loader.packages.mText.getString(msg, `MOST PROBABLE PEAK WIND GUST...`)
+                let hailIntensityProbability = loader.packages.mText.getString(msg, `MOST PROBABLE PEAK HAIL SIZE...`)
+                let alert = { 
+                    hitch: `${new Date().getTime() - startTime}ms`,
+                    id: `Wire-${defaultWMO ? defaultWMO[0] : `N/A`}-${mUgc.zones.join(`-`)}`,
+                    tracking: `${defaultWMO ? defaultWMO[0] : `N/A`}-${mUgc.zones.join(`-`)}`,
+                    action: `Issued`,
+                    history: [],
+                    properties: {
+                        areaDesc: mUgc.locations.join(`; `) || `N/A`,
+                        expires: new Date(new Date().getTime() + 1 * 60 * 60 * 1000),
+                        sent: new Date(stanza.attributes.issue),
+                        messageType: `Issued`,
+                        event: `Mesoscale Discussion`,
+                        sender: senderOffice,
+                        senderName: `${senderOffice}`,
+                        description: getDescription,
+                        geocode: { 
+                            UGC: mUgc.zones,
+                        },
+                        parameters: {
+                            WMOidentifier: defaultWMO?.[0] ? [defaultWMO[0]] : [`N/A`],
+                            tornadoIntensityProbability: tornadoIntensityProbability || `N/A`,
+                            hailIntensityProbability: hailIntensityProbability || `N/A`,
+                            windIntensityProbability: windIntensityProbability || `N/A`,
+                        },
+                    },
+                }
+                loader.static.events.emit(`onMesoscaleDiscussion`, alert);
+            }
+        }
+    }
+
+    /**
+      * @function newStormReport
+      * @description Creates a new storm report event from the provided stanza.
+      * 
+      * @param {object} stanza - The stanza object containing message and attributes.
+      */ 
+
+    newStormReport = async function(stanza) {
+        loader.static.events.emit(`onStormReport`, loader.packages.mText.getCleanDescription(stanza.message, null));
+    }
+
+}
+
+module.exports = new NoaaWeatherWireServiceEvents();

package/src/stanza.js

@@ -0,0 +1,103 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| '_ ` _ \ / _ \/ __| '_ \| '_ \ / _ \ '__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: k3yomi@GitHub                        
+*/
+
+let loader = require(`../bootstrap.js`);
+
+class NoaaWeatherWireServiceStanza { 
+
+    /**
+      * @function newStanza
+      * @description Creates a new alert stanza from the provided message and attributes.
+      * 
+      * @param {object} stanza - The stanza object containing message and attributes.
+      * @param {boolean} isDebug - Optional debug information.
+      */
+
+    newStanza = function(stanza, isDebug=false) {
+        try {
+            if (isDebug != false) {
+                let message = isDebug.stanza
+                let attributes = isDebug.attrs;
+                let isCap = message.includes(`<?xml version="1.0"`)
+                let hasCapArea = message.includes(`<areaDesc>`);
+                let hasVtec = message.match(loader.definitions.expressions.vtec) != null;
+                let getId = this.getAwipsType(attributes)
+                return { message: message, attributes: attributes, isCap: isCap, hasCapArea: hasCapArea, hasVtec: hasVtec, id: getId, ignore: false } 
+            }
+            if (stanza.is(`message`)) { 
+                let cb = stanza.getChild(`x`);
+                if (cb?.children) {
+                    let message = cb.children[0];
+                    let attributes = cb.attrs;
+                    let isCap = message.includes(`<?xml version="1.0"`)
+                    let hasCapArea = message.includes(`<areaDesc>`);
+                    let hasVtec = message.match(loader.definitions.expressions.vtec) != null;
+                    let getId = this.getAwipsType(attributes)
+                    this.saveCache(message, attributes, getId, isCap, hasVtec);
+                    return { message: message, attributes: attributes, isCap: isCap, hasCapArea: hasCapArea, hasVtec: hasVtec, id: getId, ignore: false }
+                }
+            }
+            return { message: null, arrtributes: null, isCap: null, hasCapArea: null, hasVtec: null, id: null, ignore: true}
+        } catch (error) {
+            console.error(`[!] Error in newStanza: ${error.stack}`);
+            return { message: null, arrtributes: null, isCap: null, hasCapArea: null, hasVtec: null, id: null, ignore: true }
+        }
+    }
+
+    /**
+      * @function getAwipsType
+      * @description Determines the AWIPS type based on the attributes of the message.
+      * 
+      * @param {object} attributes - The attributes of the message.
+      */
+
+    getAwipsType = function(attributes) {
+        if (!attributes || !attributes.awipsid) return `unknown`;
+        for (let [prefix, type] of Object.entries(loader.definitions.awips)) { if (attributes.awipsid.startsWith(prefix)) return type; }
+        return `default`;
+    }
+
+    /**
+      * @function createNewAlert
+      * @description Creates a new alert based on the stanza type and its properties.
+      * 
+      * @param {object} stanza - The stanza object containing message and attributes.
+      */
+
+    createNewAlert = async function(stanza) { 
+        let type = stanza.id
+        let cap = stanza.isCap;
+        let vtec = stanza.hasVtec; 
+        if (type == `default` && vtec && !cap) { loader.packages.mEvents.newRawProductEvent(stanza); return; }
+        if (type == `default` && vtec && cap) { loader.packages.mEvents.newCapEvent(stanza); return; }
+        if (type == `special-weather-statement`) { loader.packages.mEvents.newSpecialEvent(stanza); return; }
+        if (type == `mesoscale-discussion`) { loader.packages.mEvents.newMesoscaleDiscussion(stanza); return; }
+        if (type == `local-storm-report`) { loader.packages.mEvents.newStormReport(stanza); return; }
+    }
+
+    /**
+      * @function saveCache
+      * @description Saves the raw message to a cache file for later reference.
+      * 
+      * @param {string} message - The message to save.
+      * @param {string} type - The type of the message (e.g., alert, warning).
+      * @param {boolean} isCap - Indicates if the message is in CAP format.
+      */
+
+    saveCache = function(message, attributes, type, isCap, isVtec) {
+        if (!loader.settings.cacheSettings.cacheDir) return;
+        loader.packages.fs.appendFileSync(`${loader.settings.cacheSettings.cacheDir}/nwws-raw-category-${type}s-${isCap ? 'cap' : 'raw'}${isVtec ? '-vtec' : ''}.bin`, `=================================================\n${new Date().toISOString().replace(/[:.]/g, '-')}\n\n[${JSON.stringify(attributes)}]\n=================================================\n\n${message}\n\n`, `utf8`);
+    }
+}
+
+module.exports = new NoaaWeatherWireServiceStanza();

package/src/text.js

@@ -0,0 +1,108 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| '_ ` _ \ / _ \/ __| '_ \| '_ \ / _ \ '__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: k3yomi@GitHub                        
+*/
+
+let loader = require(`../bootstrap.js`);
+
+class NoaaWeatherWireServiceText { 
+
+    /**
+      * @function getString
+      * @description Extracts a specific string from a message, removing specified substrings.
+      * 
+      * @param {string} message - The message to search within.
+      * @param {string} string - The string to extract.
+      * @param {Array} removeIfExists - An array of substrings to remove from the result.
+      */
+    
+    getString = function(message, string, removeIfExists=[]) {
+        let lines = message.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].includes(string)) {
+                let start = lines[i].indexOf(string) + string.length, result = lines[i].substring(start).trim();
+                for (let j = 0; j < removeIfExists.length; j++) result = result.replace(removeIfExists[j], '');
+                return result.replace(string, '').replace(/^\s+|\s+$/g, '').replace('<', '').trim();
+            }
+        }
+        return null;
+    }
+   
+    /**
+      * @function getOffice
+      * @description Extracts the office information from a message.
+      * 
+      * @param {string} message - The message to search within.
+      */
+
+    getOffice = function(message) { 
+        return this.getString(message, `National Weather Service`) || this.getString(message, `NWS STORM PREDICTION CENTER `) || null;
+    }
+
+    /**
+      * @function getPolygonCoordinates
+      * @description Extracts polygon coordinates from a message.
+      * 
+      * @param {string} message - The message containing polygon coordinates.
+      */
+
+    getPolygonCoordinates = function(message) {
+        let coordinates = [], latLon = message.match(/LAT\.{3}LON\s+([\d\s]+)/i);
+        if (latLon && latLon[1]) {
+            let coordStrings = latLon[1].replace(/\n/g, ' ').trim().split(/\s+/);
+            for (let i = 0; i < coordStrings.length - 1; i += 2) {
+                let lat = parseFloat(coordStrings[i]) / 100, long = -1 * (parseFloat(coordStrings[i + 1]) / 100);
+                if (!isNaN(lat) && !isNaN(long)) coordinates.push([long, lat]);
+            }
+            if (coordinates.length > 2) coordinates.push(coordinates[0]);
+        }
+        return coordinates;
+    }
+
+    /**
+      * @function getCleanDescription
+      * @description Cleans the description of a message by removing unnecessary parts.
+      * 
+      * @param {string} message - The message to clean.
+      * @param {object} vtec - The VTEC object containing raw VTEC information.
+      */
+
+    getCleanDescription = function(message, vtec) { 
+        let dateLineMatches = [...message.matchAll(/\d{3,4}\s*(AM|PM)?\s*[A-Z]{2,4}\s+[A-Z]{3,}\s+[A-Z]{3,}\s+\d{1,2}\s+\d{4}/gim)];
+        if (dateLineMatches.length) {
+            let dateLineMatch = dateLineMatches[dateLineMatches.length - 1];
+            let nwsStart = message.lastIndexOf(dateLineMatch[0]);
+            if (nwsStart !== -1) {
+                let latStart = message.indexOf("&&", nwsStart);
+                message = latStart !== -1 ? message.substring(nwsStart + dateLineMatch[0].length, latStart).trim() : message.substring(nwsStart + dateLineMatch[0].length).trim();
+                if (message.startsWith('/')) message = message.substring(1).trim();
+                if (vtec && vtec.raw && message.includes(vtec.raw)) {
+                    let vtecIndex = message.indexOf(vtec.raw);
+                    if (vtecIndex !== -1) {
+                        message = message.substring(vtecIndex + vtec.raw.length).trim();
+                        if (message.startsWith('/')) message = message.substring(1).trim();
+                    }
+                }
+            }
+        } else {
+            let vtecStart = message.indexOf(vtec.raw);
+            if (vtecStart !== -1) {
+                let afterVtec = message.substring(vtecStart + vtec.raw.length);
+                if (afterVtec.startsWith('/')) afterVtec = afterVtec.substring(1);
+                let latStart = afterVtec.indexOf("&&");
+                message = latStart !== -1 ? afterVtec.substring(0, latStart).trim() : afterVtec.trim();
+            }
+        }
+        return message
+    }
+}
+
+module.exports = new NoaaWeatherWireServiceText();

package/src/ugc.js

@@ -0,0 +1,115 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| '_ ` _ \ / _ \/ __| '_ \| '_ \ / _ \ '__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: k3yomi@GitHub                        
+*/
+
+let loader = require(`../bootstrap.js`);
+
+class NoaaWeatherWireServiceUGC { 
+
+    /**
+      * @function getUGC
+      * @description Extracts UGC (FIPS) information from a message.
+      * 
+      * @param {string} message - The message containing UGC information.
+      */
+    
+    getUGC = async function(message) {
+        let header = this.getHeader(message);
+        let zones = this.getZones(header);
+        let locations = await this.getLocations(zones)
+        let ugc = zones.length > 0 ? { zones, locations} : null;
+        return ugc
+    }
+
+    /**
+      * @function getHeader
+      * @description Extracts the UGC header from the message.
+      * 
+      * @param {string} message - The message containing the UGC header.
+      */
+
+    getHeader = function(message) {
+        let start = message.search(new RegExp(loader.definitions.expressions.ugc1, "gimu"));
+        let end = message.substring(start).search(new RegExp(loader.definitions.expressions.ugc2, "gimu"));
+        let full = message.substring(start, start + end).replace(/\s+/g, '').slice(0, -1);
+        return full;
+    }
+
+    /**
+      * @function getLocations
+      * @description Retrieves the locations associated with the UGC zones.
+      * If a location is not found in the database, the zone ID is returned.
+      * 
+      * @param {Array} zones - The UGC zones to retrieve locations for.
+      */
+
+    getLocations = async function(zones) {
+        let locations = [];
+        for (let i = 0; i < zones.length; i++) {
+            let id = zones[i].trim();
+            let located = await loader.static.db.prepare(`SELECT location FROM shapefiles WHERE id = ?`).get(id);
+            located != undefined ? locations.push(located.location) : locations.push(id);
+        }     
+        return Array.from(new Set(locations));
+    }
+
+    /**
+      * @function getCoordinates
+      * @description Retrieves the coordinates for the UGC zones.
+      * 
+      * @param {Array} zones - The UGC zones to retrieve coordinates for.
+      */
+
+    getCoordinates = async function(zones) {
+        let coordinates = [];
+        for (let i = 0; i < zones.length; i++) {
+            let id = zones[i].trim();
+            let located = await loader.static.db.prepare(`SELECT geometry FROM shapefiles WHERE id = ?`).get(id);
+            if (located != undefined) {
+                let geometry = JSON.parse(located.geometry);
+                if (geometry?.type == 'Polygon') {
+                    coordinates.push(...geometry.coordinates[0].map(coord => [coord[0], coord[1]]));
+                    break;
+                }
+            }
+        }
+        return coordinates;
+    }
+
+    /**
+      * @function getZones
+      * @description Parses the UGC header to extract zone IDs.
+      * 
+      * @param {string} header - The UGC header string.
+      */
+
+    getZones = function(header) {
+        let ugcSplit = header.split('-'), zones = [], state = ugcSplit[0].substring(0, 2), format = ugcSplit[0].substring(2, 3);
+        for (let i = 0; i < ugcSplit.length; i++) {
+            if (/^[A-Z]/.test(ugcSplit[i])) {
+                state = ugcSplit[i].substring(0, 2);
+                if (ugcSplit[i].includes('>')) {
+                    let [start, end] = ugcSplit[i].split('>'), startNum = parseInt(start.substring(3), 10), endNum = parseInt(end, 10);
+                    for (let j = startNum; j <= endNum; j++) zones.push(`${state}${format}${j.toString().padStart(3, '0')}`);
+                } else zones.push(ugcSplit[i]);
+                continue;
+            }
+            if (ugcSplit[i].includes('>')) {
+                let [start, end] = ugcSplit[i].split('>'), startNum = parseInt(start, 10), endNum = parseInt(end, 10);
+                for (let j = startNum; j <= endNum; j++) zones.push(`${state}${format}${j.toString().padStart(3, '0')}`);
+            } else zones.push(`${state}${format}${ugcSplit[i]}`);
+        }
+        return zones.filter(item => item !== '');
+    }
+}
+
+module.exports = new NoaaWeatherWireServiceUGC();

package/src/vtec.js

@@ -0,0 +1,89 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| '_ ` _ \ / _ \/ __| '_ \| '_ \ / _ \ '__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: k3yomi@GitHub                        
+*/
+
+let loader = require(`../bootstrap.js`);
+
+class NoaaWeatherWireServiceVtec { 
+
+    /**
+      * @function getVTEC
+      * @description Extracts VTEC information from a message and its attributes.
+      * @param {string} message - The message containing VTEC information.
+      * @param {object} attributes - The attributes of the message.
+      */
+
+    getVTEC = function(message, attributes) {
+		let matches = message.match(new RegExp(loader.definitions.expressions.vtec, 'g'));
+		if (!matches) return null;
+		let vtecs = matches.map(match => {
+			let splitVTEC = match.split(`.`);
+			let vtecDates = splitVTEC[6].split(`-`);
+			return {
+				raw: match,
+				tracking: this.getTrackingIdentifier(splitVTEC),
+				event: this.getEventName(splitVTEC),
+				status: this.getEventStatus(splitVTEC),
+				wmo: message.match(new RegExp(loader.definitions.expressions.wmo, 'gimu')),
+				expires: this.getExpires(vtecDates),
+				issued: attributes.issue
+			};
+		});
+      	return vtecs;
+    }
+
+    /**
+      * @function getTrackingIdentifier
+      * @description Constructs a tracking identifier from the VTEC components.
+      * @param {Array} args - The components of the VTEC string.
+      */
+
+    getTrackingIdentifier = function(args) {
+        return `${args[2]}-${args[3]}-${args[4]}-${args[5]}`;
+    }
+
+    /**
+      * @function getEventName
+      * @description Constructs a an event name from the VTEC components.
+      * @param {Array} args - The components of the VTEC string.
+      */
+
+    getEventName = function(args) { 
+        return `${loader.definitions.events[args[3]]} ${loader.definitions.actions[args[4]]}`;
+    }
+
+    /**
+      * @function getEventStatus
+      * @description Retrieves the status of the event from the VTEC components. (Issued, Updated, Extended, etc.)
+      * @param {Array} args - The components of the VTEC string.
+      */
+
+    getEventStatus = function(args) { 
+        return loader.definitions.status[args[1]]
+    }
+
+    /**
+      * @function getExpires
+      * @description Converts the VTEC expiration date into a standardized format.
+      * @param {Array} args - The components of the VTEC string.
+      */
+    
+    getExpires = function(args) {
+		if (args[1] == `000000T0000Z`) return `Invalid Date Format`;
+		let expires = `${new Date().getFullYear().toString().substring(0, 2)}${args[1].substring(0, 2)}-${args[1].substring(2, 4)}-${args[1].substring(4, 6)}T${args[1].substring(7, 9)}:${args[1].substring(9, 11)}:00`;
+		let local = new Date(new Date(expires).getTime() - 4 * 60 * 60000);
+		let pad = n => n.toString().padStart(2, '0');
+		return `${local.getFullYear()}-${pad(local.getMonth() + 1)}-${pad(local.getDate())}T${pad(local.getHours())}:${pad(local.getMinutes())}:00.000-04:00`;
+    }
+}
+
+module.exports = new NoaaWeatherWireServiceVtec();

package/test.js

@@ -0,0 +1,35 @@
+AtmosXWireParser = require(`./index.js`);
+
+let Client = new AtmosXWireParser({
+    alertSettings: { 
+        onlyCap: false, // Set to true to only receive CAP messages only
+        betterEvents: true, // Set to true to receive better event handling
+        ugcPolygons: false, // Set to true to receive UGC Polygons instead of reading from raw products. 
+        filteredAlerts: [] // Alerts you want to only log, leave empty to receive all alerts (Ex. ["Tornado Warning", "Radar Indicated Tornado Warning"])
+    },
+    xmpp: {
+        reconnect: true, // Set to true to enable automatic reconnection if you lose connection
+        reconnectInterval: 60, // Interval in seconds to attempt reconnection
+    },
+    cacheSettings: {
+        maxMegabytes: 2, // Maximum cache size in megabytes
+        cacheDir: `./cache`, // Directory for cache files
+        readCache: false, // Set to true if you wish to reupload the cache from earlier
+    },
+    authentication: {
+        username: `USERNAME_HERE`, // Your XMPP username
+        password: `PASSWORD_HERE`, // Your XMPP password
+        display: `DISPLAY_NAME` // Display name for your XMPP client
+    },
+    database: `./database.db`, // Path to the SQLite database file (It will be created if it doesn't exist and will be used to store UGC counties and zones.)
+});
+
+Client.onEvent(`onAlert`, (alert) => {console.log(alert)});
+Client.onEvent(`onStormReport`, (report) => {});
+Client.onEvent(`onMesoscaleDiscussion`, (discussions) => {});
+Client.onEvent(`onMessage`, (message) => {});
+Client.onEvent(`onOccupant`, (occupant) => {});
+Client.onEvent(`onError`, (error) => {console.log(error)});
+Client.onEvent(`onReconnect`, (service) => { 
+    Client.setDisplayName(`${username} (x${service.reconnects})`)
+})