kvk-connect 0.1.6__py3-none-any.whl

kvk_connect/__init__.py

@@ -0,0 +1,11 @@
+"""KVK Connect - Python client for KVK API."""
+
+from __future__ import annotations
+
+from kvk_connect.api.client import KVKApiClient
+from kvk_connect.services.record_service import KVKRecordService
+
+__all__ = [
+    "KVKApiClient",
+    "KVKRecordService",
+]

kvk_connect/api/__init__.py

@@ -0,0 +1,4 @@
+# mappers package initialization
+from .client import KVKApiClient
+
+__all__ = ["KVKApiClient"]

kvk_connect/api/client.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import datetime
+import logging
+
+import requests
+from requests import Response
+
+from ..models.api.basisprofiel_api import BasisProfielAPI
+from ..models.api.mutatiesignalen_api import MutatiesAPI
+from ..models.api.vestigingen_api import VestigingenAPI
+from ..models.api.vestigingsprofiel_api import VestigingsProfielAPI
+from ..utils.rate_limit import global_rate_limit
+from . import endpoints
+from .session import create_session_with_retries
+
+logger = logging.getLogger(__name__)
+
+
+class KVKApiClient:
+    def __init__(self, api_key: str, base_url: str = endpoints.DEFAULT_BASE_URL):
+        self.session = create_session_with_retries()  # requests.Session()
+        self.session.headers.update({"apikey": api_key})
+        self.base_url = base_url
+        self.timeout = 600
+
+    def close(self):  # noqa: D102
+        self.session.close()
+
+    @staticmethod
+    def _get_error_payload(resp: Response) -> str:
+        """Extract error payload from response as string for logging."""
+        try:
+            error_data = resp.json()
+            return str(error_data)
+        except (ValueError, requests.exceptions.JSONDecodeError):
+            return resp.text if resp.text else "No error details available"
+
+    @global_rate_limit()
+    def get_mutatie_signaal_raw(self, abonnement_id: str, signaal_id: str) -> dict | None:
+        """Get raw mutatie signaal data from KVK API.
+
+        Args:
+            abonnement_id (str): Abonnement ID.
+            signaal_id (str): Signaal ID.
+
+            Return: Originele JSON of None bij fout.
+        """
+        url = endpoints.mutatieservice_signaal(abonnement_id, signaal_id)
+        try:
+            resp = self.session.get(url, timeout=self.timeout)
+            resp.raise_for_status()
+            return resp.json()
+        except requests.HTTPError as e:
+            logger.warning("KVK API error for nummer %s: %s", abonnement_id, e)
+            logger.warning("Mogelijke error: %s", self._get_error_payload(resp))
+            return None
+
+    @global_rate_limit()
+    def get_mutaties_raw(
+        self, abonnement_id: str, from_time: datetime.datetime, to_time: datetime.datetime, page: int, size: int
+    ) -> dict | None:
+        """Get raw mutaties data from KVK API.
+
+        Args:
+            abonnement_id (str): Abonnement ID.
+            from_time (datetime): Start datetime for mutaties.
+            to_time (datetime): End datetime for mutaties.
+            page (int): Page number.
+            size (int): Number of items per page.
+
+            Return: Originele JSON of None bij fout.
+        """
+        url = endpoints.mutatieservice(abonnement_id)
+        try:
+            params = {
+                "vanaf": from_time.strftime("%Y-%m-%dT%H:%M:%SZ"),
+                "tot": to_time.strftime("%Y-%m-%dT%H:%M:%SZ"),
+                "pagina": str(page),
+                "aantal": str(size),
+            }
+            resp = self.session.get(url, params=params, timeout=self.timeout)
+            resp.raise_for_status()
+            return resp.json()
+        except requests.HTTPError as e:
+            logger.warning("KVK API error for nummer %s: %s", abonnement_id, e)
+            logger.warning("Mogelijke error: %s", self._get_error_payload(resp))
+            return None
+
+    def get_mutaties(
+        self, abonnement_id: str, from_time: datetime.datetime, to_time: datetime.datetime, page: int, size: int
+    ) -> MutatiesAPI | None:
+        """Get mutaties from KVK API in domein model."""
+        data = self.get_mutaties_raw(abonnement_id, from_time, to_time, page, size)
+        return None if data is None else MutatiesAPI.from_dict(data)
+
+    @global_rate_limit()
+    def get_basisinformatie_raw(self, kvk_nummer: str, geo_data: bool = True) -> dict | None:
+        """Get raw basisinformatie data from KVK API.
+
+        Args:
+            kvk_nummer (str): KVK nummer.
+            geo_data (bool): Include geo data or not.
+
+            Return: Originele JSON of None bij fout.
+        """
+        url = endpoints.basisprofiel(kvk_nummer)
+        logger.debug("KVK API url: %s", url)
+        try:
+            resp = self.session.get(url, params={"geoData": geo_data}, timeout=self.timeout)
+            resp.raise_for_status()
+            logger.debug(
+                "KVK Basisinformatie Raw response for kvk nummer %s: %s, with url: %s", kvk_nummer, resp.json(), url
+            )
+            return resp.json()
+        except requests.HTTPError as e:
+            logger.warning("KVK API error for nummer %s: %s", kvk_nummer, e)
+            logger.warning("Mogelijke error: %s", self._get_error_payload(resp))
+            return None
+
+    def get_basisinformatie(self, kvk_nummer: str, geo_data: bool = True) -> BasisProfielAPI | None:
+        """Get basisinformatie from KVK API in domein model."""
+        data = self.get_basisinformatie_raw(kvk_nummer, geo_data)
+        return None if data is None else BasisProfielAPI.from_dict(data)
+
+    @global_rate_limit()
+    def get_vestigingen_raw(self, kvk_nummer: str) -> dict | None:
+        """Get raw vestigingen data from KVK API.
+
+        Args:
+            kvk_nummer (str): KVK nummer.
+            geo_data (bool): Include geo data or not.
+
+            Return: Originele JSON of None bij fout.
+        """
+        url = endpoints.vestigingen(kvk_nummer)
+        try:
+            resp = self.session.get(url, timeout=60)
+            resp.raise_for_status()
+            logger.debug(
+                "KVK Vestigingen Raw response for kvk nummer %s: %s, with url: %s", kvk_nummer, resp.json(), url
+            )
+            return resp.json()
+        except requests.HTTPError as e:
+            logger.warning("KVK API error for nummer %s: %s", kvk_nummer, e)
+            logger.warning("Mogelijke error: %s", self._get_error_payload(resp))
+            return None
+
+    def get_vestigingen(self, kvk_nummer: str) -> VestigingenAPI | None:
+        """Get vestigingen from KVK API in domein model."""
+        data = self.get_vestigingen_raw(kvk_nummer)
+        return None if data is None else VestigingenAPI.from_dict(data)
+
+    @global_rate_limit()
+    def get_vestigingsprofiel_raw(self, vestigingsnummer: str, geo_data: bool = True) -> dict | None:
+        """Get raw vestigingsprofiel data from KVK API.
+
+        Args:
+            vestigingsnummer (str): Vestigingsnummer.
+            geo_data (bool): Include geo data or not.
+
+            Return: Originele JSON of None bij fout.
+        """
+        url = endpoints.vestigingsprofiel(vestigingsnummer)
+        try:
+            resp = self.session.get(url, params={"geoData": geo_data}, timeout=self.timeout)
+            resp.raise_for_status()
+            logger.debug(
+                "KVK VestigingenProfiel Raw response for vestigingen nummer %s: %s, with url: %s",
+                vestigingsnummer,
+                resp.json(),
+                url,
+            )
+            return resp.json()
+        except requests.HTTPError as e:
+            logger.warning("KVK API error for nummer %s: %s", vestigingsnummer, e)
+            logger.warning("Mogelijke error: %s", self._get_error_payload(resp))
+            return None
+
+    def get_vestigingsprofiel(self, vestigingsnummer: str, geo_data: bool = True) -> VestigingsProfielAPI | None:
+        """Get vestigingsprofiel from KVK API in domein model."""
+        data = self.get_vestigingsprofiel_raw(vestigingsnummer, geo_data)
+        return None if data is None else VestigingsProfielAPI.from_dict(data)

