Read archived charge sessions from the Zaptec API

[martijnversluis]

De gem kan nu voltooide (archived) laadsessies ophalen via GET /api/sessions/archived. Handig voor historische rapportages of het eenmalig inlezen van bestaande data die anders alleen via live polling in beeld komt.

Wat er verandert

Nieuwe publieke method op de client:

client.archived_sessions(
  from: 1.year.ago,
  to: Time.current,
  installation_id: "…",        # of charger_id: "…", precies één van beide
  page_size: 200,              # optioneel, default is de Zaptec-default (50), max 200
  cursor: nil,                 # optioneel, opaque cursor uit de vorige page
)
# => Zaptec::ArchivedSessionsPage
#      #sessions   => Array<Zaptec::ArchivedSession>
#      #cursor     => String of nil
#      #has_more?  => Boolean

De endpoint is cursor-gepagineerd. Bewust géén auto-pagination in de gem: callers die grote hoeveelheden sessies importeren willen kunnen checkpointen op cursor-niveau (bv. na elke batch commiten aan een datastore) zonder dat de gem eerst alles in-memory verzamelt. Voorbeeld:

cursor = nil
loop do
  page = client.archived_sessions(from:, to:, installation_id:, cursor:)
  page.sessions.each { |session| import(session) }
  break unless page.has_more?
  cursor = page.cursor
end

Response-parsing

Zaptec::ArchivedSession exposeert:

• Timings: start_date_time, end_date_time, recognized_date_time
• Identifiers: id, external_id, charger_id, device_id, device_name, token_name, charger_firmware_version
• Vlagjes: offline?, reliable_clock?, stopped_by_rfid?, signed?, voided?, aborted?, ocpp_native?, externally_abandoned?
• Correcties: replaced_by_session_id voor voided-en-vervangen sessies
• authorized_user (id, email, full_name) als de sessie door een gebruiker was geauthenticeerd
• session_signature (OCMF) en session_signature_eichrecht (raw OCMF-payloads)

Energie — twee representaties

De API biedt energie op twee manieren en de gem exposeert beide expliciet:

1. energy_kwh (Float) — totale energie geleverd in de sessie
2. energy_details (Array<ArchivedSessionEnergyPoint>) — per-interval delta in kWh per uurbucket, met eindtijd van het interval. De Zaptec swagger noemt dit "cumulative" maar in de praktijk zijn het intervalwaardes (som van deze deltas = energy_kwh)
3. meter_readings (Array<Zaptec::MeterReading>) — cumulatieve meterstand (kWh) uit de OCMF-signed session_signature. Monotoon oplopend, geverifieerd door de meter. Gebruik deze wanneer je de echte meterstand op een tijdstip nodig hebt (bv. voor sub-billing of transparantie-eisen).

Zaptec::MeterReading heeft nu een parse_all class-method die alle OCMF-readings uit een payload teruggeeft (voorheen alleen parse = de eerste).

Validatie

Precies één van installation_id of charger_id is verplicht (per Zaptec-spec). Anders Zaptec::Errors::ParameterMissing. from en to zijn keyword-required.

Ontbrekende optionele velden worden veilig nil/[]/false (getest).

[martijnversluis]

@claude review please