@cemscale-voip/voip-sdk 2.0.11 → 2.0.13

package/README.md

@@ -43,78 +43,475 @@ await voip.transfer(callUuid, { targetExtension: '1002', type: 'blind' });
 await voip.hangup(callUuid);
 ```
 
-### Three-Way Calling (Conferencia Tripartita)
+### Three-Way Calling (Conferencia Tripartita) — GUÍA COMPLETA
 
-Three-way calling lets an agent merge an active call with a third party into a
-conference room. The SDK provides two flows:
+> **⚠️ LEE ESTO ANTES DE IMPLEMENTAR.** La tripartita tiene un flujo de varios pasos
+> y varios estados de UI. No es una sola llamada API. Si muestras el timer antes
+> de que la persona conteste, o llamas merge antes de que el participante esté listo,
+> TODO el flujo se rompe.
 
-**Flow 1 — `addCallParticipant` + `mergeCalls` (WebRTC softphone)**
+---
+
+#### RESUMEN del flujo
+
+```
+PASO 0: El agente está en llamada con Persona A. currentCall.state === 'established'.
+PASO 1: El agente presiona "Agregar" → addParticipant('numero de Persona B').
+        La API pone a Persona A en hold y origina llamada a Persona B.
+        threeWaySession.state → 'adding'  ← MOSTRAR "Llamando a Persona B..."
+PASO 2: Persona B contesta su teléfono.
+        threeWaySession.state → 'adding'  ← se mantiene igual, NO cambia solo
+PASO 3: El agente presiona "Fusionar" → mergeThreeWay().
+        Las 3 personas (Agente, A, B) entran a conferencia.
+        threeWaySession.state → 'active'  ← AHORA sí inicia el timer de conferencia
+```
+
+---
 
-The SDK's `useVoIP` hook handles UUID resolution automatically. After a call
-connects, `currentCall.fsChannelUuid` is populated and can be used directly.
+#### FLOW 1 — `addParticipant` + `mergeThreeWay` (WebRTC softphone, recomendado)
+
+Este es el flujo con el hook `useVoIP`. **El hook maneja TODO automáticamente:**
+resolución de UUID de FreeSWITCH, estados de la tripartita, y limpieza al colgar.
+
+##### 1.1 — Configuración inicial
 
 ```typescript
