leadgen-maps 1.1.0__tar.gz

leadgen_maps-1.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: leadgen-maps
+Version: 1.1.0
+Summary: Apollo-class local lead generation from Google Maps — no API. Streams leads to Notion, Google Sheets, or CSV with live progress and zero duplicates.
+Author: Auradevs
+License: Proprietary
+Project-URL: Homepage, https://github.com/subhadeeproy3902/lead-gen
+Project-URL: Repository, https://github.com/subhadeeproy3902/lead-gen
+Keywords: lead-generation,google-maps,scraper,notion,apollo,outreach,automation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: playwright>=1.49
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: fpdf2>=2.7
+Provides-Extra: sheets
+Requires-Dist: gspread>=6.0; extra == "sheets"
+Requires-Dist: google-auth>=2.0; extra == "sheets"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: all
+Requires-Dist: gspread>=6.0; extra == "all"
+Requires-Dist: google-auth>=2.0; extra == "all"
+Requires-Dist: mcp>=1.0; extra == "all"
+
+# leadgen 🗺️ → 📇
+
+**Apollo-class local lead generation from Google Maps. No API. Streams leads
+straight into Notion or CSV — with live progress and zero duplicates.**
+
+Ships in **two interchangeable editions** with the *same* CLI and the *same*
+41-field Apollo-grade output:
+
+| Edition | Best for | Install |
+|---|---|---|
+| 🐍 **Python** (`src/leadgen`) | Notion + **Google Sheets** + CSV + **XLSX/PDF**, scripting | `pipx install leadgen-maps` |
+| 🐹 **Go** (`go/`) | a single zero-dependency binary, terminal installs | `go install …` |
+
+> Better than Apollo for local SMBs: phone, website, socials, **geo-coordinates,
+> Google Place ID, rating, reviews, hours, photos, Lead Score** — and a
+> no-website filter to find your prime prospects. Apollo has none of that for a
+> neighbourhood business.
+
+---
+
+## 🔌 Connect Notion in one click — no keys, ever
+You **never paste keys into `.env`**. The first time you send leads to Notion,
+your browser opens, you authorize once, and the token is cached **only on your
+computer** (`~/.leadgen/credentials.json`). Every run after that is silent.
+```bash
+leadgen connect notion          # opens the browser, authorize once → done
+# or just run — it auto-connects the first time:
+leadgen run --niche "cafe" --location "Kolkata" --limit 30 --to notion
+```
+Google Sheets is the same — `leadgen connect google` opens the browser, you click
+**Allow**, and we **auto-create a Sheet** in your Drive:
+```bash
+leadgen connect google
+leadgen run --niche "cafe" --location "Kolkata" --limit 30 --to gsheets
+```
+Switch accounts or log out any time:
+```bash
+leadgen disconnect notion | google | all     # removes the local token
+```
+See **[CONNECT.md](CONNECT.md)** for the one-time OAuth setup (Notion + Google)
+and uninstall steps.
+
+## 🐍 Python edition
+```bash
+pipx install leadgen-maps          # public on PyPI — repo stays private
+python -m playwright install chromium
+leadgen connect notion             # one-time browser authorize (no .env)
+leadgen run --niche "cafe" --location "Kolkata" --limit 30 --to notion
+```
+Connectors: **Notion, Google Sheets, CSV, XLSX, PDF**. Hosting + email on
+completion in [`deploy/`](deploy/).
+
+## 🐹 Go edition (single binary)
+```bash
+go install github.com/subhadeeproy3902/lead-gen/go/cmd/leadgen@latest
+
+leadgen connect notion             # one-time browser authorize (no .env)
+leadgen run --niche "cafe" --location "Kolkata" --limit 30 --to notion
+```
+Connectors: **Notion, CSV, XLSX, PDF**. Drives your installed Chrome. See [`go/README.md`](go/README.md).
+
+---
+
+## Same CLI, both editions
+```bash
+leadgen run --niche "<type>" --location "<city>" --limit <N> --to notion --website without
+leadgen doctor        # internet, connectors, browser
+leadgen fields        # the 41-field Apollo-grade schema
+```
+```
+  [██████████░░░░░░] 21/30 leads (70%) │ #54 of 110 scanned │ ETA 1m20s │ Blue Tokai
+```
+
+## Let AI run it (Claude Code AND claude.ai)
+Ships an **MCP server** so any MCP-capable AI can call leadgen as a tool:
+- **Claude Code** — the included `.mcp.json` exposes it automatically; just ask "pull 15 gyms in Mumbai".
+- **claude.ai (website)** — run `python -m leadgen_maps.mcp_server --http`, expose it with a free tunnel, add it as a custom connector → the website executes leadgen on your machine.
+
+Exact steps: **[CONNECT-CLAUDE.md](CONNECT-CLAUDE.md)**. The plain CLI (`--json`
+events) and the agent skill ([`skills/leadgen/SKILL.md`](skills/leadgen/SKILL.md))
+also work.
+
+## Docs
+- **[CONNECT-CLAUDE.md](CONNECT-CLAUDE.md)** — let Claude Code + claude.ai run leadgen (MCP connector).
+- **[deploy/HOSTING-VPS.md](deploy/HOSTING-VPS.md)** — host a public, multi-tenant MCP server on a free VPS (e.g. `leadgen.auradevs.co/mcp`).
+- **[BUYER-GUIDE.md](BUYER-GUIDE.md)** — bought it? Dead-simple per-OS setup (Windows/Mac/Linux).
+- **[DOCUMENTATION.md](DOCUMENTATION.md)** — full guide (install, connectors, fields, hosting, edge cases).
+- **[DISTRIBUTION.md](DISTRIBUTION.md)** — install channels (release binary, `go install`, Homebrew, Scoop, winget).
+- **[ABOUT.md](ABOUT.md)** — what it is and why · **[prompt.md](prompt.md)** — paste into ChatGPT to drive it.
+- **[TESTS.md](TESTS.md)** — real runs with captured output + screenshots.
+
+Built by Auradevs.

