airthings-consumer-api/lib/client.d.ts

An unofficial Node.js client library for Airthings Air Quality Monitors via the Airthings Consumer API.

import { SensorUnits } from './schemas.js';
import type { Accounts, Devices, RemoteControlState, SensorResults, SensorResultsRateLimitMetrics } from './schemas.js';
/**
 * The Airthings for Consumer API provides secure and authorized access for Airthings
 * consumers to retrieve the latest data from their Airthings air quality monitors. Leveraging
 * HTTPS and OAuth for enhanced security, this API empowers users to seamlessly access
 * real-time information from their Airthings devices, gaining valuable insights into the air
 * quality within their environments.
 */
export declare class AirthingsClient {
    #private;
    /**
     * @param opts - The options for the Airthings client, primarily client credentials
     * @remarks
     * Create an Airthings Client ID & Secret at https://consumer-api-doc.airthings.com/dashboard
     * @example
     * ```javascript
     * const client = new AirthingsClient({
     *     clientId: 'clientId',
     *     clientSecret: 'clientSecret'
     * });
     * ```
     */
    constructor(opts: AirthingsClientOpts);
    /**
     * List all accounts the current user is member of
     * @returns
     * Lists all accounts the current user is member of. The data returned by this endpoint
     * changes when a user is added or removed from business accounts. It is safe to assume
     * that the accountId remains constant for Consumer users. The accountId returned by this
     * endpoint is used to fetch the devices and sensors from the other endpoints.
     * @see [Airthings Consumer API: Accounts](https://consumer-api-doc.airthings.com/api-docs#tag/Accounts)
     * @throws {@link AirthingsError} If the request fails
     */
    getAccounts(): Promise<Accounts>;
    /**
     * Get all devices connected to a user
     * @returns
     * List all devices (and their sensor abilities) connected to a user’s account. The data
     * returned by this endpoint changes when a device is registered, unregistered or renamed.
     * @see [Airthings Consumer API: Devices](https://consumer-api-doc.airthings.com/api-docs#tag/Device)
     * @throws {@link AirthingsError} If the request fails
     * @example
     * ```javascript
     * const devicesResponse = await client.getDevices();
     * devicesResponse.devices.forEach((device) => {
     *   console.log(device);
     * });
     * ```
     */
    getDevices(): Promise<Devices>;
    /**
     * Get sensors for a set of devices
     * @param unit - The units type sensor values will be returned in, metric or imperial
     * @param sn - An optional list of serial numbers to filter the results
     * @returns
     * Get sensors for a set of devices. The response will contain the latest sensor values for
     * the devices. The sensor values are updated depending on the device types sampling
     * rate. It is recommended to poll the API at a regular interval to get the latest
     * sensor values. The response will be paginated with a maximum of 50 records per page.
     * @see [Airthings Consumer API: Sensors](https://consumer-api-doc.airthings.com/api-docs#tag/Sensor)
     * @throws {@link AirthingsError} If the request fails
     * @example
     * ```javascript
     * const sensorsResponse = await client.getSensors(SensorUnits.Imperial);
     * sensorsResponse.results.forEach((sensor) => {
     *   console.log(sensor);
     * });
     * ```
     */
    getSensors(unit: SensorUnits, sn?: string[]): Promise<SensorResults>;
    /**
     * Get the remote control state of a Renew device
     * @param sn - The serial number of the device
     * @returns
     * The last reported operational mode of a Renew (AP\_1) air purifier.
     * The state reflects what the device last reported, not necessarily the
     * command last sent. If the device has never synced a mode, a 404 error
     * is returned.
     * @see [Airthings Consumer API: Remote Control](https://consumer-api-doc.airthings.com/api-docs#tag/Remote-Control)
     * @throws {@link AirthingsError} If the request fails
     * @example
     * ```javascript
     * const state = await client.getRemoteControl('4100007329');
     * console.log(state.mode);
     * ```
     */
    getRemoteControl(sn: string): Promise<RemoteControlState>;
    /**
     * Set the remote control mode of a Renew device
     * @param sn - The serial number of the device
     * @param state - The desired operational mode and optional fan speed
     * @returns
     * Set the operational mode of a Renew (AP\_1) air purifier. Available modes
     * are OFF, AUTO, SLEEP, BOOST, and MANUAL. Fan speed (1-5) is required for
     * MANUAL mode. The command is forwarded to the device asynchronously. Use
     * {@link getRemoteControl} to confirm the device has applied the new mode.
     * @see [Airthings Consumer API: Remote Control](https://consumer-api-doc.airthings.com/api-docs#tag/Remote-Control)
     * @throws {@link AirthingsError} If the request fails
     * @example
     * ```javascript
     * import { RemoteControlMode } from 'airthings-consumer-api';
     *
     * await client.setRemoteControl('4100007329', {
     *     mode: RemoteControlMode.Manual,
     *     fanSpeed: 3
     * });
     * ```
     */
    setRemoteControl(sn: string, state: RemoteControlState): Promise<void>;
    /**
     * Get rate limit metrics from the last getSensors request
     * @returns
     * Current rate limit metrics reflecting the `X-RateLimit-Limit`,
     * `X-RateLimit-Remaining`, and `X-RateLimit-Reset` response headers from
     * the most recent {@link getSensors} call. Before any {@link getSensors}
     * call has been made, all rate limit metrics are initialised to `-1`.
     * @see [Airthings Consumer API: Rate Limits](https://consumer-api-doc.airthings.com/docs/api/rate-limit)
     */
    getSensorsRateLimitMetrics(): SensorResultsRateLimitMetrics;
}
export interface AirthingsClientOpts {
    /**  Override the default Account ID */
    accountId?: string;
    /**  Client ID created via the Airthings Dashboard */
    clientId: string;
    /**  Client Secret created via the Airthings Dashboard */
    clientSecret: string;
}
export declare class AirthingsError extends Error {
}
//# sourceMappingURL=client.d.ts.map