iqair-api 1.0.1

package/README.md

@@ -0,0 +1,104 @@
+# iqair-api
+
+Fully typed TypeScript SDK for scraping IQAir air quality data.
+
+## Installation
+
+```bash
+bun add iqair-api
+```
+
+## Usage
+
+```typescript
+import { createIQAirClient } from "iqair-api";
+
+const client = createIQAirClient();
+
+async function main() {
+  const dataSource = "central-pollution-control-board";
+
+  const stations = await client.getStations({ dataSource });
+  console.log(`Found ${stations.length} stations`);
+
+  const nearest = await client.getNearestStation({
+    lat: 28.6139,
+    lng: 77.209,
+    dataSource,
+  });
+  console.log("Nearest station:", nearest);
+
+  if (nearest) {
+    const aqi = await client.getStationAQI({ stationUrl: nearest.url });
+    console.log("Station AQI:", aqi);
+  }
+
+  const locationAQI = await client.getAQIForLocation({
+    lat: 28.6139,
+    lng: 77.209,
+    dataSource,
+  });
+  console.log("Location AQI:", locationAQI);
+}
+
+main().catch(console.error);
+```
+
+## API
+
+### `createIQAirClient(config?)`
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `baseUrl` | `string` | No | IQAir base URL (default: `https://www.iqair.com`) |
+| `locale` | `string` | No | Locale path segment (default: `in-en`) |
+| `userAgent` | `string` | No | Custom user agent string |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `getStations(params)` | Get all stations for a data source |
+| `getStationAQI(params)` | Get AQI data for a specific station |
+| `getNearestStation(params)` | Find the nearest station to coordinates |
+| `getNearestStations(params)` | Find nearest stations to coordinates (sorted) |
+| `getAQIForLocation(params)` | Get AQI for the nearest station to coordinates |
+
+### Types
+
+```typescript
+import type {
+  Station,
+  StationWithDistance,
+  StationDetails,
+  StationItem,
+  AQIResponse,
+  CurrentConditions,
+  Pollutant,
+  HistoricalDataPoint,
+  ForecastItem,
+  GetStationsParams,
+  GetStationAQIParams,
+  GetNearestStationParams,
+  GetNearestStationsParams,
+  GetAQIForLocationParams,
+} from "iqair-api";
+```
+
+## Development
+
+```bash
+bun install
+bun run build
+bun test
+bun test:unit
+bun test:e2e
+```
+
+## License
+
+MIT
+
+## Disclaimer
+
+This is an **unofficial** API client and is not affiliated with, endorsed by, or associated with IQAir or its parent organization. This package is provided for educational and informational purposes under fair use. Accessing publicly available air quality data is lawful and serves the public interest.

package/dist/index.d.mts

