elli-charger-client

elli-charger-client ist ein ESM-Modul für den Elli Charger Pro Gen 1. Es kümmert sich um den Elli-Login, lädt Stationen und die paginierte Ladehistorie, löst Monats- oder Datumsbereiche auf, filtert nach RFID-Karten und kann den von Elli erzeugten PDF-Zeitbericht abrufen.

Installation

npm install elli-charger-client

Interaktive Anmeldung

Nach der Installation stellt das Paket das Binary elli-client bereit. Damit kann die wegen CAPTCHA oder MFA notwendige Browser-Anmeldung ohne das separate Export-CLI durchgeführt werden:

npx elli-client login

Nach CAPTCHA und Anmeldung die Browser-Entwicklerkonsole öffnen. Der fehlgeschlagene App-Redirect erscheint dort als Fehler; daraus die vollständige com.elli.ios.emsp://...-URL kopieren und in das Terminal einfügen.

Standardmäßig entsteht .elli-token.json im aktuellen Verzeichnis. Ein anderer Pfad kann per Option oder Umgebung gewählt werden:

npx elli-client login --token-file /sicherer/pfad/elli-token.json
# oder: ELLI_TOKEN_FILE=/sicherer/pfad/elli-token.json npx elli-client login

Anwendungen können die Datei anschließend mit loadElliTokenFile() laden oder ELLI_TOKEN_FILE zusammen mit createElliExporterFromEnvironment() verwenden. Bei der Token-Erneuerung wird ein rotierter Refresh-Token sicher zurückgeschrieben.

Voraussetzung sind Node.js 22.18 oder neuer und ein ESM-Projekt.

High-Level-API

Am einfachsten ist die Factory mit Werten aus process.env:

import {
  createElliExporterFromEnvironment,
  serializeOutput,
} from "elli-charger-client";

const exporter = createElliExporterFromEnvironment();

const result = await exporter.getChargingHistory({
  month: "2026-03",
  rfid: "me",
});

const csv = serializeOutput(result.records, result.range, "csv");
console.log(`${result.records.length} Ladevorgänge`);
// `csv` beispielsweise sicher in eine Datei oder einen Response schreiben.

Statt month kann auch ein inklusiver freier Zeitraum mit konkreter Station angegeben werden:

const result = await exporter.getChargingHistory({
  from: "2026-03-15",
  to: "2026-04-10",
  timeZone: "Europe/Berlin",
  stationId: "STATIONS_ID",
  rfid: "ELLI-XXXXXXXX-XXXX-X",
});

const document = await exporter.createExport({ month: "April", year: 2026 });
const stations = await exporter.listStations();

Ohne Zeitraum wird der aktuelle Kalendermonat verwendet. month kann als YYYY-MM, Zahl oder deutscher oder englischer Monatsname angegeben werden. month und from/to schließen sich gegenseitig aus. Bei einem freien Zeitraum müssen beide Datumsgrenzen im Format YYYY-MM-DD gesetzt sein.

Beim Historienexport zählt der Ladestart für die Zuordnung zum Zeitraum. Die Grenzen werden in der angegebenen IANA-Zeitzone inklusive Sommerzeit berechnet. Standard ist Europe/Berlin.

PDF-Zeitbericht

import { writeFile } from "node:fs/promises";
import { createElliExporterFromEnvironment } from "elli-charger-client";

const exporter = createElliExporterFromEnvironment();
const report = await exporter.getChargingReportPdf({
  month: "2026-03",
  stationId: "STATIONS_ID",
  rfid: "me",
});

await writeFile("elli-zeitbericht-2026-03.pdf", report.pdf, { mode: 0o600 });

Der PDF-Endpunkt akzeptiert höchstens 31 Kalendertage. Wenn im Konto mehrere Wallboxen vorhanden sind, muss genau eine stationId gewählt werden. Bei einem RFID-Filter wird die Seriennummer zuerst auf Ellis interne Karten-ID aufgelöst. Der Wert me verwendet ELLI_RFID_CARD_SERIAL_NUMBER beziehungsweise meRfidSerial aus den Defaults.

Elli erzeugt das PDF serverseitig und bezieht den Zeitraum auf created_at. Der JSON- oder CSV-Historienexport ordnet Datensätze dagegen lokal über start_date_time zu. Direkt an einer Zeitgrenze können PDF und Historienexport deshalb voneinander abweichen.

