Create LINKEDIN_INTEGRATION.md

Complete LinkedIn integration documentation with RapidAPI setup.

Includes:
- Free tier setup (50 requests/month, no credit card)
- Step-by-step configuration guide
- API key integration with HF Spaces Secrets
- Usage examples and code snippets
- Cost analysis and scaling options
- Legal compliance information
- Troubleshooting guide
- Testing instructions

Ready to use - just sign up for RapidAPI and add the API key to Spaces Secrets.

LINKEDIN_INTEGRATION.md

@@ -0,0 +1,315 @@
+# LinkedIn Data Integration Guide
+
+## 🚀 Quick Setup (5 Minutes)
+
+This guide shows you how to integrate LinkedIn profile data into StrategyStack using RapidAPI's free tier.
+
+---
+
+## Step 1: Get Your Free API Key
+
+1. **Sign up on RapidAPI** (free, no credit card): https://rapidapi.com
+2. **Search for** "Fresh LinkedIn Profile Data"
+3. **Subscribe to FREE tier** (50 requests/month)
+4. **Copy your API key** from the dashboard
+
+---
+
+## Step 2: Add API Key to Spaces
+
+1. Go to **Settings** tab in this Space
+2. Scroll to **Variables and secrets**
+3. Click **New secret**
+4. Name: `RAPIDAPI_KEY`
+5. Value: Paste your API key
+6. Click **Save**
+
+---
+
+## Step 3: What You Get
+
+### Free Tier (No Credit Card Required)
+- ✅ 50 requests per month
+- ✅ 1000 requests per hour rate limit
+- ✅ Full profile data access
+- ✅ 1-2 second response time
+
+### Profile Data Includes:
+- Full name, profile photo URL
+- Current title & company
+- Complete work history
+- Education background
+- Skills & endorsements
+- Location, connections count
+- Profile summary/bio
+- LinkedIn profile URL
+
+---
+
+## Implementation Details
+
+The integration is already built into the app via `linkedin_data.py`:
+
+```python
+import requests
+import os
+
+def fetch_linkedin_profile(profile_url: str) -> dict:
+    """Fetch LinkedIn profile data using RapidAPI"""
+    api_key = os.getenv('RAPIDAPI_KEY')
+    
+    url = "https://fresh-linkedin-profile-data.p.rapidapi.com/get-linkedin-profile"
+    
+    headers = {
+        "x-rapidapi-key": api_key,
+        "x-rapidapi-host": "fresh-linkedin-profile-data.p.rapidapi.com"
+    }
+    
+    response = requests.get(url, headers=headers, params={"linkedin_url": profile_url})
+    
+    if response.status_code == 200:
+        return response.json()
+    return None
+```
+
+---
+
+## Usage in Dashboard
+
+Once configured, the dashboard automatically enriches lead data:
+
+### Before Enrichment:
+```python
+lead = {
+    "contact_id": "c123",
+    "linkedin_url": "https://linkedin.com/in/username"
+}
+```
+
+### After Enrichment:
+```python
+lead = {
+    "contact_id": "c123",
+    "linkedin_url": "https://linkedin.com/in/username",
+    "full_name": "John Doe",
+    "headline": "CEO at Tech Company",
+    "location": "San Francisco, CA",
+    "current_company": "Tech Company",
+    "current_title": "Chief Executive Officer",
+    "experience": [...],
+    "education": [...],
+    "skills": ["Leadership", "Strategy", ...]
+}
+```
+
+---
+
+## Cost & Scaling
+
+### Free Tier Strategy
+**50 requests/month is perfect for:**
+- Initial demo and testing
+- 1-2 pilot customers
+- Enriching your "hottest" leads only
+- Development environment
+
+**Best Practices:**
+- Cache enriched profiles (stored in user's `/data` directory)
+- Only enrich leads with high engagement
+- Don't re-fetch same profile repeatedly
+- Use strategically for key decision-makers
+
+### When to Upgrade
+
+**Pro Plan: $50/month**
+- 20,000 requests/month (~650/day)
+- Perfect for 5-10 active customers
+- Small-medium outreach campaigns
+
+**Ultra Plan: $200/month**
+- 100,000 requests/month (~3,300/day)
+- 10-20 active customers
+- Large-scale campaigns
+
+**Mega Plan: $500/month**
+- 500,000 requests/month (~16,600/day)
+- Enterprise scale
+- Unlimited customers
+
+---
+
+## Legal & Compliance
+
+### What's Legal ✅
+- Scraping **public** LinkedIn data (hiQ Labs v. LinkedIn precedent)
+- Using for B2B lead enrichment
+- Caching data for business purposes
+- Providing value-added services to customers
+
+### Best Practices ⚠️
+- Use only for legitimate business purposes
+- Don't resell raw LinkedIn data
+- Respect privacy laws (GDPR, CCPA)
+- Provide data opt-out mechanisms
+- Be transparent with customers about data sources
+
+### What to Avoid ❌
+- Selling scraped data to third parties
+- Storing sensitive personal data unnecessarily
+- Excessive scraping (respect rate limits)
+- Mixing with breached/unauthorized data
+
+---
+
+## Testing Your Integration
+
+### Test Profile URLs:
+```
+https://linkedin.com/in/williamhgates
+https://linkedin.com/in/jeffweiner08
+https://linkedin.com/in/satyanadella
+```
+
+### Quick Test:
+1. Add your `RAPIDAPI_KEY` to Spaces Secrets
+2. Restart the Space
+3. Go to "Consent/Event Audit" tab
+4. Add a contact with a LinkedIn URL
+5. Click "Refresh Data"
+6. See enriched profile information!
+
+---
+
+## Troubleshooting
+
+### "API Key Not Found" Error
+**Solution:** 
+- Verify `RAPIDAPI_KEY` is in Spaces Secrets
+- Check spelling (case-sensitive)
+- Restart Space after adding secret
+
+### "Rate Limit Exceeded" Error
+**Solution:**
+- You've used your 50 free requests this month
+- Wait until next month or upgrade plan
+- Implement caching to reduce requests
+
+### "Invalid Profile URL" Error
+**Solution:**
+- Use full LinkedIn URL: `https://linkedin.com/in/username`
+- Remove trailing slashes
+- Ensure profile is public
+
+### Slow Response Times
+**Solution:**
+- First request may take 2-3 seconds (normal)
+- Implement local caching for repeat requests
+- Consider background job queue for bulk enrichment
+
+---
+
+## Alternative Options
+
+### If You Need More Than 50/Month:
+
+**Option 1: User OAuth**
+- Have users connect their own LinkedIn
+- Zero API costs
+- Legal and compliant
+- Already supported in this app!
+
+**Option 2: Multiple RapidAPI Accounts**
+- Rotate between 2-3 free accounts
+- 150 requests/month total
+- Good for early stage
+
+**Option 3: Upgrade to Paid**
+- $50/month gets you 20,000 requests
+- Worth it once you have 3+ paying customers
+
+---
+
+## Advanced Features
+
+### Caching Implementation
+```python
+def get_cached_or_fetch(linkedin_url: str) -> dict:
+    cache_file = f"/data/linkedin_cache/{hash(linkedin_url)}.json"
+    
+    if os.path.exists(cache_file):
+        with open(cache_file, 'r') as f:
+            return json.load(f)
+    
+    profile = fetch_linkedin_profile(linkedin_url)
+    
+    if profile:
+        os.makedirs(os.path.dirname(cache_file), exist_ok=True)
+        with open(cache_file, 'w') as f:
+            json.dump(profile, f)
+    
+    return profile
+```
+
+### Bulk Enrichment
+```python
+def enrich_lead_list(leads: list) -> list:
+    enriched = []
+    for lead in leads:
+        if 'linkedin_url' in lead:
+            profile = fetch_linkedin_profile(lead['linkedin_url'])
+            if profile:
+                lead.update(profile)
+        enriched.append(lead)
+    return enriched
+```
+
+---
+
+## Support & Resources
+
+**RapidAPI Documentation:**
+- https://rapidapi.com/freshdata-freshdata-default/api/fresh-linkedin-profile-data
+
+**API Response Format:**
+```json
+{
+  "full_name": "John Doe",
+  "headline": "CEO at Company",
+  "location": "San Francisco, CA",
+  "summary": "Experienced leader...",
+  "experiences": [
+    {
+      "title": "CEO",
+      "company": "Company Name",
+      "start_date": "2020-01",
+      "end_date": null,
+      "description": "..."
+    }
+  ],
+  "education": [...],
+  "skills": [...]
+}
+```
+
+**Need Help?**
+- Check RapidAPI support: https://rapidapi.com/support
+- Review HF Spaces docs: https://huggingface.co/docs/hub/spaces
+- Contact StrategyStack support via Space discussions
+
+---
+
+## Summary
+
+✅ **Free tier available** (50 requests/month, no credit card)
+✅ **5-minute setup** (sign up, get key, add to Secrets)
+✅ **Already integrated** into the app (just add API key)
+✅ **Legal & compliant** (public data only)
+✅ **Scales with you** (upgrade when ready)
+
+**Get started now:** https://rapidapi.com
+
+---
+
+**Last Updated:** November 6, 2025
+**Integration Status:** ✅ Ready to use - just add API key!
+**Free Tier:** 50 requests/month | **Paid:** From $50/month