shutro-erp 0.3.6 → 0.3.7

package/dist/approvals/index.js

@@ -10,17 +10,25 @@
  * - `GET  /api/v1/public/approvals/:token`   the confirmation page of an email link
  * - `POST /api/v1/public/approvals/:token`   `{ decision: approve | reject | send_back, comment? }`, once
  * - `POST /api/v1/approvals/deadlines/run`   reminders and escalations now (Approvals managers; hourly too)
+ * - `POST /api/v1/approvals/categories/:id/policy`  a request category's policy, made when missing (Approvals managers)
+ * - `GET  /api/v1/approvals/policies/:id/preview`    which of the last 50 records each level would have asked about
+ *
+ * **Generic requests** (step 4): categories say what a request asks for and what it leads to; a request is decided
+ * through its category's policy, and its outcome runs when approved.
  */
 import { randomBytes } from 'node:crypto';
+import { contacts } from '../contacts/index.js';
 import { mailerFromEnv } from '../mail/index.js';
 import { defineModule } from '../modules-sdk/index.js';
-import { decide, groupsOf, linkOf, permissions, sweepDeadlines, useLink, } from '../permissions/index.js';
+import { APPROVER_KEYS, decide, groupsOf, linkOf, permissions, previewPolicy, sweepDeadlines, syncLevels, turnOf, useLink, } from '../permissions/index.js';
+import { reporting } from '../reporting/index.js';
 import { digest, HttpProblem } from '../server/index.js';
-import { form, list, search } from '../views/index.js';
+import { action, form, kanban, list, search } from '../views/index.js';
+import { approvalsDemo } from './demo.js';
 import { configureMails, mailDeciders, mailTurn } from './mails.js';
-import { approvalsShutro } from './module.js';
+import { ApprovalAsk, ApprovalCategory, approvalsShutro, ensureCategoryPolicy } from './module.js';
 export { mailDeciders, mailTurn } from './mails.js';
-export { approvalsShutro } from './module.js';
+export { ApprovalAsk, ApprovalAskLine, ApprovalCategory, approvalsShutro, ensureCategoryPolicy, missingFields, outcomesOffered, } from './module.js';
 const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
 const DECISIONS = new Set(['approve', 'reject', 'send_back']);
 /** The subscribers that email a record's approvers when its approvals are asked and when a level is approved. */
@@ -35,11 +43,52 @@ export function approvalMailWorkers(context) {
             return;
         await env.asSuperuser({ reason: 'approval emails' }, (su) => mailTurn(su, model, id));
     }, { pollMs: 5000 });
+    // The people added to a waiting request (reassigned) and a request's backups (told): their own links.
+    const only = (name, topic, why) => context.shutro.subscribe(name, topic, async (event, env) => {
+        const p = (event.payload ?? {});
+        const id = Number(p['request']);
+        const users = Array.isArray(p['users']) ? p['users'] : [];
+        if (!Number.isSafeInteger(id) || users.length === 0)
+            return;
+        await env.asSuperuser({ reason: 'approval emails' }, async (su) => {
+            const [request] = (await turnOfRequest(su, id)) ?? [];
+            if (request !== undefined)
+                await mailDeciders(su, [request], why, users);
+        });
+    }, { pollMs: 5000 });
+    // Waiting requests follow their level's approvers (RFC 0027 §2.6): Shutro's change events of approval levels.
+    const sync = context.shutro.subscribe('approvals.sync', 'record.changed', async (event, env) => {
+        const p = (event.payload ?? {});
+        if (p['model'] !== 'approval.level' || p['action'] !== 'write')
+            return;
+        const keys = Array.isArray(p['keys']) ? p['keys'] : [];
+        if (!keys.some((k) => APPROVER_KEYS.includes(k)))
+            return;
+        const ids = (Array.isArray(p['ids']) ? p['ids'] : []).filter((i) => Number.isSafeInteger(i));
+        await env.asSuperuser({ reason: 'approval sync' }, async (su) => {
+            for (const done of await syncLevels(su, ids))
+                if (done.notify && done.added.length > 0)
+                    await mailDeciders(su, [done.request], 'added', done.added);
+        });
+    }, { pollMs: 5000 });
     return [
         turn('approvals.asked', 'approval.requested'),
         turn('approvals.next', 'approval.decided'),
+        only('approvals.reassigned', 'approval.reassigned', 'added'),
+        only('approvals.backups', 'approval.backups', 'backup'),
+        sync,
     ];
 }
