@adonix.org/nws-report/dist/index.d.ts

Generate weather reports from the National Weather Service

import { Geometry } from 'geojson';

declare abstract class NationalWeatherService<T> {
    private static _origin;
    static readonly headers: Headers;
    protected readonly headers: Headers;
    protected readonly params: URLSearchParams;
    static get origin(): string;
    static set origin(origin: string);
    get(): Promise<T>;
    protected abstract get resource(): string;
}

declare class Products extends NationalWeatherService<Product | undefined> {
    private readonly type;
    private readonly wfo;
    constructor(type: string, wfo: string);
    /**
     * If the product is not found, the NWS API still returns a JSON
     * object that is mostly empty. If not found, return undefined.
     */
    get(): Promise<Product | undefined>;
    protected get resource(): string;
}
interface Product {
    id: string;
    wmoCollectiveId: string;
    issuingOffice: string;
    issuanceTime: string;
    productCode: string;
    productName: string;
    productText: string;
}

declare class AlertAdminMessage extends Products {
    constructor();
}

interface QuantitativeValue {
    unitCode: string;
    value?: number | null;
    maxValue?: number;
    minValue?: number;
    qualityControl?: QualityControl;
}
type QualityControl = "Z" | "C" | "S" | "V" | "X" | "Q" | "G" | "B" | "T";

declare class Points extends NationalWeatherService<Gridpoint> {
    private readonly latitude;
    private readonly longitude;
    constructor(latitude: number, longitude: number);
    protected get resource(): string;
}
interface Gridpoint {
    id: string;
    type: string;
    geometry: Geometry;
    properties: GridpointProperties;
}
interface GridpointProperties {
    "@id": string;
    "@type": string;
    cwa: string;
    forecastOffice: string;
    gridId: string;
    gridX: number;
    gridY: number;
    forecast: string;
    forecastHourly: string;
    forecastGridData: string;
    observationStations: string;
    relativeLocation: RelativeLocation;
    forecastZone: string;
    county: string;
    fireWeatherZone: string;
    timeZone: string;
    radarStation: string;
}
interface RelativeLocation {
    type: string;
    geometry: Geometry;
    properties: RelativeLocationProperties;
}
interface RelativeLocationProperties {
    city: string;
    state: string;
    distance: QuantitativeValue;
    bearing: QuantitativeValue;
}

declare class SegmentedProducts {
    private readonly type;
    private readonly wfo;
    private readonly zone;
    private readonly filter;
    constructor(type: string, wfo: string, zone: string, filter: boolean);
    get(): Promise<SegmentedProduct | undefined>;
    protected doFilter(product: SegmentedProduct): SegmentedProduct;
}
interface SegmentedProduct {
    product: Product;
    header?: string;
    headline?: string;
    segments: ProductSegment[];
}
interface ProductSegment {
    zoneText: string;
    zones: string[];
    timestamp: string;
    body: string;
}

declare class LatestAlerts<A extends Alerts = Alerts> extends NationalWeatherService<A> {
    protected readonly point: Gridpoint;
    constructor(point: Gridpoint, status?: QueryStatus);
    get(): Promise<A>;
    protected get resource(): string;
    protected filter(features: AlertFeature[]): AlertFeature[];
}
declare class LatestAlertsProducts extends LatestAlerts<AlertsProducts> {
    get(): Promise<AlertsProducts>;
    private fetchProducts;
    static getAwipsId(feature: AlertFeature): string;
}
interface AlertsProducts extends Alerts {
    features: AlertFeatureProduct[];
}
interface AlertFeatureProduct extends AlertFeature {
    product?: SegmentedProduct;
}
interface Alerts {
    type: string;
    features: AlertFeature[];
    title: string;
    updated: string;
}
interface AlertFeature {
    id: string;
    type: string;
    geometry?: Geometry | null;
    properties: AlertProperties;
}
interface AlertProperties {
    "@id": string;
    "@type": string;
    id: string;
    areaDesc: string;
    geocode: Geocode;
    affectedZones: string[];
    references: Reference[];
    sent: string;
    effective: string;
    onset: string;
    expires: string;
    ends: string;
    status: AlertStatus;
    messageType: AlertMessageType;
    category: AlertCategory;
    severity: AlertSeverity;
    certainty: AlertCertainty;
    urgency: AlertUrgency;
    event: string;
    sender: string;
    senderName: string;
    headline: string;
    description: string;
    instruction: string;
    response: AlertResponse;
    parameters: AlertParameters;
    scope: AlertScope;
    code: string;
    language: string;
    web: string;
    eventCode: EventCode;
}
interface Geocode {
    SAME: string[];
    UGC: string[];
}
interface Reference {
    "@id": string;
    identifier: string;
    sender: string;
    sent: string;
}
interface CustomCode {
    [key: string]: string[] | undefined;
}
interface EventCode extends CustomCode {
    SAME?: string[];
    NationalWeatherService?: string[];
}
interface AlertParameters extends CustomCode {
    AWIPSidentifier?: string[];
    WMOidentifier?: string[];
    NWSheadline?: string[];
    BLOCKCHANNEL?: string[];
    "EAS-ORG"?: string[];
    VTEC?: string[];
    eventEndingTime?: string[];
    expiredReferences?: string[];
}
type AlertStatus = "Actual" | "Exercise" | "System" | "Test" | "Draft";
type QueryStatus = Lowercase<AlertStatus>;
type AlertMessageType = "Alert" | "Update" | "Cancel" | "Ack" | "Error";
type AlertCategory = "Met" | "Geo" | "Safety" | "Security" | "Rescue" | "Fire" | "Health" | "Env" | "Transport" | "Infra" | "CBRNE" | "Other";
type AlertSeverity = "Extreme" | "Severe" | "Moderate" | "Minor" | "Unknown";
type AlertCertainty = "Observed" | "Likely" | "Possible" | "Unlikely" | "Unknown";
type AlertUrgency = "Immediate" | "Expected" | "Future" | "Past" | "Unknown";
type AlertResponse = "Shelter" | "Evacuate" | "Prepare" | "Execute" | "Avoid" | "Monitor" | "Assess" | "AllClear" | "None";
type AlertScope = "Public" | "Restricted" | "Private";

