@mharj/openweathermap 0.0.1

package/README.md

@@ -0,0 +1,7 @@
+# Open Weather Map API
+
+Open Weather Map API client for TypeScript.
+
+Currently supports v2 API only (/data/2.5/weather)
+
+## [Documentation](https://mharj.github.io/ts-openweathermap/)

package/dist/OpenWeatherV2.d.ts

@@ -0,0 +1,108 @@
+import { CountryCode, LangCode, Loadable, WeatherDataV2 } from './types';
+import { Result } from 'mharj-result';
+import type { ICacheOrAsync } from '@avanio/expire-cache';
+import type { IOpenWeatherV2 } from './interfaces/IOpenWeatherV2';
+/**
+ * Open Weather V2 API Common Options
+ * @default {lang: 'en', units: 'standard'} in API
+ * @example
+ * {lang: 'fi', units: 'metric'}
+ */
+export type OpenWeatherV2CommonOptions = {
+    /**
+     * Language code
+     */
+    lang?: LangCode;
+    /**
+     * Weather units
+     */
+    units?: 'standard' | 'metric' | 'imperial';
+};
+/**
+ * Open Weather V2 API
+ * @example
+ * const weather = new OpenWeatherV2('your-api-key');
+ *
+ * const cache = new ExpireCache<WeatherDataV2>(undefined, undefined, 900000); // data 15 minutes in cache
+ * const weather = new OpenWeatherV2(() => Promise.resolve('your-api-key'), cache);
+ *
+ * const data: WeatherDataV2 = (await weather.getWeatherById(2643743)).unwrap(); // throws if error
+ * const data: WeatherDataV2 | undefined = (await weather.getWeatherByCity('Helsinki', 'fi')).ok();
+ *
+ * const result: Result<WeatherDataV2> = await weather.getWeatherByLatLon(60.1699, 24.9384);
+ * result.match({
+ *  Ok: (data: WeatherDataV2) => console.log(data),
+ *  Err: (err: DOMException | TypeError) => console.error(err),
+ * });
+ *
+ * if(result.isOk) {
+ *   const data: WeatherDataV2 = data.ok();
+ * } else {
+ *   const err: DOMException | TypeError = data.err();
+ * }
+ */
+export declare class OpenWeatherV2 {
+    private cache;
+    private loadableApiKey;
+    private apiHandler;
+    /**
+     * OpenWeatherV2 constructor
+     * @param {Loadable<string>} loadableApiKey - Loadable API key
+     * @param {ICacheOrAsync<WeatherDataV2>=} cache - optional async cache implementation
+     * @param {IOpenWeatherV2=} apiHandler - optional API handler implementation for mocking
+     */
+    constructor(loadableApiKey: Loadable<string>, cache?: ICacheOrAsync<WeatherDataV2>, apiHandler?: IOpenWeatherV2);
+    /**
+     * get weather by Id
+     * @param {number} id       - Weather station ID
+     * @param {OpenWeatherV2CommonOptions=} opts - Common options, example ```{lang: 'fi', units: 'metric'}```, defaults ```{lang: 'en', units: 'standard'}```
+     * @return {Promise<Result<WeatherDataV2, DOMException | TypeError>>} Weather data Result Promise
+     * @example
+     * const result: Result<WeatherDataV2, DOMException | TypeError> = await weather.getWeatherResultById(id: 564, {lang: 'fi'});
+     * if (result.isOk) {
+     *   const weatherData: WeatherDataV2 = result.ok();
+     * } else {
+     *   const error: DOMException | TypeError = result.err();
+     * }
+     */
+    getWeatherById(id: number, opts?: OpenWeatherV2CommonOptions): Promise<Result<WeatherDataV2, DOMException | TypeError>>;
+    /**
+     * get weather with city name and optional country code
+     * @param {string} city       - City name
+     * @param {countryCode=} countryCode       - Optional Country code
+     * @param {OpenWeatherV2CommonOptions=} opts - Common options, example ```{lang: 'fi', units: 'metric'}```, defaults ```{lang: 'en', units: 'standard'}```
+     * @return {Promise<Result<WeatherDataV2, DOMException | TypeError>>} Weather data Result Promise
+     * @example
+     * const result: Result<WeatherDataV2, DOMException | TypeError> = await weather.getWeatherByCity('Helsinki', 'fi', {lang: 'fi'});
+     * if (result.isOk) {
+     *   const weatherData: WeatherDataV2 = result.ok();
+     * } else {
+     *   const error: DOMException | TypeError = result.err();
+     * }
+     */
+    getWeatherByCity(city: string, countryCode?: CountryCode, opts?: OpenWeatherV2CommonOptions): Promise<Result<WeatherDataV2, DOMException | TypeError>>;
+    /**
+     * get weather with latitude and longitude with Result
+     * @param {number} lat       - Latitude
+     * @param {number} lon       - Longitude
+     * @param {OpenWeatherV2CommonOptions=} opts - Common options, example ```{lang: 'fi', units: 'metric'}```, defaults ```{lang: 'en', units: 'standard'}```
+     * @return {Promise<Result<WeatherDataV2, DOMException | TypeError>>} Weather data Result Promise
+     * @example
+     * const result: Result<WeatherDataV2, DOMException | TypeError> = await weather.getWeatherByLatLon(60.1699, 24.9384, {lang: 'fi'});
+     * if (result.isOk) {
+     *   const weatherData: WeatherDataV2 = result.ok();
+     * } else {
+     *   const error: DOMException | TypeError = result.err();
+     * }
+     */
+    getWeatherByLatLon(lat: number, lon: number, opts?: OpenWeatherV2CommonOptions): Promise<Result<WeatherDataV2, DOMException | TypeError>>;
+    private buildBaseParams;
+    /**
+     * build base cache key
+     * @param main - main cache key prefix
+     * @param opts -  OpenWeatherV2CommonOptions
+     * @returns {CacheKey}
+     */
+    private buildBaseCacheKey;
+    private handleFetch;
+}

