fluvius-energy-api 0.1.0__py3-none-any.whl

fluvius_energy_api/models/__init__.py

@@ -0,0 +1,123 @@
+"""Models for the Fluvius Energy API."""
+
+from .base import (
+    ErrorResponse,
+    ErrorValidationResponse,
+    FluviusBaseModel,
+    ResponseMetadata,
+)
+from .energy import (
+    AuxiliarySubHeadpoint,
+    GetEnergyResponse,
+    GetEnergyResponseApiDataResponse,
+    Headpoint,
+    HeadpointUnion,
+    MeasurementDirection,
+    MeasurementTimeSlice,
+    MeasurementValue,
+    MeasurementValueSet,
+    MeteringOnHeadpoint,
+    MeteringOnHeadpointAndMeter,
+    MeteringOnMeter,
+    OfftakeSubHeadpoint,
+    PhysicalMeter,
+    ProductionSubHeadpoint,
+    SubHeadpoint,
+    SubHeadpointUnion,
+)
+from .enums import (
+    CreateClientSessionStatus,
+    DataServiceType,
+    EnergyType,
+    EstimatedVolumeType,
+    Flow,
+    GasConversionFactor,
+    LocalProductionInstallationType,
+    MandateRenewalStatus,
+    MandateStatus,
+    MeasurementValidationState,
+    MeterType,
+    PeriodType,
+    Register,
+    Unit,
+)
+from .installation import (
+    EstimatedVolume,
+    GetInstallationResponse,
+    GetInstallationResponseApiDataResponse,
+    Installation,
+    LocalProductionInstallation,
+)
+from .mandate import (
+    CreateMandateRequest,
+    CreateMandateResponse,
+    CreateMandateResponseApiDataResponse,
+    GetMandatesResponse,
+    GetMandatesResponseApiDataResponse,
+    Mandate,
+)
+from .session import (
+    ClientSessionDataService,
+    CreateClientSessionRequest,
+    CreateClientSessionResponse,
+    CreateClientSessionResponseApiDataResponse,
+)
+
+__all__ = [
+    # Base
+    "ErrorResponse",
+    "ErrorValidationResponse",
+    "FluviusBaseModel",
+    "ResponseMetadata",
+    # Energy
+    "AuxiliarySubHeadpoint",
+    "GetEnergyResponse",
+    "GetEnergyResponseApiDataResponse",
+    "Headpoint",
+    "HeadpointUnion",
+    "MeasurementDirection",
+    "MeasurementTimeSlice",
+    "MeasurementValue",
+    "MeasurementValueSet",
+    "MeteringOnHeadpoint",
+    "MeteringOnHeadpointAndMeter",
+    "MeteringOnMeter",
+    "OfftakeSubHeadpoint",
+    "PhysicalMeter",
+    "ProductionSubHeadpoint",
+    "SubHeadpoint",
+    "SubHeadpointUnion",
+    # Enums
+    "CreateClientSessionStatus",
+    "DataServiceType",
+    "EnergyType",
+    "EstimatedVolumeType",
+    "Flow",
+    "GasConversionFactor",
+    "LocalProductionInstallationType",
+    "MandateRenewalStatus",
+    "MandateStatus",
+    "MeasurementValidationState",
+    "MeterType",
+    "PeriodType",
+    "Register",
+    "Unit",
+    # Installation
+    "EstimatedVolume",
+    "GetInstallationResponse",
+    "GetInstallationResponseApiDataResponse",
+    "Installation",
+    "LocalProductionInstallation",
+    # Mandate
+    "CreateMandateRequest",
+    "CreateMandateResponse",
+    "CreateMandateResponseApiDataResponse",
+    "GetMandatesResponse",
+    "GetMandatesResponseApiDataResponse",
+    "Mandate",
+    # Session
+    "ClientSessionDataService",
+    "CreateClientSessionRequest",
+    "CreateClientSessionResponse",
+    "CreateClientSessionResponseApiDataResponse",
+]

