@cemscale-voip/voip-sdk 2.0.15 → 2.0.17

package/README.md

@@ -43,12 +43,13 @@ await voip.transfer(callUuid, { targetExtension: '1002', type: 'blind' });
 await voip.hangup(callUuid);
 ```
 
-### Three-Way Calling (Conferencia Tripartita) — GUÍA COMPLETA
+### Three-Way Calling (Conferencia Tripartita) — Conference-Based, 1-Step
 
-> **⚠️ 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.
+> The three-way calling system uses **FreeSWITCH conferences**. When you add a
+> participant, both call legs are transferred into a conference immediately.
+> Person A is put on hold (muted + deaf + hears MOH). Person B rings directly
+> into the conference. **No separate merge step is needed** — the conference is
+> active from the moment you call `addParticipant()`.
 
 ---
 
@@ -57,173 +58,143 @@ await voip.hangup(callUuid);
 ```
 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
+        La API transfiere ambas patas a conferencia, pone A en hold (MOH),
+        y origina llamada a B directamente dentro de la conferencia.
+        threeWaySession.state → 'dialing'  ← MOSTRAR "Llamando a Persona B..."
+PASO 2: Persona B contesta → entra automáticamente a la conferencia.
+        El SDK detecta via polling → threeWaySession.state → 'holding'
+        El agente habla con B, A sigue en hold (MOH).
+PASO 3a: SWAP — El agente quiere hablar con A en privado.
+        swapParticipant(keepUuid=A, holdUuid=B) → B va a hold (MOH), A vuelve.
+PASO 3b: MERGE — El agente presiona "Conferencia" (todos hablan).
+        mergeThreeWay() → Todos salen de hold, los 3 se escuchan.
+PASO 3c: CANCEL — Persona B no contestó.
+        cancelAddParticipant() → Mata a B, reanuda a A, conferencia 2 personas.
+PASO 4:  KICK — Sacar a alguien específico.
+        dropParticipant(memberUuid) → Esa persona sale de la conferencia.
 ```
 
 ---
 
-#### 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.
+#### FLOW 1 — `useVoIP` hook (WebRTC softphone, recomendado)
 
 ##### 1.1 — Configuración inicial
 
 ```typescript
 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
+  currentCall,                // WebRTCCallInfo | null — llamada activa
+  error,                      // string | null — último error
   startPhone,                 // (ext, password, displayName?) => Promise<void>
   call,                       // (number) => Promise<WebRTCCallInfo>
-  answer,                     // () => Promise<void>
   hangup,                     // () => Promise<void>
-  toggleHold,                 // () => Promise<boolean>
   toggleMute,                 // () => boolean
 
-  // Acciones de tripartita
+  // Three-way call
   addParticipant,             // (target: string) => Promise<void>
-  mergeThreeWay,              // () => Promise<void>
-  swapParticipant,            // (keepUuid: string, holdUuid: string) => Promise<void>
-  dropParticipant,            // (memberId: string) => Promise<void>
+  mergeThreeWay,              // () => Promise<void>  — unmute/undeaf todos
+  swapParticipant,            // (keepUuid, holdUuid) => Promise<void>
+  dropParticipant,            // (memberUuid: string) => Promise<void>
+  cancelAddParticipant,       // () => Promise<void>  — B no contestó
+  endThreeWay,                // () => Promise<void>
 
-  // Estado de la tripartita
   threeWaySession,            // ThreeWaySession | null
 } = useVoIP({
   apiUrl: 'https://voip-api.cemscale.com',
-  apiKey: 'csk_live_...',     // API key de tu tenant
+  apiKey: 'csk_live_...',
 });
 ```
 
-##### 1.2 — `ThreeWaySession` (tipo completo)
-
-Este objeto describe TODO el estado de la tripartita. Tu UI debe leerlo para decidir qué mostrar.
+##### 1.2 — `ThreeWaySession` y `ThreeWayParticipant`
 
 ```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
+  conferenceName: string;       // "3way_<tenantId>_<random>"
+  state: 'dialing' | 'holding' | 'active' | 'swapping';
+  participants: ThreeWayParticipant[];
+  pendingUuid?: string;        // UUID de Persona B mientras suena
+  heldMemberUuid?: string;     // UUID del participante en hold
+  originalBridgedLeg?: string;
 }
 
 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
