@atmosx/event-product-parser 2.0.1

package/src/@parsers/hvtec.ts

@@ -0,0 +1,46 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| "_ ` _ \ / _ \/ __| "_ \| "_ \ / _ \ "__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: KiyoWx (k3yomi)                
+*/
+
+import * as loader from '../bootstrap';
+import * as types from '../types';
+
+export class HVtecParser {
+    
+    /**
+     * @function HVtecExtractor
+     * @description
+     *     Extracts VTEC entries from a raw NWWS message string and returns
+     *     structured objects containing type, tracking, event, status,
+     *     WMO identifiers, and expiry date.
+     *
+     * @static
+     * @param {string} message
+     * @returns {Promise<types.HtecEntry[] | null>}
+     */
+    public static async HVtecExtractor(message: string): Promise<types.HVtecEntry[] | null> {
+        const matches = message.match(loader.definitions.regular_expressions.hvtec);
+        if (!matches || matches.length !== 1) return null;
+        const hvtec = matches[0];
+        const parts = hvtec.split('.');
+        if (parts.length < 7) return null;
+        const hvtecs: types.HVtecEntry[] = [{
+            severity: loader.definitions.severity[parts[1]],
+            cause: loader.definitions.causes[parts[2]],
+            record: loader.definitions.records[parts[6]],
+            raw: hvtec,
+        }];
+        return hvtecs;
+    }
+}
+
+export default HVtecParser;

package/src/@parsers/pvtec.ts

@@ -0,0 +1,72 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| "_ ` _ \ / _ \/ __| "_ \| "_ \ / _ \ "__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: KiyoWx (k3yomi)                
+*/
+
+import * as loader from '../bootstrap';
+import * as types from '../types';
+
+export class PVtecParser {
+    
+    /**
+     * @function pVtecExtractor
+     * @description
+     *     Extracts VTEC entries from a raw NWWS message string and returns
+     *     structured objects containing type, tracking, event, status,
+     *     WMO identifiers, and expiry date.
+     *
+     * @static
+     * @param {string} message
+     * @returns {Promise<types.VtecEntry[] | null>}
+     */
+    public static async pVtecExtractor(message: string): Promise<types.PVtecEntry[] | null> {
+        const matches = message.match(loader.definitions.regular_expressions.pvtec) ?? [];
+        const pVtecs: types.PVtecEntry[] = [];
+        for (const pvtec of matches) {
+            const parts = pvtec.split('.');
+            if (parts.length < 7) continue; 
+            const dates = parts[6].split('-');
+            pVtecs.push({
+                raw: pvtec,
+                type: loader.definitions.productTypes[parts[0]],
+                tracking: `${parts[2]}-${parts[3]}-${parts[4]}-${parts[5]}`,
+                event: `${loader.definitions.events[parts[3]]} ${loader.definitions.actions[parts[4]]}`,
+                status: loader.definitions.status[parts[1]],
+                wmo: message.match(loader.definitions.regular_expressions.wmo)?.[0] || null,
+                expires: this.parseExpiryDate(dates),
+                isKWNS: (parts[4] == `A` || parts[4] == `Y`) && (parts[3] == `TO` || parts[3] == `SV`) ? true : false,
+            });
+        }
+        return pVtecs.length > 0 ? pVtecs : null;
+    }
+
+    /**
+     * @function parseExpiryDate
+     * @description
+     *     Converts a NWWS VTEC/expiry timestamp string into a formatted local ISO date string
+     *     with an Eastern Time offset (-04:00). Returns `Invalid Date Format` if the input
+     *     is `000000T0000Z`.
+     *
+     * @private
+     * @static
+     * @param {string[]} args
+     * @returns {string}
+     */
+    private static parseExpiryDate(args: String[]): string {
+        if (args[1] == `000000T0000Z`) return `Invalid Date Format`;
+        const 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`;
+        const local = new Date(new Date(expires).getTime() - 4 * 60 * 60000);
+        const pad = (n: number) => 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`;
+    }
+}
+
+export default PVtecParser;

