Class Health

Checks whether the native health provider is available on this device.

Reflects only the provider state — whether the OS health provider is installed and usable on this device. To detect whether the host app installed the health module at all, check Eitri.modules() first:

const modules = await Eitri.modules();
if (!modules?.health) {
  // module is not installed in the host app
  return;
}

const status = await Eitri.health.isAvailable();
if (!status.available) {
  // provider unavailable; status.reason indicates why
  return;
}
Copy

Compatibility Control

• Module: health - Install eitri-ios-health or eitri-android-health

Lists the data types the native module currently supports.

Example:

const { types } = await Eitri.health.getSupportedDataTypes();
if (types.includes("steps")) {
  showStepsCard();
}
Copy

Compatibility Control

• Module: health - Install eitri-ios-health or eitri-android-health

Requests read authorization for the given data types.

Shows the OS native permission UI:

• iOS: a single sheet aggregating all requested types.
• Android: the system permissions screen.

If the user has already decided (granted or denied), the OS does not show the prompt again and this call resolves silently. The method does not return whether access was granted.

Example:

await Eitri.health.requestPermissions({
  read: ["steps", "heartRate", "weight", "biologicalSex", "exercise"],
});
Copy

Compatibility Control

• Module: health - Install eitri-ios-health or eitri-android-health

Reads raw samples for a single data type within a time range, one page at a time.

Each call returns up to limit samples (max 500, default 100) plus a nextCursor. To read the full range, pass nextCursor back as the next call's cursor; when it is absent the range is exhausted.

If the user has not authorized the data type, this resolves with samples: [].

Example — read a single page:

await Eitri.health.requestPermissions({ read: ["heartRate"] });

const { samples } = await Eitri.health.readSamples({
  dataType: "heartRate",
  startDate: "2026-05-17T00:00:00Z",
  endDate: "2026-05-18T00:00:00Z",
  limit: 200,
});

if (samples.length === 0) {
  // Could be: denied permission, or no data in the period.
  // Offer a "Open settings" fallback so the user can grant access if needed.
  showNoDataState();
  return;
}

console.log(samples[0]); // { id, dataType: "heartRate", value: 72, unit: "bpm", ... }
Copy

Example — paginate the whole range and collect every sample (default descending order):

await Eitri.health.requestPermissions({ read: ["heartRate"] });

const query = {
  dataType: "heartRate",
  startDate: "2026-05-17T00:00:00Z",
  endDate: "2026-05-18T00:00:00Z",
  limit: 500, // page size — the max allowed
};

const all = [];
let cursor; // undefined on the first call

do {
  const { samples, nextCursor } = await Eitri.health.readSamples({ ...query, cursor });
  all.push(...samples);
  cursor = nextCursor; // undefined once the range is exhausted -> loop ends
} while (cursor);

console.log(`Collected ${all.length} heart-rate samples`);
// all[0] is the most recent; all[all.length - 1] is the oldest in the range.
Copy

Always drive the loop on nextCursor, never on samples.length: a page can return fewer than limit samples — even zero — while nextCursor is still present. The loop ends only when nextCursor is absent. To cap collection, add your own && all.length < MAX to the while.

Compatibility Control

• Module: health - Install eitri-ios-health or eitri-android-health

Reads exercises in the given time range, one page at a time.

Each exercise is a single activity record (a run, a ride, a swim). Each call returns up to limit exercises (max 500, default 100) plus a nextCursor. To read the full range, pass nextCursor back as the next call's cursor; when it is absent the range is exhausted.

Permission flows through requestPermissions under the "exercise" key.

If the user has not authorized exercise reads, this resolves with exercises: [].

Example — list a single page of this month's exercises and load the heart-rate curve for the most recent one:

await Eitri.health.requestPermissions({ read: ["exercise", "heartRate"] });

const { exercises } = await Eitri.health.readExercises({
  startDate: "2026-05-01T00:00:00Z",
  endDate: "2026-05-31T23:59:59Z",
  limit: 200,
});

for (const exercise of exercises) {
  console.log(exercise.platformDetails.platform); // "ios" | "android"
  console.log(exercise.exerciseType);             // iOS: "running"; Android: "running"
  console.log(exercise.durationSeconds);          // 1830
}

const lastExercise = exercises[0];
if (lastExercise) {
  const { samples } = await Eitri.health.readSamples({
    dataType: "heartRate",
    startDate: lastExercise.startDate,
    endDate: lastExercise.endDate,
  });
  console.log(samples); // heart-rate samples scoped to the exercise window
}
Copy

Example — paginate the whole range and collect every exercise:

await Eitri.health.requestPermissions({ read: ["exercise"] });

const query = {
  startDate: "2026-05-01T00:00:00Z",
  endDate: "2026-05-31T23:59:59Z",
  limit: 500, // page size — the max allowed
};

const all = [];
let cursor; // undefined on the first call

do {
  const { exercises, nextCursor } = await Eitri.health.readExercises({ ...query, cursor });
  all.push(...exercises);
  cursor = nextCursor; // undefined once the range is exhausted -> loop ends
} while (cursor);

console.log(`Collected ${all.length} exercises`);
// all[0] is the most recent; all[all.length - 1] is the oldest in the range.
Copy

Always drive the loop on nextCursor, never on exercises.length: a page can return fewer than limit exercises — even zero — while nextCursor is still present. The loop ends only when nextCursor is absent. To cap collection, add your own && all.length < MAX to the while.

Compatibility Control

• Module: health - Install eitri-ios-health or eitri-android-health

Reads user characteristics in a single call.

Only the names passed in input.names appear as keys in the response. A key with a null value means the characteristic was requested but is not available or the user has not filled it in. Names that were not requested are absent from the response.

🚨 iOS only. On Android every requested name appears in the response with a null value.

Example:

// 1. Request authorization
await Eitri.health.requestPermissions({
  read: ["steps", "biologicalSex", "dateOfBirth", "bloodType"],
});

// 2. Read characteristics
const characteristics = await Eitri.health.getCharacteristics({
  names: ["biologicalSex", "dateOfBirth", "bloodType"],
});
console.log(characteristics.biologicalSex); // "male" | "female" | "other" | null
console.log(characteristics.dateOfBirth);   // "1990-04-12" | null
console.log(characteristics.bloodType);     // "O+" | null
Copy

Compatibility Control

• Module: health - Install eitri-ios-health or eitri-android-health