TSME-Metering

A useful lib and CLI to collect water meter data from your TSME group provider account.

⚠️ This code is still experimental: you may encounter issues

Compatibility

Providers

• Suez (https://www.toutsurmoneau.fr/)
• ...in progress

See Known limitations - Providers for more informations

Usage

Installation

  pnpm install tsme-metering
  # or npm, yarn, whatever :D

If you don't need the lib and just want to use the CLI, you can use npx to execute it directly:

  npx tsme-metering extract-all

See CLI Usage for more informations

Configuration (env vars)

• TSME_EMAIL: email address used to connect your water provider account
• TSME_PASSWORD: password used to connect your water provider account

Env vars are used in both lib code and CLI usage.

This library is using dotenv so you can store env vars into a .env file.

Library

Each provider has its own client. You need to instantiate the one corresponding to your needs. To do so, you can either use the helper map providers or directly instantiate your provider (SuezClient for example):

  import { providers } from 'tsme-metering';
  const provider = providers.get("suez");
  const client = new provider(); // default email and password from env can be overloaded in the constructor

  import { SuezClient } from 'tsme-metering';
  const client = new SuezClient(); // default email and password from env can be overloaded in the constructor

Now that you have your client, you are free to call on of its functions:

• getMetersIds()

  Get all compatible water meters ids of your account (useful for multiple water meters)

  ← Returns: number[]

• getMetering(meterId, from?, to?)

  Get data from a specific water meter with optionnal timespan

  → Parameters: meterId (number) - from (Date) - to (Date)

  ← Returns:

    Array<{
      date: Date; // "Europe/Paris" TZ
      index: number | null; // in m³
      volume: number; // in m³
    }>

• isLoggedIn()

  Check if the current client is currently logged in

  ← Returns: boolean

Here is a full usage example:

  import { SuezClient } from 'tsme-metering';
  const client = new SuezClient();

  // Get all meters ids
  const metersIds = await client.getMetersIds();
  if (metersIds.length < 1) {
    throw new Error('There is no compatible water meter');
  }

  const metering = await client.getMetering(meterId, new Date('2025-06-01'));
  // ...

CLI

The CLI has two commands:

• tsme-metering extract-all --provider <suez> --start <2025-07-05> --end <2025-07-07> --format <csv|json>

  Extract all water meters data from the 2025-07-05 to the 2025-07-06 (2 days)

• tsme-metering extract <meter-id> --provider <suez> --start <2025-07-01> --format <csv|json>

  Extract one specific water meter data from the 2025-07-01 to the last available date (yesterday)

By default, both CLI commands are extracting the current month data if no dates are specified. Both commands outputs can be redirected to a file:

  tsme-metering extract-all --start 2025-07-05 --format csv > my_water.csv

Known limitations

Session expiration

Using the library, session may expire after a few minutes of inactivity. That is a standard management. The library is not handling session expiration and this implementation is not planned for now. Feel free to request this feature in the issue section.

Providers

That library is only limited to TSME (Tout Sur Mon Eau) providers. I started with the main provider Suez but I plan to add all its branches like Eau Olivet or Dolea in the future. Again, feel free to ask for your specific provider.

Verbosity

For now the verbosity is not adjustable, this is planned in a next release.