Inicio rápido — Node.js

Integra Rayuela en tu aplicación Node.js y obtén tu primera recomendación en menos de 5 minutos.

Requisitos previos

Node.js 14 o superior
npm o yarn
Una cuenta en Rayuela (regístrate en rayuela.ai)
Tu API Key (disponible en el dashboard después del registro)

Paso 1: Instalación

El SDK de Node.js todavía no está publicado en npm. Mientras tanto, integrá la API directamente vía HTTP (ver quickstart cURL).

# SDK de Node.js — próximamente en npm (aún sin publicar)
# Alternativa disponible hoy: llamadas HTTP directas a la API
# Ver /docs/quickstart/curl

Los ejemplos de esta página usan fetch nativo (Node.js 18+); el SDK de Node.js se publicará próximamente en npm.

Paso 2: Configuración inicial

Crea un cliente Node.js para interactuar con la API de Rayuela.

// Node.js 18+ (fetch nativo). El SDK de Node.js aún no está publicado.
const RAYUELA_BASE = process.env.RAYUELA_API_URL || 'https://api.rayuela.ai/api/v1';

async function rayuela(path, body) {
  const res = await fetch(`${RAYUELA_BASE}${path}`, {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.RAYUELA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  });
  if (!res.ok) throw new Error(`Rayuela API error: ${res.status}`);
  return res.json();
}

Paso 3: Verificar conexión

Prueba que tu API Key funciona correctamente.

// Probar conexión contra el health check autenticado
async function main() {
  try {
    const res = await fetch(`${RAYUELA_BASE}/health/auth`, {
      headers: { 'X-API-Key': process.env.RAYUELA_API_KEY }
    });

    if (res.ok) {
      console.log('OK: conexión exitosa');
    } else {
      console.log('Error: verifica tu API Key.');
    }
  } catch (error) {
    console.log('Error de conexión:', error.message);
  }
}

main();

Paso 4: Obtener recomendaciones

Solicita recomendaciones personalizadas para un usuario.

// Obtener recomendaciones personalizadas
async function getRecommendations(userId, options = {}) {
  try {
    const response = await rayuela('/recommendations/personalized/query', {
      external_user_id: userId,
      limit: options.limit || 5,
      strategy: options.strategy || 'hybrid',
      recommendation_goal: 'user_engagement',
      include_explanation: false,
      filters: options.filters || {
        logic: 'and',
        filters: []
      }
    });
    return response;
  } catch (error) {
    console.error('Error obteniendo recomendaciones:', error.message);
    throw error;
  }
}
// Ejemplo de uso
const recommendations = await getRecommendations('user_123', {
  limit: 5,
  filters: {
    logic: 'and',
    filters: [{ field: 'category', op: 'eq', value: 'electronics' }]
  }
});
console.log('Recomendaciones:', recommendations.items);

Listo — siguientes pasos

Ya tenés una integración HTTP básica para Node.js. Ahora podés: