linkedin_follower_stats.py

# -- coding: utf-8 --
import json
import requests
import logging
from datetime import datetime, timezone, timedelta
from urllib.parse import quote, urlencode
import requests_oauthlib # For version logging

# Assuming you have a sessions.py with create_session
# If sessions.py or create_session is not found, it will raise an ImportError,
# which is appropriate for a module that depends on it.
from sessions import create_session # Make sure this file exists and is correct

logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

API_V2_BASE = 'https://api.linkedin.com/v2'
API_REST_BASE = "https://api.linkedin.com/rest"
LINKEDIN_API_VERSION = "202502"

# --- ID to Name Mapping Helper Functions ---

def _fetch_linkedin_names(session, url, params, result_key_path, name_key_path, id_key="id"):
    """
    Generic helper to fetch and map IDs to names from a LinkedIn API endpoint.
    """
    mapping = {}
    request_url_for_logging = url 
    response_obj = None 
    try:
        logging.debug(f"_fetch_linkedin_names (id: {id(session)}): About to prepare request. Session token: {session.token}, Session authorized: {session.authorized}, Expires at: {session.token.get('expires_at') if session.token else 'N/A'}")
        logging.debug(f"_fetch_linkedin_names (id: {id(session)}): Session auth object: type={type(session.auth)}, value={session.auth}")

        req = requests.Request('GET', url, params=params)
        prepared_req = session.prepare_request(req) 
        request_url_for_logging = prepared_req.url
        
        logging.debug(f"Fetching names from URL: {request_url_for_logging}")
        logging.debug(f"Request headers for _fetch_linkedin_names: {json.dumps(dict(prepared_req.headers), indent=2)}")

        response_obj = session.send(prepared_req, timeout=30)
        response_obj.raise_for_status()
        data = response_obj.json()

        items = data
        for key in result_key_path:
            if isinstance(items, dict):
                items = items.get(key) 
                if items is None: 
                    logging.warning(f"Key '{key}' not found in response from {request_url_for_logging} at path {result_key_path}. Response data: {json.dumps(data, indent=2)}")
                    return mapping
            else:
                logging.warning(f"Expected dict to get key '{key}' but got {type(items)} at path {result_key_path} for URL {request_url_for_logging}. Check result_key_path.")
                return mapping

        if items is None: 
            logging.warning(f"Items became None after navigating result_key_path for URL {request_url_for_logging}. Path: {result_key_path}")
            return mapping

        if isinstance(items, dict): 
            for item_id_str, item_data in items.items():
                name = item_data
                for key_nav in name_key_path:
                    if isinstance(name, dict):
                        name = name.get(key_nav)
                    else:
                        name = None
                        break
                if name:
                    mapping[item_id_str] = name
                else:
                    logging.warning(f"No name found for ID {item_id_str} at path {name_key_path} in item: {item_data} from URL {request_url_for_logging}")
        elif isinstance(items, list): 
            for item in items:
                item_id_val = item.get(id_key)
                name = item
                for key_nav in name_key_path:
                    if isinstance(name, dict):
                        name = name.get(key_nav)
                    else:
                        name = None
                        break
                if item_id_val is not None and name:
                    mapping[str(item_id_val)] = name
                else:
                    if item_id_val is None:
                        logging.warning(f"No ID ('{id_key}') found in item: {item} from URL {request_url_for_logging}")
                    if name is None:
                         logging.warning(f"No name found at path {name_key_path} for item with ID '{item_id_val}' in item: {item} from URL {request_url_for_logging}")
        else:
            logging.warning(f"Expected list or dict of items at {result_key_path} from URL {request_url_for_logging}, got {type(items)}. Full items: {items}")

    except requests.exceptions.HTTPError as http_err:
        status_code = "N/A"; error_text = str(http_err); response_headers = {}
        if http_err.response is not None:
            status_code = http_err.response.status_code
            error_text = http_err.response.text
            response_headers = dict(http_err.response.headers)
        logging.error(f"HTTP error in _fetch_linkedin_names from {request_url_for_logging} (Status: {status_code}): {error_text}")
        logging.error(f"Response Headers: {json.dumps(response_headers, indent=2)}")
    except requests.exceptions.RequestException as req_err:
        logging.error(f"Request error in _fetch_linkedin_names from {request_url_for_logging}: {str(req_err)}")
        if req_err.response is not None:
            logging.error(f"Associated Response Status: {req_err.response.status_code}, Text: {req_err.response.text}, Headers: {json.dumps(dict(req_err.response.headers), indent=2)}")
    except json.JSONDecodeError as json_err:
        response_text = "Not available"
        if response_obj is not None and hasattr(response_obj, 'text'): response_text = response_obj.text
        logging.error(f"Error decoding JSON for names from {request_url_for_logging}: {json_err}. Response text: {response_text}")
    except Exception as e:
        logging.error(f"Unexpected error in _fetch_linkedin_names from {request_url_for_logging}: {e}", exc_info=True)
        if response_obj is not None:
            logging.error(f"Associated Response (if any) Status: {getattr(response_obj, 'status_code', 'N/A')}, Text: {getattr(response_obj, 'text', 'N/A')}")
    return mapping

