waterguru-api-js

TypeScript client library for accessing the WaterGuru dashboard data.

Table of Contents

• waterguru-api-js
  • Table of Contents
  • Installation
  • Quick Start
  • API
    • new WaterGuruAPI(options)
    • getDashboard(): Promise<WaterGuruDashboard>
  • Types
  • Error Handling
  • Demo
  • Changelog
    • [1.2.0] - 2025-10-10
      • Changed
    • [1.1.1] - 2025-10-08
      • Fixed
      • Changed
    • [1.1.0] - 2025-09-21
      • Added
    • [1.0.0] - 2025-09-20
      • Added
  • Caveats & Limitations
  • License
  • Credits

Installation

npm install waterguru-api-js
# or
yarn add waterguru-api-js
# or
ban add water-guru-js

Quick Start

import { WaterGuruAPI, WaterGuruDashboard } from 'waterguru-api-js';

async function main() {
  try {
    const username = process.env.WATERGURU_USER!;
    const password = process.env.WATERGURU_PASSWORD!;

    const api = new WaterGuruAPI({ username, password });
    const dashboard: WaterGuruDashboard = await api.getDashboard();

    console.log('Status:', dashboard.status);
    console.log('Water Bodies:', dashboard.waterBodies.length);

  }
  catch (error) {
    console.error('WaterGuru API error:', error)
  }
}

main().catch(console.error);

API

new WaterGuruAPI(options)

Constructor options:

| Option | Type | Required | Description | | ---------- | -------- | -------- | ------------------------------- | | username | string | ✅ | Your WaterGuru account email | | password | string | ✅ | Your WaterGuru account password |

getDashboard(): Promise<WaterGuruDashboard>

Returns the full dashboard data object. Includes water bodies, alerts, measurements, etc.

Types

Some important types exported by this library:

export interface WaterGuruDashboard {
  rspType: string;
  code: string;
  lastModified: string;
  status: 'GREEN' | 'YELLOW' | 'RED';
  waterBodies: WaterBodyView[];
  // ... more fields
}

export interface WaterBodyView {
  viewType: string;
  status: 'GREEN' | 'YELLOW' | 'RED';
  name: string;
  waterTemp: number;
  waterTempTime: string;
  // ... more fields
}

Error Handling

If something goes wrong (login failure, network issue, response mismatch, etc.), the methods throw an Error. Always wrap calls in try/catch:

try {
  const dashboard = await api.getDashboard();
} catch (err) {
  console.error("WaterGuru API error:", err);
}

Demo

A simple demonstration is included to show how to use the waterguru-api-ts library.

1. Install dependencies

   npm install

2. Build the library

   npm run build

3. Build the demo

   npm run build:demo

   Note: The following error will be displayed and can safely be ignored

   demo/server.ts:4:30 - error TS2792: Cannot find module '../../dist/index.js'. Did you mean to set the 'moduleResolution' option to 'nodenext', or to add aliases to the 'paths' option?

   4 import { WaterGuruAPI } from "../../dist/index.js";

4. Run the demo server

   npm run demo

   The server will start on http://localhost:3000

5. Open the demo in a browser

   Open http://localhost:3000 and enter your WaterGuru username and password. The dashboard data will be fetched and sample data displayed on the page.

Changelog

[1.2.0] - 2025-10-10

Changed

• Updated types.ts

[1.1.1] - 2025-10-08

Fixed

• Added demo script to package.json

Changed

• Updated README.md

[1.1.0] - 2025-09-21

Added

• Added demo page and server
• Updated build system to handle both distribution and demo

[1.0.0] - 2025-09-20

Added

• Initial release of waterguru-api-ts.

Caveats & Limitations

• This is an unofficial library.
• WaterGuru does not publish a stable public API; endpoints may change without warning.
• Avoid frequent polling — excessive requests may result in blocks or rate limiting.

License

MIT © Steve Maze

Credits

• This library is inspired by and ported from bdwilson/waterguru-api.
  Huge thanks to bdwilson and contributors for their work.