Explizite Konfiguration

Wer nicht aus process.env lesen möchte, kann alle Werte direkt übergeben:

import { createElliExporter } from "elli-charger-client";

const exporter = createElliExporter({
  authentication: {
    accessToken: process.env.MY_ELLI_TOKEN!,
  },
  defaults: {
    timeZone: "Europe/Berlin",
    stationId: "STATIONS_ID",
    meRfidSerial: "ELLI-XXXXXXXX-XXXX-X",
  },
});

Statt accessToken kann auch authentication: { email, password } verwendet werden. Beide Authentifizierungsarten dürfen nicht gemischt werden. Über client lassen sich bei Bedarf authBaseUrl, apiBaseUrl, clientId, redirectUri, audience, scope, timeoutMs, maxPdfBytes oder eine eigene fetchImplementation setzen. PDF-Antworten sind standardmäßig auf 20 MiB begrenzt.

Für Low-Level-Zugriff gibt es außerdem ElliClient mit login, createInteractiveLogin, refreshAccessToken, getStations, getAllChargingRecords, getRfidCards und getChargingRecordsPdf. createInteractiveLogin() liefert eine PKCE-Autorisierungs-URL und eine complete(callbackUrl)-Funktion. So können CAPTCHA oder MFA im Browser abgeschlossen werden, ohne sie zu automatisieren. Für Anwendungslogik ist ElliExporter in der Regel passender, weil Zeitraum-, Stations- und RFID-Regeln dort zentral umgesetzt sind.

Umgebungsvariablen

createElliExporterFromEnvironment() versteht:

| Variable | Bedeutung | | --- | --- | | ELLI_EMAIL, ELLI_PASSWORD | Elli-Konto; gemeinsam erforderlich, wenn kein Token verwendet wird | | ELLI_TOKEN_FILE | Token-Datei aus dem interaktiven CLI-Login; Standard .elli-token.json, falls vorhanden | | ELLI_ACCESS_TOKEN | Kurzlebige Alternative zu Token-Datei oder E-Mail/Passwort | | ELLI_TIMEZONE | Standard-IANA-Zeitzone, sonst Europe/Berlin | | ELLI_STATION_ID | Optionale Standard-Wallbox | | ELLI_RFID_CARD_SERIAL_NUMBER | Seriennummer für den Alias me | | ELLI_AUTH_BASE_URL, ELLI_API_BASE_URL | Optionale Endpoint-Overrides | | ELLI_CLIENT_ID, ELLI_REDIRECT_URI, ELLI_AUDIENCE, ELLI_SCOPE | Optionale OAuth-Overrides |

Endpoint- und OAuth-Werte sollten nur geändert werden, wenn Elli die inoffizielle Mobile-Schnittstelle verändert.

Fehlerbehandlung

Exportiert werden unter anderem diese Fehlerklassen:

• ElliConfigurationError für fehlende oder widersprüchliche Konfiguration
• ElliExporterInputError für ungültige Zeiträume oder PDF-Anforderungen
• ElliStationNotFoundError und ElliRfidCardNotFoundError
• ElliApiError für Login- und Upstream-Fehler; der optionale HTTP-Status steht in status

Sicherheit und inoffizielle Schnittstelle

Zugangsdaten, Token-Dateien, RFID-Seriennummern sowie Lade- und PDF-Daten sind vertraulich und sollten nicht in Quelltext, Logs oder Repositories landen. Das Paket sendet Elli-Zugangsdaten ausschließlich an den konfigurierten HTTPS-Login-Endpunkt. CAPTCHA oder MFA werden über createInteractiveLogin() im Browser bedient und nicht automatisiert.

Die genutzten Mobile-App-Endpunkte sind nicht öffentlich dokumentiert oder offiziell für dieses Paket freigegeben. Elli kann Login, URLs und Antwortformate jederzeit ändern. Gelesen werden nur die im angemeldeten Konto vorhandenen Cloud-Daten; eine lokale Historie direkt aus der Wallbox wird nicht rekonstruiert.

Die technische Reverse-Engineering-Referenz samt Lizenztext steht in THIRD_PARTY_NOTICES.md.