shutro-erp 0.3.4 → 0.3.6

package/dist/helpdesk/module.js

@@ -0,0 +1,326 @@
+/**
+ * The data layer of Helpdesk (RFC 0024 §2.4): teams with their members, business hours and how tickets are
+ * assigned; stages for each team's board; ticket types; SLA policies (a first reply and a resolution, in business
+ * hours, by team, priority and customer); canned replies; and tickets — open, waiting on the customer (the SLA clock
+ * paused), solved, closed — with their SLA deadlines and status, the customer's rating, and merging.
+ *
+ * Agents see their teams' tickets; Helpdesk managers every ticket; customers their own through the portal later.
+ * The SLA is refreshed by `sla.ts` (every few minutes on the server, and on request).
+ */
+import { contactsShutro } from '../contacts/index.js';
+import { messagingShutro } from '../messaging/index.js';
+import { orm } from '../server/orm.js';
+import { defineModel, defineModule, f, record, records } from './.kosh/bindings.js';
+const READ = ['read'];
+const ALL = ['read', 'write', 'create', 'unlink'];
+const me = { $env: 'uid' };
+const HHMM = orm.sql `~ '^([01][0-9]|2[0-3]):[0-5][0-9]$'`;
+export const PRIORITIES = { low: 'Low', normal: 'Normal', high: 'High', urgent: 'Urgent' };
+/** A priority's rank, for “this priority or higher”. */
+export const RANK = { low: 0, normal: 1, high: 2, urgent: 3 };
+export const HelpdeskTeam = defineModel('helpdesk.team', {
+    label: 'Helpdesk team',
+    recName: 'name',
+    order: ['name asc'],
+    archivable: true,
+    companyScoped: { required: true },
+    access: { 'helpdesk.user': READ, 'helpdesk.manager': [...ALL, 'export', 'import'] },
+    fields: {
+        name: f.char({ required: true, translate: true }),
+        members: f.many2many('res.users', { relation: 'helpdesk_team_member', label: 'Agents' }),
+        assignment: f.selection({ manual: 'By hand', round_robin: 'In turn', load: 'To the least busy' }, {
+            required: true,
+            default: 'round_robin',
+            help: 'How new tickets get their agent: in turn among the agents, or to the one with the fewest open tickets.',
+        }),
+        open: f.char({ size: 5, required: true, default: '09:00', label: 'Opens (HH:MM)' }),
+        close: f.char({ size: 5, required: true, default: '18:00', label: 'Closes (HH:MM)' }),
+        weekend: f.selection({
+            fri_sat: 'Friday and Saturday',
+            sat_sun: 'Saturday and Sunday',
+            fri: 'Friday only',
+            none: 'None (every day)',
+        }, {
+            required: true,
+            default: 'fri_sat',
+            help: 'SLA targets count working hours only: from opening to closing, outside the weekend.',
+        }),
+        rating: f.boolean({
+            default: true,
+            label: 'Ask for a rating',
+            help: 'When a ticket is solved, its customer is asked to rate the help (one to five).',
+        }),
+    },
+    sqlConstraints: {
+        hours: {
+            check: orm.sql `open ${HHMM} AND close ${HHMM} AND close > open`,
+            message: 'Hours are written HH:MM, the closing after the opening.',
+        },
+    },
+});
+export const HelpdeskStage = defineModel('helpdesk.stage', {
+    label: 'Ticket stage',
+    recName: 'name',
+    order: ['sequence asc', 'id asc'],
+    archivable: true,
+    access: { 'helpdesk.user': READ, 'helpdesk.manager': [...ALL, 'export', 'import'] },
+    fields: {
+        name: f.char({ required: true, translate: true }),
+        sequence: f.integer({ required: true, default: 10 }),
+        fold: f.boolean({ default: false, label: 'Folded on the board' }),
+    },
+});
+export const HelpdeskType = defineModel('helpdesk.type', {
+    label: 'Ticket type',
+    recName: 'name',
+    order: ['name asc'],
+    archivable: true,
+    access: { 'helpdesk.user': READ, 'helpdesk.manager': [...ALL, 'export', 'import'] },
+    fields: { name: f.char({ required: true, translate: true }) },
+});
+export const HelpdeskSla = defineModel('helpdesk.sla', {
+    label: 'SLA policy',
+    recName: 'name',
+    order: ['sequence asc', 'id asc'],
+    archivable: true,
+    companyScoped: { required: true },
+    tracking: ['firstReplyHours', 'resolveHours'],
+    access: { 'helpdesk.user': READ, 'helpdesk.manager': [...ALL, 'export', 'import'] },
+    fields: {
+        name: f.char({ required: true }),
+        sequence: f.integer({
+            required: true,
+            default: 10,
+            help: 'The first policy that matches a ticket applies.',
+        }),
+        team: f.many2one('helpdesk.team', { ondelete: 'cascade', help: 'Empty: every team.' }),
+        priority: f.selection(PRIORITIES, {
+            label: 'From priority',
+            help: 'Tickets of this priority or higher; empty: every priority.',
+        }),
+        partner: f.many2one('res.partner', {
+            ondelete: 'cascade',
+            label: 'Customer',
+            help: 'Empty: every customer.',
+        }),
+        firstReplyHours: f.decimal({
+            scale: 2,
+            required: true,
+            default: '4',
+            label: 'First reply within (hours)',
+        }),
+        resolveHours: f.decimal({
+            scale: 2,
+            required: true,
+            default: '24',
+            label: 'Solved within (hours)',
+        }),
+    },
+    sqlConstraints: {
+        positive: {
+            check: orm.sql `first_reply_hours > 0 AND resolve_hours >= first_reply_hours`,
+            message: 'Targets are positive, the resolution no sooner than the first reply.',
+        },
+    },
+});
+export const HelpdeskCanned = defineModel('helpdesk.canned', {
+    label: 'Canned reply',
+    recName: 'name',
+    order: ['name asc'],
+    archivable: true,
+    access: { 'helpdesk.user': READ, 'helpdesk.manager': [...ALL, 'export', 'import'] },
+    fields: {
+        name: f.char({ required: true, translate: true }),
+        body: f.text({
+            required: true,
+            translate: true,
+            help: 'Placeholders: {{customer}}, {{ticket}}, {{agent}} — filled in when used.',
+        }),
+    },
+});
+const TICKET_STATES = {
+    open: 'Open',
+    waiting: 'Waiting on the customer',
+    solved: 'Solved',
+    closed: 'Closed',
+    merged: 'Merged',
+};
+/** Writes `values` on the tickets as the system: the SLA bookkeeping of a transition. */
+async function stamp(tickets, values) {
+    const { env, ids } = tickets;
+    await env.flush();
+    await env.asSuperuser({ reason: 'helpdesk ticket clock' }, async (su) => {
+        await su
+            .model('helpdesk.ticket')
+            .browse([...ids])
+            .write(values);
+        await su.flush();
+    });
+}
+export const HelpdeskTicket = defineModel('helpdesk.ticket', {
+    label: 'Ticket',
+    recName: 'name',
+    order: ['id desc'],
+    companyScoped: { required: true },
+    tracking: ['state', 'stage', 'assignee', 'priority', 'team'],
+    access: {
+        'helpdesk.user': [...ALL, 'export'],
+        'helpdesk.manager': [...ALL, 'export', 'import'],
+    },
+    rules: {
+        // Agents: the tickets of their teams, and the ones given to them.
+        teams: {
+            groups: ['helpdesk.user'],
+            perms: ['read', 'write', 'create'],
+            domain: {
+                or: [{ 'team.members': { any: { id: me } } }, { assignee: me }, { team: { isNull: true } }],
+            },
+        },
+        all: { groups: ['helpdesk.manager'], perms: [...ALL], domain: {} },
+    },
+    fields: {
+        name: f.char({ required: true, sequence: 'helpdesk.ticket', label: 'Reference' }),
+        subject: f.char({ required: true }),
+        description: f.text(),
+        team: f.many2one('helpdesk.team', { ondelete: 'restrict' }),
+        stage: f.many2one('helpdesk.stage', { ondelete: 'restrict' }),
+        type: f.many2one('helpdesk.type', { ondelete: 'set null' }),
+        partner: f.many2one('res.partner', { ondelete: 'set null', label: 'Customer' }),
+        email: f.char({
+            label: 'Customer email',
+            help: 'Where replies go when the customer is not a contact yet.',
+        }),
+        assignee: f.many2one('res.users', { ondelete: 'set null', label: 'Agent' }),
+        priority: f.selection(PRIORITIES, {
+            required: true,
+            default: 'normal',
+            help: 'Decides the SLA policy: a policy from a priority covers that one and the ones above.',
+        }),
+        sla: f.many2one('helpdesk.sla', { ondelete: 'set null', label: 'SLA policy' }),
+        firstReplyDeadline: f.datetime({ label: 'First reply by' }),
+        resolveDeadline: f.datetime({ label: 'Solved by' }),
+        firstRepliedAt: f.datetime({ label: 'First replied' }),
+        solvedAt: f.datetime({ label: 'Solved' }),
+        waitingSince: f.datetime({ label: 'Waiting since' }),
+        pausedMinutes: f.integer({
+            required: true,
+            default: 0,
+            label: 'Paused (working minutes)',
+            help: 'Time waiting on the customer: added to the resolution target.',
+        }),
+        slaStatus: f.selection({
+            none: 'No SLA',
+            on_track: 'On track',
+            at_risk: 'At risk',
+            breached: 'Breached',
+            met: 'Met',
+        }, {
+            required: true,
+            default: 'none',
+            label: 'SLA',
+            help: 'At risk: less than a fifth of the time left; breached: a target passed; met: solved in time.',
+        }),
+        mergedInto: f.many2one('helpdesk.ticket', { ondelete: 'set null', label: 'Merged into' }),
+        rating: f.integer({ label: 'Rating (1–5)' }),
+        ratingComment: f.text({ label: 'The customer’s comment' }),
+        ratingToken: f.char({
+            size: 64,
+            label: 'Rating link',
+            groups: { read: ['helpdesk.manager'], write: [] },
+        }),
+        state: f.state({
+            states: TICKET_STATES,
+            initial: 'open',
+            help: 'Waiting on the customer pauses the resolution clock; a customer’s reply resumes it.',
+            transitions: {
+                wait: {
+                    from: ['open'],
+                    to: 'waiting',
+                    after: records('helpdesk.ticket', (tickets) => stamp(tickets, { waitingSince: new Date() })),
+                },
+                resume: {
+                    from: ['waiting'],
+                    to: 'open',
+                    after: records('helpdesk.ticket', (tickets) => closePause(tickets)),
+                },
+                solve: {
+                    from: ['open', 'waiting'],
+                    to: 'solved',
+                    after: records('helpdesk.ticket', async (tickets) => {
+                        await closePause(tickets);
+                        await stamp(tickets, { solvedAt: new Date() });
+                        const env = tickets.env;
+                        const { askRating } = await import('./sla.js');
+                        await env.asSuperuser({ reason: 'helpdesk rating' }, (su) => askRating(su, tickets.ids));
+                        for (const id of tickets.ids)
+                            await env.emit('helpdesk.ticket.solved', { id });
+                    }),
+                },
+                reopen: { from: ['solved'], to: 'open' },
+                close: { from: ['solved'], to: 'closed' },
+                merge: { from: ['open', 'waiting'], to: 'merged' },
+            },
+        }),
+    },
+    sqlConstraints: {
+        rating: {
+            check: orm.sql `rating IS NULL OR rating BETWEEN 1 AND 5`,
+            message: 'A rating is from one to five.',
+        },
+    },
+});
+/** Ends a waiting interval: its working minutes added to the pause. */
+async function closePause(tickets) {
+    const { env, ids } = tickets;
+    await env.flush();
+    await env.asSuperuser({ reason: 'helpdesk ticket clock' }, async (su) => {
+        const { pausedSince } = await import('./sla.js');
+        for (const t of await su
+            .model('helpdesk.ticket')
+            .browse([...ids])
+            .load({ team: true })) {
+            if (t.waitingSince === null)
+                continue;
+            const minutes = await pausedSince(su, t, new Date());
+            await su
+                .model('helpdesk.ticket')
+                .browse([t.id])
+                .write({ waitingSince: null, pausedMinutes: t.pausedMinutes + minutes });
+        }
+        await su.flush();
+    });
+}
+export const helpdeskShutro = defineModule({
+    name: 'helpdesk',
+    version: '0.1.0',
+    depends: [contactsShutro, messagingShutro],
+    groups: [
+        orm.defineGroup({
+            code: 'helpdesk.user',
+            label: 'Helpdesk agent',
+            implies: ['contacts.user', 'messaging.user'],
+        }),
+        orm.defineGroup({
+            code: 'helpdesk.manager',
+            label: 'Helpdesk manager',
+            implies: ['helpdesk.user'],
+        }),
+    ],
+    sequences: [
+        orm.defineSequence({
+            code: 'helpdesk.ticket',
+            prefix: 'HD/{year}/',
+            padding: 5,
+            reset: 'yearly',
+        }),
+    ],
+    models: [HelpdeskTeam, HelpdeskStage, HelpdeskType, HelpdeskSla, HelpdeskCanned, HelpdeskTicket],
+    data: [
+        record('helpdesk.stage', 'stage_new', { name: 'New', sequence: 1 }, { noupdate: true }),
+        record('helpdesk.stage', 'stage_progress', { name: 'In progress', sequence: 2 }, { noupdate: true }),
+        record('helpdesk.stage', 'stage_done', { name: 'Done', sequence: 9, fold: true }, { noupdate: true }),
+        record('helpdesk.type', 'type_question', { name: 'Question' }, { noupdate: true }),
+        record('helpdesk.type', 'type_problem', { name: 'Problem' }, { noupdate: true }),
+        record('helpdesk.type', 'type_request', { name: 'Request' }, { noupdate: true }),
+    ],
+});

