offers: +356 verified market-sweep deals (2026-08-08)

app/card_catalogue.py

@@ -148,8 +148,11 @@ CATALOGUE: List[Card] = [
             "travel_flights": 15000,
             "travel_hotels": 15000,
             "insurance": 10000,
-        },
-        cap_groups=[{"categories": ["groceries", "utilities"], "cap": 2000}],  # insurance cap raised to 10,000 RP/mo (eff Jul 2025); grocery/utility 2,000 RP/mo
+            # SEPARATE 2,000 RP/mo ceilings, not one shared bucket - HDFC's
+            # terms name grocery, utility and telecom individually.
+            "groceries": 2000,
+            "utilities": 2000,
+        },  # insurance cap raised to 10,000 RP/mo (eff Jul 2025)
         portal_rates={"travel_flights": 10.0, "travel_hotels": 10.0},  # only via SmartBuy
         portal_name="HDFC SmartBuy", portal_cap_units=15000,
         excluded_categories=["fuel", "rent", "wallet_load"],
@@ -193,7 +196,7 @@ CATALOGUE: List[Card] = [
         point_value_inr=1.0,
         base_rate=1.0, online_boost_only=True,                  # 1% base cashback
         category_rates={},
-        caps={},
+        caps={c: 1000 for c in ("general","dining","groceries","online_shopping","electronics","apparel","entertainment","transport","utilities","travel_flights","travel_hotels","pharmacy","insurance","education")},  # the 1% base tier is itself capped at 1,000 CashPoints/mo
         brand_bonuses={"amazon": 5.0, "flipkart": 5.0, "swiggy": 5.0, "zomato": 5.0, "uber": 5.0, "myntra": 5.0, "tata_cliq": 5.0, "bookmyshow": 5.0, "cult_fit": 5.0, "sonyliv": 5.0},  # 5% on 10 brands only
         brand_caps=[{"brands": ["amazon", "flipkart", "swiggy", "zomato", "uber", "myntra", "tata_cliq", "bookmyshow", "cult_fit", "sonyliv"], "cap": 1000}],  # ₹1,000/mo shared
         excluded_categories=["rent", "wallet_load", "fuel"],
@@ -217,9 +220,9 @@ CATALOGUE: List[Card] = [
             "apparel": 5.0,
             "dining": 5.0,
         },
-        caps={},
-        cap_groups=[{"categories": ["online_shopping", "electronics", "apparel", "dining"], "cap": 2000}],  # ₹2,000/mo shared
-        excluded_categories=["rent", "wallet_load", "fuel", "utilities", "insurance"],
+        caps={c: 2000 for c in ("general","groceries","transport","entertainment","pharmacy","travel_flights","travel_hotels")},  # the 1% tier caps at Rs.2,000/cycle too (eff 1 Apr 2026)
+        cap_groups=[{"categories": ["online_shopping", "electronics", "apparel", "dining"], "cap": 2000}],  # Rs.2,000/mo shared
+        excluded_categories=["rent", "wallet_load", "fuel", "utilities", "insurance", "education"],  # "School and Educational Services" is named in SBI's own exclusion list
         fees=FeeStructure(999, 999, 200000),
         highlights=["Flat 5% on ALL online spends", "1% offline", "No merchant lock-in"],
         persona_fit=["online_shopper", "value", "young_professional"],
@@ -253,7 +256,7 @@ CATALOGUE: List[Card] = [
         base_rate=1.0, online_boost_only=True,
         category_rates={"utilities": 2.0, "insurance": 2.0},
         caps={},
-        excluded_categories=["rent", "wallet_load"],
+        excluded_categories=["rent", "wallet_load", "fuel", "education"],   # fuel, education, tax and gold earn nothing on this card
         brand_bonuses={"amazon": 5.0},  # 5% Amazon (Prime); 2% utilities/insurance/partners; 1% else
         fees=FeeStructure(0, 0, None),  # lifetime free
         highlights=["5% on Amazon (Prime)", "2% on partner merchants", "Lifetime free"],
@@ -494,9 +497,9 @@ CATALOGUE: List[Card] = [
         point_value_inr=1.0,
         base_rate=1.5,
         category_rates={},
-        brand_bonuses={"tata_neu": 5.0, "croma": 5.0, "bigbasket": 5.0, "tata_1mg": 5.0, "westside": 5.0, "air_india": 5.0, "tata_cliq": 5.0, "tata_play": 5.0}, upi_reward_cap_units=500,  # 5% Tata brands; 1.5% else; UPI NeuCoins capped 500/mo
+        brand_bonuses={"tata_neu": 5.0, "croma": 5.0, "bigbasket": 5.0, "tata_1mg": 5.0, "westside": 5.0, "air_india": 5.0, "tata_cliq": 5.0, "tata_play": 5.0}, upi_reward_cap_units=500, upi_base_rate=0.5,  # 5% Tata brands; 1.5% on card; UPI earns 0.5% unless paid from the Tata Neu UPI ID; NeuCoins capped 500/mo
         brand_caps=[{"brands": ["tata_neu", "croma", "bigbasket", "tata_1mg", "westside", "air_india", "tata_cliq", "tata_play"], "cap": 2000}],
-        caps={},
+        caps={"groceries": 2000, "insurance": 2000, "utilities": 2000},  # 2,000 NeuCoins/mo each
         excluded_categories=["fuel", "rent", "wallet_load"],
         fees=FeeStructure(1499, 1499, 300000),
         highlights=["5% NeuCoins on Tata brands", "1.5% on other UPI/spends", "UPI-linked"],
@@ -622,7 +625,7 @@ CATALOGUE: List[Card] = [
     Card(
         id="au_zenith", name="AU Bank Zenith", issuer="AU Small Finance Bank", network="Visa", segment="premium",
         reward_unit="points", point_value_inr=0.22, base_rate=3.0,
-        category_rates={"dining": 5.0, "groceries": 5.0}, caps={}, excluded_categories=["fuel", "rent", "wallet_load"],  # devalued 1 Jan 2026; RP ~₹0.25 general / ₹0.20 voucher → modeled ₹0.22 net of ₹99 redemption fee
+        category_rates={"dining": 5.0, "groceries": 5.0, "insurance": 1.0, "utilities": 1.0}, caps={}, excluded_categories=["fuel", "rent", "wallet_load"],   # insurance/utility/telecom held at 1 RP per 100  # devalued 1 Jan 2026; RP ~₹0.25 general / ₹0.20 voucher → modeled ₹0.22 net of ₹99 redemption fee
         fees=FeeStructure(7999, 7999, 800000),
         highlights=["Devalued Jan 2026: 5 RP dining/grocery", "3 RP/₹100 base", "Lounge access"], persona_fit=["premium", "traveller", "high_spender"], annual_fee_text="₹7,999 + GST · waived on ₹8L spend",
     ),
@@ -1195,7 +1198,7 @@ CATALOGUE += [
         id="hdfc_irctc", name="IRCTC HDFC Bank Credit Card", issuer="HDFC Bank", network="RuPay",
         segment="entry", reward_unit="points", point_value_inr=1, base_rate=1,
         category_rates={},
-        caps={"wallet_load": 500},
+        caps={}, upi_reward_cap_units=500,   # the 500/mo figure is the UPI cap, not a cap on a category the card excludes
         excluded_categories=["fuel", "rent", "wallet_load", "education"],
         brand_bonuses={"irctc": 5},
         portal_rates={"transport": 5}, portal_name="SmartBuy",
@@ -1276,7 +1279,7 @@ CATALOGUE += [
         id="hdfc_tata_neu_plus", name="Tata Neu Plus HDFC Bank Credit Card", issuer="HDFC Bank", network="RuPay",
         segment="entry", reward_unit="points", point_value_inr=1, base_rate=1,
         category_rates={},
-        caps={"wallet_load": 500},
+        caps={}, upi_reward_cap_units=500,   # the 500/mo figure is the UPI cap, not a cap on a category the card excludes
         excluded_categories=["fuel", "rent", "wallet_load"],
         brand_bonuses={"tata_neu": 7},
         upi_eligible=True,

app/channels.py

@@ -483,12 +483,19 @@ def compare_channels(
         # 5,000 rupee fare is not the same money as on a 5,800 rupee one.
         price_known = ch["key"] in prices
         price = prices[ch["key"]] if price_known else float(amount)
+        # THE SCOPE TRAVELS WITH THE CONTEXT. The pool below is already geo- and
+        # trip-filtered, but score_transaction re-applies scope_filter to
+        # whatever ctx it is handed - and with no `international` flag that
+        # reads as DOMESTIC, so every international card offer this pool had
+        # deliberately kept was thrown away again one line later. The filter is
+        # only idempotent if both halves are asked the same question.
         ctx = TxnContext(
             category=category, amount=price, merchant=merchant,
             brand_key=bk,
             offers=_trip_filter(_geo_filter(active_offers_for(bk), international),
                                 passengers, round_trip),
             rail="card", channel=ch["channel"],
+            international=international, passengers=passengers, round_trip=round_trip,
         )
         res = score_transaction(held_card_ids, ctx, include_discovery=False, persona=persona)
         ranked = res["held_ranked"]

app/main.py

@@ -767,6 +767,7 @@ async def parse_statements(
 ):
     _limit(request, "parse", rate=12)       # 12/min per IP per worker
     from statement_parser import (parse_statement, detect_cards, detect_issuers,
+                              detect_points_balance_file,
                                   find_pdf_password, detect_credit_limit)
     # Smart unlock: the password field may carry MULTIPLE candidates (newline or
     # comma separated), derived app-side from the user's details the way every
@@ -784,6 +785,7 @@ async def parse_statements(
         detected: List[str] = []
         issuers: List[str] = []
         credit_limit = None       # highest total limit seen across the batch
+        points_balances: Dict[str, int] = {}   # cardId -> reward-point balance read off that card's statement
         for f in files:
             content = await f.read()
             # Resolve THE working password for this file up front (cheap pypdf
@@ -830,6 +832,22 @@ async def parse_statements(
                         credit_limit = _lim
                 except Exception:
                     pass
+                # The reward-point BALANCE, attributed to the card this file
+                # names. Without it the pay-with-points panel can only nudge the
+                # user to type the number in by hand, which is why nobody ever
+                # saw an answer. Attributed only when the file identifies
+                # exactly ONE card - the same rule the transactions follow, and
+                # a balance on the wrong card is worse than no balance.
+                try:
+                    _file_cards = await anyio.to_thread.run_sync(
+                        lambda c=content, n=f.filename, p=pw: detect_cards(n, c, password=p))
+                    if len(_file_cards) == 1:
+                        _bal = await anyio.to_thread.run_sync(
+                            lambda c=content, n=f.filename, p=pw: detect_points_balance_file(n, c, password=p))
+                        if _bal:
+                            points_balances[_file_cards[0]] = int(_bal)
+                except Exception:
+                    pass
             except Exception as e:
                 errors.append({"file": f.filename, "error": str(e)})
                 # A locked/broken file can still identify its card from the
@@ -845,7 +863,7 @@ async def parse_statements(
                     pass
         return {"transactions": all_txns, "count": len(all_txns), "errors": errors,
                 "detected_cards": detected, "detected_issuers": issuers, "reversals": all_reversals,
-                "credit_limit": credit_limit}
+                "credit_limit": credit_limit, "points_balances": points_balances}
     finally:
         _PARSE_SEM.release()
 

app/offers.py

@@ -701,15 +701,20 @@ def scope_filter(offers, scope) -> list:
     offer paid out on a domestic stay. Living here, where every consumer reaches
     it, is what stops a caller forgetting it. Mirror of offers.ts scopeFilter.
 
-    Unknown scope means DO NOT FILTER: a null passenger count must not silently
-    delete every slabbed offer from a non-travel scoring.
+    UNKNOWN SCOPE MEANS THE FLOOR, NOT A FREE PASS. This used to skip the
+    passenger and trip gates entirely when the scope was unknown, while
+    channels.trip_filter - reading the same offers - defaulted to one passenger,
+    one way. So the identical Yatra row priced 1,800 on the channel list and
+    3,000 in the card panel, the 3,000 being a slab that requires three
+    passengers on a round trip. A discount you have not qualified for is not a
+    discount, so "we do not know" resolves to the smaller claim. Mirror of
+    offers.ts scopeFilter.
     """
     if not scope:
         return list(offers or [])
     intl = bool(scope.get("international"))
-    known_pax = scope.get("passengers") is not None
-    pax = scope.get("passengers") or 1
-    known_trip = scope.get("round_trip") is not None
+    raw_pax = scope.get("passengers")
+    pax = raw_pax if isinstance(raw_pax, (int, float)) and raw_pax > 0 else 1
     rt = bool(scope.get("round_trip"))
     out = []
     for o in offers or []:
@@ -718,14 +723,13 @@ def scope_filter(offers, scope) -> list:
             continue
         if g == "domestic" and intl:
             continue
-        if known_pax and int(o.get("min_passengers") or 0) > pax:
+        if int(o.get("min_passengers") or 0) > pax:
+            continue
+        tt = str(o.get("trip_type") or "any").lower()
+        if tt == "round" and not rt:
+            continue
+        if tt == "oneway" and rt:
             continue
-        if known_trip:
-            tt = str(o.get("trip_type") or "any").lower()
-            if tt == "round" and not rt:
-                continue
-            if tt == "oneway" and rt:
-                continue
         out.append(o)
     return out
 
@@ -744,18 +748,30 @@ def offer_value(off: Dict, amount: float, category: Optional[str] = None) -> flo
     t = off.get("type")
     v = off.get("value") or 0.0
     if t in ("pct", "cashback"):
+        # A PERCENTAGE OUTSIDE (0, 100] IS NOT A DISCOUNT. The feed is ingested
+        # from scrapers, and a malformed row priced straight through: value -20
+        # returned -2,000, a "discount" that RAISES the net cost.
+        if not (v > 0) or v > 100 or v != v:
+            return 0.0
         val = amount * v / 100.0
         cap = off.get("max_discount")
-        if cap:
+        # `if cap` treated a cap of ZERO as "no cap" - the one value that most
+        # obviously means the opposite - and let a NEGATIVE cap through as the
+        # answer.
+        if cap is not None:
+            if not (cap > 0):
+                return 0.0
             val = min(val, cap)
-        return val
+        return max(0.0, min(val, amount))
     if t == "flat":
-        # A DISCOUNT CANNOT EXCEED THE BILL. "Flat Rs.3,000 off" on a Rs.500
-        # basket was valued at 3,000 - the user walkthrough (2026-07-29) showed
-        # a card "saving" six times the purchase. Most such offers carry a
-        # min_spend that gates this; for the few whose page states none, the
-        # spend itself is the ceiling. Mirrored in offers.ts offerValue.
-        return min(float(v), amount)
+        # A FLAT COUPON BIGGER THAN THE BILL DOES NOT MAKE THE BILL FREE.
+        # Clamping "Flat Rs.3,000 off" to a Rs.500 basket priced that basket at
+        # ZERO. Such a coupon almost always carries a minimum spend we do not
+        # hold; with none recorded, the honest answer is that it does not apply.
+        # Mirrored in offers.ts offerValue.
+        if not (v > 0):
+            return 0.0
+        return 0.0 if float(v) > amount else float(v)
     # bogo and nocost_emi carry no computable rupee value: a "buy one get one" is
     # worth whatever the second ticket costs, which we do not know, and no-cost EMI
     # is a financing benefit. Both are surfaced as TEXT and valued at zero, so they

app/rails.py

@@ -0,0 +1,135 @@
+"""
+WHEN THE CARD IS THE WRONG ANSWER (mirror of app/src/data/rails.ts).
+
+Rent, wallet loads, big utility bills, third-party education fees and fuel
+outside the surcharge waiver all carry a 1% + GST charge at most Indian
+issuers, and the app used to render them as "excluded, earns nothing" - which
+reads as neutral. A Rs.35,000 rent payment costs Rs.413 in fees to earn zero.
+
+The rent CHANNEL mostly closed on 15 Sep 2025: the RBI's revised Payment
+Aggregator directions require an aggregator to hold a direct contract with the
+merchant it collects for, and CRED, PhonePe and Paytm stopped card rent that
+week. So the useful answer is which rail still works, not what the card costs.
+
+Sourced from issuer fee schedules and MITC PDFs. An issuer whose own document
+could not be read is simply absent - the app never invents a charge.
+
+PARITY RULE: identical to the TypeScript half. Change both or neither.
+"""
+
+from typing import Dict, Optional
+
+try:
+    from card_catalogue import get_card
+except ImportError:  # pragma: no cover
+    from .card_catalogue import get_card
+
+RAILS_REVIEWED = "2026-08-07"
+
+# 18% GST applies on top of every one of these fees; issuer schedules state
+# their charges exclusive of it.
+FEE_GST_MULT = 1.18
+
+# issuer -> category -> {pct, threshold_inr, cap_inr, exempt_card_ids, source}
+SURCHARGES: Dict[str, Dict[str, Dict]] = {
+    "HDFC Bank": {
+        "rent": {"pct": 1, "threshold_inr": 0, "cap_inr": 4999, "source": "HDFC fee revision, eff 1 Jul 2025"},
+        "wallet_load": {"pct": 1, "threshold_inr": 10000, "cap_inr": 4999, "source": "HDFC fee revision, eff 1 Jul 2025"},
+        "utilities": {"pct": 1, "threshold_inr": 50000, "cap_inr": 4999, "source": "HDFC fee revision, eff 1 Jul 2025"},
+        "education": {"pct": 1, "threshold_inr": 0, "cap_inr": 4999, "source": "HDFC: third-party apps only; direct to the institution is free"},
+    },
+    "Axis Bank": {
+        "rent": {"pct": 1, "threshold_inr": 0, "exempt_card_ids": ["axis_olympus", "axis_primus"], "source": "Axis Schedule of Charges (KFS)"},
+        "wallet_load": {"pct": 1, "threshold_inr": 10000, "source": "Axis KFS: cumulative 10,000+ per statement cycle"},
+        "utilities": {"pct": 1, "threshold_inr": 25000, "source": "Axis KFS: cumulative 25,000+ per statement cycle"},
+        "education": {"pct": 1, "threshold_inr": 0, "source": "Axis KFS: third-party apps only"},
+    },
+    "IndusInd Bank": {
+        "rent": {"pct": 1, "threshold_inr": 0, "exempt_card_ids": ["indusind_legend"], "source": "IndusInd MITC (several premium tiers waived)"},
+        "wallet_load": {"pct": 1, "threshold_inr": 20000, "source": "IndusInd MITC: above 20,000 per statement cycle"},
+        "utilities": {"pct": 1, "threshold_inr": 25000, "source": "IndusInd MITC: above 25,000 per statement cycle"},
+        "education": {"pct": 1, "threshold_inr": 45000, "source": "IndusInd MITC: third-party apps, above 45,000 per cycle"},
+    },
+    "Kotak Mahindra Bank": {
+        "rent": {"pct": 1, "threshold_inr": 0, "source": "Kotak revision, eff 1 Jun 2025"},
+        "wallet_load": {"pct": 1, "threshold_inr": 10000, "source": "Kotak revision, eff 1 Jun 2025"},
+        "utilities": {"pct": 1, "threshold_inr": 35000, "source": "Kotak revision, eff 1 Jun 2025 (threshold varies by tier; the lowest is used)"},
+        "education": {"pct": 1, "threshold_inr": 0, "source": "Kotak revision, eff 1 Jun 2025"},
+    },
+    "SBI Card": {
+        "wallet_load": {"pct": 1, "threshold_inr": 1000, "source": "SBI Card revision, eff 1 Nov 2025 - the lowest threshold in the market"},
+        "education": {"pct": 1, "threshold_inr": 0, "source": "SBI Card, eff 1 Nov 2025: third-party apps only"},
+    },
+    "IDFC FIRST Bank": {
+        "rent": {"pct": 1, "threshold_inr": 0, "source": "IDFC First MITC, eff 3 Mar 2023 (not refunded if the payment reverses)"},
+    },
+    "Standard Chartered": {
+        "rent": {"pct": 1, "threshold_inr": 0, "source": "Standard Chartered, eff 2 Apr 2023 - no cap and no minimum"},
+    },
+}
+
+FUEL_WAIVER_MIN_INR = 400
+FUEL_WAIVER_MAX_INR = 4000
+
+
+def _r2(x: float) -> float:
+    from math import floor
+    return floor(x * 100 + 0.5) / 100
+
+
+def surcharge_for(card_id: str, category: str) -> Optional[Dict]:
+    card = get_card(card_id)
+    if card is None:
+        return None
+    rule = SURCHARGES.get(card.issuer, {}).get(category)
+    if not rule:
+        return None
+    if card_id in (rule.get("exempt_card_ids") or []):
+        return None
+    return rule
+
+
+def surcharge_inr(card_id: str, category: str, amount_inr: float, already_this_cycle_inr: float = 0.0) -> float:
+    """Fee on THIS payment. Thresholds are cumulative per statement cycle, so
+    only the part above the line is charged."""
+    rule = surcharge_for(card_id, category)
+    if not rule:
+        return 0.0
+    try:
+        amt = float(amount_inr)
+    except (TypeError, ValueError):
+        return 0.0
+    if amt != amt or amt <= 0 or amt == float("inf"):
+        return 0.0
+    prior = already_this_cycle_inr if (isinstance(already_this_cycle_inr, (int, float)) and already_this_cycle_inr > 0) else 0.0
+    threshold = rule["threshold_inr"]
+    chargeable = max(0.0, (prior + amt) - threshold) - max(0.0, prior - threshold)
+    if chargeable <= 0:
+        return 0.0
+    fee = chargeable * rule["pct"] / 100.0
+    cap = rule.get("cap_inr")
+    if cap is not None:
+        prior_fee = max(0.0, prior - threshold) * rule["pct"] / 100.0
+        fee = max(0.0, min(fee, cap - prior_fee))
+    return _r2(fee * FEE_GST_MULT)
+
+
+def fuel_fee_inr(amount_inr: float) -> float:
+    """The 1% fuel surcharge is waived inside the band - but NO issuer refunds
+    the GST on it (IDFC, IndusInd and HSBC all say so), so a fully waived fill
+    still costs about 0.18%, and a fill outside the band costs the lot."""
+    try:
+        amt = float(amount_inr)
+    except (TypeError, ValueError):
+        return 0.0
+    if amt != amt or amt <= 0 or amt == float("inf"):
+        return 0.0
+    if amt > FUEL_WAIVER_MAX_INR or amt < FUEL_WAIVER_MIN_INR:
+        return _r2(amt * 0.01 * FEE_GST_MULT)
+    return _r2(amt * 0.01 * (FEE_GST_MULT - 1))
+
+
+def fee_for(card_id: str, category: str, amount_inr: float, already_this_cycle_inr: float = 0.0) -> float:
+    if category == "fuel":
+        return fuel_fee_inr(amount_inr)
+    return surcharge_inr(card_id, category, amount_inr, already_this_cycle_inr)

app/redemptions.py

@@ -26,7 +26,7 @@ try:
 except ImportError:  # pragma: no cover - package-style import
     from .card_catalogue import get_card
 
-REDEMPTIONS_REVIEWED = "2026-07-27"
+REDEMPTIONS_REVIEWED = "2026-08-07"
 
 # ---------------------------------------------------------------------------
 # Partner mile values (INR per PARTNER mile/point, not per card point)
@@ -48,20 +48,24 @@ MILE_VALUE: Dict[str, Dict[str, float]] = {
 }
 
 # mode: key, label, kind (cashback|voucher|portal), per_point_inr,
-#       best_per_point_inr (optional), travel_bookable (optional), note (optional)
+#       best_per_point_inr (optional), travel_bookable (optional),
+#       max_share_pct (optional - the largest share of ONE booking this route
+#       lets points pay; absent means 100. HDFC caps SmartBuy travel
+#       redemptions at 70%, which the note said in prose while the
+#       arithmetic ignored it), note (optional)
 REDEMPTION_MODES: Dict[str, List[Dict]] = {
     "hdfc_infinia": [
-        {"key": "smartbuy", "label": "SmartBuy flights and hotels", "kind": "portal", "per_point_inr": 1.0, "travel_bookable": True, "note": "Up to 1.5 lakh points a month, max 70% of the booking"},
+        {"key": "smartbuy", "label": "SmartBuy flights and hotels", "kind": "portal", "per_point_inr": 1.0, "travel_bookable": True, "max_share_pct": 70, "note": "Up to 1.5 lakh points a month, max 70% of the booking"},
         {"key": "voucher", "label": "Voucher catalogue", "kind": "voucher", "per_point_inr": 0.35, "best_per_point_inr": 0.5},
         {"key": "cashback", "label": "Statement credit", "kind": "cashback", "per_point_inr": 0.3, "note": "Capped at 50,000 points a month"},
     ],
     "hdfc_diners_black": [
-        {"key": "smartbuy", "label": "SmartBuy flights and hotels", "kind": "portal", "per_point_inr": 1.0, "travel_bookable": True, "note": "Monthly cap applies, max 70% of the booking"},
+        {"key": "smartbuy", "label": "SmartBuy flights and hotels", "kind": "portal", "per_point_inr": 1.0, "travel_bookable": True, "max_share_pct": 70, "note": "Monthly cap applies, max 70% of the booking"},
         {"key": "voucher", "label": "Voucher catalogue", "kind": "voucher", "per_point_inr": 0.35, "best_per_point_inr": 0.5},
         {"key": "cashback", "label": "Statement credit", "kind": "cashback", "per_point_inr": 0.3},
     ],
     "hdfc_regalia_gold": [
-        {"key": "smartbuy", "label": "SmartBuy flights and hotels", "kind": "portal", "per_point_inr": 0.5, "travel_bookable": True},
+        {"key": "smartbuy", "label": "SmartBuy flights and hotels", "kind": "portal", "per_point_inr": 0.5, "travel_bookable": True, "max_share_pct": 70, "note": "Max 70% of the booking in points"},
         {"key": "voucher", "label": "Voucher catalogue", "kind": "voucher", "per_point_inr": 0.35},
         {"key": "cashback", "label": "Statement credit", "kind": "cashback", "per_point_inr": 0.2},
     ],
@@ -84,11 +88,11 @@ REDEMPTION_MODES: Dict[str, List[Dict]] = {
         {"key": "cashback", "label": "Statement credit", "kind": "cashback", "per_point_inr": 0.25},
     ],
     "icici_emeralde": [
-        {"key": "ishop", "label": "iShop flights, hotels and vouchers", "kind": "portal", "per_point_inr": 1.0, "travel_bookable": True},
+        {"key": "ishop", "label": "iShop flights, hotels and vouchers", "kind": "portal", "per_point_inr": 1.0, "travel_bookable": True, "max_share_pct_hotel": 90, "note": "Hotels cap at 90% in points; no redemption fee on this tier"},
         {"key": "voucher", "label": "Voucher catalogue", "kind": "voucher", "per_point_inr": 0.6},
     ],
     "icici_sapphiro": [
-        {"key": "ishop", "label": "iShop flights and hotels", "kind": "portal", "per_point_inr": 0.45, "best_per_point_inr": 1.0, "travel_bookable": True, "note": "iShop value varies by card tier"},
+        {"key": "ishop", "label": "iShop flights and hotels", "kind": "portal", "per_point_inr": 0.45, "best_per_point_inr": 1.0, "travel_bookable": True, "max_share_pct_hotel": 90, "redemption_fee_inr": 117, "note": "iShop value varies by card tier; Rs.99 + GST redemption fee"},
         {"key": "voucher", "label": "Voucher catalogue", "kind": "voucher", "per_point_inr": 0.4},
         {"key": "cashback", "label": "Statement credit", "kind": "cashback", "per_point_inr": 0.25},
     ],
@@ -114,10 +118,10 @@ REDEMPTION_MODES: Dict[str, List[Dict]] = {
     # per-booking redemption fee; best is the advertised value on a booking
     # large enough that the fee vanishes into it.
     "hdfc_6e_rewards": [
-        {"key": "indigo", "label": "IndiGo flights and add-ons (6E Rewards)", "kind": "portal", "per_point_inr": 0.9, "best_per_point_inr": 1.0, "travel_bookable": True, "note": "1 6E Reward = ₹1 on IndiGo only; ₹200 + GST fee per redemption booking"},
+        {"key": "indigo", "label": "IndiGo flights and add-ons (6E Rewards)", "kind": "portal", "per_point_inr": 1.0, "travel_bookable": True, "redemption_fee_inr": 236, "note": "1 6E Reward = ₹1, on IndiGo only; ₹200 + GST per redemption booking"},
     ],
     "hdfc_6e_rewards_xl": [
-        {"key": "indigo", "label": "IndiGo flights and add-ons (6E Rewards)", "kind": "portal", "per_point_inr": 0.9, "best_per_point_inr": 1.0, "travel_bookable": True, "note": "1 6E Reward = ₹1 on IndiGo only; ₹200 + GST fee per redemption booking"},
+        {"key": "indigo", "label": "IndiGo flights and add-ons (6E Rewards)", "kind": "portal", "per_point_inr": 1.0, "travel_bookable": True, "redemption_fee_inr": 236, "note": "1 6E Reward = ₹1, on IndiGo only; ₹200 + GST per redemption booking"},
     ],
 }
 
@@ -399,46 +403,145 @@ def transfer_uplift_fraction(card_id: str) -> float:
     return _r2(f) if f > 0.05 else 0
 
 
+STAR = ["SQ", "UA", "TK", "AC", "LH", "NH", "TG", "AI", "OZ", "SA", "ET", "MS", "BR", "CA", "ZH", "SK", "LO", "OU", "JP", "A3", "TP", "AV", "CM", "NZ"]
+SKYTEAM = ["AF", "KL", "DL", "KE", "MU", "CZ", "VN", "SV", "AZ", "RO", "UX", "AM", "GA", "KQ", "ME", "VS"]
+ONEWORLD = ["BA", "QR", "AY", "CX", "JL", "MH", "QF", "AA", "IB", "RJ", "UL", "AT", "FJ", "AS"]
+
+# WHERE A TRANSFER CAN ACTUALLY BE FLOWN OR SLEPT. The panel was answering "how
+# many miles is this fare worth" and printing it as "how to pay for THIS
+# flight", so a Rs.8,012 IndiGo BLR-PAT hop was offered as 3,642 Singapore
+# KrisFlyer miles. Singapore Airlines does not fly BLR-PAT, IndiGo is in no
+# alliance and is not a KrisFlyer redemption partner: the route does not exist
+# at any number of miles. Accor points likewise cannot book a Taj. Mirror of
+# redemptions.ts AIRLINE_REACH / HOTEL_REACH.
+AIRLINE_REACH = {
+    "krisflyer": STAR,
+    "united": STAR,
+    "turkish": STAR,
+    "aeroplan": STAR,
+    "maharaja": ["AI", "IX"] + STAR,
+    "flying_blue": SKYTEAM,
+    "avios": ONEWORLD,
+    "emirates": ["EK", "FZ", "QF", "JL", "UL"],
+    "etihad": ["EY", "AI", "IX", "VS", "JL"],
+}
+HOTEL_REACH = {
+    "marriott": ["marriott", "sheraton", "westin", "st. regis", "st regis", "le meridien", "jw ", "ritz-carlton", "ritz carlton", "courtyard", "fairfield", "aloft", "four points", "moxy", "w "],
+    "ihg": ["intercontinental", "holiday inn", "crowne plaza", "holidayinn", "even hotel", "hotel indigo", "voco", "kimpton", "staybridge"],
+    "accor": ["novotel", "ibis", "sofitel", "pullman", "mercure", "fairmont", "raffles", "swissotel", "movenpick", "mgallery", "grand mercure"],
+    "itc": ["itc ", "welcomhotel", "welcomhotels", "storii", "fortune "],
+}
+
+# Per-programme transfer mechanics: what a transfer costs and the block size it
+# moves in. 3,642 is not a number Amex or SBI will transfer.
+_GST = 1.18
+PROGRAM_RULES = {
+    "axis_magnus": {"transfer_fee_inr": round(199 * _GST), "transfer_increment": 1000},
+    "axis_atlas": {"transfer_fee_inr": round(199 * _GST), "transfer_increment": 1000},
+    "axis_horizon": {"transfer_fee_inr": round(199 * _GST), "transfer_increment": 1000},
+    "axis_olympus": {"transfer_fee_inr": round(199 * _GST), "transfer_increment": 1000},
+    "hdfc_infinia": {"transfer_increment": 100},
+    "hdfc_diners_black": {"transfer_increment": 100},
+    "hdfc_regalia_gold": {"transfer_increment": 100},
+    "hdfc_regalia": {"transfer_increment": 100},
+    "hdfc_diners_privilege": {"transfer_increment": 100},
+}
+DEFAULT_TRANSFER_INCREMENT = 1000
+
+
+def _transfer_serves(p: Dict, subject: Optional[Dict]) -> bool:
+    """Can this partner's currency actually be used on this booking?"""
+    subject = subject or {}
+    if p.get("kind") == "airline":
+        c = str(subject.get("carrier") or "").strip().upper()[:2]
+        if not c:
+            return False
+        return c in AIRLINE_REACH.get(p["key"], [])
+    n = str(subject.get("property_name") or "").strip().lower()
+    if not n:
+        return False
+    return any(b in n for b in HOTEL_REACH.get(p["key"], []))
+
+
 def pay_with_points(wallet_ids: List[str], balances: Dict[str, float],
-                    category: str, amount_inr: float) -> List[Dict]:
+                    category: str, amount_inr: float,
+                    subject: Optional[Dict] = None) -> List[Dict]:
     """For a live-priced flight or hotel, which held card's points could pay
-    for it, and on which route. Estimates only; mirrors the TypeScript half."""
+    for it, and on which route. Mirrors the TypeScript half.
+
+    TWO KINDS OF CLAIM: a portal route is a rate the issuer publishes
+    ("fixed"), a transfer is the price divided by a realistic per-mile value
+    ("estimated"). A fixed route can still be PARTIAL (max_share_pct) or carry
+    a redemption fee, both of which land in cash_remainder_inr.
+
+    A transfer is only offered when `subject` shows the operating carrier or
+    the property's chain is reachable through that programme.
+    """
     try:
         amt = float(amount_inr)
     except (TypeError, ValueError):
         return []
     if amt != amt or amt <= 0 or amt == float("inf"):
         return []
+    if category not in ("travel_flights", "travel_hotels"):
+        return []
     want_kind = "airline" if category == "travel_flights" else "hotel"
+    is_hotel = category == "travel_hotels"
     rows: List[Dict] = []
     for card_id in wallet_ids:
         card = get_card(card_id)
         if card is None or card.reward_unit == "cashback":
             continue
         balance = _sanitize_points((balances or {}).get(card_id))
+        prog = PROGRAM_RULES.get(card_id, {})
         pick = None
+        best_fixed = None
+
+        def _rank(c):
+            # A route the balance can complete, then the one that covers most
+            # of the price, then the cheapest in points. Ranking on value per
+            # point alone put a route paying 70% of a stay above one paying all
+            # of it, purely because paying for less costs fewer points.
+            return (0 if balance > 0 and balance >= c["needed"] else 1, -c["share_pct"], c["needed"])
+
+        def _better(cand, cur):
+            return cur is None or _rank(cand) < _rank(cur)
+
         for m in REDEMPTION_MODES.get(card_id, []):
             if not m.get("travel_bookable") or m["per_point_inr"] <= 0:
                 continue
-            needed = ceil(amt / m["per_point_inr"])
-            label = PORTAL_ROUTE_LABEL.get(m["key"], f"Book via {m['label']}")
-            if pick is None or needed < pick["needed"]:
-                pick = {"route": "portal", "label": label, "needed": needed,
-                        "per": m["per_point_inr"], "note": m.get("note")}
+            raw_share = m.get("max_share_pct_hotel") if (is_hotel and m.get("max_share_pct_hotel") is not None) else m.get("max_share_pct")
+            share_pct = _rint(raw_share) if raw_share is not None and 0 < raw_share < 100 else 100
+            needed = ceil(amt * share_pct / 100 / m["per_point_inr"])
+            fee = m.get("redemption_fee_inr") or 0
+            cand = {"route": "portal", "label": PORTAL_ROUTE_LABEL.get(m["key"], f"Book via {m['label']}"),
+                    "needed": needed, "per": m["per_point_inr"], "share_pct": share_pct,
+                    "fee_inr": _rint(fee) if fee > 0 else 0, "note": m.get("note")}
+            if _better(cand, pick):
+                pick = cand
+            if _better(cand, best_fixed):
+                best_fixed = cand
         for p in TRANSFER_PARTNERS.get(card_id, []):
             if p["kind"] != want_kind:
                 continue
+            if not _transfer_serves(p, subject):
+                continue
             mv = MILE_VALUE.get(p["key"])
             if not mv or mv["realistic"] <= 0:
                 continue
             miles_needed = ceil(amt / mv["realistic"])
-            needed = ceil(miles_needed * (p["from_units"] / p["to_units"]))
+            raw_needed = ceil(miles_needed * (p["from_units"] / p["to_units"]))
+            step = prog.get("transfer_increment", DEFAULT_TRANSFER_INCREMENT)
+            needed = max(step, ceil(raw_needed / step) * step)
             per = _r2((p["to_units"] / p["from_units"]) * mv["realistic"])
-            if pick is None or needed < pick["needed"]:
-                pick = {"route": "transfer", "label": f"Transfer to {p['partner']}",
-                        "needed": needed, "per": per, "note": p.get("note")}
+            cand = {"route": "transfer", "label": f"Transfer to {p['partner']}",
+                    "needed": needed, "per": per, "share_pct": 100,
+                    "fee_inr": prog.get("transfer_fee_inr", 0), "note": p.get("note")}
+            if _better(cand, pick):
+                pick = cand
         if pick is None:
             continue
+        covered = _r2(amt * pick["share_pct"] / 100)
         rows.append({
             "card_id": card_id,
             "card_name": card.name,
@@ -446,14 +549,28 @@ def pay_with_points(wallet_ids: List[str], balances: Dict[str, float],
             "balance": balance,
             "route": pick["route"],
             "route_label": pick["label"],
+            "certainty": "fixed" if pick["route"] == "portal" else "estimated",
+            "max_share_pct": pick["share_pct"],
             "points_needed": pick["needed"],
-            "coverage_pct": min(100, _rint((balance / pick["needed"]) * 100)),
+            "cash_remainder_inr": max(0.0, _r2(amt - covered + pick["fee_inr"])),
+            "fee_inr": pick["fee_inr"],
+            # FLOOR, not round: rounding printed "100% of it in points" on a
+            # balance one point short of the target.
+            "coverage_pct": min(100, int(balance / pick["needed"] * 100)),
             "enough": balance >= pick["needed"],
             "per_point_inr": pick["per"],
+            # A floor is only a floor if the balance reaches it.
+            "fixed_alt": ({"route_label": best_fixed["label"],
+                           "points_needed": best_fixed["needed"],
+                           "max_share_pct": best_fixed["share_pct"]}
+                          if pick["route"] == "transfer" and best_fixed and balance >= best_fixed["needed"] else None),
             "note": pick["note"],
         })
     rows.sort(key=lambda r: (
         0 if r["enough"] else 1,
+        (0 if r["certainty"] == "fixed" else 1) if r["enough"] else 0,
+        -r["max_share_pct"] if r["enough"] else 0,
+        r["cash_remainder_inr"] if r["enough"] else 0,
         r["points_needed"] if r["enough"] else -r["coverage_pct"],
     ))
     return rows

app/scoring_engine.py

@@ -24,6 +24,7 @@ from dataclasses import dataclass, replace
 from typing import Dict, List, Optional
 
 from card_catalogue import Card, CATALOGUE_BY_ID, all_cards
+from rails import fee_for
 
 import math
 
@@ -80,7 +81,7 @@ class CardScore:
     network: str
     reward_value_inr: float          # rewards earned on this txn (capped)
     instant_offer_inr: float         # instant discount from live offers
-    total_value_inr: float           # reward + instant offer (rounded for display)
+    total_value_inr: float           # reward + instant offer - issuer fee (rounded for display)
     raw_total: float                 # unrounded total - used for ranking
     effective_rate_pct: float        # total value as % of spend
     capped: bool                     # whether monthly cap limited the reward
@@ -93,6 +94,11 @@ class CardScore:
     emi_offer_inr: float = 0.0
     emi_offer_text: Optional[str] = None
     emi_offer_code: Optional[str] = None
+    # What this card charges to MAKE this payment, GST included: 1% on rent,
+    # wallet loads, big utility bills and third-party education fees at most
+    # issuers, and the fuel surcharge outside the waiver band. Netted out of
+    # total_value_inr so a charging card cannot outrank a free one.
+    fee_inr: float = 0.0
     # The promo code the PRICED instant discount needs, when it needs one.
     # Mirror of CardScore.instantOfferCode in engine.ts.
     instant_offer_code: Optional[str] = None
@@ -116,19 +122,26 @@ def _offer_applies(off: Dict, card: Card, allow_emi: bool = False) -> bool:
     # Needs a code we could not name, so the user cannot apply it.
     if off.get("requires_promo_code") and not (off.get("promo_code") or "").strip():
         return False
+    # AN EXPLICIT CARD IS NOT A LICENCE TO SKIP THE REST. This used to RETURN on
+    # the card match, jumping over the excluded-card, card-kind and network
+    # gates below - so a row naming a card while also carrying requires_debit,
+    # a network it is not on, AND that same card in its own excluded list
+    # priced anyway. requires_debit is derived from evidence text after the
+    # loader's contradiction check, so the feed can produce exactly that row.
     cid = off.get("card_id")
-    if cid:
-        return cid == card.id          # explicit card wins; trust it
+    if cid and cid != card.id:
+        return False
     iss = off.get("applies_to_issuer") or ""
     # An offer naming NO issuer and no card is open to anyone paying any way.
     # A blank issuer used to mean "any issuer", which handed every promo code
     # and platform sale to the whole catalogue as if plastic had earned it.
     # These are surfaced separately (offers.best_open_offer) so the user still
     # sees the money without it deciding which card to pull out.
-    if not iss:
-        return False
-    if iss != card.issuer:
-        return False
+    if not cid:
+        if not iss:
+            return False
+        if iss != card.issuer:
+            return False
     # "all HDFC Bank Credit Cards except Infinia & Diners Club Black" - the
     # offer is the issuer's, minus a named few. Mirrored in engine.ts.
     if card.id in (off.get("excluded_card_ids") or []):
@@ -233,6 +246,18 @@ def score_transaction(
     mtd_spend: {card_id: {category: rupees_spent_this_month}}
     """
     mtd_spend = mtd_spend or {}
+    # A BAD AMOUNT MUST NOT REACH THE REWARD MATH. engine.ts has clamped this
+    # since the beginning; the server did not, so the same request that returned
+    # Rs.0 on the device returned a NEGATIVE reward and a positive effective
+    # rate from the API for amount = -10,000.
+    try:
+        _amt = float(ctx.amount)
+    except (TypeError, ValueError):
+        _amt = 0.0
+    if not (_amt > 0) or _amt != _amt or _amt == float("inf"):
+        _amt = 0.0
+    if _amt != ctx.amount:
+        ctx = replace(ctx, amount=_amt)
     # Trip scope applied ONCE, here, so every downstream consumer of ctx.offers
     # inherits it. compare_channels also pre-filters; the predicate is
     # idempotent, so neither can be the only guard.
@@ -289,17 +314,41 @@ def score_transaction(
         else:
             cap_units = card.caps.get(ctx.category)
         if not upi_block and cap_units is not None and rate > 0:
+            # WHAT THE CAP HAS ALREADY EATEN, valued at each member's OWN rate.
+            # Prior spend is stored in rupees and used to be converted back at
+            # THIS transaction's rate, which is only right when every member of
+            # the bucket earns the same. Axis ACE shares one Rs.500/month cap
+            # across bill payments at 5% and food delivery at 4%: after the cap
+            # was fully spent on bills, a Swiggy order still paid out, because
+            # the same rupees re-read at 4% looked like less of the cap.
             if brand_grp:
-                spent = sum(mtd_spend.get(card.id, {}).get("~" + b, 0.0) for b in brand_grp["brands"])
+                already_units = sum(
+                    mtd_spend.get(card.id, {}).get("~" + b, 0.0) / 100.0
+                    * (card.brand_bonuses or {}).get(b, card.base_rate)
+                    for b in brand_grp["brands"])
             elif cat_grp:
-                spent = sum(mtd_spend.get(card.id, {}).get(c, 0.0) for c in cat_grp["categories"])
+                already_units = sum(
+                    mtd_spend.get(card.id, {}).get(c, 0.0) / 100.0
+                    * (0.0 if c in card.excluded_categories else card.category_rates.get(c, card.base_rate))
+                    for c in cat_grp["categories"])
             else:
-                spent = mtd_spend.get(card.id, {}).get(ctx.category, 0.0)
-            already_units = spent / 100.0 * rate
+                already_units = mtd_spend.get(card.id, {}).get(ctx.category, 0.0) / 100.0 * rate
             remaining_units = max(0.0, cap_units - already_units)
             if gross_units > remaining_units:
                 accel_units = remaining_units
-                base_units_value = card.base_rate if ctx.category not in card.excluded_categories else 0.0
+                # WHAT SPEND BEYOND THE CAP EARNS. Falling back to the base rate
+                # made the cap ARITHMETICALLY INERT wherever the capped category
+                # had no accelerated rate of its own - 28 cards are in that
+                # position. HDFC caps Infinia grocery and utility earn at 2,000
+                # points a month; since utilities earn the base rate, "cap the
+                # first 2,000 then pay base on the rest" reconstitutes the
+                # uncapped total exactly, and Rs.2,00,000 of utility spend
+                # returned Rs.6,600 against a Rs.2,000 ceiling. A cap on the
+                # BASE rate is a hard cap; a cap on an ACCELERATED rate still
+                # drops to base, which is the real rule on Millennia.
+                base_units_value = 0.0
+                if ctx.category not in card.excluded_categories and rate > card.base_rate:
+                    base_units_value = card.base_rate
                 rupees_at_accel = remaining_units / rate * 100.0 if rate > 0 else 0.0
                 rupees_beyond = max(0.0, ctx.amount - rupees_at_accel)
                 gross_units = accel_units + rupees_beyond / 100.0 * base_units_value
@@ -323,7 +372,16 @@ def score_transaction(
             offer_inr, offer_note, offer_code = _instant_offer_value(card, ctx)
             emi_inr, emi_note, emi_code = _emi_offer_value(card, ctx)
 
-        total = reward_inr + offer_inr
+        # WHAT THE CARD CHARGES TO MAKE THIS PAYMENT, GST included. Netted out
+        # of the total so an issuer that charges 1% on rent can no longer
+        # outrank one that charges nothing. Thresholds are cumulative per
+        # STATEMENT CYCLE, so same-category spend already through this card in
+        # this cycle decides how much of THIS payment sits above the line.
+        prior_cycle = mtd_spend.get(card.id, {}).get(ctx.category, 0.0)
+        fee_inr = 0.0 if rail == "upi" else fee_for(card.id, ctx.category, ctx.amount, prior_cycle)
+        # _r2, not round(): Python's round is banker's and JS Math.round is
+        # half-up, which put the two engines a paisa apart on 448 scorings.
+        total = _r2(reward_inr + offer_inr - fee_inr)
         eff_pct = (total / ctx.amount * 100.0) if ctx.amount else 0.0
 
         # --- reasons ---
@@ -384,6 +442,7 @@ def score_transaction(
             emi_offer_inr=_r2(emi_inr),
             emi_offer_text=emi_note,
             emi_offer_code=emi_code,
+            fee_inr=_r2(fee_inr),
         )
         all_scores.append(sc)
         if held:

app/statement_parser.py

@@ -744,6 +744,119 @@ def _plausible_limit(v: float) -> bool:
     return 25000 <= v <= 1e8   # real card limits; floor rejects years/small numbers
 
 
+
+# ---------------------------------------------------------------------------
+# REWARD-POINT BALANCE
+#
+# The app can already tell you your points are worth more on a transfer partner
+# than as statement credit - but only if it knows the BALANCE, and the balance
+# was a number the user had to type in by hand. So the panel sat on a nudge and
+# most people never saw an answer.
+#
+# Market check (Aug 2026): on TechnoFino the recurring complaint is that no
+# Indian app automates this - people track 17 cards in Google Sheets. The one
+# app users report as working is CRED, which reads the emailed statement. That
+# is the approach here, and it needs no credentials and no account linking.
+#
+# EVERY STATEMENT PRINTS IT, because the issuer has to. The wording differs, so
+# match the CONTEXT (a reward-points heading or label) and then the closing
+# figure, rather than any bare number near the word "points".
+# ---------------------------------------------------------------------------
+
+# The label that names the balance we want. Deliberately narrow: "points
+# earned", "points redeemed" and "points expiring" are NOT the balance, and
+# grabbing one of those would show the user a confidently wrong number.
+_PTS_CLOSING_RE = re.compile(
+    r"(?:closing|total|net|available|balance\s+of)?\s*"
+    r"(?:reward|edge|membership\s+reward|neu|payback|club\s*vistara|bonus)?\s*"
+    r"points?\s*(?:balance|as\s+on|closing|total)?\s*[:\-]?\s*"
+    r"([0-9][0-9,]{0,9})\b",
+    re.I,
+)
+# A reward-points SECTION heading; a "Closing Balance" beneath one is the
+# balance even when the word "points" is not repeated on that line.
+_PTS_SECTION_RE = re.compile(r"(reward|edge\s+reward|membership\s+reward|neu\s*coin|payback)\s*points?\s*(summary|details|statement)?", re.I)
+_CLOSING_RE = re.compile(r"closing\s*(?:balance|points?)?\s*[:\-]?\s*([0-9][0-9,]{0,9})\b", re.I)
+# Words that mean this figure is NOT the balance.
+_PTS_REJECT = re.compile(r"earn|redeem|expir|lapse|adjust|convert|debit|credit\s*card\s*no|opening", re.I)
+# A rupee context: points are a count, never a currency amount, so a figure
+# introduced by a currency mark or carrying paise is the wrong figure.
+_PTS_MONEY = re.compile(r"(?:rs\.?|inr|₹)\s*$", re.I)
+# An integer that is NOT part of a decimal amount - points are whole units, so
+# "5,000.00" is a rupee figure and must not be read as a balance.
+# The WHOLE digit run, never a fragment of one. With a plain \b boundary,
+# "99,99,99,999" backtracked to a valid-looking prefix, finditer then matched
+# the trailing "999", and an absurd figure was read as a 999-point balance.
+# The lookarounds refuse to start or stop inside a number, so an over-long run
+# is rejected by _plausible_points as a whole instead of being salvaged.
+_PTS_INT_RE = re.compile(r"(?<![0-9,])([0-9][0-9,]{0,13})(?![0-9,])(?!\s*\.\s*[0-9])")
+
+
+def _plausible_points(v: float) -> bool:
+    """A balance a real cardholder can hold. Rejects a stray year (2026), a
+    card fragment, and an absurd figure that is really a rupee total."""
+    return 0 <= v <= 5_000_000 and not (1990 <= v <= 2100 and v == int(v) and len(str(int(v))) == 4)
+
+
+def detect_points_balance(text: str) -> Optional[int]:
+    """The reward-point CLOSING balance from statement text, or None.
+
+    None is the honest answer whenever the statement is ambiguous: a wrong
+    balance would feed straight into "your points cover this flight", which is
+    a claim the user would act on.
+    """
+    if not text:
+        return None
+    lines = [l.strip() for l in text.splitlines() if l.strip()]
+    cands: List[int] = []
+
+    for i, line in enumerate(lines):
+        low = line.lower()
+        # (a) an explicit labelled balance on one line. Once the line is
+        # CONFIRMED to name a balance, take the LAST plausible integer on it
+        # rather than trying to write one regex wide enough for every issuer's
+        # wording - Amex prints "Points Balance as on 31 Jul 2026: 2,15,300",
+        # and a pattern tight enough to reject "Points Earned 3,120" can never
+        # also span that date clause. Balances are printed last on their line.
+        if re.search(r"points?", low) and re.search(r"balance|closing|as on|total", low):
+            if _PTS_REJECT.search(low) and not re.search(r"closing|balance", low):
+                continue
+            line_vals: List[int] = []
+            for m in _PTS_INT_RE.finditer(line):
+                pre = line[max(0, m.start() - 6):m.start()]
+                if _PTS_MONEY.search(pre):
+                    continue
+                try:
+                    v = int(m.group(1).replace(",", ""))
+                except ValueError:
+                    continue
+                if _plausible_points(v):
+                    line_vals.append(v)
+            if line_vals:
+                cands.append(line_vals[-1])
+        # (b) a "Closing Balance" line inside a reward-points section
+        if _PTS_SECTION_RE.search(low):
+            for j in range(i, min(i + 6, len(lines))):
+                cm = _CLOSING_RE.search(lines[j])
+                if cm:
+                    try:
+                        v = int(cm.group(1).replace(",", ""))
+                    except ValueError:
+                        continue
+                    if _plausible_points(v):
+                        cands.append(v)
+                    break
+
+    if not cands:
+        return None
+    # Several figures and no agreement means we cannot tell which is the
+    # balance - say nothing rather than pick one.
+    uniq = sorted(set(cands))
+    if len(uniq) > 1 and uniq[-1] != max(cands, key=cands.count):
+        return None
+    return max(set(cands), key=cands.count)
+
+
 def _inline_credit_limit(text: str) -> Optional[float]:
     """Inline 'Credit Limit Rs 11,30,000' on a single line (Kotak, SBI, many issuers)."""
     best = None
@@ -857,6 +970,27 @@ def _ocr_credit_limit(content: bytes, password: Optional[str] = None) -> Optiona
     return best
 
 
+def detect_points_balance_file(filename: str, content: bytes, password: Optional[str] = None) -> Optional[int]:
+    """The reward-point balance from a statement FILE. Same tiering discipline
+    as detect_credit_limit: read the text layer, and return None rather than a
+    guess. Deliberately does NOT fall through to OCR - a wrong balance would
+    feed "your points cover this flight", and no balance at all is the safer
+    failure."""
+    name = (filename or "").lower()
+    if name.endswith(".pdf"):
+        try:
+            import pdfplumber
+            with pdfplumber.open(io.BytesIO(content), password=password or "") as pdf:
+                text = "\n".join((p.extract_text() or "") for p in pdf.pages[:4])
+            return detect_points_balance(text)
+        except Exception:
+            return None
+    try:
+        return detect_points_balance(content.decode("utf-8-sig", errors="ignore"))
+    except Exception:
+        return None
+
+
 def detect_credit_limit(filename: str, content: bytes, password: Optional[str] = None) -> Optional[float]:
     """The card's total credit limit from the statement, ignoring available/cash limits.
     Tiered: inline text, then column-aligned positional, then OCR (only if the text layer

tests/hotel_totals_regress.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+HOTEL PRICE-BASIS REGRESSION.
+
+The bug: price_inr is documented as the STAY TOTAL - the figure the card is
+charged, and therefore the figure every offer minimum and cap is judged
+against - but when a vendor omitted total_rate the code silently put its
+PER-NIGHT rate in that field:
+
+    "price_inr": total if total is not None else night
+
+channel_prices then takes min() across vendors, so on a five-night stay the
+single most expensive vendor (Yatra, 6,900/night = 34,500) presented as the
+cheapest at 6,900, became priced_total_inr, and became the base for offer
+minimums and caps - a factor-of-five error, in the app's favour-looking
+direction, on a number the user is asked to trust.
+
+Second, smaller version of the same sin: _amount fell back from
+extracted_lowest (with taxes) to extracted_before_taxes_fees (without), so a
+before-tax quote competed against with-tax ones in the same min().
+
+Run: python3 backend/tests/hotel_totals_regress.py
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "app"))
+
+import hotel_sellers as hs          # noqa: E402
+import hotels_provider as hp        # noqa: E402
+
+PASS = FAIL = 0
+
+
+def t(name, ok, detail=None):
+    global PASS, FAIL
+    if ok:
+        PASS += 1
+        print(f"PASS {name}")
+    else:
+        FAIL += 1
+        print(f"FAIL {name}" + (f"  {detail}" if detail is not None else ""))
+
+
+CI, CO = "2026-09-10", "2026-09-15"          # five nights
+
+# ---------------------------------------------------------------- nights
+t("nights: 10->15 Sep is 5", hs._nights(CI, CO) == 5, hs._nights(CI, CO))
+t("nights: same day is None (not 0)", hs._nights(CI, CI) is None)
+t("nights: reversed dates is None", hs._nights(CO, CI) is None)
+t("nights: garbage is None", hs._nights("not-a-date", CO) is None)
+
+# ------------------------------------------------------------ stay total
+t("total_rate is used as-is", hs._stay_total(32339.0, 6900.0, 5) == (32339.0, False))
+t("nightly-only is MULTIPLIED OUT, not substituted",
+  hs._stay_total(None, 6900.0, 5) == (34500.0, True), hs._stay_total(None, 6900.0, 5))
+t("nightly-only with unusable dates yields nothing (caller drops the row)",
+  hs._stay_total(None, 6900.0, None) == (None, False))
+t("neither figure yields nothing", hs._stay_total(None, None, 5) == (None, False))
+t("a one-night stay is unchanged by the multiply",
+  hs._stay_total(None, 6900.0, 1) == (6900.0, True))
+
+# ------------------------------------------------------------- tax basis
+t("extracted_lowest is tax-inclusive",
+  hs._amount_taxed({"extracted_lowest": 31000}) == (31000.0, True))
+t("before-taxes figure is flagged as such",
+  hs._amount_taxed({"extracted_before_taxes_fees": 27000}) == (27000.0, False))
+t("missing block is (None, False)", hs._amount_taxed(None) == (None, False))
+
+# ------------------------------- the reported scenario, end to end
+VENDORS = [
+    ("Agoda",       {"extracted_lowest": 32339}, None),
+    ("MakeMyTrip",  {"extracted_lowest": 31000}, None),
+    ("Yatra",       None, {"extracted_lowest": 6900}),   # nightly only: a 34,500 stay
+    ("Booking.com", {"extracted_before_taxes_fees": 27000}, None),
+]
+nights = hs._nights(CI, CO)
+rows = []
+for name, total_b, night_b in VENDORS:
+    total, t_tax = hs._amount_taxed(total_b)
+    night, n_tax = hs._amount_taxed(night_b)
+    stay, derived = hs._stay_total(total, night, nights)
+    rows.append({"seller": name, "price_inr": stay, "total_derived": derived,
+                 "taxes_included": t_tax if total is not None else n_tax})
+
+yatra = next(r for r in rows if r["seller"] == "Yatra")
+t("Yatra's nightly-only quote reads as its real 34,500 stay total",
+  yatra["price_inr"] == 34500.0 and yatra["total_derived"] is True, yatra)
+t("the most expensive vendor is no longer the cheapest",
+  min(rows, key=lambda r: r["price_inr"])["seller"] != "Yatra",
+  min(rows, key=lambda r: r["price_inr"]))
+
+taxed = [r["price_inr"] for r in rows if r["taxes_included"]]
+headline = min(taxed) if taxed else min(r["price_inr"] for r in rows)
+t("the headline total is the cheapest TAX-INCLUSIVE quote, not a before-tax one",
+  headline == 31000.0, headline)
+
+# --------------------------------------------------- the other provider
+t("provider: nightly-only is multiplied out",
+  hp._price_of({"price": {"nightlyPrice": 6900}}, 5) == 34500.0,
+  hp._price_of({"price": {"nightlyPrice": 6900}}, 5))
+t("provider: nightly-only with no dates is refused (0 => row dropped)",
+  hp._price_of({"price": {"nightlyPrice": 6900}}, None) == 0.0)
+t("provider: a real total still wins over the nightly figure",
+  hp._price_of({"price": {"totalPrice": 34500, "nightlyPrice": 6900}}, 5) == 34500.0)
+t("provider: nights helper agrees with hotel_sellers",
+  hp._nights_between(CI, CO) == hs._nights(CI, CO))
+
+print(f"\nHOTEL TOTALS REGRESS: {PASS} passed, {FAIL} failed")
+sys.exit(1 if FAIL else 0)

tests/points_balance_regress.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""
+REWARD-BALANCE DETECTION REGRESSIONS.
+
+payWithPoints could always say "your points cover this flight" - but only from
+a balance the user typed in by hand, so the panel showed a nudge and never an
+answer. Market check (Aug 2026): the recurring complaint on TechnoFino is that
+no Indian app automates this; people track 17 cards in Google Sheets. The one
+app users report as working is CRED, which reads the emailed statement. That is
+what this does, and it needs no credentials and no account linking.
+
+The bar is deliberately high in one direction: a WRONG balance feeds straight
+into "your points cover this flight", which the user would act on. None is
+always the safer answer.
+
+Run: python3 backend/tests/points_balance_regress.py
+"""
+import os
+import sys
+
+_APP = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "app")
+sys.path.insert(0, _APP)
+# statement_parser imports merchants for categorisation; on a bare checkout of
+# just this file that module may not be importable, and none of the detection
+# under test needs it.
+try:
+    import merchants  # noqa: F401
+except ModuleNotFoundError:
+    import types
+    _stub = types.ModuleType("merchants")
+    _stub.resolve_merchant = lambda *a, **k: {"brand_key": None, "category": "general", "offers": []}
+    sys.modules["merchants"] = _stub
+import statement_parser as sp          # noqa: E402
+
+PASS = FAIL = 0
+
+
+def t(name, ok, detail=None):
+    global PASS, FAIL
+    if ok:
+        PASS += 1
+        print(f"PASS {name}")
+    else:
+        FAIL += 1
+        print(f"FAIL {name}" + (f"  {detail}" if detail is not None else ""))
+
+
+# ---------------------------------------------- real issuer layouts
+FOUND = [
+    ("HDFC reward-points section", "Reward Points Summary\nOpening Balance 12,450\n"
+     "Points Earned 3,120\nPoints Redeemed 5,000\nClosing Balance 10,570", 10570),
+    ("Axis inline EDGE points", "EDGE REWARD POINTS BALANCE : 48,900", 48900),
+    ("SBI total balance", "Reward Points Summary\nTotal Reward Points Balance 1,04,220", 104220),
+    # Amex puts a date clause between the label and the figure, which is why the
+    # detector takes the LAST plausible integer on a confirmed balance line
+    # rather than trying to span it with one regex.
+    ("Amex with an 'as on' date", "Membership Rewards Points Balance as on 31 Jul 2026: 2,15,300", 215300),
+    ("ICICI closing under a heading", "Reward Points\nClosing Balance  7,845", 7845),
+    ("IDFC single line", "Total Reward Points Balance: 9,310", 9310),
+    ("lakh-grouped digits", "Reward Points Balance 12,34,567", 1234567),
+]
+for name, text, want in FOUND:
+    got = sp.detect_points_balance(text)
+    t(f"reads {name}", got == want, f"got {got}, want {want}")
+
+# ------------------------------------- silence beats a wrong number
+SILENT = [
+    ("a statement with no points at all", "Statement Date 05/08/2026\nTotal Amount Due Rs 12,340.00"),
+    ("points EARNED, which is not the balance", "Reward Points Earned This Month 3,120"),
+    ("points REDEEMED", "Reward Points Redeemed 4,500"),
+    ("points EXPIRING", "Reward Points Expiring Next Month 1,200"),
+    ("a rupee value that mentions points", "Points Redeemed Value Rs. 5,000.00"),
+    ("a bare year", "Reward Points Balance 2026"),
+    ("empty input", ""),
+    ("None input", None),
+]
+for name, text in SILENT:
+    got = sp.detect_points_balance(text)
+    t(f"stays silent on {name}", got is None, f"got {got}")
+
+# --------------------------------------------------- sanity bounds
+t("rejects an implausible balance", sp.detect_points_balance("Reward Points Balance 99,99,99,999") is None)
+t("accepts a zero-ish small balance", sp.detect_points_balance("Reward Points Balance 250") == 250)
+
+# ------------------------------------------------- file-level entry
+t("CSV bytes are read", sp.detect_points_balance_file("s.csv", b"Reward Points Balance 48,900") == 48900)
+t("an unreadable file is None, not a crash", sp.detect_points_balance_file("s.pdf", b"not a pdf") is None)
+t("a file with no balance is None", sp.detect_points_balance_file("s.csv", b"Date,Desc,Amount\n01/08/2026,X,100") is None)
+
+print(f"\nPOINTS BALANCE REGRESS: {PASS} passed, {FAIL} failed")
+sys.exit(1 if FAIL else 0)