refactor: expose the Hevy client as a single adapter interface

[chrisdoc]

Summary

There are two parallel client modules — the Node axios client (src/utils/hevyClient.ts) and the Worker native-fetch Kubb wrapper (src/utils/hevyClientKubb.ts, 472 LOC) — plus observability/enrichment layers (hevy-client-observability.ts, observability-wrapper.ts, safe-error-diagnostic.ts, hevy-http-error.ts). Tool code depends on a concrete client rather than an interface, so runtime choice is spread across the edges instead of isolated at one seam.

Files

• src/utils/hevyClient.ts, hevyClientKubb.ts
• src/utils/hevy-client-observability.ts, observability-wrapper.ts, safe-error-diagnostic.ts, hevy-http-error.ts
• src/shared-server.ts (consumer), src/tools/* (callers)

Proposed approach

• Name the client as an interface (HevyClient) with method signatures tools already rely on.
• Node and Worker become two adapters behind that interface. The in-memory fake used by tests/integration/mocked/ becomes a first-class test adapter.
• Move observability/enrichment into the adapter construction, not into every call site.

Constraints

• Must remain safe for both Node.js and Cloudflare Workers (no Node built-ins in the Worker adapter).
• shared-server.ts already accepts a hevyClient override — preserve that injection point.
• Do not edit generated client code (src/generated/); adapters wrap it.

Acceptance

• Tool code depends on the HevyClient interface, not a concrete module.
• Node, Worker, and test adapters swap behind the seam; tests use the test adapter.
• npm run check:types and all suites (mocked, worker, live) pass.

Notes

Speculative — only worth it once candidates 2–4 land and the seam is clearer. Two adapters (Node + Worker) justify the seam; a test adapter makes it real.

See architecture review candidate 6.

[coderabbitai]

🔗 Related PRs

#225 - refactor(types): ✨ Improve type exports for better readability [merged]
#305 - build: update openapi spec and regenerate api client [merged]
#342 - Add tool annotations and fix body measurement payload handling [merged]
#443 - feat: instrument with OpenTelemetry for Sentry + Honeycomb dual export [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[charliecreates]

I’m holding this refactor for now because its stated prerequisites have not landed: #653, #654, and #655 are all still open without implementation PRs.

The premise also needs updating before implementation: on current main, src/utils/hevyClient.ts is already a thin facade over the same native-fetch Kubb client used by Node and Worker, following #640 and #649. There are no longer two transport implementations to put behind separate adapters.

Once the prerequisites land, I recommend re-scoping this around an explicit runtime-neutral HevyClient contract, Node/Worker-owned construction policies over the shared Kubb implementation, preserved shared-server.ts injection, and a reusable typed test client helper. No code changes were made in this pass.