Implement renter search, previews and simulated payment flows

README.md

@@ -8,3 +8,17 @@ pinned: false
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## Renter flows
+
+The finder offers step-by-step and natural-language search. Four steps collect property type, area, monthly USD budget and optional features, followed by a search summary with editable requirements. Numbered text menus work with the existing Twilio transport; lists retain every option. Photo messages replace the mockup's embedded carousel and cards.
+
+Search is free, with three numbered results per page and up to two free preview photos. A $10 Rental Pass supplies three distinct property unlocks for 14 days. Payment confirmation preserves the selected property and offers View property now or Continue browsing. Viewing an already unlocked home uses no additional credit. Full details include the gallery, optional `video_url`, `rental_requirements` and provider information. Missing video or requirements are handled without inventing content.
+
+A $5 viewing request explains the $2 provider / $3 platform split. Successful simulated payment creates an appointment-pending request for operations to coordinate. It does not claim that a viewing time is booked. Provider contact is shared in that confirmation. Property questions enter the existing support collection.
+
+Payments remain spoofed. The user explicitly confirms a demo payment; no EcoCash transfer or live payment integration occurs.
+
+## Verification
+
+Run `python -m unittest test_flows -q`. The conversation tests use local memory and mocked outbound messages, with no Firebase, Gemini, WhatsApp or payment calls. Deploy bot changes together with the admin API and UI updates that persist optional gallery/video/requirements fields.

main.py

@@ -105,11 +105,11 @@ WELCOME = (
 
 MAIN_OPTS = ["Find a place to rent", "List my property", "Talk to support"]
 
-FIND_TYPES = ["Single Room", "Cottage", "1 Bedroom", "2 Bedroom"]
-FIND_AREAS = ["Westgate", "Avondale", "Borrowdale", "Kuwadzana", "Glen View", "Hatcliffe", "Epworth", "Any area"]
+FIND_TYPES = ["Single Room", "Cottage / Garden Flat", "1 Bedroom", "2 Bedroom", "House / Townhouse"]
+FIND_AREAS = ["Mount Pleasant", "Avondale", "Borrowdale", "Westgate", "Highlands", "Hatcliffe", "Other (type suburb)", "Any area"]
 FIND_BUDGETS = [("Under $200", 200), ("$200 - $400", 400), ("$400 - $600", 600),
-                ("$600 - $800", 800), ("Above $800", 0), ("Any budget", 0)]
-FIND_AMENS = ["Solar", "Borehole", "Parking", "Furnished", "Walled", "Pet friendly", "None of these"]
+                ("$600 - $800", 800), ("Over $800", 0), ("Any (show all)", 0)]
+FIND_AMENS = ["Borehole", "Solar", "Parking", "Ensuite", "Pet friendly", "Gated community", "None", "Other (type)"]
 PAGE = 3
 
 
@@ -142,74 +142,136 @@ def my_account_text(phone: str) -> str:
 
 # ── Finder + landlord + support flows (story order) ─────────────────
 def start_find(m: str, prefill: Optional[Dict] = None) -> None:
-    """Guided search. Every step accepts a number OR free text."""
     d = {"type": "", "suburb": "", "max_budget": 0, "amenities": []}
-    if prefill:
-        d.update({k: v for k, v in prefill.items() if v})
-    if not d.get("type"):
-        wa.send_text_message(
-            m, "Great. Let's find your next home.\n"
-               "You can type your requirements naturally (e.g. 2 bedroom in Westgate under $400) "
-               "or answer step by step.")
-        wa.send_buttons_as_text(m, "What type of property are you looking for?", FIND_TYPES)
-        set_s(m, {"menu": "find", "step": "type", "data": d})
+    if prefill is None:
+        wa.send_buttons_as_text(m,
+            "Great! Let's find your next home.\nChoose step by step, or type naturally at any time.\n"
+            'Example: "1 bed cottage in Mount Pleasant with borehole, solar and parking under $400".',
+            ["Step by step", "Type my preferences"])
+        set_s(m, {"menu": "find", "step": "mode", "data": d})
         return
+    d.update(prefill)
     _find_next(m, d)
 
 
 def _find_next(m: str, d: Dict) -> None:
-    if not d.get("suburb"):
-        wa.send_buttons_as_text(m, "Which area are you interested in? Type any suburb or pick one.", FIND_AREAS)
-        set_s(m, {"menu": "find", "step": "suburb", "data": d})
-    elif not d.get("max_budget"):
-        wa.send_buttons_as_text(m, "Maximum monthly budget (USD)? Pick a range or type an amount.",
-                                [b[0] for b in FIND_BUDGETS])
-        set_s(m, {"menu": "find", "step": "budget", "data": d})
+    if not d.get("type"):
+        step, prompt, options = "type", "Step 1 of 4: What type of home are you looking for?", FIND_TYPES
+    elif not d.get("suburb") and not d.get("area_chosen"):
+        step, prompt, options = "suburb", "Step 2 of 4: Which area? You can type any suburb.", FIND_AREAS
+    elif not d.get("max_budget") and not d.get("budget_chosen"):
+        step, prompt, options = "budget", "Step 3 of 4: What's your monthly budget (USD)? Or type an amount.", [b[0] for b in FIND_BUDGETS]
+    elif not d.get("features_chosen"):
+        step, prompt, options = "amen", "Step 4 of 4: Any preferred features? Reply 1,2,3 or 123, type features, or SKIP.", FIND_AMENS
     else:
-        wa.send_buttons_as_text(
-            m, "Any must-have features? Reply numbers together (e.g. 1,3), type a list, or pick None.",
-            FIND_AMENS)
-        set_s(m, {"menu": "find", "step": "amen", "data": d})
+        _finish_find(m, d)
+        return
+    wa.send_buttons_as_text(m, prompt, options)
+    set_s(m, {"menu": "find", "step": step, "data": d})
 
 
 def _finish_find(m: str, d: Dict) -> None:
