fix(web): surface actionable error when Lighthouse is unreachable

[brendan-kellam]

When a fetch to the Lighthouse licensing service throws at the network layer (DNS, TLS, connection refused, timeout), the raw error bubbled through sew and was flattened into a generic "an unexpected error occurred" — leaving self-hosted operators with nothing to act on.

This centralizes the call in a requestLighthouse helper that catches the throw and returns a LIGHTHOUSE_UNREACHABLE ServiceError naming the URL and underlying cause. Because it's now a ServiceError, sew preserves it instead of genericizing it, so the real failure reaches the user.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Improved error messaging when the Lighthouse licensing service is unreachable, now providing specific actionable feedback to users instead of generic error notifications.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9c10e6bd-09a2-4e75-82b7-5d03cdbc31b4

📥 Commits

Reviewing files that changed from the base of the PR and between d02f61c and 0c6bf2f.

📒 Files selected for processing (4)

• CHANGELOG.md
• packages/web/src/features/billing/client.ts
• packages/web/src/lib/errorCodes.ts
• packages/web/src/lib/serviceError.ts

---

Walkthrough

The PR adds dedicated error handling for unreachable Lighthouse licensing services. A new error code and factory function create actionable SERVICE_UNAVAILABLE errors with extracted failure details. The billing client is refactored to centralize HTTP request logic through reusable helpers, with all endpoints rewired to use the shared infrastructure instead of inlined per-endpoint patterns.

Changes

Lighthouse unreachable error handling

Layer / File(s)	Summary
Error code and factory for unreachable Lighthouse packages/web/src/lib/errorCodes.ts, packages/web/src/lib/serviceError.ts	LIGHTHOUSE_UNREACHABLE error code added; lighthouseUnreachable factory creates SERVICE_UNAVAILABLE errors with message containing the unreachable URL and extracted error details.
HTTP request helpers and imports packages/web/src/features/billing/client.ts (imports, helpers)	Updated imports to include the error factory; requestLighthouse helper constructs the Lighthouse URL, executes with fetchWithRetry, maps failures to lighthouseUnreachable, and parses responses with Zod; jsonPost standardizes JSON POST request initialization.
Client endpoint refactoring to use request helpers packages/web/src/features/billing/client.ts (endpoints)	All client methods (activate, claimActivationCode, ping, pingSchema, checkout, portal, invoices, offers) delegated to centralized requestLighthouse and jsonPost instead of inlined per-endpoint HTTP construction and error handling.
Changelog documentation CHANGELOG.md	Unreleased entry documents that Lighthouse unreachability now returns an actionable error instead of a generic unexpected error.

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and clearly summarizes the main change: introducing actionable error messaging when the Lighthouse service is unreachable, which is the primary objective of all code changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch brendan/fix-lighthouse-unreachable-error

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}