@telemetryos/root-sdk 1.8.3 → 1.10.0

package/dist/mqtt.d.ts

@@ -0,0 +1,43 @@
+import { Client, type MessageHandler } from './client.js';
+export type MqttBrokerInfo = {
+    name: string;
+    address: string;
+    port: number;
+    protocol: 'mqtt' | 'mqtts' | 'ws' | 'wss';
+};
+export type MqttConnectOptions = {
+    username?: string;
+    password?: string;
+    clientId?: string;
+    keepalive?: number;
+    clean?: boolean;
+    reconnectPeriod?: number;
+    connectTimeout?: number;
+};
+export type MqttPublishOptions = {
+    qos?: 0 | 1 | 2;
+    retain?: boolean;
+};
+export type MqttSubscribeOptions = {
+    qos?: 0 | 1 | 2;
+};
+export type MqttConnectionStatus = 'connected' | 'disconnected' | 'connecting' | 'reconnecting' | 'error';
+export type MqttMessage = {
+    topic: string;
+    payload: string;
+    qos: 0 | 1 | 2;
+    retain: boolean;
+};
+export declare class Mqtt {
+    _client: Client;
+    constructor(client: Client);
+    discover(): Promise<MqttBrokerInfo[]>;
+    connect(brokerUrl: string, options?: MqttConnectOptions): Promise<string>;
+    disconnect(clientId: string): Promise<void>;
+    publish(clientId: string, topic: string, payload: string, options?: MqttPublishOptions): Promise<void>;
+    subscribe(clientId: string, topic: string, handler: MessageHandler<MqttMessage>, options?: MqttSubscribeOptions): Promise<boolean>;
+    unsubscribe(clientId: string, topic: string, handler?: MessageHandler<MqttMessage>): Promise<boolean>;
+    getConnectionStatus(clientId: string): Promise<MqttConnectionStatus>;
+    subscribeConnectionStatus(clientId: string, handler: MessageHandler<MqttConnectionStatus>): Promise<boolean>;
+    unsubscribeConnectionStatus(clientId: string, handler?: MessageHandler<MqttConnectionStatus>): Promise<boolean>;
+}

package/dist/weather.d.ts

@@ -1,165 +1,378 @@
 import type { Client } from './client.js';
 /**
- * Weather condition data with current conditions
+ * Weather location information shared across all weather endpoints
  */