-    p = U.get_profile(m)
-    prefs = {"type": d.get("type", ""), "suburb": d.get("suburb", ""),
-             "max_budget": d.get("max_budget", 0), "amenities": d.get("amenities", [])}
-    roles = sorted(set(p.get("roles", []) + ["seeker"]))
-    U.save_profile(m, {"roles": roles, "prefs": prefs})
-    show_results(m, prefs)
+    """Confirm our understanding before running a search."""
+    d = {**d, "features_chosen": True}
+    budget = (f"${d.get('min_budget', 0):g} - ${d['max_budget']:g}/month" if d.get("max_budget")
+              else "Over $800/month" if d.get("min_budget") else "Any budget")
+    wa.send_buttons_as_text(m,
+        "*Here's what I'm looking for:*\n"
+        f"Home: {d.get('type') or 'Any type'}\nArea: {d.get('suburb') or 'Any area'}\n"
+        f"Budget: {budget}\nFeatures: {', '.join(d.get('amenities', [])) or 'No preference'}\n\n"
+        "Shall I search for properties that match this? You can also type new preferences.",
+        ["Search now", "Change requirements"])
+    set_s(m, {"menu": "find", "step": "summary", "data": d})
 
 
 def handle_find(m: str, text: str, s: Dict) -> bool:
-    """Guided steps. Free text at any step jumps straight to results."""
-    step, d = s.get("step", ""), s.get("data", {})
+    step, d = s.get("step", ""), dict(s.get("data", {}))
     t = text.strip()
-    # Natural input escapes the rails anywhere
-    if step != "amen" and U.looks_like_search(t) and len(t.split()) > 2:
-        d.update({k: v for k, v in U.parse_search(t).items() if v})
-        logger.info(f"STEP find-nl from={m} crit={d}")
-        if d.get("type") and d.get("suburb") and d.get("max_budget"):
-            _finish_find(m, d)
+    low = t.lower()
+    if step == "summary":
+        if low in ("1", "search now", "search", "yes"):
+            prefs = {k: d.get(k, default) for k, default in
+                     (("type", ""), ("suburb", ""), ("min_budget", 0), ("max_budget", 0), ("amenities", []))}
+            p = U.get_profile(m)
+            U.save_profile(m, {"roles": sorted(set(p.get("roles", []) + ["seeker"])), "prefs": prefs})
+            show_results(m, prefs)
+            return True
+        if low in ("2", "change requirements", "change", "edit"):
+            wa.send_buttons_as_text(m, "What would you like to change?", ["Property type", "Location", "Budget", "Features", "Start over"])
+            set_s(m, {"menu": "find", "step": "edit", "data": d})
+            return True
+    if step == "edit":
+        choice = _pick(t, ["Property type", "Location", "Budget", "Features", "Start over"], "edit")
+        if choice == "Start over":
+            start_find(m, {})
+            return True
+        keys = {"Property type": ("type",), "Location": ("suburb", "area_chosen"),
+                "Budget": ("min_budget", "max_budget", "budget_chosen"), "Features": ("features_chosen",)}
+        if choice in keys:
+            for key in keys[choice]:
+                d.pop(key, None)
+            _find_next(m, d)
+            return True
+    # Natural descriptions work in every finder step, including preferences and summary.
+    if not t.isdigit() and len(t.split()) > 2 and U.looks_like_search(t):
+        parsed = U.parse_search(t)
+        d.update({k: v for k, v in parsed.items() if v})
+        if parsed.get("max_budget"):
+            d["min_budget"] = parsed.get("min_budget", 0)
+        if parsed.get("amenities"):
+            d["features_chosen"] = True
+        _find_next(m, d)
+        return True
+    if step == "mode":
+        if low in ("1", "step by step"):
+            _find_next(m, d)
+        elif low in ("2", "type my preferences"):
+            wa.send_text_message(m, "Tell me the type, area, monthly budget and features you want. Reply BACK for step by step.")
+            set_s(m, {"menu": "find", "step": "natural", "data": d})
+        else:
+            wa.send_text_message(m, "Reply 1 for step by step, or type your preferences.")
+        return True
+    if step == "natural":
+        if low == "back":
+            _find_next(m, d)
         else:
-            start_find(m, prefill=d)
+            start_find(m, U.parse_search(t))
         return True
     if step == "type":
-        d["type"] = _pick(t, FIND_TYPES, "type")
-        _find_next(m, d)
+        chosen = _pick(t, FIND_TYPES, "type")
+        if t.isdigit() and not 1 <= int(t) <= len(FIND_TYPES):
+            wa.send_text_message(m, "Choose a property type from 1 to 5, or type a home type.")
+            return True
+        d["type"] = {"Cottage / Garden Flat": "cottage", "House / Townhouse": "house"}.get(chosen, chosen)
     elif step == "suburb":
-        d["suburb"] = "" if t.lower() in ("8", "any area", "any") else _pick(t, FIND_AREAS, "suburb")
-        if d["suburb"] == "Any Area":
-            d["suburb"] = ""
-        _find_next(m, d)
+        if low in ("7", "other", "other (type suburb)"):
+            wa.send_text_message(m, "Type the suburb you'd like.")
+            return True
+        d["suburb"] = "" if low in ("8", "any area", "any") else _pick(t, FIND_AREAS, "suburb")
+        d["area_chosen"] = True
     elif step == "budget":
-        d["max_budget"] = _pick_budget(t)
-        _find_next(m, d)
+        if low in ("6", "any", "any budget", "any (show all)"):
+            d.update(max_budget=0, min_budget=0)
+        elif low in ("5", "over $800", "above $800"):
+            d.update(max_budget=0, min_budget=800.01)
+        else:
+            choice = int(t)-1 if t.isdigit() and 1 <= int(t) <= 4 else None
+            lo, hi = U.parse_budget(t) if choice is None else (choice * 200, FIND_BUDGETS[choice][1])
+            if not hi or hi <= 0:
+                wa.send_text_message(m, "Choose a budget option or type a positive amount, e.g. 350.")
+                return True
+            d.update(max_budget=hi, min_budget=lo or 0)
+        d["budget_chosen"] = True
     elif step == "amen":
