@tryterra/react-native 2.1.0 → 2.2.1

package/src/Terra.ts

@@ -13,19 +13,29 @@ import { GeneratedClient, type Invoker } from "./generated/client";
 import { availableOn, type OpId, type StreamId } from "./generated/ops";
 import { decodeStreamDelivery, type StreamElements } from "./generated/streams";
 import type {
+  AthleteProfile,
   BodyEntry,
+  BodyReading,
   BootstrapState,
   Connection,
   DataCategory,
+  DayTotal,
   DiagnosticsState,
+  DietaryQuantity,
   EndUser,
   HealthAccess,
   HealthChange,
   HeartRateEntry,
   HeartRateSample,
+  HydrationSample,
+  IntradaySample,
+  MenstrualEvent,
+  MenstruationFlowDay,
   NutritionEntry,
   PermissionStatus,
   PlannedWorkout,
+  RestingHeartRateSample,
+  StoreAvailability,
   WorkoutSchedulingStatus,
   SleepEntry,
   SleepSegment,
@@ -37,6 +47,8 @@ import type {
   TimeRange,
   Workout,
   WorkoutEntry,
+  WorkoutIntensitySample,
+  WorkoutRoute,
   WorkoutScope,
 } from "./generated/types";
 
@@ -113,6 +125,17 @@ interface Changes {
 
 export interface BodyMetrics extends Changes {
   heartRate(range: TimeRange): Promise<readonly HeartRateSample[]>;
+  /**
+   * The store's own resting heart rate, one per day it computed, never derived from `heartRate`.
+   * Health Connect grants it under `daily`, so on Android ask for `daily` as well as `body`.
+   */
+  restingHeartRate(range: TimeRange): Promise<readonly RestingHeartRateSample[]>;
+  /**
+   * Weight, height, BMI (iOS), body fat, lean mass, heart rate variability, VO2 max, blood pressure,
+   * blood glucose, oxygen saturation, temperature and respiratory rate. Each reading's `kind` says
+   * what it measured and fixes the unit; blood glucose keeps the unit its writer chose.
+   */
+  readings(range: TimeRange): Promise<readonly BodyReading[]>;
   logHeartRate(entries: readonly HeartRateEntry[]): Promise<readonly string[]>;
   log(entries: readonly BodyEntry[]): Promise<readonly string[]>;
   delete(id: string): Promise<void>;
@@ -120,6 +143,14 @@ export interface BodyMetrics extends Changes {
 
 export interface DailyMetrics extends Changes {
   steps(range: TimeRange): Promise<readonly StepCount[]>;
+  /**
+   * The store's own total for each whole local day the range touches: distance, active and basal
+   * energy, flights climbed and, on iOS, exercise minutes. A day with nothing recorded has no total
+   * rather than a zero. Steps are `steps`, which keeps writers apart.
+   */
+  totals(range: TimeRange): Promise<readonly DayTotal[]>;
+  /** The active energy, basal energy (iOS), distance and floors records the totals are made of. */
+  intraday(range: TimeRange): Promise<readonly IntradaySample[]>;
   log(entries: readonly StepEntry[]): Promise<readonly string[]>;
   delete(id: string): Promise<void>;
 }
@@ -132,16 +163,51 @@ export interface SleepMetrics extends Changes {
 
 export interface ActivityMetrics extends Changes {
   workouts(range: TimeRange): Promise<readonly Workout[]>;
+  /** The GPS tracks of the workouts in the range, each naming its workout by `workoutId`. */
+  routes(range: TimeRange): Promise<readonly WorkoutRoute[]>;
+  /**
+   * Speed, power and cycling cadence readings in the range. iOS names each one's workout; Health
+   * Connect stores them free-standing, so on Android `workoutId` is absent and `start` equals `end`.
+   */
+  intensity(range: TimeRange): Promise<readonly WorkoutIntensitySample[]>;
   log(entries: readonly WorkoutEntry[]): Promise<readonly string[]>;
   delete(id: string): Promise<void>;
 }
 
-/** Write-only on both platforms. */
 export interface NutritionMetrics {
+  /**
+   * One quantity per nutrient a meal recorded in the range, not grouped into meals. Quantities of
+   * one meal share `foodCorrelationId`. Water is not among them. Each `value` is in its nutrient's
+   * fixed unit: kcal for `energyConsumed`, grams for the macronutrients, milligrams for the rest.
+   */
+  quantities(range: TimeRange): Promise<readonly DietaryQuantity[]>;
+  /** Water drunk in the range, one sample per drink, in millilitres. */
+  hydration(range: TimeRange): Promise<readonly HydrationSample[]>;
   log(entries: readonly NutritionEntry[]): Promise<readonly string[]>;
   delete(id: string): Promise<void>;
 }
 
+/** Read-only on both platforms: neither SDK has a write route for menstruation. */
+export interface MenstruationMetrics {
+  /**
+   * Logged flow days overlapping the range, one per day, each bounded by that day's local
+   * midnights. A day logged with no flow comes back as `none` rather than being left out.
+   */
+  flow(range: TimeRange): Promise<readonly MenstruationFlowDay[]>;
+  /** Ovulation tests, cervical mucus and intermenstrual bleeding logged in the range. */
+  events(range: TimeRange): Promise<readonly MenstrualEvent[]>;
+}
+
+/** iOS only, and read-only. */
+export interface AthleteMetrics {
+  /**
+   * HealthKit's characteristics as one snapshot. No range, because characteristics have no
+   * history. `undefined` where the store has no notion of them at all; a store that has them and
+   * holds no values answers a profile whose `biologicalSex` is `notSet`.
+   */
+  profile(): Promise<AthleteProfile | undefined>;
+}
+
 /** iOS only. */
 export interface PlannedWorkouts {
   planned(): Promise<readonly PlannedWorkout[]>;
@@ -166,13 +232,21 @@ export class Terra {
   readonly sleep: SleepMetrics;
   readonly activity: ActivityMetrics;
   readonly nutrition: NutritionMetrics;
+  readonly menstruation: MenstruationMetrics;
+  /** `undefined` on Android, which has no characteristics to read. */
+  readonly athlete: AthleteMetrics | undefined;
   /** `undefined` on Android, which has no planned workouts. */
   readonly plannedWorkouts: PlannedWorkouts | undefined;
 
   private readonly ops: GeneratedClient;
   private readonly streams: StreamHub;
-  /** Settles once the token provider, when there is one, can be asked. */
-  private readonly tokensReady: Promise<void>;
+  private readonly tokenProvider: TokenProvider | undefined;
+  private readonly tokenTimeoutMs: number;
+  /**
+   * The provider's registration, in flight or done. `undefined` before it starts and after it failed
+   * or its stream ended, so the next connect that needs it registers again.
+   */
+  private tokenSetup: Promise<void> | undefined;
 
   constructor(native: NativeBridge, platform: Platform, options: TerraOptions = {}) {
     this.platform = platform;
@@ -180,11 +254,11 @@ export class Terra {
     const ops = new GeneratedClient(invoker);
     this.ops = ops;
     this.streams = new StreamHub(native);
-    this.tokensReady = options.tokenProvider === undefined
-      ? Promise.resolve()
-      : this.answerTokens(options.tokenProvider, options.tokenTimeoutMs ?? 30_000);
-    // The runtime can report an unhandled rejection before a later call awaits this promise.
-    this.tokensReady.catch(() => undefined);
+    this.tokenProvider = options.tokenProvider;
+    this.tokenTimeoutMs = options.tokenTimeoutMs ?? 30_000;
+    // Registered now, so the provider is in place before anything asks. A failure here is reported
+    // to the connect that needs the provider, which also tries again.
+    void this.tokensReady();
 
     const on = (op: OpId) => availableOn[op].includes(platform);
     const stream = <S extends StreamId>(id: S) =>
@@ -232,6 +306,8 @@ export class Terra {
 
     this.body = {
       heartRate: async (range) => (await ops.bodyHeartRate({ range })).samples,
+      restingHeartRate: async (range) => (await ops.bodyRestingHeartRate({ range })).samples,
+      readings: async (range) => (await ops.bodyReadings({ range })).samples,
       logHeartRate: async (entries) => (await ops.bodyLogHeartRate({ entries })).ids,
       log: async (entries) => (await ops.bodyLog({ entries })).ids,
       delete: async (id) => {
@@ -242,6 +318,8 @@ export class Terra {
 
     this.daily = {
       steps: async (range) => (await ops.dailySteps({ range })).samples,
+      totals: async (range) => (await ops.dailyTotals({ range })).totals,
+      intraday: async (range) => (await ops.dailyIntraday({ range })).samples,
       log: async (entries) => (await ops.dailyLog({ entries })).ids,
       delete: async (id) => {
         await ops.dailyDelete({ id });
@@ -260,6 +338,8 @@ export class Terra {
 
     this.activity = {
       workouts: async (range) => (await ops.activityWorkouts({ range })).samples,
+      routes: async (range) => (await ops.activityRoutes({ range })).routes,
+      intensity: async (range) => (await ops.activityIntensity({ range })).samples,
       log: async (entries) => (await ops.activityLog({ entries })).ids,
       delete: async (id) => {
         await ops.activityDelete({ id });
@@ -268,12 +348,23 @@ export class Terra {
     };
 
     this.nutrition = {
+      quantities: async (range) => (await ops.nutritionQuantities({ range })).samples,
+      hydration: async (range) => (await ops.nutritionHydration({ range })).samples,
       log: async (entries) => (await ops.nutritionLog({ entries })).ids,
       delete: async (id) => {
         await ops.nutritionDelete({ id });
       },
     };
 
+    this.menstruation = {
+      flow: async (range) => (await ops.menstruationFlow({ range })).samples,
+      events: async (range) => (await ops.menstruationEvents({ range })).samples,
+    };
+
+    this.athlete = on("athlete.profile")
+      ? { profile: async () => (await ops.athleteProfile({})).profile }
+      : undefined;
+
     this.plannedWorkouts = on("plannedWorkouts.planned")
       ? {
           planned: async () => (await ops.plannedWorkoutsPlanned({})).workouts,
@@ -305,7 +396,8 @@ export class Terra {
    * the `tokenProvider` is asked, and only when a new link is actually needed.
    */
   async connect(source: Source, endUser: EndUser, options: { readonly token?: string } = {}): Promise<Connection> {
-    await this.tokensReady;
+    // A connect that carries its token never asks the provider, so it does not wait on it either.
+    if (options.token === undefined) await this.tokensReady();
     return this.ops.clientConnect({ source, endUser, token: options.token });
   }
 
@@ -317,9 +409,35 @@ export class Terra {
     await this.ops.clientDisconnect({ source });
   }
 
-  /** Answers the native broker's token requests with `provider`, for the lifetime of this runtime. */
-  private async answerTokens(provider: TokenProvider, timeoutMs: number): Promise<void> {
-    await this.streams.open("bridge.tokenRequest", ({ requestId }) => {
+  /**
+   * Whether the device can serve `source` at all, and if not, why. Needs no connection and prompts
+   * for nothing, so an app can decide whether to offer the link before `connect`. iOS answers
+   * `available` or `unsupportedDevice`; Android names the reason, such as `providerAppMissing` when
+   * Health Connect needs installing.
+   */
+  async availability(source?: Source): Promise<StoreAvailability> {
+    return (await this.ops.clientAvailability({ source })).availability;
+  }
+
+  /** Settles once the token provider, when there is one, can be asked. */
+  private tokensReady(): Promise<void> {
+    const provider = this.tokenProvider;
+    if (provider === undefined) return Promise.resolve();
+    if (this.tokenSetup !== undefined) return this.tokenSetup;
+    const forget = () => {
+      if (this.tokenSetup === setup) this.tokenSetup = undefined;
+    };
+    const setup = this.answerTokens(provider, this.tokenTimeoutMs, forget);
+    this.tokenSetup = setup;
+    // Handles the failure, so it is never an unhandled rejection, and forgets the setup so the next
+    // connect tries again rather than rethrowing a failure that may have passed.
+    setup.catch(forget);
+    return setup;
+  }
+
+  /** Answers the native broker's token requests with `provider` until the stream ends. */
+  private async answerTokens(provider: TokenProvider, timeoutMs: number, onEnd: () => void): Promise<void> {
+    const id = await this.streams.open("bridge.tokenRequest", ({ requestId }) => {
       void (async () => {
         let token: string;
         try {
@@ -331,8 +449,14 @@ export class Terra {
         }
         await this.ops.tokenResolve({ requestId, token }).catch(() => undefined);
       })();
-    });
-    await this.ops.tokenSetProviderPresent({ present: true, timeoutMs });
+    }, undefined, onEnd);
+    try {
+      await this.ops.tokenSetProviderPresent({ present: true, timeoutMs });
+    } catch (failed) {
+      // A provider the broker was never told about answers nothing, so its stream is let go of.
+      this.streams.close(id);
+      throw failed;
+    }
   }
 }
 
@@ -344,11 +468,15 @@ class StreamHub {
 
   constructor(private readonly native: NativeBridge) {}
 
-  /** Subscribes and answers once the native stream is open. */
+  /**
+   * Subscribes and answers once the native stream is open. `onEnd` runs once the stream ends from the
+   * native side, by error or by completing; not when it is closed from here.
+   */
   async open<S extends StreamId>(
     stream: S,
     listener: StreamListener<StreamElements[S]>,
     onError?: (error: TerraError) => void,
+    onEnd?: () => void,
   ): Promise<string> {
     this.listen();
     this.pending += 1;
@@ -368,9 +496,11 @@ class StreamHub {
         case "error":
           this.ended(id);
           onError?.(new TerraError(delivery.error));
+          onEnd?.();
           return;
         case "complete":
           this.ended(id);
+          onEnd?.();
           return;
       }
     };
@@ -427,7 +557,7 @@ class StreamHub {
     };
   }
 
-  private close(id: string): void {
+  close(id: string): void {
     this.handlers.delete(id);
     this.early.delete(id);
     this.native.unsubscribe(id);

package/src/generated/client.ts

@@ -1,8 +1,8 @@
 // Generated from surface/terra-surface.json by surface/gen. Do not edit by hand.
 // Regenerate with: node surface/gen/src/cli.ts generate
 
-import type { BodyEntryList, BoolResult, BootstrapState, CategoryRequest, ConnectRequest, Connection, ConnectionList, DiagnosticsState, Empty, HealthAccess, HeartRateEntryList, HeartRateList, LastDeliveryResult, MarkCompleteRequest, NutritionEntryList, PermissionGrant, PermissionRequest, PlannedWorkoutList, RangeRequest, RecordIdList, RecordIdRequest, SleepEntryList, SleepSegmentList, SourceRequest, StatusResult, StatusesResult, StepCountList, StepEntryList, SupportReport, TokenProviderRequest, TokenRejectRequest, TokenResolveRequest, WorkoutEntryList, WorkoutList, WorkoutScheduling } from "./types";
-import { encodeBodyEntryList, encodeCategoryRequest, encodeConnectRequest, encodeEmpty, encodeHeartRateEntryList, encodeMarkCompleteRequest, encodeNutritionEntryList, encodePermissionRequest, encodeRangeRequest, encodeRecordIdRequest, encodeSleepEntryList, encodeSourceRequest, encodeStepEntryList, encodeTokenProviderRequest, encodeTokenRejectRequest, encodeTokenResolveRequest, encodeWorkoutEntryList, decodeBoolResult, decodeBootstrapState, decodeConnection, decodeConnectionList, decodeDiagnosticsState, decodeEmpty, decodeHealthAccess, decodeHeartRateList, decodeLastDeliveryResult, decodePermissionGrant, decodePlannedWorkoutList, decodeRecordIdList, decodeSleepSegmentList, decodeStatusResult, decodeStatusesResult, decodeStepCountList, decodeSupportReport, decodeWorkoutList, decodeWorkoutScheduling } from "./codecs";
+import type { AthleteProfileResult, AvailabilityResult, BodyEntryList, BodyReadingList, BoolResult, BootstrapState, CategoryRequest, ConnectRequest, Connection, ConnectionList, DayTotalList, DiagnosticsState, DietaryQuantityList, Empty, HealthAccess, HeartRateEntryList, HeartRateList, HydrationList, IntradaySampleList, LastDeliveryResult, MarkCompleteRequest, MenstrualEventList, MenstruationFlowDayList, NutritionEntryList, PermissionGrant, PermissionRequest, PlannedWorkoutList, RangeRequest, RecordIdList, RecordIdRequest, RestingHeartRateList, SleepEntryList, SleepSegmentList, SourceRequest, StatusResult, StatusesResult, StepCountList, StepEntryList, SupportReport, TokenProviderRequest, TokenRejectRequest, TokenResolveRequest, WorkoutEntryList, WorkoutIntensityList, WorkoutList, WorkoutRouteList, WorkoutScheduling } from "./types";
+import { encodeBodyEntryList, encodeCategoryRequest, encodeConnectRequest, encodeEmpty, encodeHeartRateEntryList, encodeMarkCompleteRequest, encodeNutritionEntryList, encodePermissionRequest, encodeRangeRequest, encodeRecordIdRequest, encodeSleepEntryList, encodeSourceRequest, encodeStepEntryList, encodeTokenProviderRequest, encodeTokenRejectRequest, encodeTokenResolveRequest, encodeWorkoutEntryList, decodeAthleteProfileResult, decodeAvailabilityResult, decodeBodyReadingList, decodeBoolResult, decodeBootstrapState, decodeConnection, decodeConnectionList, decodeDayTotalList, decodeDiagnosticsState, decodeDietaryQuantityList, decodeEmpty, decodeHealthAccess, decodeHeartRateList, decodeHydrationList, decodeIntradaySampleList, decodeLastDeliveryResult, decodeMenstrualEventList, decodeMenstruationFlowDayList, decodePermissionGrant, decodePlannedWorkoutList, decodeRecordIdList, decodeRestingHeartRateList, decodeSleepSegmentList, decodeStatusResult, decodeStatusesResult, decodeStepCountList, decodeSupportReport, decodeWorkoutIntensityList, decodeWorkoutList, decodeWorkoutRouteList, decodeWorkoutScheduling } from "./codecs";
 import type { OpId } from "./ops";
 import { TerraError } from "../TerraError";
 
@@ -60,6 +60,11 @@ export class GeneratedClient {
     return this.call("client.connections", () => encodeEmpty(request), (raw) => decodeConnectionList(raw, "ConnectionList"));
   }
 
+  /** Whether the device can serve the source at all. Needs no connection and prompts for nothing. */
+  async clientAvailability(request: SourceRequest): Promise<AvailabilityResult> {
+    return this.call("client.availability", () => encodeSourceRequest(request), (raw) => decodeAvailabilityResult(raw, "AvailabilityResult"));
+  }
+
   async clientDisconnect(request: SourceRequest): Promise<Empty> {
     return this.call("client.disconnect", () => encodeSourceRequest(request), (raw) => decodeEmpty(raw, "Empty"));
   }
@@ -148,6 +153,18 @@ export class GeneratedClient {
     return this.call("body.heartRate", () => encodeRangeRequest(request), (raw) => decodeHeartRateList(raw, "HeartRateList"));
   }
 
+  /**
+   * The store's own daily figures. Health Connect grants them under daily, so Android answers
+   * authorization_not_determined where only body was asked for.
+   */
+  async bodyRestingHeartRate(request: RangeRequest): Promise<RestingHeartRateList> {
+    return this.call("body.restingHeartRate", () => encodeRangeRequest(request), (raw) => decodeRestingHeartRateList(raw, "RestingHeartRateList"));
+  }
+
+  async bodyReadings(request: RangeRequest): Promise<BodyReadingList> {
+    return this.call("body.readings", () => encodeRangeRequest(request), (raw) => decodeBodyReadingList(raw, "BodyReadingList"));
+  }
+
   /** Its own op rather than an overload: Swift overloads log by element type and JS cannot. */
   async bodyLogHeartRate(request: HeartRateEntryList): Promise<RecordIdList> {
     return this.call("body.logHeartRate", () => encodeHeartRateEntryList(request), (raw) => decodeRecordIdList(raw, "RecordIdList"));
@@ -165,6 +182,19 @@ export class GeneratedClient {
     return this.call("daily.steps", () => encodeRangeRequest(request), (raw) => decodeStepCountList(raw, "StepCountList"));
   }
 
+  /**
+   * One total per metric per whole local day the range touches. A day with nothing recorded has
+   * no total, not a zero.
+   */
+  async dailyTotals(request: RangeRequest): Promise<DayTotalList> {
+    return this.call("daily.totals", () => encodeRangeRequest(request), (raw) => decodeDayTotalList(raw, "DayTotalList"));
+  }
+
+  /** The active energy, basal energy, distance and floors records the totals are made of. */
+  async dailyIntraday(request: RangeRequest): Promise<IntradaySampleList> {
+    return this.call("daily.intraday", () => encodeRangeRequest(request), (raw) => decodeIntradaySampleList(raw, "IntradaySampleList"));
+  }
+
   async dailyLog(request: StepEntryList): Promise<RecordIdList> {
     return this.call("daily.log", () => encodeStepEntryList(request), (raw) => decodeRecordIdList(raw, "RecordIdList"));
   }
@@ -189,6 +219,16 @@ export class GeneratedClient {
     return this.call("activity.workouts", () => encodeRangeRequest(request), (raw) => decodeWorkoutList(raw, "WorkoutList"));
   }
 
+  /** The GPS tracks of the workouts in the range, each naming its workout. */
+  async activityRoutes(request: RangeRequest): Promise<WorkoutRouteList> {
+    return this.call("activity.routes", () => encodeRangeRequest(request), (raw) => decodeWorkoutRouteList(raw, "WorkoutRouteList"));
+  }
+
+  /** Speed, power and cycling cadence readings in the range. */
+  async activityIntensity(request: RangeRequest): Promise<WorkoutIntensityList> {
+    return this.call("activity.intensity", () => encodeRangeRequest(request), (raw) => decodeWorkoutIntensityList(raw, "WorkoutIntensityList"));
+  }
+
   async activityLog(request: WorkoutEntryList): Promise<RecordIdList> {
     return this.call("activity.log", () => encodeWorkoutEntryList(request), (raw) => decodeRecordIdList(raw, "RecordIdList"));
   }
@@ -197,6 +237,11 @@ export class GeneratedClient {
     return this.call("activity.delete", () => encodeRecordIdRequest(request), (raw) => decodeEmpty(raw, "Empty"));
   }
 
+  /** One quantity per nutrient a meal recorded, not grouped into meals. Water is not among them. */
+  async nutritionQuantities(request: RangeRequest): Promise<DietaryQuantityList> {
+    return this.call("nutrition.quantities", () => encodeRangeRequest(request), (raw) => decodeDietaryQuantityList(raw, "DietaryQuantityList"));
+  }
+
   async nutritionLog(request: NutritionEntryList): Promise<RecordIdList> {
     return this.call("nutrition.log", () => encodeNutritionEntryList(request), (raw) => decodeRecordIdList(raw, "RecordIdList"));
   }
@@ -205,6 +250,33 @@ export class GeneratedClient {
     return this.call("nutrition.delete", () => encodeRecordIdRequest(request), (raw) => decodeEmpty(raw, "Empty"));
   }
 
+  /** Water drunk in the range, one sample per drink. */
+  async nutritionHydration(request: RangeRequest): Promise<HydrationList> {
+    return this.call("nutrition.hydration", () => encodeRangeRequest(request), (raw) => decodeHydrationList(raw, "HydrationList"));
+  }
+
+  /**
+   * Logged flow days overlapping the range, one per day. A day logged with no flow is noFlow,
+   * not left out.
+   */
+  async menstruationFlow(request: RangeRequest): Promise<MenstruationFlowDayList> {
+    return this.call("menstruation.flow", () => encodeRangeRequest(request), (raw) => decodeMenstruationFlowDayList(raw, "MenstruationFlowDayList"));
+  }
+
+  /** Ovulation tests, cervical mucus and intermenstrual bleeding logged in the range. */
+  async menstruationEvents(request: RangeRequest): Promise<MenstrualEventList> {
+    return this.call("menstruation.events", () => encodeRangeRequest(request), (raw) => decodeMenstrualEventList(raw, "MenstrualEventList"));
+  }
+
+  /**
+   * Characteristics have no history.
+   *
+   * Available on ios only.
+   */
+  async athleteProfile(request: Empty): Promise<AthleteProfileResult> {
+    return this.call("athlete.profile", () => encodeEmpty(request), (raw) => decodeAthleteProfileResult(raw, "AthleteProfileResult"));
+  }
+
   /** Available on ios only. */
   async plannedWorkoutsPlanned(request: Empty): Promise<PlannedWorkoutList> {
     return this.call("plannedWorkouts.planned", () => encodeEmpty(request), (raw) => decodePlannedWorkoutList(raw, "PlannedWorkoutList"));