@contractspec/integration.providers-impls 2.9.0 → 3.0.0

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

@@ -0,0 +1,616 @@
+// @bun
+// 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;
+  apiBaseUrl;
+  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;
+    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) {
+    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 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 {
+      activities: response.items,
+      nextCursor: response.nextCursor,
+      hasMore: response.hasMore,
+      source: this.currentSource()
+    };
+  }
+  async fetchWorkouts(params, config) {
+    const response = await this.fetchList(params, config);
+    return {
+      workouts: response.items,
+      nextCursor: response.nextCursor,
+      hasMore: response.hasMore,
+      source: this.currentSource()
+    };
+  }
+  async fetchSleep(params, config) {
+    const response = await this.fetchList(params, config);
+    return {
+      sleep: response.items,
+      nextCursor: response.nextCursor,
+      hasMore: response.hasMore,
+      source: this.currentSource()
+    };
+  }
+  async fetchBiometrics(params, config) {
+    const response = await this.fetchList(params, config);
+    return {
+      biometrics: response.items,
+      nextCursor: response.nextCursor,
+      hasMore: response.hasMore,
+      source: this.currentSource()
+    };
+  }
+  async fetchNutrition(params, config) {
+    const response = await this.fetchList(params, config);
+    return {
+      nutrition: response.items,
+      nextCursor: response.nextCursor,
+      hasMore: response.hasMore,
+      source: this.currentSource()
+    };
+  }
+  async fetchConnectionStatus(params, config) {
+    const payload = await this.fetchPayload(config, params);
+    return toHealthConnectionStatus(payload, params, this.currentSource());
+  }
+  currentSource() {
+    return {
+      providerKey: this.providerKey,
+      transport: this.transport,
+      route: this.route,
+      aggregatorKey: this.aggregatorKey
+    };
+  }
+  providerSlug() {
+    return this.providerKey.replace("health.", "").replace(/-/g, "_");
+  }
+  unsupported(capability) {
+    return new HealthProviderCapabilityError(`${this.providerKey} does not support ${capability}`);
+  }
+  async syncFromList(executor) {
+    const result = await executor();
+    const records = countResultRecords(result);
+    return {
+      synced: records,
+      failed: 0,
+      nextCursor: undefined,
+      source: result.source
+    };
+  }
+  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 {
+      items,
+      nextCursor: pagination.nextCursor,
+      hasMore: pagination.hasMore
+    };
+  }
+  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.`);
+    }
+    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((entry) => {
+            if (entry != null)
+              url.searchParams.append(key, String(entry));
+          });
+          continue;
+        }
+        url.searchParams.set(key, String(value));
+      }
+    }
+    const response = await this.fetchFn(url, {
+      method,
+      headers: this.authorizationHeaders(),
+      body: method === "POST" ? JSON.stringify(body ?? {}) : undefined
+    });
+    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);
+    }
+    return this.readResponsePayload(response, path);
+  }
+  async callMcpTool(toolName, args) {
+    if (!this.mcpUrl) {
+      throw new Error(`${this.providerKey} MCP URL is not configured.`);
+    }
+    const response = await this.fetchFn(this.mcpUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.mcpAccessToken ? { Authorization: `Bearer ${this.mcpAccessToken}` } : {}
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: ++this.mcpRequestId,
+        method: "tools/call",
+        params: {
+          name: toolName,
+          arguments: args
+        }
+      })
+    });
+    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;
+    }
+    return rpcEnvelope.structuredContent ?? rpcEnvelope.data ?? rpcEnvelope;
+  }
+  authorizationHeaders() {
+    const token = this.accessToken ?? this.apiKey;
+    return {
+      "Content-Type": "application/json",
+      ...token ? { Authorization: `Bearer ${token}` } : {}
+    };
+  }
+  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 target = key.toLowerCase();
+  const entry = Object.entries(headers).find(([headerKey]) => headerKey.toLowerCase() === target);
+  if (!entry)
+    return;
+  const value = entry[1];
+  return Array.isArray(value) ? value[0] : value;
+}
+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 0;
+}
+function ensureTrailingSlash(value) {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+function safeJsonParse(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return { rawBody: raw };
+  }
+}
+async function safeReadText(response) {
+  try {
+    return await response.text();
+  } catch {
+    return response.statusText;
+  }
+}
+export {
+  HealthProviderCapabilityError,
+  BaseHealthProvider
+};

package/dist/impls/health/hybrid-health-providers.d.ts

@@ -0,0 +1,34 @@
+import type { HealthListActivitiesParams, HealthListBiometricsParams, HealthListNutritionParams, HealthListSleepParams, HealthListWorkoutsParams } from '../../health';
+import { BaseHealthProvider, type BaseHealthProviderOptions } from './base-health-provider';
+import { OpenWearablesHealthProvider } from './official-health-providers';
+type ProviderOptions = Omit<BaseHealthProviderOptions, 'providerKey'>;
+export declare class GarminHealthProvider extends OpenWearablesHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export declare class MyFitnessPalHealthProvider extends OpenWearablesHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export declare class EightSleepHealthProvider extends OpenWearablesHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export declare class PelotonHealthProvider extends OpenWearablesHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export interface UnofficialHealthAutomationProviderOptions extends ProviderOptions {
+    providerKey: 'health.garmin' | 'health.myfitnesspal' | 'health.eightsleep' | 'health.peloton';
+}
+export declare class UnofficialHealthAutomationProvider extends BaseHealthProvider {
+    private readonly providerSlugValue;
+    constructor(options: UnofficialHealthAutomationProviderOptions);
+    listActivities(params: HealthListActivitiesParams): Promise<import("@contractspec/lib.contracts-integrations").HealthListActivitiesResult>;
+    listWorkouts(params: HealthListWorkoutsParams): Promise<import("@contractspec/lib.contracts-integrations").HealthListWorkoutsResult>;
+    listSleep(params: HealthListSleepParams): Promise<import("@contractspec/lib.contracts-integrations").HealthListSleepResult>;
+    listBiometrics(params: HealthListBiometricsParams): Promise<import("@contractspec/lib.contracts-integrations").HealthListBiometricsResult>;
+    listNutrition(params: HealthListNutritionParams): Promise<import("@contractspec/lib.contracts-integrations").HealthListNutritionResult>;
+    getConnectionStatus(params: {
+        tenantId: string;
+        connectionId: string;
+    }): Promise<import("@contractspec/lib.contracts-integrations").HealthConnectionStatus>;
+    private context;
+}
+export {};