package/dist/helpdesk/routes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Helpdesk's routes (RFC 0024 §2.4):
+ *
+ * - `POST /api/v1/helpdesk/refresh`                   managers: the SLA, assignment and resumption, now
+ * - `POST /api/v1/helpdesk/tickets/:id/merge`         `{ into }`: the ticket's conversation moved into another, it
+ *                                                     marked merged (agents of both tickets' teams)
+ * - `GET  /api/v1/helpdesk/tickets/:id/canned/:reply` a canned reply filled in for the ticket
+ * - `GET  /api/v1/public/helpdesk/rate?token=&score=` the customer's rating from the emailed link, once (no sign-in,
+ *                                                     rate limited)
+ */
+import { type ModuleContext } from '../server/index.js';
+export declare function registerHelpdeskRoutes(context: ModuleContext): void;

package/dist/helpdesk/routes.js

@@ -0,0 +1,132 @@
+/**
+ * Helpdesk's routes (RFC 0024 §2.4):
+ *
+ * - `POST /api/v1/helpdesk/refresh`                   managers: the SLA, assignment and resumption, now
+ * - `POST /api/v1/helpdesk/tickets/:id/merge`         `{ into }`: the ticket's conversation moved into another, it
+ *                                                     marked merged (agents of both tickets' teams)
+ * - `GET  /api/v1/helpdesk/tickets/:id/canned/:reply` a canned reply filled in for the ticket
+ * - `GET  /api/v1/public/helpdesk/rate?token=&score=` the customer's rating from the emailed link, once (no sign-in,
+ *                                                     rate limited)
+ */
+import { audit, HttpProblem } from '../server/index.js';
+import { rate, refreshSla } from './sla.js';
+const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+export function registerHelpdeskRoutes(context) {
+    const { app } = context;
+    app.post('/api/v1/helpdesk/refresh', async (request) => request.env(async (raw) => {
+        const env = raw;
+        if (!env.administrator && !env.groups.has('helpdesk.manager'))
+            throw new HttpProblem(403, 'access', 'Helpdesk managers', 'This needs the Helpdesk manager role.');
+        return env.asSuperuser({ reason: 'helpdesk refresh' }, async (su) => ({
+            tickets: await refreshSla(su),
+        }));
+    }, { write: true }));
+    app.post('/api/v1/helpdesk/tickets/:id/merge', async (request) => {
+        const id = Number(request.params.id);
+        const into = Number(request.body?.['into']);
+        if (!Number.isSafeInteger(into) || into === id)
+            throw new HttpProblem(422, 'invalid-merge', 'Merge into which ticket?', 'Give another ticket as `into`.');
+        return request.env(async (raw) => {
+            const env = raw;
+            // Both tickets as the agent sees them: their rules decide.
+            const both = await env
+                .model('helpdesk.ticket')
+                .search({ where: { id: { in: [id, into] } } });
+            if (both.length !== 2)
+                throw new HttpProblem(404, 'missing-record', 'Not found', 'Both tickets must be yours to see.');
+            return env.asSuperuser({ reason: 'helpdesk merge' }, async (su) => {
+                const [source] = await su
+                    .model('helpdesk.ticket')
+                    .browse([id])
+                    .load(['name', 'state']);
+                const [target] = await su
+                    .model('helpdesk.ticket')
+                    .browse([into])
+                    .load(['name', 'state']);
+                if (source === undefined ||
+                    target === undefined ||
+                    !['open', 'waiting'].includes(source.state))
+                    throw new HttpProblem(409, 'not-open', 'Not open', 'Only an open ticket is merged.');
+                if (target.state === 'merged')
+                    throw new HttpProblem(409, 'merged', 'Already merged', 'Merge into a ticket that is not merged itself.');
+                const messages = await su
+                    .model('mail.message')
+                    .search({ where: { resModel: 'helpdesk.ticket', resId: id } });
+                if (messages.length > 0)
+                    await messages.write({ resId: into });
+                await su
+                    .model('helpdesk.ticket')
+                    .browse([id])
+                    .write({ mergedInto: into });
+                await su.flush();
+                await su
+                    .model('helpdesk.ticket')
+                    .browse([id])
+                    .merge();
+                await audit(env, {
+                    kind: 'helpdesk.merged',
+                    summary: `${source.name} merged into ${target.name}.`,
+                    targetModel: 'helpdesk.ticket',
+                    targetId: into,
+                    ip: request.ip,
+                });
+                await su.flush();
+                return { id, into, moved: messages.length };
+            });
+        }, { write: true });
+    });
+    app.get('/api/v1/helpdesk/tickets/:id/canned/:reply', async (request) => {
+        const { id, reply } = request.params;
+        return request.env(async (raw) => {
+            const env = raw;
+            const [ticket] = await (await env.model('helpdesk.ticket').search({ where: { id: Number(id) }, limit: 1 })).load({ partner: true, assignee: true });
+            const [canned] = await (await env
+                .model('helpdesk.canned')
+                .search({ where: { id: Number(reply) }, limit: 1 })).load(['body']);
+            if (ticket === undefined || canned === undefined)
+                throw new HttpProblem(404, 'missing-record', 'Not found', 'No such ticket or canned reply.');
+            const fill = {
+                customer: ticket.partner?.name ?? ticket.email ?? '',
+                ticket: ticket.name,
+                agent: ticket.assignee?.name ?? '',
+            };
+            return {
+                text: canned.body.replace(/\{\{\s*(customer|ticket|agent)\s*\}\}/g, (_, k) => fill[k] ?? ''),
+            };
+        });
+    });
+    app.get('/api/v1/public/helpdesk/rate', { config: { auth: false } }, async (request, reply) => {
+        const q = request.query;
+        const token = typeof q.token === 'string' ? q.token : '';
+        const score = Number(q.score);
+        const comment = typeof q.comment === 'string' && q.comment.trim() !== '' ? q.comment.slice(0, 2000) : null;
+        const name = token.length < 20
+            ? null
+            : await context.shutro.bootstrap({ reason: 'helpdesk rating' }, (env) => 
+            // The token names the ticket, whatever its company.
+            env.asSuperuser({ reason: 'helpdesk rating' }, (su) => rate(su.withFlags({ checkCompany: false }), token, score, comment)));
+        const text = name === null
+            ? 'This link was used already, or is not valid.'
+            : `Thank you — your rating of ${'★'.repeat(score)} for ${name} is recorded.`;
+        return reply
+            .code(name === null ? 404 : 200)
+            .header('content-type', 'text/html; charset=utf-8')
+            .send(`<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Rating</title><p style="font:16px system-ui;margin:3em auto;max-width:30em;text-align:center">${escapeHtml(text)}</p>`);
+    });
+    // The clock, every five minutes, company by company (off in the CLI and in tests).
+    if (process.env['KOSH_SCHEDULES'] === 'off')
+        return;
+    const run = async () => {
+        try {
+            const companies = await context.shutro.bootstrap({ reason: 'helpdesk clock' }, async (env) => (await env.model('res.company').search({})).ids);
+            for (const company of companies)
+                await context.shutro.bootstrap({ reason: 'helpdesk clock', company }, (env) => env.asSuperuser({ reason: 'helpdesk clock' }, (su) => refreshSla(su)));
+        }
+        catch (error) {
+            app.log.error({ err: error }, 'helpdesk clock');
+        }
+    };
+    const timer = setInterval(() => void run(), 5 * 60_000);
+    timer.unref();
+    app.addHook('onClose', async () => clearInterval(timer));
+}