declare abstract class NWSError extends Error {
    readonly url: URL;
    constructor(url: URL, message: string, cause: unknown);
}
declare class NWSFetchError extends NWSError {
    constructor(url: URL, cause: unknown);
}
declare class NWSResponseError extends Error {
    readonly url: URL;
    readonly status: number;
    readonly details: NWSProblemDetails;
    constructor(url: URL, status: number, details: NWSProblemDetails);
}
interface NWSProblemDetails {
    type: string;
    title: string;
    status: number;
    detail: string;
    instance: string;
    correlationId: string;
    parameterErrors?: NWSParameterError[];
}
interface NWSParameterError {
    parameter: string;
    message: string;
}
declare function isNWSProblemDetails(obj: unknown): obj is NWSProblemDetails;
declare class NWSJsonError extends Error {
    readonly url: URL;
    readonly status: number;
    readonly json: unknown;
    constructor(url: URL, status: number, json: unknown, cause?: unknown);
}
declare class HTTPError extends Error {
    readonly url: URL;
    readonly status: number;
    readonly statusText: string;
    constructor(url: URL, status: number, statusText: string, cause?: unknown);
}

declare abstract class BaseGridpointForecast<T> extends NationalWeatherService<T> {
    private readonly point;
    constructor(point: Gridpoint);
    protected abstract get endpoint(): string;
    protected get resource(): string;
}
declare class DailyForecast extends BaseGridpointForecast<GridpointDailyForecast> {
    protected get endpoint(): string;
}
declare class HourlyForecast extends BaseGridpointForecast<GridpointHourlyForecast> {
    protected get endpoint(): string;
}
type ForecastType = {
    daily: GridpointDailyForecast;
    hourly: GridpointHourlyForecast;
};
type GridpointDailyForecast = Forecast<GridpointDailyForecastPeriod>;
type GridpointHourlyForecast = Forecast<GridpointHourlyForecastPeriod>;
interface Forecast<P extends ForecastPeriod> {
    type: string;
    geometry: Geometry;
    properties: GridpointForecast<P>;
}
interface GridpointForecast<P extends ForecastPeriod> {
    units: string;
    forecastGenerator: string;
    generatedAt: string;
    updateTime: string;
    validTimes: string;
    elevation: QuantitativeValue;
    periods: P[];
}
interface ForecastPeriod {
    number: number;
    name: string;
    startTime: string;
    endTime: string;
    isDaytime: boolean;
    temperature: QuantitativeValue;
    temperatureTrend: string;
    windSpeed: QuantitativeValue;
    windDirection: string;
    windGust: QuantitativeValue | null;
    icon: string;
    shortForecast: string;
    detailedForecast: string;
    probabilityOfPrecipitation: QuantitativeValue;
}
interface GridpointDailyForecastPeriod extends ForecastPeriod {
}
interface GridpointHourlyForecastPeriod extends ForecastPeriod {
    dewpoint: QuantitativeValue;
    relativeHumidity: QuantitativeValue;
}

