fix: Apple audiobook prices + honest format labels on scan

- Query iTunes entity=ebook and entity=audiobook for Apple Books format_prices (R-PP-014)
- Stop inventing Hardcover for ThriftBooks/AbeBooks/Bookshop single prices; use JSON-LD bookFormat when present, else list_price only (R-PP-010)
- Keep Kobo labeled as eBook (digital-only)
- Bump presence scan cache to v12; 24 unit tests pass

Co-authored-by: Cursor <cursoragent@cursor.com>

.agent/PLATFORM_PRICING_RULES.md

@@ -107,10 +107,11 @@ Amazon HTML: US-locale headers + cookie (`i18n-prefs=USD`) to avoid PKR/wrong cu
 - **R-185:** Missing price must not fail presence scan (fail open)
 - **R-186:** Amazon price fetch must use US-locale headers
 - **R-187:** Platform scan cache key version bumped when price/credential logic changes materially
-- **R-PP-010:** Scan enrichment MUST write `format_prices` when parsers find ≥1 format; MUST NOT wipe a richer existing map with a thinner scan result
+- **R-PP-010:** Scan enrichment MUST write `format_prices` when parsers find ≥1 format; MUST NOT wipe a richer existing map with a thinner scan result. Single-price fallback MUST NOT invent a binding label — Kobo may use eBook; ThriftBooks / AbeBooks / Bookshop use JSON-LD `bookFormat` when present, otherwise leave `format_prices` empty and keep `list_price` only.
 - **R-PP-011:** `fetch_listing_format_prices` fetches HTML exactly once and passes the raw HTML to format-price parsers — no double HTTP round-trips per listing
 - **R-PP-012:** Discovery platforms (goodreads, open_library, google_books) return `format_prices: {}` from enrichment; their single `list_price` is preserved as-is
 - **R-PP-013:** `fetch_listing_price` remains a backward-compatible thin wrapper over `fetch_listing_format_prices` returning only the primary formatted string
+- **R-PP-014:** Apple Books enrichment MUST query iTunes `entity=ebook` and `entity=audiobook` so both digital formats can populate `format_prices` when available
 
 ## 11. File map
 

app/services/platform_presence.py

@@ -39,7 +39,7 @@ logger = structlog.get_logger(__name__)
 
 _SCAN_TIMEOUT = 10.0
 _MAX_CONCURRENT = 6
-_SCAN_CACHE_PREFIX = "platform_scan:v11:"
+_SCAN_CACHE_PREFIX = "platform_scan:v12:"
 _SCAN_CACHE_TTL = 21_600  # 6h
 
 Status = Literal["verified", "likely", "not_found", "checking", "error", "skipped"]

app/services/platform_pricing.py

@@ -18,7 +18,9 @@ from app.services.book_url_scraper import (
     _browser_headers,
     _extract_amazon_all_format_prices,
     _extract_bn_all_format_prices,
+    _extract_json_ld,
     _google_books_api_params,
+    _normalize_retail_format_label,
     _parse_amazon_html,
     _score_itunes_item,
 )