package/src/@parsers/stanza.ts

@@ -0,0 +1,97 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| "_ ` _ \ / _ \/ __| "_ \| "_ \ / _ \ "__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: KiyoWx (k3yomi)                
+*/
+
+import * as loader from '../bootstrap';
+import * as types from '../types';
+
+export class StanzaParser {
+
+    /**
+     * @function validate
+     * @description
+     *     Validates and parses a stanza message, extracting its attributes and metadata.
+     *     Handles both raw message strings (for debug/testing) and actual stanza objects.
+     *     Determines whether the message is a CAP alert, contains VTEC codes, or contains UGCs,
+     *     and identifies the AWIPS product type and prefix.
+     *
+     * @static
+     * @param {any} stanza
+     * @param {boolean | types.StanzaAttributes} [isDebug=false]
+     * @returns {{
+     *     message: string;
+     *     attributes: types.StanzaAttributes;
+     *     isCap: boolean,
+     *     isPVtec: boolean;
+     *     isCapDescription: boolean;
+     *     awipsType: Record<string, string>;
+     *     isApi: boolean;
+     *     ignore: boolean;
+     *     isUGC?: boolean;
+     * }}
+     */
+    public static validate(stanza: any, isDebug: boolean | types.StanzaAttributes = false): { message: string; attributes: types.StanzaAttributes; isCap: any; isPVtec: boolean; isCapDescription: any; awipsType: any; isApi: boolean; ignore: boolean; isUGC?: boolean; } {
+        if (isDebug !== false) { 
+            const vTypes = isDebug as types.StanzaAttributes;  
+            const message = stanza;
+            const attributes = vTypes;
+            const isCap = vTypes.isCap ?? message.includes(`<?xml`);
+            const isCapDescription = message.includes(`<areaDesc>`);
+            const isPVtec = message.match(loader.definitions.regular_expressions.pvtec) != null;
+            const isUGC = message.match(loader.definitions.regular_expressions.ugc1) != null;
+            const awipsType = this.getType(attributes);
+            return { message, attributes, isCap, isPVtec, isUGC, isCapDescription, awipsType: awipsType, isApi: false, ignore: false };
+        }
+        if (stanza.is(`message`)) {
+            let cb = stanza.getChild(`x`)
+            if (cb && cb.children) {
+                let message = unescape(cb.children[0]);
+                let attributes = cb.attrs
+                if (attributes.awipsid && attributes.awipsid.length > 1) {
+                    const isCap = message.includes(`<?xml`);
+                    const isCapDescription = message.includes(`<areaDesc>`);
+                    const isPVtec = message.match(loader.definitions.regular_expressions.pvtec) != null;
+                    const isUGC = message.match(loader.definitions.regular_expressions.ugc1) != null;
+                    const awipsType = this.getType(attributes);
+                    return { message, attributes, isCap, isPVtec, isUGC, isCapDescription, awipsType: awipsType, isApi: false, ignore: false  };
+                }
+            }
+        }
+        return { message: null, attributes: null, isApi: null, isCap: null, isPVtec: null, isUGC: null, isCapDescription: null, awipsType: null, ignore: true };
+    }
+
+    /**
+     * @function getType
+     * @description
+     *     Determines the AWIPS product type and prefix from a stanza's attributes.
+     *     Returns a default type of 'XX' if the attributes are missing or the AWIPS ID
+     *     does not match any known definitions.
+     *
+     * @private
+     * @static
+     * @param {unknown} attributes
+     * @returns {Record<string, string>}
+     */
+    private static getType(attributes: unknown): Record<string, string> {
+        const attrs = attributes as types.StanzaAttributesType | undefined;
+        if (!attrs?.awipsid) return { type: 'XX', prefix: 'XX' };
+        const awipsDefs = loader.definitions.awips as Record<string, string>;
+        for (const [prefix, type] of Object.entries(awipsDefs)) {
+            if (attrs.awipsid.startsWith(prefix)) {
+                return { type, prefix };
+            }
+        }
+        return { type: 'XX', prefix: 'XX' };
+    }  
+}
+
+export default StanzaParser;

