@rekhu/assistant-node

Getting started · Frameworks · Actions · Public chat · Security · Configuration

Rekhu Assistant for Node.js puts a custom AI assistant inside your app, for your own customers. It answers from your help, sends people to the right page, and carries out tasks through the actions you define, as the signed-in user. Every conversation is metered per customer by Rekhu, so you can offer the assistant to your customers and bill them for it.

This package is the back end half. It adds a chat route to your Node.js server, holds your secret key, and runs your actions. The front end half is the widget, @rekhu/assistant-widget, which talks only to your route.

Contents

1. How it works
2. Requirements
3. Getting started
4. Frameworks: Express · Next.js · Nuxt · Hono, Bun and Deno
5. Actions
6. Pages
7. Help
8. Projects, usage and limits
9. A public chat for visitors
10. Reports
11. Running on more than one server
12. Security
13. Configuration
14. Checking your setup · Troubleshooting

How it works

Like Stripe: the secret key lives on your server, the browser only talks to your own routes.

Browser                              Your Node.js server                       Rekhu
┌──────────────────────┐   POST      ┌────────────────────────────────┐ secret ┌──────────┐
│ @rekhu/assistant-    │ /api/rekhu/ │ @rekhu/assistant-node          │ ─key─▶ │ model,   │
│ widget  (no key)     │ ──chat────▶ │ · who is signed in? (your auth)│        │ metering,│
│                      │ ◀─stream─── │ · runs your actions as them    │ ◀───── │ limits   │
└──────────────────────┘             └────────────────────────────────┘        └──────────┘

1. The widget sends the user's message to your chat route, with the user's own session cookie or token.
2. The package asks your user() function who that is, and builds the assistant's view of your app for this user: the actions and pages they may use, and your help.
3. It calls Rekhu with your secret key. Rekhu meters the call for the user's company and forwards it to the model.
4. When the model asks for an action, the package checks the input and calls your run function, as the user, and reports the result back.
5. The answer streams back to the widget: text, steps, and cards (a page to open, an action to confirm, a result).

Requirements

Complete examples

The examples folder is a small shop wired up file by file: an assistant with one action of each kind, its route behind your sign-in, help topics and a React chat of your own. It runs as it is, and is not part of what npm installs.

Getting started

1. Get a secret key

In your Rekhu account, put credit on the account under Billing, then create a project under Projects → New project: choose Node.js app, monolith or multi-tenant, and name it (for example "Shop"). Its assistant is on from the start; on its Connection tab add a key for your first environment (local). Add one per environment later (staging, production); they all count toward the same project. The key starts with agk_ and is shown once.

Put it in your server's environment, never in front-end code:

REKHU_SECRET_KEY=agk_…

2. Install

npm install @rekhu/assistant-node @rekhu/assistant-widget

3. Create the assistant

// assistant.js (server side)
import { createAssistant, defineAction, Forbidden } from '@rekhu/assistant-node';
import { orders } from './orders.js';

export const assistant = createAssistant({
    appName: 'My shop',
    user: (req) => req.user ?? null,                       // your own sign-in decides who this is
    tenant: (user) => ({ id: user.companyId, name: user.companyName }),
    help: './help',                                        // markdown files, one topic each
    actions: [
        defineAction({
            name: 'reorder',
            description: 'Reorder a past order: the same product as a new order; the quantity can be changed',
            input: { orderNumber: 'string', quantity: 'integer?' },
            run: async ({ orderNumber, quantity }, { user }) => {
                const order = await orders.find(orderNumber);
                if (!order || order.ownerId !== user.id) throw new Forbidden();   // your permission check
                const created = await orders.reorder(order, quantity);
                return { message: `Order ${created.number} placed.`, page: `/orders/${created.number}` };
            },
        }),
    ],
});

4. Add the route

For Express:

import express from 'express';
import { assistant } from './assistant.js';

const app = express();
app.use('/api/rekhu', assistant.express());   // serves /api/rekhu/chat

