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

package/lib/api/configure.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Handshake client: `configure(apiToken)` calls the Strapi backend, which
+ * validates the API token (plan/quota) and returns the `SdkManifest` —
+ * exercise configs, engine bundle descriptor, pose-runtime payload
+ * descriptor, model profiles, reference movements. All server-driven
+ * behavior flows from this single call.
+ *
+ * Keyless mode (`apiToken` null): the backend returns the PUBLIC manifest —
+ * pose-runtime descriptor only, no session/engine/exercises. This is how
+ * keypoints-only installs bootstrap the pose estimation payload.
+ */
+import { SDK_VERSION } from '../sdkVersion';
+import type { ConfigureRequest, PoseModelProfile, SdkManifest } from '../types/manifest';
+export declare const SDK_NAME: "posetracker-rn-light";
+export { SDK_VERSION };
+/** Overridable for staging/self-hosted backends. */
+export declare const DEFAULT_BASE_URL = "https://movelytics-strapi-c78a339b7070.herokuapp.com";
+export interface ConfigureOptions {
+    baseUrl?: string;
+    poseModelProfile?: PoseModelProfile;
+    locale?: string;
+    /** Local cache versions, so the backend can answer `upToDate` per module. */
+    localVersions?: ConfigureRequest['localVersions'];
+}
+export declare class ConfigureError extends Error {
+    readonly code: 'invalid_token' | 'quota_exceeded' | 'network' | 'internal';
+    constructor(code: 'invalid_token' | 'quota_exceeded' | 'network' | 'internal', message: string);
+}
+export declare function configure(apiToken: string | null, options?: ConfigureOptions): Promise<SdkManifest>;

