Update sync_logic.py

sync_logic.py

@@ -268,23 +268,35 @@ def sync_linkedin_mentions(token_state):
     return mentions_sync_message, token_state
 
 
+def _clean_key_component(component_value, is_category_identifier=False):
+    """
+    Helper to consistently clean key components.
+    For non-date category identifiers, converts to lowercase for case-insensitive matching.
+    """
+    if pd.isna(component_value) or component_value is None:
+        return "NONE_VALUE" # Consistent placeholder for None/NaN
+    
+    cleaned_value = str(component_value).strip()
+    if is_category_identifier: # Apply lowercasing only to general category text, not dates or URNs/Types
+        return cleaned_value.lower()
+    return cleaned_value
+
+
 def sync_linkedin_follower_stats(token_state):
     """
     Fetches new/updated LinkedIn follower statistics and uploads/updates them in Bubble,
-    if scheduled by state_manager.
-    For both monthly gains and demographics, updates counts only if the new LinkedIn count is greater.
-    Creates new records if the category/month doesn't exist.
+    if scheduled by state_manager. Includes detailed logging for debugging key mismatches.
     """
-    logging.info("Starting LinkedIn follower stats sync process check.")
+    logging.info("DEBUG: Starting LinkedIn follower stats sync process check.")
 
     if not token_state.get("fs_should_sync_now", False):
-        logging.info("Follower Stats sync: Not scheduled by state_manager. Skipping.")
+        logging.info("DEBUG: Follower Stats sync: Not scheduled by state_manager. Skipping.")
         return "Follower Stats: Sync not currently required by schedule. ", token_state
         
-    logging.info("Follower Stats sync: Proceeding as scheduled by state_manager.")
+    logging.info("DEBUG: Follower Stats sync: Proceeding as scheduled by state_manager.")
 
     if not token_state or not token_state.get("token"):
-        logging.error("Follower Stats sync: Access denied. No LinkedIn token.")
+        logging.error("DEBUG: Follower Stats sync: Access denied. No LinkedIn token.")
         org_urn_for_log = token_state.get('org_urn') if token_state else None
         if org_urn_for_log:
             token_state = _log_sync_attempt(org_urn_for_log, LOG_SUBJECT_FOLLOWER_STATS, token_state)
@@ -299,126 +311,135 @@ def sync_linkedin_follower_stats(token_state):
     attempt_logged = False
 
     if not org_urn or not client_id or client_id == "ENV VAR MISSING":
-        logging.error("Follower Stats sync: Configuration error (Org URN or Client ID missing).")
+        logging.error("DEBUG: Follower Stats sync: Configuration error (Org URN or Client ID missing).")
         if org_urn:
             token_state = _log_sync_attempt(org_urn, LOG_SUBJECT_FOLLOWER_STATS, token_state)
             attempt_logged = True
         return "Follower Stats: Config error. ", token_state
-
-        
-    logging.info(f"{bubble_follower_stats_df_orig.columns}")
-    # Ensure the BUBBLE_UNIQUE_ID_COLUMN_NAME exists in the DataFrame if it's not empty,
-    # as it's crucial for building the maps for updates.
+    
     if not bubble_follower_stats_df_orig.empty and BUBBLE_UNIQUE_ID_COLUMN_NAME not in bubble_follower_stats_df_orig.columns:
-        logging.error(f"Follower Stats sync: Critical error - '{BUBBLE_UNIQUE_ID_COLUMN_NAME}' column missing in bubble_follower_stats_df. Cannot proceed with updates.")
+        logging.error(f"DEBUG: Follower Stats sync: Critical error - '{BUBBLE_UNIQUE_ID_COLUMN_NAME}' column missing in bubble_follower_stats_df. Cannot proceed with updates.")
         if org_urn:
-             token_state = _log_sync_attempt(org_urn, LOG_SUBJECT_FOLLOWER_STATS, token_state) # Log the attempt despite error
+             token_state = _log_sync_attempt(org_urn, LOG_SUBJECT_FOLLOWER_STATS, token_state)
              attempt_logged = True
         return f"Follower Stats: Config error ({BUBBLE_UNIQUE_ID_COLUMN_NAME} missing). ", token_state
 
-    logging.info(f"Follower stats sync proceeding for org_urn: {org_urn}")
+    logging.info(f"DEBUG: Follower stats sync proceeding for org_urn: {org_urn}")
     try:
         api_follower_stats = get_linkedin_follower_stats(client_id, token_dict, org_urn)
         
-        if not api_follower_stats:
-            logging.info(f"Follower Stats sync: No stats found via API for org {org_urn}.")
+        if not api_follower_stats: # This is a list of dicts
+            logging.info(f"DEBUG: Follower Stats sync: No stats found via API for org {org_urn}. API returned: {api_follower_stats}")
             follower_stats_sync_message = "Follower Stats: None found via API. "
             token_state = _log_sync_attempt(org_urn, LOG_SUBJECT_FOLLOWER_STATS, token_state)
             attempt_logged = True
             return follower_stats_sync_message, token_state
 
         stats_for_bulk_upload = []
-        records_to_update_via_patch = [] # List of tuples: (bubble_id, fields_to_update_dict)
+        records_to_update_via_patch = []
 
-        # --- Prepare maps for existing data in Bubble for efficient lookup ---
-        # Key: (org_urn, type, category_identifier), Value: (organic, paid, bubble_record_id)
-        # For monthly gains, category_identifier is the formatted date string.
-        # For demographics, category_identifier is the FOLLOWER_STATS_CATEGORY_COLUMN value.
         existing_stats_map = {}
         stats_required_cols = [
             FOLLOWER_STATS_ORG_URN_COLUMN, FOLLOWER_STATS_TYPE_COLUMN,
-            FOLLOWER_STATS_CATEGORY_COLUMN, FOLLOWER_STATS_ORGANIC_COLUMN, # Assuming these apply to monthly too
-            FOLLOWER_STATS_PAID_COLUMN,     # Assuming these apply to monthly too
-            BUBBLE_UNIQUE_ID_COLUMN_NAME
+            FOLLOWER_STATS_CATEGORY_COLUMN, FOLLOWER_STATS_ORGANIC_COLUMN,
+            FOLLOWER_STATS_PAID_COLUMN, BUBBLE_UNIQUE_ID_COLUMN_NAME
         ]
 
+        logging.info("DEBUG: Populating existing_stats_map from Bubble data...")
         if not bubble_follower_stats_df_orig.empty and all(col in bubble_follower_stats_df_orig.columns for col in stats_required_cols):
-            for _, row in bubble_follower_stats_df_orig.iterrows():
-                category_identifier = str(row[FOLLOWER_STATS_CATEGORY_COLUMN])
-                # For monthly gains, ensure category (date) is consistently formatted if needed
-                if row[FOLLOWER_STATS_TYPE_COLUMN] == 'follower_gains_monthly':
-                    try:
-                        category_identifier = pd.to_datetime(row[FOLLOWER_STATS_CATEGORY_COLUMN], errors='coerce').strftime('%Y-%m-%d')
-                        if category_identifier == 'NaT': # Handle parsing errors
-                            logging.warning(f"Could not parse date for existing monthly gain: {row[FOLLOWER_STATS_CATEGORY_COLUMN]}. Skipping this entry for map.")
-                            continue
-                    except Exception: # Catch any other parsing issues
-                        logging.warning(f"Error parsing date for existing monthly gain: {row[FOLLOWER_STATS_CATEGORY_COLUMN]}. Skipping this entry for map.")
+            for index, row in bubble_follower_stats_df_orig.iterrows():
+                org_urn_val = _clean_key_component(row[FOLLOWER_STATS_ORG_URN_COLUMN])
+                type_val = _clean_key_component(row[FOLLOWER_STATS_TYPE_COLUMN])
+                category_raw_val = row[FOLLOWER_STATS_CATEGORY_COLUMN]
+                bubble_id_val = row.get(BUBBLE_UNIQUE_ID_COLUMN_NAME)
+
+                if pd.isna(bubble_id_val):
+                    logging.warning(f"DEBUG: Row index {index} from Bubble data has missing Bubble ID ('{BUBBLE_UNIQUE_ID_COLUMN_NAME}'). Cannot use for updates. Data: {row.to_dict()}")
+                    continue
+
+                category_identifier = ""
+                if type_val == 'follower_gains_monthly': # Type is already cleaned
+                    parsed_date = pd.to_datetime(category_raw_val, errors='coerce')
+                    if pd.NaT is parsed_date or pd.isna(parsed_date):
+                        logging.warning(f"DEBUG: Could not parse date for existing monthly gain: '{category_raw_val}' from Bubble row index {index}. Skipping for map.")
                         continue