Other frameworks are under Frameworks.

5. Add the widget

In the front end, for a signed-in user:

import { mount } from '@rekhu/assistant-widget';

mount({ endpoint: '/api/rekhu/chat' });

Ask "order my last business cards again". The widget's README shows it for Next.js, Nuxt, Vue, React and plain HTML. A Flutter app uses rekhu_assistant with the same route, behind the middleware that checks its token.

Frameworks

The package serves two routes under the path you mount it on: …/chat for signed-in users, and …/visitor/chat for the public chat. Each answers GET, POST and DELETE.

Express

app.use('/api/rekhu', assistant.express());

user(req) receives the Express request: req.user from Passport, req.session.user from express-session, or whatever your sign-in sets. express.json() before it is fine but not needed. Nest on Express mounts the same middleware with a MiddlewareConsumer.

Next.js

Route handlers, on the Node.js runtime (the default):

// app/api/rekhu/chat/route.ts
import { assistant } from '@/lib/assistant';

export const GET = assistant.fetch;
export const POST = assistant.fetch;
export const DELETE = assistant.fetch;

// lib/assistant.ts
import { createAssistant } from '@rekhu/assistant-node';
import { auth } from '@/auth';   // Auth.js, or your own session

export const assistant = createAssistant({
    user: async () => (await auth())?.user ?? null,
    // …actions, pages, help
});

For the public chat, add the same three lines in app/api/rekhu/visitor/chat/route.ts.

Nuxt

A server route that hands the user over from your session:

// server/api/rekhu/chat.ts
import { assistant } from '~/server/assistant';

export default defineEventHandler(async (event) => {
    const { user } = await getUserSession(event);   // nuxt-auth-utils, or your own session
    return assistant.fetch(toWebRequest(event), { user: user ?? null });
});

assistant.fetch(request, { user }) uses the user you pass instead of calling user(). For the public chat, add server/api/rekhu/visitor/chat.ts with assistant.fetch(toWebRequest(event)).

Hono, Bun and Deno

assistant.fetch is a standard (Request) => Promise<Response> handler:

// Hono
app.all('/api/rekhu/*', (c) => assistant.fetch(c.req.raw, { user: c.get('user') ?? null }));

// Bun
Bun.serve({ fetch: (request) => assistant.fetch(request) });

Remix and SvelteKit hand it their request the same way.

Actions

An action is a function the assistant may call for the user. The package checks the input against its schema, then calls run with the input and the user.

import { defineAction, Forbidden, ActionError } from '@rekhu/assistant-node';

defineAction({
    name: 'cancel_order',
    description: 'Cancel an order that has not shipped yet',
    input: { orderNumber: 'string' },
    danger: true,                                   // asks for a click first, with a red button
    run: async ({ orderNumber }, { user }) => {
        const order = await orders.find(orderNumber);
        if (!order || order.ownerId !== user.id) throw new Forbidden();
        if (order.status === 'shipped') throw new ActionError('This order has shipped already and cannot be cancelled.');
        await orders.cancel(order);
        return { message: `Order ${orderNumber} is cancelled.` };
    },
});

[!IMPORTANT] Check permissions inside run. The package gives run the signed-in user; deciding whether that user may touch this record is your code's job, exactly as in your own route handlers. Throw Forbidden when they may not.

Input. The short form names each field's type, with ? when it is optional:

input: {
    orderNumber: 'string',
    quantity: 'integer?',
    size: ['small', 'medium', 'large'],                               // one of these
    note: { type: 'string', maxLength: 200, optional: true },          // a JSON Schema of one field
}

Or give a full object JSON Schema ({ type: 'object', properties, required }). Supported checks: type, required, enum, minimum, maximum, minLength, maxLength, pattern, minItems, maxItems and the type of array items. Fields not in the schema are dropped. Numbers sent as text ("5") are accepted for integer and number.

