Tracer links (#174)

* initial commit * format links right jobops.dakheera47.com/cv/shaheer-google-de * don't support legacy * remove phishing look * smaller links * readiness check in settings * rework UX * right col * pop a modal * modal improvements * show links * documentation disclaimer * fix(tracer-links): preserve descriptive resume link labels * fix(tracer-links): classify bot user agents before browser families * fix(tracer-links): reject non-http redirect destinations * fix(tracer-redirect): disable caching for tracked redirects * fix(origin): prefer canonical public base url over forwarded headers * fix(auth): protect tracer analytics routes behind basic auth * fix(ui): rename misleading tracer drilldown human metric * style(tests): format tracer-links invalid-destination assertion * fix(tests): prevent mocked fs from breaking sqlite data-dir resolution * style(docs): format versioned docs json for biome * fix(tests): mock tracer-links in pdf skills validation suite
2026-02-18 22:05:15 +00:00
parent 1146d065f0
commit 5ed74bb59c
44 changed files with 4025 additions and 28 deletions
@@ -123,9 +123,27 @@ High-level flow:
 1. Load selected base resume from RxResume.
 2. Apply tailored summary/headline/skills.
 3. Compute final visible projects from your selection rules.
-4. Create temporary resume in RxResume.
-5. Export PDF.
-6. Delete temporary resume.
+4. Optionally rewrite outbound links to tracer links (per-job toggle).
+5. Create temporary resume in RxResume.
+6. Export PDF.
+7. Delete temporary resume.
+
+### Per-job tracer links
+
+Before generating a PDF, each job can enable/disable tracer links.
+
+- Disabled: original RxResume links remain unchanged.
+- Enabled: eligible outbound links are rewritten to `https://<your-host>/cv/<company>-xx` (readable slug + 2-letter suffix).
+
+For background pipeline generation, configure:
+
+- `JOBOPS_PUBLIC_BASE_URL=https://your-host`
+
+Important:
+
+- tracer enablement is gated by readiness checks
+- if public host verification fails, enable is blocked until host health is restored
+- toggle changes apply on next PDF generation only

 ### What JobOps changes with AI

@@ -18,6 +18,7 @@ It lets you configure:
 - Display and Ghostwriter defaults
 - Service credentials and basic auth
 - Reactive Resume project selection
+- Tracer Links readiness verification
 - Backup and scoring rules
 - Data-clearing actions in the Danger Zone

@@ -81,6 +82,19 @@ Settings gives you runtime overrides for the key parts of discovery, scoring, ta
  - Must-include projects
  - AI-selectable projects

+### Tracer Links
+
+- Verify tracer readiness before enabling per-job tracing
+- Shows current status (`Ready`, `Unavailable`, `Unconfigured`, or stale state)
+- Displays the effective public base URL and last check time
+- Provides **Verify now** for an on-demand health check
+
+Readiness requires:
+
+- a valid public JobOps base URL
+- successful reachability of `<public-base-url>/health`
+- non-localhost/non-private host setup for public redirect usage
+
 ### Environment & Accounts

 - Configure service accounts:
@@ -163,6 +177,12 @@ curl -X POST "http://localhost:3001/api/backups"
 - Verify URL reachability from the server host.
 - Confirm auth expectations on the receiver side (including secret/bearer token).

+### Tracer links cannot be enabled
+
+- Open **Settings → Tracer Links** and click **Verify now**.
+- Ensure `JOBOPS_PUBLIC_BASE_URL` is set for background/pipeline usage.
+- Ensure the configured host is publicly reachable and `/health` responds.
+
 ## Related pages

 - [Reactive Resume](./reactive-resume)
@@ -0,0 +1,151 @@
+---
+id: tracer-links
+title: Tracer Links
+description: Track outbound resume-link clicks with per-job toggles and privacy-safe analytics.
+sidebar_position: 8
+---
+
+## What it is
+
+Tracer Links are per-job redirect links that are generated when a PDF is created.
+
+When enabled for a job, JobOps rewrites eligible outbound RxResume links to your JobOps host, then redirects to the original destination after recording a click event.
+
+Examples:
+
+- original: `https://github.com/yourname`
+- traced: `https://jobops.dakheera47.com/cv/amazon-de`
+
+Format details:
+
+- path prefix is always `/cv/`
+- token format is `<company-slug>-<xx>`
+- `<xx>` is two lowercase letters (`a-z`)
+- visible link text in the PDF is also updated to the traced URL
+
+## Why it exists
+
+Without tracer links, resume links are "fire and forget".
+
+Tracer links let you answer:
+
+- whether links in a specific job PDF were opened
+- which destination links are being opened most
+- rough human vs bot traffic split
+- per-job and global engagement trends over time
+
+The feature is privacy-safe by design:
+
+- no raw IP is stored
+- referrer host is stored (not full referrer URL)
+- bot traffic is flagged and can be filtered in analytics
+
+## How to use it
+
+1. Open **Settings** and go to the **Tracer Links** section.
+2. Click **Verify now** and confirm status is **Ready**.
+3. Open a job in **Jobs**.
+4. Enable **Tracer links for this job** in tailoring or job details.
+5. Generate or regenerate the PDF.
+6. Open **Tracer Links** in navigation to view:
+   - global totals
+   - top jobs and top links
+   - per-job drilldown by Job ID
+
+Important behavior:
+
+- Tracer links are **off by default** per job.
+- Toggle changes apply on the **next PDF generation only**.
+- Existing PDFs are not modified retroactively.
+- Existing tracer URLs remain valid, even if a newer PDF generates new links.
+
+### Readiness and enable/disable behavior
+
+You can only turn tracer links **on** when readiness is healthy.
+
+Readiness checks:
+
+- a resolvable public base URL
+- a successful health probe to `<public-base-url>/health`
+- a non-localhost/non-private host for public usage
+
+If readiness is unavailable, enable is blocked until verification passes.
+
+### Required background-run setting
+
+If PDFs are generated by background pipeline runs, set:
+
+```bash
+JOBOPS_PUBLIC_BASE_URL=https://your-jobops-host
+```
+
+JobOps uses this URL when request host inference is not available.
+
+### URL uniqueness rules
+
+Tracer links are unique enough for tracking while still readable.
+
+- same job + same source path + same destination URL => token is reused
+- same job + same source path + changed destination URL => new token
+- old tokens continue to redirect (not retroactively deleted)
+
+### Risk and responsibility disclaimer
+
+Tracer links are redirect links. Some recruiters, companies, universities, or security tools may treat redirects as suspicious behavior and may whitelist, blacklist, filter, or flag these links as phishing-like.
+
+By enabling and using this feature, you accept full responsibility for any consequences that result from its use. Responsibility for policy, trust, and reputation outcomes sits with the user/operator of the instance, not with the app.
+
+## Common problems
+
+### I cannot enable tracer links
+
+Cause:
+
+- readiness is not **Ready**
+- host is local/private or unreachable from the verifier
+
+Fix:
+
+- configure a real public host
+- set `JOBOPS_PUBLIC_BASE_URL` for background flows
+- make sure `<public-base-url>/health` is reachable
+- retry **Verify now**
+
+### Tracer links enabled but PDF generation fails
+
+Cause:
+
+- base URL cannot be resolved at generation time, or instance health is not reachable for that run
+
+Fix:
+
+- ensure `JOBOPS_PUBLIC_BASE_URL` is set correctly
+- verify the deployment is publicly reachable
+- regenerate the PDF
+
+### I enabled tracer links, but old PDF still has direct links
+
+Cause:
+
+- toggle changes only apply to newly generated PDFs
+
+Fix:
+
+- regenerate the PDF for that job
+
+### Analytics look inflated by scanners
+
+Cause:
+
+- link scanners and preview bots may open links automatically
+
+Fix:
+
+- use the **Include likely bots** filter in Tracer Links analytics
+
+## Related pages
+
+- [Settings](/docs/features/settings)
+- [Reactive Resume](/docs/features/reactive-resume)
+- [Find Jobs and Apply Workflow](/docs/workflows/find-jobs-and-apply-workflow)
+- [Post-Application Tracking](/docs/features/post-application-tracking)
@@ -57,8 +57,9 @@ These jobs already have tailored PDFs generated for the specific job description
 At this stage:

 1. Open job details.
-2. Download the tailored PDF.
-3. Submit your application externally.
+2. Optionally enable tracer links for that specific job.
+3. Download the tailored PDF.
+4. Submit your application externally.

 ### 5) Mark jobs as applied in JobOps

@@ -85,6 +86,8 @@ Once a job is marked `applied`, it becomes part of:
 - Increase tailored-job count only after score thresholds feel calibrated.
 - Expect scraper runtime variance by source.
 - Keep resume/project context up to date so scoring/tailoring quality stays high.
+- Use per-job tracer links when you want measurable outbound-link analytics.
+- If you use tracer links, review the risk note in [Tracer Links](../features/tracer-links): some recipients/security tools may treat redirects as suspicious.

 ## Related pages

@@ -60,17 +60,12 @@
    {
      "type": "category",
      "label": "Troubleshooting",
-      "items": [
-        "troubleshooting/common-problems"
-      ]
+      "items": ["troubleshooting/common-problems"]
    },
    {
      "type": "category",
      "label": "Reference / FAQ",
-      "items": [
-        "reference/faq",
-        "reference/documentation-style-guide"
-      ]
+      "items": ["reference/faq", "reference/documentation-style-guide"]
    }
  ]
 }
@@ -1,6 +1 @@
-[
-  "0.1.23",
-  "0.1.22",
-  "0.1.21",
-  "0.1.20"
-]
+["0.1.23", "0.1.22", "0.1.21", "0.1.20"]