leadgen_maps-1.1.0/README.md

@@ -0,0 +1,92 @@
+# leadgen 🗺️ → 📇
+
+**Apollo-class local lead generation from Google Maps. No API. Streams leads
+straight into Notion or CSV — with live progress and zero duplicates.**
+
+Ships in **two interchangeable editions** with the *same* CLI and the *same*
+41-field Apollo-grade output:
+
+| Edition | Best for | Install |
+|---|---|---|
+| 🐍 **Python** (`src/leadgen`) | Notion + **Google Sheets** + CSV + **XLSX/PDF**, scripting | `pipx install leadgen-maps` |
+| 🐹 **Go** (`go/`) | a single zero-dependency binary, terminal installs | `go install …` |
+
+> Better than Apollo for local SMBs: phone, website, socials, **geo-coordinates,
+> Google Place ID, rating, reviews, hours, photos, Lead Score** — and a
+> no-website filter to find your prime prospects. Apollo has none of that for a
+> neighbourhood business.
+
+---
+
+## 🔌 Connect Notion in one click — no keys, ever
+You **never paste keys into `.env`**. The first time you send leads to Notion,
+your browser opens, you authorize once, and the token is cached **only on your
+computer** (`~/.leadgen/credentials.json`). Every run after that is silent.
+```bash
+leadgen connect notion          # opens the browser, authorize once → done
+# or just run — it auto-connects the first time:
+leadgen run --niche "cafe" --location "Kolkata" --limit 30 --to notion
+```
+Google Sheets is the same — `leadgen connect google` opens the browser, you click
+**Allow**, and we **auto-create a Sheet** in your Drive:
+```bash
+leadgen connect google
+leadgen run --niche "cafe" --location "Kolkata" --limit 30 --to gsheets
+```
+Switch accounts or log out any time:
+```bash
+leadgen disconnect notion | google | all     # removes the local token
+```
+See **[CONNECT.md](CONNECT.md)** for the one-time OAuth setup (Notion + Google)
+and uninstall steps.
+
+## 🐍 Python edition
+```bash
+pipx install leadgen-maps          # public on PyPI — repo stays private
+python -m playwright install chromium
+leadgen connect notion             # one-time browser authorize (no .env)
+leadgen run --niche "cafe" --location "Kolkata" --limit 30 --to notion
+```
+Connectors: **Notion, Google Sheets, CSV, XLSX, PDF**. Hosting + email on
+completion in [`deploy/`](deploy/).
+
+## 🐹 Go edition (single binary)
+```bash
+go install github.com/subhadeeproy3902/lead-gen/go/cmd/leadgen@latest
+
+leadgen connect notion             # one-time browser authorize (no .env)
+leadgen run --niche "cafe" --location "Kolkata" --limit 30 --to notion
+```
+Connectors: **Notion, CSV, XLSX, PDF**. Drives your installed Chrome. See [`go/README.md`](go/README.md).
+
+---
+
+## Same CLI, both editions
+```bash
+leadgen run --niche "<type>" --location "<city>" --limit <N> --to notion --website without
+leadgen doctor        # internet, connectors, browser
+leadgen fields        # the 41-field Apollo-grade schema
+```
+```
+  [██████████░░░░░░] 21/30 leads (70%) │ #54 of 110 scanned │ ETA 1m20s │ Blue Tokai
+```
+
+## Let AI run it (Claude Code AND claude.ai)
+Ships an **MCP server** so any MCP-capable AI can call leadgen as a tool:
+- **Claude Code** — the included `.mcp.json` exposes it automatically; just ask "pull 15 gyms in Mumbai".
+- **claude.ai (website)** — run `python -m leadgen_maps.mcp_server --http`, expose it with a free tunnel, add it as a custom connector → the website executes leadgen on your machine.
+
+Exact steps: **[CONNECT-CLAUDE.md](CONNECT-CLAUDE.md)**. The plain CLI (`--json`
+events) and the agent skill ([`skills/leadgen/SKILL.md`](skills/leadgen/SKILL.md))
+also work.
+
+## Docs
+- **[CONNECT-CLAUDE.md](CONNECT-CLAUDE.md)** — let Claude Code + claude.ai run leadgen (MCP connector).
+- **[deploy/HOSTING-VPS.md](deploy/HOSTING-VPS.md)** — host a public, multi-tenant MCP server on a free VPS (e.g. `leadgen.auradevs.co/mcp`).
+- **[BUYER-GUIDE.md](BUYER-GUIDE.md)** — bought it? Dead-simple per-OS setup (Windows/Mac/Linux).
+- **[DOCUMENTATION.md](DOCUMENTATION.md)** — full guide (install, connectors, fields, hosting, edge cases).
+- **[DISTRIBUTION.md](DISTRIBUTION.md)** — install channels (release binary, `go install`, Homebrew, Scoop, winget).
+- **[ABOUT.md](ABOUT.md)** — what it is and why · **[prompt.md](prompt.md)** — paste into ChatGPT to drive it.
+- **[TESTS.md](TESTS.md)** — real runs with captured output + screenshots.
+
+Built by Auradevs.