Results. Return what the assistant should know (an object, a list, text). On the result card, message is shown as the outcome and page as a button. Throw ActionError('…') for a refusal the user should hear, and Forbidden when the user may not do it. Any other error is logged, and the assistant is told the action failed.

Confirmations. For an action with confirm or danger, nothing runs when the card is shown. The action and its checked input are kept on the server; only the user's click on the card runs it, once, with exactly that input. A typed "yes", or anything the model writes, cannot run it.

Writing good actions

How well the assistant works depends mostly on how you describe your actions. The examples show every kind.

• The description is for the assistant: what the action does, what comes back, what each input means, when to use it and when not. Never shown to users. Not 'Orders', but 'List the user\'s orders, newest first: number, date, status, total in EUR. "status" keeps one status; "search" matches an order number. Use it to find an order before showing or changing it.'
• The label is for the user: a few words in their language, { en: 'Looking up your orders', nl: 'Ik zoek je bestellingen' }. Without one they read "Working on it…".
• The name stays the same: short, snake_case, a verb and a thing (list_orders, change_address).
• Read first, then change: give the assistant a way to find a record before every action that changes one.
• Changes are confirmed: confirm: true for anything the user should see first, danger: true for what cannot be undone. Nothing runs until the click.
• Say when it does not apply ("of an order that has not shipped yet"), and still refuse in run with ActionError when it does not.
• Return what helps: the facts the user asked about, ids for the next step, and message and page for the result card.

Pages

Pages the assistant may send the user to. The user gets a button; the assistant never navigates on its own.

import { definePage } from '@rekhu/assistant-node';

pages: [
    definePage({ name: 'orders', label: 'My orders', path: '/orders' }),
    definePage({ name: 'order', label: 'An order', path: '/orders/:number', help: 'One order with its status and delivery address' }),
    definePage({ name: 'invoices', label: 'Invoices', path: '/invoices', allow: (user) => user.role === 'admin' }),
    definePage({ name: 'pricing', label: 'Prices', path: '/pricing', guests: true }),
]

:parameters in the path are filled in by the assistant. allow(user) hides a page from users who may not open it; guests: true also offers it in the public chat. With the front end on another origin, set pagesBaseUrl.

Help

A folder of markdown files, one topic per file; the first # heading is the topic's title:

help: './help',          // ./help/shipping.md, ./help/returns.md, …

or topics in code: help: [{ title: 'Shipping', text: 'Orders placed before 15:00 ship the same day.' }]. The assistant searches them for how-to questions and answers from them in the user's language; when the help does not cover a question, it says so instead of guessing.

Projects, usage and limits

Your Rekhu account keeps everything per project: one project per app. Its Connection tab holds the keys; its Assistant tab the usage, the limit and the pause.

• Keys per environment. One secret key for local, staging and production; all of them count toward the project.
• One monthly limit and a pause for the project's assistant, with a message on your notification channels at 80% and 100%. At the limit, or paused, the assistant answers nobody; your other projects go on. Its users read that the assistant is not available right now, and your app's log says why.
• Usage per user or per tenant, tracked, not limited: per user for a monolith, per tenant (with its users) for a multi-tenant app, as you choose when you create the project. Conversations, messages and usage per month, and a CSV to bill from.

For a multi-tenant app, say which tenant a user belongs to, so usage shows per tenant:

tenant: (user) => ({ id: user.companyId, name: user.companyName }),

Users are identified to Rekhu by userId(user) (default user.id), never by name or e-mail.

A public chat for visitors

The same assistant for people who are not signed in, for example for a price quote. Turn it on and mark what visitors may use:

createAssistant({
    // …
    guests: { enabled: true },
    actions: [
        defineAction({ name: 'quote', description: 'A price quote', guests: true, input: { quantity: 'integer' }, run: ({ quantity }) => ({ total: quantity * 0.18 }) }),
    ],
});

Then mount the widget for visitors on the public route: mount({ endpoint: '/api/rekhu/visitor/chat', visitor: true }).

