npm package: @smkdev/geolocation
Description: Biblioteca Node.js completa para geolocalização com mapas interativos e WebSockets em tempo real
Author: smkdev
Latest version: 1.0.1

# @smkdev/geolocation 🌍

[![npm version](https://badge.fury.io/js/%40smkdev%2Fgeolocation.svg)](https://www.npmjs.com/package/@smkdev/geolocation)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/npm/dm/@smkdev/geolocation.svg)](https://www.npmjs.com/package/@smkdev/geolocation)

Biblioteca Node.js completa para geolocalização com mapas interativos, WebSockets em tempo real e funcionalidades de geocodificação. **Perfeita para integração entre apps React Native (Expo) e frontends Next.js**.

## 🚀 Instalação

```bash
npm install @smkdev/geolocation
```

## ⚡ Início Rápido

### Servidor Completo

```javascript
import { GeoLocationLib } from '@smkdev/geolocation';

const geoLib = new GeoLocationLib({
    port: 3001,
    cors: {
        origin: ["http://localhost:3000", "exp://192.168.1.100:19000"] // Next.js + Expo
    }
});

await geoLib.start();
console.log('🌍 Servidor de geolocalização rodando!');
```

### Usando Apenas os Serviços

```javascript
import { createServices } from '@smkdev/geolocation';

const services = createServices();

// Calcular distância entre dois pontos
const distance = services.geolocation.calculateDistance(
    { lat: -23.5505, lng: -46.6333 },  // São Paulo
    { lat: -22.9068, lng: -43.1729 }   // Rio de Janeiro
);
console.log(`Distância: ${Math.round(distance/1000)}km`);

// Geocodificação
const locations = await services.geocoding.geocode('São Paulo, Brasil');
console.log('Coordenadas:', locations[0]);
```

## 📱 Integração React Native + Next.js

### React Native (Cliente)

```javascript
import { io } from 'socket.io-client';
import * as Location from 'expo-location';

const useRealTimeTracking = (serverUrl) => {
    const [socket, setSocket] = useState(null);

    useEffect(() => {
        const newSocket = io(serverUrl);
        setSocket(newSocket);

        const startTracking = async () => {
            const { status } = await Location.requestForegroundPermissionsAsync();
            if (status === 'granted') {
                await Location.watchPositionAsync({
                    accuracy: Location.Accuracy.High,
                    timeInterval: 5000, // 5 segundos
                    distanceInterval: 10 // 10 metros
                }, (location) => {
                    newSocket.emit('location_update', {
                        userId: 'user123',
                        latitude: location.coords.latitude,
                        longitude: location.coords.longitude,
                        timestamp: Date.now()
                    });
                });
            }
        };

        startTracking();
        return () => newSocket.close();
    }, [serverUrl]);

    return socket;
};
```

### Next.js Frontend (Visualização)

```javascript
import { useEffect, useState } from 'react';
import { io } from 'socket.io-client';

export default function TrackingPage() {
    const [users, setUsers] = useState(new Map());

    useEffect(() => {
        const socket = io('http://seu-backend.com:3001');

        socket.on('location_update', (data) => {
            setUsers(prev => {
                const updated = new Map(prev);
                updated.set(data.userId, {
                    ...data,
                    lastUpdate: new Date()
                });
                return updated;
            });
        });

        socket.on('user_disconnected', (data) => {
            setUsers(prev => {
                const updated = new Map(prev);
                updated.delete(data.userId);
                return updated;
            });
        });

        return () => socket.close();
    }, []);

    return (
        <div>
            <h1>📍 Rastreamento em Tempo Real</h1>
            {Array.from(users.values()).map(user => (
                <div key={user.userId} style={{ 
                    padding: '10px', 
                    border: '1px solid #ccc', 
                    margin: '5px',
                    borderRadius: '5px'
                }}>
                    <strong>👤 {user.userId}</strong><br/>
                    📍 Lat: {user.latitude.toFixed(6)}<br/>
                    📍 Lng: {user.longitude.toFixed(6)}<br/>
                    🕐 {user.lastUpdate.toLocaleTimeString()}
                </div>
            ))}
        </div>
    );
}
```

## 🌐 APIs Disponíveis

### WebSocket Events

```javascript
// Enviar (cliente → servidor)
socket.emit('location_update', locationData);
socket.emit('location_share', { userId, latitude, longitude, message });
socket.emit('join_room', { userId, roomId });

// Receber (servidor → cliente)
socket.on('location_update', handleLocationUpdate);
socket.on('user_connected', handleUserConnected);
socket.on('geofence_alert', handleGeofenceAlert);
```

### REST Endpoints

```javascript
// Geocodificação
GET /api/geocoding/forward?q=São Paulo, Brasil
GET /api/geocoding/reverse?lat=-23.5505&lng=-46.6333

// Cálculos de distância
POST /api/geolocation/distance
{
    "from": {"lat": -23.5505, "lng": -46.6333},
    "to": {"lat": -23.5506, "lng": -46.6334}
}
```

## 🎯 Funcionalidades

- ✅ **WebSocket em tempo real** com Socket.IO
- ✅ **Mapas interativos** com Leaflet.js  
- ✅ **Geocodificação** com rate limiting inteligente
- ✅ **Cálculos geográficos** (distância, bearing, geofencing)
- ✅ **Interface web** pronta para demonstrações
- ✅ **Segurança** e monitoramento integrados
- ✅ **Compatível** com React Native, Next.js, Vue, Angular
- ✅ **Pronto para produção** com logs e métricas

## 🔧 Configuração Avançada

```javascript
import { GeoLocationLib } from '@smkdev/geolocation';

const geoLib = new GeoLocationLib({
    port: 3001,
    cors: {
        origin: process.env.ALLOWED_ORIGINS?.split(',') || ["*"]
    },
    security: {
        rateLimit: {
            windowMs: 15 * 60 * 1000, // 15 minutos
            max: 100 // máximo 100 requests por IP
        }
    },
    geocoding: {
        providers: ['openstreetmap', 'nominatim'],
        cacheTimeout: 60 * 60 * 1000, // 1 hora
        maxRequestsPerMinute: 60
    }
});
```

## 📖 Documentação Completa

Para documentação completa, exemplos avançados e guias de implementação, visite:
- **GitHub:** [Repositório do projeto](https://github.com/smkdev/geolocation)
- **NPM:** [Página oficial do pacote](https://www.npmjs.com/package/@smkdev/geolocation)

## 📄 Licença

MIT © smkdev

---

**🌍 Construa aplicações de geolocalização em tempo real de forma simples e rápida!**