Chapter 10: Advanced JSON Processing

{
  "order": {
    "id": "ord_9f2c",
    "customer": {
      "profile": {
        "name": {
          "first": "Ava",
          "last": "Murphy"
        },
        "contact": {
          "email": "ava@example.com",
          "address": {
            "shipping": {
              "line1": "12 Harbour St",
              "city": "Dublin",
              "country": "IE"
            }
          }
        }
      }
    },
    "items": [
      {
        "sku": "SKU-001",
        "product": {
          "details": {
            "title": "Stainless Water Bottle",
            "pricing": {
              "currency": "EUR",
              "amount": 24.99
            }
          }
        }
      }
    ],
    "payment": {
      "provider": "stripe",
      "transaction": {
        "status": "succeeded",
        "risk": {
          "score": 12,
          "flags": ["ip_mismatch"]
        }
      }
    }
  }
}

{
  "order": {
    "id": "ord_9f2c",
    "customer": {
      "profile": {
        "name": { "first": "Ava", "last": "Murphy" },
        "contact": {
          "email": "ava@example.com"
        }
      }
    }
  }
}

{
  "id": "ORD-91352",
  "created_at": "2025-06-18T14:22:31Z",
  "total": "129.50",
  "currency": "EUR",
  "status": "shipped",
  "customer": {
    "id": 7712,
    "email": "alice@example.com"
  },
  "items": [
    { "sku": "P-001", "qty": 2, "price": 39.75 },
    { "sku": "P-009", "qty": 1, "price": 50.00 }
  ],
  "discount": null
}

{
  "order_id": 91352,
  "ts": 1718710951,
  "amount": 129.5,
  "currency_code": "EUR",
  "state": "Shipped",
  "customer_id": "7712",
  "line_items": [
    { "product": { "sku": "P-001" }, "quantity": "2", "unit_price": "39.75" },
    { "product": { "sku": "P-009" }, "quantity": 1,   "unit_price": 50 }
  ],
  "promo": { "code": "SUMMER", "value": "10%" }
}

{
  "data": {
    "orders": [
      {
        "id": "ORD-91352",
        "created_at": "2025-06-18T14:22:31Z",
        "total": "129.50",
        "currency": "EUR",
        "customer": {
          "id": 7712,
          "email": "alice@example.com"
        },
        "items": [
          {"sku": "P-001", "qty": 2, "price": 39.75},
          {"sku": "P-009", "qty": 1, "price": 50.00}
        ],
        "discount": null,
        "status": "shipped"
      }
    ]
  },
  "meta": { "cursor": "eyJwYWdlIjoyfQ==" }
}

{
  "orders": [
    {
      "order_id": 91352,
      "ts": 1718710951,
      "amount": 129.5,
      "currency_code": "EUR",
      "customer_id": "7712",
      "line_items": [
        {"product": {"sku": "P-001"}, "quantity": "2", "unit_price": "39.75"},
        {"product": {"sku": "P-009"}, "quantity": 1, "unit_price": 50}
      ],
      "promo": { "code": "SUMMER", "value": "10%" },
      "state": "Shipped"
    }
  ],
  "nextPage": "/orders?page=2"
}

{
  "id": "ORD-91352",
  "created_at": "2025-06-18T14:22:31Z",
  "total": 129.50,
  "currency": "EUR",
  "customer": { "id": 7712, "email": "alice@example.com" },
  "items": [
    {"sku": "P-001", "qty": 2, "price": 39.75},
    {"sku": "P-009", "qty": 1, "price": 50.00}
  ],
  "discount": {"type": "percent", "value": 10},
  "status": "shipped"
}

def normalize_order_preview(order):
    """
    Preview: Shows the core concept with just two transformations.
    The complete normalizer in Section 7 handles all eight patterns.
    """
    # 1. FIELD MAPPING: Try both possible field names
    order_id = order.get("id") or order.get("order_id")
    total_amount = order.get("total") or order.get("amount")
    
    # 2. TYPE COERCION: Ensure consistent types
    order_id = str(order_id)  # Always string
    total_amount = float(total_amount or 0)  # Always number
    
    return {
        "id": order_id,
        "total": total_amount
    }

import requests
import json

