AgrarmonitorConnector/README.md

Agrarmonitor Connector

TypeScript MVP connector for Agrarmonitor with shared cookie persistence, optional AES-GCM cookie encryption, automatic login, retry after expired sessions, device registration checks, and customer detail extraction.

Login uses Agrarmonitor's redirect flow only: the connector loads /, extracts the nonce, and posts credentials to /redirect.php?id=benutzerverwaltung&action=login.

Installation

npm install

Build

npm run build

Example

import {
  AesGcmCookieEncryptor,
  FileCookieStore,
  createAgrarmonitorClient,
} from 'agrarmonitor-connector';

const agrarmonitor = await createAgrarmonitorClient({
  baseUrl: 'https://admin7.agrarmonitor.de',
  apiToken: process.env.AGRARMONITOR_API_TOKEN,
  username: process.env.AGRARMONITOR_USERNAME ?? '',
  password: process.env.AGRARMONITOR_PASSWORD ?? '',
  cookieStore: new FileCookieStore(
    process.env.AGRARMONITOR_COOKIE_PATH ?? './data/agrarmonitor-cookies.json',
    {
      encryptor: process.env.AGRARMONITOR_ENCRYPTION_KEY
        ? new AesGcmCookieEncryptor(process.env.AGRARMONITOR_ENCRYPTION_KEY)
        : undefined,
      logger: console,
    }
  ),
  logger: console,
});

const freischaltung = await agrarmonitor.checkFreigeschaltet();
console.log(freischaltung.freigeschaltet);

const registrierung = await agrarmonitor.checkRegistriert();
console.log(registrierung.registriert);

const response = await agrarmonitor.http.get('/kunden/detail/123');
console.log(response.status);

Login-Logging

Der Login-Flow protokolliert jeden Schritt auf debug-Level, sofern der uebergebene Logger eine debug-Methode hat. Ohne debug-Methode bleiben diese Details still - ein reiner info-Logger sieht davon nichts.

Protokolliert werden der Aufruf der Loginseite, die gelesene Nonce, der POST /login/api/login.php, die Session-Pruefung und jeder Request, der wegen abgelaufener Session wiederholt wird. Zu jedem dieser Requests steht ein Cookie-Snapshot vor dem Absenden und einer danach im Log, dazu ein Delta mit neuen, geaenderten und entfernten Cookies:

[debug] Login-POST: POST /login/api/login.php
        {"phase":"request","method":"POST","url":"/login/api/login.php","cookies":[],
         "body":{"username":"demo","passwort":"***","nonce":"9f3a1c7b2e...","ssoAction":"","ssoReturn":""}}
[debug] Login-POST: POST /login/api/login.php -> 200
        {"phase":"response","status":200,"istLoginSeite":false,
         "setCookie":["PHPSESSID=f81d…(len=32); Path=/; HttpOnly"],
         "cookies":[{"name":"PHPSESSID","value":"f81d…(len=32)","domain":"127.0.0.1","path":"/",
                     "expires":"Session","httpOnly":true,"secure":false}],
         "cookieChanges":{"added":["PHPSESSID"],"changed":[],"removed":[]}}

Passwort und Cookie-Werte stehen nie im Klartext im Log: das Passwort wird durch *** ersetzt, Cookie-Werte und der rohe Set-Cookie-Header werden auf die ersten vier Zeichen plus Laenge gekuerzt. Damit bleibt erkennbar, ob sich eine Session-ID geaendert hat, ohne dass das Log selbst die Session preisgibt.

Das phase-Feld ordnet jeden Eintrag zu: login-start, request, response, nonce, session-check, session-expired, retry, error, login-done.

Cookie Persistence

FileCookieStore keeps one shared CookieJar per file path inside the Node process. Multiple connector instances that use the same cookie file therefore reuse the same session and every successful request saves the latest cookies back to disk.

The store can read both the connector format and the older Telefonbuch cookie-array format.

Useful Methods