package/dist/helpdesk/sla.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The Helpdesk clock (RFC 0024 §2.4), refreshed every few minutes on the server and on request:
+ *
+ * - each open ticket gets its **SLA policy** (the first, by sequence, of its team or every team, from its priority,
+ *   for its customer or every customer) and its **deadlines** in the team's business hours — the first reply from
+ *   the ticket's opening, the resolution pushed back by the time spent waiting on the customer;
+ * - the **first reply** is the first message (not a note) an agent posted on it;
+ * - a ticket waiting on the customer **resumes** when the customer writes back (a message by email);
+ * - unassigned tickets of teams that assign get their **agent**: in turn, or the one with the fewest open tickets;
+ * - the **status**: met (solved in time), breached (a target passed), at risk (less than a fifth left), on track.
+ *
+ * A solved ticket asks its customer for a **rating** through a link (`/api/v1/public/helpdesk/rate`).
+ */
+import { orm } from '../server/orm.js';
+import type { Env } from './.kosh/bindings.js';
+import { type Hours } from './hours.js';
+/** The installation's time zone for business hours (App settings › Helpdesk). */
+export declare function timeZoneOf(env: Env): Promise<string>;
+interface TeamHours {
+    readonly open: string;
+    readonly close: string;
+    readonly weekend: string;
+}
+/** A team's business hours; without a team, every day from 09:00 to 18:00. */
+export declare function hoursOf(env: Env, team: TeamHours | null): Promise<Hours>;
+/** The working minutes a ticket has been waiting on the customer, up to `now`. */
+export declare function pausedSince(env: Env, ticket: {
+    readonly waitingSince: Date | null;
+    readonly team: TeamHours | null;
+}, now: Date): Promise<number>;
+/** Refreshes the tickets given (every open, waiting and just-solved ticket when none). */
+export declare function refreshSla(env: Env, ids?: readonly number[], now?: Date): Promise<number>;
+/** Solved tickets of teams that ask: a rating link for the customer, sent by email when a mailer is set. */
+export declare function askRating(env: Env, ids: readonly number[]): Promise<void>;
+/** A rating from the link, once. @returns the ticket's reference, or `null` for an unknown or used link */
+export declare function rate(env: Env, token: string, score: number, comment: string | null): Promise<string | null>;
+export { orm };