react-native-workouts 0.1.0 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-workouts",
-  "version": "0.1.0",
+  "version": "0.2.3",
   "description": "React Native Expo module for Apple WorkoutKit - create, preview, and sync custom workouts to Apple Watch",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -49,8 +49,8 @@
   "dependencies": {},
   "devDependencies": {
     "@types/react": "~19.1.0",
-    "expo-module-scripts": "^5.0.8",
     "expo": "^54.0.27",
+    "expo-module-scripts": "^5.0.8",
     "react-native": "0.81.5"
   },
   "peerDependencies": {

package/src/ReactNativeWorkouts.types.ts

@@ -1,105 +1,116 @@
-// Authorization
+/**
+ * WorkoutKit authorization state as seen by Apple's `WorkoutScheduler`.
+ */
 
 export type AuthorizationStatus =
-  | 'authorized'
-  | 'notDetermined'
-  | 'denied'
-  | 'unknown';
+  | "authorized"
+  | "notDetermined"
+  | "denied"
+  | "unknown";
+
+// Shared Objects
+
+import type { SharedObject } from "expo";
 
 // Activity Types
 
+/**
+ * Supported workout activity types exposed by this package.
+ *
+ * Note: these map to HealthKit `HKWorkoutActivityType` values.
+ */
 export type ActivityType =
-  | 'running'
-  | 'cycling'
-  | 'walking'
-  | 'hiking'
-  | 'swimming'
-  | 'rowing'
-  | 'elliptical'
-  | 'stairClimbing'
-  | 'highIntensityIntervalTraining'
-  | 'yoga'
-  | 'functionalStrengthTraining'
-  | 'traditionalStrengthTraining'
-  | 'dance'
-  | 'jumpRope'
-  | 'coreTraining'
-  | 'pilates'
-  | 'kickboxing'
-  | 'stairs'
-  | 'stepTraining'
-  | 'wheelchairRunPace'
-  | 'wheelchairWalkPace';
-
-export type LocationType = 'indoor' | 'outdoor';
+  | "running"
+  | "cycling"
+  | "walking"
+  | "hiking"
+  | "swimming"
+  | "rowing"
+  | "elliptical"
+  | "stairClimbing"
+  | "highIntensityIntervalTraining"
+  | "yoga"
+  | "functionalStrengthTraining"
+  | "traditionalStrengthTraining"
+  | "dance"
+  | "jumpRope"
+  | "coreTraining"
+  | "pilates"
+  | "kickboxing"
+  | "stairs"
+  | "stepTraining"
+  | "wheelchairRunPace"
+  | "wheelchairWalkPace";
+
+export type LocationType = "indoor" | "outdoor";
 
 // Units
 
 export type DistanceUnit =
-  | 'meters'
-  | 'm'
-  | 'kilometers'
-  | 'km'
-  | 'miles'
-  | 'mi'
-  | 'yards'
-  | 'yd'
-  | 'feet'
-  | 'ft';
+  | "meters"
+  | "m"
+  | "kilometers"
+  | "km"
+  | "miles"
+  | "mi"
+  | "yards"
+  | "yd"
+  | "feet"
+  | "ft";
 
 export type TimeUnit =
-  | 'seconds'
-  | 's'
-  | 'sec'
-  | 'minutes'
-  | 'min'
-  | 'hours'
-  | 'h'
-  | 'hr';
+  | "seconds"
+  | "s"
+  | "sec"
+  | "minutes"
+  | "min"
+  | "hours"
+  | "h"
+  | "hr";
 
 export type EnergyUnit =
-  | 'kilocalories'
-  | 'kcal'
-  | 'cal'
-  | 'kilojoules'
-  | 'kj';
+  | "kilocalories"
+  | "kcal"
+  | "cal"
+  | "kilojoules"
+  | "kj";
 
 export type SpeedUnit =
-  | 'metersPerSecond'
-  | 'mps'
-  | 'm/s'
-  | 'kilometersPerHour'
-  | 'kph'
-  | 'km/h'
-  | 'milesPerHour'
-  | 'mph';
+  | "metersPerSecond"
+  | "mps"
+  | "m/s"
+  | "kilometersPerHour"
+  | "kph"
+  | "km/h"
+  | "milesPerHour"
+  | "mph";
 
 export type PaceUnit =
-  | 'minutesPerKilometer'
-  | 'min/km'
-  | 'minutesPerMile'
-  | 'min/mi';
+  | "minutesPerKilometer"
+  | "min/km"
+  | "minutesPerMile"
+  | "min/mi";
 
 // Goals
 
 export interface OpenGoal {
-  type: 'open';
+  type: "open";
 }
 
 export interface DistanceGoal {
-  type: 'distance';
+  type: "distance";
   value: number;
   unit?: DistanceUnit;
 }
 
 export interface TimeGoal {
-  type: 'time';
+  type: "time";
   value: number;
   unit?: TimeUnit;
 }
 
 export interface EnergyGoal {
-  type: 'energy';
+  type: "energy";
   value: number;
   unit?: EnergyUnit;
 }
@@ -109,38 +120,38 @@ export type WorkoutGoal = OpenGoal | DistanceGoal | TimeGoal | EnergyGoal;
 // Alerts
 
 export interface HeartRateZoneAlert {
-  type: 'heartRate';
+  type: "heartRate";
   zone: number;
 }
 
 export interface HeartRateRangeAlert {
-  type: 'heartRate';
+  type: "heartRate";
   min: number;
   max: number;
 }
 
 export interface PaceAlert {
-  type: 'pace';
+  type: "pace";
   min: number;
   max: number;
   unit?: PaceUnit;
 }
 
 export interface SpeedAlert {
-  type: 'speed';
+  type: "speed";
   min: number;
   max: number;
   unit?: SpeedUnit;
 }
 
 export interface CadenceAlert {
-  type: 'cadence';
+  type: "cadence";
   min: number;
   max: number;
 }
 
 export interface PowerAlert {
-  type: 'power';
+  type: "power";
   min: number;
   max: number;
 }
@@ -155,7 +166,7 @@ export type WorkoutAlert =
 
 // Workout Steps
 
-export type StepPurpose = 'work' | 'recovery';
+export type StepPurpose = "work" | "recovery";
 
 export interface WorkoutStep {
   goal?: WorkoutGoal;
@@ -176,8 +187,17 @@ export interface IntervalBlock {
 // Workout Configurations
 
 export interface CustomWorkoutConfig {
+  /**
+   * Activity type (running, cycling, etc).
+   */
   activityType: ActivityType;
+  /**
+   * Indoor/outdoor (where applicable). Defaults to `"outdoor"` when omitted.
+   */
   locationType?: LocationType;
+  /**
+   * Display name used by the system (where supported by WorkoutKit).
+   */
   displayName?: string;
   warmup?: WorkoutStep;
   blocks: IntervalBlock[];
@@ -187,12 +207,15 @@ export interface CustomWorkoutConfig {
 export interface SingleGoalWorkoutConfig {
   activityType: ActivityType;
   locationType?: LocationType;
+  /**
+   * Optional label for your app/back-end. WorkoutKit may not display this for all workout kinds.
+   */
   displayName?: string;
   goal: WorkoutGoal;
 }
 
 export interface PacerTarget {
-  type: 'speed' | 'pace';
+  type: "speed" | "pace";
   value: number;
   unit?: SpeedUnit | PaceUnit;
 }
@@ -200,10 +223,35 @@ export interface PacerTarget {
 export interface PacerWorkoutConfig {
   activityType: ActivityType;
   locationType?: LocationType;
+  /**
+   * Optional label for your app/back-end. WorkoutKit may not display this for all workout kinds.
+   */
   displayName?: string;
   target: PacerTarget;
 }
 
+export type SwimBikeRunActivityType = "swimming" | "cycling" | "running";
+
+export interface SwimBikeRunActivityConfig {
+  type: SwimBikeRunActivityType;
+  /**
+   * For running/cycling: `"indoor" | "outdoor"`.
+   * For swimming: `"indoor"` means pool, `"outdoor"` means open water.
+   */
+  locationType?: LocationType;
+}
+
+export interface SwimBikeRunWorkoutConfig {
+  /**
+   * Display name shown by the system for multisport workouts.
+   */
+  displayName?: string;
+  /**
+   * Ordered list of activities (e.g. swim -> bike -> run).
+   */
+  activities: SwimBikeRunActivityConfig[];
+}
+
 // Date Components
 
 export interface DateComponents {
@@ -240,3 +288,52 @@ export interface AuthorizationChangeEvent {
 export type ReactNativeWorkoutsModuleEvents = {
   onAuthorizationChange: (event: AuthorizationChangeEvent) => void;
 };
+
+export type WorkoutPlanKind = "custom" | "singleGoal" | "pacer" | "swimBikeRun";
+
+export interface WorkoutPlanExport {
+  /**
+   * UUID of the underlying `WorkoutPlan` instance.
+   *
+   * This is useful for debugging/logging and for matching the ID returned by `plan.scheduleAndSync`.
+   */
+  id: string;
+  kind: WorkoutPlanKind;
+  /**
+   * The original config used to create the plan.
+   *
+   * Use this to persist/share the plan in your own backend and recreate the plan later.
+   */
+  config: unknown;
+}
+
+export declare class WorkoutPlan extends SharedObject<{}> {
+  /**
+   * UUID of this plan instance.
+   */
+  readonly id: string;
+  /**
+   * Which kind of workout this plan represents.
+   */
+  readonly kind: WorkoutPlanKind;
+
+  /**
+   * Shows Apple's system Workout preview modal (includes “Add to Watch / Send to Watch” UX).
+   */
+  preview(): Promise<boolean>;
+
+  /**
+   * Schedules the plan using Apple's `WorkoutScheduler`.
+   *
+   * This is the mechanism that syncs the plan to the Apple Watch Workout app.
+   */
+  scheduleAndSync(date: DateComponents): Promise<ScheduleResult>;
+
+  /**
+   * Returns `{ id, kind, config }` for storing/sharing the plan in your own backend.
+   *
+   * This does NOT export a system-importable file — it's a JSON payload you can use to recreate
+   * the plan via the `create*WorkoutPlan(...)` factories.
+   */
+  export(): WorkoutPlanExport;
+}

package/src/ReactNativeWorkoutsModule.ts

@@ -1,64 +1,147 @@
-import { NativeModule, requireNativeModule } from 'expo';
+import { NativeModule, requireNativeModule } from "expo";
 
 import type {
-  ReactNativeWorkoutsModuleEvents,
-  AuthorizationStatus,
   ActivityType,
-  LocationType,
+  AuthorizationStatus,
   CustomWorkoutConfig,
-  SingleGoalWorkoutConfig,
-  PacerWorkoutConfig,
   DateComponents,
-  WorkoutValidationResult,
-  ScheduleResult,
+  LocationType,
+  PacerWorkoutConfig,
+  ReactNativeWorkoutsModuleEvents,
   ScheduledWorkout,
-} from './ReactNativeWorkouts.types';
+  ScheduleResult,
+  SingleGoalWorkoutConfig,
+  SwimBikeRunWorkoutConfig,
+  WorkoutPlan,
+  WorkoutValidationResult,
+} from "./ReactNativeWorkouts.types";
 
-declare class ReactNativeWorkoutsModule extends NativeModule<ReactNativeWorkoutsModuleEvents> {
+declare class ReactNativeWorkoutsModule
+  extends NativeModule<ReactNativeWorkoutsModuleEvents> {
   // Constants
+  /**
+   * Whether Health data is available on this device.
+   * On iOS simulators this is typically `false`.
+   */
   readonly isAvailable: boolean;
 
   // Authorization
+  /**
+   * Returns the current WorkoutKit authorization status.
+   */
   getAuthorizationStatus(): Promise<AuthorizationStatus>;
+  /**
+   * Prompts the user for WorkoutKit authorization (if needed).
+   */
   requestAuthorization(): Promise<AuthorizationStatus>;
 
   // Validation
+  /**
+   * Returns whether a given goal type is supported for the provided activity + location.
+   */
   supportsGoal(
     activityType: ActivityType,
     locationType: LocationType,
-    goalType: string
+    goalType: string,
   ): Promise<boolean>;
 
   // Custom Workouts
+  /**
+   * Validates a custom workout config. (Legacy name: this does not persist anything.)
+   */
   createCustomWorkout(
-    config: CustomWorkoutConfig
+    config: CustomWorkoutConfig,
   ): Promise<WorkoutValidationResult>;
+  /**
+   * Previews a custom workout via Apple's system modal.
+   */
+  previewWorkout(config: CustomWorkoutConfig): Promise<boolean>;
+  /**
+   * Schedules a custom workout (syncs it to the Apple Watch Workout app).
+   *
+   * Prefer using `useCustomWorkout(...)` + `plan.scheduleAndSync(...)` for new code.
+   */
   scheduleWorkout(
     config: CustomWorkoutConfig,
-    date: DateComponents
+    date: DateComponents,
   ): Promise<ScheduleResult>;
 
   // Single Goal Workouts
+  /**
+   * Validates a single-goal workout config. (Legacy name: this does not persist anything.)
+   */
   createSingleGoalWorkout(
-    config: SingleGoalWorkoutConfig
+    config: SingleGoalWorkoutConfig,
   ): Promise<WorkoutValidationResult>;
+  /**
+   * Previews a single-goal workout via Apple's system modal.
+   */
+  previewSingleGoalWorkout(config: SingleGoalWorkoutConfig): Promise<boolean>;
+  /**
+   * Schedules a single-goal workout (syncs it to the Apple Watch Workout app).
+   *
+   * Prefer using `useSingleGoalWorkout(...)` + `plan.scheduleAndSync(...)` for new code.
+   */
   scheduleSingleGoalWorkout(
     config: SingleGoalWorkoutConfig,
-    date: DateComponents
+    date: DateComponents,
   ): Promise<ScheduleResult>;
 
   // Pacer Workouts
+  /**
+   * Validates a pacer workout config. (Legacy name: this does not persist anything.)
+   */
   createPacerWorkout(
-    config: PacerWorkoutConfig
+    config: PacerWorkoutConfig,
   ): Promise<WorkoutValidationResult>;
+  /**
+   * Previews a pacer workout via Apple's system modal.
+   */
+  previewPacerWorkout(config: PacerWorkoutConfig): Promise<boolean>;
+  /**
+   * Schedules a pacer workout (syncs it to the Apple Watch Workout app).
+   *
+   * Prefer using `usePacerWorkout(...)` + `plan.scheduleAndSync(...)` for new code.
+   */
   schedulePacerWorkout(
     config: PacerWorkoutConfig,
-    date: DateComponents
+    date: DateComponents,
   ): Promise<ScheduleResult>;
 
+  // Shared WorkoutPlan factories (object-oriented API)
+  /**
+   * Creates a stateful `WorkoutPlan` shared object (recommended API for new code).
+   */
+  createCustomWorkoutPlan(config: CustomWorkoutConfig): Promise<WorkoutPlan>;
+  /**
+   * Creates a stateful `WorkoutPlan` shared object (recommended API for new code).
+   */
+  createSingleGoalWorkoutPlan(
+    config: SingleGoalWorkoutConfig,
+  ): Promise<WorkoutPlan>;
+  /**
+   * Creates a stateful `WorkoutPlan` shared object (recommended API for new code).
+   */
+  createPacerWorkoutPlan(config: PacerWorkoutConfig): Promise<WorkoutPlan>;
+  /**
+   * Creates a stateful multisport `WorkoutPlan` shared object (recommended API for new code).
+   */
+  createSwimBikeRunWorkoutPlan(
+    config: SwimBikeRunWorkoutConfig,
+  ): Promise<WorkoutPlan>;
+
   // Scheduled Workouts Management
+  /**
+   * Lists scheduled workouts created by this app.
+   */
   getScheduledWorkouts(): Promise<ScheduledWorkout[]>;
+  /**
+   * Removes a scheduled workout by ID.
+   */
   removeScheduledWorkout(id: string): Promise<boolean>;
+  /**
+   * Removes all scheduled workouts created by this app.
+   */
   removeAllScheduledWorkouts(): Promise<boolean>;
 
   // Utility
@@ -68,5 +151,5 @@ declare class ReactNativeWorkoutsModule extends NativeModule<ReactNativeWorkouts
 }
 
 export default requireNativeModule<ReactNativeWorkoutsModule>(
-  'ReactNativeWorkouts'
+  "ReactNativeWorkouts",
 );