@tryterra/react-native 0.0.0-stage → 2.1.0

package/src/generated/types.ts

@@ -0,0 +1,667 @@
+// Generated from surface/terra-surface.json by surface/gen. Do not edit by hand.
+// Regenerate with: node surface/gen/src/cli.ts generate
+
+/** A health store the SDK can link. One connection per source per device. */
+export type Source =
+  | "health"
+  | "samsungHealth"; // android only
+
+export const SourceValues: readonly Source[] = [
+  "health",
+  "samsungHealth",
+];
+
+/** The unit permissions are asked for and changes are reported against. */
+export type DataCategory =
+  | "activity"
+  | "body"
+  | "daily"
+  | "sleep"
+  | "nutrition";
+
+export const DataCategoryValues: readonly DataCategory[] = [
+  "activity",
+  "body",
+  "daily",
+  "sleep",
+  "nutrition",
+];
+
+export type PermissionStatus =
+  | "granted"
+  | "denied"
+  | "notDetermined"
+  | "notDisclosed"
+  | "unsupported"
+  | "unavailable"; // ios only
+
+export const PermissionStatusValues: readonly PermissionStatus[] = [
+  "granted",
+  "denied",
+  "notDetermined",
+  "notDisclosed",
+  "unsupported",
+  "unavailable",
+];
+
+export type MotionContext =
+  | "unknown"
+  | "sedentary"
+  | "active";
+
+export const MotionContextValues: readonly MotionContext[] = [
+  "unknown",
+  "sedentary",
+  "active",
+];
+
+/**
+ * Why background delivery is restricted. Android discloses which; Apple reports the state
+ * without a reason.
+ *
+ * Available on android only.
+ */
+export type BackgroundRestrictionReason =
+  | "oemRestricted" // android only
+  | "backgroundReadDenied" // android only
+  | "healthConnectFeatureUnavailable" // android only
+  | "storeFeatureUnavailable" // android only
+  | "ticksNotRunning"; // android only
+
+export const BackgroundRestrictionReasonValues: readonly BackgroundRestrictionReason[] = [
+  "oemRestricted",
+  "backgroundReadDenied",
+  "healthConnectFeatureUnavailable",
+  "storeFeatureUnavailable",
+  "ticksNotRunning",
+];
+
+export type DiagnosticsReason =
+  | "uploadFailed"
+  | "backfillAbandoned"
+  | "backgroundObservationUnavailable"
+  | "backgroundRestricted"
+  | "backgroundRefreshUnscheduled"
+  | "quiet"
+  | "requested";
+
+export const DiagnosticsReasonValues: readonly DiagnosticsReason[] = [
+  "uploadFailed",
+  "backfillAbandoned",
+  "backgroundObservationUnavailable",
+  "backgroundRestricted",
+  "backgroundRefreshUnscheduled",
+  "quiet",
+  "requested",
+];
+
+export type DeviceKeyRevokeOutcome =
+  | "revoked"
+  | "alreadyRevoked"
+  | "routeAbsent";
+
+export const DeviceKeyRevokeOutcomeValues: readonly DeviceKeyRevokeOutcome[] = [
+  "revoked",
+  "alreadyRevoked",
+  "routeAbsent",
+];
+
+/**
+ * The redacted error name an event carries. Deliberately not TerraErrorCode: an event names
+ * the failure without the detail bag, because a support report leaves the device.
+ */
+export type FailureCode =
+  | "healthDataUnavailable"
+  | "notConnected"
+  | "tokenUnavailable"
+  | "tokenRejected"
+  | "tokenProviderFailed"
+  | "offline"
+  | "timedOut"
+  | "serverError"
+  | "transport"
+  | "malformedResponse"
+  | "userLimitReached"
+  | "upgradeRequired"
+  | "platform"
+  | "deviceKeyUnavailable"
+  | "signatureRejected"
+  | "linkRevoked"
+  | "linkConflict"
+  | "clockSkewed"
+  | "devIDMismatch"
+  | "syncAlreadyRunning"
+  | "linkAlreadyRunning"
+  | "storeLocked"
+  | "storeUnreadable"
+  | "deadlineExceeded"
+  | "permissionDenied"
+  | "authorizationNotDetermined"
+  | "sampleNotFound"
+  | "rollbackIncomplete"
+  | "distanceNotAttributable"
+  | "bloodPressureIncomplete"
+  | "authorizationUnavailableInExtension"
+  | "routeAwaitingConverter"
+  | "readQuotaExceeded" // android only
+  | "plannedWorkoutUnnamed"; // ios only
+
+export const FailureCodeValues: readonly FailureCode[] = [
+  "healthDataUnavailable",
+  "notConnected",
+  "tokenUnavailable",
+  "tokenRejected",
+  "tokenProviderFailed",
+  "offline",
+  "timedOut",
+  "serverError",
+  "transport",
+  "malformedResponse",
+  "userLimitReached",
+  "upgradeRequired",
+  "platform",
+  "deviceKeyUnavailable",
+  "signatureRejected",
+  "linkRevoked",
+  "linkConflict",
+  "clockSkewed",
+  "devIDMismatch",
+  "syncAlreadyRunning",
+  "linkAlreadyRunning",
+  "storeLocked",
+  "storeUnreadable",
+  "deadlineExceeded",
+  "permissionDenied",
+  "authorizationNotDetermined",
+  "sampleNotFound",
+  "rollbackIncomplete",
+  "distanceNotAttributable",
+  "bloodPressureIncomplete",
+  "authorizationUnavailableInExtension",
+  "routeAwaitingConverter",
+  "readQuotaExceeded",
+  "plannedWorkoutUnnamed",
+];
+
+/**
+ * Whether Terra's plans can be put on the person's Apple Watch. unsupported before iOS 17 or
+ * where WorkoutKit cannot schedule.
+ *
+ * Available on ios only.
+ */
+export type WorkoutSchedulingStatus =
+  | "unsupported" // ios only
+  | "notDetermined" // ios only
+  | "denied" // ios only
+  | "authorized"; // ios only
+
+export const WorkoutSchedulingStatusValues: readonly WorkoutSchedulingStatus[] = [
+  "unsupported",
+  "notDetermined",
+  "denied",
+  "authorized",
+];
+
+/**
+ * The person a connect is for. A stored link is restored only for the person it was made for;
+ * anybody else gets a fresh link. Never sent to Terra as identity.
+ */
+export type EndUser =
+  | { kind: "reference"; id: string }
+  | { kind: "anonymous" };
+
+/** A half-open window [start, end). Resolved against the device's calendar natively. */
+export type TimeRange =
+  | { kind: "lastHours"; hours: number }
+  | { kind: "lastDays"; days: number }
+  | { kind: "today" }
+  | { kind: "between"; start: Date; end: Date };
+
+export type SleepStage =
+  | { kind: "inBed" }
+  | { kind: "awake" }
+  | { kind: "asleep" }
+  | { kind: "light" }
+  | { kind: "deep" }
+  | { kind: "rem" }
+  | { kind: "unknown"; raw: string };
+
+export type WorkoutActivity =
+  | { kind: "running" }
+  | { kind: "walking" }
+  | { kind: "cycling" }
+  | { kind: "swimming" }
+  | { kind: "strengthTraining" }
+  | { kind: "other"; label: string };
+
+/**
+ * What the SDK believes about delivery right now. Wire spelling matches DiagnosticsWire.state
+ * and Apple's DiagnosticsState Encodable.
+ */
+export type DiagnosticsState =
+  | { state: "healthy" }
+  | { state: "quiet"; since: Date }
+  | { state: "backgroundRestricted"; reason?: BackgroundRestrictionReason | undefined }
+  | { state: "backgroundRefreshUnscheduled" }
+  | { state: "pendingRetry" }
+  | { state: "linkRevoked" }
+  | { state: "devIDMismatch" };
+
+/**
+ * What a subscription delivers. A stream can fail or finish, and without saying so the
+ * framework layer has to invent a convention for both - two of those, one per wrapper, is a
+ * contract nobody wrote down.
+ */
+export type StreamMessage =
+  | { kind: "data"; element: Record<string, unknown> }
+  | { kind: "error"; error: TerraErrorPayload }
+  | { kind: "complete" };
+
+/** Who recorded a sample. The only stable handle an app has for filtering by app or device. */
+export interface SampleSource {
+  readonly name: string;
+  readonly bundleId: string;
+  readonly productType?: string | undefined;
+  readonly deviceType?: string | undefined;
+}
+
+/**
+ * A link record. A value, not a handle: Apple's Connection carries sync and disconnect
+ * methods, and an object with behaviour cannot cross the bridge, so those are ops on the
+ * client.
+ */
+export interface Connection {
+  readonly source: Source;
+  readonly userId: string;
+  /**
+   * Android's StoredConnection carries the store-side id. Apple's Connection does not.
+   *
+   * Available on android only.
+   */
+  readonly providerUserId?: string | undefined;
+}
+
+export interface HeartRateSample {
+  readonly id: string;
+  readonly time: Date;
+  readonly beatsPerMinute: number;
+  readonly source: SampleSource;
+  readonly motionContext?: MotionContext | undefined;
+  readonly userEntered: boolean;
+  readonly timeZone?: string | undefined;
+}
+
+/**
+ * A step total over an interval. Apple derives the id from the source and start; Android
+ * carries a RecordId when it has one, so the id is optional on the wire.
+ */
+export interface StepCount {
+  readonly id?: string | undefined;
+  readonly start: Date;
+  readonly end: Date;
+  readonly steps: number;
+  readonly source: SampleSource;
+  readonly userEntered: boolean;
+  readonly timeZone?: string | undefined;
+}
+
+export interface SleepSegment {
+  readonly id: string;
+  readonly start: Date;
+  readonly end: Date;
+  readonly stage: SleepStage;
+  readonly source: SampleSource;
+  readonly userEntered: boolean;
+  readonly timeZone?: string | undefined;
+}
+
+/**
+ * indoor is optional because Health Connect does not always record it; Apple always has an
+ * answer.
+ */
+export interface Workout {
+  readonly id: string;
+  readonly start: Date;
+  readonly end: Date;
+  readonly activity: WorkoutActivity;
+  readonly activityTypeCode: number;
+  readonly indoor?: boolean | undefined;
+  readonly activeEnergyKilocalories?: number | undefined;
+  readonly distanceMeters?: number | undefined;
+  readonly source: SampleSource;
+  readonly userEntered: boolean;
+  readonly timeZone?: string | undefined;
+}
+
+/** A day whose data changed. Carries no health value by construction. */
+export interface HealthChange {
+  readonly category: DataCategory;
+  readonly day: string;
+}
+
+export interface WorkoutScope {
+  readonly activity: WorkoutActivity;
+  readonly energy: boolean;
+  readonly distance: boolean;
+}
+
+/**
+ * Lists rather than sets: JSON has no set, so the category lists are marked `set` and every
+ * generated codec de-duplicates and sorts them, so two orderings compare equal.
+ */
+export interface HealthAccess {
+  readonly read: readonly DataCategory[];
+  readonly write: readonly DataCategory[];
+  readonly workouts: readonly WorkoutScope[];
+}
+
+export interface HeartRateEntry {
+  readonly time: Date;
+  readonly beatsPerMinute: number;
+  readonly recordId?: string | undefined;
+}
+
+export interface StepEntry {
+  readonly start: Date;
+  readonly end: Date;
+  readonly steps: number;
+  readonly recordId?: string | undefined;
+}
+
+export interface SleepEntry {
+  readonly start: Date;
+  readonly end: Date;
+  readonly stage: SleepStage;
+  readonly recordId?: string | undefined;
+}
+
+export interface WorkoutEntry {
+  readonly start: Date;
+  readonly end: Date;
+  readonly activity: WorkoutActivity;
+  readonly totalEnergyKilocalories?: number | undefined;
+  readonly totalDistanceMeters?: number | undefined;
+  readonly recordId?: string | undefined;
+}
+
+export interface BodyEntry {
+  readonly time: Date;
+  readonly bodyMassKilograms?: number | undefined;
+  readonly bodyFatPercent?: number | undefined;
+  readonly bodyMassIndex?: number | undefined;
+  readonly heightMeters?: number | undefined;
+  readonly leanBodyMassKilograms?: number | undefined;
+  readonly bodyTemperatureCelsius?: number | undefined;
+  readonly oxygenSaturationPercent?: number | undefined;
+  readonly bloodGlucoseMilligramsPerDeciliter?: number | undefined;
+  readonly bloodPressureSystolicMillimetersOfMercury?: number | undefined;
+  readonly bloodPressureDiastolicMillimetersOfMercury?: number | undefined;
+  readonly recordId?: string | undefined;
+}
+
+/**
+ * Every field optional and every unit in the name, matching NutritionEntry.Nutrients on both
+ * platforms field for field.
+ */
+export interface Nutrients {
+  readonly energyKilocalories?: number | undefined;
+  readonly proteinGrams?: number | undefined;
+  readonly carbohydratesGrams?: number | undefined;
+  readonly fiberGrams?: number | undefined;
+  readonly sugarGrams?: number | undefined;
+  readonly fatTotalGrams?: number | undefined;
+  readonly fatSaturatedGrams?: number | undefined;
+  readonly fatMonounsaturatedGrams?: number | undefined;
+  readonly fatPolyunsaturatedGrams?: number | undefined;
+  readonly cholesterolMilligrams?: number | undefined;
+  readonly sodiumMilligrams?: number | undefined;
+  readonly potassiumMilligrams?: number | undefined;
+  readonly calciumMilligrams?: number | undefined;
+  readonly ironMilligrams?: number | undefined;
+  readonly magnesiumMilligrams?: number | undefined;
+  readonly zincMilligrams?: number | undefined;
+  readonly waterLiters?: number | undefined;
+  readonly caffeineMilligrams?: number | undefined;
+  readonly vitaminAMicrograms?: number | undefined;
+  readonly vitaminCMilligrams?: number | undefined;
+  readonly vitaminDMicrograms?: number | undefined;
+  readonly vitaminEMilligrams?: number | undefined;
+  readonly vitaminKMicrograms?: number | undefined;
+  readonly vitaminB6Milligrams?: number | undefined;
+  readonly vitaminB12Micrograms?: number | undefined;
+  readonly folateMicrograms?: number | undefined;
+  readonly thiaminMilligrams?: number | undefined;
+  readonly riboflavinMilligrams?: number | undefined;
+  readonly niacinMilligrams?: number | undefined;
+  readonly biotinMicrograms?: number | undefined;
+  readonly pantothenicAcidMilligrams?: number | undefined;
+  readonly phosphorusMilligrams?: number | undefined;
+  readonly iodineMicrograms?: number | undefined;
+  readonly chromiumMicrograms?: number | undefined;
+  readonly copperMilligrams?: number | undefined;
+  readonly manganeseMilligrams?: number | undefined;
+  readonly molybdenumMicrograms?: number | undefined;
+  readonly seleniumMicrograms?: number | undefined;
+  readonly chlorideMilligrams?: number | undefined;
+}
+
+export interface NutritionEntry {
+  readonly start: Date;
+  readonly end: Date;
+  readonly name?: string | undefined;
+  readonly nutrients: Nutrients;
+  readonly recordId?: string | undefined;
+}
+
+/**
+ * An error carried as a value rather than thrown, inside a sync result. The same shape the
+ * bridge rejects a promise with.
+ */
+export interface TerraErrorPayload {
+  readonly code: string;
+  readonly retryable: boolean;
+  readonly message: string;
+  readonly source?: Source | undefined;
+  readonly details?: Record<string, unknown> | undefined;
+}
+
+/** Available on ios only. */
+export interface PlannedWorkout {
+  readonly id: string;
+  readonly plannedOn: string;
+  readonly activity: WorkoutActivity;
+  readonly title?: string | undefined;
+  readonly completedAt?: Date | undefined;
+}
+
+/**
+ * The flat object both SDKs already emit: `at`, `event`, and whatever keys that kind carries.
+ * Carried through unchanged rather than reshaped, because reshaping it would be a hand-written
+ * second contract on each platform that no vector could pin - and the encoding it would be
+ * translating is one DiagnosticsWire and Apple's Encodable already agree on, and that
+ * EventPrivacyTest already guards against carrying a health value.
+ */
+export type TerraEvent = Record<string, unknown>;
+
+/**
+ * The redacted report, carried as the wire object DiagnosticsWire.report and Apple's
+ * SupportReport.json already produce.
+ */
+export interface SupportReport {
+  readonly sdkVersion: string;
+  readonly generatedAt: Date;
+  readonly state: DiagnosticsState;
+  readonly lastDelivery?: Date | undefined;
+  readonly isConnected: boolean;
+  readonly requestedCategories: readonly string[];
+  readonly requestedWrites: readonly string[];
+  readonly requestedWorkouts: readonly string[];
+  readonly recentEvents: readonly TerraEvent[];
+}
+
+/**
+ * What the JS side needs to know about the native client it is attaching to. bootstrapped
+ * false is a host setup bug, and the wrapper says so with the exact line to add.
+ */
+export interface BootstrapState {
+  readonly bootstrapped: boolean;
+  readonly devId?: string | undefined;
+  readonly platform: string;
+  readonly sdkVersion: string;
+  readonly backgroundRegistered: boolean;
+}
+
+/**
+ * The broker asking JS for a link token. Answered by token.resolve or token.reject with the
+ * same requestId.
+ */
+export interface TokenRequest {
+  readonly requestId: string;
+}
+
+/** No request fields, or no response value. */
+export type Empty = Record<string, never>;
+
+export interface SourceRequest {
+  readonly source?: Source | undefined;
+}
+
+export interface RangeRequest {
+  readonly range: TimeRange;
+}
+
+export interface CategoryRequest {
+  readonly category: DataCategory;
+  readonly source?: Source | undefined;
+}
+
+export interface RecordIdRequest {
+  readonly id: string;
+}
+
+export interface ConnectRequest {
+  readonly source?: Source | undefined;
+  readonly endUser: EndUser;
+  /**
+   * A grant already in hand, from a QR code or a deep link. Absent means the token provider is
+   * asked.
+   */
+  readonly token?: string | undefined;
+}
+
+export interface PermissionRequest {
+  readonly read: readonly DataCategory[];
+  readonly write: readonly DataCategory[];
+  readonly workouts: readonly WorkoutScope[];
+  readonly source?: Source | undefined;
+}
+
+/**
+ * What the sheet granted. Android answers with the access this call obtained; HealthKit will
+ * not report read grants, so Apple answers nothing at all.
+ */
+export interface PermissionGrant {
+  /** Available on android only. */
+  readonly granted?: HealthAccess | undefined;
+}
+
+export interface TokenResolveRequest {
+  readonly requestId: string;
+  readonly token: string;
+}
+
+export interface TokenRejectRequest {
+  readonly requestId: string;
+  readonly message: string;
+}
+
+export interface TokenProviderRequest {
+  readonly present: boolean;
+  readonly timeoutMs: number;
+}
+
+/** Available on ios only. */
+export interface MarkCompleteRequest {
+  readonly id: string;
+  readonly at?: Date | undefined;
+}
+
+export interface BoolResult {
+  readonly value: boolean;
+}
+
+export interface StatusResult {
+  readonly status: PermissionStatus;
+}
+
+/** Available on android only. */
+export interface StatusesResult {
+  readonly statuses: Partial<Record<DataCategory, PermissionStatus>>;
+}
+
+export interface RecordIdList {
+  readonly ids: readonly string[];
+}
+
+export interface ConnectionList {
+  readonly connections: readonly Connection[];
+}
+
+export interface HeartRateList {
+  readonly samples: readonly HeartRateSample[];
+}
+
+export interface StepCountList {
+  readonly samples: readonly StepCount[];
+}
+
+export interface SleepSegmentList {
+  readonly samples: readonly SleepSegment[];
+}
+
+export interface WorkoutList {
+  readonly samples: readonly Workout[];
+}
+
+/** Available on ios only. */
+export interface PlannedWorkoutList {
+  readonly workouts: readonly PlannedWorkout[];
+}
+
+/**
+ * Once authorized, every sync run keeps the Watch schedule in step with Terra.
+ *
+ * Available on ios only.
+ */
+export interface WorkoutScheduling {
+  readonly status: WorkoutSchedulingStatus;
+}
+
+export interface LastDeliveryResult {
+  readonly at?: Date | undefined;
+}
+
+export interface HeartRateEntryList {
+  readonly entries: readonly HeartRateEntry[];
+}
+
+export interface BodyEntryList {
+  readonly entries: readonly BodyEntry[];
+}
+
+export interface StepEntryList {
+  readonly entries: readonly StepEntry[];
+}
+
+export interface SleepEntryList {
+  readonly entries: readonly SleepEntry[];
+}
+
+export interface WorkoutEntryList {
+  readonly entries: readonly WorkoutEntry[];
+}
+
+export interface NutritionEntryList {
+  readonly entries: readonly NutritionEntry[];
+}
+

