shutro-erp 0.3.4 → 0.3.6

package/dist/website_sale/couriers.d.ts

@@ -0,0 +1,50 @@
+/** Where a parcel is, in the Shop's words. */
+export type ParcelStatus = 'booked' | 'picked' | 'in_transit' | 'delivered' | 'returned' | 'cancelled';
+export interface Parcel {
+    /** The shipment's reference on our side (`SHP/2026/00007`). */
+    readonly reference: string;
+    readonly recipient: {
+        readonly name: string;
+        readonly phone: string;
+        readonly address: string;
+        readonly city: string;
+    };
+    /** The cash the courier collects on delivery (`0.00`: paid already), in the company's currency. */
+    readonly cod: string;
+    readonly weightKg: string;
+    readonly note: string;
+}
+export interface Booked {
+    /** The courier's consignment id. */
+    readonly trackingRef: string;
+    readonly labelUrl?: string;
+}
+export interface Tracking {
+    readonly status: ParcelStatus;
+    /** What the courier says happened, oldest first. */
+    readonly events: readonly {
+        readonly at: string;
+        readonly status: ParcelStatus;
+        readonly note: string;
+    }[];
+    /** Delivered with the cash collected. */
+    readonly codCollected: boolean;
+}
+export interface CourierAdapter {
+    readonly code: string;
+    /** Whether this server has the courier's credentials. */
+    configured(): boolean;
+    book(parcel: Parcel): Promise<Booked>;
+    track(trackingRef: string): Promise<Tracking>;
+    cancel(trackingRef: string): Promise<void>;
+}
+/** The test courier: parcels in memory, moved along by `advance`. */
+export interface FakeCourier extends CourierAdapter {
+    /** Moves a parcel to `status` (delivered collects its cash). */
+    advance(trackingRef: string, status: ParcelStatus, note?: string): void;
+}
+export declare function fakeCourier(): FakeCourier;
+/** The test courier every server has (the demo's and the tests'). */
+export declare const testCourier: FakeCourier;
+export declare function setCouriers(next: ReadonlyMap<string, CourierAdapter>): void;
+export declare function courierOf(code: string): CourierAdapter | null;

package/dist/website_sale/couriers.js

@@ -0,0 +1,59 @@
+/**
+ * Couriers (RFC 0024 §2.7): what the Shop asks of a courier — book a parcel (with the cash to collect on delivery),
+ * say where it is, cancel it — behind one adapter per courier, so Pathao, Steadfast or RedX can be switched without
+ * changing the Shop. Credentials are never in records: an adapter reads them from the environment. The test courier
+ * moves no parcel: tests (and the demo) move it along with `advance`.
+ */
+import { randomBytes } from 'node:crypto';
+export function fakeCourier() {
+    const parcels = new Map();
+    const step = (p, status, note) => {
+        p.status = status;
+        p.events.push({ at: new Date().toISOString(), status, note });
+    };
+    const known = (ref) => {
+        const p = parcels.get(ref);
+        if (p === undefined)
+            throw new Error(`The test courier has no parcel ${ref}.`);
+        return p;
+    };
+    return {
+        code: 'fake',
+        configured: () => true,
+        book: async (parcel) => {
+            const trackingRef = `FAKE-${randomBytes(5).toString('hex').toUpperCase()}`;
+            parcels.set(trackingRef, {
+                parcel,
+                status: 'booked',
+                events: [{ at: new Date().toISOString(), status: 'booked', note: 'Booked' }],
+            });
+            return { trackingRef, labelUrl: `https://courier.test/labels/${trackingRef}.pdf` };
+        },
+        track: async (ref) => {
+            const p = known(ref);
+            return {
+                status: p.status,
+                events: p.events.map((e) => ({ ...e })),
+                codCollected: p.status === 'delivered' && Number(p.parcel.cod) > 0,
+            };
+        },
+        cancel: async (ref) => {
+            const p = known(ref);
+            if (p.status !== 'booked')
+                throw new Error('The courier has picked the parcel up already.');
+            step(p, 'cancelled', 'Cancelled');
+        },
+        advance: (ref, status, note) => step(known(ref), status, note ?? status),
+    };
+}
+/** The test courier every server has (the demo's and the tests'). */
+export const testCourier = fakeCourier();
+/** The couriers of the running server, by code (Pathao, Steadfast and RedX come with their sandbox credentials). */
+let couriers = new Map([['fake', testCourier]]);
+export function setCouriers(next) {
+    couriers = next;
+}
+export function courierOf(code) {
+    const c = couriers.get(code);
+    return c?.configured() ? c : null;
+}

