meteo-lt-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Giedrius Macevičius
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+# meteo-lt-sdk
+
+TypeScript SDK for the [Meteo.lt API](https://api.meteo.lt/) - Lithuanian Hydrometeorological Service (LHMT).
+
+## Features
+
+- 🎯 **Full Type Safety** - Strict TypeScript types with branded types for coordinates
+- ✅ **Runtime Validation** - Zod schemas validate all API responses
+- 🌳 **Tree-shakeable** - Modular design for optimal bundle size
+- 📚 **Comprehensive TSDoc** - IntelliSense-friendly documentation
+- ⚡ **Zero Dependencies** - Only Zod for runtime validation
+- 🔒 **Error Handling** - Custom error classes for different failure modes
+
+## Installation
+
+```bash
+npm install meteo-lt-sdk
+```
+
+## Quick Start
+
+```typescript
+import { MeteoClient } from "meteo-lt-sdk";
+
+const client = new MeteoClient();
+
+// Get weather forecast for Vilnius
+const forecast = await client.places.getForecast("vilnius", "long-term");
+console.log(`Temperature: ${forecast.forecastTimestamps[0]?.airTemperature}°C`);
+
+// Get latest observations from a weather station
+const observations = await client.stations.getObservations(
+  "vilniaus-ams",
+  "latest"
+);
+
+// Get water level data
+const hydroData = await client.hydroStations.getMeasuredObservations(
+  "nemajunu-vms",
+  "latest"
+);
+```
+
+## API Reference
+
+### MeteoClient
+
+Main entry point for the SDK.
+
+```typescript
+const client = new MeteoClient({
+  timeout: 10000, // Optional: request timeout in ms (default: 30000)
+  throttle: true, // Optional: enable rate limiting (default: false)
+  headers: { "X-Custom-Header": "value" }, // Optional: custom headers
+});
+```
+
+### Rate Limiting
+
+The API limits requests to **180 per minute** per IP. Enable automatic rate limiting to prevent hitting this limit:
+
+```typescript
+const client = new MeteoClient({ throttle: true });
+
+// Multiple client instances share the same global rate limiter
+const client1 = new MeteoClient({ throttle: true });
+const client2 = new MeteoClient({ throttle: true });
+// Both clients share the same 180 req/min budget
+```
+
+**How it works:**
+
+- Uses a **60-second sliding window** - each request "reserves" a slot for 60 seconds
+- **Time-based, not completion-based** - slots are used when requests _start_, not when they finish
+- **Queuing, not dropping** - excess requests wait in a queue until slots are available
+
+**Example:** If you fire 200 requests at once at `t=0`:
+
+- 180 start immediately (parallel execution)
+- 20 queue and wait for slots to expire
+- At `t=60s`, all 180 slots expire → 20 queued requests proceed
+
+### Places API
+
+Access weather forecasts for Lithuanian cities and towns.
+
+```typescript
+// List all available places
+const places = await client.places.getAll();
+
+// Get place details
+const place = await client.places.get("vilnius");
+
+// Get available forecast types
+const forecastTypes = await client.places.getForecastTypes("vilnius");
+
+// Get weather forecast
+const forecast = await client.places.getForecast("vilnius", "long-term");
+```
+
+#### Forecast Data
+
+Each forecast timestamp includes:
+
+- `airTemperature` - Air temperature (°C)
+- `feelsLikeTemperature` - Feels-like temperature (°C)
+- `windSpeed` - Wind speed (m/s)
+- `windGust` - Wind gust (m/s)
+- `windDirection` - Wind direction (0° = north, 180° = south)
+- `cloudCover` - Cloud cover (0-100%)
+- `seaLevelPressure` - Pressure at sea level (hPa)
+- `relativeHumidity` - Relative humidity (%)
+- `totalPrecipitation` - Precipitation amount (mm)
+- `conditionCode` - Weather condition code
+
+### Stations API
+
+Access meteorological observation data from weather stations.
+
+```typescript
+// List all stations
+const stations = await client.stations.getAll();
+
+// Get station details
+const station = await client.stations.get("vilniaus-ams");
+
+// Get data availability info
+const info = await client.stations.getObservationsInfo("vilniaus-ams");
+
+// Get observations for a specific date
+const observations = await client.stations.getObservations(
+  "vilniaus-ams",
+  "2024-01-15"
+);
+
+// Get latest 24-hour observations
+const latest = await client.stations.getObservations("vilniaus-ams", "latest");
+```
+
+### Hydro Stations API
+
+Access hydrological observation data from water monitoring stations.
+
+```typescript
+// List all hydro stations
+const stations = await client.hydroStations.getAll();
+
+// Get station details
+const station = await client.hydroStations.get("nemajunu-vms");
+
+// Get current year (measured) observations
+const measured = await client.hydroStations.getMeasuredObservations(
+  "nemajunu-vms",
+  "latest"
+);
+
+// Get historical observations
+const historical = await client.hydroStations.getHistoricalObservations(
+  "nemajunu-vms",
+  "2024-06"
+);
+```
+
+## Error Handling
+
+The SDK provides specific error classes for different failure scenarios:
+
+```typescript
+import {
+  MeteoNotFoundError,
+  MeteoRateLimitError,
+  MeteoNetworkError,
+  MeteoTimeoutError,
+  MeteoValidationError,
+} from "meteo-lt-sdk";
+
+try {
+  const forecast = await client.places.getForecast(
+    "invalid-place",
+    "long-term"
+  );
+} catch (error) {
+  if (error instanceof MeteoNotFoundError) {
+    console.log("Place not found:", error.resource);
+  } else if (error instanceof MeteoRateLimitError) {
+    console.log("Rate limited, retry after:", error.retryAfterSeconds);
+  } else if (error instanceof MeteoNetworkError) {
+    console.log("Network error:", error.message);
+  } else if (error instanceof MeteoTimeoutError) {
+    console.log("Request timed out after:", error.timeoutMs, "ms");
+  } else if (error instanceof MeteoValidationError) {
+    console.log("Invalid response:", error.validationErrors);
+  }
+}
+```
+
+## Weather Condition Codes
+
+The SDK exports condition code utilities:
+
+```typescript
+import {
+  FORECAST_CONDITION_CODES,
+  OBSERVATION_CONDITION_CODES,
+  getConditionDescription,
+  isForecastConditionCode,
+} from "meteo-lt-sdk";
+
+// Get human-readable description
+const description = getConditionDescription("partly-cloudy"); // 'Partly cloudy'
+
+// Type guard
+if (isForecastConditionCode(value)) {
+  // value is ForecastConditionCode
+}
+```
+
+## Types
+
+All types are exported for use in your application:
+
+```typescript
+import type {
+  PlaceSummary,
+  PlaceDetails,
+  Forecast,
+  ForecastTimestamp,
+  StationSummary,
+  Observation,
+  HydroStationSummary,
+  MeasuredHydroObservation,
+  Coordinates,
+} from "meteo-lt-sdk";
+```
+
+## Advanced Usage
+
+### Custom Fetch Implementation
+
+```typescript
+const client = new MeteoClient({
+  fetch: customFetch, // Custom fetch function
+});
+```
+
+### Direct Schema Access
+
+For advanced validation needs, schemas are exported:
+
+```typescript
+import { schemas } from "meteo-lt-sdk";
+
+const result = schemas.forecastSchema.safeParse(data);
+```
+
+### Subpath Imports
+
+For tree-shaking, you can import from subpaths:
+
+```typescript
+import { MeteoClient } from "meteo-lt-sdk/client";
+import type { Forecast } from "meteo-lt-sdk/types";
+```
+
+## Rate Limits
+
+The API has the following limits:
+
+- **180 requests per minute** per IP address
+- **20,000 requests per day** recommended maximum per IP
+
+Exceeding these limits may result in temporary IP blocking. **Enable `throttle: true`** to stay within the per-minute limit. The daily limit is not enforced by the SDK.
+
+## License
+
+MIT
+
+## Credits
+
+Data provided by the [Lithuanian Hydrometeorological Service (LHMT)](https://www.meteo.lt/) under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).

package/dist/__tests__/test-utils.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Test utilities and mock helpers for Meteo.lt SDK tests.
+ */
+import type { ResolvedMeteoClientConfig } from '../client/config.js';
+/**
+ * Creates a mock fetch function that returns the specified response.
+ */
+export declare function createMockFetch(response: unknown, options?: {
+    status?: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+}): typeof globalThis.fetch;
+/**
+ * Creates a mock fetch that throws a network error.
+ */
+export declare function createNetworkErrorFetch(message?: string): typeof globalThis.fetch;
+/**
+ * Creates a mock fetch that times out via AbortController.
+ */
+export declare function createTimeoutFetch(): typeof globalThis.fetch;
+/**
+ * Creates a resolved config with a mock fetch.
+ */
+export declare function createMockConfig(mockFetch: typeof globalThis.fetch, overrides?: Partial<ResolvedMeteoClientConfig>): ResolvedMeteoClientConfig;
+/**
+ * Sample data for testing places API.
+ */
+export declare const MOCK_PLACES: {
+    code: string;
+    name: string;
+    administrativeDivision: string;
+    countryCode: string;
+    coordinates: {
+        latitude: number;
+        longitude: number;
+    };
+}[];
+export declare const MOCK_PLACE_DETAILS: {
+    code: string;
+    name: string;
+    administrativeDivision: string;
+    country: string;
+    countryCode: string;
+    coordinates: {
+        latitude: number;
+        longitude: number;
+    };
+};
+export declare const MOCK_FORECAST_TYPES: {
+    place: {
+        code: string;
+        name: string;
+        administrativeDivision: string;
+        country: string;
+        countryCode: string;
+        coordinates: {
+            latitude: number;
+            longitude: number;
+        };
+    };
+    forecastTypes: {
+        type: string;
+        description: string;
+    }[];
+};
+export declare const MOCK_FORECAST: {
+    place: {
+        code: string;
+        name: string;
+        administrativeDivision: string;
+        country: string;
+        countryCode: string;
+        coordinates: {
+            latitude: number;
+            longitude: number;
+        };
+    };
+    forecastType: string;
+    forecastCreationTimeUtc: string;
+    forecastTimestamps: {
+        forecastTimeUtc: string;
+        airTemperature: number;
+        feelsLikeTemperature: number;
+        windSpeed: number;
+        windGust: number;
+        windDirection: number;
+        cloudCover: number;
+        seaLevelPressure: number;
+        relativeHumidity: number;
+        totalPrecipitation: number;
+        conditionCode: string;
+    }[];
+};
+/**
+ * Sample data for testing stations API.
+ */
+export declare const MOCK_STATIONS: {
+    code: string;
+    name: string;
+    coordinates: {
+        latitude: number;
+        longitude: number;
+    };
+}[];
+export declare const MOCK_STATION_DETAILS: {
+    code: string;
+    name: string;
+    type: string;
+    coordinates: {
+        latitude: number;
+        longitude: number;
+    };
+};
+export declare const MOCK_STATION_OBS_INFO: {
+    station: {
+        code: string;
+        name: string;
+        coordinates: {
+            latitude: number;
+            longitude: number;
+        };
+    };
+    observationsDataRange: {
+        startTimeUtc: string;
+        endTimeUtc: string;
+    };
+};
+export declare const MOCK_OBSERVATIONS: {
+    station: {
+        code: string;
+        name: string;
+        coordinates: {
+            latitude: number;
+            longitude: number;
+        };
+    };
+    observations: {
+        observationTimeUtc: string;
+        airTemperature: number;
+        feelsLikeTemperature: number;
+        windSpeed: number;
+        windGust: number;
+        windDirection: number;
+        cloudCover: number;
+        seaLevelPressure: number;
+        relativeHumidity: number;
+        precipitation: number;
+        conditionCode: string;
+    }[];
+};
+/**
+ * Sample data for testing hydro stations API.
+ */
+export declare const MOCK_HYDRO_STATIONS: {
+    code: string;
+    name: string;
+    waterBody: string;
+    coordinates: {
+        latitude: number;
+        longitude: number;
+    };
+}[];
+export declare const MOCK_HYDRO_OBS_TYPES: {
+    station: {
+        code: string;
+        name: string;
+        waterBody: string;
+        coordinates: {
+            latitude: number;
+            longitude: number;
+        };
+    };
+    observationTypes: {
+        type: string;
+        description: string;
+    }[];
+};
+export declare const MOCK_HYDRO_MEASURED_INFO: {
+    station: {
+        code: string;
+        name: string;
+        waterBody: string;
+        coordinates: {
+            latitude: number;
+            longitude: number;
+        };
+    };
+    observationsDataRange: {
+        startTimeUtc: string;
+        endTimeUtc: string;
+    };
+};
+export declare const MOCK_HYDRO_HISTORICAL_INFO: {
+    station: {
+        code: string;
+        name: string;
+        waterBody: string;
+        coordinates: {
+            latitude: number;
+            longitude: number;
+        };
+    };
+    observationsDataRange: {
+        startDateUtc: string;
+        endDateUtc: string;
+    };
+};
+export declare const MOCK_HYDRO_MEASURED_OBS: {
+    station: {
+        code: string;
+        name: string;
+        waterBody: string;
+        coordinates: {
+            latitude: number;
+            longitude: number;
+        };
+    };
+    observations: {
+        observationTimeUtc: string;
+        waterLevel: number;
+        waterTemperature: number;
+    }[];
+};
+export declare const MOCK_HYDRO_HISTORICAL_OBS: {
+    station: {
+        code: string;
+        name: string;
+        waterBody: string;
+        coordinates: {
+            latitude: number;
+            longitude: number;
+        };
+    };
+    observations: {
+        observationDateUtc: string;
+        waterLevel: number;
+        waterDischarge: number;
+    }[];
+};
+//# sourceMappingURL=test-utils.d.ts.map

package/dist/__tests__/test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../src/__tests__/test-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAErE;;GAEG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,OAAO,EACjB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAO,GACvF,OAAO,UAAU,CAAC,KAAK,CAWzB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,SAAkB,GAAG,OAAO,UAAU,CAAC,KAAK,CAI1F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,UAAU,CAAC,KAAK,CAS5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,OAAO,UAAU,CAAC,KAAK,EAClC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,yBAAyB,CAS3B;AAED;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;GAevB,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;CAO9B,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;CAK/B,CAAC;AAEF,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCzB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;GAWzB,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;CAKhC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;CAUjC,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;CAkC7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;GAa/B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;CAWhC,CAAC;AAEF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;CAWpC,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;CAWtC,CAAC;AAEF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;CAmBnC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;CAmBrC,CAAC"}