TransferGratis KYC SDK

A comprehensive KYC (Know Your Customer) SDK built with React Native and Expo, featuring advanced camera capabilities powered by react-native-vision-camera.

🚀 Features

✅ Advanced Camera Integration with react-native-vision-camera
✅ Selfie Capture with face detection overlay
✅ Document Capture with auto-focus and quality controls
✅ Orientation Video Processing for liveness detection
✅ File Upload with validation
✅ Custom Overlays and instructions
✅ Permission Management with graceful fallbacks
✅ Multi-Platform Support (iOS, Android)
✅ TypeScript Support with full type definitions
✅ Expo Config Plugin for easy setup

📦 Installation

npm install transfergratis-sdk react-native-vision-camera

iOS Setup

Add to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "transfergratis-sdk/plugin",
        {
          "cameraPermissionText": "This app uses the camera for identity verification.",
          "microphonePermissionText": "This app uses the microphone for video capture.",
          "enableFrameProcessors": false
        }
      ]
    ]
  }
}

Android Setup

The config plugin will handle Android permissions automatically. No additional setup required.

🎯 Quick Start

Basic KYC Flow

import React from 'react';
import { LauchTransferGratisKYC } from 'transfergratis-sdk';

export default function App() {
  return (
    <LauchTransferGratisKYC
      apiKey="your-api-key"
      onComplete={(result) => {
        console.log('KYC completed:', result);
      }}
      onError={(error) => {
        console.error('KYC error:', error);
      }}
    />
  );
}

Advanced Camera Usage

import React, { useState } from 'react';
import { View } from 'react-native';
import { EnhancedCameraView } from 'transfergratis-sdk';

export default function CameraExample() {
  const [showCamera, setShowCamera] = useState(true);

  const handleCapture = (result) => {
    if (result.success) {
      console.log('Photo captured:', result.path);
      setShowCamera(false);
    } else {
      console.error('Capture failed:', result.error);
    }
  };

  return (
    <View style={{ flex: 1 }}>
      <EnhancedCameraView
        showCamera={showCamera}
        cameraType="front"
        instructions="Position your face in the frame"
        onCapture={handleCapture}
        onError={(error) => console.error('Camera error:', error)}
        onClose={() => setShowCamera(false)}
        quality="high"
        enableFlash={true}
        showCaptureButton={true}
        showSwitchCamera={true}
      />
    </View>
  );
}

📚 API Reference

Components

EnhancedCameraView

The main camera component with full Vision Camera integration.

interface EnhancedCameraViewProps {
  instructions?: string;
  showCamera: boolean;
  cameraType?: 'front' | 'back';
  style?: ViewStyle;
  onCapture?: (result: CaptureResult) => void;
  onError?: (event: { message: string }) => void;
  onClose?: () => void;
  enableFlash?: boolean;
  enableHdr?: boolean;
  quality?: 'low' | 'medium' | 'high';
  showCaptureButton?: boolean;
  showSwitchCamera?: boolean;
  overlayComponent?: React.ReactNode;
}

VisionCameraView

A simpler camera component for basic use cases.

interface VisionCameraViewProps {
  instructions?: string;
  showCamera: boolean;
  cameraType?: 'front' | 'back';
  style?: ViewStyle;
  onCapture?: (result: CaptureResult) => void;
  onError?: (event: { message: string }) => void;
  onPermissionError?: () => void;
  enableHdr?: boolean;
  enableNightMode?: boolean;
  quality?: 'low' | 'medium' | 'high';
}

SelfieCapture

Pre-configured component for selfie capture with KYC integration.

// No props required - integrates with KYC store
<SelfieCapture />

Modules

VisionCameraModule

Core module for camera operations and permissions.

import { VisionCameraModule } from 'transfergratis-sdk';

// Request permissions
const hasPermissions = await VisionCameraModule.requestAllPermissions();

// Get camera devices
const frontCamera = await VisionCameraModule.getFrontCameraDevice();
const backCamera = await VisionCameraModule.getBackCameraDevice();

// Check camera availability
const isAvailable = await VisionCameraModule.isCameraAvailable();

🎨 Customization

Custom Overlay Example

import React from 'react';
import { View, Text, StyleSheet } from 'react-native';
import { EnhancedCameraView } from 'transfergratis-sdk';

export default function CustomCameraExample() {
  const customOverlay = (
    <View style={styles.overlay}>
      <View style={styles.faceFrame} />
      <Text style={styles.instruction}>
        Align your face with the frame
      </Text>
    </View>
  );

  return (
    <EnhancedCameraView
      showCamera={true}
      overlayComponent={customOverlay}
      onCapture={(result) => console.log(result)}
    />
  );
}

const styles = StyleSheet.create({
  overlay: {
    position: 'absolute',
    top: 0,
    left: 0,
    right: 0,
    bottom: 0,
    justifyContent: 'center',
    alignItems: 'center',
    pointerEvents: 'none',
  },
  faceFrame: {
    width: 250,
    height: 300,
    borderWidth: 3,
    borderColor: '#4CAF50',
    borderRadius: 125,
  },
  instruction: {
    color: 'white',
    fontSize: 16,
    textAlign: 'center',
    marginTop: 20,
    backgroundColor: 'rgba(0, 0, 0, 0.7)',
    padding: 10,
    borderRadius: 8,
  },
});