fluvius_energy_api/models/base.py

@@ -0,0 +1,36 @@
+"""Base model classes for the Fluvius Energy API."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FluviusBaseModel(BaseModel):
+    """Base model with camelCase alias configuration."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        use_enum_values=True,
+    )
+
+
+class ResponseMetadata(FluviusBaseModel):
+    """Represents metadata for a response."""
+
+    fetch_time: datetime | None = Field(default=None, alias="fetchTime")
+
+
+class ErrorResponse(FluviusBaseModel):
+    """Represents an error response from the API."""
+
+    type: str | None = Field(default=None, alias="Type")
+    code: str | None = Field(default=None, alias="Code")
+    message: str | None = Field(default=None, alias="Message")
+
+
+class ErrorValidationResponse(ErrorResponse):
+    """Represents a response when validation has failed during the request."""
+
+    validation_error_messages: list[str] | None = Field(
+        default=None, alias="ValidationErrorMessages"
+    )

fluvius_energy_api/models/energy.py

@@ -0,0 +1,201 @@
+"""Energy measurement models for the Fluvius Energy API."""
+
+from datetime import datetime
+from typing import Annotated, Literal
+from pydantic import Field
+
+from .base import FluviusBaseModel, ResponseMetadata
+from .enums import (
+    EnergyType,
+    GasConversionFactor,
+    LocalProductionInstallationType,
+    MeasurementValidationState,
+    Unit,
+)
+
+
+class MeasurementValue(FluviusBaseModel):
+    """Represents a single measurement value."""
+
+    value: float | None = None
+    unit: Unit | None = None
+    validation_state: MeasurementValidationState | None = Field(
+        default=None, alias="validationState"
+    )
+    gas_conversion_factor: GasConversionFactor | None = Field(
+        default=None, alias="gasConversionFactor"
+    )
+
+
+class MeasurementValueSet(FluviusBaseModel):
+    """Represents a measurement value set for different registers."""
+
+    total: MeasurementValue | None = None
+    day: MeasurementValue | None = None
+    night: MeasurementValue | None = None
+    reactive: MeasurementValue | None = None
+    inductive: MeasurementValue | None = None
+    capacitive: MeasurementValue | None = None
+
+
+class MeasurementDirection(FluviusBaseModel):
+    """Represents a measurement set for different energy directions."""
+
+    offtake: MeasurementValueSet | None = None
+    injection: MeasurementValueSet | None = None
+    production: MeasurementValueSet | None = None
+    auxiliary: MeasurementValueSet | None = None
+
+
+class MeasurementTimeSlice(FluviusBaseModel):
+    """Represents a measurement set within a given period (time slice)."""
+
+    start: datetime | None = None
+    end: datetime | None = None
+    measurements: list[MeasurementDirection] | None = None
+
+
+class PhysicalMeter(FluviusBaseModel):
+    """Represents a physical meter."""
+
+    seq_number: str | None = Field(default=None, alias="seqNumber")
+    meter_id: str | None = Field(default=None, alias="meterID")
+    daily_energy: list[MeasurementTimeSlice] | None = Field(
+        default=None, alias="dailyEnergy"
+    )
+    hourly_energy: list[MeasurementTimeSlice] | None = Field(
+        default=None, alias="hourlyEnergy"
+    )
+    quarter_hourly_energy: list[MeasurementTimeSlice] | None = Field(
+        default=None, alias="quarterHourlyEnergy"
+    )
+
+
+class SubHeadpoint(FluviusBaseModel):
+    """Base response for different kinds of submetering installations."""
+
+    type_discriminator: str = Field(alias="$type")
+    ean: str | None = None
+    seq_number: str | None = Field(default=None, alias="seqNumber")
+    vreg_id: str | None = Field(default=None, alias="vregId")
+    type: LocalProductionInstallationType | None = None
+    daily_energy: list[MeasurementTimeSlice] | None = Field(
+        default=None, alias="dailyEnergy"
+    )
+    hourly_energy: list[MeasurementTimeSlice] | None = Field(
+        default=None, alias="hourlyEnergy"
+    )
+    quarter_hourly_energy: list[MeasurementTimeSlice] | None = Field(
+        default=None, alias="quarterHourlyEnergy"
+    )
+
+
+class AuxiliarySubHeadpoint(SubHeadpoint):
+    """Represents a submetering installation for auxiliary energy."""
+
+    type_discriminator: Literal["submetering-auxiliary"] = Field(
+        default="submetering-auxiliary", alias="$type"
+    )
+
+
+class OfftakeSubHeadpoint(SubHeadpoint):
+    """Represents a submetering installation for offtake energy."""
+
+    type_discriminator: Literal["submetering-offtake"] = Field(
+        default="submetering-offtake", alias="$type"
+    )
+
+
+class ProductionSubHeadpoint(SubHeadpoint):
+    """Represents a submetering installation for produced energy."""
+
+    type_discriminator: Literal["submetering-production"] = Field(
+        default="submetering-production", alias="$type"
+    )
+
+
+SubHeadpointUnion = Annotated[
+    AuxiliarySubHeadpoint | OfftakeSubHeadpoint | ProductionSubHeadpoint,
+    Field(discriminator="type_discriminator"),
+]
+
+
+class Headpoint(FluviusBaseModel):
+    """Base response for different kinds of installations."""
+
+    type_discriminator: str = Field(alias="$type")
+    ean: str | None = None
+    energy_type: EnergyType | None = Field(default=None, alias="energyType")
+
+
+class MeteringOnHeadpoint(Headpoint):
+    """Response containing an installation where metering is done on headpoint level (AMR)."""
+
+    type_discriminator: Literal["metering-on-headpoint"] = Field(
+        default="metering-on-headpoint", alias="$type"
+    )
+    daily_energy: list[MeasurementTimeSlice] | None = Field(
+        default=None, alias="dailyEnergy"
+    )
+    hourly_energy: list[MeasurementTimeSlice] | None = Field(
+        default=None, alias="hourlyEnergy"
+    )
+    quarter_hourly_energy: list[MeasurementTimeSlice] | None = Field(
+        default=None, alias="quarterHourlyEnergy"
+    )
+    sub_headpoints: list[SubHeadpointUnion] | None = Field(
+        default=None, alias="subHeadpoints"
+    )
+
+
+class MeteringOnMeter(Headpoint):
+    """Response containing an installation where metering is done on meter level (DM)."""
+
+    type_discriminator: Literal["metering-on-meter"] = Field(
+        default="metering-on-meter", alias="$type"
+    )
+    physical_meters: list[PhysicalMeter] | None = Field(
+        default=None, alias="physicalMeters"
+    )
+
+
+class MeteringOnHeadpointAndMeter(Headpoint):
+    """Response containing an installation where metering is done on both headpoint and meter level."""
+
+    type_discriminator: Literal["metering-on-headpoint-and-meter"] = Field(
+        default="metering-on-headpoint-and-meter", alias="$type"
+    )
+    physical_meters: list[PhysicalMeter] | None = Field(
+        default=None, alias="physicalMeters"
+    )
+    daily_energy: list[MeasurementTimeSlice] | None = Field(
+        default=None, alias="dailyEnergy"
+    )
+    hourly_energy: list[MeasurementTimeSlice] | None = Field(
+        default=None, alias="hourlyEnergy"
+    )
+    quarter_hourly_energy: list[MeasurementTimeSlice] | None = Field(
+        default=None, alias="quarterHourlyEnergy"
+    )
+    sub_headpoints: list[SubHeadpointUnion] | None = Field(
+        default=None, alias="subHeadpoints"
+    )
+
+
+HeadpointUnion = Annotated[
+    MeteringOnHeadpoint | MeteringOnMeter | MeteringOnHeadpointAndMeter,
+    Field(discriminator="type_discriminator"),
+]
+
+
+class GetEnergyResponse(FluviusBaseModel):
+    """Represents a response containing energy for a single installation."""
+
+    headpoint: HeadpointUnion | None = None
+
+
+class GetEnergyResponseApiDataResponse(FluviusBaseModel):
+    """Represents a successful response from the server containing data."""
+
+    meta: ResponseMetadata | None = Field(default=None, alias="_meta")
+    data: GetEnergyResponse | None = None

