@voipsdk/react-native-voipcloud 0.2.1 → 1.0.0

package/README.md

@@ -1,25 +1,45 @@
-# react-native-voipcloud
+# @voipsdk/react-native-voipcloud
 
-> Platform: Android (RN 0.70+, Android 12+).
+> Public PJSIP VoIP SDK for React Native — Android only (RN 0.70+, Android 12 / API 31+).  
+> Package: `@voipsdk/react-native-voipcloud@1.0.0`
+
+---
+
+## Requirements
+
+| | |
+|---|---|
+| React Native | ≥ 0.70 |
+| Android | API 31+ (Android 12+) |
+| ABIs | `arm64-v8a`, `armeabi-v7a`, `x86_64` (emulator) |
+| iOS | Stub only — rejects with `VC_NOT_IMPLEMENTED` |
 
 ---
 
 ## Install
 
 ```bash
-npm install react-native-voipcloud
+npm install @voipsdk/react-native-voipcloud
 # or:
-yarn add react-native-voipcloud
+yarn add @voipsdk/react-native-voipcloud
 ```
 
-Android autolinks the `VoipCloudPackage` if you are on React Native 0.60+.
+Rebuild the native app after install:
+
+```bash
+cd android && ./gradlew clean assembleDebug
+```
+
+React Native 0.60+ autolinks `VoipCloudPackage`. For older RN, add manually in `MainApplication.java`:
 
-For older RN versions, add manually to `MainApplication.java`:
 ```java
 packages.add(new com.voipcloud.sdk.rn.VoipCloudPackage());
 ```
 
-Required `AndroidManifest.xml` permissions (declare in **your** app):
+### Android permissions
+
+Declare in **your** app `AndroidManifest.xml`:
+
 ```xml
 <uses-permission android:name="android.permission.INTERNET" />
 <uses-permission android:name="android.permission.RECORD_AUDIO" />
@@ -29,144 +49,188 @@ Required `AndroidManifest.xml` permissions (declare in **your** app):
 <uses-permission android:name="android.permission.FOREGROUND_SERVICE_PHONE_CALL" />
 ```
 
-Runtime permissions to request:
-`RECORD_AUDIO`, `POST_NOTIFICATIONS` (Android 13+), `BLUETOOTH_CONNECT`.
+Request at runtime: `RECORD_AUDIO`, `POST_NOTIFICATIONS` (Android 13+), `BLUETOOTH_CONNECT`.
 
 ---
 
 ## Quick start
 
 ```ts
-import { VoipCloud } from 'react-native-voipcloud';
-
-// 1. Apply the license your operator issued.
-try {
-    await VoipCloud.License.set(myToken);
-} catch (e) {
-    // VC_LICENSE — token format / signature / expiry / bundle issues.
-}
-
-// 2. Start the engine.
-await VoipCloud.init({ userAgent: 'acme-voip/1.0' });
-
-// 3. Register a SIP account.
-const accId = await VoipCloud.register({
-    uri:       'sip:alice@example.com',
-    registrar: 'sip:example.com:5061;transport=tls',
-    username:  'alice',
-    password:  '••••••',
-    transport: 'TLS',
+import { VoipCloud } from '@voipsdk/react-native-voipcloud';
+
+// 1. Start PJSIP endpoint (required before any SIP call).
+await VoipCloud.init({ userAgent: 'my-app/1.0' });
+
+// 2. Register a SIP account → returns numeric accountId.
+const accountId = await VoipCloud.register({
+  uri:       'sip:alice@example.com',
+  registrar: 'sip:pbx.example.com:5061;transport=tls',
+  username:  'alice',
+  password:  'secret',
+  transport: 'TLS',   // 'UDP' | 'TCP' | 'TLS'
 });
 
-// 4. Make a call.
-const callId = await VoipCloud.makeCall(accId, 'sip:bob@example.com');
+// 3. Place or receive calls.
+const callId = await VoipCloud.makeCall(accountId, 'sip:bob@example.com');
+await VoipCloud.answer(callId);          // incoming
+await VoipCloud.hangup(callId);
 
-// 5. In-call controls.
-await VoipCloud.hold(callId);                      // put on hold
-await VoipCloud.unhold(callId);                    // resume
-await VoipCloud.mute(callId, true);                // mute mic
-await VoipCloud.sendDtmf(callId, '1234#');         // send DTMF
-await VoipCloud.transferCall(callId, 'sip:charlie@example.com'); // blind transfer
-await VoipCloud.hangup(callId);                    // end this call
-await VoipCloud.hangupAllCalls();                  // end every active call
+// 4. In-call controls.
+await VoipCloud.hold(callId);
+await VoipCloud.unhold(callId);
+await VoipCloud.mute(callId, true);
+await VoipCloud.sendDtmf(callId, '1234#');
+await VoipCloud.transferCall(callId, 'sip:charlie@example.com');
+await VoipCloud.hangupAllCalls();
 
-// 6. Subscribe to events.
+// 5. Events (always remove in useEffect cleanup).
 const sub = VoipCloud.on('callState', ({ callId, state }) => {
-    console.log('call', callId, '→', state);
-});
-const subMedia = VoipCloud.on('callMediaState', ({ callId, hasAudio, isHold, isMuted }) => {
-    console.log('media', callId, { hasAudio, isHold, isMuted });
+  console.log('call', callId, state);
 });
-// sub.remove() / subMedia.remove() when done
-
-// 7. License refresh is automatic.
-//    If your token's payload includes a `ref` field, the SDK starts a
-//    24 h refresher in the background after `License.set` succeeds.
-//    No URL configuration needed on the app side.
-//
-//    Optional: stop the refresher when the user logs out.
-await VoipCloud.License.stopRefresh();
+sub.remove();
 
-// 8. Tear down the SDK on app exit.
+// 6. Unregister and tear down.
+await VoipCloud.unregister(accountId);
 await VoipCloud.shutdown();
 ```
 
