shutro-erp 0.3.5 → 0.3.7

package/dist/expense_account/module.js

@@ -0,0 +1,318 @@
+/**
+ * Spend in the books (RFC 0024 §2.1, `expense_account`): each category has its expense account; an approved report
+ * is **booked** as one posted entry — each expense's amount less its tax to the category's account, the tax to the
+ * tax's account; against it what the advance covered (Employee advances), what the employee paid (Employee
+ * reimbursements payable) and what the company card paid (Company card clearing) — and **reimbursed** from the cash
+ * or bank journal chosen on the report. An advance's payout and the cash returned at its settlement are booked from
+ * its journal. Accounts and the Expenses journal are found by their codes, and made when the chart lacks them.
+ */
+import { accountingShutro } from '../accounting/index.js';
+import { expenseShutro } from '../expense/index.js';
+import { orm } from '../server/orm.js';
+import { defineModule, extendModel, f, records } from './.kosh/bindings.js';
+const ZERO = orm.toDecimal(0);
+/** The accounts Spend books to, by code, made when missing. */
+export const EXPENSE_ACCOUNTS = {
+    advances: { code: '1170', name: 'Employee advances', type: 'asset_current', reconcile: true },
+    payable: {
+        code: '2170',
+        name: 'Employee reimbursements payable',
+        type: 'liability_current',
+        reconcile: true,
+    },
+    card: { code: '2180', name: 'Company card clearing', type: 'liability_current', reconcile: true },
+    expense: { code: '6350', name: 'Staff expenses', type: 'expense', reconcile: false },
+};
+/** The company's Spend accounts and the Expenses journal (`EXP`); `null` without a chart. */
+export async function expenseAccountsOf(env, company) {
+    const chart = await env.model('account.account').search({ where: { company }, limit: 1 });
+    if (chart.length === 0)
+        return null;
+    const out = {};
+    for (const [key, spec] of Object.entries(EXPENSE_ACCOUNTS)) {
+        const found = (await env.model('account.account').search({ where: { company, code: spec.code }, limit: 1 })).ids[0];
+        out[key] =
+            found ??
+                (await env.model('account.account').create([{ ...spec, company }]))
+                    .ids[0];
+    }
+    const journal = (await env.model('account.journal').search({ where: { company, code: 'EXP' }, limit: 1 }))
+        .ids[0] ??
+        (await env
+            .model('account.journal')
+            .create([{ company, code: 'EXP', name: 'Expenses', type: 'general' }])).ids[0];
+    out.journal = journal;
+    return out;
+}
+/** Posts one balanced entry in `journal` and returns it. */
+async function post(env, company, journal, ref, lines) {
+    const kept = lines.filter((l) => !l.debit.isZero() || !l.credit.isZero());
+    const [c] = await env.model('res.company').browse([company]).load({});
+    const made = await env.model('account.move').create([
+        {
+            kind: 'entry',
+            journal,
+            company,
+            currency: c?.currency.id,
+            date: env.today(),
+            ref,
+            lines: {
+                create: kept.map((l) => ({
+                    account: l.account,
+                    name: l.name,
+                    debit: l.debit.toDecimalPlaces(2).toString(),
+                    credit: l.credit.toDecimalPlaces(2).toString(),
+                })),
+            },
+        },
+    ]);
+    await env.withGrants({ grants: ['account.post'], reason: `Spend ${ref}` }, (e) => e.model('account.move').browse(made.ids).post());
+    return made.ids[0];
+}
+const noChart = (model) => new orm.ValidationError(model, ['state'], 'The company has no chart of accounts yet.', 'Install a chart in Accounting first.');
+/** The cash or bank journal's account. @throws {ValidationError} without one */
+async function moneyAccount(env, model, journal) {
+    if (journal === null)
+        throw new orm.ValidationError(model, ['paymentJournal'], 'Choose the cash or bank journal it is paid from.', 'Set “Paid from” on the record, then try again.');
+    const [j] = await env.model('account.journal').browse([journal.id]).load({});
+    const account = j?.defaultAccount?.id;
+    if (j === undefined || account === undefined || (j.type !== 'cash' && j.type !== 'bank'))
+        throw new orm.ValidationError(model, ['paymentJournal'], 'Pay from a cash or bank journal with its account.', 'Choose a cash or bank journal (Accounting › Configuration › Journals).');
+    return { journal: journal.id, account };
+}
+/** Books approved reports: one posted entry each. */
+async function bookSheets(env, ids) {
+    for (const s of await env
+        .model('expense.sheet')
+        .browse(ids)
+        .load({
+        expenses: { category: true, tax: true },
+        company: true,
+        employee: true,
+    })) {
+        const accounts = await expenseAccountsOf(env, s.company.id);
+        if (accounts === null)
+            throw noChart('expense.sheet');
+        const lines = [];
+        let employeePaid = ZERO;
+        let companyPaid = ZERO;
+        for (const e of s.expenses) {
+            const tax = e.taxAmount ?? ZERO;
+            const account = e.category.account?.id ?? accounts.expense;
+            lines.push({ account, debit: e.amount.minus(tax), credit: ZERO, name: e.name });
+            if (!tax.isZero())
+                lines.push({
+                    account: e.tax?.account?.id ?? account,
+                    debit: tax,
+                    credit: ZERO,
+                    name: `${e.name} (${e.tax?.name ?? 'tax'})`,
+                });
+            if (e.paidBy === 'company')
+                companyPaid = companyPaid.plus(e.amount);
+            else
+                employeePaid = employeePaid.plus(e.amount);
+        }
+        const fromAdvance = s.advanceUsed.gt(employeePaid) ? employeePaid : s.advanceUsed;
+        lines.push({
+            account: accounts.advances,
+            debit: ZERO,
+            credit: fromAdvance,
+            name: `${s.name} from the advance`,
+        });
+        lines.push({
+            account: accounts.payable,
+            debit: ZERO,
+            credit: employeePaid.minus(fromAdvance),
+            name: `${s.name} to reimburse ${s.employee.name}`,
+        });
+        lines.push({
+            account: accounts.card,
+            debit: ZERO,
+            credit: companyPaid,
+            name: `${s.name} company card`,
+        });
+        const entry = await post(env, s.company.id, accounts.journal, s.name, lines);
+        await env
+            .model('expense.sheet')
+            .browse([s.id])
+            .write({ entry });
+    }
+}
+/** Pays reports out: the payable cleared against the cash or bank journal. */
+async function reimburseSheets(env, ids) {
+    for (const s of await env
+        .model('expense.sheet')
+        .browse(ids)
+        .load({ company: true, employee: true })) {
+        const accounts = await expenseAccountsOf(env, s.company.id);
+        if (accounts === null)
+            throw noChart('expense.sheet');
+        const amount = s.toReimburse ?? ZERO;
+        if (amount.isZero())
+            continue;
+        const money = await moneyAccount(env, 'expense.sheet', s.paymentJournal);
+        const entry = await post(env, s.company.id, money.journal, `${s.name} reimbursed`, [
+            {
+                account: accounts.payable,
+                debit: amount,
+                credit: ZERO,
+                name: `${s.name} ${s.employee.name}`,
+            },
+            { account: money.account, debit: ZERO, credit: amount, name: `${s.name} ${s.employee.name}` },
+        ]);
+        await env
+            .model('expense.sheet')
+            .browse([s.id])
+            .write({ paymentEntry: entry });
+    }
+}
+export const CategoryAccount = extendModel('expense.category', {
+    fields: {
+        account: f.many2one('account.account', {
+            ondelete: 'restrict',
+            label: 'Expense account',
+            help: 'Where this category is booked; empty: Staff expenses (6350).',
+        }),
+    },
+});
+export const SheetBooks = extendModel('expense.sheet', {
+    fields: {
+        entry: f.many2one('account.move', { ondelete: 'restrict', label: 'Journal entry' }),
+        paymentJournal: f.many2one('account.journal', {
+            ondelete: 'restrict',
+            label: 'Paid from',
+            help: 'The cash or bank journal the reimbursement is paid from.',
+        }),
+        paymentEntry: f.many2one('account.move', {
+            ondelete: 'restrict',
+            label: 'Reimbursement entry',
+        }),
+    },
+    fieldOverrides: {
+        state: {
+            statesAdd: { posted: 'Booked', paid: 'Reimbursed' },
+            transitionsAdd: {
+                post: {
+                    from: ['approved'],
+                    to: 'posted',
+                    requires: 'expense.settle',
+                    after: records('expense.sheet', async (sheets) => {
+                        const env = sheets.env;
+                        await env.flush();
+                        await env.asSuperuser({ reason: 'book expense reports' }, (su) => bookSheets(su, sheets.ids));
+                    }),
+                },
+                reimburse: {
+                    from: ['posted'],
+                    to: 'paid',
+                    requires: 'expense.settle',
+                    after: records('expense.sheet', async (sheets) => {
+                        const env = sheets.env;
+                        await env.flush();
+                        await env.asSuperuser({ reason: 'reimburse expense reports' }, (su) => reimburseSheets(su, sheets.ids));
+                    }),
+                },
+            },
+        },
+    },
+});
+export const AdvanceBooks = extendModel('expense.advance', {
+    fields: {
+        paymentJournal: f.many2one('account.journal', {
+            ondelete: 'restrict',
+            label: 'Paid from',
+            help: 'The cash or bank journal the advance is paid from, and the rest returned to.',
+        }),
+        entry: f.many2one('account.move', { ondelete: 'restrict', label: 'Payout entry' }),
+        returnEntry: f.many2one('account.move', { ondelete: 'restrict', label: 'Return entry' }),
+    },
+    overrides: {
+        // The payout: Employee advances against the cash or bank journal.
+        paidOut: async function (next) {
+            await next();
+            const advances = this;
+            const env = advances.env;
+            await env.asSuperuser({ reason: 'book advance payouts' }, async (su) => {
+                for (const a of await su
+                    .model('expense.advance')
+                    .browse(advances.ids)
+                    .load({ company: true, employee: true })) {
+                    const accounts = await expenseAccountsOf(su, a.company.id);
+                    if (accounts === null)
+                        throw noChart('expense.advance');
+                    const money = await moneyAccount(su, 'expense.advance', a.paymentJournal);
+                    const entry = await post(su, a.company.id, money.journal, `${a.name} paid out`, [
+                        {
+                            account: accounts.advances,
+                            debit: a.amount,
+                            credit: ZERO,
+                            name: `${a.name} ${a.employee.name}`,
+                        },
+                        {
+                            account: money.account,
+                            debit: ZERO,
+                            credit: a.amount,
+                            name: `${a.name} ${a.employee.name}`,
+                        },
+                    ]);
+                    await su
+                        .model('expense.advance')
+                        .browse([a.id])
+                        .write({ entry });
+                }
+            });
+        },
+        // The settlement: what is left comes back to the cash or bank journal.
+        settledOut: async function (next) {
+            await next();
+            const advances = this;
+            const env = advances.env;
+            await env.asSuperuser({ reason: 'book advance returns' }, async (su) => {
+                for (const a of await su
+                    .model('expense.advance')
+                    .browse(advances.ids)
+                    .load({ company: true, employee: true })) {
+                    const left = a.balance ?? ZERO;
+                    if (left.lte(0))
+                        continue;
+                    const accounts = await expenseAccountsOf(su, a.company.id);
+                    if (accounts === null)
+                        throw noChart('expense.advance');
+                    const money = await moneyAccount(su, 'expense.advance', a.paymentJournal);
+                    const entry = await post(su, a.company.id, money.journal, `${a.name} returned`, [
+                        {
+                            account: money.account,
+                            debit: left,
+                            credit: ZERO,
+                            name: `${a.name} ${a.employee.name}`,
+                        },
+                        {
+                            account: accounts.advances,
+                            debit: ZERO,
+                            credit: left,
+                            name: `${a.name} ${a.employee.name}`,
+                        },
+                    ]);
+                    await su
+                        .model('expense.advance')
+                        .browse([a.id])
+                        .write({ returnEntry: entry });
+                }
+            });
+        },
+    },
+});
+export const expenseAccountShutro = defineModule({
+    name: 'expense_account',
+    version: '0.1.0',
+    depends: [expenseShutro, accountingShutro],
+    groups: [
+        orm.defineGroup({
+            code: 'expense_account.user',
+            label: 'Spend in the books',
+            implies: ['expense.user'],
+        }),
+    ],
+    models: [],
+    extensions: [CategoryAccount, SheetBooks, AdvanceBooks],
+});

