PlatformsNode.js
Node.js
Integrate @aelio/sdk with Node.js backends — Express, Fastify, vanilla HTTP.
The official Node.js SDK (@aelio/sdk) is the primary Convox SDK. It supports Express, Fastify, vanilla node:http, and any Node.js backend framework.
Install
npm install @aelio/sdkRequires Node.js ≥ 20.
Guides in this section
| Guide | Framework | Complexity |
|---|---|---|
| Express | Express.js | Minimal — recommended starting point |
| 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.state(id, schema) | Lifecycle state |
aelio.policy(id, schema) | Conversation policy |
aelio.flow(id, schema) | Guided multi-step flow |
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 |
Environment variables
AELIO_SDK_SECRET=change-me-in-production
AELIO_SERVER_URL=ws://127.0.0.1:3010Working examples
- Minimal:
examples/nodejs-express/src/index.ts— 3 tools, Express health endpoint - Full SaaS:
examples/sample-saas/— 6 tools, lifecycle states, REST API - E-commerce:
Aelio-Test/server.mjs— 11 tools, 5 states, Postgres, WebSocket proxy