Hugging Face's logo

Spaces:
abc1181
/
Leads
Sleeping

App Files Community
Leads / docs /guide.md
abc1181's picture
abc1181
Mappls: support static REST key (MAPPLS_API_KEY) as well as OAuth
0b4f70e
preview code
|
Raw History Blame Contribute Delete
9.05 kB

LeadGen — Step-by-Step Guide (Personal Tool by AJ)

Single-owner India SMB finder: Maps → no-website hunt → scoring → AI icebreakers → Sheets. No bulk sending from this server.

1) What you need before you start

  • A Gmail account (owner — this will be the only login allowed via APP_ALLOW_EMAIL)
  • A Hugging Face account (for the Space at https://abc1181-leads.hf.space)
  • Optional but recommended: a Google Cloud project (for Places + OAuth) — free tier is enough

2) Create the Hugging Face Space

The code is already pushed to abc1181/Leads (Docker). Just configure envs:

  1. HF → Space abc1181/Leads → Settings → Variables (non-secrets) and Secrets (tokens)
  2. Set the essentials below (Section 3). The Space auto-restarts on save.
  3. Check https://abc1181-leads.hf.space/api/health → should be {"ok":true,"db":"ok","persistence":"on"}. If persistence:off, the Space has no /data bucket — it will still run on ephemeral /tmp (banner shows), but add a bucket at /data in Space Settings for durability.

3) Env vars — what to create

3.1 Essentials (app won't work without these)

Set in HF Variables unless marked Secret:

Key Where Value / How
APP_ALLOW_EMAIL Variables Your Gmail exactly — only this can sign in (middleware.ts:39, lib/auth.ts:14)
GOOGLE_CLIENT_ID Variables From Google Cloud OAuth (see 4.1)
GOOGLE_CLIENT_SECRET Secrets Same OAuth client
NEXTAUTH_SECRET Secrets Random 32b hex: openssl rand -hex 32 (already set)
NEXTAUTH_URL Variables https://abc1181-leads.hf.space (already set)
PLACES_API_KEY Secrets Google Places API key (see 4.2) — or leave empty and use the free OSM/Ola rail (Section 4.3)

Also needed (already set, don't change): DATABASE_URL=file:/data/leads.db, CRON_SECRET, ENCRYPTION_KEY

3.2 Optional — add when you want more coverage

Key Where Free tier Notes
OLA_API_KEY Secrets 100k/API/mo free India best free — docs/maps-providers.md#5
MAPPLS_CLIENT_ID + MAPPLS_CLIENT_SECRET Secrets Free eval, no card India best address hit — docs/maps-providers.md#4
FOURSQUARE_API_KEY Secrets 500 free calls Global fallback
HERE_API_KEY Secrets ~5k-250k free (needs card) Global fallback
ENRICH_PROVIDER=hunter + ENRICH_API_KEY Secrets 25-50/mo free Else phone is spine, emails stay unknown
LLM_BASE_URL + LLM_API_KEY + LLM_MODEL=mistral-large-latest Secrets Your gateway Else fallback templates (lib/ai/fallback.ts)
SMTP_HOST/PORT/USER/PASS or RESEND_API_KEY + DIGEST_TO Secrets/Vars 100/d free Else digest is in-app only
MOCK_SOURCES=1 Variables — Use for demo with 50 Delhi fixtures, no keys

No billing? Leave PLACES_API_KEY empty — the 6-provider rail (lib/sources/maps.ts) runs on OSM Overpass (free, no key) + OLA_API_KEY/MAPPLS_* if you set them. Add Google later and it stacks — no rebuild.

4) How to get each credential

4.1 Google OAuth (for Sign-in + Sheets)

  1. https://console.cloud.google.com → Create project → APIs & Services → OAuth consent screen → External → fill App name, Support email → Save
  2. Credentials → Create Credentials → OAuth client ID → Web application → Authorized redirect URI → add: https://abc1181-leads.hf.space/api/auth/callback/google → Create → copy Client ID and Client Secret → paste to HF as above.

4.2 Google Places API (New) — $200 free, needs billing

  1. Same Cloud project → APIs & Services → Enable APIs → search Places API (New) → Enable
  2. Credentials → Create Credentials → API key → Restrict → API restrictions → Places API (New) only → Save → copy to PLACES_API_KEY.
  3. Enable billing (Billing → Link account) to get the $200 credit — you won't be charged inside free. Our use ≈ $5-10 (lib/sources/places.ts:50 caps to 60 + Details only for no-website). Quota bar turns amber at 80% and degrades to partial.

4.3 Free India maps (no billing) — Mappls + Ola

  • Mappls: https://www.mapmyindia.com/api → Sign up → Dashboard → Create project → If you have a Static/REST key (your case), set MAPPLS_API_KEY; if you have OAuth pair, set MAPPLS_CLIENT_ID + MAPPLS_CLIENT_SECRET — either works. Free eval, no card.
  • Ola Maps: https://maps.olakrutrim.com → Sign up (Krutrim Cloud) → Credentials → API Key → OLA_API_KEY. 100k/API/mo free from 2026-09-01. GET https://api.olamaps.io/places/v1/nearbysearch?location=lat,lng&radius=&keyword= header X-API-KEY.

4.4 Other free maps (optional)

  • Foursquare: foursquare.com/developers → My Apps → Create App → API Key → FOURSQUARE_API_KEY (500 free).
  • HERE: developer.here.com → Project → API Key → HERE_API_KEY (needs card, pay-as-you-grow).
  • OSM Overpass: No key. Always on at https://overpass-api.de/api/interpreter.

Full per-provider table: docs/maps-providers.md.

4.5 Enrich (emails, optional)

  • Hunter: hunter.io → API key (25 free) → ENRICH_API_KEY with ENRICH_PROVIDER=hunter
  • Apollo: app.apollo.io → API key (50 free) → ENRICH_PROVIDER=apollo

4.6 LLM (AI drafts, optional)

Any OpenAI-compatible gateway. Set LLM_BASE_URL (e.g. https://api.mistral.ai/v1), LLM_API_KEY, LLM_MODEL=mistral-large-latest. Llama banned on any provider (lib/ai/llm.ts:44 — AUP). Prompts are PII-free (lib/ai/prompts.ts:8).

4.7 Email digest (optional)

  • Gmail: App Password → SMTP_HOST=smtp.gmail.com, SMTP_PORT=587, SMTP_USER, SMTP_PASS, DIGEST_TO=you@gmail.com
  • Resend: resend.com → API key → RESEND_API_KEY (100/d free)

5) Run locally (optional) 

cp .env.example .env.local   # fill with your keys; use absolute DATABASE_URL
# MUST be absolute locally (Prisma CLI vs app resolve differently):
# DATABASE_URL="file:/abs/path/to/leads-app/data/leads.db"
npm install --registry https://registry.npmjs.org/
npx prisma migrate dev       # creates data/leads.db
npm run dev                  # http://localhost:7860
npm test                     # 59 unit (lib 80% lines)
# integration (mock): INTEGRATION=1 MOCK_SOURCES=1 DATABASE_URL="file:$PWD/data/test.db" npx vitest run

6) How to use the app (morning loop)

  1. Searches → New search → pick template (Health/Beauty, Food, B2B/Factory, MidMarket/Upgrade, Generic) → city + radius (geocoded & cached, lib/geo.ts:4) → keywords → Cap 20/50/100/200 → Create. Star it for nightly.
  2. Run search → progress header (per-provider ms/quota) → tabs Hot/Warm/Cold (lib/score.ts:65 threshold) → table (filter by status/source/email/band/phone, sort score/rating) → drawer (AI draft violet, Copy/Regenerate, notes, blocklist).
  3. Verify all (concurrency 5, skips fresh <7d unless forced) → Push to Sheets (master LeadGen Master, tab per search, 21 cols, idempotent on email→phone→company|location via lib/sheets.ts:rowKey) → CSV fallback per run.
  4. Hot queue (/hot) is the morning inbox — j/k move, q qualify, c copy icebreaker, ? help.
  5. Dashboard shows Hot/Warm/Cold donut, per-source yield, category intel (Where the buyers are), quotas ($0), recent runs. Bell shows unread Hot + quota warnings.
  6. Settings → Quotas, Keys presence (masked), Scoring weights + Re-score, Templates, Sheets connect/disconnect (OAuth sealed lib/crypto.ts), Blocklist (undo), Danger (purge caches).

