# Módulos

> Qué es un módulo de Orkan, en qué lenguajes se escribe y cómo se crea, se construye y se empaqueta con la CLI orkan-module.

Un **módulo** enseña a Orkan a hablar con un servicio. Aporta **pasos** (y, si hace falta, pasos de inicio) a las automatizaciones. En la interfaz se llaman **más apps**; los oficiales (Gmail, Slack, Stripe…) los firma Gnevoo. Mira el [catálogo de integraciones](https://wiki.itsorkan.com/integraciones/).

Esta sección es para quien quiere **escribir** módulos. Si solo quieres usarlos, no la necesitas.

## Qué es por dentro

-   Un **componente WebAssembly** (`wasm32-wasip2`) del mundo `orkan:module@1.0.0`. Mira el [contrato WIT](https://wiki.itsorkan.com/desarrolladores/contrato-wit/).
-   Se distribuye como un paquete **`.orkmod`**: un `tar` comprimido con `zstd` que contiene `module.wasm`, `orkan-module.toml` (el [manifiesto](https://wiki.itsorkan.com/desarrolladores/manifiesto-y-firma/)), `module.sig` (la firma) y, de forma opcional, `README.md`, `LICENSE`, `icon.svg` y la carpeta `assets/`.
-   Los **logos de las marcas** que muestra Orkan (en los pasos y en las cuentas) los lleva cada módulo en `assets/brands/`; Orkan no incluye logos de terceros.

## Qué puede y qué no puede hacer

Un módulo puede describir sus pasos, ejecutarlos, dar opciones a los desplegables del editor, comprobar una cuenta, escribir registros, hacer peticiones a los servidores que declare, guardar estado entre ejecuciones y usar las [cuentas](https://wiki.itsorkan.com/usar/cuentas-conectadas/) de la organización **sin ver nunca la clave**.

No puede acceder al sistema de ficheros ni a variables de entorno, ni salir a la red fuera de lo declarado, ni conservar memoria entre ejecuciones (cada ejecución es una instancia nueva). Todo permiso que necesita se declara como [capacidad](https://wiki.itsorkan.com/desarrolladores/manifiesto-y-firma/#capacidades); lo que no se declara, queda denegado.

## Lenguajes

Hay SDK para cuatro lenguajes:

| Lenguaje | Notas |
| --- | --- |
| **Rust** | El SDK todavía no está publicado: hasta entonces, `--sdk-path` apunta a una copia local. |
| **JavaScript / TypeScript** | Paquete `@orkan/module-sdk`. Necesita Node 22 o superior. El componente pesa unos 14 MB. |
| **Python** | Paquete `orkan-module-sdk`. |
| **Go** | Compila con TinyGo. Hoy se empaqueta con `orkan-module pack --wasm`. |

## La CLI `orkan-module`

```bash
orkan-module new acme.echo                  # módulo nuevo (Rust)
orkan-module new acme.echo --lang js        # o --lang python, --lang go
orkan-module new acme.poller --trigger      # con un paso de inicio de ejemplo
orkan-module build                          # compila y comprueba las capacidades
orkan-module keygen --out ./claves          # genera tu clave de firma
orkan-module pack --key ./claves/<id>.pk8   # crea el .orkmod firmado
orkan-module verify <paquete>.orkmod --trust ./claves/trust.toml
```

| Comando | Para qué |
| --- | --- |
| `new` | Crea el esqueleto de un módulo con su manifiesto. |
| `build` | Compila el módulo y comprueba que las capacidades declaradas cubren lo que importa. |
| `world` | Genera un paquete WIT reducido a las capacidades declaradas. |
| `inspect` | Muestra el contenido de un `.wasm` o `.orkmod`. |
| `keygen` | Genera un par de claves Ed25519 de firma. |
| `pack` | Compila (salvo `--no-build`) y crea un `.orkmod` firmado. |
| `verify` | Comprueba firma, hashes, manifiesto y capacidades de un `.orkmod`. |
| `redeem`, `register-key`, `publish`, `list`, `yank` | Para publicar en el registro. Mira [manifiesto y firma](https://wiki.itsorkan.com/desarrolladores/manifiesto-y-firma/#publicar). |

> **Pendiente**
>
> Pendiente
> 
> La CLI también tiene `openapi-import` y `curl-import`, pero **todavía no funcionan**.

## Límites de tamaño

| Qué | Límite |
| --- | --- |
| `module.wasm` | 32 MiB |
| `icon.svg` | 256 KiB |
| `assets/` en total | 2 MiB |
| Cada elemento (JSON y metadatos) | 1 MiB |
| Estado guardado entre ejecuciones | 256 KiB por valor |

## Errores y reintentos

Cuando un paso falla, devuelve un error con tipo, y el tipo decide qué hace Orkan: `transient` (red, 5xx, límite de ritmo) se **reintenta**; `user`, `config` y `credential` **no**, y piden a la persona que corrija algo; `denied` indica que Orkan denegó la operación. Usa la variante que corresponde: es la única señal que recibe el motor.

Como se reintenta, **un paso con efectos externos debe poder repetirse sin duplicar el efecto** (por ejemplo, con una clave de idempotencia del servicio).

## Publicar

Publicar en el catálogo requiere una **invitación de Gnevoo**: [escríbenos](mailto:contact@gnevoo.es) y te contamos cómo. Mira [manifiesto y firma](https://wiki.itsorkan.com/desarrolladores/manifiesto-y-firma/).