@atmosx/event-product-parser 2.0.1

package/src/index.ts

@@ -0,0 +1,218 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| "_ ` _ \ / _ \/ __| "_ \| "_ \ / _ \ "__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: KiyoWx (k3yomi)                
+*/
+
+import * as loader from './bootstrap';
+import * as types from './types';
+import Utils from './@submodules/utils';
+import Xmpp from './@submodules/xmpp';
+import EAS from './@submodules/eas';
+import Database from './@submodules/database';
+import StanzaParser from './@parsers/stanza';
+import EventParser from './@parsers/events';
+import TextParser from './@parsers/text';
+import PVtecParser from './@parsers/pvtec';
+import HVtecParser from './@parsers/hvtec';
+import UGCParser from './@parsers/ugc';
+
+export class Manager { 
+    isNoaaWeatherWireService: boolean
+    job: any
+    constructor(metadata: types.ClientSettingsTypes) { this.start(metadata) }
+    
+    /**
+     * @function setDisplayName
+     * @description
+     *     Sets the display nickname for the NWWS XMPP session. Trims the provided
+     *     name and validates it, emitting a warning if the name is empty or invalid.
+     *
+     * @param {string} [name]
+     */
+    public setDisplayName(name?: string) {
+        const settings = loader.settings as types.ClientSettingsTypes;
+        const trimmed = name?.trim();
+        if (!trimmed) {
+            Utils.warn(loader.definitions.messages.invalid_nickname);
+            return;
+        }
+        settings.noaa_weather_wire_service_settings.credentials.nickname = trimmed;
+    }
+
+    /**
+     * @function getEventPolygon
+     * @description
+     *    Retrieves the geographical polygon for a given event based on its
+     *    generated geocode and UGC zones.
+     * 
+     * @async
+     * @param {types.EventCompiled} event
+     * @returns {Promise<types.geometry | null>}
+     */
+    public async getEventPolygon(event: types.EventCompiled, isUnion: boolean = true): Promise<types.geometry | null> {
+        const hasGenerated = event.properties.geocode?.generated ?? null;
+        const getUgc = event.properties.geocode?.UGC ?? null;
+        return await EventParser.getEventGeometry(hasGenerated, {zones: getUgc}, isUnion);
+    }
+
+    /**
+     * @function createEasAudio
+     * @description
+     *     Generates an EAS (Emergency Alert System) audio file using the provided
+     *     description and header.
+     *
+     * @async
+     * @param {string} description
+     * @param {string} header
+     * @returns {Promise<string>}
+     */
+    public async createEasAudio(description: string, header: string): Promise<string> {
+        return await EAS.generateEASAudio(description, header);
+    }
+
+    /**
+     * @function getAllAlertTypes
+     * @description
+     *     Generates a list of all possible alert types by combining defined
+     *     event names with action names.
+     *
+     * @returns {string[]}
+     */
+    public getAllAlertTypes(): string[] {
+        const events = new Set(Object.values(loader.definitions.events));
+        const actions = new Set(Object.values(loader.definitions.actions));
+        return Array.from(events).flatMap(event =>
+            Array.from(actions).map(action => `${event} ${action}`)
+        );
+    }
+
+    /**
+     * @function searchStanzaDatabase
+     * @description
+     *     Searches the stanza database for entries containing the specified query.
+     *     Escapes SQL wildcard characters and returns results in descending order
+     *     by ID, up to the specified limit.
+     *
+     * @async
+     * @param {string} query
+     * @param {number} [limit=250]
+     * @returns {Promise<string[]>}
+     */
+    public async searchStanzaDatabase(query: string, limit: number = 250): Promise<string[]> {
+        const escapeLike = (s: string) => s.replace(/[%_]/g, '\\$&');
+        const rows = await loader.cache.db
+            .prepare(`SELECT * FROM stanzas WHERE stanza LIKE ? ESCAPE '\\' ORDER BY id DESC LIMIT ${limit}`)
+            .all(`%${escapeLike(query)}%`);
+        return rows;
+    }
+
+    /**
+     * @function setSettings
+     * @description
+     *     Merges the provided client settings into the current configuration,
+     *     preserving nested structures.
+     *
+     * @async
+     * @param {types.ClientSettingsTypes} settings
+     * @returns {Promise<void>}
+     */
+    public async setSettings(settings: types.ClientSettingsTypes): Promise<void> {
+        Utils.mergeClientSettings(loader.settings, settings);
+    }
+
+    /**
+     * @function on
+     * @description
+     *     Registers a callback for a specific event and returns a function
+     *     to unregister the listener.
+     *
+     * @param {string} event
+     * @param {(...args: any[]) => void} callback
+     * @returns {() => void}
+     */
+    public on(event: string, callback: (...args: any[]) => void): () => void {
+        loader.cache.events.on(event, callback);
+        return () => loader.cache.events.off(event, callback);
+    }
+
+    /**
+     * @function start
+     * @description
+     *     Initializes the client with the provided settings, starts the NWWS XMPP
+     *     session if applicable, loads cached messages, and sets up scheduled
+     *     tasks (cron jobs) for ongoing processing.
+     *
+     * @async
+     * @param {types.ClientSettingsTypes} metadata
+     * @returns {Promise<void>}
+     */
+    public async start(metadata: types.ClientSettingsTypes): Promise<void> {
+        if (!loader.cache.isReady) { 
+            Utils.warn(loader.definitions.messages.not_ready);
+            return;
+        }
+        this.setSettings(metadata);
+        const settings = loader.settings as types.ClientSettingsTypes;
+        this.isNoaaWeatherWireService = settings.is_wire;
+        loader.cache.isReady = false;
+        await Database.loadDatabase();
+        if (this.isNoaaWeatherWireService) {
+            (async () => {
+                try {
+                    await Xmpp.deploySession();
+                    await Utils.loadCollectionCache();
+                } catch (err: unknown) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    Utils.warn(`Failed to initialize NWWS services: ${msg}`);
+                }
+            })();
+        }
+        Utils.handleCronJob(this.isNoaaWeatherWireService);
+        if (this.job) {
+            try { this.job.stop(); } catch { Utils.warn(`Failed to stop existing cron job.`); }
+            this.job = null;
+        }
+        const interval = !this.isNoaaWeatherWireService ? settings.national_weather_service_settings.interval : 5;
+        this.job = new loader.packages.jobs.Cron(`*/${interval} * * * * *`, () => { 
+            Utils.handleCronJob(this.isNoaaWeatherWireService);
+        });
+    }
+
+    /**
+     * @function stop
+     * @description
+     *     Stops active scheduled tasks (cron job) and, if connected, the NWWS
+     *     XMPP session. Updates relevant cache flags to indicate the session
+     *     is no longer active.
+     *
+     * @async
+     * @returns {Promise<void>}
+     */
+    public async stop(): Promise<void> {
+        loader.cache.isReady = true;
+        if (this.job) {
+            try { this.job.stop(); } catch { Utils.warn(`Failed to stop cron job.`); }
+            this.job = null;
+        }
+        const session = loader.cache.session;
+        if (session && this.isNoaaWeatherWireService) {
+            try { await session.stop(); } catch { Utils.warn(`Failed to stop XMPP session.`); }
+            loader.cache.sigHalt = true;
+            loader.cache.isConnected = false;
+            loader.cache.session = null;
+            this.isNoaaWeatherWireService = false;
+        }
+    }
+}
+
+export default Manager;
+export type * as types from './types';
+export { StanzaParser, EventParser, TextParser, PVtecParser, HVtecParser, UGCParser, EAS, Database, Utils };