def get_functions_map(session):
    url = f"{API_V2_BASE}/functions"
    params = {'count': 200} 
    logging.info("Fetching all LinkedIn functions.")
    return _fetch_linkedin_names(session, url, params, ["elements"], ["name", "localized", "en_US"], "id")

def get_seniorities_map(session):
    url = f"{API_V2_BASE}/seniorities"
    params = {'count': 200} 
    logging.info("Fetching all LinkedIn seniorities.")
    return _fetch_linkedin_names(session, url, params, ["elements"], ["name", "localized", "en_US"], "id")

def get_industries_map(session, industry_urns, version="DEFAULT"):
    industry_ids = [_parse_urn_to_id(urn) for urn in industry_urns or []]
    unique_ids = set(filter(None, industry_ids))
    if not unique_ids:
        return {}

    url = f"{API_V2_BASE}/industryTaxonomyVersions/{version}/industries"
    params = { 'start': 0, 'count': 500 }
    request_url_for_logging = url 
    response_obj = None
    logging.info(f"Fetching all industries (to filter {len(unique_ids)} IDs)")
    try:
        logging.debug(f"get_industries_map (id: {id(session)}): About to prepare request. Session token: {session.token}, Session authorized: {session.authorized}, Expires at: {session.token.get('expires_at') if session.token else 'N/A'}")
        logging.debug(f"get_industries_map (id: {id(session)}): Session auth object: type={type(session.auth)}, value={session.auth}")
        req = requests.Request('GET', url, params=params)
        prepared_req = session.prepare_request(req)
        request_url_for_logging = prepared_req.url
        logging.debug(f"Requesting all industries from URL: {request_url_for_logging}")
        logging.debug(f"Request headers for get_industries_map: {json.dumps(dict(prepared_req.headers), indent=2)}")

        response_obj = session.send(prepared_req, timeout=30)
        response_obj.raise_for_status()
        data = response_obj.json()
        elements = data.get('elements', [])

        mapping = {}
        for el in elements:
            el_id = el.get('id')
            if el_id and str(el_id) in unique_ids:
                name = el.get('name', {}).get('localized', {}).get('en_US')
                if name:
                    mapping[str(el_id)] = name
                else:
                    logging.warning(f"Industry {el_id} has no en_US name field in element: {el} from URL {request_url_for_logging}")
        return mapping
    except requests.exceptions.HTTPError as http_err:
        status_code = "N/A"; error_text = str(http_err); response_headers = {}
        if http_err.response is not None:
            status_code = http_err.response.status_code
            error_text = http_err.response.text
            response_headers = dict(http_err.response.headers)
        logging.error(f"HTTP error fetching all industries from {request_url_for_logging} (Status: {status_code}): {error_text}")
        logging.error(f"Response Headers: {json.dumps(response_headers, indent=2)}")
        return {}
    except requests.exceptions.RequestException as req_err:
        logging.error(f"Request error fetching all industries from {request_url_for_logging}: {str(req_err)}")
        if req_err.response is not None:
            logging.error(f"Associated Response Status: {req_err.response.status_code}, Text: {req_err.response.text}, Headers: {json.dumps(dict(req_err.response.headers), indent=2)}")
        return {}
    except json.JSONDecodeError as json_err:
        response_text = "Not available"
        if response_obj is not None and hasattr(response_obj, 'text'): response_text = response_obj.text
        logging.error(f"Error decoding JSON for industries from {request_url_for_logging}: {json_err}. Response text: {response_text}")
        return {}
    except Exception as e:
        logging.error(f"Unexpected error fetching all industries from {request_url_for_logging}: {e}", exc_info=True)
        if response_obj is not None:
            logging.error(f"Associated Response (if any) Status: {getattr(response_obj, 'status_code', 'N/A')}, Text: {getattr(response_obj, 'text', 'N/A')}")
        return {}

