@gasolinaradar/repsol-collector 1.0.0

package/LEGAL.md

@@ -0,0 +1,95 @@
+# Legal Notice / Aviso Legal
+
+> **Disclaimer:** This document is provided for informational purposes only and does **not** constitute legal advice. If you need legal certainty, consult a qualified attorney in your jurisdiction.
+>
+> **Descargo:** Este documento tiene carácter meramente informativo y **no** constituye asesoramiento legal. Si necesitas seguridad jurídica, consulta con un abogado cualificado en tu jurisdicción.
+
+---
+
+## 1. Independent project / Proyecto independiente
+
+**EN:** This library is an **independent, unofficial software client**. It is **not affiliated with, endorsed by, or sponsored by** BonÀrea Agrupa or any of its related companies. The library merely reads a public locator feed and reshapes its responses.
+
+**ES:** Esta librería es un **cliente de software independiente y no oficial**. **No está afiliada, respaldada ni patrocinada** por BonÀrea Agrupa ni por ninguna de sus sociedades relacionadas. La librería únicamente lee un feed de localización público y reformatea sus respuestas.
+
+---
+
+## 2. Data source and ownership / Fuente de datos y titularidad
+
+**EN:** The data consumed by this library is **public information** published by BonÀrea through its public locator endpoints:
+
+- `https://www.bonarea-agrupa.com/locator/Localitzador/Get` (station list)
+- `https://www.bonarea-agrupa.com/locator/Localitzador/GetByID` (station detail)
+
+The **data belongs to BonÀrea**. This project **does not own the data**. The library only transforms the raw payload into a normalized structure; it does not create, alter, or endorse the underlying information.
+
+**ES:** Los datos que consume esta librería son **información pública** publicada por BonÀrea a través de sus endpoints públicos de localización:
+
+- `https://www.bonarea-agrupa.com/locator/Localitzador/Get` (listado de estaciones)
+- `https://www.bonarea-agrupa.com/locator/Localitzador/GetByID` (detalle de estación)
+
+Los **datos pertenecen a BonÀrea**. Este proyecto **no es titular de los datos**. La librería solo transforma el payload original en una estructura normalizada; no crea, modifica ni respalda la información subyacente.
+
+---
+
+## 3. Terms of the source / Condiciones de la fuente
+
+**EN:** The source website may have its own terms of service, copyright, or usage conditions. You are responsible for reviewing and complying with them before reusing, redistributing, or displaying the data. If the source restricts automated access or scraping, you must not use this library to circumvent those restrictions.
+
+**ES:** El sitio web de origen puede tener sus propios términos de servicio, derechos de autor o condiciones de uso. Eres responsable de revisarlos y cumplirlos antes de reutilizar, redistribuir o mostrar los datos. Si la fuente restringe el acceso automatizado o el scraping, no debes usar esta librería para eludir esas restricciones.
+
+---
+
+## 4. Trademarks / Marcas registradas
+
+**EN:** All product names, logos, and brands are trademarks of their respective owners and are used only as data points returned by the source. Their appearance in the output does not imply any affiliation or endorsement.
+
+**ES:** Todos los nombres de producto, logotipos y marcas son marcas de sus respectivos titulares y se usan únicamente como datos devueltos por la fuente. Su aparición en la salida no implica afiliación ni respaldo alguno.
+
+---
+
+## 5. No warranty / Sin garantía
+
+**EN:** This software and the data it returns are provided **"AS IS", WITHOUT WARRANTY OF ANY KIND**, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, accuracy, completeness, or timeliness. The source can change, be delayed, or be unavailable at any time.
+
+**ES:** Este software y los datos que devuelve se proporcionan **"TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO**, expresa o implícita, incluidas, entre otras, las garantías de comerciabilidad, idoneidad para un fin particular, exactitud, integridad o actualidad. La fuente puede cambiar, retrasarse o no estar disponible en cualquier momento.
+
+---
+
+## 6. Limitation of liability / Limitación de responsabilidad
+
+**EN:** To the maximum extent permitted by applicable law, in no event shall the author(s) or contributors be liable for any direct, indirect, incidental, special, consequential, or punitive damages, or any loss of profits or data, arising out of or in connection with the use of this software or the data it returns (including decisions made based on fuel prices). The author(s) are **not responsible** for how you use the data, for violations committed by downstream consumers, or for interruptions or inaccuracies in the source service.
+
+**ES:** En la máxima medida permitida por la ley aplicable, en ningún caso el/los autor(es) o colaboradores serán responsables de daños directos, indirectos, incidentales, especiales, consecuenciales o punitivos, ni de pérdidas de beneficios o datos, derivados de o relacionados con el uso de este software o de los datos que devuelve (incluidas las decisiones adoptadas a partir de los precios de los carburantes). El/los autor(es) **no son responsables** de cómo uses los datos, de las infracciones cometidas por consumidores posteriores, ni de interrupciones o inexactitudes del servicio de origen.
+
+---
+
+## 7. Responsible use / Uso responsable
+
+**EN:** Do not use this library to flood, overload, or circumvent the source service. Excessive, abusive, or automated requests may affect a service used by many people. Respect the source's terms of service and any rate limiting.
+
+**ES:** No uses esta librería para saturar, sobrecargar o eludir el servicio de origen. Las peticiones excesivas, abusivas o automatizadas pueden afectar a un servicio utilizado por muchas personas. Respeta los términos de servicio de la fuente y su limitación de peticiones.
+
+---
+
+## 8. Compliance / Cumplimiento normativo
+
+**EN:** You are solely responsible for ensuring that your use of this software and the underlying data complies with all applicable laws and regulations in your jurisdiction, including data protection, intellectual property, and consumer-protection rules.
+
+**ES:** Eres el único responsable de garantizar que tu uso de este software y de los datos subyacentes cumple todas las leyes y regulaciones aplicables en tu jurisdicción, incluidas las normas de protección de datos, propiedad intelectual y protección de consumidores.
+
+---
+
+## 9. No endorsement / Sin respaldo oficial
+
+**EN:** The appearance of company names or URLs in this project is for identification purposes only and does not mean that BonÀrea endorses, participates in, or is in any way connected to this project.
+
+**ES:** La aparición de nombres de empresa o URLs en este proyecto es únicamente con fines de identificación y no significa que BonÀrea respalde, participe o esté conectada de alguna manera con este proyecto.
+
+---
+
+## 10. Changes to this notice / Cambios en este aviso
+
+**EN:** This notice may be updated from time to time. Continued use of the library after changes implies acceptance of the updated notice.
+
+**ES:** Este aviso puede actualizarse periódicamente. El uso continuado de la librería tras los cambios implica la aceptación del aviso actualizado.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GasolinaRadar
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -0,0 +1,89 @@
+# @gasolinaradar/repsol-collector
+
+Node.js collector para el buscador de estaciones de servicio de **Repsol** (España). Devuelve un array de estaciones normalizado, listo para **enriquecer** las fuentes primarias (p. ej. MITERD) vía `matching.enrichStations`.
+
+Collector de Node.js para el **buscador de estaciones de servicio de Repsol** (España). Devuelve un array de estaciones normalizado listo para enriquecer las fuentes primarias (p. ej. MITERD) mediante `matching.enrichStations`.
+
+## Fuente de datos / Data source
+
+El buscador de Repsol es una SPA (AEM) en `https://www.repsol.es/buscador-eess-y-puntos-de-recarga/`.
+Cada entidad (estaciones, recarga, oficinas) se carga mediante **un único POST por lote** al endpoint interno:
+
+```
+POST https://www.repsol.es/bin/repsol/searchmiddleware/station-search.json
+     ?action=search&idioma=ES&tipo=1
+```
+
+Referer: `https://www.repsol.es/buscador-eess-y-puntos-de-recarga/`, `Origin: https://www.repsol.es`.
+
+- `action=search` devuelve todas las estaciones de un tipo en una sola respuesta.
+- `tipo=1` = España (default); `tipo=2` = Portugal; `tipo=1,2` = ambos.
+- Respuesta: `{ eess: { count, items: [...] }, recarga: {...}, ... }`. Las estaciones de
+  servicio son `eess.items` (~3147 estaciones en España). Cada item incluye `id`, `nombre`,
+  `x`/`y` (lon/lat), `direccion`, `cp`, `localidad`, `provincia`, `pais`, `horario`/`horarios`
+  y `productos[]` con `precio`/`fecha`.
+
+> ⚠️ Es un endpoint interno de una SPA: funciona con una llamada HTTP cruda (verificado con
+> `axios`), pero al ser un endpoint no documentado puede cambiar de forma o aplicar
+> rate-limiting. Si en producción empezara a devolver 4xx, se puede reutilizar una sesión o
+> cookies de navegador obtenidas previamente.
+
+```bash
+npm install @gasolinaradar/repsol-collector
+```
+
+## Quick start / Inicio rápido
+
+```js
+const { createRepsolCollector } = require('@gasolinaradar/repsol-collector');
+
+const collector = createRepsolCollector({ logger: console });
+const stations = await collector.fetch({ reportProgress: (p) => {} });
+
+// Opcional: apuntar a otro host/endpoint o cambiar el tipo (país).
+const collector = createRepsolCollector({
+  logger: console,
+  searchUrl: 'https://www.repsol.es/bin/repsol/searchmiddleware/station-search.json',
+  tipo: '1', // '1' España, '2' Portugal, '1,2' ambos
+});
+```
+
+## Contract / Contrato
+
+```js
+{ name: 'repsol', country: 'ES', fetch(context) }
+```
+
+Cada estación normalizada sigue la forma compartida de `@gasolinaradar`:
+
+```js
+{
+  source: 'repsol', country: 'ES', sourceStationId,
+  name, address, municipality, province, postalCode,
+  schedule, services,
+  location: { type: 'Point', coordinates: [lon, lat] },
+  prices, lastUpdated,
+}
+```
+
+- `location.coordinates` es GeoJSON `[lon, lat]` (de los campos `x`/`y` del payload).
+- `prices` mapea los combustibles con precio a `{ fuelSlug: amount }` (p. ej.
+  `{ efitec95: 1.799, diéle: 1.949 }`), tolerando decimales con coma española.
+- `schedule` usa el texto `horario` o formatea el array `horarios` por día.
+- `services` recoge la disponibilidad de productos del item (`productos[].producto`).
+- `lastUpdated` se toma de la fecha de precio más reciente, si existe.
+
+## Tests
+
+```bash
+npm test
+npm run test:live   # opcional; golpea el endpoint real de Repsol
+```
+
+## Legal / Legal
+
+Los datos pertenecen a Repsol y se proporcionan "tal cual".
+
+## License / Licencia
+
+MIT. See [LICENSE](./LICENSE).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,20 @@
+# Third Party Notices / Avisos de terceros
+
+## Data source: BonÀrea stations / Fuente de datos: estaciones de BonÀrea
+
+This product includes data published by **BonÀrea Agrupa** through its public locator feed:
+
+Este producto incluye datos publicados por **BonÀrea Agrupa** a través de su feed público de localización:
+
+- `https://www.bonarea-agrupa.com/locator/Localitzador/Get`
+- `https://www.bonarea-agrupa.com/locator/Localitzador/GetByID`
+
+The data belongs to BonÀrea and is provided "as is". See [LEGAL.md](./LEGAL.md) for details.
+
+Los datos pertenecen a BonÀrea y se proporcionan "tal cual". Consulta [LEGAL.md](./LEGAL.md) para más detalles.
+
+## Runtime dependencies / Dependencias en tiempo de ejecución
+
+This library uses the following runtime dependencies / Esta librería usa las siguientes dependencias en tiempo de ejecución:
+
+- [axios](https://github.com/axios/axios), licensed under the MIT License (Copyright (c) 2014-present, Axios Contributors) / licenciada bajo la Licencia MIT.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@gasolinaradar/repsol-collector",
+  "version": "1.0.0",
+  "description": "Collector for the Repsol fuel station finder (Spain) returning normalized fuel stations for enrichment",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "LEGAL.md",
+    "THIRD_PARTY_NOTICES.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gasolinaradar/repsol-collector.git"
+  },
+  "homepage": "https://github.com/gasolinaradar/repsol-collector#readme",
+  "bugs": {
+    "url": "https://github.com/gasolinaradar/repsol-collector/issues"
+  },
+  "scripts": {
+    "test": "node --test test/collector.test.js",
+    "test:live": "node --test test/live.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "repsol",
+    "fuel",
+    "stations",
+    "gasolineras",
+    "espana",
+    "spain",
+    "combustibles",
+    "collector"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "axios": "^1.13.2"
+  }
+}

