shutro-erp 0.2.0 → 0.3.0

package/dist/portal/module.js

@@ -0,0 +1,84 @@
+/**
+ * The data layer of the portal (RFC 0015 §5.1–5.2): portal users are `res.users` holding only `portal.user` (never
+ * `base.user`), each linked to one partner; invitations are one-time activation tokens, kept as SHA-256 digests.
+ */
+import { contactsShutro } from '../contacts/index.js';
+import { baseShutro } from '../server/index.js';
+import { orm } from '../server/orm.js';
+import { defineModel, defineModule, extendModel, f } from './.kosh/bindings.js';
+/** The partner a portal user acts for. Internal users have none. */
+export const UserPortalPartner = extendModel('res.users', {
+    fields: {
+        portalPartner: f.many2one('res.partner', { ondelete: 'set null', label: 'Portal contact' }),
+    },
+});
+/** The portal users of a contact (one, in practice): who the invitations went to. */
+export const PartnerPortalUsers = extendModel('res.partner', {
+    fields: {
+        portalUsers: f.one2many('res.users', 'portalPartner', { label: 'Portal users' }),
+    },
+});
+/** A one-time link that lets an invited contact choose a password. Private: read through the portal routes. */
+export const PortalInvitation = defineModel('portal.invitation', {
+    label: 'Portal invitation',
+    order: ['id desc'],
+    access: {},
+    fields: {
+        user: f.many2one('res.users', { required: true, ondelete: 'cascade' }),
+        tokenHash: f.char({ required: true, index: 'unique' }),
+        expiresAt: f.datetime({ required: true }),
+        usedAt: f.datetime(),
+        invitedBy: f.many2one('res.users', { ondelete: 'set null' }),
+    },
+});
+/**
+ * A signature given in the portal (RFC 0015 §5.3): who signed which document, under which name, the drawn image,
+ * when, from where, and the hash of what they saw. Private: written by the portal routes, read by staff.
+ */
+export const PortalSignature = defineModel('portal.signature', {
+    label: 'Portal signature',
+    order: ['id desc'],
+    companyScoped: { required: true },
+    access: { 'base.user': ['read'] },
+    fields: {
+        resModel: f.char({ required: true, label: 'Model' }),
+        resId: f.integer({ required: true, label: 'Record' }),
+        action: f.char({ required: true, size: 40 }),
+        user: f.many2one('res.users', { required: true, ondelete: 'restrict' }),
+        signedName: f.char({ required: true, size: 200, label: 'Name' }),
+        image: f.binary({ label: 'Signature' }),
+        /** SHA-256 of the declared fields and lines the user saw. */
+        documentHash: f.char({ required: true, size: 64 }),
+        ip: f.char({ size: 64 }),
+    },
+});
+/** A document announced to its customer by email (RFC 0015 §5.7): once per record and document type. */
+export const PortalAnnouncement = defineModel('portal.announcement', {
+    label: 'Portal announcement',
+    access: {},
+    fields: {
+        resModel: f.char({ required: true, label: 'Model' }),
+        resId: f.integer({ required: true, label: 'Record' }),
+        document: f.char({ required: true, size: 64 }),
+        recipients: f.integer({ required: true, default: 0 }),
+    },
+    sqlConstraints: {
+        once: { unique: ['resModel', 'resId', 'document'], message: 'A document is announced once.' },
+    },
+});
+export const portalShutro = defineModule({
+    name: 'portal',
+    version: '0.1.0',
+    depends: [baseShutro, contactsShutro],
+    groups: [
+        // Never implies base.user: holders are outside the company (the server keeps them to the portal).
+        orm.defineGroup({ code: 'portal.user', label: 'Portal user' }),
+        orm.defineGroup({
+            code: 'portal.manager',
+            label: 'Portal access manager',
+            implies: ['contacts.user'],
+        }),
+    ],
+    models: [PortalInvitation, PortalSignature, PortalAnnouncement],
+    extensions: [UserPortalPartner, PartnerPortalUsers],
+});

package/dist/portal/routes-documents.d.ts

@@ -0,0 +1,2 @@
+import { type ModuleContext } from '../server/index.js';
+export declare function registerPortalDocumentRoutes(context: ModuleContext): void;

package/dist/portal/routes-documents.js

