feat: Telegram via Cloudflare Worker relay (HF blocks Telegram egress)

Confirmed via /telegram/diag that HF blocks outbound to api.telegram.org.
Add a Cloudflare Worker relay (relay/cloudflare-worker.js + relay/README.md)
that reaches Telegram and calls HF /api/generate. Extend /api/generate:
accept jd_url (server-side JD fetch via src/jd_from_url), make jd_text optional,
and fall back to the bundled default resume when no resume is supplied.
Backward-compatible with the extension.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

HISTORY.md

@@ -4,6 +4,33 @@ A running log of everything built, fixed, and changed. Most recent first.
 
 ---
 
+## 2026-06-24 (AM4) — Telegram via Cloudflare relay (HF blocks Telegram egress)
+
+`GET /telegram/diag` confirmed it definitively: from inside the Space,
+`getMe` to api.telegram.org read-times-out at 5s with no proxy — **HF blocks
+outbound to Telegram**. Inbound webhooks arrive, but the Space can never send
+replies. IPv4/retries can't fix a blocked route.
+
+Solution (owner chose "free relay host"): a **Cloudflare Worker** relay that can
+reach Telegram. Telegram → Worker → HF `/api/generate` → Worker sends the PDF.
+`ctx.waitUntil` acks Telegram instantly then finishes the ~30–60s job in the
+background (avoids Telegram's ~60s webhook-retry).
+
+- `relay/cloudflare-worker.js` — the Worker (allowlist, status msgs, calls HF,
+  sends PDF or .tex fallback). Holds no resume data.
+- `relay/README.md` — full Cloudflare setup + re-point the Telegram webhook.
+- `api_server.py` `/api/generate` extended so the Worker stays thin:
+  - `jd_url` form field → server fetches + extracts the JD via `src/jd_from_url.py`
+    (returns `{"error":"jd_unreadable"}` when a link can't be read so the bot asks
+    for pasted text);
+  - `jd_text` is now optional (required only if no `jd_url`);
+  - resume falls back to the bundled default when no `resume_latex`/PDF supplied.
+  Backward-compatible with the extension (still sends `jd_text` + `resume_latex`).
+- The in-Space `/telegram/webhook` + `/telegram/diag` remain for diagnostics; the
+  working path is now the Cloudflare relay.
+
+---
+
 ## 2026-06-24 (AM3) — Fix Telegram bot: force IPv4 to api.telegram.org + retries
 
 After making the Space public, the webhook received updates (`POST /telegram/webhook

README.md

@@ -258,29 +258,25 @@ Hybrid scoring: **70% JD Match + 30% Resume Quality**
 
 ---
 
-## Telegram Bot (mobile touchpoint)
+## Telegram Bot (mobile touchpoint, via Cloudflare relay)
 
 Third touchpoint alongside the Streamlit app and Chrome extension: send a **job
 link** (or paste the JD) to your Telegram bot and get back a tailored resume PDF.
-Reuses the exact same pipeline (hardcoded default resume + Maximum ATS Mode +
-structured placement + Tectonic compile). Endpoint: `POST /telegram/webhook` on
-the HF Space; generation runs in a background task so Telegram gets an instant ACK.
-
-**Setup (one-time):**
-1. In Telegram, message **@BotFather** → `/newbot` → copy the **bot token**.
-2. Message **@userinfobot** → copy your numeric **user ID**.
-3. HF Space → Settings → Secrets, add:
-   - `TELEGRAM_BOT_TOKEN` = the BotFather token
-   - `TELEGRAM_ALLOWED_USER_IDS` = your numeric ID (comma-separated for multiple; **empty = nobody**, fail-closed)
-   - `TELEGRAM_WEBHOOK_SECRET` = any random string (optional but recommended)
-4. After the Space redeploys, register the webhook (paste in a browser, filling in
-   token/secret/space):
-   `https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://<your-space>.hf.space/telegram/webhook&secret_token=<SECRET>`
-   (or run `python scripts/telegram_set_webhook.py set https://<your-space>.hf.space`).
-
-**Use:** send a job URL (Greenhouse/Lever/Ashby/Naukri/public pages fetch directly;
-LinkedIn/Indeed may be blocked server-side → the bot asks you to paste the JD text),
-or just paste the full job description. The bot replies with the compiled PDF.
+
+**Architecture note:** HF Spaces *block outbound traffic to `api.telegram.org`*, so
+the HF app can receive webhooks but can't send replies. The bot therefore runs
+through a tiny **Cloudflare Worker** relay (free, always-on, can reach Telegram):
+Telegram → Worker → HF `/api/generate` (does JD-fetch + tailoring + Tectonic
+compile) → Worker sends the PDF back. Worker code + full setup:
+[`relay/cloudflare-worker.js`](relay/cloudflare-worker.js) and
+[`relay/README.md`](relay/README.md).
+
+`/api/generate` accepts `jd_url` (server fetches/extracts the JD) or `jd_text`, and
+falls back to the bundled default resume when no resume is supplied — so the relay
+stays a thin Telegram-I/O layer.
+
+(The legacy in-Space `POST /telegram/webhook` + `GET /telegram/diag` remain for
+diagnostics, but the working path is the Cloudflare relay because of the egress block.)
 
 ## Chrome Extension + JSON API
 

api_server.py

@@ -494,7 +494,8 @@ async def telegram_webhook(request: Request, background_tasks: BackgroundTasks):
 # ── /api/generate ─────────────────────────────────────────────────────────────
 @app.post("/api/generate")
 async def generate(
-    jd_text: str = Form(...),
+    jd_text: str = Form(""),
+    jd_url: str = Form(""),                  # Telegram relay: fetch JD from a link
     job_title: str = Form(""),
     company: str = Form(""),
     maximum_ats_mode: str = Form(""),       # "1"/"true" enables Maximum ATS Mode
@@ -508,10 +509,11 @@ async def generate(
     Generate a tailored resume DOCX (and optional PDF) for the supplied JD.
 
     Request: multipart/form-data
-      - jd_text   (required) — full job description text
+      - jd_text   — full job description text (required unless jd_url given)
+      - jd_url    — a job link; server fetches + extracts the JD (Telegram relay)
       - job_title (optional) — for recruiter pitch header
       - company   (optional) — for recruiter pitch header
-      - resume    (required) — PDF file bytes of the candidate's resume
+      - resume    — PDF bytes; OPTIONAL — falls back to the bundled default resume
       Header: X-Api-Token — must match API_SECRET_TOKEN env var (when set)
 
     Response: JSON with docx_b64, pdf_b64, status, scores, quality_flag, etc.
@@ -521,6 +523,37 @@ async def generate(
     max_ats = _truthy(maximum_ats_mode) or _truthy(user_confirmed_expansion)
     conf_terms = _term_list(confirmed_terms)
 
+    # ── jd_url → fetch + extract the JD server-side (used by the Telegram relay) ──
+    if not (jd_text or "").strip() and (jd_url or "").strip():
+        try:
+            from src.jd_from_url import fetch_jd_from_url
+            res = fetch_jd_from_url(jd_url.strip())
+            if res.get("ok"):
+                jd_text = res["jd_text"]
+                job_title = job_title or res.get("job_title", "")
+            else:
+                return JSONResponse(
+                    {"error": "jd_unreadable",
+                     "detail": "Couldn't read that link server-side. Paste the job "
+                               "description text instead."},
+                    status_code=200,
+                )
+        except Exception as exc:  # noqa: BLE001
+            return JSONResponse({"error": "jd_fetch_failed", "detail": str(exc)[:200]},
+                                status_code=200)
+
+    if not (jd_text or "").strip():
+        return JSONResponse({"error": "jd_required",
+                             "detail": "Provide jd_text or jd_url."}, status_code=200)
+
+    # ── Resume fallback: no LaTeX and no PDF → use the bundled default resume. ────
+    if not (resume_latex or "").strip() and resume is None:
+        try:
+            from src.default_resume import get_default_resume_latex
+            resume_latex = get_default_resume_latex()
+        except Exception:  # noqa: BLE001
+            pass
+
     # ── LaTeX-first: if the user supplied LaTeX source, use it (priority over the
     #    uploaded PDF) for keyword matching + scoring, then compile to PDF. ──────
     if (resume_latex or "").strip():

relay/README.md

@@ -0,0 +1,51 @@
+# Telegram → Resume PDF relay (Cloudflare Worker)
+
+HF Spaces block outbound traffic to `api.telegram.org`, so the HF app can receive
+Telegram webhooks but can't send replies. This tiny Cloudflare Worker runs on a
+network that *can* reach Telegram: it receives the webhook, calls your HF
+`/api/generate` (which works publicly), and sends the PDF back to Telegram.
+
+Cloudflare Workers are free, always-on, and `ctx.waitUntil()` lets the Worker ack
+Telegram instantly then finish the ~30–60s job in the background (so Telegram
+doesn't time out and retry).
+
+## One-time setup (~15 min)
+
+1. **Create the Worker**
+   - Go to https://dash.cloudflare.com → **Workers & Pages** → **Create** → **Create Worker**.
+   - Give it a name (e.g. `jaa-telegram-relay`) → **Deploy** (creates a placeholder).
+   - Click **Edit code**, delete the sample, paste the contents of
+     `relay/cloudflare-worker.js`, then **Deploy**.
+   - Copy the Worker URL, e.g. `https://jaa-telegram-relay.<you>.workers.dev`.
+
+2. **Set the Worker's Variables & Secrets**
+   Worker → **Settings** → **Variables and Secrets** → add (type "Secret" for the token):
+   | Name | Value |
+   |---|---|
+   | `TELEGRAM_BOT_TOKEN` | your BotFather token |
+   | `ALLOWED_USER_IDS` | your numeric Telegram ID (comma-separated for more) |
+   | `HF_API_URL` | `https://saitejatirunagari-jaa-ats-tool.hf.space` |
+   | `HF_API_TOKEN` | your `API_SECRET_TOKEN` (same value as the HF secret) |
+   | `WEBHOOK_SECRET` | any random string (optional but recommended) |
+   Re-deploy after saving.
+
+3. **Point Telegram at the Worker** (paste in a browser, filling in token/secret/worker URL):
+   ```
+   https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://jaa-telegram-relay.<you>.workers.dev&secret_token=<WEBHOOK_SECRET>
+   ```
+   Expect `{"ok":true,...,"description":"Webhook was set"}`.
+   (This replaces the old HF webhook — the bot now flows through Cloudflare.)
+
+4. **Make sure `API_SECRET_TOKEN` is set on the HF Space** (it gates `/api/generate`)
+   and equals the Worker's `HF_API_TOKEN`.
+
+## Use
+Message the bot a **job link** or paste the **job description** → it replies with
+the tailored PDF. The HF Space must be public (the Worker calls it unauthenticated
+with the API token).
+
+## Notes
+- First request after the HF Space has been idle is slower (cold start ~30s).
+- LinkedIn/Indeed links may not be fetchable server-side; the bot will ask you to
+  paste the description text (always works).
+- The Worker holds no resume data — HF uses your bundled default resume.

relay/cloudflare-worker.js

@@ -0,0 +1,142 @@
+/**
+ * Telegram → resume PDF relay (Cloudflare Worker).
+ *
+ * WHY: Hugging Face Spaces block outbound traffic to api.telegram.org, so the HF
+ * app can RECEIVE Telegram webhooks but can't SEND replies. This tiny Worker runs
+ * on Cloudflare (which can reach Telegram), receives the webhook, calls the HF
+ * /api/generate endpoint (which works publicly), and sends the PDF back to Telegram.
+ *
+ * It acks Telegram instantly and finishes the ~30–60s job via ctx.waitUntil so
+ * Telegram never times out and retries.
+ *
+ * Deploy: paste into a Cloudflare Worker. Set these Variables/Secrets:
+ *   TELEGRAM_BOT_TOKEN   — from @BotFather
+ *   ALLOWED_USER_IDS     — comma-separated numeric Telegram user IDs (allowlist)
+ *   HF_API_URL           — https://<your-space>.hf.space
+ *   HF_API_TOKEN         — your API_SECRET_TOKEN (matches the HF secret)
+ *   WEBHOOK_SECRET       — optional; must match the setWebhook secret_token
+ * Then point the Telegram webhook at the Worker URL (see relay/README.md).
+ */
+
+const HELP =
+  "👋 Send me a *job link* (or paste the full job description) and I'll send back " +
+  "your tailored, ATS-optimized resume PDF.\n\n" +
+  "• Company/ATS links (Greenhouse, Lever, Ashby, Naukri) usually work directly.\n" +
+  "• If I can't read a LinkedIn/Indeed link, copy the description text and send that.\n\n" +
+  "Commands: /start, /help";
+
+export default {
+  async fetch(request, env, ctx) {
+    if (request.method !== "POST") return new Response("ok"); // health/GET
+    if (env.WEBHOOK_SECRET &&
+        request.headers.get("x-telegram-bot-api-secret-token") !== env.WEBHOOK_SECRET) {
+      return new Response("forbidden", { status: 403 });
+    }
+    let update;
+    try { update = await request.json(); } catch { return new Response("ok"); }
+    ctx.waitUntil(handle(update, env));   // finish in background; ack now
+    return new Response("ok");
+  },
+};
+
+function tgUrl(env, method) {
+  return `https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/${method}`;
+}
+
+async function tg(env, method, payload) {
+  try {
+    await fetch(tgUrl(env, method), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+  } catch (_) { /* best-effort */ }
+}
+
+async function handle(update, env) {
+  const msg = update.message || update.edited_message;
+  if (!msg) return;
+  const chatId = msg.chat && msg.chat.id;
+  const userId = msg.from && msg.from.id;
+  const text = (msg.text || "").trim();
+  if (chatId == null) return;
+
+  const allowed = (env.ALLOWED_USER_IDS || "")
+    .split(/[,\s]+/).filter(Boolean).map(Number);
+  if (!allowed.length || !allowed.includes(Number(userId))) {
+    await tg(env, "sendMessage", { chat_id: chatId, text: "⛔ This bot is private." });
+    return;
+  }
+
+  if (!text || /^\/(start|help)\b/i.test(text)) {
+    await tg(env, "sendMessage", { chat_id: chatId, text: HELP, parse_mode: "Markdown" });
+    return;
+  }
+
+  const urlMatch = text.match(/https?:\/\/\S+/);
+  const form = new FormData();
+  if (urlMatch) {
+    await tg(env, "sendMessage", { chat_id: chatId, text: "🔍 Reading the job & generating your resume… (~30–60s)" });
+    form.append("jd_url", urlMatch[0].replace(/[).,]+$/, ""));
+  } else if (text.length >= 200) {
+    await tg(env, "sendMessage", { chat_id: chatId, text: "⚙️ Generating your ATS resume… (~30–60s)" });
+    form.append("jd_text", text);
+  } else {
+    await tg(env, "sendMessage", { chat_id: chatId, text: "Send a job link, or paste the full job description (a paragraph or more)." });
+    return;
+  }
+  form.append("maximum_ats_mode", "1");
+
+  let res;
+  try {
+    const r = await fetch(`${env.HF_API_URL.replace(/\/$/, "")}/api/generate`, {
+      method: "POST",
+      headers: { "X-Api-Token": env.HF_API_TOKEN || "" },
+      body: form,
+    });
+    res = await r.json();
+  } catch (e) {
+    await tg(env, "sendMessage", { chat_id: chatId, text: "❌ Generation service is waking up or busy. Try again in a minute." });
+    return;
+  }
+
+  if (res.error === "jd_unreadable") {
+    await tg(env, "sendMessage", { chat_id: chatId, text: "⚠️ I couldn't read that link (LinkedIn/Indeed block server access). Please copy the *job description text* and send it to me." , parse_mode: "Markdown" });
+    return;
+  }
+  if (res.error) {
+    await tg(env, "sendMessage", { chat_id: chatId, text: `❌ ${res.detail || res.error}` });
+    return;
+  }
+
+  const cov = res.external_coverage_pct != null ? res.external_coverage_pct
+            : (res.scores && res.scores.jd_match);
+  if (res.pdf_b64) {
+    await sendDoc(env, chatId, res.pdf_b64, "resume.pdf", "application/pdf",
+                  `✅ Tailored resume — ~${cov ?? "?"}% JD keyword coverage.`);
+  } else if (res.tex_b64) {
+    await sendDoc(env, chatId, res.tex_b64, "resume.tex", "application/x-tex",
+                  "⚠️ PDF compile failed — here's the .tex (compile at overleaf.com).");
+  } else {
+    await tg(env, "sendMessage", { chat_id: chatId, text: "❌ Generation produced no file. Try again." });
+  }
+}
+
+function b64ToBytes(b64) {
+  const bin = atob(b64);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return bytes;
+}
+
+async function sendDoc(env, chatId, b64, filename, mime, caption) {
+  try {
+    const fd = new FormData();
+    fd.append("chat_id", String(chatId));
+    fd.append("caption", caption.slice(0, 1024));
+    fd.append("document", new Blob([b64ToBytes(b64)], { type: mime }), filename);
+    await fetch(tgUrl(env, "sendDocument"), { method: "POST", body: fd });
+  } catch (_) {
+    await tg(env, "sendMessage", { chat_id: chatId, text: "❌ Couldn't upload the file to Telegram. Try again." });
+  }
+}