fluvius_energy_api/models/enums.py

@@ -0,0 +1,137 @@
+"""Enum definitions for the Fluvius Energy API."""
+
+from enum import Enum
+
+
+class CreateClientSessionStatus(str, Enum):
+    """Defines all client session creation statuses."""
+
+    SUCCESS = "success"
+    FAILED = "failed"
+
+
+class DataServiceType(str, Enum):
+    """Defines the available data service types."""
+
+    VH_ONBEPAALD = "VH_onbepaald"
+    VH_KWARTIER_UUR = "VH_kwartier_uur"
+    VH_DAG = "VH_dag"
+    IG = "IG"
+
+
+class EnergyType(str, Enum):
+    """Defines all supported disciplines (energy types)."""
+
+    ELECTRICITY = "E"
+    GAS = "G"
+
+
+class EstimatedVolumeType(str, Enum):
+    """Defines the supported types of estimated volume."""
+
+    EAV = "EAV"
+
+
+class Flow(str, Enum):
+    """Defines all possible flows."""
+
+    B2C = "B2C"
+    B2B = "B2B"
+
+
+class GasConversionFactor(str, Enum):
+    """Defines all possible values for gas conversion factor."""
+
+    PREDICTIVE = "P"
+    DEFINITIVE = "D"
+    CONSTANT = "C"
+
+
+class LocalProductionInstallationType(str, Enum):
+    """Defines the types of local production installation."""
+
+    UNKNOWN = "?"
+    NDGR = "NDGR"
+    NDGR2 = "NDGR2"
+    PV = "PV"
+    WKKB = "WKKB"
+    WKKD = "WKKD"
+    WKKA = "WKKA"
+    WTR = "WTR"
+    WND = "WND"
+    TBJT = "TBJT"
+    ORC = "ORC"
+    BC = "BC"
+    BIOM = "BIOM"
+    DSL = "DSL"
+    FOSM = "FOSM"
+    PPPV = "PPPV"
+    PPBAT = "PPBAT"
+    BAT = "BAT"
+
+
+class MandateRenewalStatus(str, Enum):
+    """Defines all mandate renewal statuses."""
+
+    TO_BE_RENEWED = "ToBeRenewed"
+    RENEWAL_REQUESTED = "RenewalRequested"
+    EXPIRED = "Expired"
+
+
+class MandateStatus(str, Enum):
+    """Defines all mandate statuses."""
+
+    REQUESTED = "Requested"
+    APPROVED = "Approved"
+    REJECTED = "Rejected"
+    FINISHED = "Finished"
+
+
+class MeasurementValidationState(str, Enum):
+    """Defines all possible values for validation states of measurements."""
+
+    READ = "READ"
+    EST = "EST"
+    VAL = "VAL"
+    NVAL = "NVAL"
+
+
+class MeterType(str, Enum):
+    """Defines all possible meter types."""
+
+    KM = "KM"
+    DM = "DM"
+
+
+class PeriodType(str, Enum):
+    """Defines the type of period for which will be queried."""
+
+    READ_TIME = "readTime"
+    INSERT_TIME = "insertTime"
+
+
+class Register(str, Enum):
+    """Represents a register."""
+
+    UNKNOWN = "Unknown"
+    OFFTAKE_TOTAL_HOURS = "OfftakeTotalHours"
+    OFFTAKE_HIGH = "OfftakeHigh"
+    OFFTAKE_LOW = "OfftakeLow"
+    OFFTAKE_EXCLUSIVE_NIGHT = "OfftakeExclusiveNight"
+    COMPENSATED_OFFTAKE_TOTAL_HOURS = "CompensatedOfftakeTotalHours"
+    COMPENSATED_OFFTAKE_HIGH = "CompensatedOfftakeHigh"
+    COMPENSATED_OFFTAKE_LOW = "CompensatedOfftakeLow"
+    INJECTION_TOTAL_HOURS = "InjectionTotalHours"
+    INJECTION_HIGH = "InjectionHigh"
+    INJECTION_LOW = "InjectionLow"
+
+
+class Unit(str, Enum):
+    """Defines all supported units."""
+
+    UNKNOWN = "?"
+    KVA = "kVA"
+    KVARH = "kVArh"
+    KWH = "kWh"
+    KW = "kW"
+    M3 = "m3"