def explore_api_structure(url, max_depth=2):
    """
    Systematically explore an API response structure.
    This should be your first step with any new API.
    """
    try:
        response = requests.get(url, timeout=10)
        response.raise_for_status()
        data = response.json()
        
        print(f"API Response Analysis for: {url}")
        print("=" * 60)
        print(f"Response type: {type(data).__name__}")
        
        if isinstance(data, dict):
            print(f"Top-level keys: {list(data.keys())}")
            print(f"Total keys: {len(data)}")
            
            # Look for common data container patterns
            common_containers = ['results', 'data', 'items', 'content', 'payload']
            found_containers = [key for key in common_containers if key in data]
            if found_containers:
                print(f"Possible data containers found: {found_containers}")
            
            # Show structure of first few fields
            print("\nFirst few fields (with truncated values):")
            for i, (key, value) in enumerate(list(data.items())[:5]):
                value_type = type(value).__name__
                if isinstance(value, (dict, list)):
                    size_info = f" (length: {len(value)})" if hasattr(value, '__len__') else ""
                    print(f"  {key}: {value_type}{size_info}")
                else:
                    str_value = str(value)
                    display_value = str_value[:50] + "..." if len(str_value) > 50 else str_value
                    print(f"  {key}: {display_value}")
        
        elif isinstance(data, list):
            print(f"Array with {len(data)} items")
            if data:
                first_item = data[0]
                print(f"First item type: {type(first_item).__name__}")
                if isinstance(first_item, dict):
                    print(f"First item keys: {list(first_item.keys())}")
        
        print("\nSample structure (truncated for readability):")
        print(json.dumps(truncate_for_display(data, max_depth), indent=2))
        
    except requests.RequestException as e:
        print(f"Error fetching data: {e}")
    except json.JSONDecodeError as e:
        print(f"Error parsing JSON: {e}")

def truncate_for_display(obj, max_depth=2, current_depth=0):
    """Helper function to truncate nested data for readable display."""
    if current_depth >= max_depth:
        return "..."
    
    if isinstance(obj, dict):
        truncated = {}
        for i, (key, value) in enumerate(obj.items()):
            if i >= 5:
                truncated["..."] = f"({len(obj) - 5} more keys)"
                break
            truncated[key] = truncate_for_display(value, max_depth, current_depth + 1)
        return truncated
    
    elif isinstance(obj, list):
        truncated = []
        for i, item in enumerate(obj[:3]):
            truncated.append(truncate_for_display(item, max_depth, current_depth + 1))
        if len(obj) > 3:
            truncated.append(f"... ({len(obj) - 3} more items)")
        return truncated
    
    else:
        if isinstance(obj, str) and len(obj) > 50:
            return obj[:50] + "..."
        return obj

# Test with different APIs to see variety in structures
print("=== Comparing Different API Response Structures ===\n")

# GitHub API - direct object response
explore_api_structure("https://api.github.com/repos/octocat/Hello-World")
print("\n")

# GitHub Search API - uses 'items' array
explore_api_structure("https://api.github.com/search/repositories?q=python&per_page=2")

=== Comparing Different API Response Structures ===

API Response Analysis for: https://api.github.com/repos/octocat/Hello-World
============================================================
Response type: dict
Top-level keys: ['id', 'node_id', 'name', 'full_name', 'private', 'owner', ...]
Total keys: 79
Possible data containers found: []

First few fields (with truncated values):
  id: 1296269
  node_id: MDEwOlJlcG9zaXRvcnkxMjk2MjY5
  name: Hello-World
  full_name: octocat/Hello-World
  private: False

Sample structure (truncated for readability):
{
  "id": 1296269,
  "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "private": false,
  "...": "(74 more keys)"
}

API Response Analysis for: https://api.github.com/search/repositories?q=python&per_page=2
============================================================
Response type: dict
Top-level keys: ['total_count', 'incomplete_results', 'items']
Total keys: 3
Possible data containers found: ['items']

First few fields (with truncated values):
  total_count: 8937004
  incomplete_results: False
  items: list (length: 2)

Sample structure (truncated for readability):
{
  "total_count": 8937004,
  "incomplete_results": false,
  "items": [
    {
      "id": 54346799,
      "node_id": "MDEwOlJlcG9zaXRvcnk1NDM0Njc5OQ==",
      "name": "public-apis",
      "full_name": "public-apis/public-apis",
      "private": false,
      "...": "(74 more keys)"
    },
    "... (1 more items)"
  ]
}

from typing import Any, List, Optional

COMMON_COLLECTION_KEYS = ["items", "results", "data", "content", "entries", "records"]

def normalize_collection(
    api_response: Any,
    container_hints: Optional[List[str]] = None
) -> List[Any]:
    """
    Return a list of items regardless of response shape:
    - list          → itself
    - dict+wrapper  → wrapper list
    - dict (single) → [dict]
    - other         → []
    """
    # Direct array → pass through
    if isinstance(api_response, list):
        return api_response

    # Not a dict → can't extract anything
    if not isinstance(api_response, dict):
        return []

    # Check for common wrapper keys
    keys = (container_hints or []) + COMMON_COLLECTION_KEYS
    for key in keys:
        val = api_response.get(key)
        if isinstance(val, list):
            return val

    # No wrapper found → treat dict as single item
    return [api_response]

from typing import Any, Dict, List, Tuple, Optional

