vyndr/specs/a1-s3-affiliate-partner-plumbing.md

A1 Session 3 — Affiliate + Partnership Plumbing

Operating constraints

• ZERO out-of-pocket. No affiliate program is approved yet — everything ships config-flip-ready but DISABLED / organic by default.
• Data semantics: never fabricate market values. A "best price" claim renders only when genuinely multiple books post the same line — absent beats wrong.
• No exclamation points in any copy (VOICE v1.1).

1. BOOK IT deep-link builder

• web/src/lib/bookLinks.js (CommonJS, unit-testable)
  • SUPPORTED_BOOKS: draftkings, fanduel, betmgm, caesars, betrivers (hosts sourced from the existing SPORTSBOOKS list in scan/page.tsx + lib/books.js brand map).
  • buildBookLink({ book, player, sport, state? }, config?) → { url, tracking } | null
    • Unknown book → null (absent beats wrong).
    • Organic base: https://{host}/?search={player} (existing deep-link shape).
    • Affiliate layer: reads web/src/lib/affiliateConfig.js — per book { enabled: false, params: {} } with Impact/Partnerize-style param shapes documented in comments (irclickid / sharedid / afid / btag).
    • tracking: true only when the book is enabled AND at least one non-empty param was appended. Disabled → clean organic link.
  • BOOK_LINK_REL = 'sponsored noopener noreferrer' — every book anchor renders this rel.
• Wiring:
  • StatStrip.tsx BookItTeaser → real <a> deep link (best-price book when known, else the prop's book, else DraftKings). Organic until config flips.
  • scan/page.tsx sportsbook hand-off anchors → buildBookLink + BOOK_LINK_REL (replaces the local SPORTSBOOKS/deepLink pair).

2. Best-line highlight (cheap version)

• Finding (documented in the session report): the grouped odds proxy already ships per-book rows to the browser as lines[] per player+stat; Slate.groupByGame/pickLine collapse to ONE line and discard the rest.
• Ship: thread books (the raw lines[]) onto each PropRowProp; slateAdapter.detectBestBook(rows, side, refLine) returns { book, odds } ONLY when ≥2 books post the SAME line for the side and prices differ; buildPlayerStripsFromProps attaches bestBook + book to each strip prop; StatStrip renders a subtle signal-green dot (one meaning: best available price).

3. Partner ref system

• (a) web/src/lib/partnerRef.js (CommonJS) — parse ?ref=CODE, sanitize (A–Z 0–9 - _, ≤32, uppercased), first-party cookie vyndr_ref (90d, SameSite=Lax, Path=/), first-touch (never overwrites an existing cookie). components/vyndr/PartnerRefCapture.tsx mounted in the layout (GlobalHosts pattern).
• (b) src/routes/partners.js — GET /api/partners/report/:code behind requireInternalAuth → { signups, conversions, mrr_attributed } read from user_profiles filtered by partner_ref. The column does NOT exist yet: the endpoint degrades to zeros + a note, and the TODO migration is documented in docs/PARTNERS.md (NOT run).
• (c) Signup: AuthContext.signUp forwards the vyndr_ref cookie into Supabase signup metadata as partner_ref.
• (d) docs/PARTNERS.md — Stripe promo-code mapping convention + the TODO migration.

Acceptance criteria

• All book links organic by default; flipping enabled + params in affiliateConfig produces a tracked URL with the params appended.
• Best-price dot never renders on single-book or unequal-line data.
• ?ref=CODE first visit sets vyndr_ref for 90 days; signup metadata carries partner_ref; report endpoint 401s without the internal key.
• Full npx jest green; cd web && npx next build exit 0.

Test plan

• tests/unit/bookLinks.test.js — organic default, enabled param shapes, aliases, betrivers state, unknown book, rel constant + source assertions.
• tests/unit/slateAdapterBestBook.test.js — detectBestBook honesty rules + strip attachment.
• tests/unit/partnerRef.test.js — sanitize/parse/cookie/first-touch.
• tests/unit/partnersRoute.test.js — report math + internal-auth mount.