Sync from GitHub · 2026-10-22 23:15 UTC

bsa/questions.json

@@ -0,0 +1,448 @@
+{
+ "order": [
+  "ST",
+  "AN",
+  "LD",
+  "SA",
+  "MK",
+  "OP",
+  "FN"
+ ],
+ "stages": [
+  "I haven't started anything yet",
+  "I have an idea but haven't started",
+  "I've started and have early customers or sales (less than 2 years)",
+  "I've been in business for 2 to 3 years",
+  "I've been in business for 4 to 5 years",
+  "I've been in business for 6 to 9 years",
+  "I've been in business for 10 years or more"
+ ],
+ "ages": [
+  "Under 18",
+  "18 to 24",
+  "25 to 34",
+  "35 and above"
+ ],
+ "questions": [
+  {
+   "id": 1,
+   "naturalFit": "ST",
+   "dims": [
+    "ST",
+    "AN",
+    "SA",
+    "FN"
+   ]
+  },
+  {
+   "id": 2,
+   "naturalFit": "SA",
+   "dims": [
+    "ST",
+    "SA",
+    "MK",
+    "OP"
+   ]
+  },
+  {
+   "id": 3,
+   "naturalFit": "FN",
+   "dims": [
+    "OP",
+    "ST",
+    "FN",
+    "LD"
+   ]
+  },
+  {
+   "id": 4,
+   "naturalFit": "LD",
+   "dims": [
+    "OP",
+    "ST",
+    "MK",
+    "LD"
+   ]
+  },
+  {
+   "id": 5,
+   "naturalFit": "OP",
+   "dims": [
+    "OP",
+    "LD",
+    "FN",
+    "ST"
+   ]
+  },
+  {
+   "id": 6,
+   "naturalFit": "AN",
+   "dims": [
+    "OP",
+    "AN",
+    "FN",
+    "LD"
+   ]
+  },
+  {
+   "id": 7,
+   "naturalFit": "MK",
+   "dims": [
+    "OP",
+    "ST",
+    "MK",
+    "SA"
+   ]
+  },
+  {
+   "id": 8,
+   "naturalFit": "AN",
+   "dims": [
+    "FN",
+    "SA",
+    "MK",
+    "AN"
+   ]
+  },
+  {
+   "id": 9,
+   "naturalFit": "MK",
+   "dims": [
+    "MK",
+    "LD",
+    "SA",
+    "FN"
+   ]
+  },
+  {
+   "id": 10,
+   "naturalFit": "ST",
+   "dims": [
+    "OP",
+    "ST",
+    "LD",
+    "FN"
+   ]
+  },
+  {
+   "id": 11,
+   "naturalFit": "SA",
+   "dims": [
+    "FN",
+    "LD",
+    "SA",
+    "MK"
+   ]
+  },
+  {
+   "id": 12,
+   "naturalFit": "FN",
+   "dims": [
+    "AN",
+    "LD",
+    "MK",
+    "FN"
+   ]
+  },
+  {
+   "id": 13,
+   "naturalFit": "LD",
+   "dims": [
+    "LD",
+    "AN",
+    "MK",
+    "ST"
+   ]
+  },
+  {
+   "id": 14,
+   "naturalFit": "OP",
+   "dims": [
+    "FN",
+    "OP",
+    "LD",
+    "SA"
+   ]
+  },
+  {
+   "id": 15,
+   "naturalFit": "LD",
+   "dims": [
+    "FN",
+    "ST",
+    "LD",
+    "SA"
+   ]
+  },
+  {
+   "id": 16,
+   "naturalFit": "OP",
+   "dims": [
+    "FN",
+    "AN",
+    "MK",
+    "OP"
+   ]
+  },
+  {
+   "id": 17,
+   "naturalFit": "AN",
+   "dims": [
+    "AN",
+    "MK",
+    "ST",
+    "LD"
+   ]
+  },
+  {
+   "id": 18,
+   "naturalFit": "MK",
+   "dims": [
+    "OP",
+    "MK",
+    "FN",
+    "AN"
+   ]
+  },
+  {
+   "id": 19,
+   "naturalFit": "ST",
+   "dims": [
+    "SA",
+    "OP",
+    "ST",
+    "LD"
+   ]
+  },
+  {
+   "id": 20,
+   "naturalFit": "SA",
+   "dims": [
+    "FN",
+    "AN",
+    "OP",
+    "SA"
+   ]
+  },
+  {
+   "id": 21,
+   "naturalFit": "FN",
+   "dims": [
+    "FN",
+    "MK",
+    "OP",
+    "AN"
+   ]
+  },
+  {
+   "id": 22,
+   "naturalFit": "SA",
+   "dims": [
+    "LD",
+    "SA",
+    "ST",
+    "FN"
+   ]
+  },
+  {
+   "id": 23,
+   "naturalFit": "FN",
+   "dims": [
+    "OP",
+    "LD",
+    "FN",
+    "SA"
+   ]
+  },
+  {
+   "id": 24,
+   "naturalFit": "LD",
+   "dims": [
+    "AN",
+    "SA",
+    "OP",
+    "LD"
+   ]
+  },
+  {
+   "id": 25,
+   "naturalFit": "OP",
+   "dims": [
+    "OP",
+    "MK",
+    "ST",
+    "SA"
+   ]
+  },
+  {
+   "id": 26,
+   "naturalFit": "AN",
+   "dims": [
+    "OP",
+    "AN",
+    "LD",
+    "SA"
+   ]
+  },
+  {
+   "id": 27,
+   "naturalFit": "MK",
+   "dims": [
+    "AN",
+    "LD",
+    "MK",
+    "OP"
+   ]
+  },
+  {
+   "id": 28,
+   "naturalFit": "ST",
+   "dims": [
+    "OP",
+    "AN",
+    "MK",
+    "ST"
+   ]
+  },
+  {
+   "id": 29,
+   "naturalFit": "MK",
+   "dims": [
+    "MK",
+    "SA",
+    "ST",
+    "AN"
+   ]
+  },
+  {
+   "id": 30,
+   "naturalFit": "ST",
+   "dims": [
+    "AN",
+    "ST",
+    "LD",
+    "MK"
+   ]
+  },
+  {
+   "id": 31,
+   "naturalFit": "SA",
+   "dims": [
+    "AN",
+    "MK",
+    "SA",
+    "ST"
+   ]
+  },
+  {
+   "id": 32,
+   "naturalFit": "FN",
+   "dims": [
+    "SA",
+    "ST",
+    "AN",
+    "FN"
+   ]
+  },
+  {
+   "id": 33,
+   "naturalFit": "LD",
+   "dims": [
+    "LD",
+    "SA",
+    "MK",
+    "FN"
+   ]
+  },
+  {
+   "id": 34,
+   "naturalFit": "OP",
+   "dims": [
+    "LD",
+    "OP",
+    "MK",
+    "AN"
+   ]
+  },
+  {
+   "id": 35,
+   "naturalFit": "AN",
+   "dims": [
+    "SA",
+    "FN",
+    "AN",
+    "ST"
+   ]
+  },
+  {
+   "id": 36,
+   "naturalFit": "OP",
+   "dims": [
+    "ST",
+    "AN",
+    "SA",
+    "OP"
+   ]
+  },
+  {
+   "id": 37,
+   "naturalFit": "AN",
+   "dims": [
+    "AN",
+    "OP",
+    "ST",
+    "MK"
+   ]
+  },
+  {
+   "id": 38,
+   "naturalFit": "MK",
+   "dims": [
+    "LD",
+    "MK",
+    "FN",
+    "ST"
+   ]
+  },
+  {
+   "id": 39,
+   "naturalFit": "ST",
+   "dims": [
+    "FN",
+    "SA",
+    "ST",
+    "MK"
+   ]
+  },
+  {
+   "id": 40,
+   "naturalFit": "SA",
+   "dims": [
+    "LD",
+    "OP",
+    "AN",
+    "SA"
+   ]
+  },
+  {
+   "id": 41,
+   "naturalFit": "FN",
+   "dims": [
+    "FN",
+    "ST",
+    "SA",
+    "MK"
+   ]
+  },
+  {
+   "id": 42,
+   "naturalFit": "LD",
+   "dims": [
+    "OP",
+    "LD",
+    "FN",
+    "AN"
+   ]
+  }
+ ]
+}

