@encarnage7/local-meet 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Local Meet Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,404 @@
-# Temporary Holding Version
+# Local Meet SDK (`local-meet`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Zero-trust, resilient WebRTC client library with P2P Mesh & Cloudflare Calls SFU, E2EE data channels, and HTTPS signaling fallback. Works everywhere like Axios.
+
+[![npm version](https://img.shields.io/npm/v/local-meet.svg)](https://www.npmjs.com/package/local-meet)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Características
+
+- **Cero Dependencias en Runtime**: Ligera, rápida y empaquetada en ESM, CommonJS y Browser UMD.
+- **Doble Arquitectura**: Funciona en modo **WebRTC P2P Mesh Ilimitado** (gratis, sin servidores de medios) y **Cloudflare Calls SFU** (1,000 GB/mes gratis).
+- **Señalización Ultrarresistente por HTTPS**: Supera firewalls restrictivos, NAT simétrico y redes móviles 4G/5G gracias a su bus de respaldo HTTPS `/api/room-sync`.
+- **Cifrado de Extremo a Extremo (E2EE)**: Mensajería de datos, chat y reacciones cifradas con AES-GCM-256 mediante Web Crypto API.
+- **Pantalla Compartida Nativa**: Conexión directa y fluida sin pantallas negras.
+- **Sala de Espera y Controles de Anfitrión**: Admitir, rechazar, silenciar micrófonos, expulsar y finalizar salas para todos.
+- **Soporte TypeScript Completo**: Definiciones de tipos `.d.ts` incluidas.
+
+---
+
+## Instalación
+
+### Vía NPM (React, Next.js, Vue, Angular, Svelte, Vite)
+```bash
+npm install @encarnage7/local-meet
+```
+
+### Vía CDN (HTML directo sin bundler, igual que Axios)
+```html
+<script src="https://cdn.jsdelivr.net/npm/@encarnage7/local-meet@1.0.0/dist/local-meet.min.js"></script>
+```
+*(O a través de unpkg)*:
+```html
+<script src="https://unpkg.com/@encarnage7/local-meet@1.0.0/dist/local-meet.min.js"></script>
+```
+
+---
+
+## Inicio Rápido
+
+### 1. Unirse como Invitado (3 líneas)
+
+```javascript
+import { LocalMeet, RoomEvents } from "@encarnage7/local-meet";
+
+// 1. Conectar a la sala
+const room = await LocalMeet.join({
+  serverUrl: "https://tu-worker.workers.dev",
+  roomHash: "c4f2-9k81-m3n2",
+  guestName: "Carlos"
+});
+
+// 2. Escuchar video de los participantes remotos
+room.on(RoomEvents.TrackSubscribed, (track, publication, participant) => {
+  const mediaEl = track.attach();
+  document.getElementById("video-grid").appendChild(mediaEl);
+});
+
+// 3. Conectar y activar cámara + micrófono
+await room.connect();
+await room.enableCameraAndMicrophone();
+```
+
+---
+
+### 2. Crear una Sala como Anfitrión
+
+```javascript
+import { LocalMeet, RoomEvents, EngineModes } from "@encarnage7/local-meet";
+
+const room = await LocalMeet.createRoom({
+  serverUrl: "https://tu-worker.workers.dev",
+  hostName: "María (Anfitriona)",
+  title: "Reunión de Equipo",
+  engine: EngineModes.CloudflareCalls, // o EngineModes.P2PMesh
+});
+
+console.log("Comparte este hash con tus invitados:", room.roomHash);
+
+// Escuchar cuando un invitado llega a la sala de espera
+room.on(RoomEvents.ParticipantConnected, (participant) => {
+  console.log(`${participant.name} está en la sala de espera.`);
+  // Para admitirlo:
+  room.admitGuest(participant.identity);
+});
+
+await room.connect();
+await room.enableCameraAndMicrophone();
+```
+
+---
+
+### 3. Ejemplo con Vue 3 (Composition API / `<script setup>`)
+
+```vue
+<script setup>
+import { ref, onMounted, onUnmounted } from "vue";
+import { LocalMeet, RoomEvents } from "@encarnage7/local-meet";
+
+const props = defineProps({
+  roomHash: { type: String, required: true },
+  userName: { type: String, default: "Invitado" },
+  serverUrl: { type: String, default: "https://tu-worker.workers.dev" }
+});
+
+const videoContainer = ref(null);
+let room = null;
+
+onMounted(async () => {
+  room = await LocalMeet.join({
+    serverUrl: props.serverUrl,
+    roomHash: props.roomHash,
+    guestName: props.userName,
+  });
+
+  room.on(RoomEvents.TrackSubscribed, (track) => {
+    const el = track.attach();
+    videoContainer.value?.appendChild(el);
+  });
+
+  room.on(RoomEvents.TrackUnsubscribed, (track) => {
+    track.detach().forEach((el) => el.remove());
+  });
+
+  await room.connect();
+  await room.enableCameraAndMicrophone();
+});
+
+onUnmounted(() => {
+  room?.disconnect();
+});
+
+const toggleMic = () => room?.setMicrophoneEnabled(false);
+const toggleScreen = () => room?.startScreenShare();
+const leave = () => room?.disconnect();
+</script>
+
+<template>
+  <div class="meeting-room">
+    <div ref="videoContainer" class="video-grid"></div>
+    <div class="controls">
+      <button @click="toggleMic">Silenciar Micrófono</button>
+      <button @click="toggleScreen">Compartir Pantalla</button>
+      <button @click="leave">Salir de la Reunión</button>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.video-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 12px;
+}
+.controls {
+  margin-top: 16px;
+  display: flex;
+  gap: 8px;
+}
+</style>
+```
+
+---
+
+### 4. Ejemplo con Angular (Standalone Component / TypeScript)
+
+```typescript
+import { Component, ElementRef, Input, OnDestroy, OnInit, ViewChild } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { LocalMeet, LocalMeetRoom, RoomEvents } from '@encarnage7/local-meet';
+
+@Component({
+  selector: 'app-video-meeting',
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <div class="meeting-room">
+      <div #videoContainer class="video-grid"></div>
+      <div class="controls">
+        <button (click)="toggleScreen()">Compartir Pantalla</button>
+        <button (click)="toggleMic()">Silenciar</button>
+        <button (click)="leave()">Salir</button>
+      </div>
+    </div>
+  `,
+  styles: [`
+    .video-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+      gap: 12px;
+    }
+    .controls {
+      margin-top: 16px;
+      display: flex;
+      gap: 8px;
+    }
+  `]
+})
+export class VideoMeetingComponent implements OnInit, OnDestroy {
+  @Input() roomHash!: string;
+  @Input() userName: string = 'Invitado';
+  @Input() serverUrl: string = 'https://tu-worker.workers.dev';
+
+  @ViewChild('videoContainer', { static: true }) videoContainer!: ElementRef<HTMLDivElement>;
+
+  private room?: LocalMeetRoom;
+
+  async ngOnInit() {
+    this.room = await LocalMeet.join({
+      serverUrl: this.serverUrl,
+      roomHash: this.roomHash,
+      guestName: this.userName,
+    });
+
+    this.room.on(RoomEvents.TrackSubscribed, (track) => {
+      const el = track.attach();
+      this.videoContainer.nativeElement.appendChild(el);
+    });
+
+    this.room.on(RoomEvents.TrackUnsubscribed, (track) => {
+      track.detach().forEach((el) => el.remove());
+    });
+
+    await this.room.connect();
+    await this.room.enableCameraAndMicrophone();
+  }
+
+  ngOnDestroy() {
+    this.room?.disconnect();
+  }
+
+  toggleMic() {
+    this.room?.setMicrophoneEnabled(false);
+  }
+
+  toggleScreen() {
+    this.room?.startScreenShare();
+  }
+
+  leave() {
+    this.room?.disconnect();
+  }
+}
+```
+
+---
+
+### 5. Ejemplo con React / Next.js
+
+```jsx
+import React, { useEffect, useRef, useState } from "react";
+import { LocalMeet, RoomEvents } from "@encarnage7/local-meet";
+
+export function VideoMeeting({ roomHash, userName }) {
+  const [room, setRoom] = useState(null);
+  const containerRef = useRef(null);
+
+  useEffect(() => {
+    let currentRoom = null;
+
+    async function init() {
+      currentRoom = await LocalMeet.join({
+        serverUrl: "https://tu-worker.workers.dev",
+        roomHash,
+        guestName: userName,
+      });
+
+      currentRoom.on(RoomEvents.TrackSubscribed, (track) => {
+        const el = track.attach();
+        containerRef.current?.appendChild(el);
+      });
+
+      currentRoom.on(RoomEvents.TrackUnsubscribed, (track) => {
+        track.detach().forEach((el) => el.remove());
+      });
+
+      await currentRoom.connect();
+      await currentRoom.enableCameraAndMicrophone();
+      setRoom(currentRoom);
+    }
+
+    init();
+
+    return () => {
+      currentRoom?.disconnect();
+    };
+  }, [roomHash, userName]);
+
+  return (
+    <div>
+      <div ref={containerRef} className="video-grid" />
+      <button onClick={() => room?.setMicrophoneEnabled(false)}>Silenciar</button>
+      <button onClick={() => room?.startScreenShare()}>Compartir Pantalla</button>
+      <button onClick={() => room?.disconnect()}>Salir</button>
+    </div>
+  );
+}
+```
+
+---
+
+### 4. Ejemplo en HTML puro (Vanilla JS con CDN)
+
+```html
+<!DOCTYPE html>
+<html lang="es">
+<head>
+  <meta charset="UTF-8" />
+  <title>Mi Videollamada</title>
+  <script src="https://cdn.jsdelivr.net/npm/local-meet@1.0.0/dist/local-meet.min.js"></script>
+</head>
+<body>
+  <div id="videos" style="display: flex; gap: 10px;"></div>
+  <button id="btn-share">Compartir Pantalla</button>
+
+  <script>
+    async function start() {
+      const room = await LocalMeet.join({
+        serverUrl: "https://tu-worker.workers.dev",
+        roomHash: "c4f2-9k81-m3n2",
+        guestName: "Invitado Web",
+      });
+
+      room.on(LocalMeet.RoomEvents.TrackSubscribed, (track) => {
+        document.getElementById("videos").appendChild(track.attach());
+      });
+
+      await room.connect();
+      await room.enableCameraAndMicrophone();
+
+      document.getElementById("btn-share").onclick = () => {
+        room.startScreenShare();
+      };
+    }
+
+    start();
+  </script>
+</body>
+</html>
+```
+
+---
+
+## Referencia de API
+
+### `LocalMeet`
+- `LocalMeet.createRoom(options)`: Petición a `/api/host-join` y retorno de instancia `LocalMeetRoom`.
+- `LocalMeet.join(options)`: Petición a `/api/guest-join` y retorno de instancia `LocalMeetRoom`.
+- `LocalMeet.RoomEvents`: Constantes de eventos.
+- `LocalMeet.TrackSources`: `Camera`, `Microphone`, `ScreenShare`.
+- `LocalMeet.EngineModes`: `CloudflareCalls`, `P2PMesh`, `LiveKit`.
+
+### `LocalMeetRoom`
+#### Métodos de Medios
+- `await room.connect()`: Inicia señalización y conexión WebRTC.
+- `await room.enableCameraAndMicrophone()`: Solicita permisos y publica audio y video.
+- `await room.setCameraEnabled(boolean)`: Enciende o apaga la cámara.
+- `await room.setMicrophoneEnabled(boolean)`: Enciende o silencia el micrófono.
+- `await room.startScreenShare()`: Inicia compartir pantalla con selección nativa del navegador.
+- `await room.stopScreenShare()`: Detiene la pantalla compartida.
+- `room.disconnect()`: Finaliza y destruye todos los tracks y conexiones locales.
+
+#### Métodos de Datos y Chat (E2EE)
+- `await room.sendData(payload, { reliable: true })`: Envía texto, objetos o `Uint8Array` cifrados de extremo a extremo a todos los participantes.
+
+#### Controles de Anfitrión (Solo Anfitriones)
+- `await room.admitGuest(identity)`: Admite a un invitado de la sala de espera.
+- `await room.rejectGuest(identity)`: Rechaza a un invitado.
+- `await room.muteParticipant(identity, trackSid)`: Silencia el micrófono de un participante.
+- `await room.kickParticipant(identity)`: Expulsa a un participante.
+- `await room.endRoom()`: Cierra la reunión para todos los asistentes.
+
+---
+
+## ¿Cómo Publicar esta Librería en NPM?
+
+Si deseas publicar tu paquete bajo tu cuenta de npm (ej: `mi-libreria` o `@mi-usuario/local-meet`):
+
+1. **Editar el nombre en `packages/sdk/package.json`:**
+   ```json
+   {
+     "name": "tu-nombre-o-organizacion/local-meet"
+   }
+   ```
+2. **Iniciar sesión en NPM desde tu terminal:**
+   ```bash
+   npm login
+   ```
+3. **Publicar el SDK:**
+   ```bash
+   cd packages/sdk
+   npm publish --access public
+   ```
+4. **¡Listo!** En minutos estará disponible en:
+   - `npm install tu-libreria`
+   - `https://cdn.jsdelivr.net/npm/tu-libreria/dist/local-meet.min.js`
+   - `https://unpkg.com/tu-libreria/dist/local-meet.min.js`
+
+---
+
+## Licencia
+
+MIT © Local Meet Contributors