kvk_connect/api/endpoints.py

@@ -0,0 +1,24 @@
+# ruff: noqa: D103
+import os
+
+DEFAULT_BASE_URL = os.getenv("KVK_BASE_URL", "https://api.kvk.nl/api/v1")
+
+
+def basisprofiel(kvk_nummer: str) -> str:
+    return f"{DEFAULT_BASE_URL}/basisprofielen/{kvk_nummer}"
+
+
+def vestigingen(kvk_nummer: str) -> str:
+    return f"{DEFAULT_BASE_URL}/basisprofielen/{kvk_nummer}/vestigingen"
+
+
+def vestigingsprofiel(vestigingsnummer: str) -> str:
+    return f"{DEFAULT_BASE_URL}/vestigingsprofielen/{vestigingsnummer}"
+
+
+def mutatieservice(abonnement_id: str) -> str:
+    return f"{DEFAULT_BASE_URL}/abonnementen/{abonnement_id}"
+
+
+def mutatieservice_signaal(abonnement_id: str, signaal_id: str) -> str:
+    return f"{DEFAULT_BASE_URL}/abonnementen/{abonnement_id}/signalen/{signaal_id}"

kvk_connect/api/session.py

@@ -0,0 +1,34 @@
+import logging
+
+from requests import Session
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+logger = logging.getLogger(__name__)
+
+
+def create_session_with_retries(
+    retries: int = 3, backoff_factor: float = 1.0, status_forcelist: tuple[int, ...] = (429, 500, 502, 503, 504)
+) -> Session:
+    """Maakt een requests.Session met automatische retry-logica."""
+    session = Session()
+    retry_strategy = Retry(
+        total=retries,
+        backoff_factor=backoff_factor,
+        status_forcelist=status_forcelist,
+        allowed_methods=["GET", "POST", "PUT", "DELETE"],
+    )
+    adapter = HTTPAdapter(max_retries=retry_strategy)
+    session.mount("http://", adapter)
+    session.mount("https://", adapter)
+
+    # logging.getLogger("urllib3.util.retry").setLevel(logging.DEBUG)
+    # logging.getLogger("urllib3.connectionpool").setLevel(logging.DEBUG)
+    logger.debug(
+        "Retry strategy configured: total=%d, backoff_factor=%f, status_forcelist=%s",
+        retries,
+        backoff_factor,
+        status_forcelist,
+    )
+
+    return session