package/lib/api/configure.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Handshake client: `configure(apiToken)` calls the Strapi backend, which
+ * validates the API token (plan/quota) and returns the `SdkManifest` —
+ * exercise configs, engine bundle descriptor, pose-runtime payload
+ * descriptor, model profiles, reference movements. All server-driven
+ * behavior flows from this single call.
+ *
+ * Keyless mode (`apiToken` null): the backend returns the PUBLIC manifest —
+ * pose-runtime descriptor only, no session/engine/exercises. This is how
+ * keypoints-only installs bootstrap the pose estimation payload.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigureError = exports.DEFAULT_BASE_URL = exports.SDK_VERSION = exports.SDK_NAME = void 0;
+exports.configure = configure;
+const react_native_1 = require("react-native");
+const sdkVersion_1 = require("../sdkVersion");
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return sdkVersion_1.SDK_VERSION; } });
+exports.SDK_NAME = 'posetracker-rn-light';
+/** Overridable for staging/self-hosted backends. */
+exports.DEFAULT_BASE_URL = 'https://movelytics-strapi-c78a339b7070.herokuapp.com';
+class ConfigureError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ConfigureError';
+    }
+}
+exports.ConfigureError = ConfigureError;
+async function configure(apiToken, options = {}) {
+    const baseUrl = (options.baseUrl ?? exports.DEFAULT_BASE_URL).replace(/\/$/, '');
+    const body = {
+        ...(apiToken ? { apiToken } : {}),
+        sdkName: exports.SDK_NAME,
+        sdkVersion: sdkVersion_1.SDK_VERSION,
+        targetPlatform: react_native_1.Platform.OS === 'ios' ? 'ios' : 'android',
+        poseModelProfile: options.poseModelProfile ?? 'AdaptiveChoice',
+        locale: options.locale,
+        localVersions: options.localVersions,
+    };
+    let response;
+    try {
+        response = await fetch(`${baseUrl}/api/sdk/configure`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        throw new ConfigureError('network', `Handshake request failed: ${String(err)}`);
+    }
+    if (response.status === 401 || response.status === 403) {
+        // The 401 body carries `revoked: true` — the caller purges the sealed
+        // engine/session caches (a revoked key must not keep the engine alive).
+        throw new ConfigureError('invalid_token', 'Invalid, revoked or unauthorized API token.');
+    }
+    if (response.status === 429) {
+        throw new ConfigureError('quota_exceeded', 'API call quota exceeded for the current plan.');
+    }
+    if (!response.ok) {
+        throw new ConfigureError('internal', `Handshake failed with HTTP ${response.status}.`);
+    }
+    return (await response.json());
+}

package/lib/api/skeleton.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Fetch a custom skeleton overlay by Strapi `api_uuid`
+ * (WebView `?skeleton=<uuid>` parity).
+ */
+import type { SkeletonDefinition } from '../types/skeleton';
+export interface FetchSkeletonOptions {
+    baseUrl?: string;
+}
+export declare class SkeletonFetchError extends Error {
+    readonly code: 'not_found' | 'network' | 'invalid';
+    constructor(code: 'not_found' | 'network' | 'invalid', message: string);
+}
+/**
+ * GET /api/sdk/skeleton?uuid=…
+ * Returns the overlay definition or throws {@link SkeletonFetchError}.
+ */
+export declare function fetchSkeletonDefinition(uuid: string, options?: FetchSkeletonOptions): Promise<SkeletonDefinition>;

package/lib/api/skeleton.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Fetch a custom skeleton overlay by Strapi `api_uuid`
+ * (WebView `?skeleton=<uuid>` parity).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkeletonFetchError = void 0;
+exports.fetchSkeletonDefinition = fetchSkeletonDefinition;
+const configure_1 = require("./configure");
+class SkeletonFetchError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SkeletonFetchError';
+    }
+}
+exports.SkeletonFetchError = SkeletonFetchError;
+/**
+ * GET /api/sdk/skeleton?uuid=…
+ * Returns the overlay definition or throws {@link SkeletonFetchError}.
+ */
+async function fetchSkeletonDefinition(uuid, options = {}) {
+    const id = uuid.trim();
+    if (!id || id === 'true' || id === 'false') {
+        throw new SkeletonFetchError('invalid', 'skeleton uuid is required');
+    }
+    const baseUrl = (options.baseUrl ?? configure_1.DEFAULT_BASE_URL).replace(/\/$/, '');
+    let response;
+    try {
+        response = await fetch(`${baseUrl}/api/sdk/skeleton?uuid=${encodeURIComponent(id)}`);
+    }
+    catch (err) {
+        throw new SkeletonFetchError('network', `Skeleton fetch failed: ${String(err)}`);
+    }
+    if (response.status === 404) {
+        throw new SkeletonFetchError('not_found', `Skeleton '${id}' not found`);
+    }
+    if (!response.ok) {
+        throw new SkeletonFetchError('network', `Skeleton fetch HTTP ${response.status}`);
+    }
+    const body = (await response.json());
+    if (!body?.keypoints || !body?.keypoint_lines || !body?.circles || !body?.lines) {
+        throw new SkeletonFetchError('invalid', 'Skeleton payload incomplete');
+    }
+    return {
+        keypoints: body.keypoints,
+        keypoint_lines: body.keypoint_lines,
+        keypoint_angles: body.keypoint_angles ?? [],
+        circles: body.circles,
+        lines: body.lines,
+        angles: body.angles,
+    };
+}

