Node.js

The official Node.js SDK (@aelio/sdk) is the primary Aelio SDK. It supports Express, Fastify, vanilla node:http, and any Node.js backend framework.

Install

npm install @aelio/sdk

Requires Node.js ≥ 20.

Guides in this section

Guide	Framework	Complexity
Express	Express.js	Minimal — tools only
ShopCo Sample SaaS	Express + YAML pipeline	Recommended — multi-stage onboarding
Vanilla Node	node:http (no framework)	Shopping Testbed pattern

Quick integration

import { aelio } from '@aelio/sdk';

aelio.expose('getOrderStatus', async ({ orderId }, ctx) => {
  return await db.orders.findOne({ id: orderId, userId: ctx.customerId });
}, {
  description: 'Get order status',
  params: { orderId: 'string' },
  safety: 'read',
});

await aelio.listen({
  secret: process.env.AELIO_SDK_SECRET,
  url: process.env.AELIO_SERVER_URL ?? 'ws://127.0.0.1:3010',
});

Full API surface

Method	Purpose
`aelio.expose(name, handler, schema)`	Register LLM tool
`aelio.persona(text)`	Assistant tone/brand
`aelio.describe(text)`	Product description for harness
`aelio.toolGroups(groups)`	Reusable allow/block buckets for stages
`aelio.pipeline(schema)`	Global pipeline stages + transitions
`aelio.attribute(id, schema)`	Profile memory field schema
`aelio.state(id, schema)`	Lifecycle state (optional if using pipeline)
`aelio.policy(id, schema)`	Conversation policy
`aelio.flow(id, schema)`	Guided multi-step flow
`aelio.setGlobalStage(id, stage, reason?)`	Push global pipeline stage
`aelio.setAttribute(id, attrId, value, opts?)`	Push profile attribute
`aelio.setCustomerState(id, state, reason?)`	Push lifecycle state
`aelio.setFlowProgress(id, flow, step, completed?)`	Update flow progress
`aelio.onSend(handler)`	BYO channel delivery
`aelio.ingest(message)`	Push inbound message
`aelio.listen(options)`	Connect to server
`aelio.disconnect()`	Close connection

For YAML-backed pipelines, see Pipeline YAML Manifest.

Environment variables

AELIO_SDK_SECRET=change-me-in-production
AELIO_SERVER_URL=ws://127.0.0.1:3010

Working examples

Minimal: examples/nodejs-express/src/index.ts — 3 tools, Express health endpoint
Pipeline YAML: examples/sample-saas/ — ShopCo demo with multi-stage onboarding manifest
E-commerce: Aelio-Test/server.mjs — 11 tools, 5 states, Postgres, WebSocket proxy