kvk_connect/cli/main.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import argparse
+
+from kvk_connect import KVKApiClient
+from kvk_connect.utils import get_env
+
+
+def run():
+    """Start de CLI tool voor KVK Connect."""
+
+    parser = argparse.ArgumentParser(prog="kvk-connect")
+    parser.add_argument("--kvk", help="KVK number", required=True)
+    parser.add_argument("--geo", action="store_true", default=True)
+    args = parser.parse_args()
+
+    api_key = get_env("KVK_API_KEY_PROD", required=True) or "NO_KEY_FOUND"
+    client = KVKApiClient(api_key)
+    try:
+        basis = client.get_basisinformatie(args.kvk, geo_data=args.geo)
+        if not basis:
+            print("No data")
+            return
+        print(basis.to_dict())
+    finally:
+        client.close()

kvk_connect/db/basisprofiel_reader.py

@@ -0,0 +1,67 @@
+import random
+
+from sqlalchemy import func, select
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session
+
+from kvk_connect.models.orm.basisprofiel_orm import BasisProfielORM
+from kvk_connect.models.orm.signaal_orm import SignaalORM
+
+
+class BasisProfielReader:
+    def __init__(self, engine: Engine):
+        self.engine = engine
+
+    def get_missing_kvk_nummers(self, limit: int = 50) -> list[str]:
+        """Retourneert random sample van KVK nummers die wel in signalen staan maar nog niet in basisprofielen.
+
+        Hiermee halen we kvk nummers op die wel uit signalen komen, maar mogelijk nog niet bekend zijn.
+        Hierdoor beperking op aantal op te halen nummers per keer (limit), zodat we langzaam over tijd inlopen.
+        """
+        fetch_size = limit * 5
+        with Session(self.engine) as session:
+            stmt = (
+                select(SignaalORM.kvknummer)
+                .outerjoin(BasisProfielORM, SignaalORM.kvknummer == BasisProfielORM.kvk_nummer)
+                .where(BasisProfielORM.kvk_nummer.is_(None))
+                .distinct()
+                .limit(fetch_size)  # maximaal limit nieuwe per keer ophalen
+            )
+
+            result = session.execute(stmt).scalars().all()
+            all_kvk_nrs = list(result)
+
+            # Random sample uit de opgehaalde resultaten
+            return random.sample(all_kvk_nrs, min(limit, len(all_kvk_nrs)))
+
+    def get_missing_kvk_nummers_count(self) -> int:
+        """Retourneert het totaal aantal KVK nummers die wel in signalen staan maar nog niet in basisprofielen."""
+        with Session(self.engine) as session:
+            stmt = (
+                select(func.count(func.distinct(SignaalORM.kvknummer)))
+                .outerjoin(BasisProfielORM, SignaalORM.kvknummer == BasisProfielORM.kvk_nummer)
+                .where(BasisProfielORM.kvk_nummer.is_(None))
+            )
+
+            result = session.execute(stmt).scalar()
+            return result or 0
+
+    def get_outdated_kvk_nummers(self) -> list[str]:
+        """Retourneert unieke KVK nummers die zowel in signalen als basisprofielen staan.
+
+        Hierbij worden alleen basisprofielen bekeken de signaal timestamp nieuwer is
+        dan het basisprofiel (update nodig).
+        """
+        with Session(self.engine) as session:
+            stmt = (
+                select(SignaalORM.kvknummer)
+                .join(BasisProfielORM, SignaalORM.kvknummer == BasisProfielORM.kvk_nummer)
+                .where(
+                    SignaalORM.timestamp > BasisProfielORM.last_updated,
+                    SignaalORM.vestigingsnummer.is_(None),  # Alleen basisprofiel updates, geen vestigingsprofielen
+                )
+                .distinct()
+            )
+
+            result = session.execute(stmt).scalars().all()
+            return list(result)