def extract_items_and_meta(
    api_response: Any,
    container_hints: Optional[List[str]] = None
) -> Tuple[List[Any], Dict[str, Any]]:
    """
    Return (items, metadata) and normalize pagination signals to:
      meta.next_token  (cursor or next URL)
      meta.total       (total results if present)
      meta.page_info   (page/per_page if present)
    """
    meta: Dict[str, Any] = {}

    # Direct list → no metadata
    if isinstance(api_response, list):
        return api_response, meta

    # Not a dict → can't extract anything
    if not isinstance(api_response, dict):
        return [], meta

    # Find the collection container
    keys = (container_hints or []) + COMMON_COLLECTION_KEYS
    container_key = None
    for key in keys:
        if key in api_response and isinstance(api_response[key], list):
            container_key = key
            break

    # Extract items and separate metadata
    if container_key:
        items = api_response[container_key]
        # Everything else is metadata
        meta = {k: v for k, v in api_response.items() if k != container_key}
    else:
        # Single object response
        items = [api_response]
        meta = {}

    # Normalize pagination signals into common format
    meta_obj = meta.get("meta") if isinstance(meta.get("meta"), dict) else {}
    
    # Look for cursor-style pagination
    next_token = (
        meta_obj.get("cursor") or
        meta.get("cursor") or
        None
    )
    
    # Look for URL-style pagination
    if not next_token:
        links = meta.get("links") if isinstance(meta.get("links"), dict) else {}
        next_token = meta.get("nextPage") or links.get("next") or None

    # Extract count and page information
    total = meta.get("total") or meta.get("total_count") or meta_obj.get("total") or None
    page_info = {
        "page": meta.get("page") or meta_obj.get("page"),
        "per_page": meta.get("per_page") or meta_obj.get("per_page")
    }
    
    # Add normalized fields to metadata
    meta_norm = {"next_token": next_token, "total": total, "page_info": page_info}

    return items, {**meta, **meta_norm}

def first_item(
    api_response: Any,
    container_hints: Optional[List[str]] = None
) -> Optional[Dict[str, Any]]:
    """Get the first item (or None) across response variants."""
    items = normalize_collection(api_response, container_hints)
    return items[0] if items else None

import requests

# Fetch both GitHub response types
single_repo = requests.get(
    "https://api.github.com/repos/octocat/Hello-World",
    timeout=10
).json()

search_results = requests.get(
    "https://api.github.com/search/repositories?q=python&per_page=2",
    timeout=10
).json()

print("=== Testing Universal Access Patterns ===\n")

# Test with single repository endpoint
items1, meta1 = extract_items_and_meta(single_repo)
print(f"Single repo endpoint:")
print(f"  Items returned: {len(items1)}")
print(f"  Pagination token: {meta1.get('next_token')}")
print(f"  Total count: {meta1.get('total')}")
print(f"  First item name: {items1[0].get('name')}\n")

# Test with search endpoint  
items2, meta2 = extract_items_and_meta(search_results)
print(f"Search endpoint:")
print(f"  Items returned: {len(items2)}")
print(f"  Pagination token: {meta2.get('next_token')}")
print(f"  Total count: {meta2.get('total'):,}")
print(f"  First item name: {items2[0].get('name')}\n")

# Test convenience helper
first = first_item(single_repo)
print(f"Using first_item() helper:")
print(f"  Repository: {first.get('name')} by {first.get('owner', {}).get('login')}")

=== Testing Universal Access Patterns ===

Single repo endpoint:
  Items returned: 1
  Pagination token: None
  Total count: None
  First item name: Hello-World

Search endpoint:
  Items returned: 2
  Pagination token: None
  Total count: 8,937,004
  First item name: public-apis

Using first_item() helper:
  Repository: Hello-World by octocat

from typing import Any, Dict, List

def safe_get(obj: Any, path: str, default=None):
    """
    Dot-path lookup: 'owner.login' → obj['owner']['login'] if present.
    Returns default if any part of the path doesn't exist.
    """
    cur = obj
    for part in path.split("."):
        # Check if we can traverse this level
        if not isinstance(cur, dict) or part not in cur:
            return default
        cur = cur[part]
    return cur

def try_fields(d: Dict[str, Any], names: List[str], default=None):
    """
    Return first present/non-empty field from a list of candidates.
    Useful when different APIs use different field names for the same data.
    """
    for name in names:
        val = d.get(name)
        if val not in (None, ""):
            return val
    return default

from api_helpers import safe_get, extract_items_and_meta

# Now use them in your main script
owner = safe_get(repo, "owner.login", "Unknown")

import requests

# Fetch repository data
resp = requests.get("https://api.github.com/repos/octocat/Hello-World", timeout=10)
resp.raise_for_status()
repo = resp.json()

# Safe navigation using utility from Section 4
name = repo.get("name", "Unknown")
owner_login = safe_get(repo, "owner.login", "Unknown")
owner_url = safe_get(repo, "owner.html_url", "")
language = repo.get("language") or "Not specified"
stars = repo.get("stargazers_count", 0)

print(f"Repository: {name}")
print(f"Owner: {owner_login}")
print(f"Profile: {owner_url}")
print(f"Language: {language}")
print(f"Stars: {stars:,}")

Repository: Hello-World
Owner: octocat
Profile: https://github.com/octocat
Language: Not specified
Stars: 3,126