Orientation Video Processing

The SDK now includes advanced liveness detection through orientation video processing. This feature captures and analyzes short videos to verify that a real person is present during the KYC process.

Basic Usage

import React from 'react';
import { OrientationVideoCapture, KYCService } from 'transfergratis-sdk';

const kycService = new KYCService('https://api.yourdomain.com', 'your-api-key');

export default function LivenessDetection() {
  return (
    <OrientationVideoCapture
      config={{
        duration: 10,
        orientations: ['center', 'left', 'right'],
        instructions: {
          center: 'Look straight ahead at the camera',
          left: 'Turn your head to the left',
          right: 'Turn your head to the right',
        },
        showPreview: true,
        allowRetake: true,
        maxRetakes: 3,
      }}
      onComplete={(result) => {
        console.log('Liveness detection result:', result);
        // Handle successful processing
      }}
      onError={(error) => {
        console.error('Liveness detection error:', error);
        // Handle error
      }}
      kycService={kycService}
    />
  );
}

Using the Custom Hook

import React from 'react';
import { View, Text, Button } from 'react-native';
import { useOrientationVideo, KYCService } from 'transfergratis-sdk';

export default function LivenessDetectionHook() {
  const kycService = new KYCService('https://api.yourdomain.com', 'your-api-key');
  
  const { state, actions } = useOrientationVideo(kycService, {
    duration: 10,
    maxRetakes: 2,
  });

  return (
    <View>
      {state.isRecording && <Text>Recording...</Text>}
      {state.isProcessing && <Text>Processing...</Text>}
      {state.error && <Text>Error: {state.error}</Text>}
      
      <Button title="Start Recording" onPress={actions.startRecording} />
      <Button title="Process Video" onPress={actions.processVideo} />
    </View>
  );
}

API Response Format

The orientation video processing returns detailed results for each face orientation:

{
  "center": {
    "captured": true,
    "frame": 35
  },
  "right": {
    "captured": true,
    "frame": 98
  },
  "left": {
    "captured": false,
    "frame": null
  }
}

For more detailed information, see the Orientation Video Processing Guide.

🔧 Configuration Plugin

The SDK includes an Expo config plugin for automatic setup of native permissions and dependencies.

Plugin Options

interface VisionCameraPluginProps {
  cameraPermissionText?: string;
  microphonePermissionText?: string;
  enableFrameProcessors?: boolean;
}

Manual Plugin Usage

import { withVisionCamera } from 'transfergratis-sdk/plugin';

export default withVisionCamera(config, {
  cameraPermissionText: "Custom camera permission message",
  microphonePermissionText: "Custom microphone permission message",
  enableFrameProcessors: false
});

🛠️ Development

Building the SDK

cd transfergratis-sdk
npm install
npm run build

Running the Example

cd transfergratis-sdk/example
npm install
npm run ios # or npm run android

🚀 Publication npm

Pré-requis

• Compte npm avec droits de publication sur le package
• Node 18+ et npm 9+

Étapes de release

1. Installer et nettoyer

cd transfergratis-sdk
npm ci
npm run clean

2. Builder le SDK

npm run build

3. Vérifier le contenu qui sera publié

npm publish --dry-run
npm pack
tar -tf transfergratis-sdk-*.tgz | cat

4. Monter la version (exemples)

# patch | minor | major | prerelease
npm version patch -m "release: %s"

5. Connexion npm (si nécessaire)

npm whoami || npm login

6. Publier sur npm (public)

npm publish --access public

• Avec 2FA:

npm publish --access public --otp=123456

• Publier une préversion (tag beta):

npm publish --tag beta --access public

7. Pousser les tags git

git push && git push --tags

8. Vérifier la version publiée

npm info transfergratis-sdk version

📝 Migration from Legacy Camera

If you're upgrading from the legacy native camera implementation:

Component Changes

// Old (Legacy)
import { NativeCameraView } from 'transfergratis-sdk';

<NativeCameraView
  instructions="Take a photo"
  showCamera={true}
  onCapture={(event) => {
    if (event.action === 'capture') {
      console.log(event.imagePath);
    }
  }}
/>

// New (Vision Camera)
import { EnhancedCameraView } from 'transfergratis-sdk';

<EnhancedCameraView
  instructions="Take a photo"
  showCamera={true}
  onCapture={(result) => {
    if (result.success) {
      console.log(result.path);
    }
  }}
/>

Module Changes

// Old
import { NativeCameraModule } from 'transfergratis-sdk';
const hasPermission = await NativeCameraModule.requestCameraPermission();

// New
import { VisionCameraModule } from 'transfergratis-sdk';
const hasPermissions = await VisionCameraModule.requestAllPermissions();

🚨 Breaking Changes

v2.0.0

• Camera Implementation: Switched from custom native views to react-native-vision-camera
• Permissions: Now requires both camera and microphone permissions
• Component Props: Updated prop interfaces for better type safety
• Config Plugin: New plugin required for automatic permissions setup

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support, email [email protected] or open an issue on GitHub.

Built with ❤️ by the TransferGratis Team