kvk_connect/db/basisprofiel_writer.py

@@ -0,0 +1,73 @@
+import logging
+from datetime import UTC, datetime
+
+from sqlalchemy import Engine
+from sqlalchemy.orm import Session, sessionmaker
+
+from kvk_connect.models.domain import BasisProfielDomain
+from kvk_connect.models.orm.basisprofiel_orm import BasisProfielORM
+from kvk_connect.utils.tools import parse_kvk_datum
+
+logger = logging.getLogger(__name__)
+
+
+class BasisProfielWriter:
+    # lage default batch size op 1 om db locking te minimaliseren
+    def __init__(self, engine: Engine, batch_size: int = 1):
+        logger.info("Initializing BasisProfielWriter, met batch size: %d", batch_size)
+        self.Session = sessionmaker(bind=engine)
+        self.batch_size = batch_size
+        self._session: Session | None = None
+        self._count = 0
+
+    def __enter__(self):
+        """Create a new session for the context."""
+        self._session = self.Session()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        """Commit changes if no exception, else rollback. Always close session."""
+        try:
+            if exc is None:
+                self.flush()
+            else:
+                if self._session:
+                    self._session.rollback()
+        finally:
+            if self._session:
+                self._session.close()
+            self._session = None
+
+    def flush(self) -> None:  # noqa: D102
+        if self._session:
+            self._session.commit()
+
+    def add(self, domain_basisprofiel: BasisProfielDomain) -> None:  # noqa: D102
+        if not self._session:
+            raise RuntimeError("Session not initialized. Use context manager.")
+
+        orm_obj = self._to_orm(domain_basisprofiel)
+        orm_obj.last_updated = datetime.now(UTC)
+
+        self._session.merge(orm_obj)
+        self._count += 1
+
+        if self._count % self.batch_size == 0:
+            self._session.commit()
+
+    @staticmethod
+    def _to_orm(api_obj: BasisProfielDomain) -> BasisProfielORM:
+        return BasisProfielORM(
+            kvk_nummer=api_obj.kvk_nummer,
+            naam=api_obj.naam,
+            hoofdactiviteit=api_obj.hoofdactiviteit,
+            hoofdactiviteit_omschrijving=api_obj.hoofdactiviteit_omschrijving,
+            activiteit_overig=api_obj.activiteit_overig,
+            rechtsvorm=api_obj.rechtsvorm,
+            rechtsvorm_uitgebreid=api_obj.rechtsvorm_uitgebreid,
+            eerste_handelsnaam=api_obj.eerste_handelsnaam,
+            totaal_werkzame_personen=api_obj.totaal_werkzame_personen,
+            websites=api_obj.websites,
+            registratie_datum_aanvang=parse_kvk_datum(api_obj.registratie_datum_aanvang),
+            registratie_datum_einde=parse_kvk_datum(api_obj.registratie_datum_einde),
+        )