+                    category_identifier = parsed_date.strftime('%Y-%m-%d') # Date format, not lowercased
+                else:
+                    # Apply lowercasing for general text categories for case-insensitive matching
+                    category_identifier = _clean_key_component(category_raw_val, is_category_identifier=True) 
                 
-                key = (
-                    str(row[FOLLOWER_STATS_ORG_URN_COLUMN]),
-                    str(row[FOLLOWER_STATS_TYPE_COLUMN]),
-                    category_identifier
-                )
+                key = (org_urn_val, type_val, category_identifier)
+                
+                # Ensure counts are numeric when storing in map
+                existing_organic_count = pd.to_numeric(row[FOLLOWER_STATS_ORGANIC_COLUMN], errors='coerce')
+                existing_paid_count = pd.to_numeric(row[FOLLOWER_STATS_PAID_COLUMN], errors='coerce')
+                existing_organic_count = 0 if pd.isna(existing_organic_count) else int(existing_organic_count)
+                existing_paid_count = 0 if pd.isna(existing_paid_count) else int(existing_paid_count)
+
                 existing_stats_map[key] = (
-                    row[FOLLOWER_STATS_ORGANIC_COLUMN], # Assuming monthly gains have this
-                    row[FOLLOWER_STATS_PAID_COLUMN],   # Assuming monthly gains have this
-                    row[BUBBLE_UNIQUE_ID_COLUMN_NAME]
+                    existing_organic_count,
+                    existing_paid_count,
+                    str(bubble_id_val) # Ensure Bubble ID is string
                 )
-        elif not bubble_follower_stats_df_orig.empty:
-            logging.warning(f"Follower Stats: Data in Bubble is missing one or more required columns for update logic: {stats_required_cols}. Will treat all API stats as new if not matched by key elements.")
+                logging.debug(f"DEBUG: Added to existing_stats_map: Key={key}, BubbleID={str(bubble_id_val)}, OrgCounts={existing_organic_count}, PaidCounts={existing_paid_count}")
 
+        elif not bubble_follower_stats_df_orig.empty:
+            logging.warning(f"DEBUG: Follower Stats: Bubble data is missing one or more required columns for map: {stats_required_cols}.")
+        else:
+            logging.info("DEBUG: Follower Stats: Bubble_follower_stats_df_orig is empty. existing_stats_map will be empty.")
 
-        # --- Process all stats from API (monthly gains and demographics) ---
-        for stat_from_api in api_follower_stats:
-            api_type = str(stat_from_api.get(FOLLOWER_STATS_TYPE_COLUMN))
+        logging.info(f"DEBUG: Processing {len(api_follower_stats)} stats from API...")
+        for i, stat_from_api in enumerate(api_follower_stats): # api_follower_stats is a list of dicts
+            api_org_urn = _clean_key_component(stat_from_api.get(FOLLOWER_STATS_ORG_URN_COLUMN))
+            api_type = _clean_key_component(stat_from_api.get(FOLLOWER_STATS_TYPE_COLUMN))
             api_category_raw = stat_from_api.get(FOLLOWER_STATS_CATEGORY_COLUMN)
             
