astra-sdk-web 1.0.0 → 1.1.0

package/src/services/faceMeshService.ts

@@ -0,0 +1,382 @@
+import { FaceMesh, FACEMESH_TESSELATION, FACEMESH_FACE_OVAL, FACEMESH_LEFT_EYE, FACEMESH_RIGHT_EYE, FACEMESH_LIPS } from '@mediapipe/face_mesh';
+import { drawConnectors, drawLandmarks as drawMPLandmarks } from '@mediapipe/drawing_utils';
+
+export type LivenessStage = 'CENTER' | 'LEFT' | 'RIGHT' | 'SNAP' | 'DONE';
+
+export interface FaceMeshServiceCallbacks {
+  onFaceDetected?: (faceOnCanvas: Array<{ x: number; y: number }>) => void;
+  onLivenessUpdate?: (stage: LivenessStage, instruction: string) => void;
+  onModelLoaded?: () => void;
+  onModelFailed?: (error: Error) => void;
+  onCaptureTrigger?: () => void;
+}
+
+export interface LivenessState {
+  centerHold: number;
+  leftHold: number;
+  rightHold: number;
+  snapTriggered: boolean;
+  lastResultsAt: number;
+  stage: LivenessStage;
+  livenessReady: boolean;
+}
+
+export class FaceMeshService {
+  private faceMesh: FaceMesh | null = null;
+  private videoRef: React.RefObject<HTMLVideoElement | null>;
+  private canvasRef: React.RefObject<HTMLCanvasElement | null>;
+  private callbacks: FaceMeshServiceCallbacks;
+  private cameraDriverRef: React.MutableRefObject<number | null>;
+  private livenessStateRef: React.MutableRefObject<LivenessState>;
+  private cancelled = false;
+
+  constructor(
+    videoRef: React.RefObject<HTMLVideoElement | null>,
+    canvasRef: React.RefObject<HTMLCanvasElement | null>,
+    cameraDriverRef: React.MutableRefObject<number | null>,
+    livenessStateRef: React.MutableRefObject<LivenessState>,
+    callbacks: FaceMeshServiceCallbacks
+  ) {
+    this.videoRef = videoRef;
+    this.canvasRef = canvasRef;
+    this.cameraDriverRef = cameraDriverRef;
+    this.livenessStateRef = livenessStateRef;
+    this.callbacks = callbacks;
+  }
+
+  private drawOverlays(ctx: CanvasRenderingContext2D, normalized: Array<{ x: number; y: number }>) {
+    drawConnectors(ctx, normalized as any, FACEMESH_TESSELATION, { color: "#60a5fa", lineWidth: 0.5 });
+    drawConnectors(ctx, normalized as any, FACEMESH_FACE_OVAL, { color: "#f59e0b", lineWidth: 2 });
+    drawConnectors(ctx, normalized as any, FACEMESH_LEFT_EYE, { color: "#10b981", lineWidth: 1.5 });
+    drawConnectors(ctx, normalized as any, FACEMESH_RIGHT_EYE, { color: "#ef4444", lineWidth: 1.5 });
+    drawConnectors(ctx, normalized as any, FACEMESH_LIPS, { color: "#a855f7", lineWidth: 1.5 });
+    drawMPLandmarks(ctx, normalized as any, { color: "#2563eb", lineWidth: 0, radius: 1.5 });
+  }
+
+  private processResults(results: any) {
+    const canvas = this.canvasRef.current;
+    if (!canvas) return;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+    
+    const dpr = Math.max(1, Math.min(3, window.devicePixelRatio || 1));
+    const displayW = (canvas.parentElement as HTMLElement)?.clientWidth || canvas.width;
+    const displayH = (canvas.parentElement as HTMLElement)?.clientHeight || canvas.height;
+    if (canvas.width !== Math.round(displayW * dpr) || canvas.height !== Math.round(displayH * dpr)) {
+      canvas.width = Math.round(displayW * dpr);
+      canvas.height = Math.round(displayH * dpr);
+    }
+    const w = canvas.width, h = canvas.height;
+    
+    ctx.fillStyle = 'rgb(0, 0, 0)';
+    ctx.fillRect(0, 0, w, h);
+    
+    const faces = results.multiFaceLandmarks as Array<Array<{ x: number; y: number }>> | undefined;
+    const face = faces && faces[0];
+    
+    if (face) {
+      const vid = this.videoRef.current as HTMLVideoElement | null;
+      const vidW = Math.max(1, vid?.videoWidth || displayW);
+      const vidH = Math.max(1, vid?.videoHeight || displayH);
+      const scale = Math.max(w / vidW, h / vidH);
+      const offsetX = (w - vidW * scale) / 2;
+      const offsetY = (h - vidH * scale) / 2;
+      
+      const faceOnCanvas = face.map(p => {
+        const mappedX = (p.x * vidW * scale + offsetX) / w;
+        return {
+          x: 1 - mappedX,
+          y: (p.y * vidH * scale + offsetY) / h,
+        };
+      });
+
+      const guideCX = w / 2;
+      const guideCY = h / 2;
+      const guideR = Math.min(w, h) * 0.45;
+
+      ctx.save();
+      ctx.beginPath();
+      ctx.arc(guideCX, guideCY, guideR, 0, Math.PI * 2);
+      ctx.clip();
+      ctx.drawImage(vid!, offsetX, offsetY, vidW * scale, vidH * scale);
+      ctx.restore();
+
+      this.drawOverlays(ctx, faceOnCanvas as any);
+      
+      this.livenessStateRef.current.lastResultsAt = Date.now();
+      
+      if (this.callbacks.onFaceDetected) {
+        this.callbacks.onFaceDetected(faceOnCanvas);
+      }
+
+      this.processLiveness(faceOnCanvas, w, h);
+    } else {
+      const vid = this.videoRef.current as HTMLVideoElement | null;
+      if (vid) {
+        const vidW = Math.max(1, vid?.videoWidth || displayW);
+        const vidH = Math.max(1, vid?.videoHeight || displayH);
+        const scale = Math.max(w / vidW, h / vidH);
+        const offsetX = (w - vidW * scale) / 2;
+        const offsetY = (h - vidH * scale) / 2;
+        
+        const guideCX = w / 2;
+        const guideCY = h / 2;
+        const guideR = Math.min(w, h) * 0.45;
+        
+        ctx.save();
+        ctx.beginPath();
+        ctx.arc(guideCX, guideCY, guideR, 0, Math.PI * 2);
+        ctx.clip();
+        ctx.drawImage(vid, offsetX, offsetY, vidW * scale, vidH * scale);
+        ctx.restore();
+      }
+      
+      if (Date.now() - this.livenessStateRef.current.lastResultsAt > 2000) {
+        if (this.callbacks.onLivenessUpdate) {
+          this.callbacks.onLivenessUpdate(
+            this.livenessStateRef.current.stage,
+            "No face detected. Center your face in frame with good lighting."
+          );
+        }
+      }
+    }
+  }
+
+  private processLiveness(faceOnCanvas: Array<{ x: number; y: number }>, w: number, h: number) {
+    const eyeA = faceOnCanvas[33];
+    const eyeB = faceOnCanvas[263];
+    const flipX = (p: any) => ({ x: 1 - p.x, y: p.y });
+    const eA = flipX(eyeA);
+    const eB = flipX(eyeB);
+    const n1 = faceOnCanvas[1];
+    const n4 = faceOnCanvas[4];
+    const nT = flipX(n1 && n4 ? { x: (n1.x + n4.x) / 2, y: (n1.y + n4.y) / 2 } : (n1 || n4 || faceOnCanvas[197]));
+    const leftEyeOuter = eA.x < eB.x ? eA : eB;
+    const rightEyeOuter = eA.x < eB.x ? eB : eA;
+    
+    if (leftEyeOuter && rightEyeOuter && nT) {
+      const faceWidth = Math.abs(rightEyeOuter.x - leftEyeOuter.x);
+      const midX = (leftEyeOuter.x + rightEyeOuter.x) / 2;
+      const yaw = (nT.x - midX) / Math.max(1e-6, faceWidth);
+      const absYaw = Math.abs(yaw);
+      
+      const xs = faceOnCanvas.map(p => p.x), ys = faceOnCanvas.map(p => p.y);
+      const minX = Math.min(...xs) * w, maxX = Math.max(...xs) * w;
+      const minY = Math.min(...ys) * h, maxY = Math.max(...ys) * h;
+      const boxCX = (minX + maxX) / 2, boxCY = (minY + maxY) / 2;
+      const guideCX = w / 2;
+      const guideCY = h / 2;
+      const guideR = Math.min(w, h) * 0.45;
+      const dx = boxCX - guideCX;
+      const dy = boxCY - guideCY;
+      const insideGuide = (dx * dx + dy * dy) <= (guideR * guideR)
+        && (maxX - minX) <= guideR * 2 * 1.05 && (maxY - minY) <= guideR * 2 * 1.05;
+      
+      if (!this.livenessStateRef.current.livenessReady) {
+        this.livenessStateRef.current.livenessReady = true;
+      }
+      
+      const centerThreshold = 0.05;
+      const leftThreshold = 0.08;
+      const rightThreshold = 0.08;
+      const holdFramesCenter = 12;
+      const holdFramesTurn = 12;
+      
+      const state = this.livenessStateRef.current;
+      
+      if (state.stage === "CENTER") {
+        if (!insideGuide) {
+          if (this.callbacks.onLivenessUpdate) {
+            this.callbacks.onLivenessUpdate(state.stage, "Center your face inside the circle");
+          }
+        } else if (absYaw < centerThreshold) {
+          state.centerHold += 1;
+          if (state.centerHold >= holdFramesCenter) {
+            const newStage: LivenessStage = "LEFT";
+            state.stage = newStage;
+            state.centerHold = 0;
+            if (this.callbacks.onLivenessUpdate) {
+              this.callbacks.onLivenessUpdate(newStage, "Turn your face LEFT");
+            }
+          }
+        } else {
+          state.centerHold = 0;
+          if (this.callbacks.onLivenessUpdate) {
+            this.callbacks.onLivenessUpdate(state.stage, yaw > 0 ? "Move your face slightly LEFT" : "Move your face slightly RIGHT");
+          }
+        }
+      } else if (state.stage === "LEFT") {
+        if (faceWidth < 0.08) {
+          if (this.callbacks.onLivenessUpdate) {
+            this.callbacks.onLivenessUpdate(state.stage, "Move closer to the camera");
+          }
+        } else if (yaw < -leftThreshold) {
+          state.leftHold += 1;
+          if (state.leftHold >= holdFramesTurn) {
+            const newStage: LivenessStage = "RIGHT";
+            state.stage = newStage;
+            state.leftHold = 0;
+            if (this.callbacks.onLivenessUpdate) {
+              this.callbacks.onLivenessUpdate(newStage, "Great! Now turn your face RIGHT");
+            }
+          }
+        } else {
+          state.leftHold = 0;
+          if (this.callbacks.onLivenessUpdate) {
+            this.callbacks.onLivenessUpdate(state.stage, yaw > rightThreshold ? "You're facing right. Turn LEFT" : "Turn a bit more LEFT");
+          }
+        }
+      } else if (state.stage === "RIGHT") {
+        if (faceWidth < 0.08) {
+          if (this.callbacks.onLivenessUpdate) {
+            this.callbacks.onLivenessUpdate(state.stage, "Move closer to the camera");
+          }
+        } else if (yaw > rightThreshold) {
+          state.rightHold += 1;
+          if (state.rightHold >= holdFramesTurn) {
+            state.rightHold = 0;
+            if (!state.snapTriggered) {
+              state.snapTriggered = true;
+              const newStage: LivenessStage = "DONE";
+              state.stage = newStage;
+              if (this.callbacks.onLivenessUpdate) {
+                this.callbacks.onLivenessUpdate(newStage, "Capturing...");
+              }
+              if (this.callbacks.onCaptureTrigger) {
+                this.callbacks.onCaptureTrigger();
+              }
+            }
+          }
+        } else {
+          state.rightHold = 0;
+          if (this.callbacks.onLivenessUpdate) {
+            this.callbacks.onLivenessUpdate(state.stage, yaw < -leftThreshold ? "You're facing left. Turn RIGHT" : "Turn a bit more RIGHT");
+          }
+        }
+      }
+    }
+  }
+
+  private waitForVideoReady(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      let attempts = 0;
+      const maxAttempts = 100;
+      
+      const checkReady = () => {
+        if (this.cancelled) {
+          reject(new Error('Cancelled'));
+          return;
+        }
+        
+        const video = this.videoRef.current;
+        if (
+          video &&
+          video.readyState >= 2 &&
+          video.videoWidth > 0 &&
+          video.videoHeight > 0 &&
+          !isNaN(video.videoWidth) &&
+          !isNaN(video.videoHeight)
+        ) {
+          resolve();
+        } else if (attempts >= maxAttempts) {
+          if (video) {
+            resolve();
+          } else {
+            reject(new Error('Video not ready'));
+          }
+        } else {
+          attempts++;
+          requestAnimationFrame(checkReady);
+        }
+      };
+      checkReady();
+    });
+  }
+
+  async initialize(): Promise<void> {
+    try {
+      const fm = new FaceMesh({ 
+        locateFile: (file: string) => `https://cdn.jsdelivr.net/npm/@mediapipe/face_mesh@0.4.1633559619/${file}` 
+      });
+      fm.setOptions({
+        selfieMode: true,
+        maxNumFaces: 1,
+        refineLandmarks: true,
+        minDetectionConfidence: 0.5,
+        minTrackingConfidence: 0.5
+      } as any);
+      
+      this.faceMesh = fm;
+      
+      if (this.cancelled) return;
+      
+      if (this.callbacks.onModelLoaded) {
+        this.callbacks.onModelLoaded();
+      }
+      
+      fm.onResults((results) => {
+        if (!this.cancelled) {
+          this.processResults(results);
+        }
+      });
+      
+      if (this.videoRef.current) {
+        try {
+          await this.waitForVideoReady();
+        } catch (error) {
+          if (!this.cancelled) {
+            console.debug('Video ready check failed, continuing anyway:', error);
+          }
+        }
+        
+        const tick = async () => {
+          if (this.cancelled) return;
+          if (!this.videoRef.current || !this.faceMesh) return;
+          
+          const video = this.videoRef.current;
+          if (
+            video.readyState >= 2 &&
+            video.videoWidth > 0 &&
+            video.videoHeight > 0 &&
+            !isNaN(video.videoWidth) &&
+            !isNaN(video.videoHeight)
+          ) {
+            try {
+              await this.faceMesh.send({ image: video as HTMLVideoElement });
+            } catch (error) {
+              if (!this.cancelled) {
+                console.debug('MediaPipe send error (non-critical):', error);
+              }
+            }
+          }
+          
+          if (!this.cancelled) {
+            this.cameraDriverRef.current = requestAnimationFrame(tick);
+          }
+        };
+        
+        this.cameraDriverRef.current = requestAnimationFrame(tick);
+      }
+    } catch (e) {
+      if (!this.cancelled && this.callbacks.onModelFailed) {
+        this.callbacks.onModelFailed(e as Error);
+      }
+      throw e;
+    }
+  }
+
+  cleanup(): void {
+    this.cancelled = true;
+    if (this.cameraDriverRef.current) {
+      cancelAnimationFrame(this.cameraDriverRef.current);
+      this.cameraDriverRef.current = null;
+    }
+    if (this.faceMesh) {
+      try {
+        (this.faceMesh as any).close?.();
+      } catch {}
+      this.faceMesh = null;
+    }
+  }
+}
+