kvk_connect/db/init.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from sqlalchemy import inspect
+
+if TYPE_CHECKING:
+    from sqlalchemy.engine import Engine
+    from sqlalchemy.orm import DeclarativeBase
+
+logger = logging.getLogger(__name__)
+
+
+def ensure_database_initialized(engine: Engine, base: type[DeclarativeBase]) -> None:
+    """Ensure all tables for the given Base exist in the database.
+
+    This is safe to run multiple times - existing tables are skipped.
+    """
+    logger.info("Ensuring tables exist for %s...", base.__name__)
+    base.metadata.create_all(engine)
+
+    inspector = inspect(engine)
+    table_count = len([t for t in inspector.get_table_names() if t in base.metadata.tables])
+    logger.info("Database initialized: %s table(s) ready", table_count)

kvk_connect/db/kvkvestigingen_reader.py

@@ -0,0 +1,41 @@
+from sqlalchemy import select
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session
+
+from kvk_connect.models.orm.basisprofiel_orm import BasisProfielORM
+from kvk_connect.models.orm.kvkvestigingen_orm import VestigingenORM
+
+
+class KvKVestigingenReader:
+    def __init__(self, engine: Engine):
+        self.engine = engine
+
+    def get_missing_kvk_nummers(self) -> list[str]:
+        """Retourneert unieke KVK nummers die wel in basisprofielen staan maar nog niet in kvkvestigingen."""
+        with Session(self.engine) as session:
+            stmt = (
+                select(BasisProfielORM.kvk_nummer)
+                .select_from(BasisProfielORM)
+                .outerjoin(VestigingenORM, BasisProfielORM.kvk_nummer == VestigingenORM.kvk_nummer)
+                .where(VestigingenORM.kvk_nummer.is_(None))
+                .distinct()
+            )
+
+            result = session.execute(stmt).scalars().all()
+            return list(result)
+
+    def get_outdated_vestigingen(self) -> list[str]:
+        """Geen een lijst van unieke kvknummers terug waarvan de vestigingen verouderd zijn.
+
+        Dit is gedefinieerd als basisprofielen die nieuwer zijn dan de laatste update van de vestigingen.
+        """
+        with Session(self.engine) as session:
+            stmt = (
+                select(BasisProfielORM.kvk_nummer)
+                .join(VestigingenORM, BasisProfielORM.kvk_nummer == VestigingenORM.kvk_nummer)
+                .where(BasisProfielORM.last_updated > VestigingenORM.last_updated)
+                .distinct()
+            )
+
+            result = session.execute(stmt).scalars().all()
+            return list(result)

kvk_connect/db/kvkvestigingen_writer.py

@@ -0,0 +1,73 @@
+import logging
+from datetime import UTC, datetime
+
+from sqlalchemy.orm import Session, sessionmaker
+
+from kvk_connect.models.domain import KvKVestigingsNummersDomain
+from kvk_connect.models.orm.kvkvestigingen_orm import VestigingenORM
+
+logger = logging.getLogger(__name__)
+
+
+class KvKVestigingenWriter:
+    # Low batch size by default to avoid locking issues
+    def __init__(self, engine, batch_size: int = 1):
+        logger.info("Initializing BasisProfielWriter, met batch size: %d", batch_size)
+        self.Session = sessionmaker(bind=engine)
+        self.batch_size = batch_size
+        self._session: Session | None = None
+        self._count = 0
+
+    def __enter__(self):
+        """Start een nieuwe database sessie."""
+        self._session = self.Session()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        """Commit of rollback de sessie en sluit deze af."""
+        try:
+            if exc is None:
+                self.flush()
+            else:
+                if self._session:
+                    self._session.rollback()
+        finally:
+            if self._session:
+                self._session.close()
+            self._session = None
+
+    def flush(self) -> None:  # noqa: D102
+        if self._session:
+            self._session.commit()
+
+    def add(self, domain_kvkvestigingen: KvKVestigingsNummersDomain) -> None:
+        """Schrijf alle vestigingsnummers uit het domeinmodel weg naar de database.
+
+        Creëert een apart database-record per vestigingsnummer met het bijbehorende kvkNummer.
+        Als er geen vestigingsnummers zijn, wordt een record met vestigingsnummer=NULL weggeschreven.
+
+        Params:
+            domain_kvkvestigingen: KvKVestigingsNummersDomain - Domain object met kvkNummer en lijst vestigingsnummers
+        """
+        if not self._session:
+            raise RuntimeError("Session not initialized. Use context manager.")
+
+        timestamp = datetime.now(UTC)
+        vestigingsnummers = domain_kvkvestigingen.vestigingsnummers or [
+            VestigingenORM.SENTINEL_VESTIGINGSNUMMER
+        ]  # Gebruik Sentinel waarde als er geen vestigingen zijn
+
+        # Merge alle vestigingen van dit KvK nummer
+        for vestigingsnummer in vestigingsnummers:
+            orm_obj = VestigingenORM(
+                kvk_nummer=domain_kvkvestigingen.kvk_nummer, vestigingsnummer=vestigingsnummer, last_updated=timestamp
+            )
+            self._session.merge(orm_obj)
+
+        # Verhoog counter met totaal aantal vestigingen van dit KvK
+        self._count += len(vestigingsnummers)
+
+        # Commit als batch_size bereikt
+        if self._count >= self.batch_size:
+            self._session.commit()
+            self._count = 0