package/lib/api/track.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Usage tracking client — `POST /api/sdk/track`.
+ *
+ * One call per real usage: when the camera starts with the model ready
+ * (`camera_start`), NOT on handshake and NOT on preload. Server-side, a
+ * valid API key increments the same usage counters as the WebView API
+ * (quota-checked) and inserts a `sdk-usage-event` row with the params;
+ * keyless calls insert an anonymous row.
+ *
+ * Delivery rules (see ARCHITECTURE.md §Offline):
+ * - metered (with API key): the track call MUST succeed online — offline
+ *   metered sessions are refused because usage cannot be counted;
+ * - anonymous (no key): fire-and-forget with a local retry queue, flushed
+ *   on the next connection.
+ */
+import { type KeyValueStore } from '../engine/EngineLoader';
+export declare class TrackError extends Error {
+    readonly code: 'invalid_token' | 'quota_exceeded' | 'network' | 'internal';
+    constructor(code: 'invalid_token' | 'quota_exceeded' | 'network' | 'internal', message: string);
+}
+export interface TrackRequest {
+    event?: string;
+    apiToken?: string | null;
+    params?: Record<string, unknown>;
+}
+export interface TrackResponse {
+    tracked: boolean;
+    anonymous?: boolean;
+    monthly_usage_counter?: number;
+    remainingCalls?: number;
+    type?: string;
+}
+export interface UsageTrackerOptions {
+    baseUrl?: string;
+    keyValueStore?: KeyValueStore | null;
+    fetchFn?: typeof fetch;
+}
+export declare class UsageTracker {
+    private readonly baseUrl;
+    private readonly kv;
+    private readonly fetchFn;
+    constructor(options?: UsageTrackerOptions);
+    /**
+     * Metered track (API key): throws on failure — the caller refuses to start
+     * a metered session it cannot count.
+     */
+    trackMetered(request: TrackRequest & {
+        apiToken: string;
+    }): Promise<TrackResponse>;
+    /**
+     * Anonymous track (no key): never throws. Failed sends are queued locally
+     * and flushed on the next connection.
+     */
+    trackAnonymous(request?: TrackRequest): Promise<void>;
+    /** Send queued anonymous events (called on preload and after online sends). */
+    flushQueue(): Promise<void>;
+    private post;
+    private readQueue;
+    private writeQueue;
+    private enqueue;
+}