package/dist/OpenWeatherV2.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenWeatherV2 = void 0;
+const types_1 = require("./types");
+const mharj_result_1 = require("mharj-result");
+const fetchUtils_1 = require("./lib/fetchUtils");
+const defaultImplementation = {
+    dataWeatherApi: async (params) => {
+        const resp = await fetch(`https://api.openweathermap.org/data/2.5/weather?${params.toString()}`);
+        if (!resp.ok) {
+            throw new Error(resp.statusText);
+        }
+        const data = (await resp.json());
+        (0, types_1.assertWeatherDataV2)(data);
+        return data;
+    },
+};
+/**
+ * Open Weather V2 API
+ * @example
+ * const weather = new OpenWeatherV2('your-api-key');
+ *
+ * const cache = new ExpireCache<WeatherDataV2>(undefined, undefined, 900000); // data 15 minutes in cache
+ * const weather = new OpenWeatherV2(() => Promise.resolve('your-api-key'), cache);
+ *
+ * const data: WeatherDataV2 = (await weather.getWeatherById(2643743)).unwrap(); // throws if error
+ * const data: WeatherDataV2 | undefined = (await weather.getWeatherByCity('Helsinki', 'fi')).ok();
+ *
+ * const result: Result<WeatherDataV2> = await weather.getWeatherByLatLon(60.1699, 24.9384);
+ * result.match({
+ *  Ok: (data: WeatherDataV2) => console.log(data),
+ *  Err: (err: DOMException | TypeError) => console.error(err),
+ * });
+ *
+ * if(result.isOk) {
+ *   const data: WeatherDataV2 = data.ok();
+ * } else {
+ *   const err: DOMException | TypeError = data.err();
+ * }
+ */
+class OpenWeatherV2 {
+    cache;
+    loadableApiKey;
+    apiHandler;
+    /**
+     * OpenWeatherV2 constructor
+     * @param {Loadable<string>} loadableApiKey - Loadable API key
+     * @param {ICacheOrAsync<WeatherDataV2>=} cache - optional async cache implementation
+     * @param {IOpenWeatherV2=} apiHandler - optional API handler implementation for mocking
+     */
+    constructor(loadableApiKey, cache, apiHandler = defaultImplementation) {
+        this.loadableApiKey = loadableApiKey;
+        this.cache = cache;
+        this.apiHandler = apiHandler;
+    }
+    /**
+     * get weather by Id
+     * @param {number} id       - Weather station ID
+     * @param {OpenWeatherV2CommonOptions=} opts - Common options, example ```{lang: 'fi', units: 'metric'}```, defaults ```{lang: 'en', units: 'standard'}```
+     * @return {Promise<Result<WeatherDataV2, DOMException | TypeError>>} Weather data Result Promise
+     * @example
+     * const result: Result<WeatherDataV2, DOMException | TypeError> = await weather.getWeatherResultById(id: 564, {lang: 'fi'});
+     * if (result.isOk) {
+     *   const weatherData: WeatherDataV2 = result.ok();
+     * } else {
+     *   const error: DOMException | TypeError = result.err();
+     * }
+     */
+    async getWeatherById(id, opts = {}) {
+        try {
+            const cacheKey = this.buildBaseCacheKey(`id:${id}`, opts);
+            let cacheEntry = this.cache && (await this.cache.get(cacheKey));
+            if (!cacheEntry) {
+                const params = await this.buildBaseParams(opts);
+                params.append('id', String(id));
+                cacheEntry = await this.handleFetch(cacheKey, params, opts);
+            }
+            return (0, mharj_result_1.Ok)(cacheEntry);
+        }
+        catch (err) {
+            return (0, mharj_result_1.Err)((0, fetchUtils_1.fetchErrorWrapper)(err));
+        }
+    }
+    /**
+     * get weather with city name and optional country code
+     * @param {string} city       - City name
+     * @param {countryCode=} countryCode       - Optional Country code
+     * @param {OpenWeatherV2CommonOptions=} opts - Common options, example ```{lang: 'fi', units: 'metric'}```, defaults ```{lang: 'en', units: 'standard'}```
+     * @return {Promise<Result<WeatherDataV2, DOMException | TypeError>>} Weather data Result Promise
+     * @example
+     * const result: Result<WeatherDataV2, DOMException | TypeError> = await weather.getWeatherByCity('Helsinki', 'fi', {lang: 'fi'});
+     * if (result.isOk) {
+     *   const weatherData: WeatherDataV2 = result.ok();
+     * } else {
+     *   const error: DOMException | TypeError = result.err();
+     * }
+     */
+    async getWeatherByCity(city, countryCode, opts = {}) {
+        try {
+            const cacheKey = this.buildBaseCacheKey(`q:${city}:${countryCode}`, opts);
+            let cacheEntry = this.cache && (await this.cache.get(cacheKey));
+            if (!cacheEntry) {
+                const params = await this.buildBaseParams(opts);
+                params.append('q', countryCode ? `${city},${countryCode}` : city);
+                cacheEntry = await this.handleFetch(cacheKey, params, opts);
+            }
+            return (0, mharj_result_1.Ok)(cacheEntry);
+        }
+        catch (err) {
+            return (0, mharj_result_1.Err)((0, fetchUtils_1.fetchErrorWrapper)(err));
+        }
+    }
+    /**
+     * get weather with latitude and longitude with Result
+     * @param {number} lat       - Latitude
+     * @param {number} lon       - Longitude
+     * @param {OpenWeatherV2CommonOptions=} opts - Common options, example ```{lang: 'fi', units: 'metric'}```, defaults ```{lang: 'en', units: 'standard'}```
+     * @return {Promise<Result<WeatherDataV2, DOMException | TypeError>>} Weather data Result Promise
+     * @example
+     * const result: Result<WeatherDataV2, DOMException | TypeError> = await weather.getWeatherByLatLon(60.1699, 24.9384, {lang: 'fi'});
+     * if (result.isOk) {
+     *   const weatherData: WeatherDataV2 = result.ok();
+     * } else {
+     *   const error: DOMException | TypeError = result.err();
+     * }
+     */
+    async getWeatherByLatLon(lat, lon, opts = {}) {
+        try {
+            const cacheKey = this.buildBaseCacheKey(`latlon:${lat}:${lon}`, opts);
+            let cacheEntry = this.cache && (await this.cache.get(cacheKey));
+            if (!cacheEntry) {
+                const params = await this.buildBaseParams(opts);
+                params.append('lat', String(lat));
+                params.append('lon', String(lon));
+                cacheEntry = await this.handleFetch(cacheKey, params, opts);
+            }
+            return (0, mharj_result_1.Ok)(cacheEntry);
+        }
+        catch (err) {
+            return (0, mharj_result_1.Err)((0, fetchUtils_1.fetchErrorWrapper)(err));
+        }
+    }
+    async buildBaseParams({ lang, units }) {
+        const apiKey = await (typeof this.loadableApiKey === 'function' ? this.loadableApiKey() : this.loadableApiKey);
+        const params = new URLSearchParams();
+        lang && params.append('lang', lang);
+        units && params.append('units', units);
+        params.append('appid', apiKey);
+        return params;
+    }
+    /**
+     * build base cache key
+     * @param main - main cache key prefix
+     * @param opts -  OpenWeatherV2CommonOptions
+     * @returns {CacheKey}
+     */
+    buildBaseCacheKey(main, { lang, units }) {
+        return `${main}:${lang}:${units}`;
+    }
+    async handleFetch(cacheKey, params, opts) {
+        const data = await this.apiHandler.dataWeatherApi(params);
+        (0, types_1.assertWeatherDataV2)(data);
+        if (this.cache) {
+            await this.cache.set(cacheKey, data);
+            if (!cacheKey.startsWith('id:')) {
+                // update id cache too
+                await this.cache.set(this.buildBaseCacheKey(`id:${data.id}`, opts), data);
+            }
+        }
+        return data;
+    }
+}
+exports.OpenWeatherV2 = OpenWeatherV2;
+//# sourceMappingURL=OpenWeatherV2.js.map