package/src/index.ts

@@ -0,0 +1,52 @@
+/**
+ * The package's public surface.
+ *
+ * Everything re-exported from `./generated` comes out of `surface/terra-surface.json`. The
+ * hand-written members are shapes rather than vocabulary - `Terra`, `TerraError`, `EndUser` and
+ * `createTerra` - and none of them names a data type, an op or a code of its own.
+ *
+ * ```ts
+ * const terra = createTerra({ tokenProvider: () => api.terraToken() });
+ * await terra.connect("health", EndUser.reference(user.id));
+ * await terra.permissions.request({ read: ["body"] });
+ * const hr = await terra.body.heartRate({ kind: "lastHours", hours: 1 });
+ * ```
+ */
+
+export { createTerra } from "./createTerra";
+export { Terra } from "./Terra";
+export type {
+  ActivityMetrics,
+  Background,
+  BodyMetrics,
+  DailyMetrics,
+  Diagnostics,
+  NativeBridge,
+  NutritionMetrics,
+  Permissions,
+  PlannedWorkouts,
+  SleepMetrics,
+  StreamListener,
+  TerraOptions,
+  TokenProvider,
+  Unsubscribe,
+} from "./Terra";
+
+export { TerraError } from "./TerraError";
+export type { TerraErrorJSON } from "./TerraError";
+
+export { EndUser } from "./EndUser";
+
+export { GeneratedClient } from "./generated/client";
+export type { Invoker } from "./generated/client";
+
+export type { TerraErrorCode } from "./generated/errors";
+export { retryableByCode, bridgeOwnedCodes, platformOnlyCodes } from "./generated/errors";
+
+export type { OpId, StreamId } from "./generated/ops";
+export { opIds, streamIds, availableOn, eventKinds } from "./generated/ops";
+
+export type { StreamElements, StreamDelivery } from "./generated/streams";
+export { decodeStreamDelivery, decodeStreamElement, streamAvailableOn } from "./generated/streams";
+
+export * from "./generated/types";