pyr0ball
383897f990
- platforms/: eBay platform adapter (snipe integration layer) - docs/: developer guide, module reference, getting-started docs - scripts/: utility scripts for development and deployment
2.1 KiB
affiliates
Affiliate URL wrapping with user opt-out and BYOK user IDs. Shared across all CircuitForge products that surface external purchase or listing links.
from circuitforge_core.affiliates import wrap_url
Design principle
Affiliate links are disclosed to users and opt-out is always one click away. CF earns a small commission when users buy through wrapped links; this is the primary monetization path for free-tier products. The implementation is transparent: no dark patterns, no hidden redirects.
wrap_url(url, user_id=None, product=None) -> str
Wraps a URL with the configured affiliate parameters. Returns the original URL unchanged if:
- Affiliate links are disabled globally (
CF_AFFILIATES_ENABLED=false) - The user has opted out (
preferences.get("affiliates.opted_out")) - The domain is not in the supported affiliate network list
from circuitforge_core.affiliates import wrap_url
wrapped = wrap_url(
"https://www.ebay.com/itm/123456",
user_id="user_abc123",
product="snipe",
)
# → "https://www.ebay.com/itm/123456?mkrid=711-53200-19255-0&campid=CF_SNIPE_abc123&..."
User opt-out
from circuitforge_core.preferences import get_prefs
prefs = get_prefs(user_id)
prefs.set("affiliates.opted_out", True)
When opted_out is True, wrap_url() returns the bare URL. The UI should surface this setting prominently — never bury it.
BYOK user IDs
BYOK users (those with their own license key or API key) get a unique affiliate sub-ID so their contributions are tracked separately. This is handled automatically when a user_id is passed.
Supported networks
| Product | Network | Notes |
|---|---|---|
| Snipe | eBay Partner Network | campid encodes product + user |
| Kiwi | Amazon Associates (planned) | For pantry staples / equipment |
| Waxwing | Various garden suppliers (planned) |
Environment variables
CF_AFFILIATES_ENABLED=true # global kill switch
CF_EBAY_CAMPAIGN_ID=your_campaign # eBay Partner Network campaign ID
CF_AMAZON_ASSOCIATE_TAG=your_tag # Amazon Associates tag