fluvius_energy_api/models/installation.py

@@ -0,0 +1,68 @@
+"""Installation models for the Fluvius Energy API."""
+
+from datetime import datetime
+from pydantic import Field
+
+from .base import FluviusBaseModel, ResponseMetadata
+from .enums import (
+    EnergyType,
+    EstimatedVolumeType,
+    LocalProductionInstallationType,
+    MeterType,
+    Register,
+    Unit,
+)
+
+
+class LocalProductionInstallation(FluviusBaseModel):
+    """Represents a single local production installation."""
+
+    vreg_id: str | None = Field(default=None, alias="vregId")
+    type: LocalProductionInstallationType | None = None
+    converter_power: float | None = Field(default=None, alias="converterPower")
+    converter_power_unit: Unit | None = Field(default=None, alias="converterPowerUnit")
+    inspection_date: datetime | None = Field(default=None, alias="inspectionDate")
+
+
+class EstimatedVolume(FluviusBaseModel):
+    """Represents a response containing an estimated volume."""
+
+    type: EstimatedVolumeType | None = None
+    calculated_register: Register | None = Field(
+        default=None, alias="calculatedRegister"
+    )
+    value: int | None = None
+    unit: Unit | None = None
+    consumption_start_date: datetime | None = Field(
+        default=None, alias="consumptionStartDate"
+    )
+    consumption_end_date: datetime | None = Field(
+        default=None, alias="consumptionEndDate"
+    )
+
+
+class Installation(FluviusBaseModel):
+    """Represents a single installation."""
+
+    energy_type: EnergyType | None = Field(default=None, alias="energyType")
+    meter_type: MeterType | None = Field(default=None, alias="meterType")
+    smr3: bool | None = None
+    local_production_installations: list[LocalProductionInstallation] | None = Field(
+        default=None, alias="localProductionInstallations"
+    )
+    estimated_volumes: list[EstimatedVolume] | None = Field(
+        default=None, alias="estimatedVolumes"
+    )
+
+
+class GetInstallationResponse(FluviusBaseModel):
+    """Represents a response containing installation data."""
+
+    installation: Installation | None = None
+
+
+class GetInstallationResponseApiDataResponse(FluviusBaseModel):
+    """Represents a successful response from the server containing data."""
+
+    meta: ResponseMetadata | None = Field(default=None, alias="_meta")
+    data: GetInstallationResponse | None = None

