feat: eBay affiliate link builder (Option B — user-configurable, CF fallback)

- _affiliate_url() helper appends EPN params when EBAY_AFFILIATE_CAMPAIGN_ID set
- Clean /itm/ URLs by default (no affiliate tracking without explicit opt-in)
- affiliate_active flag in search response drives frontend disclosure
- SearchView shows 'Links may include an affiliate code' when active
- .env.example documents EBAY_AFFILIATE_CAMPAIGN_ID with EPN registration link
- Closes #19

.env.example

@@ -47,6 +47,13 @@ SNIPE_DB=data/snipe.db
 # HEIMDALL_URL=https://license.circuitforge.tech
 # HEIMDALL_ADMIN_TOKEN=
 
+# ── eBay Affiliate (optional) ─────────────────────────────────────────────────
+# Set to your eBay Partner Network (EPN) campaign ID to earn commissions on
+# listing click-throughs. Leave blank for clean /itm/ URLs (no tracking).
+# Register at https://partnernetwork.ebay.com — self-hosted users can use their
+# own ID; the CF cloud instance uses CF's campaign ID (disclosed in the UI).
+# EBAY_AFFILIATE_CAMPAIGN_ID=
+
 # ── In-app feedback (beta) ────────────────────────────────────────────────────
 # When set, a feedback FAB appears in the UI and routes submissions to Forgejo.
 # Leave unset to silently hide the button (demo/offline deployments).

api/main.py

@@ -69,6 +69,22 @@ def _ebay_creds() -> tuple[str, str, str]:
         client_secret = (os.environ.get("EBAY_CERT_ID") or os.environ.get("EBAY_CLIENT_SECRET", "")).strip()
     return client_id, client_secret, env
 
+def _affiliate_url(url: str) -> str:
+    """Append EPN affiliate params when EBAY_AFFILIATE_CAMPAIGN_ID is configured.
+
+    If the env var is absent or blank, the original URL is returned unchanged.
+    Params follow the standard EPN deep-link format; siteid=0 = US.
+    """
+    campaign_id = os.environ.get("EBAY_AFFILIATE_CAMPAIGN_ID", "").strip()
+    if not campaign_id:
+        return url
+    sep = "&" if "?" in url else "?"
+    return (
+        f"{url}{sep}mkcid=1&mkrid=711-53200-19255-0"
+        f"&siteid=0&campid={campaign_id}&toolid=10001&mkevt=1"
+    )
+
+
 app = FastAPI(title="Snipe API", version="0.1.0", lifespan=_lifespan)
 app.include_router(ebay_webhook_router)
 
@@ -395,12 +411,18 @@ def search(
         and shared_store.get_seller("ebay", listing.seller_platform_id)
     }
 
+    def _serialize_listing(l: object) -> dict:
+        d = dataclasses.asdict(l)
+        d["url"] = _affiliate_url(d["url"])
+        return d
+
     return {
-        "listings": [dataclasses.asdict(l) for l in listings],
+        "listings": [_serialize_listing(l) for l in listings],
         "trust_scores": trust_map,
         "sellers": seller_map,
         "market_price": market_price,
         "adapter_used": adapter_used,
+        "affiliate_active": bool(os.environ.get("EBAY_AFFILIATE_CAMPAIGN_ID", "").strip()),
     }
 
 

web/src/stores/search.ts

@@ -120,6 +120,7 @@ export const useSearchStore = defineStore('search', () => {
   )
   const marketPrice = ref<number | null>(cached?.marketPrice ?? null)
   const adapterUsed = ref<'api' | 'scraper' | null>(cached?.adapterUsed ?? null)
+  const affiliateActive = ref<boolean>(false)
   const loading = ref(false)
   const error = ref<string | null>(null)
 
@@ -164,6 +165,7 @@ export const useSearchStore = defineStore('search', () => {
         sellers: Record<string, Seller>
         market_price: number | null
         adapter_used: 'api' | 'scraper'
+        affiliate_active: boolean
       }
 
       results.value = data.listings ?? []
@@ -171,6 +173,7 @@ export const useSearchStore = defineStore('search', () => {
       sellers.value = new Map(Object.entries(data.sellers ?? {}))
       marketPrice.value = data.market_price ?? null
       adapterUsed.value = data.adapter_used ?? null
+      affiliateActive.value = data.affiliate_active ?? false
       saveCache({
         query: q,
         results: results.value,
@@ -225,6 +228,7 @@ export const useSearchStore = defineStore('search', () => {
     sellers,
     marketPrice,
     adapterUsed,
+    affiliateActive,
     loading,
     error,
     search,

web/src/views/SearchView.vue

@@ -296,6 +296,9 @@
               <span v-if="hiddenCount > 0" class="results-hidden">
                 · {{ hiddenCount }} hidden by filters
               </span>
+              <span v-if="store.affiliateActive" class="affiliate-disclosure">
+                · Links may include an affiliate code
+              </span>
             </p>
             <div class="toolbar-actions">
               <label for="sort-select" class="sr-only">Sort by</label>
@@ -1029,6 +1032,7 @@ async function onSearch() {
 }
 
 .results-hidden { color: var(--color-warning); }
+.affiliate-disclosure { color: var(--color-text-muted, #8b949e); font-size: 0.8em; }
 
 .toolbar-actions {
   display: flex;