@i-giann/open-meteo-wrapper 1.0.0

package/dist/services/weatherService.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Servicio principal para obtener y estructurar datos meteorológicos desde la API de Open-Meteo.
+ * Incluye manejo de errores y transformación de datos crudos mediante WeatherDataParser.
+ */
+import { FetchWeatherProps, StructureWeatherData, FetchError } from "../types/weatherTypes";
+import { IWeatherApiClient } from "./api/OpenMeteoClient";
+import { IWeatherAdapter } from "./adapters/OpenMeteoAdapter";
+/**
+ * Realiza una solicitud a la API de Open-Meteo para obtener datos meteorológicos.
+ * Devuelve los datos organizados mediante WeatherDataParser o un error estructurado.
+ *
+ * Flujo principal:
+ * 1. Construye la URL y realiza la solicitud a la API.
+ * 2. Si la respuesta es exitosa, transforma los datos crudos con WeatherDataParser.
+ * 3. Si hay error, retorna un objeto FetchError estandarizado.
+ * 4. Maneja timeout y errores inesperados.
+ *
+ * @param {FetchWeatherProps} params Parámetros de la consulta meteorológica
+ * @returns {Promise<StructureWeatherData | FetchError>} Datos meteorológicos organizados o error
+ */
+export declare const fetchWeather: (params: FetchWeatherProps, options?: {
+    client?: IWeatherApiClient;
+    adapter?: IWeatherAdapter;
+}) => Promise<StructureWeatherData | FetchError>;

package/dist/store/useWeatherStore.d.ts

@@ -0,0 +1,66 @@
+import { DailyWeatherData, FetchWeatherProps, HourlyWeatherData, StructureWeatherData, FetchError } from "../types/weatherTypes";
+export type WeatherFetcher = (params: FetchWeatherProps) => Promise<StructureWeatherData | FetchError>;
+export declare const setWeatherFetcher: (fetcher: WeatherFetcher) => void;
+/**
+ * Estado principal del store meteorológico.
+ */
+interface WeatherState {
+    /** Últimos datos meteorológicos obtenidos y organizados */
+    data: StructureWeatherData | null;
+    /** Indica si se está realizando una solicitud */
+    loading: boolean;
+    /** Último error producido en la consulta */
+    error: FetchError | null;
+    /** Si la actualización automática está activa */
+    autoRefresh: boolean;
+    /** Últimos parámetros usados para la consulta */
+    fetchParams: FetchWeatherProps | null;
+    /** Timestamp de la última consulta exitosa */
+    lastFetchTime: number | null;
+    /** Duración del caché en milisegundos */
+    cacheDuration: number;
+}
+/**
+ * Acciones y selectores del store meteorológico.
+ *
+ * `fetchWeather`: Realiza la consulta meteorológica y actualiza el estado.
+ * `isLoading`, `hasError`, `getError`, `clearError`: Métodos para manejar el estado de carga y errores.
+ * `setAutoRefresh`, `scheduleAutoRefresh`: Métodos para manejar la actualización automática de datos.
+ * `getAllWeatherData`, `getCurrentDayWeather`, `getPastDayWeather`, `getForecastWeather`, `getCurrentHourWeather`: Selectores para acceder a los datos meteorológicos organizados.
+ */
+interface WeatherActions {
+    fetchWeather: (params: FetchWeatherProps) => Promise<void>;
+    isLoading: () => boolean;
+    hasError: () => boolean;
+    getError: () => FetchError | null;
+    clearError: () => void;
+    setAutoRefresh: (value: boolean) => void;
+    scheduleAutoRefresh: () => void;
+    getAllWeatherData: () => StructureWeatherData | null;
+    getCurrentDayWeather: () => DailyWeatherData | null;
+    getPastDayWeather: () => DailyWeatherData[] | null;
+    getForecastWeather: () => DailyWeatherData[] | null;
+    getCurrentHourWeather: () => HourlyWeatherData | null;
+}
+export declare const useWeatherStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<WeatherState & WeatherActions>, "persist"> & {
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<WeatherState & WeatherActions, {
+            data: StructureWeatherData | null;
+            fetchParams: FetchWeatherProps | null;
+            lastFetchTime: number | null;
+            autoRefresh: boolean;
+        }>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: WeatherState & WeatherActions) => void) => () => void;
+        onFinishHydration: (fn: (state: WeatherState & WeatherActions) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<WeatherState & WeatherActions, {
+            data: StructureWeatherData | null;
+            fetchParams: FetchWeatherProps | null;
+            lastFetchTime: number | null;
+            autoRefresh: boolean;
+        }>>;
+    };
+}>;
+export {};

package/dist/types/apiTypes.d.ts