+### React example
+
+```tsx
+import { useEffect } from 'react';
+import { VoipCloud } from '@voipsdk/react-native-voipcloud';
+
+export function useVoipEvents() {
+  useEffect(() => {
+    const subs = [
+      VoipCloud.on('registrationState', e =>
+        console.log('reg', e.accountId, e.code, e.reason)),
+      VoipCloud.on('incomingCall', e =>
+        console.log('incoming', e.callId, e.from)),
+      VoipCloud.on('callState', e =>
+        console.log('call', e.callId, e.state)),
+    ];
+    return () => subs.forEach(s => s.remove());
+  }, []);
+}
+```
+
 ---
 
-## Error codes (Promise rejection.code)
-
-Mọi method trả Promise; khi reject, `code` mang một trong các mã sau.
-Cụ thể lỗi license được tách thành các mã granular để app dễ hiển thị
-thông báo phù hợp.
-
-License (từ `License.set` / `License.status`):
-
-| code                  | Ý nghĩa                                              |
-|-----------------------|------------------------------------------------------|
-| `VC_NO_LICENSE`       | Chưa cài token, hoặc token đã bị reset               |
-| `VC_BAD_FORMAT`       | Token sai định dạng (không phải base64url JWT)       |
-| `VC_BAD_SIGNATURE`    | Chữ ký Ed25519 không hợp lệ                          |
-| `VC_EXPIRED`          | Token hết hạn                                        |
-| `VC_NOT_ACTIVE`       | Token bị tạm khoá (status ≠ active)                  |
-| `VC_REVOKED`          | Token đã bị thu hồi                                  |
-| `VC_BUNDLE_MISMATCH`  | Bundle id app không khớp `bundle_id` trong token     |
-| `VC_PAYLOAD_TOO_BIG`  | Payload token quá lớn                                |
-| `VC_CLOCK_SKEW`       | Đồng hồ thiết bị bị chỉnh lùi so với mốc server     |
-| `VC_LICENSE`          | Lỗi license chung không khớp các mã trên             |
-| `VC_STATUS`           | Đọc trạng thái thất bại                              |
-
-Endpoint / call:
-
-| code                  | Ý nghĩa                                              |
-|-----------------------|------------------------------------------------------|
-| `VC_INIT`             | Endpoint không khởi động được                        |
-| `VC_SHUTDOWN`         | Lỗi khi `shutdown()` dọn endpoint                    |
-| `VC_REGISTER`         | `register()` thất bại                                |
-| `VC_UNREGISTER`       | `unregister()` thất bại                              |
-| `VC_NO_ACCOUNT`       | accountId không tồn tại                              |
-| `VC_MAKE_CALL`        | `makeCall()` thất bại (bao gồm `VC_CCU_EXCEEDED`)    |
-| `VC_CCU_EXCEEDED`     | Vượt số cuộc gọi đồng thời license cho phép          |
-| `VC_NO_CALL`          | callId không tồn tại                                 |
-| `VC_ANSWER`           | `answer()` thất bại                                  |
-| `VC_HANGUP`           | `hangup()` thất bại                                  |
-| `VC_HOLD` / `VC_UNHOLD` | `hold()` / `unhold()` thất bại                     |
-| `VC_MUTE`             | `mute()` thất bại (vd: chưa init endpoint)            |
-| `VC_DTMF`             | `sendDtmf()` thất bại                                |
-| `VC_TRANSFER`         | `transferCall()` thất bại                            |
-| `VC_HANGUP_ALL`       | `hangupAllCalls()` thất bại                          |
-
-`message` đính kèm là `pj_strerror` từ PJSIP, hữu ích khi log.
+## API reference
+
+| Method | Description |
+|--------|-------------|
+| `init(config?)` | Create and start PJSIP endpoint |
+| `shutdown()` | Hang up all, destroy endpoint |
+| `register(account)` | Register SIP account → `accountId` |
+| `unregister(accountId)` | Unregister account |
+| `makeCall(accountId, uri)` | Outbound call → `callId` |
+| `answer(callId)` | Answer incoming call |
+| `hangup(callId)` | End one call |
+| `hangupAllCalls()` | End all active calls |
+| `hold(callId)` / `unhold(callId)` | Hold / resume |
+| `mute(callId, on)` | Mute / unmute microphone |
+| `sendDtmf(callId, digits)` | Send DTMF tones |
+| `transferCall(callId, uri)` | Blind transfer |
+| `on(event, callback)` | Subscribe to native events |
+
+### `InitConfig`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `userAgent` | `string` | SIP User-Agent header |
+| `stunServer` | `string` | STUN server URI |
+| `logLevel` | `number` | PJSIP log level (0–6) |
+
+### `AccountConfig`
+
+| Field | Type | Required |
+|-------|------|----------|
+| `uri` | `string` | SIP AOR, e.g. `sip:user@domain` |
+| `registrar` | `string` | Registrar URI |
+| `username` | `string` | Auth username |
+| `password` | `string` | Auth password |
+| `transport` | `'UDP' \| 'TCP' \| 'TLS'` | Signaling transport |
 
 ---
 
 ## Events
 
