@contractspec/integration.providers-impls 2.8.0 → 2.10.0

package/README.md

@@ -43,6 +43,59 @@ const factory = new IntegrationProviderFactory();
 const analytics = await factory.createAnalyticsProvider(context); // key: analytics.posthog
 ```
 
+## Health integrations
+
+This package ships health/wearables providers routed by a transport strategy:
+
+- Official provider APIs/MCP (Whoop, Apple Health bridge, Oura, Strava, Garmin, Fitbit)
+- Aggregator API/MCP (Open Wearables)
+- Unofficial automation fallback (opt-in and allow-list gated)
+
+Factory usage:
+
+```ts
+import { IntegrationProviderFactory } from "@contractspec/integration.providers-impls/impls/provider-factory";
+
+const factory = new IntegrationProviderFactory();
+const healthProvider = await factory.createHealthProvider(context); // key: health.*
+```
+
+Connection config example:
+
+```json
+{
+  "defaultTransport": "official-api",
+  "strategyOrder": [
+    "official-api",
+    "official-mcp",
+    "aggregator-api",
+    "aggregator-mcp",
+    "unofficial"
+  ],
+  "allowUnofficial": false,
+  "unofficialAllowList": ["health.peloton"],
+  "apiBaseUrl": "https://api.provider.example",
+  "mcpUrl": "https://mcp.provider.example"
+}
+```
+
+Secret payload example (`secretRef` target value):
+
+```json
+{
+  "apiKey": "provider-api-key",
+  "accessToken": "oauth-access-token",
+  "mcpAccessToken": "mcp-access-token",
+  "webhookSecret": "webhook-signature-secret"
+}
+```
+
+Notes:
+
+- Unofficial routing is disabled unless `allowUnofficial: true`.
+- When `unofficialAllowList` is provided, only listed `health.*` keys can use unofficial routing.
+- If a selected strategy is unavailable, the resolver falls through `strategyOrder`.
+
 ## Supabase integrations
 
 This package now ships two Supabase providers:

package/dist/health.d.ts

@@ -0,0 +1 @@
+export * from '@contractspec/lib.contracts-integrations';

package/dist/health.js

@@ -0,0 +1,3 @@
+// @bun
+// src/health.ts
+export * from "@contractspec/lib.contracts-integrations";

package/dist/impls/health/base-health-provider.d.ts

@@ -0,0 +1,47 @@
+import type { HealthConnectionStatus, HealthDataSource, HealthListActivitiesParams, HealthListActivitiesResult, HealthListBiometricsParams, HealthListBiometricsResult, HealthListNutritionParams, HealthListNutritionResult, HealthListSleepParams, HealthListSleepResult, HealthListWorkoutsParams, HealthListWorkoutsResult, HealthProvider, HealthSyncRequest, HealthSyncResult, HealthWebhookEvent, HealthWebhookRequest } from '../../health';
+import type { HealthTransportStrategy } from '@contractspec/integration.runtime/runtime';
+export interface BaseHealthProviderOptions {
+    providerKey: string;
+    transport: HealthTransportStrategy;
+    apiBaseUrl?: string;
+    mcpUrl?: string;
+    apiKey?: string;
+    accessToken?: string;
+    mcpAccessToken?: string;
+    webhookSecret?: string;
+    fetchFn?: typeof fetch;
+}
+export declare class BaseHealthProvider implements HealthProvider {
+    private readonly providerKey;
+    private readonly transport;
+    private readonly apiBaseUrl;
+    private readonly mcpUrl?;
+    private readonly apiKey?;
+    private readonly accessToken?;
+    private readonly mcpAccessToken?;
+    private readonly webhookSecret?;
+    private readonly fetchFn;
+    private mcpRequestId;
+    constructor(options: BaseHealthProviderOptions);
+    listActivities(params: HealthListActivitiesParams): Promise<HealthListActivitiesResult>;
+    listWorkouts(params: HealthListWorkoutsParams): Promise<HealthListWorkoutsResult>;
+    listSleep(params: HealthListSleepParams): Promise<HealthListSleepResult>;
+    listBiometrics(params: HealthListBiometricsParams): Promise<HealthListBiometricsResult>;
+    listNutrition(params: HealthListNutritionParams): Promise<HealthListNutritionResult>;
+    getConnectionStatus(params: {
+        tenantId: string;
+        connectionId: string;
+    }): Promise<HealthConnectionStatus>;
+    syncActivities(params: HealthSyncRequest): Promise<HealthSyncResult>;
+    syncWorkouts(params: HealthSyncRequest): Promise<HealthSyncResult>;
+    syncSleep(params: HealthSyncRequest): Promise<HealthSyncResult>;
+    syncBiometrics(params: HealthSyncRequest): Promise<HealthSyncResult>;
+    syncNutrition(params: HealthSyncRequest): Promise<HealthSyncResult>;
+    parseWebhook(request: HealthWebhookRequest): Promise<HealthWebhookEvent>;
+    verifyWebhook(request: HealthWebhookRequest): Promise<boolean>;
+    private fetchList;
+    private sync;
+    private fetchRecord;
+    private callMcpTool;
+    protected currentSource(): HealthDataSource;
+}

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

@@ -0,0 +1,266 @@
+// @bun
+// src/impls/health/base-health-provider.ts
+class BaseHealthProvider {
+  providerKey;
+  transport;
+  apiBaseUrl;
+  mcpUrl;
+  apiKey;
+  accessToken;
+  mcpAccessToken;
+  webhookSecret;
+  fetchFn;
+  mcpRequestId = 0;
+  constructor(options) {
+    this.providerKey = options.providerKey;
+    this.transport = options.transport;
+    this.apiBaseUrl = options.apiBaseUrl ?? "https://api.example-health.local";
+    this.mcpUrl = options.mcpUrl;
+    this.apiKey = options.apiKey;
+    this.accessToken = options.accessToken;
+    this.mcpAccessToken = options.mcpAccessToken;
+    this.webhookSecret = options.webhookSecret;
+    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 listWorkouts(params) {
+    const result = await this.fetchList("workouts", params);
+    return {
+      workouts: result.items,
+      nextCursor: result.nextCursor,
+      hasMore: result.hasMore,
+      source: this.currentSource()
+    };
+  }
+  async listSleep(params) {
+    const result = await this.fetchList("sleep", params);
+    return {
+      sleep: result.items,
+      nextCursor: result.nextCursor,
+      hasMore: result.hasMore,
+      source: this.currentSource()
+    };
+  }
+  async listBiometrics(params) {
+    const result = await this.fetchList("biometrics", params);
+    return {
+      biometrics: result.items,
+      nextCursor: result.nextCursor,
+      hasMore: result.hasMore,
+      source: this.currentSource()
+    };
+  }
+  async listNutrition(params) {
+    const result = await this.fetchList("nutrition", params);
+    return {
+      nutrition: result.items,
+      nextCursor: result.nextCursor,
+      hasMore: result.hasMore,
+      source: this.currentSource()
+    };
+  }
+  async getConnectionStatus(params) {
+    const payload = await this.fetchRecord("connection/status", params);
+    const status = readString(payload, "status") ?? "healthy";
+    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)
+    };
+  }
+  async syncActivities(params) {
+    return this.sync("activities", params);
+  }
+  async syncWorkouts(params) {
+    return this.sync("workouts", params);
+  }
+  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);
+    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
+    };
+  }
+  async verifyWebhook(request) {
+    if (!this.webhookSecret) {
+      return true;
+    }
+    const signature = readHeader(request.headers, "x-webhook-signature");
+    return signature === this.webhookSecret;
+  }
+  async fetchList(resource, params) {
+    const payload = await this.fetchRecord(resource, params);
+    const items = asArray(payload.items) ?? asArray(payload[resource]) ?? asArray(payload.records) ?? [];
+    return {
+      items,
+      nextCursor: readString(payload, "nextCursor") ?? readString(payload, "cursor"),
+      hasMore: readBoolean(payload, "hasMore")
+    };
+  }
+  async sync(resource, params) {
+    const payload = await this.fetchRecord(`sync/${resource}`, params, "POST");
+    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()
+    };
+  }
+  async fetchRecord(resource, params, method = "GET") {
+    if (this.transport.endsWith("mcp")) {
+      return this.callMcpTool(resource, params);
+    }
+    const url = new URL(`${this.apiBaseUrl.replace(/\/$/, "")}/${resource}`);
+    if (method === "GET") {
+      for (const [key, value] of Object.entries(params)) {
+        if (value == null)
+          continue;
+        if (Array.isArray(value)) {
+          value.forEach((item) => {
+            url.searchParams.append(key, String(item));
+          });
+          continue;
+        }
+        url.searchParams.set(key, String(value));
+      }
+    }
+    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
+    });
+    if (!response.ok) {
+      const errorBody = await safeResponseText(response);
+      throw new Error(`${this.providerKey} ${resource} failed (${response.status}): ${errorBody}`);
+    }
+    const data = await response.json();
+    return asRecord(data) ?? {};
+  }
+  async callMcpTool(resource, params) {
+    if (!this.mcpUrl) {
+      return {};
+    }
+    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: `${this.providerKey.replace("health.", "")}_${resource.replace(/\//g, "_")}`,
+          arguments: params
+        }
+      })
+    });
+    if (!response.ok) {
+      const errorBody = await safeResponseText(response);
+      throw new Error(`${this.providerKey} MCP ${resource} failed (${response.status}): ${errorBody}`);
+    }
+    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;
+  }
+  currentSource() {
+    return {
+      providerKey: this.providerKey,
+      transport: this.transport,
+      route: "primary"
+    };
+  }
+}
+function safeJsonParse(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return { rawBody: raw };
+  }
+}
+function readHeader(headers, key) {
+  const match = Object.entries(headers).find(([headerKey]) => headerKey.toLowerCase() === key.toLowerCase());
+  if (!match)
+    return;
+  const value = match[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;
+  }
+  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;
+}
+function readBoolean(record, key) {
+  const value = record?.[key];
+  return typeof value === "boolean" ? value : undefined;
+}
+function readNumber(record, key) {
+  const value = record?.[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+async function safeResponseText(response) {
+  try {
+    return await response.text();
+  } catch {
+    return response.statusText;
+  }
+}
+export {
+  BaseHealthProvider
+};

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

@@ -0,0 +1,39 @@
+import { BaseHealthProvider, type BaseHealthProviderOptions } from './base-health-provider';
+type ProviderOptions = Omit<BaseHealthProviderOptions, 'providerKey'>;
+export declare class OpenWearablesHealthProvider extends BaseHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export declare class WhoopHealthProvider extends BaseHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export declare class AppleHealthBridgeProvider extends BaseHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export declare class OuraHealthProvider extends BaseHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export declare class StravaHealthProvider extends BaseHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export declare class GarminHealthProvider extends BaseHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export declare class FitbitHealthProvider extends BaseHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export declare class MyFitnessPalHealthProvider extends BaseHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export declare class EightSleepHealthProvider extends BaseHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export declare class PelotonHealthProvider extends BaseHealthProvider {
+    constructor(options: ProviderOptions);
+}
+export interface UnofficialHealthAutomationProviderOptions extends ProviderOptions {
+    providerKey: 'health.myfitnesspal' | 'health.eightsleep' | 'health.peloton' | 'health.garmin';
+}
+export declare class UnofficialHealthAutomationProvider extends BaseHealthProvider {
+    constructor(options: UnofficialHealthAutomationProviderOptions);
+}
+export {};