leadgen_maps-1.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "leadgen-maps"
+version = "1.1.0"
+description = "Apollo-class local lead generation from Google Maps — no API. Streams leads to Notion, Google Sheets, or CSV with live progress and zero duplicates."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "Auradevs" }]
+keywords = ["lead-generation", "google-maps", "scraper", "notion", "apollo", "outreach", "automation"]
+dependencies = [
+    "playwright>=1.49",
+    "openpyxl>=3.1",
+    "fpdf2>=2.7",
+]
+
+[project.optional-dependencies]
+sheets = ["gspread>=6.0", "google-auth>=2.0"]
+mcp = ["mcp>=1.0"]
+all = ["gspread>=6.0", "google-auth>=2.0", "mcp>=1.0"]
+
+[project.scripts]
+leadgen = "leadgen_maps.cli:main"
+leadgen-maps = "leadgen_maps.cli:main"
+leadgen-mcp = "leadgen_maps.mcp_server:main"
+
+[project.urls]
+Homepage = "https://github.com/subhadeeproy3902/lead-gen"
+Repository = "https://github.com/subhadeeproy3902/lead-gen"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+leadgen_maps = ["py.typed", "logo.svg"]

leadgen_maps-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

leadgen_maps-1.1.0/src/leadgen_maps/__init__.py

@@ -0,0 +1,10 @@
+"""
+leadgen — Apollo-class local lead generation from Google Maps, no API.
+
+Scrapes Google Maps via real browser automation, extracts a rich Apollo-grade
+field set, and streams leads directly into your connector of choice (Notion,
+Google Sheets, or CSV) with live progress and guaranteed de-duplication.
+"""
+
+__version__ = "1.0.0"
+__all__ = ["__version__"]

leadgen_maps-1.1.0/src/leadgen_maps/__main__.py