-Account / call lifecycle (do PJSIP phát):
+| Event | Payload highlights |
+|-------|-------------------|
+| `registrationState` | `{ accountId, code, reason }` |
+| `incomingCall` | `{ accountId, callId, from, to }` |
+| `callState` | `{ callId, state, code, reason }` |
+| `callMediaState` | `{ callId, hasAudio, isHold, isMuted }` |
+| `callHold` / `callUnhold` | `{ callId }` |
+| `callMute` | `{ callId, isMuted }` |
+| `callDtmfSent` | `{ callId, digits }` |
+| `callTransfer` | `{ callId, destinationUri }` |
+| `callTransferStatus` | `{ callId, statusCode, reason, finalNotify }` |
+| `incomingDtmf` | `{ callId, digit, duration }` |
 
-```ts
-VoipCloud.on('registrationState', e => /* { accountId, code, reason } */);
-VoipCloud.on('incomingCall',      e => /* { accountId, callId, from, to } */);
-VoipCloud.on('callState',         e => /* { callId, state, code, reason } */);
-VoipCloud.on('callMediaState',    e => /* { callId, hasAudio, isHold, isMuted } */);
-```
+---
+
+## Error handling
 
-Per-action xác nhận (bridge phát sau khi action thành công — tiện cho
-UI bind 1-1 với từng nút bấm):
+Every method returns a `Promise`. Failures reject with `error.code` (string). The bridge **never crashes** the host app for API misuse or recoverable PJSIP errors.
 
 ```ts
-VoipCloud.on('callHold',      e => /* { callId } */);
-VoipCloud.on('callUnhold',    e => /* { callId } */);
-VoipCloud.on('callMute',      e => /* { callId, isMuted } */);
-VoipCloud.on('callDtmfSent',  e => /* { callId, digits } */);
-VoipCloud.on('callTransfer',  e => /* { callId, destinationUri } */);
+try {
+  await VoipCloud.init();
+} catch (e: any) {
+  console.warn(e.code, e.message);
+}
 ```
 