package/src/collector.js

@@ -0,0 +1,17 @@
+const { fetchStations } = require('./fetch');
+
+function createRepsolCollector(options = {}) {
+  return {
+    name: 'repsol',
+    country: 'ES',
+    async fetch(context = {}) {
+      const reportProgress =
+        typeof context?.reportProgress === 'function' ? context.reportProgress : () => {};
+      return fetchStations(options, { reportProgress });
+    },
+  };
+}
+
+module.exports = {
+  createRepsolCollector,
+};

package/src/fetch.js

@@ -0,0 +1,122 @@
+const axios = require('axios');
+const { normalizeRepsolStation } = require('./normalize');
+const { retry } = require('./retry');
+
+// Repsol public fuel station finder is served from AEM as a map SPA. The map loads every
+// station in one bulk POST to the search middleware endpoint; the response groups all point
+// types under entity keys, and fuel stations live under `eess.items` as `{ count, items }`.
+// tipo=1 is Spain-only (tipo=2 is Portugal, tipo=1,2 returns both); the provider builds the
+// Estaciones de servicio card against tipo=1, so that is the default here.
+const DEFAULT_REPSOL_SEARCH_URL =
+  'https://www.repsol.es/bin/repsol/searchmiddleware/station-search.json';
+const DEFAULT_TIPO = '1';
+const DEFAULT_LANGUAGE = 'ES';
+const DEFAULT_TIMEOUT = 20000;
+const DEFAULT_RETRIES = 3;
+
+const BASE_HEADERS = {
+  Accept: 'application/json, text/plain, */*',
+  'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
+  'X-Requested-With': 'XMLHttpRequest',
+  'User-Agent':
+    'Mozilla/5.0 (compatible; GasolinaRadar repsol-collector/1.0; +https://github.com/gasolinaradar/repsol-collector)',
+  Origin: 'https://www.repsol.es',
+  Referer: 'https://www.repsol.es/buscador-eess-y-puntos-de-recarga/',
+};
+
+function resolveLogger(loggerOption) {
+  return loggerOption && typeof loggerOption.info === 'function' ? loggerOption : console;
+}
+
+function resolveHttpClient(httpClientOption) {
+  return httpClientOption && typeof httpClientOption.post === 'function' ? httpClientOption : axios;
+}
+
+function resolveUrl(urlOption, fallback) {
+  const value = typeof urlOption === 'function' ? urlOption() : urlOption;
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback;
+}
+
+async function fetchStationList(httpClient, logger, searchUrl, tipo, language, timeout) {
+  const params = new URLSearchParams({
+    action: 'search',
+    idioma: language,
+    tipo: tipo,
+  });
+  const url = `${searchUrl}${searchUrl.includes('?') ? '&' : '?'}${params.toString()}`;
+
+  logger.info('Requesting Repsol station list', { url });
+  const response = await httpClient.post(url, null, {
+    headers: BASE_HEADERS,
+    timeout,
+  });
+
+  const data = response && response.data;
+  const eess = data && typeof data === 'object' ? data.eess : undefined;
+  const items = eess && Array.isArray(eess.items) ? eess.items : undefined;
+
+  if (!items) {
+    throw new Error('Unexpected Repsol search response');
+  }
+
+  logger.info('Received Repsol station list', {
+    url,
+    status: response.status,
+    stationCount: items.length,
+  });
+
+  return items;
+}
+
+async function fetchStations(options = {}, hooks = {}) {
+  const logger = resolveLogger(options.logger);
+  const httpClient = resolveHttpClient(options.httpClient);
+  const searchUrl = resolveUrl(options.searchUrl, DEFAULT_REPSOL_SEARCH_URL);
+  const tipo = options.tipo ?? DEFAULT_TIPO;
+  const language = options.language ?? DEFAULT_LANGUAGE;
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  const retries = options.retries ?? DEFAULT_RETRIES;
+  const reportProgress =
+    typeof hooks.reportProgress === 'function' ? hooks.reportProgress : () => {};
+
+  logger.info('Starting Repsol collector fetch');
+  reportProgress(5, { stage: 'fetching_station_list' });
+  const rawStations = await retry(
+    () => fetchStationList(httpClient, logger, searchUrl, tipo, language, timeout),
+    { retries, minTimeoutMs: 1000, logger },
+  );
+  const totalStations = rawStations.length;
+  reportProgress(10, { stage: 'station_list_received', stationCount: totalStations });
+
+  if (totalStations === 0) {
+    reportProgress(100, { stage: 'completed', stationCount: 0 });
+    return [];
+  }
+
+  const stations = [];
+  for (let index = 0; index < totalStations; index += 1) {
+    const normalized = normalizeRepsolStation(rawStations[index]);
+    if (normalized) {
+      stations.push(normalized);
+    }
+
+    const progress = 10 + Math.round(((index + 1) / totalStations) * 90);
+    reportProgress(progress > 100 ? 100 : progress, {
+      stage: 'normalizing_stations',
+      processed: index + 1,
+      total: totalStations,
+    });
+  }
+
+  reportProgress(100, { stage: 'completed', stationCount: stations.length });
+  return stations;
+}
+
+module.exports = {
+  fetchStations,
+  fetchStationList,
+  DEFAULT_REPSOL_SEARCH_URL,
+  DEFAULT_TIPO,
+  DEFAULT_LANGUAGE,
+  BASE_HEADERS,
+};