{
  "result": {
    "name": "Google Building 40",
    "geometry": {
      "location": {"lat": 37.4224764, "lng": -122.0842499},
      "viewport": {
        "northeast": { "lat": 37.4238, "lng": -122.0829 },
        "southwest": { "lat": 37.4211, "lng": -122.0856 }
      }
    },
    "opening_hours": {
      "periods": [
        { "open": {"day": 1, "time": "0900"}, "close": {"day": 1, "time": "1800"} }
      ],
      "weekday_text": ["Monday: 9:00 AM – 6:00 PM"]
    },
    "reviews": [
      { "author_name": "John Smith", "rating": 5, "text": "Great place!" }
    ]
  }
}

# Assume 'data' contains the Google Places response above

# Extract top-level result container
place = data.get("result", {})

# Basic fields (shallow)
name = place.get("name", "Unknown")

# Deep nested coordinates (3 levels)
lat = safe_get(place, "geometry.location.lat")
lng = safe_get(place, "geometry.location.lng")

# Optional opening hours (navigate to array, then first item)
periods = safe_get(place, "opening_hours.periods", [])
if periods:
    first_period = periods[0]
    open_time = safe_get(first_period, "open.time")
    close_time = safe_get(first_period, "close.time")
else:
    open_time = close_time = None

# Optional reviews array (check existence before indexing)
reviews = place.get("reviews", [])
if reviews:
    first_review = reviews[0]
    review_author = first_review.get("author_name", "Anonymous")
    review_text = first_review.get("text", "No review text")
else:
    review_author = review_text = None

# Display extracted data
print(f"Place: {name}")
print(f"Location: ({lat}, {lng})")
if open_time and close_time:
    print(f"Hours: Opens {open_time}, closes {close_time}")
if review_author:
    print(f"Review by {review_author}: {review_text}")

Place: Google Building 40
Location: (37.4224764, -122.0842499)
Hours: Opens 0900, closes 1800
Review by John Smith: Great place!

import requests

# Fetch GitHub repository search results
resp = requests.get(
    "https://api.github.com/search/repositories?q=python+language:python&sort=stars&order=desc&per_page=5",
    timeout=10
)
resp.raise_for_status()
search = resp.json()

# Use Section 4's extractor to normalize container and metadata
items, meta = extract_items_and_meta(search)

print(f"Total repositories found: {meta.get('total', 0):,}\n")

# Process each complex item in the array
for i, repo in enumerate(items, start=1):
    # Extract fields with safe navigation
    name = repo.get("name", "Unknown")
    owner = safe_get(repo, "owner.login", "Unknown")
    stars = repo.get("stargazers_count", 0)
    
    # Handle optional nested license object
    license_name = safe_get(repo, "license.name", "Not specified")
    
    # Safely truncate optional description
    description = repo.get("description") or ""
    desc_preview = description[:80] + "..." if len(description) > 80 else description
    
    # Required URL field
    url = repo.get("html_url", "")

    # Display formatted output
    print(f"{i}. {name} by {owner}")
    print(f"   ⭐ {stars:,} stars")
    if desc_preview:
        print(f"   📄 {desc_preview}")
    print(f"   📋 License: {license_name}")
    print(f"   🔗 {url}\n")

Total repositories found: 1,247,563

1. awesome-python by vinta
   ⭐ 185,450 stars
   📄 A curated list of awesome Python frameworks, libraries, software and reso...
   📋 License: Other
   🔗 https://github.com/vinta/awesome-python

2. public-apis by public-apis
   ⭐ 294,142 stars
   📄 A collective list of free APIs for use in software and web development
   📋 License: MIT License
   🔗 https://github.com/public-apis/public-apis

def extract_repository_details(api_response):
    """
    Extract repository information from any GitHub endpoint response.
    Handles: single repos, search results, nested owner data, optional fields.
    """
    # Normalize container (might be direct object, 'items' array, etc.)
    items, meta = extract_items_and_meta(api_response)
    
    if not items:
        return None, meta
    
    # Get first repository
    repo = items[0]
    
    # Extract with defensive navigation
    details = {
        # Basic fields
        "name": repo.get("name", "Unknown"),
        "full_name": repo.get("full_name", "Unknown"),
        "description": repo.get("description") or "No description",
        
        # Nested owner data (2 levels deep)
        "owner_login": safe_get(repo, "owner.login", "Unknown"),
        "owner_url": safe_get(repo, "owner.html_url", ""),
        "owner_type": safe_get(repo, "owner.type", "Unknown"),
        
        # Metrics
        "stars": repo.get("stargazers_count", 0),
        "forks": repo.get("forks_count", 0),
        "watchers": repo.get("watchers_count", 0),
        "open_issues": repo.get("open_issues_count", 0),
        
        # Optional nested license
        "license": safe_get(repo, "license.name", "Not specified"),
        
        # Optional language
        "language": repo.get("language") or "Not specified",
        
        # Timestamps
        "created": repo.get("created_at", "Unknown"),
        "updated": repo.get("updated_at", "Unknown"),
        
        # URLs
        "repo_url": repo.get("html_url", ""),
        "api_url": repo.get("url", ""),
        
        # Flags
        "private": bool(repo.get("private", False)),
        "archived": bool(repo.get("archived", False)),
    }
    
    return details, meta

