shutro-erp 0.3.4 → 0.3.6

package/dist/website_sale/module.js

@@ -0,0 +1,397 @@
+/**
+ * The data layer of the Shop (RFC 0024 §2.7, in Sites): products published on a site's shop with a description in
+ * English and Bangla, a weight and related products; delivery methods with their fee — fixed, by weight or by zone
+ * (inside a set of cities, Dhaka, or outside) — free above an amount, cash on delivery or not; carts, which are
+ * quotations of the site's company with a secret token and the method chosen; and online payments of a shop's order,
+ * which confirm it, invoice it and register the payment once the provider confirms.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { paymentShutro } from '../payment/index.js';
+import { productShutro } from '../product/index.js';
+import { saleAccountShutro } from '../sale_account/index.js';
+import { salesShutro } from '../sales/index.js';
+import { orm } from '../server/orm.js';
+import { websiteShutro } from '../website/index.js';
+import { check, defineModel, defineModule, extendModel, f, method, records, } from './.kosh/bindings.js';
+import { courierOf } from './couriers.js';
+const ALL = ['read', 'write', 'create', 'unlink', 'export', 'import'];
+const zero = orm.toDecimal(0);
+/** A cart's secret: given to the visitor once; only its hash is kept. */
+export const newCartToken = () => randomBytes(24).toString('base64url');
+export const hashToken = (token) => createHash('sha256').update(token).digest('hex');
+/** The couriers whose adapters book shipments (RFC 0024 §2.7; the adapters come with part 2). */
+export const COURIERS = {
+    none: 'None (delivered by hand)',
+    fake: 'Test courier',
+    pathao: 'Pathao',
+    steadfast: 'Steadfast',
+    redx: 'RedX',
+};
+export const ProductShop = extendModel('product.product', {
+    fields: {
+        /** Shown on the sites' shops. */
+        published: f.boolean({ default: false, label: 'On the shop' }),
+        /** What the shop says about it (English and Bangla). */
+        websiteDescription: f.text({ translate: true, label: 'Shop description' }),
+        /** For fees by weight, in kg. */
+        weight: f.decimal({ scale: 3, label: 'Weight (kg)' }),
+        /** Shown with it on its page. */
+        related: f.many2many('product.product', {
+            relation: 'product_shop_related_rel',
+            label: 'Related products',
+        }),
+        /** The order on the shop (lowest first). */
+        shopSequence: f.integer({ required: true, default: 10, label: 'Shop order' }),
+        /** What search engines show (the name when empty), in English and Bangla. */
+        seoTitle: f.char({ translate: true, label: 'Search title' }),
+        seoDescription: f.text({ translate: true, label: 'Search description' }),
+    },
+    methods: {
+        /**
+         * What each of these products has available for the shop, in its unit (a decimal string), or null when stock is
+         * not followed. Null here; `website_sale_stock` says what Stockroom has.
+         */
+        shopAvailable: method('product.product', async function () {
+            return new Map(this.ids.map((id) => [id, null]));
+        }),
+    },
+});
+export const SiteShop = extendModel('website.site', {
+    fields: {
+        /** The site sells: its shop's API answers. */
+        shop: f.boolean({ default: false, label: 'Shop' }),
+        /** Cash-on-delivery orders above this stay quotations until someone confirms them (empty: no limit). */
+        codLimit: f.decimal({ scale: 2, label: 'Cash on delivery up to' }),
+        /** Who shop orders are assigned to (the site's creator when empty). */
+        salesperson: f.many2one('res.users', { ondelete: 'set null', label: 'Shop orders for' }),
+        /** With stock shown (`website_sale_stock`): at most this many is "few left". */
+        fewLeft: f.integer({ required: true, default: 5, label: 'Few left from' }),
+        /** With stock shown: whether more than is available may be ordered. */
+        allowBackorders: f.boolean({ default: true, label: 'Sell beyond stock' }),
+        /** Carts left this many hours with an email get one reminder (0: never). */
+        abandonedHours: f.integer({
+            required: true,
+            default: 24,
+            label: 'Remind abandoned carts after (h)',
+        }),
+        /** Who carts belong to before checkout (made with the first cart). */
+        visitor: f.many2one('res.partner', { ondelete: 'set null', label: 'Shop visitor' }),
+    },
+});
+export const DeliveryCarrier = defineModel('delivery.carrier', {
+    label: 'Delivery method',
+    recName: 'name',
+    order: ['sequence asc', 'id asc'],
+    archivable: true,
+    companyScoped: { required: true },
+    tracking: ['kind', 'price', 'freeOver'],
+    access: { 'sales.user': ['read'], 'sales.manager': ALL, 'website.manager': ALL },
+    fields: {
+        name: f.char({ required: true, translate: true }),
+        kind: f.selection({ fixed: 'Fixed fee', weight: 'By weight', zone: 'By zone' }, { required: true, default: 'fixed', label: 'Fee by' }),
+        /** The fixed fee; by weight, the fee of the first kg. */
+        price: f.decimal({ scale: 2, required: true, default: '0', label: 'Fee' }),
+        /** By weight: each kg (or part of one) beyond the first. */
+        pricePerKg: f.decimal({ scale: 2, required: true, default: '0', label: 'Each further kg' }),
+        /** By zone: the cities inside, comma separated (`Dhaka`). */
+        zoneCities: f.char({ default: 'Dhaka', label: 'Inside: cities' }),
+        priceInside: f.decimal({ scale: 2, required: true, default: '0', label: 'Fee inside' }),
+        priceOutside: f.decimal({ scale: 2, required: true, default: '0', label: 'Fee outside' }),
+        /** Free when the goods come to this much or more (empty: never). */
+        freeOver: f.decimal({ scale: 2, label: 'Free from' }),
+        /** Customers may pay the courier on delivery. */
+        cod: f.boolean({ default: true, label: 'Cash on delivery' }),
+        courier: f.selection(COURIERS, { required: true, default: 'none', label: 'Courier' }),
+        /** The service product the fee is charged as on orders (made with the method). */
+        product: f.many2one('product.product', { ondelete: 'restrict', label: 'Fee product' }),
+        sequence: f.integer({ required: true, default: 10 }),
+        description: f.text({ translate: true }),
+    },
+    sqlConstraints: {
+        fees: {
+            check: orm.sql `price >= 0 AND price_per_kg >= 0 AND price_inside >= 0 AND price_outside >= 0 AND (free_over IS NULL OR free_over >= 0)`,
+            message: 'Fees are zero or more.',
+        },
+    },
+});
+/** The fee of `carrier` for goods worth `amount` weighing `weight` kg, delivered to `city`. */
+export function feeOf(carrier, amount, weight, city) {
+    if (carrier.freeOver !== null && amount.gte(carrier.freeOver))
+        return zero;
+    if (carrier.kind === 'weight') {
+        const beyond = weight.minus(1);
+        return carrier.price.plus(beyond.gt(0) ? beyond.ceil().times(carrier.pricePerKg) : zero);
+    }
+    if (carrier.kind === 'zone') {
+        const inside = (carrier.zoneCities ?? '')
+            .split(',')
+            .map((c) => c.trim().toLowerCase())
+            .filter((c) => c !== '');
+        const here = (city ?? '').trim().toLowerCase();
+        return here !== '' && inside.includes(here) ? carrier.priceInside : carrier.priceOutside;
+    }
+    return carrier.price;
+}
+/**
+ * A coupon of the shop (RFC 0024 §2.7): a code that takes a percentage off the goods, an amount off, or the delivery
+ * fee — from a minimum, between two dates, up to a number of uses, once per customer if it says so.
+ */
+export const ShopCoupon = defineModel('shop.coupon', {
+    label: 'Coupon',
+    recName: 'code',
+    order: ['code asc'],
+    archivable: true,
+    companyScoped: { required: true },
+    tracking: ['value', 'validTo', 'maxUses'],
+    access: { 'sales.user': ['read'], 'sales.manager': ALL, 'website.manager': ALL },
+    fields: {
+        /** What the customer types (upper case). */
+        code: f.char({ required: true, size: 40 }),
+        name: f.char({ translate: true, label: 'What it gives' }),
+        kind: f.selection({ percent: 'Percentage off the goods', amount: 'Amount off', free_delivery: 'Free delivery' }, { required: true, default: 'percent', label: 'Gives' }),
+        value: f.decimal({ scale: 2, required: true, default: '0', label: 'Value' }),
+        /** The goods must come to this much. */
+        minimum: f.decimal({ scale: 2, required: true, default: '0', label: 'From' }),
+        validFrom: f.date({ label: 'Valid from' }),
+        validTo: f.date({ label: 'Valid until' }),
+        /** Empty: as often as it is used. */
+        maxUses: f.integer({ label: 'Uses at most' }),
+        uses: f.integer({ required: true, default: 0, label: 'Used' }),
+        oncePerCustomer: f.boolean({ default: false, label: 'Once per customer' }),
+        /** The service product an amount off is charged as (made with its first use). */
+        product: f.many2one('product.product', { ondelete: 'set null', label: 'Discount product' }),
+    },
+    sqlConstraints: {
+        oneCode: { unique: ['company', 'code'], message: 'Another coupon has this code.' },
+        values: {
+            check: orm.sql `value >= 0 AND minimum >= 0 AND (kind <> 'percent' OR value <= 100) AND (max_uses IS NULL OR max_uses > 0)`,
+            message: 'A coupon gives zero or more (a percentage up to 100), from zero or more.',
+        },
+        period: {
+            check: orm.sql `valid_from IS NULL OR valid_to IS NULL OR valid_to >= valid_from`,
+            message: 'A coupon ends on or after it starts.',
+        },
+    },
+    constraints: {
+        upperCase: {
+            ...check('shop.coupon', ['code'], async (coupons) => coupons.filter((c) => !/^[A-Z0-9_-]{2,40}$/.test(c.code)).map((c) => c.id)),
+            message: 'A code is 2 to 40 capital letters, digits, dashes or underscores (EID10).',
+        },
+    },
+});
+export const OrderShop = extendModel('sale.order', {
+    fields: {
+        /** The site the order was placed on. */
+        website: f.many2one('website.site', { ondelete: 'set null', label: 'Site' }),
+        /** The hash of the cart's secret token (the visitor holds the token). */
+        cartToken: f.char({ index: true, label: 'Cart token' }),
+        carrier: f.many2one('delivery.carrier', { ondelete: 'set null', label: 'Delivery method' }),
+        shopPayment: f.selection({ cod: 'Cash on delivery', online: 'Paid online' }, { label: 'Payment' }),
+        /** Placed by the customer (checked out); a cart before that. */
+        placedAt: f.datetime({ label: 'Placed at' }),
+        shopNote: f.text({ label: 'Customer note' }),
+        coupon: f.many2one('shop.coupon', { ondelete: 'set null', label: 'Coupon' }),
+        /** The email a visitor left on their cart (reminded once if they leave it). */
+        contactEmail: f.char({ label: 'Cart email' }),
+        /** The hash of the cart's recovery code, sent with the reminder. */
+        recoveryToken: f.char({ index: true, label: 'Recovery code' }),
+        remindedAt: f.datetime({ label: 'Reminded at' }),
+    },
+});
+export const LineShop = extendModel('sale.order.line', {
+    fields: {
+        /** The delivery fee's line (replaced when the method or the cart changes). */
+        isDelivery: f.boolean({ default: false, label: 'Delivery fee' }),
+        /** A coupon's amount off (replaced when the cart or the coupon changes). */
+        isDiscount: f.boolean({ default: false, label: 'Coupon discount' }),
+    },
+});
+export const TransactionOrder = extendModel('payment.transaction', {
+    fields: {
+        saleOrder: f.many2one('sale.order', { ondelete: 'set null', label: 'Sales order' }),
+    },
+    overrides: {
+        // A shop's order is confirmed, invoiced and its invoice posted when its payment is confirmed; the payment pays it.
+        payable: async function (next) {
+            const out = await next();
+            const txs = this;
+            const env = txs.env;
+            for (const t of await txs.load({ saleOrder: true })) {
+                if ((out.get(t.id) ?? []).length > 0 || t.saleOrder === null)
+                    continue;
+                const order = env.model('sale.order').browse([t.saleOrder.id]);
+                const [o] = await order.load({ invoices: true });
+                if (o === undefined)
+                    continue;
+                if (o.state === 'draft' || o.state === 'sent')
+                    await order.confirm();
+                let invoice = [...o.invoices].find((i) => i.state !== 'cancel')?.id;
+                if (invoice === undefined) {
+                    await order.invoice();
+                    const [again] = await order.load({ invoices: true });
+                    invoice = [...(again?.invoices ?? [])].find((i) => i.state !== 'cancel')?.id;
+                }
+                if (invoice === undefined)
+                    continue;
+                const move = env.model('account.move').browse([invoice]);
+                const [m] = await move.load({});
+                if (m?.state === 'draft')
+                    await move.post();
+                await txs.env.model('payment.transaction').browse([t.id]).write({ move: invoice });
+                out.set(t.id, [invoice]);
+            }
+            return out;
+        },
+    },
+});
+/**
+ * A shipment (RFC 0024 §2.7): a shop order's parcel with its courier — made as a draft when an order whose delivery
+ * method has a courier is confirmed, booked by the team (the courier's consignment id and label), then moved along by
+ * what the courier says (picked, in transit, delivered or returned) with its events; delivered with the cash to
+ * collect, the cash is collected.
+ */
+export const DeliveryShipment = defineModel('delivery.shipment', {
+    label: 'Shipment',
+    recName: 'name',
+    order: ['id desc'],
+    companyScoped: { required: true },
+    tracking: ['state', 'trackingRef'],
+    access: { 'sales.user': ['read', 'write', 'create'], 'sales.manager': ALL },
+    fields: {
+        name: f.char({
+            required: true,
+            readonly: true,
+            sequence: { code: 'delivery.shipment' },
+            label: 'Reference',
+        }),
+        order: f.many2one('sale.order', { required: true, ondelete: 'restrict', label: 'Order' }),
+        carrier: f.many2one('delivery.carrier', { required: true, ondelete: 'restrict' }),
+        courier: f.selection(COURIERS, { required: true, default: 'fake' }),
+        recipient: f.char({ required: true }),
+        phone: f.char({ required: true }),
+        address: f.char({ required: true }),
+        city: f.char({ required: true }),
+        /** The cash the courier collects (0: paid online). */
+        cod: f.decimal({ scale: 2, required: true, default: '0', label: 'Cash to collect' }),
+        weight: f.decimal({ scale: 3, required: true, default: '0', label: 'Weight (kg)' }),
+        trackingRef: f.char({ index: true, label: 'Consignment' }),
+        labelUrl: f.char({ label: 'Label' }),
+        codCollected: f.boolean({ default: false, label: 'Cash collected' }),
+        codCollectedAt: f.datetime({ label: 'Collected at' }),
+        events: f.one2many('delivery.shipment.event', 'shipment', { label: 'Tracking' }),
+        note: f.text(),
+        state: f.state({
+            states: {
+                draft: 'To book',
+                booked: 'Booked',
+                picked: 'Picked up',
+                in_transit: 'In transit',
+                delivered: 'Delivered',
+                returned: 'Returned',
+                cancel: 'Cancelled',
+            },
+            initial: 'draft',
+            transitions: {
+                /** Books the parcel with the courier: its consignment id and label. */
+                book: {
+                    from: ['draft'],
+                    to: 'booked',
+                    before: records('delivery.shipment', async (shipments) => {
+                        for (const s of await shipments.load({})) {
+                            const courier = courierOf(s.courier);
+                            if (courier === null)
+                                throw new orm.ValidationError('delivery.shipment', ['courier'], `The ${COURIERS[s.courier] ?? s.courier} courier is not set up on this server.`, 'Its credentials go in the server’s environment; the test courier always works.');
+                            let booked;
+                            try {
+                                booked = await courier.book({
+                                    reference: s.name,
+                                    recipient: {
+                                        name: s.recipient,
+                                        phone: s.phone,
+                                        address: s.address,
+                                        city: s.city,
+                                    },
+                                    cod: s.cod.toFixed(2),
+                                    weightKg: s.weight.toFixed(3),
+                                    note: s.note ?? '',
+                                });
+                            }
+                            catch (error) {
+                                throw new orm.ValidationError('delivery.shipment', ['courier'], `The courier refused the booking: ${error instanceof Error ? error.message : String(error)}`, 'Check the address and phone number, then book again.');
+                            }
+                            await s.write({ trackingRef: booked.trackingRef, labelUrl: booked.labelUrl ?? null });
+                            await shipments.env
+                                .model('delivery.shipment.event')
+                                .create([{ shipment: s.id, status: 'booked', note: 'Booked with the courier' }]);
+                        }
+                    }),
+                },
+                pick: { from: ['booked'], to: 'picked' },
+                transit: { from: ['booked', 'picked'], to: 'in_transit' },
+                deliver: {
+                    from: ['booked', 'picked', 'in_transit'],
+                    to: 'delivered',
+                    after: records('delivery.shipment', async (shipments) => {
+                        for (const s of await shipments.load({}))
+                            if (s.cod.gt(0) && !s.codCollected)
+                                await s.write({ codCollected: true, codCollectedAt: new Date() });
+                    }),
+                },
+                bounce: { from: ['booked', 'picked', 'in_transit'], to: 'returned' },
+                cancel: {
+                    from: ['draft', 'booked'],
+                    to: 'cancel',
+                    before: records('delivery.shipment', async (shipments) => {
+                        for (const s of await shipments.load({})) {
+                            if (s.trackingRef === null)
+                                continue;
+                            const courier = courierOf(s.courier);
+                            try {
+                                await courier?.cancel(s.trackingRef);
+                            }
+                            catch (error) {
+                                throw new orm.ValidationError('delivery.shipment', ['state'], `The courier did not cancel it: ${error instanceof Error ? error.message : String(error)}`, 'Ask the courier to return the parcel instead.');
+                            }
+                        }
+                    }),
+                },
+            },
+        }),
+    },
+    sqlConstraints: {
+        amounts: { check: orm.sql `cod >= 0 AND weight >= 0`, message: 'Amounts are zero or more.' },
+    },
+});
+export const DeliveryShipmentEvent = defineModel('delivery.shipment.event', {
+    label: 'Tracking event',
+    order: ['at asc', 'id asc'],
+    access: { 'sales.user': ['read', 'create'], 'sales.manager': ['read', 'create', 'unlink'] },
+    fields: {
+        shipment: f.many2one('delivery.shipment', { required: true, ondelete: 'cascade' }),
+        at: f.datetime({ required: true, default: () => new Date(), label: 'When' }),
+        status: f.char({ required: true }),
+        note: f.char(),
+    },
+});
+export const websiteSaleShutro = defineModule({
+    name: 'website_sale',
+    version: '0.3.0',
+    depends: [websiteShutro, salesShutro, saleAccountShutro, paymentShutro, productShutro],
+    groups: [
+        orm.defineGroup({
+            code: 'website_sale.manager',
+            label: 'Shop manager',
+            implies: ['website.manager', 'sales.manager'],
+        }),
+    ],
+    sequences: [
+        orm.defineSequence({
+            code: 'delivery.shipment',
+            prefix: 'SHP/{year}/',
+            padding: 5,
+            reset: 'yearly',
+        }),
+    ],
+    models: [DeliveryCarrier, DeliveryShipment, DeliveryShipmentEvent, ShopCoupon],
+    extensions: [ProductShop, SiteShop, OrderShop, LineShop, TransactionOrder],
+});

