Módulos

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.

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.
Se distribuye como un paquete .orkmod: un tar comprimido con zstd que contiene module.wasm, orkan-module.toml (el manifiesto), 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 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; 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`

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.

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 y te contamos cómo. Mira manifiesto y firma.