shutro-erp 0.3.4 → 0.3.6

package/dist/documents/demo.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Documents' demo data (RFC 0008 §5.8): the company's folders — Contracts and Suppliers open to everyone with
+ * Documents, HR kept to its members —, two tags, and a request to a supplier for their trade licence.
+ */
+import type { DemoContext } from '../modules-sdk/index.js';
+export declare function documentsDemo(ctx: DemoContext): Promise<string>;

package/dist/documents/demo.js

@@ -0,0 +1,22 @@
+import { idByName } from '../modules-sdk/index.js';
+const DINA = { login: 'dina', name: 'Dina Rahman', groups: ['documents.manager'] };
+export async function documentsDemo(ctx) {
+    await ctx.as(DINA, async (raw) => {
+        const env = raw;
+        const folders = await env
+            .model('documents.folder')
+            .create([{ name: 'Contracts' }, { name: 'Suppliers' }, { name: 'HR', restricted: true }]);
+        await env.model('documents.tag').create([{ name: 'Signed' }, { name: 'To review' }]);
+        const supplier = (await idByName(env, 'res.partner', 'Padma Cement'));
+        await env.model('documents.request').create([
+            {
+                name: 'Your trade licence (2026)',
+                folder: folders.ids[1],
+                partner: (supplier ?? null),
+                email: 'accounts@padmacement.example',
+                message: 'A scan or a photo is fine.',
+            },
+        ]);
+    });
+    return 'Documents: 3 folders (HR for its members), 2 tags, a request to a supplier.';
+}

package/dist/documents/documents.d.ts

@@ -0,0 +1,98 @@
+import { type Mailer } from '../mail/index.js';
+import { type Storage } from '../storage/index.js';
+import type { Env } from './.kosh/bindings.js';
+/** A new secret for a link: given once; only its digest is kept. */
+export declare const newToken: () => string;
+/**
+ * Stores `data` as the document's new version (the document read as the user first, so their rules apply); the
+ * document's file, type, size and count of versions follow.
+ */
+export declare function addVersion(env: Env, storage: Storage, id: number, file: {
+    readonly name: string;
+    readonly mime?: string | undefined;
+    readonly data: Uint8Array;
+}): Promise<{
+    id: number;
+    versions: number;
+}>;
+/** The versions of a document the user may read, newest first. */
+export declare function versionsOf(env: Env, id: number): Promise<{
+    id: number;
+    name: string;
+    mime: string;
+    size: number;
+    at: string;
+    by: number | null;
+}[]>;
+/**
+ * One search: the documents whose name matches, and the attachments of any record whose name matches — each kept
+ * only when the user may read its record.
+ */
+export declare function searchAll(env: Env, q: string, canRead: (model: string, id: number) => Promise<boolean>): Promise<{
+    documents: {
+        id: number;
+        name: string;
+        folder: string;
+        mime: string | null;
+    }[];
+    attachments: {
+        id: number;
+        name: string;
+        model: string;
+        record: number;
+        mime: string;
+    }[];
+}>;
+/** A share link of a document or a folder the user may read, for `days` (1 to 90), with an optional password. */
+export declare function makeShare(env: Env, input: {
+    document?: number;
+    folder?: number;
+    days?: number;
+    password?: string;
+}): Promise<{
+    token: string;
+    expiresAt: string;
+}>;
+/**
+ * What a share link opens (as the system): its document, or its folder's documents, while it has not expired or
+ * been revoked, and with its password when it has one. @throws 404 for an unknown, expired or revoked link, 401
+ * for a missing or wrong password
+ */
+export declare function openShare(env: Env, token: string, password: string): Promise<{
+    share: number;
+    documents: {
+        id: number;
+        name: string;
+        mime: string | null;
+        size: number | null;
+        attachment: number | null;
+    }[];
+}>;
+/** The storage key of an attachment (as the system). */
+export declare function keyOf(env: Env, attachment: number): Promise<string | null>;
+export declare function configureRequests(next: {
+    mailer: Mailer | undefined;
+    apiUrl: string;
+}): void;
+/** As requests are sent: a new link each (only its digest kept), by email after the commit. */
+export declare function announceRequests(env: Env, ids: readonly number[]): Promise<void>;
+/**
+ * Reminds the sent requests that are late (past their due date, or a week after they were sent), once each: a new
+ * link (the old one stops).
+ */
+export declare function remindRequests(env: Env, now?: Date): Promise<number>;
+/** The open request of a link (as the system), or null. */
+export declare function requestOf(env: Env, token: string): Promise<{
+    id: number;
+    name: string;
+    company: string;
+    message: string | null;
+} | null>;
+/** Takes a request's file (as the system): a document in its folder with the file, the request received, once. */
+export declare function fulfil(env: Env, storage: Storage, token: string, file: {
+    readonly name: string;
+    readonly mime?: string | undefined;
+    readonly data: Uint8Array;
+}): Promise<{
+    document: number;
+}>;