package/dist/website_sale/shipments.d.ts

@@ -0,0 +1,16 @@
+import type { Env } from './.kosh/bindings.js';
+/** Makes the draft shipment of each confirmed shop order of `ids` sent with a courier, once; returns how many. */
+export declare function draftShipments(env: Env, ids: readonly number[]): Promise<number>;
+/** Asks the couriers about the open shipments (those of `ids`, or all); returns how many moved. */
+export declare function refreshShipments(env: Env, ids?: readonly number[]): Promise<number>;
+/** A placed order's shipments as its customer may follow them. */
+export declare function trackingOf(env: Env, order: number): Promise<{
+    name: string;
+    state: string;
+    trackingRef: string | null;
+    events: {
+        at: string;
+        status: string;
+        note: string | null;
+    }[];
+}[]>;

package/dist/website_sale/shipments.js

@@ -0,0 +1,113 @@
+/**
+ * Shipments of shop orders (RFC 0024 §2.7): a draft for each confirmed shop order whose delivery method has a
+ * courier — once — with the customer's name, phone and address, the weight of its goods and, paid on delivery, the
+ * cash to collect; and tracking: what the courier says of each open shipment becomes its events and moves it along
+ * (picked, in transit, delivered — the cash collected — or returned).
+ */
+import { orm } from '../server/orm.js';
+import { courierOf } from './couriers.js';
+const zero = orm.toDecimal(0);
+const OPEN = ['booked', 'picked', 'in_transit'];
+/** The transitions that bring a shipment to what the courier says. */
+const TO = {
+    picked: ['pick'],
+    in_transit: ['transit'],
+    delivered: ['deliver'],
+    returned: ['bounce'],
+};
+/** Makes the draft shipment of each confirmed shop order of `ids` sent with a courier, once; returns how many. */
+export async function draftShipments(env, ids) {
+    let made = 0;
+    for (const o of await env
+        .model('sale.order')
+        .browse(ids)
+        .load({ carrier: true, partner: true, lines: { product: true }, company: true })) {
+        if (o.website === null || o.carrier === null || o.carrier.courier === 'none')
+            continue;
+        if (o.state !== 'sale' && o.state !== 'done')
+            continue;
+        const existing = await env
+            .model('delivery.shipment')
+            .search({ where: { order: o.id, state: { ne: 'cancel' } }, limit: 1 });
+        if (existing.length > 0)
+            continue;
+        const weight = [...o.lines]
+            .filter((l) => !l.isDelivery)
+            .reduce((s, l) => s.plus((l.product.weight ?? zero).times(l.quantity)), zero);
+        await env.model('delivery.shipment').create([
+            {
+                order: o.id,
+                carrier: o.carrier.id,
+                courier: o.carrier.courier,
+                company: o.company.id,
+                recipient: o.partner.name,
+                phone: o.partner.phone ?? o.partner.mobile ?? '-',
+                address: o.partner.street ?? '-',
+                city: o.partner.city ?? '-',
+                cod: o.shopPayment === 'cod' ? (o.amountTotal?.amount ?? zero) : zero,
+                weight,
+                note: o.shopNote,
+            },
+        ]);
+        made += 1;
+    }
+    await env.flush();
+    return made;
+}
+/** Asks the couriers about the open shipments (those of `ids`, or all); returns how many moved. */
+export async function refreshShipments(env, ids) {
+    const found = await env.model('delivery.shipment').search({
+        where: {
+            state: { in: OPEN },
+            trackingRef: { isNull: false },
+            ...(ids === undefined ? {} : { id: { in: ids } }),
+        },
+    });
+    let moved = 0;
+    for (const s of await found.load({ events: true })) {
+        const courier = courierOf(s.courier);
+        if (courier === null || s.trackingRef === null)
+            continue;
+        let tracking;
+        try {
+            tracking = await courier.track(s.trackingRef);
+        }
+        catch {
+            continue; // asked again next time
+        }
+        const known = s.events.length;
+        const fresh = tracking.events.slice(known);
+        if (fresh.length > 0)
+            await env.model('delivery.shipment.event').create(fresh.map((e) => ({
+                shipment: s.id,
+                at: new Date(e.at),
+                status: e.status,
+                note: e.note,
+            })));
+        const steps = TO[tracking.status];
+        if (steps !== undefined && tracking.status !== s.state) {
+            const one = env.model('delivery.shipment').browse([s.id]);
+            for (const step of steps)
+                await one[step]?.();
+            moved += 1;
+        }
+    }
+    await env.flush();
+    return moved;
+}
+/** A placed order's shipments as its customer may follow them. */
+export async function trackingOf(env, order) {
+    const found = await (await env
+        .model('delivery.shipment')
+        .search({ where: { order: order, state: { ne: 'cancel' } } })).load({ events: true });
+    return [...found].map((s) => ({
+        name: s.name,
+        state: s.state,
+        trackingRef: s.trackingRef,
+        events: [...s.events].map((e) => ({
+            at: e.at instanceof Date ? e.at.toISOString() : String(e.at),
+            status: e.status,
+            note: e.note,
+        })),
+    }));
+}