package/src/index.js

@@ -0,0 +1,7 @@
+const { createRepsolCollector } = require('./collector');
+const { fetchStations } = require('./fetch');
+
+module.exports = {
+  createRepsolCollector,
+  fetchStations,
+};

package/src/normalize.js

@@ -0,0 +1,189 @@
+const decimalCommaRegex = /,/g;
+
+function normalizePrice(value) {
+  if (value === null || value === undefined) return null;
+  const raw = typeof value === 'number' ? value.toString() : String(value).trim();
+  if (!raw) return null;
+  const normalized = raw.replace(decimalCommaRegex, '.');
+  const parsed = Number.parseFloat(normalized);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function normalizeCoordinate(value) {
+  if (value === null || value === undefined) {
+    throw new Error('Missing coordinate value');
+  }
+
+  const raw = typeof value === 'number' ? value.toString() : String(value).trim();
+  if (!raw) {
+    throw new Error('Empty coordinate value');
+  }
+
+  const normalized = raw.replace(decimalCommaRegex, '.');
+  const parsed = Number.parseFloat(normalized);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Invalid coordinate value: ${value}`);
+  }
+
+  return parsed;
+}
+
+function slugifyFuelName(name) {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim()
+    .replace(/\s+/g, '');
+}
+
+function cleanText(value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    return '';
+  }
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function normalizeOptionalText(value) {
+  const cleaned = cleanText(value);
+  return cleaned.length > 0 ? cleaned : undefined;
+}
+
+function parseRepsolPrices(products) {
+  if (!Array.isArray(products) || products.length === 0) {
+    return undefined;
+  }
+
+  const prices = products.reduce((acc, entry) => {
+    if (!entry || typeof entry !== 'object') {
+      return acc;
+    }
+
+    const productName = cleanText(entry.producto);
+    const slug = slugifyFuelName(productName);
+    if (!slug || Object.prototype.hasOwnProperty.call(acc, slug)) {
+      return acc;
+    }
+
+    const amount = normalizePrice(entry.precio);
+    if (amount === null) {
+      return acc;
+    }
+
+    acc[slug] = amount;
+    return acc;
+  }, {});
+
+  return Object.keys(prices).length > 0 ? prices : undefined;
+}
+
+function parseRepsolServices(products) {
+  if (!Array.isArray(products) || products.length === 0) {
+    return undefined;
+  }
+
+  const services = products
+    .map((entry) => (entry && typeof entry === 'object' ? normalizeOptionalText(entry.producto) : undefined))
+    .filter(Boolean);
+
+  return services.length > 0 ? services : undefined;
+}
+
+function formatRepsolSchedule(schedule) {
+  if (typeof schedule === 'string' && schedule.trim()) {
+    return schedule.trim();
+  }
+
+  if (!Array.isArray(schedule) || schedule.length === 0) {
+    return undefined;
+  }
+
+  const parts = schedule
+    .map((entry) => {
+      if (!entry || typeof entry !== 'object') {
+        return undefined;
+      }
+      const day = normalizeOptionalText(entry.dia);
+      const hours = normalizeOptionalText(entry.horario);
+      if (!day || !hours) {
+        return undefined;
+      }
+      return `${day}: ${hours}`;
+    })
+    .filter(Boolean);
+
+  return parts.length > 0 ? parts.join(', ') : undefined;
+}
+
+function latestProductDate(products) {
+  if (!Array.isArray(products) || products.length === 0) {
+    return undefined;
+  }
+
+  let latest;
+  for (const entry of products) {
+    if (!entry || typeof entry !== 'object') {
+      continue;
+    }
+    const raw = entry.fecha;
+    const time = typeof raw === 'string' ? Date.parse(raw) : NaN;
+    if (Number.isFinite(time) && (latest === undefined || time > latest)) {
+      latest = time;
+    }
+  }
+
+  return latest === undefined ? undefined : new Date(latest);
+}
+
+function normalizeRepsolStation(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return null;
+  }
+
+  if (raw.pais && String(raw.pais).trim().toLowerCase() !== 'españa') {
+    return null;
+  }
+
+  let latitude;
+  let longitude;
+  try {
+    latitude = normalizeCoordinate(raw.y);
+    longitude = normalizeCoordinate(raw.x);
+  } catch (error) {
+    return null;
+  }
+
+  const prices = parseRepsolPrices(raw.productos);
+  const services = parseRepsolServices(raw.productos);
+  const productDate = latestProductDate(raw.productos);
+
+  return {
+    source: 'repsol',
+    country: 'ES',
+    sourceStationId: raw.id ?? undefined,
+    name: normalizeOptionalText(raw.nombre),
+    address: normalizeOptionalText(raw.direccion),
+    municipality: normalizeOptionalText(raw.localidad),
+    province: normalizeOptionalText(raw.provincia),
+    postalCode: normalizeOptionalText(raw.cp),
+    schedule: formatRepsolSchedule(raw.horario ?? raw.horarios),
+    services,
+    location: {
+      type: 'Point',
+      coordinates: [longitude, latitude],
+    },
+    prices,
+    lastUpdated: productDate ?? new Date(),
+  };
+}
+
+module.exports = {
+  normalizePrice,
+  normalizeCoordinate,
+  slugifyFuelName,
+  cleanText,
+  normalizeOptionalText,
+  parseRepsolPrices,
+  parseRepsolServices,
+  formatRepsolSchedule,
+  normalizeRepsolStation,
+};

package/src/retry.js

@@ -0,0 +1,25 @@
+async function retry(fn, options = {}) {
+  const { retries = 3, factor = 2, minTimeoutMs = 500, logger = console } = options;
+
+  let delay = minTimeoutMs;
+
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === retries) {
+        throw error;
+      }
+
+      const nextAttempt = attempt + 1;
+      const message = error instanceof Error ? error.message : String(error);
+      logger.warn(`Retry attempt ${nextAttempt} after failure: ${message}`);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      delay *= factor;
+    }
+  }
+}
+
+module.exports = {
+  retry,
+};