@modelhealth/sdk 0.1.0 → 0.1.7

package/README.md

@@ -1,40 +1,315 @@
-# Model Health SDK
+# Model Health SDK for TypeScript
 
-TypeScript/JavaScript SDK for biomechanical analysis from smartphone videos.
+TypeScript/JavaScript SDK for the Model Health biomechanics platform.
+
+## Features
+
+- 📦 **Type-safe**: Full TypeScript type definitions
+- 🌐 **Cross-platform**: Works in browsers, Node.js, React, Vue, Svelte, etc.
+- 🔒 **Secure**: Pluggable storage system for authentication tokens
+- ⚡ **Fast**: WASM performance with JavaScript ergonomics
 
 ## Installation
+
 ```bash
 npm install @modelhealth/sdk
 ```
 
 ## Quick Start
+
 ```typescript
 import { ModelHealthService } from '@modelhealth/sdk';
 
-const service = new ModelHealthService();
-await service.login('user@example.com', 'password');
+// Create client
+const client = new ModelHealthService();
+await client.init();
+
+// Login
+const result = await client.login('username', 'password');
+if (result === 'verification_r_equired') {
+  await client.verify('123456', true);
+}
+
+// Get sessions
+const sessions = await client.sessionList();
+console.log(sessions);
+```
+
+## Configuration
+
+### Development Mode
+
+```typescript
+const client = new ModelHealthService({
+  development: true, // Use development API endpoint
+});
+```
+
+### Custom Token Storage
+
+By default, the SDK uses in-memory token storage (tokens are lost on page refresh). For production, implement secure token storage:
+
+```typescript
+import { ModelHealthService, TokenStorage } from '@modelhealth/sdk';
+
+// Option 1: Use provided LocalStorage implementation (basic security)
+import { LocalStorageTokenStorage } from '@modelhealth/sdk';
+
+const client = new ModelHealthService({
+  storage: new LocalStorageTokenStorage(),
+});
+
+// Option 2: Implement your own secure storage
+class SecureTokenStorage implements TokenStorage {
+  async getToken(): Promise<string | null> {
+    // Your secure storage implementation
+    // Examples: encrypted IndexedDB, secure cookies, etc.
+  }
+
+  async setToken(token: string): Promise<void> {
+    // Store token securely
+  }
+
+  async removeToken(): Promise<void> {
+    // Remove token
+  }
+}
+
+const secureClient = new ModelHealthService({
+  storage: new SecureTokenStorage(),
+});
 ```
 
-## Documentation
+### Storage Security Recommendations
 
