fix: shorten refresh backoff for transient failures and log the cause (#178)

[Percy2Live]

Closes part of #178.

Problem

A failed OAuth token refresh set a single, fixed one-hour throttle (DEFAULT_REFRESH_RETRY_DELAY_MS) regardless of the cause. Combined with occasional packet loss on the reporter's line, one transient error during a refresh stopped telemetry for up to 75 minutes (60 min throttle + backoff). On short poll intervals this happened several times an hour.

On top of that, the actual reason of a failed refresh was never logged — onFailure only wrote status.lastError, which the next poll's throttle message immediately overwrote, so the original error was invisible.

Change

• Classify the refresh failure (classifyRefreshFailure, duck-typed on the BluettiOAuthTokenClientError reason/httpStatus to avoid a circular import):
  • auth — invalid_grant/oauth_error and other 4xx (except 429): keep the full one-hour backoff, because retrying a rejected refresh token cannot succeed until re-auth (see Re-authentication has no effect until manual restart: running poll loop keeps the stale token #175).
  • transient — network error, timeout, 5xx, 429, and anything unknown: back off only ~1 minute (DEFAULT_TRANSIENT_REFRESH_RETRY_DELAY_MS) so the next scheduled poll retries.
• Log the underlying refresh error once via a new onRefreshFailure callback, wired to this.log.warn in main.ts. It fires only on real attempts, not on throttled polls, so it does not spam.

Not addressed here (needs reporter input)

Point 1 of the issue — "token refreshed on every poll". The code already stamps created_at from expires_in (normalizeTokenResponse, fix for #46), so expiry should be computable and refresh should not run every poll. If it still does for the reporter, BLUETTI's refresh response likely omits expires_in entirely. I'll ask on the issue which expiry fields the stored token actually contains before guessing at a fallback lifetime.

Tests

Added unit tests: transient failure retries after the short delay; rejected credentials keep the full backoff; the failure is reported exactly once per failure window (not on throttled polls); and the classifier mapping. npm run check, lint, test:ts (99 passing) and test:package (57 passing) all green.

🤖 Generated with Claude Code