iobroker.parcelapp 0.2.0 → 0.2.1

package/README.md

@@ -22,7 +22,7 @@ ioBroker adapter that connects to the [parcel.app](https://parcelapp.net) API an
 - **Summary states** — active count, today count, combined delivery window
 - **Delivery time estimates** — today, tomorrow, in X days with combined time window
 - **Automatic polling** with configurable interval (5–60 minutes)
-- **Configurable cleanup** of delivered packages — auto-remove or keep as "Delivered"
+- **Configurable cleanup** — auto-remove delivered packages or keep them until deleted in parcel.app
 - **Add deliveries** via sendTo message from scripts or other adapters
 - **Admin UI** with connection test, polling settings, and status language selection
 - **Multilingual status labels** (German/English)
@@ -44,7 +44,7 @@ ioBroker adapter that connects to the [parcel.app](https://parcelapp.net) API an
 |--------|-------------|---------|
 | **API Key** | Your parcel.app API key (get it at [web.parcelapp.net](https://web.parcelapp.net)) | — |
 | **Poll Interval** | How often to fetch updates (minutes) | 10 |
-| **Auto-remove delivered** | Remove delivered packages from states automatically | Yes |
+| **Auto-remove delivered** | Remove delivered packages from states automatically. When disabled, they stay until deleted in parcel.app. | Yes |
 | **Status Language** | Language for status labels (German/English) | German |
 
 ---
@@ -94,6 +94,9 @@ parcelapp.0.
 
 ## Changelog
 
+### 0.2.1 (2026-03-25)
+- Robust error handling: rate limit detection, connection error deduplication, poll throttling
+
 ### 0.2.0 (2026-03-25)
 - Added option to keep delivered packages in states
 - Simplified admin UI to single page
@@ -114,9 +117,6 @@ parcelapp.0.
 ### 0.1.1 (2026-03-23)
 - Redesigned adapter logo
 
-### 0.1.0 (2026-03-23)
-- Initial release
-
 Older changelog: [CHANGELOG.md](CHANGELOG.md)
 
 ---

package/build/lib/parcel-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parcel-client.d.ts","sourceRoot":"","sources":["../../src/lib/parcel-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACX,MAAM,SAAS,CAAC;AAKjB,yCAAyC;AACzC,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAA2B;IAE/C,2CAA2C;gBAC/B,MAAM,EAAE,MAAM;IAI1B;;;;OAIG;IACG,aAAa,CACjB,UAAU,GAAE,QAAQ,GAAG,QAAmB,GACzC,OAAO,CAAC,cAAc,EAAE,CAAC;IAqB5B;;;;OAIG;IACG,WAAW,CACf,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,mBAAmB,CAAC;IAS/B,kDAAkD;IAC5C,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC;IAkB5C;;;;OAIG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK1D,mCAAmC;IAC7B,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAatE;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;CAqEhB"}
+{"version":3,"file":"parcel-client.d.ts","sourceRoot":"","sources":["../../src/lib/parcel-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACX,MAAM,SAAS,CAAC;AAKjB,yCAAyC;AACzC,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAA2B;IAE/C,2CAA2C;gBAC/B,MAAM,EAAE,MAAM;IAI1B;;;;OAIG;IACG,aAAa,CACjB,UAAU,GAAE,QAAQ,GAAG,QAAmB,GACzC,OAAO,CAAC,cAAc,EAAE,CAAC;IAqB5B;;;;OAIG;IACG,WAAW,CACf,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,mBAAmB,CAAC;IAS/B,kDAAkD;IAC5C,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC;IAkB5C;;;;OAIG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK1D,mCAAmC;IAC7B,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAatE;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;CAiFhB"}

package/build/lib/parcel-client.js

@@ -137,6 +137,15 @@ class ParcelClient {
                     const raw = Buffer.concat(chunks).toString("utf-8");
                     if (res.statusCode &&
                         (res.statusCode < 200 || res.statusCode >= 300)) {
+                        if (res.statusCode === 429) {
+                            const retryAfter = parseInt(res.headers["retry-after"] || "", 10);
+                            const err = new Error("Rate limit exceeded");
+                            err.code = "RATE_LIMITED";
+                            // Use Retry-After header or default to 5 minutes
+                            err.retryAfterSeconds = retryAfter > 0 ? retryAfter : 5 * 60;
+                            reject(err);
+                            return;
+                        }
                         const err = new Error(`HTTP ${res.statusCode}: ${res.statusMessage}`);
                         err.code =
                             res.statusCode === 401 || res.statusCode === 403

package/build/main.js

@@ -40,12 +40,16 @@ require("./lib/types");
 const MIN_POLL_INTERVAL = 5;
 const MAX_POLL_INTERVAL = 60;
 const DEFAULT_POLL_INTERVAL = 10;
+const MIN_POLL_GAP_MS = 60_000; // Minimum 60s between polls
 /** ioBroker adapter for parcel.app package tracking */
 class ParcelappAdapter extends utils.Adapter {
     client = null;
     stateManager = null;
     pollTimer = null;
     isPolling = false;
+    lastPollTime = 0;
+    rateLimitedUntil = 0;
+    lastErrorCode = "";
     /** @param options Adapter options */
     constructor(options = {}) {
         super({
@@ -138,15 +142,59 @@ class ParcelappAdapter extends utils.Adapter {
             }
         }
     }
+    /**
+     * Classify an error for deduplication and log-level decisions.
+     *
+     * @param error The error to classify
+     */
+    classifyError(error) {
+        if (error.code === "RATE_LIMITED") {
+            return "RATE_LIMITED";
+        }
+        if (error.code === "INVALID_API_KEY") {
+            return "INVALID_API_KEY";
+        }
+        // Network errors: DNS, connection refused, no internet
+        if (error.code === "ENOTFOUND" ||
+            error.code === "ECONNREFUSED" ||
+            error.code === "ECONNRESET" ||
+            error.code === "ENETUNREACH" ||
+            error.code === "EAI_AGAIN") {
+            return "NETWORK";
+        }
+        if (error.message.includes("timeout") || error.code === "ETIMEDOUT") {
+            return "TIMEOUT";
+        }
+        return error.code || "UNKNOWN";
+    }
     async poll() {
         if (this.isPolling || !this.client || !this.stateManager) {
             return;
         }
+        const now = Date.now();
+        // Skip if rate limited
+        if (now < this.rateLimitedUntil) {
+            const waitMin = Math.ceil((this.rateLimitedUntil - now) / 60_000);
+            this.log.debug(`Skipping poll — rate limited for ${waitMin} more minute(s)`);
+            return;
+        }
+        // Throttle: minimum gap between polls
+        if (now - this.lastPollTime < MIN_POLL_GAP_MS) {
+            this.log.debug("Skipping poll — too soon after last poll");
+            return;
+        }
         this.isPolling = true;
+        this.lastPollTime = now;
         try {
             // When keeping delivered packages, use "recent" to get them from API
             const autoRemove = this.config.autoRemoveDelivered !== false;
             const deliveries = await this.client.getDeliveries(autoRemove ? "active" : "recent");
+            // Reset error state on success
+            this.rateLimitedUntil = 0;
+            if (this.lastErrorCode) {
+                this.log.info("Connection restored");
+                this.lastErrorCode = "";
+            }
             await this.setStateAsync("info.connection", { val: true, ack: true });
             // Filter deliveries based on auto-remove setting
             const visibleDeliveries = autoRemove
@@ -170,11 +218,28 @@ class ParcelappAdapter extends utils.Adapter {
         }
         catch (err) {
             const error = err;
-            if (error.code === "INVALID_API_KEY") {
+            // Classify the error
+            const errorCode = this.classifyError(error);
+            const isRepeat = errorCode === this.lastErrorCode;
+            this.lastErrorCode = errorCode;
+            if (error.code === "RATE_LIMITED") {
+                const cooldownSec = error.retryAfterSeconds || 5 * 60;
+                this.rateLimitedUntil = Date.now() + cooldownSec * 1000;
+                this.log.warn(`Rate limit hit — pausing API requests for ${Math.ceil(cooldownSec / 60)} minute(s)`);
+            }
+            else if (error.code === "INVALID_API_KEY") {
+                // Always log — user must fix config
                 this.log.error("Invalid API key — please check your parcel.app API key");
             }
-            else if (error.message.includes("timeout")) {
-                this.log.error(`API request timeout: ${error.message}`);
+            else if (isRepeat) {
+                // Same error as last time — don't spam the log
+                this.log.debug(`Poll failed (ongoing): ${error.message}`);
+            }
+            else if (errorCode === "NETWORK") {
+                this.log.warn(`Cannot reach parcel.app API — will keep retrying`);
+            }
+            else if (errorCode === "TIMEOUT") {
+                this.log.warn(`API request timeout — will retry next cycle`);
             }
             else {
                 this.log.error(`Poll failed: ${error.message}`);

package/io-package.json

@@ -1,8 +1,21 @@
 {
   "common": {
     "name": "parcelapp",
-    "version": "0.2.0",
+    "version": "0.2.1",
     "news": {
+      "0.2.1": {
+        "en": "Robust error handling: API rate limit detection, connection error deduplication, poll throttling",
+        "de": "Robuste Fehlerbehandlung: Erkennung von API-Ratenlimits, Deduplizierung von Verbindungsfehlern, Polling-Drosselung",
+        "ru": "Надежная обработка ошибок: обнаружение ограничения скорости API, дедупликация ошибок соединения, регулирование опроса.",
+        "pt": "Tratamento robusto de erros: detecção de limite de taxa de API, desduplicação de erros de conexão, otimização de pesquisa",
+        "nl": "Robuuste foutafhandeling: detectie van API-snelheidslimieten, deduplicatie van verbindingsfouten, poll-throttling",
+        "fr": "Gestion robuste des erreurs : détection de limite de débit API, déduplication des erreurs de connexion, limitation des interrogations",
+        "it": "Gestione efficace degli errori: rilevamento del limite di velocità dell'API, deduplicazione degli errori di connessione, limitazione del poll",
+        "es": "Manejo sólido de errores: detección de límite de tasa de API, deduplicación de errores de conexión, limitación de encuestas",
+        "pl": "Solidna obsługa błędów: wykrywanie limitów szybkości interfejsu API, deduplikacja błędów połączenia, ograniczanie odpytywania",
+        "uk": "Надійна обробка помилок: виявлення обмеження швидкості API, дедуплікація помилок підключення, регулювання опитування",
+        "zh-cn": "强大的错误处理：API 速率限制检测、连接错误重复数据删除、轮询限制"
+      },
       "0.2.0": {
         "en": "Added option to keep delivered packages, simplified admin UI, removed summary.json state",
         "de": "Option zum Beibehalten gelieferter Pakete hinzugefügt, Admin-Benutzeroberfläche vereinfacht, Status „summary.json“ entfernt",
@@ -80,19 +93,6 @@
         "pl": "Przeprojektowano logo adaptera, naprawiono problemy repochecker",
         "uk": "Оновлено логотип адаптера, виправлено проблеми repochecker",
         "zh-cn": "重新设计适配器图标，修复 repochecker 问题"
-      },
-      "0.1.0": {
-        "en": "Initial release — track packages from 300+ carriers via parcel.app",
-        "de": "Erstveröffentlichung — Pakete von 300+ Versandunternehmen über parcel.app verfolgen",
-        "ru": "Первый выпуск — отслеживание посылок от 300+ перевозчиков через parcel.app",
-        "pt": "Lançamento inicial — rastreie pacotes de mais de 300 transportadoras via parcel.app",
-        "nl": "Eerste release — volg pakketten van 300+ vervoerders via parcel.app",
-        "fr": "Version initiale — suivez vos colis de plus de 300 transporteurs via parcel.app",
-        "it": "Prima versione — traccia pacchi da più di 300 corrieri tramite parcel.app",
-        "es": "Versión inicial — rastrea paquetes de más de 300 transportistas a través de parcel.app",
-        "pl": "Pierwsze wydanie — śledź przesyłki od 300+ przewoźników przez parcel.app",
-        "uk": "Перший випуск — відстеження посилок від 300+ перевізників через parcel.app",
-        "zh-cn": "初始版本 — 通过 parcel.app 追踪 300+ 快递公司的包裹"
       }
     },
     "titleLang": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iobroker.parcelapp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "ioBroker adapter for parcel.app — track packages from 300+ carriers",
   "author": {
     "name": "krobi",