def get_geo_map(session, geo_urns):
    if not geo_urns: return {}
    geo_ids = [_parse_urn_to_id(urn) for urn in geo_urns if urn]
    unique_ids = list(set(filter(None, geo_ids)))
    if not unique_ids: return {}

    MAX_GEO_IDS_PER_CALL = 100 
    all_geo_mappings = {}

    for i in range(0, len(unique_ids), MAX_GEO_IDS_PER_CALL):
        chunk_ids = unique_ids[i:i + MAX_GEO_IDS_PER_CALL]
        if not chunk_ids: continue

        ids_param_value = "List(" + ",".join(map(str, chunk_ids)) + ")"
        locale_param_value = "(language:en,country:US)" 

        url = f"{API_V2_BASE}/geo"
        geo_params = { 'ids': ids_param_value, 'locale': locale_param_value }
        
        logging.info(f"Fetching names for {len(chunk_ids)} geo IDs (chunk {i//MAX_GEO_IDS_PER_CALL + 1})")
        chunk_mapping = _fetch_linkedin_names(session, url, geo_params, ["results"], ["defaultLocalizedName", "value"])
        all_geo_mappings.update(chunk_mapping)
        
    return all_geo_mappings


def _parse_urn_to_id(urn_string):
    if not isinstance(urn_string, str):
        logging.debug(f"Invalid URN type: {type(urn_string)}, value: {urn_string}. Cannot parse ID.")
        return None
    try:
        return urn_string.split(':')[-1]
    except IndexError:
        logging.warning(f"Could not parse ID from URN: {urn_string}")
        return None
    except Exception as e: 
        logging.error(f"Unexpected error parsing URN {urn_string}: {e}")
        return None

# --- Follower Data Fetching Functions ---