@@ -0,0 +1,8 @@
+"""Enable `python -m leadgen_maps ...`."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

leadgen_maps-1.1.0/src/leadgen_maps/cli.py

@@ -0,0 +1,226 @@
+"""
+leadgen command-line interface.
+
+  leadgen run --niche "cafe" --location "Kolkata" --limit 30 --to notion
+  leadgen run --niche "dentist" --location "Pune" --limit 50 --website any --to csv,notion
+  leadgen doctor          # check internet, connectors, license
+  leadgen fields          # list the Apollo-grade field set
+  leadgen connectors      # list available push targets
+
+AI agents: add --json to stream machine-readable progress + a final summary
+object on stdout (one JSON event per line).
+"""
+
+import argparse
+import json
+import sys
+
+from . import __version__, config, fields, net
+
+
+def _err(msg, json_mode=False):
+    if json_mode:
+        sys.stdout.write(json.dumps({"event": "fatal", "error": msg}) + "\n")
+    else:
+        sys.stderr.write(f"\nERROR: {msg}\n")
+    return 2
+
+
+def cmd_run(args):
+    to = [t.strip() for t in args.to.split(",") if t.strip()]
+    columns = fields.select_columns(args.fields)
+
+    # Keyless connect: if a destination is requested but not linked yet, open the
+    # browser and connect once — no .env, no keys.
+    if not args.json:
+        lowered = [t.lower() for t in to]
+        if "notion" in lowered:
+            from .connectors.notion import notion_connected
+            if not notion_connected():
+                from .connect import connect_notion
+                print("[leadgen] Notion isn't connected yet — let's fix that once.")
+                try:
+                    connect_notion()
+                except Exception as e:
+                    return _err(f"connect notion: {e}", args.json)
+                print("[leadgen] ✓ Notion connected. Continuing your run…")
+        if any(t in lowered for t in ("gsheets", "sheets", "google")):
+            from .connectors.gsheets import gsheets_connected
+            if not gsheets_connected():
+                from .connect import connect_google
+                print("[leadgen] Google Sheets isn't connected yet — let's fix that once.")
+                try:
+                    connect_google()
+                except Exception as e:
+                    return _err(f"connect google: {e}", args.json)
+                print("[leadgen] ✓ Google Sheets connected. Continuing your run…")
+
+    try:
+        from .engine import run
+        summary = run(
+            niche=args.niche, location=args.location, limit=args.limit,
+            website=args.website, to=to, columns=columns, country_code=args.cc,
+            headless=not args.show, want_reviews=not args.no_reviews,
+            json_mode=args.json, notify_email=args.email,
+        )
+    except net.OfflineError as e:
+        return _err(str(e), args.json)
+    except Exception as e:
+        return _err(f"{type(e).__name__}: {e}", args.json)
+
+    if args.json:
+        sys.stdout.write(json.dumps({"event": "summary", **summary}) + "\n")
+    else:
+        print(f"\n{'='*58}")
+        print(f"  ✓ {summary['kept']} new leads  (target {summary['target']})")
+        print(f"  scanned {summary['queued']} listings · "
+              f"{summary['skipped_filtered']} filtered · "
+              f"{summary['skipped_duplicate']} duplicate · "
+              f"{summary['skipped_no_phone']} no-phone")
+        for name, loc in summary["connectors"].items():
+            print(f"  → {name}: {loc}")
+        if summary.get("emailed"):
+            print(f"  ✉ emailed {summary['emailed']}")
+        print(f"{'='*58}")
+    return 0
+
+
+def cmd_connect(args):
+    target = (args.target or "notion").lower()
+    if target == "notion":
+        from .connect import connect_notion
+        try:
+            info = connect_notion(allow_paste=getattr(args, "paste", False))
+        except Exception as e:
+            return _err(str(e))
+        ws = info.get("workspace_name") or "your workspace"
+        print(f"\n[leadgen] ✓ Connected to {ws}. Leads database is ready.")
+        print('[leadgen] Try: leadgen run --niche "cafe" --location "Kolkata" --limit 10 --to notion')
+        return 0
+    if target in ("google", "gsheets", "sheets"):
+        from .connect import connect_google
+        try:
+            info = connect_google()
+        except Exception as e:
+            return _err(str(e))
+        print(f"\n[leadgen] ✓ Connected Google Sheets. Your sheet:")
+        print(f"  https://docs.google.com/spreadsheets/d/{info['spreadsheet_id']}")
+        print('[leadgen] Try: leadgen run --niche "cafe" --location "Kolkata" --limit 10 --to gsheets')
+        return 0
+    return _err(f"don't know how to connect '{target}' (supported: notion, google)")
+
+
+def cmd_disconnect(args):
+    target = (args.target or "all").lower()
+    from . import credstore
+    if target == "notion":
+        credstore.clear("notion"); what = "Notion"
+    elif target in ("google", "gsheets", "sheets"):
+        credstore.clear("google"); what = "Google Sheets"
+    elif target in ("all", ""):
+        credstore.clear_all(); what = "all connections"
+    else:
+        return _err(f"don't know how to disconnect '{target}' (supported: notion, google, all)")
+    print(f"[leadgen] ✓ Disconnected {what}. Re-link any time with `leadgen connect`.")
+    return 0
+
+
+def cmd_doctor(args):
+    print("leadgen doctor")
+    print(f"  version           : {__version__}")
+    online = net.is_online()
+    print(f"  internet          : {'OK' if online else 'OFFLINE (required!)'}")
+    from .connectors.notion import notion_connected
+    from .connectors.gsheets import gsheets_connected
+    print(f"  Notion connected  : {'yes (relink: leadgen connect notion)' if notion_connected() else 'no — run `leadgen connect notion`'}")
+    print(f"  Google Sheets     : {'connected (relink: leadgen connect google)' if gsheets_connected() else 'not connected — run `leadgen connect google`'}")
+    print(f"  SMTP (email)      : {'configured' if config.SMTP_HOST else 'not configured'}")
+    try:
+        import playwright  # noqa: F401
+        print("  Playwright        : installed")
+    except ImportError:
+        print("  Playwright        : MISSING — run `python -m playwright install chromium`")
+    return 0 if online else 1
+
+
+def cmd_fields(args):
+    if args.json:
+        out = [{"key": k, "label": fields.LABELS[k], "type": fields.TYPES[k],
+                "group": fields.GROUPS[k], "source": fields.SOURCE[k]} for k in fields.KEYS]
+        print(json.dumps(out, indent=2)); return 0
+    group = None
+    for k in fields.KEYS:
+        if fields.GROUPS[k] != group:
+            group = fields.GROUPS[k]
+            print(f"\n{group}")
+        print(f"  {k:<16} {fields.LABELS[k]:<20} {fields.TYPES[k]:<12} [{fields.SOURCE[k]}]")
+    print(f"\n{len(fields.KEYS)} fields. Use --fields default|all|apollo|<comma,list>")
+    return 0
+
+
+def cmd_connectors(args):
+    from .connectors import NAMES
+    print("Available connectors (--to):")
+    print("  notion   — Notion database (rich pages, photos, reviews) · `leadgen connect notion`")
+    print("  gsheets  — Google Sheets (keyless OAuth) · `leadgen connect google`")
+    print("  csv      — local CSV table view")
+    print("  xlsx     — local Excel workbook (.xlsx)")
+    print("  pdf      — local printable lead sheet (.pdf)")
+    print("\nCombine with commas, e.g. --to notion,gsheets,xlsx,pdf")
+    return 0
+
+
+def build_parser():
+    p = argparse.ArgumentParser(prog="leadgen", description="Apollo-class local lead-gen from Google Maps (no API).")
+    p.add_argument("--version", action="version", version=f"leadgen {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+
+    r = sub.add_parser("run", help="run a lead-gen job")
+    r.add_argument("--niche", required=True, help='business type, e.g. "cafe"')
+    r.add_argument("--location", required=True, help='city/area, e.g. "Kolkata"')
+    r.add_argument("--limit", type=int, default=30, help=f"how many NEW leads (max {config.MAX_LIMIT})")
+    r.add_argument("--website", choices=["without", "with", "any"], default="without",
+                   help="keep businesses without a website (default), with one, or any")
+    r.add_argument("--to", default="notion", help="connector(s), comma list: notion,gsheets,csv,xlsx,pdf")
+    r.add_argument("--fields", default="default", help="default|all|apollo|<comma,list of keys>")
+    r.add_argument("--cc", default=None, help="country calling code (default 91 → Region India)")
+    r.add_argument("--show", action="store_true", help="show the browser window")
+    r.add_argument("--no-reviews", action="store_true", help="skip review snippets (faster)")
+    r.add_argument("--email", default=None, help="email a summary when the job finishes")
+    r.add_argument("--json", action="store_true", help="stream JSON events (for AI agents)")
+    r.set_defaults(func=cmd_run)
+
+    cn = sub.add_parser("connect", help="connect a destination (keyless, browser-based)")
+    cn.add_argument("target", nargs="?", default="notion", help="what to connect: notion | google")
+    cn.add_argument("--paste", action="store_true", help="(Notion) paste an integration token once instead of OAuth")
+    cn.set_defaults(func=cmd_connect)
+
+    dc = sub.add_parser("disconnect", help="remove a stored connection (logout) — notion | google | all")
+    dc.add_argument("target", nargs="?", default="all", help="what to disconnect: notion | google | all")
+    dc.set_defaults(func=cmd_disconnect)
+
+    d = sub.add_parser("doctor", help="check environment, connectors, license")
+    d.set_defaults(func=cmd_doctor)
+
+    f = sub.add_parser("fields", help="list the field set")
+    f.add_argument("--json", action="store_true")
+    f.set_defaults(func=cmd_fields)
+
+    c = sub.add_parser("connectors", help="list push targets")
+    c.set_defaults(func=cmd_connectors)
+    return p
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "cmd", None):
+        parser.print_help()
+        return 0
+    if not hasattr(args, "json"):
+        args.json = False
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

leadgen_maps-1.1.0/src/leadgen_maps/config.py

@@ -0,0 +1,74 @@
+"""Configuration + .env loading for leadgen. Secrets never live in code."""
+
+import os
+
+MAX_LIMIT = 256  # hard cap on leads per run (product constraint)
+
+
+def load_dotenv(explicit=None):
+    """Load KEY=VALUE pairs from the first .env found (cwd, then ~/.leadgen)."""
+    candidates = []
+    if explicit:
+        candidates.append(explicit)
+    d = os.getcwd()
+    for _ in range(6):  # walk up to find a shared root .env (works from subfolders)
+        candidates.append(os.path.join(d, ".env"))
+        parent = os.path.dirname(d)
+        if parent == d:
+            break
+        d = parent
+    candidates.append(os.path.expanduser(os.path.join("~", ".leadgen", ".env")))
+    for path in candidates:
+        if path and os.path.exists(path):
+            with open(path, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line or line.startswith("#") or "=" not in line:
+                        continue
+                    k, v = line.split("=", 1)
+                    os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))
+            return path
+    return None
+
+
+load_dotenv()
+
+
+def get(name, default=""):
+    return os.environ.get(name, default)
+
+
+def get_bool(name, default=False):
+    v = os.environ.get(name)
+    if v is None:
+        return default
+    return v.strip().lower() in ("1", "true", "yes", "on")
+
+
+def get_float(name, default):
+    try:
+        return float(os.environ.get(name, default))
+    except (TypeError, ValueError):
+        return default
+
+
+# ── Connectors ───────────────────────────────────────────────────────────────
+NOTION_TOKEN = get("NOTION_TOKEN")
+NOTION_DATABASE_ID = get("NOTION_DATABASE_ID")
+
+GOOGLE_SERVICE_ACCOUNT_JSON = get("GOOGLE_SERVICE_ACCOUNT_JSON")  # path to creds file
+GSHEET_ID = get("GSHEET_ID")
+GSHEET_TAB = get("GSHEET_TAB", "Leads")
+
+# ── Notifications (email on completion) ──────────────────────────────────────
+SMTP_HOST = get("SMTP_HOST")
+SMTP_PORT = int(get("SMTP_PORT", "587") or 587)
+SMTP_USER = get("SMTP_USER")
+SMTP_PASS = get("SMTP_PASS")
+NOTIFY_EMAIL = get("NOTIFY_EMAIL")
+
+# ── Scrape defaults ──────────────────────────────────────────────────────────
+DEFAULT_COUNTRY_CODE = get("DEFAULT_COUNTRY_CODE", "91")
+HEADLESS = get_bool("HEADLESS", True)
+MIN_DELAY = get_float("MIN_DELAY", 1.0)
+MAX_DELAY = get_float("MAX_DELAY", 2.5)