Example module acme/hello

'use strict';

const path = require('path');
const Validator = require('fastest-validator');
const { Core, DB, Log, Pages } = require('@orbito/api-lib');

// The collection belongs to this installation only: the core namespaces it per instance.
const Greetings = new DB.Schema('greetings', {
    name: { type: 'string', min: 1, max: 100 },
    message: { type: 'string' },
    createdAt: { type: 'date', optional: true, default: () => new Date() },
});

// One schema, two jobs: `params` documents the method for the core and the AI assistant,
// the compiled checker validates the input. The core never validates params by itself.
const greetParams = {
    name: { type: 'string', trim: true, min: 1, max: 100 },
};
const checkGreetParams = new Validator().compile(greetParams);

Core.registerMethod('greet', {
    description: 'Stores a greeting for the given name and returns it.',
    params: greetParams,
    returns: { type: 'object', props: { _id: 'string', message: 'string' } },
    handler: async (params) => {
        const input = { ...params };
        const check = checkGreetParams(input);
        if (check !== true) {
            throw new Error(`INVALID_PARAMS: ${check.map((error) => error.message).join('; ')}`);
        }

        const message = `Hello, ${input.name}!`;
        const greeting = await Greetings.create({ name: input.name, message });
        Log.info('Greeting stored', { greetingId: String(greeting._id) });

        return { _id: String(greeting._id), message };
    },
});

Core.registerMethod('listGreetings', {
    description: 'Lists stored greetings, newest first, one page at a time.',
    params: {
        page: { type: 'number', integer: true, positive: true, optional: true },
        perPage: { type: 'number', integer: true, positive: true, max: 100, optional: true },
    },
    returns: { type: 'object', props: { data: 'array', total: 'number' } },
    handler: async (params) => {
        const query = params || {};
        const page = Math.max(1, parseInt(query.page, 10) || 1);
        const perPage = Math.min(100, Math.max(1, parseInt(query.perPage, 10) || 10));

        const [data, total] = await Promise.all([
            Greetings.find({}, perPage, (page - 1) * perPage, { createdAt: -1 }),
            Greetings.count({}),
        ]);

        // `{ data, total }` is the shape an OVE datatable reads without extra mapping.
        return { data, total };
    },
});

Pages.registerPages({
    '/hello': {
        name: 'Hello',
        view: path.join(__dirname, 'pages', 'hello.yaml'),
        placement: { location: 'navbar', icon: 'mood-smile', order: 100 },
    },
}).catch((error) => {
    Log.error('Page registration failed', { error: error.message });
});

// Runs once per installed version (first install and every update), not on every
// container start - use it for one-off setup such as indexes, never to start timers.
Core.onEnabled(async () => {
    await DB.createIndex(Greetings.name, { createdAt: -1 });
    Log.info('acme/hello enabled');
});