package/src/services/index.ts

@@ -0,0 +1,5 @@
+export { FaceMeshService } from './faceMeshService';
+export type { LivenessStage, FaceMeshServiceCallbacks, LivenessState } from './faceMeshService';
+export { KycApiService } from './kycApiService';
+export type { KycApiConfig, SessionStatusResponse, FaceScanResponse, DocumentUploadResponse } from './kycApiService';
+

package/src/services/kycApiService.ts

@@ -0,0 +1,194 @@
+/**
+ * KYC API Service
+ * Handles all KYC-related API calls (face scan, document upload, status check)
+ */
+
+export interface KycApiConfig {
+  apiBaseUrl: string;
+  sessionId: string;
+  serverKey: string;
+  deviceType?: string;
+}
+
+export interface SessionStatusResponse {
+  status: string;
+  message: string;
+  data: {
+    session_id: string;
+    status: 'ACTIVE' | 'INACTIVE' | 'EXPIRED' | 'COMPLETED';
+    completed_steps: string[];
+    next_step: string;
+  };
+}
+
+export interface FaceScanResponse {
+  status: string;
+  message: string;
+  data?: unknown;
+}
+
+export interface DocumentUploadResponse {
+  status: string;
+  message: string;
+  data?: unknown;
+}
+
+export class KycApiService {
+  private config: KycApiConfig;
+
+  constructor(config: KycApiConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Detect device type
+   */
+  private detectDeviceType(): string {
+    const userAgent = navigator.userAgent || navigator.vendor || (window as any).opera;
+    if (/android/i.test(userAgent)) return 'android';
+    if (/iPad|iPhone|iPod/.test(userAgent) && !(window as any).MSStream) return 'ios';
+    if (/Mac|Windows|Linux/.test(userAgent)) return 'desktop';
+    return 'unknown';
+  }
+
+  /**
+   * Get session status
+   */
+  async getSessionStatus(): Promise<SessionStatusResponse> {
+    const deviceType = this.config.deviceType || this.detectDeviceType();
+    
+    try {
+      const response = await fetch(
+        `${this.config.apiBaseUrl}/api/v2/dashboard/merchant/onsite/session/${this.config.sessionId}/status`,
+        {
+          method: 'GET',
+          headers: {
+            'x-server-key': this.config.serverKey,
+            'device-type': deviceType,
+            'Content-Type': 'application/json',
+          },
+          credentials: 'include',
+        }
+      );
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        const message = errorData?.message || `Status fetch failed with status ${response.status}`;
+        throw new Error(message);
+      }
+
+      const data = await response.json();
+      return data;
+    } catch (error: any) {
+      const message = error?.message || 'Status fetch failed';
+      throw new Error(`Status fetch failed: ${message}`);
+    }
+  }
+
+  /**
+   * Upload face scan image
+   */
+  async uploadFaceScan(faceBlob: Blob | File): Promise<FaceScanResponse> {
+    // Check session status first
+    await this.checkSessionActive();
+
+    const deviceType = this.config.deviceType || this.detectDeviceType();
+    const formData = new FormData();
+    const faceFileName = (faceBlob as File)?.name || `face-${Date.now()}.jpg`;
+    formData.append('face_scan_img', faceBlob, faceFileName);
+
+    try {
+      const response = await fetch(
+        `${this.config.apiBaseUrl}/api/v2/dashboard/merchant/onsite/session/${this.config.sessionId}/face`,
+        {
+          method: 'POST',
+          headers: {
+            'x-server-key': this.config.serverKey,
+            'device-type': deviceType,
+          },
+          credentials: 'include',
+          body: formData,
+        }
+      );
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        const message = errorData?.message || `Face upload failed with status ${response.status}`;
+        throw new Error(message);
+      }
+
+      const data = await response.json();
+      return data;
+    } catch (error: any) {
+      const message = error?.message || 'Face upload failed';
+      throw new Error(`Face upload failed: ${message}`);
+    }
+  }
+
+  /**
+   * Upload document scan image
+   */
+  async uploadDocument(docBlob: Blob | File, docType: string): Promise<DocumentUploadResponse> {
+    // Check session status first
+    await this.checkSessionActive();
+
+    const deviceType = this.config.deviceType || this.detectDeviceType();
+    const formData = new FormData();
+    const docFileName = (docBlob as File)?.name || `document-${Date.now()}.jpg`;
+    formData.append('docs_scan_img', docBlob, docFileName);
+    formData.append('docType', docType);
+
+    try {
+      const response = await fetch(
+        `${this.config.apiBaseUrl}/api/v2/dashboard/merchant/onsite/session/${this.config.sessionId}/docs`,
+        {
+          method: 'POST',
+          headers: {
+            'x-server-key': this.config.serverKey,
+            'device-type': deviceType,
+          },
+          credentials: 'include',
+          body: formData,
+        }
+      );
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        const message = errorData?.message || `Document upload failed with status ${response.status}`;
+        throw new Error(message);
+      }
+
+      const data = await response.json();
+      return data;
+    } catch (error: any) {
+      const message = error?.message || 'Document upload failed';
+      throw new Error(`Document upload failed: ${message}`);
+    }
+  }
+
+  /**
+   * Check if session is active, throw error if not
+   */
+  async checkSessionActive(): Promise<void> {
+    const status = await this.getSessionStatus();
+    
+    if (status.data.status !== 'ACTIVE') {
+      throw new Error('Session expired or inactive. Please start a new session.');
+    }
+  }
+
+  /**
+   * Update configuration
+   */
+  updateConfig(config: Partial<KycApiConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): KycApiConfig {
+    return { ...this.config };
+  }
+}
+