def fetch_monthly_follower_gains(session, org_urn, api_rest_base_url):
    now_utc = datetime.now(timezone.utc)
    start_of_reporting_period = (now_utc - timedelta(days=365)).replace(day=1, hour=0, minute=0, second=0, microsecond=0)
    start_ms = int(start_of_reporting_period.timestamp() * 1000)

    base_url = f"{api_rest_base_url}/organizationalEntityFollowerStatistics"
    time_intervals_value = f"(timeRange:(start:{start_ms}),timeGranularityType:MONTH)"

    api_params = {
        "q": "organizationalEntity",
        "organizationalEntity": org_urn,
        "timeIntervals": time_intervals_value
    }
    
    logging.info(f"Preparing to fetch monthly follower gains for {org_urn}.")
    logging.debug(f"API Parameters for monthly gains: {json.dumps(api_params)}")

    results = []
    request_url_for_logging = "Not constructed" 
    response_obj = None 

    try:
        logging.debug(f"fetch_monthly_follower_gains (id: {id(session)}): About to prepare request. Session token: {session.token}, Session authorized: {session.authorized}, Expires at: {session.token.get('expires_at') if session.token else 'N/A'}")
        logging.debug(f"fetch_monthly_follower_gains (id: {id(session)}): Session auth object: type={type(session.auth)}, value={session.auth}")
        logging.debug(f"fetch_monthly_follower_gains (id: {id(session)}): Auto-refresh URL: {session.auto_refresh_url}, Auto-refresh kwargs: {session.auto_refresh_kwargs}")
        if session.token and 'access_token' in session.token:
            logging.debug(f"fetch_monthly_follower_gains: Access token (partial): {str(session.token['access_token'])[:20]}...")
        else:
            logging.warning("fetch_monthly_follower_gains: session.token is None or 'access_token' key is missing before prepare_request.")

        req = requests.Request('GET', base_url, params=api_params)
        prepared_req = session.prepare_request(req)
        request_url_for_logging = prepared_req.url
        
        logging.info(f"Requesting monthly follower gains from URL: {request_url_for_logging}")
        logging.debug(f"Request Headers for monthly gains: {json.dumps(dict(prepared_req.headers), indent=2)}")

        response_obj = session.send(prepared_req, timeout=30) 
        response_obj.raise_for_status() 
        data = response_obj.json()
        
        elements = data.get('elements', [])
        if not elements:
            logging.info(f"No 'elements' found in monthly follower gains API response for {org_urn} (start_ms {start_ms}). Response data: {json.dumps(data, indent=2)}")

        for item in elements:
            time_range = item.get('timeRange', {})
            ts = time_range.get('start')
            if ts is None:
                logging.warning(f"Skipping item due to missing 'start' timestamp: {item}")
                continue
            
            date_obj = datetime.fromtimestamp(ts / 1000, tz=timezone.utc)
            date_str = date_obj.strftime('%Y-%m-%d')
            
            gains = item.get('followerGains', {})
            if gains is None: gains = {} 

            results.append({
                'category_name': date_str,
                'follower_count_organic': gains.get('organicFollowerGain', 0),
                'follower_count_paid': gains.get('paidFollowerGain', 0),
                'follower_count_type': 'follower_gains_monthly',
                'organization_urn': org_urn
            })
        logging.info(f"Fetched {len(results)} monthly follower entries for {org_urn} starting from {start_of_reporting_period.strftime('%Y-%m-%d')}.")
    
    except requests.exceptions.HTTPError as http_err:
        code = "N/A"; text = str(http_err); resp_headers = {}
        if http_err.response is not None:
            code = http_err.response.status_code
            text = http_err.response.text
            resp_headers = dict(http_err.response.headers)
        logging.error(f"HTTP error fetching monthly gains for {org_urn}: {code} - {text}")
        logging.error(f"Request URL was: {request_url_for_logging}")
        logging.error(f"Response Headers: {json.dumps(resp_headers, indent=2)}")
    except requests.exceptions.RequestException as req_err: 
        logging.error(f"RequestException fetching monthly gains for {org_urn}: {str(req_err)}")
        logging.error(f"Request URL was: {request_url_for_logging}")
        if req_err.response is not None: 
            logging.error(f"Associated Response Status: {req_err.response.status_code}")
            logging.error(f"Associated Response Text: {req_err.response.text}")
            logging.error(f"Associated Response Headers: {json.dumps(dict(req_err.response.headers), indent=2)}")
    except json.JSONDecodeError as json_err:
        response_text = "Not available"
        if response_obj is not None and hasattr(response_obj, 'text'):
            response_text = response_obj.text
        logging.error(f"Error decoding JSON for monthly follower gains for {org_urn}: {json_err}")
        logging.error(f"Request URL was: {request_url_for_logging}")
        logging.error(f"Raw Response Text: {response_text}")
    except Exception as ex:
        logging.error(f"An unexpected error occurred while fetching monthly gains for {org_urn}: {str(ex)}", exc_info=True)
        logging.error(f"Request URL was: {request_url_for_logging}")
        if response_obj is not None: 
            logging.error(f"Response Status (if available): {getattr(response_obj, 'status_code', 'N/A')}")
            logging.error(f"Response Text (if available): {getattr(response_obj, 'text', 'N/A')}")
            logging.error(f"Response Headers (if available): {json.dumps(dict(getattr(response_obj, 'headers', {})), indent=2)}")
            
    return results


