@pose-tracker/react-native-pose-estimation-light 0.1.0

package/src/types/events.ts

@@ -0,0 +1,437 @@
+/**
+ * SDK event types.
+ *
+ * These mirror the postMessage payloads of the existing PoseTracker WebView
+ * API (keypoints, angles, counter, posture, progression, recommendations,
+ * form_score, exercise_summary) so existing integrations can migrate with
+ * minimal changes: the WebView `onMessage` JSON becomes a typed callback.
+ */
+
+import type { Keypoint } from './pose';
+import type { AccelerationState } from './acceleration';
+import type { QualityProfile, QualityProfileId } from '../quality/profiles';
+
+export type PoseTrackerStatus =
+  | 'idle'
+  | 'configuring'
+  | 'downloading'
+  | 'warming'
+  | 'ready'
+  | 'error';
+
+/**
+ * Operating mode (commercial boundary):
+ * - 'keypoints-only': no validated API key/session — the SDK provides its
+ *   core value only (bundled MoveNet, warm-up, camera pipeline) and streams
+ *   raw `keypoints` events. No business events (counter, angles, posture,
+ *   progression, recommendations, form_score, exercise_summary).
+ * - 'full-engine': a handshake succeeded (live or from the encrypted local
+ *   session cache) and the engine bundle is loaded — all events available.
+ *
+ * The mode can upgrade at runtime (keypoints-only → full-engine) without
+ * restarting the camera pipeline, via `configure()` or a preload retry.
+ */
+export type PoseTrackerMode = 'keypoints-only' | 'full-engine';
+
+export type InitializationStep =
+  | 'configuring'
+  | 'downloading'
+  | 'warming'
+  | 'accessing_webcam'
+  | 'loading_pose_model'
+  | 'ready';
+
+export interface InitializationEvent {
+  type: 'initialization';
+  /**
+   * Machine step. Classic PoseTracker used free-form `message` strings
+   * ("accessing webcam", "loading pose model", "running"); both are set.
+   */
+  step: InitializationStep;
+  /** Human-readable status (PoseTracker WebView parity). */
+  message: string;
+  ready: boolean;
+  /** Present on the `ready` step. */
+  mode?: PoseTrackerMode;
+  /**
+   * Present on the `ready` step: GPU-acceleration verdict from the warm-up
+   * health check ('gpu' | 'cpu-fallback' | 'unavailable'). See
+   * docs/ANDROID_GL_ACCELERATION.md.
+   */
+  acceleration?: AccelerationState;
+}
+
+export interface ErrorEvent {
+  type: 'error';
+  code:
+    | 'invalid_token'
+    | 'quota_exceeded'
+    | 'network'
+    /**
+     * First launch, no network, empty runtime cache: the pose runtime cannot
+     * be initialized without downloading the payload once. Fatal.
+     */
+    | 'network_required'
+    /**
+     * Offline with an API key: metered features (engine/exercises) are
+     * refused because PoseTracker cannot count their usage. Non-fatal —
+     * keypoints-only keeps running from the cache.
+     */
+    | 'offline_metered'
+    /**
+     * The `free` plan requested developer features (angles, recommendations,
+     * progression, or keypoints combined with an exercise). Same message as
+     * the PoseTracker WebView (`TrackingAppV3`). Non-fatal: keypoints-only
+     * pose estimation keeps running.
+     */
+    | 'free_plan_feature_blocked'
+    /**
+     * A WebView-only option was requested (blazepose, poseEngine,
+     * mediapipeModel, …): this SDK ships MoveNet Lightning only.
+     */
+    | 'feature_not_supported'
+    /** Unknown exercise id (WebView parity: `invalid_exercise`). */
+    | 'invalid_exercise'
+    /** jump_analysis requires `userHeightCm` (WebView parity). */
+    | 'jump_analysis_missing_height'
+    | 'model_load_failed'
+    | 'engine_load_failed'
+    | 'integrity_check_failed'
+    | 'webview_error'
+    | 'device_too_slow'
+    | 'backend_fallback_wasm'
+    | 'internal';
+  message: string;
+}
+
+/**
+ * Non-fatal warning the host can surface (telemetry / soft UX).
+ * Classic WebView sometimes used `type: "warning"`; V3 degradations often
+ * reuse `type: "error"` with a code — see {@link PerformanceWarningEvent}.
+ */
+export interface WarningEvent {
+  type: 'warning';
+  code:
+    | 'quality_downgraded'
+    | 'backend_fallback_wasm'
+    | 'webview'
+    | 'internal';
+  message: string;
+  timestampMs: number;
+}
+
+export interface KeypointsEvent {
+  type: 'keypoints';
+  keypoints: Keypoint[];
+  /** Mean confidence of the pose. */
+  score: number;
+  timestampMs: number;
+}
+
+export interface AngleValue {
+  /** Angle id from the exercise config, e.g. "left_knee". */
+  id: string;
+  side: 'left' | 'right' | 'center';
+  degrees: number;
+  /** Min confidence of the three keypoints defining the angle. */
+  score: number;
+}
+
+export interface AnglesEvent {
+  type: 'angles';
+  angles: AngleValue[];
+  timestampMs: number;
+}
+
+/**
+ * Letter grade for a 0–100 form score (GitBook / Front BaseExercise):
+ * A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F < 60.
+ */
+export type FormGrade = 'A' | 'B' | 'C' | 'D' | 'F';
+
+/** Valid `minGrade` filter values (F is not a valid minGrade config). */
+export type MinGrade = 'A' | 'B' | 'C' | 'D';
+
+/**
+ * Nested form score on a counted rep — GitBook / WebView V3
+ * `counter.form_score` (authoritative grade for that rep).
+ */
+export interface CounterFormScore {
+  /** Score of the rep that was just counted, 0–100. */
+  score: number;
+  /** Running average across counted reps, 0–100. */
+  average: number;
+  grade: FormGrade;
+}
+
+export interface CounterEvent {
+  type: 'counter';
+  count: number;
+  /**
+   * Authoritative form score for the counted rep (WebView
+   * `counter.form_score`). Prefer this over a standalone `form_score` event
+   * when mirroring the tracking endpoint.
+   */
+  formScore?: CounterFormScore;
+  /** Similarity score vs. reference movement for the last rep, when a reference is active. */
+  referenceScore?: number;
+  timestampMs: number;
+}
+
+export interface PostureEvent {
+  type: 'posture';
+  /** True when the user placement satisfies the exercise posture requirements. */
+  ready: boolean;
+  /** Localized human hint ("Face the camera", "Get ready…"). */
+  hint: string;
+  /** WebView parity: placement direction hint ("in-frame", "face-camera", "profile-camera"). */
+  direction?: string;
+  missingKeypoints: string[];
+  timestampMs: number;
+}
+
+export interface ProgressionEvent {
+  type: 'progression';
+  /** Movement progression within the current rep, 0–100. */
+  value: number;
+  timestampMs: number;
+}
+
+export interface RecommendationsEvent {
+  type: 'recommendations';
+  /** Localized form advice strings. */
+  recommendations: string[];
+  timestampMs: number;
+}
+
+export interface FormScoreEvent {
+  type: 'form_score';
+  /** Score of the last completed rep, 0–100. */
+  score: number;
+  /** Running average across the session, 0–100. */
+  average: number;
+  grade: FormGrade;
+  timestampMs: number;
+}
+
+export interface RepSummary {
+  index: number;
+  formScore: number;
+  durationMs: number;
+  referenceScore?: number;
+}
+
+export interface ExerciseSummaryEvent {
+  type: 'exercise_summary';
+  exercise: string;
+  counter: number;
+  averageFormScore: number;
+  averageSimilarity?: number;
+  grade: FormGrade;
+  history: RepSummary[];
+  durationMs: number;
+  timestampMs: number;
+}
+
+// ---------------------------------------------------------------------------
+// Custom jump exercises (jump_analysis / air_time_jump) — WebView parity:
+// same event `type` strings and field names as the front's sendDataToNative
+// payloads (CameraFeedV3 runCustomHandlerCompute).
+// ---------------------------------------------------------------------------
+
+export interface VisibleHipsInfo {
+  left: boolean;
+  right: boolean;
+}
+
+/** jump_analysis only: cm/pixel calibration established from userHeightCm. */
+export interface JumpCalibrationEvent {
+  type: 'jump_calibration';
+  calibrated: true;
+  cmPerPixel: number;
+  baselineY: number | null;
+  visibleHips: VisibleHipsInfo;
+  /** WebView literal: "Calibration complete - ready to jump". */
+  message: string;
+  timestampMs: number;
+}
+
+/** Push-off detected — measurement in progress. */
+export interface JumpStartedEvent {
+  type: 'jump_started';
+  /** WebView literal: "Jump detected - measuring height". */
+  message: string;
+  timestampMs: number;
+}
+
+/** Live/final jump height. `final: true` closes the jump (see JumpResultEvent). */
+export interface JumpHeightEvent {
+  type: 'jump_height';
+  jumpHeightCm: number;
+  baselineY?: number | null;
+  minY?: number | null;
+  measuring: boolean;
+  landed: boolean;
+  final?: boolean;
+  deltaPixels?: number;
+  sideUsed?: string | null;
+  airTimeMs?: number;
+  airTimeSeconds?: number;
+  visibleHips?: VisibleHipsInfo;
+  timestampMs: number;
+}
+
+/** Detection aborted (approach toward camera, timeout, tracking lost…). */
+export interface JumpDiscardedEvent {
+  type: 'jump_discarded';
+  reason: string;
+  userMessage: string;
+  timestampMs: number;
+}
+
+/** One completed jump (final height for jump N). */
+export interface JumpResultEvent {
+  type: 'jump_result';
+  jumpNumber: number;
+  jumpHeightCm: number;
+  airTimeMs?: number;
+  airTimeSeconds?: number;
+  baselineY?: number | null;
+  minY?: number | null;
+  deltaPixels?: number;
+  sideUsed?: string | null;
+  visibleHips?: VisibleHipsInfo;
+  timestampMs: number;
+}
+
+export interface JumpSummaryEntry {
+  jumpNumber: number;
+  jumpHeightCm: number;
+  airTimeMs?: number;
+  airTimeSeconds?: number;
+}
+
+/** Running summary of all completed jumps (emitted after each jump_result). */
+export interface JumpSummaryEvent {
+  type: 'jump_summary';
+  totalJumps: number;
+  avgJumpHeight: number;
+  maxJumpHeight: number;
+  minJumpHeight: number;
+  avgAirTimeSeconds?: number;
+  jumps: JumpSummaryEntry[];
+  timestampMs: number;
+}
+
+/**
+ * Camera / preprocess quality tier changed (AdaptiveChoice auto-downgrade,
+ * crash-guard recovery, or GL capability hint). English, for app developers.
+ */
+export interface QualityChangedEvent {
+  type: 'quality_changed';
+  previousProfile: QualityProfileId;
+  activeProfile: QualityProfileId;
+  reason:
+    | 'low_fps'
+    | 'device_capability'
+    | 'crash_guard'
+    | 'warmup_estimate'
+    | 'manual';
+  detail: string;
+  profile: QualityProfile;
+  /** Present when reason is warmup_estimate / low_fps. */
+  estimatedFps?: number | null;
+  medianInferenceMs?: number | null;
+  timestampMs: number;
+}
+
+/**
+ * Fired when mean inference FPS stays critically low. English developer alert —
+ * surface in your own telemetry / support tooling; do not show raw to end users
+ * unless you localize it.
+ */
+export interface PerformanceWarningEvent {
+  type: 'performance_warning';
+  code: 'device_too_slow';
+  message: string;
+  meanFps: number;
+  thresholdFps: number;
+  activeProfile: QualityProfileId;
+  medianInferenceMs: number | null;
+  videoSize?: string;
+  timestampMs: number;
+}
+
+/**
+ * Download progress of the pose-runtime payload (first preload, or version
+ * update). Lets the host app show a loader/progress bar during the initial
+ * ~9 MB download; never fired when the cache is already up-to-date.
+ */
+export interface RuntimeDownloadProgressEvent {
+  type: 'runtime_download_progress';
+  /** Part being downloaded (tfjs, tfjs-wasm, model, weights, pipeline, runtime). */
+  part: string;
+  completedParts: number;
+  totalParts: number;
+  /** Size of the current part, from the signed manifest. */
+  partBytes: number;
+  timestampMs: number;
+}
+
+export type PoseTrackerEvent =
+  | InitializationEvent
+  | ErrorEvent
+  | WarningEvent
+  | RuntimeDownloadProgressEvent
+  | KeypointsEvent
+  | AnglesEvent
+  | CounterEvent
+  | PostureEvent
+  | ProgressionEvent
+  | RecommendationsEvent
+  | FormScoreEvent
+  | ExerciseSummaryEvent
+  | JumpCalibrationEvent
+  | JumpStartedEvent
+  | JumpHeightEvent
+  | JumpDiscardedEvent
+  | JumpResultEvent
+  | JumpSummaryEvent
+  | QualityChangedEvent
+  | PerformanceWarningEvent;
+
+export type PoseTrackerEventType = PoseTrackerEvent['type'];
+
+export type PoseTrackerEventListener = (event: PoseTrackerEvent) => void;
+
+/**
+ * Typed per-event callbacks, convenient for `usePoseTracker({ onCounter, ... })`.
+ * Also accepts {@link onMessage} for classic PoseTracker WebView JSON parity.
+ */
+export interface PoseTrackerCallbacks {
+  onInitialization?: (event: InitializationEvent) => void;
+  onError?: (event: ErrorEvent) => void;
+  onWarning?: (event: WarningEvent) => void;
+  onKeypoints?: (event: KeypointsEvent) => void;
+  onAngles?: (event: AnglesEvent) => void;
+  onCounter?: (event: CounterEvent) => void;
+  onPosture?: (event: PostureEvent) => void;
+  onProgression?: (event: ProgressionEvent) => void;
+  onRecommendations?: (event: RecommendationsEvent) => void;
+  onFormScore?: (event: FormScoreEvent) => void;
+  onExerciseSummary?: (event: ExerciseSummaryEvent) => void;
+  onJumpCalibration?: (event: JumpCalibrationEvent) => void;
+  onJumpStarted?: (event: JumpStartedEvent) => void;
+  onJumpHeight?: (event: JumpHeightEvent) => void;
+  onJumpDiscarded?: (event: JumpDiscardedEvent) => void;
+  onJumpResult?: (event: JumpResultEvent) => void;
+  onJumpSummary?: (event: JumpSummaryEvent) => void;
+  onQualityChanged?: (event: QualityChangedEvent) => void;
+  onPerformanceWarning?: (event: PerformanceWarningEvent) => void;
+  onRuntimeDownloadProgress?: (event: RuntimeDownloadProgressEvent) => void;
+  /**
+   * Classic PoseTracker `sendDataToNative` JSON stream (same `type` / field
+   * names as the WebView product). Fires for every typed event.
+   */
+  onMessage?: (message: import('../events/classicMessage').ClassicNativeMessage) => void;
+}

