shutro-erp 0.3.5 → 0.3.7

package/dist/sign/module.js

@@ -0,0 +1,167 @@
+/**
+ * The data layer of Sign (RFC 0024 §2.8): templates — a PDF with fields for each signer's role (signature, initials,
+ * date, text, checkbox), placed on a page as fractions of its width and height —; requests made from a template,
+ * often from a record (a quotation, a contract), with their signers in order or all at once; and each signer's link
+ * and one-time code (only hashes kept), what they filled in, when and from where. Once the last signer is done the
+ * PDF is sealed — the values stamped in, a certificate page added, its hash before and after kept — and stored.
+ */
+import { contactsShutro } from '../contacts/index.js';
+import { documentsShutro } from '../documents/index.js';
+import { messagingShutro } from '../messaging/index.js';
+import { orm } from '../server/orm.js';
+import { check, defineModel, defineModule, f, records } from './.kosh/bindings.js';
+import { beforeSend } from './sign.js';
+const ALL = ['read', 'write', 'create', 'unlink'];
+export const FIELD_KINDS = {
+    signature: 'Signature',
+    initials: 'Initials',
+    date: 'Date signed',
+    text: 'Text',
+    checkbox: 'Checkbox',
+};
+export const SignTemplate = defineModel('sign.template', {
+    label: 'Signing template',
+    recName: 'name',
+    order: ['name asc'],
+    archivable: true,
+    companyScoped: { required: true },
+    tracking: ['name', 'attachment'],
+    access: { 'sign.user': ['read'], 'sign.manager': [...ALL, 'export'] },
+    fields: {
+        name: f.char({ required: true }),
+        /** The PDF (an attachment of the template). */
+        attachment: f.many2one('storage.attachment', { ondelete: 'set null', label: 'PDF' }),
+        pages: f.integer({ label: 'Pages' }),
+        fields: f.one2many('sign.template.field', 'template', { label: 'Fields' }),
+        description: f.text(),
+    },
+});
+export const SignTemplateField = defineModel('sign.template.field', {
+    label: 'Signing field',
+    order: ['page asc', 'y asc', 'x asc', 'id asc'],
+    access: { 'sign.user': ['read'], 'sign.manager': ALL },
+    fields: {
+        template: f.many2one('sign.template', { required: true, ondelete: 'cascade' }),
+        /** Whose it is: "Customer", "Company". */
+        role: f.char({ required: true }),
+        kind: f.selection(FIELD_KINDS, {
+            required: true,
+            default: 'signature',
+            help: 'What the signer fills in here: a signature, initials, the date signed, a text or a checkbox.',
+        }),
+        label: f.char(),
+        page: f.integer({ required: true, default: 1 }),
+        /** From the page's top-left corner, as fractions of its width and height (0 to 1). */
+        x: f.decimal({ scale: 4, required: true, default: '0.1' }),
+        y: f.decimal({ scale: 4, required: true, default: '0.8' }),
+        width: f.decimal({ scale: 4, required: true, default: '0.3' }),
+        height: f.decimal({ scale: 4, required: true, default: '0.06' }),
+        required: f.boolean({ default: true }),
+    },
+    sqlConstraints: {
+        placed: {
+            check: orm.sql `page >= 1 AND x >= 0 AND y >= 0 AND width > 0 AND height > 0 AND x + width <= 1 AND y + height <= 1`,
+            message: 'A field is on a page, inside it.',
+        },
+    },
+});
+export const SignRequest = defineModel('sign.request', {
+    label: 'Signing request',
+    recName: 'name',
+    order: ['id desc'],
+    companyScoped: { required: true },
+    tracking: ['state'],
+    access: { 'sign.user': ['read', 'write', 'create'], 'sign.manager': [...ALL, 'export'] },
+    fields: {
+        name: f.char({ required: true }),
+        template: f.many2one('sign.template', { required: true, ondelete: 'restrict' }),
+        /** The record it is signed from (its signed PDF is attached to it). */
+        resModel: f.char({ label: 'For (model)' }),
+        resId: f.integer({ label: 'For (record)' }),
+        ordered: f.boolean({ default: true, label: 'Signers in order' }),
+        signers: f.one2many('sign.signer', 'request'),
+        message: f.text(),
+        /** The SHA-256 of the template's PDF when the request was sent, and of the sealed one. */
+        hashBefore: f.char({ label: 'Hash before' }),
+        hashAfter: f.char({ label: 'Hash after' }),
+        sealed: f.many2one('storage.attachment', { ondelete: 'set null', label: 'Signed PDF' }),
+        document: f.many2one('documents.document', { ondelete: 'set null', label: 'Document' }),
+        completedAt: f.datetime({ label: 'Completed at' }),
+        refusal: f.text({ label: 'Why it was refused' }),
+        state: f.state({
+            help: 'A request is out for signature once sent, and signed when the last signer is done, which seals the PDF.',
+            states: {
+                draft: 'Draft',
+                sent: 'Out for signature',
+                signed: 'Signed',
+                refused: 'Refused',
+                cancel: 'Cancelled',
+            },
+            initial: 'draft',
+            transitions: {
+                /** Checks the template and asks the signers (the first in order, or all). */
+                send: {
+                    from: ['draft'],
+                    to: 'sent',
+                    before: records('sign.request', async (requests) => {
+                        await beforeSend(requests.env, requests.ids);
+                    }),
+                },
+                complete: {
+                    from: ['sent'],
+                    to: 'signed',
+                    after: records('sign.request', async (requests) => {
+                        for (const id of requests.ids)
+                            await requests.env.emit('sign.request.signed', { id });
+                    }),
+                },
+                refuse: { from: ['sent'], to: 'refused' },
+                cancel: { from: ['draft', 'sent'], to: 'cancel' },
+            },
+        }),
+    },
+});
+export const SignSigner = defineModel('sign.signer', {
+    label: 'Signer',
+    order: ['sequence asc', 'id asc'],
+    access: { 'sign.user': ['read', 'write', 'create'], 'sign.manager': ALL },
+    fields: {
+        request: f.many2one('sign.request', { required: true, ondelete: 'cascade' }),
+        role: f.char({ required: true }),
+        name: f.char({ required: true }),
+        email: f.char({ required: true }),
+        partner: f.many2one('res.partner', { ondelete: 'set null' }),
+        sequence: f.integer({ required: true, default: 10 }),
+        state: f.selection({ waiting: 'Waiting', sent: 'Asked', signed: 'Signed', refused: 'Refused' }, {
+            required: true,
+            default: 'waiting',
+            help: 'Waiting for the signers before them, asked once their link is sent, then signed or refused.',
+        }),
+        tokenHash: f.char({ index: true, label: 'Link (hash)' }),
+        codeHash: f.char({ label: 'Code (hash)' }),
+        codeExpiresAt: f.datetime({ label: 'Code expires' }),
+        codeAttempts: f.integer({ required: true, default: 0 }),
+        /** What they filled in, by field id (a signature as a PNG data URL). */
+        values: f.json({ label: 'Values' }),
+        sentAt: f.datetime({ label: 'Asked at' }),
+        signedAt: f.datetime({ label: 'Signed at' }),
+        ip: f.char({ label: 'IP address' }),
+        userAgent: f.char({ label: 'Browser' }),
+    },
+    constraints: {
+        email: {
+            ...check('sign.signer', ['email'], async (signers) => signers.filter((s) => !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s.email)).map((s) => s.id)),
+            message: 'A signer has an email address.',
+        },
+    },
+});
+export const signShutro = defineModule({
+    name: 'sign',
+    version: '0.1.0',
+    depends: [contactsShutro, messagingShutro, documentsShutro],
+    groups: [
+        orm.defineGroup({ code: 'sign.user', label: 'Sign user', implies: ['contacts.user'] }),
+        orm.defineGroup({ code: 'sign.manager', label: 'Sign manager', implies: ['sign.user'] }),
+    ],
+    models: [SignTemplate, SignTemplateField, SignRequest, SignSigner],
+});