package/dist/helpdesk/.kosh/bindings.d.ts

@@ -0,0 +1,22 @@
+export { defineModel, defineModule, extendModel, f, replace } from '../../server/orm.js';
+import { type DefinitionHelpers } from '../../server/orm.js';
+import type { DefaultLoaded, Env as CoreEnv, RecordSet as CoreRecordSet, Shutro as CoreShutro } from '../../server/orm.js';
+import type { SchemaView } from './schema.js';
+export type { SchemaView };
+/** Every model visible in this view. */
+export type ModelName = keyof SchemaView & string;
+/** `Env` typed to this view. */
+export type Env = CoreEnv<SchemaView>;
+/** `Shutro` typed to this view. */
+export type Shutro = CoreShutro<SchemaView>;
+/** A recordset of `M`, with the default loaded shape unless `L` is given. */
+export type Records<M extends ModelName, L = DefaultLoaded<SchemaView, M>> = CoreRecordSet<SchemaView, M, L>;
+export declare const compute: DefinitionHelpers<SchemaView>['compute'];
+export declare const check: DefinitionHelpers<SchemaView>['check'];
+export declare const onchange: DefinitionHelpers<SchemaView>['onchange'];
+export declare const records: DefinitionHelpers<SchemaView>['records'];
+export declare const method: DefinitionHelpers<SchemaView>['method'];
+/** Module data (RFC 0017): records, overrides of dependencies' records, and references, typed like creates. */
+export declare const record: DefinitionHelpers<SchemaView>['record'];
+export declare const override: DefinitionHelpers<SchemaView>['override'];
+export declare const ref: DefinitionHelpers<SchemaView>['ref'];

package/dist/helpdesk/.kosh/bindings.js

@@ -0,0 +1,15 @@
+// GENERATED by `pnpm generate:models` (Shutro’s generator). Do not edit. definitions-hash: ddd7d7982ac2630d
+// Bindings of module `helpdesk`: import the definition API from here to get types scoped to what it can see.
+export { defineModel, defineModule, extendModel, f, replace } from '../../server/orm.js';
+import { definitions } from '../../server/orm.js';
+/** Definition callbacks typed against this module's view: no casts in computes, checks, onchange, methods. */
+const helpers = definitions();
+export const compute = helpers.compute;
+export const check = helpers.check;
+export const onchange = helpers.onchange;
+export const records = helpers.records;
+export const method = helpers.method;
+/** Module data (RFC 0017): records, overrides of dependencies' records, and references, typed like creates. */
+export const record = helpers.record;
+export const override = helpers.override;
+export const ref = helpers.ref;