package/dist/website_sale/demo.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The Shop's demo data (RFC 0024 §2.7): Padma Traders' site sells — cement, LED panels and copper cable published with
+ * their weight and a Bangla description, related to one another; two delivery methods (by zone, Dhaka or outside,
+ * free from 10 000; and a courier by weight); and an order placed on the shop with cash on delivery.
+ */
+import type { DemoContext } from '../modules-sdk/index.js';
+export declare function shopDemo(ctx: DemoContext): Promise<string>;

package/dist/website_sale/demo.js

@@ -0,0 +1,90 @@
+/**
+ * The Shop's demo data (RFC 0024 §2.7): Padma Traders' site sells — cement, LED panels and copper cable published with
+ * their weight and a Bangla description, related to one another; two delivery methods (by zone, Dhaka or outside,
+ * free from 10 000; and a courier by weight); and an order placed on the shop with cash on delivery.
+ */
+import { idByName } from '../modules-sdk/index.js';
+import { orm } from '../server/orm.js';
+import { checkout, newCart, setLine } from './shop.js';
+const DINA = {
+    login: 'dina',
+    name: 'Dina Rahman',
+    groups: ['website_sale.manager', 'product.manager'],
+};
+export async function shopDemo(ctx) {
+    const placed = await ctx.as(DINA, async (raw) => {
+        const env = raw;
+        const [site] = await (await env.model('website.site').search({ where: { key: 'padma' }, limit: 1 })).load({});
+        if (site === undefined)
+            return null;
+        await env.model('website.site').browse([site.id]).write({ shop: true, codLimit: '50000' });
+        const products = [
+            ['Cement bag 50 kg', '50', 'পোর্টল্যান্ড কম্পোজিট সিমেন্ট, ৫০ কেজির বস্তা।'],
+            ['LED panel 40 W', '2.5', '৪০ ওয়াটের এলইডি প্যানেল, অফিস ও দোকানের জন্য।'],
+            ['Copper cable 2.5 mm²', '0.03', 'তামার তার, ২.৫ বর্গমিলিমিটার, মিটার হিসেবে।'],
+        ];
+        const ids = [];
+        for (const [name, weight, bangla] of products) {
+            const id = (await idByName(env, 'product.product', name));
+            if (id === undefined)
+                continue;
+            ids.push(id);
+            await env
+                .model('product.product')
+                .browse([id])
+                .write({
+                published: true,
+                weight,
+                websiteDescription: { en_US: `${name}, delivered across Bangladesh.`, bn_BD: bangla },
+            });
+        }
+        for (const id of ids)
+            await env
+                .model('product.product')
+                .browse([id])
+                .write({ related: { set: ids.filter((o) => o !== id) } });
+        const carriers = await env.model('delivery.carrier').create([
+            {
+                name: 'Home delivery',
+                kind: 'zone',
+                zoneCities: 'Dhaka',
+                priceInside: '60',
+                priceOutside: '120',
+                freeOver: '10000',
+                cod: true,
+                courier: 'fake',
+                sequence: 1,
+            },
+            {
+                name: 'Courier by weight',
+                kind: 'weight',
+                price: '80',
+                pricePerKg: '20',
+                cod: false,
+                sequence: 2,
+            },
+        ]);
+        await env.flush();
+        // An order placed with cash on delivery, as a visitor would (the shop works as the system).
+        return env.asSuperuser({ reason: 'demo shop order' }, async (su) => {
+            const shop = { id: site.id, key: site.key, company: site.company.id };
+            const cart = await newCart(su, shop);
+            const cement = ids[0];
+            if (cement === undefined)
+                return null;
+            await setLine(su, cart.id, cement, orm.toDecimal(4));
+            return checkout(su, shop, cart.id, {
+                name: 'Rina Akter',
+                email: 'rina@example.com',
+                phone: '01700000000',
+                street: 'House 12, Road 5, Dhanmondi',
+                city: 'Dhaka',
+                carrier: carriers.ids[0],
+                payment: 'cod',
+            });
+        });
+    });
+    return placed === null
+        ? 'Shop: no site to sell on.'
+        : `Shop: 3 products published, 2 delivery methods, order ${placed.order} placed with cash on delivery.`;
+}