package/src/types.ts

@@ -0,0 +1,259 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| '_ ` _ \ / _ \/ __| '_ \| '_ \ / _ \ '__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: k3yomi@GitHub                        
+*/
+
+// ----------- Settings ----------- //
+interface LocalEasSettings {
+    directory?: string;
+    intro_wav?: string;
+}
+
+interface LocalAlertFilteringSettings { 
+    events?: string[]; 
+    filtered_icao?: string[]; 
+    ignored_icao?: string[]; 
+    ugc_filter?: string[]; 
+    state_filter?: string[]; 
+    ignored_events?: string[]; 
+    check_expired?: boolean;
+}
+
+interface LocalGlobalSettings {
+    parent_events_only?: boolean;
+    better_event_parsing?: boolean;
+    shapefile_coordinates?: boolean;
+    shapefile_skip?: number;
+    eas_settings?: LocalEasSettings;
+    filtering?: LocalAlertFilteringSettings;
+}
+
+interface LocalClientReconnectionSettings { 
+    enabled?: boolean;
+    interval?: number;
+}
+
+interface LocalClientCredentialSettings {
+    username?: string;
+    password?: string;
+    nickname?: string;
+}
+
+interface LocalCacheSettings { 
+    enabled?: boolean;
+    max_db_history?: number;
+    use_db_for_cache?: boolean;
+    max_db_cache_size?: number;
+}
+
+interface LocalAlertPreferenceSettings {
+    disable_ugc?: boolean;
+    disable_vtec?: boolean;
+    disable_text?: boolean;
+    cap_only?: boolean;
+}
+
+interface LocalNoaaWeatherWireServiceSettings {
+    reconnection_settings?: LocalClientReconnectionSettings;
+    credentials?: LocalClientCredentialSettings;
+    cache?: LocalCacheSettings;
+    preferences?: LocalAlertPreferenceSettings;
+}
+
+interface LocalNationalWeatherServiceSettings {
+    interval?: number;
+    endpoint?: string;
+}
+
+// --- Exports --- //
+export interface ClientSettingsTypes {
+    database?: string;
+    is_wire?: boolean;
+    journal?: boolean;
+    noaa_weather_wire_service_settings?: LocalNoaaWeatherWireServiceSettings;
+    national_weather_service_settings?: LocalNationalWeatherServiceSettings;
+    global_settings?: LocalGlobalSettings;
+}
+
+
+// ----------- Alert / Events ----------- //
+
+
+interface LocalEventHistory { 
+    description?: string;
+    issued?: string;
+    type?: string;
+}
+
+
+interface LocalEventParameters {
+    wmo?: string;
+    source?: string;
+    max_hail_size?: string;
+    max_wind_gust?: string;
+    damage_threat?: string;
+    tornado_detection?: string;
+    flood_detection?: string;
+    discussion_tornado_intensity?: string;
+    discussion_wind_intensity?: string;
+    discussion_hail_intensity?: string;
+    WMOidentifier?: string[];
+    VTEC?: string;
+    maxHailSize?: string;
+    maxWindGust?: string;
+    thunderstormDamageThreat?: string[];
+    tornadoDetection?: string[];
+    waterspoutDetection?: string[];
+    floodDetection?: string[];
+    AWIPSidentifier?: string[];
+    NWSheadline?: string[];
+}
+
+interface LocalEventProperties { 
+    parent?: string;
+    event?: string; 
+    locations?: string;
+    issued?: string;
+    expires?: string;
+    geocode?: { 
+        UGC: string[], 
+        generated?: string | null 
+    };
+    description?: string;
+    instruction?: string;
+    sender_name?: string;
+    sender_icao?: string;
+    raw?: DefaultAttributesType;
+    parameters?: LocalEventParameters;
+    messageType?: string;
+    sent?: string;
+    areaDesc?: string;
+    action_type?: string;
+    is_updated?: boolean;
+    is_cancelled?: boolean;
+    is_issued?: boolean;
+    is_test?: boolean;
+    hash?: string;
+    tags?: string[];
+    details?: Record<string, any>;
+}
+
+// --- Exports --- //
+
+export interface StanzaAttributesType {
+    xmlns?: string; 
+    id?: string; 
+    issue?: string; 
+    ttaaii?: string; 
+    cccc?: string; 
+    awipsid?: string; 
+}
+export interface DefaultAttributesType {
+    attributes?: {
+        xmlns?: string; 
+        id?: string; 
+        issue?: string; 
+        ttaaii?: string; 
+        cccc?: string; 
+        awipsid?: string; 
+    }
+    getAwip?: Record<string, string>;
+    awipsType?: Record<string, string>;
+    isCap?: boolean;
+    raw?: boolean;
+}
+
+export interface StanzaCompiled { 
+    message?: string;
+    attributes?: DefaultAttributesType;
+    isCap?: boolean;
+    isApi?: boolean;
+    isCapDescription?: boolean;
+    isPVtec?: boolean;
+    isUGC?: boolean;
+    getAwip?: Record<string, string>;
+    awipsType?: Record<string, string>;
+    awipsPrefix?: string;
+    ignore?: boolean;
+    awipsid?: string;
+}
+
+export interface PVtecEntry { 
+    raw?: string;
+    type?: string;
+    tracking?: string;
+    event?: string;
+    status?: string;
+    wmo?: string;
+    expires?: Date | string;
+    isKWNS?: boolean;
+}
+
+export interface UGCEntry { 
+    zones?: string[];
+    locations?: string[];
+    expiry?: Date | string;
+    polygon?: [number, number][];
+}
+
+export interface HVtecEntry { 
+    severity?: string,
+    cause?: string,
+    record?: string,
+    raw?: string,
+}
+
+export interface geometry { 
+    type?: string;
+    coordinates?: [number, number][];
+}
+
+
+export interface EventCompiled {
+    performance?: number;
+    id?: string;
+    tracking?: string;
+    header?: string;
+    pvtec?: string;
+    hvtec?: string;
+    history?: LocalEventHistory[];
+    properties?: LocalEventProperties
+    geometry?: { type?: string; coordinates?: [number, number][] } | null;
+}
+
+export type EventProperties = LocalEventProperties;
+export type StanzaAttributes = DefaultAttributesType;
+
+
+// ----------- Generic ----------- //
+
+// --- Exports --- //
+export type Coordinates = { 
+    lon: number; 
+    lat: number;
+}
+
+export type HTTPSettings = { 
+    timeout?: number;
+    headers?: Record<string, string>;
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    body?: string;
+}
+
+export interface EnhancedEventCondition {
+    description?: string; 
+    condition?: (value: string) => boolean; 
+}
+
+export interface GenericHTTPResponse { 
+    error?: boolean,
+    message?: { features: Record<string, any>[] } | string,
+}