package/dist/documents/documents.js

@@ -0,0 +1,318 @@
+/**
+ * Documents' logic (RFC 0024 §2.8): versions — each upload a stored file of the document, the latest its current
+ * one —; one search over the documents and every record's attachments a user may read; share links that serve a
+ * document or a folder's documents until they expire (and with the password, when set); and requests whose link
+ * takes the file into the request's folder, once.
+ */
+import { randomBytes } from 'node:crypto';
+import { layout } from '../mail/index.js';
+import { digest, HttpProblem, hashPassword, verifyPassword } from '../server/index.js';
+import { orm } from '../server/orm.js';
+import { saveAttachment } from '../storage/index.js';
+const DOCS = new Set(['documents.document']);
+const DAY = 86_400_000;
+/** A date as `YYYY-MM-DD` (date-only values from PostgreSQL may read as local midnights). */
+const dayOf = (v) => {
+    if (!(v instanceof Date))
+        return String(v ?? '').slice(0, 10);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${v.getFullYear()}-${pad(v.getMonth() + 1)}-${pad(v.getDate())}`;
+};
+const notFound = (what) => new HttpProblem(404, 'not-found', 'Not found', `There is no ${what}.`);
+/** A new secret for a link: given once; only its digest is kept. */
+export const newToken = () => randomBytes(24).toString('base64url');
+/**
+ * Stores `data` as the document's new version (the document read as the user first, so their rules apply); the
+ * document's file, type, size and count of versions follow.
+ */
+export async function addVersion(env, storage, id, file) {
+    const [doc] = await (await env.model('documents.document').search({
+        where: { id: orm.asId(id, 'documents.document') },
+        limit: 1,
+    })).load({});
+    if (doc === undefined)
+        throw notFound(`document ${id}`);
+    return env.asSuperuser({ reason: 'document version' }, async (su) => {
+        const saved = await saveAttachment(su, storage, DOCS, {
+            model: 'documents.document',
+            id: doc.id,
+            name: file.name,
+            mime: file.mime,
+            data: file.data,
+        });
+        // The count of its files (thumbnails aside): every upload is one.
+        const att = su.model('storage.attachment');
+        const versions = (await att.search({
+            where: { resModel: 'documents.document', resId: doc.id, variantOf: null },
+        })).length;
+        await su
+            .model('documents.document')
+            .browse([doc.id])
+            .write({ attachment: saved.id, mime: saved.mime, size: saved.size, versions });
+        await su.flush();
+        return { id: saved.id, versions };
+    });
+}
+/** The versions of a document the user may read, newest first. */
+export async function versionsOf(env, id) {
+    const [doc] = await (await env.model('documents.document').search({
+        where: { id: orm.asId(id, 'documents.document') },
+        limit: 1,
+    })).load({});
+    if (doc === undefined)
+        throw notFound(`document ${id}`);
+    return env.asSuperuser({ reason: 'document versions' }, async (su) => {
+        const att = su.model('storage.attachment');
+        const rows = await (await att.search({
+            where: { resModel: 'documents.document', resId: doc.id, variantOf: null },
+            order: ['id desc'],
+        })).load({});
+        return [...rows].map((r) => ({
+            id: r.id,
+            name: r.name,
+            mime: r.mime,
+            size: r.size,
+            at: r.createdAt instanceof Date ? r.createdAt.toISOString() : String(r.createdAt),
+            by: r.createdBy?.id ?? null,
+        }));
+    });
+}
+/**
+ * One search: the documents whose name matches, and the attachments of any record whose name matches — each kept
+ * only when the user may read its record.
+ */
+export async function searchAll(env, q, canRead) {
+    const text = q.trim().slice(0, 100);
+    if (text === '')
+        return { documents: [], attachments: [] };
+    const docs = await (await env.model('documents.document').search({
+        where: { name: { ilike: `%${text}%` } },
+        limit: 50,
+    })).load({ folder: true });
+    const found = await env.asSuperuser({ reason: 'document search' }, async (su) => {
+        const att = su.model('storage.attachment');
+        return [
+            ...(await (await att.search({
+                where: {
+                    name: { ilike: `%${text}%` },
+                    variantOf: null,
+                    resModel: { ne: 'documents.document' },
+                },
+                order: ['id desc'],
+                limit: 100,
+            })).load({})),
+        ];
+    });
+    const attachments = [];
+    for (const a of found) {
+        if (attachments.length >= 50)
+            break;
+        if (await canRead(a.resModel, a.resId))
+            attachments.push({
+                id: a.id,
+                name: a.name,
+                model: a.resModel,
+                record: a.resId,
+                mime: a.mime,
+            });
+    }
+    return {
+        documents: [...docs].map((d) => ({
+            id: d.id,
+            name: d.name,
+            folder: d.folder.fullName ?? d.folder.name,
+            mime: d.mime,
+        })),
+        attachments,
+    };
+}
+/** A share link of a document or a folder the user may read, for `days` (1 to 90), with an optional password. */
+export async function makeShare(env, input) {
+    const days = input.days ?? 7;
+    if (!Number.isSafeInteger(days) || days < 1 || days > 90)
+        throw new HttpProblem(400, 'invalid-input', 'Invalid expiry', 'From 1 to 90 days.');
+    if (input.document !== undefined) {
+        const found = await env
+            .model('documents.document')
+            .search({ where: { id: orm.asId(input.document, 'documents.document') }, limit: 1 });
+        if (found.length === 0)
+            throw notFound(`document ${input.document}`);
+    }
+    else if (input.folder !== undefined) {
+        const found = await env
+            .model('documents.folder')
+            .search({ where: { id: orm.asId(input.folder, 'documents.folder') }, limit: 1 });
+        if (found.length === 0)
+            throw notFound(`folder ${input.folder}`);
+    }
+    else
+        throw new HttpProblem(400, 'invalid-input', 'Nothing to share', 'A document or a folder.');
+    const password = input.password ?? '';
+    if (password !== '' && password.length < 6)
+        throw new HttpProblem(400, 'invalid-input', 'Short password', 'At least 6 characters.');
+    const token = newToken();
+    const expiresAt = new Date(Date.now() + days * DAY);
+    await env.model('documents.share').create([
+        {
+            ...(input.document === undefined ? {} : { document: input.document }),
+            ...(input.folder === undefined ? {} : { folder: input.folder }),
+            tokenHash: digest(token),
+            passwordHash: password === '' ? null : await hashPassword(password),
+            expiresAt,
+        },
+    ]);
+    await env.flush();
+    return { token, expiresAt: expiresAt.toISOString() };
+}
+/**
+ * What a share link opens (as the system): its document, or its folder's documents, while it has not expired or
+ * been revoked, and with its password when it has one. @throws 404 for an unknown, expired or revoked link, 401
+ * for a missing or wrong password
+ */
+export async function openShare(env, token, password) {
+    if (token === '' || token.length > 100)
+        throw notFound('such link');
+    const [share] = await (await env.model('documents.share').search({ where: { tokenHash: digest(token) }, limit: 1 })).load({ document: true, folder: true });
+    if (share === undefined || share.revoked || share.expiresAt.getTime() < Date.now())
+        throw notFound('such link (it may have expired)');
+    if (share.passwordHash !== null && !(await verifyPassword(password, share.passwordHash)))
+        throw new HttpProblem(401, 'password', 'Password', 'This link needs its password.');
+    const docs = share.document !== null
+        ? await env.model('documents.document').browse([share.document.id]).load({})
+        : await (await env.model('documents.document').search({
+            where: { folder: share.folder?.id },
+            order: ['name asc'],
+        })).load({});
+    return {
+        share: share.id,
+        documents: [...docs].map((d) => ({
+            id: d.id,
+            name: d.name,
+            mime: d.mime,
+            size: d.size,
+            attachment: d.attachment?.id ?? null,
+        })),
+    };
+}
+/** The storage key of an attachment (as the system). */
+export async function keyOf(env, attachment) {
+    const att = env.model('storage.attachment');
+    const [a] = [...(await att.browse([attachment]).load(['key']))];
+    return a?.key ?? null;
+}
+/** Who sends the requests and where their links point: set by the module. */
+let config = {
+    mailer: undefined,
+    apiUrl: 'http://localhost:3000',
+};
+export function configureRequests(next) {
+    config = next;
+}
+/** As requests are sent: a new link each (only its digest kept), by email after the commit. */
+export async function announceRequests(env, ids) {
+    for (const r of await env
+        .model('documents.request')
+        .browse(ids)
+        .load({ company: true })) {
+        const token = newToken();
+        await env
+            .model('documents.request')
+            .browse([r.id])
+            .write({ tokenHash: digest(token), sentAt: new Date() });
+        const due = r.dueDate === null ? null : dayOf(r.dueDate);
+        mail(env, config.mailer, r.email, {
+            title: `${r.company.name} asks you for a document`,
+            paragraphs: [
+                `${r.company.name} asks you for: ${r.name}.`,
+                ...(r.message === null || r.message === '' ? [] : [r.message]),
+                ...(due === null ? [] : [`Please send it by ${due}.`]),
+            ],
+            action: {
+                label: 'Upload it',
+                url: `${config.apiUrl}/api/v1/public/documents/requests/${token}`,
+            },
+        });
+    }
+}
+function mail(env, mailer, to, content) {
+    if (mailer === undefined)
+        return;
+    const body = layout(content);
+    env.afterCommit(async () => {
+        await mailer
+            .send({ to, subject: content.title, html: body.html, text: body.text })
+            .catch(() => undefined);
+    });
+}
+/**
+ * Reminds the sent requests that are late (past their due date, or a week after they were sent), once each: a new
+ * link (the old one stops).
+ */
+export async function remindRequests(env, now = new Date()) {
+    const { mailer, apiUrl } = config;
+    const found = await (await env.model('documents.request').search({
+        where: { state: 'sent', remindedAt: { isNull: true } },
+    })).load({ company: true });
+    let reminded = 0;
+    for (const r of found) {
+        const due = r.dueDate !== null
+            ? new Date(`${dayOf(r.dueDate)}T23:59:59Z`)
+            : new Date((r.sentAt?.getTime() ?? now.getTime()) + 7 * DAY);
+        if (due.getTime() > now.getTime())
+            continue;
+        const token = newToken();
+        await env
+            .model('documents.request')
+            .browse([r.id])
+            .write({ tokenHash: digest(token), remindedAt: now });
+        mail(env, mailer, r.email, {
+            title: `Reminder: ${r.company.name} is waiting for ${r.name}`,
+            paragraphs: [`${r.company.name} is still waiting for: ${r.name}.`],
+            action: { label: 'Upload it', url: `${apiUrl}/api/v1/public/documents/requests/${token}` },
+        });
+        reminded += 1;
+    }
+    await env.flush();
+    return reminded;
+}
+/** The open request of a link (as the system), or null. */
+export async function requestOf(env, token) {
+    if (token === '' || token.length > 100)
+        return null;
+    const [r] = await (await env
+        .model('documents.request')
+        .search({ where: { tokenHash: digest(token), state: 'sent' }, limit: 1 })).load({ company: true });
+    return r === undefined
+        ? null
+        : { id: r.id, name: r.name, company: r.company.name, message: r.message };
+}
+/** Takes a request's file (as the system): a document in its folder with the file, the request received, once. */
+export async function fulfil(env, storage, token, file) {
+    const open = await requestOf(env, token);
+    if (open === null)
+        throw notFound('open request for this link (it may be answered already)');
+    const [r] = await env
+        .model('documents.request')
+        .browse([open.id])
+        .load({ folder: true, partner: true, company: true });
+    if (r === undefined)
+        throw notFound('request');
+    const made = await env.model('documents.document').create([
+        {
+            name: `${r.name} — ${r.partner?.name ?? r.email}`,
+            folder: r.folder.id,
+            company: r.company.id,
+            owner: r.createdBy?.id ?? null,
+            request: r.id,
+        },
+    ]);
+    const id = made.ids[0];
+    await env.flush();
+    await addVersion(env, storage, id, file);
+    const one = env.model('documents.request').browse([r.id]);
+    await one.write({ document: id, tokenHash: null });
+    await one.receive();
+    await env.emit('documents.request.received', { id: r.id });
+    await env.flush();
+    return { document: id };
+}

package/dist/documents/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @packageDocumentation
+ * `shutro-erp/documents` (RFC 0024 §2.8): the **Documents** app. Folders (open, or kept to their members), documents with
+ * tags and versions, one search over documents and every record's attachments, share links with an expiry and an
+ * optional password, and requests that ask a person for a file by email and take it into the right folder.
+ *
+ * - `POST /api/v1/documents/upload?folder=&name=`         the raw body is the file (`X-Filename`): a new document
+ * - `POST /api/v1/documents/:id/versions`                 a new version (the raw body)
+ * - `GET  /api/v1/documents/:id/versions`                 its versions, newest first
+ * - `GET  /api/v1/documents/search?q=`                    documents and record attachments the user may read
+ * - `POST /api/v1/documents/shares`                       `{ document | folder, days?, password? }` → `{ url }`
+ * - `POST /api/v1/documents/requests/remind`              the late requests reminded now (managers; hourly too)
+ * - `GET  /api/v1/public/documents/shares/:token`         what a link shares (`x-share-password` when it has one)
+ * - `GET  /api/v1/public/documents/shares/:token/documents/:id`   a shared document's file
+ * - `GET|POST /api/v1/public/documents/requests/:token`   the upload page of a request; its file (the raw body)
+ */
+import { type Mailer } from '../mail/index.js';
+import { defineModule } from '../modules-sdk/index.js';
+export { addVersion, fulfil, makeShare, openShare, remindRequests, searchAll, versionsOf, } from './documents.js';
+export { DocumentsDocument, DocumentsFolder, DocumentsRequest, DocumentsShare, DocumentsTag, documentsShutro, } from './module.js';
+export interface DocumentsOptions {
+    /** Who sends the requests; default: SMTP from the environment (`SMTP_URL`), none without it. */
+    readonly mailer?: Mailer | undefined;
+    /** The API's public address, which request and share links point to (`KOSH_API_URL`). */
+    readonly apiUrl?: string;
+}
+/** Documents with explicit options (tests: a memory mailer). */
+export declare function documentsModule(options?: DocumentsOptions): ReturnType<typeof defineModule>;
+/** Documents (mail from the environment). */
+export declare const documents: ReturnType<typeof defineModule>;