Job Assistant Tracker (Google Apps Script + OpenAI)

Automate your job applications: email your alias (e.g. you+jobassistant@gmail.com) and this script will:

• auto-label the thread
• rename & save attachments to Drive
• extract Company and Role using the OpenAI API (JSON mode)
• log to Google Sheets (Log, Runs, Activity tabs)
• email a receipt back to the original sender (with optional CC)

Privacy note: API keys and IDs are stored in Script properties (not hardcoded). No secrets in source.

---

✨ Features

• Lean minute trigger (no full inbox scan); skips heavy work if nothing’s new
• Auto-label alias mail (tiny Gmail search)
• Deterministic file naming and year/date folders in Drive
• OpenAI extraction (structured JSON; robust fallback)
• Dedup by Gmail permalink
• Receipts & error emails (to the original sender, optional CC to you)
• Observability: three Sheets tabs
  • Log – canonical application table
  • Runs – one row per execution (counts, timing, outcome)
  • Activity – per-thread details (optional AI prompt/response, truncated)

---

🧱 Requirements

• Personal Google account with Gmail, Drive, Sheets
• OpenAI API key (restricted to /v1/chat/completions → Write)
• A Google Sheet (blank is fine; script will create headers)
• No deploy/web app needed—just a time trigger

---

🚀 Setup (one time)

1. Create the Google Sheet

   • Go to Google Sheets → Blank.
   • Copy the Sheet ID (between /d/ and /edit in the URL).

2. Create alias (optional but recommended)

   • Use any Gmail plus-alias, e.g. you+jobassistant@gmail.com.

3. Open Apps Script

   • https://script.google.com/ → New project.
   • Create a JobAssistant.gs file and paste the contents from src/JobAssistant.gs (from this repo).
   • Save.

4. Project Settings → Script properties (add rows; key/value):

   • SHEET_ID = <your sheet id>
   • BASE_FOLDER_PATH = Job Apps
   • ALIAS_EMAIL = you+jobassistant@gmail.com
   • NOTIFY_EMAIL = <your main email> (optional CC on receipts)
   • USE_LLM = true
   • LLM_PROVIDER = OPENAI
   • OPENAI_API_KEY = <your OpenAI key>
   • (optional) DEBUG = true (console logs in Executions)
   • (optional) LOG_AI_PAYLOADS = true (store AI prompt/response in Activity; set false to suppress)
   • (optional) LOG_AI_MAXLEN = 1200
   • (optional) BATCH_SIZE = 30
   • (optional) ALIAS_LOOKBACK_DAYS = 2

5. Authorize & initialize

   • In Apps Script, pick function setup → Run.
   • Approve permissions (Gmail, Drive, Sheets, external requests).
   • After run, your Google Sheet will have Log, Runs, Activity tabs with headers.

6. Add a time trigger

   • Left sidebar Triggers (⏰) → Add Trigger:
     • Function: processJobAssistant
     • Event source: Time-driven
     • Type: Every 1 minute (or every 5)
   • Save.

Tip: if strict Firefox privacy blocks OAuth popups, do the first Run → setup in Chrome/Edge once.

---

🧪 Test

1. From any account, send an email to your alias
   Subject: Applied: Sopra Steria – Observability konsulent
   Body: include a job URL
   Attach: two PDFs (CV + letter)

2. Either wait a minute for the trigger or Run → processJobAssistant.

3. Verify:

   • Drive: Job Apps/<year>/<YYYY-MM-DD_Company_Role>/ with renamed PDFs
   • Sheet:
     • Log row (links, hashes, company, role, permalink)
     • Runs row (counts, duration, outcome=processed or silent-check)
     • Activity row (sender, subject, links; plus AI payloads if enabled)
   • Email: sender gets a receipt (optional CC to NOTIFY_EMAIL). Errors send to sender too and label thread JobAssistant/Error.

---

🔧 Customization

• Naming: edit guessDocType() and folder naming lines in JobAssistant.gs.
• Receipt content: adjust receipt body string in processJobAssistant() after files save.
• Digest: add a weekly digest() that queries the Log tab and emails a summary (left as an exercise).

---

🛡️ Security & privacy

• API key stored in Script properties; never commit keys or IDs.
• Optional logging of AI prompt/response; set LOG_AI_PAYLOADS=false to suppress.
• Data stays in your Google account (Gmail/Drive/Sheets).

---

💸 Cost control

• OpenAI calls happen only when a new labeled thread is processed.
• Idle ticks (no work) perform a tiny Gmail search + quick exit.

---

🐛 Troubleshooting

• Nothing happens: check that the alias email received the message; ensure the time trigger exists; look at Executions for logs.
• 401/429 from OpenAI: verify OPENAI_API_KEY; try again later for 429.
• Wrong company/role: the LLM is robust; adding lines like Company: / Position: in the email body improves reliability.
• Duplicates: dedup is by Gmail permalink + Processed label; forwarding as a new thread will log as a new entry (expected).

---

📜 License

MIT — see LICENSE.

---

🙋 FAQ

See docs/FAQ.md.