package/dist/sign/sign.d.ts

@@ -0,0 +1,82 @@
+import { type Mailer } from '../mail/index.js';
+import { type Storage } from '../storage/index.js';
+import type { Env } from './.kosh/bindings.js';
+export declare const sha256: (bytes: Uint8Array) => string;
+declare let config: {
+    mailer: Mailer | undefined;
+    apiUrl: string;
+    /** The file store, asked for when a PDF is read or written (a server may have none). */
+    storage: (() => Storage) | null;
+};
+export declare function configureSign(next: Partial<typeof config>): void;
+/** A template's PDF, as bytes. */
+export declare function templatePdf(env: Env, template: number): Promise<Uint8Array>;
+/** Stores a PDF as the template's (as the system, the template read by the caller): its page count follows. */
+export declare function setTemplatePdf(env: Env, template: number, file: {
+    name: string;
+    data: Uint8Array;
+}): Promise<{
+    pages: number;
+}>;
+/**
+ * As requests are sent: the template has its PDF and a signer for every role of its fields; the PDF's hash is
+ * kept; the first signer (in order) or all of them are asked.
+ */
+export declare function beforeSend(env: Env, ids: readonly number[]): Promise<void>;
+/** The signer a link belongs to, while they are asked and the request is out for signature. */
+export declare function signerOf(env: Env, token: string): Promise<{
+    id: number;
+    name: string;
+    role: string;
+    request: {
+        id: number;
+        name: string;
+        company: string;
+        message: string | null;
+    };
+    fields: {
+        id: number;
+        kind: string;
+        label: string | null;
+        page: number;
+        required: boolean;
+    }[];
+} | null>;
+/** A one-time code by email to the link's signer (a new one replaces the last). */
+export declare function sendCode(env: Env, token: string): Promise<void>;
+/** A wrong or expired code: counted (the count commits), then answered with 401 by the route. */
+export declare class WrongCode extends Error {
+}
+/**
+ * Signs for the link's signer with their code: their values kept with when and from where; the next signer asked
+ * (in order), or — the last — the PDF sealed and the request completed.
+ */
+export declare function signWith(env: Env, token: string, input: {
+    code: string;
+    values: Record<string, unknown>;
+    ip: string;
+    userAgent: string;
+}): Promise<{
+    completed: boolean;
+}>;
+/** Refuses for the link's signer, with their code and why: the request is refused, the others told. */
+export declare function refuseWith(env: Env, token: string, input: {
+    code: string;
+    reason: string;
+}): Promise<void>;
+/** Makes a request from a template for a record (or none), with its signers; a draft, to send. */
+export declare function requestFrom(env: Env, input: {
+    template: number;
+    name?: string;
+    model?: string;
+    id?: number;
+    ordered?: boolean;
+    message?: string;
+    signers: {
+        role: string;
+        name: string;
+        email: string;
+        partner?: number;
+    }[];
+}): Promise<number>;
+export {};