package/src/@parsers/text.ts

@@ -0,0 +1,165 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| "_ ` _ \ / _ \/ __| "_ \| "_ \ / _ \ "__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: KiyoWx (k3yomi)                
+*/
+
+import * as loader from '../bootstrap';
+
+export class TextParser {
+    
+    /**
+     * @function textProductToString
+     * @description
+     *     Searches a text product message for a line containing a specific value,
+     *     extracts the substring immediately following that value, and optionally
+     *     removes additional specified strings. Cleans up the extracted string by
+     *     trimming whitespace and removing any remaining occurrences of the search
+     *     value or '<' characters.
+     *
+     * @static
+     * @param {string} message
+     * @param {string} value
+     * @param {string[]} [removal=[]]
+     * @returns {string | null}
+     */
+    public static textProductToString(message: string,value: string,removal: string[] = []): string | null {
+        const lines = message.split('\n');
+        for (const line of lines) {
+            if (line.includes(value)) {
+                let result = line.slice(line.indexOf(value) + value.length).trim();
+                for (const str of removal) { result = result.split(str).join(''); }
+                result = result.replace(value, '').replace('<', '').trim();
+                return result || null;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * @function textProductToPolygon
+     * @description
+     *     Parses a text product message to extract polygon coordinates based on
+     *     LAT...LON data. Coordinates are converted to [latitude, longitude] pairs
+     *     with longitude negated (assumes Western Hemisphere). If the polygon has
+     *     more than two points, the first point is repeated at the end to close it.
+     *
+     * @static
+     * @param {string} message
+     * @returns {[number, number][]}
+     */
+    public static textProductToPolygon(message: string): [number, number][] {
+        const coordinates: [number, number][] = [];
+        const latLonMatch = message.match(/LAT\.{3}LON\s+([\d\s]+)/i);
+        if (!latLonMatch || !latLonMatch[1]) return coordinates;
+        const coordStrings = latLonMatch[1].replace(/\n/g, ' ').trim().split(/\s+/);
+        for (let i = 0; i < coordStrings.length - 1; i += 2) {
+            const lat = parseFloat(coordStrings[i]) / 100;
+            const lon = -parseFloat(coordStrings[i + 1]) / 100;
+            if (!isNaN(lat) && !isNaN(lon)) { coordinates.push([lon, lat]); }
+        }
+        if (coordinates.length > 2) { coordinates.push(coordinates[0]); }
+        return coordinates;
+    }
+
+    /**
+     * @function textProductToDescription
+     * @description
+     *     Extracts a clean description portion from a text product message, optionally
+     *     removing a handle and any extra metadata such as "STANZA ATTRIBUTES...".
+     *     Also trims and normalizes whitespace.
+     *
+     * @static
+     * @param {string} message
+     * @param {string | null} [handle=null]
+     * @returns {string}
+     */
+    public static textProductToDescription(message: string, handle: string = null): string {
+        const original = message;
+        const discoveredDates = Array.from(message.matchAll(loader.definitions.regular_expressions.dateline));
+        if (discoveredDates.length) {
+            const lastMatch = discoveredDates[discoveredDates.length - 1][0];
+            const startIdx = message.lastIndexOf(lastMatch);
+            if (startIdx !== -1) {
+                const endIdx = message.indexOf('&&', startIdx);
+                message = message.substring(startIdx + lastMatch.length, endIdx !== -1 ? endIdx : undefined).trimStart();
+                if (message.startsWith('/')) message = message.slice(1).trimStart();
+                if (handle && message.includes(handle)) {
+                    const handleIdx = message.indexOf(handle);
+                    message = message.substring(handleIdx + handle.length).trimStart();
+                    if (message.startsWith('/')) message = message.slice(1).trimStart();
+                }
+            }
+        } else if (handle) {
+            const handleIdx = message.indexOf(handle);
+            if (handleIdx !== -1) {
+                let afterHandle = message.substring(handleIdx + handle.length).trimStart();
+                if (afterHandle.startsWith('/')) afterHandle = afterHandle.slice(1).trimStart();
+                const latEnd = afterHandle.indexOf('&&')
+                message = latEnd !== -1 ? afterHandle.substring(0, latEnd).trim() : afterHandle.trim();
+            }
+        }
+        return message.replace(/\s+/g, ' ').trim().startsWith('STANZA ATTRIBUTES...') ? original : message.split('STANZA ATTRIBUTES...')[0].trim();
+    }
+    
+    /**
+     * @function getXmlValues
+     * @description
+     *     Recursively extracts specified values from a parsed XML-like object.
+     *     Searches both object keys and array items for matching keys (case-insensitive)
+     *     and returns the corresponding values. If multiple unique values are found for
+     *     a key, an array is returned; if one value is found, it returns that value; 
+     *     if none are found, returns `null`.
+     *
+     * @static
+     * @param {any} parsed
+     * @param {string[]} valuesToExtract
+     * @returns {Record<string, string | string[] | null>}
+     */
+    public static getXmlValues(parsed: any, valuesToExtract: string[]): Record<string, string> {
+        const extracted: Record<string, any> = {};   
+        const findValueByKey = (obj: any, searchKey: string) => {
+            const results = [];
+            if (obj === null || typeof obj !== 'object') {
+                return results;
+            }
+            const searchKeyLower = searchKey.toLowerCase();
+            for (const key in obj) {
+                if (obj.hasOwnProperty(key) && key.toLowerCase() === searchKeyLower) {
+                    results.push(obj[key]);
+                }
+            }
+            if (Array.isArray(obj)) {
+                for (const item of obj) {
+                    if (item.valueName && item.valueName.toLowerCase() === searchKeyLower && item.value !== undefined) {
+                        results.push(item.value);
+                    }
+                    const nestedResults = findValueByKey(item, searchKey);
+                    results.push(...nestedResults);
+                }
+            }
+            for (const key in obj) {
+                if (obj.hasOwnProperty(key)) {
+                    const nestedResults = findValueByKey(obj[key], searchKey);
+                    results.push(...nestedResults);
+                }
+            }
+            return results;
+        };
+        for (const key of valuesToExtract) {
+            const values = findValueByKey(parsed.alert, key);
+            const uniqueValues = [...new Set(values)];
+            extracted[key] = uniqueValues.length === 0 ? null : (uniqueValues.length === 1 ? uniqueValues[0] : uniqueValues);
+        }
+        return extracted;
+    } 
+}
+
+export default TextParser;

package/src/@parsers/ugc.ts

@@ -0,0 +1,247 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| "_ ` _ \ / _ \/ __| "_ \| "_ \ / _ \ "__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: KiyoWx (k3yomi)                
+*/
+
+import * as loader from '../bootstrap';
+import * as types from '../types';
+
+export class UGCParser {
+    
+    /**
+     * @function ugcExtractor
+     * @description
+     *     Extracts UGC (Universal Geographic Code) information from a message.
+     *     This includes parsing the header, resolving zones, calculating the expiry
+     *     date, and retrieving associated location names from the database.
+     *
+     * @static
+     * @async
+     * @param {string} message
+     * @returns {Promise<types.UGCEntry | null>}
+     */
+    public static async ugcExtractor(message: string): Promise<types.UGCEntry | null> {
+        const header = this.getHeader(message);
+        if (!header) return null;
+        const zones = this.getZones(header);
+        if (zones.length === 0) return null;
+        const expiry = this.getExpiry(message);
+        const locations = await this.getLocations(zones);
+        return { 
+            zones: zones, 
+            locations: locations,
+            expiry: expiry
+        };
+    }
+
+    /**
+     * @function getHeader
+     * @description
+     *     Extracts the UGC header from a message by locating patterns defined in
+     *     `ugc1` and `ugc2` regular expressions. Removes all whitespace and the
+     *     trailing character from the matched header.
+     *
+     * @static
+     * @param {string} message
+     * @returns {string | null}
+     */
+    public static getHeader(message: string): string | null {
+        const start = message.search(loader.definitions.regular_expressions.ugc1);
+        const subMessage = message.substring(start);
+        const end = subMessage.search(loader.definitions.regular_expressions.ugc2);
+        const full = subMessage.substring(0, end).replace(/\s+/g, '').slice(0, -1);
+        return full || null;
+    }
+
+    /**
+     * @function getExpiry
+     * @description
+     *     Extracts an expiration date from a message using the UGC3 format.
+     *     The function parses day, hour, and minute from the message and constructs
+     *     a Date object in the current month and year. Returns `null` if no valid
+     *     expiration is found.
+     *
+     * @static
+     * @param {string} message
+     * @returns {Date | null}
+     */
+    public static getExpiry(message: string): Date | null {
+        const match = message.match(/\b(\d{6})-/);
+        if (!match) return null;
+        const token = match[1];
+        const day = parseInt(token.slice(0, 2), 10);
+        const hour = parseInt(token.slice(2, 4), 10);
+        const minute = parseInt(token.slice(4, 6), 10);
+        const now = new Date();
+        const expires = new Date(Date.UTC(now.getUTCFullYear(),now.getUTCMonth(),day,hour,minute));
+        return expires;
+    }
+
+    /**
+     * @function getLocations
+     * @description
+     *     Retrieves human-readable location names for an array of zone identifiers
+     *     from the shapefiles database. If a zone is not found, the zone ID itself
+     *     is returned. Duplicate locations are removed and the result is sorted.
+     *
+     * @static
+     * @async
+     * @param {string[]} zones
+     * @returns {Promise<string[]>}
+     */
+    public static async getLocations(zones: string[]): Promise<string[]> {
+        const uniqueZones = Array.from(new Set(zones.map(z => z.trim())));
+        const placeholders = uniqueZones.map(() => '?').join(',');
+        const rows = await loader.cache.db.prepare(
+            `SELECT id, location FROM shapefiles WHERE id IN (${placeholders})`
+        ).all(...uniqueZones);
+        const locationMap = new Map<string, string>();
+        for (const row of rows) { locationMap.set(row.id, row.location) }
+        const locations = uniqueZones.map(id => locationMap.get(id) ?? id);
+        return locations.sort();
+    }
+
+    /**
+     * @function getCoordinates
+     * @description
+     *     Calculates the outer boundary coordinates for a set of UGC zones by
+     *     querying their geometries from the database, merging them, and extracting
+     *     the largest outer ring. The coordinates are downsampled based on a skip
+     *     setting to reduce complexity. Returns `null` if no valid coordinates are found.
+     *
+     * @static
+     * @param {string[]} zones
+     * @returns {[number, number][]}
+     */
+    public static getCoordinates(zones: string[], isUnion=true): any | null {
+        const list = [...new Set(zones.map(z => z.trim()))].filter(z => z === 'XX000' ? false : true);
+        if (list.length === 0) return null;
+        const placeholders = list.map(() => "?").join(",");
+        const rows = loader.cache.db
+            .prepare(`SELECT geometry FROM shapefiles WHERE id IN (${placeholders})`)
+            .all(...list);
+        const polygons: any[] = [];
+        for (const row of rows) {
+            if (!row?.geometry) continue;
+            const geom = JSON.parse(row.geometry);
+            if (geom?.type === "Polygon") {
+                polygons.push(geom.coordinates);
+            }
+        }
+        if (polygons.length === 0) return null;
+        if (isUnion) {
+            const unionFn = loader.packages.polygonClipping.union as (...polys: any[]) => any;
+            const mergedCoords = unionFn(...polygons);
+            if (!mergedCoords || mergedCoords.length === 0) return null;
+            let maxArea = -1;
+            let bestPoly: any[] = [];
+            for (const poly of mergedCoords) {
+                const outerRing = poly[0];
+                let area = 0;
+                for (let i = 0; i < outerRing.length - 1; i++) {
+                    const [x1, y1] = outerRing[i];
+                    const [x2, y2] = outerRing[i + 1];
+                    area += x1 * y2 - x2 * y1;
+                }
+                area = Math.abs(area / 2);
+                if (area > maxArea) {
+                    maxArea = area;
+                    bestPoly = poly;
+                }
+            }
+            if (!bestPoly || bestPoly.length === 0) return null;
+            const outerRing = bestPoly[0];
+            const skip = Math.max(1, parseInt(String(loader.settings.global_settings.shapefile_skip), 10) || 1);
+            let skipped = outerRing.filter((_: any, idx: number) => idx % skip === 0);
+            if (skipped.length < 4) {
+                skipped = outerRing.slice();
+            }
+            const first = skipped[0];
+            const last = skipped[skipped.length - 1];
+            if (!first || !last || first[0] !== last[0] || first[1] !== last[1]) {
+                skipped.push([first[0], first[1]]);
+            }
+            return {type: "Polygon", coordinates: [skipped]};
+        } else {
+            const multi: any[] = [];
+            for (const polyCoords of polygons) {
+                if (Array.isArray(polyCoords) && Array.isArray(polyCoords[0])) {
+                    multi.push(polyCoords);
+                }
+            }
+            if (multi.length === 0) return null;
+            const skip = Math.max(1, parseInt(String(loader.settings.global_settings.shapefile_skip), 10) || 1);
+            if (skip > 1) {
+                for (let p = 0; p < multi.length; p++) {
+                    for (let r = 0; r < multi[p].length; r++) {
+                        const ring = multi[p][r];
+                        let reduced = ring.filter((_: any, i: number) => i % skip === 0);
+                        if (reduced.length < 4) reduced = ring.slice();
+                        const first = reduced[0];
+                        const last = reduced[reduced.length - 1];
+                        if ( first && last && (first[0] !== last[0] || first[1] !== last[1])) {
+                            reduced.push([first[0], first[1]]);
+                        }
+                        multi[p][r] = reduced;
+                    }
+                }
+            }
+            return {type: "MultiPolygon", coordinates: multi};
+        }
+    }
+
+    /**
+     * @function getZones
+     * @description
+     *     Parses a UGC header string and returns an array of individual zone
+     *     identifiers. Handles ranges indicated with `>` and preserves the
+     *     state and format prefixes.
+     *
+     * @static
+     * @param {string} header
+     * @returns {string[]}
+     */
+    public static getZones(header: string): string[] {
+        const ugcSplit = header.split('-');
+        const zones: string[] = [];
+        let state = ugcSplit[0].substring(0, 2);
+        const format = ugcSplit[0].substring(2, 3);
+        for (const part of ugcSplit) {
+            if (/^[A-Z]/.test(part)) {
+                state = part.substring(0, 2);
+                if (part.includes('>')) {
+                    const [start, end] = part.split('>');
+                    const startNum = parseInt(start.substring(3), 10);
+                    const endNum = parseInt(end, 10);
+                    for (let j = startNum; j <= endNum; j++) {
+                        zones.push(`${state}${format}${j.toString().padStart(3, '0')}`);
+                    }
+                } else {
+                    zones.push(part);
+                }
+                continue;
+            }
+            if (part.includes('>')) {
+                const [start, end] = part.split('>');
+                const startNum = parseInt(start, 10);
+                const 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}${part}`);
+            }
+        }
+        return zones.filter(item => item !== '');
+    }
+}
+
+export default UGCParser;