@@ -0,0 +1,23 @@
+import { HourlyParams } from "./weatherTypes";
+export interface WeatherData {
+    latitude: number;
+    longitude: number;
+    timezone: string;
+    timezone_abbreviation?: string;
+    current?: {
+        time: Date;
+    };
+    hourly: {
+        time: (string | Date)[];
+        temperature_2m: number[];
+        weather_code: number[];
+    } & Partial<Record<Exclude<HourlyParams, HourlyParams.Temperature | HourlyParams.WeatherCode>, number[]>>;
+    daily: {
+        time: (string | Date)[];
+        temperature_2m_max: number[];
+        temperature_2m_min: number[];
+        sunrise?: (string | Date)[];
+        sunset?: (string | Date)[];
+        daylight_duration?: number[];
+    };
+}

package/dist/types/weatherTypes.d.ts

@@ -0,0 +1,162 @@
+export declare enum MessageType {
+    SUCCESS = "success",
+    ERROR = "error",
+    WARNING = "warning",
+    INFO = "info"
+}
+export declare enum ErrorType {
+    NETWORK_ERROR = "network_error",
+    API_ERROR = "api_error",
+    DATA_ERROR = "data_error",
+    UNKNOWN_ERROR = "unknown_error"
+}
+export interface FetchError {
+    error: string;
+    status?: number;
+    type: MessageType;
+    errorType: ErrorType;
+    info?: string;
+}
+export declare enum HourlyParams {
+    Temperature = "temperature_2m",// En grados Celsius ºC
+    RelativeHumidity = "relative_humidity_2m",// En porcentaje %
+    DewPoint = "dew_point_2m",// En grados Celsius ºC (Punto rocio)
+    ApparentTemperature = "apparent_temperature",// En grados Celsius ºC (Sensación térmica)
+    PrecipitationProbability = "precipitation_probability",// En porcentaje %
+    Precipitation = "precipitation",// En milímetros mm
+    Rain = "rain",// En milímetros mm
+    Snowfall = "snowfall",// En milímetros cm
+    SnowDepth = "snow_depth",// En metros m
+    WeatherCode = "weather_code",// En código WMO
+    PressureMsl = "pressure_msl",// En hectopascales hPa
+    CloudCover = "cloud_cover",// En porcentaje %
+    Visibility = "visibility",// En metros m
+    WindSpeed = "wind_speed_10m",// En kilometros por hora km/h
+    WindDirection = "wind_direction_10m",// En grados
+    UvIndex = "uv_index",// Índice UV
+    IsDay = "is_day"
+}
+export declare enum DailyParams {
+    TemperatureMax = "temperature_2m_max",
+    TemperatureMin = "temperature_2m_min",
+    Sunrise = "sunrise",
+    Sunset = "sunset",
+    DaylightDuration = "daylight_duration"
+}
+export interface FetchWeatherProps {
+    latitude: number;
+    longitude: number;
+    hourly?: HourlyParams[];
+    daily?: DailyParams[];
+    timezone?: string;
+    past_days?: number;
+    forecast_days?: number;
+}
+export interface StructureWeatherData {
+    latitude: number;
+    longitude: number;
+    timezone: string;
+    pastDay: DailyWeatherData[];
+    currentDay: DailyWeatherData;
+    forecast: DailyWeatherData[];
+}
+export interface WeatherValue {
+    value: number;
+    unit: string;
+}
+export interface DateValue {
+    value: Date;
+    unit: string;
+}
+export interface TextValue {
+    value: string;
+    unit: string;
+}
+export interface WindData {
+    speed: WeatherValue;
+    direction?: WeatherValue;
+}
+export interface UVData {
+    value: number;
+    riskLevel: UvRiskLevels;
+    description: string;
+    unit: string;
+}
+export interface DailyWeatherData {
+    day?: DateValue;
+    hourly?: HourlyWeatherData[];
+    temperatureMax?: WeatherValue;
+    temperatureMin?: WeatherValue;
+    sunrise?: DateValue;
+    sunset?: DateValue;
+    daylightDuration?: WeatherValue;
+}
+export interface HourlyWeatherData {
+    hour?: DateValue;
+    temperature?: WeatherValue;
+    relativeHumidity?: WeatherValue;
+    dewPoint?: WeatherValue;
+    apparentTemperature?: WeatherValue;
+    precipitationProbability?: WeatherValue;
+    precipitation?: WeatherValue;
+    rain?: WeatherValue;
+    snowfall?: WeatherValue;
+    snowDepth?: WeatherValue;
+    weatherCode?: WeatherValue;
+    weatherDescription?: TextValue;
+    pressureMsl?: WeatherValue;
+    cloudCover?: WeatherValue;
+    visibility?: WeatherValue;
+    wind?: WindData;
+    uv?: UVData;
+    isDay?: WeatherValue;
+}
+export declare enum UvRiskLevels {
+    UNKNOWN = "Desconocido",
+    LOW = "Bajo",
+    MODERATE = "Moderado",
+    HIGH = "Alto"
+}
+/** Relación entre códigos WMO y su descripción meteorológica correspondiente.
+ * WMO Weather interpretation codes (WW)
+ * 0	Clear sky
+ * 1, 2, 3	Mainly clear, partly cloudy, and overcast
+ * 45, 48	Fog and depositing rime fog
+ * 51, 53, 55	Drizzle: Light, moderate, and dense intensity
+ * 56, 57	Freezing Drizzle: Light and dense intensity
+ * 61, 63, 65	Rain: Slight, moderate and heavy intensity
+ * 66, 67	Freezing Rain: Light and heavy intensity
+ * 71, 73, 75	Snow fall: Slight, moderate, and heavy intensity
+ * 77	Snow grains
+ * 80, 81, 82	Rain showers: Slight, moderate, and violent
+ * 85, 86	Snow showers slight and heavy
+ * 95	Thunderstorm: Slight or moderate
+ */
+export declare enum WeatherDescriptions {
+    clear_sky = "Cielo despejado",
+    mainly_clear = "Mayormente despejado",
+    partly_cloudy = "Parcialmente nublado",
+    overcast = "Mayormente nublado",
+    fog = "Niebla",
+    depositing_rime_fog = "Niebla con escarcha",
+    drizzle_light = "Llovizna ligera",
+    drizzle_moderate = "Llovizna moderada",
+    drizzle_dense = "Llovizna densa",
+    freezing_drizzle_light = "Llovizna helada ligera",
+    freezing_drizzle_dense = "Llovizna helada densa",
+    rain_slight = "Lluvia ligera",
+    rain_moderate = "Lluvia moderada",
+    rain_heavy = "Lluvia intensa",
+    freezing_rain_light = "Lluvia helada ligera",
+    freezing_rain_heavy = "Lluvia helada intensa",
+    snowfall_slight = "Nevada ligera",
+    snowfall_moderate = "Nevada moderada",
+    snowfall_heavy = "Nevada intensa",
+    snow_grains = "Precipitaci\u00F3n de granos de nieve",
+    rain_showers_slight = "Chubascos ligeros",
+    rain_showers_moderate = "Chubascos moderados",
+    rain_showers_violent = "Chubascos violentos",
+    snow_showers_slight = "Chubascos de nieve ligeros",
+    snow_showers_heavy = "Chubascos de nieve intensos",
+    thunderstorm = "Tormenta"
+}

