@contractspec/integration.providers-impls 2.10.0 → 3.1.1

package/dist/node/impls/health/base-health-provider.js

@@ -1,4 +1,286 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/impls/health/provider-normalizers.ts
+var DEFAULT_LIST_KEYS = [
+  "items",
+  "data",
+  "records",
+  "activities",
+  "workouts",
+  "sleep",
+  "biometrics",
+  "nutrition"
+];
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return;
+  }
+  return value;
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : undefined;
+}
+function readString(record, keys) {
+  if (!record)
+    return;
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value;
+    }
+  }
+  return;
+}
+function readNumber(record, keys) {
+  if (!record)
+    return;
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed)) {
+        return parsed;
+      }
+    }
+  }
+  return;
+}
+function readBoolean(record, keys) {
+  if (!record)
+    return;
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "boolean") {
+      return value;
+    }
+  }
+  return;
+}
+function extractList(payload, listKeys = DEFAULT_LIST_KEYS) {
+  const root = asRecord(payload);
+  if (!root) {
+    return asArray(payload)?.map((item) => asRecord(item)).filter((item) => Boolean(item)) ?? [];
+  }
+  for (const key of listKeys) {
+    const arrayValue = asArray(root[key]);
+    if (!arrayValue)
+      continue;
+    return arrayValue.map((item) => asRecord(item)).filter((item) => Boolean(item));
+  }
+  return [];
+}
+function extractPagination(payload) {
+  const root = asRecord(payload);
+  const nestedPagination = asRecord(root?.pagination);
+  const nextCursor = readString(nestedPagination, ["nextCursor", "next_cursor"]) ?? readString(root, [
+    "nextCursor",
+    "next_cursor",
+    "cursor",
+    "next_page_token"
+  ]);
+  const hasMore = readBoolean(nestedPagination, ["hasMore", "has_more"]) ?? readBoolean(root, ["hasMore", "has_more"]);
+  return {
+    nextCursor,
+    hasMore: hasMore ?? Boolean(nextCursor)
+  };
+}
+function toHealthActivity(item, context, fallbackType = "activity") {
+  const externalId = readString(item, ["external_id", "externalId", "uuid", "id"]) ?? `${context.providerKey}:${fallbackType}`;
+  const id = readString(item, ["id", "uuid", "workout_id"]) ?? `${context.providerKey}:activity:${externalId}`;
+  return {
+    id,
+    externalId,
+    tenantId: context.tenantId,
+    connectionId: context.connectionId ?? "unknown",
+    userId: readString(item, ["user_id", "userId", "athlete_id"]),
+    providerKey: context.providerKey,
+    activityType: readString(item, ["activity_type", "type", "sport_type", "sport"]) ?? fallbackType,
+    startedAt: readIsoDate(item, [
+      "started_at",
+      "start_time",
+      "start_date",
+      "created_at"
+    ]),
+    endedAt: readIsoDate(item, ["ended_at", "end_time"]),
+    durationSeconds: readNumber(item, [
+      "duration_seconds",
+      "duration",
+      "elapsed_time"
+    ]),
+    distanceMeters: readNumber(item, ["distance_meters", "distance"]),
+    caloriesKcal: readNumber(item, [
+      "calories_kcal",
+      "calories",
+      "active_kilocalories"
+    ]),
+    steps: readNumber(item, ["steps"])?.valueOf(),
+    metadata: item
+  };
+}
+function toHealthWorkout(item, context, fallbackType = "workout") {
+  const activity = toHealthActivity(item, context, fallbackType);
+  return {
+    id: activity.id,
+    externalId: activity.externalId,
+    tenantId: activity.tenantId,
+    connectionId: activity.connectionId,
+    userId: activity.userId,
+    providerKey: activity.providerKey,
+    workoutType: readString(item, [
+      "workout_type",
+      "sport_type",
+      "type",
+      "activity_type"
+    ]) ?? fallbackType,
+    startedAt: activity.startedAt,
+    endedAt: activity.endedAt,
+    durationSeconds: activity.durationSeconds,
+    distanceMeters: activity.distanceMeters,
+    caloriesKcal: activity.caloriesKcal,
+    averageHeartRateBpm: readNumber(item, [
+      "average_heart_rate",
+      "avg_hr",
+      "average_heart_rate_bpm"
+    ]),
+    maxHeartRateBpm: readNumber(item, [
+      "max_heart_rate",
+      "max_hr",
+      "max_heart_rate_bpm"
+    ]),
+    metadata: item
+  };
+}
+function toHealthSleep(item, context) {
+  const externalId = readString(item, ["external_id", "externalId", "uuid", "id"]) ?? `${context.providerKey}:sleep`;
+  const id = readString(item, ["id", "uuid"]) ?? `${context.providerKey}:sleep:${externalId}`;
+  const startedAt = readIsoDate(item, ["started_at", "start_time", "bedtime_start", "start"]) ?? new Date(0).toISOString();
+  const endedAt = readIsoDate(item, ["ended_at", "end_time", "bedtime_end", "end"]) ?? startedAt;
+  return {
+    id,
+    externalId,
+    tenantId: context.tenantId,
+    connectionId: context.connectionId ?? "unknown",
+    userId: readString(item, ["user_id", "userId"]),
+    providerKey: context.providerKey,
+    startedAt,
+    endedAt,
+    durationSeconds: readNumber(item, [
+      "duration_seconds",
+      "duration",
+      "total_sleep_duration"
+    ]),
+    deepSleepSeconds: readNumber(item, [
+      "deep_sleep_seconds",
+      "deep_sleep_duration"
+    ]),
+    lightSleepSeconds: readNumber(item, [
+      "light_sleep_seconds",
+      "light_sleep_duration"
+    ]),
+    remSleepSeconds: readNumber(item, [
+      "rem_sleep_seconds",
+      "rem_sleep_duration"
+    ]),
+    awakeSeconds: readNumber(item, ["awake_seconds", "awake_time"]),
+    sleepScore: readNumber(item, ["sleep_score", "score"]),
+    metadata: item
+  };
+}
+function toHealthBiometric(item, context, metricTypeFallback = "metric") {
+  const externalId = readString(item, ["external_id", "externalId", "uuid", "id"]) ?? `${context.providerKey}:biometric`;
+  const id = readString(item, ["id", "uuid"]) ?? `${context.providerKey}:biometric:${externalId}`;
+  return {
+    id,
+    externalId,
+    tenantId: context.tenantId,
+    connectionId: context.connectionId ?? "unknown",
+    userId: readString(item, ["user_id", "userId"]),
+    providerKey: context.providerKey,
+    metricType: readString(item, ["metric_type", "metric", "type", "name"]) ?? metricTypeFallback,
+    value: readNumber(item, ["value", "score", "measurement"]) ?? 0,
+    unit: readString(item, ["unit"]),
+    measuredAt: readIsoDate(item, ["measured_at", "timestamp", "created_at"]) ?? new Date().toISOString(),
+    metadata: item
+  };
+}
+function toHealthNutrition(item, context) {
+  const externalId = readString(item, ["external_id", "externalId", "uuid", "id"]) ?? `${context.providerKey}:nutrition`;
+  const id = readString(item, ["id", "uuid"]) ?? `${context.providerKey}:nutrition:${externalId}`;
+  return {
+    id,
+    externalId,
+    tenantId: context.tenantId,
+    connectionId: context.connectionId ?? "unknown",
+    userId: readString(item, ["user_id", "userId"]),
+    providerKey: context.providerKey,
+    loggedAt: readIsoDate(item, ["logged_at", "created_at", "date", "timestamp"]) ?? new Date().toISOString(),
+    caloriesKcal: readNumber(item, ["calories_kcal", "calories"]),
+    proteinGrams: readNumber(item, ["protein_grams", "protein"]),
+    carbsGrams: readNumber(item, ["carbs_grams", "carbs"]),
+    fatGrams: readNumber(item, ["fat_grams", "fat"]),
+    fiberGrams: readNumber(item, ["fiber_grams", "fiber"]),
+    hydrationMl: readNumber(item, ["hydration_ml", "water_ml", "water"]),
+    metadata: item
+  };
+}
+function toHealthConnectionStatus(payload, params, source) {
+  const record = asRecord(payload);
+  const rawStatus = readString(record, ["status", "connection_status", "health"]) ?? "healthy";
+  return {
+    tenantId: params.tenantId,
+    connectionId: params.connectionId,
+    status: rawStatus === "healthy" || rawStatus === "degraded" || rawStatus === "error" || rawStatus === "disconnected" ? rawStatus : "healthy",
+    source,
+    lastCheckedAt: readIsoDate(record, ["last_checked_at", "lastCheckedAt"]) ?? new Date().toISOString(),
+    errorCode: readString(record, ["error_code", "errorCode"]),
+    errorMessage: readString(record, ["error_message", "errorMessage"]),
+    metadata: asRecord(record?.metadata)
+  };
+}
+function toHealthWebhookEvent(payload, providerKey, verified) {
+  const record = asRecord(payload);
+  const entityType = readString(record, ["entity_type", "entityType", "type"]);
+  const normalizedEntityType = entityType === "activity" || entityType === "workout" || entityType === "sleep" || entityType === "biometric" || entityType === "nutrition" ? entityType : undefined;
+  return {
+    providerKey,
+    eventType: readString(record, ["event_type", "eventType", "event"]),
+    externalEntityId: readString(record, [
+      "external_entity_id",
+      "externalEntityId",
+      "entity_id",
+      "entityId",
+      "id"
+    ]),
+    entityType: normalizedEntityType,
+    receivedAt: new Date().toISOString(),
+    verified,
+    payload,
+    metadata: asRecord(record?.metadata)
+  };
+}
+function readIsoDate(record, keys) {
+  const value = readString(record, keys);
+  if (!value)
+    return;
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime()))
+    return;
+  return parsed.toISOString();
+}
+
 // src/impls/health/base-health-provider.ts