@@ -0,0 +1,284 @@
+//#region src/client/iqair-client.config.d.ts
+interface IQAirClientConfig {
+  baseUrl?: string;
+  locale?: string;
+  userAgent?: string;
+}
+//#endregion
+//#region src/types/station/station.interface.d.ts
+interface Station {
+  id: string;
+  name: string;
+  url: string;
+  latitude: number;
+  longitude: number;
+  city?: string;
+  country?: string;
+}
+//#endregion
+//#region src/types/station/station-with-distance.interface.d.ts
+interface StationWithDistance extends Station {
+  distance: number;
+}
+//#endregion
+//#region src/types/station/station-item.interface.d.ts
+interface StationItem {
+  id: string;
+  name: string;
+  url: string;
+  coordinates: {
+    latitude: number;
+    longitude: number;
+  };
+  current: {
+    aqi: {
+      value: number;
+      color: string;
+      label: string;
+    };
+    ts: string;
+  };
+}
+//#endregion
+//#region src/types/aqi/pollutant.interface.d.ts
+interface Pollutant {
+  unit: string;
+  description: string;
+  aqi: number;
+  concentration: number;
+  pollutantName: string;
+}
+//#endregion
+//#region src/types/aqi/current-conditions.interface.d.ts
+interface CurrentConditions {
+  ts: string;
+  aqi: number;
+  mainPollutant: string;
+  concentration: number;
+  estimated: boolean;
+  condition?: string;
+  icon?: string;
+  humidity?: number;
+  pressure?: number;
+  temperature?: number;
+  wind?: {
+    speed: number;
+    direction: number;
+  };
+  pollutants?: Pollutant[];
+  aqiDescription?: string;
+}
+//#endregion
+//#region src/types/forecast/forecast-item.interface.d.ts
+interface ForecastItem {
+  ts: string;
+  aqi?: number;
+  pressure?: number;
+  humidity?: number;
+  wind?: {
+    speed: number;
+    direction: number;
+  };
+  icon?: string;
+  condition?: string;
+  temperature?: number | {
+    max: number;
+    min: number;
+  };
+}
+//#endregion
+//#region src/types/station/station-details.interface.d.ts
+interface StationDetails {
+  id: string;
+  name: string;
+  country: string;
+  state: string;
+  type: string;
+  timezone: string;
+  coordinates: {
+    latitude: number;
+    longitude: number;
+  };
+  current: CurrentConditions;
+  forecasts?: {
+    hourly: ForecastItem[];
+    daily: ForecastItem[];
+  };
+}
+//#endregion
+//#region src/types/history/historical-data-point.interface.d.ts
+interface HistoricalDataPoint {
+  ts: string;
+  aqi?: number;
+  pm25?: {
+    aqi: number;
+    concentration: number;
+  };
+  pm10?: {
+    aqi: number;
+    concentration: number;
+  };
+  o3?: {
+    aqi: number;
+    concentration: number;
+  };
+  no2?: {
+    aqi: number;
+    concentration: number;
+  };
+  so2?: {
+    aqi: number;
+    concentration: number;
+  };
+  co?: {
+    aqi: number;
+    concentration: number;
+  };
+  pressure?: number;
+  humidity?: number;
+  temperature?: number | {
+    max: number;
+    min: number;
+  };
+  wind?: {
+    speed: number;
+    direction: number;
+  };
+  condition?: string;
+  icon?: string;
+}
+//#endregion
+//#region src/types/aqi/aqi-response.interface.d.ts
+interface AQIResponse {
+  station: {
+    id: string;
+    name: string;
+    url: string;
+    distance: number;
+  };
+  current: {
+    ts: string;
+    aqi: number;
+    mainPollutant?: string;
+    concentration?: number;
+    condition?: string;
+    temperature?: number;
+    humidity?: number;
+    pressure?: number;
+    wind?: {
+      speed: number;
+      direction: number;
+    };
+  };
+  pollutants?: Array<{
+    name: string;
+    aqi: number;
+    concentration: number;
+    unit: string;
+  }>;
+  historical?: {
+    hourly: HistoricalDataPoint[];
+    daily: HistoricalDataPoint[];
+  };
+}
+//#endregion
+//#region src/types/params/get-stations.params.d.ts
+interface GetStationsParams {
+  dataSource: string;
+  limit?: number;
+}
+//#endregion
+//#region src/types/params/get-station-aqi.params.d.ts
+interface GetStationAQIParams {
+  stationUrl: string;
+}
+//#endregion
+//#region src/types/params/get-nearest-station.params.d.ts
+interface GetNearestStationParams {
+  lat: number;
+  lng: number;
+  dataSource: string;
+}
+//#endregion
+//#region src/types/params/get-nearest-stations.params.d.ts
+interface GetNearestStationsParams {
+  lat: number;
+  lng: number;
+  dataSource: string;
+  limit?: number;
+}
+//#endregion
+//#region src/types/params/get-aqi-for-location.params.d.ts
+interface GetAQIForLocationParams {
+  lat: number;
+  lng: number;
+  dataSource: string;
+}
+//#endregion
+//#region src/types/internal/station-list-response.interface.d.ts
+interface StationListData {
+  profileStations?: {
+    data: StationItem[];
+    response: Record<string, unknown>;
+  };
+  stationsMapData?: {
+    data: StationItem[];
+    response: Record<string, unknown>;
+  };
+}
+interface StationListResponse {
+  "routes/$(locale)": {
+    data: StationListData;
+  };
+  "routes/$(locale).profile.$slug": {
+    data: StationListData;
+  };
+}
+//#endregion
+//#region src/types/internal/individual-station-response.interface.d.ts
+interface IndividualStationData {
+  details?: StationDetails;
+  measurements?: {
+    data?: {
+      measurements?: {
+        hourly?: HistoricalDataPoint[];
+        daily?: HistoricalDataPoint[];
+      };
+    };
+  };
+}
+interface IndividualStationResponse {
+  root: {
+    data: IndividualStationData;
+  };
+  "routes/$": {
+    data: IndividualStationData;
+  };
+}
+//#endregion
+//#region src/client/iqair-client.d.ts
+declare class IQAirClient {
+  private readonly baseUrl;
+  private readonly locale;
+  private readonly userAgent;
+  constructor(config?: IQAirClientConfig);
+  private request;
+  getStations(params: GetStationsParams): Promise<Station[]>;
+  getStationAQI(params: GetStationAQIParams): Promise<AQIResponse>;
+  getNearestStation(params: GetNearestStationParams): Promise<StationWithDistance | null>;
+  getNearestStations(params: GetNearestStationsParams): Promise<StationWithDistance[]>;
+  getAQIForLocation(params: GetAQIForLocationParams): Promise<AQIResponse | null>;
+}
+//#endregion
+//#region src/client/create-iqair-client.d.ts
+declare function createIQAirClient(config?: IQAirClientConfig): IQAirClient;
+//#endregion
+//#region src/exceptions/iqair.exception.d.ts
+declare class IQAirException extends Error {
+  readonly statusCode: number;
+  readonly body?: string;
+  constructor(message: string, statusCode: number, body?: string);
+}
+//#endregion
+export { AQIResponse, CurrentConditions, ForecastItem, GetAQIForLocationParams, GetNearestStationParams, GetNearestStationsParams, GetStationAQIParams, GetStationsParams, HistoricalDataPoint, IQAirClient, type IQAirClientConfig, IQAirException, IndividualStationData, IndividualStationResponse, Pollutant, Station, StationDetails, StationItem, StationListData, StationListResponse, StationWithDistance, createIQAirClient };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/client/iqair-client.config.ts","../src/types/station/station.interface.ts","../src/types/station/station-with-distance.interface.ts","../src/types/station/station-item.interface.ts","../src/types/aqi/pollutant.interface.ts","../src/types/aqi/current-conditions.interface.ts","../src/types/forecast/forecast-item.interface.ts","../src/types/station/station-details.interface.ts","../src/types/history/historical-data-point.interface.ts","../src/types/aqi/aqi-response.interface.ts","../src/types/params/get-stations.params.ts","../src/types/params/get-station-aqi.params.ts","../src/types/params/get-nearest-station.params.ts","../src/types/params/get-nearest-stations.params.ts","../src/types/params/get-aqi-for-location.params.ts","../src/types/internal/station-list-response.interface.ts","../src/types/internal/individual-station-response.interface.ts","../src/client/iqair-client.ts","../src/client/create-iqair-client.ts","../src/exceptions/iqair.exception.ts"],"sourcesContent":[],"mappings":";UAAiB,iBAAA;EAAA,OAAA,CAAA,EAAA,MAAA;;;;;;UCAA,OAAA;EDAA,EAAA,EAAA,MAAA;;;;ECAA,SAAA,EAAO,MAAA;;;;;;ADAP,UEEA,mBAAA,SAA4B,OFFX,CAAA;;;;;UGAjB,WAAA;EHAA,EAAA,EAAA,MAAA;;;;ICAA,QAAO,EAAA,MAAA;;;;ICEP,GAAA,EAAA;;;;ICFA,CAAA;;;;;;UCAA,SAAA;EJAA,IAAA,EAAA,MAAA;;;;ECAA,aAAO,EAAA,MAAA;;;;ADAP,UKEA,iBAAA,CLFiB;;;;ECAjB,aAAO,EAAA,MAAA;;;;ECEP,QAAA,CAAA,EAAA,MAAA;;;;ICFA,KAAA,EAAA,MAAW;;;eEiBb;EDjBE,cAAS,CAAA,EAAA,MAAA;;;;UEAT,YAAA;ENAA,EAAA,EAAA,MAAA;;;;ECAA,IAAA,CAAA,EAAA;;;;ECEA,IAAA,CAAA,EAAA,MAAA;;;;ICFA,GAAA,EAAA,MAAW;;;;;UIGX,cAAA;;;ENHA,OAAA,EAAA,MAAO;;;;ECEP,WAAA,EAAA;;;;ECFA,OAAA,EIcN,iBJdiB;;YIgBhB;WACD;EHjBM,CAAA;;;;UIAA,mBAAA;ERAA,EAAA,EAAA,MAAA;;;;ICAA,aAAO,EAAA,MAAA;;;;ICEP,aAAA,EAAA,MAAoB;;;;ICFpB,aAAW,EAAA,MAAA;;;;ICAX,aAAS,EAAA,MAAA;;;;ICET,aAAA,EAAA,MAAiB;;;;ICFjB,aAAY,EAAA,MAAA;;;;ECGZ,WAAA,CAAA,EAAA,MAAc,GAAA;IAWpB,GAAA,EAAA,MAAA;IAEC,GAAA,EAAA,MAAA;EACD,CAAA;EAAY,IAAA,CAAA,EAAA;;;;ECjBN,SAAA,CAAA,EAAA,MAAA;;;;;ARAA,USEA,WAAA,CTFiB;;;;ICAjB,GAAA,EAAA,MAAO;;;;ICEP,EAAA,EAAA,MAAA;;;;ICFA,SAAA,CAAW,EAAA,MAAA;;;;ICAX,IAAA,CAAA,EAAA;;;;ECEA,CAAA;eIqBF;;;IHvBE,aAAY,EAAA,MAAA;;;;ICGZ,MAAA,EE2BL,mBF3BmB,EAAA;IAWpB,KAAA,EEiBA,mBFjBA,EAAA;EAEC,CAAA;;;;UGhBK,iBAAA;EVAA,UAAA,EAAA,MAAA;;;;;UWAA,mBAAA;EXAA,UAAA,EAAA,MAAA;;;;UYAA,uBAAA;EZAA,GAAA,EAAA,MAAA;;;;;;UaAA,wBAAA;EbAA,GAAA,EAAA,MAAA;;;;ACAjB;;;UaAiB,uBAAA;EdAA,GAAA,EAAA,MAAA;;;;;;AAAA,UeEA,eAAA,CfFiB;;UeIxB;cACI;EdLG,CAAA;;UcQP;cACI;EbPG,CAAA;;UaWA,mBAAA;;IZbA,IAAA,EYeP,eZfkB;;;UYkBlB;EXlBO,CAAA;;;;UYGA,qBAAA;YACL;;IfJK,IAAA,CAAA,EAAO;;iBeQP;gBACD;MdPC,CAAA;;;;ACFA,UaeA,yBAAA,CbfW;;UaiBlB;;EZjBO,UAAA,EAAS;UYoBhB;;;;;cCKG,WAAA;;;EhBzBI,iBAAO,SAAA;uBgB8BF;;sBAUM,oBAAoB,QAAQ;EftCvC,aAAA,CAAA,MAAA,EeiEa,mBfjEsB,CAAA,EeiEA,OfjEA,CeiEQ,WfjER,CAAA;4BeuHxC,0BACP,QAAQ;6BAMD,2BACP,QAAQ;4BAMD,0BACP,QAAQ;AdxIb;;;iBeGgB,iBAAA,UAA2B,oBAAoB;;;cCHlD,cAAA,SAAuB,KAAA;EnBAnB,SAAA,UAAA,EAAiB,MAAA"}