Behind a proxy or load balancer, make sure the IP address is the visitor's: in Express set app.set('trust proxy', …), or pass ip: (request) => ….

Reports

Under each answer the user sees Report a problem. They pick what went wrong, may say what they expected instead, and send it; the link becomes "Thanks, we will look into it." The report shows up on the project's Assistant tab in your Rekhu account, linked to the conversation it came from, so you can see what went wrong and improve the knowledge, the help or your actions.

No tables and no routes of your own: the route is …/chat/report next to your chat route (and …/visitor/chat/report for the public chat), the report goes to Rekhu, and onReport gives you a copy.

What a report contains. The package builds it on the server from the conversation it kept; the browser only sends the answer's id, the reason and the comment.

The user is identified by their id only, as with every call. Reports are visible to the project's team in your Rekhu account. A second report on the same answer by the same user replaces the first.

Configure it with reports:

createAssistant({
    // …
    reports: {
        enabled: true,
        reasons: {                      // key => label; null is the built-in text (en, ar, nl)
            wrong_answer: null,
            misunderstood: null,
            wrong_information: null,
            other: null,
            wrong_numbers: { en: 'The numbers are wrong', ar: 'الأرقام غير صحيحة' },   // your own
        },
        maxComment: 1000,
        perUserPerHour: 20,
        guests: true,                   // visitors of the public chat may report too
        includeResults: false,
    },
});

The widget and the history show the server's reasons in the user's language; a chat of your own builds its form from history().report and never hard-codes them. enabled: false removes the link and the route.

A copy of your own. onReport is called for every report, for a table of your own, a message to your team or a ticket:

createAssistant({
    // …
    onReport: async (report, { user, visitor, conversation, message, reason, comment }) => {
        // report: everything that was sent to Rekhu (question, answer, transcript, tools)
        await notifyTeam(`Assistant answer reported: ${reason}`, report);
    },
});

A chat of your own reports with the widget's headless client, by the answer's id from the history or from the stream's done event:

let answer;
await chat.send('Revenue in May?', (event) => { if (event.type === 'done') answer = event.message; });
const { report } = await chat.history();            // report.reasons, report.max_comment
await chat.report({ message: answer, reason: 'wrong_answer', comment: 'It was 41,200' });   // { message: thank-you }

When Rekhu cannot be reached, the user is still thanked; the failure goes to your logger and the report is tried once more. check() says whether reports are on and whether Rekhu takes them.

Running on more than one server

Conversations, confirmations and the public chat's counters are kept in memory by default, which is right for one process. With several processes or servers, give the package a shared store with four methods:

import Redis from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);

createAssistant({
    // …
    store: {
        get: async (key) => JSON.parse((await redis.get(key)) ?? 'null') ?? undefined,
        set: (key, value, ttl) => redis.set(key, JSON.stringify(value), 'EX', ttl),
        delete: (key) => redis.del(key),
        increment: async (key, ttl) => {
            const count = await redis.incr(key);
            if (count === 1) await redis.expire(key, ttl);
            return count;
        },
    },
});

Security

Configuration

createAssistant(options):

Checking your setup

console.log(await assistant.check(someUser));   // or check(null) for what a visitor sees

{ connected: true, credit: '$42.10', problem: null, actions: ['reorder', 'cancel_order'], pages: ['orders', 'order'], help: ['Shipping', 'Returns'],
  reports: { enabled: true, reasons: ['wrong_answer', 'misunderstood', 'wrong_information', 'other'], taken: 'yes' } }

problem says what is wrong: a refused key, or no credit. reports.taken is 'yes' when Rekhu takes reports from this key, 'not yet' when the platform does not take them yet (users are still thanked and the failure is logged), or why it refused.

Troubleshooting

Protocol

The widget and this package speak protocol 1. A chat screen of your own can use the same routes.

Changelog

See CHANGELOG.md.

Licence

Licensed, not sold, to holders of a Rekhu account under the Rekhu Terms of Service. See LICENSE.txt.