-}
-```
-
-##### 1.3 — `WebRTCCallInfo` (campos relevantes para tripartita)
-
-```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;
+  uuid: string;                // UUID del canal FreeSWITCH
+  memberId: string;            // ID de miembro en la conferencia
+  callerIdNumber: string;      // "+17865551234" o "1002"
+  callerIdName: string;        // "John Smith"
+  muted: boolean;              // true si está muteado
+  deaf: boolean;               // true si está ensordecido
+  status: 'active' | 'held';   // 'held' = muted + deaf + MOH
 }
 ```
 
-##### 1.4 — Flujo COMPLETO paso a paso
+##### 1.3 — Flujo COMPLETO paso a paso
 
 ```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
+// currentCall.state === 'established'  ← condición para botón "Agregar"
+// threeWaySession === null
 
 // ═══════════════════════════════════════════════════════════
 // PASO 1: Agregar Persona B
 // ═══════════════════════════════════════════════════════════
+await addParticipant('+17866302522');
+// La API:
+//   1. Transfiere WebRTC + Persona A a conferencia (uuid_transfer -both)
+//   2. Mutea + ensordece a Persona A + le pone MOH (uuid_displace)
+//   3. Origina llamada a Persona B directamente a la conferencia
+//   4. Retorna inmediatamente
+
+// DESPUÉS:
+// threeWaySession.state === 'dialing'     ← Persona B está sonando
+// threeWaySession.conferenceName !== ''   ← Conferencia YA existe
+// ❌ NO iniciar timer — B no ha contestado
 
-// 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 (detectado por polling automático)
+// ═══════════════════════════════════════════════════════════
+// El hook hace polling de getConferenceMembers() cada 2s.
+// Cuando detecta que B entró a la conferencia:
+// threeWaySession.state → 'holding'
+// threeWaySession.participants → [agente(active), A(held), B(active)]
+// El agente habla con B. A escucha MOH.
 
 // ═══════════════════════════════════════════════════════════
-// PASO 2: Persona B contesta (el agente lo escucha o ve en UI)
+// PASO 3a: SWAP — Hablar con A, poner B en hold
 // ═══════════════════════════════════════════════════════════
+await swapParticipant(personA.uuid, personB.uuid);
+// B → muted + deaf + MOH
+// A → unmuted + undeaf + stop MOH
+// threeWaySession.state → 'holding'
 
-// 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 3b: MERGE — Todos hablan (conferencia tripartita)
+// ═══════════════════════════════════════════════════════════
+await mergeThreeWay();
+// Desmutea + undeaf a TODOS los participantes en hold
+// threeWaySession.state → 'active'
+// ✅ AHORA sí iniciar timer de conferencia
 
 // ═══════════════════════════════════════════════════════════
-// PASO 3: Fusionar en conferencia
+// PASO 3c: CANCEL — B no contestó
 // ═══════════════════════════════════════════════════════════
+await cancelAddParticipant();
+// Mata canal de B, desmutea + undeaf a A
+// Conferencia sigue con 2 personas (agente + A)
 
-// 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);
-}
+// ═══════════════════════════════════════════════════════════
+// PASO 4: KICK — Sacar a alguien de la conferencia
+// ═══════════════════════════════════════════════════════════
+await dropParticipant(personB.uuid);
+// B sale de la conferencia (su canal cuelga)
+// Si solo queda 1 participante, threeWaySession → null
 ```
 
-##### 1.5 — Qué mostrar en la UI en CADA estado
+##### 1.4 — Qué mostrar en la UI en CADA estado
 
 ```typescript
 // ── SIN LLAMADA ──
@@ -238,281 +209,182 @@ if (currentCall && !threeWaySession) {
       <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') {
+// ── DIALING — Persona B está sonando ──
+if (threeWaySession?.state === 'dialing') {
   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>
+      <CancelButton onPress={cancelAddParticipant} />
+      <HangupButton onPress={hangup} />
+    </InCallScreen>
+  );
+}
 
