@capgo/capacitor-twilio-voice 7.1.0

package/CapgoCapacitorTwilioVoice.podspec

@@ -0,0 +1,19 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'CapgoCapacitorTwilioVoice'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '14.0'
+  s.dependency 'Capacitor'
+  s.dependency 'TwilioVoice', '~> 6.13'
+  s.frameworks = 'PushKit', 'CallKit', 'AVFoundation'
+  s.swift_version = '5.1'
+end

package/Package.swift

@@ -0,0 +1,35 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "CapgoCapacitorTwilioVoice",
+    platforms: [.iOS(.v14)],
+    products: [
+        .library(
+            name: "CapgoCapacitorTwilioVoice",
+            targets: ["CapacitorTwilioVoicePlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "7.0.0"),
+        .package(url: "https://github.com/twilio/twilio-voice-ios", from: "6.13.0")
+    ],
+    targets: [
+        .target(
+            name: "CapacitorTwilioVoicePlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm"),
+                .product(name: "TwilioVoice", package: "twilio-voice-ios")
+            ],
+            path: "ios/Sources/CapacitorTwilioVoicePlugin",
+            linkerSettings: [
+                .linkedFramework("PushKit"),
+                .linkedFramework("CallKit"),
+                .linkedFramework("AVFoundation")
+            ]),
+        .testTarget(
+            name: "CapacitorTwilioVoicePluginTests",
+            dependencies: ["CapacitorTwilioVoicePlugin"],
+            path: "ios/Tests/CapacitorTwilioVoicePluginTests")
+    ]
+)

package/README.md

