@globaling/client

Este módulo es un cliente HTTP diseñado para interactuar con el API de Globaling, permitiendo la autenticación y el acceso a todos los servicios que ofrece la plataforma Globaling de forma segura y eficiente.

Características

• Autenticación automática con apiKey.
• Acceso a todos los servicios de la plataforma Globaling.
• Soporte completo para el servicio Insightify v2 (análisis de texto e insights).
• Compatible con JavaScript y TypeScript.

Instalación

Instala el paquete usando npm:

npm install @globaling/client

O usando yarn:

yarn add @globaling/client

Configuración Inicial

Obtener tu API Key

Antes de usar la librería, necesitas obtener tu API key desde el portal de la plataforma Globaling:

1. Accede al portal de Globaling
2. Ve a la sección de configuración o API keys
3. Genera o copia tu API key personal
4. Guarda tu API key de forma segura

Importante: Mantén tu API key segura y no la compartas públicamente.

Uso

Para usar esta librería, importa y crea una instancia de GlobaLing con tu API key obtenida del portal.

JavaScript (CommonJS)

const GlobaLing = require('@globaling/client');

const client = await new GlobaLing({ apiKey: 'your-api-key' });

TypeScript/ES6

import GlobaLing from '@globaling/client';

const client = await new GlobaLing({ apiKey: 'your-api-key' });

Servicios Disponibles

La plataforma Globaling ofrece múltiples servicios especializados. Actualmente disponibles:

Insightify v2

Servicio de análisis de texto e insights que permite crear entrenamientos, categorías y analizar reseñas de texto para extraer información valiosa.

const client = await new GlobaLing({ apiKey: 'your-api-key' });

// Crear un entrenamiento
const training = await client.Insightify.createTraining({
  name: 'Mi Entrenamiento',
  businessType: 'restaurant',
  allowNewCategories: true
});

// Analizar una reseña
const analysis = await client.Insightify.analyzeReview(training.id, {
  text: 'La comida estaba deliciosa pero el servicio fue lento'
});

API Reference

Constructor

new GlobaLing(options: { apiKey: string })

Crea una nueva instancia del cliente para acceder a todos los servicios de Globaling. Retorna una Promise que resuelve con la instancia autenticada.

Parámetros:

• options.apiKey (string, requerido): Tu API key de Globaling obtenida desde el portal de la plataforma para autenticación y acceso a los servicios.

Servicio Insightify v2 - Análisis de Texto e Insights

createTraining(input)

Crea un nuevo entrenamiento para análisis de texto e insights.

Parámetros:

• input.name (string, requerido): Nombre del entrenamiento.
• input.description (string, opcional): Descripción detallada del entrenamiento.
• input.businessDescription (string, opcional): Descripción del negocio o contexto.
• input.businessType (string, requerido): Tipo de negocio (ej: 'restaurant', 'hotel', 'retail').
• input.allowNewCategories (boolean, requerido): Si permite crear nuevas categorías automáticamente.

Retorna: Objeto con los datos del entrenamiento creado.

updateTrainingById(trainingId, input)

Actualiza un entrenamiento existente.

Parámetros:

• trainingId (string, requerido): ID único del entrenamiento.
• input.name (string, opcional): Nuevo nombre del entrenamiento.
• input.description (string, opcional): Nueva descripción del entrenamiento.
• input.businessDescription (string, opcional): Nueva descripción del negocio.
• input.businessType (string, opcional): Nuevo tipo de negocio.
• input.allowNewCategories (boolean, opcional): Si permite crear nuevas categorías.

Retorna: Objeto con los datos del entrenamiento actualizado.

deleteTrainingById(trainingId)

Elimina un entrenamiento y todos sus datos asociados.

Parámetros:

• trainingId (string, requerido): ID único del entrenamiento a eliminar.

Retorna: Confirmación de eliminación.

createCategory(trainingId, input)

Crea una nueva categoría dentro de un entrenamiento.

Parámetros:

• trainingId (string, requerido): ID del entrenamiento donde crear la categoría.
• input.name (string, requerido): Nombre de la categoría.
• input.description (string, opcional): Descripción de la categoría.
• input.tags (string[], opcional): Array de etiquetas asociadas.
• input.color (string, opcional): Color hexadecimal para la categoría (ej: '#FF5733').

Retorna: Objeto con los datos de la categoría creada.

updateCategoryById(trainingId, categoryId, input)