package/dist/utils/constants.d.ts

@@ -0,0 +1,87 @@
+import { DailyParams, HourlyParams, WeatherDescriptions } from "../types/weatherTypes";
+/**
+ * URL base para las solicitudes de datos meteorológicos de Open-Meteo API.
+ */
+export declare const BASE_URL = "https://api.open-meteo.com/v1/forecast";
+/**
+ * Configuración por defecto para las solicitudes meteorológicas.
+ * Estos valores se usan cuando el usuario no especifica parámetros.
+ */
+export declare const WEATHER_CONSTANTS: {
+    /** Zona horaria por defecto para las consultas */
+    readonly DEFAULT_TIMEZONE: "America/Sao_Paulo";
+    /** Parámetros meteorológicos por hora solicitados por defecto */
+    readonly DEFAULT_HOURLY_PARAMS: HourlyParams[];
+    /** Parámetros meteorológicos diarios solicitados por defecto */
+    readonly DEFAULT_DAILY_PARAMS: DailyParams[];
+    /** Número de días pasados a incluir por defecto */
+    readonly DEFAULT_PAST_DAYS: 0;
+    /** Número de días de pronóstico a incluir por defecto */
+    readonly DEFAULT_FORECAST_DAYS: 7;
+    /** Duración del caché en milisegundos (10 minutos) */
+    readonly DEFAULT_CACHE_DURATION: number;
+    /** Timeout para las solicitudes HTTP en milisegundos */
+    readonly REQUEST_TIMEOUT: 10000;
+};
+/**
+ * Configuración de niveles de riesgo UV según la OMS.
+ * @see https://www.who.int/news-room/questions-and-answers/item/radiation-the-ultraviolet-(uv)-index
+ */
+export declare const UV_RISK_CONFIG: {
+    /** Rangos de índice UV para cada nivel de riesgo */
+    readonly RANGES: {
+        readonly Bajo: {
+            readonly min: 0;
+            readonly max: 2;
+        };
+        readonly Moderado: {
+            readonly min: 3;
+            readonly max: 7;
+        };
+        readonly Alto: {
+            readonly min: 8;
+            readonly max: number;
+        };
+    };
+    /** Descripciones de recomendaciones por nivel de riesgo UV */
+    readonly DESCRIPTIONS: {
+        readonly Desconocido: "No se puede determinar el riesgo de exposición";
+        readonly Bajo: "Puedes disfrutar de estar afuera con seguridad";
+        readonly Moderado: "Busca sombra durante las horas del mediodía. Ponte una remera, utiliza protector solar y un sombrero.";
+        readonly Alto: "Evita estar afuera durante las horas del mediodía. Asegúrate de buscar sombra. La remera, el protector solar y el sombrero son imprescindibles.";
+    };
+};
+/**
+ * Mapeo de códigos meteorológicos WMO a descripciones en español.
+ * @see https://www.nodc.noaa.gov/archive/arc0021/0002199/1.1/data/0-data/HTML/WMO-CODE/WMO4677.HTM
+ */
+export declare const WMO_WEATHER_CODES: Record<number, WeatherDescriptions>;
+/**
+ * Mapeo de parámetros meteorológicos a sus unidades correspondientes.
+ */
+export declare const UNITS: {
+    readonly time: "iso8601";
+    readonly hour: "iso8601";
+    readonly temperature_2m: "ºC";
+    readonly temperature_2m_max: "ºC";
+    readonly temperature_2m_min: "ºC";
+    readonly dew_point_2m: "ºC";
+    readonly apparent_temperature: "ºC";
+    readonly relative_humidity_2m: "%";
+    readonly precipitation_probability: "%";
+    readonly precipitation: "mm";
+    readonly rain: "mm";
+    readonly snowfall: "cm";
+    readonly snow_depth: "m";
+    readonly pressure_msl: "hPa";
+    readonly wind_speed_10m: "km/h";
+    readonly wind_direction_10m: "°";
+    readonly cloud_cover: "%";
+    readonly visibility: "km";
+    readonly weather_code: "wmo code";
+    readonly sunrise: "iso8601";
+    readonly sunset: "iso8601";
+    readonly daylight_duration: "h";
+    readonly uv_index: "index";
+    readonly is_day: "flag";
+};