kvk_connect/db/signaal_reader.py

@@ -0,0 +1,23 @@
+from datetime import datetime
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import sessionmaker
+
+from kvk_connect.models.orm.signaal_orm import SignaalORM
+
+
+class SignaalReader:
+    def __init__(self, engine):
+        self.Session = sessionmaker(bind=engine)
+
+    def get_last_timestamp(self) -> datetime | None:
+        """Returns the latest stored signaal timestamp, or None if table is empty."""
+        with self.Session() as session:
+            stmt = select(func.max(SignaalORM.timestamp))
+            return session.execute(stmt).scalar()
+
+    def get_first_timestamp(self) -> datetime | None:
+        """Returns the latest stored signaal timestamp, or None if table is empty."""
+        with self.Session() as session:
+            stmt = select(func.min(SignaalORM.timestamp))
+            return session.execute(stmt).scalar()

kvk_connect/db/signaal_writer.py

@@ -0,0 +1,73 @@
+# ruff: noqa: D102
+import logging
+
+from sqlalchemy.orm import Session, sessionmaker
+
+from kvk_connect.models.api.mutatiesignalen_api import MutatieSignaal
+from kvk_connect.models.orm.signaal_orm import SignaalORM
+
+logger = logging.getLogger(__name__)
+
+
+class SignaalWriter:
+    def __init__(self, engine, batch_size: int = 10, upsert: bool = True):
+        logger.info("Initializing BasisProfielWriter, met batch size: %d", batch_size)
+        self.Session = sessionmaker(bind=engine)
+        self.batch_size = batch_size
+        self.upsert = upsert
+        self._session: Session | None = None
+        self._buffer: list[SignaalORM] = []
+        self._count = 0
+
+    def __enter__(self):
+        """Create a new session on entry of context manager."""
+        self._session = self.Session()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        """Handle commit/rollback on exit of context manager."""
+        try:
+            if exc is None:
+                self.flush()
+            else:
+                if self._session:
+                    self._session.rollback()
+        finally:
+            if self._session:
+                self._session.close()
+            self._session = None
+
+    def add(self, api_signaal: MutatieSignaal) -> None:
+        if not self._session:
+            raise RuntimeError("Session not initialized. Use context manager.")
+
+        orm_obj = self._to_orm(api_signaal)
+        if self.upsert:
+            self._session.merge(orm_obj)  # upsert per row
+            self._count += 1
+            if self._count % self.batch_size == 0:
+                self._session.commit()
+        else:
+            self._buffer.append(orm_obj)
+            if len(self._buffer) >= self.batch_size:
+                self._session.bulk_save_objects(self._buffer)
+                self._session.commit()
+                self._buffer.clear()
+
+    def flush(self) -> None:
+        if not self._session:
+            return
+        if not self.upsert and self._buffer:
+            self._session.bulk_save_objects(self._buffer)
+            self._buffer.clear()
+        self._session.commit()
+
+    @staticmethod
+    def _to_orm(s: MutatieSignaal) -> SignaalORM:
+        return SignaalORM(
+            id=s.id,
+            timestamp=s.timestamp,
+            kvknummer=s.kvknummer,
+            signaal_type=s.signaal_type,
+            vestigingsnummer=s.vestigingsnummer,
+        )