shutro-erp 0.3.4 → 0.3.5

package/dist/pos/accounting.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A closed session in the books (RFC 0021, Counter step 2): one entry in the shop's sales journal — the sales'
+ * untaxed amounts to the journal's income account, each tax to its account, the payments per method to their
+ * journals' accounts (cash less the change given), and the cash difference at closing to the shop's difference
+ * account — posted as the cashier with the posting grant. A shop without a sales journal books nothing.
+ */
+import { type Id } from '../server/orm.js';
+import type { Env } from './.kosh/bindings.js';
+/** Books the closed sessions that have a sales journal; returns the entries made, by session. */
+export declare function bookSessions(env: Env, ids: readonly Id<'pos.session'>[]): Promise<Map<number, number>>;

package/dist/pos/accounting.js

@@ -0,0 +1,149 @@
+/**
+ * A closed session in the books (RFC 0021, Counter step 2): one entry in the shop's sales journal — the sales'
+ * untaxed amounts to the journal's income account, each tax to its account, the payments per method to their
+ * journals' accounts (cash less the change given), and the cash difference at closing to the shop's difference
+ * account — posted as the cashier with the posting grant. A shop without a sales journal books nothing.
+ */
+import { orm } from '../server/orm.js';
+const ZERO = orm.toDecimal(0);
+/** Books the closed sessions that have a sales journal; returns the entries made, by session. */
+export async function bookSessions(env, ids) {
+    const out = new Map();
+    const sessions = await env
+        .model('pos.session')
+        .browse(ids)
+        .load({
+        shop: { salesJournal: true, differenceAccount: true },
+        company: { currency: true },
+        orders: { lines: { taxes: true }, payments: { method: { journal: true } } },
+    });
+    for (const s of sessions) {
+        if (s.state !== 'closed' || s.entry !== null)
+            continue;
+        const journal = s.shop.salesJournal;
+        if (journal === null)
+            continue;
+        const income = journal.defaultAccount?.id ?? null;
+        if (income === null)
+            throw new orm.ValidationError('pos.session', ['state'], `The sales journal ${journal.code} of ${s.shop.name} has no default account.`, 'Set the income account as the journal’s default account (Accounting › Configuration).');
+        const lines = [];
+        const add = (account, debit, credit, name) => {
+            const existing = lines.find((l) => l.account === account && l.name === name);
+            if (existing === undefined)
+                lines.push({ account, debit, credit, name });
+            else {
+                existing.debit = existing.debit.plus(debit);
+                existing.credit = existing.credit.plus(credit);
+            }
+        };
+        let untaxed = ZERO;
+        const taxes = new Map();
+        const byMethod = new Map();
+        for (const o of s.orders) {
+            if (o.state !== 'paid')
+                continue;
+            for (const l of o.lines) {
+                untaxed = untaxed.plus(l.subtotal ?? ZERO);
+                // The line's tax, shared between its taxes in proportion to their rates (fixed taxes by their amount).
+                const lineTax = l.taxAmount ?? ZERO;
+                const parts = [...l.taxes].map((t) => ({
+                    tax: t,
+                    weight: t.amountType === 'percent' ? t.rate : t.fixedAmount.times(l.quantity),
+                }));
+                const total = parts.reduce((sum, p) => sum.plus(p.weight), ZERO);
+                for (const p of parts) {
+                    const share = total.isZero()
+                        ? ZERO
+                        : lineTax.times(p.weight).div(total).toDecimalPlaces(2);
+                    const slot = taxes.get(p.tax.id) ?? {
+                        account: p.tax.account?.id ?? null,
+                        name: p.tax.name,
+                        amount: ZERO,
+                    };
+                    slot.amount = slot.amount.plus(share);
+                    taxes.set(p.tax.id, slot);
+                }
+            }
+            for (const p of o.payments) {
+                const slot = byMethod.get(p.method.id) ?? {
+                    account: p.method.journal?.defaultAccount?.id ?? null,
+                    name: p.method.name,
+                    amount: ZERO,
+                };
+                slot.amount = slot.amount.plus(p.amount);
+                byMethod.set(p.method.id, slot);
+            }
+            // The change comes out of the cash taken.
+            const change = o.change ?? ZERO;
+            if (change.gt(0)) {
+                const cash = [...o.payments].find((p) => p.method.kind === 'cash');
+                if (cash !== undefined) {
+                    const slot = byMethod.get(cash.method.id);
+                    if (slot !== undefined)
+                        slot.amount = slot.amount.minus(change);
+                }
+            }
+        }
+        add(income, ZERO, untaxed, `${s.name} sales`);
+        for (const t of taxes.values())
+            add(t.account ?? income, ZERO, t.amount, `${s.name} ${t.name}`);
+        for (const m of byMethod.values()) {
+            if (m.account === null)
+                throw new orm.ValidationError('pos.session', ['state'], `The payment method ${m.name} has no journal with a default account.`, 'Give the method a journal (Counter › Shops).');
+            add(m.account, m.amount, ZERO, `${s.name} ${m.name}`);
+        }
+        const difference = s.closingDifference ?? ZERO;
+        if (!difference.isZero()) {
+            // More cash than expected: the drawer holds it (debit), a gain (credit); less: a loss.
+            const cash = [...byMethod.values()].find((m) => m.account !== null);
+            const differenceAccount = s.shop.differenceAccount?.id ?? income;
+            if (cash?.account !== null && cash !== undefined) {
+                if (difference.gt(0)) {
+                    add(cash.account, difference, ZERO, `${s.name} cash counted over`);
+                    add(differenceAccount, ZERO, difference, `${s.name} cash difference`);
+                }
+                else {
+                    add(differenceAccount, difference.neg(), ZERO, `${s.name} cash difference`);
+                    add(cash.account, ZERO, difference.neg(), `${s.name} cash counted short`);
+                }
+            }
+        }
+        const debit = lines.reduce((sum, l) => sum.plus(l.debit), ZERO);
+        const credit = lines.reduce((sum, l) => sum.plus(l.credit), ZERO);
+        if (debit.isZero() && credit.isZero())
+            continue;
+        if (!debit.minus(credit).abs().lt(orm.toDecimal('0.05')))
+            throw new orm.ValidationError('pos.session', ['state'], `${s.name} does not balance (${debit.toString()} against ${credit.toString()}).`, 'Check the sales’ taxes and payments.');
+        // Rounding of tax shares: the last cent goes with the income.
+        const gap = debit.minus(credit);
+        if (!gap.isZero())
+            add(income, ZERO, gap, `${s.name} rounding`);
+        const made = await env.model('account.move').create([
+            {
+                kind: 'entry',
+                journal: journal.id,
+                company: s.company.id,
+                currency: s.company.currency.id,
+                date: env.today(),
+                ref: `${s.name} (${s.shop.name})`,
+                lines: {
+                    create: lines.map((l) => ({
+                        ...l,
+                        debit: l.debit.toString(),
+                        credit: l.credit.toString(),
+                    })),
+                },
+            },
+        ]);
+        await env.withGrants({ grants: ['account.post'], reason: `counter session ${s.name}` }, (e) => e.model('account.move').browse(made.ids).post());
+        const entry = made.ids[0];
+        if (entry !== undefined) {
+            await env
+                .model('pos.session')
+                .browse([s.id])
+                .write({ entry });
+            out.set(s.id, entry);
+        }
+    }
+    return out;
+}

