zedai-voice/README.md

Siri-like voice banking SDK for React Native - Complete voice-powered fintech solution with wake word detection and beautiful UI

# 🎙️ Zed Voice - Siri-like Voice Banking SDK

**Transform your banking app with premium voice interactions in minutes!**

Zed Voice is a complete voice banking SDK that provides Siri-like voice interactions for React Native banking applications. Just install, configure, and your users can say "Hey [YourAIName]" to perform money transfers with a beautiful animated interface.

[![npm version](https://badge.fury.io/js/zedai-voice.svg)](https://badge.fury.io/js/zedai-voice)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![React Native](https://img.shields.io/badge/React%20Native-0.60+-blue.svg)](https://reactnative.dev/)

## ✨ Features

🎯 **Ultra Simple Integration** - One method call setup  
🎙️ **Wake Word Detection** - Always listening for "Hey [YourAIName]"  
🎨 **Siri-like UI** - Beautiful animated overlay interface  
🔐 **Secure PIN Flow** - Webhook-based PIN collection  
💰 **Money Transfers** - Complete conversation flows  
🏦 **Account Verification** - Real-time account lookup  
🌍 **Multi-platform** - iOS & Android React Native  
🔒 **Enterprise Security** - End-to-end encryption  
📱 **Auto Permissions** - Automatic permission requests like iOS apps  
🎵 **Voice Feedback** - Natural text-to-speech responses  

## 🚀 Quick Start

### Installation

```bash
npm install zedai-voice
```

### iOS Setup

Add to your `Info.plist`:

```xml
<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone for voice banking commands</string>
<key>NSSpeechRecognitionUsageDescription</key>
<string>This app uses speech recognition for voice banking</string>
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
    <string>background-processing</string>
</array>
```

### Android Setup

Add to your `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
```

## 🎯 Ultra Simple Integration

```javascript
import ZedVoice from 'zedai-voice';

// This is ALL the code you need!
const voiceSDK = ZedVoice.createSimpleIntegration({
  bankName: "YourAIName",
  wakeWord: "hey YourAIName",
  brandColor: "#FF6B35",
  
  // Your banking APIs
  apiEndpoints: {
    verifyAccount: "https://api.YourAIName.com/verify-account",
    transfer: "https://api.YourAIName.com/transfer"
  },
  webhookUrl: "https://yourapp.com/webhook/pin",
  apiKey: "your-bank-api-key"
});

await voiceSDK.initialize();
// Done! Voice banking is now active! 🎉

// Handle PIN requests (only UI you need to implement)
voiceSDK.onPinRequest((data) => {
  showYourPinModal((pin) => {
    voiceSDK.handlePINResponse(data.requestId, pin);
  });
});
```

## 🎨 User Experience

1. **User says "hey YourAIName"** → Beautiful Siri-like overlay appears
2. **User:** "Transfer 5000 naira to account 1234567890 at GTBank"
3. **Zed Voice:** "I found John Doe at GTBank. Is this correct?"
4. **User:** "Yes"
5. **Your PIN modal appears** (your existing UI)
6. **Transfer completes** → Success animation

## 📱 What You Get

### 🎙️ Complete Voice Recognition
- Natural language understanding
- Banking-specific intent parsing
- Error handling and retry logic

### 🎨 Beautiful Siri-like Interface
- Animated voice overlay
- Pulsing microphone animations
- Sound wave visualizations
- Brand customization with your colors
- Voice state indicators

### 🔐 Enterprise Security
- PIN never stored in SDK
- End-to-end encryption
- Secure webhook PIN collection
- Session management
- Rate limiting protection

### 🏦 Banking Features
- Money transfers
- Account verification
- Real-time balance checks (coming soon)
- Transaction history (coming soon)
- Bill payments (coming soon)

## 🔧 Advanced Configuration

```javascript
const voiceSDK = new ZedVoice({
  bankName: "YourAIName",
  wakeWord: "hey YourAIName",
  
  // UI Customization
  ui: {
    enabled: true,
    overlayTheme: {
      primaryColor: "#007AFF",
      backgroundColor: "rgba(0, 0, 0, 0.8)",
      textColor: "#FFFFFF"
    },
    backgroundMode: true,
    sensitivity: 0.8
  },
  
  // Banking APIs
  apiEndpoints: {
    verifyAccount: "https://api.YourAIName.com/verify",
    transfer: "https://api.YourAIName.com/transfer",
    balance: "https://api.YourAIName.com/balance"
  },
  
  // Security
  webhookUrl: "https://yourapp.com/webhook/pin",
  apiKey: "your-secure-api-key",
  security: {
    timeout: 300000,
    maxRetries: 3
  }
});
```

## 🎯 API Reference

### Core Methods

```javascript
// Initialize SDK (handles permissions automatically)
await voiceSDK.initialize();

// Show voice UI manually
voiceSDK.showVoiceUI();

// Start voice interaction
await voiceSDK.startVoiceInteraction();

// Process text command (for testing)
await voiceSDK.processVoiceCommand("Transfer 1000 to account 1234567890");

// Handle PIN response
await voiceSDK.handlePINResponse(requestId, pin);
```

### Event Handlers

```javascript
// Wake word detected
voiceSDK.onWakeWordDetected((data) => {
  console.log('Wake word:', data.wakeWord);
});

// Transfer completed
voiceSDK.onTransferComplete((data) => {
  console.log('Transfer successful:', data.transferResult);
});

// PIN requested
voiceSDK.onPinRequest((data) => {
  // Show your PIN input modal
});

// Errors
voiceSDK.onError((error) => {
  console.error('Voice error:', error);
});
```

### Global Access (Like Siri)

```javascript
// Call from anywhere in your app
ZedVoice.showVoiceUI();
ZedVoice.startVoiceInteraction();
ZedVoice.hideVoiceUI();
```

## 🏦 Banking API Integration

### Account Verification Endpoint

```javascript
// POST /verify-account
{
  "account_number": "1234567890",
  "bank_name": "GTBank",
  "timestamp": 1640995200000
}

// Expected Response:
{
  "success": true,
  "account_name": "John Doe",
  "bank_code": "058",
  "verification_id": "ver_12345"
}
```

### Transfer Endpoint

```javascript
// POST /transfer
{
  "from_account": "0987654321",
  "to_account": "1234567890",
  "bank_name": "GTBank",
  "bank_code": "058",
  "amount": 5000,
  "narration": "Voice transfer",
  "pin": "1234",
  "verification_id": "ver_12345",
  "reference": "VFT12345678ABC",
  "timestamp": 1640995200000
}

// Expected Response:
{
  "success": true,
  "reference": "TXN_67890",
  "amount": 5000,
  "fee": 10,
  "balance_after": 45000,
  "timestamp": 1640995200000
}
```

### PIN Webhook

```javascript
// POST /webhook/pin
{
  "action": "REQUEST_PIN",
  "request_id": "PIN_12345",
  "session_id": "sess_67890",
  "transfer_data": {
    "amount": 5000,
    "account_name": "John Doe",
    "bank_name": "GTBank"
  },
  "timestamp": 1640995200000
}
```

## 🎨 UI Customization

### Theme Configuration

```javascript
const customTheme = {
  primaryColor: "#FF6B35",        // Main brand color
  secondaryColor: "#5856D6",      // Accent color  
  backgroundColor: "rgba(255, 107, 53, 0.9)", // Overlay background
  textColor: "#FFFFFF",           // Text color
  bankColor: "#FF9500",          // Bank-specific color
  errorColor: "#FF3B30"          // Error color
};

voiceSDK.updateUITheme(customTheme);
```

### Wake Word Customization

```javascript
// Multiple wake words
voiceSDK.updateWakeWords([
  "hey YourAIName",
  "YourAIName assistant", 
  "banking assistant"
]);

// Sensitivity (0.1 = less sensitive, 1.0 = more sensitive)
voiceSDK.setWakeWordSensitivity(0.8);
```

## 🧪 Testing

### Wake Word Testing

```javascript
const result = await voiceSDK.testWakeWord("hey YourAIName transfer money");
console.log(result);
// {
//   detected: true,
//   wakeWord: "hey YourAIName",
//   command: "transfer money",
//   confidence: 0.95
// }
```

### Voice Command Testing

```javascript
// Test without UI
await voiceSDK.processVoiceCommand("Transfer 1000 to account 1234567890 at UBA");

// Test with UI
await voiceSDK.processTextCommandWithUI("Send money to John Doe");
```

## 📊 Monitoring & Analytics

```javascript
// Get usage metrics
const metrics = voiceSDK.getMetrics();
console.log(metrics);
// {
//   totalInteractions: 150,
//   successfulTransfers: 142,
//   failedTransfers: 8,
//   averageResponseTime: 1200,
//   currentSession: "sess_12345"
// }

// Health check
const health = await voiceSDK.healthCheck();
console.log(health.status); // 'healthy', 'degraded', or 'unhealthy'
```

## 🔧 Troubleshooting

### Common Issues

**Microphone Permission Denied**
```javascript
// The SDK handles this automatically, but you can check:
const permissions = await voiceSDK.getPermissionStatus();
console.log(permissions);
```

**Wake Word Not Detecting**
```javascript
// Test wake word sensitivity
const result = await voiceSDK.testWakeWord("hey YourAIName");
if (!result.detected) {
  voiceSDK.setWakeWordSensitivity(0.6); // Lower = more sensitive
}
```

**API Connection Issues**
```javascript
// Test all connections
const connections = await voiceSDK.testConnections();
console.log(connections);
// Shows status of banking APIs, webhooks
```

## 📝 Examples

- [Basic Integration](examples/basic-integration.js)
- [Custom UI Theme](examples/custom-theme.js)
- [Advanced Configuration](examples/advanced-config.js)
- [Testing Guide](examples/testing.md)

## 🤝 Support

- **Documentation:** [GitHub Wiki](https://github.com/CodaBae/zedai-voice/wiki)
- **Issues:** [GitHub Issues](https://github.com/CodaBae/zedai-voice/issues)
- **Email:** shalom@fractnmoney.com
- **Community:** [Discussions](https://github.com/CodaBae/zedai-voice/discussions)

## 📄 License

MIT © [Shalom Rayhamen](https://github.com/CodaBae)

## 🎯 What's Next?

- Multi-language support
- Offline capabilities  
- Advanced analytics
- Voice biometrics
- International banking standards

---

**Transform your banking app with voice interactions today!** 🚀

```bash
npm install zedai-voice
```