-Remote-driven (PJSIP forward từ callback gốc):
+| code | Meaning |
+|------|---------|
+| `VC_NOT_LINKED` | Native module not linked — reinstall package and rebuild Android |
+| `VC_NATIVE_LOAD` | `libvoipcloud.so` failed to load (missing ABI or AAR) |
+| `VC_NOT_INITIALIZED` | SIP API called before successful `init()` |
+| `VC_INVALID_ARGUMENT` | Missing or empty required field |
+| `VC_INIT` | Endpoint failed to start |
+| `VC_SHUTDOWN` | Shutdown error |
+| `VC_REGISTER` / `VC_UNREGISTER` | Account registration error |
+| `VC_NO_ACCOUNT` | Unknown `accountId` |
+| `VC_MAKE_CALL` / `VC_ANSWER` / `VC_HANGUP` | Call operation error |
+| `VC_NO_CALL` | Unknown `callId` |
+| `VC_HOLD` / `VC_UNHOLD` / `VC_MUTE` / `VC_DTMF` / `VC_TRANSFER` | In-call control error |
 
-```ts
-// REFER multi-stage: nhận một event mỗi NOTIFY; finalNotify=true là kết quả cuối.
-VoipCloud.on('callTransferStatus', e => /* { callId, statusCode, reason, finalNotify } */);
+---
 
-// DTMF do đầu remote gửi qua RTP (RFC 2833).
-VoipCloud.on('incomingDtmf',       e => /* { callId, digit, duration } */);
-```
+## Native artifacts (Android)
+
+Shipped inside `android/src/main/libs/voipcloud-release.aar`:
+
+| Artifact | Name |
+|----------|------|
+| Shared library | `libvoipcloud.so` — `System.loadLibrary("voipcloud")` |
+| SWIG JNI class | `com.voipcloud.sdk.voipcloudJNI` |
+| RN bridge module | `VoipsdkReactNativeVoipcloud` (JS: `VoipCloud`) |
+| Java SDK | `com.voipcloud.sdk.*` |
+
+This package does **not** use upstream `libpjsua2.so` / `pjsua2JNI`.
+
+---
+
+## Troubleshooting
+
+**`VC_NOT_LINKED` after install**  
+Run `cd android && ./gradlew clean assembleDebug`. Confirm `@voipsdk/react-native-voipcloud` appears in `settings.gradle` / autolinking.
+
+**`VC_NATIVE_LOAD`**  
+Ensure your device ABI is supported (`arm64-v8a` on most phones). For release builds, R8 applies ProGuard rules from the AAR automatically.
+
+**Registration fails (`VC_REGISTER`)**  
+Check `registrar`, credentials, and network. TLS requires a valid server certificate or appropriate PJSIP TLS settings on the PBX side.
+
+**No audio**  
+Grant `RECORD_AUDIO` at runtime before placing a call.
+
+---
+
+## License
+
+UNLICENSED — see package metadata. Contact the author for commercial terms.

package/android/build.gradle

@@ -1,11 +1,11 @@
-// react-native-voipcloud — Android library module.
+// @voipsdk/react-native-voipcloud — Android library module.
 //
-// Consumer apps that include this package via Gradle pull in:
-//   * com.voipcloud.sdk.* from voipcloud-release.aar
-//   * com.voipcloud.sdk.rn.* React Native bridge classes (this module)
+// npm: @voipsdk/react-native-voipcloud
+// native module: VoipsdkReactNativeVoipcloud (VoipCloudModule.getName())
 //
-// The AAR ships its own ProGuard rules (proguard.txt) which R8 auto-
-// applies to the consumer release build; no extra setup needed.
+// Consumer apps pull in:
+//   * com.voipcloud.sdk.* from voipcloud-release.aar
+//   * com.voipcloud.sdk.rn.* React Native bridge (this module)
 
 buildscript {
     repositories {
@@ -52,7 +52,7 @@ repositories {
 }
 
 dependencies {
-    // Prebuilt PJSIP + license layer (com.voipcloud.sdk.*).
+    // Prebuilt PJSIP SDK (com.voipcloud.sdk.*).
     implementation(name: 'voipcloud-release', ext: 'aar')
 
     // Pin to a permissive range — the consumer app controls the actual