-            api_category_identifier = str(api_category_raw)
-            if api_type == 'follower_gains_monthly':
-                try:
-                    api_category_identifier = pd.to_datetime(api_category_raw, errors='coerce').strftime('%Y-%m-%d')
-                    if api_category_identifier == 'NaT':
-                        logging.warning(f"Could not parse date from API for monthly gain: {api_category_raw}. Skipping this API stat.")
-                        continue
-                except Exception:
-                    logging.warning(f"Error parsing date from API for monthly gain: {api_category_raw}. Skipping this API stat.")
+            api_category_identifier = ""
+            if api_type == 'follower_gains_monthly': # API type is already cleaned
+                parsed_date = pd.to_datetime(api_category_raw, errors='coerce')
+                if pd.NaT is parsed_date or pd.isna(parsed_date):
+                    logging.warning(f"DEBUG: API stat index {i}: Could not parse date for API monthly gain: '{api_category_raw}'. Skipping.")
                     continue
+                api_category_identifier = parsed_date.strftime('%Y-%m-%d') # Date format, not lowercased
+            else:
+                # Apply lowercasing for general text categories for case-insensitive matching
+                api_category_identifier = _clean_key_component(api_category_raw, is_category_identifier=True)
 
-            key = (
-                str(stat_from_api.get(FOLLOWER_STATS_ORG_URN_COLUMN)),
-                api_type,
-                api_category_identifier
-            )
+            key_from_api = (api_org_urn, api_type, api_category_identifier)
+            logging.debug(f"DEBUG: API stat index {i}: Generated Key={key_from_api}, RawData={stat_from_api}")
             
-            # Assuming monthly gains also have organic/paid counts.
-            # If they have different count fields, these need to be specified.
-            # For simplicity, using FOLLOWER_STATS_ORGANIC_COLUMN and FOLLOWER_STATS_PAID_COLUMN.
-            # If monthly gains only have a single 'count' field, adjust logic accordingly.
-            api_organic_count = stat_from_api.get(FOLLOWER_STATS_ORGANIC_COLUMN, 0)
-            api_paid_count = stat_from_api.get(FOLLOWER_STATS_PAID_COLUMN, 0)
-
-            if key not in existing_stats_map:
-                # This stat category/month is entirely new, add for bulk creation
+            # Ensure API counts are numeric
+            api_organic_count = pd.to_numeric(stat_from_api.get(FOLLOWER_STATS_ORGANIC_COLUMN), errors='coerce')
+            api_paid_count = pd.to_numeric(stat_from_api.get(FOLLOWER_STATS_PAID_COLUMN), errors='coerce')
+            api_organic_count = 0 if pd.isna(api_organic_count) else int(api_organic_count)
+            api_paid_count = 0 if pd.isna(api_paid_count) else int(api_paid_count)
+
+
+            if key_from_api not in existing_stats_map:
+                logging.info(f"DEBUG: API stat index {i}: Key={key_from_api} NOT FOUND in existing_stats_map. Adding for BULK UPLOAD.")
                 stats_for_bulk_upload.append(stat_from_api)
             else:
-                # Stat category/month exists, check if counts need updating
-                existing_organic, existing_paid, bubble_id = existing_stats_map[key]
+                existing_organic, existing_paid, bubble_id = existing_stats_map[key_from_api] # Counts are already int from map
+                logging.info(f"DEBUG: API stat index {i}: Key={key_from_api} FOUND in existing_stats_map. BubbleID={bubble_id}. ExistingCounts(O/P): {existing_organic}/{existing_paid}. APICounts(O/P): {api_organic_count}/{api_paid_count}.")
+                
                 fields_to_update_in_bubble = {}
-
-                if api_organic_count != existing_organic:
+                if api_organic_count > existing_organic:
                     fields_to_update_in_bubble[FOLLOWER_STATS_ORGANIC_COLUMN] = api_organic_count