+class HealthProviderCapabilityError extends Error {
+  code = "NOT_SUPPORTED";
+  constructor(message) {
+    super(message);
+    this.name = "HealthProviderCapabilityError";
+  }
+}
+
 class BaseHealthProvider {
   providerKey;
   transport;
@@ -6,146 +288,191 @@ class BaseHealthProvider {
   mcpUrl;
   apiKey;
   accessToken;
+  refreshToken;
   mcpAccessToken;
   webhookSecret;
+  webhookSignatureHeader;
+  route;
+  aggregatorKey;
+  oauth;
   fetchFn;
   mcpRequestId = 0;
   constructor(options) {
     this.providerKey = options.providerKey;
     this.transport = options.transport;
-    this.apiBaseUrl = options.apiBaseUrl ?? "https://api.example-health.local";
+    this.apiBaseUrl = options.apiBaseUrl;
     this.mcpUrl = options.mcpUrl;
     this.apiKey = options.apiKey;
     this.accessToken = options.accessToken;
+    this.refreshToken = options.oauth?.refreshToken;
     this.mcpAccessToken = options.mcpAccessToken;
     this.webhookSecret = options.webhookSecret;
+    this.webhookSignatureHeader = options.webhookSignatureHeader ?? "x-webhook-signature";
+    this.route = options.route ?? "primary";
+    this.aggregatorKey = options.aggregatorKey;
+    this.oauth = options.oauth ?? {};
     this.fetchFn = options.fetchFn ?? fetch;
   }
-  async listActivities(params) {
-    const result = await this.fetchList("activities", params);
-    return {
-      activities: result.items,
-      nextCursor: result.nextCursor,
-      hasMore: result.hasMore,
-      source: this.currentSource()
-    };
+  async listActivities(_params) {
+    throw this.unsupported("activities");
+  }
+  async listWorkouts(_params) {
+    throw this.unsupported("workouts");
+  }
+  async listSleep(_params) {
+    throw this.unsupported("sleep");
+  }
+  async listBiometrics(_params) {
+    throw this.unsupported("biometrics");
+  }
+  async listNutrition(_params) {
+    throw this.unsupported("nutrition");
+  }
+  async getConnectionStatus(params) {
+    return this.fetchConnectionStatus(params, {
+      mcpTool: `${this.providerSlug()}_connection_status`
+    });
+  }
+  async syncActivities(params) {
+    return this.syncFromList(() => this.listActivities(params));
   }
-  async listWorkouts(params) {
-    const result = await this.fetchList("workouts", params);
+  async syncWorkouts(params) {
+    return this.syncFromList(() => this.listWorkouts(params));
+  }
+  async syncSleep(params) {
+    return this.syncFromList(() => this.listSleep(params));
+  }
+  async syncBiometrics(params) {
+    return this.syncFromList(() => this.listBiometrics(params));
+  }
+  async syncNutrition(params) {
+    return this.syncFromList(() => this.listNutrition(params));
+  }
+  async parseWebhook(request) {
+    const payload = request.parsedBody ?? safeJsonParse(request.rawBody);
+    const verified = await this.verifyWebhook(request);
+    return toHealthWebhookEvent(payload, this.providerKey, verified);
+  }
+  async verifyWebhook(request) {
+    if (!this.webhookSecret)
+      return true;
+    const signature = readHeader(request.headers, this.webhookSignatureHeader);
+    return signature === this.webhookSecret;
+  }
+  async fetchActivities(params, config) {
+    const response = await this.fetchList(params, config);
     return {
-      workouts: result.items,
-      nextCursor: result.nextCursor,
-      hasMore: result.hasMore,
+      activities: response.items,
+      nextCursor: response.nextCursor,
+      hasMore: response.hasMore,
       source: this.currentSource()
     };
   }
-  async listSleep(params) {
-    const result = await this.fetchList("sleep", params);
+  async fetchWorkouts(params, config) {
+    const response = await this.fetchList(params, config);
     return {
-      sleep: result.items,
-      nextCursor: result.nextCursor,
-      hasMore: result.hasMore,
+      workouts: response.items,
+      nextCursor: response.nextCursor,
+      hasMore: response.hasMore,
       source: this.currentSource()
     };
   }
-  async listBiometrics(params) {
-    const result = await this.fetchList("biometrics", params);
+  async fetchSleep(params, config) {
+    const response = await this.fetchList(params, config);
     return {
-      biometrics: result.items,
-      nextCursor: result.nextCursor,
-      hasMore: result.hasMore,
+      sleep: response.items,
+      nextCursor: response.nextCursor,
+      hasMore: response.hasMore,
       source: this.currentSource()
     };
   }
-  async listNutrition(params) {
-    const result = await this.fetchList("nutrition", params);
+  async fetchBiometrics(params, config) {
+    const response = await this.fetchList(params, config);
     return {
-      nutrition: result.items,
-      nextCursor: result.nextCursor,
-      hasMore: result.hasMore,
+      biometrics: response.items,
+      nextCursor: response.nextCursor,
+      hasMore: response.hasMore,
       source: this.currentSource()
     };
   }
-  async getConnectionStatus(params) {
-    const payload = await this.fetchRecord("connection/status", params);
-    const status = readString(payload, "status") ?? "healthy";
+  async fetchNutrition(params, config) {
+    const response = await this.fetchList(params, config);
     return {
-      tenantId: params.tenantId,
-      connectionId: params.connectionId,
-      status: status === "healthy" || status === "degraded" || status === "error" || status === "disconnected" ? status : "healthy",
-      source: this.currentSource(),
-      lastCheckedAt: readString(payload, "lastCheckedAt") ?? new Date().toISOString(),
-      errorCode: readString(payload, "errorCode"),
-      errorMessage: readString(payload, "errorMessage"),
-      metadata: asRecord(payload.metadata)
+      nutrition: response.items,
+      nextCursor: response.nextCursor,
+      hasMore: response.hasMore,
+      source: this.currentSource()
     };
   }
-  async syncActivities(params) {
-    return this.sync("activities", params);
-  }
-  async syncWorkouts(params) {
-    return this.sync("workouts", params);
+  async fetchConnectionStatus(params, config) {
+    const payload = await this.fetchPayload(config, params);
+    return toHealthConnectionStatus(payload, params, this.currentSource());
   }
-  async syncSleep(params) {
-    return this.sync("sleep", params);
-  }
-  async syncBiometrics(params) {
-    return this.sync("biometrics", params);
-  }
-  async syncNutrition(params) {
-    return this.sync("nutrition", params);
-  }
-  async parseWebhook(request) {
-    const payload = request.parsedBody ?? safeJsonParse(request.rawBody);
-    const body = asRecord(payload);
+  currentSource() {
     return {
       providerKey: this.providerKey,
-      eventType: readString(body, "eventType") ?? readString(body, "event"),
-      externalEntityId: readString(body, "externalEntityId") ?? readString(body, "entityId"),
-      entityType: normalizeEntityType(readString(body, "entityType") ?? readString(body, "type")),
-      receivedAt: new Date().toISOString(),
-      verified: await this.verifyWebhook(request),
-      payload
+      transport: this.transport,
+      route: this.route,
+      aggregatorKey: this.aggregatorKey
     };
   }
-  async verifyWebhook(request) {
-    if (!this.webhookSecret) {
-      return true;
-    }
-    const signature = readHeader(request.headers, "x-webhook-signature");
-    return signature === this.webhookSecret;
+  providerSlug() {
+    return this.providerKey.replace("health.", "").replace(/-/g, "_");
   }
-  async fetchList(resource, params) {
-    const payload = await this.fetchRecord(resource, params);
-    const items = asArray(payload.items) ?? asArray(payload[resource]) ?? asArray(payload.records) ?? [];
+  unsupported(capability) {
+    return new HealthProviderCapabilityError(`${this.providerKey} does not support ${capability}`);
+  }
+  async syncFromList(executor) {
+    const result = await executor();
+    const records = countResultRecords(result);
     return {
-      items,
-      nextCursor: readString(payload, "nextCursor") ?? readString(payload, "cursor"),
-      hasMore: readBoolean(payload, "hasMore")
+      synced: records,
+      failed: 0,
+      nextCursor: undefined,
+      source: result.source
     };
   }
-  async sync(resource, params) {
-    const payload = await this.fetchRecord(`sync/${resource}`, params, "POST");
+  async fetchList(params, config) {
+    const payload = await this.fetchPayload(config, params);
+    const items = extractList(payload, config.listKeys).map((item) => config.mapItem(item, params)).filter((item) => Boolean(item));
+    const pagination = extractPagination(payload);
     return {
-      synced: readNumber(payload, "synced") ?? 0,
-      failed: readNumber(payload, "failed") ?? 0,
-      nextCursor: readString(payload, "nextCursor"),
-      errors: asArray(payload.errors)?.map((item) => String(item)),
-      source: this.currentSource()
+      items,
+      nextCursor: pagination.nextCursor,
+      hasMore: pagination.hasMore
     };
   }
-  async fetchRecord(resource, params, method = "GET") {
-    if (this.transport.endsWith("mcp")) {
-      return this.callMcpTool(resource, params);
+  async fetchPayload(config, params) {
+    const method = config.method ?? "GET";
+    const query = config.buildQuery?.(params);
+    const body = config.buildBody?.(params);
+    if (this.isMcpTransport()) {
+      return this.callMcpTool(config.mcpTool, {
+        ...query ?? {},
+        ...body ?? {}
+      });
+    }
+    if (!config.apiPath || !this.apiBaseUrl) {
+      throw new Error(`${this.providerKey} transport is missing an API path.`);
     }
-    const url = new URL(`${this.apiBaseUrl.replace(/\/$/, "")}/${resource}`);
-    if (method === "GET") {
-      for (const [key, value] of Object.entries(params)) {
+    if (method === "POST") {
+      return this.requestApi(config.apiPath, "POST", undefined, body);
+    }
+    return this.requestApi(config.apiPath, "GET", query, undefined);
+  }
+  isMcpTransport() {
+    return this.transport.endsWith("mcp") || this.transport === "unofficial";
+  }
+  async requestApi(path, method, query, body) {
+    const url = new URL(path, ensureTrailingSlash(this.apiBaseUrl ?? ""));
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
         if (value == null)
           continue;
         if (Array.isArray(value)) {
-          value.forEach((item) => {
-            url.searchParams.append(key, String(item));
+          value.forEach((entry) => {
+            if (entry != null)
+              url.searchParams.append(key, String(entry));
           });
           continue;
         }
@@ -154,22 +481,22 @@ class BaseHealthProvider {
     }
     const response = await this.fetchFn(url, {
       method,
-      headers: {
-        "Content-Type": "application/json",
-        ...this.accessToken || this.apiKey ? { Authorization: `Bearer ${this.accessToken ?? this.apiKey}` } : {}
-      },
-      body: method === "POST" ? JSON.stringify(params) : undefined
+      headers: this.authorizationHeaders(),
+      body: method === "POST" ? JSON.stringify(body ?? {}) : undefined
     });
-    if (!response.ok) {
-      const errorBody = await safeResponseText(response);
-      throw new Error(`${this.providerKey} ${resource} failed (${response.status}): ${errorBody}`);
+    if (response.status === 401 && await this.refreshAccessToken()) {
+      const retryResponse = await this.fetchFn(url, {
+        method,
+        headers: this.authorizationHeaders(),
+        body: method === "POST" ? JSON.stringify(body ?? {}) : undefined
+      });
+      return this.readResponsePayload(retryResponse, path);
     }
-    const data = await response.json();
-    return asRecord(data) ?? {};
+    return this.readResponsePayload(response, path);
   }
-  async callMcpTool(resource, params) {
+  async callMcpTool(toolName, args) {
     if (!this.mcpUrl) {
-      return {};
+      throw new Error(`${this.providerKey} MCP URL is not configured.`);
     }
     const response = await this.fetchFn(this.mcpUrl, {
       method: "POST",
@@ -182,78 +509,103 @@ class BaseHealthProvider {
         id: ++this.mcpRequestId,
         method: "tools/call",
         params: {
-          name: `${this.providerKey.replace("health.", "")}_${resource.replace(/\//g, "_")}`,
-          arguments: params
+          name: toolName,
+          arguments: args
         }
       })
     });
-    if (!response.ok) {
-      const errorBody = await safeResponseText(response);
-      throw new Error(`${this.providerKey} MCP ${resource} failed (${response.status}): ${errorBody}`);
+    const payload = await this.readResponsePayload(response, toolName);
+    const rpcEnvelope = asRecord(payload);
+    if (!rpcEnvelope)
+      return payload;
+    const rpcResult = asRecord(rpcEnvelope.result);
+    if (rpcResult) {
+      return rpcResult.structuredContent ?? rpcResult.data ?? rpcResult;
     }
-    const rpcPayload = await response.json();
-    const rpc = asRecord(rpcPayload);
-    const result = asRecord(rpc?.result) ?? {};
-    const structured = asRecord(result.structuredContent);
-    if (structured)
-      return structured;
-    const data = asRecord(result.data);
-    if (data)
-      return data;
-    return result;
+    return rpcEnvelope.structuredContent ?? rpcEnvelope.data ?? rpcEnvelope;
   }
-  currentSource() {
+  authorizationHeaders() {
+    const token = this.accessToken ?? this.apiKey;
     return {
-      providerKey: this.providerKey,
-      transport: this.transport,
-      route: "primary"
+      "Content-Type": "application/json",
+      ...token ? { Authorization: `Bearer ${token}` } : {}
     };
   }
-}
-function safeJsonParse(raw) {
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return { rawBody: raw };
+  async refreshAccessToken() {
+    if (!this.oauth.tokenUrl || !this.refreshToken) {
+      return false;
+    }
+    const tokenUrl = new URL(this.oauth.tokenUrl);
+    const body = new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: this.refreshToken,
+      ...this.oauth.clientId ? { client_id: this.oauth.clientId } : {},
+      ...this.oauth.clientSecret ? { client_secret: this.oauth.clientSecret } : {}
+    });
+    const response = await this.fetchFn(tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: body.toString()
+    });
+    if (!response.ok) {
+      return false;
+    }
+    const payload = await response.json();
+    this.accessToken = payload.access_token;
+    this.refreshToken = payload.refresh_token ?? this.refreshToken;
+    if (typeof payload.expires_in === "number") {
+      this.oauth.tokenExpiresAt = new Date(Date.now() + payload.expires_in * 1000).toISOString();
+    }
+    return Boolean(this.accessToken);
+  }
+  async readResponsePayload(response, context) {
+    if (!response.ok) {
+      const message = await safeReadText(response);
+      throw new Error(`${this.providerKey} request ${context} failed (${response.status}): ${message}`);
+    }
+    if (response.status === 204) {
+      return {};
+    }
+    return response.json();
   }
 }
 function readHeader(headers, key) {
-  const match = Object.entries(headers).find(([headerKey]) => headerKey.toLowerCase() === key.toLowerCase());
-  if (!match)
+  const target = key.toLowerCase();
+  const entry = Object.entries(headers).find(([headerKey]) => headerKey.toLowerCase() === target);
+  if (!entry)
     return;
-  const value = match[1];
+  const value = entry[1];
   return Array.isArray(value) ? value[0] : value;
 }
-function normalizeEntityType(value) {
-  if (!value)
-    return;
-  if (value === "activity" || value === "workout" || value === "sleep" || value === "biometric" || value === "nutrition") {
-    return value;
-  }
-  return;
-}
-function asRecord(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return;
+function countResultRecords(result) {
+  const listKeys = [
+    "activities",
+    "workouts",
+    "sleep",
+    "biometrics",
+    "nutrition"
+  ];
+  for (const key of listKeys) {
+    const value = result[key];
+    if (Array.isArray(value)) {
+      return value.length;
+    }
   }
-  return value;
-}
-function asArray(value) {
-  return Array.isArray(value) ? value : undefined;
-}
-function readString(record, key) {
-  const value = record?.[key];
-  return typeof value === "string" ? value : undefined;
+  return 0;
 }
-function readBoolean(record, key) {
-  const value = record?.[key];
-  return typeof value === "boolean" ? value : undefined;
+function ensureTrailingSlash(value) {
+  return value.endsWith("/") ? value : `${value}/`;
 }
-function readNumber(record, key) {
-  const value = record?.[key];
-  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+function safeJsonParse(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return { rawBody: raw };
+  }
 }
-async function safeResponseText(response) {
+async function safeReadText(response) {
   try {
     return await response.text();
   } catch {
@@ -261,5 +613,6 @@ async function safeResponseText(response) {
   }
 }
 export {
+  HealthProviderCapabilityError,
   BaseHealthProvider
 };