-      <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 */}
+// ── HOLDING — Un participante en hold, otro activo ──
+if (threeWaySession?.state === 'holding' || threeWaySession?.state === 'swapping') {
+  return (
+    <InCallScreen>
+      {threeWaySession.participants.map(p => (
+        <ParticipantRow key={p.uuid}>
+          <ParticipantName name={p.callerIdName} number={p.callerIdNumber} />
+          <ParticipantStatus status={p.status} />  {/* 'held' o 'active' */}
+          {p.status === 'held' && (
+            <UnholdButton onPress={() => {
+              const other = threeWaySession.participants.find(x => x.uuid !== p.uuid && x.status === 'active');
+              if (other) swapParticipant(p.uuid, other.uuid);
+            }} />
+          )}
+        </ParticipantRow>
+      ))}
+      <MergeButton onPress={mergeThreeWay} label="Conferencia (3)" />
+      <HangupButton onPress={hangup} />
     </InCallScreen>
   );
 }
 
-// ── CONFERENCIA ACTIVA ──
+// ── ACTIVE — Conferencia tripartita (todos hablan) ──
 if (threeWaySession?.state === 'active') {
   return (
     <ConferenceScreen>
-      <ConferenceHeader>
-        <ConferenceIcon />
-        <Text>Conferencia — 3 participantes</Text>
-        <ConferenceTimer startTime={conferenceStartTime} />
-        {/* ↑ AHORA sí iniciar timer */}
-      </ConferenceHeader>
-
+      <ConferenceTimer startTime={conferenceStartTime} />
       {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)} />
+          <DropButton onPress={() => dropParticipant(p.uuid)} />
         </ParticipantRow>
       ))}
-
-      <MuteButton active={currentCall.muted} onPress={toggleMute} />
       <EndConferenceButton onPress={hangup} />
-      {/* ↑ Cuelga a TODOS y destruye la conferencia */}
     </ConferenceScreen>
   );
 }
 ```
 
-##### 1.6 — Errores comunes y cómo manejarlos
+##### 1.5 — Errores comunes
 
 | 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. |
+| `"FreeSWITCH UUID not resolved yet"` | Llamaste `addParticipant` antes de que la llamada conecte | Espera `currentCall.state === 'established'` y `fsChannelUuid !== null` |
+| `"No active call"` | `currentCall` es null | Verifica que haya una llamada activa |
+| Timer se inicia antes de contestar | Iniciaste timer en state='dialing' | Solo iniciar timer cuando `state === 'active'` |
+| `addParticipant` lanza error 500 | El backend no pudo originar a Persona B | La llamada con A se reanuda automáticamente |
 
 ---
 
-#### 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.
+#### FLOW 2 — VoIPClient directo (sin hook)
 
 ```typescript
 import { VoIPClient } from '@cemscale-voip/voip-sdk';
 
-const voip = new VoIPClient({
-  apiUrl: 'https://voip-api.cemscale.com',
-  apiKey: 'csk_live_...',
+const voip = new VoIPClient({ apiUrl: '...', apiKey: '...' });
+
+// PASO 1: Agregar participante (conferencia se crea inmediatamente)
+const result = await voip.addCallParticipant(fsUuid, {
+  toNumber: '+17866302522',
 });
 
-// ═══════════════════════════════════════════════════════
-// PASO 1: Detectar 2+ llamadas activas de la misma extensión
-// ═══════════════════════════════════════════════════════
+// result = {
+//   conferenceName: "3way_<tenantId>_<hex>",
+//   state: "dialing",
+//   participants: [
+//     { uuid: "webrtc-uuid", callerIdNumber: "1001", status: "active", ... },
+//     { uuid: "personA-uuid", callerIdNumber: "+1786...", status: "held", muted: true, deaf: true },
+//   ],
+//   newCallUuid: "personB-uuid",
+//   heldMemberUuid: "personA-uuid",
+//   originalBridgedLeg: "personA-uuid",
+// }
 
-// Hacer polling cada 5 segundos
+// PASO 2: Detectar cuando B contesta (polling)
 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);
+  const { conference } = await voip.getConferenceMembers(result.conferenceName);
+  const activeCount = conference.members.filter(m => !m.muted || !m.deaf).length;
+  if (activeCount >= 2) {
+    clearInterval(pollInterval);
+    // B contestó — ahora puedes swap/merge
   }
-}
-
-// ═══════════════════════════════════════════════════════
-// LIMPIEZA
-// ═══════════════════════════════════════════════════════
+}, 2000);
 
