fix: self-heal stale auth token on translate instead of failing

[navidshad]

🏷️ PR Title:
fix: self-heal stale auth token on translate instead of failing

📋 Summary

This PR introduces a fix that enables the system to automatically recover from a stale authentication token during translation requests rather than failing immediately. This improves the robustness and user experience of the translation feature.

🔗 Related Tasks

#6ef3766 - fix: self-heal stale auth token on translate instead of failing

📝 Additional Details

The change ensures that when an expired or invalid auth token is detected during a translate operation, the token is refreshed internally and the translation is retried, minimizing errors and interruptions.

📜 Commit List

6ef3766 fix: self-heal stale auth token on translate instead of failing

[navidshad]

Automated PR Review

Primary Task: fix: self-heal stale auth token on translate instead of failing
(No ClickUp task ID found — the link in the PR body resolves to the commit SHA, not a task record.)

---

Task alignment

✅ Core fix — withAuthRetry wraps all three functionProvider.run calls in translate.service.ts (fetchSimpleTranslation, fetchDetailedTranslation, and translationAdvice). The retried result is still cached correctly.

✅ Anonymous-login refactor — loginWithLastSession is cleanly consolidated to call the shared reauthAnonymously() primitive, eliminating the duplicated inline anonymous-login chain. The finally callback is now correctly async, fixing a subtle case where the previous promise chain was fire-and-forget.

✅ Registered-user downgrade path — recoverSession in modular-rest.ts tears down a dead registered session via logout() before re-establishing anonymous, so no phantom logged-in UI lingers. The check authentication.user?.type?.toLowerCase() === "user" correctly skips the teardown for anonymous sessions.

✅ Thundering-herd prevention — Two single-flight guards are in place: inflightReauth inside reauthAnonymously (prevents multiple /user/loginAnonymous calls) and inflightRecovery inside recoverOnce (coalesces concurrent withAuthRetry recoveries). The double-layering is harmless and correct.

✅ Circular-import avoidance — setSessionRecovery / late binding is the right solution: auth-recovery.ts stays side-effect-free so importing it from translate.service doesn't drag the plugin's content-script init chain into the test graph.

✅ translateByDictionaryapi not wrapped — correct; it calls dictionaryapi.dev (a public API), not the modular-rest backend, so it doesn't need auth recovery.

---

Commit messages

✅ fix: self-heal stale auth token on translate instead of failing — well-formed conventional commit, fix: type is accurate (bug fix for a reported user-facing failure), message is descriptive enough to understand the change without reading the diff.

---

Prior review follow-up

(No prior reviews.)

---

Convention check

✅ New file src/common/helper/auth-recovery.ts is in the right location for a shared, bundle-agnostic utility.

✅ Comments follow the project convention: multi-line JSDoc explaining the why (auth-error detection rationale, the Koa/modular-rest body format, the single-flight guarantee, the late-binding motivation) — exactly what CLAUDE.md encourages.

✅ vi.resetModules() is used in auth-anon-flow.test.ts where modular-rest.ts side effects (the setSessionRecovery call at module load) must re-run per test. auth-recovery.test.ts omits it intentionally since all operations are awaited and the .finally() guard resets in-flight state.

✅ No new bundle entries, no CSS/DOM, no manifest changes required.

One minor observation (no change needed): AUTH_ERROR_PATTERNS includes catch-all strings like "forbidden" and "jwt" marked as "defensive nets." These are well-documented as guards against intermediary proxies, not the backend itself. The conservative extractMessage depth-limit (3) prevents runaway recursion on exotic error shapes. The false-positive risk is low given the business errors documented as deliberately non-matching.

---

Verdict

APPROVE — The implementation is well-designed, thoroughly tested (25+ new unit/integration tests across 3 files), and follows all project conventions. The refactoring of the existing anonymous-login flow is a meaningful correctness improvement, not just scope creep.

---

Generated by Claude Code

[github-actions]

🎉 This PR is included in version 1.14.1-dev.2 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 1.14.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