package/lib/api/track.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Usage tracking client — `POST /api/sdk/track`.
+ *
+ * One call per real usage: when the camera starts with the model ready
+ * (`camera_start`), NOT on handshake and NOT on preload. Server-side, a
+ * valid API key increments the same usage counters as the WebView API
+ * (quota-checked) and inserts a `sdk-usage-event` row with the params;
+ * keyless calls insert an anonymous row.
+ *
+ * Delivery rules (see ARCHITECTURE.md §Offline):
+ * - metered (with API key): the track call MUST succeed online — offline
+ *   metered sessions are refused because usage cannot be counted;
+ * - anonymous (no key): fire-and-forget with a local retry queue, flushed
+ *   on the next connection.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageTracker = exports.TrackError = void 0;
+const react_native_1 = require("react-native");
+const configure_1 = require("./configure");
+const EngineLoader_1 = require("../engine/EngineLoader");
+const QUEUE_KEY = 'posetracker.track.queue';
+const QUEUE_LIMIT = 100;
+class TrackError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'TrackError';
+    }
+}
+exports.TrackError = TrackError;
+class UsageTracker {
+    constructor(options = {}) {
+        this.baseUrl = (options.baseUrl ?? configure_1.DEFAULT_BASE_URL).replace(/\/$/, '');
+        this.kv =
+            options.keyValueStore !== undefined ? options.keyValueStore : (0, EngineLoader_1.createAsyncKeyValueStore)();
+        this.fetchFn = options.fetchFn ?? fetch;
+    }
+    /**
+     * Metered track (API key): throws on failure — the caller refuses to start
+     * a metered session it cannot count.
+     */
+    async trackMetered(request) {
+        return this.post({
+            event: request.event ?? 'camera_start',
+            apiToken: request.apiToken,
+            platform: react_native_1.Platform.OS,
+            sdkVersion: configure_1.SDK_VERSION,
+            params: request.params,
+        });
+    }
+    /**
+     * Anonymous track (no key): never throws. Failed sends are queued locally
+     * and flushed on the next connection.
+     */
+    async trackAnonymous(request = {}) {
+        const payload = {
+            event: request.event ?? 'camera_start',
+            platform: react_native_1.Platform.OS,
+            sdkVersion: configure_1.SDK_VERSION,
+            params: request.params,
+            queuedAtMs: Date.now(),
+        };
+        try {
+            await this.post({ ...payload });
+            // A send just worked: opportunistically drain older queued events.
+            void this.flushQueue();
+        }
+        catch {
+            await this.enqueue(payload);
+        }
+    }
+    /** Send queued anonymous events (called on preload and after online sends). */
+    async flushQueue() {
+        const queue = await this.readQueue();
+        if (queue.length === 0) {
+            return;
+        }
+        const remaining = [];
+        for (const item of queue) {
+            try {
+                await this.post({ ...item, params: { ...(item.params ?? {}), queuedAtMs: item.queuedAtMs } });
+            }
+            catch {
+                remaining.push(item);
+            }
+        }
+        await this.writeQueue(remaining);
+    }
+    // -------------------------------------------------------------------------
+    async post(body) {
+        let response;
+        try {
+            response = await this.fetchFn(`${this.baseUrl}/api/sdk/track`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw new TrackError('network', `Usage tracking request failed: ${String(err)}`);
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new TrackError('invalid_token', 'Invalid, revoked or unauthorized API token.');
+        }
+        if (response.status === 429) {
+            throw new TrackError('quota_exceeded', 'API call quota exceeded for the current plan.');
+        }
+        if (!response.ok) {
+            throw new TrackError('internal', `Usage tracking failed with HTTP ${response.status}.`);
+        }
+        return (await response.json());
+    }
+    async readQueue() {
+        try {
+            const raw = await this.kv?.getItem(QUEUE_KEY);
+            if (!raw) {
+                return [];
+            }
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async writeQueue(queue) {
+        try {
+            if (queue.length === 0) {
+                await this.kv?.removeItem(QUEUE_KEY);
+            }
+            else {
+                await this.kv?.setItem(QUEUE_KEY, JSON.stringify(queue.slice(-QUEUE_LIMIT)));
+            }
+        }
+        catch {
+            // Queue persistence is best-effort.
+        }
+    }
+    async enqueue(item) {
+        const queue = await this.readQueue();
+        queue.push(item);
+        await this.writeQueue(queue);
+    }
+}
+exports.UsageTracker = UsageTracker;

package/lib/backends/PoseBackend.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Inference backend abstraction.
+ *
+ * v1 ships a single implementation (`TfjsMoveNetBackend`, TF.js +
+ * bundleResourceIO). The interface is deliberately minimal so a native
+ * TFLite backend (react-native-fast-tflite + custom models downloaded from
+ * the manifest) can be plugged in later without touching the engine or the
+ * provider: anything that turns an input frame into a `Pose` qualifies.
+ */
+import type { Pose } from '../types/pose';
+import type { ModelDescriptor } from '../types/manifest';
+import type { AccelerationDiagnostics } from '../types/acceleration';
+/**
+ * Input frame handed to the backend. For the TF.js backend this is a
+ * `tf.Tensor3D` ([height, width, 3], int32/float32). Kept opaque here so the
+ * interface does not force a TF.js dependency on future native backends
+ * (which would receive a native frame/buffer reference instead).
+ */
+export type PoseInputFrame = unknown;
+export interface PoseBackendInitOptions {
+    /** Model resolved from the manifest for the active profile. */
+    model: ModelDescriptor;
+    /**
+     * Local filesystem path of a downloaded model archive, when the manifest
+     * provided one and it passed integrity validation. Undefined = use the
+     * model bundled in the SDK package.
+     */
+    localModelPath?: string;
+}
+export interface PoseBackend {
+    readonly name: string;
+    /** Prepare the runtime (TF.js ready + backend selection for tfjs). */
+    init(options: PoseBackendInitOptions): Promise<void>;
+    /**
+     * Run 1–2 dummy inferences so shaders/kernels are compiled before the
+     * first real camera frame. No-op if already warm.
+     */
+    warmup(): Promise<void>;
+    /** Estimate a single pose from an input frame. */
+    estimatePose(frame: PoseInputFrame): Promise<Pose | null>;
+    /** Release model and GPU resources. */
+    dispose(): Promise<void>;
+    /**
+     * Optional: GPU-acceleration verdict + diagnostics collected during
+     * `warmup()` (see docs/ANDROID_GL_ACCELERATION.md). Backends that cannot
+     * introspect their accelerator (or a future native TFLite backend using
+     * GPU/NNAPI delegates) may omit it or return null before warm-up.
+     */
+    getAcceleration?(): AccelerationDiagnostics | null;
+}

package/lib/backends/PoseBackend.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Inference backend abstraction.
+ *
+ * v1 ships a single implementation (`TfjsMoveNetBackend`, TF.js +
+ * bundleResourceIO). The interface is deliberately minimal so a native
+ * TFLite backend (react-native-fast-tflite + custom models downloaded from
+ * the manifest) can be plugged in later without touching the engine or the
+ * provider: anything that turns an input frame into a `Pose` qualifies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/backends/vision/VisionPoseBackend.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Apple Vision implementation of `PoseBackend` (iOS only).
+ *
+ * Uses `VNDetectHumanBodyPoseRequest` via a VisionCamera frame-processor
+ * plugin shipped in this package's `ios/` folder. Up to 19 anatomical
+ * joints (COCO-17 + `neck` + `root`). Primary fast path is
+ * `PoseCameraView` → worklet → native plugin (CVPixelBuffer, no RGB copy).
+ *
+ * Never loaded in Expo Go (`isExpoGo()` guard). On Android,
+ * `init()` throws {@link VisionUnavailableError} so the client can fall
+ * back to TFLite / TF.js when selection is `'auto'`.
+ */
+import type { PoseBackend, PoseBackendInitOptions, PoseInputFrame } from '../PoseBackend';
+import type { Pose } from '../../types/pose';
+import type { AccelerationDiagnostics, AccelerationState, DiagnosticListener } from '../../types/acceleration';
+import { type VisionFrameProcessorPlugin } from './optionalVision';
+import { type VisionPluginResult } from './mapVisionJoints';
+/** Thrown when Apple Vision cannot run (wrong platform, Expo Go, missing pod). */
+export declare class VisionUnavailableError extends Error {
+    constructor(message: string);
+}
+export interface VisionPoseBackendOptions {
+    maxAcceptableInferenceMs?: number;
+    onDiagnostic?: DiagnosticListener;
+    onAccelerationChange?: (state: AccelerationState) => void;
+}
+/**
+ * Opaque frame accepted on the JS path: either a VisionCamera `Frame`
+ * (preferred — passed through to the plugin) or a pre-decoded
+ * {@link VisionPluginResult} (for tests / hosts that already ran Vision).
+ */
+export type VisionPoseInput = VisionPluginResult | {
+    __visionCameraFrame: true;
+};
+export declare class VisionPoseBackend implements PoseBackend {
+    private readonly options;
+    readonly name = "apple-vision";
+    private plugin;
+    private warm;
+    private acceleration;
+    private inferenceTimesMs;
+    private reasons;
+    private readonly maxAcceptableInferenceMs;
+    private readonly onDiagnostic;
+    private readonly onAccelerationChange;
+    constructor(options?: VisionPoseBackendOptions);
+    init(_options: PoseBackendInitOptions): Promise<void>;
+    /**
+     * Vision has no separate model load — warm-up records the accelerator
+     * verdict. Real timings come from the first camera frames via
+     * {@link recordInferenceTime}.
+     */
+    warmup(): Promise<void>;
+    /**
+     * JS-path estimation. Accepts:
+     * - a VisionCamera `Frame` (has `.width`/`.height` and is callable via plugin);
+     * - a precomputed {@link VisionPluginResult} `{ joints }`.
+     *
+     * Prefer `PoseCameraView` (worklet) for production — this path is for
+     * TensorCamera-style hosts and unit tests.
+     */
+    estimatePose(frame: PoseInputFrame): Promise<Pose | null>;
+    getAcceleration(): AccelerationDiagnostics | null;
+    dispose(): Promise<void>;
+    /** Plugin handle for PoseCameraView worklets. */
+    getFrameProcessorPlugin(): VisionFrameProcessorPlugin | null;
+    /** Feed live inference timings from the camera worklet into diagnostics. */
+    recordInferenceTime(ms: number): void;
+    private setAcceleration;
+    private noteReason;
+    private requirePlugin;
+}