shutro-erp 0.3.2 → 0.3.4

package/dist/settings/company.js

@@ -0,0 +1,189 @@
+/**
+ * The companies (RFC 0018, RFC 0019 §3.4). The current company's name, number grouping and brand colour (the
+ * back-office's accent), and its details: every simple field the installed apps add to the company (address,
+ * contacts, tax ids, fiscal year…). Administrators and holders of the Settings / Company access level change them;
+ * administrators also add companies, whose defaults (journals, sequences, taxes…) the apps then install.
+ *
+ * - `GET   /api/v1/settings/company`
+ * - `PATCH /api/v1/settings/company`     `{ name?, numberGrouping?, accentColor?, details? }` (`accentColor`:
+ *                                         `#rrggbb` or null; `details`: `{ field: value }`)
+ * - `GET   /api/v1/settings/companies`   every company with its currency and people, the currencies
+ * - `POST  /api/v1/settings/companies`   `{ name, currency }`: a new company (administrators)
+ */
+import { audit, HttpProblem, imageVersions, installDefaults, publicApiModels, } from '../server/index.js';
+const model = (env, name) => env.model(name);
+const find = async (env, name, where, keys) => {
+    const set = await model(env, name).search({ where, order: ['id asc'] });
+    return set.length === 0 ? [] : (await set.load(keys)).read(['id', ...keys]);
+};
+const KEYS = ['name', 'numberGrouping', 'accentColor', 'currency'];
+/** Fields with controls of their own, or not the person's to edit. */
+const OWN = new Set([...KEYS, 'id', 'displayName']);
+const SIMPLE = new Set(['char', 'text', 'integer', 'boolean', 'selection']);
+/** Shown, not changed here: an app's own flow sets them (the chart of accounts of a localization). */
+const SHOWN_ONLY = new Set(['chartTemplate']);
+export function registerCompanyRoutes(context) {
+    const { app, registry } = context;
+    /** The company's details: its stored simple fields, as the generated API serves them. */
+    const detailFields = () => (publicApiModels(registry).get('res.company')?.fields ?? []).filter((f) => f.stored && SIMPLE.has(f.kind) && !OWN.has(f.key));
+    const read = async (env, id) => {
+        const fields = detailFields();
+        const keys = [...KEYS, ...fields.map((f) => f.key)];
+        const [row] = (await model(env, 'res.company').browse([id]).load(keys)).read(['id', ...keys]);
+        const currency = row?.['currency'];
+        const [money] = typeof currency === 'number'
+            ? await find(env, 'res.currency', { id: currency }, ['name'])
+            : [];
+        return {
+            id,
+            name: String(row?.['name'] ?? ''),
+            numberGrouping: row?.['numberGrouping'] === 'lakh' ? 'lakh' : 'international',
+            accentColor: typeof row?.['accentColor'] === 'string' ? row['accentColor'] : null,
+            currency: String(money?.['name'] ?? ''),
+            details: fields.map((f) => ({
+                key: f.key,
+                label: f.label,
+                kind: f.kind,
+                readonly: f.readonly || SHOWN_ONLY.has(f.key),
+                options: f.options?.map((o) => ({ value: String(o[0]), label: String(o[1]) })) ?? null,
+                value: (row?.[f.key] ?? null),
+            })),
+        };
+    };
+    const guarded = (request, fn, write = false) => request.env(async (env) => {
+        if (!env.administrator && !env.groups.has('settings.company'))
+            throw new HttpProblem(403, 'access', 'Company settings', 'Changing the company needs the Administrator role or the Settings / Company access.');
+        if (env.companyId === null || env.companyId === undefined)
+            throw new HttpProblem(409, 'no-company', 'No company', 'Choose a company first.');
+        return env.asSuperuser({ reason: 'company settings' }, async (su) => {
+            const out = await fn(su, env.companyId, env);
+            if (write)
+                await su.flush();
+            return out;
+        });
+    }, 
+    // The superuser scope is audited: even a read writes its audit record.
+    { write: true });
+    app.get('/api/v1/settings/company', async (request) => guarded(request, (su, company) => read(su, company)));
+    app.patch('/api/v1/settings/company', async (request) => {
+        const body = (request.body ?? {});
+        const values = {};
+        const invalid = (code, title, detail) => new HttpProblem(422, code, title, detail);
+        if (body['name'] !== undefined) {
+            const name = String(body['name']).trim();
+            if (name === '')
+                throw invalid('invalid-name', 'Invalid name', 'The company needs a name.');
+            values['name'] = name;
+        }
+        if (body['numberGrouping'] !== undefined) {
+            if (body['numberGrouping'] !== 'international' && body['numberGrouping'] !== 'lakh')
+                throw invalid('invalid-grouping', 'Invalid grouping', "Number grouping is 'international' or 'lakh'.");
+            values['numberGrouping'] = body['numberGrouping'];
+        }
+        if (body['accentColor'] !== undefined) {
+            const color = body['accentColor'];
+            if (color !== null && !(typeof color === 'string' && /^#[0-9a-fA-F]{6}$/.test(color)))
+                throw invalid('invalid-color', 'Invalid colour', 'The brand colour is a hex colour such as #4f46e5, or empty for the default.');
+            values['accentColor'] = color === null ? null : color.toLowerCase();
+        }
+        // The details: only the fields offered, each with a value of its kind (Shutro checks sizes and constraints).
+        const details = body['details'];
+        if (details !== undefined) {
+            if (typeof details !== 'object' || details === null || Array.isArray(details))
+                throw invalid('invalid-details', 'Invalid details', 'details is { field: value }.');
+            const offered = new Map(detailFields().map((f) => [f.key, f]));
+            for (const [key, value] of Object.entries(details)) {
+                const f = offered.get(key);
+                if (f === undefined || f.readonly || SHOWN_ONLY.has(key))
+                    throw invalid('invalid-details', 'Invalid details', `'${key}' is not changed here.`);
+                const fits = value === null ||
+                    (f.kind === 'boolean'
+                        ? typeof value === 'boolean'
+                        : f.kind === 'integer'
+                            ? Number.isSafeInteger(value)
+                            : f.kind === 'selection'
+                                ? (f.options ?? []).some((o) => o[0] === value)
+                                : typeof value === 'string' && value.length <= 4000);
+                if (!fits)
+                    throw invalid('invalid-details', 'Invalid details', `'${f.label}' has an invalid value.`);
+                values[key] = typeof value === 'string' && value.trim() === '' ? null : value;
+            }
+        }
+        return guarded(request, async (su, company) => {
+            if (Object.keys(values).length > 0)
+                await model(su, 'res.company').browse([company]).write(values);
+            return read(su, company);
+        }, true);
+    });
+    app.get('/api/v1/settings/companies', async (request) => guarded(request, async (su, current, env) => {
+        const all = await find(su, 'res.company', {}, ['name', 'currency']);
+        const currencies = await find(su, 'res.currency', {}, ['name']);
+        const logos = await imageVersions(su, 'company', all.map((c) => c['id']));
+        const currencyName = new Map(currencies.map((c) => [c['id'], String(c['name'])]));
+        return {
+            canCreate: env.administrator,
+            companies: (await Promise.all(all.map(async (c) => ({
+                id: c['id'],
+                name: String(c['name']),
+                currency: currencyName.get(c['currency']) ?? '',
+                people: (await model(su, 'res.users').search({
+                    where: { isService: { ne: true }, companies: { any: { id: c['id'] } } },
+                })).length,
+                current: c['id'] === current,
+                logo: logos[String(c['id'])] ?? null,
+                // The person can switch to it: it is one of their companies.
+                member: (await model(su, 'res.users').search({
+                    where: { id: env.uid, companies: { any: { id: c['id'] } } },
+                })).length > 0,
+            })))).sort((a, b) => a.name.localeCompare(b.name)),
+            currencies: currencies
+                .map((c) => ({ id: c['id'], name: String(c['name']) }))
+                .sort((a, b) => a.name.localeCompare(b.name)),
+        };
+    }));
+    app.post('/api/v1/settings/companies', async (request, reply) => {
+        const body = (request.body ?? {});
+        const name = String(body['name'] ?? '').trim();
+        const currency = Number(body['currency']);
+        if (name === '' || name.length > 200)
+            throw new HttpProblem(422, 'invalid-name', 'Invalid name', 'The company needs a name.');
+        if (!Number.isSafeInteger(currency) || currency <= 0)
+            throw new HttpProblem(422, 'invalid-currency', 'Invalid currency', 'Choose its currency.');
+        const made = await request.env(async (env) => {
+            if (!env.administrator)
+                throw new HttpProblem(403, 'access', 'Administrators only', 'Only an administrator adds companies.');
+            return env.asSuperuser({ reason: 'new company' }, async (su) => {
+                if ((await find(su, 'res.currency', { id: currency }, ['name'])).length === 0)
+                    throw new HttpProblem(422, 'invalid-currency', 'Invalid currency', 'Choose its currency.');
+                const company = (await model(su, 'res.company').create([{ name, currency }]))
+                    .ids[0];
+                // The administrators and the person who made it can switch to it at once.
+                const admins = [...su.access.administratorGroups()];
+                const holders = admins.length === 0
+                    ? []
+                    : await find(su, 'auth.user_group', { group: { in: admins } }, ['user']);
+                const users = [...new Set([env.uid, ...holders.map((h) => h['user'])])];
+                await model(su, 'res.users')
+                    .browse(users)
+                    .write({ companies: { link: [company] } });
+                await audit(env, {
+                    kind: 'settings.company_created',
+                    summary: `Company ${name} created.`,
+                    targetModel: 'res.company',
+                    targetId: company,
+                    ip: request.ip,
+                });
+                await su.flush();
+                return { company, users };
+            });
+        }, { write: true });
+        for (const user of made.users)
+            context.auth?.forget(user);
+        // The apps' defaults for it, once it exists (after the commit), as for a company made at install.
+        const defaults = await installDefaults(context.shutro, registry.loaded.modules, {
+            company: made.company,
+            reason: `defaults of company ${name}`,
+        });
+        return reply.code(201).send({ id: made.company, name, defaults });
+    });
+}

package/dist/settings/index.d.ts

@@ -1,18 +1,18 @@
-/**
- * @packageDocumentation
- * `shutro-erp/settings` (RFC 0008): the Settings app. Its App manager lists the installed, disabled and available apps and
- * installs, enables or disables them (`/api/v1/settings/apps`, the Settings → Apps page). Every installation has it;
- * it cannot be disabled. Changing apps needs the Administrator role or the `settings.apps` access level.
- */
-import { defineModule } from '../modules-sdk/index.js';
+import { type KoshModule } from '../modules-sdk/index.js';
 import { orm } from '../server/orm.js';
+import { type PeopleOptions } from './people.js';
+export { type CompanyDetail, type CompanySettings, registerCompanyRoutes } from './company.js';
+export { type Assignment, INVITATION_DAYS, type PeopleOptions, registerPeopleRoutes, } from './people.js';
 export { type AppInfo, type PlanInfo, PROTECTED_APPS, registerAppRoutes } from './routes.js';
+export { registerSecurityRoutes } from './security.js';
 /** Package identity. */
 export declare const PACKAGE: {
     readonly name: string;
     readonly rfc: string;
 };
-/** The Shutro module: the App manager group. */
+/** The Shutro module: the Settings groups and invitations. */
 export declare const settingsShutro: ReturnType<typeof orm.defineModule>;
-/** The Settings app. */
-export declare const settings: ReturnType<typeof defineModule>;
+/** The Settings app with explicit options (tests): the back-office's address and the mailer of invitations. */
+export declare function settingsModule(options?: Partial<PeopleOptions>): KoshModule;
+/** The Settings app (the back-office's address and the mailer from the environment). */
+export declare const settings: KoshModule;

package/dist/settings/index.js

@@ -1,51 +1,180 @@
 /**
  * @packageDocumentation
- * `shutro-erp/settings` (RFC 0008): the Settings app. Its App manager lists the installed, disabled and available apps and
- * installs, enables or disables them (`/api/v1/settings/apps`, the Settings → Apps page). Every installation has it;
- * it cannot be disabled. Changing apps needs the Administrator role or the `settings.apps` access level.
+ * `shutro-erp/settings` (RFC 0008, RFC 0019): the Settings app. Its App manager lists the installed, disabled and
+ * available apps and installs, enables or disables them (`/api/v1/settings/apps`); it cannot be disabled. Changing
+ * apps needs the Administrator role or the `settings.apps` access level. Its Company page sets the current company's
+ * name, number grouping, brand colour and details, and Companies lists them, switches and adds one (`settings.company`, RFC 0018,
+ * RFC 0019 §3.4). People (RFC 0019 §3.2) invites, deactivates
+ * and gives roles to the installation's users (`settings.people`).
  */
+import { mailerFromEnv } from '../mail/index.js';
 import { defineModule } from '../modules-sdk/index.js';
 import { base, baseShutro } from '../server/index.js';
 import { orm } from '../server/orm.js';
+import { registerCompanyRoutes } from './company.js';
+import { registerPeopleRoutes } from './people.js';
 import { registerAppRoutes } from './routes.js';
+import { registerSecurityRoutes } from './security.js';
+export { registerCompanyRoutes } from './company.js';
+export { INVITATION_DAYS, registerPeopleRoutes, } from './people.js';
 export { PROTECTED_APPS, registerAppRoutes } from './routes.js';
+export { registerSecurityRoutes } from './security.js';
 /** Package identity. */
 export const PACKAGE = Object.freeze({
     name: 'shutro-erp/settings',
     rfc: 'RFC 0008',
 });
-/** The Shutro module: the App manager group. */
+/** A one-time link that lets an invited person choose their password. Private: read through the People routes. */
+const Invitation = orm.defineModel('settings.invitation', {
+    label: 'Invitation',
+    order: ['id desc'],
+    access: {},
+    fields: {
+        user: orm.f.many2one('res.users', { required: true, ondelete: 'cascade' }),
+        tokenHash: orm.f.char({ required: true, index: 'unique' }),
+        expiresAt: orm.f.datetime({ required: true }),
+        usedAt: orm.f.datetime(),
+        invitedBy: orm.f.many2one('res.users', { ondelete: 'set null' }),
+    },
+});
+/** The Shutro module: the Settings groups and invitations. */
 export const settingsShutro = orm.defineModule({
     name: 'settings',
     version: '0.1.0',
     depends: [baseShutro],
     groups: [
         orm.defineGroup({ code: 'settings.apps', label: 'App manager', implies: ['base.user'] }),
+        orm.defineGroup({
+            code: 'settings.company',
+            label: 'Company settings',
+            implies: ['base.user'],
+        }),
+        orm.defineGroup({ code: 'settings.people', label: 'People manager', implies: ['base.user'] }),
     ],
-    models: [],
-});
-/** The Settings app. */
-export const settings = defineModule({
-    shutro: settingsShutro,
-    kosh: '^0.1.0',
-    depends: [base],
-    app: {
-        code: 'settings',
-        label: 'Settings',
-        icon: 'settings',
-        sequence: 1000,
-        category: 'Administration',
-        summary: 'Apps, and the settings of this installation',
-    },
-    accessLevels: {
-        apps: { label: 'App manager', groups: ['settings.apps'] },
-    },
-    actions: {
-        'settings.action_apps': { type: 'client', page: 'settings.Apps', label: 'Apps' },
-    },
-    menus: [
-        { id: 'settings.root', label: 'Settings', app: 'settings' },
-        { id: 'settings.apps', parent: 'settings.root', label: 'Apps', action: 'settings.action_apps' },
-    ],
-    routes: (context) => registerAppRoutes(context),
+    models: [Invitation],
 });
+/** The Settings app with explicit options (tests): the back-office's address and the mailer of invitations. */
+export function settingsModule(options = {}) {
+    return defineModule({
+        shutro: settingsShutro,
+        kosh: '^0.1.0',
+        depends: [base],
+        app: {
+            code: 'settings',
+            label: 'Settings',
+            icon: 'settings',
+            sequence: 1000,
+            category: 'Administration',
+            summary: 'Apps, people and the settings of this installation',
+        },
+        accessLevels: {
+            apps: { label: 'App manager', groups: ['settings.apps'] },
+            company: { label: 'Company settings', groups: ['settings.company'] },
+            people: { label: 'People manager', groups: ['settings.people'] },
+        },
+        privateModels: ['settings.invitation'],
+        actions: {
+            'settings.action_overview': { type: 'client', page: 'settings.Overview', label: 'Settings' },
+            'settings.action_apps': { type: 'client', page: 'settings.Apps', label: 'Apps' },
+            'settings.action_company': { type: 'client', page: 'settings.Company', label: 'Company' },
+            'settings.action_companies': {
+                type: 'client',
+                page: 'settings.Companies',
+                label: 'Companies',
+            },
+            'settings.action_security': { type: 'client', page: 'settings.Security', label: 'Security' },
+            'settings.action_audit': { type: 'client', page: 'settings.Audit', label: 'Audit log' },
+            'settings.action_people': { type: 'client', page: 'settings.People', label: 'People' },
+            'settings.action_roles': {
+                type: 'client',
+                page: 'settings.Roles',
+                label: 'Roles & permissions',
+            },
+        },
+        menus: [
+            { id: 'settings.root', label: 'Settings', app: 'settings' },
+            // The overview first (the app's home), then the sections in groups (RFC 0019 §3.1). Modules add their
+            // settings under `settings.group_apps`.
+            {
+                id: 'settings.overview',
+                parent: 'settings.root',
+                label: 'Overview',
+                action: 'settings.action_overview',
+                sequence: 0,
+            },
+            { id: 'settings.group_workspace', parent: 'settings.root', label: 'Workspace', sequence: 10 },
+            {
+                id: 'settings.company',
+                parent: 'settings.group_workspace',
+                label: 'Company',
+                action: 'settings.action_company',
+                sequence: 1,
+            },
+            {
+                id: 'settings.companies',
+                parent: 'settings.group_workspace',
+                label: 'Companies',
+                action: 'settings.action_companies',
+                sequence: 2,
+            },
+            { id: 'settings.group_people', parent: 'settings.root', label: 'People', sequence: 20 },
+            {
+                id: 'settings.people',
+                parent: 'settings.group_people',
+                label: 'People',
+                action: 'settings.action_people',
+                sequence: 1,
+            },
+            {
+                id: 'settings.roles',
+                parent: 'settings.group_people',
+                label: 'Roles & permissions',
+                action: 'settings.action_roles',
+                sequence: 2,
+            },
+            // Security: administrators only (the server refuses everyone else).
+            {
+                id: 'settings.group_security',
+                parent: 'settings.root',
+                label: 'Security',
+                sequence: 30,
+                visibleTo: ['base.admin'],
+            },
+            {
+                id: 'settings.security',
+                parent: 'settings.group_security',
+                label: 'Security',
+                action: 'settings.action_security',
+                sequence: 1,
+                visibleTo: ['base.admin'],
+            },
+            {
+                id: 'settings.audit',
+                parent: 'settings.group_security',
+                label: 'Audit log',
+                action: 'settings.action_audit',
+                sequence: 2,
+                visibleTo: ['base.admin'],
+            },
+            { id: 'settings.group_apps', parent: 'settings.root', label: 'Apps', sequence: 40 },
+            {
+                id: 'settings.apps',
+                parent: 'settings.group_apps',
+                label: 'App manager',
+                action: 'settings.action_apps',
+                sequence: 1,
+            },
+        ],
+        routes: (context) => {
+            registerAppRoutes(context);
+            registerCompanyRoutes(context);
+            registerSecurityRoutes(context);
+            registerPeopleRoutes(context, {
+                baseUrl: options.baseUrl ?? process.env['KOSH_BASE_URL'] ?? 'http://localhost:5173',
+                mailer: 'mailer' in options ? options.mailer : mailerFromEnv(),
+            });
+        },
+    });
+}
+/** The Settings app (the back-office's address and the mailer from the environment). */
+export const settings = settingsModule();

package/dist/settings/people.d.ts

@@ -0,0 +1,16 @@
+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;
+export interface PeopleOptions {
+    /** The back-office's address (`SHUTRO_ERP_BASE_URL`): activation links point there. */
+    readonly baseUrl: string;
+    /** Sends the invitations; without one, the inviter passes the link on. */
+    readonly mailer?: Mailer | undefined;
+}
+export interface Assignment {
+    readonly group: string;
+    /** null: every company. */
+    readonly company: number | null;
+}
+export declare function registerPeopleRoutes(context: ModuleContext, options: PeopleOptions): void;