package/dist/index.mjs

@@ -0,0 +1,206 @@
+import { UNSAFE_decodeViaTurboStream } from "react-router";
+
+//#region src/constants/base-url.constant.ts
+const DEFAULT_BASE_URL = "https://www.iqair.com";
+
+//#endregion
+//#region src/constants/locale.constant.ts
+const DEFAULT_LOCALE = "in-en";
+
+//#endregion
+//#region src/constants/routes.constant.ts
+const STATION_LIST_ROUTES = encodeURIComponent("routes/$(locale),routes/$(locale).profile.$slug");
+const INDIVIDUAL_STATION_ROUTES = encodeURIComponent("routes/$");
+
+//#endregion
+//#region src/constants/user-agent.constant.ts
+const DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36";
+
+//#endregion
+//#region src/exceptions/iqair.exception.ts
+var IQAirException = class extends Error {
+	statusCode;
+	body;
+	constructor(message, statusCode, body) {
+		super(message);
+		this.name = "IQAirException";
+		this.statusCode = statusCode;
+		this.body = body;
+	}
+};
+
+//#endregion
+//#region src/utils/decoder.util.ts
+async function resolveAllPromises(obj) {
+	if (obj instanceof Promise) return resolveAllPromises(await obj);
+	if (Array.isArray(obj)) return await Promise.all(obj.map(resolveAllPromises));
+	if (obj !== null && typeof obj === "object") {
+		const entries = Object.entries(obj);
+		const resolvedEntries = await Promise.all(entries.map(async ([key, value]) => [key, await resolveAllPromises(value)]));
+		return Object.fromEntries(resolvedEntries);
+	}
+	return obj;
+}
+async function decodeTurboStream(stream) {
+	const decoded = await UNSAFE_decodeViaTurboStream(stream, globalThis);
+	await decoded.done;
+	return await resolveAllPromises(decoded.value);
+}
+async function fetchAndDecode(url, userAgent) {
+	const response = await fetch(url, { headers: {
+		"User-Agent": userAgent,
+		Accept: "*/*",
+		"Accept-Language": "en-US,en;q=0.9"
+	} });
+	if (!response.ok) {
+		const text = await response.text();
+		throw new IQAirException(`Request failed: ${response.status} ${response.statusText}`, response.status, text);
+	}
+	if (!response.body) throw new IQAirException("Response body is null", 500);
+	return decodeTurboStream(response.body);
+}
+
+//#endregion
+//#region src/utils/geo.util.ts
+const EARTH_RADIUS_KM = 6371;
+function toRadians(degrees) {
+	return degrees * (Math.PI / 180);
+}
+function haversineDistance(lat1, lon1, lat2, lon2) {
+	const dLat = toRadians(lat2 - lat1);
+	const dLon = toRadians(lon2 - lon1);
+	const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) + Math.cos(toRadians(lat1)) * Math.cos(toRadians(lat2)) * Math.sin(dLon / 2) * Math.sin(dLon / 2);
+	return EARTH_RADIUS_KM * (2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a)));
+}
+function findNearestStation(latitude, longitude, stations) {
+	if (stations.length === 0) return null;
+	let nearest = null;
+	let minDistance = Infinity;
+	for (const station of stations) {
+		const distance = haversineDistance(latitude, longitude, station.latitude, station.longitude);
+		if (distance < minDistance) {
+			minDistance = distance;
+			nearest = {
+				...station,
+				distance
+			};
+		}
+	}
+	return nearest;
+}
+function findNearestStations(latitude, longitude, stations, limit = 5) {
+	const withDistances = stations.map((station) => ({
+		...station,
+		distance: haversineDistance(latitude, longitude, station.latitude, station.longitude)
+	}));
+	withDistances.sort((a, b) => a.distance - b.distance);
+	return withDistances.slice(0, limit);
+}
+
+//#endregion
+//#region src/utils/build-url.util.ts
+function buildUrl(baseUrl, path, params) {
+	const url = new URL(baseUrl + path);
+	if (params) Object.entries(params).forEach(([key, value]) => {
+		if (value !== void 0) url.searchParams.set(key, String(value));
+	});
+	return url;
+}
+
+//#endregion
+//#region src/client/iqair-client.ts
+var IQAirClient = class {
+	baseUrl;
+	locale;
+	userAgent;
+	constructor(config = {}) {
+		this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+		this.locale = config.locale ?? DEFAULT_LOCALE;
+		this.userAgent = config.userAgent ?? DEFAULT_USER_AGENT;
+	}
+	async request(url) {
+		return fetchAndDecode(url, this.userAgent);
+	}
+	async getStations(params) {
+		const url = buildUrl(this.baseUrl, `/${this.locale}/profile/${params.dataSource}.data`, {
+			limit: params.limit ?? 500,
+			_routes: STATION_LIST_ROUTES
+		});
+		const stationsData = ((await this.request(url.toString()))["routes/$(locale).profile.$slug"]?.data)?.stationsMapData?.data;
+		if (!stationsData || stationsData.length === 0) return [];
+		return stationsData.map((station) => ({
+			id: station.id,
+			name: station.name,
+			url: station.url,
+			latitude: station.coordinates.latitude,
+			longitude: station.coordinates.longitude
+		}));
+	}
+	async getStationAQI(params) {
+		const url = buildUrl(this.baseUrl, `/${this.locale}${params.stationUrl}.data`, { _routes: INDIVIDUAL_STATION_ROUTES });
+		const data = await this.request(url.toString());
+		const routeData = data.root?.data || data["routes/$"]?.data;
+		const details = routeData?.details;
+		if (!details || !details.current) throw new IQAirException("No station details found in response", 404);
+		const measurements = routeData?.measurements?.data?.measurements;
+		const historical = measurements ? {
+			hourly: measurements.hourly || [],
+			daily: measurements.daily || []
+		} : void 0;
+		return {
+			station: {
+				id: details.id,
+				name: details.name,
+				url: params.stationUrl,
+				distance: 0
+			},
+			current: {
+				ts: details.current.ts,
+				aqi: details.current.aqi,
+				mainPollutant: details.current.mainPollutant,
+				concentration: details.current.concentration,
+				condition: details.current.condition,
+				temperature: details.current.temperature,
+				humidity: details.current.humidity,
+				pressure: details.current.pressure,
+				wind: details.current.wind
+			},
+			pollutants: details.current.pollutants?.map((p) => ({
+				name: p.pollutantName,
+				aqi: p.aqi,
+				concentration: p.concentration,
+				unit: p.unit
+			})),
+			historical
+		};
+	}
+	async getNearestStation(params) {
+		const stations = await this.getStations({ dataSource: params.dataSource });
+		return findNearestStation(params.lat, params.lng, stations);
+	}
+	async getNearestStations(params) {
+		const stations = await this.getStations({ dataSource: params.dataSource });
+		return findNearestStations(params.lat, params.lng, stations, params.limit);
+	}
+	async getAQIForLocation(params) {
+		const nearestStation = await this.getNearestStation({
+			lat: params.lat,
+			lng: params.lng,
+			dataSource: params.dataSource
+		});
+		if (!nearestStation) return null;
+		const aqi = await this.getStationAQI({ stationUrl: nearestStation.url });
+		aqi.station.distance = nearestStation.distance;
+		return aqi;
+	}
+};
+
+//#endregion
+//#region src/client/create-iqair-client.ts
+function createIQAirClient(config) {
+	return new IQAirClient(config);
+}
+
+//#endregion
+export { IQAirClient, IQAirException, createIQAirClient };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["nearest: StationWithDistance | null","withDistances: StationWithDistance[]"],"sources":["../src/constants/base-url.constant.ts","../src/constants/locale.constant.ts","../src/constants/routes.constant.ts","../src/constants/user-agent.constant.ts","../src/exceptions/iqair.exception.ts","../src/utils/decoder.util.ts","../src/utils/geo.util.ts","../src/utils/build-url.util.ts","../src/client/iqair-client.ts","../src/client/create-iqair-client.ts"],"sourcesContent":["export const DEFAULT_BASE_URL = \"https://www.iqair.com\";\n","export const DEFAULT_LOCALE = \"in-en\";\n","export const STATION_LIST_ROUTES = encodeURIComponent(\n  \"routes/$(locale),routes/$(locale).profile.$slug\"\n);\n\nexport const INDIVIDUAL_STATION_ROUTES = encodeURIComponent(\"routes/$\");\n","export const DEFAULT_USER_AGENT =\n  \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36\";\n","export class IQAirException extends Error {\n  readonly statusCode: number;\n  readonly body?: string;\n\n  constructor(message: string, statusCode: number, body?: string) {\n    super(message);\n    this.name = \"IQAirException\";\n    this.statusCode = statusCode;\n    this.body = body;\n  }\n}\n","import { UNSAFE_decodeViaTurboStream } from \"react-router\";\nimport { IQAirException } from \"../exceptions\";\n\nasync function resolveAllPromises<T>(obj: T): Promise<T> {\n  if (obj instanceof Promise) {\n    const resolved = await obj;\n    return resolveAllPromises(resolved);\n  }\n\n  if (Array.isArray(obj)) {\n    const resolved = await Promise.all(obj.map(resolveAllPromises));\n    return resolved as T;\n  }\n\n  if (obj !== null && typeof obj === \"object\") {\n    const entries = Object.entries(obj);\n    const resolvedEntries = await Promise.all(\n      entries.map(async ([key, value]) => [key, await resolveAllPromises(value)])\n    );\n    return Object.fromEntries(resolvedEntries) as T;\n  }\n\n  return obj;\n}\n\nexport async function decodeTurboStream<T>(\n  stream: ReadableStream<Uint8Array>\n): Promise<T> {\n  const decoded = await UNSAFE_decodeViaTurboStream(stream, globalThis);\n  await decoded.done;\n  const resolved = await resolveAllPromises(decoded.value);\n  return resolved as T;\n}\n\nexport async function fetchAndDecode<T>(url: string, userAgent: string): Promise<T> {\n  const response = await fetch(url, {\n    headers: {\n      \"User-Agent\": userAgent,\n      Accept: \"*/*\",\n      \"Accept-Language\": \"en-US,en;q=0.9\",\n    },\n  });\n\n  if (!response.ok) {\n    const text = await response.text();\n    throw new IQAirException(\n      `Request failed: ${response.status} ${response.statusText}`,\n      response.status,\n      text\n    );\n  }\n\n  if (!response.body) {\n    throw new IQAirException(\"Response body is null\", 500);\n  }\n\n  return decodeTurboStream<T>(response.body);\n}\n","import type { Station, StationWithDistance } from \"../types\";\n\nconst EARTH_RADIUS_KM = 6371;\n\nfunction toRadians(degrees: number): number {\n  return degrees * (Math.PI / 180);\n}\n\nexport function haversineDistance(\n  lat1: number,\n  lon1: number,\n  lat2: number,\n  lon2: number\n): number {\n  const dLat = toRadians(lat2 - lat1);\n  const dLon = toRadians(lon2 - lon1);\n\n  const a =\n    Math.sin(dLat / 2) * Math.sin(dLat / 2) +\n    Math.cos(toRadians(lat1)) *\n      Math.cos(toRadians(lat2)) *\n      Math.sin(dLon / 2) *\n      Math.sin(dLon / 2);\n\n  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));\n\n  return EARTH_RADIUS_KM * c;\n}\n\nexport function findNearestStation(\n  latitude: number,\n  longitude: number,\n  stations: Station[]\n): StationWithDistance | null {\n  if (stations.length === 0) {\n    return null;\n  }\n\n  let nearest: StationWithDistance | null = null;\n  let minDistance = Infinity;\n\n  for (const station of stations) {\n    const distance = haversineDistance(\n      latitude,\n      longitude,\n      station.latitude,\n      station.longitude\n    );\n\n    if (distance < minDistance) {\n      minDistance = distance;\n      nearest = { ...station, distance };\n    }\n  }\n\n  return nearest;\n}\n\nexport function findNearestStations(\n  latitude: number,\n  longitude: number,\n  stations: Station[],\n  limit: number = 5\n): StationWithDistance[] {\n  const withDistances: StationWithDistance[] = stations.map((station) => ({\n    ...station,\n    distance: haversineDistance(\n      latitude,\n      longitude,\n      station.latitude,\n      station.longitude\n    ),\n  }));\n\n  withDistances.sort((a, b) => a.distance - b.distance);\n\n  return withDistances.slice(0, limit);\n}\n","export function buildUrl(\n  baseUrl: string,\n  path: string,\n  params?: Record<string, string | number | undefined>\n): URL {\n  const url = new URL(baseUrl + path);\n\n  if (params) {\n    Object.entries(params).forEach(([key, value]) => {\n      if (value !== undefined) {\n        url.searchParams.set(key, String(value));\n      }\n    });\n  }\n\n  return url;\n}\n","import { IQAirClientConfig } from \"./iqair-client.config\";\nimport {\n  DEFAULT_BASE_URL,\n  DEFAULT_LOCALE,\n  DEFAULT_USER_AGENT,\n  STATION_LIST_ROUTES,\n  INDIVIDUAL_STATION_ROUTES,\n} from \"../constants\";\nimport { IQAirException } from \"../exceptions\";\nimport { fetchAndDecode } from \"../utils/decoder.util\";\nimport { findNearestStation, findNearestStations } from \"../utils/geo.util\";\nimport { buildUrl } from \"../utils/build-url.util\";\nimport type {\n  Station,\n  StationWithDistance,\n  AQIResponse,\n  StationListResponse,\n  IndividualStationResponse,\n  GetStationsParams,\n  GetStationAQIParams,\n  GetNearestStationParams,\n  GetNearestStationsParams,\n  GetAQIForLocationParams,\n} from \"../types\";\n\nexport class IQAirClient {\n  private readonly baseUrl: string;\n  private readonly locale: string;\n  private readonly userAgent: string;\n\n  constructor(config: IQAirClientConfig = {}) {\n    this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;\n    this.locale = config.locale ?? DEFAULT_LOCALE;\n    this.userAgent = config.userAgent ?? DEFAULT_USER_AGENT;\n  }\n\n  private async request<T>(url: string): Promise<T> {\n    return fetchAndDecode<T>(url, this.userAgent);\n  }\n\n  async getStations(params: GetStationsParams): Promise<Station[]> {\n    const url = buildUrl(\n      this.baseUrl,\n      `/${this.locale}/profile/${params.dataSource}.data`,\n      {\n        limit: params.limit ?? 500,\n        _routes: STATION_LIST_ROUTES,\n      }\n    );\n\n    const data = await this.request<StationListResponse>(url.toString());\n    const routeData = data[\"routes/$(locale).profile.$slug\"]?.data;\n    const stationsData = routeData?.stationsMapData?.data;\n\n    if (!stationsData || stationsData.length === 0) {\n      return [];\n    }\n\n    return stationsData.map((station) => ({\n      id: station.id,\n      name: station.name,\n      url: station.url,\n      latitude: station.coordinates.latitude,\n      longitude: station.coordinates.longitude,\n    }));\n  }\n\n  async getStationAQI(params: GetStationAQIParams): Promise<AQIResponse> {\n    const url = buildUrl(\n      this.baseUrl,\n      `/${this.locale}${params.stationUrl}.data`,\n      {\n        _routes: INDIVIDUAL_STATION_ROUTES,\n      }\n    );\n\n    const data = await this.request<IndividualStationResponse>(url.toString());\n    const routeData = data.root?.data || data[\"routes/$\"]?.data;\n    const details = routeData?.details;\n\n    if (!details || !details.current) {\n      throw new IQAirException(\"No station details found in response\", 404);\n    }\n\n    const measurements = routeData?.measurements?.data?.measurements;\n    const historical = measurements\n      ? {\n          hourly: measurements.hourly || [],\n          daily: measurements.daily || [],\n        }\n      : undefined;\n\n    return {\n      station: {\n        id: details.id,\n        name: details.name,\n        url: params.stationUrl,\n        distance: 0,\n      },\n      current: {\n        ts: details.current.ts,\n        aqi: details.current.aqi,\n        mainPollutant: details.current.mainPollutant,\n        concentration: details.current.concentration,\n        condition: details.current.condition,\n        temperature: details.current.temperature,\n        humidity: details.current.humidity,\n        pressure: details.current.pressure,\n        wind: details.current.wind,\n      },\n      pollutants: details.current.pollutants?.map((p) => ({\n        name: p.pollutantName,\n        aqi: p.aqi,\n        concentration: p.concentration,\n        unit: p.unit,\n      })),\n      historical,\n    };\n  }\n\n  async getNearestStation(\n    params: GetNearestStationParams\n  ): Promise<StationWithDistance | null> {\n    const stations = await this.getStations({ dataSource: params.dataSource });\n    return findNearestStation(params.lat, params.lng, stations);\n  }\n\n  async getNearestStations(\n    params: GetNearestStationsParams\n  ): Promise<StationWithDistance[]> {\n    const stations = await this.getStations({ dataSource: params.dataSource });\n    return findNearestStations(params.lat, params.lng, stations, params.limit);\n  }\n\n  async getAQIForLocation(\n    params: GetAQIForLocationParams\n  ): Promise<AQIResponse | null> {\n    const nearestStation = await this.getNearestStation({\n      lat: params.lat,\n      lng: params.lng,\n      dataSource: params.dataSource,\n    });\n\n    if (!nearestStation) {\n      return null;\n    }\n\n    const aqi = await this.getStationAQI({ stationUrl: nearestStation.url });\n    aqi.station.distance = nearestStation.distance;\n    return aqi;\n  }\n}\n","import { IQAirClient } from \"./iqair-client\";\nimport { IQAirClientConfig } from \"./iqair-client.config\";\n\nexport function createIQAirClient(config?: IQAirClientConfig): IQAirClient {\n  return new IQAirClient(config);\n}\n"],"mappings":";;;AAAA,MAAa,mBAAmB;;;;ACAhC,MAAa,iBAAiB;;;;ACA9B,MAAa,sBAAsB,mBACjC,kDACD;AAED,MAAa,4BAA4B,mBAAmB,WAAW;;;;ACJvE,MAAa,qBACX;;;;ACDF,IAAa,iBAAb,cAAoC,MAAM;CACxC,AAAS;CACT,AAAS;CAET,YAAY,SAAiB,YAAoB,MAAe;AAC9D,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,aAAa;AAClB,OAAK,OAAO;;;;;;ACLhB,eAAe,mBAAsB,KAAoB;AACvD,KAAI,eAAe,QAEjB,QAAO,mBADU,MAAM,IACY;AAGrC,KAAI,MAAM,QAAQ,IAAI,CAEpB,QADiB,MAAM,QAAQ,IAAI,IAAI,IAAI,mBAAmB,CAAC;AAIjE,KAAI,QAAQ,QAAQ,OAAO,QAAQ,UAAU;EAC3C,MAAM,UAAU,OAAO,QAAQ,IAAI;EACnC,MAAM,kBAAkB,MAAM,QAAQ,IACpC,QAAQ,IAAI,OAAO,CAAC,KAAK,WAAW,CAAC,KAAK,MAAM,mBAAmB,MAAM,CAAC,CAAC,CAC5E;AACD,SAAO,OAAO,YAAY,gBAAgB;;AAG5C,QAAO;;AAGT,eAAsB,kBACpB,QACY;CACZ,MAAM,UAAU,MAAM,4BAA4B,QAAQ,WAAW;AACrE,OAAM,QAAQ;AAEd,QADiB,MAAM,mBAAmB,QAAQ,MAAM;;AAI1D,eAAsB,eAAkB,KAAa,WAA+B;CAClF,MAAM,WAAW,MAAM,MAAM,KAAK,EAChC,SAAS;EACP,cAAc;EACd,QAAQ;EACR,mBAAmB;EACpB,EACF,CAAC;AAEF,KAAI,CAAC,SAAS,IAAI;EAChB,MAAM,OAAO,MAAM,SAAS,MAAM;AAClC,QAAM,IAAI,eACR,mBAAmB,SAAS,OAAO,GAAG,SAAS,cAC/C,SAAS,QACT,KACD;;AAGH,KAAI,CAAC,SAAS,KACZ,OAAM,IAAI,eAAe,yBAAyB,IAAI;AAGxD,QAAO,kBAAqB,SAAS,KAAK;;;;;ACtD5C,MAAM,kBAAkB;AAExB,SAAS,UAAU,SAAyB;AAC1C,QAAO,WAAW,KAAK,KAAK;;AAG9B,SAAgB,kBACd,MACA,MACA,MACA,MACQ;CACR,MAAM,OAAO,UAAU,OAAO,KAAK;CACnC,MAAM,OAAO,UAAU,OAAO,KAAK;CAEnC,MAAM,IACJ,KAAK,IAAI,OAAO,EAAE,GAAG,KAAK,IAAI,OAAO,EAAE,GACvC,KAAK,IAAI,UAAU,KAAK,CAAC,GACvB,KAAK,IAAI,UAAU,KAAK,CAAC,GACzB,KAAK,IAAI,OAAO,EAAE,GAClB,KAAK,IAAI,OAAO,EAAE;AAItB,QAAO,mBAFG,IAAI,KAAK,MAAM,KAAK,KAAK,EAAE,EAAE,KAAK,KAAK,IAAI,EAAE,CAAC;;AAK1D,SAAgB,mBACd,UACA,WACA,UAC4B;AAC5B,KAAI,SAAS,WAAW,EACtB,QAAO;CAGT,IAAIA,UAAsC;CAC1C,IAAI,cAAc;AAElB,MAAK,MAAM,WAAW,UAAU;EAC9B,MAAM,WAAW,kBACf,UACA,WACA,QAAQ,UACR,QAAQ,UACT;AAED,MAAI,WAAW,aAAa;AAC1B,iBAAc;AACd,aAAU;IAAE,GAAG;IAAS;IAAU;;;AAItC,QAAO;;AAGT,SAAgB,oBACd,UACA,WACA,UACA,QAAgB,GACO;CACvB,MAAMC,gBAAuC,SAAS,KAAK,aAAa;EACtE,GAAG;EACH,UAAU,kBACR,UACA,WACA,QAAQ,UACR,QAAQ,UACT;EACF,EAAE;AAEH,eAAc,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,SAAS;AAErD,QAAO,cAAc,MAAM,GAAG,MAAM;;;;;AC5EtC,SAAgB,SACd,SACA,MACA,QACK;CACL,MAAM,MAAM,IAAI,IAAI,UAAU,KAAK;AAEnC,KAAI,OACF,QAAO,QAAQ,OAAO,CAAC,SAAS,CAAC,KAAK,WAAW;AAC/C,MAAI,UAAU,OACZ,KAAI,aAAa,IAAI,KAAK,OAAO,MAAM,CAAC;GAE1C;AAGJ,QAAO;;;;;ACUT,IAAa,cAAb,MAAyB;CACvB,AAAiB;CACjB,AAAiB;CACjB,AAAiB;CAEjB,YAAY,SAA4B,EAAE,EAAE;AAC1C,OAAK,UAAU,OAAO,WAAW;AACjC,OAAK,SAAS,OAAO,UAAU;AAC/B,OAAK,YAAY,OAAO,aAAa;;CAGvC,MAAc,QAAW,KAAyB;AAChD,SAAO,eAAkB,KAAK,KAAK,UAAU;;CAG/C,MAAM,YAAY,QAA+C;EAC/D,MAAM,MAAM,SACV,KAAK,SACL,IAAI,KAAK,OAAO,WAAW,OAAO,WAAW,QAC7C;GACE,OAAO,OAAO,SAAS;GACvB,SAAS;GACV,CACF;EAID,MAAM,iBAFO,MAAM,KAAK,QAA6B,IAAI,UAAU,CAAC,EAC7C,mCAAmC,OAC1B,iBAAiB;AAEjD,MAAI,CAAC,gBAAgB,aAAa,WAAW,EAC3C,QAAO,EAAE;AAGX,SAAO,aAAa,KAAK,aAAa;GACpC,IAAI,QAAQ;GACZ,MAAM,QAAQ;GACd,KAAK,QAAQ;GACb,UAAU,QAAQ,YAAY;GAC9B,WAAW,QAAQ,YAAY;GAChC,EAAE;;CAGL,MAAM,cAAc,QAAmD;EACrE,MAAM,MAAM,SACV,KAAK,SACL,IAAI,KAAK,SAAS,OAAO,WAAW,QACpC,EACE,SAAS,2BACV,CACF;EAED,MAAM,OAAO,MAAM,KAAK,QAAmC,IAAI,UAAU,CAAC;EAC1E,MAAM,YAAY,KAAK,MAAM,QAAQ,KAAK,aAAa;EACvD,MAAM,UAAU,WAAW;AAE3B,MAAI,CAAC,WAAW,CAAC,QAAQ,QACvB,OAAM,IAAI,eAAe,wCAAwC,IAAI;EAGvE,MAAM,eAAe,WAAW,cAAc,MAAM;EACpD,MAAM,aAAa,eACf;GACE,QAAQ,aAAa,UAAU,EAAE;GACjC,OAAO,aAAa,SAAS,EAAE;GAChC,GACD;AAEJ,SAAO;GACL,SAAS;IACP,IAAI,QAAQ;IACZ,MAAM,QAAQ;IACd,KAAK,OAAO;IACZ,UAAU;IACX;GACD,SAAS;IACP,IAAI,QAAQ,QAAQ;IACpB,KAAK,QAAQ,QAAQ;IACrB,eAAe,QAAQ,QAAQ;IAC/B,eAAe,QAAQ,QAAQ;IAC/B,WAAW,QAAQ,QAAQ;IAC3B,aAAa,QAAQ,QAAQ;IAC7B,UAAU,QAAQ,QAAQ;IAC1B,UAAU,QAAQ,QAAQ;IAC1B,MAAM,QAAQ,QAAQ;IACvB;GACD,YAAY,QAAQ,QAAQ,YAAY,KAAK,OAAO;IAClD,MAAM,EAAE;IACR,KAAK,EAAE;IACP,eAAe,EAAE;IACjB,MAAM,EAAE;IACT,EAAE;GACH;GACD;;CAGH,MAAM,kBACJ,QACqC;EACrC,MAAM,WAAW,MAAM,KAAK,YAAY,EAAE,YAAY,OAAO,YAAY,CAAC;AAC1E,SAAO,mBAAmB,OAAO,KAAK,OAAO,KAAK,SAAS;;CAG7D,MAAM,mBACJ,QACgC;EAChC,MAAM,WAAW,MAAM,KAAK,YAAY,EAAE,YAAY,OAAO,YAAY,CAAC;AAC1E,SAAO,oBAAoB,OAAO,KAAK,OAAO,KAAK,UAAU,OAAO,MAAM;;CAG5E,MAAM,kBACJ,QAC6B;EAC7B,MAAM,iBAAiB,MAAM,KAAK,kBAAkB;GAClD,KAAK,OAAO;GACZ,KAAK,OAAO;GACZ,YAAY,OAAO;GACpB,CAAC;AAEF,MAAI,CAAC,eACH,QAAO;EAGT,MAAM,MAAM,MAAM,KAAK,cAAc,EAAE,YAAY,eAAe,KAAK,CAAC;AACxE,MAAI,QAAQ,WAAW,eAAe;AACtC,SAAO;;;;;;AClJX,SAAgB,kBAAkB,QAAyC;AACzE,QAAO,IAAI,YAAY,OAAO"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "iqair-api",
+  "type": "module",
+  "version": "1.0.1",
+  "description": "Fully typed TypeScript SDK for scraping IQAir air quality data",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neo773/iqair-api.git"
+  },
+  "author": "neo773",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown src/index.ts",
+    "dev": "tsdown src/index.ts --watch",
+    "test": "bun test",
+    "test:unit": "bun test tests/unit",
+    "test:e2e": "bun test tests/e2e",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "iqair",
+    "air-quality",
+    "aqi",
+    "pollution",
+    "pm25",
+    "api",
+    "sdk"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "react-router": "^7.6.1",
+    "turbo-stream": "^2.4.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "tsdown": "^0.18.1",
+    "typescript": "^5.9.3"
+  },
+  "directories": {
+    "example": "examples",
+    "test": "tests"
+  },
+  "bugs": {
+    "url": "https://github.com/neo773/iqair-api/issues"
+  },
+  "homepage": "https://github.com/neo773/iqair-api#readme"
+}