+/** One request by id, while it waits (for the emails). */
+async function turnOfRequest(su, id) {
+    const found = await su.model('approval.request').search({ where: { id, state: 'pending' }, limit: 1 });
+    if (found.length === 0)
+        return undefined;
+    const [row] = (await found.load(['targetModel', 'targetId'])).read(['targetModel', 'targetId']);
+    if (row === undefined)
+        return undefined;
+    return (await turnOf(su, String(row['targetModel']), Number(row['targetId']))).filter((r) => r.id === id);
+}
 /** Reminders and escalations, then their emails (as the system). */
 async function runDeadlines(su) {
     const done = await sweepDeadlines(su);
@@ -51,6 +100,61 @@ async function runDeadlines(su) {
 }
 function registerApprovalAppRoutes(context) {
     const { app, shutro } = context;
+    const managersOnly = (env) => {
+        if (!env.administrator && !env.groups.has('approvals.manager'))
+            throw new HttpProblem(403, 'access', 'Approvals managers', 'This needs the Approvals manager role.');
+    };
+    const idParam = (params) => {
+        const id = Number(params['id']);
+        if (!Number.isSafeInteger(id) || id <= 0)
+            throw new HttpProblem(404, 'missing-record', 'Not found', 'No such record.');
+        return id;
+    };
+    app.post('/api/v1/approvals/categories/:id/policy', async (request) => {
+        const id = idParam(request.params);
+        return request.env(async (raw) => {
+            const env = raw;
+            managersOnly(env);
+            return env.asSuperuser({ reason: 'request category policy' }, async (su) => ({
+                policy: await ensureCategoryPolicy(su, id),
+            }));
+        }, { write: true });
+    });
+    app.get('/api/v1/approvals/policies/:id/preview', async (request) => {
+        const id = idParam(request.params);
+        return request.env(async (raw) => {
+            const env = raw;
+            managersOnly(env);
+            return env.asSuperuser({ reason: 'approval policy preview' }, (su) => previewPolicy(su, id));
+        }, { write: true });
+    });
+    // `POST /api/v1/approvals/policies/:id/sync` `{ mode? }`: "Sync now" — the policy's waiting requests get their
+    // approvers found again (RFC 0027 §2.6), adding unless the body or the policy says replace.
+    app.post('/api/v1/approvals/policies/:id/sync', async (request) => {
+        const id = idParam(request.params);
+        const mode = request.body?.mode;
+        if (mode !== undefined && mode !== 'add' && mode !== 'replace')
+            throw new HttpProblem(400, 'invalid-body', 'Invalid body', "mode is 'add' or 'replace'.");
+        return request.env(async (raw) => {
+            const env = raw;
+            managersOnly(env);
+            return env.asSuperuser({ reason: 'approval sync' }, async (su) => {
+                const levels = await (await su.model('approval.level').search({ where: { policy: id } })).ids;
+                const [policy] = await (await su.model('approval.policy').search({ where: { id }, limit: 1 }))
+                    .load(['syncPending'])
+                    .then((r) => r.read(['syncPending']));
+                if (policy === undefined)
+                    throw new HttpProblem(404, 'missing-record', 'Not found', 'No such policy.');
+                const how = mode ??
+                    (policy['syncPending'] === 'replace' ? 'replace' : 'add');
+                const done = await syncLevels(su, levels, how);
+                for (const d of done)
+                    if (d.notify && d.added.length > 0)
+                        await mailDeciders(su, [d.request], 'added', d.added);
+                return { synced: done.length };
+            });
+        });
+    });
     const tokenOf = (params) => String(params['token'] ?? '');
     const linkFor = (token) => shutro.bootstrap({ reason: 'approval link' }, (raw) => raw.asSuperuser({ reason: 'approval link' }, async (su) => {
         const link = await linkOf(su.withFlags({ checkCompany: false }), digest(token));
@@ -154,7 +258,8 @@ export function approvalsModule(options = {}) {
     return defineModule({
         shutro: approvalsShutro,
         kosh: '^0.1.0',
-        depends: [permissions],
+        hooks: { demo: approvalsDemo },
+        depends: [permissions, contacts, reporting],
         app: {
             code: 'approvals',
             label: 'Approvals',
@@ -163,6 +268,92 @@ export function approvalsModule(options = {}) {
             category: 'Productivity',
             summary: 'Everything waiting for your decision, in one place — and what you asked for',
         },
+        importTemplates: [
+            {
+                key: 'approval_ask',
+                model: 'approval.ask',
+                label: 'Request',
+                columns: [
+                    { header: 'Category', field: 'category' },
+                    { header: 'What for', field: 'title' },
+                    { header: 'Asked by', field: 'requester' },
+                    { header: 'Description', field: 'description' },
+                    { header: 'Amount', field: 'amount' },
+                    { header: 'From', field: 'dateFrom' },
+                    { header: 'Until', field: 'dateTo' },
+                    { header: 'Contact', field: 'partner' },
+                    { header: 'Location', field: 'location' },
+                    { header: 'Quantity', field: 'quantity' },
+                    { header: 'Lines › Description', field: 'lines.name' },
+                    { header: 'Lines › Quantity', field: 'lines.quantity' },
+                    { header: 'Lines › Unit price', field: 'lines.priceUnit' },
+                ],
+            },
+        ],
+        events: [{ topic: 'approval.ask.approved', model: 'approval.ask', label: 'Request approved' }],
+        // Bangla for the labels it serves (RFC 0023 §3.1; `pnpm i18n:extract`).
+        i18n: { bn: () => import('./i18n/bn.js') },
+        overview: {
+            cards: [
+                {
+                    id: 'waiting',
+                    title: 'Requests waiting',
+                    kind: 'kpi',
+                    model: 'approval.ask',
+                    measure: 'count',
+                    filter: { state: 'submitted' },
+                    w: 3,
+                },
+                {
+                    id: 'approved',
+                    title: 'Approved this month',
+                    kind: 'kpi',
+                    model: 'approval.ask',
+                    measure: 'count',
+                    filter: { state: 'approved' },
+                    comparison: { field: 'approvedAt', mode: 'previous' },
+                    w: 3,
+                },
+                {
+                    id: 'refused',
+                    title: 'Refused',
+                    kind: 'kpi',
+                    model: 'approval.ask',
+                    measure: 'count',
+                    filter: { state: 'refused' },
+                    w: 3,
+                },
+                {
+                    id: 'amount',
+                    title: 'Amount waiting',
+                    kind: 'kpi',
+                    model: 'approval.ask',
+                    measure: 'sum:amount',
+                    filter: { state: 'submitted' },
+                    w: 3,
+                },
+                {
+                    id: 'by_category',
+                    title: 'Requests by category',
+                    kind: 'chart',
+                    model: 'approval.ask',
+                    measure: 'count',
+                    groupBy: 'category',
+                    chart: 'bar',
+                    w: 6,
+                },
+                {
+                    id: 'by_state',
+                    title: 'Requests by state',
+                    kind: 'chart',
+                    model: 'approval.ask',
+                    measure: 'count',
+                    groupBy: 'state',
+                    chart: 'pie',
+                    w: 6,
+                },
+            ],
+        },
         accessLevels: {
             user: { label: 'Everyone (decide and ask)', groups: ['base.user'] },
             manager: {
@@ -175,6 +366,58 @@ export function approvalsModule(options = {}) {
             configureMails({ log: (message, error) => context.app.log.warn({ err: error }, message) });
             registerApprovalAppRoutes(context);
         },
+        documents: [
+            {
+                key: 'approval_request',
+                name: 'Request',
+                model: 'approval.ask',
+                layout: {
+                    paper: 'A4',
+                    header: '{{company.name}}',
+                    footer: 'Page {{page}} of {{pages}}',
+                    blocks: [
+                        { kind: 'heading', id: 'title', text: 'Request {{name}}: {{title}}', level: 1 },
+                        {
+                            kind: 'fields',
+                            id: 'ask',
+                            items: [
+                                { label: 'Category', bind: 'category.name' },
+                                { label: 'Asked by', bind: 'requester.name' },
+                                { label: 'Amount', bind: 'amount' },
+                                { label: 'From', bind: 'dateFrom' },
+                                { label: 'Until', bind: 'dateTo' },
+                                { label: 'Contact', bind: 'partner.name' },
+                                { label: 'Location', bind: 'location' },
+                                { label: 'Quantity', bind: 'quantity' },
+                                { label: 'Status', bind: 'state' },
+                                { label: 'Approved on', bind: 'approvedAt' },
+                            ],
+                        },
+                        { kind: 'text', id: 'about', text: '{{description}}' },
+                        {
+                            kind: 'table',
+                            id: 'lines',
+                            bind: 'lines',
+                            columns: [
+                                { label: 'Description', bind: 'name' },
+                                { label: 'Quantity', bind: 'quantity' },
+                                { label: 'Unit price', bind: 'priceUnit' },
+                                { label: 'Amount', bind: 'subtotal' },
+                            ],
+                        },
+                        {
+                            kind: 'fields',
+                            id: 'total',
+                            items: [
+                                { label: 'Lines total', bind: 'linesTotal' },
+                                { label: 'Made', bind: 'resultName' },
+                            ],
+                        },
+                        { kind: 'signature', id: 'sign', labels: ['Asked by', 'Approved by'] },
+                    ],
+                },
+            },
+        ],
         actions: {
             'approvals.action_inbox': { type: 'client', page: 'approvals.Inbox', label: 'To approve' },
             'approvals.action_mine': { type: 'client', page: 'approvals.Mine', label: 'My requests' },
@@ -183,17 +426,32 @@ export function approvalsModule(options = {}) {
                 page: 'approvals.History',
                 label: 'What I decided',
             },
+            'approvals.action_matrix': { type: 'client', page: 'approvals.Matrix', label: 'Matrix' },
             'approvals.action_away': {
                 model: 'approval.delegation',
                 label: 'Away',
                 views: ['list', 'form'],
             },
+            'approvals.action_asks': action(ApprovalAsk, {
+                label: 'Requests',
+                views: ['list', 'kanban', 'form'],
+            }),
+            'approvals.action_categories': action(ApprovalCategory, {
+                label: 'Request categories',
+                views: ['kanban', 'list', 'form'],
+            }),
             'approvals.action_policies': {
                 model: 'approval.policy',
                 label: 'Policies',
                 views: ['list', 'form'],
                 visibleTo: ['approvals.manager'],
             },
+            'approvals.action_segments': {
+                model: 'res.segment',
+                label: 'Segments',
+                views: ['list', 'form'],
+                visibleTo: ['approvals.manager'],
+            },
         },
         menus: [
             { id: 'approvals.root', label: 'Approvals', app: 'approvals' },
@@ -218,6 +476,20 @@ export function approvalsModule(options = {}) {
                 action: 'approvals.action_history',
                 sequence: 3,
             },
+            {
+                id: 'approvals.matrix',
+                parent: 'approvals.root',
+                label: 'Matrix',
+                action: 'approvals.action_matrix',
+                sequence: 3.5,
+            },
+            {
+                id: 'approvals.asks',
+                parent: 'approvals.root',
+                label: 'Requests',
+                action: 'approvals.action_asks',
+                sequence: 2.5,
+            },
             {
                 id: 'approvals.away',
                 parent: 'approvals.root',
@@ -232,6 +504,14 @@ export function approvalsModule(options = {}) {
                 sequence: 9,
                 visibleTo: ['approvals.manager'],
             },
+            {
+                id: 'approvals.categories',
+                parent: 'approvals.configuration',
+                label: 'Request categories',
+                action: 'approvals.action_categories',
+                sequence: 0.5,
+                visibleTo: ['approvals.manager'],
+            },
             {
                 id: 'approvals.policies',
                 parent: 'approvals.configuration',
@@ -240,8 +520,31 @@ export function approvalsModule(options = {}) {
                 sequence: 1,
                 visibleTo: ['approvals.manager'],
             },
+            {
+                id: 'approvals.segments',
+                parent: 'approvals.configuration',
+                label: 'Segments',
+                action: 'approvals.action_segments',
+                sequence: 2,
+                visibleTo: ['approvals.manager'],
+            },
         ],
         views: {
+            'res.segment.list': list('res.segment', {
+                columns: ['name', 'code', 'companies', 'active'],
+            }),
+            'res.segment.form': form('res.segment', (k) => ({
+                sheet: [
+                    k.group('main', ['name', 'code'], {
+                        description: 'A group of companies (Feed, Poultry, Dairy): an approval policy of the segment covers every company in it.',
+                    }),
+                    k.group('members', [{ field: 'companies', id: 'segment_companies', widget: 'tags' }], {
+                        label: 'Companies',
+                        description: 'A company is in one segment at most.',
+                    }),
+                    k.group('notes', ['note'], { label: 'Note' }),
+                ],
+            })),
             'approval.delegation.list': list('approval.delegation', {
                 columns: ['user', 'delegate', 'dateFrom', 'dateTo', 'note'],
             }),
@@ -252,11 +555,137 @@ export function approvalsModule(options = {}) {
                     }),
                 ],
             })),
+            'approval.ask.list': list(ApprovalAsk, {
+                columns: [
+                    'name',
+                    'category',
+                    'title',
+                    'requester',
+                    { field: 'amount', sum: true },
+                    'dateFrom',
+                    { field: 'state', widget: 'badge' },
+                ],
+                decorations: {
+                    warning: { state: 'submitted' },
+                    success: { state: 'approved' },
+                    danger: { state: 'refused' },
+                },
+            }),
+            'approval.ask.kanban': kanban(ApprovalAsk, {
+                groupBy: 'state',
+                card: {
+                    title: 'title',
+                    subtitle: 'category',
+                    avatar: 'requester',
+                    footer: ['amount', 'name'],
+                },
+            }),
+            'approval.ask.form': form(ApprovalAsk, (k) => ({
+                header: {
+                    statusbar: 'state',
+                    buttons: [
+                        k.button('submit', { primary: true, label: 'Submit for approval' }),
+                        k.button('redraft', { label: 'Set to draft' }),
+                        k.button('cancel', { label: 'Cancel' }),
+                    ],
+                },
+                sheet: [
+                    k.group('main', ['category', 'title', 'name', 'requester']),
+                    k.component('approvals', 'approvals.Panel'),
+                    k.group('details', [
+                        {
+                            field: 'amount',
+                            id: 'ask_amount',
+                            visibleWhen: { askAmount: { ne: 'none' } },
+                            requiredWhen: { askAmount: 'required' },
+                        },
+                        {
+                            field: 'dateFrom',
+                            id: 'ask_dateFrom',
+                            visibleWhen: { askPeriod: { ne: 'none' } },
+                            requiredWhen: { askPeriod: 'required' },
+                        },
+                        {
+                            field: 'dateTo',
+                            id: 'ask_dateTo',
+                            visibleWhen: { askPeriod: { ne: 'none' } },
+                            requiredWhen: { askPeriod: 'required' },
+                        },
+                        {
+                            field: 'partner',
+                            id: 'ask_partner',
+                            visibleWhen: { askPartner: { ne: 'none' } },
+                            requiredWhen: { askPartner: 'required' },
+                        },
+                        {
+                            field: 'location',
+                            id: 'ask_location',
+                            visibleWhen: { askLocation: { ne: 'none' } },
+                            requiredWhen: { askLocation: 'required' },
+                        },
+                        {
+                            field: 'quantity',
+                            id: 'ask_quantity',
+                            visibleWhen: { askQuantity: { ne: 'none' } },
+                            requiredWhen: { askQuantity: 'required' },
+                        },
+                    ], {
+                        label: 'Details',
+                        description: 'What the category asks for; required ones are marked. A file, when asked for, goes in the chatter.',
+                    }),
+                    k.group('about', ['description'], { columns: 1 }),
+                    {
+                        ...k.lines('lines', [
+                            { field: 'name', id: 'line_name' },
+                            { field: 'quantity', id: 'line_quantity' },
+                            { field: 'priceUnit', id: 'line_price' },
+                            { field: 'subtotal', id: 'line_subtotal', sum: true },
+                        ]),
+                        visibleWhen: { askLines: { ne: 'none' } },
+                    },
+                    k.group('result', ['approvedAt', 'resultName'], {
+                        label: 'Outcome',
+                        visibleWhen: { state: 'approved' },
+                    }),
+                ],
+                chatter: true,
+            })),
+            'approval.category.kanban': kanban(ApprovalCategory, {
+                groupBy: 'outcome',
+                card: { title: 'name', subtitle: 'description', footer: ['requestCount', 'code'] },
+            }),
+            'approval.category.list': list(ApprovalCategory, {
+                columns: ['sequence', 'code', 'name', 'outcome', 'policy', 'requestCount'],
+            }),
+            'approval.category.form': form(ApprovalCategory, (k) => ({
+                sheet: [
+                    k.group('main', ['name', 'code', 'sequence', 'company']),
+                    k.group('about', ['description'], { columns: 1 }),
+                    k.group('fields', [
+                        'askAmount',
+                        'askPeriod',
+                        'askPartner',
+                        'askLocation',
+                        'askQuantity',
+                        'askLines',
+                        'askAttachment',
+                    ], {
+                        label: 'What a request asks for',
+                        description: 'Not asked, optional or required; submitting checks the required ones.',
+                    }),
+                    k.group('decision', ['policy', 'outcome'], {
+                        label: 'Who decides and what follows',
+                        description: 'The policy’s levels decide (made with the first request: the requester’s manager, else an Approvals manager); edit them on the policy. The outcome runs once approved.',
+                    }),
+                    k.component('category_policy', 'approvals.CategoryPolicy'),
+                ],
+            })),
             'approval.policy.list': list('approval.policy', {
                 columns: [
                     'name',
                     'targetModel',
                     'company',
+                    'segment',
                     'onApproved',
                     'reasonRequired',
                     'active',
@@ -264,10 +693,29 @@ export function approvalsModule(options = {}) {
             }),
             'approval.policy.form': form('approval.policy', (k) => ({
                 sheet: [
-                    k.group('main', ['name', 'targetModel', 'company', 'sequence'], {
+                    k.component('preview', 'approvals.PolicyPreview'),
+                    k.group('main', ['name', 'targetModel', 'sequence', 'condition'], {
                         description: 'A record of the model gets one approval per level whose condition it meets; levels with a lower sequence are decided first, those with the same side by side.',
                     }),
-                    k.group('outcomes', ['onApproved', 'onRejected', 'onSentBack', 'onWithdrawn', 'reasonRequired'], {
+                    k.group('scope', [
+                        'company',
+                        { field: 'companies', id: 'policy_companies', widget: 'tags' },
+                        'segment',
+                    ], {
+                        label: 'Companies',
+                        description: 'The policy covers this company, these companies and every company of the segment together; leave all three empty for every company.',
+                    }),
+                    k.group('outcomes', [
+                        'onApproved',
+                        'onRejected',
+                        'onSentBack',
+                        'onWithdrawn',
+                        'reasonRequired',
+                        'whenNobody',
+                        'skipDuplicates',
+                        'syncPending',
+                        'notifyOnSync',
+                    ], {
                         label: 'What happens',
                         description: 'The transitions of the record run when it is approved, rejected, sent back or withdrawn.',
                     }),
@@ -278,6 +726,8 @@ export function approvalsModule(options = {}) {
                         { field: 'approverRole', id: 'level_role' },
                         { field: 'approverUsers', id: 'level_users', widget: 'tags' },
                         { field: 'approverField', id: 'level_field' },
+                        { field: 'extraUsers', id: 'level_extra', widget: 'tags' },
+                        { field: 'backupUsers', id: 'level_backups', widget: 'tags' },
                         { field: 'quorum', id: 'level_quorum' },
                         { field: 'quorumCount', id: 'level_count' },
                         { field: 'deadlineHours', id: 'level_deadline' },
@@ -287,10 +737,30 @@ export function approvalsModule(options = {}) {
             })),
         },
         search: {
+            'res.segment': search('res.segment', {
+                fields: ['name', 'code'],
+            }),
             'approval.delegation': search('approval.delegation', {
                 fields: ['user.name', 'delegate.name'],
                 groupBy: ['user', 'delegate'],
             }),
+            'approval.ask': search(ApprovalAsk, {
+                fields: ['title', 'name', 'requester.name'],
+                filters: {
+                    mine: { label: 'Mine', domain: { requester: { $env: 'uid' } } },
+                    waiting: {
+                        label: 'Waiting for approval',
+                        domain: { state: 'submitted' },
+                        group: 'state',
+                    },
+                    approved: { label: 'Approved', domain: { state: 'approved' }, group: 'state' },
+                },
+                groupBy: ['category', 'state', 'requester'],
+            }),
+            'approval.category': search(ApprovalCategory, {
+                fields: ['name', 'code'],
+                groupBy: ['outcome'],
+            }),
             'approval.policy': search('approval.policy', {
                 fields: ['name', 'targetModel'],
                 groupBy: ['targetModel'],

package/dist/approvals/mails.d.ts

@@ -17,9 +17,14 @@ declare const WHY: {
     readonly asked: (who: string, record: string) => string;
     readonly reminded: (_who: string, record: string) => string;
     readonly escalated: (_who: string, record: string) => string;
+    readonly added: (who: string, record: string) => string;
+    readonly backup: (_who: string, record: string) => string;
 };
-/** Emails each person who may decide `requests` now a link of their own; skips those already sent one. */
-export declare function mailDeciders(su: Env, requests: readonly ApprovalRequestInfo[], why: keyof typeof WHY): Promise<number>;
+/**
+ * Emails each person who may decide `requests` now a link of their own (only `only`, when given: the people added
+ * to a request, its backups); for a new turn, skips requests already sent links.
+ */
+export declare function mailDeciders(su: Env, requests: readonly ApprovalRequestInfo[], why: keyof typeof WHY, only?: readonly number[]): Promise<number>;
 /** After a record's approvals were asked, or one of its levels approved: the requests whose turn it is now. */
 export declare function mailTurn(su: Env, model: string, id: number): Promise<number>;
 export {};

package/dist/approvals/mails.js

@@ -21,9 +21,14 @@ const WHY = {
     asked: (who, record) => `${who} asks you to approve ${record}`,
     reminded: (_who, record) => `Reminder: ${record} waits for your approval`,
     escalated: (_who, record) => `${record} is late: you may decide it now`,
+    added: (who, record) => `${who} waits for your approval of ${record}`,
+    backup: (_who, record) => `As a backup approver: ${record} waits for a decision`,
 };
-/** Emails each person who may decide `requests` now a link of their own; skips those already sent one. */
-export async function mailDeciders(su, requests, why) {
+/**
+ * Emails each person who may decide `requests` now a link of their own (only `only`, when given: the people added
+ * to a request, its backups); for a new turn, skips requests already sent links.
+ */
+export async function mailDeciders(su, requests, why, only) {
     const mailer = config.mailer;
     let sent = 0;
     for (const request of requests) {
@@ -35,7 +40,7 @@ export async function mailDeciders(su, requests, why) {
             if (existing.length > 0)
                 continue;
         }
-        const links = await issueLinks(su, request, su.today(), () => randomToken(24), digest);
+        const links = await issueLinks(su, request, su.today(), () => randomToken(24), digest, only);
         if (links.length === 0)
             continue;
         const [record] = await read(await ref(su, request.targetModel)