Nightly: GitHub Actions 30 20 * * * UTC (02:00 IST) pings /api/health 5× then POST /api/cron/nightly with CRON_SECRET (jobs/runner.ts:38 sequential, roles rolled if >25min). Digest top-10 Hot to DIGEST_TO (self only) + in-app bell.

7) Troubleshooting

  • https://abc1181-leads.hf.space/api/health → ok:true, db:ok, persistence:on means good. persistence:off = no bucket at /data — still runs on /tmp but data resets on restart (banner shows).
  • Sign-in 500 → GOOGLE_* or APP_ALLOW_EMAIL wrong, or redirect URI not set to https://abc1181-leads.hf.space/api/auth/callback/google.
  • Search returns 0 / partial → check quota bars in Settings; with no keys, OSM/Ola still work if those keys are set.
  • Chrome "Deceptive site" → fixed in c029112 by making /, /privacy, /terms public (no auto-Google redirect). If still cached, request review at https://transparencyreport.google.com/safe-browsing/search?url=https://abc1181-leads.hf.space

8) Branding & cost

  • Branding: Made by AJ · personal tool (sidebar/footer/landing, components/app-shell.tsx:39). No Vercel triangle.
  • Cost: $0 target (docs/runbook.md). Quota bars prove it. 80% banners + auto-degrade, never spend.

Questions? See PRD.md/TRD.md checkboxes (210 ticked, 52 intentionally unticked for live/V1.1/V2/parked).