temp: partner credits proposal

partner-credits-proposal.md

@@ -0,0 +1,253 @@
+# Partner Credits: Zero-Registration Free Tier for last30days Users
+
+**Type:** Partnership proposal for ScrapeCreators
+**Date:** 2026-03-05
+**Status:** Draft proposal
+
+---
+
+## The Pitch
+
+Every last30days user gets 100 free ScrapeCreators credits — Reddit, TikTok, Instagram — without ever visiting scrapecreators.com or creating an account. When they run out, the skill tells them where to upgrade. ScrapeCreators gets a distribution channel. last30days gets a killer default experience.
+
+## The Problem
+
+Right now, new last30days users hit a wall:
+
+1. Install the skill (30 seconds)
+2. Try `/last30days AI video tools`
+3. Get told they need a `SCRAPECREATORS_API_KEY`
+4. Have to go to scrapecreators.com, register, get a key, paste it into `.env`
+5. Many never come back
+
+The best Reddit experience requires a key. The friction kills adoption.
+
+## The Proposal: Machine-Bound Partner Tokens
+
+### How It Works
+
+**ScrapeCreators side:**
+1. Issue last30days a **partner ID** (e.g., `partner_last30days`)
+2. Accept a new header: `X-Partner-Device: <device_hash>`
+3. On first request per device hash: allocate 100 credits, no registration needed
+4. Track usage: `(partner_id, device_hash) → credits_remaining`
+5. When credits hit 0: return `402` with upgrade URL in response body
+
+**last30days side:**
+1. On first run, generate a **device fingerprint** and cache it locally
+2. If user has no `SCRAPECREATORS_API_KEY`, send requests with partner headers instead
+3. When 402 comes back, show a friendly "upgrade" message
+
+That's it. No accounts, no OAuth, no registration flow.
+
+### The Device Fingerprint
+
+```python
+import hashlib, platform, uuid, os
+
+def get_device_id():
+    """Generate a stable, hard-to-forge device fingerprint."""
+    # Use the OS-level machine ID (persists across reinstalls on most systems)
+    machine_id = _get_machine_id()
+
+    # Salt with the partner ID so the hash is useless outside this context
+    raw = f"last30days:{machine_id}"
+    return hashlib.sha256(raw.encode()).hexdigest()
+
+def _get_machine_id():
+    """Get the OS hardware/machine ID."""
+    if platform.system() == "Darwin":
+        # macOS: IOPlatformUUID (hardware-bound, survives OS reinstall)
+        import subprocess
+        result = subprocess.run(
+            ["ioreg", "-rd1", "-c", "IOPlatformExpertDevice"],
+            capture_output=True, text=True
+        )
+        for line in result.stdout.splitlines():
+            if "IOPlatformUUID" in line:
+                return line.split('"')[-2]
+
+    elif platform.system() == "Linux":
+        # Linux: /etc/machine-id (set at install time)
+        try:
+            return open("/etc/machine-id").read().strip()
+        except FileNotFoundError:
+            pass
+
+    # Fallback: MAC address + hostname (less stable but reasonable)
+    return f"{uuid.getnode()}:{platform.node()}"
+```
+
+**Why this works:**
+- macOS `IOPlatformUUID` is hardware-bound — can't change it without a new motherboard
+- Linux `/etc/machine-id` is set at OS install — persists across reboots
+- Hashed with `last30days:` prefix so the raw ID is never sent to ScrapeCreators
+- Cached locally in `~/.config/last30days/.device_id` after first generation
+
+### API Request Format
+
+```
+# Without partner credits (existing flow — user has their own key)
+GET /v1/reddit/search?query=AI+tools
+x-api-key: sc_user_abc123
+
+# With partner credits (new — no registration needed)
+GET /v1/reddit/search?query=AI+tools
+x-api-key: sc_partner_last30days
+X-Partner-Device: a1b2c3d4e5f6...  (sha256 hex)
+```
+
+ScrapeCreators treats `sc_partner_last30days` as a special key class:
+- Requires `X-Partner-Device` header
+- Credits tracked per device hash, not per API key
+- Rate limited per device (e.g., 10 requests/minute)
+- 100 credits per unique device, lifetime
+
+### What Counts as a Credit
+
+One API call = one credit. A typical `/last30days` run uses roughly:
+- 2-4 Reddit searches (global + subreddit drilldowns)
+- 1-2 TikTok searches + 2-3 transcript fetches
+- 1-2 Instagram searches + 2-3 transcript fetches
+
+So ~10-15 credits per run. 100 credits ≈ **7-10 full research runs** before upgrade.
+
+That's enough to get hooked.
+
+## Abuse Prevention
+
+### What we're defending against
+
+| Threat | Likelihood | Impact |
+|--------|-----------|--------|
+| User spoofs device ID to get infinite credits | Low | Medium |
+| Script generates thousands of fake device IDs | Medium | High |
+| User shares partner key for non-last30days use | Low | Low |
+
+### Defenses (simplest first)
+
+**1. Hardware-bound device ID (primary defense)**
+- macOS IOPlatformUUID can't be changed without hardware swap
+- Linux machine-id requires root to change and breaks other software
+- Not a cookie or config file — it's the machine itself
+
+**2. Rate limiting per device (ScrapeCreators side)**
+- 10 requests/minute per device hash
+- Prevents scripted rapid-fire abuse even with valid device IDs
+- Normal usage never hits this — a full run takes 60-70 seconds with natural gaps
+
+**3. IP rate limiting on new device registrations (ScrapeCreators side)**
+- Max 3 new device hashes per IP per day
+- Stops "generate 1000 device IDs from one server" attacks
+- Legitimate users: one machine, one device ID, done
+
+**4. Total partner pool cap (safety valve)**
+- ScrapeCreators sets a monthly cap on total partner credits (e.g., 50,000/month)
+- If last30days goes viral and blows the cap, both parties renegotiate
+- Prevents runaway costs from unexpected growth
+
+### What we're NOT doing (intentional simplicity)
+
+- No CAPTCHAs
+- No email verification
+- No phone verification
+- No browser fingerprinting
+- No token signing or crypto
+- No account creation whatsoever
+
+The goal is zero friction. The device ID is "good enough" — it stops casual abuse and scripts. A determined attacker could maybe get 200-300 free credits by VM gymnastics, but that's not worth defending against when paid plans are cheap.
+
+## User Experience
+
+### First run (no key configured)
+
+```
+$ /last30days AI video tools
+
+🔍 Searching Reddit, TikTok, Instagram...
+ℹ️  Using 100 free partner credits from ScrapeCreators (93 remaining)
+   Get your own key for unlimited use: scrapecreators.com/last30days
+
+[... normal results ...]
+```
+
+### Credits running low
+
+```
+ℹ️  12 partner credits remaining. Get unlimited access: scrapecreators.com/last30days
+```
+
+### Credits exhausted
+
+```
+⚠️  Free partner credits used up!
+
+Reddit, TikTok, and Instagram require a ScrapeCreators API key.
+Get one at: scrapecreators.com/last30days (100 free credits on signup, then pay-as-you-go)
+
+Continuing with X, YouTube, Hacker News, Polymarket, and web search...
+```
+
+Key detail: the skill **doesn't stop working** — it gracefully falls back to the sources that don't need a key. The user still gets value, but they see what they're missing.
+
+### After upgrade
+
+```
+$ echo 'SCRAPECREATORS_API_KEY=sc_abc123' >> ~/.config/last30days/.env
+
+# Next run — partner headers no longer sent, user's own key used
+```
+
+## What ScrapeCreators Gets
+
+1. **Distribution channel** — every last30days install is a potential paying customer
+2. **Zero support burden** — no accounts to manage for free tier users
+3. **Qualified leads** — users who exhaust 100 credits are proven power users
+4. **Co-marketing** — "Powered by ScrapeCreators" in every skill run
+5. **Usage data** — anonymous device-level usage patterns across topics
+
+## What last30days Gets
+
+1. **Zero-config Reddit** — install and go, no registration anywhere
+2. **TikTok and Instagram included** — three sources work out of the box
+3. **Lower barrier to adoption** — the #1 friction point eliminated
+4. **Upgrade path built in** — natural conversion funnel
+
+## Implementation Effort
+
+### ScrapeCreators side (their work)
+- [ ] Create partner key class with per-device credit tracking
+- [ ] Accept `X-Partner-Device` header on partner keys
+- [ ] Return `402` with upgrade URL when credits exhausted
+- [ ] Rate limit: 10 req/min per device, 3 new devices/day per IP
+- [ ] Dashboard for last30days to see aggregate partner usage
+
+### last30days side (our work)
+- [ ] `scripts/lib/device_id.py` — generate and cache device fingerprint (~30 lines)
+- [ ] Update `scripts/lib/env.py` — fall back to partner auth when no user key
+- [ ] Update `_sc_headers()` in reddit.py, tiktok.py, instagram.py — add partner headers
+- [ ] Handle 402 response — show upgrade message, continue with other sources
+- [ ] Show credits remaining in run output (from response header)
+
+### Suggested response headers from ScrapeCreators
+
+```
+X-Partner-Credits-Remaining: 87
+X-Partner-Credits-Total: 100
+X-Partner-Upgrade-URL: https://scrapecreators.com/last30days
+```
+
+## Open Questions
+
+1. **Credit pool negotiation** — what monthly cap works for ScrapeCreators?
+2. **Referral tracking** — should `scrapecreators.com/last30days` give a signup bonus or revenue share?
+3. **Credit count per endpoint** — should transcript fetches cost the same as searches?
+4. **Expiration** — do unused partner credits expire (e.g., 90 days)?
+
+---
+
+## Summary
+
+One device ID. One partner key. One header. 100 free credits. Zero registration.
+
+The entire abuse prevention is: your computer has a hardware ID that you can't easily change. That's it. Simple, clever, and good enough.

