@tryterra/react-native 0.0.0-stage → 2.2.1

package/src/Terra.ts

@@ -0,0 +1,592 @@
+/**
+ * The client an app holds: namespaces over the generated ops, the token provider, and the streams.
+ *
+ * Hand-written, deliberately thin. Every method is one generated `GeneratedClient` call; what lives
+ * here is only what the generated layer cannot know - which runtime the app is on, how a JS
+ * function answers a native token request, and how one native event emitter fans out to many
+ * listeners. `facade.test.ts` drives every method and fails when an op in the schema has no member
+ * here, so this file cannot quietly fall behind the surface the way the 1.x wrapper did.
+ */
+
+import { TerraError } from "./TerraError";
+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,
+  Source,
+  StepCount,
+  StepEntry,
+  SupportReport,
+  TerraEvent,
+  TimeRange,
+  Workout,
+  WorkoutEntry,
+  WorkoutIntensitySample,
+  WorkoutRoute,
+  WorkoutScope,
+} from "./generated/types";
+
+/** What the facade needs from the native module. `NativeTerraBridge` satisfies it; so does a double. */
+export interface NativeBridge {
+  invoke(op: string, payload: string): Promise<string>;
+  subscribe(stream: string, params: string): Promise<string>;
+  unsubscribe(subscriptionId: string): void;
+  onMessage(listener: (event: { subscriptionId: string; message: string }) => void): { remove(): void };
+}
+
+export type Platform = "ios" | "android";
+
+/** Asked for a one-shot link token, and only while `connect` establishes a new link. */
+export type TokenProvider = () => Promise<string>;
+
+export interface TerraOptions {
+  /**
+   * Called only when `connect` has to make a new link and was given no token. A restored link
+   * never asks, and neither does a background wake: uploads are signed by the device key.
+   */
+  readonly tokenProvider?: TokenProvider;
+  /** How long the native side waits for `tokenProvider`. 30 seconds by default. */
+  readonly tokenTimeoutMs?: number;
+}
+
+export type Unsubscribe = () => void;
+
+/** A stream's listener. `onError` receives the error a stream ended with; a stream that completes ends quietly. */
+export interface StreamListener<T> {
+  (element: T): void;
+}
+
+export interface Permissions {
+  /**
+   * One sheet covering both directions and everything asked before. Android answers what this call
+   * obtained; HealthKit will not report read grants, so iOS answers `undefined`.
+   *
+   * `source` defaults to `health`. `samsungHealth` presents Samsung Health's own consent popup and
+   * is Android only.
+   */
+  request(access: Partial<HealthAccess>, source?: Source): Promise<HealthAccess | undefined>;
+  status(category: DataCategory, source?: Source): Promise<PermissionStatus>;
+  writeStatus(category: DataCategory, source?: Source): Promise<PermissionStatus>;
+  requested(source?: Source): Promise<HealthAccess>;
+  /** Android only. */
+  readonly statuses?: (source?: Source) => Promise<Partial<Record<DataCategory, PermissionStatus>>>;
+  /** Android only. */
+  readonly backgroundReadStatus?: (source?: Source) => Promise<PermissionStatus>;
+  /** Android only. */
+  readonly historyReadStatus?: (source?: Source) => Promise<PermissionStatus>;
+}
+
+export interface Diagnostics {
+  state(source?: Source): Promise<DiagnosticsState>;
+  lastDelivery(source?: Source): Promise<Date | undefined>;
+  report(source?: Source): Promise<SupportReport>;
+  send(source?: Source): Promise<void>;
+  /** Everything the SDK does, as it happens. Never carries a health value. */
+  events(listener: StreamListener<TerraEvent>, onError?: (error: TerraError) => void): Unsubscribe;
+}
+
+export interface Background {
+  /** Whether the native bootstrap registered background sync at launch. False is a host setup bug. */
+  isRegistered(): Promise<boolean>;
+  /** Android only: drops the schedule. */
+  readonly cancel?: () => Promise<boolean>;
+}
+
+interface Changes {
+  /** Which days changed in the health store. Re-read through this namespace's accessor. */
+  changes(listener: StreamListener<HealthChange>, onError?: (error: TerraError) => void): Unsubscribe;
+}
+
+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>;
+}
+
+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>;
+}
+
+export interface SleepMetrics extends Changes {
+  segments(range: TimeRange): Promise<readonly SleepSegment[]>;
+  log(entries: readonly SleepEntry[]): Promise<readonly string[]>;
+  delete(id: string): Promise<void>;
+}
+
+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>;
+}
+
+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[]>;
+  markComplete(id: string, at?: Date): Promise<void>;
+  delete(id: string): Promise<void>;
+  /** Whether plans can be put on the person's Apple Watch. Never prompts. */
+  schedulingStatus(): Promise<WorkoutSchedulingStatus>;
+  /**
+   * Shows WorkoutKit's sheet if the person has not been asked. Once authorized, every sync run
+   * keeps the Watch schedule in step with Terra; nothing else needs calling.
+   */
+  requestScheduling(): Promise<WorkoutSchedulingStatus>;
+}
+
+export class Terra {
+  readonly platform: Platform;
+  readonly permissions: Permissions;
+  readonly diagnostics: Diagnostics;
+  readonly background: Background;
+  readonly body: BodyMetrics;
+  readonly daily: DailyMetrics;
+  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;
+  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;
+    const invoker: Invoker = native;
+    const ops = new GeneratedClient(invoker);
+    this.ops = ops;
+    this.streams = new StreamHub(native);
+    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) =>
+      (listener: StreamListener<StreamElements[S]>, onError?: (error: TerraError) => void) =>
+        this.streams.subscribe(id, listener, onError);
+
+    this.permissions = {
+      request: async (access, source) => {
+        const grant = await ops.permissionsRequest({
+          read: access.read ?? [],
+          write: access.write ?? [],
+          workouts: access.workouts ?? ([] as readonly WorkoutScope[]),
+          source,
+        });
+        return grant.granted;
+      },
+      status: async (category, source) => (await ops.permissionsStatus({ category, source })).status,
+      writeStatus: async (category, source) => (await ops.permissionsWriteStatus({ category, source })).status,
+      requested: (source) => ops.permissionsRequested({ source }),
+      ...(on("permissions.statuses") && {
+        statuses: async (source?: Source) => (await ops.permissionsStatuses({ source })).statuses,
+      }),
+      ...(on("permissions.backgroundReadStatus") && {
+        backgroundReadStatus: async (source?: Source) => (await ops.permissionsBackgroundReadStatus({ source })).status,
+      }),
+      ...(on("permissions.historyReadStatus") && {
+        historyReadStatus: async (source?: Source) => (await ops.permissionsHistoryReadStatus({ source })).status,
+      }),
+    };
+
+    this.diagnostics = {
+      state: (source) => ops.diagnosticsState({ source }),
+      lastDelivery: async (source) => (await ops.diagnosticsLastDelivery({ source })).at,
+      report: (source) => ops.diagnosticsReport({ source }),
+      send: async (source) => {
+        await ops.diagnosticsSend({ source });
+      },
+      events: stream("diagnostics.events"),
+    };
+
+    this.background = {
+      isRegistered: async () => (await ops.backgroundIsRegistered({})).value,
+      ...(on("background.cancel") && { cancel: async () => (await ops.backgroundCancel({})).value }),
+    };
+
+    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) => {
+        await ops.bodyDelete({ id });
+      },
+      changes: stream("body.changes"),
+    };
+
+    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 });
+      },
+      changes: stream("daily.changes"),
+    };
+
+    this.sleep = {
+      segments: async (range) => (await ops.sleepSegments({ range })).samples,
+      log: async (entries) => (await ops.sleepLog({ entries })).ids,
+      delete: async (id) => {
+        await ops.sleepDelete({ id });
+      },
+      changes: stream("sleep.changes"),
+    };
+
+    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 });
+      },
+      changes: stream("activity.changes"),
+    };
+
+    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,
+          markComplete: async (id, at) => {
+            await ops.plannedWorkoutsMarkComplete({ id, at });
+          },
+          delete: async (id) => {
+            await ops.plannedWorkoutsDelete({ id });
+          },
+          schedulingStatus: async () => (await ops.plannedWorkoutsSchedulingStatus({})).status,
+          requestScheduling: async () => (await ops.plannedWorkoutsRequestScheduling({})).status,
+        }
+      : undefined;
+  }
+
+  /**
+   * The native client this runtime is attached to. Rejects with `bridge.not_bootstrapped`, carrying
+   * the exact line to add in `details.line`, when the app's native launch never set Terra up.
+   */
+  attach(): Promise<BootstrapState> {
+    return this.ops.clientAttach({});
+  }
+
+  /**
+   * Links `source` for the person `endUser` names, or restores the link already made for them.
+   *
+   * Every connect names its person: a second account on the same phone must not be handed the
+   * first one's link. With `token` the grant in hand is spent (a QR code, a deep link); without it
+   * 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> {
+    // 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 });
+  }
+
+  async connections(): Promise<readonly Connection[]> {
+    return (await this.ops.clientConnections({})).connections;
+  }
+
+  async disconnect(source?: Source): Promise<void> {
+    await this.ops.clientDisconnect({ source });
+  }
+
+  /**
+   * 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 {
+          token = await provider();
+        } catch (failed) {
+          const message = failed instanceof Error ? failed.message : String(failed);
+          await this.ops.tokenReject({ requestId, message }).catch(() => undefined);
+          return;
+        }
+        await this.ops.tokenResolve({ requestId, token }).catch(() => undefined);
+      })();
+    }, 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;
+    }
+  }
+}
+
+class StreamHub {
+  private readonly handlers = new Map<string, (message: string) => void>();
+  private readonly early = new Map<string, string[]>();
+  private pending = 0;
+  private listening: { remove(): void } | undefined;
+
+  constructor(private readonly native: NativeBridge) {}
+
+  /**
+   * 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;
+    let id: string;
+    try {
+      id = await this.native.subscribe(stream, "{}");
+    } catch (thrown) {
+      this.settled();
+      throw TerraError.from(thrown);
+    }
+    const handle = (message: string) => {
+      const delivery = decodeStreamDelivery(stream, JSON.parse(message));
+      switch (delivery.kind) {
+        case "data":
+          listener(delivery.element);
+          return;
+        case "error":
+          this.ended(id);
+          onError?.(new TerraError(delivery.error));
+          onEnd?.();
+          return;
+        case "complete":
+          this.ended(id);
+          onEnd?.();
+          return;
+      }
+    };
+    this.handlers.set(id, handle);
+    const held = this.early.get(id);
+    this.early.delete(id);
+    this.settled();
+    held?.forEach(handle);
+    return id;
+  }
+
+  private settled(): void {
+    this.pending -= 1;
+    if (this.pending === 0) this.early.clear();
+    this.releaseIfIdle();
+  }
+
+  private ended(id: string): void {
+    this.handlers.delete(id);
+    this.releaseIfIdle();
+  }
+
+  private releaseIfIdle(): void {
+    if (this.handlers.size > 0 || this.pending > 0) return;
+    this.listening?.remove();
+    this.listening = undefined;
+  }
+
+  /** Subscribes without waiting; the returned function cancels whether or not the stream has opened yet. */
+  subscribe<S extends StreamId>(
+    stream: S,
+    listener: StreamListener<StreamElements[S]>,
+    onError?: (error: TerraError) => void,
+  ): Unsubscribe {
+    let cancelled = false;
+    let opened: string | undefined;
+    this.open(stream, (element) => {
+      if (!cancelled) listener(element);
+    }, (error) => {
+      if (!cancelled) onError?.(error);
+    }).then(
+      (id) => {
+        opened = id;
+        if (cancelled) this.close(id);
+      },
+      (error: TerraError) => {
+        if (!cancelled) onError?.(error);
+      },
+    );
+    return () => {
+      if (cancelled) return;
+      cancelled = true;
+      if (opened !== undefined) this.close(opened);
+    };
+  }
+
+  close(id: string): void {
+    this.handlers.delete(id);
+    this.early.delete(id);
+    this.native.unsubscribe(id);
+    this.releaseIfIdle();
+  }
+
+  private listen(): void {
+    if (this.listening !== undefined) return;
+    this.listening = this.native.onMessage(({ subscriptionId, message }) => {
+      const handler = this.handlers.get(subscriptionId);
+      if (handler !== undefined) {
+        handler(message);
+        return;
+      }
+      if (this.pending === 0) return;
+      const held = this.early.get(subscriptionId) ?? [];
+      if (held.length < EARLY_LIMIT || isTerminal(message)) held.push(message);
+      this.early.set(subscriptionId, held);
+    });
+  }
+}
+
+const EARLY_LIMIT = 64;
+
+function isTerminal(message: string): boolean {
+  try {
+    const kind = (JSON.parse(message) as { kind?: unknown }).kind;
+    return kind === "error" || kind === "complete";
+  } catch {
+    return false;
+  }
+}