package/dist/pos/demo.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Counter's demo data (RFC 0008 §5.8): the shop with cash and card, a session opened by the cashier with the
+ * drawer's cash, and two sales paid — one by card, one in cash with change given.
+ */
+import type { DemoContext } from '../modules-sdk/index.js';
+export declare function posDemo(ctx: DemoContext): Promise<string>;

package/dist/pos/demo.js

@@ -0,0 +1,90 @@
+import { orm } from '../server/orm.js';
+const DINA = { login: 'dina', name: 'Dina Rahman', groups: ['pos.manager'] };
+const RAHIM = { login: 'rahim', name: 'Rahim Uddin', groups: ['pos.cashier'] };
+export async function posDemo(ctx) {
+    let shop;
+    let cash;
+    let card;
+    await ctx.as(DINA, async (raw) => {
+        const env = raw;
+        const [journal] = (await env.model('account.journal').search({ where: { type: 'sale' }, limit: 1 })).ids;
+        const made = await env.model('pos.shop').create([
+            {
+                name: 'Padma Shop, Dhanmondi',
+                pricesIncludeTax: true,
+                receiptFooter: 'Thank you — exchanges within 7 days with this receipt.',
+                ...(journal === undefined ? {} : { salesJournal: journal }),
+                methods: {
+                    create: [
+                        { name: 'Cash', kind: 'cash', sequence: 1 },
+                        { name: 'Card', kind: 'card', sequence: 2 },
+                        { name: 'bKash', kind: 'mobile', sequence: 3 },
+                    ],
+                },
+            },
+        ]);
+        shop = made.ids[0];
+        if (shop === undefined)
+            return;
+        const methods = await env
+            .model('pos.payment.method')
+            .search({ where: { shop: shop } });
+        for (const m of methods) {
+            if (m.kind === 'cash')
+                cash = m.id;
+            if (m.kind === 'card')
+                card = m.id;
+        }
+    });
+    if (shop === undefined || cash === undefined || card === undefined)
+        return 'Counter: no shop';
+    await ctx.as(RAHIM, async (raw) => {
+        const env = raw;
+        const session = await env
+            .model('pos.session')
+            .create([{ shop: shop, openingCash: orm.toDecimal('5000') }]);
+        const [sessionId] = session.ids;
+        if (sessionId === undefined)
+            return;
+        const products = await env
+            .model('product.product')
+            .search({ where: { saleOk: true, kind: 'goods' }, order: ['id asc'], limit: 2 });
+        const [first, second] = [...products];
+        if (first === undefined)
+            return;
+        const sale = async (lines, payments, clientId) => {
+            const made = await env.model('pos.order').create([
+                {
+                    session: sessionId,
+                    clientId,
+                    lines: {
+                        create: lines.map((l) => ({
+                            product: l.product.id,
+                            name: l.product.name,
+                            quantity: orm.toDecimal(l.quantity),
+                            priceUnit: l.product.listPrice,
+                            discount: orm.toDecimal(0),
+                        })),
+                    },
+                    payments: {
+                        create: payments.map((p) => ({ method: p.method, amount: orm.toDecimal(p.amount) })),
+                    },
+                },
+            ]);
+            await env.flush();
+            await made.pay();
+        };
+        const price = (p, qty) => p.listPrice.times(qty).toString();
+        await sale([{ product: first, quantity: '2' }], [{ method: card, amount: price(first, 2) }], 'demo-1');
+        if (second !== undefined) {
+            const due = second.listPrice.plus(first.listPrice);
+            const given = due.plus(100);
+            await sale([
+                { product: second, quantity: '1' },
+                { product: first, quantity: '1' },
+            ], [{ method: cash, amount: given.toString() }], 'demo-2');
+            void due;
+        }
+    });
+    return 'Counter: a shop with 3 payment methods, an open session, 2 sales';
+}