bsa/scoring.py

@@ -0,0 +1,52 @@
+"""
+Re-scores a Business Strength Archetype submission on the server, so what we
+store never depends on numbers the browser sent. Mirrors lib/bsa/score.ts; the
+question bank comes from questions.json, built by scripts/bsa/build_content.py.
+"""
+
+import json
+import math
+from pathlib import Path
+
+_DATA = json.loads((Path(__file__).resolve().parent / "questions.json").read_text(encoding="utf-8"))
+ORDER: list[str] = _DATA["order"]
+STAGES: list[str] = _DATA["stages"]
+AGES: list[str] = _DATA["ages"]
+QUESTIONS: dict[int, dict] = {q["id"]: q for q in _DATA["questions"]}
+
+
+def percentages(raw: dict[str, int]) -> dict[str, int]:
+    """Whole percentages that add up to 100 (largest remainder method)."""
+    total = sum(raw.values()) or 1
+    exact = [raw[d] / total * 100 for d in ORDER]
+    pct = [math.floor(e) for e in exact]
+    order = sorted(range(len(ORDER)), key=lambda i: (-(exact[i] - pct[i]), i))
+    for i in order[: 100 - sum(pct)]:
+        pct[i] += 1
+    return dict(zip(ORDER, pct))
+
+
+def score(answers: dict[int, str]) -> dict:
+    """answers: question id → strength picked. Raises ValueError if any answer is impossible."""
+    if set(answers) != set(QUESTIONS):
+        raise ValueError(f"Expected answers to all {len(QUESTIONS)} questions.")
+    raw = {d: 0 for d in ORDER}
+    fit = {d: 0 for d in ORDER}
+    for qid, dim in answers.items():
+        q = QUESTIONS[qid]
+        if dim not in q["dims"]:
+            raise ValueError(f"Question {qid} has no option for {dim}.")
+        raw[dim] += 1
+        if dim == q["naturalFit"]:
+            fit[dim] += 1
+    ranked = sorted(ORDER, key=lambda d: (-raw[d], -fit[d], ORDER.index(d)))
+    primary, secondary = ranked[0], ranked[1]
+    pair = sorted([primary, secondary], key=ORDER.index)
+    return {
+        "raw": raw,
+        "pct": percentages(raw),
+        "primary": primary,
+        "secondary": secondary,
+        "lowest": [ranked[6], ranked[5]],
+        "blendKey": f"{pair[0]}-{pair[1]}",
+    }