+        if low in ("8", "other", "other (type)"):
+            wa.send_text_message(m, "Type your preferred features, or SKIP.")
+            return True
         d["amenities"] = _pick_multi(t, FIND_AMENS)
-        _finish_find(m, d)
+        d["features_chosen"] = True
     else:
-        return False
+        wa.send_text_message(m, "Reply with an option above or type your new preferences.")
+        return True
+    _find_next(m, d)
     return True
 
 
@@ -241,19 +303,19 @@ def _pick_multi(t: str, opts: list) -> list:
     if t.lower() in ("none", "none of these", "7", "skip"):
         return []
     out = []
-    for part in re.split(r"[, ]+", t):
+    for part in (list(t) if t.isdigit() and len(t) > 1 else re.split(r"[, ]+", t)):
         part = part.strip()
         if part.isdigit() and 1 <= int(part) <= len(opts):
             o = opts[int(part) - 1]
-            if o != "None of these" and o not in out:
+            if o not in ("None", "None of these", "Other (type)") and o not in out:
                 out.append(o)
         elif part:
             hit = next((o for o in opts if part.lower() in o.lower()), None)
-            if hit and hit != "None of these" and hit not in out:
+            if hit and hit not in ("None", "None of these", "Other (type)") and hit not in out:
                 out.append(hit)
     if not out and t.lower() not in ("none",):
         c = U.parse_search(t)
-        out = [a.title() for a in c["amenities"]]
+        out = [a.title() for a in c["amenities"]] or [t]
     return out
 
 
@@ -270,12 +332,14 @@ def start_create_listing(m: str) -> None:
 def story_results_text(res: list, shown: int) -> str:
     lines = []
     for i, r in enumerate(res[:shown], 1):
-        lines.append(U.format_preview(r, i, r["_score"], r["_reasons"]))
+        if not r:
+            continue
+        lines.append(U.format_preview(r, i, r.get("_score"), r.get("_reasons")))
         lines.append("")
     left = len(res) - shown
     if left > 0:
         lines.append(f"_View more properties ({left} remaining): reply MORE_")
-    lines.append("Reply a number for details, UNLOCK n for full photos, NEW for a new search.")
+    lines.append("Reply a property number for a free preview, UNLOCK n to unlock, MORE for more homes, or NEW to search.")
     return "\n".join(lines)
 
 
@@ -286,40 +350,55 @@ def show_results(m: str, crit: Dict) -> None:
         set_s(m, {"menu": "browse", "results": [], "shown": 0, "criteria": crit})
         return
     wa.send_text_message(m, U.gemini_ack_search(crit, len(res)))
-    exact = [r for r in res if r["_score"] >= 50]
-    note = f"{len(exact)} exact matches" if exact else f"{len(res)} matches"
-    near = len(res) - len(exact)
-    if near > 0:
-        note += f" + {near} nearby alternatives"
-    wa.send_text_message(m, f"*{note}.*\nYour search: {crit.get('type','Any')} in {crit.get('suburb','Any area')}"
-                            + (f" up to ${int(crit['max_budget'])}" if crit.get("max_budget") else ""))
+    wa.send_text_message(m, f"I found {len(res)} matching properties. Here are the first {min(PAGE, len(res))}.")
     shown = min(PAGE, len(res))
-    wa.send_text_message(m, story_results_text(res, shown))
+    send_result_page(m, res, 0, shown)
     set_s(m, {"menu": "browse", "results": [r["id"] for r in res], "shown": shown, "criteria": crit})
 
 
+def send_result_page(m: str, results: list, start: int, end: int) -> None:
+    for index in range(start, end):
+        item = results[index]
+        if not item:
+            continue
+        caption = U.format_preview(item, index + 1)
+        photos = item.get("media") or []
+        if not photos or not wa.send_image_message(m, photos[0], caption):
+            wa.send_text_message(m, caption)
+    wa.send_text_message(m, "Reply a property number for a free preview. UNLOCK n for full details with a $10 Rental Pass.\n"
+                            + ("MORE for more homes. " if end < len(results) else "") + "NEW for a new search.")
+
+
 def show_detail(m: str, lid: str, n: int) -> None:
     item = U.get_listing(lid)
     if not item:
         wa.send_text_message(m, "That home just left the market. Reply MORE for others.")
         return
+    s = get_s(m) or {}
+    set_s(m, {**s, "menu": "browse", "detail": lid, "detail_n": n, "screen": "preview"})
     if U.is_unlocked(m, lid):
         send_full_details(m, item, n)
         return
-    wa.send_text_message(m, U.format_preview(item, n, None, None))
-    wa.send_buttons_as_text(m, "Full photos, video and landlord contact are locked.",
-                            [f"Unlock {n}", "Back to results"])
+    wa.send_text_message(m, U.format_preview(item, n))
+    for url in (item.get("media") or [])[:2]:
+        wa.send_image_message(m, url, "Free preview")
+    wa.send_buttons_as_text(m,
+        "More available after unlock: full photo gallery, video (where available), description, rental requirements and provider information.",
+        ["Unlock property", "Back to results"])
 
 
 def send_full_details(m: str, item: Dict, n: int = 0) -> None:
-    wa.send_text_message(m, f"Property unlocked.\n\n{U.format_full(item)}")
-    for url in (item.get("media") or [])[:3]:
+    ap = U.active_pass(m)
+    left = ap["credits_total"] - ap["credits_used"] if ap else 0
+    wa.send_text_message(m, f"*{left} of 3 unlocks remaining*\n\n{U.format_full(item)}")
+    for url in (item.get("media") or []):
         wa.send_image_message(m, url, item.get("title", ""))