v29-tweet.html

@@ -0,0 +1,41 @@
+<!DOCTYPE html>
+<html>
+<head>
+<style>
+body { font-family: -apple-system, sans-serif; max-width: 600px; margin: 40px auto; padding: 20px; background: #f5f5f5; }
+.tweet { background: white; border-radius: 12px; padding: 24px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); white-space: pre-wrap; font-size: 15px; line-height: 1.5; }
+button { margin-top: 16px; padding: 10px 20px; background: #1d9bf0; color: white; border: none; border-radius: 20px; font-size: 14px; cursor: pointer; }
+button:hover { background: #1a8cd8; }
+.copied { background: #00ba7c; }
+</style>
+</head>
+<body>
+<div class="tweet" id="tweet">/last30days v2.9 is out. Reddit just got a massive upgrade.
+
+Top comments are now first-class. The best comment on each thread gets 10% scoring weight and shows up like:
+
+r/ClaudeAI — "Anthropic Released 32 Page Detailed Guide on Building Claude Skills" [1,470pts, 112 comments]
+💬 Top comment (567 pts): "Can't wait to have Claude read this and explain it to me."
+
+Reddit's value was always in the comments. Now the skill actually reads them.
+
+The other big change: smart subreddit discovery. It scores every candidate by frequency × recency × topic-word match and blocklists utility subs that used to pollute results.
+
+Before: search "Kanye West" → r/AskReddit, r/OutOfTheLoop
+Now: r/hiphopheads, r/Kanye, r/NFCWestMemeWar
+
+Shoutout to @ScrapeCreators — one API key now covers Reddit, TikTok, and Instagram. Three sources, one key. Should be cheaper than using an OpenAI key too.</div>
+<button onclick="copyTweet()">Copy to clipboard</button>
+<script>
+function copyTweet() {
+  const text = document.getElementById('tweet').textContent;
+  navigator.clipboard.writeText(text).then(() => {
+    const btn = document.querySelector('button');
+    btn.textContent = 'Copied!';
+    btn.classList.add('copied');
+    setTimeout(() => { btn.textContent = 'Copy to clipboard'; btn.classList.remove('copied'); }, 2000);
+  });
+}
+</script>
+</body>
+</html>