# Test with both endpoint types
print("=== Single Repository ===")
single = requests.get("https://api.github.com/repos/octocat/Hello-World", timeout=10).json()
repo_info, _ = extract_repository_details(single)
print(f"{repo_info['name']} by {repo_info['owner_login']}")
print(f"⭐ {repo_info['stars']:,} stars | Language: {repo_info['language']}")
print(f"License: {repo_info['license']}\n")

print("=== Search Results ===")
search = requests.get("https://api.github.com/search/repositories?q=python&per_page=1", timeout=10).json()
repo_info, meta = extract_repository_details(search)
print(f"{repo_info['name']} by {repo_info['owner_login']}")
print(f"⭐ {repo_info['stars']:,} stars | Language: {repo_info['language']}")
print(f"Total matching repos: {meta.get('total', 0):,}")

=== Single Repository ===
Hello-World by octocat
⭐ 3,126 stars | Language: Not specified
License: Not specified

=== Search Results ===
public-apis by public-apis
⭐ 294,142 stars | Language: Python
Total matching repos: 8,937,004

from typing import Any, Dict, Optional

class MissingRequired(Exception):
    pass

def require(d: Dict[str, Any], name: str) -> Any:
    """Return d[name] or raise a clear error."""
    if not isinstance(d, dict) or name not in d or d[name] in (None, ""):
        raise MissingRequired(f"Missing required field: {name}")
    return d[name]

def default(d: Dict[str, Any], name: str, fallback: Any):
    """Return d.get(name) with an explicit default."""
    v = d.get(name)
    return fallback if v in (None, "") else v

def safe_get(obj: Any, path: str, default_value=None):
    """Dot-path lookup: 'a.b.c' with a safe default."""
    cur = obj
    for part in path.split("."):
        if not isinstance(cur, dict) or part not in cur:
            return default_value
        cur = cur[part]
    return cur

# Example usage
order = {"id": "ORD-123", "customer": {"email": "alice@example.com"}}
order_id = require(order, "id")                         # must exist
email    = safe_get(order, "customer.email", "Unknown") # optional
notes    = default(order, "notes", "")                  # optional string

def extract_order_minimal(obj: Dict[str, Any]) -> Dict[str, Any]:
    try:
        # Required
        oid = require(obj, "id")

        # Recommended / Optional
        email = safe_get(obj, "customer.email", "Unknown")
        total = default(obj, "total", 0.0)
        discount = default(obj, "discount", None)

        return {
            "id": oid,
            "email": email,
            "total": float(total) if total is not None else None,
            "discount": discount,
        }
    except MissingRequired as e:
        return {"error": str(e), "_raw_id": obj.get("id")}

{'id': 'ORD-123', 'email': 'alice@example.com', 'total': 129.5, 'discount': None}
{'id': 'ORD-124', 'email': 'Unknown', 'total': 0.0, 'discount': {'type': 'percent', 'value': 10}}
{'error': 'Missing required field: id', '_raw_id': None}

def normalize_order_v1(raw: Dict[str, Any]) -> Dict[str, Any]:
    """
    Version 1: Field mapping + type coercion only.
    Handles: id/order_id, total/amount, currency naming.
    """
    # PATTERN 1: FIELD MAPPING
    # Try both possible field names, normalize to 'id'
    order_id_raw = try_fields(raw, ["id", "order_id"])
    order_id = str(order_id_raw)  # Ensure string type
    
    # Ensure ID has proper prefix
    if order_id and not order_id.startswith("ORD-"):
        order_id = f"ORD-{order_id}"
    
    # PATTERN 2: TYPE COERCION
    # Convert string or number to float
    total_raw = try_fields(raw, ["total", "amount"])
    total = float(total_raw) if total_raw is not None else 0.0
    
    # Map currency field names and normalize to uppercase
    currency = try_fields(raw, ["currency", "currency_code"], "USD")
    currency = currency.upper() if currency else "USD"
    
    return {
        "id": order_id,
        "total": total,
        "currency": currency,
    }

# Variant A excerpt
variant_a = {
    "id": "ORD-91352",
    "total": "129.50",
    "currency": "EUR"
}

# Variant B excerpt
variant_b = {
    "order_id": 91352,
    "amount": 129.5,
    "currency_code": "EUR"
}

print("=== Version 1: Field Mapping + Type Coercion ===")
print("Variant A:", normalize_order_v1(variant_a))
print("Variant B:", normalize_order_v1(variant_b))
print("Same structure?", normalize_order_v1(variant_a).keys() == normalize_order_v1(variant_b).keys())

=== Version 1: Field Mapping + Type Coercion ===
Variant A: {'id': 'ORD-91352', 'total': 129.5, 'currency': 'EUR'}
Variant B: {'id': 'ORD-91352', 'total': 129.5, 'currency': 'EUR'}
Same structure? True