package/src/utils/deviceDetection.ts

@@ -0,0 +1,28 @@
+/**
+ * Utility functions for device detection
+ */
+
+export function isMobileDevice(): boolean {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+
+  // Check user agent
+  const userAgent = navigator.userAgent || navigator.vendor || (window as any).opera;
+  
+  // Common mobile device patterns
+  const mobileRegex = /android|webos|iphone|ipad|ipod|blackberry|iemobile|opera mini/i;
+  
+  // Check screen width (mobile devices typically have smaller screens)
+  const isSmallScreen = window.innerWidth <= 768;
+  
+  // Check for touch support
+  const hasTouchScreen = 'ontouchstart' in window || navigator.maxTouchPoints > 0;
+  
+  return mobileRegex.test(userAgent) || (isSmallScreen && hasTouchScreen);
+}
+
+export function getDeviceType(): 'mobile' | 'desktop' {
+  return isMobileDevice() ? 'mobile' : 'desktop';
+}
+

package/src/App.css

@@ -1,42 +0,0 @@
-#root {
-  max-width: 1280px;
-  margin: 0 auto;
-  padding: 2rem;
-  text-align: center;
-}
-
-.logo {
-  height: 6em;
-  padding: 1.5em;
-  will-change: filter;
-  transition: filter 300ms;
-}
-.logo:hover {
-  filter: drop-shadow(0 0 2em #646cffaa);
-}
-.logo.react:hover {
-  filter: drop-shadow(0 0 2em #61dafbaa);
-}
-
-@keyframes logo-spin {
-  from {
-    transform: rotate(0deg);
-  }
-  to {
-    transform: rotate(360deg);
-  }
-}
-
-@media (prefers-reduced-motion: no-preference) {
-  a:nth-of-type(2) .logo {
-    animation: logo-spin infinite 20s linear;
-  }
-}
-
-.card {
-  padding: 2em;
-}
-
-.read-the-docs {
-  color: #888;
-}