-**Full API Documentation**: [docs.modelhealth.io](https://docs.modelhealth.io/typescript)
+**Development:**
+- `MemoryTokenStorage`: Quick testing (default, not persistent)
+- `LocalStorageTokenStorage`: Simple persistence (basic security)
 
-## Examples
+**Production:**
+- Encrypted IndexedDB with Web Crypto API
+- HttpOnly cookies with SameSite protection and CSRF tokens
+- Platform-specific secure storage (React Native: Keychain/Keystore)
+
+**Never:**
+- Store tokens in plain localStorage in production
+- Log tokens to console
+- Embed tokens in URLs
+
+## API Reference
+
+### Authentication
+
+```typescript
+// Register new account
+await client.register({
+  username: 'user',
+  email: 'user@example.com',
+  password: 'secure_password',
+  firstName: 'John',
+  lastName: 'Doe',
+  newsletter: true,
+  // Optional fields
+  country: 'US',
+  institution: 'University',
+  profession: 'Researcher',
+  unit: 'metric',
+});
+
+// Login
+const result = await client.login('username', 'password');
+
+// Verify 2FA code
+if (result === 'verification_required') {
+  await client.verify('123456', true);
+}
+
+// Check authentication status
+const isAuth = await client.isAuthenticated();
+
+// Logout
+await client.logout();
+
+// Manual token management
+const token = client.getToken();
+client.setToken('your-token');
+```
+
+### Sessions
+
+```typescript
+// Get all sessions
+const sessions = await client.sessionList();
+
+// Get specific session with trials
+const session = await client.getSession('session-id');
+
+// Create new session
+const newSession = await client.createSession();
+```
+
+### Subjects
+
+```typescript
+// Get all subjects
+const subjects = await client.subjectList();
+```
 
-See the [examples directory](https://github.com/model-health/model-health/tree/main/examples) in the GitHub repository for complete working implementations.
+### Trials
 
-To run examples locally:
+```typescript
+// Get trials for a session
+const trials = await client.trialList('session-id');
+
+// Download trial videos
+const videos = await client.downloadTrialVideos(
+  trial,
+  'raw' // or 'synced'
+);
+
+// Download result data
+const results = await client.downloadTrialResultData(
+  trial,
+  ['motData', 'csvData']
+);
+```
+
+### Utilities
+
+```typescript
+// Convert MOT to CSV
+const motData = new Uint8Array([...]); // MOT file data
+const csv = ModelHealthService.motToCsv(motData);
+```
+
+## React Example
+
+```tsx
+import { useState, useEffect } from 'react';
+import { ModelHealthService, Session } from '@modelhealth/sdk';
+
+function App() {
+  const [client] = useState(() => new ModelHealthService());
+  const [sessions, setSessions] = useState<Session[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    async function init() {
+      await client.init();
+      
+      // Try to restore session
+      const isAuth = await client.isAuthenticated();
+      if (!isAuth) {
+        // Redirect to login
+        return;
+      }
+      
+      // Load sessions
+      const data = await client.sessionList();
+      setSessions(data);
+      setLoading(false);
+    }
+    
+    init();
+  }, [client]);
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>Sessions</h1>
+      {sessions.map(session => (
+        <div key={session.id}>{session.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Vite Configuration
+
+If using Vite, add WASM support:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import wasm from 'vite-plugin-wasm';
+import topLevelAwait from 'vite-plugin-top-level-await';
+
+export default defineConfig({
+  plugins: [
+    wasm(),
+    topLevelAwait(),
+  ],
+});
+```
+
+Install plugins:
 ```bash
-git clone https://github.com/model-health/model-health.git
-cd model-health/examples
+npm install -D vite-plugin-wasm vite-plugin-top-level-await
+```
+
+## TypeScript Types
+
+All types are fully documented with JSDoc comments. Import types as needed:
+
+```typescript
+import type {
+  Session,
+  Subject,
+  Trial,
+  LoginResult,
+  RegistrationParameters,
+  CheckerboardDetails,
+  // ... etc
+} from '@modelhealth/sdk';
+```
+
+## Building from Source
+
+```bash
+# Install dependencies
+npm install
+
+# Build WASM and TypeScript
+npm run build
+
+# Development build with watch mode
+npm run dev
+```
+
+### Requirements
+
+- Node.js 18+
+- Rust 1.70+
+- wasm-pack (`cargo install wasm-pack`)
+
+## Platform Support
+
+- ✅ Modern browsers (Chrome, Firefox, Safari, Edge)
+- ✅ Node.js 18+ (with WASM support)
+- ✅ React, Vue, Svelte, Angular
+- ✅ React Native (with WASM bridge)
+- ✅ Electron
+
+## Error Handling
+
+All async methods can throw errors. Always use try-catch:
+
+```typescript
+try {
+  await client.login('username', 'password');
+} catch (error) {
+  console.error('Login failed:', error);
+}
 ```
 
-## Swift SDK
+## License
 
-Looking for the Swift/iOS SDK? See the [main repository](https://github.com/model-health/model-health) for Swift Package Manager installation.
+MIT © Model Health
 
 ## Support
 
-- **Issues**: [GitHub Issues](https://github.com/model-health/model-health/issues)
-- **Documentation**: [docs.modelhealth.io](https://docs.modelhealth.io)
-- **Email**: support@modelhealth.io
+- Documentation: https://docs.modelhealth.io
+- Issues: https://github.com/model-health/model-health/issues
+- Email: support@modelhealth.io

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelhealth/sdk",
-  "version": "0.1.0",
+  "version": "0.1.7",
   "description": "Model Health SDK for TypeScript/JavaScript",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,6 +13,13 @@
     "model_health_wasm_bg.wasm",
     "model_health_wasm_bg.wasm.d.ts"
   ],
+  "scripts": {
+    "build:wasm": "wasm-pack build ../model-health-wasm --target web --out-dir ../../model-health-ts/wasm --scope modelhealth",
+    "build:ts": "tsc",
+    "build": "npm run build:wasm && npm run build:ts",
+    "dev": "npm run build:wasm -- --dev && tsc --watch",
+    "clean": "rm -rf dist wasm node_modules"
+  },
   "keywords": [
     "modelhealth",
     "biomechanics",
@@ -23,6 +30,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/model-health/model-health.git"
+    "url": "https://github.com/model-health/model-health"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typedoc": "^0.28.15",
+    "typescript": "^5.3.0"
   }
 }

package/{model_health_wasm.d.ts → wasm/model_health_wasm.d.ts}

@@ -46,46 +46,49 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_modelhealthservice_free: (a: number, b: number) => void;
-    readonly calibrateCamera: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => number;
-    readonly calibrateNeutralPose: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => number;
-    readonly modelhealthservice_createSession: (a: number) => number;
-    readonly modelhealthservice_createSubject: (a: number, b: number) => number;
-    readonly modelhealthservice_deleteActivity: (a: number, b: number) => number;
-    readonly modelhealthservice_downloadAnalysisResult: (a: number, b: number, c: number, d: number) => number;
-    readonly modelhealthservice_downloadTrialResultData: (a: number, b: number, c: number) => number;
-    readonly modelhealthservice_downloadTrialVideos: (a: number, b: number, c: number) => number;
-    readonly modelhealthservice_getActivitiesForSubject: (a: number, b: number, c: number, d: number, e: number, f: number) => number;
-    readonly modelhealthservice_getActivity: (a: number, b: number, c: number) => number;
-    readonly modelhealthservice_getActivityTags: (a: number) => number;
-    readonly modelhealthservice_getAnalysisStatus: (a: number, b: number) => number;
-    readonly modelhealthservice_getSession: (a: number, b: number, c: number) => number;
-    readonly modelhealthservice_getStatus: (a: number, b: number) => number;
-    readonly modelhealthservice_getToken: (a: number, b: number) => void;
-    readonly modelhealthservice_isAuthenticated: (a: number) => number;
-    readonly modelhealthservice_login: (a: number, b: number, c: number, d: number, e: number) => number;
-    readonly modelhealthservice_logout: (a: number) => number;
-    readonly modelhealthservice_new: (a: number, b: number, c: number) => void;
-    readonly modelhealthservice_record: (a: number, b: number, c: number, d: number) => number;
-    readonly modelhealthservice_register: (a: number, b: number) => number;
-    readonly modelhealthservice_restoreToken: (a: number) => number;
-    readonly modelhealthservice_sessionList: (a: number) => number;
-    readonly modelhealthservice_setStorage: (a: number, b: number) => void;
-    readonly modelhealthservice_setToken: (a: number, b: number, c: number) => void;
-    readonly modelhealthservice_startAnalysis: (a: number, b: number, c: number, d: number) => number;
-    readonly modelhealthservice_stopRecording: (a: number, b: number) => number;
-    readonly modelhealthservice_subjectList: (a: number) => number;
-    readonly modelhealthservice_trialList: (a: number, b: number, c: number) => number;
-    readonly modelhealthservice_updateActivity: (a: number, b: number) => number;
-    readonly modelhealthservice_verify: (a: number, b: number, c: number, d: number) => number;
+    readonly calibrateCamera: (a: number, b: number, c: number, d: number, e: any, f: any, g: any) => any;
+    readonly calibrateNeutralPose: (a: number, b: number, c: number, d: number, e: any, f: any, g: any) => any;
     readonly init: () => void;
-    readonly __wasm_bindgen_func_elem_883: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_1271: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_884: (a: number, b: number, c: number) => void;
-    readonly __wbindgen_export: (a: number, b: number) => number;
-    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
-    readonly __wbindgen_export3: (a: number) => void;
-    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
-    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly modelhealthservice_createSession: (a: number) => any;
+    readonly modelhealthservice_createSubject: (a: number, b: any) => any;
+    readonly modelhealthservice_deleteActivity: (a: number, b: any) => any;
+    readonly modelhealthservice_downloadAnalysisResult: (a: number, b: any, c: number, d: number) => any;
+    readonly modelhealthservice_downloadTrialResultData: (a: number, b: any, c: any) => any;
+    readonly modelhealthservice_downloadTrialVideos: (a: number, b: any, c: any) => any;
+    readonly modelhealthservice_getActivitiesForSubject: (a: number, b: number, c: number, d: number, e: number, f: any) => any;
+    readonly modelhealthservice_getActivity: (a: number, b: number, c: number) => any;
+    readonly modelhealthservice_getActivityTags: (a: number) => any;
+    readonly modelhealthservice_getAnalysisStatus: (a: number, b: any) => any;
+    readonly modelhealthservice_getSession: (a: number, b: number, c: number) => any;
+    readonly modelhealthservice_getStatus: (a: number, b: any) => any;
+    readonly modelhealthservice_getToken: (a: number) => [number, number];
+    readonly modelhealthservice_isAuthenticated: (a: number) => any;
+    readonly modelhealthservice_login: (a: number, b: number, c: number, d: number, e: number) => any;
+    readonly modelhealthservice_logout: (a: number) => any;
+    readonly modelhealthservice_new: (a: number, b: number) => [number, number, number];
+    readonly modelhealthservice_record: (a: number, b: number, c: number, d: any) => any;
+    readonly modelhealthservice_register: (a: number, b: any) => any;
+    readonly modelhealthservice_restoreToken: (a: number) => any;
+    readonly modelhealthservice_sessionList: (a: number) => any;
+    readonly modelhealthservice_setStorage: (a: number, b: any) => void;
+    readonly modelhealthservice_setToken: (a: number, b: number, c: number) => void;
+    readonly modelhealthservice_startAnalysis: (a: number, b: any, c: any, d: any) => any;
+    readonly modelhealthservice_stopRecording: (a: number, b: any) => any;
+    readonly modelhealthservice_subjectList: (a: number) => any;
+    readonly modelhealthservice_trialList: (a: number, b: number, c: number) => any;
+    readonly modelhealthservice_updateActivity: (a: number, b: any) => any;
+    readonly modelhealthservice_verify: (a: number, b: number, c: number, d: number) => any;
+    readonly wasm_bindgen__closure__destroy__ha71e9a94fc0225d6: (a: number, b: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__haaf7ae974232f393: (a: number, b: number, c: any, d: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__hb3dc8239211a7dce: (a: number, b: number, c: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h34a416afb1ff4b4f: (a: number, b: number) => number;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __externref_table_dealloc: (a: number) => void;
     readonly __wbindgen_start: () => void;
 }