@utilia-os/sdk-js

SDK JavaScript/TypeScript para integrar aplicaciones externas con UTILIA OS.

Instalación

npm install @utilia-os/sdk-js

Configuración

import { UtiliaSDK } from '@utilia-os/sdk-js';

const sdk = new UtiliaSDK({
  baseURL: 'https://os.utilia.ai/api',
  apiKey: 'tu-api-key',
  timeout: 30000,  // opcional, default: 30000ms
  debug: false,    // opcional, habilita logs de debug
});

Uso

Identificar Usuario

Antes de crear tickets, identifica al usuario en tu sistema:

const user = await sdk.users.identify({
  externalId: 'user-123',           // ID único en tu sistema (requerido)
  email: '[email protected]',        // opcional
  name: 'Juan Perez',               // opcional
  avatarUrl: 'https://...',         // opcional
  metadata: {                       // opcional, datos adicionales
    plan: 'premium',
    company: 'Acme Inc',
  },
});

Crear Ticket

const ticket = await sdk.tickets.create({
  user: {
    externalId: 'user-123',
    email: '[email protected]',
    name: 'Juan Perez',
  },
  title: 'Problema con la facturación',
  description: 'No puedo ver mis facturas del mes pasado...',
  category: 'PROBLEMA',  // CONSULTA | PROBLEMA | SUGERENCIA | OTRO
  priority: 'MEDIA',     // BAJA | MEDIA | ALTA | CRÍTICA
  context: {             // opcional
    url: window.location.href,
    appVersion: '1.2.3',
    browserInfo: navigator.userAgent,
  },
});

console.log(ticket.ticketKey);  // APP-0001
console.log(ticket.id);         // uuid del ticket

Listar Tickets

const result = await sdk.tickets.list('user-123', {
  status: 'OPEN',  // OPEN | IN_REVIEW | RESOLVED | CLOSED
  page: 1,
  limit: 20,
});

console.log(result.data);              // Array de tickets
console.log(result.pagination.total);  // Total de tickets

Obtener Detalle de Ticket

const ticket = await sdk.tickets.get('ticket-uuid', 'user-123');

console.log(ticket.title);
console.log(ticket.messages);  // Array de mensajes

Agregar Mensaje

const message = await sdk.tickets.addMessage('ticket-uuid', 'user-123', {
  content: 'Gracias por la respuesta, el problema ya fue resuelto.',
});

Cerrar/Reabrir Ticket

// Cerrar
await sdk.tickets.close('ticket-uuid', 'user-123');

// Reabrir
await sdk.tickets.reopen('ticket-uuid', 'user-123');

Obtener Mensajes No Leídos

const { count } = await sdk.tickets.getUnreadCount('user-123');
if (count > 0) {
  console.log(`Tienes ${count} mensajes sin leer`);
}

Reportar Error

const result = await sdk.errors.report({
  message: 'Error al procesar pago',
  module: 'payment-processor',
  severity: 'critical',
  stack: error.stack,
  endpoint: '/api/payments',
  method: 'POST',
  context: {
    gatewayId: 'stripe',
    orderId: 'order-456',
  },
});

console.log(result.hash);          // Hash único del error
console.log(result.deduplicated);   // true si el error ya existía

Listar Errores

const result = await sdk.errors.list({
  severity: ['critical', 'high'],
  resolved: false,
  limit: 20,
});

console.log(result.errors);
console.log(result.pagination.total);

Estadísticas de Errores

const stats = await sdk.errors.stats();

console.log(stats.total);        // Total de errores
console.log(stats.unresolved);   // Errores sin resolver
console.log(stats.bySeverity);   // { critical: 5, high: 10, ... }
console.log(stats.byModule);     // { auth: 3, payments: 7, ... }

Manejo de Errores

import { UtiliaSDK, UtiliaSDKError, ErrorCode } from '@utilia-os/sdk-js';

try {
  await sdk.tickets.create({ ... });
} catch (error) {
  if (error instanceof UtiliaSDKError) {
    switch (error.code) {
      case ErrorCode.UNAUTHORIZED:
        console.error('API Key inválida');
        break;
      case ErrorCode.RATE_LIMITED:
        console.error('Demasiadas peticiones, espera antes de reintentar');
        break;
      case ErrorCode.VALIDATION_ERROR:
        console.error('Datos inválidos:', error.message);
        break;
      case ErrorCode.NOT_FOUND:
        console.error('Recurso no encontrado');
        break;
      default:
        console.error('Error:', error.message);
    }

    // Verificar si se puede reintentar
    if (error.isRetryable()) {
      // Implementar lógica de reintento
    }
  }
}

Tipos

El SDK exporta todos los tipos TypeScript necesarios:

import type {
  // Configuración
  UtiliaSDKConfig,

  // Tickets
  CreateTicketInput,
  TicketFilters,
  AddMessageInput,
  CreatedTicket,
  TicketListItem,
  TicketDetail,
  TicketMessage,

  // Usuarios
  IdentifyUserInput,
  ExternalUser,

  // Errores del sistema
  ReportErrorInput,
  ReportedError,
  SystemError,
  ErrorFilters,
  ErrorStats,

  // Comunes
  TicketStatus,
  TicketCategory,
  TicketPriority,
  PaginatedResponse,
} from '@utilia-os/sdk-js';

Requisitos

• Node.js >= 18.0.0
• TypeScript >= 4.7 (opcional, para tipos)

Licencia

MIT