@contractspec/integration.providers-impls 2.8.0 → 2.10.0

package/dist/node/index.js

@@ -13,6 +13,9 @@ export * from "@contractspec/lib.contracts-integrations";
 // src/embedding.ts
 export * from "@contractspec/lib.contracts-integrations";
 
+// src/health.ts
+export * from "@contractspec/lib.contracts-integrations";
+
 // src/impls/elevenlabs-voice.ts
 import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
 var FORMAT_MAP = {
@@ -2030,6 +2033,498 @@ async function safeReadError3(response) {
   }
 }
 
+// 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 = readString2(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: readString2(payload, "lastCheckedAt") ?? new Date().toISOString(),
+      errorCode: readString2(payload, "errorCode"),
+      errorMessage: readString2(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: readString2(body, "eventType") ?? readString2(body, "event"),
+      externalEntityId: readString2(body, "externalEntityId") ?? readString2(body, "entityId"),
+      entityType: normalizeEntityType(readString2(body, "entityType") ?? readString2(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 = asArray2(payload.items) ?? asArray2(payload[resource]) ?? asArray2(payload.records) ?? [];
+    return {
+      items,
+      nextCursor: readString2(payload, "nextCursor") ?? readString2(payload, "cursor"),
+      hasMore: readBoolean2(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: readString2(payload, "nextCursor"),
+      errors: asArray2(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 asArray2(value) {
+  return Array.isArray(value) ? value : undefined;
+}
+function readString2(record, key) {
+  const value = record?.[key];
+  return typeof value === "string" ? value : undefined;
+}
+function readBoolean2(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;
+  }
+}
+
+// src/impls/health/providers.ts
+function createProviderOptions(options, fallbackTransport) {
+  return {
+    ...options,
+    transport: options.transport ?? fallbackTransport
+  };
+}
+
+class OpenWearablesHealthProvider extends BaseHealthProvider {
+  constructor(options) {
+    super({
+      providerKey: "health.openwearables",
+      ...createProviderOptions(options, "aggregator-api")
+    });
+  }
+}
+
+class WhoopHealthProvider extends BaseHealthProvider {
+  constructor(options) {
+    super({
+      providerKey: "health.whoop",
+      ...createProviderOptions(options, "official-api")
+    });
+  }
+}
+
+class AppleHealthBridgeProvider extends BaseHealthProvider {
+  constructor(options) {
+    super({
+      providerKey: "health.apple-health",
+      ...createProviderOptions(options, "aggregator-api")
+    });
+  }
+}
+
+class OuraHealthProvider extends BaseHealthProvider {
+  constructor(options) {
+    super({
+      providerKey: "health.oura",
+      ...createProviderOptions(options, "official-api")
+    });
+  }
+}
+
+class StravaHealthProvider extends BaseHealthProvider {
+  constructor(options) {
+    super({
+      providerKey: "health.strava",
+      ...createProviderOptions(options, "official-api")
+    });
+  }
+}
+
+class GarminHealthProvider extends BaseHealthProvider {
+  constructor(options) {
+    super({
+      providerKey: "health.garmin",
+      ...createProviderOptions(options, "official-api")
+    });
+  }
+}
+
+class FitbitHealthProvider extends BaseHealthProvider {
+  constructor(options) {
+    super({
+      providerKey: "health.fitbit",
+      ...createProviderOptions(options, "official-api")
+    });
+  }
+}
+
+class MyFitnessPalHealthProvider extends BaseHealthProvider {
+  constructor(options) {
+    super({
+      providerKey: "health.myfitnesspal",
+      ...createProviderOptions(options, "official-api")
+    });
+  }
+}
+
+class EightSleepHealthProvider extends BaseHealthProvider {
+  constructor(options) {
+    super({
+      providerKey: "health.eightsleep",
+      ...createProviderOptions(options, "official-api")
+    });
+  }
+}
+
+class PelotonHealthProvider extends BaseHealthProvider {
+  constructor(options) {
+    super({
+      providerKey: "health.peloton",
+      ...createProviderOptions(options, "official-api")
+    });
+  }
+}
+
+class UnofficialHealthAutomationProvider extends BaseHealthProvider {
+  constructor(options) {
+    super({
+      ...createProviderOptions(options, "unofficial"),
+      providerKey: options.providerKey
+    });
+  }
+}
+
+// src/impls/health-provider-factory.ts
+import {
+  isUnofficialHealthProviderAllowed,
+  resolveHealthStrategyOrder
+} from "@contractspec/integration.runtime/runtime";
+function createHealthProviderFromContext(context, secrets) {
+  const providerKey = context.spec.meta.key;
+  const config = toFactoryConfig(context.config);
+  const strategyOrder = buildStrategyOrder(config);
+  const errors = [];
+  for (const strategy of strategyOrder) {
+    const provider = createHealthProviderForStrategy(providerKey, strategy, config, secrets);
+    if (provider) {
+      return provider;
+    }
+    errors.push(`${strategy}: not available`);
+  }
+  throw new Error(`Unable to resolve health provider for ${providerKey}. Strategies attempted: ${errors.join(", ")}.`);
+}
+function createHealthProviderForStrategy(providerKey, strategy, config, secrets) {
+  const options = {
+    transport: strategy,
+    apiBaseUrl: config.apiBaseUrl,
+    mcpUrl: config.mcpUrl,
+    apiKey: getSecretString(secrets, "apiKey"),
+    accessToken: getSecretString(secrets, "accessToken"),
+    mcpAccessToken: getSecretString(secrets, "mcpAccessToken"),
+    webhookSecret: getSecretString(secrets, "webhookSecret")
+  };
+  if (strategy === "aggregator-api" || strategy === "aggregator-mcp") {
+    return new OpenWearablesHealthProvider(options);
+  }
+  if (strategy === "unofficial") {
+    if (!isUnofficialHealthProviderAllowed(providerKey, config)) {
+      return;
+    }
+    if (providerKey !== "health.myfitnesspal" && providerKey !== "health.eightsleep" && providerKey !== "health.peloton" && providerKey !== "health.garmin") {
+      return;
+    }
+    return new UnofficialHealthAutomationProvider({
+      ...options,
+      providerKey
+    });
+  }
+  if (strategy === "official-mcp") {
+    return createOfficialProvider(providerKey, {
+      ...options,
+      transport: "official-mcp"
+    });
+  }
+  return createOfficialProvider(providerKey, options);
+}
+function createOfficialProvider(providerKey, options) {
+  switch (providerKey) {
+    case "health.openwearables":
+      return new OpenWearablesHealthProvider(options);
+    case "health.whoop":
+      return new WhoopHealthProvider(options);
+    case "health.apple-health":
+      return new AppleHealthBridgeProvider(options);
+    case "health.oura":
+      return new OuraHealthProvider(options);
+    case "health.strava":
+      return new StravaHealthProvider(options);
+    case "health.garmin":
+      return new GarminHealthProvider(options);
+    case "health.fitbit":
+      return new FitbitHealthProvider(options);
+    case "health.myfitnesspal":
+      return new MyFitnessPalHealthProvider(options);
+    case "health.eightsleep":
+      return new EightSleepHealthProvider(options);
+    case "health.peloton":
+      return new PelotonHealthProvider(options);
+    default:
+      throw new Error(`Unsupported health provider key: ${providerKey}`);
+  }
+}
+function toFactoryConfig(config) {
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    return {};
+  }
+  const record = config;
+  return {
+    apiBaseUrl: asString(record.apiBaseUrl),
+    mcpUrl: asString(record.mcpUrl),
+    defaultTransport: normalizeTransport(record.defaultTransport),
+    strategyOrder: normalizeTransportArray(record.strategyOrder),
+    allowUnofficial: typeof record.allowUnofficial === "boolean" ? record.allowUnofficial : false,
+    unofficialAllowList: Array.isArray(record.unofficialAllowList) ? record.unofficialAllowList.map((item) => typeof item === "string" ? item : undefined).filter((item) => Boolean(item)) : undefined
+  };
+}
+function buildStrategyOrder(config) {
+  const order = resolveHealthStrategyOrder(config);
+  if (!config.defaultTransport) {
+    return order;
+  }
+  const withoutDefault = order.filter((item) => item !== config.defaultTransport);
+  return [config.defaultTransport, ...withoutDefault];
+}
+function normalizeTransport(value) {
+  if (typeof value !== "string")
+    return;
+  if (value === "official-api" || value === "official-mcp" || value === "aggregator-api" || value === "aggregator-mcp" || value === "unofficial") {
+    return value;
+  }
+  return;
+}
+function normalizeTransportArray(value) {
+  if (!Array.isArray(value))
+    return;
+  const transports = value.map((item) => normalizeTransport(item)).filter((item) => Boolean(item));
+  return transports.length > 0 ? transports : undefined;
+}
+function getSecretString(secrets, key) {
+  const value = secrets[key];
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function asString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
 // src/impls/mistral-llm.ts
 import { Mistral } from "@mistralai/mistralai";
 
@@ -3403,7 +3898,7 @@ function mapStatus(status) {
 }
 
 // src/impls/powens-client.ts
-import { URL } from "node:url";
+import { URL as URL2 } from "node:url";
 var POWENS_BASE_URL = {
   sandbox: "https://api-sandbox.powens.com/v2",
   production: "https://api.powens.com/v2"
@@ -3489,7 +3984,7 @@ class PowensClient {
     });
   }
   async request(options) {
-    const url = new URL(options.path, this.baseUrl);
+    const url = new URL2(options.path, this.baseUrl);
     if (options.searchParams) {
       for (const [key, value] of Object.entries(options.searchParams)) {
         if (value === undefined || value === null)
@@ -3559,7 +4054,7 @@ class PowensClient {
     return this.token.accessToken;
   }
   async fetchAccessToken() {
-    const url = new URL("/oauth/token", this.baseUrl);
+    const url = new URL2("/oauth/token", this.baseUrl);
     const basicAuth = Buffer.from(`${this.clientId}:${this.clientSecret}`, "utf-8").toString("base64");
     const response = await this.fetchImpl(url, {
       method: "POST",
@@ -4603,6 +5098,10 @@ class IntegrationProviderFactory {
         throw new Error(`Unsupported open banking integration: ${context.spec.meta.key}`);
     }
   }
+  async createHealthProvider(context) {
+    const secrets = await this.loadSecrets(context);
+    return createHealthProviderFromContext(context, secrets);
+  }
   async loadSecrets(context) {
     const cacheKey = context.connection.meta.id;
     if (SECRET_CACHE.has(cacheKey)) {
@@ -4674,11 +5173,15 @@ export * from "@contractspec/lib.contracts-integrations";
 // src/meeting-recorder.ts
 export * from "@contractspec/lib.contracts-integrations";
 export {
+  createHealthProviderFromContext,
+  WhoopHealthProvider,
+  UnofficialHealthAutomationProvider,
   TwilioSmsProvider,
   TldvMeetingRecorderProvider,
   SupabaseVectorProvider,
   SupabasePostgresProvider,
   StripePaymentsProvider,
+  StravaHealthProvider,
   QdrantVectorProvider,
   PowensOpenBankingProvider,
   PowensClientError,
@@ -4686,7 +5189,11 @@ export {
   PostmarkEmailProvider,
   PosthogAnalyticsReader,
   PosthogAnalyticsProvider,
+  PelotonHealthProvider,
+  OuraHealthProvider,
+  OpenWearablesHealthProvider,
   NotionProjectManagementProvider,
+  MyFitnessPalHealthProvider,
   MistralLLMProvider,
   MistralEmbeddingProvider,
   LinearProjectManagementProvider,
@@ -4698,8 +5205,12 @@ export {
   GoogleCalendarProvider,
   GmailOutboundProvider,
   GmailInboundProvider,
+  GarminHealthProvider,
+  FitbitHealthProvider,
   FirefliesMeetingRecorderProvider,
   FathomMeetingRecorderProvider,
   FalVoiceProvider,
-  ElevenLabsVoiceProvider
+  ElevenLabsVoiceProvider,
+  EightSleepHealthProvider,
+  AppleHealthBridgeProvider
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/integration.providers-impls",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "description": "Integration provider implementations for email, payments, storage, and more",
   "keywords": [
     "contractspec",
@@ -32,9 +32,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.contracts-spec": "2.8.0",
-    "@contractspec/lib.contracts-integrations": "2.8.0",
-    "@contractspec/integration.runtime": "2.8.0",
+    "@contractspec/lib.contracts-spec": "2.10.0",
+    "@contractspec/lib.contracts-integrations": "2.10.0",
+    "@contractspec/integration.runtime": "2.10.0",
     "@elevenlabs/elevenlabs-js": "^2.36.0",
     "@fal-ai/client": "^1.9.3",
     "@google-cloud/storage": "^7.19.0",
@@ -55,9 +55,9 @@
   },
   "devDependencies": {
     "@types/bun": "1.3.9",
-    "@contractspec/tool.typescript": "2.8.0",
+    "@contractspec/tool.typescript": "2.9.0",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "2.8.0"
+    "@contractspec/tool.bun": "2.9.0"
   },
   "exports": {
     ".": {
@@ -96,6 +96,12 @@
       "node": "./dist/node/embedding.js",
       "default": "./dist/embedding.js"
     },
+    "./health": {
+      "types": "./dist/health.d.ts",
+      "bun": "./dist/health.js",
+      "node": "./dist/node/health.js",
+      "default": "./dist/health.js"
+    },
     "./impls": {
       "types": "./dist/impls/index.d.ts",
       "bun": "./dist/impls/index.js",
@@ -216,6 +222,24 @@
       "node": "./dist/node/impls/granola-meeting-recorder.types.js",
       "default": "./dist/impls/granola-meeting-recorder.types.js"
     },
+    "./impls/health-provider-factory": {
+      "types": "./dist/impls/health-provider-factory.d.ts",
+      "bun": "./dist/impls/health-provider-factory.js",
+      "node": "./dist/node/impls/health-provider-factory.js",
+      "default": "./dist/impls/health-provider-factory.js"
+    },
+    "./impls/health/base-health-provider": {
+      "types": "./dist/impls/health/base-health-provider.d.ts",
+      "bun": "./dist/impls/health/base-health-provider.js",
+      "node": "./dist/node/impls/health/base-health-provider.js",
+      "default": "./dist/impls/health/base-health-provider.js"
+    },
+    "./impls/health/providers": {
+      "types": "./dist/impls/health/providers.d.ts",
+      "bun": "./dist/impls/health/providers.js",
+      "node": "./dist/node/impls/health/providers.js",
+      "default": "./dist/impls/health/providers.js"
+    },
     "./impls/index": {
       "types": "./dist/impls/index.d.ts",
       "bun": "./dist/impls/index.js",
@@ -436,6 +460,12 @@
         "node": "./dist/node/embedding.js",
         "default": "./dist/embedding.js"
       },
+      "./health": {
+        "types": "./dist/health.d.ts",
+        "bun": "./dist/health.js",
+        "node": "./dist/node/health.js",
+        "default": "./dist/health.js"
+      },
       "./impls": {
         "types": "./dist/impls/index.d.ts",
         "bun": "./dist/impls/index.js",
@@ -556,6 +586,24 @@
         "node": "./dist/node/impls/granola-meeting-recorder.types.js",
         "default": "./dist/impls/granola-meeting-recorder.types.js"
       },
+      "./impls/health-provider-factory": {
+        "types": "./dist/impls/health-provider-factory.d.ts",
+        "bun": "./dist/impls/health-provider-factory.js",
+        "node": "./dist/node/impls/health-provider-factory.js",
+        "default": "./dist/impls/health-provider-factory.js"
+      },
+      "./impls/health/base-health-provider": {
+        "types": "./dist/impls/health/base-health-provider.d.ts",
+        "bun": "./dist/impls/health/base-health-provider.js",
+        "node": "./dist/node/impls/health/base-health-provider.js",
+        "default": "./dist/impls/health/base-health-provider.js"
+      },
+      "./impls/health/providers": {
+        "types": "./dist/impls/health/providers.d.ts",
+        "bun": "./dist/impls/health/providers.js",
+        "node": "./dist/node/impls/health/providers.js",
+        "default": "./dist/impls/health/providers.js"
+      },
       "./impls/index": {
         "types": "./dist/impls/index.d.ts",
         "bun": "./dist/impls/index.js",