payfri-video-sdk 0.1.1 → 0.1.2

package/README.md

@@ -1,91 +1,112 @@
 # payfri-video-sdk
 
-SDK del **servicio de video de Payfri**. Integra videollamadas en tu producto en minutos: tu
-backend emite tokens contra la API del servicio y tu frontend se une a la llamada — sin implementar
-WebRTC ni montar infraestructura de medios propia. Tres entry points con una **separación estricta
-de seguridad**:
+SDK oficial del **servicio de video de Payfri**. Integra videollamadas en tu producto sin
+implementar WebRTC ni montar infraestructura de medios.
 
-| Entry | Dónde corre | Credencial que recibe | Para qué |
-| --- | --- | --- | --- |
-| `payfri-video-sdk/server` | Tu **backend** | **API key** del tenant (secreta) | Crear salas y emitir tokens |
-| `payfri-video-sdk/client` | **Navegador** | Solo un **token** de corta duración | Unirse a la llamada (web) |
-| `payfri-video-sdk/native` | **React Native** | Solo un **token** de corta duración | Unirse a la llamada (móvil) |
+## La idea en 30 segundos
 
-> La API key **jamás** debe llegar al navegador ni al dispositivo. Los tipos de `/client` y
-> `/native` hacen **imposible** pasarla (no compila), y además hay una verificación en runtime.
+Una videollamada son dos pasos, en dos lugares distintos:
 
-## Cómo funciona
+1. **Tu backend** pide un token de acceso al servicio (aquí vive tu **API key**, que es secreta).
+2. **Tu frontend** (web o móvil) se une a la llamada con ese token (expira; default 1 hora).
 
 ```
 Tu backend ──(API key)──▶ API de video ──▶ { token, livekitUrl }
-     │                                            │
-     └────────── pasa token + livekitUrl ─────────┘
-                          ▼
-   Navegador / app móvil se une a la llamada con el token
+     │
+     └──▶ tu frontend se une a la llamada con { token, livekitUrl }
 ```
 
-1. Tu backend usa la API key para pedir un **token de acceso** (`tokens.issue`).
-2. Le pasas `{ token, livekitUrl }` a tu frontend (respuesta de tu propio endpoint).
-3. El frontend se une a la sala con `/client` (web) o `/native` (React Native).
-
-Los tokens expiran (default **1 hora**, configurable de 60 s a 12 h), así que emite uno nuevo por
-participante y por sesión.
-
-## Qué necesitas antes de empezar
-
-Te lo entrega el equipo que administra el servicio de video:
-
-- **`baseUrl`** — URL de la API de video, p. ej. `https://api.video.tuempresa.com`
-- **`apiKey`** — API key de tu tenant (formato `{prefijo}_live_{aleatorio}`). Se muestra **una sola
-  vez** al crearla: guárdala en un gestor de secretos, nunca en el código.
-- **`embedBaseUrl`** (solo para `/native`) — URL de la página embebible, p. ej.
-  `https://embed.tuempresa.com`
-- **Alta de CORS** — pide que agreguen el dominio de tu frontend a los orígenes permitidos de la API.
-
-Requisitos técnicos: Node 18+ en el backend (usa `fetch` global; en runtimes sin él puedes inyectar
-uno propio). El paquete se distribuye en **ESM + CJS con tipos incluidos**.
-
-## Instalación
-
-```bash
-# Backend (emitir tokens) — sin dependencias extra
-npm install payfri-video-sdk
-
-# Navegador (unirse a la llamada) — livekit-client es peer dependency
-npm install payfri-video-sdk livekit-client
+El SDK trae un entry point para cada lugar:
 
-# React Native / Expo
-npm install payfri-video-sdk react-native-webview
-```
+| Entry | Dónde corre | Recibe | Para qué |
+| --- | --- | --- | --- |
+| `payfri-video-sdk/server` | Tu backend | API key (secreta) | Emitir tokens, administrar salas |
+| `payfri-video-sdk/client` | Navegador | Solo el token | Unirse a la llamada (web, tú pones la UI) |
+| `payfri-video-sdk/native` | React Native | Solo el token | Unirse a la llamada (móvil, UI lista) |
 
-Todas las peer dependencies son **opcionales**: instala solo lo que exige el entry que uses.
+Dos cosas que conviene saber desde ya:
 