fluvius_energy_api/models/mandate.py

@@ -0,0 +1,73 @@
+"""Mandate models for the Fluvius Energy API."""
+
+from datetime import datetime
+from pydantic import Field
+
+from .base import FluviusBaseModel, ResponseMetadata
+from .enums import DataServiceType, EnergyType, MandateRenewalStatus, MandateStatus
+
+
+class Mandate(FluviusBaseModel):
+    """Represents a single mandate."""
+
+    reference_number: str | None = Field(default=None, alias="referenceNumber")
+    status: MandateStatus | None = None
+    ean: str | None = None
+    energy_type: EnergyType | None = Field(default=None, alias="energyType")
+    data_period_from: datetime | None = Field(default=None, alias="dataPeriodFrom")
+    data_period_to: datetime | None = Field(default=None, alias="dataPeriodTo")
+    data_service_type: DataServiceType | None = Field(
+        default=None, alias="dataServiceType"
+    )
+    mandate_expiration_date: datetime | None = Field(
+        default=None, alias="mandateExpirationDate"
+    )
+    renewal_status: MandateRenewalStatus | None = Field(
+        default=None, alias="renewalStatus"
+    )
+
+
+class GetMandatesResponse(FluviusBaseModel):
+    """Represents a response containing multiple mandates."""
+
+    mandates: list[Mandate] | None = None
+
+
+class GetMandatesResponseApiDataResponse(FluviusBaseModel):
+    """Represents a successful response from the server containing data."""
+
+    meta: ResponseMetadata | None = Field(default=None, alias="_meta")
+    data: GetMandatesResponse | None = None
+
+
+class CreateMandateRequest(FluviusBaseModel):
+    """Request to create a mock mandate in the sandbox environment.
+
+    This endpoint is only available in the sandbox environment.
+    """
+
+    reference_number: str = Field(..., alias="referenceNumber")
+    ean: str
+    data_service_type: DataServiceType = Field(..., alias="dataServiceType")
+    data_period_from: str | None = Field(default=None, alias="dataPeriodFrom")
+    data_period_to: str | None = Field(default=None, alias="dataPeriodTo")
+    status: MandateStatus | None = None
+    mandate_expiration_date: str | None = Field(
+        default=None, alias="mandateExpirationDate"
+    )
+    renewal_status: MandateRenewalStatus | None = Field(
+        default=None, alias="renewalStatus"
+    )
+
+
+class CreateMandateResponse(FluviusBaseModel):
+    """Response from creating a mock mandate."""
+
+    status: str | None = None
+
+
+class CreateMandateResponseApiDataResponse(FluviusBaseModel):
+    """Represents a successful response from the mock mandate creation."""
+
+    meta: ResponseMetadata | None = Field(default=None, alias="_meta")
+    data: CreateMandateResponse | None = None