-const { currentCall, addParticipant, mergeThreeWay, swapParticipant, kickParticipant } = useVoIP({
+import { useVoIP } from '@cemscale-voip/voip-sdk';
+
+// Dentro de tu componente React:
+const {
+  // Estado del teléfono
+  isRegistered,               // boolean — SIP registrado?
+  currentCall,                // WebRTCCallInfo | null — datos de la llamada activa
+  error,                      // string | null — último error (resetear con clearError)
+
+  // Acciones de llamada básica
+  startPhone,                 // (ext, password, displayName?) => Promise<void>
+  call,                       // (number) => Promise<WebRTCCallInfo>
+  answer,                     // () => Promise<void>
+  hangup,                     // () => Promise<void>
+  toggleHold,                 // () => Promise<boolean>
+  toggleMute,                 // () => boolean
+
+  // Acciones de tripartita
+  addParticipant,             // (target: string) => Promise<void>
+  mergeThreeWay,              // () => Promise<void>
+  swapParticipant,            // (keepUuid: string, holdUuid: string) => Promise<void>
+  dropParticipant,            // (memberId: string) => Promise<void>
+
+  // Estado de la tripartita
+  threeWaySession,            // ThreeWaySession | null
+} = useVoIP({
   apiUrl: 'https://voip-api.cemscale.com',
-  apiKey: 'csk_live_...',
+  apiKey: 'csk_live_...',     // API key de tu tenant
 });
+```
 
-// Step 1 — Call Person A (normal call)
-await call('+15551234567');
-// Wait for state: 'established'
+##### 1.2 — `ThreeWaySession` (tipo completo)
 
-// Step 2 — Add Person B (Person A goes on hold automatically)
-await addParticipant('+15559999999');
-// Person B is now ringing. When they answer:
+Este objeto describe TODO el estado de la tripartita. Tu UI debe leerlo para decidir qué mostrar.
 
-// Step 3 — Merge all three into conference
-await mergeThreeWay();
-// All three parties in conference. currentCall is now the conference room.
+```typescript
+interface ThreeWaySession {
+  conferenceName: string;       // Nombre de la sala de conferencia (UUID, ej: "page_abc_123")
+  state: 'adding' | 'active' | 'swapping';
+                                // 'adding'   = Persona B está siendo llamada. MOSTRAR "Llamando..."
+                                // 'active'   = Conferencia activa. AHORA iniciar timer.
+                                // 'swapping' = Intercambiando participantes (no mostrar timer propio)
+  participants: ThreeWayParticipant[];  // Solo poblado en state='active'
+  pendingUuid: string | undefined;      // UUID de Persona B. Existe en state='adding'
+  originalBridgedLeg: string | undefined; // UUID de la pata PSTN de Persona A
+}
+
+interface ThreeWayParticipant {
+  uuid: string;                 // UUID del canal FreeSWITCH
+  callerIdNumber: string;       // Número de teléfono
+  callerIdName: string;         // Nombre (o número si no hay nombre)
+  status: 'active' | 'held';    // Estado en la conferencia
+  memberId: string;             // ID de miembro en la conferencia
+}
+```
 
-// Bonus — Swap: go private with one participant
-await swapParticipant(keepUuid, holdUuid);
+##### 1.3 — `WebRTCCallInfo` (campos relevantes para tripartita)
 
-// Bonus — Kick one participant
-await kickParticipant(memberId);
+```typescript
+interface WebRTCCallInfo {
+  id: string;                   // ID local de SIP.js — ** NO USAR para API calls **
+  fsChannelUuid: string | null; // UUID de FreeSWITCH — ** USAR ESTE para API calls **
+                                // null mientras la llamada está conectando
+                                // poblado automáticamente cuando state === 'established'
+  state: string;                // 'ringing' | 'connecting' | 'established' | 'held' | 'terminated' | ...
+  direction: 'inbound' | 'outbound';
+  remoteIdentity: string;       // Número remoto (ej: '+17866302522')
+  remoteDisplayName: string;    // Nombre mostrado
+  held: boolean;
+  muted: boolean;
+}
 ```
 
-**Flow 2 — `mergeDirectCalls` (desk phone / manual)**
+##### 1.4 — Flujo COMPLETO paso a paso
 
-For physical SIP phones where the user manually holds call A and dials call B.
-Does NOT require `addCallParticipant()` first.
+```typescript
+// ═══════════════════════════════════════════════════════════
+// PASO 0: Agente en llamada con Persona A
+// ═══════════════════════════════════════════════════════════
+
+// currentCall.state === 'established'       ← CONDICIÓN para mostrar botón "Agregar"
+// currentCall.fsChannelUuid !== null         ← resuelto automáticamente
+// threeWaySession === null                   ← no hay tripartita activa
+
+// ═══════════════════════════════════════════════════════════
+// PASO 1: Agregar Persona B
+// ═══════════════════════════════════════════════════════════
+
+// UI: Botón "Agregar participante" → input para número → llama a addParticipant
+
+try {
+  await addParticipant('+17866302522');
+  // └─ Internamente el SDK:
+  //    1. Toma currentCall.fsChannelUuid
+  //    2. Llama POST /api/calls/{fsChannelUuid}/add-participant
+  //    3. API pone Persona A en hold (escucha música)
+  //    4. API origina llamada a Persona B vía trunk
+  //    5. Retorna { newCallUuid, originalBridgedLeg }
+  //    6. SDK setea threeWaySession = { state: 'adding', pendingUuid, ... }
+
+  // ⚠️ DESPUÉS DE ESTA LLAMADA:
+  // threeWaySession.state === 'adding'     ← MOSTRAR "Llamando a Persona B..."
+  // threeWaySession.pendingUuid !== undefined ← Persona B está sonando
+  // currentCall aún existe (Persona A en hold)
+  // ❌ NO iniciar timer — Persona B NO ha contestado todavía
+  // ❌ NO llamar a mergeThreeWay() todavía — Persona B no ha contestado
+
+} catch (err) {
+  // addParticipant falló. Persona A vuelve de hold automáticamente.
+  console.error('Error al agregar participante:', err);
+}
+
+// ═══════════════════════════════════════════════════════════
+// PASO 2: Persona B contesta (el agente lo escucha o ve en UI)
+// ═══════════════════════════════════════════════════════════
+
+// El SDK NO notifica automáticamente cuando Persona B contesta.
+// La UI debe mostrar un botón "Fusionar" inmediatamente después de
+// addParticipant. El agente presiona "Fusionar" cuando escucha
+// que Persona B contestó, o cuando ve que pasaron ~10 segundos.
+
+// ═══════════════════════════════════════════════════════════
+// PASO 3: Fusionar en conferencia
+// ═══════════════════════════════════════════════════════════
+
+// UI: Botón "Fusionar" — visible cuando threeWaySession.state === 'adding'
+
+try {
+  await mergeThreeWay();
+  // └─ Internamente el SDK:
+  //    1. Toma currentCall.fsChannelUuid (callUuidA)
+  //    2. Toma threeWaySession.pendingUuid (callUuidB)
+  //    3. Toma threeWaySession.originalBridgedLeg
+  //    4. Llama POST /api/calls/three-way/merge
+  //    5. API mueve todos a conferencia
+  //    6. SDK setea threeWaySession = { state: 'active', participants: [...] }
+
+  // ✅ DESPUÉS DE ESTA LLAMADA:
+  // threeWaySession.state === 'active'     ← AHORA sí iniciar timer de conferencia
+  // threeWaySession.participants.length >= 2  ← Persona A + Persona B (más el agente)
+  // currentCall sigue activo (el agente está en la conferencia)
+
+} catch (err) {
+  console.error('Error al fusionar:', err);
+}
+```
+
+##### 1.5 — Qué mostrar en la UI en CADA estado
 
 ```typescript
-// Detect 2+ active calls from the same extension
-const { activeCalls } = await voip.getActiveCalls();
-const userCalls = activeCalls.filter(
-  c => c.caller_id_number === '1001' || c.destination === '1001'
-);
+// ── SIN LLAMADA ──
+if (!currentCall) {
+  return <Dialpad onCall={call} />;
+}
 
-if (userCalls.length >= 2) {
-  await voip.mergeDirectCalls({
-    callUuidA: userCalls[0].uuid,  // FreeSWITCH channel UUID
-    callUuidB: userCalls[1].uuid,
-  });
-  // Both calls merged into conference. User stays on call A's path.
+// ── LLAMADA ACTIVA, SIN TRIPARTITA ──
+if (currentCall && !threeWaySession) {
+  return (
+    <InCallScreen>
+      <CallTimer startTime={currentCall.answerTime} />
+      <RemoteParty name={currentCall.remoteDisplayName} number={currentCall.remoteIdentity} />
+      <MuteButton active={currentCall.muted} onPress={toggleMute} />
+      <HoldButton active={currentCall.held} onPress={toggleHold} />
+      <HangupButton onPress={hangup} />
+      <AddParticipantButton onPress={() => showAddParticipantInput()} />
+      {/* ↑ Solo mostrar si currentCall.state === 'established' */}
+    </InCallScreen>
+  );
+}
+
+// ── AGREGANDO PARTICIPANTE (Persona B está sonando) ──
+if (threeWaySession?.state === 'adding') {
+  return (
+    <InCallScreen>
+      {/* Persona A sigue en hold — mostrar timer de Persona A */}
+      <CallTimer startTime={currentCall.answerTime} />
+      <RemoteParty name={currentCall.remoteDisplayName} number={currentCall.remoteIdentity} />
+      <HoldIndicator />  {/* Persona A está en hold */}
+
+      {/* Persona B */}
+      <CallingBanner>
+        <Spinner />
+        <Text>Llamando a Persona B...</Text>
+        {/* ❌ NO mostrar timer para Persona B — no ha contestado */}
+      </CallingBanner>
+
+      <MergeButton onPress={mergeThreeWay} />
+      {/* ↑ El agente presiona esto cuando escucha que Persona B contestó */}
+
+      <CancelButton onPress={hangup} />
+      {/* ↑ Cancela todo: cuelga Persona A, Persona B, y al agente */}
+    </InCallScreen>
+  );
+}
+
+// ── CONFERENCIA ACTIVA ──
+if (threeWaySession?.state === 'active') {
+  return (
+    <ConferenceScreen>
+      <ConferenceHeader>
+        <ConferenceIcon />
+        <Text>Conferencia — 3 participantes</Text>
+        <ConferenceTimer startTime={conferenceStartTime} />
+        {/* ↑ AHORA sí iniciar timer */}
+      </ConferenceHeader>
+
+      {threeWaySession.participants.map(p => (
+        <ParticipantRow key={p.uuid}>
+          <ParticipantName name={p.callerIdName} number={p.callerIdNumber} />
+          <ParticipantStatus status={p.status} />
+          {/* p.status === 'held' → mostrar "En espera" */}
+          <SwapButton onPress={() => swapParticipant(p.uuid, getOtherActiveUuid(p))} />
+          {/* ↑ Solo mostrar si hay >1 participante active */}
+          <DropButton onPress={() => dropParticipant(p.memberId)} />
+        </ParticipantRow>
+      ))}
+
+      <MuteButton active={currentCall.muted} onPress={toggleMute} />
+      <EndConferenceButton onPress={hangup} />
+      {/* ↑ Cuelga a TODOS y destruye la conferencia */}
+    </ConferenceScreen>
+  );
 }
 ```
 
-**CRITICAL — UUID types:**
+##### 1.6 — Errores comunes y cómo manejarlos
 
-| ID | Source | Used for |
-|---|---|---|
-| `call.id` | SIP.js local session ID | NOT valid for API calls |
-| `call.fsChannelUuid` | Resolved from FreeSWITCH | `addCallParticipant`, `mergeCalls` |
-| `call.uuid` (from ActiveCall) | `getActiveCalls()` response | `mergeDirectCalls` |
-| `result.newCallUuid` | Response from `addCallParticipant` | Pass to `mergeCalls` as `callUuidB` |
+| Error | Causa | Solución |
+|-------|-------|----------|
+| `"FreeSWITCH UUID not resolved yet"` | Llamaste `addParticipant` antes de que la llamada conecte | Espera a `currentCall.state === 'established'` y `currentCall.fsChannelUuid !== null` |
+| `"No active call"` | `currentCall` es null | Verifica que haya una llamada activa antes de mostrar el botón |
+| `"No pending participant to merge"` | `threeWaySession.pendingUuid` es undefined | Solo mostrar botón "Fusionar" cuando `threeWaySession?.state === 'adding'` y `threeWaySession?.pendingUuid` existe |
+| Timer se inicia antes de contestar | Tu UI inicia el timer en state='adding' | Solo iniciar timer cuando `threeWaySession.state === 'active'` |
+| La llamada se cuelga al hacer merge | Llamaste merge antes de que Persona B conteste | Asegúrate de que Persona B ya contestó antes de fusionar |
+| `addParticipant` lanza error 500 | El backend no pudo originar a Persona B | Mostrar el mensaje de error al agente. La llamada con Persona A se reanuda sola. |
 
-**Manual UUID resolution (for custom UIs):**
+---
+
+#### FLOW 2 — `mergeDirectCalls` (teléfono físico / desk phone)
+
+Para cuando el agente usa un teléfono físico (Yealink, Grandstream) y manualmente:
+1. Llama a Persona A
+2. Pone en hold
+3. Marca a Persona B
+4. Quiere fusionar ambas
+
+**NO usa `addParticipant`.** Solo detecta las 2 llamadas activas y las fusiona.
 
 ```typescript
-const fsUuid = await voip.resolveCallFsUuid('1001', '+15551234567', 'outbound');
-if (fsUuid) {
-  const result = await voip.addCallParticipant(fsUuid, { toNumber: '+15559999999' });
+import { VoIPClient } from '@cemscale-voip/voip-sdk';
+
+const voip = new VoIPClient({
+  apiUrl: 'https://voip-api.cemscale.com',
+  apiKey: 'csk_live_...',
+});
+
+// ═══════════════════════════════════════════════════════
+// PASO 1: Detectar 2+ llamadas activas de la misma extensión
+// ═══════════════════════════════════════════════════════
+
+// Hacer polling cada 5 segundos
+const pollInterval = setInterval(async () => {
+  const { activeCalls } = await voip.getActiveCalls();
+
+  // Filtrar llamadas de la extensión del agente
+  const agentExt = '1001';
+  const myCalls = activeCalls.filter(c =>
+    c.caller_id_number === agentExt || c.destination === agentExt
+  );
+
+  // ¿Hay 2 o más llamadas activas?
+  if (myCalls.length >= 2) {
+    // Mostrar botón "Fusionar" con opción de seleccionar cuáles 2
+    showMergeButton(myCalls);
+  } else {
+    hideMergeButton();
+  }
+}, 5000);
+
+// ═══════════════════════════════════════════════════════
+// PASO 2: Fusionar las 2 llamadas seleccionadas
+// ═══════════════════════════════════════════════════════
+
+async function handleMerge(callA: ActiveCall, callB: ActiveCall) {
+  try {
+    const result = await voip.mergeDirectCalls({
+      callUuidA: callA.uuid,  // ⚠️ uuid de FreeSWITCH, NO call_uuid
+      callUuidB: callB.uuid,
+    });
+
+    console.log('Conferencia creada:', result.conferenceName);
+    // result.participants → Array con los 3 participantes
+    // La conferencia se destruye sola cuando el agente cuelga
+
+  } catch (err) {
+    console.error('Error al fusionar:', err);
+  }
+}
+
+// ═══════════════════════════════════════════════════════
+// LIMPIEZA
+// ═══════════════════════════════════════════════════════
+
+// Cuando el componente se desmonta:
+clearInterval(pollInterval);
+```
+
+##### 2.1 — Formato de `ActiveCall` (de `getActiveCalls()`)
+
+```typescript
+interface ActiveCall {
+  uuid: string;             // UUID del canal FreeSWITCH — USAR ESTE
+  call_uuid: string;        // UUID de la sesión de llamada (compartido entre A-leg y B-leg)
+  caller_id_number: string; // Quién llama (extensión o número externo)
+  caller_id_name: string;   // Nombre del caller
+  destination: string;      // Número marcado
+  direction: string;        // 'inbound' | 'outbound'
+  callstate: string;        // 'ACTIVE' | 'EARLY' | 'RINGING' | 'HANGUP'
+  answered: boolean;
+  on_hold: boolean;
+}
+```
+
+##### 2.2 — IMPORTANTE: No confundir los UUIDs
+
+```
+activeCall.uuid      → "a1b2c3d4-..."  ← USAR ESTE para mergeDirectCalls
+activeCall.call_uuid → "a1b2c3d4-..."  ← NO USAR (es el mismo que el de la otra pata)
+
+Una llamada tiene 2 canales (A-leg y B-leg) que comparten el MISMO call_uuid
+pero tienen DIFERENTE uuid. mergeDirectCalls necesita los uuid de canal.
+```
+
+---
+
+#### FLOW 3 — `addCallParticipant` + `mergeCalls` sin hook (VoIPClient directo)
+
+Si NO estás usando `useVoIP` (estás usando `VoIPClient` + `WebRTCPhone` manualmente):
+
+```typescript
+import { VoIPClient, WebRTCPhone } from '@cemscale-voip/voip-sdk';
+
+const voip = new VoIPClient({ apiUrl: '...', apiKey: '...' });
+const phone = new WebRTCPhone({ ... });
+
+// ════════ PASO 1: Hacer llamada a Persona A ════════
+const callInfo = await phone.call('+17863402240');
+// Esperar: callInfo.state === 'established'
+
+// ════════ PASO 2: Resolver el UUID de FreeSWITCH ════════
+const fsUuid = await voip.resolveCallFsUuid(
+  callInfo.remoteIdentity.includes('100') ? callInfo.remoteIdentity : '1001', // extensión
+  callInfo.remoteIdentity,   // número remoto
+  callInfo.direction         // 'outbound' | 'inbound'
+);
+
+if (!fsUuid) {
+  throw new Error('No se pudo resolver el UUID de FreeSWITCH. ¿La llamada sigue activa?');
 }
+// fsUuid → "53c4b1ef-487c-438a-8254-c99ef17a3a26" (UUID real de FreeSWITCH)
+
+// ════════ PASO 3: Agregar Persona B ════════
+const { newCallUuid, originalBridgedLeg } = await voip.addCallParticipant(fsUuid, {
+  toNumber: '+17866302522',  // Número externo (E.164)
+  // toExtension: '1004',    // O extensión interna
+});
+
+// ⚠️ Persona B está SONANDO (no ha contestado)
+// newCallUuid → UUID del canal de Persona B
+// originalBridgedLeg → UUID de la pata PSTN de Persona A
+
+// ════════ PASO 4: Esperar a que Persona B conteste ════════
+// El agente escucha que Persona B contestó, o la UI muestra el botón "Fusionar"
+
+// ════════ PASO 5: Fusionar ════════
+const result = await voip.mergeCalls({
+  callUuidA: fsUuid,              // UUID de FreeSWITCH de la llamada original
+  callUuidB: newCallUuid,         // UUID de Persona B (de addCallParticipant)
+  bridgedLegA: originalBridgedLeg, // UUID de la pata PSTN de Persona A
+  conferenceName: undefined,       // Auto-generado si no se especifica
+});
+
+// result.conferenceName → "page_15d0851a_..."
+// result.participants → [{ callerIdNumber, callerIdName, uuid, status, memberId }, ...]
+// result.state → 'active'
+```
+
+---
+
+#### RESUMEN de estados y UUIDs
+
+| Contexto | Qué UUID usar | De dónde viene |
+|----------|--------------|----------------|
+| `addParticipant` | `currentCall.fsChannelUuid` | Resuelto automático por useVoIP al conectar |
+| `mergeThreeWay` (callUuidA) | `currentCall.fsChannelUuid` | Mismo que arriba |
+| `mergeThreeWay` (callUuidB) | `threeWaySession.pendingUuid` | Retornado por `addParticipant` |
+| `mergeThreeWay` (bridgedLegA) | `threeWaySession.originalBridgedLeg` | Retornado por `addParticipant` |
+| `mergeDirectCalls` (callUuidA/B) | `activeCall.uuid` | De `getActiveCalls()` |
+| `resolveCallFsUuid` (manual) | Retorna `string \| null` | Lo usas para `addCallParticipant` |
+| `swapParticipant` (keepUuid/holdUuid) | `participant.uuid` | De `threeWaySession.participants[i].uuid` |
+| `dropParticipant` (memberId) | `participant.memberId` | De `threeWaySession.participants[i].memberId` |
+
+| ❌ NO USAR NUNCA | Por qué |
+|------------------|---------|
+| `currentCall.id` | Es el ID local de SIP.js, no el UUID de FreeSWITCH |
+| `activeCall.call_uuid` | Es compartido entre A-leg y B-leg, no identifica un canal único |
+
+---
+
+#### MÁQUINA DE ESTADOS de threeWaySession
+
+```
+null ──addParticipant()──> { state: 'adding', pendingUuid: '...' }
+                                       │
+                              mergeThreeWay()
+                                       │
+                                       ▼
+                              { state: 'active', participants: [...] }
+                                       │
+                          swapParticipant()
+                                       │
+                                       ▼
+                              { state: 'swapping', ... }
+                                       │ (automático al completar)
+                                       ▼
+                              { state: 'active', participants: [...] }
+                                       │
+                          dropParticipant() (si quedan ≤1)
+                                       │
+                                       ▼
+                                      null
+                                       │
+                          currentCall === null
+                                       │
+                                       ▼
+                                      null  (limpieza automática)
 ```
 
 ### Extensions