@vinnyum/google-places-reviews

Un paquete modular y seguro para consultar de forma asíncrona la calificación (rating) y el número de reseñas (user_ratings_total) de un negocio a través de la API de Google Places.

Diseñado específicamente para integrarse de forma robusta con arquitecturas SSR (Server-Side Rendering) como Astro y Next.js sin bloquear el hilo principal ni agotar tu cuota de API.

🚀 Características

• TypeScript Nativo: Completamente tipado de forma estática con definiciones completas (.d.ts).
• Resiliente y Seguro: Manejo inteligente de errores integrado. Si la API de Google falla o tus llaves son inválidas, devuelve un fallback configurable en lugar de romper tu renderizado.
• Control de Tiempos de Espera (Timeout): Soporte para límite de tiempo configurable (por defecto 5 segundos) usando AbortController para que llamadas a APIs colgadas no demoren la carga de tu web.
• Cero Dependencias Externas: Diseñado en base a la API estándar nativa de fetch presente en Node 18+.

📦 Instalación

Instala el paquete en tu proyecto cliente:

npm install @vinnyum/google-places-reviews

🛠️ Uso Básico

import { getPlacesReviews } from '@vinnyum/google-places-reviews';

const apiKey = 'TU_GOOGLE_PLACES_API_KEY';
const placeId = 'TU_PLACE_ID';

const result = await getPlacesReviews(apiKey, placeId, {
  timeout: 4000, // Límite de 4 segundos
  fallback: {
    rating: 5.0,
    count: 10 // alias para user_ratings_total
  }
});

console.log(result.rating); // ej: 4.8
console.log(result.count);  // ej: 45
console.log(result.isFallback); // true o false

Opciones (GetPlacesReviewsOptions)

| Opción | Tipo | Defecto | Descripción | | --- | --- | --- | --- | | timeout | number | 5000 | Tiempo de espera límite en milisegundos antes de abortar la petición a Google. | | fallback | object | { rating: 5.0, count: 0 } | Valores devueltos en caso de error, timeout o credenciales incorrectas. |

Objeto Retornado (PlacesReviewsResult)

| Propiedad | Tipo | Descripción | | --- | --- | --- | | rating | number | Calificación promedio del negocio (de 1.0 a 5.0). | | user_ratings_total | number | Cantidad total de reseñas en Google. | | count | number | Alias conveniente para user_ratings_total. | | status | string | Estado devuelto por la API (ej: "OK", "FALLBACK", "TIMEOUT_ERROR"). | | isFallback | boolean | true si falló la API y se están mostrando los valores por defecto, de lo contrario false. |

🌟 Integración en Astro (SSR con Caché para Vercel)

Para no agotar las cuotas de Google Places, se recomienda renderizar bajo SSR y configurar cabeceras de caché CDN (s-maxage).

Crea un componente Astro (ej. src/components/GoogleReviews.astro):

---
import { getPlacesReviews } from '@vinnyum/google-places-reviews';

const GOOGLE_PLACES_API_KEY = import.meta.env.GOOGLE_PLACES_API_KEY;
const GOOGLE_PLACE_ID = import.meta.env.GOOGLE_PLACE_ID;

// Configurar cabeceras de caché CDN (Vercel Edge Network)
// - Cachea la página en la red de Vercel por 24 horas (86400s)
// - Sirve contenido antiguo en background mientras revalida por 1 hora (3600s)
Astro.response.headers.set(
  'Cache-Control',
  'public, max-age=0, s-maxage=86400, stale-while-revalidate=3600'
);

const reviews = await getPlacesReviews(GOOGLE_PLACES_API_KEY, GOOGLE_PLACE_ID, {
  timeout: 4000,
  fallback: {
    rating: 5.0,
    count: 20
  }
});
---

<div class="reviews-badge">
  <strong>Google Reviews</strong>
  <span>⭐ {reviews.rating.toFixed(1)} / 5 ({reviews.count} reseñas)</span>
  {reviews.isFallback && <small class="offline">(offline)</small>}
</div>

📝 Licencia

ISC