@tryterra/react-native 0.0.0-stage → 2.2.1

package/src/TerraError.ts

@@ -0,0 +1,116 @@
+/**
+ * The error every rejected op carries, hydrated from the bridge's JSON.
+ *
+ * Hand-written, and one of only two files here that are: the shape is fixed, while the *vocabulary*
+ * it carries is generated. `code` is a `TerraErrorCode`, so a code renamed natively stops a
+ * `switch` over it compiling rather than silently never matching.
+ */
+
+import { decodeTerraErrorPayload } from "./generated/codecs";
+import { retryableByCode, type TerraErrorCode } from "./generated/errors";
+import type { Source, TerraErrorPayload } from "./generated/types";
+
+/**
+ * The JSON a native rejection carries in its userInfo / message: the schema's own payload, except
+ * that `retryable` may be left out, in which case the per-code table answers.
+ */
+export type TerraErrorJSON = Omit<TerraErrorPayload, "retryable"> & { readonly retryable?: boolean };
+
+export class TerraError extends Error {
+  readonly code: TerraErrorCode;
+  /**
+   * Whether the same call could succeed if repeated.
+   *
+   * Read from the rejection rather than from `retryableByCode`, because one code decides per
+   * instance: `network.server_error` is retryable for a 503 and not for a 400. The table is the
+   * fallback for a rejection that did not carry the flag at all.
+   */
+  readonly retryable: boolean;
+  readonly source: Source | undefined;
+  readonly details: Record<string, unknown> | undefined;
+
+  constructor(json: TerraErrorJSON, options?: { readonly cause?: unknown }) {
+    super(json.message, options);
+    this.name = "TerraError";
+    const known = isKnownCode(json.code);
+    this.code = known ? json.code : "platform";
+    this.retryable = known ? (json.retryable ?? fallbackRetryable(json.code)) : false;
+    this.source = json.source;
+    this.details = known ? json.details : { ...json.details, unrecognisedCode: json.code };
+  }
+
+  /**
+   * Rebuilds a `TerraError` from whatever the native module rejected with.
+   *
+   * Anything unrecognisable becomes `platform` rather than being rethrown as-is: a caller that has
+   * to handle both `TerraError` and an arbitrary `Error` ends up handling neither properly, and the
+   * original is kept as `cause` and its text in `message`.
+   */
+  static from(thrown: unknown): TerraError {
+    if (thrown instanceof TerraError) return thrown;
+    const json = readJSON(thrown);
+    if (json !== undefined) return new TerraError(json, { cause: thrown });
+    return new TerraError({ code: "platform", retryable: false, message: messageOf(thrown) }, { cause: thrown });
+  }
+
+  /** A response the bridge resolved that this build cannot read: the native side and JS disagree. */
+  static invalidPayload(op: string, thrown: unknown): TerraError {
+    return new TerraError(
+      { code: "bridge.invalid_payload", message: `${op}: ${messageOf(thrown)}`, details: { op } },
+      { cause: thrown },
+    );
+  }
+}
+
+function isKnownCode(code: string): code is TerraErrorCode {
+  return Object.prototype.hasOwnProperty.call(retryableByCode, code);
+}
+
+function messageOf(thrown: unknown): string {
+  if (thrown instanceof Error) return thrown.message;
+  if (isObject(thrown) && typeof thrown.message === "string") return thrown.message;
+  return String(thrown);
+}
+
+function fallbackRetryable(code: TerraErrorCode): boolean {
+  return retryableByCode[code] === true;
+}
+
+/** A JSON string preserves payload types across `NSError` and `WritableMap`, unlike a nested map. */
+function readJSON(thrown: unknown): TerraErrorJSON | undefined {
+  if (typeof thrown !== "object" || thrown === null) return undefined;
+  const candidate = thrown as Record<string, unknown>;
+  const userInfo = candidate.userInfo;
+  const encoded = isObject(userInfo) ? userInfo.payload : undefined;
+  return (typeof encoded === "string" ? decode(parse(encoded)) : undefined) ?? decode(userInfo) ?? decode(candidate);
+}
+
+function parse(encoded: string): unknown {
+  try {
+    return JSON.parse(encoded);
+  } catch {
+    return undefined;
+  }
+}
+
+/** The generated decoder does the checking: a string code, a boolean flag, a known source. */
+function decode(raw: unknown): TerraErrorJSON | undefined {
+  if (!isObject(raw) || typeof raw.code !== "string") return undefined;
+  try {
+    // Read field by field: an Error's `message` is not enumerable, so spreading one drops it.
+    const { retryable, ...rest } = decodeTerraErrorPayload({
+      code: raw.code,
+      retryable: raw.retryable ?? false,
+      message: raw.message,
+      source: raw.source,
+      details: raw.details,
+    });
+    return raw.retryable === undefined ? rest : { ...rest, retryable };
+  } catch {
+    return undefined;
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/createTerra.ts

@@ -0,0 +1,18 @@
+import { Platform } from "react-native";
+
+import NativeTerraBridge from "./NativeTerraBridge";
+import { Terra, type TerraOptions } from "./Terra";
+
+/**
+ * Attaches this JavaScript runtime to the native client the app built at launch.
+ *
+ * Call it once, at module scope. The native client outlives a reload, so a reload attaches again
+ * rather than building a second client.
+ */
+export function createTerra(options: TerraOptions = {}): Terra {
+  const platform = Platform.OS;
+  if (platform !== "ios" && platform !== "android") {
+    throw new Error(`@tryterra/react-native runs on iOS and Android, not ${platform}`);
+  }
+  return new Terra(NativeTerraBridge, platform, options);
+}

package/src/generated/client.ts

@@ -0,0 +1,315 @@
+// 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 { 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";
+
+/** What the facade needs from the native module. The TurboModule spec satisfies it; so does a test double. */
+export interface Invoker {
+  invoke(op: OpId, payload: string): Promise<string>;
+}
+
+/**
+ * One generated method per op, and nothing else.
+ *
+ * The `op` string exists only between this file and the generated native dispatch, and a vector
+ * in `vectors/bridge` pins the two to each other. A caller never sees it.
+ */
+export class GeneratedClient {
+  protected readonly invoker: Invoker;
+
+  constructor(invoker: Invoker) {
+    this.invoker = invoker;
+  }
+
+  private async call<T>(op: OpId, encode: () => Record<string, unknown>, decode: (raw: unknown) => T): Promise<T> {
+    let payload: string;
+    try {
+      payload = JSON.stringify(encode());
+    } catch (thrown) {
+      throw TerraError.invalidPayload(op, thrown);
+    }
+    let text: string;
+    try {
+      text = await this.invoker.invoke(op, payload);
+    } catch (thrown) {
+      throw TerraError.from(thrown);
+    }
+    try {
+      return decode(JSON.parse(text));
+    } catch (thrown) {
+      throw TerraError.invalidPayload(op, thrown);
+    }
+  }
+
+  /**
+   * Reports the native client the JS side is attaching to. Idempotent, and safe to call after a
+   * JS reload.
+   */
+  async clientAttach(request: Empty): Promise<BootstrapState> {
+    return this.call("client.attach", () => encodeEmpty(request), (raw) => decodeBootstrapState(raw, "BootstrapState"));
+  }
+
+  async clientConnect(request: ConnectRequest): Promise<Connection> {
+    return this.call("client.connect", () => encodeConnectRequest(request), (raw) => decodeConnection(raw, "Connection"));
+  }
+
+  async clientConnections(request: Empty): Promise<ConnectionList> {
+    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"));
+  }
+
+  /**
+   * Tells the broker whether JS can answer at all. Without it a link asks a provider that is not
+   * there and waits out the timeout.
+   */
+  async tokenSetProviderPresent(request: TokenProviderRequest): Promise<Empty> {
+    return this.call("token.setProviderPresent", () => encodeTokenProviderRequest(request), (raw) => decodeEmpty(raw, "Empty"));
+  }
+
+  /**
+   * An unknown or already-settled requestId is ignored rather than rejected, so a reload cannot
+   * fail a link that has already moved on.
+   */
+  async tokenResolve(request: TokenResolveRequest): Promise<Empty> {
+    return this.call("token.resolve", () => encodeTokenResolveRequest(request), (raw) => decodeEmpty(raw, "Empty"));
+  }
+
+  async tokenReject(request: TokenRejectRequest): Promise<Empty> {
+    return this.call("token.reject", () => encodeTokenRejectRequest(request), (raw) => decodeEmpty(raw, "Empty"));
+  }
+
+  async permissionsRequest(request: PermissionRequest): Promise<PermissionGrant> {
+    return this.call("permissions.request", () => encodePermissionRequest(request), (raw) => decodePermissionGrant(raw, "PermissionGrant"));
+  }
+
+  async permissionsStatus(request: CategoryRequest): Promise<StatusResult> {
+    return this.call("permissions.status", () => encodeCategoryRequest(request), (raw) => decodeStatusResult(raw, "StatusResult"));
+  }
+
+  async permissionsWriteStatus(request: CategoryRequest): Promise<StatusResult> {
+    return this.call("permissions.writeStatus", () => encodeCategoryRequest(request), (raw) => decodeStatusResult(raw, "StatusResult"));
+  }
+
+  async permissionsRequested(request: SourceRequest): Promise<HealthAccess> {
+    return this.call("permissions.requested", () => encodeSourceRequest(request), (raw) => decodeHealthAccess(raw, "HealthAccess"));
+  }
+
+  /** Available on android only. */
+  async permissionsStatuses(request: SourceRequest): Promise<StatusesResult> {
+    return this.call("permissions.statuses", () => encodeSourceRequest(request), (raw) => decodeStatusesResult(raw, "StatusesResult"));
+  }
+
+  /** Available on android only. */
+  async permissionsBackgroundReadStatus(request: SourceRequest): Promise<StatusResult> {
+    return this.call("permissions.backgroundReadStatus", () => encodeSourceRequest(request), (raw) => decodeStatusResult(raw, "StatusResult"));
+  }
+
+  /** Available on android only. */
+  async permissionsHistoryReadStatus(request: SourceRequest): Promise<StatusResult> {
+    return this.call("permissions.historyReadStatus", () => encodeSourceRequest(request), (raw) => decodeStatusResult(raw, "StatusResult"));
+  }
+
+  async diagnosticsState(request: SourceRequest): Promise<DiagnosticsState> {
+    return this.call("diagnostics.state", () => encodeSourceRequest(request), (raw) => decodeDiagnosticsState(raw, "DiagnosticsState"));
+  }
+
+  async diagnosticsLastDelivery(request: SourceRequest): Promise<LastDeliveryResult> {
+    return this.call("diagnostics.lastDelivery", () => encodeSourceRequest(request), (raw) => decodeLastDeliveryResult(raw, "LastDeliveryResult"));
+  }
+
+  async diagnosticsReport(request: SourceRequest): Promise<SupportReport> {
+    return this.call("diagnostics.report", () => encodeSourceRequest(request), (raw) => decodeSupportReport(raw, "SupportReport"));
+  }
+
+  async diagnosticsSend(request: SourceRequest): Promise<Empty> {
+    return this.call("diagnostics.send", () => encodeSourceRequest(request), (raw) => decodeEmpty(raw, "Empty"));
+  }
+
+  /**
+   * False means bootstrap did not run. The SDK reports the same thing independently as
+   * backgroundRefreshUnscheduled.
+   */
+  async backgroundIsRegistered(request: Empty): Promise<BoolResult> {
+    return this.call("background.isRegistered", () => encodeEmpty(request), (raw) => decodeBoolResult(raw, "BoolResult"));
+  }
+
+  /** Available on android only. */
+  async backgroundCancel(request: Empty): Promise<BoolResult> {
+    return this.call("background.cancel", () => encodeEmpty(request), (raw) => decodeBoolResult(raw, "BoolResult"));
+  }
+
+  async bodyHeartRate(request: RangeRequest): Promise<HeartRateList> {
+    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"));
+  }
+
+  async bodyLog(request: BodyEntryList): Promise<RecordIdList> {
+    return this.call("body.log", () => encodeBodyEntryList(request), (raw) => decodeRecordIdList(raw, "RecordIdList"));
+  }
+
+  async bodyDelete(request: RecordIdRequest): Promise<Empty> {
+    return this.call("body.delete", () => encodeRecordIdRequest(request), (raw) => decodeEmpty(raw, "Empty"));
+  }
+
+  async dailySteps(request: RangeRequest): Promise<StepCountList> {
+    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"));
+  }
+
+  async dailyDelete(request: RecordIdRequest): Promise<Empty> {
+    return this.call("daily.delete", () => encodeRecordIdRequest(request), (raw) => decodeEmpty(raw, "Empty"));
+  }
+
+  async sleepSegments(request: RangeRequest): Promise<SleepSegmentList> {
+    return this.call("sleep.segments", () => encodeRangeRequest(request), (raw) => decodeSleepSegmentList(raw, "SleepSegmentList"));
+  }
+
+  async sleepLog(request: SleepEntryList): Promise<RecordIdList> {
+    return this.call("sleep.log", () => encodeSleepEntryList(request), (raw) => decodeRecordIdList(raw, "RecordIdList"));
+  }
+
+  async sleepDelete(request: RecordIdRequest): Promise<Empty> {
+    return this.call("sleep.delete", () => encodeRecordIdRequest(request), (raw) => decodeEmpty(raw, "Empty"));
+  }
+
+  async activityWorkouts(request: RangeRequest): Promise<WorkoutList> {
+    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"));
+  }
+
+  async activityDelete(request: RecordIdRequest): Promise<Empty> {
+    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"));
+  }
+
+  async nutritionDelete(request: RecordIdRequest): Promise<Empty> {
+    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"));
+  }
+
+  /** Available on ios only. */
+  async plannedWorkoutsMarkComplete(request: MarkCompleteRequest): Promise<Empty> {
+    return this.call("plannedWorkouts.markComplete", () => encodeMarkCompleteRequest(request), (raw) => decodeEmpty(raw, "Empty"));
+  }
+
+  /** Available on ios only. */
+  async plannedWorkoutsDelete(request: RecordIdRequest): Promise<Empty> {
+    return this.call("plannedWorkouts.delete", () => encodeRecordIdRequest(request), (raw) => decodeEmpty(raw, "Empty"));
+  }
+
+  /**
+   * Never prompts.
+   *
+   * Available on ios only.
+   */
+  async plannedWorkoutsSchedulingStatus(request: Empty): Promise<WorkoutScheduling> {
+    return this.call("plannedWorkouts.schedulingStatus", () => encodeEmpty(request), (raw) => decodeWorkoutScheduling(raw, "WorkoutScheduling"));
+  }
+
+  /**
+   * Shows WorkoutKit's sheet if the person has not been asked, and reconciles straight away once
+   * authorized.
+   *
+   * Available on ios only.
+   */
+  async plannedWorkoutsRequestScheduling(request: Empty): Promise<WorkoutScheduling> {
+    return this.call("plannedWorkouts.requestScheduling", () => encodeEmpty(request), (raw) => decodeWorkoutScheduling(raw, "WorkoutScheduling"));
+  }
+
+}
+