package/dist/utils/utils.d.ts

@@ -0,0 +1,13 @@
+import { UvRiskLevels } from "../types/weatherTypes";
+/**
+ * Obtiene el nivel de riesgo UV basado en el índice UV.
+ * @param index - Índice UV.
+ * @returns Nivel de riesgo UV.
+ */
+export declare const getUvRiskLevel: (index: number) => UvRiskLevels;
+/**
+ * Obtiene la descripción del riesgo UV basado en el índice UV.
+ * @param index - Índice UV.
+ * @returns Descripción del riesgo UV.
+ */
+export declare const getUvDescription: (index: number) => string;

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@i-giann/open-meteo-wrapper",
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IaconoG/open-meteo-wrapper-npm.git"
+  },
+  "description": "Un wrapper completo para la API de Open-Meteo con hooks de React y servicios reutilizables",
+  "keywords": [
+    "weather",
+    "open-meteo",
+    "react",
+    "zustand",
+    "vite",
+    "typescript",
+    "weather-api",
+    "meteorology",
+    "forecast",
+    "climate"
+  ],
+  "author": "Giann Iacono <email@example.com>",
+  "homepage": "https://github.com/IaconoG/open-meteo-wrapper-npm#readme",
+  "bugs": {
+    "url": "https://github.com/IaconoG/open-meteo-wrapper-npm/issues"
+  },
+  "private": false,
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "module": "./dist/index.esm.js",
+  "sideEffects": false,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "npm run build:js && npm run build:types",
+    "build:js": "vite build",
+    "build:types": "tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "format": "prettier --write .",
+    "test": "jest"
+  },
+  "dependencies": {
+    "immer": "^10.1.1"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "zustand": "^5.0.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@testing-library/react": "^16.2.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^24.0.10",
+    "@types/react": "^19.1.8",
+    "@types/testing-library__react": "^10.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "eslint": "^9.39.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.18",
+    "globals": "^15.15.0",
+    "jest": "^29.7.0",
+    "jest-fixed-jsdom": "^0.0.9",
+    "jiti": "^2.6.1",
+    "msw": "^2.7.3",
+    "ts-jest": "^29.2.6",
+    "tsc-alias": "^1.8.15",
+    "typescript": "~5.7.2",
+    "typescript-eslint": "^8.54.0",
+    "vite": "^6.1.0"
+  }
+}