-    wa.send_buttons_as_text(
-        m, "Want to see it in person? $5. Our team coordinates with the landlord.",
-        [f"Request Viewing - $5", "Back to results", "Save property"])
+    if item.get("video_url"):
+        wa.send_document_message(m, doc_url=item["video_url"], caption="Video walkthrough")
+    wa.send_buttons_as_text(m, "Want to see it in person? RentNow coordinates your viewing.",
+                            ["Request viewing - $5", "Back to results", "Ask a question", "Save property"])
     s = get_s(m) or {}
-    set_s(m, {**s, "menu": "browse", "detail": item["id"], "detail_n": n,
+    set_s(m, {**s, "menu": "browse", "detail": item["id"], "detail_n": n, "screen": "full",
               "results": s.get("results", []), "shown": s.get("shown", PAGE),
               "criteria": s.get("criteria", {})})
 
@@ -364,6 +443,7 @@ def handle_need_name(m: str, text: str, s: Dict) -> bool:
     pend = s.get("pending", {})
     lid = pend.get("pending_unlock", "")
     if lid:
+        set_s(m, pend)
         buy_pass(m, pending_unlock=lid)
         return True
     set_s(m, pend if pend.get("menu") else {"menu": "main"})
@@ -500,42 +580,74 @@ def buy_pass(m: str, pending_unlock: str = "") -> None:
     wa.send_text_message(
         m, f"{head}"
            "Unlock 3 properties. Full photos, video and details. Valid for 14 days.\n"
-           "Simple and secure payment via EcoCash.\n\n"
+           "Includes rental requirements and provider information. Use unlocks on any properties.\n"
+           "One-off pass. No subscription. You can continue browsing free.\n\n"
            f"{U.ecocash_instructions(pay)}")
-    wa.send_buttons_as_text(m, "After paying:", ["Payment done", "Cancel"])
-    st: Dict = {"menu": "await_pay", "payment_id": pay["id"], "kind": "rental_pass"}
+    wa.send_buttons_as_text(m, "Demo payment. No money is charged.", ["Pay with EcoCash (demo)", "Continue browsing"])
+    st: Dict = {**(get_s(m) or {}), "menu": "await_pay", "payment_id": pay["id"], "kind": "rental_pass"}
     if pending_unlock:
         st["pending_unlock"] = pending_unlock
     set_s(m, st)
 
 
 def buy_viewing(m: str, listing_id: str) -> None:
+    if not U.is_unlocked(m, listing_id):
+        wa.send_text_message(m, "Unlock this property before requesting a viewing.")
+        return
     pay = U.create_payment(m, "viewing", U.VIEWING_FEE_CENTS, {"listing_id": listing_id})
-    wa.send_text_message(m, f"*Physical viewing $5* for [{listing_id}].\n$2 goes to the landlord, $3 to the platform. Our team coordinates the appointment.\n\n{U.ecocash_instructions(pay)}")
-    wa.send_buttons_as_text(m, "After paying:", ["Payment done", "Cancel"])
-    set_s(m, {"menu": "await_pay", "payment_id": pay["id"], "kind": "viewing", "listing_id": listing_id})
+    wa.send_text_message(m, f"*Physical viewing $5* for [{listing_id}].\n$2 goes to the landlord, $3 to the platform. Our team confirms availability, sends the provider your request and coordinates the date and time. Provider contact details are shared after payment.\n\n{U.ecocash_instructions(pay)}")
+    wa.send_buttons_as_text(m, "Demo payment. No money is charged.", ["Pay with EcoCash (demo)", "Continue browsing"])
+    set_s(m, {**(get_s(m) or {}), "menu": "await_pay", "payment_id": pay["id"], "kind": "viewing", "listing_id": listing_id})
 
 
 def handle_browse(m: str, text: str, s: Dict) -> bool:
     t = text.strip().lower()
+    if t.isdigit() and s.get("screen") in ("preview", "full"):
+        options = ["unlock property", "back to results"] if s["screen"] == "preview" else ["request viewing", "back to results", "ask a question", "save property"]
+        if 1 <= int(t) <= len(options):
+            t = options[int(t) - 1]
     ids = s.get("results", [])
     shown = s.get("shown", PAGE)
     if t in ("new", "new search"):
         start_find(m)
         return True
     if t in ("more", "view more", "view more properties"):
-        shown = min(len(ids), shown + PAGE)
-        wa.send_text_message(m, story_results_text([U.get_listing(i) for i in ids], shown))
-        set_s(m, {**s, "shown": shown})
+        end = min(len(ids), shown + PAGE)
+        send_result_page(m, [U.get_listing(i) for i in ids], shown, end)
+        set_s(m, {**s, "shown": end, "screen": "results"})
         return True
     if t in ("back", "back to results"):
         wa.send_text_message(m, story_results_text([U.get_listing(i) for i in ids], shown))
-        set_s(m, {**s, "detail": "", "detail_n": 0})
+        set_s(m, {**s, "detail": "", "detail_n": 0, "screen": "results"})
         return True
-    if t in ("pass", "get rental pass", "rental pass", "payment done", "1"):
+    if t in ("pass", "get rental pass", "rental pass", "payment done"):
         buy_pass(m)
         return True
-    # Button labels from detail cards (Twilio has no tap-to-action)
+    if t in ("view property now", "continue browsing"):
+        lid = s.get("pending_unlock")
+        if t == "view property now" and lid:
+            return handle_browse(m, f"unlock {_num_of(s, lid)}", {**s, "screen": "results"})
+        wa.send_text_message(m, story_results_text([U.get_listing(i) for i in ids], shown))
+        set_s(m, {**s, "screen": "results"})
+        return True
+    if s.get("screen") == "pass_ready" and t in ("1", "2"):
+        return handle_browse(m, "view property now" if t == "1" else "continue browsing", s)
+    if t in ("ask a question", "back to property") and s.get("detail"):
+        if t == "back to property":
+            show_detail(m, s["detail"], s.get("detail_n", 0))
+        else:
+            wa.send_text_message(m, "Type your question. Our team will help with this property.")
+            set_s(m, {**s, "screen": "question"})
+        return True
+    if s.get("screen") == "question":
+        if U.db:
+            U.db.collection("rentnow_support").add({"phone": m, "listing_id": s["detail"], "issue": text, "ts": U._now(), "status": "open"})
+        else:
+            U._mem[f"question:{uuid.uuid4().hex}"] = {"phone": m, "listing_id": s["detail"], "issue": text}
+        wa.send_text_message(m, "Question received. Our team will reply here. Reply BACK TO PROPERTY to return.")
+        set_s(m, {**s, "screen": "full"})
+        return True
+    # Resolve numbered text-menu actions within the current property screen.
     det_id = s.get("detail", "")
     if "request viewing" in t and det_id:
         if not U.is_unlocked(m, det_id):
@@ -607,19 +719,7 @@ def handle_browse(m: str, text: str, s: Dict) -> bool:
         n = int(t)
         if 1 <= n <= len(ids):
             show_detail(m, ids[n - 1], n)
-            set_s(m, {**s, "detail": ids[n - 1], "detail_n": n})
             return True
-        # number answers inside detail options map to option rows
-        det = s.get("detail_n") or 0
-        if det and n in (1, 2, 3):
-            lid = ids[det - 1]
-            if n == 1:
-                return handle_browse(m, f"unlock {det}", s)
-            if n == 2:
-                return handle_browse(m, "back", s)
-            if n == 3 and U.is_unlocked(m, lid):
-                buy_viewing(m, lid)
-                return True
     return False
 
 
@@ -652,6 +752,10 @@ def _process_text_inner(text: str, mobile: str) -> None:
     low = text.strip().lower()
     logger.info(f"STEP route from={mobile} session={(s or {}).get('menu')}/{str((s or {}).get('step'))}")
 
+    if low in ("menu", "start"):
+        send_welcome(mobile)
+        return
+
     if GREET.match(text.strip()) and (not s or s.get("menu") in ("main", "post_reg")):
         logger.info(f"STEP welcome from={mobile}")
         send_welcome(mobile)
@@ -707,7 +811,7 @@ def _process_text_inner(text: str, mobile: str) -> None:
                 return
         if menu == "await_pay":
             logger.info(f"STEP pay-confirm from={mobile} kind={s.get('kind')} low={low!r}")
-            if low in ("1", "payment done", "i have paid", "paid", "confirm", "pay"):
+            if low in ("1", "payment done", "i have paid", "paid", "confirm", "pay", "pay with ecocash (demo)"):
                 pay = U.confirm_payment_spoof(s["payment_id"], text)
                 logger.info(f"STEP pay-status from={mobile} pay={(pay or {}).get('id')} status={(pay or {}).get('status')}")
                 if not pay or pay.get("status") != "confirmed":
@@ -716,29 +820,26 @@ def _process_text_inner(text: str, mobile: str) -> None:
                 if s.get("kind") == "rental_pass":
                     p = U.issue_pass(mobile, pay["id"])
                     left = p["credits_total"] - p["credits_used"]
-                    wa.send_text_message(mobile, f"Great! Your Home Seeker Pass is active. You have {left} property unlocks remaining.")
-                    lid = s.get("pending_unlock", "")
-                    if lid and U.get_listing(lid):
-                        ok, msg = U.consume_unlock(mobile, lid)
-                        logger.info(f"STEP auto-unlock from={mobile} lid={lid} ok={ok}")
-                        if ok:
-                            item = U.get_listing(lid)
-                            n = _num_of(s, lid)
-                            send_full_details(mobile, item, n)
-                            wa.send_text_message(mobile, f"_{msg}_")
-                            return
-                    clear_s(mobile)
-                    start_find(mobile)
+                    wa.send_text_message(mobile, f"Payment successful (demo). Your $10 Rental Pass is active.\n{left} property unlocks available, valid for 14 days.")
+                    set_s(mobile, {**s, "menu": "browse", "screen": "pass_ready"})
+                    if s.get("pending_unlock"):
+                        wa.send_buttons_as_text(mobile, "View the property you selected, or keep browsing free.", ["View property now", "Continue browsing"])
+                    else:
+                        wa.send_text_message(mobile, "Reply CONTINUE BROWSING or NEW to find a property.")
                 else:
                     v = U.create_viewing(mobile, s.get("listing_id", ""), pay["id"])
-                    clear_s(mobile)
-                    wa.send_text_message(mobile, f"Viewing booked [{v['id']}]. Our team will coordinate with the landlord and confirm the time here.")
+                    item = U.get_listing(s.get("listing_id", "")) or {}
+                    set_s(mobile, {**s, "menu": "browse", "screen": "full"})
+                    wa.send_text_message(mobile, f"Viewing request paid (demo) [{v['id']}]. Our team will send your request to the provider and confirm the appointment date and time here.\n"
+                                                f"Provider: {item.get('provider_name') or 'Contact RentNow'} {item.get('provider_phone') or ''}\nReply BACK TO PROPERTY or ASK A QUESTION.")
                 return
-            if low in ("2", "cancel"):
-                clear_s(mobile)
-                wa.send_text_message(mobile, "Cancelled. Reply MENU anytime.")
+            if low in ("2", "cancel", "continue browsing"):
+                set_s(mobile, {**s, "menu": "browse", "screen": "results"})
+                wa.send_text_message(mobile, "Payment cancelled. You can keep browsing free.")
+                wa.send_text_message(mobile, story_results_text([U.get_listing(i) for i in s.get("results", [])], s.get("shown", PAGE)))
                 return
-            logger.info(f"STEP pay-unmatched from={mobile}")
+            wa.send_text_message(mobile, "Reply 1 to simulate payment or 2 to continue browsing free.")
+            return
 
     # keyword shortcuts (no session)
     logger.info(f"STEP shortcuts from={mobile} low={low!r}")

test_flows.py

@@ -0,0 +1,204 @@
+"""Conversation regressions. No credentials, network calls or real payments."""
+import os
+import unittest
+from unittest.mock import patch
+
+os.environ.pop('FIREBASE', None)
+os.environ.pop('GOOGLE_API_KEY', None)
+with patch('dotenv.load_dotenv'):
+    import main as bot
+import utility as U
+import whatsapp_client as wa
+
+
+class RentalFlows(unittest.TestCase):
+    def setUp(self):
+        self.phone = '+263770000099'
+        U.db = None
+        U._mem.clear()
+        self.messages = []
+        self.images = []
+        self.patches = [
+            patch.object(wa, 'send_text_message', side_effect=lambda m, text: self.messages.append(text) or True),
+            patch.object(wa, 'send_image_message', side_effect=lambda m, url, caption='': self.images.append((url, caption)) or True),
+            patch.object(wa, 'send_document_message', return_value=True),
+            patch.object(U, 'gemini_ack_search', return_value='Matching homes'),
+            patch.object(U, 'gemini_detect_intent', return_value={'intent': 'SEARCH', 'criteria': {}}),
+        ]
+        bot.logger.disabled = True
+        for p in self.patches:
+            p.start()
+            self.addCleanup(p.stop)
+
+    def say(self, text):
+        bot._process_text_inner(text, self.phone)
+        return bot.get_s(self.phone)
+
+    def browse(self):
+        U.save_profile(self.phone, {'name': 'Test Renter'})
+        bot.show_results(self.phone, {})
+        return bot.get_s(self.phone)
+
+    def test_all_text_menu_options_visible(self):
+        wa.send_buttons_as_text(self.phone, 'Features', bot.FIND_AMENS)
+        self.assertIn('8. Other (type)', self.messages[-1])
+
+    def test_guided_any_choices_reach_summary(self):
+        self.say('menu')
+        self.say('1')
+        self.assertEqual(self.say('1')['step'], 'type')
+        self.assertEqual(self.say('2')['step'], 'suburb')
+        self.assertEqual(self.say('8')['step'], 'budget')
+        self.assertEqual(self.say('6')['step'], 'amen')
+        state = self.say('skip')
+        self.assertEqual(state['step'], 'summary')
+        self.assertEqual(state['data']['type'], 'cottage')
+        self.assertEqual(self.say('1')['menu'], 'browse')
+
+    def test_budget_range_preserves_lower_bound(self):
+        bot.start_find(self.phone, {'type': 'cottage', 'suburb': 'Avondale'})
+        self.say('2')
+        state = self.say('7')
+        self.assertEqual(state['data']['min_budget'], 200)
+        self.assertEqual(state['data']['max_budget'], 400)
+
+    def test_over_800_has_no_upper_bound(self):
+        bot.start_find(self.phone, {'type': 'house', 'suburb': 'Harare'})
+        self.assertEqual(self.say('5')['step'], 'amen')
+        state = self.say('7')
+        self.assertGreater(state['data']['min_budget'], 800)
+        self.assertEqual(state['data']['max_budget'], 0)
+
+    def test_compact_features(self):
+        self.assertEqual(bot._pick_multi('123', bot.FIND_AMENS), ['Borehole', 'Solar', 'Parking'])
+        self.assertEqual(bot._pick_multi('7', bot.FIND_AMENS), [])
+
+    def test_natural_input_from_feature_step(self):
+        bot.start_find(self.phone, {'type': 'cottage', 'suburb': 'Westgate', 'max_budget': 400})
+        state = self.say('1 bed cottage in Mount Pleasant with borehole solar parking under $400')
+        self.assertEqual(state['step'], 'summary')
+        self.assertEqual(state['data']['type'], 'cottage')
+        self.assertEqual(state['data']['suburb'], 'Mount Pleasant')
+        self.assertEqual(len(state['data']['amenities']), 3)
+
+    def test_edit_budget_returns_to_summary(self):
+        bot._finish_find(self.phone, {'type': 'cottage', 'suburb': 'Avondale', 'max_budget': 400, 'features_chosen': True})
+        self.say('2')
+        self.assertEqual(self.say('3')['step'], 'budget')
+        state = self.say('350')
+        self.assertEqual(state['step'], 'summary')
+        self.assertEqual(state['data']['max_budget'], 350)
+
+    def test_first_result_is_free_preview(self):
+        self.browse()
+        state = self.say('1')
+        self.assertEqual(state['screen'], 'preview')
+        self.assertFalse(any(k.startswith('pay:') for k in U._mem))
+        self.assertTrue(self.images)
+
+    def test_payment_then_selected_unlock_and_repeat_preview(self):
+        original = self.browse()
+        lid = original['results'][0]
+        self.say('1')
+        state = self.say('1')
+        self.assertEqual(state['menu'], 'await_pay')
+        self.assertEqual(state['results'], original['results'])
+        state = self.say('1')
+        self.assertEqual(state['screen'], 'pass_ready')
+        self.assertEqual(U.active_pass(self.phone)['credits_used'], 0)
+        state = self.say('1')
+        self.assertEqual(state['screen'], 'full')
+        self.assertTrue(U.is_unlocked(self.phone, lid))
+        self.assertEqual(U.active_pass(self.phone)['credits_used'], 1)
+        self.say('back to results')
+        self.say('1')
+        self.assertEqual(U.active_pass(self.phone)['credits_used'], 1)
+
+    def test_account_capture_retains_selected_property(self):
+        bot.show_results(self.phone, {})
+        original = bot.get_s(self.phone)
+        self.assertEqual(self.say('unlock 2')['menu'], 'need_name')
+        state = self.say('Test Renter')
+        self.assertEqual(state['menu'], 'await_pay')
+        self.assertEqual(state['results'], original['results'])
+        self.assertEqual(state['pending_unlock'], original['results'][1])
+
+    def test_cancel_preserves_results_without_pass(self):
+        original = self.browse()
+        self.say('unlock 2')
+        state = self.say('2')
+        self.assertEqual(state['menu'], 'browse')
+        self.assertEqual(state['results'], original['results'])
+        self.assertIsNone(U.active_pass(self.phone))
+
+    def test_continue_after_pass_does_not_consume_credit(self):
+        self.browse()
+        self.say('unlock 2')
+        self.say('1')
+        state = self.say('2')
+        self.assertEqual(state['screen'], 'results')
+        self.assertEqual(U.active_pass(self.phone)['credits_used'], 0)
+
+    def test_full_gallery_and_viewing_request(self):
+        original = self.browse()
+        lid = original['results'][0]
+        self.say('unlock 1')
+        self.say('1')
+        self.say('1')
+        state = self.say('1')
+        self.assertEqual(state['kind'], 'viewing')
+        self.assertEqual(U._mem['pay:' + state['payment_id']]['amount_cents'], 500)
+        self.assertIn('$2 goes to the landlord', '\n'.join(self.messages))
+        state = self.say('1')
+        self.assertEqual(state['menu'], 'browse')
+        viewings = [v for k, v in U._mem.items() if k.startswith('view:')]
+        self.assertEqual(len(viewings), 1)
+        self.assertEqual(viewings[0]['status'], 'paid_appointment_pending')
+        self.assertEqual(viewings[0]['listing_id'], lid)
+
+    def test_locked_property_cannot_buy_viewing(self):
+        self.browse()
+        self.say('1')
+        self.say('request viewing')
+        self.assertFalse(any(k.startswith('pay:') for k in U._mem))
+
+    def test_more_handles_listing_without_ranking(self):
+        self.browse()
+        state = self.say('more')
+        self.assertEqual(state['shown'], 6)
+        self.say('back')
+        self.assertIn('NEW', self.messages[-1])
+
+    def test_constraints_filter_all_required_features_and_minimum(self):
+        fixture = [dict(id='a', type='cottage', suburb='Mt Pleasant', rent_cents=35000, amenities=['solar', 'parking']),
+                   dict(id='b', type='cottage', suburb='Mount Pleasant', rent_cents=15000, amenities=['solar']),
+                   dict(id='c', type='cottage', suburb='Mount Pleasant', rent_cents=85000, amenities=['solar', 'parking'])]
+        with patch.object(U, 'get_listings', return_value=fixture):
+            rows = U.search_listings({'suburb': 'Mount Pleasant', 'min_budget': 200, 'max_budget': 400, 'amenities': ['solar', 'parking']})
+        self.assertEqual([r['id'] for r in rows], ['a'])
+
+    def test_unknown_suburb_and_other_features(self):
+        bot.start_find(self.phone, {'type': 'cottage'})
+        self.say('7')
+        self.say('Chishawasha')
+        self.say('400')
+        self.say('8')
+        state = self.say('swimming pool')
+        self.assertEqual(state['step'], 'summary')
+        self.assertEqual(state['data']['amenities'], ['swimming pool'])
+
+    def test_pass_expires_and_exhausts(self):
+        from datetime import datetime, timezone, timedelta
+        p = U.issue_pass(self.phone, 'test-payment')
+        p['expires_at'] = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
+        self.assertIsNone(U.active_pass(self.phone))
+        p['expires_at'] = (datetime.now(timezone.utc) + timedelta(days=1)).isoformat()
+        for lid in ['a', 'b', 'c']:
+            self.assertTrue(U.consume_unlock(self.phone, lid)[0])
+        self.assertIsNone(U.active_pass(self.phone))
+        self.assertFalse(U.consume_unlock(self.phone, 'd')[0])
+        self.assertTrue(U.consume_unlock(self.phone, 'a')[0])
+
+
+if __name__ == '__main__':
+    unittest.main()

utility.py

@@ -79,7 +79,7 @@ VIEWING_FEE_CENTS = 500       # $5
 LANDLORD_SHARE_CENTS = 200    # $2
 PLATFORM_SHARE_CENTS = 300    # $3
 
-PROPERTY_TYPES = ["single room", "cottage", "1 bedroom", "2 bedroom"]
+PROPERTY_TYPES = ["single room", "cottage", "1 bedroom", "2 bedroom", "house"]
 AMENITIES = ["solar", "borehole", "tiled floors", "fitted kitchen", "parking",
              "security", "water", "electricity", "furnished", "wifi"]
 CITIES = ["Harare", "Bulawayo", "Mutare", "Gweru", "Victoria Falls"]
@@ -355,6 +355,8 @@ def admin_create_listing(data: Dict, reviewer: str = "admin") -> Dict:
                      else [a.strip() for a in (data.get("amenities") or "").split(",") if a.strip()],
         "media": data.get("media", []) if isinstance(data.get("media"), list)
                  else [u.strip() for u in (data.get("media") or "").split(",") if u.strip()],
+        "video_url": data.get("video_url", ""),
+        "rental_requirements": data.get("rental_requirements", ""),
         "status": "active", "verification": "verified",
         "created_by": reviewer, "created_at": _now(), "updated_at": _now(),
     }
@@ -396,7 +398,7 @@ def match_score(item: Dict, crit: Dict) -> Tuple[int, List[str]]:
     if want_type and want_type in (item.get("type") or "").lower():
         score += 30
         reasons.append("correct type")
-    suburb = (crit.get("suburb") or "").lower()
+    suburb = (crit.get("suburb") or "").lower().replace("mt pleasant", "mount pleasant")
     if suburb and suburb in (item.get("suburb") or "").lower():
         score += 25
         reasons.append("correct suburb")
@@ -423,19 +425,26 @@ def match_score(item: Dict, crit: Dict) -> Tuple[int, List[str]]:
 def search_listings(crit: Dict, limit: int = 5) -> List[Dict]:
     items = get_listings(active_only=True)
     want_type = (crit.get("type") or "").lower()
-    suburb = (crit.get("suburb") or "").lower()
+    suburb = (crit.get("suburb") or "").lower().replace("mt pleasant", "mount pleasant")
     try:
         max_b = float(crit.get("max_budget") or 0)
     except Exception:
         max_b = 0
+    min_b = float(crit.get("min_budget") or 0)
     ranked = []
     for it in items:
         if want_type and want_type not in (it.get("type") or "").lower():
             continue
-        if suburb and suburb not in (it.get("suburb") or "").lower():
+        if suburb and suburb not in (it.get("suburb") or "").lower().replace("mt pleasant", "mount pleasant"):
             continue
         if max_b and (it.get("rent_cents") or 0) / 100 > max_b:
             continue
+        if min_b and (it.get("rent_cents") or 0) / 100 < min_b:
+            continue
+        wants = [a.lower() for a in crit.get("amenities", [])]
+        haves = [a.lower() for a in it.get("amenities", [])]
+        if any(not any(a in h for h in haves) for a in wants):
+            continue
         s, reasons = match_score(it, crit)
         ranked.append({**it, "_score": s, "_reasons": reasons})
     ranked.sort(key=lambda x: (-x["_score"], x.get("rent_cents", 0)))
@@ -451,7 +460,10 @@ def format_preview(item: Dict, idx: int = 0, score: Optional[int] = None,
              f"  {', '.join(item.get('amenities', [])[:5])}"]
     if score is not None:
         lines.append(f"  _{score}% match — {', '.join((reasons or [])[:4])}_")
-    lines.append("  _Full photos locked. Unlock with Rental Pass._")
+    lines.append("  Property: " + ("Verified" if item.get("verification") == "verified" else "Verification pending"))
+    provider = get_profile(item.get("provider_phone", ""))
+    lines.append("  Provider: " + ("Verified" if (provider.get("landlord") or {}).get("verification") == "verified" else "Verification pending"))
+    lines.append("  _Free preview. Full details available with a $10 Rental Pass._")
     return "\n".join(lines)
 
 
@@ -463,7 +475,10 @@ def format_full(item: Dict) -> str:
              f"{item.get('description')}",
              f"Amenities: {', '.join(item.get('amenities', []))}",
              f"Verified: {'yes' if item.get('verification') == 'verified' else 'pending'}",
-             f"Photos: {len(item.get('media', []))} unlocked"]
+             f"Photos: {len(item.get('media', []))} unlocked",
+             f"Rental requirements: {item.get('rental_requirements') or item.get('requirements') or 'Ask RentNow for the provider requirements.'}",
+             f"Provider: {item.get('provider_name') or 'RentNow coordinates with the provider'}",
+             "Provider contact details are shared after the $5 viewing payment."]
     return "\n".join(lines)
 
 