Actualiza una categoría existente.

Parámetros:

• trainingId (string, requerido): ID del entrenamiento.
• categoryId (string, requerido): ID de la categoría a actualizar.
• input.name (string, opcional): Nuevo nombre de la categoría.
• input.description (string, opcional): Nueva descripción.
• input.tags (string[], opcional): Nuevas etiquetas.
• input.color (string, opcional): Nuevo color hexadecimal.

Retorna: Objeto con los datos de la categoría actualizada.

getCategoryById(trainingId, categoryId)

Obtiene los datos de una categoría específica.

Parámetros:

• trainingId (string, requerido): ID del entrenamiento.
• categoryId (string, requerido): ID de la categoría.

Retorna: Objeto con todos los datos de la categoría.

deleteCategoryById(trainingId, categoryId)

Elimina una categoría del entrenamiento.

Parámetros:

• trainingId (string, requerido): ID del entrenamiento.
• categoryId (string, requerido): ID de la categoría a eliminar.

Retorna: Confirmación de eliminación.

analyzeReview(trainingId, input)

Analiza una reseña de texto o archivo para extraer insights y categorizar fragmentos.

Parámetros:

• trainingId (string, requerido): ID del entrenamiento a usar para el análisis.
• input.text (string, opcional): Texto de la reseña a analizar.
• input.file (File | Blob, opcional): Archivo con el contenido a analizar.

Nota: Debe proporcionar text o file, no ambos.

Retorna: Objeto con el análisis completo, fragmentos categorizados y scores.

resetReviewById(trainingId, reviewId)

Reinicia el análisis de una reseña, eliminando todas las categorizaciones manuales.

Parámetros:

• trainingId (string, requerido): ID del entrenamiento.
• reviewId (string, requerido): ID de la reseña a reiniciar.

Retorna: Confirmación del reinicio.

voteFragmentById(trainingId, reviewId, fragmentId, input)

Vota positiva o negativamente un fragmento de texto para mejorar el entrenamiento.

Parámetros:

• trainingId (string, requerido): ID del entrenamiento.
• reviewId (string, requerido): ID de la reseña.
• fragmentId (string, requerido): ID del fragmento a votar.
• input.uniqueIdentifier (string, requerido): Identificador único del votante.
• input.isPositive (boolean, requerido): true para voto positivo, false para negativo.

Retorna: Confirmación del voto registrado.

updateReviewById(trainingId, reviewId, input)

Actualiza manualmente los fragmentos y categorizaciones de una reseña.

Parámetros:

• trainingId (string, requerido): ID del entrenamiento.
• reviewId (string, requerido): ID de la reseña.
• input.fragments (array, requerido): Array de fragmentos a actualizar.
  • fragmentId (string, opcional): ID del fragmento existente.
  • categoryId (string, opcional): ID de la categoría asignada.
  • categoryName (string, requerido): Nombre de la categoría.
  • startIndex (number, requerido): Índice de inicio del fragmento en el texto.
  • endIndex (number, requerido): Índice de fin del fragmento.
  • reason (string, requerido): Razón de la categorización.
  • score (number, requerido): Puntuación del fragmento (-1 a 1).
  • delete (boolean, requerido): Si el fragmento debe ser eliminado.

Retorna: Objeto con la reseña actualizada.

Configuración de Entornos

La librería detecta automáticamente el entorno basado en NODE_ENV:

• production: https://io-api.globaling.ai
• test: https://io-api.globaling.techbuzzo.io
• develop: http://localhost:3100

Manejo de Errores

Todos los métodos pueden lanzar errores con la siguiente estructura:

try {
  const result = await client.Insightify.createTraining(data);
} catch (error) {
  console.error('Error:', error.message);
  console.error('Status:', error.code || error.statusCode);
}

// Ejemplo con otros servicios (cuando estén disponibles)
// const otherResult = await client.OtherService.someMethod(data);

Códigos de error comunes:

• 401: API key inválida o expirada
• 404: Recurso no encontrado
• 422: Datos de entrada inválidos
• 503: Servicio temporalmente no disponible

Contribuciones

Las contribuciones son siempre bienvenidas. Si deseas contribuir a este proyecto, por favor, crea un fork del repositorio y envía un pull request.

Licencia

Este proyecto está licenciado bajo la Licencia ISC. Consulta el archivo LICENSE en este repositorio para más información.