@enerlence/suntropy-cli 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@enerlence/suntropy-cli",
+  "version": "0.1.0",
+  "description": "Agent-first CLI for Suntropy solar platform",
+  "type": "module",
+  "bin": {
+    "suntropy": "./dist/bin/suntropy.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx bin/suntropy.ts",
+    "start": "node dist/bin/suntropy.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["suntropy", "solar", "cli", "agent"],
+  "license": "UNLICENSED",
+  "dependencies": {
+    "axios": "^1.7.0",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "energy-types": "^0.0.127",
+    "form-data": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.1.0",
+    "tsx": "^4.15.0",
+    "typescript": "^5.5.0"
+  }
+}

package/skills/inventory-create-kit.md

@@ -0,0 +1,245 @@
+Guía detallada para crear kits solares, kits de cargadores VE y kits de aerotermia, incluyendo la asociación de componentes y equipos personalizados (custom assets).
+
+## Conceptos clave
+
+Un kit agrupa componentes en un producto comercializable. Existen tres tipos:
+
+| Tipo | Comando | Componente principal | Custom assets |
+|------|---------|---------------------|---------------|
+| Kit solar | `suntropy inventory kits` | KitSolarPanel + KitInverter + Battery | SolarKitCustomAsset |
+| Kit cargador VE | `suntropy inventory charger-kits` | Charger | VEChargerKitCustomAsset |
+| Kit aerotermia | `suntropy inventory heatpump-kits` | Heatpump | HeatpumpKitCustomAsset |
+
+**Importante:** Los componentes de un kit solar (KitSolarPanel, KitInverter) son entidades **separadas** de los paneles e inversores del inventario general. Tienen sus propios IDs y campos. Esto permite que un kit defina su panel/inversor específico sin modificar el inventario.
+
+## Flujo completo: Kit solar
+
+### Paso 1: Crear componentes del kit
+
+#### Panel del kit
+```bash
+suntropy inventory kits panels create --data '{
+  "name": "Panel Kit 450W",
+  "peakPower": 450,
+  "efficiency": 21.3,
+  "panelDegradation": 0.55,
+  "width": 1134,
+  "heigth": 1762,
+  "costPerUnit": 120,
+  "manufacturer": {"idManufacturer": <id>}
+}'
+```
+Guarda el `idKitSolarPanel` del resultado.
+
+Campos disponibles: name, peakPower, efficiency, panelDegradation, technology, width, heigth, depth, costPerUnit, referenceId, imageUrl, manufacturer, manufacturingWarranty, materialsWarranty, description
+
+#### Inversor del kit
+```bash
+suntropy inventory kits inverters create --data '{
+  "name": "Inversor Kit 5kW",
+  "nominalPower": 5000,
+  "efficiency": 98.4,
+  "isMicroinverter": false,
+  "costPerUnit": 800,
+  "manufacturer": {"idManufacturer": <id>}
+}'
+```
+Guarda el `idKitInverter` del resultado.
+
+Campos disponibles: name, nominalPower, efficiency, isMicroinverter, costPerUnit, referenceId, imageUrl, manufacturer, manufacturingWarranty, materialsWarranty, description
+
+#### Batería (opcional)
+Los kits referencian baterías del inventario general directamente (no tienen entidad separada):
+```bash
+# Buscar baterías existentes
+suntropy inventory batteries list --fields batteryId,name,capacity,costPerUnit
+
+# O crear una nueva
+suntropy inventory batteries create --data '{"name":"LUNA2000-5","capacity":5,"costPerUnit":2500}'
+```
+Guarda el `batteryId`.
+
+### Paso 2: Preparar custom assets (opcional)
+
+Los custom assets del kit referencian equipos personalizados existentes del inventario. Cada asociación incluye un campo `units` (cantidad).
+
+```bash
+# Buscar custom assets existentes
+suntropy inventory custom-assets list --fields idCustomAsset,label,costPerUnit,customAssetType
+```
+
+Si no existe el asset que necesitas, créalo primero siguiendo la guía de [equipos personalizados](inventory-create.md).
+
+### Paso 3: Ensamblar el kit (método recomendado)
+
+Usa el comando `assemble` para crear el kit referenciando componentes por ID con flags explícitos. Esto evita construir JSON anidado y hace el comando autoexplicativo:
+
+```bash
+suntropy inventory kits assemble \
+  --name "Kit Solar Premium 5kW" \
+  --panel <kitPanelId> \
+  --inverter <kitInverterId> \
+  --battery <batteryId> \
+  --panels-count 12 \
+  --inverters-count 1 \
+  --batteries-count 1 \
+  --peak-power 5.4 \
+  --price 6500 \
+  --phase single_phase \
+  --coplanar \
+  --taxes 21 \
+  --custom-asset <assetId1>:12 \
+  --custom-asset <assetId2>:1
+```
+
+**Opciones de `assemble`:**
+
+| Flag | Default | Descripción |
+|------|---------|-------------|
+| `--name` | (obligatorio) | Nombre/identificador del kit |
+| `--panel` | - | ID del panel del kit (idKitSolarPanel) |
+| `--inverter` | - | ID del inversor del kit (idKitInverter) |
+| `--battery` | - | ID de batería del inventario (batteryId) |
+| `--panels-count` | 12 | Cantidad de paneles |
+| `--inverters-count` | 1 | Cantidad de inversores |
+| `--batteries-count` | 0 | Cantidad de baterías |
+| `--peak-power` | - | Potencia pico total (kW) |
+| `--price` | - | Precio del kit (€) |
+| `--phase` | single_phase | single_phase o three_phase |
+| `--coplanar` | false | Montaje coplanar |
+| `--taxes` | 21 | IVA por defecto (%) |
+| `--custom-asset` | - | Equipo personalizado como `<id>:<unidades>` (repetible) |
+
+**Ejemplo completo:**
+```bash
+suntropy inventory kits assemble \
+  --name "Kit Residencial 5.4kW" \
+  --panel 57532 --inverter 23359 \
+  --panels-count 12 --peak-power 5.4 --price 6500 \
+  --coplanar \
+  --custom-asset 2281:12 --custom-asset 2282:1
+```
+
+### Alternativa: Crear con JSON completo
+
+Para campos avanzados (garantías, useTotalKitCostAsPrice, etc.) usa `create --data`:
+
+```bash
+suntropy inventory kits create --data '{
+  "identifier": "Kit Solar Premium 5kW",
+  "kitSolarPanel": {"idKitSolarPanel": <panelId>},
+  "kitInverter": {"idKitInverter": <inverterId>},
+  "battery": {"batteryId": <batteryId>},
+  "panelNumber": 12,
+  "inverterNumber": 1,
+  "peakPower": 5.4,
+  "price": 6500,
+  "phaseNumber": "single_phase",
+  "coplanar": true,
+  "defaultTaxesPercentage": 21,
+  "manufacturingWarranty": 10,
+  "materialsWarranty": 5,
+  "useTotalKitCostAsPrice": false,
+  "active": true,
+  "solarKitCustomAssets": [
+    {"customAsset": {"idCustomAsset": <assetId1>}, "units": 12},
+    {"customAsset": {"idCustomAsset": <assetId2>}, "units": 1}
+  ]
+}'
+```
+
+### Paso 4: Verificar el kit creado
+
+```bash
+suntropy inventory kits get <kitId>
+```
+
+## Gestión de custom assets en un kit existente
+
+### Añadir custom assets
+Actualiza el kit incluyendo los custom assets existentes MÁS los nuevos:
+
+```bash
+# Primero obtén los custom assets actuales
+suntropy inventory kits get <kitId> --fields solarKitCustomAssets
+
+# Luego actualiza incluyendo todos (existentes + nuevos)
+suntropy inventory kits update <kitId> --data '{
+  "solarKitCustomAssets": [
+    {"idSolarKitCustomAsset": <existente1>, "customAsset": {"idCustomAsset": <id>}, "units": 12},
+    {"idSolarKitCustomAsset": <existente2>, "customAsset": {"idCustomAsset": <id>}, "units": 1},
+    {"customAsset": {"idCustomAsset": <nuevoAssetId>}, "units": 3}
+  ]
+}'
+```
+
+**Lógica del backend en update:**
+- Elementos CON `idSolarKitCustomAsset` → se actualizan (solo `units`)
+- Elementos SIN `idSolarKitCustomAsset` → se crean nuevos
+- Elementos existentes NO incluidos en el array → se eliminan
+
+Esto significa que para eliminar un custom asset de un kit, simplemente lo omites del array en el update.
+
+### Cambiar cantidad
+```bash
+suntropy inventory kits update <kitId> --data '{
+  "solarKitCustomAssets": [
+    {"idSolarKitCustomAsset": <id>, "customAsset": {"idCustomAsset": <id>}, "units": 20}
+  ]
+}'
+```
+
+## Kit de cargador VE
+
+```bash
+# Crear el kit referenciando un cargador existente
+suntropy inventory charger-kits create --data '{
+  "identifier": "Kit Wallbox Premium",
+  "charger": {"idCharger": <chargerId>},
+  "price": 1200,
+  "phaseNumber": 1,
+  "defaultTaxesPercentage": 21,
+  "useTotalKitCostAsPrice": false,
+  "active": true,
+  "veChargerKitCustomAssets": [
+    {"customAsset": {"idCustomAsset": <assetId>}, "units": 1}
+  ]
+}'
+```
+
+## Kit de aerotermia
+
+```bash
+# Crear el kit referenciando una aerotermia existente
+suntropy inventory heatpump-kits create --data '{
+  "identifier": "Kit Aerotermia Daikin 8kW",
+  "heatpump": {"idHeatpump": <heatpumpId>},
+  "price": 8500,
+  "phaseNumber": 1,
+  "defaultTaxesPercentage": 21,
+  "useTotalKitCostAsPrice": false,
+  "active": true,
+  "heatpumpKitCustomAssets": [
+    {"customAsset": {"idCustomAsset": <assetId>}, "units": 1}
+  ]
+}'
+```
+
+## Otros comandos útiles
+
+```bash
+# Listar componentes del kit
+suntropy inventory kits panels list
+suntropy inventory kits inverters list
+suntropy inventory kits batteries list
+
+# Archivar kit (soft delete)
+suntropy inventory kits archive <kitId>
+
+# Marcar panel/inversor como destacado
+suntropy inventory kits panels featured <kitPanelId>
+suntropy inventory kits inverters featured <kitInverterId>
+
+# Buscar fabricantes para los componentes
+suntropy inventory manufacturers list
+```

