@contractspec/integration.providers-impls 2.9.0 → 3.0.0

package/README.md

@@ -43,6 +43,65 @@ 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",
+  "oauthTokenUrl": "https://api.provider.example/oauth/token"
+}
+```
+
+Secret payload example (`secretRef` target value):
+
+```json
+{
+  "apiKey": "provider-api-key",
+  "accessToken": "oauth-access-token",
+  "refreshToken": "oauth-refresh-token",
+  "clientId": "oauth-client-id",
+  "clientSecret": "oauth-client-secret",
+  "tokenExpiresAt": "2026-02-01T00:00:00.000Z",
+  "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.
+- Unofficial routing expects MCP transport (`mcpUrl`) plus either `mcpAccessToken` or automation credentials.
+- 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/async-event-queue.d.ts

@@ -0,0 +1,8 @@
+export declare class AsyncEventQueue<T> implements AsyncIterable<T> {
+    private readonly values;
+    private readonly waiters;
+    private done;
+    push(value: T): void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/impls/async-event-queue.js

@@ -0,0 +1,47 @@
+// @bun
+// src/impls/async-event-queue.ts
+class AsyncEventQueue {
+  values = [];
+  waiters = [];
+  done = false;
+  push(value) {
+    if (this.done) {
+      return;
+    }
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ value, done: false });
+      return;
+    }
+    this.values.push(value);
+  }
+  close() {
+    if (this.done) {
+      return;
+    }
+    this.done = true;
+    for (const waiter of this.waiters) {
+      waiter({ value: undefined, done: true });
+    }
+    this.waiters.length = 0;
+  }
+  [Symbol.asyncIterator]() {
+    return {
+      next: async () => {
+        const value = this.values.shift();
+        if (value != null) {
+          return { value, done: false };
+        }
+        if (this.done) {
+          return { value: undefined, done: true };
+        }
+        return new Promise((resolve) => {
+          this.waiters.push(resolve);
+        });
+      }
+    };
+  }
+}
+export {
+  AsyncEventQueue
+};

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

@@ -0,0 +1,98 @@
+import type { HealthActivity, HealthBiometric, HealthConnectionStatus, HealthDataSource, HealthListActivitiesParams, HealthListActivitiesResult, HealthListBiometricsParams, HealthListBiometricsResult, HealthListNutritionParams, HealthListNutritionResult, HealthListSleepParams, HealthListSleepResult, HealthListWorkoutsParams, HealthListWorkoutsResult, HealthNutrition, HealthProvider, HealthSleep, HealthSyncRequest, HealthSyncResult, HealthWebhookEvent, HealthWebhookRequest, HealthWorkout } from '../../health';
+import type { HealthTransportStrategy } from '@contractspec/integration.runtime/runtime';
+type UnknownRecord = Record<string, unknown>;
+interface OAuthOptions {
+    tokenUrl?: string;
+    refreshToken?: string;
+    clientId?: string;
+    clientSecret?: string;
+    tokenExpiresAt?: string;
+}
+export interface BaseHealthProviderOptions {
+    providerKey: string;
+    transport: HealthTransportStrategy;
+    apiBaseUrl?: string;
+    mcpUrl?: string;
+    apiKey?: string;
+    accessToken?: string;
+    mcpAccessToken?: string;
+    webhookSecret?: string;
+    webhookSignatureHeader?: string;
+    route?: 'primary' | 'fallback';
+    aggregatorKey?: string;
+    oauth?: OAuthOptions;
+    fetchFn?: typeof fetch;
+}
+interface DatasetFetchConfig<P, T> {
+    apiPath?: string;
+    mcpTool: string;
+    listKeys?: readonly string[];
+    method?: 'GET' | 'POST';
+    buildQuery?: (params: P) => UnknownRecord;
+    buildBody?: (params: P) => UnknownRecord;
+    mapItem: (item: UnknownRecord, params: P) => T | undefined;
+}
+interface ConnectionStatusConfig {
+    apiPath?: string;
+    mcpTool: string;
+}
+export declare class HealthProviderCapabilityError extends Error {
+    readonly code = "NOT_SUPPORTED";
+    constructor(message: string);
+}
+export declare class BaseHealthProvider implements HealthProvider {
+    protected readonly providerKey: string;
+    protected readonly transport: HealthTransportStrategy;
+    private readonly apiBaseUrl?;
+    private readonly mcpUrl?;
+    private readonly apiKey?;
+    private accessToken?;
+    private refreshToken?;
+    private readonly mcpAccessToken?;
+    private readonly webhookSecret?;
+    private readonly webhookSignatureHeader;
+    private readonly route;
+    private readonly aggregatorKey?;
+    private readonly oauth;
+    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>;
+    protected fetchActivities(params: HealthListActivitiesParams, config: DatasetFetchConfig<HealthListActivitiesParams, HealthActivity>): Promise<HealthListActivitiesResult>;
+    protected fetchWorkouts(params: HealthListWorkoutsParams, config: DatasetFetchConfig<HealthListWorkoutsParams, HealthWorkout>): Promise<HealthListWorkoutsResult>;
+    protected fetchSleep(params: HealthListSleepParams, config: DatasetFetchConfig<HealthListSleepParams, HealthSleep>): Promise<HealthListSleepResult>;
+    protected fetchBiometrics(params: HealthListBiometricsParams, config: DatasetFetchConfig<HealthListBiometricsParams, HealthBiometric>): Promise<HealthListBiometricsResult>;
+    protected fetchNutrition(params: HealthListNutritionParams, config: DatasetFetchConfig<HealthListNutritionParams, HealthNutrition>): Promise<HealthListNutritionResult>;
+    protected fetchConnectionStatus(params: {
+        tenantId: string;
+        connectionId: string;
+    }, config: ConnectionStatusConfig): Promise<HealthConnectionStatus>;
+    protected currentSource(): HealthDataSource;
+    protected providerSlug(): string;
+    protected unsupported(capability: string): HealthProviderCapabilityError;
+    private syncFromList;
+    private fetchList;
+    private fetchPayload;
+    private isMcpTransport;
+    private requestApi;
+    private callMcpTool;
+    private authorizationHeaders;
+    private refreshAccessToken;
+    private readResponsePayload;
+}
+export {};