package/dist/website_sale/shop.d.ts

@@ -0,0 +1,81 @@
+import { type Decimal, type Id } from '../server/orm.js';
+import type { Env } from './.kosh/bindings.js';
+export interface Site {
+    readonly id: number;
+    readonly key: string;
+    readonly company: number;
+}
+/** The environment reading in the visitor's language. */
+export declare const inLang: (env: Env, lang: string) => Env;
+/** Published products on sale, searched, filtered, sorted and paged. */
+export declare function catalogue(env: Env, query: {
+    readonly q?: string;
+    readonly category?: number;
+    readonly min?: Decimal;
+    readonly max?: Decimal;
+    readonly sort?: string;
+    readonly page?: number;
+    readonly size?: number;
+}, site?: Site): Promise<{
+    products: Record<string, unknown>[];
+    total: number;
+    page: number;
+    pages: number;
+}>;
+export declare function productPage(env: Env, id: number, site?: Site): Promise<Record<string, unknown> | null>;
+/** The product categories that hold published products, with their parents. */
+export declare function categories(env: Env): Promise<{
+    id: number;
+    name: string;
+    parent: number | null;
+}[]>;
+/** A new cart: a quotation of the site's company for its visitor, with a new secret token. */
+export declare function newCart(env: Env, site: Site): Promise<{
+    token: string;
+    id: number;
+}>;
+/** The order of `token` on the site: a cart (not checked out) unless `placed`. */
+export declare function orderOf(env: Env, site: Site, token: string, placed?: boolean): Promise<Id<'sale.order'> | null>;
+/** What the visitor sees of a cart or an order. */
+export declare function cartView(env: Env, id: Id<'sale.order'>): Promise<Record<string, unknown>>;
+/** Sets how many of `product` the cart holds (0 removes it), at the product's price; the fee follows. */
+export declare function setLine(env: Env, id: Id<'sale.order'>, product: number, quantity: Decimal): Promise<void>;
+/** Puts a coupon on the cart (an empty code takes it off). @throws 422 with why it does not apply */
+export declare function setCoupon(env: Env, site: Site, id: Id<'sale.order'>, code: string): Promise<void>;
+/** The company's delivery methods with their fee for the cart, delivered to `city`. */
+export declare function carriersFor(env: Env, id: Id<'sale.order'>, city: string | null): Promise<{
+    id: number;
+    name: string;
+    fee: string;
+    cod: boolean;
+    description: string | null;
+}[]>;
+/** Chooses the delivery method: its fee, for the cart and `city`, replaces the cart's fee line. */
+export declare function setDelivery(env: Env, id: Id<'sale.order'>, carrier: number, city: string | null): Promise<void>;
+export interface CheckoutInput {
+    readonly name: string;
+    readonly email: string;
+    readonly phone: string;
+    readonly street: string;
+    readonly city: string;
+    readonly carrier: number;
+    /** `cod`, or a payment provider's id. */
+    readonly payment: string;
+    readonly note?: string;
+    /** Where the customer comes back to after paying online (http(s)). */
+    readonly returnUrl?: string;
+}
+/** Reads and checks a checkout's input. */
+export declare function checkoutInput(body: unknown): CheckoutInput;
+/**
+ * Places the cart: the customer (found by email in the company, else made), the delivery to their city, the note.
+ * Cash on delivery confirms it when the method takes cash and the total is within the site's limit (above it, it
+ * stays a quotation for the team to confirm); paying online starts a payment and returns where to send the visitor.
+ */
+export declare function checkout(env: Env, site: Site, id: Id<'sale.order'>, input: CheckoutInput): Promise<{
+    order: string;
+    state: string;
+    total: string;
+    redirectUrl?: string;
+    reference?: string;
+}>;