from datetime import datetime, timezone

def normalize_order_v2(raw: Dict[str, Any]) -> Dict[str, Any]:
    """
    Version 2: Adds time unification and enum harmonization.
    Handles: created_at/ts, status/state.
    """
    # PATTERNS 1-2: Field mapping + type coercion (from v1)
    order_id_raw = try_fields(raw, ["id", "order_id"])
    order_id = str(order_id_raw)
    if order_id and not order_id.startswith("ORD-"):
        order_id = f"ORD-{order_id}"
    
    total_raw = try_fields(raw, ["total", "amount"])
    total = float(total_raw) if total_raw is not None else 0.0
    
    currency = try_fields(raw, ["currency", "currency_code"], "USD")
    currency = currency.upper() if currency else "USD"
    
    # ── NEW IN v2 ────────────────────────────────────────────────────────────
    # PATTERN 3: TIME UNIFICATION
    # Convert unix timestamp to ISO 8601, or keep ISO string
    created_raw = try_fields(raw, ["created_at", "ts"])
    if isinstance(created_raw, (int, float)):
        # Unix timestamp → ISO 8601
        created_at = datetime.fromtimestamp(created_raw, tz=timezone.utc).isoformat()
    else:
        created_at = created_raw  # Already ISO string
    
    # PATTERN 4: ENUM HARMONIZATION
    # Normalize status to lowercase and validate
    status_raw = try_fields(raw, ["status", "state"], "pending")
    status = status_raw.lower() if status_raw else "pending"
    
    # Validate against allowed values
    allowed_statuses = {"pending", "processing", "shipped", "delivered", "cancelled"}
    if status not in allowed_statuses:
        status = "pending"  # Safe default
    
    return {
        "id": order_id,
        "created_at": created_at,
        "total": total,
        "currency": currency,
        "status": status,
    }

variant_a = {
    "id": "ORD-91352",
    "created_at": "2025-06-18T14:22:31Z",
    "total": "129.50",
    "currency": "EUR",
    "status": "shipped"
}

variant_b = {
    "order_id": 91352,
    "ts": 1718710951,
    "amount": 129.5,
    "currency_code": "EUR",
    "state": "Shipped"
}

print("=== Version 2: Added Time + Enum Patterns ===")
result_a = normalize_order_v2(variant_a)
result_b = normalize_order_v2(variant_b)

print(f"Variant A timestamp: {result_a['created_at']}")
print(f"Variant B timestamp: {result_b['created_at']}")
print(f"Variant A status: {result_a['status']}")
print(f"Variant B status: {result_b['status']}")
print(f"Both timestamps are ISO strings: {isinstance(result_a['created_at'], str) and isinstance(result_b['created_at'], str)}")
print(f"Status normalized to lowercase: {result_a['status'] == result_b['status'] == 'shipped'}")

=== Version 2: Added Time + Enum Patterns ===
Variant A timestamp: 2025-06-18T14:22:31Z
Variant B timestamp: 2025-06-18T14:22:31+00:00
Variant A status: shipped
Variant B status: shipped
Both timestamps are ISO strings: True
Status normalized to lowercase: True

def normalize_order_v3(raw: Dict[str, Any]) -> Dict[str, Any]:
    """
    Version 3: Adds customer embedding and item normalization.
    Handles: customer object vs customer_id, items/line_items.
    """
    # PATTERNS 1-4: (same as v2)
    order_id_raw = try_fields(raw, ["id", "order_id"])
    order_id = str(order_id_raw)
    if order_id and not order_id.startswith("ORD-"):
        order_id = f"ORD-{order_id}"
    
    total_raw = try_fields(raw, ["total", "amount"])
    total = float(total_raw) if total_raw is not None else 0.0
    
    currency = try_fields(raw, ["currency", "currency_code"], "USD")
    currency = currency.upper() if currency else "USD"
    
    created_raw = try_fields(raw, ["created_at", "ts"])
    if isinstance(created_raw, (int, float)):
        created_at = datetime.fromtimestamp(created_raw, tz=timezone.utc).isoformat()
    else:
        created_at = created_raw
    
    status_raw = try_fields(raw, ["status", "state"], "pending")
    status = status_raw.lower() if status_raw else "pending"
    allowed_statuses = {"pending", "processing", "shipped", "delivered", "cancelled"}
    if status not in allowed_statuses:
        status = "pending"
    
    # ── NEW IN v3 ────────────────────────────────────────────────────────────
    # PATTERN 5: JOIN STRATEGY (Customer Embedding)
    # Handle embedded object vs reference ID
    customer_obj = raw.get("customer")
    if isinstance(customer_obj, dict):
        # Already embedded - extract fields
        customer = {
            "id": customer_obj.get("id"),
            "email": customer_obj.get("email", "Unknown")
        }
    else:
        # Only have customer_id reference - create minimal object
        customer_id = raw.get("customer_id")
        customer = {
            "id": int(customer_id) if customer_id else None,
            "email": "Unknown"
        }
    
    # PATTERN 8: ARRAY PROCESSING (Item Normalization)
    # Handle items vs line_items with different nesting
    raw_items = try_fields(raw, ["items", "line_items"], [])
    items = []
    
    for item in raw_items:
        # SKU might be nested in product.sku or flat
        sku = safe_get(item, "product.sku") or item.get("sku")
        
        # Quantity: qty vs quantity, string vs int
        qty_raw = try_fields(item, ["qty", "quantity"], 0)
        qty = int(qty_raw) if qty_raw else 0
        
        # Price: price vs unit_price, string vs number
        price_raw = try_fields(item, ["price", "unit_price"], 0)
        price = float(price_raw) if price_raw else 0.0
        
        items.append({
            "sku": sku,
            "qty": qty,
            "price": price
        })
    
    return {
        "id": order_id,
        "created_at": created_at,
        "total": total,
        "currency": currency,
        "customer": customer,
        "items": items,
        "status": status,
    }

variant_a = {
    "id": "ORD-91352",
    "created_at": "2025-06-18T14:22:31Z",
    "total": "129.50",
    "currency": "EUR",
    "customer": {"id": 7712, "email": "alice@example.com"},
    "items": [
        {"sku": "P-001", "qty": 2, "price": 39.75},
        {"sku": "P-009", "qty": 1, "price": 50.00}
    ],
    "status": "shipped"
}

variant_b = {
    "order_id": 91352,
    "ts": 1718710951,
    "amount": 129.5,
    "currency_code": "EUR",
    "customer_id": "7712",
    "line_items": [
        {"product": {"sku": "P-001"}, "quantity": "2", "unit_price": "39.75"},
        {"product": {"sku": "P-009"}, "quantity": 1, "unit_price": 50}
    ],
    "state": "Shipped"
}

print("=== Version 3: Added Customer + Items ===")
result_a = normalize_order_v3(variant_a)
result_b = normalize_order_v3(variant_b)

print(f"Variant A customer: {result_a['customer']}")
print(f"Variant B customer: {result_b['customer']}")
print(f"Variant A items count: {len(result_a['items'])}")
print(f"Variant B items count: {len(result_b['items'])}")
print(f"First item from A: {result_a['items'][0]}")
print(f"First item from B: {result_b['items'][0]}")

=== Version 3: Added Customer + Items ===
Variant A customer: {'id': 7712, 'email': 'alice@example.com'}
Variant B customer: {'id': 7712, 'email': 'Unknown'}
Variant A items count: 2
Variant B items count: 2
First item from A: {'sku': 'P-001', 'qty': 2, 'price': 39.75}
First item from B: {'sku': 'P-001', 'qty': 2, 'price': 39.75}

def normalize_order(raw: Dict[str, Any]) -> Dict[str, Any]:
    """
    Complete normalizer implementing all eight transformation patterns.
    Transforms both order variants into identical canonical shape.
    """
    # PATTERN 1: FIELD MAPPING - Rename to canonical names
    order_id_raw = try_fields(raw, ["id", "order_id"])
    order_id = str(order_id_raw)
    if order_id and not order_id.startswith("ORD-"):
        order_id = f"ORD-{order_id}"
    
    # PATTERN 2: TYPE COERCION - Ensure consistent types
    total_raw = try_fields(raw, ["total", "amount"])
    total = float(total_raw) if total_raw is not None else 0.0
    
    currency = try_fields(raw, ["currency", "currency_code"], "USD")
    currency = currency.upper() if currency else "USD"
    
    # PATTERN 3: TIME UNIFICATION - Normalize to ISO 8601
    created_raw = try_fields(raw, ["created_at", "ts"])
    if isinstance(created_raw, (int, float)):
        created_at = datetime.fromtimestamp(created_raw, tz=timezone.utc).isoformat()
    else:
        created_at = created_raw
    
    # PATTERN 4: ENUM HARMONIZATION - Standardize status values
    status_raw = try_fields(raw, ["status", "state"], "pending")
    status = status_raw.lower() if status_raw else "pending"
    allowed_statuses = {"pending", "processing", "shipped", "delivered", "cancelled"}
    if status not in allowed_statuses:
        status = "pending"
    
    # PATTERN 5: JOIN STRATEGY - Embed customer data
    customer_obj = raw.get("customer")
    if isinstance(customer_obj, dict):
        customer = {
            "id": customer_obj.get("id"),
            "email": customer_obj.get("email", "Unknown")
        }
    else:
        customer_id = raw.get("customer_id")
        customer = {
            "id": int(customer_id) if customer_id else None,
            "email": "Unknown"
        }
    
    # PATTERN 8: ARRAY PROCESSING - Normalize item collections
    raw_items = try_fields(raw, ["items", "line_items"], [])
    items = []
    for item in raw_items:
        sku = safe_get(item, "product.sku") or item.get("sku")
        qty_raw = try_fields(item, ["qty", "quantity"], 0)
        qty = int(qty_raw) if qty_raw else 0
        price_raw = try_fields(item, ["price", "unit_price"], 0)
        price = float(price_raw) if price_raw else 0.0
        items.append({"sku": sku, "qty": qty, "price": price})
    
    # PATTERN 7: OPTIONAL FIELD HANDLING - Discount/promo normalization
    discount = None
    if raw.get("discount") is not None:
        discount = raw["discount"]
    elif raw.get("promo"):
        promo = raw["promo"]
        value_str = promo.get("value", "0")
        # Parse "10%" format to structured object
        if isinstance(value_str, str) and value_str.endswith("%"):
            discount = {
                "type": "percent",
                "value": int(value_str.rstrip("%"))
            }
        else:
            discount = {
                "type": "fixed",
                "value": float(value_str)
            }
    
    return {
        "id": order_id,
        "created_at": created_at,
        "total": total,
        "currency": currency,
        "customer": customer,
        "items": items,
        "discount": discount,
        "status": status
    }