package/dist/website_sale/growth.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Bringing visitors back and to the shop (RFC 0024 §2.7): carts left with an email get one reminder with a code that
+ * restores them (the cart's own token is never sent); the site's sitemap lists its published pages and products for
+ * search engines; product pictures are served without a sign-in, only of products on the shop.
+ */
+import { type Mailer } from '../mail/index.js';
+import type { Env } from './.kosh/bindings.js';
+import type { Site } from './shop.js';
+export declare function setShopMailer(mailer: Mailer | undefined): void;
+/** The email a visitor leaves on their cart, for one reminder if they leave it. */
+export declare function setContact(env: Env, id: number, email: string): Promise<void>;
+/**
+ * Reminds the carts of the company's shops left longer than their site says, with an email and goods, once each: a
+ * new recovery code (only its hash is kept) in a link to the site's `/cart/recover`. Sent after the commit; returns
+ * how many were reminded.
+ */
+export declare function remindAbandoned(env: Env, now?: Date): Promise<number>;
+/** A reminder's code restores its cart: a new token for it (the old one stops working); null when unknown. */
+export declare function recoverCart(env: Env, site: Site, code: string): Promise<string | null>;
+/**
+ * The site's sitemap: its published pages (the default language at their path, the other at `/<lang><path>`) and the
+ * products on its shop (at `/shop/p/<id>`), each with when it last changed. Null without the site's domain.
+ */
+export declare function sitemap(env: Env, site: Site): Promise<string | null>;
+/** The picture of a product on the shop (`width`: its thumbnail of that width, when one was made). */
+export declare function productImage(env: Env, product: number, width?: number): Promise<{
+    key: string;
+    mime: string;
+    size: number;
+    name: string;
+} | null>;

package/dist/website_sale/growth.js

@@ -0,0 +1,163 @@
+/**
+ * Bringing visitors back and to the shop (RFC 0024 §2.7): carts left with an email get one reminder with a code that
+ * restores them (the cart's own token is never sent); the site's sitemap lists its published pages and products for
+ * search engines; product pictures are served without a sign-in, only of products on the shop.
+ */
+import { layout } from '../mail/index.js';
+import { HttpProblem } from '../server/index.js';
+import { orm } from '../server/orm.js';
+import { hashToken, newCartToken } from './module.js';
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const escapeXml = (s) => s.replace(/[<>&'"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', "'": '&apos;', '"': '&quot;' })[c] ?? c);
+/** The shop's mailer (from the environment, or the tests'): set by the module. */
+let shopMailer;
+export function setShopMailer(mailer) {
+    shopMailer = mailer;
+}
+/** The email a visitor leaves on their cart, for one reminder if they leave it. */
+export async function setContact(env, id, email) {
+    const clean = email.trim().slice(0, 200);
+    if (!EMAIL.test(clean))
+        throw new HttpProblem(422, 'invalid-input', 'Invalid email', 'An email address.');
+    await env
+        .model('sale.order')
+        .browse([id])
+        .write({ contactEmail: clean });
+    await env.flush();
+}
+/**
+ * Reminds the carts of the company's shops left longer than their site says, with an email and goods, once each: a
+ * new recovery code (only its hash is kept) in a link to the site's `/cart/recover`. Sent after the commit; returns
+ * how many were reminded.
+ */
+export async function remindAbandoned(env, now = new Date()) {
+    const sites = await (await env
+        .model('website.site')
+        .search({ where: { shop: true, abandonedHours: { gt: 0 } } })).load({});
+    let reminded = 0;
+    for (const site of sites) {
+        if (site.domain === null || site.domain === '')
+            continue;
+        const before = new Date(now.getTime() - site.abandonedHours * 3_600_000);
+        const carts = await (await env.model('sale.order').search({
+            where: {
+                website: site.id,
+                state: 'draft',
+                placedAt: { isNull: true },
+                contactEmail: { isNull: false },
+                remindedAt: { isNull: true },
+                updatedAt: { lt: before },
+            },
+            limit: 200,
+        })).load({ lines: true, currency: true });
+        for (const cart of carts) {
+            const goods = [...cart.lines].filter((l) => !l.isDelivery && !l.isDiscount);
+            if (goods.length === 0 || cart.contactEmail === null)
+                continue;
+            const code = newCartToken();
+            await env
+                .model('sale.order')
+                .browse([cart.id])
+                .write({ recoveryToken: hashToken(code), remindedAt: now });
+            const bangla = site.lang === 'bn';
+            const url = `https://${site.domain}/cart/recover?code=${encodeURIComponent(code)}`;
+            const mail = layout({
+                title: bangla ? 'আপনার কার্ট অপেক্ষা করছে' : 'Your cart is waiting',
+                paragraphs: [
+                    bangla
+                        ? `${site.name}-এ আপনার কার্টে রাখা পণ্যগুলো:`
+                        : `What you left in your cart at ${site.name}:`,
+                    ...goods.map((l) => `${l.quantity.toString()} × ${l.name}`),
+                ],
+                action: { label: bangla ? 'কার্টে ফিরে যান' : 'Back to your cart', url },
+                lang: bangla ? 'bn' : 'en',
+            });
+            const to = cart.contactEmail;
+            const subject = bangla ? 'আপনার কার্ট অপেক্ষা করছে' : `Your cart at ${site.name} is waiting`;
+            const mailer = shopMailer;
+            if (mailer !== undefined)
+                env.afterCommit(async () => {
+                    await mailer
+                        .send({ to, subject, html: mail.html, text: mail.text })
+                        .catch(() => undefined);
+                });
+            reminded += 1;
+        }
+    }
+    await env.flush();
+    return reminded;
+}
+/** A reminder's code restores its cart: a new token for it (the old one stops working); null when unknown. */
+export async function recoverCart(env, site, code) {
+    if (code === '' || code.length > 100)
+        return null;
+    const [id] = (await env.model('sale.order').search({
+        where: {
+            website: site.id,
+            recoveryToken: hashToken(code),
+            state: 'draft',
+            placedAt: { isNull: true },
+        },
+        limit: 1,
+    })).ids;
+    if (id === undefined)
+        return null;
+    const token = newCartToken();
+    await env
+        .model('sale.order')
+        .browse([id])
+        .write({ cartToken: hashToken(token), recoveryToken: null });
+    await env.flush();
+    return token;
+}
+/**
+ * The site's sitemap: its published pages (the default language at their path, the other at `/<lang><path>`) and the
+ * products on its shop (at `/shop/p/<id>`), each with when it last changed. Null without the site's domain.
+ */
+export async function sitemap(env, site) {
+    const [s] = await env
+        .model('website.site')
+        .browse([site.id])
+        .load({});
+    if (s === undefined || s.domain === null || s.domain === '')
+        return null;
+    const base = `https://${s.domain.replace(/^https?:\/\//, '').replace(/\/$/, '')}`;
+    const day = (v) => v instanceof Date ? v.toISOString().slice(0, 10) : String(v ?? '').slice(0, 10);
+    const pages = await (await env
+        .model('website.page')
+        .search({ where: { site: site.id, state: 'published' }, order: ['path asc'] })).load({});
+    const products = await (await env.model('product.product').search({
+        where: { published: true, saleOk: true },
+        order: ['shopSequence asc', 'id asc'],
+        limit: 5000,
+    })).load({});
+    const urls = [
+        ...[...pages].map((p) => ({
+            loc: `${base}${p.lang === s.lang ? '' : `/${p.lang}`}${p.path === '/' && p.lang !== s.lang ? '' : p.path}`,
+            lastmod: day(p.updatedAt),
+        })),
+        ...[...products].map((p) => ({ loc: `${base}/shop/p/${p.id}`, lastmod: day(p.updatedAt) })),
+    ];
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls
+        .map((u) => `  <url><loc>${escapeXml(u.loc)}</loc><lastmod>${u.lastmod}</lastmod></url>`)
+        .join('\n')}\n</urlset>\n`;
+}
+/** The picture of a product on the shop (`width`: its thumbnail of that width, when one was made). */
+export async function productImage(env, product, width) {
+    const [p] = await (await env.model('product.product').search({
+        where: { id: orm.asId(product, 'product.product'), published: true, saleOk: true },
+        limit: 1,
+    })).load({});
+    if (p === undefined || p.image === null)
+        return null;
+    const attachments = env.model('storage.attachment');
+    let id = p.image.id;
+    if (width !== undefined) {
+        const variant = await attachments.search({ where: { variantOf: id, width }, limit: 1 });
+        id = variant.ids[0] ?? id;
+    }
+    const [a] = [...(await attachments.browse([id]).load(['key', 'mime', 'size', 'name']))];
+    if (a === undefined || !a.mime.startsWith('image/'))
+        return null;
+    return { key: a.key, mime: a.mime, size: a.size, name: a.name };
+}

package/dist/website_sale/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @packageDocumentation
+ * `shutro-erp/website_sale` (RFC 0024 §2.7): the **Shop** on a Sites site. Products published with a description in English
+ * and Bangla; delivery methods with fees (fixed, by weight, by zone — Dhaka or outside — free above an amount); a
+ * public API for a storefront (the Next.js site, or any other): the catalogue, a cart held by a secret token, the
+ * delivery methods with their fee, and checkout with cash on delivery or an online payment (RFC 0017 providers),
+ * which confirms, invoices and pays the order once the provider confirms. No sign-in; rate limited per address as
+ * every public route is; prices always the server's. The cart's token travels in the `x-cart-token` header.
+ *
+ * - `GET  /api/v1/public/shop/:site/products?q=&category=&min=&max=&sort=price|-price|name|new&page=&lang=`
+ * - `GET  /api/v1/public/shop/:site/products/:id?lang=`         a product's page with related products
+ * - `GET  /api/v1/public/shop/:site/categories?lang=`
+ * - `POST /api/v1/public/shop/:site/cart`                       a new cart → `{ token }`
+ * - `GET  /api/v1/public/shop/:site/cart`                       the cart (lines, fee, taxes, total)
+ * - `PUT  /api/v1/public/shop/:site/cart/lines`                 `{ product, quantity }` (0 removes)
+ * - `GET  /api/v1/public/shop/:site/carriers?city=`             the delivery methods with their fee for the cart
+ * - `GET  /api/v1/public/shop/:site/payments`                   the online payment providers offered
+ * - `POST /api/v1/public/shop/:site/checkout`                   `{ name, email, phone, street, city, carrier,
+ *                                                                  payment: 'cod' | provider id, note?, returnUrl? }`
+ * - `GET  /api/v1/public/shop/:site/order`                      the placed order of the token: its state, payment
+ *                                                                  and shipments
+ * - `PUT  /api/v1/public/shop/:site/cart/coupon`                `{ code }` (empty takes it off)
+ * - `PUT  /api/v1/public/shop/:site/cart/contact`               `{ email }`: one reminder if the cart is left
+ * - `POST /api/v1/public/shop/:site/cart/recover`               `{ code }` from the reminder → `{ token }`
+ * - `GET  /api/v1/public/shop/:site/products/:id/image?w=256`   a published product's picture
+ * - `GET  /api/v1/public/shop/:site/sitemap.xml`                the site's pages and products for search engines
+ */
+import { type Mailer } from '../mail/index.js';
+import { defineModule } from '../modules-sdk/index.js';
+import { type ModuleContext } from '../server/index.js';
+import { type Worker } from '../server/orm.js';
+import { type CourierAdapter } from './couriers.js';
+export { type Booked, type CourierAdapter, courierOf, type FakeCourier, fakeCourier, type Parcel, type ParcelStatus, setCouriers, type Tracking, testCourier, } from './couriers.js';
+export { recoverCart, remindAbandoned, setContact, sitemap } from './growth.js';
+export { COURIERS, DeliveryCarrier, DeliveryShipment, DeliveryShipmentEvent, feeOf, hashToken, LineShop, OrderShop, ProductShop, ShopCoupon, SiteShop, TransactionOrder, websiteSaleShutro, } from './module.js';
+export { draftShipments, refreshShipments, trackingOf } from './shipments.js';
+export { type CheckoutInput, checkout, setDelivery, setLine } from './shop.js';
+/** The subscriber that makes the draft shipments of confirmed shop orders; tests `drain()` it, the server starts it. */
+export declare function shipmentWorker(context: Pick<ModuleContext, 'shutro'>): Worker;
+export interface ShopOptions {
+    /** The couriers by code (tests; default: the test courier). */
+    readonly couriers?: ReadonlyMap<string, CourierAdapter>;
+    /** Who sends the reminders; default: SMTP from the environment (`SMTP_URL`), none without it. */
+    readonly mailer?: Mailer | undefined;
+}
+/** The Shop with explicit options (tests, installations wiring their couriers). */
+export declare function websiteSaleModule(options?: ShopOptions): ReturnType<typeof defineModule>;
+/** The Shop (the test courier; Pathao, Steadfast and RedX adapters come with their sandbox credentials). */
+export declare const websiteSale: ReturnType<typeof defineModule>;