+                    logging.debug(f"DEBUG: API stat index {i}: Organic count update: API({api_organic_count}) > Bubble({existing_organic}) for BubbleID {bubble_id}")
                 
-                if api_paid_count != existing_paid:
+                if api_paid_count > existing_paid:
                     fields_to_update_in_bubble[FOLLOWER_STATS_PAID_COLUMN] = api_paid_count
+                    logging.debug(f"DEBUG: API stat index {i}: Paid count update: API({api_paid_count}) > Bubble({existing_paid}) for BubbleID {bubble_id}")
                 
-                if fields_to_update_in_bubble: # If there's at least one field to update
+                if fields_to_update_in_bubble:
                     records_to_update_via_patch.append((bubble_id, fields_to_update_in_bubble))
+                    logging.info(f"DEBUG: API stat index {i}: Queued for PATCH update. BubbleID={bubble_id}, Updates={fields_to_update_in_bubble}")
+                else:
+                    logging.info(f"DEBUG: API stat index {i}: Counts are not greater or equal. No update needed for BubbleID={bubble_id}.")
         
-        # --- Perform Bubble Operations ---
         num_bulk_uploaded = 0
         if stats_for_bulk_upload:
+            logging.info(f"DEBUG: Attempting to bulk upload {len(stats_for_bulk_upload)} new follower stat entries.")
             if bulk_upload_to_bubble(stats_for_bulk_upload, BUBBLE_FOLLOWER_STATS_TABLE_NAME):
                 num_bulk_uploaded = len(stats_for_bulk_upload)
                 logging.info(f"Successfully bulk-uploaded {num_bulk_uploaded} new follower stat entries to Bubble for org {org_urn}.")
@@ -427,15 +448,18 @@ def sync_linkedin_follower_stats(token_state):
         
         num_patched_updated = 0
         if records_to_update_via_patch:
+            logging.info(f"DEBUG: Attempting to PATCH update {len(records_to_update_via_patch)} follower stat entries.")
+            successfully_patched_ids_and_data_temp = [] # To store what was actually successful for token_state update
             for bubble_id, fields_to_update in records_to_update_via_patch:
                 if update_record_in_bubble(BUBBLE_FOLLOWER_STATS_TABLE_NAME, bubble_id, fields_to_update):
                     num_patched_updated += 1
+                    successfully_patched_ids_and_data_temp.append({'bubble_id': bubble_id, 'fields': fields_to_update})
                 else:
                     logging.error(f"Failed to update record {bubble_id} via PATCH for follower stats for org {org_urn}.")
             logging.info(f"Attempted to update {len(records_to_update_via_patch)} follower stat entries via PATCH, {num_patched_updated} succeeded for org {org_urn}.")
 
         if not stats_for_bulk_upload and not records_to_update_via_patch:
-            logging.info(f"Follower Stats sync: Data for org {org_urn} is up-to-date or no changes met update criteria.")
+            logging.info(f"DEBUG: Follower Stats sync: Data for org {org_urn} is up-to-date or no changes met update criteria.")
             follower_stats_sync_message = "Follower Stats: Data up-to-date or no qualifying changes. "
         else:
             follower_stats_sync_message = f"Follower Stats: Synced (New: {num_bulk_uploaded}, Updated: {num_patched_updated}). "
@@ -443,85 +467,71 @@ def sync_linkedin_follower_stats(token_state):
         # --- Update token_state's follower stats DataFrame ---
         current_data_for_state_df = bubble_follower_stats_df_orig.copy()
 
