Utility Bills API

import requests
import os
import json
from datetime import datetime, timedelta
from typing import Dict, List, Optional

# --- Configuration ---
BASE_URL = "https://app.billgauge.com"
API_KEY = os.environ.get("BILLGAUGE_API_KEY", "your_api_key_here")
PROPERTY_ID = "prop_example_123456"  # Replace with a real property ID

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

class UtilityBillAPI:
    """View and analyze utility bill information using the V1 API."""
    
    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        }
    
    def list_utility_bills(self, page: int = 1, limit: int = 20) -> Optional[Dict]:
        """List utility bills with pagination."""
        print("Fetching utility bills (page %d, limit %d)..." % (page, limit))
        
        params = {"page": page, "limit": limit}
        response = requests.get(
            self.base_url + "/utility-bills",
            headers=self.headers,
            params=params
        )
        
        if response.status_code == 200:
            data = response.json()
            print("✅ Found %d total bills" % data['pagination']['total'])
            return data
        else:
            print("❌ Error fetching bills: %d" % response.status_code)
            print(response.text)
            return None
    
    def get_utility_bill(self, bill_id: str) -> Optional[Dict]:
        """Get a specific utility bill by ID."""
        print("Fetching utility bill %s..." % bill_id)
        
        response = requests.get(
            self.base_url + "/utility-bills/" + bill_id,
            headers=self.headers
        )
        
        if response.status_code == 200:
            print("✅ Successfully retrieved utility bill")
            return response.json()
        elif response.status_code == 404:
            print("❌ Utility bill not found")
            return None
        else:
            print("❌ Error fetching bill: %d" % response.status_code)
            print(response.text)
            return None

def main():
    """Demonstrate utility bill viewing operations."""
    api = UtilityBillAPI(BASE_URL, API_KEY)
    
    # 1. List all bills with pagination
    print("=== Listing All Bills ===")
    bills_response = api.list_utility_bills(page=1, limit=10)
    if bills_response:
        print("Total bills: %d" % bills_response['pagination']['total'])
        print("Showing %d bills" % len(bills_response['data']))
        
        # Show utility types for each bill
        for bill in bills_response['data'][:5]:  # Show first 5
            utility_types = ', '.join(bill.get('utilityType', []))
            payment_status = bill.get('paymentStatus', 'Unknown')
            print("  - %s: %s ($%.2f) - %s" % (bill['issuerName'], utility_types, bill['totalAmountDue'], payment_status))
    
    # 2. Get specific bill details
    if bills_response and bills_response['data']:
        print("\n=== Getting Bill Details ===")
        first_bill = bills_response['data'][0]
        detailed_bill = api.get_utility_bill(first_bill['id'])
        if detailed_bill:
            print("Bill ID:", detailed_bill['id'])
            print("Issuer:", detailed_bill['issuerName'])
            print("Utility Types:", ', '.join(detailed_bill.get('utilityType', [])))
            print("Amount: $%.2f" % detailed_bill['totalAmountDue'])
            print("Payment Status:", detailed_bill.get('paymentStatus', 'Unknown'))
            print("Bill Date:", detailed_bill.get('billDate', 'N/A'))
            if detailed_bill.get('property'):
                print("Property:", detailed_bill['property'].get('name', 'N/A'))
    
    print("\n=== Analysis Complete ===")

# Utility functions for common operations
def analyze_bills_by_utility_type(api: UtilityBillAPI) -> Dict[str, List[Dict]]:
    """Analyze bills grouped by utility type."""
    print("Analyzing bills by utility type...")
    
    bills_response = api.list_utility_bills(limit=100)  # Get more bills for analysis
    if not bills_response:
        return {}
    
    bills_by_type = {}
    total_by_type = {}
    
    for bill in bills_response['data']:
        for utility_type in bill.get('utilityType', []):
            if utility_type not in bills_by_type:
                bills_by_type[utility_type] = []
                total_by_type[utility_type] = 0
            
            bills_by_type[utility_type].append(bill)
            total_by_type[utility_type] += bill.get('totalAmountDue', 0)
    
    # Print summary
    print("\nUtility Type Analysis:")
    for utility_type, bills in bills_by_type.items():
        avg_amount = total_by_type[utility_type] / len(bills)
        print("  %s: %d bills, Total: $%.2f, Avg: $%.2f" % (utility_type, len(bills), total_by_type[utility_type], avg_amount))
    
    return bills_by_type

def find_bills_by_property(api: UtilityBillAPI, property_id: str) -> List[Dict]:
    """Find all bills for a specific property."""
    print("Finding bills for property %s..." % property_id)
    
    all_bills = []
    page = 1
    
    while True:
        bills_response = api.list_utility_bills(page=page, limit=50)
        if not bills_response or not bills_response['data']:
            break
        
        # Filter bills for the specific property
        property_bills = [bill for bill in bills_response['data'] if bill.get('propertyId') == property_id]
        all_bills.extend(property_bills)
        
        # Check if we've reached the last page
        if page >= bills_response['pagination']['totalPages']:
            break
        page += 1
    
    print("Found %d bills for property %s" % (len(all_bills), property_id))
    return all_bills

# Payment status analysis
def analyze_payment_status(api: UtilityBillAPI) -> Dict[str, int]:
    """Analyze payment status distribution."""
    print("Analyzing payment status distribution...")
    
    bills_response = api.list_utility_bills(limit=100)
    if not bills_response:
        return {}
    
    status_counts = {}
    for bill in bills_response['data']:
        status = bill.get('paymentStatus', 'Unknown')
        status_counts[status] = status_counts.get(status, 0) + 1
    
    print("\nPayment Status Distribution:")
    for status, count in status_counts.items():
        print("  %s: %d bills" % (status, count))
    
    return status_counts

if __name__ == "__main__":
    main()
    
    # Uncomment to run analysis examples
    # api = UtilityBillAPI(BASE_URL, API_KEY)
    # analyze_bills_by_utility_type(api)
    # analyze_payment_status(api)
    # find_bills_by_property(api, PROPERTY_ID)