main.py

@@ -14,7 +14,7 @@ from fastapi.responses import JSONResponse
 import firebase_admin
 from firebase_admin import credentials
 
-from routes import bff, chat, transcribe, documents, consultation, planning, admin, account, help as help_routes, news
+from routes import bff, chat, transcribe, documents, consultation, planning, admin, account, help as help_routes, news, bsa as bsa_routes, bff_form
 
 
 # ─── Firebase Admin SDK initialisation ───────────────────────────────────────
@@ -93,6 +93,8 @@ app.include_router(admin.router,        prefix="/api/admin",        tags=["Admin
 app.include_router(account.router,      prefix="/api/account",      tags=["Account"])
 app.include_router(help_routes.router,  prefix="/api/help",         tags=["Help"])
 app.include_router(news.router,         prefix="/api/news",         tags=["News"])
+app.include_router(bsa_routes.router,   prefix="/api/bsa",          tags=["BSA"])
+app.include_router(bff_form.router,     prefix="/api/bff-form",     tags=["BFF form"])
 
 
 # ─── Health check (unauthenticated) ──────────────────────────────────────────

routes/bff_form.py

@@ -0,0 +1,122 @@
+"""
+The public Business Footing Framework at /bff: the WHAT, WHY and HOW questions
+from onboarding, with no sign-in, no AI and no follow-up questions.
+
+The browser sends the answers and the person's contact details; this route
+checks them and stores one document per submission in bff_submissions.
+firestore.rules' default deny keeps the collection backend-only.
+"""
+
+import time
+
+from fastapi import APIRouter, HTTPException
+from firebase_admin import firestore
+from pydantic import BaseModel, Field
+
+from routes.bff import BUSINESS_STAGES
+from utils.business_type import describe
+from utils.public_forms import RateLimiter, clean_email, clean_phone
+
+router = APIRouter()
+
+COLLECTION = "bff_submissions"
+PER_SESSION_LIMIT = (5, 3600)    # 5 submissions per hour per browser
+GLOBAL_LIMIT = (500, 3600)       # 500 per hour across everyone
+limiter = RateLimiter()
+
+Short = Field(default="", max_length=200)
+Long = Field(default="", max_length=4000)
+Choices = Field(default_factory=list, max_length=40)
+
+
+class What(BaseModel):
+    businessStage: str = Field(max_length=40)
+    businessName: str = Field(min_length=1, max_length=120)
+    sectorId: str = Field(min_length=1, max_length=80)
+    subsectorId: str = Field(min_length=1, max_length=80)
+    nicheId: str = Field(min_length=1, max_length=80)
+    customNiche: str = Short
+    products: list[str] = Choices
+
+
+class Why(BaseModel):
+    whyRaw: str = Field(min_length=1, max_length=4000)
+    valueProposition: str = Field(min_length=1, max_length=4000)
+
+
+class Hours(BaseModel):
+    open: str = Field(max_length=5)
+    close: str = Field(max_length=5)
+    off: bool
+
+
+class How(BaseModel):
+    locationType: str = Field(default="online", pattern="^(online|physical|hybrid)$")
+    state: str = Short
+    lga: str = Short
+    city: str = Short
+    address: str = Short
+    hours: dict[str, Hours] = Field(default_factory=dict, max_length=7)
+    demographics: dict[str, list[str]] = Field(default_factory=dict, max_length=12)
+    psychographics: str = Long
+    channels: dict[str, list[str]] = Field(default_factory=dict, max_length=6)
+    keyPartners: str = Long
+    revenueStreams: str = Long
+
+
+class SubmissionIn(BaseModel):
+    name: str = Field(min_length=1, max_length=120)
+    email: str = Field(min_length=3, max_length=254)
+    phone: str = Field(min_length=1, max_length=30)
+    consent: bool
+    what: What
+    why: Why
+    how: How
+    startedAt: int = Field(ge=0)        # ms since epoch, from the browser
+    sessionId: str = Field(min_length=1, max_length=64)
+
+
+def _clean_list(items: list[str]) -> list[str]:
+    return [i.strip()[:200] for i in items if i.strip()]
+
+
+@router.post("/submissions")
+def submit(body: SubmissionIn):
+    if not limiter.allow(f"s:{body.sessionId}", *PER_SESSION_LIMIT) or not limiter.allow("global", *GLOBAL_LIMIT):
+        raise HTTPException(status_code=429, detail="Too many submissions. Try again later.")
+    if not body.consent:
+        raise HTTPException(status_code=400, detail="Consent is required to send your answers.")
+    email = clean_email(body.email)
+    phone = clean_phone(body.phone)
+    if body.what.businessStage not in BUSINESS_STAGES:
+        raise HTTPException(status_code=400, detail="Choose how far along your business is.")
+    if body.what.nicheId == "other" and not body.what.customNiche.strip():
+        raise HTTPException(status_code=400, detail="Tell us your niche.")
+
+    what = body.what.model_dump()
+    what["products"] = _clean_list(body.what.products)
+    how = body.how.model_dump()
+    how["demographics"] = {k[:40]: _clean_list(v) for k, v in body.how.demographics.items()}
+    how["channels"] = {k[:40]: _clean_list(v) for k, v in body.how.channels.items()}
+
+    now_ms = int(time.time() * 1000)
+    doc = {
+        "name": body.name.strip(),
+        "email": email,
+        "phone": phone,
+        "consent": True,
+        "what": what,
+        "why": {k: v.strip() for k, v in body.why.model_dump().items()},
+        "how": how,
+        # Readable labels next to the ids, so the collection can be read without the app.
+        "labels": {**describe(what), "stage": BUSINESS_STAGES[body.what.businessStage]},
+        "startedAt": body.startedAt,
+        "durationSeconds": max(0, (now_ms - body.startedAt) // 1000) if body.startedAt else None,
+        "submittedAt": firestore.SERVER_TIMESTAMP,
+        "version": 1,
+    }
+    try:
+        _, ref = firestore.client().collection(COLLECTION).add(doc)
+    except Exception:
+        raise HTTPException(status_code=500, detail="Could not save your answers.")
+    return {"success": True, "id": ref.id}

routes/bsa.py

@@ -0,0 +1,86 @@
+"""
+Business Strength Archetype results: the public assessment at /bsa.
+
+No sign-in. The browser sends the person's details and the strength behind each
+answer; this route re-scores the answers itself (bsa/scoring.py), then stores one
+document per submission in bsa_results. firestore.rules' default deny keeps the
+collection backend-only.
+"""
+
+import time
+
+from fastapi import APIRouter, HTTPException
+from firebase_admin import firestore
+from pydantic import BaseModel, Field
+
+from bsa import scoring
+from utils.public_forms import RateLimiter, clean_email, clean_phone
+
+router = APIRouter()
+
+COLLECTION = "bsa_results"
+PER_SESSION_LIMIT = (5, 3600)    # 5 submissions per hour per browser
+GLOBAL_LIMIT = (500, 3600)       # 500 per hour across everyone
+limiter = RateLimiter()
+
+
+class Answer(BaseModel):
+    q: int
+    dim: str = Field(min_length=2, max_length=2)
+
+
+class ResultIn(BaseModel):
+    firstName: str = Field(min_length=1, max_length=60)
+    email: str = Field(min_length=3, max_length=254)
+    phone: str = Field(min_length=1, max_length=30)
+    ageRange: str = Field(max_length=40)
+    stage: str = Field(max_length=120)
+    field: str = Field(default="", max_length=120)
+    location: str = Field(default="", max_length=120)
+    consent: bool
+    answers: list[Answer] = Field(min_length=1, max_length=100)
+    startedAt: int = Field(ge=0)        # ms since epoch, from the browser
+    sessionId: str = Field(min_length=1, max_length=64)
+
+
+@router.post("/results")
+def submit_result(body: ResultIn):
+    if not limiter.allow(f"s:{body.sessionId}", *PER_SESSION_LIMIT) or not limiter.allow("global", *GLOBAL_LIMIT):
+        raise HTTPException(status_code=429, detail="Too many submissions. Try again later.")
+    if not body.consent:
+        raise HTTPException(status_code=400, detail="Consent is required to save your result.")
+    email = clean_email(body.email)
+    phone = clean_phone(body.phone)
+    if body.ageRange not in scoring.AGES or body.stage not in scoring.STAGES:
+        raise HTTPException(status_code=400, detail="Choose your age range and business stage.")
+
+    answers = {a.q: a.dim for a in body.answers}
+    if len(answers) != len(body.answers):
+        raise HTTPException(status_code=400, detail="Each question can only be answered once.")
+    try:
+        result = scoring.score(answers)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    now_ms = int(time.time() * 1000)
+    doc = {
+        "firstName": body.firstName.strip(),
+        "email": email,
+        "phone": phone,
+        "ageRange": body.ageRange,
+        "stage": body.stage,
+        "field": body.field.strip(),
+        "location": body.location.strip(),
+        "consent": True,
+        "answers": [{"q": q, "dim": d} for q, d in sorted(answers.items())],
+        **result,
+        "startedAt": body.startedAt,
+        "durationSeconds": max(0, (now_ms - body.startedAt) // 1000) if body.startedAt else None,
+        "finishedAt": firestore.SERVER_TIMESTAMP,
+        "version": 1,
+    }
+    try:
+        _, ref = firestore.client().collection(COLLECTION).add(doc)
+    except Exception:
+        raise HTTPException(status_code=500, detail="Could not save your result.")
+    return {"success": True, "id": ref.id, **result}

tests/test_bff_form.py

@@ -0,0 +1,86 @@
+"""
+Unit tests for the public Business Footing Framework route (routes/bff_form.py)
+and the shared public-form checks (utils/public_forms.py). Firestore is mocked.
+"""
+from unittest.mock import MagicMock, patch
+
+import pytest
+from fastapi import HTTPException
+
+from routes import bff_form
+from routes.bff_form import SubmissionIn, submit
+from utils.public_forms import clean_phone
+
+
+@pytest.fixture(autouse=True)
+def _reset_limits():
+    bff_form.limiter.reset()
+
+
+def _body(**over):
+    base = dict(
+        name=" Ada Obi ", email=" Ada@Example.com ", phone="0803 123 4567", consent=True,
+        what=dict(businessStage="early", businessName="Ada Books", sectorId="retail_trade",
+                  subsectorId="bookshops", nicheId="other", customNiche="Children's books",
+                  products=["Story books", "  ", "School texts"]),
+        why=dict(whyRaw=" I love reading ", valueProposition="Good books at fair prices"),
+        how=dict(locationType="physical", state="Lagos", city="Ikeja",
+                 hours={"monday": {"open": "09:00", "close": "18:00", "off": False}},
+                 demographics={"ageRanges": ["21–25"]}, channels={"social_media": ["Instagram"]},
+                 revenueStreams="Book sales"),
+        startedAt=1, sessionId="s-1",
+    )
+    base.update(over)
+    return SubmissionIn(**base)
+
+
+def _db():
+    db = MagicMock()
+    db.collection.return_value.add.return_value = (None, MagicMock(id="doc1"))
+    return db
+
+
+def test_stores_answers_contact_and_labels():
+    db = _db()
+    with patch.object(bff_form.firestore, "client", return_value=db):
+        out = submit(_body())
+    assert out == {"success": True, "id": "doc1"}
+    db.collection.assert_called_with("bff_submissions")
+    doc = db.collection.return_value.add.call_args[0][0]
+    assert (doc["name"], doc["email"], doc["phone"]) == ("Ada Obi", "ada@example.com", "0803 123 4567")
+    assert doc["what"]["products"] == ["Story books", "School texts"]
+    assert doc["why"]["whyRaw"] == "I love reading"
+    assert doc["labels"]["niche"] == "Children's books" and doc["labels"]["stage"].startswith("Running for 1")
+    assert doc["how"]["hours"]["monday"]["open"] == "09:00"
+
+
+@pytest.mark.parametrize("over", [
+    {"consent": False}, {"email": "nope"}, {"phone": "12345"},
+    {"what": dict(businessStage="unknown", businessName="X", sectorId="a", subsectorId="b", nicheId="c")},
+    {"what": dict(businessStage="idea", businessName="X", sectorId="a", subsectorId="b", nicheId="other")},
+])
+def test_rejects_bad_submissions(over):
+    with pytest.raises(HTTPException) as e:
+        submit(_body(**over))
+    assert e.value.status_code == 400
+
+
+def test_rate_limits_per_browser():
+    with patch.object(bff_form.firestore, "client", return_value=_db()):
+        for _ in range(5):
+            submit(_body())
+        with pytest.raises(HTTPException) as e:
+            submit(_body())
+    assert e.value.status_code == 429
+
+
+@pytest.mark.parametrize("raw,ok", [
+    ("+234 803 123 4567", True), ("(0803) 123-4567", True), ("08031234567", True),
+    ("123", False), ("0803 abc 4567", False), ("+1234567890123456", False),
+])
+def test_phone_check(raw, ok):
+    if ok:
+        assert clean_phone(raw) == " ".join(raw.split())
+    else:
+        with pytest.raises(HTTPException):
+            clean_phone(raw)

tests/test_bsa.py

@@ -0,0 +1,83 @@
+"""
+Unit tests for the Business Strength Archetype: server-side scoring (bsa/scoring.py)
+and the public results route (routes/bsa.py). Firestore is mocked.
+"""
+from unittest.mock import MagicMock, patch
+
+import pytest
+from fastapi import HTTPException
+
+from bsa import scoring
+from routes import bsa as bsa_routes
+from routes.bsa import ResultIn, submit_result
+
+
+@pytest.fixture(autouse=True)
+def _reset_limits():
+    bsa_routes.limiter.reset()
+
+
+def _natural():
+    return {qid: q["naturalFit"] for qid, q in scoring.QUESTIONS.items()}
+
+
+def _body(answers=None, **over):
+    answers = answers or _natural()
+    base = dict(firstName=" Ada ", email=" Ada@Example.com ", phone=" +234 803 123 4567 ", ageRange=scoring.AGES[1], stage=scoring.STAGES[2],
+                consent=True, answers=[{"q": q, "dim": d} for q, d in answers.items()],
+                startedAt=1, sessionId="s-1")
+    base.update(over)
+    return ResultIn(**base)
+
+
+def test_scoring_matches_the_documented_rules():
+    r = scoring.score(_natural())
+    assert set(r["raw"].values()) == {6}
+    assert (r["primary"], r["secondary"], r["blendKey"]) == ("ST", "AN", "ST-AN")
+    assert sum(r["pct"].values()) == 100
+
+    op = {qid: ("OP" if "OP" in q["dims"] else q["dims"][0]) for qid, q in scoring.QUESTIONS.items()}
+    r = scoring.score(op)
+    assert r["primary"] == "OP" and r["raw"]["OP"] == 24
+
+
+def test_rejects_impossible_or_missing_answers():
+    answers = _natural()
+    first = min(answers)
+    bad = next(d for d in scoring.ORDER if d not in scoring.QUESTIONS[first]["dims"])
+    with pytest.raises(ValueError):
+        scoring.score({**answers, first: bad})
+    answers.pop(first)
+    with pytest.raises(ValueError):
+        scoring.score(answers)
+
+
+def test_stores_details_and_server_computed_score():
+    db = MagicMock()
+    db.collection.return_value.add.return_value = (None, MagicMock(id="doc1"))
+    with patch.object(bsa_routes.firestore, "client", return_value=db):
+        out = submit_result(_body())
+    assert out["id"] == "doc1" and out["blendKey"] == "ST-AN"
+    db.collection.assert_called_with("bsa_results")
+    stored = db.collection.return_value.add.call_args[0][0]
+    assert stored["firstName"] == "Ada" and stored["email"] == "ada@example.com"
+    assert stored["phone"] == "+234 803 123 4567"
+    assert len(stored["answers"]) == 42 and stored["primary"] == "ST"
+
+
+@pytest.mark.parametrize("over", [{"consent": False}, {"email": "not-an-email"}, {"phone": "call me maybe"}, {"phone": "123456"}, {"stage": "made up"}])
+def test_rejects_bad_details(over):
+    with pytest.raises(HTTPException) as e:
+        submit_result(_body(**over))
+    assert e.value.status_code == 400
+
+
+def test_rate_limits_per_browser():
+    db = MagicMock()
+    db.collection.return_value.add.return_value = (None, MagicMock(id="x"))
+    with patch.object(bsa_routes.firestore, "client", return_value=db):
+        for _ in range(5):
+            submit_result(_body())
+        with pytest.raises(HTTPException) as e:
+            submit_result(_body())
+    assert e.value.status_code == 429

utils/public_forms.py

@@ -0,0 +1,54 @@
+"""
+Shared checks for the public, no-sign-in forms (/bsa and /bff): a simple rate
+limiter and the contact-detail validators. Rate limits are in-memory, per
+process (same trade-off as routes/help.py).
+"""
+
+import re
+import threading
+import time
+from collections import defaultdict
+
+from fastapi import HTTPException
+
+EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+# Digits with an optional leading +, allowing the spaces, dashes, dots and brackets people type.
+PHONE_RE = re.compile(r"^\+?[\d\s().-]+$")
+
+
+class RateLimiter:
+    """Allows `count` hits per `period` seconds for each key."""
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._hits: dict[str, list[float]] = defaultdict(list)
+
+    def allow(self, key: str, count: int, period: int) -> bool:
+        now = time.time()
+        with self._lock:
+            recent = [t for t in self._hits[key] if now - t < period]
+            allowed = len(recent) < count
+            if allowed:
+                recent.append(now)
+            self._hits[key] = recent
+            return allowed
+
+    def reset(self):
+        with self._lock:
+            self._hits.clear()
+
+
+def clean_email(raw: str) -> str:
+    email = raw.strip().lower()
+    if not EMAIL_RE.match(email):
+        raise HTTPException(status_code=400, detail="Enter a valid email address.")
+    return email
+
+
+def clean_phone(raw: str) -> str:
+    """Trimmed phone number, kept as typed apart from spacing. 7 to 15 digits."""
+    phone = " ".join(raw.split())
+    digits = re.sub(r"\D", "", phone)
+    if not PHONE_RE.match(phone) or not 7 <= len(digits) <= 15:
+        raise HTTPException(status_code=400, detail="Enter a valid phone number.")
+    return phone