@utilia-os/sdk-js 1.0.0

package/README.md

@@ -0,0 +1,187 @@
+# @utilia-os/sdk-js
+
+SDK JavaScript/TypeScript para integrar aplicaciones externas con UTILIA OS.
+
+## Instalacion
+
+```bash
+npm install @utilia-os/sdk-js
+```
+
+## Configuracion
+
+```typescript
+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:
+
+```typescript
+const user = await sdk.users.identify({
+  externalId: 'user-123',           // ID unico en tu sistema (requerido)
+  email: 'user@example.com',        // opcional
+  name: 'Juan Perez',               // opcional
+  avatarUrl: 'https://...',         // opcional
+  metadata: {                       // opcional, datos adicionales
+    plan: 'premium',
+    company: 'Acme Inc',
+  },
+});
+```
+
+### Crear Ticket
+
+```typescript
+const ticket = await sdk.tickets.create({
+  user: {
+    externalId: 'user-123',
+    email: 'user@example.com',
+    name: 'Juan Perez',
+  },
+  title: 'Problema con la facturacion',
+  description: 'No puedo ver mis facturas del mes pasado...',
+  category: 'PROBLEMA',  // CONSULTA | PROBLEMA | SUGERENCIA | OTRO
+  priority: 'MEDIA',     // BAJA | MEDIA | ALTA | CRITICA
+  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
+
+```typescript
+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
+
+```typescript
+const ticket = await sdk.tickets.get('ticket-uuid', 'user-123');
+
+console.log(ticket.title);
+console.log(ticket.messages);  // Array de mensajes
+```
+
+### Agregar Mensaje
+
+```typescript
+const message = await sdk.tickets.addMessage('ticket-uuid', 'user-123', {
+  content: 'Gracias por la respuesta, el problema ya fue resuelto.',
+});
+```
+
+### Cerrar/Reabrir Ticket
+
+```typescript
+// Cerrar
+await sdk.tickets.close('ticket-uuid', 'user-123');
+
+// Reabrir
+await sdk.tickets.reopen('ticket-uuid', 'user-123');
+```
+
+### Obtener Mensajes No Leidos
+
+```typescript
+const { count } = await sdk.tickets.getUnreadCount('user-123');
+if (count > 0) {
+  console.log(`Tienes ${count} mensajes sin leer`);
+}
+```
+
+## Manejo de Errores
+
+```typescript
+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 invalida');
+        break;
+      case ErrorCode.RATE_LIMITED:
+        console.error('Demasiadas peticiones, espera antes de reintentar');
+        break;
+      case ErrorCode.VALIDATION_ERROR:
+        console.error('Datos invalidos:', 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 logica de reintento
+    }
+  }
+}
+```
+
+## Tipos
+
+El SDK exporta todos los tipos TypeScript necesarios:
+
+```typescript
+import type {
+  // Configuracion
+  UtiliaSDKConfig,
+
+  // Tickets
+  CreateTicketInput,
+  TicketFilters,
+  AddMessageInput,
+  CreatedTicket,
+  TicketListItem,
+  TicketDetail,
+  TicketMessage,
+
+  // Usuarios
+  IdentifyUserInput,
+  ExternalUser,
+
+  // Comunes
+  TicketStatus,
+  TicketCategory,
+  TicketPriority,
+  PaginatedResponse,
+} from '@utilia-os/sdk-js';
+```
+
+## Requisitos
+
+- Node.js >= 18.0.0
+- TypeScript >= 4.7 (opcional, para tipos)
+
+## Licencia
+
+MIT