@@ -460,55 +462,9 @@ async def fetch_listing_format_prices(
         fmt_map: dict[str, str] = {}
         return FormatPriceHit(format_prices=fmt_map, formatted="Free", currency="USD")
 
-    # --- Apple Books via iTunes API (already multi-format aware) ---
+    # --- Apple Books via iTunes API (eBook + Audiobook) ---
     if platform_id == "apple_books":
-        book_id = _apple_book_id(listing_url)
-        title = (ctx.title if ctx else None) or ""
-        author = (ctx.author if ctx else None) or ""
-        fmt_map = {}
-        primary_fmt = ""
-        currency = "USD"
-        try:
-            for params in (
-                *(([{"id": book_id, "entity": "ebook"}] if book_id else [])),
-                {"term": f"{title} {author}".strip(), "entity": "ebook", "limit": "5", "country": "US"} if title else None,
-            ):
-                if params is None:
-                    continue
-                r = await client.get(
-                    "https://itunes.apple.com/" + ("lookup" if "id" in params else "search"),
-                    params=params,
-                    timeout=_API_TIMEOUT,
-                )
-                if r.status_code != 200:
-                    continue
-                results = r.json().get("results") or []
-                for item in results:
-                    if not _score_itunes_item(item, title, author):
-                        continue
-                    raw_price = item.get("formattedPrice") or item.get("trackPrice")
-                    if raw_price is None:
-                        continue
-                    amt_str = str(raw_price)
-                    m = re.search(r"([0-9]+(?:\.[0-9]{2})?)", amt_str.replace(",", ""))
-                    if m:
-                        amount = float(m.group(1))
-                        currency = str(item.get("currency") or "USD").upper()
-                        formatted_str = format_price(amount, currency)
-                        fmt_map["eBook"] = formatted_str
-                        primary_fmt = formatted_str
-                        break
-                if fmt_map:
-                    break
-        except Exception as exc:
-            logger.debug("Apple format price fetch failed", error=str(exc)[:120])
-        if not fmt_map:
-            return None
-        return FormatPriceHit(
-            format_prices=canonical_format_prices(fmt_map, platform_id),
-            formatted=primary_fmt,
-            currency=currency,
-        )
+        return await _fetch_apple_format_prices(client, listing_url, ctx)
 
     # --- Credential-based platforms ---
     if credential is not None:
@@ -555,13 +511,22 @@ async def fetch_listing_format_prices(
                         currency="USD",
                     )
 
-            # Fallback to single price
+            # Fallback to single price — label only when binding is known (R-PP-010)
             single = extract_price_from_html(platform_id, html)
             if single:
-                fmt_key = "eBook" if platform_id in {"kobo"} else "Hardcover"
-                norm = canonical_format_prices({fmt_key: single.formatted}, platform_id)
+                fmt_key = _single_price_format_key(platform_id, html)
+                if fmt_key:
+                    norm = canonical_format_prices(
+                        {fmt_key: single.formatted}, platform_id,
+                    )
+                    return FormatPriceHit(
+                        format_prices=norm,
+                        formatted=single.formatted,
+                        currency=single.currency,
+                    )
+                # Unknown binding: keep list_price only, do not invent a format label
                 return FormatPriceHit(
-                    format_prices=norm,
+                    format_prices={},
                     formatted=single.formatted,
                     currency=single.currency,
                 )
@@ -572,3 +537,139 @@ async def fetch_listing_format_prices(
                 error=str(exc)[:120],
             )
     return None
+
+
+def _itunes_price_from_item(item: dict) -> tuple[str, str] | None:
+    """Return (formatted_price, currency) from an iTunes lookup/search item."""
+    raw_price = item.get("formattedPrice")
+    if raw_price:
+        m = re.search(r"([0-9]+(?:\.[0-9]{2})?)", str(raw_price).replace(",", ""))
+        if m:
+            currency = str(item.get("currency") or "USD").upper()
+            return format_price(float(m.group(1)), currency), currency
+    if item.get("trackPrice") is not None:
+        try:
+            amount = float(item["trackPrice"])
+        except (TypeError, ValueError):
+            return None
+        currency = str(item.get("currency") or "USD").upper()
+        return format_price(amount, currency), currency
+    return None
+
+
+async def _fetch_apple_format_prices(
+    client: httpx.AsyncClient,
+    listing_url: str,
+    ctx: PriceContext | None,
+) -> FormatPriceHit | None:
+    """Fetch eBook and Audiobook prices from iTunes (free API)."""
+    from app.services.platform_catalog import canonical_format_prices, primary_list_price
+
+    book_id = _apple_book_id(listing_url)
+    title = (ctx.title if ctx else None) or ""
+    author = (ctx.author if ctx else None) or ""
+    fmt_map: dict[str, str] = {}
+    currency = "USD"
+
+    async def _query(entity: str, format_key: str) -> None:
+        nonlocal currency
+        if format_key in fmt_map:
+            return
+        queries: list[tuple[str, dict]] = []
+        if book_id:
+            queries.append(("lookup", {"id": book_id, "entity": entity}))
+        if title:
+            queries.append((
+                "search",
+                {
+                    "term": f"{title} {author}".strip(),
+                    "entity": entity,
+                    "limit": "8",
+                    "country": "US",
+                },
+            ))
+        for endpoint, params in queries:
+            try:
+                r = await client.get(
+                    f"https://itunes.apple.com/{endpoint}",
+                    params=params,
+                    timeout=_API_TIMEOUT,
+                )
+                if r.status_code != 200:
+                    continue
+                results = r.json().get("results") or []
+                if not results:
+                    continue
+                if endpoint == "lookup":
+                    candidates = results
+                else:
+                    scored = [
+                        (item, _score_itunes_item(item, title, author))
+                        for item in results
+                    ]
+                    scored = [(i, s) for i, s in scored if s >= 4.0]
+                    if not scored:
+                        continue
+                    candidates = [max(scored, key=lambda x: x[1])[0]]
+                for item in candidates:
+                    hit = _itunes_price_from_item(item)
+                    if hit:
+                        formatted_str, currency = hit
+                        fmt_map[format_key] = formatted_str
+                        return
+            except Exception as exc:
+                logger.debug(
+                    "Apple format price fetch failed",
+                    entity=entity,
+                    error=str(exc)[:120],
+                )
+
+    try:
+        await _query("ebook", "eBook")
+        await _query("audiobook", "Audiobook")
+    except Exception as exc:
+        logger.debug("Apple format price fetch failed", error=str(exc)[:120])
+
+    if not fmt_map:
+        return None
+    norm = canonical_format_prices(fmt_map, "apple_books")
+    primary = primary_list_price(norm, "", next(iter(fmt_map.values()), ""))
+    return FormatPriceHit(
+        format_prices=norm,
+        formatted=primary or next(iter(fmt_map.values())),
+        currency=currency,
+    )
+
+
+def _book_format_from_json_ld(html: str) -> str:
+    """Return a canonical format label from schema.org bookFormat/binding, or ''."""
+    for block in _extract_json_ld(html):
+        raw = str(block.get("bookFormat") or block.get("binding") or "").strip()
+        if not raw:
+            continue
+        # schema.org URLs like https://schema.org/Hardcover
+        if "/" in raw:
+            raw = raw.rsplit("/", 1)[-1]
+        label = _normalize_retail_format_label(raw)
+        if label in {
+            "Hardcover", "Paperback", "Mass Market Paperback", "eBook", "Audiobook",
+        }:
+            return label
+    return ""
+
+
+def _single_price_format_key(platform_id: str, html: str) -> str:
+    """Choose a format label for a single list price, or '' if unknown.
+
+    Never invent Hardcover for multi-binding used-book stores (R-PP-010).
+    Kobo is digital-only so eBook is safe. JSON-LD bookFormat wins when present.
+    """
+    if platform_id == "kobo":
+        return "eBook"
+    detected = _book_format_from_json_ld(html)
+    if detected:
+        return detected
+    # Multi-binding retailers: omit label rather than guessing Hardcover
+    if platform_id in {"thriftbooks", "abebooks", "bookshop"}:
+        return ""
+    return detected

tests/unit/test_platform_pricing.py

@@ -7,6 +7,8 @@ import pytest
 from app.services.platform_pricing import (
     FormatPriceHit,
     PriceContext,
+    _book_format_from_json_ld,
+    _single_price_format_key,
     extract_price_from_html,
     fetch_apple_books_price,
     fetch_google_books_price,
@@ -158,6 +160,128 @@ class TestFetchListingFormatPrices:
         assert hit is not None
         assert hit.formatted == "Free"
 
+    @pytest.mark.asyncio
+    async def test_apple_returns_ebook_and_audiobook(self):
+        """iTunes ebook + audiobook entities both populate format_prices."""
+        ebook_resp = MagicMock()
+        ebook_resp.status_code = 200
+        ebook_resp.json = MagicMock(return_value={
+            "results": [{
+                "trackName": "All We Say",
+                "artistName": "Test Author",
+                "formattedPrice": "$14.99",
+                "currency": "USD",
+                "description": "A long enough description for scoring boost " * 3,
+            }],
+        })
+        audio_resp = MagicMock()
+        audio_resp.status_code = 200
+        audio_resp.json = MagicMock(return_value={
+            "results": [{
+                "trackName": "All We Say",
+                "artistName": "Test Author",
+                "formattedPrice": "$28.00",
+                "currency": "USD",
+                "description": "A long enough description for scoring boost " * 3,
+            }],
+        })
+        client = AsyncMock()
+
+        async def _get(url, params=None, timeout=None):
+            entity = (params or {}).get("entity", "")
+            return audio_resp if entity == "audiobook" else ebook_resp
+
+        client.get = AsyncMock(side_effect=_get)
+        ctx = PriceContext(title="All We Say", author="Test Author")
+        hit = await fetch_listing_format_prices(
+            client,
+            "apple_books",
+            "https://books.apple.com/us/book/id123",
+            ctx,
+        )
+        assert hit is not None
+        assert hit.format_prices.get("eBook") == "$14.99"
+        assert hit.format_prices.get("Audiobook") == "$28.00"
+
+    @pytest.mark.asyncio
+    async def test_thriftbooks_unlabeled_single_price(self):
+        """ThriftBooks single price without bookFormat stays out of format_prices."""
+        html = (
+            "A" * 600
+            + '<span class="Item-price">$12.50</span>'
+        )
+        resp = MagicMock()
+        resp.status_code = 200
+        resp.text = html
+        client = AsyncMock()
+        client.get = AsyncMock(return_value=resp)
+
+        hit = await fetch_listing_format_prices(
+            client, "thriftbooks", "https://www.thriftbooks.com/w/foo/1/",
+        )
+        assert hit is not None
+        assert hit.formatted == "$12.50"
+        assert hit.format_prices == {}
+
+    @pytest.mark.asyncio
+    async def test_kobo_keeps_ebook_label(self):
+        """Kobo is digital-only — single price is labeled eBook."""
+        html = (
+            "A" * 600
+            + 'itemprop="price" content="9.99"'
+        )
+        resp = MagicMock()
+        resp.status_code = 200
+        resp.text = html
+        client = AsyncMock()
+        client.get = AsyncMock(return_value=resp)
+
+        hit = await fetch_listing_format_prices(
+            client, "kobo", "https://www.kobo.com/ebook/foo",
+        )
+        assert hit is not None
+        assert hit.format_prices.get("eBook") == "$9.99"
+
+    @pytest.mark.asyncio
+    async def test_json_ld_binding_labels_single_price(self):
+        """AbeBooks with JSON-LD Hardcover labels the single price correctly."""
+        html = (
+            "A" * 400
+            + '<script type="application/ld+json">'
+            + '{"@type":"Book","bookFormat":"Hardcover",'
+            + '"offers":{"price":"18.00","priceCurrency":"USD"}}'
+            + "</script>"
+            + 'itemprop="price" content="18.00"'
+        )
+        resp = MagicMock()
+        resp.status_code = 200
+        resp.text = html
+        client = AsyncMock()
+        client.get = AsyncMock(return_value=resp)
+
+        hit = await fetch_listing_format_prices(
+            client, "abebooks", "https://www.abebooks.com/book/123",
+        )
+        assert hit is not None
+        assert hit.format_prices.get("Hardcover") == "$18.00"
+
+
+class TestSinglePriceFormatKey:
+    def test_kobo_is_ebook(self):
+        assert _single_price_format_key("kobo", "") == "eBook"
+
+    def test_thriftbooks_without_json_ld_is_empty(self):
+        assert _single_price_format_key("thriftbooks", "<html></html>") == ""
+
+    def test_json_ld_hardcover(self):
+        html = (
+            '<script type="application/ld+json">'
+            '{"bookFormat":"https://schema.org/Hardcover"}'
+            "</script>"
+        )
+        assert _book_format_from_json_ld(html) == "Hardcover"
+        assert _single_price_format_key("abebooks", html) == "Hardcover"
+
 
 class TestReplaceScanPreservesRichMap:
     """replace_from_scan should not clobber a richer existing format_prices map."""