package/src/types/features.ts

@@ -0,0 +1,176 @@
+/**
+ * Host-selectable tracking features — SDK port of the PoseTracker WebView
+ * query params (`/pose_tracker/tracking?angles=true&…`) with the SAME plan
+ * gating and the SAME error messages as `TrackingAppV3`.
+ *
+ * Rules (mirroring the WebView product):
+ * - Without an API key the SDK always runs keypoints-only (offline, free,
+ *   no gating) — pose-only mode streams `keypoints` unconditionally.
+ * - `angles`, `recommendations`, `progression` require a PAID plan
+ *   (anything but `free`).
+ * - `keypoints` DURING an exercise session requires a paid plan too
+ *   (free may stream keypoints only in pose-only mode, i.e. no exercise).
+ * - `blazepose` / `poseEngine` / `mediapipeModel` / `poseBackend` /
+ *   `runInWorker` are NOT part of this SDK (MoveNet Lightning only) and are
+ *   rejected with a clear error.
+ */
+
+import type { MinGrade } from './events';
+
+export interface PoseTrackerFeatures {
+  /**
+   * Stream `angles` events during an exercise session. Default `false`
+   * (WebView parity: `angles="false"`). Paid plans only.
+   */
+  angles?: boolean;
+  /**
+   * Stream `recommendations` events (form advice) during an exercise
+   * session. Default `false`. Paid plans only.
+   */
+  recommendations?: boolean;
+  /**
+   * Stream `progression` events (0–100 within the rep) during an exercise
+   * session. Default `false`. Paid plans only.
+   */
+  progression?: boolean;
+  /**
+   * Stream raw `keypoints` events DURING an exercise session. Default
+   * `false` (WebView parity: free plans cannot combine keypoints with an
+   * exercise). Outside a session (pose-only mode) keypoints always stream —
+   * that is the SDK's free offline base and is never gated.
+   */
+  keypoints?: boolean;
+  /**
+   * Only count reps whose form grade is at or above this letter (`A` best).
+   * WebView parity: `minGrade` query param (`A`…`D` only). Works on all
+   * plans that can run the exercise.
+   */
+  minGrade?: MinGrade;
+}
+
+/** Feature keys after defaults are applied. */
+export interface ResolvedFeatures {
+  angles: boolean;
+  recommendations: boolean;
+  progression: boolean;
+  keypoints: boolean;
+  minGrade: MinGrade | null;
+}
+
+/** WebView-parity defaults: everything opt-in, like the query params. */
+export const DEFAULT_FEATURES: ResolvedFeatures = {
+  angles: false,
+  recommendations: false,
+  progression: false,
+  keypoints: false,
+  minGrade: null,
+};
+
+const KNOWN_FEATURE_KEYS = new Set<string>([
+  'angles',
+  'recommendations',
+  'progression',
+  'keypoints',
+  'minGrade',
+]);
+
+/**
+ * WebView params that this SDK deliberately does NOT ship (one SDK, one
+ * model: MoveNet Lightning). Passing them (possible from untyped JS hosts)
+ * produces a clear `feature_not_supported` error.
+ */
+const UNSUPPORTED_FEATURE_HINTS: Record<string, string> = {
+  blazepose: 'BlazePose',
+  poseEngine: 'pose engine selection (MediaPipe/PoseLandmarker)',
+  mediapipeModel: 'MediaPipe model selection',
+  poseBackend: 'pose backend selection',
+  runInWorker: 'worker thread selection',
+};
+
+// ---------------------------------------------------------------------------
+// Error messages — EXACT copies of PoseTrackerFront/components/v3/TrackingAppV3.js
+// so hosts migrating from the WebView see identical strings.
+// ---------------------------------------------------------------------------
+
+/** Free plan requested developer features (angles/recommendations/progression/keypoints+exercise). */
+export const FREE_PLAN_FEATURES_MESSAGE =
+  'You cannot use developer features. (visit: https://posetracker.gitbook.io/posetracker-api/tracking-endpoint)';
+
+/** Missing/invalid API token when key-gated features are requested. */
+export const INVALID_TOKEN_MESSAGE =
+  'Invalid params. Please refer to the documentation and set token=YOUR API_KEY et exercise=A correct exercise. (visit: https://posetracker.gitbook.io/posetracker-api/tracking-endpoint)';
+
+/** Reference movement and exercise are mutually exclusive (Phase 2 surface). */
+export const COMBINED_REFERENCE_EXERCISE_MESSAGE =
+  'You cannot combine reference & exercise. Please check the documentation.';
+
+/** SDK-specific: the requested WebView feature does not exist in this SDK. */
+export function featureNotSupportedMessage(key: string): string {
+  const hint = UNSUPPORTED_FEATURE_HINTS[key] ?? `'${key}'`;
+  return (
+    `The '${key}' option (${hint}) is not available in this SDK. ` +
+    'This SDK ships MoveNet Lightning only — pose engine and model cannot be changed. ' +
+    'Remove the option, or use the PoseTracker WebView product if you need it. ' +
+    '(visit: https://posetracker.gitbook.io/posetracker-api/tracking-endpoint)'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply WebView-parity defaults and detect unsupported keys passed by
+ * untyped JS hosts (e.g. `{ blazepose: true }`).
+ */
+export function resolveFeatures(input: PoseTrackerFeatures | undefined): {
+  features: ResolvedFeatures;
+  unsupportedKeys: string[];
+} {
+  if (!input) {
+    return { features: { ...DEFAULT_FEATURES }, unsupportedKeys: [] };
+  }
+  const unsupportedKeys = Object.keys(input).filter((k) => !KNOWN_FEATURE_KEYS.has(k));
+  return {
+    features: {
+      angles: input.angles === true,
+      recommendations: input.recommendations === true,
+      progression: input.progression === true,
+      keypoints: input.keypoints === true,
+      minGrade: input.minGrade ?? null,
+    },
+    unsupportedKeys,
+  };
+}
+
+/**
+ * Which requested features a `free` plan is NOT allowed to use — exact port
+ * of the TrackingAppV3 condition (keypoints only blocked when an exercise
+ * is involved; pose-only keypoints stay free).
+ */
+export function freeBlockedFeatures(
+  features: ResolvedFeatures,
+  options: { withExercise: boolean },
+): string[] {
+  const blocked: string[] = [];
+  if (features.angles) blocked.push('angles');
+  if (features.recommendations) blocked.push('recommendations');
+  if (features.progression) blocked.push('progression');
+  if (features.keypoints && options.withExercise) blocked.push('keypoints');
+  return blocked;
+}
+
+/** True for every plan type except `free` (developer / company / custom). */
+export function isPaidPlan(planType: string | null | undefined): boolean {
+  return typeof planType === 'string' && planType.length > 0 && planType !== 'free';
+}
+
+/**
+ * Whether the live camera overlay should show the PoseTracker watermark.
+ * Shown for keyless (null), `free`, and any non-paid plan. Hidden for paid
+ * plans (`developer`, `company`, `enterprise`, custom, …) — same rule as
+ * {@link isPaidPlan}.
+ */
+export function shouldShowWatermark(planType: string | null | undefined): boolean {
+  return !isPaidPlan(planType);
+}