declare class LatestObservation extends NationalWeatherService<Observation> {
    private readonly station;
    constructor(station: string);
    protected get resource(): string;
}
declare class Observations extends NationalWeatherService<ObservationCollection> {
    private readonly station;
    constructor(station: string, limit?: number);
    protected get resource(): string;
}
interface ObservationCollection {
    type: string;
    features: Observation[];
}
interface Observation {
    id: string;
    type: string;
    geometry: Geometry;
    properties: ObservationProperties;
}
interface ObservationProperties {
    "@id": string;
    "@type": string;
    elevation: QuantitativeValue;
    station: string;
    stationID: string;
    stationName: string;
    timestamp: string;
    rawMessage: string;
    textDescription: string;
    presentWeather: MetarPhenomenon[];
    icon: string;
    temperature: QuantitativeValue;
    dewpoint: QuantitativeValue;
    windDirection: QuantitativeValue;
    windSpeed: QuantitativeValue;
    windGust: QuantitativeValue;
    barometricPressure: QuantitativeValue;
    seaLevelPressure: QuantitativeValue;
    visibility: QuantitativeValue;
    maxTemperatureLast24Hours: QuantitativeValue;
    minTemperatureLast24Hours: QuantitativeValue;
    precipitationLastHour: QuantitativeValue;
    precipitationLast3Hours: QuantitativeValue;
    precipitationLast6Hours: QuantitativeValue;
    relativeHumidity: QuantitativeValue;
    windChill: QuantitativeValue;
    heatIndex: QuantitativeValue;
    cloudLayers: CloudLayer[];
}
interface MetarPhenomenon {
    intensity: string | null;
    modifier: string | null;
    rawString: string;
    weather: WeatherPhenomenon;
    inVicinity?: boolean;
}
interface CloudLayer {
    base: QuantitativeValue;
    amount: string;
}
type WeatherPhenomenon = "fog_mist" | "dust_storm" | "dust" | "drizzle" | "funnel_cloud" | "fog" | "smoke" | "hail" | "snow_pellets" | "haze" | "ice_crystals" | "ice_pellets" | "dust_whirls" | "spray" | "rain" | "sand" | "snow_grains" | "snow" | "squalls" | "sand_storm" | "thunderstorms" | "unknown" | "volcanic_ash";

declare class Stations extends NationalWeatherService<StationCollection> {
    private readonly point;
    constructor(point: Gridpoint, limit?: number);
    protected get resource(): string;
}
interface StationCollection {
    type: string;
    features: Station[];
    observationStations: string[];
    pagination: Pagination;
}
interface Station {
    id: string;
    type: string;
    geometry: Geometry;
    properties: StationProperties;
}
interface StationProperties {
    id: string;
    type: string;
    elevation: QuantitativeValue;
    stationIdentifier: string;
    name: string;
    timeZone: string;
    provider: string;
    subProvider: string;
    distance: QuantitativeValue;
    bearing: QuantitativeValue;
    forecast: string;
    county: string;
    fireWeatherZone: string;
}
interface Pagination {
    next: string;
}

declare class WeatherReport {
    private readonly latitude;
    private readonly longitude;
    private readonly forecastType;
    private _point?;
    private _station?;
    private _current?;
    private _forecast?;
    private _products;
    private _hwo?;
    private _alerts?;
    static create(latitude: number, longitude: number, forecast?: keyof ForecastType): Promise<WeatherReport>;
    private constructor();
    get point(): Gridpoint | undefined;
    get station(): Station | undefined;
    get current(): Observation | undefined;
    get forecast(): GridpointDailyForecast | GridpointHourlyForecast | undefined;
    get alerts(): AlertsProducts | undefined;
    get hwo(): SegmentedProduct | undefined;
    get products(): SegmentedProduct[];
    refresh(): Promise<void>;
}

declare class Units {
    static to_number(quant?: QuantitativeValue): number | undefined;
    static c_to_f(celsius: number): number;
    static meters_to_miles(meters: number): number;
    static degrees_to_cardinal(degrees: number): string;
    static kmh_to_mph(kmh: number): number;
    static pascals_to_inches(pascals: number): number;
    static pascals_to_mb(pascals: number): number;
}

export { AlertAdminMessage, type AlertFeature, type AlertFeatureProduct, type Alerts, type AlertsProducts, DailyForecast, type ForecastPeriod, type ForecastType, type Gridpoint, type GridpointDailyForecast, type GridpointHourlyForecast, HTTPError, HourlyForecast, LatestAlerts, LatestAlertsProducts, LatestObservation, NWSFetchError, NWSJsonError, type NWSProblemDetails, NWSResponseError, NationalWeatherService, type Observation, type ObservationCollection, Observations, Points, type Product, type ProductSegment, Products, type QuantitativeValue, type SegmentedProduct, SegmentedProducts, type Station, type StationCollection, Stations, Units, WeatherReport, isNWSProblemDetails };