def fetch_follower_demographics(session, org_urn, functions_map, seniorities_map):
    final_demographics_results = []
    base_url = f"{API_REST_BASE}/organizationalEntityFollowerStatistics"
    params = { 'q': 'organizationalEntity', 'organizationalEntity': org_urn }
    
    logging.info(f"Preparing to fetch follower demographics for org URN {org_urn}.")
    logging.debug(f"API Parameters for demographics: {json.dumps(params)}")
    request_url_for_logging = "Not constructed"
    response_obj = None

    try:
        logging.debug(f"fetch_follower_demographics (id: {id(session)}): About to prepare request. Session token: {session.token}, Session authorized: {session.authorized}, Expires at: {session.token.get('expires_at') if session.token else 'N/A'}")
        logging.debug(f"fetch_follower_demographics (id: {id(session)}): Session auth object: type={type(session.auth)}, value={session.auth}")
        logging.debug(f"fetch_follower_demographics (id: {id(session)}): Auto-refresh URL: {session.auto_refresh_url}, Auto-refresh kwargs: {session.auto_refresh_kwargs}")
        if session.token and 'access_token' in session.token:
            logging.debug(f"fetch_follower_demographics: Access token (partial): {str(session.token['access_token'])[:20]}...")
        else:
            logging.warning("fetch_follower_demographics: session.token is None or 'access_token' key is missing before prepare_request.")

        req = requests.Request('GET', base_url, params=params)
        prepared_req = session.prepare_request(req)
        request_url_for_logging = prepared_req.url

        logging.info(f"Requesting follower demographics from URL: {request_url_for_logging}")
        logging.debug(f"Request Headers for demographics: {json.dumps(dict(prepared_req.headers), indent=2)}")

        response_obj = session.send(prepared_req, timeout=30) 
        response_obj.raise_for_status()
        data = response_obj.json()
        
        elements = data.get("elements", [])
        if not elements:
            logging.warning(f"No elements found in follower demographics response for {org_urn}. Response data: {json.dumps(data, indent=2)}")
            return []
        
        stat_element = elements[0] if len(elements) > 0 else None
        if not stat_element:
            logging.warning(f"Elements list is empty or stat_element is None in demographics response for {org_urn}. Response data: {json.dumps(data, indent=2)}")
            return []

        def _get_entries_for_type(raw_items_list, type_name, id_map, id_field_name_in_item, org_urn_val):
            current_type_entries = []
            if not raw_items_list:
                logging.debug(f"No raw items for demographic type '{type_name}' for org {org_urn_val}.")
                return current_type_entries
            for item in raw_items_list:
                category_name_val = "Unknown"
                if type_name == "follower_association": 
                    category_name_val = item.get(id_field_name_in_item, f"Unknown {id_field_name_in_item}")
                else: 
                    urn_val = item.get(id_field_name_in_item)
                    entity_id = _parse_urn_to_id(urn_val)
                    if entity_id and id_map: 
                        category_name_val = id_map.get(str(entity_id), f"Unknown {type_name.split('_')[-1].capitalize()} (ID: {entity_id})")
                    elif urn_val: 
                         category_name_val = f"Unmapped {type_name.split('_')[-1].capitalize()} (URN: {urn_val})"
                    else: 
                        category_name_val = f"Missing URN for {type_name.split('_')[-1].capitalize()}"
                counts = item.get("followerCounts", {})
                organic_count = counts.get("organicFollowerCount", 0)
                paid_count = counts.get("paidFollowerCount", 0) 
                current_type_entries.append({
                    "category_name": category_name_val,
                    "follower_count_organic": organic_count, 
                    "follower_count_paid": paid_count,       
                    "follower_count_type": type_name,
                    "organization_urn": org_urn_val
                })
            return current_type_entries
        industry_urns_to_map = [item.get("industry") for item in stat_element.get("followerCountsByIndustry", []) if item.get("industry")]
        geo_urns_to_map = [item.get("geo") for item in stat_element.get("followerCountsByGeoCountry", []) if item.get("geo")]
        live_industries_map = get_industries_map(session, list(set(industry_urns_to_map))) 
        live_geo_map = get_geo_map(session, list(set(geo_urns_to_map))) 
        demographic_configs = [
            {"items_key": "followerCountsBySeniority", "type_name": "follower_seniority", "id_map": seniorities_map, "id_field": "seniority", "top_n": 10},
            {"items_key": "followerCountsByFunction", "type_name": "follower_function", "id_map": functions_map, "id_field": "function", "top_n": 10},
            {"items_key": "followerCountsByIndustry", "type_name": "follower_industry", "id_map": live_industries_map, "id_field": "industry", "top_n": 10},
            {"items_key": "followerCountsByGeoCountry", "type_name": "follower_geo", "id_map": live_geo_map, "id_field": "geo", "top_n": 10},
            {"items_key": "followerCountsByAssociationType", "type_name": "follower_association", "id_map": {}, "id_field": "associationType", "top_n": None} 
        ]
        for config in demographic_configs:
            raw_items = stat_element.get(config["items_key"], [])
            processed_entries = _get_entries_for_type(raw_items, config["type_name"], config["id_map"], config["id_field"], org_urn)
            if config["top_n"] is not None and processed_entries:
                for entry in processed_entries:
                    if not isinstance(entry.get("follower_count_organic"), (int, float)):
                        logging.warning(f"Invalid organic follower count for sorting in {config['type_name']}: {entry['follower_count_organic']}. Setting to 0.")
                        entry["follower_count_organic"] = 0
                sorted_entries = sorted(processed_entries, key=lambda x: x.get("follower_count_organic", 0), reverse=True)
                final_demographics_results.extend(sorted_entries[:config["top_n"]])
                logging.debug(f"Added top {config['top_n']} for {config['type_name']}. Count: {len(sorted_entries[:config['top_n']])}")
            else: 
                final_demographics_results.extend(processed_entries)
                logging.debug(f"Added all for {config['type_name']}. Count: {len(processed_entries)}")
        logging.info(f"Processed follower demographics for {org_urn}. Total entries from all types: {len(final_demographics_results)}")
    except requests.exceptions.HTTPError as http_err:
        code = "N/A"; text = str(http_err); resp_headers = {}
        if http_err.response is not None:
            code = http_err.response.status_code
            text = http_err.response.text
            resp_headers = dict(http_err.response.headers)
        logging.error(f"HTTP error fetching follower demographics for {org_urn} (Status: {code}): {text}")
        logging.error(f"Request URL was: {request_url_for_logging}")
        logging.error(f"Response Headers: {json.dumps(resp_headers, indent=2)}")
    except requests.exceptions.RequestException as req_err:
        logging.error(f"RequestException fetching follower demographics for {org_urn}: {str(req_err)}")
        logging.error(f"Request URL was: {request_url_for_logging}")
        if req_err.response is not None:
            logging.error(f"Associated Response Status: {req_err.response.status_code}")
            logging.error(f"Associated Response Text: {req_err.response.text}")
            logging.error(f"Associated Response Headers: {json.dumps(dict(req_err.response.headers), indent=2)}")
    except json.JSONDecodeError as json_err:
        response_text = "Not available"
        if response_obj is not None and hasattr(response_obj, 'text'):
            response_text = response_obj.text
        logging.error(f"Error decoding JSON for follower demographics for {org_urn}: {json_err}")
        logging.error(f"Request URL was: {request_url_for_logging}")
        logging.error(f"Raw Response Text: {response_text}")
    except Exception as e:
        logging.error(f"Unexpected error fetching follower demographics for {org_urn}: {e}", exc_info=True)
        logging.error(f"Request URL was: {request_url_for_logging}")
        if response_obj is not None:
            logging.error(f"Response Status (if available): {getattr(response_obj, 'status_code', 'N/A')}")
            logging.error(f"Response Text (if available): {getattr(response_obj, 'text', 'N/A')}")
            logging.error(f"Response Headers (if available): {json.dumps(dict(getattr(response_obj, 'headers', {})), indent=2)}")
    return final_demographics_results

