@eleva-io/erp-sdk/README.md

SDK oficial para el ERP de Eleva

# ERP SDK - Eleva

SDK oficial para el ERP de Eleva que funciona tanto en navegador como en Node.js.

## Instalación

```bash
npm install @eleva-io/erp-sdk
# o
yarn add @eleva-io/erp-sdk
# o
pnpm add @eleva-io/erp-sdk
```

## Uso

### En Node.js (CommonJS)

```javascript
const { ERPClient } = require('@eleva-io/erp-sdk');

const client = new ERPClient({
  baseURL: 'https://api.eleva.io',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});

// O usando token
const client = new ERPClient({
  baseURL: 'https://api.eleva.io',
  token: 'your-token'
});
```

### En Node.js (ESM)

```javascript
import { ERPClient } from '@eleva-io/erp-sdk';

const client = new ERPClient({
  baseURL: 'https://api.eleva.io',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});
```

### En el navegador

```javascript
import { ERPClient } from '@eleva-io/erp-sdk';

const client = new ERPClient({
  baseURL: 'https://api.eleva.io',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});
```

## Características

- ✅ Compatible con navegador y Node.js
- ✅ Soporte para CommonJS y ESM
- ✅ Tipado completo con TypeScript
- ✅ Manejo automático de autenticación
- ✅ Subida de archivos compatible con ambos entornos
- ✅ Descarga de archivos binarios
- ✅ Estructura de módulos limpia y organizada
- ✅ Imports resueltos correctamente para distribución

## Autenticación

La librería soporta dos métodos de autenticación:

### API Key + Secret
```javascript
const client = new ERPClient({
  baseURL: 'https://api.eleva.io',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});
```

### Token Bearer
```javascript
const client = new ERPClient({
  baseURL: 'https://api.eleva.io',
  token: 'your-bearer-token'
});
```

## Ejemplos

### Trabajar con documentos

```javascript
// Subir un archivo
const document = await client.horizontal().communities('community-id').documents().create({
  fileName: 'document.pdf',
  fileData: fileBuffer // Buffer en Node.js o Uint8Array en navegador
});

// Descargar un archivo
const fileData = await client.horizontal().communities('community-id').documents().download('document-id');
```

### Trabajar con tareas

```javascript
// Crear una tarea con adjunto
const task = await client.ticketing().tasks().create({
  title: 'Nueva tarea',
  description: 'Descripción de la tarea',
  // ... otros campos
});

// Agregar un comentario con archivo adjunto
await client.ticketing().tasks().conversations().create(task.id, {
  message: 'Comentario con archivo',
  attachment: {
    fileName: 'archivo.pdf',
    fileData: fileBuffer
  }
});
```

### Importar tipos específicos

```typescript
// Importar tipos de recibos
import { 
  ReceiptDetail, 
  ReceiptStatus, 
  ReceiptCurrency,
  Receipt,
  CreateReceiptDTO 
} from '@eleva-io/erp-sdk'

// Importar tipos de documentos
import { 
  Document, 
  DocumentStatus,
  CreateDocumentDTO 
} from '@eleva-io/erp-sdk'

// Importar tipos de tareas
import { 
  TicketingTask,
  TicketingTaskStatus,
  CreateTicketingTaskDTO 
} from '@eleva-io/erp-sdk'

// Importar tipos de utilidades
import { 
  PaginatedResponse,
  CrossPlatformBuffer,
  CrossPlatformFile 
} from '@eleva-io/erp-sdk'
```

## Estructura de Módulos

La librería utiliza una estructura de módulos duales para máxima compatibilidad:

```
dist/
├── cjs/     # CommonJS (Node.js tradicional)
└── esm/     # ESM (Navegadores y Node.js moderno)
```

- **CommonJS**: Para `require()` en Node.js
- **ESM**: Para `import` en navegadores y Node.js moderno

## Resolución de Imports

La librería utiliza rutas relativas para todos los imports internos, lo que garantiza que funcione correctamente cuando se instala como dependencia.

### Proceso de Build

1. **Compilación TypeScript**: Genera archivos JavaScript con imports relativos
2. **Dual Output**: Genera tanto CommonJS como ESM sin necesidad de procesamiento adicional

### Ventajas de la Estructura Actual

- ✅ **Sin dependencias adicionales**: No requiere `tsc-alias` ni herramientas externas
- ✅ **Build más rápido**: Proceso de compilación simplificado
- ✅ **Menos complejidad**: Configuración más simple y mantenible
- ✅ **Compatibilidad total**: Funciona en todos los entornos sin problemas

## Compatibilidad

- **Node.js**: >= 16
- **Navegadores**: Todos los navegadores modernos que soporten ES2022
- **TypeScript**: >= 4.9

## Desarrollo

```bash
# Instalar dependencias
pnpm install

# Compilar
pnpm build

# Ejecutar tests
pnpm test

# Linting
pnpm lint
```

## Estructura del Proyecto

```
src/
├── utils/
│   ├── compatibility.ts  # Utilidades cross-platform
│   ├── http.ts          # Cliente HTTP
│   └── ...
├── modules/
│   ├── horizontal/      # Módulo horizontal
│   ├── ticketing/       # Módulo de tareas
│   └── ...
└── erp.ts              # Cliente principal
```