package/dist/OpenWeatherV2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenWeatherV2.js","sourceRoot":"./src/","sources":["OpenWeatherV2.ts"],"names":[],"mappings":"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","sourcesContent":["import {assertWeatherDataV2, CountryCode, LangCode, Loadable, WeatherDataV2} from './types';\nimport {Err, Ok, Result} from 'mharj-result';\nimport {fetchErrorWrapper} from './lib/fetchUtils';\nimport type {ICacheOrAsync} from '@avanio/expire-cache';\nimport type {IOpenWeatherV2} from './interfaces/IOpenWeatherV2';\n\n/**\n * Open Weather V2 API Common Options\n * @default {lang: 'en', units: 'standard'} in API\n * @example\n * {lang: 'fi', units: 'metric'}\n */\nexport type OpenWeatherV2CommonOptions = {\n\t/**\n\t * Language code\n\t */\n\tlang?: LangCode;\n\t/**\n\t * Weather units\n\t */\n\tunits?: 'standard' | 'metric' | 'imperial';\n};\n\nconst defaultImplementation: IOpenWeatherV2 = {\n\tdataWeatherApi: async (params: URLSearchParams): Promise<WeatherDataV2> => {\n\t\tconst resp = await fetch(`https://api.openweathermap.org/data/2.5/weather?${params.toString()}`);\n\t\tif (!resp.ok) {\n\t\t\tthrow new Error(resp.statusText);\n\t\t}\n\t\tconst data = (await resp.json()) as unknown;\n\t\tassertWeatherDataV2(data);\n\t\treturn data;\n\t},\n};\n\n/**\n * Open Weather V2 API\n * @example\n * const weather = new OpenWeatherV2('your-api-key');\n *\n * const cache = new ExpireCache<WeatherDataV2>(undefined, undefined, 900000); // data 15 minutes in cache\n * const weather = new OpenWeatherV2(() => Promise.resolve('your-api-key'), cache);\n *\n * const data: WeatherDataV2 = (await weather.getWeatherById(2643743)).unwrap(); // throws if error\n * const data: WeatherDataV2 | undefined = (await weather.getWeatherByCity('Helsinki', 'fi')).ok();\n *\n * const result: Result<WeatherDataV2> = await weather.getWeatherByLatLon(60.1699, 24.9384);\n * result.match({\n *  Ok: (data: WeatherDataV2) => console.log(data),\n *  Err: (err: DOMException | TypeError) => console.error(err),\n * });\n *\n * if(result.isOk) {\n *   const data: WeatherDataV2 = data.ok();\n * } else {\n *   const err: DOMException | TypeError = data.err();\n * }\n */\nexport class OpenWeatherV2 {\n\tprivate cache: ICacheOrAsync<WeatherDataV2> | undefined;\n\tprivate loadableApiKey: Loadable<string>;\n\tprivate apiHandler: IOpenWeatherV2;\n\t/**\n\t * OpenWeatherV2 constructor\n\t * @param {Loadable<string>} loadableApiKey - Loadable API key\n\t * @param {ICacheOrAsync<WeatherDataV2>=} cache - optional async cache implementation\n\t * @param {IOpenWeatherV2=} apiHandler - optional API handler implementation for mocking\n\t */\n\tconstructor(loadableApiKey: Loadable<string>, cache?: ICacheOrAsync<WeatherDataV2>, apiHandler: IOpenWeatherV2 = defaultImplementation) {\n\t\tthis.loadableApiKey = loadableApiKey;\n\t\tthis.cache = cache;\n\t\tthis.apiHandler = apiHandler;\n\t}\n\n\t/**\n\t * get weather by Id\n\t * @param {number} id       - Weather station ID\n\t * @param {OpenWeatherV2CommonOptions=} opts - Common options, example ```{lang: 'fi', units: 'metric'}```, defaults ```{lang: 'en', units: 'standard'}```\n\t * @return {Promise<Result<WeatherDataV2, DOMException | TypeError>>} Weather data Result Promise\n\t * @example\n\t * const result: Result<WeatherDataV2, DOMException | TypeError> = await weather.getWeatherResultById(id: 564, {lang: 'fi'});\n\t * if (result.isOk) {\n\t *   const weatherData: WeatherDataV2 = result.ok();\n\t * } else {\n\t *   const error: DOMException | TypeError = result.err();\n\t * }\n\t */\n\tpublic async getWeatherById(id: number, opts: OpenWeatherV2CommonOptions = {}): Promise<Result<WeatherDataV2, DOMException | TypeError>> {\n\t\ttry {\n\t\t\tconst cacheKey = this.buildBaseCacheKey(`id:${id}`, opts);\n\t\t\tlet cacheEntry = this.cache && (await this.cache.get(cacheKey));\n\t\t\tif (!cacheEntry) {\n\t\t\t\tconst params = await this.buildBaseParams(opts);\n\t\t\t\tparams.append('id', String(id));\n\t\t\t\tcacheEntry = await this.handleFetch(cacheKey, params, opts);\n\t\t\t}\n\t\t\treturn Ok(cacheEntry);\n\t\t} catch (err) {\n\t\t\treturn Err(fetchErrorWrapper(err));\n\t\t}\n\t}\n\n\t/**\n\t * get weather with city name and optional country code\n\t * @param {string} city       - City name\n\t * @param {countryCode=} countryCode       - Optional Country code\n\t * @param {OpenWeatherV2CommonOptions=} opts - Common options, example ```{lang: 'fi', units: 'metric'}```, defaults ```{lang: 'en', units: 'standard'}```\n\t * @return {Promise<Result<WeatherDataV2, DOMException | TypeError>>} Weather data Result Promise\n\t * @example\n\t * const result: Result<WeatherDataV2, DOMException | TypeError> = await weather.getWeatherByCity('Helsinki', 'fi', {lang: 'fi'});\n\t * if (result.isOk) {\n\t *   const weatherData: WeatherDataV2 = result.ok();\n\t * } else {\n\t *   const error: DOMException | TypeError = result.err();\n\t * }\n\t */\n\tpublic async getWeatherByCity(\n\t\tcity: string,\n\t\tcountryCode?: CountryCode,\n\t\topts: OpenWeatherV2CommonOptions = {},\n\t): Promise<Result<WeatherDataV2, DOMException | TypeError>> {\n\t\ttry {\n\t\t\tconst cacheKey = this.buildBaseCacheKey(`q:${city}:${countryCode}`, opts);\n\t\t\tlet cacheEntry = this.cache && (await this.cache.get(cacheKey));\n\t\t\tif (!cacheEntry) {\n\t\t\t\tconst params = await this.buildBaseParams(opts);\n\t\t\t\tparams.append('q', countryCode ? `${city},${countryCode}` : city);\n\t\t\t\tcacheEntry = await this.handleFetch(cacheKey, params, opts);\n\t\t\t}\n\t\t\treturn Ok(cacheEntry);\n\t\t} catch (err) {\n\t\t\treturn Err(fetchErrorWrapper(err));\n\t\t}\n\t}\n\n\t/**\n\t * get weather with latitude and longitude with Result\n\t * @param {number} lat       - Latitude\n\t * @param {number} lon       - Longitude\n\t * @param {OpenWeatherV2CommonOptions=} opts - Common options, example ```{lang: 'fi', units: 'metric'}```, defaults ```{lang: 'en', units: 'standard'}```\n\t * @return {Promise<Result<WeatherDataV2, DOMException | TypeError>>} Weather data Result Promise\n\t * @example\n\t * const result: Result<WeatherDataV2, DOMException | TypeError> = await weather.getWeatherByLatLon(60.1699, 24.9384, {lang: 'fi'});\n\t * if (result.isOk) {\n\t *   const weatherData: WeatherDataV2 = result.ok();\n\t * } else {\n\t *   const error: DOMException | TypeError = result.err();\n\t * }\n\t */\n\tpublic async getWeatherByLatLon(lat: number, lon: number, opts: OpenWeatherV2CommonOptions = {}): Promise<Result<WeatherDataV2, DOMException | TypeError>> {\n\t\ttry {\n\t\t\tconst cacheKey = this.buildBaseCacheKey(`latlon:${lat}:${lon}`, opts);\n\t\t\tlet cacheEntry = this.cache && (await this.cache.get(cacheKey));\n\t\t\tif (!cacheEntry) {\n\t\t\t\tconst params = await this.buildBaseParams(opts);\n\t\t\t\tparams.append('lat', String(lat));\n\t\t\t\tparams.append('lon', String(lon));\n\t\t\t\tcacheEntry = await this.handleFetch(cacheKey, params, opts);\n\t\t\t}\n\t\t\treturn Ok(cacheEntry);\n\t\t} catch (err) {\n\t\t\treturn Err(fetchErrorWrapper(err));\n\t\t}\n\t}\n\n\tprivate async buildBaseParams({lang, units}: OpenWeatherV2CommonOptions): Promise<URLSearchParams> {\n\t\tconst apiKey = await (typeof this.loadableApiKey === 'function' ? this.loadableApiKey() : this.loadableApiKey);\n\t\tconst params = new URLSearchParams();\n\t\tlang && params.append('lang', lang);\n\t\tunits && params.append('units', units);\n\t\tparams.append('appid', apiKey);\n\t\treturn params;\n\t}\n\n\t/**\n\t * build base cache key\n\t * @param main - main cache key prefix\n\t * @param opts -  OpenWeatherV2CommonOptions\n\t * @returns {CacheKey}\n\t */\n\tprivate buildBaseCacheKey(main: string, {lang, units}: OpenWeatherV2CommonOptions): string {\n\t\treturn `${main}:${lang}:${units}`;\n\t}\n\n\tprivate async handleFetch(cacheKey: string, params: URLSearchParams, opts: OpenWeatherV2CommonOptions): Promise<WeatherDataV2> {\n\t\tconst data = await this.apiHandler.dataWeatherApi(params);\n\t\tassertWeatherDataV2(data);\n\t\tif (this.cache) {\n\t\t\tawait this.cache.set(cacheKey, data);\n\t\t\tif (!cacheKey.startsWith('id:')) {\n\t\t\t\t// update id cache too\n\t\t\t\tawait this.cache.set(this.buildBaseCacheKey(`id:${data.id}`, opts), data);\n\t\t\t}\n\t\t}\n\t\treturn data;\n\t}\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './OpenWeatherV2';
+export * from './types';
+export * from './lib';
+export * from './interfaces';

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./OpenWeatherV2"), exports);
+tslib_1.__exportStar(require("./types"), exports);
+tslib_1.__exportStar(require("./lib"), exports);
+tslib_1.__exportStar(require("./interfaces"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"./src/","sources":["index.ts"],"names":[],"mappings":";;;AAAA,0DAAgC;AAChC,kDAAwB;AACxB,gDAAsB;AACtB,uDAA6B","sourcesContent":["export * from './OpenWeatherV2';\nexport * from './types';\nexport * from './lib';\nexport * from './interfaces';\n"]}

package/dist/interfaces/IOpenWeatherV2.d.ts

@@ -0,0 +1,7 @@
+import { WeatherDataV2 } from '../types/v2';
+/**
+ * Interface for OpenWeatherMap API v2 implementation.
+ */
+export interface IOpenWeatherV2 {
+    dataWeatherApi: (params: URLSearchParams) => Promise<WeatherDataV2>;
+}

package/dist/interfaces/IOpenWeatherV2.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IOpenWeatherV2.js.map

package/dist/interfaces/IOpenWeatherV2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IOpenWeatherV2.js","sourceRoot":"./src/","sources":["interfaces/IOpenWeatherV2.ts"],"names":[],"mappings":"","sourcesContent":["import {WeatherDataV2} from '../types/v2';\n\n/**\n * Interface for OpenWeatherMap API v2 implementation.\n */\nexport interface IOpenWeatherV2 {\n\tdataWeatherApi: (params: URLSearchParams) => Promise<WeatherDataV2>;\n}\n"]}

package/dist/interfaces/index.d.ts

@@ -0,0 +1 @@
+export * from './IOpenWeatherV2';

package/dist/interfaces/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./IOpenWeatherV2"), exports);
+//# sourceMappingURL=index.js.map

package/dist/interfaces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"./src/","sources":["interfaces/index.ts"],"names":[],"mappings":";;;AAAA,2DAAiC","sourcesContent":["export * from './IOpenWeatherV2';\n"]}

package/dist/lib/fetchUtils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Ensures that the error is a DOMException or TypeError.
+ * @internal
+ */
+export declare function fetchErrorWrapper(err: unknown): DOMException | TypeError;

package/dist/lib/fetchUtils.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchErrorWrapper = void 0;
+/**
+ * Ensures that the error is a DOMException or TypeError.
+ * @internal
+ */
+function fetchErrorWrapper(err) {
+    if (err instanceof DOMException || err instanceof TypeError) {
+        return err;
+    }
+    else {
+        return new TypeError(`Unknown error: ${String(err)}`);
+    }
+}
+exports.fetchErrorWrapper = fetchErrorWrapper;
+//# sourceMappingURL=fetchUtils.js.map

package/dist/lib/fetchUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchUtils.js","sourceRoot":"./src/","sources":["lib/fetchUtils.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,GAAY;IAC7C,IAAI,GAAG,YAAY,YAAY,IAAI,GAAG,YAAY,SAAS,EAAE;QAC5D,OAAO,GAAG,CAAC;KACX;SAAM;QACN,OAAO,IAAI,SAAS,CAAC,kBAAkB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;KACtD;AACF,CAAC;AAND,8CAMC","sourcesContent":["/**\n * Ensures that the error is a DOMException or TypeError.\n * @internal\n */\nexport function fetchErrorWrapper(err: unknown): DOMException | TypeError {\n\tif (err instanceof DOMException || err instanceof TypeError) {\n\t\treturn err;\n\t} else {\n\t\treturn new TypeError(`Unknown error: ${String(err)}`);\n\t}\n}\n"]}

package/dist/lib/index.d.ts

@@ -0,0 +1 @@
+export * from './fetchUtils';

package/dist/lib/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./fetchUtils"), exports);
+//# sourceMappingURL=index.js.map

package/dist/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"./src/","sources":["lib/index.ts"],"names":[],"mappings":";;;AAAA,uDAA6B","sourcesContent":["export * from './fetchUtils';\n"]}

package/dist/types/ISO3166-Countries.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export declare const CountryCodeList: readonly ["af", "ax", "al", "dz", "as", "ad", "ao", "ai", "aq", "ag", "ar", "am", "aw", "au", "at", "az", "bs", "bh", "bd", "bb", "by", "be", "bz", "bj", "bm", "bt", "bo", "bq", "ba", "bw", "bv", "br", "io", "bn", "bg", "bf", "bi", "kh", "cm", "ca", "cv", "ky", "cf", "td", "cl", "cn", "cx", "cc", "co", "km", "cg", "cd", "ck", "cr", "ci", "hr", "cu", "cw", "cy", "cz", "dk", "dj", "dm", "do", "ec", "eg", "sv", "gq", "er", "ee", "et", "fk", "fo", "fj", "fi", "fr", "gf", "pf", "tf", "ga", "gm", "ge", "de", "gh", "gi", "gr", "gl", "gd", "gp", "gu", "gt", "gg", "gn", "gw", "gy", "ht", "hm", "va", "hn", "hk", "hu", "is", "in", "id", "ir", "iq", "ie", "im", "il", "it", "jm", "jp", "je", "jo", "kz", "ke", "ki", "kp", "kr", "kw", "kg", "la", "lv", "lb", "ls", "lr", "ly", "li", "lt", "lu", "mo", "mk", "mg", "mw", "my", "mv", "ml", "mt", "mh", "mq", "mr", "mu", "yt", "mx", "fm", "md", "mc", "mn", "me", "ms", "ma", "mz", "mm", "na", "nr", "np", "nl", "nc", "nz", "ni", "ne", "ng", "nu", "nf", "mp", "no", "om", "pk", "pw", "ps", "pa", "pg", "py", "pe", "ph", "pn", "pl", "pt", "pr", "qa", "re", "ro", "ru", "rw", "bl", "sh", "kn", "lc", "mf", "pm", "vc", "ws", "sm", "st", "sa", "sn", "rs", "sc", "sl", "sg", "sx", "sk", "si", "sb", "so", "za", "gs", "ss", "es", "lk", "sd", "sr", "sj", "sz", "se", "ch", "sy", "tw", "tj", "tz", "th", "tl", "tg", "tk", "to", "tt", "tn", "tr", "tm", "tc", "tv", "ug", "ua", "ae", "gb", "us", "um", "uy", "uz", "vu", "ve", "vn", "vg", "vi", "wf", "eh", "ye", "zm", "zw"];
+/**
+ * @internal
+ */
+export declare const CountryCodeSchema: z.ZodEnum<["af", "ax", "al", "dz", "as", "ad", "ao", "ai", "aq", "ag", "ar", "am", "aw", "au", "at", "az", "bs", "bh", "bd", "bb", "by", "be", "bz", "bj", "bm", "bt", "bo", "bq", "ba", "bw", "bv", "br", "io", "bn", "bg", "bf", "bi", "kh", "cm", "ca", "cv", "ky", "cf", "td", "cl", "cn", "cx", "cc", "co", "km", "cg", "cd", "ck", "cr", "ci", "hr", "cu", "cw", "cy", "cz", "dk", "dj", "dm", "do", "ec", "eg", "sv", "gq", "er", "ee", "et", "fk", "fo", "fj", "fi", "fr", "gf", "pf", "tf", "ga", "gm", "ge", "de", "gh", "gi", "gr", "gl", "gd", "gp", "gu", "gt", "gg", "gn", "gw", "gy", "ht", "hm", "va", "hn", "hk", "hu", "is", "in", "id", "ir", "iq", "ie", "im", "il", "it", "jm", "jp", "je", "jo", "kz", "ke", "ki", "kp", "kr", "kw", "kg", "la", "lv", "lb", "ls", "lr", "ly", "li", "lt", "lu", "mo", "mk", "mg", "mw", "my", "mv", "ml", "mt", "mh", "mq", "mr", "mu", "yt", "mx", "fm", "md", "mc", "mn", "me", "ms", "ma", "mz", "mm", "na", "nr", "np", "nl", "nc", "nz", "ni", "ne", "ng", "nu", "nf", "mp", "no", "om", "pk", "pw", "ps", "pa", "pg", "py", "pe", "ph", "pn", "pl", "pt", "pr", "qa", "re", "ro", "ru", "rw", "bl", "sh", "kn", "lc", "mf", "pm", "vc", "ws", "sm", "st", "sa", "sn", "rs", "sc", "sl", "sg", "sx", "sk", "si", "sb", "so", "za", "gs", "ss", "es", "lk", "sd", "sr", "sj", "sz", "se", "ch", "sy", "tw", "tj", "tz", "th", "tl", "tg", "tk", "to", "tt", "tn", "tr", "tm", "tc", "tv", "ug", "ua", "ae", "gb", "us", "um", "uy", "uz", "vu", "ve", "vn", "vg", "vi", "wf", "eh", "ye", "zm", "zw"]>;
+export type CountryCode = z.infer<typeof CountryCodeSchema>;