@@ -0,0 +1,280 @@
+## Capacitor Twilio Voice Plugin
+ <a href="https://capgo.app/"><img src='https://raw.githubusercontent.com/Cap-go/capgo/main/assets/capgo_banner.png' alt='Capgo - Instant updates for capacitor'/></a>
+
+<div align="center">
+  <h2><a href="https://capgo.app/?ref=plugin"> ➡️ Get Instant updates for your App with Capgo</a></h2>
+  <h2><a href="https://capgo.app/consulting/?ref=plugin"> Missing a feature? We’ll build the plugin for you 💪</a></h2>
+</div>
+
+A Capacitor plugin for integrating Twilio Voice calling functionality into iOS and Android applications.
+
+## Installation
+
+```bash
+npm install @capgo/capacitor-twilio-voice
+npx cap sync
+```
+
+## iOS Setup
+
+### 1. Install Dependencies
+
+#### Option A: CocoaPods (Recommended)
+Add to your app's `ios/App/Podfile`:
+```ruby
+pod 'TwilioVoice', '~> 6.13'
+```
+
+#### Option B: Swift Package Manager  
+Add to your `Package.swift`:
+```swift
+dependencies: [
+    .package(url: "https://github.com/twilio/twilio-voice-ios", from: "6.13.0")
+]
+```
+
+### 2. Configure Info.plist
+Add to `ios/App/App/Info.plist`:
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>This app uses the microphone for voice calls</string>
+
+<key>UIBackgroundModes</key>
+<array>
+    <string>voip</string>
+    <string>audio</string>
+</array>
+```
+
+### 3. Enable Push Notifications Capability
+In Xcode, select your app target → Signing & Capabilities → Add Capability → Push Notifications
+
+### 4. PushKit Setup
+PushKit is automatically configured by the plugin. No additional setup required.
+
+## Android Setup
+
+### 1. Firebase Setup
+Add Firebase to your Android project:
+
+1. Add `google-services.json` to `android/app/`
+2. Update `android/app/build.gradle`:
+```gradle
+apply plugin: 'com.google.gms.google-services'
+
+dependencies {
+    // ... existing dependencies
+    implementation 'com.google.firebase:firebase-messaging:25.0.0'
+    implementation platform('com.google.firebase:firebase-bom:34.0.0')
+    implementation 'com.twilio:audioswitch:1.2.2'
+    implementation 'androidx.core:core:1.13.1'
+    implementation 'androidx.media:media:1.6.0'
+}
+```
+
+3. Update project-level `android/build.gradle`:
+```gradle
+buildscript {
+    dependencies {
+        classpath 'com.google.gms:google-services:4.4.2'
+    }
+}
+```
+
+### 2. AndroidManifest.xml
+Required permissions are automatically added by the plugin:
+- `RECORD_AUDIO`
+- `INTERNET` 
+- `ACCESS_NETWORK_STATE`
+- `WAKE_LOCK`
+- `USE_FULL_SCREEN_INTENT`
+- `VIBRATE`
+- `SYSTEM_ALERT_WINDOW`
+- `FOREGROUND_SERVICE`
+
+### 3. Firebase Messaging Service
+The plugin automatically registers a Firebase Messaging Service to handle incoming calls.
+
+### 4. Android Notification Features 📱
+The Android implementation includes comprehensive notification support:
+
+- **🔔 System Notifications**: Incoming calls appear as proper Android notifications with caller information
+- **📱 Full-Screen Intent**: Calls can launch the app on lock screen for immediate visibility
+- **🎵 Ringtone & Vibration**: Uses system default ringtone with vibration pattern for audio/haptic alerts
+- **⚡ Action Buttons**: Accept/Reject buttons directly in notification for quick response
+- **🔕 Auto-Dismiss**: Notifications automatically clear when calls end or are answered
+- **🌙 Do Not Disturb**: Respects system notification settings and priority modes
+
+**Note**: Notification functionality requires notification permissions. The app will request these permissions during login if not already granted.
+
+## Usage
+
+### Authentication
+
+#### `login(options: { accessToken: string })`
+Authenticates with Twilio using a JWT access token:
+- Validates token expiration automatically
+- Stores token securely for app restarts  
+- Registers for VoIP push notifications
+- **Note**: The plugin will reject expired tokens
+
+#### `logout()`
+Logs out the current user and cleans up all session data:
+- Unregisters from VoIP push notifications
+- Clears stored access tokens
+- Ends any active calls
+- Resets all call state
+
+#### `isLoggedIn()`
+Checks if user is currently logged in with a valid (non-expired) token.
+Returns: `{ isLoggedIn: boolean, hasValidToken: boolean, identity?: string }`
+
+The `identity` field contains the user identity extracted from the JWT token if logged in.
+
+#### `makeCall(options: { to: string })`
+Initiates an outgoing call. Requires prior authentication via `login()`.
+
+#### `acceptCall(options: { callSid: string })`
+Accepts an incoming call.
+
+#### `rejectCall(options: { callSid: string })`
+Rejects an incoming call.
+
+#### `endCall(options?: { callSid?: string })`
+Ends the active call or a specific call.
+
+#### `muteCall(options: { muted: boolean, callSid?: string })`
+Mutes or unmutes the microphone.
+
+#### `setSpeaker(options: { enabled: boolean })`
+Enables or disables the speaker. On Android, uses Twilio AudioSwitch to manage audio routing between earpiece, speaker, and connected devices (headsets, Bluetooth, etc.).
+
+#### `getCallStatus()`
+Gets the current call status.
+
+#### `checkMicrophonePermission()`
+Checks if microphone permission is granted.
+
+#### `requestMicrophonePermission()`
+Requests microphone permission from the user.
+
+### Event Listeners
+
+```typescript
+import { CapacitorTwilioVoice } from '@capgo/capacitor-twilio-voice';
+
+// Registration events
+CapacitorTwilioVoice.addListener('registrationSuccess', (data) => {
+  console.log('Successfully registered:', data);
+});
+
+CapacitorTwilioVoice.addListener('registrationFailure', (data) => {
+  console.error('Registration failed:', data);
+});
+
+// Call events
+CapacitorTwilioVoice.addListener('callInviteReceived', (data) => {
+  console.log('Incoming call from:', data.from);
+});
+
+CapacitorTwilioVoice.addListener('callConnected', (data) => {
+  console.log('Call connected:', data);
+});
+
+CapacitorTwilioVoice.addListener('callDisconnected', (data) => {
+  console.log('Call ended:', data);
+});
+
+CapacitorTwilioVoice.addListener('callRinging', (data) => {
+  console.log('Call is ringing:', data);
+});
+
+CapacitorTwilioVoice.addListener('callReconnecting', (data) => {
+  console.log('Call reconnecting:', data);
+});
+
+CapacitorTwilioVoice.addListener('callReconnected', (data) => {
+  console.log('Call reconnected:', data);
+});
+
+CapacitorTwilioVoice.addListener('callQualityWarningsChanged', (data) => {
+  console.log('Quality warnings:', data);
+});
+```
+
+## JWT Token Management
+
+### Token Format
+The plugin expects Twilio access tokens in JWT format with this structure:
+```json
+{
+  "iss": "your-account-sid",
+  "exp": 1234567890,
+  "grants": {
+    "voice": {
+      "outgoing": {
+        "application_sid": "your-app-sid"
+      },
+      "push_credential_sid": "your-push-credential-sid"
+    },
+    "identity": "user-identity"
+  }
+}
+```
+
+### Token Validation
+- Tokens are automatically validated for expiration
+- Invalid or expired tokens will be rejected
+- Use `isLoggedIn()` to check token status
+
+### Backend Integration
+Fetch access tokens from your backend server:
+```typescript
+async function fetchAccessToken(identity: string): Promise<string> {
+  const response = await fetch(`/accessToken?identity=${identity}`);
+  return response.text();
+}
+```
+
+## Testing Requirements
+
+### iOS Simulator Limitations
+- VoIP push notifications don't work in the iOS Simulator
+- Use a physical iOS device for testing incoming calls
+- Outgoing calls work in both Simulator and device
+
+### Android Emulator
+- Requires Google Play Services
+- Firebase messaging works in Android Emulator with Google APIs
+
+## Error Handling
+
+The plugin provides detailed error information:
+```typescript
+try {
+  await CapacitorTwilioVoice.makeCall({ to: '+1234567890' });
+} catch (error) {
+  console.error('Call failed:', error);
+}
+```
+
+Common error scenarios:
+- **Invalid token**: Check token format and expiration
+- **No microphone permission**: Call `requestMicrophonePermission()`
+- **Network issues**: Verify internet connectivity
+- **Invalid phone number**: Use E.164 format (+1234567890)
+
+## Security Notes
+
+- Access tokens are stored in secure device storage
+- Tokens are automatically validated before use
+- No sensitive data is logged in production builds
+- Always use HTTPS for token fetching from your backend
+
+## Platform Support
+
+| Platform | Support | Notes |
+|----------|---------|-------|
+| iOS      | ✅      | Requires iOS 13.0+ |
+| Android  | ✅      | Requires API level 23+ |
+| Web      | ❌      | Not supported |

package/android/build.gradle

@@ -0,0 +1,65 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.7.2'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace "ee.forgr.capacitor_twilio_voice"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation 'com.twilio:voice-android:6.9.+'
+    implementation 'com.twilio:audioswitch:1.2.2'
+    implementation 'com.google.firebase:firebase-messaging:25.0.0'
+    implementation 'androidx.lifecycle:lifecycle-extensions:2.2.0'
+    implementation platform('com.google.firebase:firebase-bom:34.0.0')
+    implementation 'androidx.core:core:1.13.1'
+    implementation 'androidx.media:media:1.6.0'
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,43 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- Permissions for Twilio Voice -->
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />
+    <uses-permission android:name="android.permission.VIBRATE" />
+    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
+
+    <application>
+        <!-- Firebase Messaging Service for Twilio Voice -->
+        <service
+            android:name="ee.forgr.capacitor_twilio_voice.VoiceFirebaseMessagingService"
+            android:exported="false">
+            <intent-filter>
+                <action android:name="com.google.firebase.MESSAGING_EVENT" />
+            </intent-filter>
+        </service>
+
+        <!-- Notification Action Receiver for accept/reject buttons -->
+        <receiver
+            android:name="ee.forgr.capacitor_twilio_voice.NotificationActionReceiver"
+            android:exported="false">
+            <intent-filter>
+                <action android:name="ACTION_ACCEPT_CALL" />
+                <action android:name="ACTION_REJECT_CALL" />
+            </intent-filter>
+        </receiver>
+
+        <!-- Voice Call Foreground Service -->
+        <service
+            android:name="ee.forgr.capacitor_twilio_voice.VoiceCallService"
+            android:enabled="true"
+            android:exported="false"
+            android:foregroundServiceType="microphone" />
+    </application>
+
+</manifest>