package/dist/pos/index.d.ts

@@ -0,0 +1,9 @@
+import { defineModule } from '../modules-sdk/index.js';
+import { type CounterOptions } from './routes.js';
+export { bookSessions } from './accounting.js';
+export { amountOf, PosOrder, PosOrderLine, PosOrderPayment, PosPaymentMethod, PosSession, PosShop, posShutro, } from './module.js';
+export { type CounterOptions, registerCounterRoutes, type SaleInput } from './routes.js';
+/** Counter with explicit options (tests: a memory mailer and messenger for receipts). */
+export declare function posModule(options?: CounterOptions): ReturnType<typeof defineModule>;
+/** Counter: SMTP and the text messenger from the environment for receipts. */
+export declare const pos: ReturnType<typeof defineModule>;

package/dist/pos/index.js

@@ -0,0 +1,349 @@
+/**
+ * @packageDocumentation
+ * `shutro-erp/pos` (RFC 0021): the **Counter** app. Shops with their payment methods, cashiers' sessions with opening
+ * and closing counts, sales with lines, taxes, several payments and the change — accepted once per device
+ * reference — and the register, a page for a tablet or a phone. Receipts are documents. What a closed session
+ * means to Stockroom and Accounting is the bridges' (`pos_stock`, `pos_account`).
+ */
+import { accounting } from '../accounting/index.js';
+import { contacts } from '../contacts/index.js';
+import { messaging } from '../messaging/index.js';
+import { defineModule } from '../modules-sdk/index.js';
+import { product } from '../product/index.js';
+import { reporting } from '../reporting/index.js';
+import { action, form, list, search } from '../views/index.js';
+import { posDemo } from './demo.js';
+import { PosOrder, PosPaymentMethod, PosSession, PosShop, posShutro } from './module.js';
+import { registerCounterRoutes } from './routes.js';
+export { bookSessions } from './accounting.js';
+export { amountOf, PosOrder, PosOrderLine, PosOrderPayment, PosPaymentMethod, PosSession, PosShop, posShutro, } from './module.js';
+export { registerCounterRoutes } from './routes.js';
+/** Counter with explicit options (tests: a memory mailer and messenger for receipts). */
+export function posModule(options = {}) {
+    return defineModule({
+        shutro: posShutro,
+        kosh: '^0.1.0',
+        hooks: { demo: posDemo },
+        depends: [product, contacts, accounting, messaging, reporting],
+        app: {
+            code: 'counter',
+            label: 'Counter',
+            icon: 'counter',
+            sequence: 43,
+            category: 'Sales',
+            summary: 'Point of sale: sessions, split payments, receipts, the register on a tablet',
+        },
+        accessLevels: {
+            cashier: { label: 'Cashier (sell in own sessions)', groups: ['pos.cashier'] },
+            manager: {
+                label: 'Manager (shops, methods, every session)',
+                groups: ['pos.manager'],
+                implies: ['cashier'],
+            },
+        },
+        events: [{ topic: 'pos.order.paid', model: 'pos.order', label: 'Sale paid at the counter' }],
+        documents: [
+            {
+                key: 'receipt',
+                name: 'Receipt',
+                model: 'pos.order',
+                layout: {
+                    paper: 'A4',
+                    header: '{{company.name}}',
+                    blocks: [
+                        { kind: 'heading', id: 'title', text: '{{name}}', level: 1 },
+                        {
+                            kind: 'fields',
+                            id: 'when',
+                            items: [
+                                { label: 'Date', bind: 'date' },
+                                { label: 'Session', bind: 'session.name' },
+                                { label: 'Customer', bind: 'partner.name' },
+                            ],
+                        },
+                        {
+                            kind: 'table',
+                            id: 'lines',
+                            bind: 'lines',
+                            columns: [
+                                { label: 'Item', bind: 'name' },
+                                { label: 'Qty', bind: 'quantity' },
+                                { label: 'Price', bind: 'priceUnit' },
+                                { label: 'Amount', bind: 'subtotal' },
+                            ],
+                        },
+                        {
+                            kind: 'fields',
+                            id: 'totals',
+                            items: [
+                                { label: 'Untaxed', bind: 'amountUntaxed' },
+                                { label: 'Taxes', bind: 'amountTax' },
+                                { label: 'Total', bind: 'total' },
+                                { label: 'Paid', bind: 'amountPaid' },
+                                { label: 'Change', bind: 'change' },
+                            ],
+                        },
+                        { kind: 'qr', id: 'qr', bind: 'name', size: 30, label: 'Sale reference' },
+                        { kind: 'text', id: 'footer', text: '{{session.shop.receiptFooter}}' },
+                    ],
+                },
+            },
+        ],
+        routes: (context) => registerCounterRoutes(context, options),
+        overview: {
+            cards: [
+                {
+                    id: 'sold_today',
+                    title: 'Sold this month',
+                    kind: 'kpi',
+                    model: 'pos.order',
+                    measure: 'sum:total',
+                    filter: { state: 'paid' },
+                    comparison: { field: 'date', mode: 'previous' },
+                    w: 3,
+                },
+                {
+                    id: 'sales_month',
+                    title: 'Sales this month',
+                    kind: 'kpi',
+                    model: 'pos.order',
+                    measure: 'count',
+                    filter: { state: 'paid' },
+                    comparison: { field: 'date', mode: 'previous' },
+                    w: 3,
+                },
+                {
+                    id: 'open_sessions',
+                    title: 'Open sessions',
+                    kind: 'kpi',
+                    model: 'pos.session',
+                    measure: 'count',
+                    filter: { state: 'open' },
+                    w: 3,
+                },
+                {
+                    id: 'average_sale',
+                    title: 'Average sale',
+                    kind: 'kpi',
+                    model: 'pos.order',
+                    measure: 'avg:total',
+                    filter: { state: 'paid' },
+                    w: 3,
+                },
+                {
+                    id: 'by_day',
+                    title: 'Sold by day',
+                    kind: 'chart',
+                    model: 'pos.order',
+                    measure: 'sum:total',
+                    groupBy: 'date:day',
+                    filter: { state: 'paid' },
+                    chart: 'bar',
+                    w: 6,
+                },
+                {
+                    id: 'by_method',
+                    title: 'By payment method',
+                    kind: 'chart',
+                    model: 'pos.order.payment',
+                    measure: 'sum:amount',
+                    groupBy: 'method',
+                    chart: 'pie',
+                    w: 6,
+                },
+                {
+                    id: 'top_products',
+                    title: 'Best sellers',
+                    kind: 'pivot',
+                    model: 'pos.order.line',
+                    measure: 'sum:quantity',
+                    groupBy: 'product',
+                    w: 6,
+                },
+                {
+                    id: 'differences',
+                    title: 'Closing differences',
+                    kind: 'list',
+                    model: 'pos.session',
+                    measure: 'sum:closingDifference',
+                    filter: { state: 'closed' },
+                    w: 6,
+                },
+            ],
+        },
+        actions: {
+            'counter.action_register': { type: 'client', page: 'counter.Register', label: 'Register' },
+            'counter.action_sessions': action(PosSession, { label: 'Sessions', views: ['list', 'form'] }),
+            'counter.action_orders': action(PosOrder, {
+                label: 'Sales',
+                views: ['list', 'form'],
+                defaultFilters: ['paid'],
+            }),
+            'counter.action_shops': action(PosShop, {
+                label: 'Shops',
+                views: ['list', 'form'],
+                visibleTo: ['pos.manager'],
+            }),
+        },
+        menus: [
+            { id: 'counter.root', label: 'Counter', app: 'counter' },
+            {
+                id: 'counter.register',
+                parent: 'counter.root',
+                label: 'Register',
+                action: 'counter.action_register',
+                sequence: 1,
+            },
+            {
+                id: 'counter.sessions',
+                parent: 'counter.root',
+                label: 'Sessions',
+                action: 'counter.action_sessions',
+                sequence: 2,
+            },
+            {
+                id: 'counter.orders',
+                parent: 'counter.root',
+                label: 'Sales',
+                action: 'counter.action_orders',
+                sequence: 3,
+            },
+            {
+                id: 'counter.shops',
+                parent: 'counter.root',
+                label: 'Shops',
+                action: 'counter.action_shops',
+                sequence: 9,
+                visibleTo: ['pos.manager'],
+            },
+        ],
+        views: {
+            'pos.session.list': list(PosSession, {
+                columns: [
+                    'name',
+                    'shop',
+                    'cashier',
+                    'openedAt',
+                    'closedAt',
+                    'orderCount',
+                    { field: 'total', sum: true },
+                    'expectedCash',
+                    'closingCash',
+                    'closingDifference',
+                    { field: 'state', widget: 'badge' },
+                ],
+                decorations: {
+                    success: { state: 'closed', closingDifference: '0' },
+                    warning: { state: 'open' },
+                },
+            }),
+            'pos.session.form': form(PosSession, (k) => ({
+                header: {
+                    statusbar: 'state',
+                    buttons: [k.button('close', { primary: true, label: 'Close the session' })],
+                },
+                sheet: [
+                    k.group('main', ['name', 'shop', 'cashier', 'openedAt', 'closedAt']),
+                    k.group('cash', ['openingCash', 'expectedCash', 'closingCash', 'closingDifference', 'differenceReason'], {
+                        label: 'Cash',
+                        description: 'Count the drawer before closing; a difference needs a reason.',
+                    }),
+                    k.group('totals', ['orderCount', 'total', 'entry'], { label: 'Totals' }),
+                ],
+                chatter: true,
+            })),
+            'pos.order.list': list(PosOrder, {
+                columns: [
+                    'name',
+                    'date',
+                    'session',
+                    'partner',
+                    { field: 'total', sum: true },
+                    { field: 'amountTax', sum: true },
+                    'change',
+                    { field: 'state', widget: 'badge' },
+                ],
+                decorations: { neutral: { state: 'void' } },
+            }),
+            'pos.order.form': form(PosOrder, (k) => ({
+                header: {
+                    statusbar: 'state',
+                    buttons: [
+                        k.button('pay', { primary: true, label: 'Mark paid' }),
+                        k.button('void', { label: 'Void' }),
+                    ],
+                },
+                sheet: [
+                    k.group('main', [
+                        'name',
+                        'session',
+                        'date',
+                        'partner',
+                        'refundOf',
+                        'refundReason',
+                        'note',
+                    ]),
+                    k.lines('lines', [
+                        'product',
+                        { field: 'name', id: 'line_name' },
+                        'quantity',
+                        'priceUnit',
+                        'discount',
+                        'taxes',
+                        'subtotal',
+                        'taxAmount',
+                    ]),
+                    k.lines('payments', ['method', { field: 'amount', id: 'payment_amount' }, 'reference']),
+                    k.group('totals', ['amountUntaxed', 'amountTax', 'total', 'amountPaid', 'change'], {
+                        label: 'Totals',
+                    }),
+                    k.lines('refunds', [
+                        { field: 'name', id: 'refund_name' },
+                        { field: 'date', id: 'refund_date' },
+                        { field: 'refundReason', id: 'refund_reason' },
+                        { field: 'total', id: 'refund_total' },
+                    ]),
+                ],
+                chatter: true,
+            })),
+            'pos.shop.list': list(PosShop, { columns: ['name', 'pricesIncludeTax', 'salesJournal'] }),
+            'pos.shop.form': form(PosShop, (k) => ({
+                header: { buttons: [] },
+                sheet: [
+                    k.group('main', [
+                        'name',
+                        'pricesIncludeTax',
+                        'salesJournal',
+                        'differenceAccount',
+                        'receiptFooter',
+                    ]),
+                    k.lines('methods', [{ field: 'name', id: 'method_name' }, 'kind', 'journal', 'sequence']),
+                ],
+            })),
+            'pos.payment.method.list': list(PosPaymentMethod, {
+                columns: ['name', 'shop', 'kind', 'journal'],
+            }),
+        },
+        search: {
+            'pos.session': search(PosSession, {
+                fields: ['name', 'shop.name', 'cashier.name'],
+                filters: {
+                    open: { label: 'Open', domain: { state: 'open' }, group: 'state' },
+                    closed: { label: 'Closed', domain: { state: 'closed' }, group: 'state' },
+                },
+                groupBy: ['shop', 'cashier', 'state', 'openedAt:day'],
+            }),
+            'pos.order': search(PosOrder, {
+                fields: ['name', 'partner.name', 'note'],
+                filters: {
+                    paid: { label: 'Paid', domain: { state: 'paid' }, group: 'state' },
+                    voided: { label: 'Voided', domain: { state: 'void' }, group: 'state' },
+                },
+                groupBy: ['session', 'partner', 'date:day'],
+            }),
+            'pos.shop': search(PosShop, { fields: ['name'] }),
+        },
+    });
+}
+/** Counter: SMTP and the text messenger from the environment for receipts. */
+export const pos = posModule();