package/skills/inventory-create.md

@@ -0,0 +1,210 @@
+Crea elementos en el inventario de Suntropy usando la CLI. El inventario incluye: paneles solares, inversores, baterías, cargadores VE, aerotermias, equipos personalizados (custom assets) y kits.
+
+## Parámetros de entrada
+
+Pregunta al usuario qué tipo de elemento quiere crear. Si no especifica, pregunta.
+
+## Tipos de elementos y sus campos
+
+### Paneles solares (`suntropy inventory panels create`)
+| Campo | Tipo | Obligatorio | Ejemplo |
+|-------|------|-------------|---------|
+| name | string | Sí | "JA Solar 450W" |
+| peakPower | number | Sí | 450 (Wp) |
+| efficiency | number | No | 21.3 (%) |
+| manufacturer | object | No | {"idManufacturer": N} |
+| panelDegradation | number | No | 0.55 (%) |
+| width | number | No | 1134 (mm) |
+| heigth | number | No | 1762 (mm) |
+| costPerUnit | number | No | 120 (€) |
+| active | boolean | No | true |
+| referenceId | string | No | "JAM72S30-450" |
+| description | string | No | - |
+
+```bash
+suntropy inventory panels create --data '{"name":"JA Solar 450W","peakPower":450,"efficiency":21.3,"costPerUnit":120,"active":true}'
+```
+
+### Inversores (`suntropy inventory inverters create`)
+| Campo | Tipo | Obligatorio | Ejemplo |
+|-------|------|-------------|---------|
+| name | string | Sí | "Huawei SUN2000-5KTL" |
+| nominalPower | number | Sí | 5000 (W) |
+| efficiency | number | No | 98.4 (%) |
+| manufacturer | object | No | {"idManufacturer": N} |
+| phaseNumber | string | No | "single_phase" o "three_phase" |
+| isMicroinverter | boolean | No | false |
+| isHybrid | boolean | No | false |
+| maxCapacityOfBattery | number | No | 15 (kWh) |
+| costPerUnit | number | No | 800 (€) |
+| active | boolean | No | true |
+
+```bash
+suntropy inventory inverters create --data '{"name":"Huawei SUN2000-5KTL","nominalPower":5000,"efficiency":98.4,"phaseNumber":"single_phase","costPerUnit":800}'
+```
+
+### Baterías (`suntropy inventory batteries create`)
+| Campo | Tipo | Obligatorio | Ejemplo |
+|-------|------|-------------|---------|
+| name | string | Sí | "Huawei LUNA2000-5" |
+| capacity | number | Sí | 5 (kWh) |
+| manufacturer | object | No | {"idManufacturer": N} |
+| isModular | boolean | No | true |
+| maxNumberOfModules | number | No | 3 |
+| availableCapacities | string | No | "5,10,15" |
+| price | number | No | 2500 (€) |
+| costPerUnit | number | No | 2500 (€) |
+| active | boolean | No | true |
+
+```bash
+suntropy inventory batteries create --data '{"name":"Huawei LUNA2000-5","capacity":5,"isModular":true,"costPerUnit":2500}'
+```
+
+### Cargadores VE (`suntropy inventory chargers create`)
+| Campo | Tipo | Obligatorio | Ejemplo |
+|-------|------|-------------|---------|
+| name | string | Sí | "Wallbox Pulsar Plus" |
+| maxPower | number | Sí | 7400 (W) |
+| connectorType | string | No | TYPE_1, TYPE_2, CCS1, CCS2, GBT, CHAdeMO |
+| phaseNumber | number | No | 1 |
+| includedPlug | boolean | No | true |
+| price | number | No | 650 (€) |
+| costPerUnit | number | No | 650 (€) |
+| active | boolean | No | true |
+
+```bash
+suntropy inventory chargers create --data '{"name":"Wallbox Pulsar Plus","maxPower":7400,"connectorType":"TYPE_2","costPerUnit":650}'
+```
+
+### Aerotermias (`suntropy inventory heatpumps create`)
+| Campo | Tipo | Obligatorio | Ejemplo |
+|-------|------|-------------|---------|
+| identifier | string | Sí | "Daikin Altherma 3 8kW" |
+| lowerPower | number | No | 4000 (W) |
+| upperPower | number | No | 8000 (W) |
+| scop | number | No | 4.5 |
+| phases_number | number | No | 1 |
+| manufacturer | object | No | {"idManufacturer": N} |
+| price | number | No | 4500 (€) |
+| costPerUnit | number | No | 4500 (€) |
+| active | boolean | No | true |
+
+```bash
+suntropy inventory heatpumps create --data '{"identifier":"Daikin Altherma 3 8kW","lowerPower":4000,"upperPower":8000,"scop":4.5,"costPerUnit":4500}'
+```
+
+### Equipos personalizados (Custom Assets)
+
+Los custom assets tienen una estructura jerárquica: **Tipo → Campos → Asset**
+
+#### Paso 1: Buscar o crear un tipo
+
+Primero busca si ya existe un tipo adecuado:
+```bash
+suntropy inventory custom-asset-types list
+```
+
+Si necesitas crear uno nuevo:
+```bash
+suntropy inventory custom-asset-types create --data '{
+  "label": "Nombre del tipo",
+  "image": "wrench",
+  "isMaterialConcept": true,
+  "panelsQuantity": false,
+  "uniqueCustomAssetSelection": false,
+  "customFields": [
+    {"label": "Campo texto", "type": "text"},
+    {"label": "Campo numérico", "type": "number"},
+    {"label": "Campo opciones", "type": "options", "customFieldOptions": [
+      {"label": "Opción A", "value": "a"},
+      {"label": "Opción B", "value": "b"}
+    ]}
+  ]
+}'
+```
+
+**Flags del tipo:**
+- `isMaterialConcept`: true = aparece como material en presupuestos
+- `panelsQuantity`: true = la cantidad se iguala automáticamente al número de paneles
+- `uniqueCustomAssetSelection`: true = solo se puede seleccionar un asset de este tipo por estudio
+
+**Tipos de campo soportados:**
+text, number, date, datetime, time, email, phonenumber, website, options, labels, currency, large_text, user
+
+#### Paso 2: Obtener IDs de los campos del tipo
+
+```bash
+suntropy inventory custom-asset-types get <typeId>
+```
+Anota los `idCustomField` de cada campo en `customFields`.
+
+#### Paso 3: Crear el asset
+
+```bash
+suntropy inventory custom-assets create --data '{
+  "label": "Nombre del equipo",
+  "identifier": "REF-001",
+  "costPerUnit": 100,
+  "isMaterial": true,
+  "hideOnBudget": false,
+  "description": "Descripción del equipo",
+  "customAssetType": {"idCustomAssetType": <typeId>},
+  "customAssetCustomField": [
+    {"customField": {"idCustomField": <fieldId1>}, "value": "valor1"},
+    {"customField": {"idCustomField": <fieldId2>}, "value": "42"},
+    {"customField": {"idCustomField": <fieldId3>}, "value": "a"}
+  ]
+}'
+```
+
+**Campos del asset:**
+- `label`: Nombre visible
+- `identifier`: Referencia interna
+- `costPerUnit`: Precio unitario (€)
+- `isMaterial`: Es un concepto material
+- `hideOnBudget`: Ocultar en presupuesto (pero incluir en coste)
+- `customAssetType`: Referencia al tipo por ID
+- `customAssetCustomField`: Array de valores para los campos del tipo. Para campos tipo `options`, el value es el `value` de la opción (no el label)
+
+### Manufacturers
+
+Si necesitas referenciar un fabricante, primero búscalo o créalo:
+
+```bash
+# Buscar fabricantes existentes
+suntropy inventory manufacturers list
+
+# Crear nuevo fabricante
+suntropy inventory manufacturers create --data '{"name": "JA Solar"}'
+```
+
+Luego referéncialo en el equipo: `"manufacturer": {"idManufacturer": <id>}`
+
+### Kits (solar, cargador VE, aerotermia)
+
+Para crear kits con todos sus componentes y equipos personalizados asociados, consulta la guía detallada:
+
+**[Crear kits y asociar componentes](inventory-create-kit.md)**
+
+Resumen rápido de un kit solar básico:
+```bash
+# 1. Crear panel y inversor del kit
+suntropy inventory kits panels create --data '{"name":"Panel Kit","peakPower":450,"efficiency":21}'
+suntropy inventory kits inverters create --data '{"name":"Inversor Kit","nominalPower":5000}'
+
+# 2. Ensamblar el kit (método recomendado)
+suntropy inventory kits assemble \
+  --name "Kit Solar 5kW" \
+  --panel <panelId> --inverter <inverterId> \
+  --panels-count 12 --peak-power 5.4 --price 3500 \
+  --custom-asset <assetId>:12
+```
+
+## Notas
+
+- Todos los comandos devuelven JSON con el elemento creado (incluido su ID)
+- Para actualizar: `suntropy inventory <tipo> update <id> --data '{"campo": "nuevo_valor"}'`
+- Para eliminar: `suntropy inventory <tipo> delete <id>`
+- Para listar con filtros: `suntropy inventory <tipo> list --limit 10 --active-only`
+- Usa `--fields campo1,campo2` para seleccionar campos en el output
+- Usa `--format human` para vista legible en tabla