@@ -516,8 +531,7 @@ def ecocash_instructions(pay: Dict) -> str:
         f"EcoCash (spoofed MVP):\n"
         f"Amount: *{cents_fmt(pay['amount_cents'])}*\n"
         f"Reference: *{pay['provider_ref']}*\n"
-        f"Dial *151*2*1*Merchant*Amount*Ref# on your EcoCash line.\n"
-        f"_Demo mode: tap 1 (I have paid). Wiring comes later._"
+        "Demo only. No money is charged. Reply 1 to simulate a successful EcoCash payment."
     )
 
 
@@ -895,18 +909,20 @@ def parse_budget(text: str) -> Tuple[Optional[float], Optional[float]]:
 
 SUBURBS = ["westgate", "avondale", "borrowdale", "mbare", "kuwadzana", "glen view",
            "hatcliffe", "epworth", "ruwa", "chitungwiza", "bulawayo", "cbd", "town",
-           "greendale", "mt pleasant", "chisipite", "highlands", "southerton"]
+           "greendale", "mount pleasant", "mt pleasant", "chisipite", "highlands", "southerton"]
 
 TYPE_KEYS = [
     ("2 bedroom", ["2 bedroom", "2 bedrooms", "2 bed", "two bedroom", "2bed"]),
     ("1 bedroom", ["1 bedroom", "1 bedrooms", "1 bed", "one bedroom", "1bed"]),
     ("cottage", ["cottage", "cottages"]),
+    ("house", ["house", "townhouse"]),
+    ("cottage", ["garden flat"]),
     ("single room", ["single room", "single rooms", "room", "rooms", "bedsitter"]),
 ]
 
 AMEN_KEYS = ["solar", "borehole", "parking", "furnished", "walled", "tiled",
              "secure", "security", "water", "electricity", "wifi", "fitted kitchen",
-             "pet friendly", "pets"]
+             "pet friendly", "pets", "ensuite", "gated community"]
 
 
 def parse_search(text: str) -> Dict:
@@ -918,7 +934,8 @@ def parse_search(text: str) -> Dict:
     t = (text or "").lower()
     crit: Dict = {"type": "", "suburb": "", "max_budget": 0, "amenities": []}
 
-    for canon, keys in TYPE_KEYS:
+    t = t.replace("mt pleasant", "mount pleasant")
+    for canon, keys in sorted(TYPE_KEYS, key=lambda pair: pair[0] != "cottage"):
         if any(k in t for k in keys):
             crit["type"] = canon
             break
@@ -940,6 +957,7 @@ def parse_search(text: str) -> Dict:
     else:
         rng = re.search(r"(\d[\d,]*)\s*[-\u2013]\s*(\d[\d,]*)", t)
         if rng:
+            crit["min_budget"] = float(rng.group(1).replace(",", ""))
             crit["max_budget"] = float(rng.group(2).replace(",", ""))
         else:
             nums = re.findall(r"\$\s*(\d[\d,]*)", t)

whatsapp_client.py

@@ -152,7 +152,7 @@ def send_audio_message(recipient_id: str, audio_url: str) -> bool:
 
 
 def send_buttons_as_text(recipient_id: str, body: str, options: list) -> bool:
-    safe = [str(o) for o in (options or []) if str(o).strip()][:3]
+    safe = [str(o) for o in (options or []) if str(o).strip()]
     lines = [body, ""]
     for i, opt in enumerate(safe, 1):
         lines.append(f"{i}. {opt}")