@atmosx/event-product-parser 3.0.4 → 3.0.7

package/.github/docs/docs-source-configuration.md

@@ -0,0 +1,218 @@
+<div align="center">
+	<a href="https://atmosphericx.scriptkitty.cafe">
+		<img src="https://scriptkitty.cafe/ftp/@atmosphericx/assets/logo-event-product-parser.png" alt="@atmosx/event-product-parser" width="800"/>
+	</a>
+	<br>
+	<p>A TypeScript/JavaScript library for parsing and ingesting NOAA and NWS Weather Text Products</p>
+	<small>A project built and maintained with ❤️ by the AtmosphericX team</small>
+	<p align="center">
+		<a href="https://atmosphericx.scriptkitty.cafe"><b>Documentation</b></a> |
+		<a href="https://github.com/AtmosphericX"><b>Repositories</b></a> |
+		<a href="https://www.npmjs.com/search?q=%40atmosx"><b>NPM Packages</b></a> |
+		<a href="https://atmosphericx-discord.scriptkitty.cafe"><b>Community Discord</b></a>
+	</p>
+</div>
+<br><br>
+
+
+# 3.0 - Source Configurations
+
+
+`@atmosx/event-product-parser` supports multiple source configurations that allow you to customize how weather data is ingested and processed. These configurations define the external services, connection methods, and parsing used by the parser to receive weather products. The available source configurations provide flexibility for different data ingestion requirements, allowing you to choose the appropriate source based on your application's needs while maintaining a consistent parsing experience.
+
+# 3.1 - NOAA Weather Wire Service
+[NOAA Weather Wire Service](https://www.weather.gov/nwws) is a real-time dissemination service that delivers official weather information, alerts, forecasts, products, and warnings in text format from NWS Weather Forecast Offices and National Centers.
+
+This service is designed for television and radio broadcasters, emergency managers, commercial alerting providers, private weather services, and other organizations that require rapid access to weather products.
+
+
+Each alert, forecast, and observation is delivered over [XMPP](https://xmpp.org/) using the standardized [WMO Header Format](#34---geojson--wmo-formatting). This provides a consistent structure for automated processing.
+
+Accessing the NOAA Weather Wire Service requires credentials, which can be obtained by sending an email to [NWWS.Issue@noaa.gov](mailto:NWWS.Issue@noaa.gov).
+
+When requesting access, provide the following information:
+
+* Name (First and Last)
+* Company
+* Address
+* State, City, and ZIP Code
+* Telephone Number
+* Account Information: Single or Multiple Accounts
+
+NWS processing of your request may take as long as 10 days or more depending on critical weather days and NWS priority requirements.
+
+
+# 3.2 - National Weather Service API
+The [National Weather Service](https://www.weather.gov/) provides a [RESTful API](https://www.weather.gov/documentation/services-web-api) for programmatically accessing weather data and products.
+
+Compared to the [NOAA Weather Wire Service](#31---noaa-weather-wire-service), the API introduces additional latency, with data typically delayed by 1 to 2 minutes on average. This delay is one of the primary tradeoffs when using the API instead of NOAA Weather Wire Service for real-time weather product ingestion.
+
+The NWS API is best suited for applications that require on demand access to weather data rather than the lowest possible latency delivery of operational weather products. All responses are provided in [GeoJSON](https://geojson.org/) format, making the data straightforward to parse and integrate into applications.
+
+
+# 3.3 - NOAA Weather Wire Service vs NWS RESTful API
+There are significant differences between these two sources. [NOAA Weather Wire Service](#31---noaa-weather-wire-service) requires authenticated access and is optimized for real-time product delivery, while the [NWS RESTful API](#32---national-weather-service-api) is publicly accessible and designed for on demand data retrieval.
+
+| Feature | NOAA Weather Wire Service | NWS RESTful API |
+| --- | --- | --- |
+| Authentication | ✅ | ❌ |
+| Real-time Delivery | ✅ | ❌ |
+| WMO Formatting | ✅ | ❌ |
+| Persistent Connection | ✅ | ❌ |
+| Low Latency Products | ✅ | ❌ |
+| Easy to Use | ❌ | ✅ |
+| Publicly Accessible | ❌ | ✅ |
+
+
+# 3.4 - GeoJSON & WMO Formatting
+
+`@atmosx/event-product-parser` supports two primary data formats when ingesting weather products. The [NOAA Weather Wire Service](#31---noaa-weather-wire-service) uses [WMO Format](#342---wmo-format), while the [National Weather Service API](#32---national-weather-service-api) uses [GeoJSON](#341---geojson).
+
+## 3.4.1 - GeoJSON
+[GeoJSON](https://geojson.org/) is a format for encoding a variety of geographic data structures. It is based on the JavaScript Object Notation (JSON) standard and is widely used for representing geographic features in web applications.
+
+You can view a real-world sample [here](/.github/samples/SAMPLE_GEOJSON.json).
+
+```json
+{
+	"type": "Feature",
+	"geometry": {
+		"type": "Polygon",
+		"coordinates": [[]]
+	},
+	"properties": {}
+}
+```
+
+## 3.4.2 - WMO Format
+**WMO Format** (World Meteorological Organization Format) is a standardized structure used for exchanging meteorological data, including observations, forecasts, and warnings. It provides a consistent format for weather products, allowing meteorological organizations and systems around the world to reliably share and process weather information.
+
+A real-world example of a WMO-formatted product can be found [here](/.github/samples/SAMPLE_TEXT_PRODUCT.txt).
+```text
+000
+WUUS51 KLOT 000000
+SVRGYX
+ILC001-ILC002-
+/O.NEW.XXXX.XX.X.0000.000000T0000Z-000000T0000Z/
+
+BULLETIN - IMMEDIATE BROADCAST REQUESTED
+
+Severe Thunderstorm Warning
+
+National Weather Service
+
+XXXX PM Timezone Weekday Month DD 2026
+
+TEST EXAMPLE - TEXT EXAMPLE - TEST EXAMPLE
+
+&&
+
+
+
+LAT...LON 4587 6965 4585 6968 4588 6971 4587 6972
+
+      4584 6970 4576 6972 4576 6976 4577 6978
+
+      4574 6981 4566 6974 4565 6970 4558 6971
+
+      4553 6978 4530 6970 4567 7054 4573 7038
+
+      4580 7042 4589 7026 4596 7026 4598 6968
+
+TIME...MOT...LOC 1650Z 313DEG 52KT 4600 7042
+```
+
+
+# 3.5 - Configuring NOAA Weather Wire Service
+
+Configuring `@atmosx/event-product-parser` to use the [NOAA Weather Wire Service](#31---noaa-weather-wire-service) requires setting up the necessary credentials and connection parameters to establish a persistent connection to the service. This can be configured through the **Manager** class within your application.
+
+* Keep in mind that settings configured within `NOAAWeatherWireServiceSettings` only apply to the [NOAA Weather Wire Service](#31---noaa-weather-wire-service) source and do not affect the [National Weather Service API](#32---national-weather-service-api) source.
+
+```ts
+import { Manager } from '@atmosx/event-product-parser';
+
+const client = new Manager({
+	EnableWireService: true, // Enable NOAA Weather Wire Service (NWWS)
+	NOAAWeatherWireServiceSettings: {
+		CredentialSettings: {
+			Username: `USERNAME`, // Case sensitive
+			Password: `PASSWORD`, // Case sensitive
+			Nickname: `NICKNAME`, // Visible to other connected users
+		},
+	},
+});
+```
+
+* Only **one** source can be enabled at a time. (*This project does not use fallback sources*)
+
+## 3.5.1 - Auto Reconnecting
+
+With [XMPP](https://xmpp.org/) connections, `@atmosx/event-product-parser` can automatically reconnect to the [NOAA Weather Wire Service](#31---noaa-weather-wire-service) if the connection is interrupted.
+
+This ensures your application can maintain a persistent connection and continue receiving weather products without requiring manual intervention after temporary network failures or service disruptions.
+
+* This configuration only applies to the [NOAA Weather Wire Service](#31---noaa-weather-wire-service) using [XMPP](https://xmpp.org/). The [National Weather Service API](#32---national-weather-service-api) source does not require auto reconnect configuration.
+
+```ts
+NOAAWeatherWireServiceSettings: {
+	ReconnectionSettings: {
+		Enabled: true, // Enable auto reconnect
+		ReconnectionInterval: 60, // Time since last stanza before reconnecting (seconds)
+	},
+},
+```
+
+## 3.5.2 - Stanza Caching
+
+Optionally, you can enable stanza caching to retain previously processed [XMPP](https://xmpp.org/) stanzas. This can help prevent data loss in the event that your application requires a fresh restart.
+
+* Keep in mind that increasing **MaxRetentionHistory** will increase the amount of time required for `@atmosx/event-product-parser` to initialize, as more cached stanzas must be loaded and processed during startup.
+
+```ts
+NOAAWeatherWireServiceSettings: {
+	CacheSettings: {
+		Enabled: true, // Enable stanza caching
+		MaxDatabaseHistory: 50000, // Maximum stanzas to store in the database
+		MaxRetentionHistory: 1200, // Maximum stanzas to load during startup
+	},
+},
+```
+
+## 3.5.3 - Stanza Processing Settings
+
+While processing stanzas, each one is categorized based on its contents and characteristics. This includes formats such as [CAP (Common Alerting Protocol) v1.2](https://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html), [VTEC](https://www.weather.gov/vtec/), [UGC](https://www.weather.gov/gis/AWIPSShapefiles), and **Raw Text** products. By default, all product categories are enabled by default which includes: 
+
+* UGC Only Products
+* VTEC/HVTEC Only Products
+* Raw Text (No UGC/VTEC Present)
+
+Please keep in mind that the **Common Alerting Protocol** text products will always be skipped as they tend to be slower for ingestion and require extra steps which include parsing [XML](https://www.w3.org/TR/REC-xml/). There is **NO** longer support for this category.
+
+
+```ts
+NOAAWeatherWireServiceSettings: {
+	StanzaSettings: {
+		DisableUGC: false, // Disables all UGC Categories
+		DisableVTEC: false, // Disables all VTEC/HVTEC Categories
+		DisableText: false, // Disables all RawText Categories
+	}
+},
+```
+
+
+# 3.6 - Configuring National Weather Service API
+
+The [National Weather Service API](#32---national-weather-service-api) requires minimal configuration compared to the [NOAA Weather Wire Service](#31---noaa-weather-wire-service). While there are fewer available settings, the API source is designed to provide simple access to weather data through RESTful requests without requiring authentication or persistent connections.
+
+```ts
+import { Manager } from '@atmosx/event-product-parser';
+
+const client = new Manager({
+	EnableWireService: false, // Disable NOAA Weather Wire Service (NWWS)
+	NationalWeatherServiceSettings: {
+        CallbackInterval: 30, // How often it retrieves new products (Minimum: 15 seconds)
+        EventsEndpoint: `https://api.weather.gov/alerts/active`, // RESTful API
+    },
+});
+```

package/.github/docs/docs-technical.md

@@ -0,0 +1,50 @@
+<div align="center">
+	<a href="https://atmosphericx.scriptkitty.cafe">
+		<img src="https://scriptkitty.cafe/ftp/@atmosphericx/assets/logo-event-product-parser.png" alt="@atmosx/event-product-parser" width="800"/>
+	</a>
+	<br>
+	<p>A TypeScript/JavaScript library for parsing and ingesting NOAA and NWS Weather Text Products</p>
+	<small>A project built and maintained with ❤️ by the AtmosphericX team</small>
+	<p align="center">
+		<a href="https://atmosphericx.scriptkitty.cafe"><b>Documentation</b></a> |
+		<a href="https://github.com/AtmosphericX"><b>Repositories</b></a> |
+		<a href="https://www.npmjs.com/search?q=%40atmosx"><b>NPM Packages</b></a> |
+		<a href="https://atmosphericx-discord.scriptkitty.cafe"><b>Community Discord</b></a>
+	</p>
+</div>
+<br><br>
+
+# 8.0 - Technical Parser Documentation
+# 8.1 - Workflow & Pipeline
+# 8.2 - Core Parsing Logic
+## 8.2.1 - VTEC
+### 8.2.1.1 - Product Dictionary
+### 8.2.1.2 - Tracking
+### 8.2.1.3 - Event Dictionary
+### 8.2.1.4 - Status Dictionary
+### 8.2.1.5 - Organization Sender
+### 8.2.1.6 - Expiry Parsing
+### 8.2.1.7 - Watch Parsing
+### 8.2.1.8 - KWNS / SPC
+## 8.2.2 - UGC
+### 8.2.2.1 - Extracting Headers
+### 8.2.2.2 - Getting Zones
+### 8.2.2.3 - Extracting Expiry
+### 8.2.2.4 - UGC to Zones
+## 8.2.3 - HVTEC
+### 8.2.3.1 - Flood Severity
+### 8.2.3.2 - Flood Causes
+### 8.2.3.3 - Flood Records
+## 8.2.4 - Raw Text
+### 8.2.4.1 - Extracting Descriptions
+### 8.2.4.2 - Extracting Coordinates
+### 8.2.4.3 - Extracting String Specifics
+### 8.2.4.4 - Extracting XML
+## 8.2.5 - Building Properties
+## 8.2.6 - Building Geometry
+# 8.3 - Event Validation & Filtering
+## 8.3.1 - Enhanced Event Naming
+## 8.3.2 - Appending Attachments
+## 8.3.3 - Generation Hashes
+# 8.4 - Event & History Management
+# 8.5 - Action Workflow

package/.github/samples/SAMPLE_GEOJSON.json

@@ -0,0 +1,204 @@
+{
+	"type": "Feature",
+	"geometry": {
+		"type": "Polygon",
+		"coordinates": [
+			[
+				[
+					-69.65,
+					45.87
+				],
+				[
+					-69.68,
+					45.85
+				],
+				[
+					-69.71,
+					45.88
+				],
+				[
+					-69.72,
+					45.87
+				],
+				[
+					-69.7,
+					45.84
+				],
+				[
+					-69.72,
+					45.76
+				],
+				[
+					-69.76,
+					45.76
+				],
+				[
+					-69.78,
+					45.77
+				],
+				[
+					-69.81,
+					45.74
+				],
+				[
+					-69.74,
+					45.66
+				],
+				[
+					-69.7,
+					45.65
+				],
+				[
+					-69.71,
+					45.58
+				],
+				[
+					-69.78,
+					45.53
+				],
+				[
+					-69.7,
+					45.3
+				],
+				[
+					-70.54,
+					45.67
+				],
+				[
+					-70.38,
+					45.73
+				],
+				[
+					-70.42,
+					45.8
+				],
+				[
+					-70.26,
+					45.89
+				],
+				[
+					-70.26,
+					45.96
+				],
+				[
+					-69.68,
+					45.98
+				],
+				[
+					-69.65,
+					45.87
+				]
+			]
+		]
+	},
+	"properties": {
+		"event": "Considerable Severe Thunderstorm Warning",
+		"parent": "Severe Thunderstorm Warning",
+		"status": "Expired",
+		"issued": "2026-07-14T16:51:00.000Z",
+		"expires": "2026-07-14T17:45:00.012Z",
+		"locations": "Somerset, ME",
+		"locations_array": [
+			"Somerset, ME"
+		],
+		"description": "Considerable Severe Thunderstorm Warning has been allowed to expire. This product is no longer in effect.",
+		"attributes": {
+			"xmlns": "nwws-oi",
+			"id": "nwws_processor.6830",
+			"issue": "2026-07-14T16:51:00Z",
+			"ttaaii": "WUUS51",
+			"cccc": "KGYX",
+			"awipsid": "SVRGYX"
+		},
+		"geocode": {
+			"office": {
+				"office": "KGYX",
+				"name": "Portland, ME"
+			},
+			"organization": "WUUS51 KGYX 141651",
+			"ugc": [
+				"MEC025"
+			],
+			"polygon": "W1tbLTY5LjY1LDQ1Ljg3XSxbLTY5LjY4LDQ1Ljg1XSxbLTY5LjcxLDQ1Ljg4XSxbLTY5LjcyLDQ1Ljg3XSxbLTY5LjcsNDUuODRdLFstNjkuNzIsNDUuNzZdLFstNjkuNzYsNDUuNzZdLFstNjkuNzgsNDUuNzddLFstNjkuODEsNDUuNzRdLFstNjkuNzQsNDUuNjZdLFstNjkuNyw0NS42NV0sWy02OS43MSw0NS41OF0sWy02OS43OCw0NS41M10sWy02OS43LDQ1LjNdLFstNzAuNTQsNDUuNjddLFstNzAuMzgsNDUuNzNdLFstNzAuNDIsNDUuOF0sWy03MC4yNiw0NS44OV0sWy03MC4yNiw0NS45Nl0sWy02OS42OCw0NS45OF0sWy02OS42NSw0NS44N11dXQ==",
+			"polygon_generated": true
+		},
+		"parameters": {
+			"tags": [
+				"Radar Indicated",
+				"Nickel Size Hail"
+			],
+			"instructions": "MOVE TO AN INTERIOR ROOM ON THE LOWEST FLOOR OF A...",
+			"source": "RADAR INDICATED",
+			"hazards": "70 MPH WIND GUSTS AND NICKEL SIZE HAIL",
+			"impacts": "EXPECT CONSIDERABLE TREE DAMAGE DAMAGE IS LIKELY TO",
+			"estimated_hail_size": "0.88 (Nickel)",
+			"estimated_wind_gusts": "70 MPH",
+			"damage_threat": "CONSIDERABLE",
+			"wind_threat": "RADAR INDICATED",
+			"hail_threat": "RADAR INDICATED"
+		},
+		"discussion_parameters": {},
+		"watch_parameters": {
+			"watch_number": false
+		},
+		"metadata": {
+			"ms": 13.219468999654055,
+			"source": "events.vtec",
+			"tracking": "KGYX.SV.W.0034",
+			"header": "ZCZC-ATMOSX-SVR-MEC025-Issued-20260714T165133-KGYX",
+			"vtec": {
+				"vtec": "O.NEW.KGYX.SV.W.0034.260714T1651Z-260714T1745Z",
+				"product": "Operational Product",
+				"tracking": "KGYX.SV.W.0034",
+				"event": "Severe Thunderstorm Warning",
+				"status": "Issued",
+				"organization": "WUUS51 KGYX 141651",
+				"expires": "2026-07-14T13:45:00.000-04:00",
+				"is_watch": false,
+				"prediction_center": false
+			},
+			"raw": "Considerable Severe Thunderstorm Warning has been allowed to expire. This product is no longer in effect.",
+			"history": [
+				{
+					"description": "The National Weather Service in Gray Maine has issued a\n\n\n\n* Severe Thunderstorm Warning for...\n\n  Northwestern Somerset County in west central Maine...\n\n\n\n* Until 145 PM EDT.\n\n\n\n* At 1250 PM EDT, a severe thunderstorm was located 29 miles north of\n\n  Jackman, moving southeast at 60 mph.\n\n\n\n  HAZARD...70 mph wind gusts and nickel size hail.\n\n\n\n  SOURCE...Radar indicated.\n\n\n\n  IMPACT...Expect considerable tree damage. Damage is likely to \n\n           mobile homes, roofs, and outbuildings.\n\n\n\n* Locations impacted include...\n\n  Jackman, Seboomook, Misery Gore, Sandwich Academy Grant, Moose\n\n  River, Long Pond, Parlin Pond, Forsyth, Tomhegan, Dennistown\n\n  Plantation, Chase Stream, Rockwood Strip, Soldiertown, Sandy Bay,\n\n  Johnson Mountain, Plymouth, Taunton And Raynham Academy Grant,\n\n  Pittston Academy Grant, Brassua, and Sapling.\n\n\n\nPRECAUTIONARY/PREPAREDNESS ACTIONS...\n\n\n\nFor your protection move to an interior room on the lowest floor of a\n\nbuilding.\n\n\n\nIf on or near Moosehead Lake, get away from the water and move \n\nindoors or inside a vehicle. Remember, lightning can strike out to \n\n15 miles from the parent thunderstorm. If you can hear thunder, you \n\nare close enough to be struck by lightning. Move to safe shelter \n\nnow!  Do not be caught on the water in a thunderstorm.",
+					"issued": "2026-07-14T16:51:00.000Z",
+					"status": "Issued"
+				},
+				{
+					"description": "Considerable Severe Thunderstorm Warning has been allowed to expire. This product is no longer in effect.",
+					"issued": "2026-07-14T17:45:00.012Z",
+					"status": "Expired"
+				}
+			],
+			"attachments": [
+				{
+					"name": "Public Safety: Anson and Madison Fire",
+					"link": "https://www.broadcastify.com/listen/feed/47168"
+				},
+				{
+					"name": "Public Safety: Anson/Madison/Starks Ambulance",
+					"link": "https://www.broadcastify.com/listen/feed/47335"
+				},
+				{
+					"name": "Public Safety: Kennebec, Somerset, and Waldo County Fire Departments",
+					"link": "https://www.broadcastify.com/listen/feed/41643"
+				},
+				{
+					"name": "Public Safety: Somerset County Fire",
+					"link": "https://www.broadcastify.com/listen/feed/25011"
+				}
+			],
+			"hash": "0d3f2b404c2ea964712416139e1867534fc63f1343ea84a0be91760918d9bf33",
+			"nodes": [],
+			"filtered_proximity": false,
+			"updated": 1784051098011
+		},
+		"status_metadata": {
+			"is_issued": true,
+			"is_test": false,
+			"is_updated": false,
+			"is_expired": true,
+			"is_statement": false
+		}
+	}
+}

package/.github/samples/SAMPLE_TEXT_PRODUCT.txt

@@ -0,0 +1,119 @@
+449
+
+WUUS51 KGYX 141651
+
+SVRGYX
+
+MEC025-141745-
+
+/O.NEW.KGYX.SV.W.0034.260714T1651Z-260714T1745Z/
+
+
+
+BULLETIN - IMMEDIATE BROADCAST REQUESTED
+
+Severe Thunderstorm Warning
+
+National Weather Service Gray ME
+
+1251 PM EDT Tue Jul 14 2026
+
+
+
+The National Weather Service in Gray Maine has issued a
+
+
+
+* Severe Thunderstorm Warning for...
+
+  Northwestern Somerset County in west central Maine...
+
+
+
+* Until 145 PM EDT.
+
+
+
+* At 1250 PM EDT, a severe thunderstorm was located 29 miles north of
+
+  Jackman, moving southeast at 60 mph.
+
+
+
+  HAZARD...70 mph wind gusts and nickel size hail.
+
+
+
+  SOURCE...Radar indicated.
+
+
+
+  IMPACT...Expect considerable tree damage. Damage is likely to 
+
+           mobile homes, roofs, and outbuildings.
+
+
+
+* Locations impacted include...
+
+  Jackman, Seboomook, Misery Gore, Sandwich Academy Grant, Moose
+
+  River, Long Pond, Parlin Pond, Forsyth, Tomhegan, Dennistown
+
+  Plantation, Chase Stream, Rockwood Strip, Soldiertown, Sandy Bay,
+
+  Johnson Mountain, Plymouth, Taunton And Raynham Academy Grant,
+
+  Pittston Academy Grant, Brassua, and Sapling.
+
+
+
+PRECAUTIONARY/PREPAREDNESS ACTIONS...
+
+
+
+For your protection move to an interior room on the lowest floor of a
+
+building.
+
+
+
+If on or near Moosehead Lake, get away from the water and move 
+
+indoors or inside a vehicle. Remember, lightning can strike out to 
+
+15 miles from the parent thunderstorm. If you can hear thunder, you 
+
+are close enough to be struck by lightning. Move to safe shelter 
+
+now!  Do not be caught on the water in a thunderstorm.
+
+
+
+&&
+
+
+
+LAT...LON 4587 6965 4585 6968 4588 6971 4587 6972
+
+      4584 6970 4576 6972 4576 6976 4577 6978
+
+      4574 6981 4566 6974 4565 6970 4558 6971
+
+      4553 6978 4530 6970 4567 7054 4573 7038
+
+      4580 7042 4589 7026 4596 7026 4598 6968
+
+TIME...MOT...LOC 1650Z 313DEG 52KT 4600 7042 
+
+
+
+THUNDERSTORM DAMAGE THREAT...CONSIDERABLE
+
+HAIL THREAT...RADAR INDICATED
+
+MAX HAIL SIZE...0.88 IN
+
+WIND THREAT...RADAR INDICATED
+
+MAX WIND GUST...70 MPH