# --- Main Orchestration Function ---

def get_linkedin_follower_stats(comm_client_id, community_token, org_urn):
    logging.info(f"--- Initiating get_linkedin_follower_stats for org: {org_urn} ---")
    logging.info(f"requests-oauthlib version: {requests_oauthlib.__version__}") # Log version
    logging.debug(f"Received comm_client_id: {comm_client_id}")
    logging.debug(f"Received community_token - Type: {type(community_token)}, IsSet: {bool(community_token)}")
    if isinstance(community_token, str) and len(community_token) > 10:
        logging.debug(f"Received community_token (partial): {community_token[:10]}...")
    elif isinstance(community_token, dict):
         logging.debug(f"Received community_token (dict): { {k: (v[:10] + '...' if k == 'access_token' and isinstance(v, str) and len(v)>10 else v) for k,v in community_token.items()} }")

    if not all([comm_client_id, community_token, org_urn]):
        logging.error("Client ID, community_token, or Organization URN is missing or empty.")
        if not comm_client_id: logging.error("comm_client_id is missing.")
        if not community_token: logging.error("community_token is missing or empty.") 
        if not org_urn: logging.error("org_urn is missing.")
        return []

    token_dict = community_token if isinstance(community_token, dict) else {'access_token': str(community_token), 'token_type': 'Bearer'}
    
    if not token_dict.get('access_token'):
        logging.error("Failed to construct a valid token_dict: 'access_token' is empty.")
        logging.debug(f"Problematic token_dict: {token_dict}")
        return []
    
    logging.debug(f"Constructed token_dict for session: { {k: (v[:10] + '...' if k == 'access_token' and isinstance(v, str) and len(v)>10 else v) for k,v in token_dict.items()} }")
    
    session = None
    try:
        session = create_session(comm_client_id, token=token_dict) 
        session.headers.update({
            "X-Restli-Protocol-Version": "2.0.0", 
            "LinkedIn-Version": LINKEDIN_API_VERSION, 
            "Accept-Language": "en_US" 
        })
        logging.info(f"Session (id: {id(session)}) created and headers updated for org {org_urn}.")
        logging.debug(f"get_linkedin_follower_stats (id: {id(session)}): Session token after creation: {session.token}, Session authorized: {session.authorized}, Expires at: {session.token.get('expires_at') if session.token else 'N/A'}")
        logging.debug(f"get_linkedin_follower_stats (id: {id(session)}): Session auth object: type={type(session.auth)}, value={session.auth}")
        logging.debug(f"get_linkedin_follower_stats (id: {id(session)}): Auto-refresh URL: {session.auto_refresh_url}, Auto-refresh kwargs: {session.auto_refresh_kwargs}")

        if session.token and 'access_token' in session.token:
             logging.debug(f"get_linkedin_follower_stats: Access token in session (partial): {str(session.token['access_token'])[:20]}...")
        else:
            logging.warning("get_linkedin_follower_stats: session.token is None or 'access_token' key is missing after session creation.")


    except Exception as e:
        logging.error(f"Failed to create session or update headers for org {org_urn}: {e}", exc_info=True)
        return []

    logging.info(f"Starting follower stats retrieval for org: {org_urn} using session (id: {id(session)})")

    functions_map = get_functions_map(session) # Pass session
    seniorities_map = get_seniorities_map(session) # Pass session
    
    if not functions_map: logging.warning(f"Functions map is empty for org {org_urn}.")
    if not seniorities_map: logging.warning(f"Seniorities map is empty for org {org_urn}.")

    all_follower_data = []

    monthly_gains = fetch_monthly_follower_gains(session, org_urn, API_REST_BASE) # Pass session
    all_follower_data.extend(monthly_gains)

    demographics = fetch_follower_demographics(session, org_urn, functions_map, seniorities_map) # Pass session
    all_follower_data.extend(demographics)

    if not all_follower_data:
        logging.warning(f"No follower data (gains or demographics) could be compiled for {org_urn}.")
    else:
        logging.info(f"Successfully compiled {len(all_follower_data)} total follower stat entries for {org_urn}.")
    
    return all_follower_data