From cf2c83236bf2ccb415c81b20fa5e22fc0c61c8f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Sun, 14 Jun 2026 21:23:55 +0200 Subject: [PATCH] Reuse shared HTTP classifier for WHOOP and Fitbit --- src/lib/fitbit/response-classifier.ts | 133 +++++------------------ src/lib/whoop/response-classifier.ts | 146 +++++--------------------- 2 files changed, 52 insertions(+), 227 deletions(-) diff --git a/src/lib/fitbit/response-classifier.ts b/src/lib/fitbit/response-classifier.ts index ca90b8290..46540168b 100644 --- a/src/lib/fitbit/response-classifier.ts +++ b/src/lib/fitbit/response-classifier.ts @@ -1,19 +1,17 @@ /** * Off-response classifier for Fitbit / Google Health API replies (v1.12.0). * - * Mirrors the WHOOP classifier (`src/lib/whoop/response-classifier.ts`) but - * speaks the Google Health wire. Like WHOOP, Google signals failure through the - * HTTP status code itself (no `status` field embedded in a 200 body), so this - * classifier is HTTP-status-driven. - * - * Classification buckets: + * Like WHOOP, Google signals failure through the HTTP status code itself (no + * `status` field embedded in a 200 body), so the classification is + * status-driven. The shared core lives in + * `src/lib/integrations/http-status-classifier.ts`; this module re-exports it + * under the Fitbit-specific names callers already use. * * - `success` → HTTP 2xx * - `transient` → retryable: HTTP 429 (rate-limited — honour * `Retry-After` for backoff at the call site), 5xx * upstream outages, 3xx CDN/network glitches, and an - * empty / off-spec body where we never reached the - * envelope. + * unknown status where we never reached the envelope. * - `reauth_required` → HTTP 401 / 403 — the access token is rejected or the * grant was revoked; the user must redo OAuth. (The * per-data-class 403 soft-skip lives in `sync.ts`'s @@ -24,99 +22,37 @@ * request or a contract mismatch that retrying without * operator intervention will not fix. * - * The classifier is conservative: anything it doesn't recognise defaults to - * `transient` so a single unknown response doesn't hard-disable the - * integration. The 3-strike admin-alert ladder in `recordSyncFailure` already - * catches the "keeps happening" case for recurring transients. - * * Unlike WHOOP, there is no `invalid_grant` token-body special-case: Google * signals a revoked refresh token with a 401 on the token endpoint, which the * status-driven classifier already buckets as `reauth_required`. */ -/** Outcome buckets for a Fitbit response. Same shape as WHOOP. */ -export type FitbitClassification = - | "success" - | "transient" - | "reauth_required" - | "persistent"; +import { + classifyHttpStatus, + classifyIntegrationError, + IntegrationApiError, + type ClassifiedHttpResponse, + type IntegrationClassification, +} from "@/lib/integrations/http-status-classifier"; -export interface ClassifiedFitbitResponse { - classification: FitbitClassification; - /** The HTTP status code that drove the verdict (undefined if none seen). */ - httpStatus: number | undefined; - /** Short human-readable label for logs / audit details. */ - reason: string; -} +/** Outcome buckets for a Fitbit response. */ +export type FitbitClassification = IntegrationClassification; -/** - * Classify a single Fitbit / Google Health API response by its HTTP status. - * - * @param httpStatus The HTTP status from fetch. - */ +export type ClassifiedFitbitResponse = ClassifiedHttpResponse; + +/** Classify a single Fitbit / Google Health API response by its HTTP status. */ export function classifyFitbitResponse( httpStatus: number, ): ClassifiedFitbitResponse { - if (httpStatus >= 200 && httpStatus < 300) { - return { classification: "success", httpStatus, reason: "ok" }; - } - // 429 is rate-limit — honour `Retry-After` for backoff at the call site, but - // the verdict is a plain transient so the next sync retries. - if (httpStatus === 429) { - return { classification: "transient", httpStatus, reason: "http_429" }; - } - // 401/403 — the bearer token is rejected or the grant revoked. The user has - // to reconnect; do not retry silently. (A per-data-class 403 soft-skip is - // applied in sync.ts before this verdict drives a connection-wide reauth.) - if (httpStatus === 401 || httpStatus === 403) { - return { - classification: "reauth_required", - httpStatus, - reason: `http_${httpStatus}`, - }; - } - // Any other 4xx is a malformed request / contract mismatch — persistent. - if (httpStatus >= 400 && httpStatus < 500) { - return { - classification: "persistent", - httpStatus, - reason: `http_${httpStatus}`, - }; - } - // 5xx upstream outage — retryable. - if (httpStatus >= 500 && httpStatus < 600) { - return { - classification: "transient", - httpStatus, - reason: `http_${httpStatus}`, - }; - } - // 3xx (a CDN / redirect glitch — safeFetch uses redirect:"manual", so a - // surfaced 3xx is unexpected) and everything else defaults to transient. - return { - classification: "transient", - httpStatus, - reason: `http_${httpStatus}_unknown`, - }; + return classifyHttpStatus(httpStatus); } /** - * Typed Error subclass carrying the classification verdict so downstream - * `try/catch` blocks can branch without re-parsing the message. Mirrors - * `WhoopApiError`. + * Typed error carrying the classification verdict so downstream `try/catch` + * blocks can branch without re-parsing the message. Extends the shared base + * (message shape `Fitbit error: ` is preserved). */ -export class FitbitApiError extends Error { - readonly classification: FitbitClassification; - readonly httpStatus: number | undefined; - readonly reason: string; - readonly verb: string; - /** - * The OAuth `error` code from a token-endpoint failure body (e.g. - * `invalid_grant`). Captured for the audit trail; the classifier does not - * branch on it (Google signals a revoked grant with a 401 status). - */ - readonly upstreamError: string | undefined; - +export class FitbitApiError extends IntegrationApiError { constructor(opts: { verb: string; classification: FitbitClassification; @@ -124,20 +60,8 @@ export class FitbitApiError extends Error { reason: string; upstreamError?: string; }) { - const statusLabel = - typeof opts.httpStatus === "number" ? opts.httpStatus : "?"; - const errSegment = opts.upstreamError ? ` - ${opts.upstreamError}` : ""; - // Cap the message at 1024 chars in the constructor (same bound as - // WhoopApiError) so a misbehaving upstream returning a multi-MB error body - // can't bloat an AuditLog row downstream. - const raw = `Fitbit ${opts.verb} error: ${statusLabel}${errSegment}`; - super(raw.slice(0, 1024)); + super({ vendor: "Fitbit", ...opts }); this.name = "FitbitApiError"; - this.verb = opts.verb; - this.classification = opts.classification; - this.httpStatus = opts.httpStatus; - this.reason = opts.reason; - this.upstreamError = opts.upstreamError; } } @@ -149,12 +73,5 @@ export class FitbitApiError extends Error { * for callers that lose the original prototype across a pg-boss retry. */ export function classifyFitbitError(err: unknown): FitbitClassification { - if (err instanceof FitbitApiError) return err.classification; - - const msg = err instanceof Error ? err.message : String(err); - const m = /Fitbit\s+\w+\s+error:\s*(\d+)/.exec(msg); - if (!m) return "transient"; - const status = Number.parseInt(m[1]!, 10); - if (!Number.isFinite(status)) return "transient"; - return classifyFitbitResponse(status).classification; + return classifyIntegrationError(err, "Fitbit"); } diff --git a/src/lib/whoop/response-classifier.ts b/src/lib/whoop/response-classifier.ts index b6b5538ce..792815d83 100644 --- a/src/lib/whoop/response-classifier.ts +++ b/src/lib/whoop/response-classifier.ts @@ -1,112 +1,50 @@ /** * Off-response classifier for WHOOP API replies. * - * Mirrors the Withings classifier (`src/lib/withings/response-classifier.ts`) - * but speaks the WHOOP wire instead. WHOOP, unlike Withings, signals failure - * through the HTTP status code itself (no `status` field embedded in a 200 - * body), so this classifier is HTTP-status-driven. - * - * Classification buckets: + * WHOOP signals failure through the HTTP status code itself (no `status` field + * embedded in a 200 body), so the classification is status-driven. The shared + * core lives in `src/lib/integrations/http-status-classifier.ts`; this module + * re-exports it under the WHOOP-specific names callers already use. * * - `success` → HTTP 2xx * - `transient` → retryable: HTTP 429 (rate-limited — WHOOP caps at * 100 req/min + 10 000 req/day per app), 5xx upstream - * outages, 3xx CDN/network glitches, and an empty / - * off-spec body where we never reached the envelope. + * outages, 3xx CDN/network glitches, and an unknown + * status where we never reached the envelope. * - `reauth_required` → HTTP 401 / 403 — the access token is rejected or the * grant was revoked; the user must redo OAuth. * - `persistent` → any other 4xx (400, 404, 422, …) — a malformed * request or a contract mismatch that retrying without * operator intervention will not fix. - * - * The classifier is conservative: anything it doesn't recognise defaults to - * `transient` so a single unknown response doesn't hard-disable the - * integration. The 3-strike admin-alert ladder in `recordSyncFailure` - * already catches the "keeps happening" case for recurring transients. */ -/** Outcome buckets for a WHOOP response. Same shape as Withings. */ -export type WhoopClassification = - | "success" - | "transient" - | "reauth_required" - | "persistent"; +import { + classifyHttpStatus, + classifyIntegrationError, + IntegrationApiError, + isOAuthInvalidGrant, + type ClassifiedHttpResponse, + type IntegrationClassification, +} from "@/lib/integrations/http-status-classifier"; -export interface ClassifiedWhoopResponse { - classification: WhoopClassification; - /** The HTTP status code that drove the verdict (undefined if none seen). */ - httpStatus: number | undefined; - /** Short human-readable label for logs / audit details. */ - reason: string; -} +/** Outcome buckets for a WHOOP response. */ +export type WhoopClassification = IntegrationClassification; -/** - * Classify a single WHOOP API response by its HTTP status code. - * - * @param httpStatus The HTTP status from fetch. - */ +export type ClassifiedWhoopResponse = ClassifiedHttpResponse; + +/** Classify a single WHOOP API response by its HTTP status code. */ export function classifyWhoopResponse( httpStatus: number, ): ClassifiedWhoopResponse { - if (httpStatus >= 200 && httpStatus < 300) { - return { classification: "success", httpStatus, reason: "ok" }; - } - // 429 is rate-limit — honour `X-RateLimit-*` for backoff at the call site, - // but the verdict is a plain transient so the next sync retries. - if (httpStatus === 429) { - return { classification: "transient", httpStatus, reason: "http_429" }; - } - // 401/403 — the bearer token is rejected or the grant revoked. The user has - // to reconnect; do not retry silently. - if (httpStatus === 401 || httpStatus === 403) { - return { - classification: "reauth_required", - httpStatus, - reason: `http_${httpStatus}`, - }; - } - // Any other 4xx is a malformed request / contract mismatch — persistent. - if (httpStatus >= 400 && httpStatus < 500) { - return { - classification: "persistent", - httpStatus, - reason: `http_${httpStatus}`, - }; - } - // 5xx upstream outage — retryable. - if (httpStatus >= 500 && httpStatus < 600) { - return { - classification: "transient", - httpStatus, - reason: `http_${httpStatus}`, - }; - } - // 3xx (a CDN / redirect glitch — safeFetch uses redirect:"manual", so a - // surfaced 3xx is unexpected) and everything else defaults to transient. - return { - classification: "transient", - httpStatus, - reason: `http_${httpStatus}_unknown`, - }; + return classifyHttpStatus(httpStatus); } /** - * Typed Error subclass carrying the classification verdict so downstream - * `try/catch` blocks can branch without re-parsing the message. Mirrors - * `WithingsApiError`. + * Typed error carrying the classification verdict so downstream `try/catch` + * blocks can branch without re-parsing the message. Extends the shared base + * (message shape `WHOOP error: ` is preserved). */ -export class WhoopApiError extends Error { - readonly classification: WhoopClassification; - readonly httpStatus: number | undefined; - readonly reason: string; - readonly verb: string; - /** - * The OAuth `error` code from a token-endpoint failure body (e.g. - * `invalid_grant` when a refresh token is revoked). Undefined for the - * collection endpoints, which signal failure through the status code alone. - */ - readonly upstreamError: string | undefined; - +export class WhoopApiError extends IntegrationApiError { constructor(opts: { verb: string; classification: WhoopClassification; @@ -114,20 +52,8 @@ export class WhoopApiError extends Error { reason: string; upstreamError?: string; }) { - const statusLabel = - typeof opts.httpStatus === "number" ? opts.httpStatus : "?"; - const errSegment = opts.upstreamError ? ` - ${opts.upstreamError}` : ""; - // Cap the message at 1024 chars in the constructor (same bound as - // WithingsApiError) so a misbehaving upstream returning a multi-MB error - // body can't bloat an AuditLog row downstream. - const raw = `WHOOP ${opts.verb} error: ${statusLabel}${errSegment}`; - super(raw.slice(0, 1024)); + super({ vendor: "WHOOP", ...opts }); this.name = "WhoopApiError"; - this.verb = opts.verb; - this.classification = opts.classification; - this.httpStatus = opts.httpStatus; - this.reason = opts.reason; - this.upstreamError = opts.upstreamError; } } @@ -140,19 +66,9 @@ export class WhoopApiError extends Error { * surface the reauth prompt. Scoped tightly to a 400 carrying `invalid_grant` * so other 400s (a malformed request, a bad client_secret → `invalid_client`) * stay persistent. - * - * Robust to a lost prototype across a pg-boss retry: it reads the dedicated - * `upstreamError` field when present, else falls back to the - * `"... error: 400 - invalid_grant"` message segment. */ export function isInvalidGrant(err: unknown): boolean { - if (err instanceof WhoopApiError) { - if (err.httpStatus !== 400) return false; - if (err.upstreamError === "invalid_grant") return true; - return /\binvalid_grant\b/.test(err.message); - } - const msg = err instanceof Error ? err.message : String(err); - return /WHOOP\s+\w+\s+error:\s*400\b[\s\S]*\binvalid_grant\b/.test(msg); + return isOAuthInvalidGrant(err, "WHOOP"); } /** @@ -168,13 +84,5 @@ export function isInvalidGrant(err: unknown): boolean { */ export function classifyWhoopError(err: unknown): WhoopClassification { if (isInvalidGrant(err)) return "reauth_required"; - - if (err instanceof WhoopApiError) return err.classification; - - const msg = err instanceof Error ? err.message : String(err); - const m = /WHOOP\s+\w+\s+error:\s*(\d+)/.exec(msg); - if (!m) return "transient"; - const status = Number.parseInt(m[1]!, 10); - if (!Number.isFinite(status)) return "transient"; - return classifyWhoopResponse(status).classification; + return classifyIntegrationError(err, "WHOOP"); }