@@ -0,0 +1,391 @@
+/**
+ * The portal's documents API (RFC 0015 §5.3–5.5), for portal users only:
+ *
+ * - `GET  /api/portal/v1/home`                               per document type: what needs the user, and counts
+ * - `GET  /api/portal/v1/documents`                          the document types (and how many the user has)
+ * - `GET  /api/portal/v1/documents/:key?q=&offset=&limit=`   a list: the declared list fields
+ * - `GET  /api/portal/v1/documents/:key/:id`                 a document: the declared fields, lines, actions
+ * - `GET  /api/portal/v1/documents/:key/:id/pdf`             its PDF, from the declared template
+ * - `POST /api/portal/v1/documents/:key/:id/actions/:action` `{ signature?: { name, image }, message? }`
+ * - `GET  /api/portal/v1/documents/:key/:id/thread`          its comments (never notes, activities or the log)
+ * - `POST /api/portal/v1/documents/:key/:id/thread`          `{ body }`: a comment, its followers notified
+ *
+ * Which records: always a search **as the portal user**, so the model's portal record rule decides, narrowed by the
+ * declared domain; another customer's document is 404. What of them: only the declared fields, read once the record
+ * is known to be theirs (relations as their names). Actions run their transition in a system transaction once the
+ * checks passed — the system confirms on the customer's word, as an employee would — so the apps' own reactions
+ * (tasks of a confirmed order) run with the rights they need; the signature, the thread and the audit name the
+ * portal user.
+ */
+import { createHash } from 'node:crypto';
+import { chatterContext, postExternalMessage } from '../messaging/index.js';
+import { documentFields, renderDocument } from '../reporting/index.js';
+import { audit, HttpProblem, idempotent } from '../server/index.js';
+import { portalDocuments } from './documents.js';
+const ref = (env, name) => env.model(name);
+/** Largest drawn signature accepted (a PNG data URL, decoded). */
+const MAX_SIGNATURE_BYTES = 300_000;
+const ATTENTION_ITEMS = 5;
+export function registerPortalDocumentRoutes(context) {
+    const { app, driver } = context;
+    const documents = portalDocuments(context.registry);
+    const printable = documentFields(new Map([...documents.values()].map((d) => [d.model.name, d.model])));
+    const chatter = chatterContext(context);
+    const portalOnly = (env) => {
+        if (!env.groups.has('portal.user') || env.groups.has('base.user'))
+            throw new HttpProblem(403, 'portal-only', 'Portal users only', 'This is the portal’s API.');
+    };
+    const documentOf = (params) => {
+        const key = String(params['key'] ?? '');
+        const document = documents.get(key);
+        if (document === undefined)
+            throw new HttpProblem(404, 'not-found', 'No such document type', `No documents '${key}'.`);
+        return document;
+    };
+    const idOf = (params) => {
+        const id = Number(params['id']);
+        if (!Number.isSafeInteger(id) || id <= 0)
+            throw new HttpProblem(404, 'not-found', 'No such document', 'No such document.');
+        return id;
+    };
+    /** The declared records the user may see, narrowed by `extra`. */
+    const scope = (d, extra = {}) => ({
+        and: [d.spec.domain ?? {}, extra],
+    });
+    /** Whether record `id` is the user's (searched as the user: the record rule decides). */
+    const mine = async (env, d, id) => {
+        const found = await ref(env, d.model.name).search({ where: scope(d, { id }), limit: 1 });
+        if (found.length === 0)
+            throw new HttpProblem(404, 'not-found', 'No such document', `No ${d.spec.label} #${id}.`);
+    };
+    /** Field descriptions of `keys` of `model`, for the screen. */
+    const meta = (model, keys) => keys.map((key) => {
+        const f = model.byKey.get(key);
+        return {
+            key,
+            label: f?.label ?? key,
+            kind: f?.kind ?? 'char',
+            ...(f?.options === null || f?.options === undefined
+                ? {}
+                : { options: f.options.map(([value, label]) => ({ value, label })) }),
+        };
+    });
+    /** `keys` of `ids` read as the system (the records are known to be the user's): relations as names. */
+    const values = async (su, model, ids, keys) => {
+        if (ids.length === 0)
+            return [];
+        const loaded = await ref(su, model.name)
+            .browse(ids)
+            .load([...keys]);
+        const rows = loaded.read([...keys]);
+        for (const key of keys) {
+            const field = model.byKey.get(key);
+            if (field?.kind !== 'many2one' && field?.kind !== 'many2many')
+                continue;
+            const targetIds = [
+                ...new Set(rows.flatMap((r) => (Array.isArray(r[key]) ? r[key] : [r[key]]))),
+            ].filter((v) => typeof v === 'number');
+            const names = new Map();
+            if (targetIds.length > 0 && field.target !== null)
+                for (const t of (await ref(su, field.target).browse(targetIds).load(['displayName'])).read([
+                    'displayName',
+                ]))
+                    names.set(t['id'], String(t['displayName'] ?? ''));
+            const named = (v) => typeof v === 'number' ? { id: v, name: names.get(v) ?? '' } : null;
+            for (const r of rows)
+                r[key] =
+                    field.kind === 'many2one' ? named(r[key]) : (r[key] ?? []).map(named);
+        }
+        return rows;
+    };
+    /** The actions `when` allows on record `id`. */
+    const available = async (su, d, id) => {
+        const out = [];
+        for (const action of d.spec.actions ?? [])
+            if ((await ref(su, d.model.name).search({ where: { and: [{ id }, action.when] }, limit: 1 }))
+                .length > 0)
+                out.push({
+                    key: action.key,
+                    label: action.label,
+                    signature: action.signature === true,
+                    message: action.message === true,
+                });
+        return out;
+    };
+    /** The document as the user sees it: what a signature's hash covers. */
+    const documentOfRecord = async (su, d, id) => {
+        const [record] = await values(su, d.model, [id], d.spec.fields);
+        let lines = [];
+        if (d.spec.lines !== undefined && d.lineModel !== null) {
+            const [withLines] = (await ref(su, d.model.name)
+                .browse([id])
+                .load({ [d.spec.lines.field]: true })).read([d.spec.lines.field]);
+            const lineIds = withLines?.[d.spec.lines.field] ?? [];
+            lines = await values(su, d.lineModel, lineIds, d.spec.lines.fields);
+        }
+        return { record: record ?? { id }, lines };
+    };
+    const run = (request, fn) => request.env((env) => {
+        portalOnly(env);
+        return env.asSuperuser({ reason: 'portal read' }, (su) => fn(env, su));
+    }, { write: true });
+    app.get('/api/portal/v1/documents', async (request) => run(request, async (env) => {
+        const out = [];
+        for (const d of documents.values()) {
+            const [row] = await ref(env, d.model.name).aggregate({
+                where: scope(d),
+                measures: { count: 'count' },
+            });
+            out.push({ key: d.spec.key, label: d.spec.label, count: Number(row?.['count'] ?? 0) });
+        }
+        return { documents: out };
+    }));
+    app.get('/api/portal/v1/home', async (request) => run(request, async (env, su) => {
+        const sections = [];
+        for (const d of documents.values()) {
+            if (d.spec.attention === undefined)
+                continue;
+            const found = await ref(env, d.model.name).search({
+                where: scope(d, d.spec.attention),
+                ...(d.spec.order === undefined ? {} : { order: d.spec.order }),
+                limit: ATTENTION_ITEMS,
+            });
+            const [count] = await ref(env, d.model.name).aggregate({
+                where: scope(d, d.spec.attention),
+                measures: { count: 'count' },
+            });
+            sections.push({
+                key: d.spec.key,
+                label: d.spec.label,
+                count: Number(count?.['count'] ?? 0),
+                fields: meta(d.model, d.spec.list),
+                items: await values(su, d.model, found.ids, d.spec.list),
+            });
+        }
+        return { sections };
+    }));
+    app.get('/api/portal/v1/documents/:key', async (request) => {
+        const d = documentOf(request.params);
+        const q = (request.query ?? {});
+        const limit = Math.min(Math.max(Number(q['limit'] ?? 30) || 30, 1), 100);
+        const offset = Math.max(Number(q['offset'] ?? 0) || 0, 0);
+        const text = typeof q['q'] === 'string' ? q['q'].trim().slice(0, 100) : '';
+        const recName = d.model.recName ?? 'name';
+        const where = scope(d, text === '' ? {} : { [recName]: { ilike: `%${text.replace(/[%_\\]/g, (m) => `\\${m}`)}%` } });
+        return run(request, async (env, su) => {
+            const found = await ref(env, d.model.name).search({
+                where,
+                ...(d.spec.order === undefined ? {} : { order: d.spec.order }),
+                limit,
+                offset,
+            });
+            const [count] = await ref(env, d.model.name).aggregate({
+                where,
+                measures: { count: 'count' },
+            });
+            return {
+                key: d.spec.key,
+                label: d.spec.label,
+                fields: meta(d.model, d.spec.list),
+                items: await values(su, d.model, found.ids, d.spec.list),
+                count: Number(count?.['count'] ?? 0),
+            };
+        });
+    });
+    app.get('/api/portal/v1/documents/:key/:id', async (request) => {
+        const d = documentOf(request.params);
+        const id = idOf(request.params);
+        return run(request, async (env, su) => {
+            await mine(env, d, id);
+            const { record, lines } = await documentOfRecord(su, d, id);
+            return {
+                key: d.spec.key,
+                label: d.spec.label,
+                fields: meta(d.model, d.spec.fields),
+                record,
+                ...(d.spec.lines === undefined || d.lineModel === null
+                    ? {}
+                    : { lineFields: meta(d.lineModel, d.spec.lines.fields), lines }),
+                actions: await available(su, d, id),
+                pdf: d.spec.pdf !== undefined,
+                thread: d.spec.thread === true,
+            };
+        });
+    });
+    app.get('/api/portal/v1/documents/:key/:id/pdf', async (request, reply) => {
+        const d = documentOf(request.params);
+        const id = idOf(request.params);
+        const template = d.spec.pdf;
+        if (template === undefined)
+            throw new HttpProblem(404, 'not-found', 'No PDF', `${d.spec.label} have no PDF.`);
+        const rendered = await run(request, async (env, su) => {
+            await mine(env, d, id);
+            const keys = ['name', 'layout', 'scope'];
+            const found = await ref(su, 'report.template').search({
+                where: { key: template, targetModel: d.model.name, active: true },
+                limit: 1,
+            });
+            const [row] = (await found.load(keys)).read(keys);
+            if (row === undefined)
+                throw new HttpProblem(404, 'not-found', 'No PDF', `The template ${template} is not installed.`);
+            // The company's printed document of a record that is the user's: printed as the system.
+            return renderDocument(su, d.model, row, printable, { ids: [id] }, 'pdf');
+        });
+        return reply
+            .header('content-type', rendered.mime)
+            .header('content-disposition', `attachment; filename="${rendered.filename.replace(/["\\\r\n]/g, '_')}"`)
+            .send(rendered.content);
+    });
+    app.post('/api/portal/v1/documents/:key/:id/actions/:action', async (request, reply) => {
+        const d = documentOf(request.params);
+        const id = idOf(request.params);
+        const key = String(request.params['action'] ?? '');
+        const action = (d.spec.actions ?? []).find((a) => a.key === key);
+        if (action === undefined)
+            throw new HttpProblem(404, 'not-found', 'No such action', `${d.spec.label} have no '${key}'.`);
+        const body = (request.body ?? {});
+        const message = typeof body['message'] === 'string' ? body['message'].trim() : '';
+        if (action.message === true && message === '')
+            throw new HttpProblem(422, 'message-required', 'Say why', 'Write a message for this action.');
+        const signature = (body['signature'] ?? null);
+        const signedName = typeof signature?.['name'] === 'string' ? signature['name'].trim() : '';
+        let image = null;
+        if (action.signature === true) {
+            const data = typeof signature?.['image'] === 'string' ? signature['image'] : '';
+            const png = /^data:image\/png;base64,([A-Za-z0-9+/=]+)$/.exec(data);
+            if (signedName === '' || signedName.length > 200 || png === null)
+                throw new HttpProblem(422, 'signature-required', 'Sign first', 'Type your name and draw your signature.');
+            image = new Uint8Array(Buffer.from(png[1], 'base64'));
+            if (image.byteLength > MAX_SIGNATURE_BYTES || image.byteLength === 0)
+                throw new HttpProblem(422, 'signature-too-large', 'Signature too large', 'Draw it again.');
+        }
+        const outcome = await request.env((env) => idempotent(request, env, driver, async () => {
+            portalOnly(env);
+            await mine(env, d, id);
+            const who = await env.asSuperuser({ reason: 'portal action' }, async (su) => {
+                if (!(await available(su, d, id)).some((a) => a.key === key))
+                    throw new HttpProblem(409, 'not-available', 'Not possible any more', `${action.label} is not possible on this document now.`);
+                const [user] = (await ref(su, 'res.users').browse([env.uid]).load(['login', 'name'])).read(['login', 'name']);
+                const seen = await documentOfRecord(su, d, id);
+                return {
+                    login: String(user?.['login'] ?? ''),
+                    name: String(user?.['name'] ?? ''),
+                    hash: createHash('sha256').update(JSON.stringify(seen)).digest('hex'),
+                };
+            });
+            // The transition and its record, as the system, in one transaction of their own.
+            await context.shutro.bootstrap({ reason: `portal ${d.spec.key} ${key} by ${who.login}`, company: env.companyId }, async (su) => {
+                const target = ref(su, d.model.name).browse([id]);
+                await target[action.transition].call(target);
+                let signatureId = null;
+                if (image !== null) {
+                    const created = await ref(su, 'portal.signature').create([
+                        {
+                            resModel: d.model.name,
+                            resId: id,
+                            action: key,
+                            user: env.uid,
+                            signedName,
+                            image,
+                            documentHash: who.hash,
+                            ip: request.ip,
+                            company: env.companyId,
+                        },
+                    ]);
+                    signatureId = created.ids[0] ?? null;
+                }
+                const text = [
+                    image === null
+                        ? `${action.label} by ${who.name} in the portal.`
+                        : `${action.label} by ${who.name} in the portal, signed as “${signedName}”.`,
+                    message,
+                ]
+                    .filter((t) => t !== '')
+                    .join('\n\n');
+                await postExternalMessage(su, chatter, d.model.name, id, {
+                    text,
+                    authorEmail: who.login,
+                    authorName: who.name,
+                });
+                await audit(su, {
+                    kind: 'portal.action',
+                    summary: `${who.name} (${who.login}): ${action.label} on ${d.model.name} #${id} in the portal.`,
+                    actor: env.uid,
+                    company: env.companyId,
+                    targetModel: d.model.name,
+                    targetId: id,
+                    details: { action: key, signature: signatureId, documentHash: who.hash },
+                    ip: request.ip,
+                });
+                await su.flush(); // checks run in this scope, not at commit (Shutro request #11)
+            });
+            return { status: 200, body: { done: key } };
+        }), { write: true });
+        return reply.status(outcome.status).send(outcome.body);
+    });
+    app.get('/api/portal/v1/documents/:key/:id/thread', async (request) => {
+        const d = documentOf(request.params);
+        const id = idOf(request.params);
+        if (d.spec.thread !== true)
+            throw new HttpProblem(404, 'not-found', 'No thread', `${d.spec.label} have no thread.`);
+        return run(request, async (env, su) => {
+            await mine(env, d, id);
+            const keys = ['body', 'author', 'authorName', 'createdAt'];
+            const found = await ref(su, 'mail.message').search({
+                where: { resModel: d.model.name, resId: id, kind: 'comment' },
+                order: ['id desc'],
+                limit: 100,
+            });
+            const rows = (await found.load(keys)).read(keys);
+            const authors = [
+                ...new Set(rows.map((r) => r['author']).filter((a) => typeof a === 'number')),
+            ];
+            const names = new Map();
+            if (authors.length > 0)
+                for (const u of (await ref(su, 'res.users')
+                    .browse(authors)
+                    .load(['name'])).read(['name']))
+                    names.set(u['id'], String(u['name']));
+            return {
+                messages: rows.map((r) => ({
+                    id: r['id'],
+                    at: r['createdAt'],
+                    body: r['body'],
+                    author: typeof r['author'] === 'number'
+                        ? (names.get(r['author']) ?? '')
+                        : String(r['authorName'] ?? ''),
+                    mine: r['author'] === env.uid,
+                })),
+            };
+        });
+    });
+    app.post('/api/portal/v1/documents/:key/:id/thread', async (request, reply) => {
+        const d = documentOf(request.params);
+        const id = idOf(request.params);
+        if (d.spec.thread !== true)
+            throw new HttpProblem(404, 'not-found', 'No thread', `${d.spec.label} have no thread.`);
+        const text = String((request.body ?? {})['body'] ?? '').trim();
+        if (text === '')
+            throw new HttpProblem(400, 'invalid-body', 'Empty message', 'Write something first.');
+        const posted = await run(request, async (env, su) => {
+            await mine(env, d, id);
+            const [user] = (await ref(su, 'res.users').browse([env.uid]).load(['login', 'name'])).read([
+                'login',
+                'name',
+            ]);
+            const item = await postExternalMessage(su, chatter, d.model.name, id, {
+                text,
+                authorEmail: String(user?.['login'] ?? ''),
+                authorName: String(user?.['name'] ?? ''),
+            });
+            return {
+                id: item.id,
+                at: item.at,
+                body: item.body,
+                author: item.authorName ?? '',
+                mine: true,
+            };
+        });
+        return reply.code(201).send(posted);
+    });
+}

package/dist/portal/routes.d.ts

@@ -0,0 +1,13 @@
+import { type Mailer } from '../mail/index.js';
+import { type ModuleContext } from '../server/index.js';
+/** How long an invitation works. */
+export declare const INVITATION_DAYS = 7;
+/** The group of portal users. */
+export declare const PORTAL_USER = "portal.user";
+export interface PortalRoutesOptions {
+    /** Where the portal app is served: activation links point there. */
+    readonly portalUrl: string;
+    /** Sends the invitations; without one, the inviter passes the link on. */
+    readonly mailer?: Mailer | undefined;
+}
+export declare function registerPortalRoutes(context: ModuleContext, options: PortalRoutesOptions): void;