storing last run in database

The old behaviour was: You open a page without being authorized, you are getting redirected to /login that
redirects you after a successful authentication to /dashboard. This is really annoying if you want to open
listenings directly from your notification adapter for example. This commit introduces a method to redirect
you back to the original page you opened after the authentication process by adding the navigation of the
opened page as state to the navigation to /login. The login component than unpacks the state that contains
the old navigation and redirects the user back to path from the original navigation. The path /dashboard is
used as a fallback if no navigation in the state is present.

.dockerignore

@@ -1,7 +1,47 @@
+# Dependencies (will be installed fresh in container)
 node_modules/
-npm-debug.log
-test/
+
+# Database and config (mounted as volumes)
 db/
 conf/
+
+# Git
 .git/
 .github/
+.gitignore
+
+# IDE and editor
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Testing
+test/
+
+# Documentation
+doc/
+*.md
+!README.md
+
+# Development config files
+.babelrc
+.husky/
+.nvmrc
+.prettierrc
+.prettierignore
+eslint.config.js
+
+# Docker files (not needed inside container)
+Dockerfile
+docker-compose.yml
+docker-test.sh
+.dockerignore
+
+# Logs
+*.log
+npm-debug.log
+
+# Build artifacts (built fresh in container)
+dist/

.gitattributes

@@ -0,0 +1 @@
+test/testFixtures/** linguist-vendored

.github/ISSUE_TEMPLATE/bug.yml

@@ -5,6 +5,40 @@ labels: [bug]
 assignees: []
 
 body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Please attach a debug bundle (available since Fredy 22.5.0+)
+
+        Since **Fredy 22.5.0** you can export a debug bundle that contains a system
+        snapshot (`sys.txt`, Fredy version, Node.js version, OS, Docker detection,
+        CPU, memory, sanitized settings) and the full log buffer (`logs.txt`) that
+        Fredy recorded while you reproduced the issue. Attaching it dramatically
+        speeds up triage.
+        Oh and before you ask: I decided against simply putting all logs into the debug
+        due to privacy reasons :)
+
+        **The bundle is only useful when the error is actually inside `logs.txt`.**
+        That means you have to record first, reproduce after:
+
+        1. Log in to Fredy as **admin** and open **Settings → Debug**.
+        2. Click **"Enable debug logging" / "Debug-Logging aktivieren"**. A red banner
+           appears across the whole app while recording is on.
+        3. **Now reproduce the bug.** Trigger the broken job, click the failing
+           button, wait for the failing scrape — whatever it was.
+        4. Come back to **Settings → Debug** and confirm the progress bar moved
+           (i.e. log entries were actually written). If it stayed at 0%, nothing was
+           captured and the bundle won't help us.
+        5. Click **"Download debug information" / "Debug Informationen herunterladen"**
+           and drop the resulting `FredyDebug-*.zip` into the "Screenshots / Logs"
+           field below.
+        6. Optional but recommended: click **"Disable debug logging"** to stop the
+           recording, and **"Delete stored debug logs"** once you have the zip so the
+           database does not keep them around.
+
+        On Fredy versions older than 22.5.0, paste the relevant log lines from your
+        console / Docker / systemd journal manually instead.
+
   - type: textarea
     id: description
     attributes:
@@ -49,8 +83,11 @@ body:
     id: screenshots
     attributes:
       label: Screenshots / Logs
-      description: Add screenshots or paste log output to help explain the problem.
-      placeholder: "Drag and drop screenshots here, or paste logs."
+      description: |
+        Drop the FredyDebug-*.zip here (see the instructions at the top, available
+        since Fredy 22.5.0) and/or any additional screenshots. If you cannot produce
+        the bundle, paste relevant log lines instead.
+      placeholder: "Drag and drop the FredyDebug-*.zip and any screenshots here."
     validations:
       required: false
 
@@ -58,8 +95,10 @@ body:
     id: environment
     attributes:
       label: Environment
-      description: Provide details about your environment.
-      placeholder: "OS: macOS 15, Browser: Chrome 124, App version: 1.2.3"
+      description: |
+        Provide details about your environment. You can copy most of this from
+        sys.txt inside the debug bundle.
+      placeholder: "OS: macOS 15, Browser: Chrome 124, App version: 22.5.0, Docker: yes"
     validations:
       required: true
 

.github/workflows/docker.yml

@@ -62,6 +62,7 @@ jobs:
       - name: Test container with docker compose
         run: |
           echo "Starting container with docker compose..."
+          mkdir -p ./db ./conf && chmod 777 ./db ./conf
           docker compose up --build -d
           echo "Waiting for container to be ready (60 seconds for start_period)..."
           sleep 60

.github/workflows/test.yml

@@ -19,4 +19,4 @@ jobs:
           cache: 'yarn'
 
       - run: yarn install
-      - run: yarn test
+      - run: yarn test:offline

.gitignore

@@ -6,3 +6,4 @@ npm-debug.log
 .DS_Store
 .idea
 .vscode
+tools/release/config.json

CHANGELOG.md

@@ -1,94 +0,0 @@
-Newer release changelog see https://github.com/orangecoding/fredy/releases
-
----
-
-###### [V5.5.0]
-
-- Upgrading dependencies
-- fixing provider
-- allow multiple instances of 1 provider
-- **BREAKING**: Minimum node version is now 16
-
-###### [V5.4.6]
-
-- Adding Instana node.js monitoring
--
-
-###### [V5.4.5]
-
-- Adding Instana node.js monitoring
-
-###### [V5.4.4]
-
-- Add support for Immo Südwest Presse (immo.swp.de)
-- Telegram: Use job name instead of ID and link in title
-- Fix race condition if user ID is in session but not in user store
-- Allow visiting the original provider URL
-
-###### [V5.4.3]
-
-- re-writing readme
-- improving docker build
-- using github's actions to build docker and test automatically
-
-###### [V5.4.2]
-
-- Fixing prod build
-
-###### [V5.4.1]
-
-- Upgrading dependencies
-- Provider urls are now automagically been changed to include the correct sort order for search results
-
-```
-Note: It has been an point of confusion since the very beginning of Fredy, that people simply copied the url, but
-did not take care of sorting the search results by date. If this is not done, Fredy will most likely not see the latest
-results, thus cannot report them. This release fixes it by adding the necessary params (or replaces them).
-```
-
-###### [V5.3.0]
-
-- Upgrading dependencies
-- It's now possible to send mails to multiple receiver using comma separation for MailJet & Sendgrid
-- Fixing Immowelt scraping
-
-###### [V5.2.0]
-
-- Upgrading dependencies
-- Adding new similarity check layer (Duplicates are being removed now)
-- Adding paging for search results
-
-###### [V5.1.0]
-
-- Upgrading dependencies
-- NodeJS 12.13 is now the minimum supported version
-- Adding general settings as new configuration page to ui
-- Adding new feature working hours
-
-###### [V5.0.0]
-
-- Upgrading dependencies
-- NodeJS 12 is now the minimum supported version
-
-###### [V4.0.0]
-
-Bringing back Immoscout :tada:
-
-###### [V3.0.0]
-
-This is basically a re-write, your old config file will not be compatible anymore. Please re-created your search jobs
-on the new ui and use the values from your previous config file if needed.
-
-```
-- We're getting rid of manual config changes, Fredy, now ships with a UI so that it's easy for you to create and edit jobs
-```
-
-###### [V2.0.0]
-
-```
-- Fredy can now run multiple search job on one instance
-- Changed lot's of the structure of Fredy to make this happen
-[BREAKING CHANGES]
-- The config has been changed, the config of V1.x will not work any longer
-- Sources have been renamed to provider
-```

CLAUDE.md

@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Fredy is a self-hosted real estate finder for Germany. It scrapes German real estate portals (ImmoScout24, Immowelt, Immonet, Kleinanzeigen, WG-Gesucht, etc.), deduplicates results across providers, and sends notifications via Slack, Telegram, Email, Discord, ntfy, etc. It includes a React web UI and a built-in MCP server for LLM access to listings data.
+
+- Node.js >= 22, ESM-only (`"type": "module"`)
+- Default port: 9998, default login: admin / admin
+- SQLite via `better-sqlite3` (synchronous - all DB ops are sync; only network I/O is async)
+
+## Commands
+
+```bash
+# Development
+yarn run start:backend:dev    # nodemon backend
+yarn run start:frontend:dev   # Vite dev server (proxies /api → :9998)
+
+# Production
+yarn run start:backend        # NODE_ENV=production node index.js
+yarn run build:frontend       # vite build → ui/public/
+
+# Tests
+yarn test                     # Live tests (hits actual providers)
+yarn test:offline             # Offline tests using HTML/JSON fixtures (fast, preferred)
+yarn test:download-fixtures   # Re-download fresh provider HTML fixtures
+
+# Single test file
+TEST_MODE=offline npx vitest run test/provider/immoscout.test.js
+
+# Lint / Format
+yarn lint && yarn lint:fix
+yarn format && yarn format:check
+
+# DB migrations
+yarn migratedb
+```
+
+## Architecture
+
+### Core data flow
+
+```
+index.js (startup)
+  ├── runMigrations()
+  ├── getProviders()            # lazily imports lib/provider/*.js
+  ├── similarityCache.init()    # preloads hash cache from DB
+  ├── api.js                    # starts restana HTTP server
+  └── initJobExecutionService() # registers event-bus listeners + starts scheduler
+
+scheduler (every N minutes) or manual trigger via POST /api/jobs/:id/run
+  └── FredyPipelineExecutioner.execute()
+      1. queryStringMutator(url)           # inject sort-by-date param
+      2. provider.getListings()            # API or Puppeteer+Cheerio
+      3. provider.normalize(listing)       # raw → ParsedListing
+      4. provider.filter(listing)          # blacklist + required fields
+      5. filter to hashes not yet in DB
+      6. provider.fetchDetails()           # optional enrichment
+      7. geocodeAddress()                  # optional lat/lng
+      8. storeListings()
+      9. similarityCache.checkAndAddEntry() # cross-provider dedup
+      10. _filterBySpecs() + _filterByArea()
+      11. notify.send()                    # fan-out to all adapters
+```
+
+### Plugin systems
+
+**Providers** (`lib/provider/*.js`) - each module exports:
+- `metaInformation` - `{ id, name, baseUrl }`
+- `config` - `ProviderConfig` with `requiredFieldNames`, `crawlContainer`, `crawlFields`, `sortByDateParam`, `normalize()`, `filter()`, optional `getListings()`, `fetchDetails()`, `activeTester()`
+- `init(sourceConfig, blacklist)` - called before each job run; providers are **stateful modules** holding mutable `url` and `appliedBlackList` at module scope
+
+**Notification adapters** (`lib/notification/adapter/*.js`) - each exports:
+- `config` - `{ id, name, description, fields }` (drives the UI form)
+- `send({ serviceName, newListings, notificationConfig, jobKey, baseUrl })`
+- Loaded dynamically at startup via `fs.readdirSync`
+
+### Key services
+
+| Service | Location | Notes |
+|---|---|---|
+| Event bus | `lib/services/events/event-bus.js` | Plain `EventEmitter`; events: `jobs:runAll`, `jobs:runOne`, `jobs:status` |
+| SSE broker | `lib/services/sse/sse-broker.js` | Per-userId `Set<ServerResponse>`; heartbeat every 25s; pushes job status to UI |
+| Similarity cache | `lib/services/similarity-check/` | In-memory SHA-256 Set; refreshes hourly; cross-provider dedup by title+price+address |
+| SqliteConnection | `lib/services/storage/SqliteConnection.js` | Singleton, WAL mode; `execute()`, `query()`, `withTransaction()` |
+| Migrations | `lib/services/storage/migrations/` | Numbered JS files each exporting `up(db)`; checksum-tracked in `schema_migrations` |
+| Extractor | `lib/services/extractor/` | Orchestrates Puppeteer + Cheerio; shared browser instance per job |
+
+### Frontend
+
+- React 19 SPA, Vite build → `ui/public/` (served as static by backend)
+- State: Zustand single store with per-domain slices
+- UI library: `@douyinfe/semi-ui`
+- Map: MapLibre GL + `@mapbox/mapbox-gl-draw` + `@turf/boolean-point-in-polygon` for GeoJSON polygon filters
+- In dev: Vite proxies `/api` to `:9998`
+
+### MCP server
+
+Two transports:
+1. **stdio** (`lib/mcp/stdio.js`) - for Claude Desktop/LM Studio; opens its own DB connection (main process need not be running)
+2. **HTTP** (`/api/mcp`) - authenticated via Bearer token (`mcp_token` column in `users` table)
+
+Tools: `list_jobs`, `get_job`, `list_listings`, `get_listing`, `get_current_date_time`. Responses are Markdown via `lib/mcp/mcpNormalizer.js`.
+
+## Key Conventions
+
+- **ESM only** - `import`/`export` everywhere, no CommonJS
+- **JSDoc typedefs** (no TypeScript) in `lib/types/` - `listing.js`, `job.js`, `filter.js`, `providerConfig.js`
+- **Copyright header** required on all `.js` files - enforced by `lint-staged` pre-commit hook via `copyright.js`
+- **`NoNewListingsWarning`** (`lib/errors.js`) is used as control flow to short-circuit the pipeline (not an error)
+- **Test fixtures** in `test/testFixtures/` - HTML/JSON snapshots per provider; `TEST_MODE=offline` mocks `puppeteerExtractor` and global `fetch` via `test/offlineFixtures.js`
+- **`conf/config.json`** is the only runtime config file; created with defaults if missing
+
+## Coding
+- After building the task, run the linter
+- After building the task, run the tests
+- New features must be tested
+- New features must be properly documented with JsDoc
+- You do **not** commit any changes, you do **not** create a new branch unless I told you so

Dockerfile

@@ -1,38 +1,54 @@
 FROM node:22-slim
 
+# System deps for CloakBrowser + build tools for native modules (better-sqlite3)
+# fonts-noto-color-emoji and fonts-freefont-ttf are required so canvas fingerprint
+# hashes match real browsers; missing emoji fonts cause bot detection on Kasada/Akamai.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl ca-certificates fonts-liberation libasound2 \
+    libatk-bridge2.0-0 libatk1.0-0 libcups2 libdbus-1-3 \
+    libdrm2 libgbm1 libgtk-3-0 libnspr4 libnss3 \
+    libx11-xcb1 libxcomposite1 libxdamage1 libxrandr2 xdg-utils \
+    fonts-noto-color-emoji fonts-freefont-ttf \
+    python3 make g++ \
+  && rm -rf /var/lib/apt/lists/* \
+  && mkdir -p /db /conf /fredy
+
 WORKDIR /fredy
 
-# Install Chromium and curl without extra recommended packages and clean apt cache
-# curl is needed for the health check
-RUN apt-get update \
-  && apt-get install -y --no-install-recommends chromium curl \
-  && rm -rf /var/lib/apt/lists/*
+ENV NODE_ENV=production \
+    IS_DOCKER=true
 
-ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
-    PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
+COPY package.json yarn.lock ./
 
-# Copy lockfiles first to leverage cache for dependencies
-COPY package.json yarn.lock .
-
-# Set Yarn timeout, install dependencies and PM2 globally
+# Install dependencies and purge build tools (only needed to compile better-sqlite3)
 RUN yarn config set network-timeout 600000 \
   && yarn --frozen-lockfile \
-  && yarn global add pm2
+  && yarn cache clean
+
+# Pre-download the CloakBrowser stealth Chromium binary (supports x86_64 and arm64)
+RUN node -e "import('cloakbrowser').then(({ensureBinary}) => ensureBinary())"
+
+# Purge build tools now that native modules are compiled
+RUN apt-get purge -y python3 make g++ \
+  && apt-get autoremove -y \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY index.html vite.config.js ./
+COPY ui ./ui
+COPY lib ./lib
 
-# Copy application source and build production assets
-COPY . .
 RUN yarn build:frontend
 
-# Prepare runtime directories and symlinks for data and config
-RUN mkdir -p /db /conf \
-  && chown 1000:1000 /db /conf \
-  && chmod 777 /db /conf \
-  && ln -s /db /fredy/db \
+COPY index.js ./
+
+RUN ln -s /db /fredy/db \
   && ln -s /conf /fredy/conf
 
 EXPOSE 9998
 VOLUME /db
 VOLUME /conf
 
-# Start application using PM2 runtime
-CMD ["pm2-runtime", "index.js"]
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+  CMD curl -f http://localhost:9998/ || exit 1
+
+CMD ["node", "index.js"]

LICENSE

@@ -1,21 +1,214 @@
-MIT License
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
 
-Copyright (c) 2025 Christian Kellner
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+1. Definitions.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor
+   be liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+
+Additional License Condition – Commons Clause
+
+The Licensed Work is provided under the terms of this license and is also
+subject to the following additional condition ("Commons Clause"):
+
+"License Condition v1.0":
+
+The Licensed Work and its derivative works may not be used by any person or
+organization to Sell the Licensed Work (as defined below).
+
+"Sell" or "Selling" means practicing any or all of the rights granted to you
+under the License to provide to third parties, for a fee or other consideration
+(including without limitation fees for hosting or consulting/support services
+related to the Software), a product or service whose value derives, entirely or
+substantially, from the functionality of the Licensed Work.
+
+A non-exhaustive list of activities considered "Selling" includes:
+- Using the Licensed Work to provide paid hosted services or managed services
+- Distributing the Licensed Work as part of a commercial product or service
+  for which a fee is charged primarily for the value of the Licensed Work
+
+This restriction does not apply to the use of the Licensed Work for internal
+business purposes or non-commercial use.
+
+
+Attribution and Naming Clause
+
+Any derivative work based on this software must include clear and visible
+attribution to the original project "Fredy" and its author(s).
+Derivative works may not be distributed, published, or presented under a
+different name or branding without the explicit written permission of the
+original copyright holder.
+
+
+Copyright (c) 2026 Christian Kellner
+Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause

README.md

@@ -23,7 +23,7 @@
 
 
 
-# Fredy 🏡 – Your Self-Hosted Real Estate Finder for Germany
+# Fredy 🏡 - Your Self-Hosted Real Estate Finder for Germany
 
 Finding an apartment or house in Germany can be stressful and
 time-consuming.\
@@ -107,6 +107,10 @@ yarn run start:frontend  # in another terminal
 
 👉 Open <http://localhost:9998>
 
+### With Unraid
+
+Should you use [Unraid](https://unraid.net/), you can now install Fredy from the community store :)
+
 **Default Login:**
 - Username: `admin`
 - Password: `admin`
@@ -115,7 +119,7 @@ yarn run start:frontend  # in another terminal
 
 ## 📸 Screenshots
 
-| Fredy Main Overview                              | Job Configuration                                                     | Found Listings                                                              |
+| Fredy Maps View                                  | Dashboard                                               | Found Listings                                                              |
 |--------------------------------------------------|-----------------------------------------------------------------------|-----------------------------------------------------------------------------|
 | ![Screenshot showing Fredy](doc/screenshot1.png) | ![Screenshot showing job configuration in Fredy](doc/screenshot3.png) | ![Screenshot showing found listings in Fredy](doc/screenshot2.png) |
 
@@ -150,12 +154,53 @@ to Slack + Telegram."\
 Jobs run automatically at the interval you configure (see
 `/conf/config.json`).
 
+### MCP Server 🤖
+
+Starting with **V20**, Fredy ships with a built-in **MCP Server **. This allows you to connect Fredy to LLMs (like Claude, ChatGPT, or local models via LM Studio) and query your real estate data using natural language.
+The local LLM can even enrich existing listings by checking the listing online.   
+
+For more information on how to set it up and use it, please refer to the [MCP Readme](lib/mcp/README.md).
+
 ------------------------------------------------------------------------
 
 ## Immoscout
 
 Immoscout has implemented advanced bot detection. In order to work around this, we are using a reversed engineered version of their mobile api. See [Immoscout Reverse Engineering Documentation](https://github.com/orangecoding/fredy/blob/master/reverse-engineered-immoscout.md)
 
+## 🛡️ Bot Detection & Proxies
+
+Most browser-based providers (immowelt, immonet, kleinanzeigen, ...) are scraped through a hardened headless browser ([CloakBrowser](https://www.npmjs.com/package/cloakbrowser)). It makes the **browser fingerprint** indistinguishable from a real Chrome, which is enough when you run Fredy on a normal home connection.
+
+On a **server / VPS the requests usually originate from a datacenter IP**, and providers behind anti-bot systems (e.g. AWS CloudFront/WAF) block those based on **IP reputation alone**, no matter how perfect the fingerprint is. The typical symptom: it works locally but you get `We have been detected as a bot :-/` on the server.
+
+### The fix: a residential proxy
+
+A **residential proxy** routes Fredy's browser through the internet connection of a real household, so the provider sees a "normal user" IP instead of a datacenter. For German portals, use a **German (DE) residential** (or mobile/4G) proxy. Plain VPNs and **datacenter proxies do not help** here, they share the same bad reputation as your server.
+
+**Configure it** under **Settings → Execution → Proxy URL**. Supported formats:
+
+```
+http://user:pass@host:port
+socks5://user:pass@host:port
+```
+
+Leave the field empty to disable. The proxy applies to all headless-browser providers and takes effect on the next job run (no restart needed). Immoscout uses a separate mobile API and is not affected.
+
+### Where to get a residential proxy
+
+Residential proxies are a paid service (usually billed per GB, Fredy's traffic is small). Well-known providers offering German residential IPs include:
+
+| Provider | Notes |
+|---|---|
+| [IPRoyal](https://iproyal.com) | Pay-as-you-go, no monthly minimum, good for low volume |
+| [Webshare](https://www.webshare.io) | Cheap entry tier, has a small free plan to test with |
+| [Decodo (formerly Smartproxy)](https://decodo.com) | Easy setup, country/city targeting |
+| [SOAX](https://soax.com) | Residential + mobile, fine-grained geo-targeting |
+| [Bright Data](https://brightdata.com) | Largest pool, most features, higher complexity/price |
+| [Oxylabs](https://oxylabs.io) | Enterprise-grade, larger plans |
+
+This is not an endorsement, pick whatever fits your budget. For low-volume use like Fredy, a pay-as-you-go plan (e.g. IPRoyal) or a cheap entry tier (e.g. Webshare) is usually plenty. Make sure to select **Germany** as the proxy location and keep the search interval reasonable (the higher the interval, the less you look like a bot).
+
 ## Analytics
 
 Fredy is completely free (and will always remain free). However, it would be a huge help if you’d allow me to collect some analytical data.
@@ -165,6 +210,50 @@ The data includes: names of active adapters/providers, OS, architecture, Node ve
 
 **Thanks**🤘
 
+## 🐞 Debug Information
+
+Since Fredy **22.5.0** there is a built-in way to capture everything Fredy logs into the
+database for a limited time and download it as a single zip file. This is the recommended
+way to attach diagnostics to a bug report. I decided against simply putting all logs into
+a debug bundle due to privacy reasons!
+
+**How it works**
+
+- Debug logging is **opt-in** and admin-only. As long as it is off, Fredy behaves exactly
+  as before (console output only, nothing in the DB).
+- When you turn it on, every log line (`debug`, `info`, `warn`, `error`) is additionally
+  written into the `debug_logs` SQLite table. The console keeps logging at its usual level.
+- The recorded data is hard-capped at **5 MiB** via a rolling buffer: once the cap is hit,
+  the oldest entries are dropped automatically so the newest ones always survive.
+- The on/off flag is persisted, so debug logging stays on across restarts (and you'll see
+  the warning banner everywhere until you turn it off again).
+
+**Capturing a debug bundle**
+
+1. Open Fredy as an **admin** and go to **Settings → Debug**.
+2. Click **"Enable debug logging" / "Debug-Logging aktivieren"**. A red banner appears on
+   every page while recording is on.
+3. **Reproduce the bug**.
+4. Come back to **Settings → Debug** and check the progress bar, if it stayed at 0 %,
+   nothing was captured.
+5. Click **"Download debug information" / "Debug Informationen herunterladen"**. You get a
+   zip named `YYYY-MM-DD-FredyDebug-<version>.zip` containing two files:
+   - `logs.txt` - every log line captured while recording was on, prefixed with timestamp
+     and level.
+   - `sys.txt` - runtime snapshot (Fredy version, Node.js version, OS, Docker detection,
+     CPU, memory, sanitized settings). Proxy credentials and session secrets are
+     **stripped** before export.
+6. Attach the zip to the bug report.
+7. Optional but recommended: click **"Disable debug logging"** to stop recording, and
+   **"Delete stored debug logs"** once you've sent the zip so the DB does not keep them
+   around.
+
+**What is _not_ included**
+
+- passwords/privacy relevant things
+- Anything that Fredy itself does not pass through its `logger`. If a third-party library
+  writes directly to `process.stderr`, that output stays on the console only.
+
 ## 🛠️ Development
 
 ### Development Mode
@@ -177,10 +266,56 @@ You should now be able to access _Fredy_ from your browser. Check your Terminal
 
 ### Run Tests
 
+## "Online" tests
+These tests are directly executed against the actual providers.
 ``` bash
 yarn run test
 ```
 
+## "Offline" tests
+These tests are using the test fixtures instead of the actual providers. Much faster and "good enough" to test the core functionality.
+``` bash
+yarn run test:offline
+```
+
+## Download new fixtures
+If you have to refresh the fixtures (every once in a while needed because the providers change their code), run this command:
+``` bash
+yarn run download-fixtures
+```
+
+## Adding a new language
+
+Fredy's UI is fully multilingual. Translation files live in `ui/src/locales/`. To add a new language, create a single JSON file there, no code changes required.
+
+**Example: `ui/src/locales/fr.json`**
+```json
+{
+  "_meta": {
+    "flag": "🇫🇷",
+    "name": "Français",
+    "locale": "fr-FR",
+    "semiLocale": "fr"
+  },
+  "nav.dashboard": "Tableau de bord",
+  "common.save": "Enregistrer",
+  ...
+}
+```
+
+The `_meta` fields:
+
+| Field | Description |
+|---|---|
+| `flag` | Unicode flag emoji shown in the language selector |
+| `name` | Display name shown in the language selector |
+| `locale` | BCP 47 locale string used for date and number formatting (e.g. `fr-FR`) |
+| `semiLocale` | Semi UI locale key for component-level strings (date pickers, pagination, etc.) |
+
+> **Important:** `semiLocale` must exactly match a locale filename from the Semi UI locale sources (without the `.js` extension). See the [available Semi UI locales on GitHub](https://github.com/DouyinFE/semi-design/tree/main/packages/semi-ui/locale/source) for the full list of supported keys.
+
+After adding the file, rebuild the frontend (`yarn build:frontend` or restart the dev server) and the new language will appear automatically in **Settings → User Settings → Language**.
+
 ------------------------------------------------------------------------
 
 ## 📐 Architecture
@@ -202,7 +337,7 @@ flowchart TD
         F2["Adapter 2"]
   end
 
-    A1 --> B["FredyPipeline"]
+    A1 --> B["FredyPipelineExecutioner"]
     A2 --> B
     A3 --> B
     B --> C1 & C2 & C3
@@ -214,6 +349,20 @@ flowchart TD
     F1 --> F2
 ```
 
+------------------------------------------------------------------------
+## 🤖 Using AI such as Claude Code
+When I started building Fredy, LLMs were still basically the wet dream of a few nerdy scientists.
+
+Nowadays, it’s easier than ever to throw a prompt into the LLM of your choice and let 'the AI' build your stuff. I’m not against that. I use Claude Code myself for smaller tasks, and I do think these tools can be really useful.
+
+That said, I still believe humans should stay in charge. AI is great-ish at writing code, but it still lacks creativity, context, and the ability to see the full picture.
+
+So, if you want to contribute to Fredy, using AI tools to get things done is totally fine. Just please don’t stop thinking.
+
+I’ve had one too many PRs full of hallucinated bullshit.
+
+**Thanks ;)**
+
 ------------------------------------------------------------------------
 
 ## 👐 Contributing

conf/config.json

@@ -1 +1 @@
-{"interval":"60","port":9998,"workingHours":{"from":"","to":""},"demoMode":false,"analyticsEnabled":true,"sqlitepath":"/db"}
+{"sqlitepath":"/db"}

copyright.js

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+const COPYRIGHT = `/*
+ * Copyright (c) ${new Date().getFullYear()} by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+`;
+
+async function getAllFiles(dir = '.') {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  let files = [];
+  for (let entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      files = files.concat(await getAllFiles(fullPath));
+    } else if (fullPath.endsWith('.js') || fullPath.endsWith('.jsx')) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+/* eslint-disable no-console */
+async function addCopyright(files) {
+  const oldCopyrightRegex =
+    /^(\/\*\n \* Copyright \(c\) \d{4} by Christian Kellner\.\n \* Licensed under Apache-2.0 with Commons Clause and Attribution\/Naming Clause\n \*\/\n\n)+/;
+  for (let file of files) {
+    try {
+      let content = await fs.readFile(file, 'utf8');
+      const strippedContent = content.replace(oldCopyrightRegex, '');
+      const newContent = COPYRIGHT + strippedContent;
+      if (content !== newContent) {
+        await fs.writeFile(file, newContent);
+        console.log(`Added/Updated copyright in ${file}`);
+      }
+    } catch (err) {
+      console.error(`Error processing ${file}: ${err}`);
+    }
+  }
+}
+/* eslint-enable no-console */
+
+const filesToProcess = process.argv.length > 2 ? process.argv.slice(2) : await getAllFiles();
+await addCopyright(filesToProcess);

docker-compose.yml

@@ -1,22 +1,26 @@
 services:
   fredy:
     container_name: fredy
-    # build from empty build folder to reduce size of image
     build:
       context: .
       dockerfile: Dockerfile
     image: ghcr.io/orangecoding/fredy
-    # map existing config and database
+    environment:
+      - NODE_ENV=production
     volumes:
       - ./conf:/conf
       - ./db:/db
     ports:
       - "9998:9998"
     restart: unless-stopped
+    # Resource limits to prevent runaway memory usage from Chromium
+    deploy:
+      resources:
+        limits:
+          memory: 1G
     healthcheck:
-      # The container will immediately stop when health check fails after retries
-      test: ["CMD-SHELL", "curl --fail --silent --show-error --max-time 5 http://localhost:9998/ || exit 1"]
+      test: ["CMD", "curl", "--fail", "--silent", "--show-error", "--max-time", "5", "http://localhost:9998/"]
       interval: 120s
       timeout: 10s
-      retries: 1
-      start_period: 10s
+      retries: 3
+      start_period: 30s

docker-test.sh

@@ -7,12 +7,72 @@ if [ "$(docker ps -aq -f name=fredy)" ]; then
   docker rm fredy || true
 fi
 
+# On Apple Silicon, force linux/amd64 to match production CI and avoid arm64/x86_64
+# Chrome mismatch under Rosetta. On native Linux (amd64 or arm64) let Docker pick naturally. That took me fucking 1 hour to figure out.
+PLATFORM=""
+if [ "$(uname -m)" = "arm64" ] && [ "$(uname -s)" = "Darwin" ]; then
+  PLATFORM="linux/amd64"
+fi
+
 # Build image from local Dockerfile, forcing a fresh build without cache
-docker build --no-cache -t fredy:local .
+if [ -n "$PLATFORM" ]; then
+  docker build --no-cache --platform "$PLATFORM" -t fredy:local .
+else
+  docker build --no-cache -t fredy:local .
+fi
 
 # Run container with volumes and port mapping
-docker run -d --name fredy \
-  -v fredy_conf:/conf \
-  -v fredy_db:/db \
-  -p 9998:9998 \
-  fredy:local
+if [ -n "$PLATFORM" ]; then
+  docker run -d --name fredy --platform "$PLATFORM" -v fredy_conf:/conf -v fredy_db:/db -p 9998:9998 fredy:local
+else
+  docker run -d --name fredy -v fredy_conf:/conf -v fredy_db:/db -p 9998:9998 fredy:local
+fi
+
+echo "Waiting for app to be ready..."
+for i in $(seq 1 30); do
+  if docker exec fredy curl -sf http://localhost:9998/ > /dev/null 2>&1; then
+    echo "App is up"
+    break
+  fi
+  if [ "$i" = "30" ]; then
+    echo "App did not come up in time"
+    docker logs fredy
+    exit 1
+  fi
+  sleep 2
+done
+
+# Verify the DB is readable/writable via the API.
+# /api/demo is unauthenticated and reads the settings table - if SQLite is broken this returns an error.
+echo "Testing DB via API (/api/demo)..."
+DEMO_RESPONSE=$(docker exec fredy curl -sf http://localhost:9998/api/demo 2>&1)
+if echo "$DEMO_RESPONSE" | grep -q "demoMode"; then
+  echo "DB is readable (got demoMode from /api/demo)"
+else
+  echo "DB check failed - unexpected response from /api/demo: $DEMO_RESPONSE"
+  docker logs fredy
+  exit 1
+fi
+
+# Verify Chrome launches without crashing.
+# On amd64: Chrome for Testing lives in the puppeteer cache.
+# On arm64: system Chromium is used instead.
+echo "Testing Chrome..."
+CHROME=$(docker exec fredy find /root/.cache/puppeteer /home -name chrome -type f 2>/dev/null | head -1)
+if [ -z "$CHROME" ]; then
+  CHROME=$(docker exec fredy which chromium 2>/dev/null || true)
+fi
+if [ -z "$CHROME" ]; then
+  echo "Chrome/Chromium binary not found"
+  exit 1
+fi
+if docker exec fredy "$CHROME" --headless --no-sandbox --disable-gpu --dump-dom https://example.com 2>&1 | grep -q "<html"; then
+  echo "Chrome works"
+else
+  echo "Chrome failed to render a page"
+  docker exec fredy "$CHROME" --headless --no-sandbox --disable-gpu --dump-dom https://example.com 2>&1 | head -20
+  exit 1
+fi
+
+echo ""
+echo "All checks passed."

eslint.config.js

@@ -1,96 +1,48 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 // eslint.config.js
 import js from '@eslint/js';
 import prettier from 'eslint-config-prettier';
 import globals from 'globals';
 import react from 'eslint-plugin-react';
-import babelParser from '@babel/eslint-parser';
 
 export default [
   {
-    files: ['**/*.{js,jsx,ts,tsx}'],
     ignores: ['**/node_modules/**', '**/dist/**', '**/build/**', '**/public/**', 'db/**', 'conf/**'],
   },
-  js.configs.recommended,
-  prettier,
+
   {
+    files: ['**/*.{js,jsx}'],
     languageOptions: {
-      parser: babelParser,
+      ecmaVersion: 'latest',
       sourceType: 'module',
-      ecmaVersion: 2021,
+      parserOptions: {
+        ecmaFeatures: { jsx: true },
+      },
       globals: {
         ...globals.browser,
         ...globals.node,
-        ...globals.mocha,
+        ...globals.jest,
         Promise: 'readonly',
         fetch: 'readonly',
         describe: 'readonly',
         after: 'readonly',
         it: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        vi: 'readonly',
       },
-      parserOptions: { requireConfigFile: false },
     },
     plugins: { react },
-    rules: {
-      eqeqeq: [2, 'allow-null'],
-      strict: 0,
-      'no-redeclare': [2, { builtinGlobals: false }],
-      'class-methods-use-this': 'off',
-      indent: ['off', 2],
-      'linebreak-style': ['error', 'unix'],
-      quotes: ['error', 'single', { avoidEscape: true, allowTemplateLiterals: true }],
-      semi: ['error', 'always'],
-      'no-console': ['error', { allow: ['warn', 'error'] }],
-      'jsx-quotes': ['error', 'prefer-double'],
-      'react/display-name': 'off',
-      'react/forbid-prop-types': 'off',
-      'react/jsx-closing-bracket-location': 'off',
-      'react/jsx-curly-spacing': 'off',
-      'react/jsx-handler-names': ['off', { eventHandlerPrefix: 'handle', eventHandlerPropPrefix: 'on' }],
-      'react/jsx-indent-props': 'off',
-      'react/jsx-key': 'off',
-      'react/jsx-max-props-per-line': 'off',
-      'react/jsx-no-bind': ['error', { ignoreRefs: true, allowArrowFunctions: true, allowBind: false }],
-      'react/jsx-no-duplicate-props': ['error', { ignoreCase: true }],
-      'react/jsx-no-literals': 'off',
-      'react/jsx-no-undef': 'error',
-      'react/jsx-pascal-case': ['error', { allowAllCaps: true, ignore: [] }],
-      'react/sort-prop-types': ['off', { ignoreCase: true, callbacksLast: false, requiredFirst: false }],
-      'react/jsx-sort-prop-types': 'off',
-      'react/jsx-sort-props': 'off',
-      'react/jsx-uses-react': 'error',
-      'react/jsx-uses-vars': 'error',
-      'react/no-danger': 'warn',
-      'react/no-deprecated': 'error',
-      'react/no-did-mount-set-state': 'error',
-      'react/no-did-update-set-state': 'warn',
-      'react/no-direct-mutation-state': 'off',
-      'react/no-is-mounted': 'error',
-      'react/no-set-state': 'off',
-      'react/no-string-refs': 'warn',
-      'react/no-unknown-property': 'error',
-      'react/prop-types': ['error', { ignore: [], customValidators: [], skipUndeclared: true }],
-      'react/react-in-jsx-scope': 'error',
-      'react/require-extension': 'off',
-      'react/require-render-return': 'error',
-      'react/self-closing-comp': 'warn',
-      'react/sort-comp': 'off',
-      'react/jsx-wrap-multilines': ['warn', { declaration: true, assignment: true, return: true }],
-      'react/wrap-multilines': 'off',
-      'react/jsx-first-prop-new-line': 'off',
-      'react/jsx-equals-spacing': ['warn', 'never'],
-      'react/jsx-no-target-blank': 'error',
-      'react/jsx-filename-extension': ['error', { extensions: ['.jsx'] }],
-      'react/jsx-no-comment-textnodes': 'error',
-      'react/no-comment-textnodes': 'off',
-      'react/no-render-return-value': 'error',
-      'react/require-optimization': ['off', { allowDecorators: [] }],
-      'react/no-find-dom-node': 'warn',
-      'react/forbid-component-props': ['off', { forbid: [] }],
-      'react/no-danger-with-children': 'error',
-      'react/no-unused-prop-types': ['warn', { customValidators: [], skipShapeProps: true }],
-      'react/style-prop-object': 'error',
-      'react/no-children-prop': 'warn',
-    },
     settings: { react: { version: 'detect' } },
+    rules: {
+      ...js.configs.recommended.rules,
+      'no-console': ['error', { allow: ['warn', 'error'] }],
+    },
   },
+
+  prettier,
 ];

index.html

@@ -7,10 +7,15 @@
       content="user-scalable=no, width=device-width, initial-scale=1, maximum-scale=1"
     />
     <meta name="google" content="notranslate" />
-      <meta name="apple-mobile-web-app-capable" content="yes" />
+      <meta name="mobile-web-app-capable" content="yes">
       <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
 
       <title>Fredy || Real Estate Finder</title>
+    <link rel="icon" type="image/png" href="/ui/src/assets/heart.png" />
+    <link rel="apple-touch-icon" href="/ui/src/assets/heart.png" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
   </head>
   <body theme-mode="dark">
     <div id="fredy" style="position: absolute; top: 0; left: 0; right: 0; bottom: 0"></div>

index.js

@@ -1,39 +1,60 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import fs from 'fs';
-import path from 'path';
-import { checkIfConfigIsAccessible, config, getProviders, refreshConfig } from './lib/utils.js';
+import { checkIfConfigIsAccessible, getProviders, refreshConfig } from './lib/utils.js';
 import * as similarityCache from './lib/services/similarity-check/similarityCache.js';
-import * as jobStorage from './lib/services/storage/jobStorage.js';
-import FredyPipeline from './lib/FredyPipeline.js';
-import { duringWorkingHoursOrNotSet } from './lib/utils.js';
 import { runMigrations } from './lib/services/storage/migrations/migrate.js';
 import { ensureDemoUserExists, ensureAdminUserExists } from './lib/services/storage/userStorage.js';
-import { cleanupDemoAtMidnight } from './lib/services/crons/demoCleanup-cron.js';
 import { initTrackerCron } from './lib/services/crons/tracker-cron.js';
 import logger from './lib/services/logger.js';
-import { bus } from './lib/services/events/event-bus.js';
+import { reloadEnabledFromSettings } from './lib/services/debug/debugLogStorage.js';
 import { initActiveCheckerCron } from './lib/services/crons/listing-alive-cron.js';
+import { initGeocodingCron } from './lib/services/crons/geocoding-cron.js';
+import { getSettings } from './lib/services/storage/settingsStorage.js';
+import SqliteConnection, { computeDbPath } from './lib/services/storage/SqliteConnection.js';
+import { initJobExecutionService } from './lib/services/jobs/jobExecutionService.js';
+import { ensureValidBinary } from './lib/services/ensureValidBinary.js';
+
+// Ensure the CloakBrowser stealth Chromium binary is present and complete before
+// jobs run.  ensureValidBinary() also detects and auto-heals partial extractions
+// (e.g. a newer version that was downloaded but only the chrome executable was
+// written) so Chrome never crashes with "Invalid file descriptor to ICU data".
+logger.info('Checking CloakBrowser binary...');
+await ensureValidBinary();
+logger.info('CloakBrowser binary ready.');
+
+//in the config, we store the path of the sqlite file, thus we must check if it is available
+const isConfigAccessible = await checkIfConfigIsAccessible();
+await SqliteConnection.init();
 
 // Load configuration before any other startup steps
 await refreshConfig();
 
-const isConfigAccessible = await checkIfConfigIsAccessible();
-
 if (!isConfigAccessible) {
   logger.error('Configuration exists, but is not accessible. Please check the file permission');
   process.exit(1);
 }
 
-// Ensure sqlite directory exists before loading anything else (based on config.sqlitepath)
-const rawDir = config.sqlitepath || '/db';
-const relDir = rawDir.startsWith('/') ? rawDir.slice(1) : rawDir;
-const absDir = path.isAbsolute(relDir) ? relDir : path.join(process.cwd(), relDir);
-if (!fs.existsSync(absDir)) {
-  fs.mkdirSync(absDir, { recursive: true });
-}
-
 // Run DB migrations once at startup and block until finished
 await runMigrations();
 
+const settings = await getSettings();
+
+// Restore the persisted on/off flag for opt-in DB log capture so it survives a
+// Fredy restart. reloadEnabledFromSettings() also (un)wires the logger sink based
+// on the restored flag, so the logger hot path stays cost-free when nobody enabled
+// the feature.
+await reloadEnabledFromSettings();
+
+// Ensure the sqlite directory exists before loading anything else (based on config.sqlitepath)
+const { dir: sqliteDir } = await computeDbPath();
+if (!fs.existsSync(sqliteDir)) {
+  fs.mkdirSync(sqliteDir, { recursive: true });
+}
+
 // Load provider modules once at startup
 const providers = await getProviders();
 
@@ -41,58 +62,23 @@ similarityCache.initSimilarityCache();
 similarityCache.startSimilarityCacheReloader();
 
 //assuming interval is always in minutes
-const INTERVAL = config.interval * 60 * 1000;
+const INTERVAL = settings.interval * 60 * 1000;
 
 // Initialize API only after migrations completed
 await import('./lib/api/api.js');
 
-if (config.demoMode) {
+if (settings.demoMode) {
   logger.info('Running in demo mode');
-  cleanupDemoAtMidnight();
 }
 
-logger.info(`Started Fredy successfully. Ui can be accessed via http://localhost:${config.port}`);
-
 ensureAdminUserExists();
 ensureDemoUserExists();
 await initTrackerCron();
 //do not wait for this to finish, let it run in the background
 initActiveCheckerCron();
+initGeocodingCron();
 
-bus.on('jobs:runAll', () => {
-  logger.debug('Running Fredy Job manually');
-  execute();
-});
+logger.info(`Started Fredy successfully. Ui can be accessed via http://localhost:${settings.port}`);
 
-const execute = () => {
-  const isDuringWorkingHoursOrNotSet = duringWorkingHoursOrNotSet(config, Date.now());
-  if (!config.demoMode) {
-    if (isDuringWorkingHoursOrNotSet) {
-      config.lastRun = Date.now();
-      jobStorage
-        .getJobs()
-        .filter((job) => job.enabled)
-        .forEach((job) => {
-          job.provider
-            .filter((p) => providers.find((loaded) => loaded.metaInformation.id === p.id) != null)
-            .forEach(async (prov) => {
-              const matchedProvider = providers.find((loaded) => loaded.metaInformation.id === prov.id);
-              matchedProvider.init(prov, job.blacklist);
-              await new FredyPipeline(
-                matchedProvider.config,
-                job.notificationAdapter,
-                prov.id,
-                job.id,
-                similarityCache,
-              ).execute();
-            });
-        });
-    } else {
-      logger.debug('Working hours set. Skipping as outside of working hours.');
-    }
-  }
-};
-
-setInterval(execute, INTERVAL);
-//start once at startup
-execute();
+// Initialize the lean Job Execution Service (schedules and bus listeners)
+initJobExecutionService({ providers, settings, intervalMs: INTERVAL });

jsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ESNext",
+    "checkJs": true,
+    "allowJs": true,
+    "noEmit": true,
+    "strict": false
+  },
+  "exclude": ["node_modules", "ui"]
+}

lib/FredyPipeline.js

@@ -1,216 +0,0 @@
-import { NoNewListingsWarning } from './errors.js';
-import { storeListings, getKnownListingHashesForJobAndProvider } from './services/storage/listingsStorage.js';
-import * as notify from './notification/notify.js';
-import Extractor from './services/extractor/extractor.js';
-import urlModifier from './services/queryStringMutator.js';
-import logger from './services/logger.js';
-
-/**
- * @typedef {Object} Listing
- * @property {string} id Stable unique identifier (hash) of the listing.
- * @property {string} title Title or headline of the listing.
- * @property {string} [address] Optional address/location text.
- * @property {string} [price] Optional price text/value.
- * @property {string} [url] Link to the listing detail page.
- * @property {any} [meta] Provider-specific additional metadata.
- */
-
-/**
- * @typedef {Object} SimilarityCache
- * @property {(title:string, address?:string)=>boolean} hasSimilarEntries Returns true if a similar entry is known.
- * @property {(title:string, address?:string)=>void} addCacheEntry Adds a new entry to the similarity cache.
- */
-
-/**
- * Runtime orchestrator for fetching, normalizing, filtering, deduplicating, storing,
- * and notifying about new listings from a configured provider.
- *
- * The execution flow is:
- * 1) Prepare provider URL (sorting, etc.)
- * 2) Extract raw listings from the provider
- * 3) Normalize listings to the provider schema
- * 4) Filter out incomplete/blacklisted listings
- * 5) Identify new listings (vs. previously stored hashes)
- * 6) Persist new listings
- * 7) Filter out entries similar to already seen ones
- * 8) Dispatch notifications
- */
-class FredyPipeline {
-  /**
-   * Create a new runtime instance for a single provider/job execution.
-   *
-   * @param {Object} providerConfig Provider configuration.
-   * @param {string} providerConfig.url Base URL to crawl.
-   * @param {string} [providerConfig.sortByDateParam] Query parameter used to enforce sorting by date (provider-specific).
-   * @param {string} [providerConfig.waitForSelector] CSS selector to wait for before parsing content.
-   * @param {Object.<string, string>} providerConfig.crawlFields Mapping of field names to selectors/paths to extract.
-   * @param {string} providerConfig.crawlContainer CSS selector for the container holding listing items.
-   * @param {(raw:any)=>Listing} providerConfig.normalize Function to convert raw scraped data into a Listing shape.
-   * @param {(listing:Listing)=>boolean} providerConfig.filter Function to filter out unwanted listings.
-   * @param {(url:string, waitForSelector?:string)=>Promise<void>|Promise<Listing[]>} [providerConfig.getListings] Optional override to fetch listings.
-   *
-   * @param {Object} notificationConfig Notification configuration passed to notification adapters.
-   * @param {string} providerId The ID of the provider currently in use.
-   * @param {string} jobKey Key of the job that is currently running (from within the config).
-   * @param {SimilarityCache} similarityCache Cache instance for checking similar entries.
-   */
-  constructor(providerConfig, notificationConfig, providerId, jobKey, similarityCache) {
-    this._providerConfig = providerConfig;
-    this._notificationConfig = notificationConfig;
-    this._providerId = providerId;
-    this._jobKey = jobKey;
-    this._similarityCache = similarityCache;
-  }
-
-  /**
-   * Execute the end-to-end pipeline for a single provider run.
-   *
-   * @returns {Promise<Listing[]|void>} Resolves to the list of new (and similarity-filtered) listings
-   * after notifications have been sent; resolves to void when there are no new listings.
-   */
-  execute() {
-    return Promise.resolve(urlModifier(this._providerConfig.url, this._providerConfig.sortByDateParam))
-      .then(this._providerConfig.getListings?.bind(this) ?? this._getListings.bind(this))
-      .then(this._normalize.bind(this))
-      .then(this._filter.bind(this))
-      .then(this._findNew.bind(this))
-      .then(this._save.bind(this))
-      .then(this._filterBySimilarListings.bind(this))
-      .then(this._notify.bind(this))
-      .catch(this._handleError.bind(this));
-  }
-
-  /**
-   * Fetch listings from the provider, using the default Extractor flow unless
-   * a provider-specific getListings override is supplied.
-   *
-   * @param {string} url The provider URL to fetch from.
-   * @returns {Promise<Listing[]>} Resolves with an array of listings (empty when none found).
-   */
-  _getListings(url) {
-    const extractor = new Extractor();
-    return new Promise((resolve, reject) => {
-      extractor
-        .execute(url, this._providerConfig.waitForSelector)
-        .then(() => {
-          const listings = extractor.parseResponseText(
-            this._providerConfig.crawlContainer,
-            this._providerConfig.crawlFields,
-            url,
-          );
-          resolve(listings == null ? [] : listings);
-        })
-        .catch((err) => {
-          reject(err);
-          logger.error(err);
-        });
-    });
-  }
-
-  /**
-   * Normalize raw listings into the provider-specific Listing shape.
-   *
-   * @param {any[]} listings Raw listing entries from the extractor or override.
-   * @returns {Listing[]} Normalized listings.
-   */
-  _normalize(listings) {
-    return listings.map(this._providerConfig.normalize);
-  }
-
-  /**
-   * Filter out listings that are missing required fields and those rejected by the
-   * provider's blacklist/filter function.
-   *
-   * @param {Listing[]} listings Listings to filter.
-   * @returns {Listing[]} Filtered listings that pass validation and provider filter.
-   */
-  _filter(listings) {
-    const keys = Object.keys(this._providerConfig.crawlFields);
-    const filteredListings = listings.filter((item) => keys.every((key) => key in item));
-    return filteredListings.filter(this._providerConfig.filter);
-  }
-
-  /**
-   * Determine which listings are new by comparing their IDs against stored hashes.
-   *
-   * @param {Listing[]} listings Listings to evaluate for novelty.
-   * @returns {Listing[]} New listings not seen before.
-   * @throws {NoNewListingsWarning} When no new listings are found.
-   */
-  _findNew(listings) {
-    logger.debug(`Checking ${listings.length} listings for new entries (Provider: '${this._providerId}')`);
-    const hashes = getKnownListingHashesForJobAndProvider(this._jobKey, this._providerId) || [];
-
-    const newListings = listings.filter((o) => !hashes.includes(o.id));
-    if (newListings.length === 0) {
-      throw new NoNewListingsWarning();
-    }
-    return newListings;
-  }
-
-  /**
-   * Send notifications for new listings using the configured notification adapter(s).
-   *
-   * @param {Listing[]} newListings New listings to notify about.
-   * @returns {Promise<Listing[]>} Resolves to the provided listings after notifications complete.
-   * @throws {NoNewListingsWarning} When there are no listings to notify about.
-   */
-  _notify(newListings) {
-    if (newListings.length === 0) {
-      throw new NoNewListingsWarning();
-    }
-    const sendNotifications = notify.send(this._providerId, newListings, this._notificationConfig, this._jobKey);
-    return Promise.all(sendNotifications).then(() => newListings);
-  }
-
-  /**
-   * Persist new listings and pass them through.
-   *
-   * @param {Listing[]} newListings Listings to store.
-   * @returns {Listing[]} The same listings, unchanged.
-   */
-  _save(newListings) {
-    logger.debug(`Storing ${newListings.length} new listings (Provider: '${this._providerId}')`);
-    storeListings(this._jobKey, this._providerId, newListings);
-    return newListings;
-  }
-
-  /**
-   * Remove listings that are similar to already known entries according to the similarity cache.
-   * Adds the remaining listings to the cache.
-   *
-   * @param {Listing[]} listings Listings to filter by similarity.
-   * @returns {Listing[]} Listings considered unique enough to keep.
-   */
-  _filterBySimilarListings(listings) {
-    return listings.filter((listing) => {
-      const similar = this._similarityCache.checkAndAddEntry({
-        title: listing.title,
-        address: listing.address,
-        price: listing.price,
-      });
-      if (similar) {
-        logger.debug(
-          `Filtering similar entry for title '${listing.title}' and address '${listing.address}' (Provider: '${this._providerId}')`,
-        );
-      }
-      return !similar;
-    });
-  }
-
-  /**
-   * Handle errors occurring in the pipeline, logging levels depending on type.
-   *
-   * @param {Error} err Error instance thrown by previous steps.
-   * @returns {void}
-   */
-  _handleError(err) {
-    if (err.name === 'NoNewListingsWarning') {
-      logger.debug(`No new listings found (Provider: '${this._providerId}').`);
-    } else {
-      logger.error(err);
-    }
-  }
-}
-
-export default FredyPipeline;

lib/FredyPipelineExecutioner.js

@@ -0,0 +1,405 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import { NoNewListingsWarning } from './errors.js';
+import {
+  deleteListingsById,
+  getKnownListingHashesForJobAndProvider,
+  storeListings,
+  updateListingDistance,
+} from './services/storage/listingsStorage.js';
+import { getJob } from './services/storage/jobStorage.js';
+import * as notify from './notification/notify.js';
+import Extractor from './services/extractor/extractor.js';
+import urlModifier from './services/queryStringMutator.js';
+import logger from './services/logger.js';
+import { geocodeAddress } from './services/geocoding/geoCodingService.js';
+import { distanceMeters } from './services/listings/distanceCalculator.js';
+import { getSettings, getUserSettings } from './services/storage/settingsStorage.js';
+import booleanPointInPolygon from '@turf/boolean-point-in-polygon';
+import { formatListing } from './utils/formatListing.js';
+
+/** @import { ParsedListing } from './types/listing.js' */
+/** @import { Job } from './types/job.js' */
+/** @import { ProviderConfig } from './types/providerConfig.js' */
+/** @import { SpecFilter, SpatialFilter } from './types/filter.js' */
+/** @import { SimilarityCache } from './types/similarityCache.js' */
+/** @import { Browser } from './types/browser.js' */
+
+/**
+ * Runtime orchestrator for fetching, normalizing, filtering, deduplicating, storing,
+ * and notifying about new listings from a configured provider.
+ *
+ * The execution flow is:
+ * 1) Prepare provider URL (sorting, etc.)
+ * 2) Extract raw listings from the provider
+ * 3) Normalize listings to the provider schema
+ * 4) Filter out incomplete/blacklisted listings
+ * 5) Identify new listings (vs. previously stored hashes)
+ * 6) Persist new listings
+ * 7) Filter out entries similar to already seen ones
+ * 8) Filter out entries that do not match the job's specFilter
+ * 9) Filter out entries that do not match the job's spatialFilter
+ * 10) Dispatch notifications
+ */
+class FredyPipelineExecutioner {
+  /**
+   * Create a new runtime instance for a single provider/job execution.
+   *
+   * @param {ProviderConfig} providerConfig Provider configuration.
+   * @param {Job} job Job configuration.
+   * @param {string} providerId The ID of the provider currently in use.
+   * @param {SimilarityCache} similarityCache Cache instance for checking similar entries.
+   * @param {Browser} browser Puppeteer browser instance.
+   */
+  constructor(providerConfig, job, providerId, similarityCache, browser) {
+    /** @type {ProviderConfig} */
+    this._providerConfig = providerConfig;
+    /** @type {Object} */
+    this._jobNotificationConfig = job.notificationAdapter;
+    /** @type {string} */
+    this._jobKey = job.id;
+    /** @type {SpecFilter | null} */
+    this._jobSpecFilter = job.specFilter;
+    /** @type {SpatialFilter | null} */
+    this._jobSpatialFilter = job.spatialFilter;
+    /** @type {string} */
+    this._providerId = providerId;
+    /** @type {SimilarityCache} */
+    this._similarityCache = similarityCache;
+    /** @type {Browser} */
+    this._browser = browser;
+  }
+
+  /**
+   * Execute the end-to-end pipeline for a single provider run.
+   *
+   * @returns {Promise<ParsedListing[]|void>} Resolves to the list of new (and similarity-filtered) listings
+   * after notifications have been sent; resolves to void when there are no new listings.
+   */
+  execute() {
+    return Promise.resolve(urlModifier(this._providerConfig.url, this._providerConfig.sortByDateParam))
+      .then(this._providerConfig.getListings?.bind(this) ?? this._getListings.bind(this))
+      .then(this._normalize.bind(this))
+      .then(this._filter.bind(this))
+      .then(this._findNew.bind(this))
+      .then(this._fetchDetails.bind(this))
+      .then(this._geocode.bind(this))
+      .then(this._save.bind(this))
+      .then(this._calculateDistance.bind(this))
+      .then(this._filterBySimilarListings.bind(this))
+      .then(this._filterBySpecs.bind(this))
+      .then(this._filterByArea.bind(this))
+      .then(this._notify.bind(this))
+      .catch(this._handleError.bind(this));
+  }
+
+  /**
+   * Optionally, enrich new listings with data from their detail pages.
+   * Only called when the provider config defines a `fetchDetails` function.
+   * Fetches are performed sequentially to avoid overloading the provider or
+   * the shared browser instance.
+   *
+   * @param {Listing[]} newListings New listings to enrich.
+   * @returns {Promise<Listing[]>} Resolves with enriched listings.
+   */
+  async _fetchDetails(newListings) {
+    if (typeof this._providerConfig.fetchDetails !== 'function') {
+      return newListings;
+    }
+    const userId = getJob(this._jobKey)?.userId;
+    const enabledProviders = getUserSettings(userId)?.provider_details ?? [];
+    if (!userId || !Array.isArray(enabledProviders) || !enabledProviders.includes(this._providerId)) {
+      return newListings;
+    }
+    const listingsToEnrich = process.env.NODE_ENV === 'test' ? newListings.slice(0, 1) : newListings;
+    const enriched = [];
+    for (const listing of listingsToEnrich) {
+      enriched.push(await this._providerConfig.fetchDetails(listing, this._browser));
+    }
+    return enriched;
+  }
+
+  /**
+   * Geocode new listings.
+   *
+   * @param {ParsedListing[]} newListings New listings to geocode.
+   * @returns {Promise<ParsedListing[]>} Resolves with the listings (potentially with added coordinates).
+   */
+  async _geocode(newListings) {
+    for (const listing of newListings) {
+      if (listing.address) {
+        const coords = await geocodeAddress(listing.address);
+        if (coords && coords.lat !== -1 && coords.lng !== -1) {
+          listing.latitude = coords.lat;
+          listing.longitude = coords.lng;
+        }
+      }
+    }
+    return newListings;
+  }
+
+  /**
+   * Filter listings by area using the provider's area filter if available.
+   * Only filters if areaFilter is set on the provider AND the listing has coordinates.
+   *
+   * @param {ParsedListing[]} newListings New listings to filter by area.
+   * @returns {ParsedListing[]} Resolves with listings that are within the area (or not filtered if no area is set).
+   */
+  _filterByArea(newListings) {
+    const polygonFeatures = this._jobSpatialFilter?.features?.filter((f) => f.geometry?.type === 'Polygon');
+
+    // If no area filter is set, return all listings
+    if (!polygonFeatures?.length) {
+      return newListings;
+    }
+
+    const toDeleteListingByIds = [];
+    // Filter listings by area - keep only those within the polygon
+    const keptListings = newListings.filter((listing) => {
+      // If listing doesn't have coordinates, keep it (don't filter out)
+      if (listing.latitude == null || listing.longitude == null) {
+        return true;
+      }
+
+      // Check if the point is inside the polygons
+      const point = [listing.longitude, listing.latitude]; // GeoJSON format: [lon, lat]
+      const isInPolygon = polygonFeatures.some((feature) => booleanPointInPolygon(point, feature));
+
+      if (!isInPolygon) {
+        toDeleteListingByIds.push(listing.id);
+      }
+
+      return isInPolygon;
+    });
+
+    if (toDeleteListingByIds.length > 0) {
+      deleteListingsById(toDeleteListingByIds);
+    }
+
+    return keptListings;
+  }
+
+  /**
+   * Filter listings based on its specifications (minRooms, minSize, maxPrice).
+   *
+   * @param {ParsedListing[]} newListings New listings to filter.
+   * @returns {ParsedListing[]} Resolves with listings that pass the specification filters.
+   */
+  _filterBySpecs(newListings) {
+    const { minRooms, minSize, maxPrice } = this._jobSpecFilter || {};
+
+    // If no specs are set, return all listings
+    if (!minRooms && !minSize && !maxPrice) {
+      return newListings;
+    }
+
+    const toDeleteListingByIds = [];
+    const keptListings = newListings.filter((listing) => {
+      const filterOut =
+        (minRooms && listing.rooms != null && listing.rooms < minRooms) ||
+        (minSize && listing.size != null && listing.size < minSize) ||
+        (maxPrice && listing.price != null && listing.price > maxPrice);
+
+      if (filterOut) {
+        toDeleteListingByIds.push(listing.id);
+      }
+      return !filterOut;
+    });
+
+    if (toDeleteListingByIds.length > 0) {
+      deleteListingsById(toDeleteListingByIds);
+    }
+
+    return keptListings;
+  }
+
+  /**
+   * Fetch listings from the provider, using the default Extractor flow unless
+   * a provider-specific getListings override is supplied.
+   *
+   * @param {string} url The provider URL to fetch from.
+   * @returns {Promise<ParsedListing[]>} Resolves with an array of listings (empty when none found).
+   */
+  async _getListings(url) {
+    const extractor = new Extractor({ ...this._providerConfig.puppeteerOptions, browser: this._browser });
+    await extractor.execute(url, this._providerConfig.waitForSelector, this._providerId);
+    const listings = extractor.parseResponseText(
+      this._providerConfig.crawlContainer,
+      this._providerConfig.crawlFields,
+      url,
+    );
+    return listings == null ? [] : listings;
+  }
+
+  /**
+   * Normalize raw listings into the provider-specific ParsedListing shape.
+   *
+   * @param {any[]} listings Raw listing entries from the extractor or override.
+   * @returns {ParsedListing[]} Normalized listings.
+   */
+  _normalize(listings) {
+    return listings.map((listing) => this._providerConfig.normalize(listing));
+  }
+
+  /**
+   * Filter out listings that are missing required fields and those rejected by the
+   * provider's blacklist/filter function.
+   *
+   * @param {ParsedListing[]} listings Listings to filter.
+   * @returns {ParsedListing[]} Filtered listings that pass validation and provider filter.
+   */
+  _filter(listings) {
+    const requiredKeys = this._providerConfig.requiredFieldNames;
+    const requireValues = ['id', 'link', 'title'];
+
+    return (
+      listings
+        // this should never filter some listings out, because the normalize function should always extract all fields.
+        .filter((item) => requiredKeys.every((key) => key in item))
+        // TODO: move blacklist filter to this file, so it will handle for all providers in same way.
+        .filter(this._providerConfig.filter)
+        // filter out listings that are missing required fields
+        .filter((item) => requireValues.every((key) => item[key] != null))
+    );
+  }
+
+  /**
+   * Determine which listings are new by comparing their IDs against stored hashes.
+   *
+   * @param {ParsedListing[]} listings Listings to evaluate for novelty.
+   * @returns {ParsedListing[]} New listings not seen before.
+   * @throws {NoNewListingsWarning} When no new listings are found.
+   */
+  _findNew(listings) {
+    logger.debug(`Checking ${listings.length} listings for new entries (Provider: '${this._providerId}')`);
+    const hashes = getKnownListingHashesForJobAndProvider(this._jobKey, this._providerId) || [];
+
+    const newListings = listings.filter((o) => !hashes.includes(o.id));
+    if (newListings.length === 0) {
+      throw new NoNewListingsWarning();
+    }
+    return newListings;
+  }
+
+  /**
+   * Send notifications for new listings using the configured notification adapter(s).
+   *
+   * @param {ParsedListing[]} newListings New listings to notify about.
+   * @returns {Promise<ParsedListing[]>} Resolves to the provided listings after notifications complete.
+   * @throws {NoNewListingsWarning} When there are no listings to notify about.
+   */
+  async _notify(newListings) {
+    if (newListings.length === 0) {
+      throw new NoNewListingsWarning();
+    }
+    const formattedListings = newListings.map(formatListing);
+    const settings = await getSettings();
+    const baseUrl = settings?.baseUrl ?? '';
+    const sendNotifications = notify.send(
+      this._providerId,
+      formattedListings,
+      this._jobNotificationConfig,
+      this._jobKey,
+      baseUrl,
+    );
+    return Promise.all(sendNotifications).then(() => newListings);
+  }
+
+  /**
+   * Persist new listings and pass them through.
+   *
+   * @param {ParsedListing[]} newListings Listings to store.
+   * @returns {ParsedListing[]} The same listings, unchanged.
+   */
+  _save(newListings) {
+    logger.debug(`Storing ${newListings.length} new listings (Provider: '${this._providerId}')`);
+    storeListings(this._jobKey, this._providerId, newListings);
+    return newListings;
+  }
+
+  /**
+   * Calculate distance for new listings.
+   *
+   * @param {ParsedListing[]} listings
+   * @returns {ParsedListing[]}
+   * @private
+   */
+  _calculateDistance(listings) {
+    if (listings.length === 0) return [];
+
+    const job = getJob(this._jobKey);
+    const userId = job?.userId;
+
+    if (userId == null || typeof userId !== 'string') {
+      logger.debug('Skipping distance calculation: userId is missing or invalid');
+      return listings;
+    }
+
+    const userSettings = getUserSettings(userId);
+    const homeAddress = userSettings?.home_address;
+
+    if (!homeAddress || !homeAddress.coords) {
+      return listings;
+    }
+
+    const { lat, lng } = homeAddress.coords;
+    for (const listing of listings) {
+      if (listing.latitude != null && listing.longitude != null) {
+        const dist = distanceMeters(lat, lng, listing.latitude, listing.longitude);
+        updateListingDistance(listing.id, dist);
+        listing.distance_to_destination = dist;
+      }
+    }
+    return listings;
+  }
+
+  /**
+   * Remove listings that are similar to already known entries according to the similarity cache.
+   * Adds the remaining listings to the cache.
+   *
+   * @param {ParsedListing[]} listings Listings to filter by similarity.
+   * @returns {ParsedListing[]} Listings considered unique enough to keep.
+   */
+  _filterBySimilarListings(listings) {
+    const filteredIds = [];
+    const keptListings = listings.filter((listing) => {
+      const similar = this._similarityCache.checkAndAddEntry({
+        title: listing.title,
+        address: listing.address,
+        price: listing.price,
+      });
+      if (similar) {
+        logger.debug(
+          `Filtering similar entry for title '${listing.title}' and address '${listing.address}' (Provider: '${this._providerId}')`,
+        );
+        filteredIds.push(listing.id);
+      }
+      return !similar;
+    });
+
+    if (filteredIds.length > 0) {
+      deleteListingsById(filteredIds);
+    }
+
+    return keptListings;
+  }
+
+  /**
+   * Handle errors occurring in the pipeline, logging levels depending on type.
+   *
+   * @param {Error} err Error instance thrown by previous steps.
+   * @returns {void}
+   */
+  _handleError(err) {
+    if (err.name === 'NoNewListingsWarning') {
+      logger.debug(`No new listings found (Provider: '${this._providerId}').`);
+    } else {
+      logger.error(err);
+    }
+  }
+}
+
+export default FredyPipelineExecutioner;

lib/TRACKING_POIS.js

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+export const TRACKING_POIS = {
+  DISTANCE_ADDRESS_ENTERED: 'DISTANCE_ADDRESS_ENTERED',
+  WELCOME_FINISHED: 'WELCOME_FINISHED',
+  WELCOME_SKIPPED: 'WELCOME_SKIPPED',
+  JOBS_TABLE_VIEW: 'JOBS_TABLE_VIEW',
+  LISTING_TABLE_VIEW: 'LISTING_TABLE_VIEW',
+  BASE_URL_SETTING: 'BASE_URL_SETTING',
+  SET_PROXY_SETTING: 'SET_PROXY_SETTING',
+  DETECTED_AS_BOT: 'DETECTED_AS_BOT',
+  NOTES_CREATE: 'NOTES_CREATE',
+  USING_LISTING_STATUS: 'USING_LISTING_STATUS',
+  CHANGE_LANGUAGE: 'CHANGE_LANGUAGE',
+};

lib/api/api.js

@@ -1,47 +1,114 @@
-import { notificationAdapterRouter } from './routes/notificationAdapterRouter.js';
-import { authInterceptor, cookieSession, adminInterceptor } from './security.js';
-import { generalSettingsRouter } from './routes/generalSettingsRoute.js';
-import { analyticsRouter } from './routes/analyticsRouter.js';
-import { providerRouter } from './routes/providerRouter.js';
-import { versionRouter } from './routes/versionRouter.js';
-import { loginRouter } from './routes/loginRoute.js';
-import { userRouter } from './routes/userRoute.js';
-import { jobRouter } from './routes/jobRouter.js';
-import { config } from '../utils.js';
-import bodyParser from 'body-parser';
-import restana from 'restana';
-import files from 'serve-static';
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import Fastify from 'fastify';
+import fastifyHelmet from '@fastify/helmet';
+import fastifyCookie from '@fastify/cookie';
+import fastifySession from '@fastify/session';
+import fastifyStatic from '@fastify/static';
 import path from 'path';
 import { getDirName } from '../utils.js';
-import { demoRouter } from './routes/demoRouter.js';
+import { getSettings, getOrCreateSessionSecret } from '../services/storage/settingsStorage.js';
 import logger from '../services/logger.js';
-import { listingsRouter } from './routes/listingsRouter.js';
-const service = restana();
-const staticService = files(path.join(getDirName(), '../ui/public'));
-const PORT = config.port || 9998;
+import { authHook, adminHook } from './security.js';
 
-service.use(bodyParser.json());
-service.use(cookieSession());
-service.use(staticService);
-service.use('/api/admin', authInterceptor());
-service.use('/api/jobs', authInterceptor());
-service.use('/api/version', authInterceptor());
-service.use('/api/listings', authInterceptor());
+import loginPlugin from './routes/loginRoute.js';
+import demoPlugin from './routes/demoRouter.js';
+import jobPlugin from './routes/jobRouter.js';
+import versionPlugin from './routes/versionRouter.js';
+import listingsPlugin from './routes/listingsRouter.js';
+import dashboardPlugin from './routes/dashboardRouter.js';
+import userSettingsPlugin from './routes/userSettingsRoute.js';
+import trackingPlugin from './routes/trackingRoute.js';
+import generalSettingsPlugin from './routes/generalSettingsRoute.js';
+import backupPlugin from './routes/backupRouter.js';
+import debugPlugin, { registerDebugPublicProbe } from './routes/debugRouter.js';
+import userPlugin from './routes/userRoute.js';
+import notificationAdapterPlugin from './routes/notificationAdapterRouter.js';
+import providerPlugin from './routes/providerRouter.js';
+import { registerMcpRoutes } from '../mcp/mcpHttpRoute.js';
 
-// /admin can only be accessed when user is having admin permissions
-service.use('/api/admin', adminInterceptor());
-service.use('/api/jobs/notificationAdapter', notificationAdapterRouter);
-service.use('/api/admin/generalSettings', generalSettingsRouter);
-service.use('/api/jobs/provider', providerRouter);
-service.use('/api/jobs/insights', analyticsRouter);
-service.use('/api/admin/users', userRouter);
-service.use('/api/version', versionRouter);
-service.use('/api/jobs', jobRouter);
-service.use('/api/login', loginRouter);
-service.use('/api/listings', listingsRouter);
-//this route is unsecured intentionally as it is being queried from the login page
-service.use('/api/demo', demoRouter);
+const PORT = (await getSettings()).port || 9998;
+const sessionSecret = await getOrCreateSessionSecret();
+const SESSION_MAX_AGE = 2 * 60 * 60 * 1000;
 
-service.start(PORT).then(() => {
-  logger.debug(`Started API service on port ${PORT}`);
+const fastify = Fastify({
+  logger: false,
+  bodyLimit: 50 * 1024 * 1024, // 50 MB for backup uploads
 });
+
+// Security headers (CSP disabled to avoid breaking the SPA)
+await fastify.register(fastifyHelmet, { contentSecurityPolicy: false });
+
+// Cookie + session (in-memory store, signed cookie)
+await fastify.register(fastifyCookie);
+await fastify.register(fastifySession, {
+  secret: sessionSecret,
+  cookieName: 'fredy-admin-session',
+  cookie: {
+    maxAge: SESSION_MAX_AGE,
+    httpOnly: true,
+    secure: false,
+    sameSite: 'lax',
+  },
+  saveUninitialized: false,
+});
+
+// Serve the React SPA from ui/public/
+await fastify.register(fastifyStatic, {
+  root: path.join(getDirName(), '../ui/public'),
+  wildcard: false,
+});
+
+// Public routes - no auth required
+fastify.register(loginPlugin, { prefix: '/api/login' });
+fastify.register(demoPlugin, { prefix: '/api/demo' });
+
+// User-authenticated routes
+fastify.register(async (app) => {
+  app.addHook('preHandler', authHook);
+  app.register(jobPlugin, { prefix: '/api/jobs' });
+  app.register(notificationAdapterPlugin, { prefix: '/api/jobs/notificationAdapter' });
+  app.register(providerPlugin, { prefix: '/api/jobs/provider' });
+  app.register(versionPlugin, { prefix: '/api/version' });
+  app.register(listingsPlugin, { prefix: '/api/listings' });
+  app.register(dashboardPlugin, { prefix: '/api/dashboard' });
+  app.register(userSettingsPlugin, { prefix: '/api/user/settings' });
+  app.register(trackingPlugin, { prefix: '/api/tracking' });
+  app.register(generalSettingsPlugin, { prefix: '/api/admin/generalSettings' });
+  // The lightweight /api/debug/active probe used by the app-wide red banner. Lives
+  // here (under authHook, NOT adminHook) so non-admin users also see the warning
+  // banner when an admin has enabled the feature, without exposing the rest of the
+  // settings payload.
+  app.register(
+    async (sub) => {
+      registerDebugPublicProbe(sub);
+    },
+    { prefix: '/api/debug' },
+  );
+});
+
+// Admin-only routes
+fastify.register(async (app) => {
+  app.addHook('preHandler', authHook);
+  app.addHook('preHandler', adminHook);
+  app.register(backupPlugin, { prefix: '/api/admin/backup' });
+  app.register(debugPlugin, { prefix: '/api/admin/debug' });
+  app.register(userPlugin, { prefix: '/api/admin/users' });
+});
+
+// MCP Streamable HTTP (Bearer token auth - no session)
+registerMcpRoutes(fastify);
+
+// SPA fallback - serve index.html for all non-API GET requests
+fastify.setNotFoundHandler((request, reply) => {
+  if (!request.url.startsWith('/api/')) {
+    return reply.sendFile('index.html');
+  }
+  return reply.code(404).send({ error: 'Not found' });
+});
+
+await fastify.listen({ port: PORT, host: '0.0.0.0' });
+logger.debug(`Started API service on port ${PORT}`);

lib/api/routes/analyticsRouter.js

@@ -1,10 +0,0 @@
-import restana from 'restana';
-import * as listingStorage from '../../services/storage/listingsStorage.js';
-const service = restana();
-const analyticsRouter = service.newRouter();
-analyticsRouter.get('/:jobId', async (req, res) => {
-  const { jobId } = req.params;
-  res.body = listingStorage.getListingProviderDataForAnalytics(jobId) || {};
-  res.send();
-});
-export { analyticsRouter };

lib/api/routes/backupRouter.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import {
+  buildBackupFileName,
+  createBackupZip,
+  precheckRestore,
+  restoreFromZip,
+} from '../../services/storage/backupRestoreService.js';
+import { getSettings } from '../../services/storage/settingsStorage.js';
+import { isAdmin } from '../security.js';
+
+const DEMO_MODE_ERROR = 'Backup and restore are not available in demo mode.';
+
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function backupPlugin(fastify) {
+  // Parse raw binary uploads as Buffer
+  fastify.addContentTypeParser(
+    ['application/zip', 'application/octet-stream'],
+    { parseAs: 'buffer' },
+    (req, body, done) => done(null, body),
+  );
+
+  fastify.get('/', async (request, reply) => {
+    const settings = await getSettings();
+    if (settings.demoMode && !isAdmin(request)) {
+      return reply.code(403).send({ error: DEMO_MODE_ERROR });
+    }
+    const zipBuffer = await createBackupZip();
+    const fileName = await buildBackupFileName();
+    reply.header('Content-Type', 'application/zip');
+    reply.header('Content-Disposition', `attachment; filename="${fileName}"`);
+    return reply.send(zipBuffer);
+  });
+
+  fastify.post('/restore', async (request, reply) => {
+    const settings = await getSettings();
+    if (settings.demoMode && !isAdmin(request)) {
+      return reply.code(403).send({ error: DEMO_MODE_ERROR });
+    }
+    const { dryRun = 'false', force = 'false' } = request.query || {};
+    const doDryRun = String(dryRun) === 'true';
+    const doForce = String(force) === 'true';
+    const body = request.body; // Buffer from addContentTypeParser
+
+    if (doDryRun) {
+      return precheckRestore(body);
+    }
+
+    try {
+      return restoreFromZip(body, { force: doForce });
+    } catch (e) {
+      return reply.code(400).send({
+        message: e?.message || 'Restore failed',
+        details: e?.payload || null,
+      });
+    }
+  });
+}

lib/api/routes/dashboardRouter.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import * as jobStorage from '../../services/storage/jobStorage.js';
+import { getListingsKpisForJobIds, getProviderDistributionForJobIds } from '../../services/storage/listingsStorage.js';
+import { getSettings } from '../../services/storage/settingsStorage.js';
+import { isAdmin } from '../security.js';
+
+function getAccessibleJobs(request) {
+  const currentUser = request.session.currentUser;
+  const admin = isAdmin(request);
+  return jobStorage
+    .getJobs()
+    .filter((job) => admin || job.userId === currentUser || job.shared_with_user.includes(currentUser));
+}
+
+function cap(val) {
+  return String(val).charAt(0).toUpperCase() + String(val).slice(1);
+}
+
+/**
+ * Compute the most recent job trigger timestamp across the given jobs.
+ *
+ * Returns `null` when none of the jobs has ever been triggered. The value is
+ * persisted per-job via `jobs.last_run_at`, so the dashboard reflects the
+ * scope visible to the current user (own + shared, or all for admins) rather
+ * than a process-wide in-memory value.
+ *
+ * @param {Array<{lastRunAt?: number|null}>} jobs
+ * @returns {number|null}
+ */
+function computeLastRun(jobs) {
+  let lastRun = null;
+  for (const job of jobs) {
+    const ts = job.lastRunAt;
+    if (typeof ts === 'number' && (lastRun == null || ts > lastRun)) {
+      lastRun = ts;
+    }
+  }
+  return lastRun;
+}
+
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function dashboardPlugin(fastify) {
+  fastify.get('/', async (request) => {
+    const jobs = getAccessibleJobs(request);
+    const settings = await getSettings();
+
+    const totalJobs = jobs.length;
+    const totalListings = jobs.reduce((sum, j) => sum + (j.numberOfFoundListings || 0), 0);
+    const jobIds = jobs.map((j) => j.id);
+    const { numberOfActiveListings, medianPriceOfListings } = getListingsKpisForJobIds(jobIds);
+
+    const providerPieRaw = getProviderDistributionForJobIds(jobIds);
+    const providerPie = Array.isArray(providerPieRaw)
+      ? {
+          labels: providerPieRaw.map((p) => cap(p.type)),
+          values: providerPieRaw.map((p) => Number(p.value) || 0),
+        }
+      : providerPieRaw && typeof providerPieRaw === 'object'
+        ? {
+            labels: Array.isArray(providerPieRaw.labels) ? providerPieRaw.labels : [],
+            values: Array.isArray(providerPieRaw.values) ? providerPieRaw.values : [],
+          }
+        : { labels: [], values: [] };
+
+    const lastRun = computeLastRun(jobs);
+
+    return {
+      general: {
+        interval: settings.interval,
+        lastRun,
+        nextRun: lastRun == null ? 0 : lastRun + settings.interval * 60000,
+      },
+      kpis: {
+        totalJobs,
+        totalListings,
+        numberOfActiveListings,
+        medianPriceOfListings,
+      },
+      pie: providerPie,
+    };
+  });
+}

lib/api/routes/debugRouter.js

@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import {
+  isEnabled,
+  enableDebugLogging,
+  disableDebugLogging,
+  getCurrentSize,
+  getMaxSize,
+  hasAnyLogs,
+  wasEverEnabled,
+  clearAllDebugLogs,
+} from '../../services/debug/debugLogStorage.js';
+import { buildDebugBundleFileName, buildDebugBundleZip } from '../../services/debug/debugBundleService.js';
+import { getSettings } from '../../services/storage/settingsStorage.js';
+
+/**
+ * Build the JSON status payload returned by /status and after each enable/disable.
+ * @returns {Promise<{enabled:boolean, size:number, max:number, hasLogs:boolean, everEnabled:boolean}>}
+ */
+async function buildStatus() {
+  return {
+    enabled: isEnabled(),
+    size: await getCurrentSize(),
+    max: getMaxSize(),
+    hasLogs: hasAnyLogs(),
+    everEnabled: await wasEverEnabled(),
+  };
+}
+
+/**
+ * Register the lightweight /active probe used by the app-wide red banner. Exposed
+ * to every authenticated user (not just admins) so non-admin users see the warning
+ * banner too. Returns only a single boolean so it cannot be repurposed to leak any
+ * other state.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export async function registerDebugPublicProbe(fastify) {
+  fastify.get('/active', async () => ({ enabled: isEnabled() }));
+}
+
+/**
+ * Admin-only debug logging endpoints.
+ *
+ * Routes (all relative to the registered prefix /api/admin/debug):
+ *   GET    /status          → current feature status (used by the UI polling).
+ *   POST   /enable          → turn debug logging on. Body: { clearPrevious?:boolean }.
+ *   POST   /disable         → turn debug logging off (existing logs are kept on disk).
+ *   GET    /download        → ZIP with logs.txt + sys.txt. 409 when the feature has
+ *                              never been enabled OR there are no logs to export.
+ *   DELETE /logs            → drop every stored debug log row (does NOT change the
+ *                              enabled flag — useful to free space while keeping
+ *                              recording on).
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function debugPlugin(fastify) {
+  fastify.get('/status', async () => buildStatus());
+
+  fastify.post('/enable', async (request) => {
+    const clearPrevious = request.body?.clearPrevious === true;
+    await enableDebugLogging({ clearPrevious });
+    return buildStatus();
+  });
+
+  fastify.post('/disable', async () => {
+    await disableDebugLogging();
+    return buildStatus();
+  });
+
+  fastify.delete('/logs', async () => {
+    clearAllDebugLogs();
+    return buildStatus();
+  });
+
+  fastify.get('/download', async (request, reply) => {
+    const ever = await wasEverEnabled();
+    if (!ever || !hasAnyLogs()) {
+      return reply.code(409).send({
+        error: 'Debug logging has never produced any data on this Fredy installation.',
+      });
+    }
+    const settings = await getSettings();
+    const zipBuffer = await buildDebugBundleZip({ settings });
+    const fileName = await buildDebugBundleFileName();
+    reply.header('Content-Type', 'application/zip');
+    reply.header('Content-Disposition', `attachment; filename="${fileName}"`);
+    return reply.send(zipBuffer);
+  });
+}

lib/api/routes/demoRouter.js

@@ -1,11 +1,16 @@
-import restana from 'restana';
-import { config } from '../../utils.js';
-const service = restana();
-const demoRouter = service.newRouter();
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
 
-demoRouter.get('/', async (req, res) => {
-  res.body = Object.assign({}, { demoMode: config.demoMode });
-  res.send();
-});
+import { getSettings } from '../../services/storage/settingsStorage.js';
 
-export { demoRouter };
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function demoPlugin(fastify) {
+  fastify.get('/', async () => {
+    const settings = await getSettings();
+    return { demoMode: settings.demoMode };
+  });
+}

lib/api/routes/generalSettingsRoute.js

@@ -1,30 +1,56 @@
-import restana from 'restana';
-import { config, getDirName, readConfigFromStorage, refreshConfig } from '../../utils.js';
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import { getDirName } from '../../utils.js';
 import fs from 'fs';
 import { ensureDemoUserExists } from '../../services/storage/userStorage.js';
 import logger from '../../services/logger.js';
-const service = restana();
-const generalSettingsRouter = service.newRouter();
-generalSettingsRouter.get('/', async (req, res) => {
-  res.body = Object.assign({}, config);
-  res.send();
-});
-generalSettingsRouter.post('/', async (req, res) => {
-  const settings = req.body;
-  try {
-    if (config.demoMode) {
-      res.send(new Error('In demo mode, it is not allowed to change these settings.'));
-      return;
+import { getSettings, upsertSettings } from '../../services/storage/settingsStorage.js';
+import { isAdmin } from '../security.js';
+import { trackPoi } from '../../services/tracking/Tracker.js';
+import { TRACKING_POIS } from '../../TRACKING_POIS.js';
+
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function generalSettingsPlugin(fastify) {
+  fastify.get('/', async () => {
+    return Object.assign({}, await getSettings());
+  });
+
+  fastify.post('/', async (request, reply) => {
+    const { sqlitepath, ...appSettings } = request.body || {};
+    if (typeof appSettings.baseUrl === 'string') {
+      appSettings.baseUrl = appSettings.baseUrl.trim().replace(/\/$/, '');
     }
-    const currentConfig = await readConfigFromStorage();
-    fs.writeFileSync(`${getDirName()}/../conf/config.json`, JSON.stringify({ ...currentConfig, ...settings }));
-    await refreshConfig();
-    ensureDemoUserExists();
-  } catch (err) {
-    logger.error(err);
-    res.send(new Error('Error while trying to write settings.'));
-    return;
-  }
-  res.send();
-});
-export { generalSettingsRouter };
+    const localSettings = await getSettings();
+
+    if (!isAdmin(request)) {
+      const reason = localSettings.demoMode
+        ? 'In demo mode, it is not allowed to change these settings.'
+        : 'Only admins can change these settings.';
+      return reply.code(403).send({ error: reason });
+    }
+
+    try {
+      if (typeof sqlitepath !== 'undefined') {
+        fs.writeFileSync(`${getDirName()}/../conf/config.json`, JSON.stringify({ sqlitepath }));
+      }
+
+      upsertSettings(appSettings);
+      ensureDemoUserExists();
+      if (appSettings.baseUrl != null) {
+        await trackPoi(TRACKING_POIS.BASE_URL_SETTING);
+      }
+      if (appSettings.proxyUrl != null) {
+        await trackPoi(TRACKING_POIS.SET_PROXY_SETTING);
+      }
+    } catch (err) {
+      logger.error(err);
+      return reply.code(500).send({ error: 'Error while trying to write settings.' });
+    }
+    return reply.send();
+  });
+}

lib/api/routes/jobRouter.js

@@ -1,132 +1,251 @@
-import restana from 'restana';
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import * as jobStorage from '../../services/storage/jobStorage.js';
 import * as userStorage from '../../services/storage/userStorage.js';
-import { config } from '../../utils.js';
 import { isAdmin } from '../security.js';
 import logger from '../../services/logger.js';
 import { bus } from '../../services/events/event-bus.js';
+import { isRunning as isJobRunning } from '../../services/jobs/run-state.js';
+import { addClient as addSseClient, removeClient } from '../../services/sse/sse-broker.js';
+import { getSettings } from '../../services/storage/settingsStorage.js';
 
-const service = restana();
-const jobRouter = service.newRouter();
+const DEMO_JOB_NAME = 'Demo-Job';
 
-function doesJobBelongsToUser(job, req) {
-  const userId = req.session.currentUser;
-  if (userId == null) {
-    return false;
-  }
+function doesJobBelongsToUser(job, request) {
+  const userId = request.session.currentUser;
+  if (userId == null) return false;
   const user = userStorage.getUser(userId);
-  if (user == null) {
-    return false;
-  }
+  if (user == null) return false;
   return user.isAdmin || job.userId === user.id;
 }
 
-jobRouter.get('/', async (req, res) => {
-  const isUserAdmin = isAdmin(req);
-  //show only the jobs which belongs to the user (or all of the user is an admin)
-  res.body = jobStorage
-    .getJobs()
-    .filter(
-      (job) =>
-        isUserAdmin || job.userId === req.session.currentUser || job.shared_with_user.includes(req.session.currentUser),
-    )
-    .map((job) => {
-      return {
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function jobPlugin(fastify) {
+  fastify.get('/', async (request) => {
+    const isUserAdmin = isAdmin(request);
+    return jobStorage
+      .getJobs()
+      .filter(
+        (job) =>
+          isUserAdmin ||
+          job.userId === request.session.currentUser ||
+          job.shared_with_user.includes(request.session.currentUser),
+      )
+      .map((job) => ({
         ...job,
+        running: isJobRunning(job.id),
         isOnlyShared:
           !isUserAdmin &&
-          job.userId !== req.session.currentUser &&
-          job.shared_with_user.includes(req.session.currentUser),
-      };
+          job.userId !== request.session.currentUser &&
+          job.shared_with_user.includes(request.session.currentUser),
+      }));
+  });
+
+  fastify.get('/data', async (request) => {
+    const {
+      page,
+      pageSize = 50,
+      activityFilter,
+      sortfield = null,
+      sortdir = 'asc',
+      freeTextFilter,
+    } = request.query || {};
+
+    const toBool = (v) => {
+      if (v === true || v === 'true' || v === 1 || v === '1') return true;
+      if (v === false || v === 'false' || v === 0 || v === '0') return false;
+      return null;
+    };
+    const normalizedActivity = toBool(activityFilter);
+
+    const queryResult = jobStorage.queryJobs({
+      page: page ? parseInt(page, 10) : 1,
+      pageSize: pageSize ? parseInt(pageSize, 10) : 50,
+      freeTextFilter: freeTextFilter || null,
+      activityFilter: normalizedActivity,
+      sortField: sortfield || null,
+      sortDir: sortdir === 'desc' ? 'desc' : 'asc',
+      userId: request.session.currentUser,
+      isAdmin: isAdmin(request),
     });
 
-  res.send();
-});
+    const isUserAdmin = isAdmin(request);
+    queryResult.result = queryResult.result.map((job) => ({
+      ...job,
+      running: isJobRunning(job.id),
+      isOnlyShared:
+        !isUserAdmin &&
+        job.userId !== request.session.currentUser &&
+        job.shared_with_user.includes(request.session.currentUser),
+    }));
 
-jobRouter.get('/processingTimes', async (req, res) => {
-  res.body = {
-    interval: config.interval,
-    lastRun: config.lastRun || null,
-  };
-  res.send();
-});
+    return queryResult;
+  });
 
-jobRouter.post('/startAll', async (req, res) => {
-  bus.emit('jobs:runAll');
-  res.send();
-});
-
-jobRouter.post('/', async (req, res) => {
-  const { provider, notificationAdapter, name, blacklist = [], jobId, enabled, shareWithUsers = [] } = req.body;
-  try {
-    let jobFromDb = jobStorage.getJob(jobId);
-
-    if (jobFromDb && !doesJobBelongsToUser(jobFromDb, req)) {
-      res.send(new Error('You are trying to change a job that is not associated to your user.'));
-      return;
+  // Server-Sent Events for real-time job status updates
+  fastify.get('/events', async (request, reply) => {
+    const userId = request.session?.currentUser;
+    if (userId == null) {
+      return reply.code(401).send({ message: 'Unauthorized' });
     }
 
-    jobStorage.upsertJob({
-      userId: req.session.currentUser,
-      jobId,
-      enabled,
-      name,
-      blacklist,
+    reply.hijack();
+    const raw = reply.raw;
+    raw.setHeader('Content-Type', 'text/event-stream');
+    raw.setHeader('Cache-Control', 'no-cache');
+    raw.setHeader('Connection', 'keep-alive');
+
+    try {
+      raw.write(': connected\n\n');
+      addSseClient(userId, raw);
+      const onClose = () => removeClient(userId, raw);
+      request.raw.on('close', onClose);
+    } catch (e) {
+      logger.error('Error establishing SSE connection', e);
+      try {
+        raw.end();
+      } catch {
+        /* noop */
+      }
+    }
+  });
+
+  fastify.post('/startAll', async (request, reply) => {
+    try {
+      const userId = request.session.currentUser;
+      bus.emit('jobs:runAll', { userId });
+      return reply.code(202).send({ message: 'Run all accepted' });
+    } catch (err) {
+      logger.error('Failed to trigger startAll', err);
+      return reply.code(500).send({ message: 'Unexpected error' });
+    }
+  });
+
+  fastify.post('/:jobId/run', async (request, reply) => {
+    const { jobId } = request.params;
+    try {
+      const job = jobStorage.getJob(jobId);
+      if (!job) {
+        return reply.code(404).send({ message: 'Job not found' });
+      }
+      if (!doesJobBelongsToUser(job, request)) {
+        return reply.code(403).send({ message: 'You are trying to run a job that is not associated to your user' });
+      }
+      if (isJobRunning(jobId)) {
+        return reply.code(409).send({ message: 'Job is already running' });
+      }
+      bus.emit('jobs:runOne', { jobId });
+      return reply.code(202).send({ message: 'Job run accepted' });
+    } catch (error) {
+      logger.error(error);
+      return reply.code(500).send({ message: 'Unexpected error triggering job' });
+    }
+  });
+
+  fastify.post('/', async (request, reply) => {
+    const {
       provider,
       notificationAdapter,
-      shareWithUsers,
-    });
-  } catch (error) {
-    res.send(new Error(error));
-    logger.error(error);
-  }
-  res.send();
-});
+      name,
+      blacklist = [],
+      jobId,
+      enabled,
+      shareWithUsers = [],
+      spatialFilter = null,
+      specFilter = null,
+    } = request.body;
+    const settings = await getSettings();
+    try {
+      const jobFromDb = jobStorage.getJob(jobId);
 
-jobRouter.delete('', async (req, res) => {
-  const { jobId } = req.body;
-  try {
-    const job = jobStorage.getJob(jobId);
-    if (!doesJobBelongsToUser(job, req)) {
-      res.send(new Error('You are trying to remove a job that is not associated to your user'));
-    } else {
-      jobStorage.removeJob(jobId);
-    }
-  } catch (error) {
-    res.send(new Error(error));
-    logger.error(error);
-  }
-  res.send();
-});
-jobRouter.put('/:jobId/status', async (req, res) => {
-  const { status } = req.body;
-  const { jobId } = req.params;
-  try {
-    const job = jobStorage.getJob(jobId);
-    if (!doesJobBelongsToUser(job, req)) {
-      res.send(new Error('You are trying change a job that is not associated to your user'));
-    } else {
-      jobStorage.setJobStatus({
+      if (jobFromDb && !doesJobBelongsToUser(jobFromDb, request)) {
+        return reply.code(403).send({ error: 'You are trying to change a job that is not associated to your user.' });
+      }
+
+      if (settings.demoMode && !isAdmin(request) && jobFromDb && jobFromDb.name === DEMO_JOB_NAME) {
+        return reply.code(403).send({ error: 'Sorry, but you cannot change the Status of our Demo Job ;)' });
+      }
+
+      jobStorage.upsertJob({
+        userId: request.session.currentUser,
         jobId,
-        status,
+        enabled,
+        name,
+        blacklist,
+        provider,
+        notificationAdapter,
+        shareWithUsers,
+        spatialFilter,
+        specFilter,
       });
+    } catch (error) {
+      logger.error(error);
+      return reply.code(500).send({ error: error.message });
     }
-  } catch (error) {
-    res.send(new Error(error));
-    logger.error(error);
-  }
-  res.send();
-});
+    return reply.send();
+  });
 
-jobRouter.get('/shareableUserList', async (req, res) => {
-  const currentUser = req.session.currentUser;
-  const users = userStorage.getUsers(false);
-  res.body = users
-    .filter((user) => !user.isAdmin && user.id !== currentUser)
-    .map((user) => ({
-      id: user.id,
-      name: user.username,
-    }));
-  res.send();
-});
-export { jobRouter };
+  fastify.delete('/', async (request, reply) => {
+    const { jobId } = request.body;
+    const settings = await getSettings();
+    try {
+      const job = jobStorage.getJob(jobId);
+      if (!job) {
+        return reply.code(404).send({ error: 'Job not found' });
+      }
+      if (settings.demoMode && !isAdmin(request) && job.name === DEMO_JOB_NAME) {
+        return reply.code(403).send({ error: 'Sorry, but you cannot remove the Demo Job ;)' });
+      }
+
+      if (!doesJobBelongsToUser(job, request)) {
+        return reply.code(403).send({ error: 'You are trying to remove a job that is not associated to your user' });
+      }
+      jobStorage.removeJob(jobId);
+    } catch (error) {
+      logger.error(error);
+      return reply.code(500).send({ error: error.message });
+    }
+    return reply.send();
+  });
+
+  fastify.put('/:jobId/status', async (request, reply) => {
+    const { status } = request.body;
+    const { jobId } = request.params;
+    const settings = await getSettings();
+    try {
+      const job = jobStorage.getJob(jobId);
+      if (!job) {
+        return reply.code(404).send({ error: 'Job not found' });
+      }
+
+      if (settings.demoMode && !isAdmin(request) && job.name === DEMO_JOB_NAME) {
+        return reply.code(403).send({ error: 'Sorry, but you cannot change the Status of our Demo Job ;)' });
+      }
+
+      if (!doesJobBelongsToUser(job, request)) {
+        return reply.code(403).send({ error: 'You are trying change a job that is not associated to your user' });
+      }
+      jobStorage.setJobStatus({ jobId, status });
+    } catch (error) {
+      logger.error(error);
+      return reply.code(500).send({ error: error.message });
+    }
+    return reply.send();
+  });
+
+  fastify.get('/shareableUserList', async (request) => {
+    const currentUser = request.session.currentUser;
+    const users = userStorage.getUsers(false);
+    return users
+      .filter((user) => !user.isAdmin && user.id !== currentUser)
+      .map((user) => ({
+        id: user.id,
+        name: user.username,
+      }));
+  });
+}

lib/api/routes/listingsRouter.js

@@ -1,100 +1,195 @@
-import restana from 'restana';
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import * as listingStorage from '../../services/storage/listingsStorage.js';
 import * as watchListStorage from '../../services/storage/watchListStorage.js';
 import { isAdmin as isAdminFn } from '../security.js';
 import logger from '../../services/logger.js';
 import { nullOrEmpty } from '../../utils.js';
-import { getJobs } from '../../services/storage/jobStorage.js';
+import { getJob } from '../../services/storage/jobStorage.js';
+import { getSettings } from '../../services/storage/settingsStorage.js';
+import { trackPoi } from '../../services/tracking/Tracker.js';
+import { TRACKING_POIS } from '../../TRACKING_POIS.js';
 
-const service = restana();
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function listingsPlugin(fastify) {
+  fastify.get('/table', async (request) => {
+    const {
+      page,
+      pageSize = 50,
+      activityFilter,
+      jobNameFilter,
+      providerFilter,
+      watchListFilter,
+      statusFilter,
+      sortfield = null,
+      sortdir = 'asc',
+      freeTextFilter,
+    } = request.query || {};
 
-const listingsRouter = service.newRouter();
+    const toBool = (v) => {
+      if (v === true || v === 'true' || v === 1 || v === '1') return true;
+      if (v === false || v === 'false' || v === 0 || v === '0') return false;
+      return null;
+    };
+    const normalizedActivity = toBool(activityFilter);
+    const normalizedWatch = toBool(watchListFilter);
+    const allowedStatuses = ['applied', 'rejected', 'accepted', 'none'];
+    const normalizedStatus =
+      typeof statusFilter === 'string' && allowedStatuses.includes(statusFilter.toLowerCase())
+        ? statusFilter.toLowerCase()
+        : undefined;
 
-listingsRouter.get('/table', async (req, res) => {
-  const {
-    page,
-    pageSize = 50,
-    activityFilter,
-    jobNameFilter,
-    providerFilter,
-    watchListFilter,
-    sortfield = null,
-    sortdir = 'asc',
-    freeTextFilter,
-  } = req.query || {};
+    let jobFilter = null;
+    let jobIdFilter = null;
+    if (!nullOrEmpty(jobNameFilter)) {
+      const job = getJob(jobNameFilter);
+      jobFilter = job != null ? job.name : null;
+      jobIdFilter = job != null ? job.id : null;
+    }
 
-  // normalize booleans (accept true, 'true', 1, '1')
-  const toBool = (v) => v === true || v === 'true' || v === 1 || v === '1';
-  const normalizedActivity = toBool(activityFilter) ? true : null;
-  const normalizedWatch = toBool(watchListFilter) ? true : null;
-
-  let jobFilter = null;
-  let jobIdFilter = null;
-  const jobs = getJobs();
-  if (!nullOrEmpty(jobNameFilter)) {
-    const job = jobs.find((j) => j.id === jobNameFilter);
-    jobFilter = job != null ? job.name : null;
-    jobIdFilter = job != null ? job.id : null;
-  }
-
-  res.body = listingStorage.queryListings({
-    page: page ? parseInt(page, 10) : 1,
-    pageSize: pageSize ? parseInt(pageSize, 10) : 50,
-    freeTextFilter: freeTextFilter || null,
-    activityFilter: normalizedActivity,
-    jobNameFilter: jobFilter,
-    jobIdFilter: jobIdFilter,
-    providerFilter,
-    watchListFilter: normalizedWatch,
-    sortField: sortfield || null,
-    sortDir: sortdir === 'desc' ? 'desc' : 'asc',
-    userId: req.session.currentUser,
-    isAdmin: isAdminFn(req),
+    return listingStorage.queryListings({
+      page: page ? parseInt(page, 10) : 1,
+      pageSize: pageSize ? parseInt(pageSize, 10) : 50,
+      freeTextFilter: freeTextFilter || null,
+      activityFilter: normalizedActivity,
+      jobNameFilter: jobFilter,
+      jobIdFilter: jobIdFilter,
+      providerFilter,
+      watchListFilter: normalizedWatch,
+      statusFilter: normalizedStatus,
+      sortField: sortfield || null,
+      sortDir: sortdir === 'desc' ? 'desc' : 'asc',
+      userId: request.session.currentUser,
+      isAdmin: isAdminFn(request),
+    });
   });
-  res.send();
-});
 
-// Toggle watch state for the current user on a listing
-listingsRouter.post('/watch', async (req, res) => {
-  try {
-    const { listingId } = req.body || {};
-    const userId = req.session?.currentUser;
+  fastify.get('/map', async (request) => {
+    const { jobId } = request.query || {};
+    return listingStorage.getListingsForMap({
+      jobId: nullOrEmpty(jobId) ? null : jobId,
+      userId: request.session.currentUser,
+      isAdmin: isAdminFn(request),
+    });
+  });
+
+  fastify.get('/:listingId', async (request, reply) => {
+    const { listingId } = request.params;
+    const listing = listingStorage.getListingById(listingId, request.session.currentUser, isAdminFn(request));
+    if (!listing) {
+      return reply.code(404).send({ message: 'Listing not found' });
+    }
+    return listing;
+  });
+
+  fastify.post('/watch', async (request, reply) => {
+    try {
+      const { listingId } = request.body || {};
+      const userId = request.session?.currentUser;
+      if (!listingId || !userId) {
+        return reply.code(400).send({ message: 'listingId or user not provided' });
+      }
+      watchListStorage.toggleWatch(listingId, userId);
+    } catch (error) {
+      logger.error(error);
+      return reply.code(500).send({ message: 'Failed to toggle watch' });
+    }
+    return reply.send();
+  });
+
+  fastify.post('/:listingId/notes', async (request, reply) => {
+    const { listingId } = request.params || {};
+    const { notes } = request.body || {};
+    const userId = request.session?.currentUser;
     if (!listingId || !userId) {
-      res.statusCode = 400;
-      res.body = { message: 'listingId or user not provided' };
-      return res.send();
+      return reply.code(400).send({ message: 'listingId or user not provided' });
     }
-    watchListStorage.toggleWatch(listingId, userId);
-  } catch (error) {
-    logger.error(error);
-    res.statusCode = 500;
-    res.body = { message: 'Failed to toggle watch' };
-  }
-  res.send();
-});
-
-listingsRouter.delete('/job', async (req, res) => {
-  const { jobId } = req.body;
-  try {
-    listingStorage.deleteListingsByJobId(jobId);
-  } catch (error) {
-    res.send(new Error(error));
-    logger.error(error);
-  }
-  res.send();
-});
-
-listingsRouter.delete('/', async (req, res) => {
-  const { ids } = req.body;
-  try {
-    if (Array.isArray(ids) && ids.length > 0) {
-      listingStorage.deleteListingsById(ids);
+    try {
+      const changes = listingStorage.setListingNotes(listingId, typeof notes === 'string' ? notes : null);
+      if (changes === 0) {
+        return reply.code(404).send({ message: 'Listing not found' });
+      }
+    } catch (error) {
+      logger.error(error);
+      return reply.code(500).send({ message: 'Failed to update listing notes' });
     }
-  } catch (error) {
-    res.send(new Error(error));
-    logger.error(error);
-  }
-  res.send();
-});
 
-export { listingsRouter };
+    await trackPoi(TRACKING_POIS.NOTES_CREATE);
+    return reply.send();
+  });
+
+  fastify.post('/:listingId/status', async (request, reply) => {
+    const { listingId } = request.params || {};
+    const { status } = request.body || {};
+    const userId = request.session?.currentUser;
+    if (!listingId || !userId) {
+      return reply.code(400).send({ message: 'listingId or user not provided' });
+    }
+    const allowed = ['applied', 'rejected', 'accepted'];
+    const normalized = status == null ? null : String(status).toLowerCase();
+    if (normalized != null && !allowed.includes(normalized)) {
+      return reply.code(400).send({ message: `Invalid status: ${status}` });
+    }
+    try {
+      const changes = listingStorage.setListingStatus(listingId, normalized);
+      await trackPoi(TRACKING_POIS.USING_LISTING_STATUS);
+      if (changes === 0) {
+        return reply.code(404).send({ message: 'Listing not found' });
+      }
+      if (normalized != null) {
+        watchListStorage.ensureWatch(listingId, userId);
+      }
+    } catch (error) {
+      logger.error(error);
+      return reply.code(500).send({ message: 'Failed to update listing status' });
+    }
+    return reply.send();
+  });
+
+  fastify.delete('/job', async (request, reply) => {
+    const { jobId, hardDelete = false } = request.body;
+    const settings = await getSettings();
+    try {
+      if (settings.demoMode && !isAdminFn(request)) {
+        return reply.code(403).send({ error: 'Sorry, but you cannot remove listings in demo mode ;)' });
+      }
+      const job = getJob(jobId);
+      if (!job) {
+        return reply.code(404).send({ error: 'Job not found' });
+      }
+      const userId = request.session.currentUser;
+      if (!isAdminFn(request) && job.userId !== userId && !job.shared_with_user.includes(userId)) {
+        return reply
+          .code(403)
+          .send({ error: 'You are trying to remove listings for a job that is not associated to your user' });
+      }
+      listingStorage.deleteListingsByJobId(jobId, hardDelete);
+    } catch (error) {
+      logger.error(error);
+      return reply.code(500).send({ error: error.message });
+    }
+    return reply.send();
+  });
+
+  fastify.delete('/', async (request, reply) => {
+    const { ids, hardDelete = false } = request.body;
+    const settings = await getSettings();
+    try {
+      if (settings.demoMode && !isAdminFn(request)) {
+        return reply.code(403).send({ error: 'Sorry, but you cannot remove listings in demo mode ;)' });
+      }
+      if (Array.isArray(ids) && ids.length > 0) {
+        listingStorage.deleteListingsById(ids, hardDelete);
+      }
+    } catch (error) {
+      logger.error(error);
+      return reply.code(500).send({ error: error.message });
+    }
+    return reply.send();
+  });
+}

lib/api/routes/loginRoute.js

@@ -1,47 +1,82 @@
-import restana from 'restana';
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import * as userStorage from '../../services/storage/userStorage.js';
 import * as hasher from '../../services/security/hash.js';
-import { config } from '../../utils.js';
 import { trackDemoAccessed } from '../../services/tracking/Tracker.js';
 import logger from '../../services/logger.js';
-const service = restana();
-const loginRouter = service.newRouter();
-loginRouter.get('/user', async (req, res) => {
-  const currentUserId = req.session.currentUser;
-  const currentUser = currentUserId == null ? null : userStorage.getUser(currentUserId);
-  if (currentUser == null) {
-    res.body = {};
-  } else {
-    res.body = {
+import { getSettings } from '../../services/storage/settingsStorage.js';
+
+const MAX_LOGIN_ATTEMPTS = 10;
+const LOGIN_WINDOW_MS = 15 * 60 * 1000;
+const loginAttempts = new Map();
+
+function getClientIp(request) {
+  const forwarded = request.headers['x-forwarded-for'];
+  return (forwarded ? forwarded.split(',')[0] : request.socket?.remoteAddress) || 'unknown';
+}
+
+function isRateLimited(ip) {
+  const now = Date.now();
+  for (const [key, rec] of loginAttempts) {
+    if (now - rec.firstAttempt > LOGIN_WINDOW_MS) loginAttempts.delete(key);
+  }
+  const record = loginAttempts.get(ip);
+  if (!record || now - record.firstAttempt > LOGIN_WINDOW_MS) {
+    loginAttempts.set(ip, { count: 1, firstAttempt: now });
+    return false;
+  }
+  record.count++;
+  return record.count > MAX_LOGIN_ATTEMPTS;
+}
+
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function loginPlugin(fastify) {
+  fastify.get('/user', async (request) => {
+    const currentUserId = request.session?.currentUser;
+    const currentUser = currentUserId == null ? null : userStorage.getUser(currentUserId);
+    if (currentUser == null) {
+      return {};
+    }
+    return {
       userId: currentUser.id,
       isAdmin: currentUser.isAdmin,
     };
-  }
-  res.send();
-});
-loginRouter.post('/', async (req, res) => {
-  const { username, password } = req.body;
-  const user = userStorage.getUsers(true).find((user) => user.username === username);
-  if (user == null) {
-    res.send(401);
-    return;
-  }
-  if (user.password === hasher.hash(password)) {
-    if (config.demoMode) {
-      await trackDemoAccessed();
-    }
+  });
 
-    req.session.currentUser = user.id;
-    userStorage.setLastLoginToNow({ userId: user.id });
-    res.send(200);
-    return;
-  } else {
-    logger.error(`User ${username} tried to login, but password was wrong.`);
-  }
-  res.send(401);
-});
-loginRouter.post('/logout', async (req, res) => {
-  req.session = null;
-  res.send(200);
-});
-export { loginRouter };
+  fastify.post('/', async (request, reply) => {
+    const ip = getClientIp(request);
+    if (isRateLimited(ip)) {
+      logger.error(`Login rate limit exceeded for IP ${ip}`);
+      return reply.code(429).send();
+    }
+    const settings = await getSettings();
+    const { username, password } = request.body;
+    const user = userStorage.getUsers(true).find((u) => u.username === username);
+    if (user == null) {
+      return reply.code(401).send();
+    }
+    if (user.password === hasher.hash(password)) {
+      if (settings.demoMode) {
+        await trackDemoAccessed();
+      }
+      request.session.currentUser = user.id;
+      request.session.createdAt = Date.now();
+      loginAttempts.delete(ip);
+      userStorage.setLastLoginToNow({ userId: user.id });
+      return reply.code(200).send();
+    } else {
+      logger.error(`User ${username} tried to login, but password was wrong.`);
+    }
+    return reply.code(401).send();
+  });
+
+  fastify.post('/logout', async (request, reply) => {
+    await request.session.destroy();
+    return reply.code(200).send();
+  });
+}

lib/api/routes/notificationAdapterRouter.js

@@ -1,51 +1,112 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import fs from 'fs';
-import restana from 'restana';
-const service = restana();
-const notificationAdapterRouter = service.newRouter();
+import logger from '../../services/logger.js';
+
 const notificationAdapterList = fs.readdirSync('./lib//notification/adapter').filter((file) => file.endsWith('.js'));
 const notificationAdapter = await Promise.all(
   notificationAdapterList.map(async (pro) => {
     return await import(`../../notification/adapter/${pro}`);
   }),
 );
-notificationAdapterRouter.post('/try', async (req, res) => {
-  const { id, fields } = req.body;
-  const adapter = notificationAdapter.find((adapter) => adapter.config.id === id);
-  if (adapter == null) {
-    res.send(404);
-  }
-  const notificationConfig = [];
-  const notificationObject = {};
-  Object.keys(fields).forEach((key) => {
-    notificationObject[key] = fields[key].value;
+
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function notificationAdapterPlugin(fastify) {
+  fastify.get('/', async () => {
+    return notificationAdapter.map((adapter) => adapter.config).filter(Boolean);
   });
-  notificationConfig.push({
-    fields: { ...notificationObject },
-    enabled: true,
-    id,
-  });
-  try {
-    await adapter.send({
-      serviceName: 'TestCall',
-      newListings: [
-        {
-          price: '42 €',
-          title: 'This is a test listing',
-          address: 'some address',
-          size: '666 2m',
-          link: 'https://www.orange-coding.net',
-        },
-      ],
-      notificationConfig,
-      jobKey: 'TestJob',
+
+  fastify.post('/try', async (request, reply) => {
+    const { id, fields } = request.body;
+    const adapter = notificationAdapter.find((adapter) => adapter.config.id === id);
+    if (adapter == null) {
+      return reply.code(404).send();
+    }
+    const notificationConfig = [];
+    const notificationObject = {};
+    Object.keys(fields).forEach((key) => {
+      notificationObject[key] = fields[key].value;
     });
-    res.send();
-  } catch (Exception) {
-    res.send(new Error(Exception));
-  }
-});
-notificationAdapterRouter.get('/', async (req, res) => {
-  res.body = notificationAdapter.map((adapter) => adapter.config);
-  res.send();
-});
-export { notificationAdapterRouter };
+    notificationConfig.push({
+      fields: { ...notificationObject },
+      enabled: true,
+      id,
+    });
+    try {
+      await adapter.send({
+        serviceName: 'TestCall',
+        newListings: [
+          {
+            address: 'Heidestrasse 17, 51147 Köln',
+            description: exampleDescription,
+            id: '1',
+            imageUrl: 'https://placehold.co/600x400/png',
+            price: '1.000 €',
+            size: '76 m²',
+            title: 'Stilvolle gepflegte 3-Raum-Wohnung mit gehobener Innenausstattung',
+            url: 'https://www.orange-coding.net',
+          },
+        ],
+        notificationConfig,
+        jobKey: 'TestJob',
+      });
+      return reply.send();
+    } catch (Exception) {
+      logger.error('Error during notification adapter test:', Exception);
+      return reply.code(500).send({ error: String(Exception) });
+    }
+  });
+}
+
+const exampleDescription = `
+Wohnungstyp: Etagenwohnung
+Nutzfläche: 76 m²
+Etage: 2 von 3
+Schlafzimmer: 1
+Badezimmer: 1
+Bezugsfrei ab: 1.4.2026
+Haustiere: Nein
+Garage/Stellplatz: Tiefgarage
+Anzahl Garage/Stellplatz: 1
+Kaltmiete (zzgl. Nebenkosten): 1.000 €
+Preis/m²: 13,16 €/m²
+Nebenkosten: 230 €
+Heizkosten in Nebenkosten enthalten: Ja
+Gesamtmiete: 1.230 €
+Kaution: 3.000,00
+Preis pro Parkfläche: 60 €
+Baujahr: 2000
+Objektzustand: Modernisiert
+Qualität der Ausstattung: Gehoben
+Heizungsart: Fernwärme
+Energieausweistyp: Verbrauchsausweis
+Energieausweis: liegt vor
+Endenergieverbrauch: 72 kWh/(m²∙a)
+Baujahr laut Energieausweis: 2000
+
+Diese moderne 3-Zimmer-Wohnung liegt direkt neben einem Park und nur wenige Minuten von der S-Bahn-Haltestelle entfernt. Das Stadtzentrum sowie Freizeiteinrichtungen sind 1,5 km entfernt.
+
+Die Wohnung ist ideal für Paare oder kleine Familien geeignet.
+
+Ausstattung:
+- neuer hochwertiger Bodenbelag (Holzoptik) in allen Räumen außer Bad/Küche
+- sonniger Balkon (Süd)
+- Tiefgaragenstellplatz
+- Kellerabteil
+- gepflegtes Mehrfamilienhaus
+
+Die Küche ist vom Mieter nach eigenen Wünschen einzurichten.
+
+Vermietung direkt vom Eigentümer - provisionsfrei!
+
+Lage:
+• Park: 1 Minute zu Fuß
+• S-Bahn Station: 2 Minuten zu Fuß
+• Supermärkte, Restaurants, täglicher Bedarf in der Nähe
+• Gute Anbindung Richtung Großstadt und Flughafen
+`;

lib/api/routes/providerRouter.js

@@ -1,15 +1,18 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import fs from 'fs';
-import restana from 'restana';
-const service = restana();
-const providerRouter = service.newRouter();
+
 const providerList = fs.readdirSync('./lib/provider').filter((file) => file.endsWith('.js'));
-const provider = await Promise.all(
-  providerList.map(async (pro) => {
-    return await import(`../../provider/${pro}`);
-  }),
-);
-providerRouter.get('/', async (req, res) => {
-  res.body = provider.map((p) => p.metaInformation);
-  res.send();
-});
-export { providerRouter };
+const providers = await Promise.all(providerList.map(async (pro) => import(`../../provider/${pro}`)));
+
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function providerPlugin(fastify) {
+  fastify.get('/', async () => {
+    return providers.map((p) => p.metaInformation);
+  });
+}

lib/api/routes/trackingRoute.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import { trackPoi } from '../../services/tracking/Tracker.js';
+import { TRACKING_POIS } from '../../TRACKING_POIS.js';
+import logger from '../../services/logger.js';
+
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function trackingPlugin(fastify) {
+  fastify.get('/trackingPois', async () => {
+    return TRACKING_POIS;
+  });
+
+  fastify.post('/poi', async (request, reply) => {
+    const { poi } = request.body;
+    if (!poi) {
+      return reply.code(400).send({ error: 'Feature name is required' });
+    }
+    try {
+      await trackPoi(poi);
+      return { success: true };
+    } catch (error) {
+      logger.error('Error tracking feature', error);
+      return reply.code(500).send({ error: error.message });
+    }
+  });
+}

lib/api/routes/userRoute.js

@@ -1,76 +1,75 @@
-import restana from 'restana';
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import * as userStorage from '../../services/storage/userStorage.js';
 import * as jobStorage from '../../services/storage/jobStorage.js';
-import { config } from '../../utils.js';
-const service = restana();
-const userRouter = service.newRouter();
+import { getSettings } from '../../services/storage/settingsStorage.js';
+import { isAdmin as isAdminUser } from '../security.js';
+
 function checkIfAnyAdminAfterRemovingUser(userIdToBeRemoved, allUser) {
   return allUser.filter((user) => user.id !== userIdToBeRemoved && user.isAdmin).length > 0;
 }
-function checkIfUserToBeRemovedIsLoggedIn(userIdToBeRemoved, req) {
-  return req.session.currentUser === userIdToBeRemoved;
+
+function checkIfUserToBeRemovedIsLoggedIn(userIdToBeRemoved, request) {
+  return request.session.currentUser === userIdToBeRemoved;
 }
+
 const nullOrEmpty = (str) => str == null || str.length === 0;
 
-userRouter.get('/', async (req, res) => {
-  res.body = userStorage.getUsers(false);
-  res.send();
-});
-
-userRouter.get('/:userId', async (req, res) => {
-  const { userId } = req.params;
-  res.body = userStorage.getUser(userId);
-  res.send();
-});
-userRouter.delete('/', async (req, res) => {
-  if (config.demoMode) {
-    res.send(new Error('In demo mode, it is not allowed to remove user.'));
-    return;
-  }
-
-  const { userId } = req.body;
-  const allUser = userStorage.getUsers(false);
-  if (!checkIfAnyAdminAfterRemovingUser(userId, allUser)) {
-    res.send(new Error('You are trying to remove the last admin user. This is prohibited.'));
-    return;
-  }
-  if (checkIfUserToBeRemovedIsLoggedIn(userId, req)) {
-    res.send(new Error('You are trying to remove yourself. This is prohibited.'));
-    return;
-  }
-  //TODO: Remove also analytics
-  jobStorage.removeJobsByUserId(userId);
-  userStorage.removeUser(userId);
-  res.send();
-});
-userRouter.post('/', async (req, res) => {
-  if (config.demoMode) {
-    res.send(new Error('In demo mode, it is not allowed to change or add user.'));
-    return;
-  }
-
-  const { username, password, password2, isAdmin, userId } = req.body;
-  if (password !== password2) {
-    res.send(new Error('Passwords does not match'));
-    return;
-  }
-  if (nullOrEmpty(username) || nullOrEmpty(password) || nullOrEmpty(password2)) {
-    res.send(new Error('Username and password are mandatory.'));
-    return;
-  }
-  const allUser = userStorage.getUsers(false);
-  if (!isAdmin && !checkIfAnyAdminAfterRemovingUser(userId, allUser)) {
-    res.send(
-      new Error('You cannot change the admin flag for this user as otherwise, there is no other user in the system'),
-    );
-    return;
-  }
-  userStorage.upsertUser({
-    userId,
-    username,
-    password,
-    isAdmin,
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function userPlugin(fastify) {
+  fastify.get('/', async () => {
+    return userStorage.getUsers(false);
   });
-  res.send();
-});
-export { userRouter };
+
+  fastify.get('/:userId', async (request) => {
+    const { userId } = request.params;
+    return userStorage.getUser(userId);
+  });
+
+  fastify.delete('/', async (request, reply) => {
+    const settings = await getSettings();
+    if (settings.demoMode && !isAdminUser(request)) {
+      return reply.code(403).send({ error: 'In demo mode, it is not allowed to remove user.' });
+    }
+
+    const { userId } = request.body;
+    const allUser = userStorage.getUsers(false);
+    if (!checkIfAnyAdminAfterRemovingUser(userId, allUser)) {
+      return reply.code(400).send({ error: 'You are trying to remove the last admin user. This is prohibited.' });
+    }
+    if (checkIfUserToBeRemovedIsLoggedIn(userId, request)) {
+      return reply.code(400).send({ error: 'You are trying to remove yourself. This is prohibited.' });
+    }
+    jobStorage.removeJobsByUserId(userId);
+    userStorage.removeUser(userId);
+    return reply.send();
+  });
+
+  fastify.post('/', async (request, reply) => {
+    const settings = await getSettings();
+    if (settings.demoMode && !isAdminUser(request)) {
+      return reply.code(403).send({ error: 'In demo mode, it is not allowed to change or add user.' });
+    }
+
+    const { username, password, password2, isAdmin, userId } = request.body;
+    if (password !== password2) {
+      return reply.code(400).send({ error: 'Passwords do not match.' });
+    }
+    if (nullOrEmpty(username) || nullOrEmpty(password) || nullOrEmpty(password2)) {
+      return reply.code(400).send({ error: 'Username and password are mandatory.' });
+    }
+    const allUser = userStorage.getUsers(false);
+    if (!isAdmin && !checkIfAnyAdminAfterRemovingUser(userId, allUser)) {
+      return reply.code(400).send({
+        error: 'You cannot change the admin flag for this user as otherwise, there is no other user in the system',
+      });
+    }
+    userStorage.upsertUser({ userId, username, password, isAdmin });
+    return reply.send();
+  });
+}

lib/api/routes/userSettingsRoute.js

@@ -0,0 +1,189 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import { getSettings, getUserSettings, upsertSettings } from '../../services/storage/settingsStorage.js';
+import { isAdmin } from '../security.js';
+import { resetGeocoordinatesAndDistanceForUser } from '../../services/storage/listingsStorage.js';
+import { geocodeAddress } from '../../services/geocoding/geoCodingService.js';
+import { autocompleteAddress } from '../../services/geocoding/autocompleteService.js';
+import { trackPoi } from '../../services/tracking/Tracker.js';
+import { TRACKING_POIS } from '../../TRACKING_POIS.js';
+import logger from '../../services/logger.js';
+import { runGeoCordTask } from '../../services/crons/geocoding-cron.js';
+
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function userSettingsPlugin(fastify) {
+  fastify.get('/', async (request) => {
+    const userId = request.session.currentUser;
+    return getUserSettings(userId);
+  });
+
+  fastify.get('/autocomplete', async (request, reply) => {
+    const { q } = request.query;
+    try {
+      const results = await autocompleteAddress(q);
+      return results;
+    } catch (error) {
+      return reply.code(500).send({ error: error.message });
+    }
+  });
+
+  fastify.post('/home-address', async (request, reply) => {
+    const userId = request.session.currentUser;
+    const { home_address } = request.body;
+    const settings = await getSettings();
+
+    if (settings.demoMode && !isAdmin(request)) {
+      return reply.code(403).send({ error: 'In demo mode, it is not allowed to change the home address.' });
+    }
+
+    try {
+      if (home_address) {
+        await trackPoi(TRACKING_POIS.DISTANCE_ADDRESS_ENTERED);
+        const coords = await geocodeAddress(home_address);
+        if (coords && coords.lat !== -1) {
+          upsertSettings({ home_address: { address: home_address, coords } }, userId);
+          resetGeocoordinatesAndDistanceForUser(userId);
+          runGeoCordTask();
+          return { success: true, coords };
+        } else {
+          return reply.code(400).send({ error: 'Could not geocode address' });
+        }
+      } else {
+        upsertSettings({ home_address: null }, userId);
+        return { success: true };
+      }
+    } catch (error) {
+      logger.error('Error updating home address settings', error);
+      return reply.code(500).send({ error: error.message });
+    }
+  });
+
+  fastify.post('/news-hash', async (request, reply) => {
+    const userId = request.session.currentUser;
+    const { news_hash } = request.body;
+
+    const globalSettings = await getSettings();
+    if (globalSettings.demoMode && !isAdmin(request)) {
+      return reply.code(403).send({ error: 'In demo mode, it is not allowed to change settings.' });
+    }
+
+    try {
+      upsertSettings({ news_hash }, userId);
+      return { success: true };
+    } catch (error) {
+      logger.error('Error updating news hash', error);
+      return reply.code(500).send({ error: error.message });
+    }
+  });
+
+  fastify.post('/provider-details', async (request, reply) => {
+    const userId = request.session.currentUser;
+    const { provider_details } = request.body;
+
+    const globalSettings = await getSettings();
+    if (globalSettings.demoMode && !isAdmin(request)) {
+      return reply.code(403).send({ error: 'In demo mode, it is not allowed to change settings.' });
+    }
+
+    if (!Array.isArray(provider_details)) {
+      return reply.code(400).send({ error: 'provider_details must be an array of provider ids.' });
+    }
+
+    try {
+      upsertSettings({ provider_details }, userId);
+      return { success: true };
+    } catch (error) {
+      logger.error('Error updating provider details setting', error);
+      return reply.code(500).send({ error: error.message });
+    }
+  });
+
+  fastify.post('/listings-view-mode', async (request, reply) => {
+    const userId = request.session.currentUser;
+    const { listings_view_mode } = request.body;
+
+    if (listings_view_mode !== 'grid' && listings_view_mode !== 'table') {
+      return reply.code(400).send({ error: 'listings_view_mode must be "grid" or "table".' });
+    }
+
+    if (listings_view_mode === 'table') {
+      await trackPoi(TRACKING_POIS.LISTING_TABLE_VIEW);
+    }
+
+    try {
+      upsertSettings({ listings_view_mode }, userId);
+      return { success: true };
+    } catch (error) {
+      logger.error('Error updating listings view mode setting', error);
+      return reply.code(500).send({ error: error.message });
+    }
+  });
+
+  fastify.post('/jobs-view-mode', async (request, reply) => {
+    const userId = request.session.currentUser;
+    const { jobs_view_mode } = request.body;
+
+    if (jobs_view_mode !== 'grid' && jobs_view_mode !== 'table') {
+      return reply.code(400).send({ error: 'jobs_view_mode must be "grid" or "table".' });
+    }
+
+    if (jobs_view_mode === 'table') {
+      await trackPoi(TRACKING_POIS.JOBS_TABLE_VIEW);
+    }
+
+    try {
+      upsertSettings({ jobs_view_mode }, userId);
+      return { success: true };
+    } catch (error) {
+      logger.error('Error updating jobs view mode setting', error);
+      return reply.code(500).send({ error: error.message });
+    }
+  });
+
+  fastify.post('/listing-deletion-preference', async (request, reply) => {
+    const userId = request.session.currentUser;
+    const { listing_deletion_preference } = request.body;
+
+    const globalSettings = await getSettings();
+    if (globalSettings.demoMode && !isAdmin(request)) {
+      return reply.code(403).send({ error: 'In demo mode, it is not allowed to change settings.' });
+    }
+
+    if (listing_deletion_preference == null) {
+      return reply.code(400).send({ error: 'listing_deletion_preference is required.' });
+    }
+
+    const { skipPrompt, hardDelete } = listing_deletion_preference;
+
+    try {
+      upsertSettings({ listing_deletion_preference: { skipPrompt, hardDelete } }, userId);
+      return { success: true };
+    } catch (error) {
+      logger.error('Error updating listing deletion preference', error);
+      return reply.code(500).send({ error: error.message });
+    }
+  });
+
+  fastify.post('/language', async (request, reply) => {
+    const userId = request.session.currentUser;
+    const { language } = request.body;
+
+    if (typeof language !== 'string' || language.trim() === '') {
+      return reply.code(400).send({ error: 'language must be a non-empty string.' });
+    }
+
+    try {
+      upsertSettings({ language }, userId);
+      await trackPoi(TRACKING_POIS.CHANGE_LANGUAGE);
+      return { success: true };
+    } catch (error) {
+      logger.error('Error updating language setting', error);
+      return reply.code(500).send({ error: error.message });
+    }
+  });
+}

lib/api/routes/versionRouter.js

@@ -1,24 +1,12 @@
-import restana from 'restana';
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import fetch from 'node-fetch';
 import { getPackageVersion } from '../../utils.js';
 import semver from 'semver';
 
-const service = restana();
-const versionRouter = service.newRouter();
-
-versionRouter.get('/', async (req, res) => {
-  const versionPayload = await getCurrentVersionFromGithub();
-  const localFredyVersion = await getPackageVersion();
-  res.body =
-    versionPayload == null
-      ? {
-          newVersion: false,
-          localFredyVersion,
-        }
-      : versionPayload;
-  res.send();
-});
-
 async function getCurrentVersionFromGithub() {
   const raw = await fetch('https://api.github.com/repos/orangecoding/fredy/releases/latest');
   const data = await raw.json();
@@ -35,4 +23,13 @@ async function getCurrentVersionFromGithub() {
   };
 }
 
-export { versionRouter };
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export default async function versionPlugin(fastify) {
+  fastify.get('/', async () => {
+    const versionPayload = await getCurrentVersionFromGithub();
+    const localFredyVersion = await getPackageVersion();
+    return versionPayload ?? { newVersion: false, localFredyVersion };
+  });
+}

lib/api/security.js

@@ -1,47 +1,53 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import * as userStorage from '../services/storage/userStorage.js';
-import cookieSession from 'cookie-session';
-import { nanoid } from 'nanoid';
-const unauthorized = (res) => {
-  return res.send(401);
-};
-const isUnauthorized = (req) => {
-  return req.session.currentUser == null;
-};
-const isAdmin = (req) => {
-  if (!isUnauthorized(req)) {
-    const user = userStorage.getUser(req.session.currentUser);
-    return user != null && user.isAdmin;
-  }
+
+const SESSION_MAX_AGE = 2 * 60 * 60 * 1000; // 2 hours
+
+/**
+ * Returns true when the request has no valid, non-expired session.
+ * @param {import('fastify').FastifyRequest} request
+ * @returns {boolean}
+ */
+export function isUnauthorized(request) {
+  if (!request.session?.currentUser) return true;
+  if (Date.now() - (request.session.createdAt || 0) > SESSION_MAX_AGE) return true;
   return false;
-};
-const authInterceptor = () => {
-  return (req, res, next) => {
-    if (isUnauthorized(req)) {
-      return unauthorized(res);
-    } else {
-      next();
-    }
-  };
-};
-const adminInterceptor = () => {
-  return (req, res, next) => {
-    if (!isAdmin(req)) {
-      return unauthorized(res);
-    } else {
-      next();
-    }
-  };
-};
-const cookieSession$0 = (userId) => {
-  return cookieSession({
-    name: 'fredy-admin-session',
-    keys: ['fredy', 'super', 'fancy', 'key', nanoid()],
-    userId,
-    maxAge: 2 * 60 * 60 * 1000, // 2 hours
-  });
-};
-export { cookieSession$0 as cookieSession };
-export { adminInterceptor };
-export { authInterceptor };
-export { isUnauthorized };
-export { isAdmin };
+}
+
+/**
+ * Returns true when the session belongs to an admin user.
+ * @param {import('fastify').FastifyRequest} request
+ * @returns {boolean}
+ */
+export function isAdmin(request) {
+  if (isUnauthorized(request)) return false;
+  const user = userStorage.getUser(request.session.currentUser);
+  return user != null && user.isAdmin;
+}
+
+/**
+ * Fastify preHandler hook - rejects unauthenticated requests with 401.
+ * @param {import('fastify').FastifyRequest} request
+ * @param {import('fastify').FastifyReply} reply
+ */
+export async function authHook(request, reply) {
+  if (isUnauthorized(request)) {
+    reply.code(401).send();
+  }
+}
+
+/**
+ * Fastify preHandler hook - rejects non-admin requests with 401.
+ * Apply after authHook.
+ * @param {import('fastify').FastifyRequest} request
+ * @param {import('fastify').FastifyReply} reply
+ */
+export async function adminHook(request, reply) {
+  if (!isAdmin(request)) {
+    reply.code(401).send();
+  }
+}

lib/defaultConfig.js

@@ -1,9 +1,9 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 export const DEFAULT_CONFIG = {
-  interval: '60',
-  port: 9998,
-  workingHours: { from: '', to: '' },
-  demoMode: false,
-  analyticsEnabled: null,
   // Default path for sqlite storage directory. Interpreted relative to project root.
   sqlitepath: '/db',
 };

lib/errors.js

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 class ExtendableError extends Error {
   constructor(message) {
     super(message);

lib/mcp/README.md

@@ -0,0 +1,323 @@
+ # Fredy MCP Server
+
+The Fredy MCP Server exposes your real estate jobs and listings data to LLM clients. It supports two transports:
+
+- **Stdio**: for local LLM clients (Claude Desktop, LM Studio, llm-cli, mcp-cli, etc.)
+- **Streamable HTTP**: for remote LLM clients (ChatGPT, cloud-hosted agents, etc.)
+
+## Authentication
+
+All MCP access is **token-based** based. Every Fredy user is automatically assigned a **permanent, non-expiring MCP token** when their account is created. This token is a secret and should be treated like a password.
+
+### Where to find your token
+
+MCP tokens are displayed in the **User Management** list (Admin → Users). Each user's token is shown in the **"MCP Token"** column.
+
+> **Important:** MCP tokens never expire. They are permanent secrets tied to each user account. If a token is compromised, you must change the token! If you chose to use a token from an admin account, the LLM can query information from ALL jobs/listings. 
+
+## Available Tools
+
+| Tool | Description                                                                    |
+|------|--------------------------------------------------------------------------------|
+| `list_jobs` | List real estate search jobs with pagination and text filtering                |
+| `get_job` | Get detailed information about a specific job                                  |
+| `list_listings` | Search and list real estate listings with pagination, text search, and filters |
+| `get_listing` | Get full details of a single listing                                           |
+| `get_current_date_time` | Gets the current date/time for the llm to be used                              |
+
+### Tool Details
+
+#### list_jobs
+- `page` (number, optional) – Page number (default: 1)
+- `pageSize` (number, optional) – Results per page (default: 50, max: 1000). Use pagination to fetch more.
+- `filter` (string, optional) – Free-text filter on job name
+
+Response: markdown table with columns ID, Name, Enabled, Active Listings. Includes summary and pagination info.
+
+#### get_job
+- `jobId` (string, required) – The job ID to retrieve
+
+#### list_listings
+- `page` (number, optional) – Page number (default: 1)
+- `pageSize` (number, optional) – Results per page (default: 50, max: 1000). Use pagination to fetch more.
+- `filter` (string, optional) – Free-text search across title, address, provider, link
+- `jobId` (string, optional) – Filter listings by job ID
+- `activeOnly` (boolean, optional) – When true, only show active listings
+- `provider` (string, optional) – Filter by provider name
+- `createdAfter` (number, optional) – Only include listings created at or after this unix timestamp in milliseconds (e.g. `1772008362564`). Useful for queries like "give me all listings from today".
+- `createdBefore` (number, optional) – Only include listings created at or before this unix timestamp in milliseconds (e.g. `1772008362564`).
+- `minPrice` (number, optional) – Only include listings with price >= this value (e.g. `500`). Numeric, no currency symbol.
+- `maxPrice` (number, optional) – Only include listings with price <= this value (e.g. `1500`). Numeric, no currency symbol.
+- `sortField` (string, optional) – Sort by: created_at, price, size, provider, title, is_active
+- `sortDir` (string, optional) – Sort direction: asc or desc
+
+Response: markdown table with columns ID, Title, Address, Price, Size, Provider, Active, Created, Job. Includes summary and pagination info. Use `get_listing` for full details.
+
+> **Note:** All timestamps are **unix timestamps in milliseconds** (e.g. `1772008362564`), not seconds.
+
+#### get_listing
+- `listingId` (string, required) – The listing ID to retrieve
+
+## Usage with Local LLM (stdio transport)
+
+The stdio transport communicates over stdin/stdout and is ideal for local LLM tools.
+
+### Quick Start
+
+```bash
+MCP_TOKEN=fredy_<your-token> node mcp/stdio.js
+# or
+MCP_TOKEN=fredy_<your-token> yarn mcp:stdio
+```
+
+### Testing with MCP Inspector
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) lets you interactively test your MCP server in a browser UI.
+
+```bash
+npx @modelcontextprotocol/inspector -e MCP_TOKEN=fredy_<your-token> -- node mcp/stdio.js
+```
+
+Once the inspector is running, open the URL shown in your terminal (usually `http://localhost:6274`). You can then:
+1. Click **Connect** to establish the stdio connection
+2. Go to the **Tools** tab to see all available tools
+3. Select a tool, fill in parameters, and click **Run** to test it
+
+### LM Studio Configuration
+
+[LM Studio](https://lmstudio.ai/) supports MCP servers natively, allowing your local LLM to access Fredy's jobs and listings data.
+
+#### Setup
+
+1. Open **LM Studio** and load a model that supports tool use (e.g., Qwen 2.5, Llama 3.1, Mistral, etc.)
+2. In the right side  under **Integrations** click on "# install" and "edit mcp.json"
+3. Edit the LM Studio MCP config file directly (`~/.lmstudio/config/mcp.json` or via the UI export):
+
+   ```json
+   {
+     "mcpServers": {
+       "fredy": {
+         "command": "node",
+         "args": ["/absolute/path/to/fredy/mcp/stdio.js"],
+         "env": {
+           "MCP_TOKEN": "fredy_<your-token>"
+         }
+       }
+     }
+   }
+   ```
+
+4. Toggle the server **on**: LM Studio will spawn the stdio process and connect
+5. You should see the Fredy tools appear as available tools
+
+#### Suggestion on LLM
+After testing numerous LLM's, I got the best results with Qwen 3.5 or Qwen 2.5.. E.g. `Qwen2.5-14B-Instruct-1M-8bit`.
+
+#### Usage
+
+Once connected, simply ask your LLM about your real estate data in natural language:
+
+- *"Show me all my active search jobs"*
+- *"List the latest listings from my Berlin apartment search"*
+- *"Get details for listing XYZ"*
+- *"What are the cheapest listings across all my jobs?"*
+
+The LLM will automatically call the appropriate Fredy MCP tools and present the results.
+
+> **Tip:** Make sure Fredy is running and the database is accessible before starting the MCP server in LM Studio. The stdio transport initializes its own database connection, so Fredy's main process does not need to be running, but the database file must exist and be up-to-date (migrations applied).
+
+### Claude Desktop Configuration
+
+[Claude Desktop](https://claude.ai/download) supports MCP servers natively via its developer settings.
+
+#### Setup
+
+1. Open **Claude Desktop**
+2. Go to **Settings → Developer → Edit Config** - this opens the `claude_desktop_config.json` file
+3. Add the `fredy` server to the `mcpServers` object:
+
+   ```json
+   {
+     "mcpServers": {
+       "fredy": {
+         "command": "/opt/homebrew/opt/node@22/bin/node",
+         "args": ["/absolute/path/to/fredy/lib/mcp/stdio.js"],
+         "env": {
+           "MCP_TOKEN": "fredy_<your-token>"
+         }
+       }
+     }
+   }
+   ```
+
+   Replace `/absolute/path/to/fredy` with the actual path on your machine (e.g. `/Users/you/dev/fredy`).
+
+   > **Important:** Claude Desktop launches with a restricted `PATH` and often cannot find `node` by name. Always use the **full absolute path** to the node binary. Find yours by running `which node` in a terminal. Common locations:
+   > - Homebrew (default): `/opt/homebrew/bin/node`
+   > - Homebrew (versioned, e.g. node@22): `/opt/homebrew/opt/node@22/bin/node`
+   > - nvm: `/Users/<you>/.nvm/versions/node/<version>/bin/node`
+
+4. Save the file and **restart Claude Desktop**
+5. You should see a hammer icon (🔨) in the chat input - click it to confirm the Fredy tools are listed
+
+#### Usage
+
+Once connected, simply ask Claude about your real estate data:
+
+- *"Show me all my active search jobs"*
+- *"List the latest listings from my Berlin apartment search"*
+- *"What are the cheapest apartments added this week?"*
+
+Claude will automatically call the appropriate Fredy MCP tools.
+
+> **Note:** Fredy's main web process does not need to be running - the stdio transport opens its own database connection directly. But the SQLite database file must exist and migrations must have been applied.
+
+---
+
+## Usage with Remote LLM (Streamable HTTP transport)
+
+The HTTP transport is automatically available when Fredy is running. It uses the MCP Streamable HTTP protocol at:
+
+```
+POST   /api/mcp   – JSON-RPC messages (initialize, tool calls)
+GET    /api/mcp   – SSE stream for server-initiated notifications
+DELETE /api/mcp   – Terminate session
+```
+
+### Authentication
+
+All requests must include the token as a Bearer token:
+
+```
+Authorization: Bearer fredy_<your-token>
+```
+
+### Example: Initialize a session
+
+```bash
+curl -X POST http://localhost:9998/api/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer fredy_<your-token>" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+      "protocolVersion": "2025-03-26",
+      "capabilities": {},
+      "clientInfo": { "name": "test-client", "version": "1.0.0" }
+    }
+  }'
+```
+
+### Example: Call a tool
+
+```bash
+curl -X POST http://localhost:9998/api/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer fredy_<your-token>" \
+  -H "Mcp-Session-Id: <session-id-from-init-response>" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "tools/call",
+    "params": {
+      "name": "list_jobs",
+      "arguments": { "page": 1, "pageSize": 10 }
+    }
+  }'
+```
+
+## Security
+
+- Every user is automatically assigned a permanent MCP token at account creation – **tokens never expire**
+- Tokens are cryptographically random (256-bit) and prefixed with `fredy_`
+- Each token is scoped to a single user – the LLM can only access that user's data
+- Non-admin users only see their own jobs and jobs shared with them
+- Tokens are stored in the `mcp_token` column of the `users` table
+- Tokens are deleted automatically when the owning user is removed
+- The `/api/mcp` endpoint uses Bearer token auth (independent of cookie-session)
+- Treat MCP tokens like passwords – do not share them publicly
+
+## Response Format
+
+All tool responses use **markdown** instead of JSON for maximum LLM readability and token efficiency:
+
+- **List responses** (list_jobs, list_listings) use markdown tables with a summary line and pagination footer
+- **Detail responses** (get_job, get_listing) use markdown key-value lists
+- **Error responses** include the tool name and error message
+
+Example list response:
+
+```
+**Tool:** list_listings | **Status:** OK
+
+Found **85** listing(s). Showing page 1 of 2 (50 on this page). More pages available - use page=2 to continue.
+
+| ID | Title | Address | Price | Size | Provider | Active | Created | Job |
+|----|-------|---------|-------|------|----------|--------|---------|-----|
+| abc123 | Nice flat | Berlin | 1200 | 70 | immoscout | yes | 2026-02-25 10:30:00 | My Search |
+| ... | ... | ... | ... | ... | ... | ... | ... | ... |
+
+Use **get_listing** with an ID for full details (description, link, image).
+
+**Page:** 1/2 | **Has more:** yes
+```
+
+Example detail response:
+
+```
+**Tool:** get_listing | **Status:** OK
+
+### Listing: Nice flat
+
+- **ID:** abc123
+- **Title:** Nice flat
+- **Address:** Berlin
+- **Price:** 1200
+- **Size:** 70
+- **Provider:** immoscout
+- **Link:** https://...
+- **Active:** yes
+- **Created:** 2026-02-25 10:30:00
+```
+
+Markdown is used because it is significantly more token-efficient than JSON (~40-60% fewer tokens for tabular data) and natively understood by all LLMs.
+
+## Architecture
+
+```
+┌─────────────────┐     stdio      ┌──────────────┐
+│  Local LLM      │◄──────────────►│  mcp/stdio.js│
+│  (LM Studio,    │                │  (transport)  │
+│   Claude, etc.) │                │               │
+└─────────────────┘                └──────┬───────┘
+                                          │
+┌─────────────────┐  Streamable HTTP ┌────┴────────┐
+│  Remote LLM     │◄───────────────►│  /api/mcp    │
+│                 │  (Bearer token) │  (transport)  │
+└─────────────────┘                 └──────┬───────┘
+                                           │
+                                ┌──────────┴──────────┐
+                                │  mcpAuthentication  │
+                                │  (token validation, │
+                                │   access control)   │
+                                └──────────┬──────────┘
+                                           │
+                                  ┌────────┴────────┐
+                                  │  mcpAdapter.js  │
+                                  │  (tool routing  │
+                                  │   + data fetch) │
+                                  └────────┬────────┘
+                                           │
+                                  ┌────────┴────────┐
+                                  │ mcpNormalizer.js│
+                                  │ (markdown       │
+                                  │  formatting)    │
+                                  └────────┬────────┘
+                                           │
+                                    ┌──────┴───────┐
+                                    │  Fredy DB    │
+                                    │  (SQLite)    │
+                                    └──────────────┘
+```

lib/mcp/mcpAdapter.js

@@ -0,0 +1,355 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { queryJobs, getJob } from '../services/storage/jobStorage.js';
+import { queryListings, getListingById } from '../services/storage/listingsStorage.js';
+import { authenticateToolCall, checkJobAccess } from './mcpAuthentication.js';
+import {
+  normalizeListJobs,
+  normalizeGetJob,
+  normalizeListListings,
+  normalizeGetListing,
+  normalizeError,
+} from './mcpNormalizer.js';
+
+/**
+ * Create a configured MCP server instance with all Fredy tools registered.
+ *
+ * The adapter fetches raw data from storage and delegates response formatting
+ * to the normalizer layer (mcpNormalizer.js) which produces a consistent
+ * { ok, summary, data, meta } envelope for every tool response.
+ *
+ * Each tool call requires a userId (resolved from the MCP token before invocation).
+ * Tools respect user scoping: non-admin users only see their own jobs/listings.
+ *
+ * @returns {McpServer}
+ */
+export function createMcpServer() {
+  const server = new McpServer(
+    {
+      name: 'fredy-mcp',
+      version: '1.0.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+      instructions:
+        'Fredy MCP Server – query real estate jobs and listings. ' +
+        'All timestamps are unix timestamps in milliseconds (e.g. 1772008362564). ' +
+        'Use list_jobs to browse jobs, get_job for details, ' +
+        'list_listings to search listings (supports time filters like createdAfter/createdBefore), ' +
+        'and get_listing for full details of a single listing. ' +
+        'Responses are formatted as markdown with a summary, data (tables for lists, key-value for details), and pagination info. ' +
+        'Always present results to the user as soon as you have them - do NOT call the tool again unless you need additional pages or different data.',
+    },
+  );
+
+  // ── list_jobs ───────────────────────────────────────────────────────
+  server.tool(
+    'list_jobs',
+    'List real estate search jobs for the authenticated user. ' +
+      'Returns up to 50 jobs per page by default. Use pagination (page parameter) to fetch more. ' +
+      'Check meta.hasMore to know if there are additional pages.',
+    {
+      page: z.number().optional().describe('Page number (default: 1)'),
+      pageSize: z
+        .number()
+        .optional()
+        .describe('Results per page (default: 50, max: 1000). Start with the default and paginate if needed.'),
+      filter: z.string().optional().describe('Free-text filter on job name'),
+    },
+    async ({ page, pageSize, filter }, extra) => {
+      const { user, error } = authenticateToolCall(extra, 'list_jobs');
+      if (error) return normalizeError(error, 'list_jobs');
+
+      const safePage = page ?? 1;
+      const safePageSize = pageSize ?? 50;
+
+      const result = queryJobs({
+        page: safePage,
+        pageSize: safePageSize,
+        freeTextFilter: filter,
+        userId: user.id,
+        isAdmin: user.isAdmin,
+      });
+
+      return normalizeListJobs(result, { page: safePage, pageSize: safePageSize });
+    },
+  );
+
+  // ── get_job ─────────────────────────────────────────────────────────
+  server.tool(
+    'get_job',
+    'Get detailed information about a specific job by its ID.',
+    {
+      jobId: z.string().describe('The job ID to retrieve'),
+    },
+    async ({ jobId }, extra) => {
+      const { user, error } = authenticateToolCall(extra, 'get_job');
+      if (error) return normalizeError(error, 'get_job');
+
+      const job = getJob(jobId);
+      if (!job) {
+        return normalizeError('Job not found.', 'get_job');
+      }
+
+      if (!checkJobAccess(user, job)) {
+        return normalizeError('Access denied.', 'get_job');
+      }
+
+      return normalizeGetJob(job);
+    },
+  );
+
+  // ── list_listings ───────────────────────────────────────────────────
+  server.tool(
+    'list_listings',
+    'Search and list real estate listings. Returns up to 50 listings per page by default. ' +
+      'Use pagination (page parameter) to fetch more. Check meta.hasMore in the response. ' +
+      'Supports text search, time filtering, and various filters. ' +
+      'All timestamps are unix timestamps in milliseconds (e.g. 1772008362564). ' +
+      'Use createdAfter/createdBefore to filter by time, e.g. "give me all listings from today". ' +
+      'Use get_listing to get full details (description, link, image) for a specific listing.',
+    {
+      page: z.number().optional().describe('Page number (default: 1)'),
+      pageSize: z
+        .number()
+        .optional()
+        .describe('Results per page (default: 50, max: 1000). Start with the default and paginate if needed.'),
+      filter: z.string().optional().describe('Free-text search across title, address, provider, link'),
+      jobId: z.string().optional().describe('Filter listings by job ID'),
+      activeOnly: z.boolean().optional().describe('When true, only show active listings'),
+      provider: z.string().optional().describe('Filter by provider name'),
+      createdAfter: z
+        .number()
+        .optional()
+        .describe(
+          'Only include listings created at or after this unix timestamp in milliseconds (e.g. 1772008362564). Useful for queries like "listings from today".',
+        ),
+      createdBefore: z
+        .number()
+        .optional()
+        .describe(
+          'Only include listings created at or before this unix timestamp in milliseconds (e.g. 1772008362564).',
+        ),
+      minPrice: z
+        .number()
+        .optional()
+        .describe(
+          'Only include listings with price >= this value (e.g. 500). Price is a numeric value (no currency symbol).',
+        ),
+      maxPrice: z
+        .number()
+        .optional()
+        .describe(
+          'Only include listings with price <= this value (e.g. 1500). Price is a numeric value (no currency symbol).',
+        ),
+      sortField: z.string().optional().describe('Sort by: created_at, price, size, provider, title, is_active'),
+      sortDir: z.string().optional().describe('Sort direction: asc or desc'),
+      status: z
+        .enum(['applied', 'rejected', 'accepted', 'none'])
+        .optional()
+        .describe(
+          'Filter by user-set status. "applied", "rejected", or "accepted" return only listings with that status; "none" returns only listings without a status set.',
+        ),
+    },
+    async (
+      {
+        page,
+        pageSize,
+        filter,
+        jobId,
+        activeOnly,
+        provider,
+        createdAfter,
+        createdBefore,
+        minPrice,
+        maxPrice,
+        sortField,
+        sortDir,
+        status,
+      },
+      extra,
+    ) => {
+      const { user, error } = authenticateToolCall(extra, 'list_listings');
+      if (error) return normalizeError(error, 'list_listings');
+
+      const safePage = page ?? 1;
+      const safePageSize = pageSize ?? 50;
+
+      const result = queryListings({
+        page: safePage,
+        pageSize: safePageSize,
+        freeTextFilter: filter,
+        jobIdFilter: jobId,
+        activityFilter: activeOnly === true ? true : activeOnly === false ? false : undefined,
+        providerFilter: provider,
+        createdAfter: createdAfter ?? null,
+        createdBefore: createdBefore ?? null,
+        minPrice: minPrice ?? null,
+        maxPrice: maxPrice ?? null,
+        sortField: sortField ?? null,
+        sortDir: sortDir ?? 'desc',
+        statusFilter: status,
+        userId: user.id,
+        isAdmin: user.isAdmin,
+      });
+
+      return normalizeListListings(result, { page: safePage, pageSize: safePageSize });
+    },
+  );
+
+  // ── get_listing ─────────────────────────────────────────────────────
+  server.tool(
+    'get_listing',
+    'Get full details of a single listing by its ID.',
+    {
+      listingId: z.string().describe('The listing ID to retrieve'),
+    },
+    async ({ listingId }, extra) => {
+      const { user, error } = authenticateToolCall(extra, 'get_listing');
+      if (error) return normalizeError(error, 'get_listing');
+
+      const listing = getListingById(listingId, user.id, user.isAdmin);
+      if (!listing) {
+        return normalizeError('Listing not found or access denied.', 'get_listing');
+      }
+
+      return normalizeGetListing(listing);
+    },
+  );
+
+  // ── get_photo_for_listing ─────────────────────────────────────────────────────
+  server.tool(
+    'get_photo_for_listing',
+    'Fetch and return the photo of a listing by its ID as an image for vision analysis.',
+    {
+      listingId: z.string().describe('The listing ID whose photo to fetch'),
+    },
+    async ({ listingId }, extra) => {
+      const { user, error } = authenticateToolCall(extra, 'get_photo_for_listing');
+      if (error) return normalizeError(error, 'get_photo_for_listing');
+
+      const listing = getListingById(listingId, user.id, user.isAdmin);
+      if (!listing) {
+        return normalizeError('Listing not found or access denied.', 'get_photo_for_listing');
+      }
+
+      const imageUrl = listing.image_url;
+      if (!imageUrl) {
+        return normalizeError('No image available for this listing.', 'get_photo_for_listing');
+      }
+
+      const SUPPORTED_MIME_TYPES = new Set(['image/jpeg', 'image/png', 'image/gif', 'image/webp']);
+
+      let response;
+      try {
+        response = await fetch(imageUrl, {
+          signal: AbortSignal.timeout(10_000),
+          headers: {
+            'User-Agent':
+              'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+            Accept: 'image/jpeg,image/png,image/webp,image/gif,image/*,*/*',
+          },
+        });
+      } catch (fetchErr) {
+        return normalizeError(`Failed to fetch image: ${fetchErr.message}`, 'get_photo_for_listing');
+      }
+
+      if (!response.ok) {
+        return normalizeError(
+          `Image fetch returned HTTP ${response.status}. Image URL: ${imageUrl}`,
+          'get_photo_for_listing',
+        );
+      }
+
+      const contentType = response.headers.get('content-type') ?? '';
+      const headerMimeType = contentType.split(';')[0].trim().toLowerCase();
+
+      let buffer;
+      try {
+        buffer = await response.arrayBuffer();
+      } catch (readErr) {
+        return normalizeError(`Failed to read image body: ${readErr.message}`, 'get_photo_for_listing');
+      }
+
+      const bytes = new Uint8Array(buffer);
+
+      if (bytes.length < 12) {
+        return normalizeError(
+          `Downloaded file is too small to determine image type. Image URL: ${imageUrl}`,
+          'get_photo_for_listing',
+        );
+      }
+
+      let resolvedMime;
+
+      if (SUPPORTED_MIME_TYPES.has(headerMimeType)) {
+        resolvedMime = headerMimeType;
+      } else {
+        if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+          resolvedMime = 'image/jpeg';
+        } else if (
+          bytes[0] === 0x89 &&
+          bytes[1] === 0x50 &&
+          bytes[2] === 0x4e &&
+          bytes[3] === 0x47 &&
+          bytes[4] === 0x0d &&
+          bytes[5] === 0x0a &&
+          bytes[6] === 0x1a &&
+          bytes[7] === 0x0a
+        ) {
+          resolvedMime = 'image/png';
+        } else if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38) {
+          resolvedMime = 'image/gif';
+        } else if (
+          bytes[0] === 0x52 &&
+          bytes[1] === 0x49 &&
+          bytes[2] === 0x46 &&
+          bytes[3] === 0x46 &&
+          bytes[8] === 0x57 &&
+          bytes[9] === 0x45 &&
+          bytes[10] === 0x42 &&
+          bytes[11] === 0x50
+        ) {
+          resolvedMime = 'image/webp';
+        } else {
+          return normalizeError(
+            `Image format not supported by vision models (header: ${headerMimeType || 'unknown'}). Image URL: ${imageUrl}`,
+            'get_photo_for_listing',
+          );
+        }
+      }
+
+      const base64 = Buffer.from(buffer).toString('base64');
+
+      return {
+        content: [
+          {
+            type: 'image',
+            data: base64,
+            mimeType: resolvedMime,
+          },
+        ],
+      };
+    },
+  );
+
+  // ── get_current_date_ime ─────────────────────────────────────────────────────
+  server.tool('get_current_date_time', 'Returns the current date and time.', {}, () => {
+    return {
+      content: [{ type: 'text', text: `Timestring: ${new Date().toLocaleString()}, MS since 1970: ${Date.now()}` }],
+    };
+  });
+
+  return server;
+}

lib/mcp/mcpAuthentication.js

@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+/**
+ * MCP Authentication Layer
+ *
+ * Centralizes all authentication and authorization logic for MCP tool calls
+ * and HTTP requests. Ensures consistent access control across all transports.
+ */
+
+import { getUser, validateMcpToken } from '../services/storage/userStorage.js';
+
+/**
+ * Authenticate an MCP tool call by extracting and validating the user from authInfo.
+ *
+ * @param {{ authInfo?: { userId?: string } }} extra - The extra context passed by the MCP SDK.
+ * @returns {{ user: object|null, error: string|null }}
+ *   - On success: { user: <userObject>, error: null }
+ *   - On failure: { user: null, error: <errorMessage> }
+ */
+export function authenticateToolCall(extra) {
+  const userId = extra?.authInfo?.userId;
+  if (!userId) {
+    return { user: null, error: 'Authentication required. Please provide a valid MCP API token.' };
+  }
+
+  const user = getUser(userId);
+  if (!user) {
+    return { user: null, error: 'Authentication required. Please provide a valid MCP API token.' };
+  }
+
+  return { user, error: null };
+}
+
+/**
+ * Check whether a user has access to a specific job.
+ * Admins have access to all jobs. Non-admins can only access their own jobs
+ * or jobs explicitly shared with them.
+ *
+ * @param {object} user - The authenticated user object.
+ * @param {object} job - The job object from storage.
+ * @returns {boolean} True if the user is allowed to access this job.
+ */
+export function checkJobAccess(user, job) {
+  if (user.isAdmin) return true;
+  if (job.userId === user.id) return true;
+  if (Array.isArray(job.shared_with_user) && job.shared_with_user.includes(user.id)) return true;
+  return false;
+}
+
+/**
+ * Authenticate an HTTP request by extracting and validating the Bearer token
+ * from the Authorization header.
+ *
+ * @param {import('http').IncomingMessage} req
+ * @returns {{ userId: string } | null} The authenticated user info, or null if invalid.
+ */
+export function authenticateRequest(req) {
+  const authHeader = req.headers['authorization'] || '';
+  if (!authHeader.startsWith('Bearer ')) return null;
+  const token = authHeader.slice(7).trim();
+  if (!token) return null;
+  return validateMcpToken(token);
+}

lib/mcp/mcpHttpRoute.js

@@ -0,0 +1,114 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMcpServer } from './mcpAdapter.js';
+import { authenticateRequest } from './mcpAuthentication.js';
+import logger from '../services/logger.js';
+import crypto from 'crypto';
+
+/**
+ * Active transports keyed by session id.
+ * @type {Map<string, { server: McpServer, transport: StreamableHTTPServerTransport }>}
+ */
+const sessions = new Map();
+
+/**
+ * @param {string|undefined} sessionId
+ * @param {{ userId: string }} auth
+ */
+function getOrCreateSession(sessionId, auth) {
+  if (sessionId && sessions.has(sessionId)) {
+    return sessions.get(sessionId);
+  }
+
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => crypto.randomUUID(),
+    onsessioninitialized: (sid) => {
+      sessions.set(sid, entry);
+      logger.debug(`MCP session created: ${sid}`);
+    },
+  });
+
+  const server = createMcpServer();
+  const entry = { server, transport, userId: auth.userId };
+
+  transport.onclose = () => {
+    const sid = transport.sessionId;
+    if (sid) {
+      sessions.delete(sid);
+      logger.debug(`MCP session closed: ${sid}`);
+    }
+  };
+
+  return entry;
+}
+
+/**
+ * Register MCP Streamable HTTP routes on a fastify instance.
+ *
+ * POST /api/mcp  – JSON-RPC messages
+ * GET  /api/mcp  – SSE stream for server-initiated notifications
+ * DELETE /api/mcp – session termination
+ *
+ * All endpoints require a valid Bearer token in the Authorization header.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+export function registerMcpRoutes(fastify) {
+  fastify.post('/api/mcp', async (request, reply) => {
+    const auth = authenticateRequest(request.raw);
+    if (!auth) {
+      return reply.code(401).send({ error: 'Unauthorized. Provide a valid Bearer token.' });
+    }
+
+    const sessionId = request.raw.headers['mcp-session-id'];
+    const { server, transport } = getOrCreateSession(sessionId, auth);
+
+    if (!transport.onmessage) {
+      await server.connect(transport);
+    }
+
+    request.raw.auth = { userId: auth.userId };
+
+    reply.hijack();
+    await transport.handleRequest(request.raw, reply.raw, request.body);
+  });
+
+  fastify.get('/api/mcp', async (request, reply) => {
+    const auth = authenticateRequest(request.raw);
+    if (!auth) {
+      return reply.code(401).send({ error: 'Unauthorized. Provide a valid Bearer token.' });
+    }
+
+    const sessionId = request.raw.headers['mcp-session-id'];
+    if (!sessionId || !sessions.has(sessionId)) {
+      return reply.code(400).send({ error: 'Invalid or missing session. Send an initialize request first.' });
+    }
+
+    const { transport } = sessions.get(sessionId);
+    reply.hijack();
+    await transport.handleRequest(request.raw, reply.raw);
+  });
+
+  fastify.delete('/api/mcp', async (request, reply) => {
+    const auth = authenticateRequest(request.raw);
+    if (!auth) {
+      return reply.code(401).send({ error: 'Unauthorized. Provide a valid Bearer token.' });
+    }
+
+    const sessionId = request.raw.headers['mcp-session-id'];
+    if (!sessionId || !sessions.has(sessionId)) {
+      return reply.code(404).send({ error: 'Session not found.' });
+    }
+
+    const { transport } = sessions.get(sessionId);
+    await transport.close();
+    sessions.delete(sessionId);
+    return { ok: true };
+  });
+
+  logger.debug('MCP Streamable HTTP endpoint registered at /api/mcp');
+}

lib/mcp/mcpNormalizer.js

@@ -0,0 +1,184 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+/**
+ * MCP Response Normalizer
+ *
+ * Transforms raw adapter data into LLM-friendly markdown responses.
+ * Markdown is significantly better than JSON for LLM consumption because:
+ * - LLMs are trained extensively on markdown text
+ * - Markdown tables are ~40-60% more token-efficient than JSON arrays
+ * - Less syntactic noise (no quotes, brackets, commas around every value)
+ * - Natively readable and structured
+ *
+ * Each response follows a consistent structure:
+ * 1. Status line (OK/ERROR + tool name)
+ * 2. Summary (human-readable description)
+ * 3. Data (markdown table for lists, key-value for single items)
+ * 4. Pagination info (for list responses)
+ */
+
+/**
+ * Wrap a markdown string as an MCP text content result.
+ * @param {string} markdown
+ * @param {boolean} [isError=false]
+ * @returns {{ content: Array, isError?: boolean }}
+ */
+function toMcpResponse(markdown, isError = false) {
+  const result = {
+    content: [{ type: 'text', text: markdown }],
+  };
+  if (isError) result.isError = true;
+  return result;
+}
+
+/**
+ * Format a unix timestamp (ms) as a human-readable date string.
+ * @param {number|null|undefined} ts
+ * @returns {string}
+ */
+function formatDate(ts) {
+  if (ts == null) return '–';
+  return new Date(ts)
+    .toISOString()
+    .replace('T', ' ')
+    .replace(/\.\d{3}Z$/, '');
+}
+
+/**
+ * Escape pipe characters in table cell values.
+ * @param {*} val
+ * @returns {string}
+ */
+function cell(val) {
+  if (val == null) return '–';
+  return String(val).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+
+/**
+ * Normalize a list_jobs response.
+ * @param {{ totalNumber: number, page: number, result: object[] }} queryResult
+ * @param {{ page: number, pageSize: number }} params
+ * @returns {{ content: Array }}
+ */
+export function normalizeListJobs(queryResult, { page, pageSize }) {
+  const maxPage = Math.max(1, Math.ceil(queryResult.totalNumber / pageSize));
+  const hasMore = page < maxPage;
+  const jobs = queryResult.result;
+
+  let md = `**Tool:** list_jobs | **Status:** OK\n\n`;
+  md += `Found **${queryResult.totalNumber}** job(s). Showing page ${page} of ${maxPage} (${jobs.length} on this page).`;
+  if (hasMore) md += ` More pages available - use page=${page + 1} to continue.`;
+  md += '\n\n';
+
+  if (jobs.length > 0) {
+    md += `| ID | Name | Enabled | Active Listings |\n`;
+    md += `|----|------|---------|----------------|\n`;
+    for (const j of jobs) {
+      md += `| ${cell(j.id)} | ${cell(j.name)} | ${j.enabled ? 'yes' : 'no'} | ${j.numberOfFoundListings ?? 0} |\n`;
+    }
+  } else {
+    md += `No jobs found.\n`;
+  }
+
+  md += `\n**Page:** ${page}/${maxPage} | **Has more:** ${hasMore ? 'yes' : 'no'}`;
+  return toMcpResponse(md);
+}
+
+/**
+ * Normalize a get_job response.
+ * @param {object} job - The job object from storage.
+ * @returns {{ content: Array }}
+ */
+export function normalizeGetJob(job) {
+  const providers = (job.provider ?? []).map((p) => p.id || p);
+
+  let md = `**Tool:** get_job | **Status:** OK\n\n`;
+  md += `### Job: ${job.name || job.id}\n\n`;
+  md += `- **ID:** ${job.id}\n`;
+  md += `- **Name:** ${job.name || '–'}\n`;
+  md += `- **Enabled:** ${job.enabled ? 'yes' : 'no'}\n`;
+  md += `- **Active Listings:** ${job.numberOfFoundListings ?? 0}\n`;
+  md += `- **Providers:** ${providers.length > 0 ? providers.join(', ') : '–'}\n`;
+  md += `- **Blacklist:** ${(job.blacklist ?? []).length > 0 ? job.blacklist.join(', ') : '–'}\n`;
+
+  return toMcpResponse(md);
+}
+
+/**
+ * Normalize a list_listings response.
+ * @param {{ totalNumber: number, page: number, result: object[] }} queryResult
+ * @param {{ page: number, pageSize: number }} params
+ * @returns {{ content: Array }}
+ */
+export function normalizeListListings(queryResult, { page, pageSize }) {
+  const maxPage = Math.max(1, Math.ceil(queryResult.totalNumber / pageSize));
+  const hasMore = page < maxPage;
+  const listings = queryResult.result;
+
+  let md = `**Tool:** list_listings | **Status:** OK\n\n`;
+  md += `Found **${queryResult.totalNumber}** listing(s). Showing page ${page} of ${maxPage} (${listings.length} on this page).`;
+  if (hasMore) md += ` More pages available - use page=${page + 1} to continue.`;
+  md += '\n\n';
+
+  if (listings.length > 0) {
+    md += `| ID | Title | Address | Price | Size | Provider | Active | Status | Created | Job |\n`;
+    md += `|----|-------|---------|-------|------|----------|--------|--------|---------|-----|\n`;
+    for (const l of listings) {
+      md += `| ${cell(l.id)} | ${cell(l.title)} | ${cell(l.address)} | ${cell(l.price)} | ${cell(l.size)} | ${cell(l.provider)} | ${l.is_active ? 'yes' : 'no'} | ${cell(l.status?.status)} | ${formatDate(l.created_at)} | ${cell(l.job_name)} |\n`;
+    }
+    md += `\nUse **get_listing** with an ID for full details (description, link, image).\n`;
+  } else {
+    md += `No listings found.\n`;
+  }
+
+  md += `\n**Page:** ${page}/${maxPage} | **Has more:** ${hasMore ? 'yes' : 'no'}`;
+  return toMcpResponse(md);
+}
+
+/**
+ * Normalize a get_listing response.
+ * @param {object} listing - The listing object from storage.
+ * @returns {{ content: Array }}
+ */
+export function normalizeGetListing(listing) {
+  let md = `**Tool:** get_listing | **Status:** OK\n\n`;
+  md += `### Listing: ${listing.title || listing.id}\n\n`;
+  md += `- **ID:** ${listing.id}\n`;
+  md += `- **Title:** ${listing.title || '–'}\n`;
+  md += `- **Description:** ${listing.description || '–'}\n`;
+  md += `- **Address:** ${listing.address || '–'}\n`;
+  md += `- **Price:** ${listing.price ?? '–'}\n`;
+  md += `- **Size:** ${listing.size ?? '–'}\n`;
+  md += `- **Provider:** ${listing.provider || '–'}\n`;
+  md += `- **Link:** ${listing.link || '–'}\n`;
+  md += `- **Image:** ${listing.image_url || '–'}\n`;
+  md += `- **Active:** ${listing.is_active ? 'yes' : 'no'}\n`;
+  md += `- **Status:** ${listing.status?.status || '–'}\n`;
+  if (listing.status?.setAt) {
+    md += `- **Status set at:** ${formatDate(listing.status.setAt)}\n`;
+  }
+  md += `- **Created:** ${formatDate(listing.created_at)}\n`;
+  md += `- **Job:** ${listing.job_name || '–'}\n`;
+  if (listing.latitude != null && listing.longitude != null) {
+    md += `- **Location:** ${listing.latitude}, ${listing.longitude}\n`;
+  }
+  if (listing.distance_to_destination != null) {
+    md += `- **Distance to destination:** ${listing.distance_to_destination}\n`;
+  }
+
+  return toMcpResponse(md);
+}
+
+/**
+ * Normalize an error response.
+ * @param {string} message - The error message.
+ * @param {string} [tool] - Optional tool name for context.
+ * @returns {{ content: Array, isError: boolean }}
+ */
+export function normalizeError(message, tool) {
+  const md = `**Tool:** ${tool ?? 'unknown'} | **Status:** ERROR\n\n${message}`;
+  return toMcpResponse(md, true);
+}

lib/mcp/stdio.js

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+/**
+ * Fredy MCP Server – stdio transport
+ *
+ * Launches the MCP server over stdin/stdout so that local LLM clients
+ * (e.g. Claude Desktop, llm-cli, mcp-cli) can connect directly.
+ *
+ * Usage:
+ *   MCP_TOKEN=fredy_<your-token> node mcp/stdio.js
+ *
+ * The MCP_TOKEN environment variable must contain a valid Fredy MCP token.
+ * Each user has a permanent, non-expiring token shown in the user management list.
+ */
+import { fileURLToPath } from 'url';
+import path from 'path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import SqliteConnection from '../services/storage/SqliteConnection.js';
+import { runMigrations } from '../services/storage/migrations/migrate.js';
+import { createMcpServer } from './mcpAdapter.js';
+import { validateMcpToken } from '../services/storage/userStorage.js';
+
+// Ensure cwd is the project root so that relative DB/config paths resolve correctly
+// (LM Studio and other MCP hosts may spawn this process from an arbitrary directory)
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+process.chdir(path.resolve(__dirname, '..', '..'));
+
+// Initialize the database (required for standalone usage)
+await SqliteConnection.init();
+await runMigrations();
+
+const token = process.env.MCP_TOKEN;
+if (!token) {
+  process.stderr.write('Error: MCP_TOKEN environment variable is required.\n');
+  process.stderr.write('Each user has a permanent MCP token shown in the user management list.\n');
+  process.exit(1);
+}
+
+const auth = validateMcpToken(token);
+if (!auth) {
+  process.stderr.write('Error: Invalid MCP_TOKEN. Token not found or user no longer exists.\n');
+  process.exit(1);
+}
+
+const mcpServer = createMcpServer();
+
+// Wrap the stdio transport to inject authInfo into every message
+const transport = new StdioServerTransport();
+
+// Patch: the MCP SDK passes authInfo through the transport's onmessage extra param.
+// For stdio we inject the resolved user from the token.
+const patchedTransport = new Proxy(transport, {
+  set(target, prop, value) {
+    if (prop === 'onmessage') {
+      target.onmessage = (message, extra) => {
+        value(message, { ...extra, authInfo: { userId: auth.userId } });
+      };
+      return true;
+    }
+    target[prop] = value;
+    return true;
+  },
+  get(target, prop) {
+    return target[prop];
+  },
+});
+
+await mcpServer.connect(patchedTransport);
+process.stderr.write('Fredy MCP Server running on stdio\n');

lib/notification/adapter/apprise.js

@@ -1,14 +1,20 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { markdown2Html } from '../../services/markdown.js';
 import { getJob } from '../../services/storage/jobStorage.js';
 import fetch from 'node-fetch';
 
-export const send = ({ serviceName, newListings, notificationConfig, jobKey }) => {
+export const send = ({ serviceName, newListings, notificationConfig, jobKey, baseUrl }) => {
   const { server } = notificationConfig.find((adapter) => adapter.id === config.id).fields;
   const job = getJob(jobKey);
   const jobName = job == null ? jobKey : job.name;
   const promises = newListings.map((newListing) => {
     const title = `${jobName} at ${serviceName}: ${newListing.title}`;
-    const message = `Address: ${newListing.address}\nSize: ${newListing.size}\nPrice: ${newListing.price}\nLink: ${newListing.link}`;
+    const fredyLine = baseUrl && newListing.id ? `\nOpen in Fredy: ${baseUrl}/#/listings/listing/${newListing.id}` : '';
+    const message = `Address: ${newListing.address}\nSize: ${newListing.size}\nPrice: ${newListing.price}\nLink: ${newListing.link}${fredyLine}`;
     return fetch(server, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },

lib/notification/adapter/console.js

@@ -1,8 +1,22 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { markdown2Html } from '../../services/markdown.js';
 
-export const send = ({ serviceName, newListings, jobKey }) => {
+export const send = ({ serviceName, newListings, jobKey, baseUrl }) => {
   /* eslint-disable no-console */
-  return [Promise.resolve(console.info(`Found entry from service ${serviceName}, Job: ${jobKey}:`, newListings))];
+  const fredyLinks = baseUrl ? newListings.map((l) => `${baseUrl}/#/listings/listing/${l.id}`).join(', ') : null;
+  return [
+    Promise.resolve(
+      console.info(
+        `Found entry from service ${serviceName}, Job: ${jobKey}:`,
+        newListings,
+        ...(fredyLinks ? [`Open in Fredy: ${fredyLinks}`] : []),
+      ),
+    ),
+  ];
   /* eslint-enable no-console */
 };
 export const config = {

lib/notification/adapter/discord_webhook.js

@@ -1,7 +1,13 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import fetch from 'node-fetch';
 import { getJob } from '../../services/storage/jobStorage.js';
 import { markdown2Html } from '../../services/markdown.js';
 import { normalizeImageUrl } from '../../utils.js';
+import logger from '../../services/logger.js';
 
 /**
  * Generates an idempotent decimal color code. The input string-based color code is
@@ -34,9 +40,10 @@ const generateColorFromString = (str) => {
  *
  * @param {string} jobKey - Key of job (used to set embed color)
  * @param {object} listing - Object holding listing details
+ * @param baseUrl
  * @returns {object} Discord webhook embed
  */
-const buildEmbed = (jobKey, listing) => {
+const buildEmbed = (jobKey, listing, baseUrl) => {
   const maxTitleLength = 252; // Max embed title length is 256 characters
   let title = String(listing.title ?? 'N/A');
   if (title.length > maxTitleLength) {
@@ -61,11 +68,19 @@ const buildEmbed = (jobKey, listing) => {
     },
   ];
 
+  if (baseUrl && listing.id) {
+    fields.push({
+      name: 'Open in Fredy',
+      value: `[Open in Fredy](${baseUrl}/#/listings/listing/${listing.id})`,
+      inline: false,
+    });
+  }
+
   const embed = {
     title: title,
     color: generateColorFromString(jobKey),
     url: listing.link,
-    fields: fields,
+    fields,
   };
 
   if (listing.image) {
@@ -77,7 +92,7 @@ const buildEmbed = (jobKey, listing) => {
   return embed;
 };
 
-export const send = ({ serviceName, newListings, notificationConfig, jobKey }) => {
+export const send = ({ serviceName, newListings, notificationConfig, jobKey, baseUrl }) => {
   const adapter = notificationConfig.find((adapter) => adapter.id === config.id);
   const webhookUrl = adapter?.fields?.webhookUrl;
   if (!webhookUrl || newListings.length === 0) return Promise.resolve([]);
@@ -85,7 +100,7 @@ export const send = ({ serviceName, newListings, notificationConfig, jobKey }) =
   const job = getJob(jobKey);
   const jobName = job?.name || jobKey;
 
-  const embeds = newListings.map((listing) => buildEmbed(jobKey, listing));
+  const embeds = newListings.map((listing) => buildEmbed(jobKey, listing, baseUrl));
 
   const maxEmbedsPerMessage = 10; // Discord only allows up to 10 embeds
   const webhookPromises = [];
@@ -105,7 +120,7 @@ export const send = ({ serviceName, newListings, notificationConfig, jobKey }) =
       headers: { 'Content-Type': 'application/json' },
       body,
     }).catch((error) => {
-      console.error(`Error sending Discord webhook for chunk starting at ${i}:`, error);
+      logger.error(`Error sending Discord webhook for chunk starting at ${i}:`, error);
       return Promise.reject(new Error(`Webhook failed: ${error.message}`));
     });
 

lib/notification/adapter/http.js

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import { markdown2Html } from '../../services/markdown.js';
+
+const mapListing = (listing, baseUrl) => ({
+  address: listing.address,
+  description: listing.description,
+  id: listing.id,
+  imageUrl: listing.image,
+  price: listing.price,
+  size: listing.size,
+  title: listing.title,
+  url: listing.link,
+  fredyUrl: baseUrl && listing.id ? `${baseUrl}/listings/listing/${listing.id}` : null,
+});
+
+export const send = async ({ serviceName, newListings, notificationConfig, jobKey, baseUrl }) => {
+  const { authToken, endpointUrl, selfSignedCerts } = notificationConfig.find((a) => a.id === config.id).fields;
+
+  const listings = newListings.map((l) => mapListing(l, baseUrl));
+  const body = {
+    jobId: jobKey,
+    timestamp: new Date().toISOString(),
+    provider: serviceName,
+    listings,
+  };
+
+  const headers = {
+    'Content-Type': 'application/json',
+  };
+  if (authToken != null) {
+    headers['Authorization'] = `Bearer ${authToken}`;
+  }
+
+  let fetchOptions = {
+    method: 'POST',
+    headers,
+    timeout: 10000,
+    body: JSON.stringify(body),
+  };
+
+  if (selfSignedCerts === true) {
+    fetchOptions.dispatcher = new (await import('undici')).Agent({
+      connect: { rejectUnauthorized: false },
+    });
+  }
+
+  return fetch(endpointUrl, fetchOptions);
+};
+
+export const config = {
+  id: 'http',
+  name: 'HTTP',
+  readme: markdown2Html('lib/notification/adapter/http.md'),
+  description: 'Fredy will send a generic HTTP POST request.',
+  fields: {
+    endpointUrl: {
+      description: "Your application's endpoint URL.",
+      label: 'Endpoint URL',
+      type: 'text',
+    },
+    selfSignedCerts: {
+      label: 'Self-signed certificates',
+      type: 'boolean',
+    },
+    authToken: {
+      description: "Your application's auth token, if required by your endpoint.",
+      label: 'Auth token (optional)',
+      optional: true,
+      type: 'text',
+    },
+  },
+};

lib/notification/adapter/http.md

@@ -0,0 +1,43 @@
+### HTTP Adapter
+
+This is a generic adapter for sending notifications via HTTP requests.
+You can leverage this adapter to integrate with various webhooks or APIs that accept HTTP requests. (e.g. Supabase
+Functions, a Node.js server, etc.)
+
+HTTP adapter supports a `authToken` field, which can be used to include an authorization token in the request headers.
+Your token would be included as a Bearer token in the `Authorization` header, which is a common method for securing API requests.
+
+Request Details:
+<details>
+Request Method: POST  
+
+Headers:
+
+```
+Content Type: `application/json`
+Authorization: Bearer {your-optional-auth-token}
+```
+
+Body:
+
+```json
+{
+  "jobId": "mg1waX4RHmIzL5NDYtYp-",
+  "provider": "immoscout",
+  "timestamp": "2024-06-15T12:34:56Z",
+  "listings": [
+    {
+      "address": "Str. 123, Bielefeld, Germany",
+      "description": "Möbliert: Einziehen & wohlfühlen: Neu möbliert.",
+      "id": "123456789",
+      "imageUrl": "https://<target-url>.com/listings/123456789.jpg",
+      "price": "1.240 €",
+      "size": "38 m²",
+      "title": "Schöne 1-Zimmer-Wohnung in Bielefeld",
+      "url": "https://<target-url>.com/listings/123456789"
+    }
+  ]
+}
+```
+
+</details>

lib/notification/adapter/mailJet.js

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import mailjet from 'node-mailjet';
 import path from 'path';
 import fs from 'fs';
@@ -30,7 +35,7 @@ const toBase64 = async (url) => {
   }
 };
 
-const mapListingsWithCid = async (serviceName, jobKey, listings) => {
+const mapListingsWithCid = async (serviceName, jobKey, listings, baseUrl) => {
   const out = [];
   const attachments = [];
 
@@ -48,6 +53,7 @@ const mapListingsWithCid = async (serviceName, jobKey, listings) => {
       jobKey,
       hasImage: false,
       imageCid: '',
+      fredyUrl: baseUrl && l.id ? `${baseUrl}/listings/listing/${l.id}` : null,
     };
 
     if (imgUrl) {
@@ -73,7 +79,7 @@ const mapListingsWithCid = async (serviceName, jobKey, listings) => {
   return { listings: out, attachments };
 };
 
-export const send = async ({ serviceName, newListings, notificationConfig, jobKey }) => {
+export const send = async ({ serviceName, newListings, notificationConfig, jobKey, baseUrl }) => {
   const { apiPublicKey, apiPrivateKey, receiver, from } = notificationConfig.find(
     (adapter) => adapter.id === config.id,
   ).fields;
@@ -84,7 +90,7 @@ export const send = async ({ serviceName, newListings, notificationConfig, jobKe
     .map((r) => ({ Email: r.trim() }))
     .filter((r) => r.Email.length > 0);
 
-  const { listings, attachments } = await mapListingsWithCid(serviceName, jobKey, newListings);
+  const { listings, attachments } = await mapListingsWithCid(serviceName, jobKey, newListings, baseUrl);
 
   const html = emailTemplate({
     serviceName: `Job: (${jobKey}) | Service: ${serviceName}`,

lib/notification/adapter/mattermost.js

@@ -1,15 +1,25 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { markdown2Html } from '../../services/markdown.js';
 import { getJob } from '../../services/storage/jobStorage.js';
 import fetch from 'node-fetch';
-export const send = ({ serviceName, newListings, notificationConfig, jobKey }) => {
+export const send = ({ serviceName, newListings, notificationConfig, jobKey, baseUrl }) => {
   const { webhook, channel } = notificationConfig.find((adapter) => adapter.id === config.id).fields;
   const job = getJob(jobKey);
   const jobName = job == null ? jobKey : job.name;
   let message = `### *${jobName}* (${serviceName}) found **${newListings.length}** new listings:\n\n`;
-  message += `| Title | Address | Size | Price |\n|:----|:----|:----|:----|\n`;
-  message += newListings.map(
-    (o) => `| [${o.title}](${o.link}) | ` + [o.address, o.size.replace(/2m/g, '$m^2$'), o.price].join(' | ') + ' |\n',
-  );
+  message += `| Title | Address | Size | Price |${baseUrl ? ' Open in Fredy |' : ''}\n|:----|:----|:----|:----|${baseUrl ? ':----|\n' : '\n'}`;
+  message += newListings.map((o) => {
+    const fredyCell = baseUrl && o.id ? ` [Open in Fredy](${baseUrl}/#/listings/listing/${o.id}) |` : '';
+    return (
+      `| [${o.title}](${o.link}) | ` +
+      [o.address, o.size.replace(/2m/g, '$m^2$'), o.price].join(' | ') +
+      ` |${fredyCell}\n`
+    );
+  });
   return fetch(webhook, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },

lib/notification/adapter/ntfy.js

@@ -1,19 +1,25 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { markdown2Html } from '../../services/markdown.js';
 import { getJob } from '../../services/storage/jobStorage.js';
 import fetch from 'node-fetch';
 import { normalizeImageUrl } from '../../utils.js';
 
-export const send = ({ serviceName, newListings, notificationConfig, jobKey }) => {
+export const send = ({ serviceName, newListings, notificationConfig, jobKey, baseUrl }) => {
   const { priority, server, topic } = notificationConfig.find((adapter) => adapter.id === config.id).fields;
   const job = getJob(jobKey);
   const jobName = job == null ? jobKey : job.name;
 
   const promises = newListings.map((newListing) => {
+    const fredyLine = baseUrl && newListing.id ? `\nOpen in Fredy: ${baseUrl}/#/listings/listing/${newListing.id}` : '';
     const message = `
 Address: ${newListing.address}
 Size: ${newListing.size == null ? 'N/A' : newListing.size.replace(/2m/g, '$m^2$')}
 Price: ${newListing.price}
-Link: ${newListing.link}`;
+Link: ${newListing.link}${fredyLine}`;
 
     const sanitizeHeaderValue = (value) =>
       String(value ?? '')

lib/notification/adapter/pushover.js

@@ -1,8 +1,13 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { markdown2Html } from '../../services/markdown.js';
 import { getJob } from '../../services/storage/jobStorage.js';
 import fetch from 'node-fetch';
 
-export const send = async ({ serviceName, newListings, notificationConfig, jobKey }) => {
+export const send = async ({ serviceName, newListings, notificationConfig, jobKey, baseUrl }) => {
   const { token, user, device } = notificationConfig.find((adapter) => adapter.id === config.id).fields;
   const job = getJob(jobKey);
   const jobName = job == null ? jobKey : job.name;
@@ -10,7 +15,9 @@ export const send = async ({ serviceName, newListings, notificationConfig, jobKe
   const results = await Promise.all(
     newListings.map(async (newListing) => {
       const title = `${jobName} at ${serviceName}: ${newListing.title}`;
-      const message = `Address: ${newListing.address}\nSize: ${newListing.size}\nPrice: ${newListing.price}\nLink: ${newListing.link}`;
+      const fredyLine =
+        baseUrl && newListing.id ? `\nOpen in Fredy: ${baseUrl}/#/listings/listing/${newListing.id}` : '';
+      const message = `Address: ${newListing.address}\nSize: ${newListing.size}\nPrice: ${newListing.price}\nLink: ${newListing.link}${fredyLine}`;
 
       const form = new FormData();
       form.append('token', token);

lib/notification/adapter/resend.js

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import { Resend } from 'resend';
+import path from 'path';
+import fs from 'fs';
+import Handlebars from 'handlebars';
+import { markdown2Html } from '../../services/markdown.js';
+import { getDirName, normalizeImageUrl } from '../../utils.js';
+
+const __dirname = getDirName();
+const template = fs.readFileSync(path.resolve(__dirname + '/notification/emailTemplate/template.hbs'), 'utf8');
+const emailTemplate = Handlebars.compile(template);
+
+const mapListings = (serviceName, jobKey, listings, baseUrl) =>
+  listings.map((l) => {
+    const image = normalizeImageUrl(l.image);
+    return {
+      title: l.title || '',
+      link: l.link || '',
+      address: l.address || '',
+      size: l.size || '',
+      price: l.price || '',
+      image,
+      hasImage: Boolean(image),
+      fredyUrl: baseUrl && l.id ? `${baseUrl}/listings/listing/${l.id}` : null,
+      serviceName,
+      jobKey,
+    };
+  });
+
+export const send = async ({ serviceName, newListings, notificationConfig, jobKey, baseUrl }) => {
+  const { apiKey, receiver, from } = notificationConfig.find((adapter) => adapter.id === config.id).fields;
+
+  const to = receiver
+    .trim()
+    .split(',')
+    .map((r) => r.trim())
+    .filter(Boolean);
+
+  const resend = new Resend(apiKey);
+
+  const listings = mapListings(serviceName, jobKey, newListings, baseUrl);
+
+  const html = emailTemplate({
+    serviceName: `Job: (${jobKey}) | Service: ${serviceName}`,
+    numberOfListings: listings.length,
+    listings,
+  });
+
+  const { error } = await resend.emails.send({
+    from,
+    to,
+    subject: `Fredy found ${listings.length} new listing(s) for ${serviceName}`,
+    html,
+  });
+
+  if (!error) {
+    return Promise.resolve();
+  } else {
+    return Promise.reject(error.message);
+  }
+};
+
+export const config = {
+  id: 'resend',
+  name: 'Resend',
+  description: 'Resend is being used to send new listings via mail.',
+  readme: markdown2Html('lib/notification/adapter/resend.md'),
+  fields: {
+    apiKey: {
+      type: 'text',
+      label: 'Api Key',
+      description: 'The Resend API key used to send emails.',
+    },
+    receiver: {
+      type: 'email',
+      label: 'Receiver Email',
+      description: 'Comma-separated email addresses Fredy will send notifications to.',
+    },
+    from: {
+      type: 'email',
+      label: 'Sender Email',
+      description: 'The verified email address or domain you send from in Resend.',
+    },
+  },
+};

lib/notification/adapter/resend.md

@@ -0,0 +1,17 @@
+### Resend Adapter
+
+Resend is a modern email delivery service that Fredy can use to send notifications.
+
+Setup:
+- Create a Resend account: https://resend.com/
+- Create an API key and add it to Fredy's configuration.
+- Choose the sender address (e.g., you@yourdomain.com). Verify the domain (https://resend.com/domains/) in Resend before using it.
+- Optional for local testing: you can use `onboarding@resend.dev`, but Resend may restrict who you can send to when using test domains.
+
+Multiple recipients:
+- Separate email addresses with commas (e.g., some@email.com, someOther@email.com).
+
+Notes & Troubleshooting:
+- Ensure the `from` address is verified or belongs to a verified domain in Resend.
+- If emails don't arrive, check your spam folder and Resend dashboard logs.
+- The template displays listing images via their public URLs; make sure images are reachable.

lib/notification/adapter/sendGrid.js

@@ -1,8 +1,13 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import sgMail from '@sendgrid/mail';
 import { markdown2Html } from '../../services/markdown.js';
 import { normalizeImageUrl } from '../../utils.js';
 
-const mapListings = (serviceName, jobKey, listings) =>
+const mapListings = (serviceName, jobKey, listings, baseUrl) =>
   listings.map((l) => {
     const image = normalizeImageUrl(l.image);
     return {
@@ -15,12 +20,13 @@ const mapListings = (serviceName, jobKey, listings) =>
       hasImage: Boolean(image),
       // optional plain text snippet
       snippet: [l.address, l.price, l.size].filter(Boolean).join(' | '),
+      fredyUrl: baseUrl && l.id ? `${baseUrl}/listings/listing/${l.id}` : null,
       serviceName,
       jobKey,
     };
   });
 
-export const send = ({ serviceName, newListings, notificationConfig, jobKey }) => {
+export const send = ({ serviceName, newListings, notificationConfig, jobKey, baseUrl }) => {
   const { apiKey, receiver, from, templateId } = notificationConfig.find((adapter) => adapter.id === config.id).fields;
 
   sgMail.setApiKey(apiKey);
@@ -31,7 +37,7 @@ export const send = ({ serviceName, newListings, notificationConfig, jobKey }) =
     .map((r) => r.trim())
     .filter(Boolean);
 
-  const listings = mapListings(serviceName, jobKey, newListings);
+  const listings = mapListings(serviceName, jobKey, newListings, baseUrl);
 
   const msg = {
     templateId,

lib/notification/adapter/slack.js

@@ -1,8 +1,13 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import Slack from 'slack';
 import { markdown2Html } from '../../services/markdown.js';
 import { normalizeImageUrl } from '../../utils.js';
 
-const buildBlocks = (serviceName, jobKey, p) => {
+const buildBlocks = (serviceName, jobKey, p, baseUrl) => {
   const blocks = [
     {
       type: 'header',
@@ -31,6 +36,13 @@ const buildBlocks = (serviceName, jobKey, p) => {
     });
   }
 
+  if (baseUrl && p.id) {
+    blocks.push({
+      type: 'section',
+      text: { type: 'mrkdwn', text: `<${baseUrl}/#/listings/listing/${p.id}|Open in Fredy>` },
+    });
+  }
+
   blocks.push({
     type: 'context',
     elements: [{ type: 'mrkdwn', text: 'Powered by Fredy' }],
@@ -39,7 +51,7 @@ const buildBlocks = (serviceName, jobKey, p) => {
   return blocks;
 };
 
-export const send = ({ serviceName, newListings, notificationConfig, jobKey }) => {
+export const send = ({ serviceName, newListings, notificationConfig, jobKey, baseUrl }) => {
   const { token, channel } = notificationConfig.find((a) => a.id === config.id).fields;
 
   return Promise.allSettled(
@@ -48,7 +60,7 @@ export const send = ({ serviceName, newListings, notificationConfig, jobKey }) =
         token,
         channel,
         text: `${serviceName} ${jobKey}: ${p.title}`,
-        blocks: buildBlocks(serviceName, jobKey, p),
+        blocks: buildBlocks(serviceName, jobKey, p, baseUrl),
         unfurl_links: false,
         unfurl_media: false,
       }),

lib/notification/adapter/slack_with_webhooks.js

@@ -1,8 +1,13 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import fetch from 'node-fetch';
 import { markdown2Html } from '../../services/markdown.js';
 import { normalizeImageUrl } from '../../utils.js';
 
-const buildBlocks = (serviceName, jobKey, p) => {
+const buildBlocks = (serviceName, jobKey, p, baseUrl) => {
   const blocks = [
     {
       type: 'header',
@@ -31,6 +36,13 @@ const buildBlocks = (serviceName, jobKey, p) => {
     });
   }
 
+  if (baseUrl && p.id) {
+    blocks.push({
+      type: 'section',
+      text: { type: 'mrkdwn', text: `<${baseUrl}/#/listings/listing/${p.id}|Open in Fredy>` },
+    });
+  }
+
   blocks.push({
     type: 'context',
     elements: [{ type: 'mrkdwn', text: 'Powered by Fredy' }],
@@ -46,7 +58,7 @@ const postJson = (url, body) =>
     body,
   });
 
-export const send = ({ serviceName, newListings, notificationConfig, jobKey }) => {
+export const send = ({ serviceName, newListings, notificationConfig, jobKey, baseUrl }) => {
   const adapter = notificationConfig.find((a) => a.id === config.id);
   const webhookUrl = adapter?.fields?.webhookUrl;
   if (!webhookUrl) return Promise.resolve([]);
@@ -54,7 +66,7 @@ export const send = ({ serviceName, newListings, notificationConfig, jobKey }) =
   const promises = newListings.map((p) => {
     const body = JSON.stringify({
       text: `${serviceName} ${jobKey}: ${p.title}`,
-      blocks: buildBlocks(serviceName, jobKey, p),
+      blocks: buildBlocks(serviceName, jobKey, p, baseUrl),
       unfurl_links: false,
       unfurl_media: false,
     });

lib/notification/adapter/smtp.js

@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import nodemailer from 'nodemailer';
+import path from 'path';
+import fs from 'fs';
+import Handlebars from 'handlebars';
+import { markdown2Html } from '../../services/markdown.js';
+import { getDirName, normalizeImageUrl } from '../../utils.js';
+
+const __dirname = getDirName();
+const template = fs.readFileSync(path.resolve(__dirname + '/notification/emailTemplate/template.hbs'), 'utf8');
+const emailTemplate = Handlebars.compile(template);
+
+const mapListings = (serviceName, jobKey, listings, baseUrl) =>
+  listings.map((l) => {
+    const image = normalizeImageUrl(l.image);
+    return {
+      title: l.title || '',
+      link: l.link || '',
+      address: l.address || '',
+      size: l.size || '',
+      price: l.price || '',
+      image,
+      hasImage: Boolean(image),
+      fredyUrl: baseUrl && l.id ? `${baseUrl}/listings/listing/${l.id}` : null,
+      serviceName,
+      jobKey,
+    };
+  });
+
+export const send = async ({ serviceName, newListings, notificationConfig, jobKey, baseUrl }) => {
+  const { host, port, secure, username, password, receiver, from } = notificationConfig.find(
+    (adapter) => adapter.id === config.id,
+  ).fields;
+
+  const to = receiver
+    .trim()
+    .split(',')
+    .map((r) => r.trim())
+    .filter(Boolean);
+
+  const transporter = nodemailer.createTransport({
+    host,
+    port: Number(port),
+    secure: secure === 'true',
+    auth: {
+      user: username,
+      pass: password,
+    },
+  });
+
+  const listings = mapListings(serviceName, jobKey, newListings, baseUrl);
+
+  const html = emailTemplate({
+    serviceName: `Job: (${jobKey}) | Service: ${serviceName}`,
+    numberOfListings: listings.length,
+    listings,
+  });
+
+  return transporter.sendMail({
+    from,
+    to: to.join(','),
+    subject: `Fredy found ${listings.length} new listing(s) for ${serviceName}`,
+    html,
+  });
+};
+
+export const config = {
+  id: 'smtp',
+  name: 'SMTP',
+  description: 'Send notifications via any SMTP server using Nodemailer.',
+  readme: markdown2Html('lib/notification/adapter/smtp.md'),
+  fields: {
+    host: {
+      type: 'text',
+      label: 'SMTP Host',
+      description: 'The hostname of the SMTP server (e.g., smtp.gmail.com).',
+    },
+    port: {
+      type: 'text',
+      label: 'SMTP Port',
+      description: 'The port of the SMTP server (e.g., 587 for STARTTLS, 465 for SSL).',
+    },
+    secure: {
+      type: 'text',
+      label: 'Secure (SSL/TLS)',
+      description: 'Set to "true" for port 465 (SSL). Leave empty or "false" for STARTTLS on port 587.',
+    },
+    username: {
+      type: 'text',
+      label: 'Username',
+      description: 'The username for SMTP authentication.',
+    },
+    password: {
+      type: 'text',
+      label: 'Password',
+      description: 'The password (or app password) for SMTP authentication.',
+    },
+    receiver: {
+      type: 'text',
+      label: 'Receiver Email(s)',
+      description: 'Comma-separated email addresses Fredy will send notifications to.',
+    },
+    from: {
+      type: 'email',
+      label: 'Sender Email',
+      description: 'The email address Fredy sends from.',
+    },
+  },
+};

lib/notification/adapter/smtp.md

@@ -0,0 +1,23 @@
+### SMTP Adapter
+
+Send notifications through any SMTP server using [Nodemailer](https://nodemailer.com/).
+This works with Gmail, Outlook, self-hosted mail servers, or any provider that supports SMTP.
+
+Setup:
+
+- Provide the SMTP host and port of your mail server.
+- For **SSL/TLS** (port 465), set Secure to `true`.
+- For **STARTTLS** (port 587), leave Secure empty or set it to `false`.
+- Enter the username and password for authentication. For Gmail, use an [App Password](https://support.google.com/accounts/answer/185833).
+- Set the sender email address (must be allowed by your SMTP server).
+
+Multiple recipients:
+
+- Separate email addresses with commas (e.g., `some@email.com`, `someOther@email.com`).
+
+Common SMTP settings:
+
+- **Gmail** - `smtp.gmail.com`, port 587, secure: false
+- **Outlook** - `smtp.office365.com`, port 587, secure: false
+- **Yahoo** - `smtp.mail.yahoo.com`, port 465, secure: true
+- **Gmx** - `mail.gmx.net`, port 587, secure: true

lib/notification/adapter/sqlite.js

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { markdown2Html } from '../../services/markdown.js';
 import Database from 'better-sqlite3';
 import path from 'path';

lib/notification/adapter/telegram.js

@@ -1,46 +1,56 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { markdown2Html } from '../../services/markdown.js';
 import { getJob } from '../../services/storage/jobStorage.js';
 import fetch from 'node-fetch';
 import pThrottle from 'p-throttle';
 import { normalizeImageUrl } from '../../utils.js';
 import logger from '../../services/logger.js';
+import { shouldUseMultipart, buildPhotoFormData } from './telegramPhotoUploader.js';
 
 const RATE_LIMIT_INTERVAL = 1000;
+const THROTTLE_MAX_IDLE_MS = RATE_LIMIT_INTERVAL + 2000;
 const chatThrottleMap = new Map();
 
 /**
  * Removes stale throttled call entries to keep memory bounded.
+ * An entry is stale when no API call has fired for longer than THROTTLE_MAX_IDLE_MS.
  */
 function cleanupOldThrottles() {
   const now = Date.now();
-  const maxAge = RATE_LIMIT_INTERVAL + 1000;
-  const toBeDeleted = [];
   for (const [chatId, chatThrottle] of chatThrottleMap.entries()) {
-    if (now - chatThrottle.lastUsedAt > maxAge) toBeDeleted.push(chatId);
+    if (now - chatThrottle.lastUsedAt > THROTTLE_MAX_IDLE_MS) chatThrottleMap.delete(chatId);
   }
-  for (const chatId of toBeDeleted) chatThrottleMap.delete(chatId);
 }
 
 /**
  * Return a throttled wrapper for a chatId to limit Telegram API calls.
  * Uses p-throttle with 1 request per RATE_LIMIT_INTERVAL per chat.
+ * `lastUsedAt` is refreshed on every actual API call so that the idle window
+ * starts from the last fired call, not from when send() was invoked.
  *
- * @template {Function} T
  * @param {string|number} chatId
- * @param {T} call - async function (endpoint: string, body: any) => Promise<Response>
- * @returns {T}
+ * @param {Function} call - async function (endpoint: string, body: any) => Promise<Response>
+ * @returns {Function}
  */
 function getThrottled(chatId, call) {
   cleanupOldThrottles();
-  const now = Date.now();
-  const chatThrottle = chatThrottleMap.get(chatId);
-  if (chatThrottle) {
-    chatThrottle.lastUsedAt = now;
-    return chatThrottle.throttled;
+  const existing = chatThrottleMap.get(chatId);
+  if (existing) {
+    existing.lastUsedAt = Date.now();
+    return existing.throttled;
   }
-  const throttled = pThrottle({ limit: 1, interval: RATE_LIMIT_INTERVAL })(call);
-  chatThrottleMap.set(chatId, { lastUsedAt: now, throttled });
-  return throttled;
+  const entry = { lastUsedAt: Date.now(), throttled: null };
+  chatThrottleMap.set(chatId, entry);
+  entry.throttled = pThrottle({ limit: 1, interval: RATE_LIMIT_INTERVAL })(async (endpoint, body) => {
+    const e = chatThrottleMap.get(chatId);
+    if (e) e.lastUsedAt = Date.now();
+    return call(endpoint, body);
+  });
+  return entry.throttled;
 }
 
 /**
@@ -64,42 +74,150 @@ function escapeHtml(s = '') {
 }
 
 /**
- * Build a Telegram photo caption (max 1024 characters) using HTML parse mode.
+ * Build a Telegram HTML-formatted message body.
+ * Suitable for both sendMessage (uncapped) and sendPhoto captions (caller must slice to 1024).
+ *
  * @param {string} jobName
  * @param {string} serviceName
  * @param {Object} o - Listing object
- * @param {string} [o.title]
- * @param {string} [o.address]
- * @param {string|number} [o.price]
- * @param {string|number} [o.size]
- * @param {string} [o.link]
+ * @param {string} [baseUrl]
  * @returns {string}
  */
-function buildCaption(jobName, serviceName, o) {
-  const title = shorten((o.title || '').replace(/\*/g, ''), 90);
-  const meta = [o.address, o.price, o.size].filter(Boolean).join(' | ');
-  return `<i>${escapeHtml(jobName)}</i> (${escapeHtml(serviceName)})\n<a href='${escapeHtml(
-    o.link || '',
-  )}'><b>${escapeHtml(title)}</b></a>\n${escapeHtml(meta)}`.slice(0, 1024);
-}
-
-/**
- * Build a Telegram message text using HTML parse mode.
- * @param {string} jobName
- * @param {string} serviceName
- * @param {Object} o - Listing object
- * @returns {string}
- */
-function buildText(jobName, serviceName, o) {
+function buildHtmlBody(jobName, serviceName, o, baseUrl) {
   const title = shorten((o.title || '').replace(/\*/g, ''), 90);
   const meta = [o.address, o.price, o.size].filter(Boolean).join(' | ');
+  const fredyLink =
+    baseUrl && o.id ? `\n<a href='${escapeHtml(`${baseUrl}/#/listings/listing/${o.id}`)}'>Open in Fredy</a>` : '';
   return (
     `<i>${escapeHtml(jobName)}</i> (${escapeHtml(serviceName)})\n` +
     `<a href='${escapeHtml(o.link || '')}'><b>${escapeHtml(title)}</b></a>\n` +
-    `${escapeHtml(meta)}`
+    `${escapeHtml(meta)}${fredyLink}`
   );
 }
 
+/**
+ * Build a plain-text Telegram photo caption (max 4096 characters).
+ * Meta appears before the link so the most relevant info is visible within the cap.
+ *
+ * @param {string} jobName
+ * @param {string} serviceName
+ * @param {Object} o - Listing object
+ * @param {string} [baseUrl]
+ * @returns {string}
+ */
+function buildPlainCaption(jobName, serviceName, o, baseUrl) {
+  const title = shorten((o.title || '').replace(/\*/g, ''), 90);
+  const meta = [o.address, o.price, o.size].filter(Boolean).join(' | ');
+  const fredyLine = baseUrl && o.id ? `\nOpen in Fredy: ${baseUrl}/#/listings/listing/${o.id}` : '';
+  return `${jobName} (${serviceName})\n${title}\n${meta}\n\n${o.link || ''}${fredyLine}`.slice(0, 4096);
+}
+
+/**
+ * Build a plain-text Telegram message body.
+ * Link appears early so it is tappable without scrolling.
+ *
+ * @param {string} jobName
+ * @param {string} serviceName
+ * @param {Object} o - Listing object
+ * @param {string} [baseUrl]
+ * @returns {string}
+ */
+function buildPlainText(jobName, serviceName, o, baseUrl) {
+  const title = shorten((o.title || '').replace(/\*/g, ''), 90);
+  const meta = [o.address, o.price, o.size].filter(Boolean).join(' | ');
+  const fredyLine = baseUrl && o.id ? `\nOpen in Fredy: ${baseUrl}/#/listings/listing/${o.id}` : '';
+  return `${jobName} (${serviceName})\n${title}\n${o.link || ''}\n${meta}${fredyLine}`;
+}
+
+/**
+ * Create the raw Telegram API caller for a given bot token.
+ * Handles JSON and multipart (FormData) bodies.
+ *
+ * @param {string} token - Telegram bot token.
+ * @param {string} jobName - Used in error messages.
+ * @returns {(endpoint: string, body: object|FormData) => Promise<Response>}
+ */
+function makeTelegramCaller(token, jobName) {
+  return async function (endpoint, body) {
+    const isFormData = body instanceof FormData;
+    const opts = isFormData
+      ? { method: 'post', body }
+      : { method: 'post', body: JSON.stringify(body), headers: { 'Content-Type': 'application/json' } };
+    const res = await fetch(`https://api.telegram.org/bot${token}/${endpoint}`, opts);
+    if (!res.ok) {
+      const errorBody = await res.text();
+      throw new Error(`API error for '${jobName}'. '${endpoint}' returned ${errorBody}`);
+    }
+    return res;
+  };
+}
+
+/**
+ * Send a single listing to a single Telegram chat, with photo-then-text fallback.
+ *
+ * @param {Function} throttledCall - Throttled Telegram API caller for this chat.
+ * @param {Object} listing - Listing object.
+ * @param {string|number} chatId
+ * @param {Object} opts
+ * @param {string} opts.jobName
+ * @param {string} opts.serviceName
+ * @param {string} opts.baseUrl
+ * @param {boolean} opts.plainText
+ * @param {number|undefined} opts.message_thread_id
+ * @returns {Promise<void>}
+ */
+async function sendListingToChat(
+  throttledCall,
+  listing,
+  chatId,
+  { jobName, serviceName, baseUrl, plainText, message_thread_id },
+) {
+  const img = normalizeImageUrl(listing.image);
+
+  const textPayload = {
+    chat_id: chatId,
+    text: plainText
+      ? buildPlainText(jobName, serviceName, listing, baseUrl)
+      : buildHtmlBody(jobName, serviceName, listing, baseUrl),
+    ...(plainText ? {} : { parse_mode: 'HTML' }),
+    disable_web_page_preview: true,
+    ...(message_thread_id ? { message_thread_id } : {}),
+  };
+
+  if (!img) {
+    return throttledCall('sendMessage', textPayload).catch((e) => {
+      logger.error(`Error sending message to Telegram: ${e.message}`);
+    });
+  }
+
+  const caption = plainText
+    ? buildPlainCaption(jobName, serviceName, listing, baseUrl)
+    : buildHtmlBody(jobName, serviceName, listing, baseUrl).slice(0, 1024);
+  const parseMode = plainText ? undefined : 'HTML';
+
+  // .webp URLs (Immowelt/Cloudimage) fail Telegram's URL-based sendPhoto with
+  // "failed to get HTTP URL content". Upload the bytes via multipart instead.
+  const photoCall = shouldUseMultipart(img)
+    ? buildPhotoFormData({ chatId, imageUrl: img, caption, parseMode, messageThreadId: message_thread_id }).then((fd) =>
+        throttledCall('sendPhoto', fd),
+      )
+    : throttledCall('sendPhoto', {
+        chat_id: chatId,
+        photo: img,
+        caption,
+        ...(parseMode ? { parse_mode: parseMode } : {}),
+        ...(message_thread_id ? { message_thread_id } : {}),
+      });
+
+  return photoCall.catch(async (e) => {
+    logger.warn(`Error sending photo to Telegram and use a fallback: ${e.message}`);
+    return throttledCall('sendMessage', textPayload).catch((e) => {
+      logger.error(`Error sending message to Telegram: ${e.message}`);
+      throw e;
+    });
+  });
+}
+
 /**
  * Send new listings to Telegram.
  * - Respects per-chat Telegram rate limits using a lightweight throttle cache.
@@ -112,16 +230,21 @@ function buildText(jobName, serviceName, o) {
  * @param {string} params.jobKey - Storage job key to resolve the human readable job name.
  * @returns {Promise<Array<Response>>} Promise resolving when all send operations complete.
  */
-export const send = ({ serviceName, newListings = [], notificationConfig, jobKey }) => {
+export const send = ({ serviceName, newListings = [], notificationConfig, jobKey, baseUrl }) => {
   const adapterCfg = notificationConfig.find((adapter) => adapter.id === config.id);
   if (!adapterCfg || !adapterCfg.fields) {
     throw new Error(`Telegram adapter configuration missing for job '${jobKey || ''}'`);
   }
-  const { token, chatId, messageThreadId } = adapterCfg.fields;
+  const { token, chatId, messageThreadId, plainText } = adapterCfg.fields;
   if (!token || !chatId) {
     throw new Error("Telegram 'token' and 'chatId' must be provided in notification config");
   }
 
+  const chatIds = String(chatId)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
   // Optional Telegram topic/thread support (supergroups)
   let message_thread_id;
   if (messageThreadId !== undefined && messageThreadId !== null && `${messageThreadId}`.trim() !== '') {
@@ -138,54 +261,16 @@ export const send = ({ serviceName, newListings = [], notificationConfig, jobKey
   const job = getJob(jobKey);
   const jobName = job == null ? jobKey : job.name;
 
-  const throttledCall = getThrottled(chatId, async function (endpoint, body) {
-    const res = await fetch(`https://api.telegram.org/bot${token}/${endpoint}`, {
-      method: 'post',
-      body: JSON.stringify(body),
-      headers: { 'Content-Type': 'application/json' },
-    });
-
-    if (!res.ok) {
-      const errorBody = await res.text();
-      throw new Error(`API error for '${jobName}'. '${endpoint}' returned ${errorBody}`);
-    }
-    return res;
-  });
-
   if (!Array.isArray(newListings) || newListings.length === 0) return Promise.resolve([]);
 
-  const promises = newListings.map(async (o) => {
-    const img = normalizeImageUrl(o.image);
-    const textPayload = {
-      chat_id: chatId,
-      text: buildText(jobName, serviceName, o),
-      parse_mode: 'HTML',
-      disable_web_page_preview: true,
-      ...(message_thread_id ? { message_thread_id } : {}),
-    };
-
-    if (!img) {
-      return await throttledCall('sendMessage', textPayload).catch(async (e) => {
-        logger.error(`Error sending message to Telegram: ${e.message}`);
-      });
-    }
-
-    return await throttledCall('sendPhoto', {
-      chat_id: chatId,
-      photo: img,
-      caption: buildCaption(jobName, serviceName, o),
-      parse_mode: 'HTML',
-      ...(message_thread_id ? { message_thread_id } : {}),
-    }).catch(async (e) => {
-      logger.error(`Error sending photo to Telegram and use a fallback: ${e.message}`);
-      return await throttledCall('sendMessage', textPayload).catch((e) => {
-        logger.error(`Error sending message to Telegram: ${e.message}`);
-        throw e;
-      });
-    });
+  const allPromises = chatIds.flatMap((id) => {
+    const caller = makeTelegramCaller(token, jobName);
+    const throttledCall = getThrottled(id, caller);
+    const opts = { jobName, serviceName, baseUrl, plainText, message_thread_id };
+    return newListings.map((listing) => sendListingToChat(throttledCall, listing, id, opts));
   });
 
-  return Promise.all(promises);
+  return Promise.all(allPromises);
 };
 
 /**
@@ -206,7 +291,8 @@ export const config = {
     chatId: {
       type: 'chatId',
       label: 'Chat Id',
-      description: 'The chat id to send messages to you.',
+      description:
+        'The chat ID to send messages to. Separate multiple IDs with commas to notify several recipients (e.g. 123456789, 987654321).',
     },
     messageThreadId: {
       type: 'text',
@@ -215,5 +301,11 @@ export const config = {
       description:
         'Optional: The topic/thread id within a supergroup to post into (Telegram message_thread_id). Provide a positive integer.',
     },
+    plainText: {
+      type: 'boolean',
+      optional: true,
+      label: 'Send as plain text',
+      description: 'Send messages as plain text instead of HTML formatted.',
+    },
   },
 };

lib/notification/adapter/telegram.md

@@ -21,6 +21,8 @@ Steps:
    - Private chats: `chat.id` is a positive number
    - Groups/supergroups: `chat.id` is a negative number
 
+**Multiple recipients:** To notify several users individually, enter a comma-separated list of chat IDs in the Chat Id field, e.g. `123456789, 987654321`. Each recipient receives the same messages and gets its own independent rate-limit window. This avoids having to create a group and add the bot to it.
+
 Keep your bot token secret. If `getUpdates` returns an empty list, send a new message and try again, or make sure your bot’s privacy settings allow it to see group messages when used in groups.
 
 #### Getting the thread ID (this is optional to be used for forum topics)

lib/notification/adapter/telegramPhotoUploader.js

@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+/**
+ * Helpers for sending photos to Telegram via `multipart/form-data` instead of
+ * the HTTP-URL path. Used when the URL is one that Telegram's URL-fetcher will
+ * reject - notably `.webp` images from Cloudimage (mms.immowelt.de), which
+ * Telegram refuses with "Bad Request: failed to get HTTP URL content".
+ *
+ * The HTTP-URL path is faster and is still the default in telegram.js; this
+ * module is the fallback for URLs whose extension makes Telegram fail.
+ */
+
+/** Telegram's sendPhoto limit when uploading bytes via multipart/form-data. */
+const TELEGRAM_MULTIPART_MAX_BYTES = 10 * 1024 * 1024;
+
+/** Accept header used when re-fetching the image ourselves.
+ *  Deliberately excludes `image/webp` so CDNs that content-negotiate
+ *  (like Cloudimage on mms.immowelt.de) transcode WEBP to JPEG. */
+const NON_WEBP_ACCEPT = 'image/jpeg,image/png,image/*;q=0.8';
+
+/**
+ * Returns true if the URL's path ends in a `.webp` extension. Such URLs need
+ * multipart upload because Telegram identifies media types from the URL path
+ * and rejects `.webp` in sendPhoto via HTTP URL.
+ *
+ * Conservative: returns false for null/empty/non-string input, malformed URLs,
+ * and non-https schemes.
+ *
+ * @param {string|null|undefined} url
+ * @returns {boolean}
+ */
+export function shouldUseMultipart(url) {
+  if (typeof url !== 'string' || url.length === 0) return false;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== 'https:') return false;
+  return /\.webp$/i.test(parsed.pathname);
+}
+
+/**
+ * Fetch an image from `imageUrl` and build a `FormData` body suitable for
+ * POSTing to `https://api.telegram.org/bot<token>/sendPhoto`.
+ *
+ * - Sends an `Accept` header that excludes `image/webp` so origin/CDN servers
+ *   that content-negotiate return JPEG bytes.
+ * - Rejects images larger than Telegram's 10 MB multipart limit, both
+ *   advertised via `Content-Length` and (defensively) after download.
+ * - The `photo` field is named with a `.jpg` extension because Telegram
+ *   identifies file type from the filename.
+ *
+ * Throws if the image fetch fails, the size limit is exceeded, or the URL is
+ * unreachable. The caller is responsible for catching and falling back.
+ *
+ * @param {Object} args
+ * @param {string|number} args.chatId
+ * @param {string} args.imageUrl
+ * @param {string} args.caption
+ * @param {string} [args.parseMode]      - Telegram parse_mode, e.g. 'HTML'.
+ * @param {number} [args.messageThreadId] - Telegram supergroup topic id.
+ * @returns {Promise<FormData>}
+ */
+export async function buildPhotoFormData({ chatId, imageUrl, caption, parseMode, messageThreadId }) {
+  const res = await fetch(imageUrl, {
+    method: 'GET',
+    headers: { Accept: NON_WEBP_ACCEPT },
+  });
+
+  if (!res.ok) {
+    throw new Error(`Failed to fetch image for multipart upload (${res.status}): ${imageUrl}`);
+  }
+
+  const advertised = Number(res.headers.get('content-length'));
+  if (Number.isFinite(advertised) && advertised > TELEGRAM_MULTIPART_MAX_BYTES) {
+    throw new Error(
+      `Image exceeds Telegram multipart size limit (advertised ${advertised} bytes, max ${TELEGRAM_MULTIPART_MAX_BYTES}): ${imageUrl}`,
+    );
+  }
+
+  const buf = await res.arrayBuffer();
+  if (buf.byteLength > TELEGRAM_MULTIPART_MAX_BYTES) {
+    throw new Error(
+      `Image exceeds Telegram multipart size limit (downloaded ${buf.byteLength} bytes, max ${TELEGRAM_MULTIPART_MAX_BYTES}): ${imageUrl}`,
+    );
+  }
+
+  // Telegram identifies the media type from the filename extension. We always
+  // upload as .jpg because the Accept header forces JPEG bytes from CDNs that
+  // honor it; for the rare CDN that ignores Accept and still returns WEBP, the
+  // .jpg filename is a small lie but Telegram's image pipeline accepts it.
+  const blob = new Blob([buf], { type: 'image/jpeg' });
+
+  const fd = new FormData();
+  fd.append('chat_id', String(chatId));
+  fd.append('caption', caption);
+  if (parseMode) fd.append('parse_mode', parseMode);
+  if (messageThreadId != null) fd.append('message_thread_id', String(messageThreadId));
+  fd.append('photo', blob, 'photo.jpg');
+  return fd;
+}

lib/notification/emailTemplate/template.hbs

@@ -106,6 +106,9 @@
                     <![endif]-->
                                         <!--[if !mso]><!-- -->
                                         <a href="{{this.link}}" class="btn" target="_blank">View Listing</a>
+                                        {{#if this.fredyUrl}}
+                                        <a href="{{this.fredyUrl}}" class="btn" style="background:#1a6fff;color:#ffffff;margin-left:8px;" target="_blank">Open in Fredy</a>
+                                        {{/if}}
                                         <!--<![endif]-->
                                     </td>
                                 </tr>

lib/notification/notify.js

@@ -1,4 +1,10 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import fs from 'fs';
+import logger from '../services/logger.js';
 const path = './adapter';
 
 /** Read every integration existing in ./adapter **/
@@ -15,10 +21,16 @@ if (adapter.length === 0) {
 const findAdapter = (notificationAdapter) => {
   return adapter.find((a) => a.config.id === notificationAdapter.id);
 };
-export const send = (serviceName, newListings, notificationConfig, jobKey) => {
+export const send = (serviceName, newListings, notificationConfig, jobKey, baseUrl) => {
   //this is not being used in tests, therefore adapter are always set
   return notificationConfig
-    .filter((notificationAdapter) => findAdapter(notificationAdapter) != null)
-    .map((notificationAdapter) => findAdapter(notificationAdapter))
-    .map((a) => a.send({ serviceName, newListings, notificationConfig, jobKey }));
+    .map((notificationAdapter) => {
+      const found = findAdapter(notificationAdapter);
+      if (!found) {
+        logger.warn(`Notification adapter '${notificationAdapter.id}' not found for job '${jobKey || ''}'`);
+      }
+      return found;
+    })
+    .filter(Boolean)
+    .map((a) => a.send({ serviceName, newListings, notificationConfig, jobKey, baseUrl }));
 };

lib/provider/einsAImmobilien.js

@@ -1,7 +1,20 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { buildHash, isOneOf } from '../utils.js';
 import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
+import { extractNumber } from '../utils/extract-number.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
+
 let appliedBlackList = [];
 
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
 function normalize(o) {
   const baseUrl = 'https://www.1a-immobilienmarkt.de';
   const link = `${baseUrl}/expose/${o.id}.html`;
@@ -9,7 +22,17 @@ function normalize(o) {
   const id = buildHash(o.id, price);
   const image = baseUrl + o.image;
   const address = o.address == null ? null : o.address.trim().replaceAll('/', ',');
-  return Object.assign(o, { id, price, link, image, address });
+  return {
+    id,
+    link,
+    title: o.title || '',
+    price: extractNumber(price),
+    size: extractNumber(o.size),
+    rooms: extractNumber(o.rooms),
+    address,
+    image,
+    description: undefined,
+  };
 }
 
 /**
@@ -29,13 +52,19 @@ function normalizePrice(price) {
   }
   return result[0];
 }
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
 function applyBlacklist(o) {
   const titleNotBlacklisted = !isOneOf(o.title, appliedBlackList);
   const descNotBlacklisted = !isOneOf(o.description, appliedBlackList);
   return titleNotBlacklisted && descNotBlacklisted;
 }
 
+/** @type {ProviderConfig} */
 const config = {
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
   url: null,
   crawlContainer: '.tabelle',
   sortByDateParam: 'sort_type=newest',
@@ -43,7 +72,8 @@ const config = {
   crawlFields: {
     id: '.inner_object_data input[name="marker_objekt_id"]@value | int',
     price: '.inner_object_data .single_data_price | removeNewline | trim',
-    size: '.tabelle .tabelle_inhalt_infos .single_data_box  | removeNewline | trim',
+    size: '.tabelle .tabelle_inhalt_infos .single_data_box:nth-of-type(1) | removeNewline | trim',
+    rooms: '.tabelle .tabelle_inhalt_infos .single_data_box:nth-of-type(2) | removeNewline | trim',
     title: '.inner_object_data .tabelle_inhalt_titel_black | removeNewline | trim',
     image: '.inner_object_pic img@src',
     address: '.tabelle .tabelle_inhalt_infos .left_information > div:nth-child(2) | removeNewline | trim',

lib/provider/immobilienDe.js

@@ -1,52 +1,129 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { buildHash, isOneOf } from '../utils.js';
 import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
+import { extractNumber } from '../utils/extract-number.js';
+import puppeteerExtractor from '../services/extractor/puppeteerExtractor.js';
+import * as cheerio from 'cheerio';
+import logger from '../services/logger.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
 
 let appliedBlackList = [];
 
 function shortenLink(link) {
-  return link.substring(0, link.indexOf('?'));
+  if (!link) return '';
+  const index = link.indexOf('?');
+  return index === -1 ? link : link.substring(0, index);
 }
 
 function parseId(shortenedLink) {
   return shortenedLink.substring(shortenedLink.lastIndexOf('/') + 1);
 }
 
+async function fetchDetails(listing, browser) {
+  try {
+    const html = await puppeteerExtractor(listing.link, null, { browser, name: 'immobilienDe_details' });
+    if (!html) return listing;
+
+    const $ = cheerio.load(html);
+
+    // Try JSON-LD first
+    let description = null;
+    let address = listing.address;
+    $('script[type="application/ld+json"]').each((_, el) => {
+      if (description) return;
+      try {
+        const data = JSON.parse($(el).text());
+        const nodes = Array.isArray(data) ? data : [data];
+        for (const node of nodes) {
+          if (node.description && !description) description = String(node.description).replace(/\s+/g, ' ').trim();
+          const addr = node.address || node?.mainEntity?.address;
+          if (addr && addr.streetAddress && address === listing.address) {
+            const parts = [addr.streetAddress, addr.postalCode, addr.addressLocality].filter(Boolean);
+            if (parts.length) address = parts.join(' ');
+          }
+        }
+      } catch {
+        // ignore malformed JSON-LD
+      }
+    });
+
+    // Fallback: common description selectors used by immobilien.de
+    if (!description) {
+      const sel = ['.beschreibung', '.freitext', '.objektbeschreibung', '.description'].find((s) => $(s).length > 0);
+      if (sel) description = $(sel).text().replace(/\s+/g, ' ').trim();
+    }
+
+    return {
+      ...listing,
+      address,
+      description: description || listing.description,
+    };
+  } catch (error) {
+    logger.warn(`Could not fetch immobilien.de detail page for listing '${listing.id}'.`, error?.message || error);
+    return listing;
+  }
+}
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
 function normalize(o) {
   const baseUrl = 'https://www.immobilien.de';
-  const size = o.size || null;
-  const price = o.price || null;
-  const title = o.title || 'No title available';
+  const title = o.title || '';
   const address = o.address || null;
   const shortLink = shortenLink(o.link);
-  const link = `${baseUrl}/${shortLink}`;
-  const image = baseUrl + o.image;
+  const link = shortLink ? (shortLink.startsWith('http') ? shortLink : baseUrl + shortLink) : baseUrl;
+  const image = o.image ? (o.image.startsWith('http') ? o.image : baseUrl + o.image) : null;
   const id = buildHash(parseId(shortLink), o.price);
-  return Object.assign(o, { id, price, size, title, address, link, image });
+  return {
+    id,
+    link,
+    title,
+    price: extractNumber(o.price),
+    size: extractNumber(o.size),
+    rooms: extractNumber(o.rooms),
+    address,
+    image,
+    description: o.description,
+  };
 }
 
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
 function applyBlacklist(o) {
   const titleNotBlacklisted = !isOneOf(o.title, appliedBlackList);
   const descNotBlacklisted = !isOneOf(o.description, appliedBlackList);
   return titleNotBlacklisted && descNotBlacklisted;
 }
 
+/** @type {ProviderConfig} */
 const config = {
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
   url: null,
-  crawlContainer: '._ref',
+  crawlContainer: 'a.lr-card',
   sortByDateParam: 'sort_col=*created_ts&sort_dir=desc',
-  waitForSelector: 'body',
+  waitForSelector: null,
   crawlFields: {
     id: '@href', //will be transformed later
-    price: '.list_entry .immo_preis .label_info',
-    size: '.list_entry .flaeche .label_info | removeNewline | trim',
-    title: '.list_entry .part_text h3 span',
-    description: '.list_entry .description | trim',
+    price: '.lr-card__price-amount | trim',
+    size: '.lr-card__fact:has(.lr-card__fact-label:contains("Fläche")) .lr-card__fact-value | trim',
+    rooms: '.zimmer .label_info',
+    title: '.lr-card__title | trim',
+    description: '.description | trim',
     link: '@href',
-    address: '.list_entry .place',
-    image: '.list_entry img@src',
+    address: '.lr-card__address span | trim',
+    image: 'img.lr-card__gallery-img@src',
   },
-  normalize: normalize,
+  normalize,
   filter: applyBlacklist,
+  fetchDetails,
   activeTester: checkIfListingIsActive,
 };
 export const init = (sourceConfig, blacklist) => {

lib/provider/immonet.js

@@ -1,48 +0,0 @@
-import { isOneOf, buildHash } from '../utils.js';
-import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
-let appliedBlackList = [];
-
-function normalize(o) {
-  const size = o.size != null ? o.size.replace('Wohnfläche ', '') : 'N/A m²';
-  const price = o.price.replace('Kaufpreis ', '');
-  const address = o.address?.split(' • ')?.pop() ?? null;
-  const title = o.title || 'No title available';
-  const link = o.link != null ? decodeURIComponent(o.link) : config.url;
-  const id = buildHash(title, price);
-  return Object.assign(o, { id, address, price, size, title, link });
-}
-function applyBlacklist(o) {
-  const titleNotBlacklisted = !isOneOf(o.title, appliedBlackList);
-  const descNotBlacklisted = !isOneOf(o.description, appliedBlackList);
-  return titleNotBlacklisted && descNotBlacklisted;
-}
-const config = {
-  url: null,
-  crawlContainer: 'div[data-testid="serp-core-classified-card-testid"]',
-  sortByDateParam: 'sortby=19',
-  waitForSelector: 'div[data-testid="serp-gridcontainer-testid"]',
-  crawlFields: {
-    id: 'button@title |trim',
-    title: 'button@title |trim',
-    price: 'div[data-testid="cardmfe-price-testid"] | trim',
-    size: 'div[data-testid="cardmfe-keyfacts-testid"] | trim',
-    address: 'div[data-testid="cardmfe-description-box-address"] | trim',
-    image: 'div[data-testid="cardmfe-picture-box-test-id"] img@src',
-    link: 'button@data-base',
-    description: 'div[data-testid="cardmfe-description-text-test-id"] | trim',
-  },
-  normalize: normalize,
-  filter: applyBlacklist,
-  activeTester: checkIfListingIsActive,
-};
-export const init = (sourceConfig, blacklist) => {
-  config.enabled = sourceConfig.enabled;
-  config.url = sourceConfig.url;
-  appliedBlackList = blacklist || [];
-};
-export const metaInformation = {
-  name: 'Immonet',
-  baseUrl: 'https://www.immonet.de/',
-  id: 'immonet',
-};
-export { config };

lib/provider/immoscout.js

@@ -1,9 +1,14 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 /**
  * ImmoScout provider using the mobile API to retrieve listings.
  *
  * The mobile API provides the following endpoints:
  * - GET /search/total?{search parameters}: Returns the total number of listings for the given query
- *   Example: `curl -H "User-Agent: ImmoScout_27.3_26.0_._" https://api.mobile.immobilienscout24.de/search/total?searchType=region&realestatetype=apartmentrent&pricetype=calculatedtotalrent&geocodes=%2Fde%2Fberlin%2Fberlin `
+ *   Example: `curl -H "User-Agent: ImmoScout_27.12_26.2_._" https://api.mobile.immobilienscout24.de/search/total?searchType=region&realestatetype=apartmentrent&pricetype=calculatedtotalrent&geocodes=%2Fde%2Fberlin%2Fberlin `
  *
  * - POST /search/list?{search parameters}: Actually retrieves the listings. Body is json encoded and contains
  *   data specifying additional results (advertisements) to return. The format is as follows:
@@ -15,12 +20,12 @@
  *   ```
  *   It is not necessary to provide data for the specified keys.
  *
- *   Example: `curl -X POST 'https://api.mobile.immobilienscout24.de/search/list?pricetype=calculatedtotalrent&realestatetype=apartmentrent&searchType=region&geocodes=%2Fde%2Fberlin%2Fberlin&pagenumber=1' -H "Connection: keep-alive" -H "User-Agent: ImmoScout_27.3_26.0_._" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"supportedResultListType": [], "userData": {}}'`
+ *   Example: `curl -X POST 'https://api.mobile.immobilienscout24.de/search/list?pricetype=calculatedtotalrent&realestatetype=apartmentrent&searchType=region&geocodes=%2Fde%2Fberlin%2Fberlin&pagenumber=1' -H "Connection: keep-alive" -H "User-Agent: ImmoScout_27.12_26.2_._" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"supportedResultListType": [], "userData": {}}'`
 
  * - GET /expose/{id} - Returns the details of a listing. The response contains additional details not included in the
  *   listing response.
  *
- *   Example: `curl -H "User-Agent: ImmoScout_27.3_26.0_._" "https://api.mobile.immobilienscout24.de/expose/158382494"`
+ *   Example: `curl -H "User-Agent: ImmoScout_27.12_26.2_._" "https://api.mobile.immobilienscout24.de/expose/158382494"`
  *
  *
  * It is necessary to set the correct User Agent (see `getListings`) in the request header.
@@ -41,13 +46,17 @@ import {
   convertWebToMobile,
 } from '../services/immoscout/immoscout-web-translator.js';
 import logger from '../services/logger.js';
+import { extractNumber } from '../utils/extract-number.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
+
 let appliedBlackList = [];
 
 async function getListings(url) {
   const response = await fetch(url, {
     method: 'POST',
     headers: {
-      'User-Agent': 'ImmoScout_27.3_26.0_._',
+      'User-Agent': 'ImmoScout_27.12_26.2_._',
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
@@ -66,13 +75,12 @@ async function getListings(url) {
     .map((expose) => {
       const item = expose.item;
       const [price, size] = item.attributes;
-      const image = item?.titlePicture?.preview ?? null;
+      const image = item?.titlePicture?.full ?? item?.titlePicture?.preview ?? null;
       return {
         id: item.id,
         price: price?.value,
         size: size?.value,
         title: item.title,
-        description: item.description,
         link: `${metaInformation.baseUrl}expose/${item.id}`,
         address: item.address?.line,
         image,
@@ -80,10 +88,72 @@ async function getListings(url) {
     });
 }
 
+async function fetchDetails(listing) {
+  return pushDetails(listing);
+}
+
+async function pushDetails(listing) {
+  const exposeId = listing.link?.split('/').pop();
+  const detailed = await fetch(`https://api.mobile.immobilienscout24.de/expose/${exposeId}`, {
+    headers: {
+      'User-Agent': 'ImmoScout_27.3_26.0_._',
+      'Content-Type': 'application/json',
+    },
+  });
+  if (!detailed.ok) {
+    logger.warn(
+      `Error fetching listing details from ImmoScout Mobile API for id: ${exposeId} Status: ${detailed.statusText}`,
+    );
+    return listing;
+  }
+  const detailBody = await detailed.json();
+
+  listing.description = buildDescription(detailBody);
+
+  return listing;
+}
+
+function buildDescription(detailBody) {
+  const sections = detailBody.sections || [];
+  const contact = detailBody.contact || {};
+  const cData = contact?.contactData || {};
+  const agentName = cData?.agent?.name || '';
+  const agentCompany = cData?.agent?.company || '';
+  const stars = cData?.agent?.rating?.numberOfStars || '';
+  const phoneNumbers = contact?.phoneNumbers || [];
+  const phoneNumbersMapped = phoneNumbers
+    .map((p) => `${p.label}: ${p.text}`)
+    .join('\n')
+    .trim();
+
+  const attributes = sections
+    .filter((s) => s.type === 'ATTRIBUTE_LIST')
+    .flatMap((s) => s.attributes)
+    .filter((attr) => attr.label && attr.text)
+    .map((attr) => `${attr.label} ${attr.text}`)
+    .join('\n');
+
+  const freeText = sections
+    .filter((s) => s.type === 'TEXT_AREA')
+    .map((s) => {
+      return `${s.title}\n${s.text}`;
+    })
+    .join('\n\n');
+
+  return (
+    `Agent: ${agentName ? agentName : 'Unbekannt'} ${agentCompany ? `(${agentCompany}) ` : ''}${stars ? `- ${stars} stars` : ''}\n` +
+    (phoneNumbersMapped ? `Phone Numbers:\n${phoneNumbersMapped}` : '') +
+    '\n\n' +
+    attributes.trim() +
+    '\n\n' +
+    freeText.trim()
+  );
+}
+
 async function isListingActive(link) {
   const result = await fetch(convertImmoscoutListingToMobileListing(link), {
     headers: {
-      'User-Agent': 'ImmoScout_27.3_26.0_._',
+      'User-Agent': 'ImmoScout_27.12_26.2_._',
     },
   });
 
@@ -102,22 +172,44 @@ async function isListingActive(link) {
 function nullOrEmpty(val) {
   return val == null || val.length === 0;
 }
+
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
 function normalize(o) {
-  const title = nullOrEmpty(o.title) ? 'NO TITLE FOUND' : o.title.replace('NEU', '');
+  const title = (o.title || '').replace('NEU', '').trim();
   const address = nullOrEmpty(o.address) ? 'NO ADDRESS FOUND' : (o.address || '').replace(/\(.*\),.*$/, '').trim();
   const id = buildHash(o.id, o.price);
-  return Object.assign(o, { id, title, address });
+  return {
+    id,
+    link: o.link,
+    title,
+    price: extractNumber(o.price),
+    size: extractNumber(o.size),
+    rooms: extractNumber(o.rooms),
+    address,
+    image: o.image,
+    description: o.description,
+  };
 }
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
 function applyBlacklist(o) {
   return !isOneOf(o.title, appliedBlackList);
 }
+/** @type {ProviderConfig} */
 const config = {
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
   url: null,
   crawlFields: {
     id: 'id',
     title: 'title',
     price: 'price',
     size: 'size',
+    rooms: 'rooms',
     link: 'link',
     address: 'address',
   },
@@ -126,6 +218,7 @@ const config = {
   normalize: normalize,
   filter: applyBlacklist,
   getListings: getListings,
+  fetchDetails: fetchDetails,
   activeTester: isListingActive,
 };
 export const init = (sourceConfig, blacklist) => {

lib/provider/immoswp.js

@@ -1,26 +1,50 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { isOneOf, buildHash } from '../utils.js';
 import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
+import { extractNumber } from '../utils/extract-number.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
 
 let appliedBlackList = [];
 
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
 function normalize(o) {
-  const size = o.size || 'N/A m²';
-  const price = (o.price || '--- €').replace('Preis auf Anfrage', '--- €');
-  const title = o.title || 'No title available';
   const immoId = o.id.substring(o.id.indexOf('-') + 1, o.id.length);
   const link = `https://immo.swp.de/immobilien/${immoId}`;
-  const description = o.description;
-  const id = buildHash(immoId, price);
-  return Object.assign(o, { id, price, size, title, link, description });
+  const id = buildHash(immoId, o.price);
+  return {
+    id,
+    link,
+    title: o.title || '',
+    price: extractNumber(o.price),
+    size: extractNumber(o.size),
+    rooms: extractNumber(o.rooms),
+    address: o.address,
+    image: o.image,
+    description: undefined,
+  };
 }
 
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
 function applyBlacklist(o) {
   const titleNotBlacklisted = !isOneOf(o.title, appliedBlackList);
   const descNotBlacklisted = !isOneOf(o.description, appliedBlackList);
   return titleNotBlacklisted && descNotBlacklisted;
 }
 
+/** @type {ProviderConfig} */
 const config = {
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
   url: null,
   crawlContainer: '.js-serp-item',
   sortByDateParam: 's=most_recently_updated_first',
@@ -29,9 +53,10 @@ const config = {
     id: '.js-bookmark-btn@data-id',
     price: 'div.align-items-start div:first-child | trim',
     size: 'div.align-items-start div:nth-child(3) | trim',
+    rooms: 'div.align-items-start div:nth-child(2) | trim',
+    address: '.js-bookmark-btn@data-address',
     title: '.js-item-title-link@title | trim',
     link: '.ci-search-result__link@href',
-    description: '.js-show-more-item-sm | removeNewline | trim',
     image: 'img@src',
   },
   normalize: normalize,

lib/provider/immowelt.js

@@ -1,29 +1,110 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { buildHash, isOneOf } from '../utils.js';
 import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
+import { extractNumber } from '../utils/extract-number.js';
+import puppeteerExtractor from '../services/extractor/puppeteerExtractor.js';
+import * as cheerio from 'cheerio';
+import logger from '../services/logger.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
 
 let appliedBlackList = [];
 
-function normalize(o) {
-  const id = buildHash(o.id, o.price);
-  return Object.assign(o, { id });
+async function fetchDetails(listing, browser) {
+  try {
+    const html = await puppeteerExtractor(listing.link, null, { browser, name: 'immowelt_details' });
+    if (!html) return listing;
+
+    const $ = cheerio.load(html);
+    const nextDataRaw = $('#__NEXT_DATA__').text();
+    if (!nextDataRaw) return listing;
+
+    const classified = JSON.parse(nextDataRaw)?.props?.pageProps?.classified;
+    if (!classified) return listing;
+
+    const description = (classified.Texts || [])
+      .map((t) => [t.Title, t.Content].filter(Boolean).join('\n'))
+      .filter(Boolean)
+      .join('\n\n');
+
+    const addr = classified.EstateAddress;
+    let address = listing.address;
+    if (addr) {
+      const street = [addr.Street, addr.HouseNumber].filter(Boolean).join(' ');
+      const cityLine = [addr.ZipCode, addr.District || addr.City].filter(Boolean).join(' ');
+      const full = [street, cityLine].filter(Boolean).join(', ');
+      if (full) address = full;
+    }
+
+    return {
+      ...listing,
+      address,
+      description: description || listing.description,
+    };
+  } catch (error) {
+    logger.warn(`Could not fetch immowelt detail page for listing '${listing.id}'.`, error?.message || error);
+    return listing;
+  }
 }
 
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
+function normalize(o) {
+  const id = buildHash(o.id, o.price);
+  return {
+    id,
+    link: o.link,
+    title: o.title || '',
+    price: extractNumber(o.price),
+    size: extractNumber(o.size),
+    rooms: extractNumber(o.rooms),
+    address: o.address,
+    image: o.image,
+    description: o.description,
+  };
+}
+
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
 function applyBlacklist(o) {
   const titleNotBlacklisted = !isOneOf(o.title, appliedBlackList);
   const descNotBlacklisted = !isOneOf(o.description, appliedBlackList);
   return titleNotBlacklisted && descNotBlacklisted;
 }
 
+/** @type {ProviderConfig} */
 const config = {
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
   url: null,
   crawlContainer:
     'div[data-testid="serp-core-scrollablelistview-testid"]:not(div[data-testid="serp-enlargementlist-testid"] div[data-testid="serp-card-testid"]) div[data-testid="serp-core-classified-card-testid"]',
   sortByDateParam: 'order=DateDesc',
-  waitForSelector: 'div[data-testid="serp-gridcontainer-testid"]',
+  // waitForSelector is null: extract the full page via page.content() so the
+  // Cheerio crawler can search anywhere in the rendered document.
+  // preNavigateUrl visits the homepage first to establish a trusted session
+  // before hitting the search URL; this prevents CDN-level bot challenges that
+  // fire on cold sessions. waitForNetworkIdle (phase 2) then catches React's
+  // listing API round-trip that fires well after domcontentloaded.
+  waitForSelector: null,
+  puppeteerOptions: {
+    puppeteerTimeout: 60_000,
+    preNavigateUrl: 'https://www.immowelt.de/',
+    waitForNetworkIdle: true,
+    waitForNetworkIdleTimeout: 60_000,
+  },
   crawlFields: {
     id: 'a@href',
     price: 'div[data-testid="cardmfe-price-testid"] | removeNewline | trim',
-    size: 'div[data-testid="cardmfe-keyfacts-testid"] | removeNewline | trim',
+    size: 'div[data-testid="cardmfe-keyfacts-testid"] div:nth-of-type(3) | removeNewline | trim',
+    rooms: 'div[data-testid="cardmfe-keyfacts-testid"] div:nth-of-type(1) | removeNewline | trim',
     title: 'div[data-testid="cardmfe-description-box-text-test-id"] > div:nth-of-type(2)',
     link: 'a@href',
     description: 'div[data-testid="cardmfe-description-text-test-id"] > div:nth-of-type(2) | removeNewline | trim',
@@ -32,6 +113,7 @@ const config = {
   },
   normalize: normalize,
   filter: applyBlacklist,
+  fetchDetails: fetchDetails,
   activeTester: checkIfListingIsActive,
 };
 export const init = (sourceConfig, blacklist) => {

lib/provider/kleinanzeigen.js

@@ -1,16 +1,181 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { buildHash, isOneOf } from '../utils.js';
 import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
+import { extractNumber } from '../utils/extract-number.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
+import puppeteerExtractor from '../services/extractor/puppeteerExtractor.js';
+import logger from '../services/logger.js';
+import * as cheerio from 'cheerio';
 
 let appliedBlackList = [];
 let appliedBlacklistedDistricts = [];
 
-function normalize(o) {
-  const size = o.size || '--- m²';
-  const id = buildHash(o.id, o.price);
-  const link = `https://www.kleinanzeigen.de${o.link}`;
-  return Object.assign(o, { id, size, link });
+function toAbsoluteLink(link) {
+  if (!link) return null;
+  return link.startsWith('http') ? link : `https://www.kleinanzeigen.de${link}`;
 }
 
+function cleanText(value) {
+  if (value == null) return '';
+  return String(value)
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function buildAddressFromJsonLd(address) {
+  if (!address || typeof address !== 'object') return null;
+
+  const locality = cleanText(address.addressLocality);
+  const region = cleanText(address.addressRegion);
+  const postalCode = cleanText(address.postalCode);
+  const streetAddress = cleanText(address.streetAddress);
+
+  const cityPart = [region, locality].filter(Boolean).join(' - ');
+  const tail = [postalCode, cityPart || locality || region].filter(Boolean).join(' ');
+  const fullAddress = [streetAddress, tail].filter(Boolean).join(', ');
+
+  return fullAddress || null;
+}
+
+function flattenJsonLdNodes(node, acc = []) {
+  if (node == null) return acc;
+
+  if (Array.isArray(node)) {
+    node.forEach((item) => flattenJsonLdNodes(item, acc));
+    return acc;
+  }
+
+  if (typeof node !== 'object') return acc;
+
+  acc.push(node);
+
+  if (Array.isArray(node['@graph'])) {
+    node['@graph'].forEach((item) => flattenJsonLdNodes(item, acc));
+  }
+
+  if (node.mainEntity) {
+    flattenJsonLdNodes(node.mainEntity, acc);
+  }
+
+  if (node.itemOffered) {
+    flattenJsonLdNodes(node.itemOffered, acc);
+  }
+
+  return acc;
+}
+
+function extractDetailFromHtml(html) {
+  const $ = cheerio.load(html);
+  const nodes = [];
+
+  // Prefer the rendered postal address block from the detail page because
+  // it contains the street line that is missing from list results.
+  const streetFromDom = cleanText($('#street-address').first().text());
+  const localityFromDom = cleanText($('#viewad-locality').first().text());
+  const domAddress = [streetFromDom, localityFromDom].filter(Boolean).join(' ');
+
+  $('script[type="application/ld+json"]').each((_, element) => {
+    const content = $(element).text();
+    if (!content) return;
+
+    try {
+      const parsed = JSON.parse(content);
+      flattenJsonLdNodes(parsed, nodes);
+    } catch {
+      // Ignore broken JSON-LD blocks from ads/trackers and keep trying others.
+    }
+  });
+
+  let detailAddress = null;
+  let detailDescription = null;
+
+  if (domAddress) {
+    detailAddress = domAddress;
+  }
+
+  for (const node of nodes) {
+    const candidateAddress = buildAddressFromJsonLd(
+      node.address || node?.itemOffered?.address || node?.offers?.address,
+    );
+    if (!detailAddress && candidateAddress) {
+      detailAddress = candidateAddress;
+    }
+
+    const candidateDescription = cleanText(node.description || node?.itemOffered?.description);
+    if (!detailDescription && candidateDescription) {
+      detailDescription = candidateDescription;
+    }
+
+    if (detailAddress && detailDescription) {
+      break;
+    }
+  }
+
+  return {
+    detailAddress,
+    detailDescription,
+  };
+}
+
+async function enrichListingFromDetails(listing, browser) {
+  const absoluteLink = toAbsoluteLink(listing.link);
+  if (!absoluteLink) return listing;
+
+  try {
+    const html = await puppeteerExtractor(absoluteLink, null, { browser, name: 'kleinanzeigen_details' });
+    if (!html) return { ...listing, link: absoluteLink };
+
+    const { detailAddress, detailDescription } = extractDetailFromHtml(html);
+
+    return {
+      ...listing,
+      link: absoluteLink,
+      address: detailAddress || listing.address,
+      description: detailDescription || listing.description,
+    };
+  } catch (error) {
+    logger.warn(`Could not fetch Kleinanzeigen detail page for listing '${listing.id}'.`, error?.message || error);
+    return { ...listing, link: absoluteLink };
+  }
+}
+
+async function fetchDetails(listing, browser) {
+  return enrichListingFromDetails(listing, browser);
+}
+
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
+function normalize(o) {
+  const parts = (o.tags || '').split('·').map((p) => p.trim());
+  const size = parts.find((p) => p.includes('m²'));
+  const rooms = parts.find((p) => p.includes('Zi.'));
+  const id = buildHash(o.id, o.price);
+
+  return {
+    id,
+    title: o.title,
+    link: toAbsoluteLink(o.link) || o.link,
+    price: extractNumber(o.price),
+    size: extractNumber(size),
+    rooms: extractNumber(rooms),
+    address: o.address,
+    description: o.description,
+    image: o.image,
+  };
+}
+
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
 function applyBlacklist(o) {
   const titleNotBlacklisted = !isOneOf(o.title, appliedBlackList);
   const descNotBlacklisted = !isOneOf(o.description, appliedBlackList);
@@ -19,28 +184,31 @@ function applyBlacklist(o) {
   return o.title != null && !isBlacklistedDistrict && titleNotBlacklisted && descNotBlacklisted;
 }
 
+/** @type {ProviderConfig} */
 const config = {
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
   url: null,
   crawlContainer: '#srchrslt-adtable .ad-listitem ',
   //sort by date is standard oO
   sortByDateParam: null,
   waitForSelector: 'body',
   crawlFields: {
-    id: '.aditem@data-adid | int',
+    id: '.aditem@data-adid',
     price: '.aditem-main--middle--price-shipping--price | removeNewline | trim',
-    size: '.aditem-main .text-module-end | removeNewline | trim',
-    title: '.aditem-main .text-module-begin a | removeNewline | trim',
-    link: '.aditem-main .text-module-begin a@href | removeNewline | trim',
+    tags: '.aditem-main--middle--tags | removeNewline | trim',
+    title: '.aditem-main .text-module-begin | removeNewline | trim',
+    link: '.aditem@data-href',
     description: '.aditem-main .aditem-main--middle--description | removeNewline | trim',
     address: '.aditem-main--top--left | trim | removeNewline',
     image: 'img@src',
   },
+  fetchDetails,
   normalize: normalize,
   filter: applyBlacklist,
   activeTester: checkIfListingIsActive,
 };
 export const metaInformation = {
-  name: 'Ebay Kleinanzeigen',
+  name: 'Kleinanzeigen',
   baseUrl: 'https://www.kleinanzeigen.de/',
   id: 'kleinanzeigen',
 };

lib/provider/mcMakler.js

@@ -1,22 +1,50 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { isOneOf, buildHash } from '../utils.js';
 import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
+import { extractNumber } from '../utils/extract-number.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
+
 let appliedBlackList = [];
 
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
 function normalize(o) {
   const originalId = o.id.split('/').pop();
   const id = buildHash(originalId, o.price);
-  const size = o.size ?? 'N/A m²';
-  const title = o.title || 'No title available';
+  const link = o.link != null ? `https://www.mcmakler.de${o.link}` : o.link;
+  const [rooms, size] = o.tags.split(' | ');
   const address = o.address?.replace(' / ', ' ') || null;
-  const link = o.link != null ? `https://www.mcmakler.de${o.link}` : config.url;
-  return Object.assign(o, { id, size, title, link, address });
+  return {
+    id,
+    link,
+    title: o.title || '',
+    price: extractNumber(o.price),
+    size: extractNumber(size),
+    rooms: extractNumber(rooms),
+    address,
+    image: o.image,
+    description: undefined,
+  };
 }
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
 function applyBlacklist(o) {
   const titleNotBlacklisted = !isOneOf(o.title, appliedBlackList);
   const descNotBlacklisted = !isOneOf(o.description, appliedBlackList);
   return titleNotBlacklisted && descNotBlacklisted;
 }
+/** @type {ProviderConfig} */
 const config = {
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
   url: null,
   crawlContainer: 'article[data-testid="propertyCard"]',
   sortByDateParam: 'sortBy=DATE&sortOn=DESC',
@@ -25,7 +53,7 @@ const config = {
     id: 'h2 a@href',
     title: 'h2 a | removeNewline | trim',
     price: 'footer > p:first-of-type | trim',
-    size: 'footer > p:nth-of-type(2) | trim',
+    tags: 'footer > p:nth-of-type(2) | trim',
     address: 'div > h2 + p | removeNewline | trim',
     image: 'img@src',
     link: 'h2 a@href',

lib/provider/neubauKompass.js

@@ -1,5 +1,13 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { isOneOf, buildHash } from '../utils.js';
 import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
+import { extractNumber } from '../utils/extract-number.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
 
 let appliedBlackList = [];
 
@@ -7,19 +15,39 @@ function nullOrEmpty(val) {
   return val == null || val.length === 0;
 }
 
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
 function normalize(o) {
   const link = nullOrEmpty(o.link)
     ? 'NO LINK'
     : `https://www.neubaukompass.de${o.link.substring(o.link.indexOf('/neubau'))}`;
   const id = buildHash(o.link, o.price);
-  return Object.assign(o, { id, link });
+  return {
+    id,
+    link,
+    title: o.title || '',
+    price: extractNumber(o.price),
+    size: extractNumber(o.size),
+    rooms: extractNumber(o.rooms),
+    address: o.address,
+    image: o.image,
+    description: o.description,
+  };
 }
 
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
 function applyBlacklist(o) {
   return !isOneOf(o.title, appliedBlackList);
 }
 
+/** @type {ProviderConfig} */
 const config = {
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
   url: null,
   crawlContainer: '.col-12.mb-4',
   sortByDateParam: 'Sortierung=Id&Richtung=DESC',
@@ -29,7 +57,9 @@ const config = {
     title: 'a@title | removeNewline | trim',
     link: 'a@href',
     address: '.nbk-project-card__description | removeNewline | trim',
-    price: '.nbk-project-card__spec-item .nbk-project-card__spec-value | removeNewline | trim',
+    price: '.nbk-project-card__spec-item:nth-child(1) .nbk-project-card__spec-value | removeNewline | trim',
+    size: '.nbk-project-card__spec-item:nth-child(2) .nbk-project-card__spec-value | removeNewline | trim',
+    rooms: '.nbk-project-card__spec-item:nth-child(3) .nbk-project-card__spec-value | removeNewline | trim',
     image: '.nbk-project-card__image@src',
   },
   normalize: normalize,

lib/provider/ohneMakler.js

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import { isOneOf, buildHash } from '../utils.js';
+import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
+import { extractNumber } from '../utils/extract-number.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
+
+let appliedBlackList = [];
+
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
+function normalize(o) {
+  const link = metaInformation.baseUrl + o.link;
+  const id = buildHash(o.title, o.link, o.price);
+  return {
+    id,
+    link,
+    title: o.title || '',
+    price: extractNumber(o.price),
+    size: extractNumber(o.size),
+    rooms: extractNumber(o.rooms),
+    address: o.address,
+    image: o.image,
+    description: o.description,
+  };
+}
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
+function applyBlacklist(o) {
+  const titleNotBlacklisted = !isOneOf(o.title, appliedBlackList);
+  const descNotBlacklisted = !isOneOf(o.description, appliedBlackList);
+  return titleNotBlacklisted && descNotBlacklisted;
+}
+/** @type {ProviderConfig} */
+const config = {
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
+  url: null,
+  crawlContainer: 'div[data-livecomponent-id*="search/property_list"] .grid > div',
+  sortByDateParam: null,
+  waitForSelector: null,
+  crawlFields: {
+    id: 'a@href',
+    title: 'h4 | removeNewline | trim',
+    price: '.text-xl | trim',
+    size: 'div[title="Wohnfläche"] | trim',
+    rooms: 'div[title="Zimmer"] | trim',
+    address: '.text-slate-800 | removeNewline | trim',
+    image: 'img@src',
+    link: 'a@href',
+  },
+  normalize: normalize,
+  filter: applyBlacklist,
+  activeTester: checkIfListingIsActive,
+};
+
+export const init = (sourceConfig, blacklist) => {
+  config.enabled = sourceConfig.enabled;
+  config.url = sourceConfig.url;
+  appliedBlackList = blacklist || [];
+};
+
+export const metaInformation = {
+  name: 'OhneMakler',
+  baseUrl: 'https://www.ohne-makler.net',
+  id: 'ohneMakler',
+};
+export { config };

lib/provider/regionalimmobilien24.js

@@ -1,23 +1,51 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { isOneOf, buildHash } from '../utils.js';
 import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
+import { extractNumber } from '../utils/extract-number.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
+
 let appliedBlackList = [];
 
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
 function normalize(o) {
   const id = buildHash(o.id, o.price);
   const address = o.address?.replace(/^adresse /i, '') ?? null;
-  const title = o.title || 'No title available';
   const link = o.link != null ? decodeURIComponent(o.link) : config.url;
 
-  var urlReg = new RegExp(/url\((.*?)\)/gim);
+  const urlReg = new RegExp(/url\((.*?)\)/gim);
   const image = o.image != null ? urlReg.exec(o.image)[1] : null;
-  return Object.assign(o, { id, address, title, link, image });
+  return {
+    id,
+    link,
+    title: o.title || '',
+    price: extractNumber(o.price),
+    size: extractNumber(o.size),
+    rooms: extractNumber(o.rooms),
+    address,
+    image,
+    description: o.description,
+  };
 }
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
 function applyBlacklist(o) {
   const titleNotBlacklisted = !isOneOf(o.title, appliedBlackList);
   const descNotBlacklisted = !isOneOf(o.description, appliedBlackList);
   return titleNotBlacklisted && descNotBlacklisted;
 }
+/** @type {ProviderConfig} */
 const config = {
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
   url: null,
   crawlContainer: '.listentry-content',
   sortByDateParam: null, // sort by date is standard
@@ -27,6 +55,7 @@ const config = {
     title: 'h2 | trim',
     price: '.listentry-details-price .listentry-details-v | trim',
     size: '.listentry-details-size .listentry-details-v | trim',
+    rooms: '.listentry-details-rooms .listentry-details-v | trim',
     address: '.listentry-adress | trim',
     image: '.listentry-img@style',
     link: '.shariff@data-url',

lib/provider/sparkasse.js

@@ -1,37 +1,114 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { isOneOf, buildHash } from '../utils.js';
 import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
+import puppeteerExtractor from '../services/extractor/puppeteerExtractor.js';
+import * as cheerio from 'cheerio';
+import logger from '../services/logger.js';
+import { extractNumber } from '../utils/extract-number.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
+
 let appliedBlackList = [];
 
+async function fetchDetails(listing, browser) {
+  try {
+    const html = await puppeteerExtractor(listing.link, 'body', { browser, name: 'sparkasse_details' });
+
+    const $ = cheerio.load(html);
+    const nextDataRaw = $('#__NEXT_DATA__').text;
+    if (!nextDataRaw) return listing;
+
+    const estate = JSON.parse(nextDataRaw)?.props?.pageProps?.estate;
+    if (!estate) return listing;
+
+    const description = (estate.frontendItems || [])
+      .map((item) => {
+        const texts = (item.contents || [])
+          .filter((c) => c.type === 'contentBoxes')
+          .flatMap((c) => c.data || [])
+          .filter((d) => d.type === 'text' && d.content)
+          .map((d) => d.content);
+        if (!texts.length) return null;
+        return [item.label, ...texts].filter(Boolean).join('\n');
+      })
+      .filter(Boolean)
+      .join('\n\n');
+
+    const addr = estate.address;
+    let address = listing.address;
+    if (addr) {
+      const street = [addr.street, addr.streetNumber].filter(Boolean).join(' ');
+      const cityLine = [addr.zip, addr.city].filter(Boolean).join(' ');
+      const full = [street, cityLine].filter(Boolean).join(', ');
+      if (full) address = full;
+    }
+
+    return {
+      ...listing,
+      address,
+      description: description || listing.description,
+    };
+  } catch (error) {
+    logger.warn(`Could not fetch Sparkasse detail page for listing '${listing.id}'.`, error?.message || error);
+    return listing;
+  }
+}
+
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
 function normalize(o) {
   const originalId = o.id.split('/').pop().replace('.html', '');
   const id = buildHash(originalId, o.price);
-  const size = o.size?.replace(' Wohnfläche', '') ?? null;
-  const title = o.title || 'No title available';
   const link = o.link != null ? `https://immobilien.sparkasse.de${o.link}` : config.url;
-  return Object.assign(o, { id, size, title, link });
+
+  return {
+    id,
+    link,
+    title: o.title || '',
+    price: extractNumber(o.price),
+    size: extractNumber(o.size),
+    rooms: extractNumber(o.rooms),
+    address: o.address,
+    image: o.image,
+    description: o.description,
+  };
 }
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
 function applyBlacklist(o) {
   const titleNotBlacklisted = !isOneOf(o.title, appliedBlackList);
   const descNotBlacklisted = !isOneOf(o.description, appliedBlackList);
   return titleNotBlacklisted && descNotBlacklisted;
 }
+/** @type {ProviderConfig} */
 const config = {
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
   url: null,
-  crawlContainer: '.estate-list-item-row',
+  crawlContainer: 'div[data-testid="estate-link"]',
   sortByDateParam: 'sortBy=date_desc',
   waitForSelector: 'body',
   crawlFields: {
-    id: 'div[data-testid="estate-link"] a@href',
+    id: 'a@href',
     title: 'h3 | trim',
     price: '.estate-list-price | trim',
-    size: '.estate-mainfact:first-child span | trim',
+    size: '.estate-mainfact:nth-child(1) span | trim',
+    rooms: '.estate-mainfact:nth-child(2) span | trim',
     address: 'h6 | trim',
-    image: '.estate-list-item-image-container img@src',
-    link: 'div[data-testid="estate-link"] a@href',
+    image: 'img@src',
+    link: 'a@href',
   },
   normalize: normalize,
   filter: applyBlacklist,
-  activeTester: checkIfListingIsActive,
+  fetchDetails,
+  activeTester: (url) => checkIfListingIsActive(url, 'Angebot nicht gefunden'),
 };
 export const init = (sourceConfig, blacklist) => {
   config.enabled = sourceConfig.enabled;

lib/provider/wgGesucht.js

@@ -1,21 +1,73 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { isOneOf, buildHash } from '../utils.js';
 import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
+import { extractNumber } from '../utils/extract-number.js';
+import puppeteerExtractor from '../services/extractor/puppeteerExtractor.js';
+import * as cheerio from 'cheerio';
+import logger from '../services/logger.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
 
 let appliedBlackList = [];
 
+async function fetchDetails(listing, browser) {
+  try {
+    const html = await puppeteerExtractor(listing.link, null, { browser, name: 'wgGesucht_details' });
+    if (!html) return listing;
+
+    const $ = cheerio.load(html);
+
+    $('#freitext_0 script').remove();
+    const description = $('#freitext_0').text().replace(/\s+/g, ' ').trim();
+    const address = $('a[href="#map_container"] .section_panel_detail').text().replace(/\s+/g, ' ').trim();
+
+    return {
+      ...listing,
+      address: address || listing.address,
+      description: description || listing.description,
+    };
+  } catch (error) {
+    logger.warn(`Could not fetch wgGesucht detail page for listing '${listing.id}'.`, error?.message || error);
+    return listing;
+  }
+}
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
 function normalize(o) {
   const id = buildHash(o.id, o.price);
   const link = `https://www.wg-gesucht.de${o.link}`;
   const image = o.image != null ? o.image.replace('small', 'large') : null;
-  return Object.assign(o, { id, link, image });
+  const [rooms, city, road] = o.details?.split(' | ') || [];
+  return {
+    id,
+    link,
+    title: o.title || '',
+    price: extractNumber(o.price),
+    size: extractNumber(o.size),
+    rooms: extractNumber(rooms),
+    address: `${city}, ${road}`,
+    image,
+    description: o.description,
+  };
 }
 
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
 function applyBlacklist(o) {
   const titleNotBlacklisted = !isOneOf(o.title, appliedBlackList);
   const descNotBlacklisted = !isOneOf(o.description, appliedBlackList);
   return o.id != null && titleNotBlacklisted && descNotBlacklisted;
 }
 
+/** @type {ProviderConfig} */
 const config = {
   url: null,
   crawlContainer: '#main_column .wgg_card',
@@ -26,12 +78,16 @@ const config = {
     details: '.row .noprint .col-xs-11 |removeNewline |trim',
     price: '.middle .col-xs-3 |removeNewline |trim',
     size: '.middle .text-right |removeNewline |trim',
+    rooms: '.middle .text-right |removeNewline |trim',
     title: '.truncate_title a |removeNewline |trim',
     link: '.truncate_title a@href',
     image: '.img-responsive@src',
+    description: '.row .noprint .col-xs-11 |removeNewline |trim',
   },
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
   normalize: normalize,
   filter: applyBlacklist,
+  fetchDetails,
   activeTester: checkIfListingIsActive,
 };
 export const init = (sourceConfig, blacklist) => {

lib/provider/wohnungsboerse.js

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import * as utils from '../utils.js';
+import checkIfListingIsActive from '../services/listings/listingActiveTester.js';
+import { extractNumber } from '../utils/extract-number.js';
+/** @import { ParsedListing } from '../types/listing.js' */
+/** @import { ProviderConfig } from '../types/providerConfig.js' */
+
+let appliedBlackList = [];
+
+/**
+ * @param {any} o
+ * @returns {ParsedListing}
+ */
+function normalize(o) {
+  const [city = '', part = ''] = (o.description || '').split('-').map((v) => v.trim());
+  const address = `${part}, ${city}`;
+  return {
+    id: o.link.split('/').pop(),
+    link: o.link,
+    title: o.title || '',
+    price: extractNumber(o.price),
+    size: extractNumber(o.size),
+    rooms: extractNumber(o.rooms),
+    address,
+    image: o.image,
+    description: o.description,
+  };
+}
+
+/**
+ * @param {ParsedListing} o
+ * @returns {boolean}
+ */
+function applyBlacklist(o) {
+  const titleNotBlacklisted = !utils.isOneOf(o.title, appliedBlackList);
+  const descNotBlacklisted = !utils.isOneOf(o.description, appliedBlackList);
+  return o.id != null && o.title != null && titleNotBlacklisted && descNotBlacklisted && o.link.startsWith(o.link);
+}
+
+/** @type {ProviderConfig} */
+const config = {
+  requiredFieldNames: ['id', 'link', 'title', 'price', 'size', 'rooms', 'address', 'image', 'description'],
+  url: null,
+  sortByDateParam: null,
+  waitForSelector: 'body',
+  crawlContainer: '.search_result_container > a',
+  crawlFields: {
+    id: '*',
+    title: 'h3 | trim',
+    price: 'dl:nth-of-type(1) dd | removeNewline | trim',
+    rooms: 'dl:nth-of-type(2) dd | removeNewline | trim',
+    size: 'dl:nth-of-type(3) dd | removeNewline | trim',
+    description: 'div.before\\:icon-location_marker | trim',
+    link: '@href',
+    image: 'img@src',
+  },
+  normalize: normalize,
+  filter: applyBlacklist,
+  activeTester: checkIfListingIsActive,
+};
+
+export const init = (sourceConfig, blacklistTerms) => {
+  config.url = sourceConfig.url;
+  appliedBlackList = blacklistTerms || [];
+};
+
+export const metaInformation = {
+  name: 'Wohnungsboerse',
+  baseUrl: 'https://www.wohnungsboerse.net',
+  id: 'wohnungsboerse',
+};
+
+export { config };

lib/services/crons/demoCleanup-cron.js

@@ -1,23 +0,0 @@
-import { removeJobsByUserId } from '../storage/jobStorage.js';
-import { config } from '../../utils.js';
-import { getUsers } from '../storage/userStorage.js';
-import logger from '../logger.js';
-import cron from 'node-cron';
-
-/**
- * if we are running in demo environment, we have to cleanup the db files (specifically the jobs table)
- */
-export function cleanupDemoAtMidnight() {
-  cron.schedule('0 0 * * *', cleanup);
-}
-
-function cleanup() {
-  if (config.demoMode) {
-    const demoUser = getUsers(false).find((user) => user.username === 'demo');
-    if (demoUser == null) {
-      logger.error('Demo user not found, cannot remove Jobs');
-      return;
-    }
-    removeJobsByUserId(demoUser.id);
-  }
-}

lib/services/crons/geocoding-cron.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import cron from 'node-cron';
+import { getListingsToGeocode, updateListingGeocoordinates } from '../storage/listingsStorage.js';
+import { geocodeAddress, isGeocodingPaused } from '../geocoding/geoCodingService.js';
+import { getJobs } from '../storage/jobStorage.js';
+import { calculateDistanceForJob } from '../geocoding/distanceService.js';
+import { getSettings } from '../storage/settingsStorage.js';
+import logger from '../logger.js';
+
+export async function runGeoCordTask() {
+  const listings = getListingsToGeocode();
+  if (listings.length > 0) {
+    for (const listing of listings) {
+      if (isGeocodingPaused()) {
+        break;
+      }
+
+      const coords = await geocodeAddress(listing.address);
+      if (coords) {
+        updateListingGeocoordinates(listing.id, coords.lat, coords.lng);
+      }
+    }
+  }
+
+  //additional run
+  const jobs = getJobs();
+  for (const job of jobs) {
+    calculateDistanceForJob(job.id, job.userId);
+  }
+}
+
+export async function initGeocodingCron() {
+  const settings = await getSettings();
+  if (settings.demoMode) {
+    logger.info('Do not start geo service as we are in demo mode');
+    return;
+  }
+  // run directly on start
+  await runGeoCordTask();
+  // then every 6 hours
+  cron.schedule('0 */6 * * *', runGeoCordTask);
+}

lib/services/crons/listing-alive-cron.js

@@ -1,11 +1,23 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import cron from 'node-cron';
 import runActiveChecker from '../listings/listingActiveService.js';
+import logger from '../logger.js';
+import { getSettings } from '../storage/settingsStorage.js';
 
 async function runTask() {
   await runActiveChecker();
 }
 
 export async function initActiveCheckerCron() {
+  const settings = await getSettings();
+  if (settings.demoMode) {
+    logger.info('Do not start listing active checker as we are in demo mode');
+    return;
+  }
   //run directly on start
   await runTask();
   // then every day at 1 am

lib/services/crons/tracker-cron.js

@@ -1,10 +1,17 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import cron from 'node-cron';
-import { config, inDevMode } from '../../utils.js';
+import { inDevMode } from '../../utils.js';
 import { trackMainEvent } from '../tracking/Tracker.js';
+import { getSettings } from '../storage/settingsStorage.js';
 
 async function runTask() {
+  const settings = await getSettings();
   //make sure to only send tracking events if the user gave us the green light and we are not in dev mode
-  if (config.analyticsEnabled && !inDevMode()) {
+  if (settings.analyticsEnabled && !inDevMode()) {
     await trackMainEvent();
   }
 }

lib/services/debug/debugBundleService.js

@@ -0,0 +1,263 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import fs from 'fs';
+import os from 'os';
+import { getAllDebugLogs } from './debugLogStorage.js';
+import { getPackageVersion } from '../../utils.js';
+
+const LOGS_FILE_NAME = 'logs.txt';
+const SYSTEM_INFO_FILE_NAME = 'sys.txt';
+const DEBUG_FILE_PREFIX = 'FredyDebug-';
+
+/**
+ * Lazily resolve AdmZip via dynamic import so tests can swap it via globalThis.
+ * Mirrors the pattern used by backupRestoreService.js for consistency.
+ * @returns {Promise<any>}
+ */
+let _AdmZipSingleton = null;
+async function getAdmZip() {
+  if (_AdmZipSingleton) return _AdmZipSingleton;
+  if (globalThis && globalThis.__TEST_ADM_ZIP__) {
+    _AdmZipSingleton = globalThis.__TEST_ADM_ZIP__;
+    return _AdmZipSingleton;
+  }
+  const mod = await import('adm-zip');
+  _AdmZipSingleton = (mod && mod.default) || mod;
+  return _AdmZipSingleton;
+}
+
+/**
+ * Format a Date as YYYY-MM-DD using local time. Used for the download filename.
+ * @param {Date} date
+ * @returns {string}
+ */
+function formatDateOnly(date) {
+  const yyyy = date.getFullYear();
+  const mm = String(date.getMonth() + 1).padStart(2, '0');
+  const dd = String(date.getDate()).padStart(2, '0');
+  return `${yyyy}-${mm}-${dd}`;
+}
+
+/**
+ * Build the debug bundle filename, e.g. "2026-06-08-FredyDebug-22.5.0.zip".
+ * @returns {Promise<string>}
+ */
+export async function buildDebugBundleFileName() {
+  const version = await getPackageVersion();
+  return `${formatDateOnly(new Date())}-${DEBUG_FILE_PREFIX}${version}.zip`;
+}
+
+/**
+ * Format a stored debug_logs row into a single text line. The format mirrors the
+ * console layout from logger.js so support staff sees familiar output:
+ *   [YYYY-MM-DD HH:MM:SS] LEVEL: message
+ *
+ * @param {{ts:number, level:string, message:string}} row
+ * @returns {string}
+ */
+function formatLogLine(row) {
+  const d = new Date(row.ts);
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  const hh = String(d.getHours()).padStart(2, '0');
+  const mi = String(d.getMinutes()).padStart(2, '0');
+  const ss = String(d.getSeconds()).padStart(2, '0');
+  const level = String(row.level || 'info').toUpperCase();
+  return `[${yyyy}-${mm}-${dd} ${hh}:${mi}:${ss}] ${level}: ${row.message}`;
+}
+
+/**
+ * Render every stored debug log row into a single newline-delimited text blob.
+ * Returns an empty string when there are no rows.
+ *
+ * @returns {string}
+ */
+export function renderLogsTxt() {
+  const rows = getAllDebugLogs();
+  if (!rows || rows.length === 0) return '';
+  return rows.map(formatLogLine).join('\n') + '\n';
+}
+
+/**
+ * Best-effort Docker detection. Used as a context hint in sys.txt so issue triage
+ * knows whether the user runs the official container image.
+ *
+ * @returns {{inDocker:boolean, evidence:string[]}}
+ */
+function detectDocker() {
+  const evidence = [];
+  let inDocker = false;
+
+  if (process.env.FREDY_IN_DOCKER === 'true' || process.env.FREDY_IN_DOCKER === '1') {
+    inDocker = true;
+    evidence.push('FREDY_IN_DOCKER env var is set');
+  }
+  try {
+    if (fs.existsSync('/.dockerenv')) {
+      inDocker = true;
+      evidence.push('/.dockerenv exists');
+    }
+  } catch {
+    // ignore
+  }
+  try {
+    if (fs.existsSync('/proc/1/cgroup')) {
+      const cgroup = fs.readFileSync('/proc/1/cgroup', 'utf-8');
+      if (/docker|containerd|kubepods/i.test(cgroup)) {
+        inDocker = true;
+        evidence.push('/proc/1/cgroup mentions a container runtime');
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return { inDocker, evidence };
+}
+
+/**
+ * Strip credentials from URL-like strings so they can safely appear in sys.txt.
+ * Returns the input unchanged for non-URL values.
+ * @param {string} value
+ * @returns {string}
+ */
+function sanitizeUrlLike(value) {
+  if (typeof value !== 'string' || value.length === 0) return value;
+  try {
+    const u = new URL(value);
+    if (u.username || u.password) {
+      u.username = '***';
+      u.password = '***';
+    }
+    return u.toString();
+  } catch {
+    return value;
+  }
+}
+
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes)) return String(bytes);
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KiB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(2)} MiB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GiB`;
+}
+
+function formatDuration(seconds) {
+  if (!Number.isFinite(seconds)) return String(seconds);
+  const s = Math.floor(seconds);
+  const days = Math.floor(s / 86400);
+  const hours = Math.floor((s % 86400) / 3600);
+  const minutes = Math.floor((s % 3600) / 60);
+  const secs = s % 60;
+  return `${days}d ${hours}h ${minutes}m ${secs}s`;
+}
+
+/**
+ * Build a plaintext system / runtime report for inclusion in the debug zip. Settings
+ * are sanitized, proxy URL credentials and session secrets are stripped before
+ * serialization.
+ *
+ * @param {object} [options]
+ * @param {object} [options.settings]
+ * @returns {Promise<string>}
+ */
+export async function buildSystemInfo({ settings = null } = {}) {
+  const fredyVersion = await getPackageVersion();
+  const docker = detectDocker();
+  const cpus = os.cpus() || [];
+  const procMem = process.memoryUsage();
+
+  const lines = [];
+  lines.push('# Fredy Debug Report');
+  lines.push(`Generated at: ${new Date().toISOString()}`);
+  lines.push('');
+
+  lines.push('## Application');
+  lines.push(`Fredy version:     ${fredyVersion}`);
+  lines.push(`Node.js version:   ${process.version}`);
+  lines.push(`Process uptime:    ${formatDuration(process.uptime())}`);
+  lines.push(`PID:               ${process.pid}`);
+  lines.push(`Env (NODE_ENV):    ${process.env.NODE_ENV || 'development'}`);
+  lines.push('');
+
+  lines.push('## Operating System');
+  lines.push(`Platform:          ${process.platform}`);
+  lines.push(`Architecture:      ${process.arch}`);
+  lines.push(`OS type:           ${os.type()}`);
+  lines.push(`OS release:        ${os.release()}`);
+  lines.push(`OS version:        ${typeof os.version === 'function' ? os.version() : 'n/a'}`);
+  lines.push(`Hostname:          ${os.hostname()}`);
+  lines.push(`System uptime:     ${formatDuration(os.uptime())}`);
+  lines.push('');
+
+  lines.push('## Container');
+  lines.push(`Running in Docker: ${docker.inDocker ? 'yes' : 'no'}`);
+  if (docker.evidence.length > 0) {
+    lines.push(`Evidence:          ${docker.evidence.join('; ')}`);
+  }
+  if (process.env.FREDY_IMAGE_TAG) {
+    lines.push(`Image tag:         ${process.env.FREDY_IMAGE_TAG}`);
+  }
+  lines.push('');
+
+  lines.push('## Hardware');
+  lines.push(`CPU count:         ${cpus.length}`);
+  lines.push(`CPU model:         ${cpus[0]?.model || 'unknown'}`);
+  lines.push(`Total memory:      ${formatBytes(os.totalmem())}`);
+  lines.push(`Free memory:       ${formatBytes(os.freemem())}`);
+  lines.push(`Process RSS:       ${formatBytes(procMem.rss)}`);
+  lines.push(`Process heapUsed:  ${formatBytes(procMem.heapUsed)}`);
+  lines.push(`Process heapTotal: ${formatBytes(procMem.heapTotal)}`);
+  lines.push('');
+
+  if (settings && typeof settings === 'object') {
+    lines.push('## Settings (sanitized)');
+    const safe = { ...settings };
+    if (safe.proxyUrl) safe.proxyUrl = sanitizeUrlLike(safe.proxyUrl);
+    delete safe.session_secret;
+    delete safe.sessionSecret;
+    for (const [key, value] of Object.entries(safe)) {
+      let printed;
+      if (value == null) {
+        printed = 'null';
+      } else if (typeof value === 'object') {
+        try {
+          printed = JSON.stringify(value);
+        } catch {
+          printed = String(value);
+        }
+      } else {
+        printed = String(value);
+      }
+      lines.push(`${key}: ${printed}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build the final debug bundle zip buffer (logs.txt + sys.txt). The caller is
+ * responsible for checking wasEverEnabled() before invoking this, we still produce
+ * a valid zip even when there are zero log rows (logs.txt will contain a placeholder)
+ * because the route layer handles the user-friendly 409 case.
+ *
+ * @param {object} [options]
+ * @param {object} [options.settings] Runtime settings to embed in sys.txt.
+ * @returns {Promise<Buffer>}
+ */
+export async function buildDebugBundleZip({ settings = null } = {}) {
+  const logsContent = renderLogsTxt() || 'No debug log entries are currently stored.\n';
+  const sysContent = await buildSystemInfo({ settings });
+
+  const AdmZip = await getAdmZip();
+  const zip = new AdmZip();
+  zip.addFile(LOGS_FILE_NAME, Buffer.from(logsContent, 'utf-8'));
+  zip.addFile(SYSTEM_INFO_FILE_NAME, Buffer.from(sysContent, 'utf-8'));
+  return zip.toBuffer();
+}

lib/services/debug/debugLogStorage.js

@@ -0,0 +1,346 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import SqliteConnection from '../storage/SqliteConnection.js';
+import { upsertSettings, getSettings } from '../storage/settingsStorage.js';
+import logger from '../logger.js';
+
+/**
+ * Hard cap on the total UTF-8 byte length of stored log MESSAGES (5 MiB).
+ *
+ * Note: this measures the payload bytes (message strings only); SQLite per-row
+ * overhead (id, ts, level, byte_size columns + page housekeeping) means the actual
+ * sqlite_master page count for debug_logs can be larger than this cap by a constant
+ * factor. The cap is intentionally about user-visible payload to keep the math
+ * predictable and to align with what ends up in logs.txt.
+ *
+ * The cap is enforced via a rolling buffer: when the live size exceeds it, the
+ * oldest rows are removed until the size falls below the limit again.
+ * @type {number}
+ */
+export const MAX_DEBUG_LOG_BYTES = 5 * 1024 * 1024;
+
+/** Settings key persisting the active on/off flag. */
+const SETTING_ENABLED = 'debug_logging_enabled';
+
+/**
+ * Settings key persisting "this feature has been turned on at least once". Used to
+ * decide whether the download endpoint returns 409 (never enabled) or whether the
+ * "delete previous logs?" confirm dialog should be shown on (re)enable.
+ */
+const SETTING_EVER_ENABLED = 'debug_logging_ever_enabled';
+
+/**
+ * Cached live byte size of all rows in debug_logs. Initialized lazily from the DB on
+ * the first call and kept in sync by append / clear / trim. Storing this in-memory
+ * avoids running SUM() on every single insert (logger writes can be very frequent).
+ * @type {number|null}
+ */
+let cachedSize = null;
+
+/**
+ * Cached value of debug_logging_enabled. Reflects DB state; flipped by enable() /
+ * disable() so the logger hot-path does not have to hit the settings cache for every
+ * log line.
+ * @type {boolean|null}
+ */
+let cachedEnabled = null;
+
+/**
+ * Compute the UTF-8 byte length of a string. Falls back to character count for
+ * environments where Buffer is not available (vitest covers Node, so it always is).
+ * @param {string} str
+ * @returns {number}
+ */
+function byteLengthOf(str) {
+  if (typeof str !== 'string') return 0;
+  if (typeof Buffer !== 'undefined' && typeof Buffer.byteLength === 'function') {
+    return Buffer.byteLength(str, 'utf-8');
+  }
+  return str.length;
+}
+
+/**
+ * Read the current total byte size from the DB and update the local cache.
+ * @returns {number}
+ */
+function refreshSizeFromDb() {
+  const rows = SqliteConnection.query('SELECT COALESCE(SUM(byte_size), 0) AS total FROM debug_logs');
+  cachedSize = Number(rows?.[0]?.total ?? 0);
+  return cachedSize;
+}
+
+/**
+ * Lazily ensure the cached enabled/size values are up to date. Called by every public
+ * method that needs to know either value, so external init is not required.
+ * @returns {Promise<void>}
+ */
+async function ensureCachesInitialized() {
+  if (cachedEnabled == null) {
+    const settings = await getSettings();
+    cachedEnabled = settings[SETTING_ENABLED] === true;
+  }
+  if (cachedSize == null) {
+    refreshSizeFromDb();
+  }
+}
+
+/**
+ * Cached prepared statements used by trimToFit(). Initialized on first use so we do
+ * not pay the prepare cost on every overflow event, and skipped entirely when the
+ * feature is never activated.
+ * @type {{select:any, del:any}|null}
+ */
+let trimStatements = null;
+
+/**
+ * Drop the oldest rows from debug_logs until the cached size falls below
+ * MAX_DEBUG_LOG_BYTES. Implements the rolling buffer behavior chosen for the feature.
+ *
+ * The deletion is performed in batches of up to 100 oldest rows wrapped in a single
+ * transaction. The size cache is updated only after the transaction commits, so a
+ * mid-batch failure (rolled back by SQLite) cannot leave cachedSize out of sync with
+ * the on-disk reality. A defensive resync via SUM() is performed on transaction
+ * failure to recover from any unexpected drift.
+ *
+ * @returns {void}
+ */
+function trimToFit() {
+  if (cachedSize == null || cachedSize <= MAX_DEBUG_LOG_BYTES) return;
+
+  const db = SqliteConnection.getConnection();
+  if (trimStatements == null) {
+    trimStatements = {
+      select: db.prepare('SELECT id, byte_size FROM debug_logs ORDER BY id ASC LIMIT 100'),
+      del: db.prepare('DELETE FROM debug_logs WHERE id = @id'),
+    };
+  }
+
+  while (cachedSize > MAX_DEBUG_LOG_BYTES) {
+    const oldest = trimStatements.select.all();
+    if (oldest.length === 0) {
+      // Table is empty but the cache still claims we are over the cap. That can only
+      // happen if cachedSize drifted (e.g. external DB modification, zero-byte
+      // messages that never contributed to SUM(byte_size), or a previous trim that
+      // partially succeeded). Resync from the source of truth and bail out.
+      refreshSizeFromDb();
+      break;
+    }
+
+    // Pick exactly enough oldest rows to bring the cache back under the cap. We do
+    // NOT delete the entire 100-row batch unconditionally, that would over-trim in
+    // edge cases where just one or two rows are enough.
+    const needToFree = cachedSize - MAX_DEBUG_LOG_BYTES;
+    let freed = 0;
+    const idsToDelete = [];
+    for (const row of oldest) {
+      idsToDelete.push(row.id);
+      freed += Number(row.byte_size) || 0;
+      if (freed >= needToFree) break;
+    }
+
+    try {
+      const tx = db.transaction((ids) => {
+        for (const id of ids) {
+          trimStatements.del.run({ id });
+        }
+      });
+      tx(idsToDelete);
+      // Only decrement after the transaction has committed; a mid-batch failure
+      // would roll the DELETEs back and leave cachedSize untouched.
+      cachedSize -= freed;
+      if (freed === 0) {
+        // We deleted rows but they all had byte_size <= 0, so cachedSize did not
+        // move. Without intervention the outer loop would spin again with the same
+        // condition. Resync from the DB and bail to prevent that.
+        refreshSizeFromDb();
+        break;
+      }
+    } catch {
+      // SQLite rolled the batch back; resync cachedSize from the DB to recover from
+      // any unexpected drift, then bail out so we do not spin forever on a persistent
+      // failure (e.g. database is locked or read-only).
+      refreshSizeFromDb();
+      break;
+    }
+  }
+  if (cachedSize < 0) cachedSize = 0;
+}
+
+/**
+ * Whether debug logging is currently enabled. Synchronous and cheap so the logger
+ * hot-path can call it on every log line.
+ *
+ * @returns {boolean} True if logs should be persisted to the debug_logs table.
+ */
+export function isEnabled() {
+  return cachedEnabled === true;
+}
+
+/**
+ * Append a single log entry to debug_logs (if enabled) and trim the rolling buffer if
+ * the new row pushes the live size above the cap.
+ *
+ * Safe to call even when logging is disabled, it becomes a no-op. Any storage error
+ * is swallowed so the logger never breaks the calling code; bookkeeping for cachedSize
+ * stays consistent because we update it only after a successful insert.
+ *
+ * @param {{ts:number, level:string, message:string}} entry
+ * @returns {void}
+ */
+export function appendLogEntry(entry) {
+  if (!isEnabled()) return;
+  if (!entry || typeof entry.message !== 'string') return;
+
+  try {
+    const ts = Number.isFinite(entry.ts) ? entry.ts : Date.now();
+    const level = String(entry.level || 'info');
+    const message = entry.message;
+    const byte_size = byteLengthOf(message);
+
+    SqliteConnection.execute(
+      'INSERT INTO debug_logs (ts, level, message, byte_size) VALUES (@ts, @level, @message, @byte_size)',
+      { ts, level, message, byte_size },
+    );
+
+    if (cachedSize == null) {
+      refreshSizeFromDb();
+    } else {
+      cachedSize += byte_size;
+    }
+    trimToFit();
+  } catch {
+    // Logging must never break the application. Swallow storage errors silently.
+  }
+}
+
+/**
+ * Remove every row from debug_logs and reset the cached size to zero. Used by both
+ * the "clear previous logs" path on (re)enable and by explicit clear actions.
+ *
+ * @returns {void}
+ */
+export function clearAllDebugLogs() {
+  SqliteConnection.execute('DELETE FROM debug_logs');
+  cachedSize = 0;
+}
+
+/**
+ * Return the cached live byte size of the debug_logs table contents.
+ * @returns {Promise<number>}
+ */
+export async function getCurrentSize() {
+  await ensureCachesInitialized();
+  return cachedSize ?? 0;
+}
+
+/**
+ * Return the configured maximum size for the debug_logs table.
+ * @returns {number}
+ */
+export function getMaxSize() {
+  return MAX_DEBUG_LOG_BYTES;
+}
+
+/**
+ * Check whether the debug_logs table contains at least one row.
+ * @returns {boolean}
+ */
+export function hasAnyLogs() {
+  const row = SqliteConnection.query('SELECT 1 AS one FROM debug_logs LIMIT 1');
+  return Array.isArray(row) && row.length > 0;
+}
+
+/**
+ * Has debug logging ever been enabled in this installation? Used by the download
+ * endpoint to distinguish "no logs yet" (empty table) from "feature never used"
+ * (which returns 409 to surface a friendlier UI error).
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function wasEverEnabled() {
+  const settings = await getSettings();
+  return settings[SETTING_EVER_ENABLED] === true;
+}
+
+/**
+ * Turn debug logging on. Persists both the active flag and the "ever enabled" flag,
+ * optionally clearing previous logs when the caller passes clearPrevious=true (this
+ * is the path taken when the UI confirm dialog "Delete previous logs?" is accepted).
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.clearPrevious=false]
+ * @returns {Promise<void>}
+ */
+export async function enableDebugLogging({ clearPrevious = false } = {}) {
+  if (clearPrevious) {
+    clearAllDebugLogs();
+  }
+  upsertSettings({ [SETTING_ENABLED]: true, [SETTING_EVER_ENABLED]: true });
+  cachedEnabled = true;
+  if (cachedSize == null) {
+    refreshSizeFromDb();
+  }
+  // Attach the logger sink only while recording is on so the logger hot path pays
+  // no per-call cost (Date.now + stringifyArgs) when nobody enabled the feature.
+  logger.setDebugLogSink(appendLogEntry);
+}
+
+/**
+ * Turn debug logging off. Previous logs are kept on disk so the user can still
+ * download them; they are only cleared when the user re-enables and chooses "delete
+ * previous logs".
+ *
+ * @returns {Promise<void>}
+ */
+export async function disableDebugLogging() {
+  upsertSettings({ [SETTING_ENABLED]: false });
+  cachedEnabled = false;
+  // Detach the sink so the logger hot path returns immediately on its `if (sink)`
+  // check instead of paying the no-op cost on every log line.
+  logger.setDebugLogSink(null);
+}
+
+/**
+ * Return all stored log entries ordered chronologically. Used by the bundle builder
+ * when assembling logs.txt.
+ *
+ * @returns {{id:number, ts:number, level:string, message:string}[]}
+ */
+export function getAllDebugLogs() {
+  return SqliteConnection.query('SELECT id, ts, level, message FROM debug_logs ORDER BY id ASC');
+}
+
+/**
+ * Reload the cached enabled flag from settings storage. Called from the logger at
+ * startup so the cache reflects the persisted state after a Fredy restart.
+ *
+ * @returns {Promise<boolean>} The active enabled flag.
+ */
+export async function reloadEnabledFromSettings() {
+  const settings = await getSettings();
+  cachedEnabled = settings[SETTING_ENABLED] === true;
+  // (Un)wire the sink to match the persisted state. Note: startup work that runs
+  // before index.js calls this (CloakBrowser binary check, runMigrations) still
+  // logs to stdout only, since the sink is not attached yet at that point.
+  if (cachedEnabled) {
+    logger.setDebugLogSink(appendLogEntry);
+  } else {
+    logger.setDebugLogSink(null);
+  }
+  return cachedEnabled;
+}
+
+/**
+ * Test-only helper to drop in-memory caches between unit tests. Resets every piece
+ * of module-scoped mutable state so a test that swaps the underlying DB does not
+ * inherit stale prepared statements from a previous run.
+ * @returns {void}
+ */
+export function _resetForTests() {
+  cachedSize = null;
+  cachedEnabled = null;
+  trimStatements = null;
+}

lib/services/ensureValidBinary.js

@@ -0,0 +1,147 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import { ensureBinary } from 'cloakbrowser';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+/**
+ * Resource files required on Linux/Windows — they must live next to the chrome binary.
+ * macOS packages these inside the .app bundle's Frameworks directory so a different
+ * check is used there (see isBinaryComplete).
+ */
+const LINUX_WIN_REQUIRED_FILES = ['icudtl.dat', 'resources.pak'];
+
+/**
+ * Return the top-level versioned installation directory for any platform.
+ *
+ * - Linux/Windows: binaryPath is   ~/.cloakbrowser/chromium-X.Y.Z/chrome
+ *                  → dirname        ~/.cloakbrowser/chromium-X.Y.Z/
+ * - macOS:         binaryPath is   ~/.cloakbrowser/chromium-X.Y.Z/Chromium.app/Contents/MacOS/Chromium
+ *                  → 4 levels up    ~/.cloakbrowser/chromium-X.Y.Z/
+ *
+ * @param {string} binaryPath
+ * @returns {string}
+ */
+function getVersionedDir(binaryPath) {
+  if (process.platform === 'darwin') {
+    return path.resolve(path.dirname(binaryPath), '../../..');
+  }
+  return path.dirname(binaryPath);
+}
+
+/**
+ * Return true when the binary at binaryPath belongs to a complete installation.
+ *
+ * On macOS the binary lives inside an .app bundle:
+ *   Chromium.app/Contents/MacOS/Chromium
+ * Resource files (icudtl.dat etc.) are deep inside
+ *   Chromium.app/Contents/Frameworks/…
+ * so checking for them next to the binary is wrong. Instead we verify the two
+ * structural markers that are only present after a full extraction: Info.plist
+ * and the Frameworks directory inside Contents/.
+ *
+ * On Linux/Windows the binary and all resource files are siblings in the same
+ * directory.
+ *
+ * @param {string} binaryPath
+ * @returns {boolean}
+ */
+function isBinaryComplete(binaryPath) {
+  if (process.platform === 'darwin') {
+    const contentsDir = path.resolve(path.dirname(binaryPath), '..');
+    return fs.existsSync(path.join(contentsDir, 'Info.plist')) && fs.existsSync(path.join(contentsDir, 'Frameworks'));
+  }
+  const dir = path.dirname(binaryPath);
+  return LINUX_WIN_REQUIRED_FILES.every((f) => fs.existsSync(path.join(dir, f)));
+}
+
+/**
+ * Return a human-readable description of which required files/dirs are missing.
+ *
+ * @param {string} binaryPath
+ * @returns {string}
+ */
+function missingDescription(binaryPath) {
+  if (process.platform === 'darwin') {
+    const contentsDir = path.resolve(path.dirname(binaryPath), '..');
+    return ['Info.plist', 'Frameworks'].filter((f) => !fs.existsSync(path.join(contentsDir, f))).join(', ');
+  }
+  const dir = path.dirname(binaryPath);
+  return LINUX_WIN_REQUIRED_FILES.filter((f) => !fs.existsSync(path.join(dir, f))).join(', ');
+}
+
+/**
+ * Remove a corrupt binary installation and all `latest_version*` markers from
+ * the CloakBrowser cache so the next `ensureBinary()` call falls back to the
+ * package-bundled version.
+ *
+ * Removes the full versioned directory (e.g. chromium-X.Y.Z/) on all platforms,
+ * not just the subdirectory that contains the binary.
+ *
+ * @param {string} binaryPath - Path to the (corrupt) chrome/Chromium binary.
+ */
+function removeCorruptInstallation(binaryPath) {
+  const versionedDir = getVersionedDir(binaryPath);
+  const cacheDir = process.env.CLOAKBROWSER_CACHE_DIR || path.join(os.homedir(), '.cloakbrowser');
+
+  fs.rmSync(versionedDir, { recursive: true, force: true });
+
+  try {
+    for (const entry of fs.readdirSync(cacheDir)) {
+      if (entry.startsWith('latest_version')) {
+        fs.rmSync(path.join(cacheDir, entry), { force: true });
+      }
+    }
+  } catch {
+    // Cache dir may not exist if versionedDir was the only entry — ignore.
+  }
+}
+
+/**
+ * Ensure the CloakBrowser stealth Chromium binary is present **and** complete.
+ *
+ * `cloakbrowser`'s own `ensureBinary()` only checks that the chrome/Chromium
+ * file exists. An incomplete extraction (e.g. interrupted download, disk full)
+ * can leave a directory that contains the executable but is missing essential
+ * resource files. Chrome then crashes immediately on launch.
+ *
+ * This wrapper validates the path returned by `ensureBinary()`. If the
+ * installation is incomplete it removes the corrupt directory, clears the
+ * version marker files, and calls `ensureBinary()` again so it falls back to
+ * (or re-downloads) a complete build.
+ *
+ * The validated path is also pinned via `CLOAKBROWSER_BINARY_PATH` so that
+ * CloakBrowser's own internal `ensureBinary()` call inside `launch()` always
+ * picks up the same, verified binary.
+ *
+ * @returns {Promise<string>} Absolute path to the validated binary.
+ * @throws {Error} When even the fallback binary is incomplete.
+ */
+export async function ensureValidBinary() {
+  const binaryPath = await ensureBinary();
+
+  if (isBinaryComplete(binaryPath)) {
+    process.env.CLOAKBROWSER_BINARY_PATH = binaryPath;
+    return binaryPath;
+  }
+
+  console.warn(
+    `[fredy] CloakBrowser installation at ${getVersionedDir(binaryPath)} is missing: ${missingDescription(binaryPath)}. Removing and retrying.`,
+  );
+
+  removeCorruptInstallation(binaryPath);
+
+  const fallbackPath = await ensureBinary();
+  if (!isBinaryComplete(fallbackPath)) {
+    throw new Error(
+      `CloakBrowser binary at ${getVersionedDir(fallbackPath)} is still missing required files after re-download: ${missingDescription(fallbackPath)}`,
+    );
+  }
+
+  process.env.CLOAKBROWSER_BINARY_PATH = fallbackPath;
+  return fallbackPath;
+}

lib/services/events/event-bus.js

@@ -1,2 +1,7 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { EventEmitter } from 'node:events';
 export const bus = new EventEmitter();

lib/services/extractor/botPrevention.js

@@ -0,0 +1,333 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import { DEFAULT_HEADER } from './utils.js';
+
+// Helper to safely coerce numbers
+const toInt = (v, d) => {
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) ? n : d;
+};
+
+/**
+ * Compute pre-launch configuration and flags for Puppeteer with bot prevention in mind.
+ * Returns language, user agent, viewport (with optional jitter), and additional launch args.
+ *
+ * @param {string} url
+ * @param {object} [options]
+ */
+export function getPreLaunchConfig(url, options = {}) {
+  const { hostname } = new URL(url);
+
+  const acceptLanguage = options.acceptLanguage || 'de-DE,de;q=0.9,en-US;q=0.7,en;q=0.5';
+  const langForFlag = acceptLanguage.split(',')[0];
+
+  const baseViewport = { width: 1366, height: 768, deviceScaleFactor: 1 };
+  const jitter = options.viewportJitter !== false ? Math.floor(Math.random() * 6) : 0; // 0..5 px
+  const width = toInt(options?.viewport?.width, baseViewport.width) + jitter;
+  const height = toInt(options?.viewport?.height, baseViewport.height) + jitter;
+  const deviceScaleFactor = toInt(options?.viewport?.deviceScaleFactor, baseViewport.deviceScaleFactor);
+  const viewport = { width, height, deviceScaleFactor };
+
+  const userAgent =
+    options.userAgent ||
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36';
+
+  const windowSizeArg = `--window-size=${viewport.width},${viewport.height}`;
+  const langArg = `--lang=${langForFlag}`;
+
+  const extraArgs = [
+    '--disable-blink-features=AutomationControlled',
+    '--force-webrtc-ip-handling-policy=disable_non_proxied_udp',
+    '--webrtc-ip-handling-policy=default_public_interface_only',
+    '--proxy-bypass-list=<-loopback>',
+  ];
+
+  const headers = {
+    ...DEFAULT_HEADER,
+    'Accept-Language': acceptLanguage,
+    'User-Agent': userAgent,
+    Referer: options?.referer || `https://${hostname}/`,
+    Connection: 'keep-alive',
+    DNT: '1',
+  };
+
+  const timezone = options?.timezone || 'Europe/Berlin';
+
+  return {
+    acceptLanguage,
+    langForFlag,
+    userAgent,
+    viewport,
+    windowSizeArg,
+    langArg,
+    extraArgs,
+    headers,
+    timezone,
+    humanDelay: options?.humanDelay !== false,
+  };
+}
+
+/**
+ * Apply bot-prevention hardening to a Puppeteer page.
+ * Sets UA, viewport, JS enabled, headers, timezone and injects stealth-like patches.
+ *
+ * @param {import('puppeteer').Page} page
+ * @param {ReturnType<typeof getPreLaunchConfig>} cfg
+ */
+export async function applyBotPreventionToPage(page, cfg) {
+  await page.setUserAgent(cfg.userAgent);
+  await page.setViewport(cfg.viewport);
+  await page.setJavaScriptEnabled(true);
+  await page.setExtraHTTPHeaders(cfg.headers);
+  try {
+    if (cfg.timezone) await page.emulateTimezone(cfg.timezone);
+  } catch {
+    // ignore timezone failures
+  }
+
+  // Inject patches as early as possible
+  await page.evaluateOnNewDocument(() => {
+    try {
+      // webdriver
+      Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+
+      // chrome runtime - expose loadTimes, csi and app like real Chrome
+      // @ts-ignore
+      window.chrome = {
+        runtime: {},
+        // @ts-ignore
+        loadTimes: () => ({
+          requestTime: performance.timeOrigin / 1000,
+          startLoadTime: performance.timeOrigin / 1000,
+          commitLoadTime: performance.timeOrigin / 1000 + 0.1,
+          finishDocumentLoadTime: 0,
+          finishLoadTime: 0,
+          firstPaintTime: 0,
+          firstPaintAfterLoadTime: 0,
+          navigationType: 'Other',
+          wasFetchedViaSpdy: false,
+          wasNpnNegotiated: false,
+          npnNegotiatedProtocol: '',
+          wasAlternateProtocolAvailable: false,
+          connectionInfo: 'http/1.1',
+        }),
+        // @ts-ignore
+        csi: () => ({ startE: performance.timeOrigin, onloadT: Date.now(), pageT: performance.now(), tran: 15 }),
+        app: {
+          isInstalled: false,
+          InstallState: { DISABLED: 'disabled', INSTALLED: 'installed', NOT_INSTALLED: 'not_installed' },
+          RunningState: { CANNOT_RUN: 'cannot_run', READY_TO_RUN: 'ready_to_run', RUNNING: 'running' },
+        },
+      };
+
+      // languages
+      // @ts-ignore
+      Object.defineProperty(navigator, 'languages', {
+        get: () => (window.localStorage.getItem('__LANGS__') || 'de-DE,de').split(','),
+      });
+
+      // plugins - mimic real Chrome's built-in PDF plugins
+      const makePlugin = (name, filename, description, mimeType, mimeTypeSuffix) => {
+        const mimeObj = { type: mimeType, suffixes: mimeTypeSuffix, description, enabledPlugin: null };
+        const plugin = { name, filename, description, length: 1, 0: mimeObj };
+        mimeObj.enabledPlugin = plugin;
+        return plugin;
+      };
+      const fakePlugins = [
+        makePlugin('PDF Viewer', 'internal-pdf-viewer', 'Portable Document Format', 'application/pdf', 'pdf'),
+        makePlugin('Chrome PDF Viewer', 'internal-pdf-viewer', 'Portable Document Format', 'application/pdf', 'pdf'),
+        makePlugin('Chromium PDF Viewer', 'internal-pdf-viewer', 'Portable Document Format', 'application/pdf', 'pdf'),
+        makePlugin(
+          'Microsoft Edge PDF Viewer',
+          'internal-pdf-viewer',
+          'Portable Document Format',
+          'application/pdf',
+          'pdf',
+        ),
+        makePlugin('WebKit built-in PDF', 'internal-pdf-viewer', 'Portable Document Format', 'application/pdf', 'pdf'),
+      ];
+      // @ts-ignore
+      Object.defineProperty(navigator, 'plugins', { get: () => fakePlugins });
+      // @ts-ignore
+      Object.defineProperty(navigator, 'mimeTypes', { get: () => [fakePlugins[0][0]] });
+
+      // platform and concurrency hints
+      // @ts-ignore
+      Object.defineProperty(navigator, 'platform', { get: () => 'Win32' });
+      // @ts-ignore
+      Object.defineProperty(navigator, 'hardwareConcurrency', { get: () => 8 });
+      // @ts-ignore
+      Object.defineProperty(navigator, 'deviceMemory', { get: () => 8 });
+
+      // userAgentData (Client Hints)
+      try {
+        // @ts-ignore
+        if ('userAgentData' in navigator) {
+          // @ts-ignore
+          Object.defineProperty(navigator, 'userAgentData', {
+            get: () => ({
+              brands: [
+                { brand: 'Chromium', version: '126' },
+                { brand: 'Google Chrome', version: '126' },
+              ],
+              mobile: false,
+              platform: 'Windows',
+              getHighEntropyValues: async (hints) => {
+                const values = {
+                  platform: 'Windows',
+                  platformVersion: '15.0.0',
+                  architecture: 'x86',
+                  model: '',
+                  uaFullVersion: '126.0.0.0',
+                  bitness: '64',
+                };
+                const out = {};
+                for (const k of hints || []) if (k in values) out[k] = values[k];
+                return out;
+              },
+            }),
+          });
+        }
+      } catch {
+        //noop
+      }
+
+      // Permissions API
+      const origQuery = navigator.permissions && navigator.permissions.query;
+      if (origQuery) {
+        // @ts-ignore
+        navigator.permissions.query = (parameters) =>
+          origQuery.call(navigator.permissions, parameters).then((result) => {
+            if (parameters && parameters.name === 'notifications') {
+              Object.defineProperty(result, 'state', { get: () => Notification.permission });
+            }
+            return result;
+          });
+      }
+
+      // WebGL vendor/renderer
+      const patchWebGL = (proto) => {
+        if (!proto || !proto.getParameter) return;
+        const getParameter = proto.getParameter;
+        // @ts-ignore
+        proto.getParameter = function (param) {
+          const UNMASKED_VENDOR_WEBGL = 0x9245;
+          const UNMASKED_RENDERER_WEBGL = 0x9246;
+          if (param === UNMASKED_VENDOR_WEBGL) return 'Google Inc.';
+          if (param === UNMASKED_RENDERER_WEBGL)
+            return 'ANGLE (NVIDIA, NVIDIA GeForce GTX 1660 Ti Direct3D11 vs_5_0 ps_5_0)';
+          return getParameter.call(this, param);
+        };
+      };
+      // @ts-ignore
+      patchWebGL(WebGLRenderingContext?.prototype);
+      // @ts-ignore
+      patchWebGL(WebGL2RenderingContext?.prototype);
+
+      // AudioContext timestamp rounding consistency
+      const patchAudio = (Ctx) => {
+        try {
+          if (!Ctx) return;
+          const proto = Ctx.prototype;
+          const createOsc = proto.createOscillator;
+          proto.createOscillator = function () {
+            const osc = createOsc.call(this);
+            const start = osc.start;
+            osc.start = function (when) {
+              return start.call(this, when || 0);
+            };
+            return osc;
+          };
+        } catch {
+          //noop
+        }
+      };
+      // @ts-ignore
+      patchAudio(window.AudioContext);
+      // @ts-ignore
+      patchAudio(window.OfflineAudioContext);
+
+      // Navigator.connection
+      try {
+        // @ts-ignore
+        Object.defineProperty(navigator, 'connection', { get: () => undefined });
+      } catch {
+        //noop
+      }
+
+      // Consistent outer sizes
+      try {
+        const calcOuter = () => {
+          const w = window.innerWidth + 16;
+          const h = window.innerHeight + 88;
+          return { w, h };
+        };
+        const { w: outerW, h: outerH } = calcOuter();
+        // @ts-ignore
+        Object.defineProperty(window, 'outerWidth', { get: () => outerW });
+        // @ts-ignore
+        Object.defineProperty(window, 'outerHeight', { get: () => outerH });
+      } catch {
+        //noop
+      }
+
+      // document.hasFocus - headless returns false; real active tabs return true
+      try {
+        document.hasFocus = () => true;
+      } catch {
+        //noop
+      }
+
+      // screen color depth - normalise in case headless reports 0
+      try {
+        Object.defineProperty(screen, 'colorDepth', { get: () => 24 });
+        Object.defineProperty(screen, 'pixelDepth', { get: () => 24 });
+      } catch {
+        //noop
+      }
+    } catch {
+      //noop
+    }
+  });
+}
+
+/**
+ * Persist languages value before navigation via localStorage.
+ * @param {import('puppeteer').Page} page
+ * @param {ReturnType<typeof getPreLaunchConfig>} cfg
+ */
+export async function applyLanguagePersistence(page, cfg) {
+  await page.evaluateOnNewDocument((langs) => {
+    try {
+      window.localStorage.setItem('__LANGS__', langs);
+    } catch {
+      // noop
+    }
+  }, cfg.acceptLanguage.split(';')[0]);
+}
+
+/**
+ * Perform subtle human-like interactions post navigation.
+ * @param {import('puppeteer').Page} page
+ * @param {ReturnType<typeof getPreLaunchConfig>} cfg
+ */
+export async function applyPostNavigationHumanSignals(page, cfg) {
+  if (!cfg.humanDelay) return;
+  const delay = 200 + Math.floor(Math.random() * 400);
+  await new Promise((res) => setTimeout(res, delay));
+  try {
+    const vw = cfg.viewport.width;
+    const vh = cfg.viewport.height;
+    const mx = Math.floor(vw * (0.3 + Math.random() * 0.4));
+    const my = Math.floor(vh * (0.3 + Math.random() * 0.4));
+    await page.mouse.move(mx, my, { steps: 10 + Math.floor(Math.random() * 10) });
+    await page.mouse.wheel({ deltaY: 100 + Math.floor(Math.random() * 200) });
+    await new Promise((res) => setTimeout(res, 150 + Math.floor(Math.random() * 200)));
+    await page.mouse.wheel({ deltaY: -(30 + Math.floor(Math.random() * 60)) });
+  } catch {
+    // ignore if mouse is unavailable
+  }
+}

lib/services/extractor/extractor.js

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import { setDebug } from './utils.js';
 import puppeteerExtractor from './puppeteerExtractor.js';
 import { loadParser, parse } from './parser/parser.js';
@@ -24,11 +29,12 @@ export default class Extractor {
    * your response will never contain what you are really looking for
    * @param url
    * @param waitForSelector
+   * @param jobKey
    */
-  execute = async (url, waitForSelector = null) => {
+  execute = async (url, waitForSelector = null, jobKey = null) => {
     this.responseText = null;
     try {
-      this.responseText = await puppeteerExtractor(url, waitForSelector, this.options);
+      this.responseText = await puppeteerExtractor(url, waitForSelector, { ...this.options, name: jobKey });
       if (this.responseText != null) {
         loadParser(this.responseText);
       }

lib/services/extractor/parser/parser.js

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import * as cheerio from 'cheerio';
 import logger from '../../logger.js';
 

lib/services/extractor/puppeteerExtractor.js

@@ -1,51 +1,135 @@
-import puppeteer from 'puppeteer-extra';
-import StealthPlugin from 'puppeteer-extra-plugin-stealth';
-import { debug, DEFAULT_HEADER, botDetected } from './utils.js';
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
+import { launch } from 'cloakbrowser/puppeteer';
+import { botDetected, debug } from './utils.js';
+import { getPreLaunchConfig } from './botPrevention.js';
 import logger from '../logger.js';
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
+import { trackPoi } from '../tracking/Tracker.js';
+import { TRACKING_POIS } from '../../TRACKING_POIS.js';
 
-puppeteer.use(StealthPlugin());
+/**
+ * Launch a CloakBrowser/Puppeteer browser instance with stealth and humanizer enabled.
+ *
+ * CloakBrowser applies 49 C++ source-level patches (canvas, WebGL, audio, WebRTC,
+ * navigator.*, automation signals) that are indistinguishable from a real browser.
+ * All fingerprinting and human-behaviour simulation is handled natively; no CDP
+ * overrides (setUserAgent, setExtraHTTPHeaders, evaluateOnNewDocument) are applied
+ * here because they would create detectable inconsistencies on top of the C++ patches.
+ *
+ * @param {string} url - Initial URL (used to derive locale/timezone hints).
+ * @param {object} [options]
+ * @param {boolean} [options.puppeteerHeadless]
+ * @param {number}  [options.puppeteerTimeout]
+ * @param {string}  [options.proxyUrl]
+ * @param {string}  [options.timezone]
+ * @param {string}  [options.acceptLanguage]
+ * @param {object}  [options.viewport]
+ * @returns {Promise<import('puppeteer-core').Browser>}
+ */
+export async function launchBrowser(url, options) {
+  const preCfg = getPreLaunchConfig(url, options || {});
 
-export default async function execute(url, waitForSelector, options) {
-  let browser;
-  let page;
-  let result = null;
-  let userDataDir;
-  let removeUserDataDir = false;
+  // Docker requires --no-sandbox; CloakBrowser handles all stealth args internally.
+  // --ignore-certificate-errors is needed because CloakBrowser ships its own Chromium
+  // binary with an independent CA bundle that may not trust proxies or interceptors
+  // present in the host environment.
+  const args = [
+    '--no-sandbox',
+    '--disable-setuid-sandbox',
+    '--disable-dev-shm-usage',
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--ignore-certificate-errors',
+    // Disables the zygote process model. Required in some container environments
+    // (e.g. limited kernel namespaces) where the zygote cannot acquire the
+    // locks it needs and exits with "Invalid file descriptor to ICU data received".
+    '--no-zygote',
+    preCfg.windowSizeArg,
+  ];
+
+  return await launch({
+    headless: options?.puppeteerHeadless ?? true,
+    humanize: true,
+    args,
+    // locale sets Accept-Language headers and JS navigator.language consistently
+    locale: preCfg.langForFlag,
+    ...(options?.proxyUrl ? { proxy: options.proxyUrl } : {}),
+    ...(preCfg.timezone ? { timezone: preCfg.timezone } : {}),
+  });
+}
+
+/**
+ * Close a browser instance returned by {@link launchBrowser}.
+ *
+ * @param {import('puppeteer-core').Browser | null} browser
+ */
+export async function closeBrowser(browser) {
+  if (!browser) return;
   try {
-    debug(`Sending request to ${url} using Puppeteer.`);
+    await browser.close();
+  } catch {
+    // ignore
+  }
+}
 
-    // Prepare a dedicated temporary userDataDir to avoid leaking /tmp/.org.chromium.* dirs
-    if (options && options.userDataDir) {
-      userDataDir = options.userDataDir;
-      removeUserDataDir = !!options.cleanupUserDataDir;
-    } else {
-      const prefix = path.join(os.tmpdir(), 'puppeteer-fredy-');
-      userDataDir = fs.mkdtempSync(prefix);
-      removeUserDataDir = true;
+/**
+ * Open a page in a (possibly reused) browser, navigate to `url`, and return the HTML source.
+ * Returns `null` when a bot-detection page is encountered or on timeout.
+ *
+ * @param {string} url
+ * @param {string | null} waitForSelector
+ * @param {object} [options]
+ * @returns {Promise<string | null>}
+ */
+export default async function execute(url, waitForSelector, options) {
+  let browser = options?.browser;
+  let isExternalBrowser = !!browser;
+  let page;
+  let result;
+  try {
+    debug(`Sending request to ${url} using CloakBrowser.`);
+
+    if (!isExternalBrowser) {
+      browser = await launchBrowser(url, options);
     }
 
-    browser = await puppeteer.launch({
-      headless: options.puppeteerHeadless ?? true,
-      args: [
-        '--no-sandbox',
-        '--disable-gpu',
-        '--disable-setuid-sandbox',
-        '--disable-dev-shm-usage',
-        '--disable-crash-reporter',
-      ],
-      timeout: options.puppeteerTimeout || 30_000,
-      userDataDir,
-    });
     page = await browser.newPage();
-    await page.setExtraHTTPHeaders(DEFAULT_HEADER);
+
+    if (Array.isArray(options?.cookies) && options.cookies.length > 0) {
+      await page.setCookie(...options.cookies);
+    }
+
+    // Warm-up navigation: visit a trusted page first so the site sees an
+    // established session before the actual target URL. Silently ignored on
+    // failure so it never blocks the main request.
+    if (options?.preNavigateUrl) {
+      try {
+        await page.goto(options.preNavigateUrl, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+        await new Promise((r) => setTimeout(r, 1500 + Math.random() * 2000));
+      } catch {
+        // ignore
+      }
+    }
+
     const response = await page.goto(url, {
-      waitUntil: 'domcontentloaded',
+      waitUntil: options?.waitUntil || 'domcontentloaded',
+      timeout: options?.puppeteerTimeout || 60000,
     });
+
+    // Optional second idle wait: useful for React SPAs that trigger API calls
+    // after domcontentloaded. Times out silently so we use whatever is rendered.
+    if (options?.waitForNetworkIdle) {
+      try {
+        await page.waitForNetworkIdle({ timeout: options?.waitForNetworkIdleTimeout ?? 60_000 });
+      } catch {
+        // ignore — we proceed with whatever the DOM contains at this point
+      }
+    }
+
     let pageSource;
-    // if we're extracting data from a SPA, we must wait for the selector
     if (waitForSelector != null) {
       const selectorTimeout = options?.puppeteerSelectorTimeout ?? options?.puppeteerTimeout ?? 30_000;
       await page.waitForSelector(waitForSelector, { timeout: selectorTimeout });
@@ -57,16 +141,27 @@ export default async function execute(url, waitForSelector, options) {
       pageSource = await page.content();
     }
 
-    const statusCode = response.status();
+    const statusCode = response?.status?.() ?? 200;
 
     if (botDetected(pageSource, statusCode)) {
       logger.warn('We have been detected as a bot :-/ Tried url: => ', url);
+
+      if (options != null && options.name != null) {
+        await trackPoi(TRACKING_POIS.DETECTED_AS_BOT + '_' + options.name);
+      } else {
+        await trackPoi(TRACKING_POIS.DETECTED_AS_BOT);
+      }
+
       result = null;
     } else {
       result = pageSource || (await page.content());
     }
   } catch (error) {
-    logger.warn('Error executing with puppeteer executor', error);
+    if (error?.name?.includes('Timeout')) {
+      logger.debug('Error executing with CloakBrowser executor', error);
+    } else {
+      logger.warn('Error executing with CloakBrowser executor', error);
+    }
     result = null;
   } finally {
     try {
@@ -76,19 +171,8 @@ export default async function execute(url, waitForSelector, options) {
     } catch {
       // ignore
     }
-    try {
-      if (browser != null) {
-        await browser.close();
-      }
-    } catch {
-      // ignore
-    }
-    try {
-      if (removeUserDataDir && userDataDir) {
-        await fs.promises.rm(userDataDir, { recursive: true, force: true });
-      }
-    } catch {
-      // ignore
+    if (browser != null && !isExternalBrowser) {
+      await closeBrowser(browser);
     }
   }
   return result;

lib/services/extractor/utils.js

@@ -1,3 +1,8 @@
+/*
+ * Copyright (c) 2026 by Christian Kellner.
+ * Licensed under Apache-2.0 with Commons Clause and Attribution/Naming Clause
+ */
+
 import logger from '../logger.js';
 
 let debuggingOn = false;