• checkFreigeschaltet() checks whether Agrarmonitor redirects to /freischaltung/.
• checkRegistriert() checks whether the page still contains Neues Gerät registrieren.
• registerDevice({ agrarmonitorId, pcName }) loads /freischaltung/, extracts the nonce, and posts the registration request.
• fetchCustomers() loads customers from https://api.agrarmonitor.de/v1/kunden.
• getKunden2() loads all customer pages and returns normalized customer/supplier fields.
• getCustomerById(id) loads one customer from the token-based Agrarmonitor API.
• eingangsrechnungenLivesearch(suchstring) searches invoice files and enriches matching Eingangsrechnungen with edit/detail metadata.
• eingangsrechnungVorhanden(suchstring) checks whether invoice file search has rows.
• eingangsrechnungImDateieingangVorhanden(suchstring) checks whether file inbox search has rows.
• getRechnungsdaten(rechnungId) reads editable invoice fields.
• setRechnungsdaten(rechnungId, daten) updates editable invoice fields.
• setLieferscheinNummer(rechnungId, nummer) updates only the delivery note number.
• setEingangsdatum(rechnungId, datum) updates the received date.
• getMaschinenKategorien() reads /maschinen/kategorien and returns ID, name, tractor flag, and mobile visibility.
• getMaschinen(gruppenId, suchstring?) reads /module/maschinen/livesearch.php and returns ID, number, name, license plate, and active flag.
• getAlleMaschinen() reads all machine categories (maschinengruppe=0), active and inactive machines, all livesearch pages, and returns each machine once with ID, number, name, license plate, active flag, its first category (gruppenId, gruppe) and all categories (gruppenIds); a machine can be listed in several categories. getMaschinen() already sends maschinen_aktiv=1, which in Agrarmonitor means active and inactive.
• getFirmen() reads /einstellungen and returns company ID and description.
• getArtikelEinheiten() reads /artikel/einheiten and returns unit ID, description, and short label.
• getArtikelKategorien() reads /artikel/kategorien and returns product group ID and name.
• getArtikel(artikelGruppe, suchstring?) reads /module/artikel/livesearch.php and returns article ID, number, and description.
• getMitarbeiter(suchstring?, mitarbeitergruppe?) reads /module/mitarbeiter/livesearch.php and returns employee ID, number, last name, first name, and active flag.
• getTaetigkeiten() reads /module/arbeitszeit/taetigkeiten-livesearch.php (active and inactive) and returns activity ID, UUID, number, name, active flag, area (bereichId, bereich) and the flags maschineZuordnen, abwesenheit, notizErzwingen.
• Agrarmonitor has no cost center master data (Kostenstelle is only a free-text field on machines, employees and articles), so there is no getKostenstellen(). See docs/zeitbuchung-analyse.md.
• beginneArbeitstag(mitarbeiterId, start, { datum? }) starts the workday: creates a running shift (attendance without end) for any employee and returns { ref } (schicht:<mitarbeiterId>:<YYYY-MM-DD>:<id>). If a running shift already exists that day, its ref is returned instead. The Agrarmonitor menu link "Arbeitstag beginnen" (bueroAnundAbmelden.php) only works for the logged-in user, so the connector uses module/auftraege/api/saveSchicht.php.
• beendeArbeitstag(ref, ende) ends the shift, updateArbeitstag(ref, { start, ende }) corrects it (ende: null keeps it running), deleteArbeitstag(ref) deletes the shift including all activities and breaks.
• createZeitbuchung(daten) books an activity block (taetigkeitId, optional maschinenId, notiz, kostenstelle) or a break (art: 'pause') for mitarbeiterId from start to ende (minute precision, Europe/Berlin) and returns { ref }. Bookings go into the shift of that day (started with beginneArbeitstag), which is extended if needed; a running shift stays open. Without any shift, an activity creates one via nachtragen.php, a break is rejected. Agrarmonitor has no cost center field, so kostenstelle is appended to the note as Kostenstelle: …. Pass datum (YYYY-MM-DD) for blocks after midnight that belong to the previous workday.
• updateZeitbuchung(ref, daten) changes times, activity, machine and note of a booking (the old note is replaced); changing the type (activity/break), employee or workday is rejected.
• deleteZeitbuchung(ref) deletes a booking; deleting the last activity of a shift also deletes the shift in Agrarmonitor.
• Refs look like verteilung:<mitarbeiterId>:<YYYY-MM-DD>:<id> or pause:…. Rejections by Agrarmonitor (HTTP 4xx such as 422 with the reason in the body) and invalid input throw ZeitbuchungError (grund, status); network and 5xx errors are thrown unchanged so callers can retry.
• saveSession() explicitly persists the current cookie jar.