def extract_orders_with_pagination(api_response: Dict[str, Any]) -> tuple:
    """
    Extract orders from either variant and return (orders, next_token).
    Implements PATTERN 6: PAGINATION ADAPTER.
    """
    # Find the orders array (handles different wrapper patterns)
    orders_raw = (
        safe_get(api_response, "data.orders") or
        api_response.get("orders") or
        (api_response if isinstance(api_response, list) else [])
    )
    
    # Normalize each order
    orders = [normalize_order(o) for o in orders_raw]
    
    # PATTERN 6: PAGINATION ADAPTER - Unify cursor vs nextPage
    next_token = (
        safe_get(api_response, "meta.cursor") or
        api_response.get("nextPage")
    )
    
    return orders, next_token

# Variant A: Modern endpoint (complete)
variant_a = {
    "data": {
        "orders": [{
            "id": "ORD-91352",
            "created_at": "2025-06-18T14:22:31Z",
            "total": "129.50",
            "currency": "EUR",
            "customer": {"id": 7712, "email": "alice@example.com"},
            "items": [
                {"sku": "P-001", "qty": 2, "price": 39.75},
                {"sku": "P-009", "qty": 1, "price": 50.00}
            ],
            "discount": None,
            "status": "shipped"
        }]
    },
    "meta": {"cursor": "eyJwYWdlIjoyfQ=="}
}

# Variant B: Legacy/partner feed (complete)
variant_b = {
    "orders": [{
        "order_id": 91352,
        "ts": 1718710951,
        "amount": 129.5,
        "currency_code": "EUR",
        "customer_id": "7712",
        "line_items": [
            {"product": {"sku": "P-001"}, "quantity": "2", "unit_price": "39.75"},
            {"product": {"sku": "P-009"}, "quantity": 1, "unit_price": 50}
        ],
        "promo": {"code": "SUMMER", "value": "10%"},
        "state": "Shipped"
    }],
    "nextPage": "/orders?page=2"
}

# Process both variants
print("=== Complete Normalizer Test ===\n")

print("--- Variant A (Modern Endpoint) ---")
orders_a, next_a = extract_orders_with_pagination(variant_a)
for order in orders_a:
    print(f"Order {order['id']}: ${order['total']:.2f} {order['currency']}")
    print(f"  Status: {order['status']}")
    print(f"  Customer: {order['customer']['email']}")
    print(f"  Items: {len(order['items'])}")
    print(f"  Discount: {order['discount']}")
print(f"Next page token: {next_a}\n")

print("--- Variant B (Legacy Feed) ---")
orders_b, next_b = extract_orders_with_pagination(variant_b)
for order in orders_b:
    print(f"Order {order['id']}: ${order['total']:.2f} {order['currency']}")
    print(f"  Status: {order['status']}")
    print(f"  Customer: {order['customer']['email']}")
    print(f"  Items: {len(order['items'])}")
    print(f"  Discount: {order['discount']}")
print(f"Next page token: {next_b}\n")

print("--- Verification ---")
print(f"Same canonical structure: {orders_a[0].keys() == orders_b[0].keys()}")
print(f"Same ID format: {orders_a[0]['id'] == orders_b[0]['id']}")
print(f"Same total: {orders_a[0]['total'] == orders_b[0]['total']}")
print(f"Same status: {orders_a[0]['status'] == orders_b[0]['status']}")
print(f"Same items structure: {orders_a[0]['items'][0].keys() == orders_b[0]['items'][0].keys()}")

=== Complete Normalizer Test ===

--- Variant A (Modern Endpoint) ---
Order ORD-91352: $129.50 EUR
  Status: shipped
  Customer: alice@example.com
  Items: 2
  Discount: None
Next page token: eyJwYWdlIjoyfQ==

--- Variant B (Legacy Feed) ---
Order ORD-91352: $129.50 EUR
  Status: shipped
  Customer: Unknown
  Items: 2
  Discount: {'type': 'percent', 'value': 10}
Next page token: /orders?page=2

--- Verification ---
Same canonical structure: True
Same ID format: True
Same total: True
Same status: True
Same items structure: True