-        if records_to_update_via_patch and num_patched_updated > 0:
-            # Create a temporary map of successful updates for quick lookup
-            successful_updates_map = {
-                bubble_id: fields for i, (bubble_id, fields) in enumerate(records_to_update_via_patch) if i < num_patched_updated
-            }
-            if successful_updates_map: # only proceed if there were successful updates to reflect
-                for index, row in current_data_for_state_df.iterrows():
-                    bubble_id_from_df = row.get(BUBBLE_UNIQUE_ID_COLUMN_NAME)
-                    if bubble_id_from_df in successful_updates_map:
-                        fields_updated = successful_updates_map[bubble_id_from_df]
-                        for col, value in fields_updated.items():
-                            current_data_for_state_df.loc[index, col] = value
+        if num_patched_updated > 0: # Check against actual successful patches
+            for item in successfully_patched_ids_and_data_temp: # Iterate over successfully patched items
+                bubble_id = item['bubble_id']
+                fields_updated = item['fields']
+                idx = current_data_for_state_df[current_data_for_state_df[BUBBLE_UNIQUE_ID_COLUMN_NAME] == bubble_id].index
+                if not idx.empty:
+                    for col, value in fields_updated.items():
+                        current_data_for_state_df.loc[idx, col] = value
         
-        if stats_for_bulk_upload and num_bulk_uploaded > 0:
-            # Only consider successfully uploaded new records
-            successfully_created_stats = [s for i, s in enumerate(stats_for_bulk_upload) if i < num_bulk_uploaded]
+        if num_bulk_uploaded > 0: # Check against actual successful bulk uploads
+            successfully_created_stats = stats_for_bulk_upload[:num_bulk_uploaded] # Slice based on success count
             if successfully_created_stats:
                 newly_created_df = pd.DataFrame(successfully_created_stats)
                 if not newly_created_df.empty:
                     for col in current_data_for_state_df.columns:
                         if col not in newly_created_df.columns:
-                            newly_created_df[col] = pd.NA # Use pd.NA for missing values
-                    # Align columns before concat to avoid issues with differing column orders or types
+                            newly_created_df[col] = pd.NA 
                     aligned_newly_created_df = newly_created_df.reindex(columns=current_data_for_state_df.columns).fillna(pd.NA)
                     current_data_for_state_df = pd.concat([current_data_for_state_df, aligned_newly_created_df], ignore_index=True)
 
         if not current_data_for_state_df.empty:
-            # Deduplication logic (important after combining original, patched, and new data)
-            # Ensure consistent primary key for deduplication across types
-            # For monthly gains, primary key is (org_urn, type='follower_gains_monthly', category=date_str)
-            # For demographics, primary key is (org_urn, type, category)
-            
-            # To handle this, we can sort by a hypothetical 'last_modified_indicator' if we had one,
-            # or rely on 'keep=last' after ensuring data is ordered such that API data (potentially newer) comes later.
-            # The concat order (original, then new) and then drop_duplicates with keep='last' on identifying keys is standard.
-
-            # We need to define unique keys for each type to drop duplicates correctly.
-            # The current deduplication splits by type and then applies different subsets. This should still work.
-            
-            monthly_part = current_data_for_state_df[current_data_for_state_df[FOLLOWER_STATS_TYPE_COLUMN] == 'follower_gains_monthly']
+            monthly_part = current_data_for_state_df[current_data_for_state_df[FOLLOWER_STATS_TYPE_COLUMN] == 'follower_gains_monthly'].copy()
             if not monthly_part.empty:
-                # Ensure category is consistently formatted for monthly gains before deduplication
-                monthly_part_copy = monthly_part.copy() # To avoid SettingWithCopyWarning
-                monthly_part_copy[FOLLOWER_STATS_CATEGORY_COLUMN] = pd.to_datetime(monthly_part_copy[FOLLOWER_STATS_CATEGORY_COLUMN], errors='coerce').dt.strftime('%Y-%m-%d')
-                monthly_part = monthly_part_copy.drop_duplicates(
+                # Ensure FOLLOWER_STATS_CATEGORY_COLUMN is string before strftime, after to_datetime
+                monthly_part.loc[:, FOLLOWER_STATS_CATEGORY_COLUMN] = pd.to_datetime(monthly_part[FOLLOWER_STATS_CATEGORY_COLUMN], errors='coerce').dt.strftime('%Y-%m-%d')
+                monthly_part = monthly_part.drop_duplicates(
                     subset=[FOLLOWER_STATS_ORG_URN_COLUMN, FOLLOWER_STATS_TYPE_COLUMN, FOLLOWER_STATS_CATEGORY_COLUMN],
                     keep='last'
                 )
 
-            demographics_part = current_data_for_state_df[current_data_for_state_df[FOLLOWER_STATS_TYPE_COLUMN] != 'follower_gains_monthly']
+            demographics_part = current_data_for_state_df[current_data_for_state_df[FOLLOWER_STATS_TYPE_COLUMN] != 'follower_gains_monthly'].copy()
             if not demographics_part.empty:
+                # For demographics, category is already cleaned (and lowercased) if it was text
+                # Ensure all subset columns exist before drop_duplicates
                 demo_subset_cols = [FOLLOWER_STATS_ORG_URN_COLUMN, FOLLOWER_STATS_TYPE_COLUMN, FOLLOWER_STATS_CATEGORY_COLUMN]
                 if all(col in demographics_part.columns for col in demo_subset_cols):
+                     # Clean the category column here again to match the key generation for demographics
+                    demographics_part.loc[:, FOLLOWER_STATS_CATEGORY_COLUMN] = demographics_part[FOLLOWER_STATS_CATEGORY_COLUMN].apply(lambda x: _clean_key_component(x, is_category_identifier=True))
                     demographics_part = demographics_part.drop_duplicates(
                         subset=demo_subset_cols,
                         keep='last'
                     )
                 else:
-                    logging.warning("Follower Stats: Missing columns for demographic deduplication in token_state update. Skipping.")
+                    logging.warning(f"DEBUG: Demographics part missing one of {demo_subset_cols} for deduplication.")
             
             if monthly_part.empty and demographics_part.empty:
                 token_state["bubble_follower_stats_df"] = pd.DataFrame(columns=bubble_follower_stats_df_orig.columns)
-            elif monthly_part.empty:
+            elif monthly_part.empty: # only demographics_part has data or is empty
                 token_state["bubble_follower_stats_df"] = demographics_part.reset_index(drop=True) if not demographics_part.empty else pd.DataFrame(columns=bubble_follower_stats_df_orig.columns)
-            elif demographics_part.empty:
+            elif demographics_part.empty: # only monthly_part has data or is empty
                 token_state["bubble_follower_stats_df"] = monthly_part.reset_index(drop=True) if not monthly_part.empty else pd.DataFrame(columns=bubble_follower_stats_df_orig.columns)
-            else:
+            else: # both have data
                 token_state["bubble_follower_stats_df"] = pd.concat([monthly_part, demographics_part], ignore_index=True)
-        else:
+        else: # if current_data_for_state_df ended up empty
             token_state["bubble_follower_stats_df"] = pd.DataFrame(columns=bubble_follower_stats_df_orig.columns)
 
+
     except ValueError as ve:
-        logging.error(f"ValueError during follower stats sync for {org_urn}: {ve}", exc_info=True)
+        logging.error(f"DEBUG: ValueError during follower stats sync for {org_urn}: {ve}", exc_info=True)
         follower_stats_sync_message = f"Follower Stats Error: {html.escape(str(ve))}. "
-    except Exception as e:
-        logging.exception(f"Unexpected error in sync_linkedin_follower_stats for {org_urn}.")
+    except Exception as e: # Catch any other unexpected error
+        logging.exception(f"DEBUG: Unexpected error in sync_linkedin_follower_stats for {org_urn}.") # .exception logs stack trace
         follower_stats_sync_message = f"Follower Stats: Unexpected error ({type(e).__name__}). "
     finally:
-        if not attempt_logged and org_urn:
+        if not attempt_logged and org_urn: # Ensure log attempt happens if not already logged due to early exit
             token_state = _log_sync_attempt(org_urn, LOG_SUBJECT_FOLLOWER_STATS, token_state)
             
     return follower_stats_sync_message, token_state