From 6832192d933254e2839534ee444f5ca0e9d7024b Mon Sep 17 00:00:00 2001
From: "borja (aider)" <borja@brobert.net>
Date: Sun, 30 Mar 2025 00:13:30 +0100
Subject: [PATCH] docs: Improve sync interval documentation and logging

---
 .env.example               |  6 ++++--
 src/services/group-sync.ts | 21 ++++++++++++++++++++-
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/.env.example b/.env.example
index c405a12..1eb4cd4 100644
--- a/.env.example
+++ b/.env.example
@@ -7,6 +7,8 @@ CHATBOT_PHONE_NUMBER="1234567890"
 PORT="3007"
 WEBHOOK_URL="https://example-url.com/webhook"
 
-# Group sync interval in milliseconds (default: 24h)
-# Set lower during development (e.g. 60000 = 1 minute)
+# Group sync interval in milliseconds (default: 24h = 86400000ms)
+# - Set lower during development (e.g. 60000 = 1 minute)
+# - Minimum 10000ms (10s) enforced in development
+# - Format: plain number without quotes
 # GROUP_SYNC_INTERVAL_MS=86400000
diff --git a/src/services/group-sync.ts b/src/services/group-sync.ts
index c8469de..418c3e2 100644
--- a/src/services/group-sync.ts
+++ b/src/services/group-sync.ts
@@ -10,6 +10,18 @@ type EvolutionGroup = {
 };
 
 export class GroupSyncService {
+  /**
+   * Gets the sync interval duration in milliseconds.
+   * 
+   * Priority:
+   * 1. GROUP_SYNC_INTERVAL_MS environment variable if set
+   * 2. Default 24 hour interval
+   * 
+   * In development mode, enforces minimum 10 second interval
+   * to prevent accidental excessive API calls.
+   * 
+   * @returns {number} Sync interval in milliseconds
+   */
   private static get SYNC_INTERVAL_MS(): number {
     const interval = process.env.GROUP_SYNC_INTERVAL_MS
       ? Number(process.env.GROUP_SYNC_INTERVAL_MS)
@@ -51,7 +63,14 @@ export class GroupSyncService {
 
   private static shouldSync(): boolean {
     const timeSinceLastSync = Date.now() - this.lastSyncAttempt;
-    return timeSinceLastSync > this.SYNC_INTERVAL_MS;
+    const shouldSync = timeSinceLastSync > this.SYNC_INTERVAL_MS;
+    
+    if (!shouldSync && process.env.NODE_ENV !== 'test') {
+      const nextSyncIn = this.SYNC_INTERVAL_MS - timeSinceLastSync;
+      console.debug(`Next sync available in ${Math.round(nextSyncIn/1000)} seconds`);
+    }
+    
+    return shouldSync;
   }
 
   private static async fetchGroupsFromAPI(): Promise<EvolutionGroup[]> {