-export type WeatherConditions = {
-    /** City name (localized) */
-    CityLocalized: string;
-    /** City name (English) */
-    CityEnglish: string;
-    /** Wind abbreviation */
-    WindAbbr: string;
-    /** ISO country code */
-    CountryCode: string;
-    /** Timezone */
-    Timezone: string;
-    /** Weather description text */
-    WeatherText: string;
-    /** State/Province */
-    State: string;
-    /** Part of day (day/night indicator) */
-    Pod: string;
-    /** Weather code (internal mapping) */
-    WeatherCode: string;
-    /** Wind direction in degrees */
-    WindDirectionDegrees: string;
-    /** Wind direction (cardinal direction in English) */
-    WindDirectionEnglish: string;
-    /** Wind direction (localized) */
-    WindDirectionLocalized: string;
-    /** Relative humidity percentage */
-    RelativeHumidity: number;
-    /** Unix timestamp */
-    Timestamp: number;
-    /** Longitude */
-    Longitude: number;
-    /** Latitude */
-    Latitude: number;
-    /** Temperature */
-    Temp: number;
-    /** Atmospheric pressure */
-    Pressure: number;
-    /** Wind speed */
-    WindSpeed: number;
-    /** Visibility distance */
-    Visibility: number;
-    /** Precipitation amount */
-    Precip: number;
+type WeatherLocation = {
+    latitude: number;
+    longitude: number;
+    cityName: string;
+    stateName?: string;
+    stateCode?: string;
+    countryName: string;
+    countryCode: string;
+    timezone: string;
 };
 /**
- * Weather forecast data point
+ * Current weather conditions
  */
-export type WeatherForecast = {
-    /** ISO datetime string */
-    Datetime: string;
-    /** Part of day (day/night indicator) */
-    Pod: string;
-    /** Weather description label */
-    Label: string;
-    /** Weather code */
-    WeatherCode: string;
-    /** Unix timestamp */
-    Timestamp: number;
-    /** Temperature */
-    Temp: number;
-    /** Minimum temperature */
-    MinTemp: number;
-    /** Maximum temperature */
-    MaxTemp: number;
+export type WeatherPartOfDay = 'day' | 'night';
+export type WeatherConditions = WeatherLocation & {
+    observedAtSec: number;
+    observedAtLocal: string;
+    sunrise: string;
+    sunset: string;
+    partOfDay: WeatherPartOfDay;
+    weatherCode: number;
+    weatherDescription: string;
+    weatherIcon: string;
+    temperatureC: number;
+    temperatureF: number;
+    temperatureFeelsLikeC: number;
+    temperatureFeelsLikeF: number;
+    dewPointC: number;
+    dewPointF: number;
+    windSpeedKph: number;
+    windSpeedMph: number;
+    gustSpeedKph: number;
+    gustSpeedMph: number;
+    windDirectionDeg: number;
+    windDirectionFull: string;
+    windDirectionShort: string;
+    pressureMb: number;
+    pressureInHg: number;
+    seaLevelPressureMb: number;
+    seaLevelPressureInHg: number;
+    visibilityKm: number;
+    visibilityMi: number;
+    humidity: number;
+    clouds: number;
+    precipitationRateMmph: number;
+    precipitationRateInph: number;
+    snowfallRateMmph: number;
+    snowfallRateInph: number;
+    uvIndex: number;
+    airQualityIndex: number;
 };
 /**
- * Parameters for weather requests
+ * Single day of forecast data
  */
-export type WeatherRequestParams = {
-    /** City name (can include state/country: "city, state, country") */
-    city?: string;
-    /** Postal/ZIP code (alternative to city) */
-    postalCode?: string;
-    /** Latitude (if city not provided) */
-    lat?: string;
-    /** Longitude (if city not provided) */
-    lon?: string;
-    /** Units system: "imperial" or "metric" */
-    units?: 'imperial' | 'metric';
-    /** Language code for localized responses */
+export type DailyForecastData = {
+    forecastDate: string;
+    forecastDateSec: number;
+    weatherCode: number;
+    weatherDescription: string;
+    weatherIcon: string;
+    precipitationProbability: number;
+    temperatureC: number;
+    temperatureF: number;
+    maxTemperatureC: number;
+    maxTemperatureF: number;
+    minTemperatureC: number;
+    minTemperatureF: number;
+    highTemperatureC: number;
+    highTemperatureF: number;
+    lowTemperatureC: number;
+    lowTemperatureF: number;
+    maxTemperatureFeelsLikeC: number;
+    maxTemperatureFeelsLikeF: number;
+    minTemperatureFeelsLikeC: number;
+    minTemperatureFeelsLikeF: number;
+    dewPointC: number;
+    dewPointF: number;
+    windSpeedKph: number;
+    windSpeedMph: number;
+    gustSpeedKph: number;
+    gustSpeedMph: number;
+    windDirectionDeg: number;
+    windDirectionFull: string;
+    windDirectionShort: string;
+    pressureMb: number;
+    pressureInHg: number;
+    seaLevelPressureMb: number;
+    seaLevelPressureInHg: number;
+    visibilityKm: number;
+    visibilityMi: number;
+    humidity: number;
+    clouds: number;
+    precipitationMm: number;
+    precipitationIn: number;
+    snowfallMm: number;
+    snowfallIn: number;
+    snowDepthMm: number;
+    snowDepthIn: number;
+    uvIndex: number;
+    sunrise: string;
+    sunset: string;
+    moonrise: string;
+    moonset: string;
+    moonIllumination: number;
+    moonLunationPhase: number;
+};
+/**
+ * Daily weather forecast with location
+ */
+export type DailyForecast = WeatherLocation & {
+    data: DailyForecastData[];
+};
+/**
+ * Single hour of forecast data
+ */
+export type HourlyForecastData = {
+    forecastTimeSec: number;
+    forecastTimeLocal: string;
+    forecastTimeUtc: string;
+    partOfDay: WeatherPartOfDay;
+    weatherCode: number;
+    weatherDescription: string;
+    weatherIcon: string;
+    precipitationProbability: number;
+    temperatureC: number;
+    temperatureF: number;
+    temperatureFeelsLikeC: number;
+    temperatureFeelsLikeF: number;
+    dewPointC: number;
+    dewPointF: number;
+    windSpeedKph: number;
+    windSpeedMph: number;
+    gustSpeedKph: number;
+    gustSpeedMph: number;
+    windDirectionDeg: number;
+    windDirectionFull: string;
+    windDirectionShort: string;
+    pressureMb: number;
+    pressureInHg: number;
+    seaLevelPressureMb: number;
+    seaLevelPressureInHg: number;
+    visibilityKm: number;
+    visibilityMi: number;
+    humidity: number;
+    clouds: number;
+    precipitationMm: number;
+    precipitationIn: number;
+    snowfallMm: number;
+    snowfallIn: number;
+    snowDepthMm: number;
+    snowDepthIn: number;
+    uvIndex: number;
+};
+/**
+ * Hourly weather forecast with location
+ */
+export type HourlyForecast = WeatherLocation & {
+    data: HourlyForecastData[];
+};
+/**
+ * Single weather alert/warning
+ */
+export type WeatherAlertSeverity = 'Advisory' | 'Watch' | 'Warning';
+export type WeatherAlert = {
+    title: string;
+    description: string;
+    severity: WeatherAlertSeverity;
+    effectiveSec: number;
+    effectiveUtc: string;
+    effectiveLocal: string;
+    expiresSec: number;
+    expiresUtc: string;
+    expiresLocal: string;
+    onsetSec?: number;
+    onsetUtc?: string;
+    onsetLocal?: string;
+    endsSec?: number;
+    endsUtc?: string;
+    endsLocal?: string;
+    uri: string;
+    regions: string[];
+};
+/**
+ * Weather alerts with location
+ */
+export type WeatherAlerts = WeatherLocation & {
+    alerts: WeatherAlert[];
+};
+/**
+ * City information for location search
+ */
+export type WeatherCity = {
+    cityId: number;
+    cityName: string;
+    stateName?: string;
+    stateCode?: string;
+    countryName: string;
+    countryCode: string;
+    latitude: number;
+    longitude: number;
+};
+/**
+ * Parameters for getting current weather conditions
+ */
+export type WeatherConditionsParams = {
+    /** WeatherBit city ID (required) */
+    cityId: number;
+    /** Language code for localized responses (optional) */
     language?: string;
 };
 /**
- * Parameters for daily forecast requests
+ * Parameters for getting daily forecast
  */
-export type DailyForecastParams = WeatherRequestParams & {
-    /** Number of days to forecast */
+export type DailyForecastParams = {
+    /** WeatherBit city ID (required) */
+    cityId: number;
+    /** Language code for localized responses (optional) */
+    language?: string;
+    /** Number of days to forecast, max 16 (optional, default 5) */
     days?: number;
 };
 /**
- * Parameters for hourly forecast requests
+ * Parameters for getting hourly forecast
  */
-export type HourlyForecastParams = WeatherRequestParams & {
-    /** Number of hours to forecast */
+export type HourlyForecastParams = {
+    /** WeatherBit city ID (required) */
+    cityId: number;
+    /** Language code for localized responses (optional) */
+    language?: string;
+    /** Number of hours to forecast, max 120 (optional, default 12) */
     hours?: number;
 };
+/**
+ * Parameters for getting weather alerts
+ */
+export type WeatherAlertsParams = {
+    /** WeatherBit city ID (required) */
+    cityId: number;
+    /** Language code for localized responses (optional) */
+    language?: string;
+};
+/**
+ * Parameters for searching cities
+ */
+export type CitiesSearchParams = {
+    /** ISO country code filter (optional) */
+    countryCode?: string;
+    /** City name search query (optional) */
+    search?: string;
+};
 /**
  * Weather API for retrieving weather data
  *
- * Provides access to current conditions and forecasts through the TelemetryOS API.
+ * Provides access to current conditions, forecasts, alerts, and city search
+ * through the TelemetryOS weather API v2.
  */
 export declare class Weather {
     _client: Client;
     constructor(client: Client);
     /**
-     * Retrieves current weather conditions for a specified location.
+     * Searches for cities by name or country
+     *
+     * @param params - Search parameters including optional country code and search query
+     * @returns A promise that resolves to an array of matching cities
+     * @throws {Error} If the request fails
+     *
+     * @example
+     * ```typescript
+     * // Search for cities named "New York"
+     * const cities = await weather.getCities({ search: 'New York' })
+     *
+     * // Search for cities in the United States
+     * const cities = await weather.getCities({ countryCode: 'US' })
+     *
+     * // Get a cityId for use in other methods
+     * const cities = await weather.getCities({ search: 'London' })
+     * const cityId = cities[0].cityId
+     * ```
+     */
+    getCities(params: CitiesSearchParams): Promise<WeatherCity[]>;
+    /**
+     * Retrieves current weather conditions for a specified city
      *
-     * @param params - Weather request parameters including location and units
-     * @returns A promise that resolves to the current weather conditions
-     * @throws {Error} If the request fails or location is invalid
+     * @param params - Weather request parameters including cityId and optional language
+     * @returns A promise that resolves to the current weather conditions with dual units (C/F, kph/mph, etc.)
+     * @throws {Error} If the request fails or cityId is invalid
      *
      * @example
      * ```typescript
-     * // Get weather by city
-     * const weather = await weather.getConditions({ city: 'New York', units: 'imperial' })
+     * // Get current conditions for a city
+     * const conditions = await weather.getConditions({ cityId: 12345 })
      *
-     * // Get weather by postal code
-     * const weather = await weather.getConditions({ postalCode: '10001', units: 'metric' })
+     * // With localized language
+     * const conditions = await weather.getConditions({
+     *   cityId: 12345,
+     *   language: 'es'
+     * })
      *
-     * // Get weather by coordinates
-     * const weather = await weather.getConditions({ lat: '40.7128', lon: '-74.0060' })
+     * // Access both units
+     * console.log(`${conditions.temperatureC}°C / ${conditions.temperatureF}°F`)
+     * console.log(`${conditions.windSpeedKph} kph / ${conditions.windSpeedMph} mph`)
      * ```
      */
-    getConditions(params: WeatherRequestParams): Promise<WeatherConditions>;
+    getConditions(params: WeatherConditionsParams): Promise<WeatherConditions>;
     /**
-     * Retrieves daily weather forecast for a specified location.
+     * Retrieves daily weather forecast for a specified city
      *
-     * @param params - Forecast request parameters including location, units, and number of days
-     * @returns A promise that resolves to an array of daily forecast data
-     * @throws {Error} If the request fails or location is invalid
+     * @param params - Forecast request parameters including cityId, optional language and days
+     * @returns A promise that resolves to daily forecast data with location information
+     * @throws {Error} If the request fails or cityId is invalid
      *
      * @example
      * ```typescript
      * // Get 5-day forecast
-     * const forecast = await weather.getDailyForecast({
-     *   city: 'London',
-     *   units: 'metric',
-     *   days: 5
+     * const forecast = await weather.getDailyForecast({ cityId: 12345 })
+     *
+     * // Get 10-day forecast
+     * const forecast = await weather.getDailyForecast({ cityId: 12345, days: 10 })
+     *
+     * // Access forecast data
+     * forecast.data.forEach(day => {
+     *   console.log(`${day.forecastDate}: ${day.weatherDescription}`)
+     *   console.log(`High: ${day.maxTemperatureC}°C, Low: ${day.minTemperatureC}°C`)
      * })
      * ```
      */
-    getDailyForecast(params: DailyForecastParams): Promise<WeatherForecast[]>;
+    getDailyForecast(params: DailyForecastParams): Promise<DailyForecast>;
     /**
-     * Retrieves hourly weather forecast for a specified location.
+     * Retrieves hourly weather forecast for a specified city
      *
-     * @param params - Forecast request parameters including location, units, and number of hours
-     * @returns A promise that resolves to an array of hourly forecast data
-     * @throws {Error} If the request fails or location is invalid
+     * @param params - Forecast request parameters including cityId, optional language and hours
+     * @returns A promise that resolves to hourly forecast data with location information
+     * @throws {Error} If the request fails or cityId is invalid
      *
      * @example
      * ```typescript
      * // Get 24-hour forecast
-     * const forecast = await weather.getHourlyForecast({
-     *   city: 'Tokyo',
-     *   units: 'metric',
-     *   hours: 24
+     * const forecast = await weather.getHourlyForecast({ cityId: 12345, hours: 24 })
+     *
+     * // Get 48-hour forecast
+     * const forecast = await weather.getHourlyForecast({ cityId: 12345, hours: 48 })
+     *
+     * // Access forecast data
+     * forecast.data.forEach(hour => {
+     *   console.log(`${hour.forecastTimeLocal}: ${hour.weatherDescription}`)
+     *   console.log(`Temp: ${hour.temperatureC}°C`)
      * })
      * ```
      */
-    getHourlyForecast(params: HourlyForecastParams): Promise<WeatherForecast[]>;
+    getHourlyForecast(params: HourlyForecastParams): Promise<HourlyForecast>;
+    /**
+     * Retrieves weather alerts and warnings for a specified city
+     *
+     * @param params - Alert request parameters including cityId and optional language
+     * @returns A promise that resolves to weather alerts with location information
+     * @throws {Error} If the request fails or cityId is invalid
+     *
+     * @example
+     * ```typescript
+     * // Get weather alerts for a city
+     * const alerts = await weather.getAlerts({ cityId: 12345 })
+     *
+     * // Check if there are any active alerts
+     * if (alerts.alerts.length > 0) {
+     *   alerts.alerts.forEach(alert => {
+     *     console.log(`${alert.severity}: ${alert.title}`)
+     *     console.log(alert.description)
+     *   })
+     * }
+     * ```
+     */
+    getAlerts(params: WeatherAlertsParams): Promise<WeatherAlerts>;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetryos/root-sdk",
-  "version": "1.8.3",
+  "version": "1.10.0",
   "description": "The official TelemetryOS root application sdk package. Provides types and apis for building root TelemetryOS applications.",
   "type": "module",
   "main": "dist/index.cjs",