-// 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;
-}
-```
+// PASO 3a: Swap (hablar con A, poner B en hold)
+await voip.swapCallParticipant({
+  conferenceName: result.conferenceName,
+  keepUuid: personA_uuid,   // persona con quien hablar
+  holdUuid: personB_uuid,   // persona que va a hold
+});
 
-##### 2.2 — IMPORTANTE: No confundir los UUIDs
+// PASO 3b: Merge (todos hablan)
+await voip.mergeThreeWay({
+  conferenceName: result.conferenceName,
+});
 
-```
-activeCall.uuid      → "a1b2c3d4-..."  ← USAR ESTE para mergeDirectCalls
-activeCall.call_uuid → "a1b2c3d4-..."  ← NO USAR (es el mismo que el de la otra pata)
+// PASO 3c: Cancel (B no contestó)
+await voip.cancelAddParticipant({
+  conferenceName: result.conferenceName,
+  newCallUuid: result.newCallUuid,
+  heldMemberUuid: result.heldMemberUuid,
+});
 
-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.
+// PASO 4: Kick (sacar a alguien)
+await voip.kickParticipant({
+  conferenceName: result.conferenceName,
+  memberUuid: personB_uuid,
+});
 ```
 
 ---
 
-#### 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
-});
+#### MÁQUINA DE ESTADOS de threeWaySession
 
-// result.conferenceName → "page_15d0851a_..."
-// result.participants → [{ callerIdNumber, callerIdName, uuid, status, memberId }, ...]
-// result.state → 'active'
+```
+null ──addParticipant()──> { state: 'dialing', pendingUuid: '...' }
+   │                                   │
+   │                          B contesta (polling automático)
+   │                                   │
+   │                                   ▼
+   │                          { state: 'holding', participants: [...] }
+   │                              │             │            │
+   │                     swapParticipant()  mergeThreeWay()  dropParticipant()
+   │                              │             │            │
+   │                              ▼             ▼            │
+   │                     { state: 'holding' }  { state: 'active' }
+   │                              │             │
+   │                     swapParticipant()      dropParticipant() (≤1 left)
+   │                              │             │
+   │                              ▼             ▼
+   │                     { state: 'holding' }   null
+   │
+   │──cancelAddParticipant()──> null (B killed, A unheld, 2-person conference)
+   │
+   │──currentCall === null──> null (cleanup automático)
 ```
 
 ---
 
-#### RESUMEN de estados y UUIDs
+#### Métodos de tres vías — Referencia completa
 
-| 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` |
+| Método | Parámetros | Qué hace |
+|--------|-----------|----------|
+| `addCallParticipant(fsUuid, { toNumber?, toExtension? })` | UUID de FS, destino | Transfiere ambas patas a conferencia, hold A, originate B |
+| `cancelAddParticipant({ conferenceName, newCallUuid, heldMemberUuid })` | Datos de addCallParticipant | Mata B, desmutea A, conferencia 2 personas |
+| `swapCallParticipant({ conferenceName, keepUuid, holdUuid })` | Conference, UUIDs | Mute+deaf+MOH holdUuid, unmute+undeaf keepUuid |
+| `mergeThreeWay({ conferenceName })` | Conference | Desmutea+undeaf TODOS los en hold |
+| `kickParticipant({ conferenceName, memberUuid })` | Conference, UUID | Saca participante de conferencia (cuelga) |
+| `getConferenceMembers(conferenceName)` | Conference | Polling: miembros actuales de la conferencia |
 
-| ❌ 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 |
+#### Deprecated methods
 
----
-
-#### 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)
-```
+| Método | Reemplazo |
+|--------|-----------|
+| `mergeCalls(params)` | `mergeThreeWay({ conferenceName })` |
+| `mergeDirectCalls(params)` | `addCallParticipant()` + `mergeThreeWay()` |
 
 ### Extensions