-> `livekit-client` aparece porque el motor de medios del servicio es [LiveKit](https://livekit.io);
-> es un detalle interno de implementación — tú solo interactúas con la API del servicio y con este SDK.
+- **Regla de oro:** la API key jamás sale de tu servidor. `/client` y `/native` ni siquiera
+  compilan si intentas pasarles una (y lo verifican también en runtime).
+- **El SDK de backend es opcional.** `/server` es un wrapper de conveniencia sobre la API REST del
+  servicio. Si prefieres, llama a la API directo con cualquier HTTP client —
+  [ejemplo abajo](#sin-sdk-rest-directo).
 
----
+## Inicio rápido
 
-## Backend — `payfri-video-sdk/server`
+**1. En tu backend — emite el token:**
 
 ```ts
 import { createVideoClient } from "payfri-video-sdk/server";
 
 const video = createVideoClient({
   baseUrl: process.env.VIDEO_API_BASE_URL!, // https://api.video.tuempresa.com
-  apiKey: process.env.VIDEO_API_KEY!,       // secreta, SOLO en el servidor
+  apiKey: process.env.VIDEO_API_KEY!,       // secreta, SOLO aquí
 });
 
-// Emitir un token para un participante (crea la sala si no existe)
+// En tu endpoint (protegido con TU auth):
 const { token, livekitUrl } = await video.tokens.issue({
   roomName: "consulta-123",
-  identity: "doctor-45",
+  identity: "doctor-45",        // id único de TU usuario
   displayName: "Dra. López",
-  createIfMissing: true,
+  createIfMissing: true,        // crea la sala si no existe
 });
+// devuelve { token, livekitUrl } a tu frontend
+```
+
+**2a. En el navegador — únete:**
 
-// Devuelve { token, livekitUrl } a tu frontend. NUNCA la apiKey.
+```ts
+import { joinRoom } from "payfri-video-sdk/client";
+
+const handle = await joinRoom({
+  token,      // desde tu backend
+  livekitUrl, // desde tu backend
+  container: document.getElementById("call")!,
+});
+
+await handle.toggleMic();
+await handle.leave();
 ```
 
+**2b. O en React Native — únete:**
+
+```tsx
+import { VideoCall } from "payfri-video-sdk/native";
+
+<VideoCall token={token} livekitUrl={livekitUrl} embedBaseUrl="https://embed.tuempresa.com" style={{ flex: 1 }} />;
+```
+
+Eso es todo el flujo. Lo demás es referencia.
+
+## Qué necesitas
+
+Te lo entrega el equipo que administra el servicio:
+
+- **`baseUrl`** — URL de la API de video
+- **`apiKey`** — la key de tu tenant. Se muestra **una sola vez** al crearla: guárdala en un gestor
+  de secretos, nunca en el código
+- **`embedBaseUrl`** — URL de la página de llamada (solo si usas `/native`)
+
+Técnico: Node 18+ en el backend (o inyecta tu propio `fetch`). El paquete es ESM + CJS con tipos
+TypeScript incluidos.
+
+## Instalación
+
+```bash
+npm install payfri-video-sdk                  # backend: suficiente para /server
+npm install payfri-video-sdk livekit-client   # web: /client necesita livekit-client
+npm install payfri-video-sdk react-native-webview   # móvil: /native necesita el WebView
+```
+
+Las peer dependencies son opcionales: instala solo lo que exige el entry que uses. (`livekit-client`
+aparece porque el motor de medios del servicio es [LiveKit](https://livekit.io) — detalle interno;
+tú solo interactúas con este SDK.)
+
+---
+
+## Referencia: `/server` (backend)
+
 ### `createVideoClient(options)`
 
 | Opción | Tipo | Requerido | Descripción |
@@ -148,23 +169,39 @@ try {
 
 | `status` | Causa típica |
 | --- | --- |
+| 400 | Body inválido (revisa `message`) |
 | 401 | API key inválida o revocada |
 | 403 | Tenant suspendido |
 | 404 | Sala inexistente (usa `createIfMissing: true` si aplica) |
-| 400 | Body inválido (revisa `message`) |
+
+### Sin SDK: REST directo
+
+`/server` solo envuelve la API REST. El mismo token del inicio rápido, con `curl`:
+
+```bash
+curl -X POST "$VIDEO_API_BASE_URL/v1/tokens" \
+  -H "Authorization: Bearer $VIDEO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"roomName":"consulta-123","identity":"doctor-45","displayName":"Dra. López","createIfMissing":true}'
+# → { "token": "...", "livekitUrl": "wss://...", "roomName": "...", "identity": "...", "expiresAt": "..." }
+```
+
+Endpoints equivalentes: `POST /v1/tokens`, `POST /v1/rooms`, `GET /v1/rooms/:roomName`,
+`DELETE /v1/rooms/:roomName`. Los errores tienen la forma `{ error: { code, message } }`. La
+documentación completa (Swagger) vive en `<baseUrl>/docs`. Úsalo desde cualquier lenguaje —
+el SDK solo es obligatorio si quieres los tipos y el manejo de errores ya resueltos.
 
 ---
 
-## Navegador — `payfri-video-sdk/client`
+## Referencia: `/client` (navegador)
+
+`joinRoom` conecta a la sala y monta los `<video>` en tu contenedor. **La UI es tuya**: tú pones
+los botones y llamas a los métodos del handle.
 
 ```ts
 import { joinRoom } from "payfri-video-sdk/client";
 
-const handle = await joinRoom({
-  token,      // recibido desde TU backend
-  livekitUrl, // recibido desde TU backend
-  container: document.getElementById("call")!,
-});
+const handle = await joinRoom({ token, livekitUrl, container: document.getElementById("call")! });
 
 handle.on("participantJoined", (p) => console.log("entró", p.identity));
 handle.on("error", (e) => console.error(e));
@@ -178,8 +215,8 @@ await handle.leave();        // salir y liberar recursos
 
 | Opción | Tipo | Default | Descripción |
 | --- | --- | --- | --- |
-| `token` | `string` | requerido | Token de acceso emitido por tu backend |
-| `livekitUrl` | `string` | requerido | URL `wss` del servidor de medios (la devuelve `tokens.issue`; pásala tal cual) |
+| `token` | `string` | requerido | Token emitido por tu backend |
+| `livekitUrl` | `string` | requerido | URL `wss` del servidor de medios (viene con el token; pásala tal cual) |
 | `container` | `HTMLElement` | requerido | Elemento donde se montan los videos |
 | `enableCamera` | `boolean` | `true` | Publicar cámara al conectar |
 | `enableMicrophone` | `boolean` | `true` | Publicar micrófono al conectar |
@@ -198,30 +235,22 @@ await handle.leave();        // salir y liberar recursos
 
 Para casos avanzados, `handle.room` expone el `Room` de `livekit-client` subyacente.
 
-### Seguridad de tipos
-
-`joinRoom` **no tiene** campo para la API key. Esto no compila:
-
-```ts
-// @ts-expect-error — apiKey no existe en JoinRoomOptions
-joinRoom({ token, livekitUrl, container, apiKey: "..." });
-```
-
-Y en runtime, `joinRoom` lanza si detecta `apiKey`/`apiSecret`/`secret` en las opciones.
+> Seguridad: `joinRoom` no tiene campo para la API key — pasarla no compila, y en runtime lanza si
+> detecta `apiKey`/`apiSecret`/`secret` en las opciones.
 
 ---
 
-## React Native — `payfri-video-sdk/native`
+## Referencia: `/native` (React Native)
 
-Componente `<VideoCall>` que incrusta la videollamada en un `WebView` (carga la página embebible
-del servicio). **No requiere `react-native-webrtc`** ni código nativo propio.
+`<VideoCall>` incrusta la llamada **con UI lista** (la página del servicio dentro de un `WebView`).
+No requiere `react-native-webrtc` ni código nativo propio.
 
 ```tsx
 import { VideoCall } from "payfri-video-sdk/native";
 
 <VideoCall
-  token={token}           // recibido desde TU backend
-  livekitUrl={livekitUrl} // recibido desde TU backend
+  token={token}           // desde tu backend
+  livekitUrl={livekitUrl} // desde tu backend
   embedBaseUrl="https://embed.tuempresa.com"
   onConnected={() => console.log("conectado")}
   onLeave={() => navigation.goBack()}
@@ -234,9 +263,9 @@ import { VideoCall } from "payfri-video-sdk/native";
 
 | Prop | Tipo | Requerido | Descripción |
 | --- | --- | --- | --- |
-| `token` | `string` | ✅ | Token de acceso emitido por tu backend |
-| `livekitUrl` | `string` | ✅ | URL `wss` del servidor de medios (la devuelve `tokens.issue`; pásala tal cual) |
-| `embedBaseUrl` | `string` | ✅ | Base de la página embebible (**HTTPS obligatorio**) |
+| `token` | `string` | ✅ | Token emitido por tu backend |
+| `livekitUrl` | `string` | ✅ | URL `wss` del servidor de medios (viene con el token; pásala tal cual) |
+| `embedBaseUrl` | `string` | ✅ | Base de la página de llamada (**HTTPS obligatorio**) |
 | `theme` | `string` | — | Color de acento para branding (ej. `#4f7cff`) |
 | `onConnected` | `() => void` | — | La videollamada conectó |
 | `onDisconnected` | `() => void` | — | El usuario se desconectó o se cerró la sala |
@@ -246,7 +275,7 @@ import { VideoCall } from "payfri-video-sdk/native";
 | `onError` | `(error: Error) => void` | — | Permisos denegados, token inválido, fallo de sala |
 | `style` | `StyleProp<ViewStyle>` | — | Estilo del contenedor (default: ocupa todo) |
 
-Igual que `/client`, `VideoCallProps` **no tiene** campo para la API key (no compila si la pasas).
+Igual que `/client`, no existe campo para la API key (no compila si la pasas).
 
 ### Permisos de cámara y micrófono
 
@@ -262,12 +291,15 @@ Igual que `/client`, `VideoCallProps` **no tiene** campo para la API key (no com
 }
 ```
 
-El plugin inyecta en el prebuild `NSCameraUsageDescription` / `NSMicrophoneUsageDescription` (iOS)
-y `CAMERA` / `RECORD_AUDIO` / `MODIFY_AUDIO_SETTINGS` (Android).
+El plugin inyecta `NSCameraUsageDescription` / `NSMicrophoneUsageDescription` (iOS) y
+`CAMERA` / `RECORD_AUDIO` / `MODIFY_AUDIO_SETTINGS` (Android).
 
 **React Native "bare"** (sin Expo) — agrégalos a mano en `Info.plist` y `AndroidManifest.xml`.
-En Android, `MODIFY_AUDIO_SETTINGS` es obligatorio: el WebView lo exige junto a `RECORD_AUDIO`
-para capturar audio; sin él el micrófono falla con "Could not start audio source".
+En Android, `MODIFY_AUDIO_SETTINGS` es obligatorio: el WebView lo exige junto a `RECORD_AUDIO`;
+sin él el micrófono falla con "Could not start audio source".
+
+**Prueba en un dev build en teléfono real** (`npx expo run:android` / `run:ios`) — Expo Go no
+aplica config plugins, así que los permisos no existen ahí.
 
 > App de ejemplo completa (Expo):
 > [`examples/expo-videocall`](https://github.com/Payfri/VideoCallsGateway/tree/main/examples/expo-videocall)
@@ -279,10 +311,9 @@ para capturar audio; sin él el micrófono falla con "Could not start audio sour
 | Síntoma | Causa probable | Solución |
 | --- | --- | --- |
 | `401 UNAUTHORIZED` desde `/server` | API key mal copiada o revocada | Verifica la env var; pide una key nueva si fue revocada |
-| CORS bloquea la petición del navegador | Tu dominio no está en la lista de orígenes | Pide el alta de tu dominio al equipo de la plataforma |
 | "token inválido o expirado" al unirse | El token venció (default 1 h) | Emite un token nuevo por sesión; sube `ttlSeconds` si aplica |
 | Cámara/micrófono no arrancan (web) | Contexto no seguro | Sirve tu página por **HTTPS** (`getUserMedia` lo exige) |
-| Cámara/micrófono no arrancan (RN) | Permisos no declarados | Config plugin (Expo) o permisos manuales (bare) + rebuild |
+| Cámara/micrófono no arrancan (RN) | Permisos no declarados, o Expo Go | Config plugin + dev build (Expo) o permisos manuales (bare) |
 | `No hay fetch disponible` en `/server` | Node < 18 o runtime sin fetch | Usa Node 18+ o pasa `fetch` en las opciones |
 | Pantalla en blanco en `<VideoCall>` | `embedBaseUrl` en HTTP o mal apuntada | Debe ser HTTPS y responder la página `/room` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payfri-video-sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "SDK del microservicio de video: entry /server (apiKey, backend), /client (token, navegador) y /native (token, React Native)",
   "license": "MIT",
   "keywords": ["livekit", "video", "webrtc", "react-native", "expo", "sdk"],