fluvius_energy_api/models/session.py

@@ -0,0 +1,46 @@
+"""Client session models for the Fluvius Energy API."""
+
+from datetime import datetime
+from pydantic import Field
+
+from .base import FluviusBaseModel, ResponseMetadata
+from .enums import CreateClientSessionStatus, DataServiceType, Flow
+
+
+class ClientSessionDataService(FluviusBaseModel):
+    """Represents a data service on a request to create a client session."""
+
+    data_service_type: DataServiceType = Field(alias="dataServiceType")
+    data_period_from: str | None = Field(default=None, alias="dataPeriodFrom")
+    data_period_to: str | None = Field(default=None, alias="dataPeriodTo")
+
+
+class CreateClientSessionRequest(FluviusBaseModel):
+    """Represents a request to create a client session."""
+
+    data_access_contract_number: str = Field(alias="dataAccessContractNumber")
+    reference_number: str = Field(alias="referenceNumber")
+    flow: Flow
+    data_services: list[ClientSessionDataService] | None = Field(
+        default=None, alias="dataServices"
+    )
+    number_of_eans: int | None = Field(default=None, alias="numberOfEans")
+    return_url_success: str | None = Field(default=None, alias="returnUrlSuccess")
+    return_url_failed: str | None = Field(default=None, alias="returnUrlFailed")
+    sso: bool | None = None
+    enterprise_number: str | None = Field(default=None, alias="enterpriseNumber")
+
+
+class CreateClientSessionResponse(FluviusBaseModel):
+    """Represents a response containing a new client session."""
+
+    status: CreateClientSessionStatus | None = None
+    short_url_identifier: str | None = Field(default=None, alias="shortUrlIdentifier")
+    valid_to: datetime | None = Field(default=None, alias="validTo")
+
+
+class CreateClientSessionResponseApiDataResponse(FluviusBaseModel):
+    """Represents a successful response from the server containing data."""
+
+    meta: ResponseMetadata | None = Field(default=None, alias="_meta")
+    data: CreateClientSessionResponse | None = None