@voyantjs/legal 0.1.0

package/dist/contracts/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/contracts/service.ts"],"names":[],"mappings":"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"}

package/dist/contracts/service.js

@@ -0,0 +1,570 @@
+import { and, desc, eq, ilike, or, sql } from "drizzle-orm";
+import { contractAttachments, contractNumberSeries, contractSignatures, contracts, contractTemplates, contractTemplateVersions, } from "./schema.js";
+function toTimestamp(value) {
+    return value ? new Date(value) : null;
+}
+// ============================================================================
+// Template rendering
+// ============================================================================
+/**
+ * Resolve a dot-path against an object, supporting array index accessors:
+ *   "a.b.c"          → obj.a.b.c
+ *   "arr[0].name"    → obj.arr[0].name
+ *   "a.b[2].c"       → obj.a.b[2].c
+ */
+function resolvePath(obj, path) {
+    if (obj === null || obj === undefined)
+        return undefined;
+    const segments = [];
+    const parts = path.split(".");
+    for (const part of parts) {
+        if (!part)
+            continue;
+        // Match "name[0]" → ["name", 0]
+        const indexMatches = [...part.matchAll(/([^[\]]+)|\[(\d+)\]/g)];
+        for (const match of indexMatches) {
+            if (match[1] !== undefined)
+                segments.push(match[1]);
+            else if (match[2] !== undefined)
+                segments.push(Number.parseInt(match[2], 10));
+        }
+    }
+    let current = obj;
+    for (const seg of segments) {
+        if (current === null || current === undefined)
+            return undefined;
+        if (typeof seg === "number") {
+            if (!Array.isArray(current))
+                return undefined;
+            current = current[seg];
+        }
+        else {
+            if (typeof current !== "object")
+                return undefined;
+            current = current[seg];
+        }
+    }
+    return current;
+}
+function stringifyValue(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return JSON.stringify(value);
+}
+const MUSTACHE_RE = /\{\{\s*([^}]+?)\s*\}\}/g;
+function renderMustache(body, variables) {
+    return body.replace(MUSTACHE_RE, (_, path) => {
+        const resolved = resolvePath(variables, path.trim());
+        return stringifyValue(resolved);
+    });
+}
+function walkLexical(node, variables) {
+    const next = { ...node };
+    if (typeof next.text === "string") {
+        next.text = renderMustache(next.text, variables);
+    }
+    if (Array.isArray(next.children)) {
+        next.children = next.children.map((child) => walkLexical(child, variables));
+    }
+    return next;
+}
+/**
+ * Substitute variables in a template body. Supports:
+ * - markdown / html / plain text: mustache replacement `{{path.to.value}}`
+ * - lexical_json: walks the AST, rewriting text nodes only
+ */
+export function renderTemplate(body, bodyFormat, variables) {
+    if (bodyFormat === "lexical_json") {
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed && typeof parsed === "object") {
+                const obj = parsed;
+                if (obj.root && typeof obj.root === "object") {
+                    const result = { ...obj, root: walkLexical(obj.root, variables) };
+                    return JSON.stringify(result);
+                }
+                return JSON.stringify(walkLexical(obj, variables));
+            }
+            return body;
+        }
+        catch {
+            // Fall through to mustache on parse error (treat as string template)
+            return renderMustache(body, variables);
+        }
+    }
+    return renderMustache(body, variables);
+}
+/**
+ * Validate variable values against a template's variableSchema (JSON object
+ * shape describing required fields). Returns a list of issues; empty array
+ * means valid.
+ */
+export function validateTemplateVariables(variableSchema, values) {
+    const issues = [];
+    if (!variableSchema || typeof variableSchema !== "object")
+        return issues;
+    const schema = variableSchema;
+    const requiredList = Array.isArray(schema.required) ? schema.required : [];
+    for (const key of requiredList) {
+        const resolved = resolvePath(values, key);
+        if (resolved === undefined || resolved === null || resolved === "") {
+            issues.push(`missing required variable: ${key}`);
+        }
+    }
+    return issues;
+}
+// ============================================================================
+// Number allocation
+// ============================================================================
+function currentPeriodBoundary(strategy, now) {
+    if (strategy === "never")
+        return null;
+    if (strategy === "annual") {
+        return new Date(Date.UTC(now.getUTCFullYear(), 0, 1));
+    }
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+}
+function formatNumber(prefix, separator, sequence, padLength) {
+    const padded = String(sequence).padStart(padLength, "0");
+    return `${prefix}${separator}${padded}`;
+}
+/**
+ * Transactionally allocate the next sequence number for a series. Honors the
+ * reset strategy (never/annual/monthly). Uses SELECT ... FOR UPDATE to avoid
+ * concurrent-increment races.
+ */
+export async function allocateContractNumber(db, seriesId) {
+    return db.transaction(async (tx) => {
+        const rows = await tx.execute(sql `SELECT * FROM ${contractNumberSeries}
+          WHERE ${contractNumberSeries.id} = ${seriesId}
+          FOR UPDATE`);
+        const row = rows[0];
+        if (!row)
+            return null;
+        const strategy = row.reset_strategy;
+        const prefix = row.prefix ?? "";
+        const separator = row.separator ?? "";
+        const padLength = row.pad_length ?? 4;
+        const currentSequence = row.current_sequence ?? 0;
+        const resetAt = row.reset_at ? new Date(row.reset_at) : null;
+        const now = new Date();
+        const boundary = currentPeriodBoundary(strategy, now);
+        const shouldReset = boundary !== null && (resetAt === null || resetAt.getTime() < boundary.getTime());
+        const nextSequence = shouldReset ? 1 : currentSequence + 1;
+        const nextResetAt = strategy === "never" ? resetAt : boundary;
+        await tx
+            .update(contractNumberSeries)
+            .set({
+            currentSequence: nextSequence,
+            resetAt: nextResetAt,
+            updatedAt: new Date(),
+        })
+            .where(eq(contractNumberSeries.id, seriesId));
+        return {
+            number: formatNumber(prefix, separator, nextSequence, padLength),
+            sequence: nextSequence,
+        };
+    });
+}
+// ============================================================================
+// Service
+// ============================================================================
+async function paginate(rowsQuery, countQuery, limit, offset) {
+    const [data, countResult] = await Promise.all([rowsQuery, countQuery]);
+    return { data, total: countResult[0]?.total ?? 0, limit, offset };
+}
+export const contractsService = {
+    // ---------- contract templates ----------
+    async listTemplates(db, query) {
+        const conditions = [];
+        if (query.scope)
+            conditions.push(eq(contractTemplates.scope, query.scope));
+        if (query.language)
+            conditions.push(eq(contractTemplates.language, query.language));
+        if (query.active !== undefined)
+            conditions.push(eq(contractTemplates.active, query.active));
+        if (query.search) {
+            const term = `%${query.search}%`;
+            conditions.push(or(ilike(contractTemplates.name, term), ilike(contractTemplates.slug, term), ilike(contractTemplates.description, term)));
+        }
+        const where = conditions.length ? and(...conditions) : undefined;
+        return paginate(db
+            .select()
+            .from(contractTemplates)
+            .where(where)
+            .limit(query.limit)
+            .offset(query.offset)
+            .orderBy(desc(contractTemplates.updatedAt)), db.select({ total: sql `count(*)::int` }).from(contractTemplates).where(where), query.limit, query.offset);
+    },
+    async getTemplateById(db, id) {
+        const [row] = await db
+            .select()
+            .from(contractTemplates)
+            .where(eq(contractTemplates.id, id))
+            .limit(1);
+        return row ?? null;
+    },
+    async createTemplate(db, data) {
+        const [row] = await db.insert(contractTemplates).values(data).returning();
+        return row ?? null;
+    },
+    async updateTemplate(db, id, data) {
+        const [row] = await db
+            .update(contractTemplates)
+            .set({ ...data, updatedAt: new Date() })
+            .where(eq(contractTemplates.id, id))
+            .returning();
+        return row ?? null;
+    },
+    async deleteTemplate(db, id) {
+        const [row] = await db
+            .delete(contractTemplates)
+            .where(eq(contractTemplates.id, id))
+            .returning({ id: contractTemplates.id });
+        return row ?? null;
+    },
+    // ---------- contract template versions ----------
+    listTemplateVersions(db, templateId) {
+        return db
+            .select()
+            .from(contractTemplateVersions)
+            .where(eq(contractTemplateVersions.templateId, templateId))
+            .orderBy(desc(contractTemplateVersions.version));
+    },
+    async getTemplateVersionById(db, id) {
+        const [row] = await db
+            .select()
+            .from(contractTemplateVersions)
+            .where(eq(contractTemplateVersions.id, id))
+            .limit(1);
+        return row ?? null;
+    },
+    async createTemplateVersion(db, templateId, data) {
+        return db.transaction(async (tx) => {
+            const [template] = await tx
+                .select({ id: contractTemplates.id })
+                .from(contractTemplates)
+                .where(eq(contractTemplates.id, templateId))
+                .limit(1);
+            if (!template)
+                return null;
+            const [maxRow] = await tx
+                .select({ max: sql `coalesce(max(${contractTemplateVersions.version}), 0)::int` })
+                .from(contractTemplateVersions)
+                .where(eq(contractTemplateVersions.templateId, templateId));
+            const nextVersion = (maxRow?.max ?? 0) + 1;
+            const [version] = await tx
+                .insert(contractTemplateVersions)
+                .values({
+                templateId,
+                version: nextVersion,
+                bodyFormat: data.bodyFormat,
+                body: data.body,
+                variableSchema: data.variableSchema ?? null,
+                changelog: data.changelog ?? null,
+                createdBy: data.createdBy ?? null,
+            })
+                .returning();
+            if (version) {
+                await tx
+                    .update(contractTemplates)
+                    .set({ currentVersionId: version.id, updatedAt: new Date() })
+                    .where(eq(contractTemplates.id, templateId));
+            }
+            return version ?? null;
+        });
+    },
+    // ---------- contract number series ----------
+    async listSeries(db) {
+        return db.select().from(contractNumberSeries).orderBy(desc(contractNumberSeries.updatedAt));
+    },
+    async getSeriesById(db, id) {
+        const [row] = await db
+            .select()
+            .from(contractNumberSeries)
+            .where(eq(contractNumberSeries.id, id))
+            .limit(1);
+        return row ?? null;
+    },
+    async createSeries(db, data) {
+        const [row] = await db.insert(contractNumberSeries).values(data).returning();
+        return row ?? null;
+    },
+    async updateSeries(db, id, data) {
+        const [row] = await db
+            .update(contractNumberSeries)
+            .set({ ...data, updatedAt: new Date() })
+            .where(eq(contractNumberSeries.id, id))
+            .returning();
+        return row ?? null;
+    },
+    async deleteSeries(db, id) {
+        const [row] = await db
+            .delete(contractNumberSeries)
+            .where(eq(contractNumberSeries.id, id))
+            .returning({ id: contractNumberSeries.id });
+        return row ?? null;
+    },
+    // ---------- contracts ----------
+    async listContracts(db, query) {
+        const conditions = [];
+        if (query.scope)
+            conditions.push(eq(contracts.scope, query.scope));
+        if (query.status)
+            conditions.push(eq(contracts.status, query.status));
+        if (query.personId)
+            conditions.push(eq(contracts.personId, query.personId));
+        if (query.organizationId)
+            conditions.push(eq(contracts.organizationId, query.organizationId));
+        if (query.supplierId)
+            conditions.push(eq(contracts.supplierId, query.supplierId));
+        if (query.bookingId)
+            conditions.push(eq(contracts.bookingId, query.bookingId));
+        if (query.orderId)
+            conditions.push(eq(contracts.orderId, query.orderId));
+        if (query.search) {
+            const term = `%${query.search}%`;
+            conditions.push(or(ilike(contracts.title, term), ilike(contracts.contractNumber, term)));
+        }
+        const where = conditions.length ? and(...conditions) : undefined;
+        return paginate(db
+            .select()
+            .from(contracts)
+            .where(where)
+            .limit(query.limit)
+            .offset(query.offset)
+            .orderBy(desc(contracts.createdAt)), db.select({ total: sql `count(*)::int` }).from(contracts).where(where), query.limit, query.offset);
+    },
+    async getContractById(db, id) {
+        const [row] = await db.select().from(contracts).where(eq(contracts.id, id)).limit(1);
+        return row ?? null;
+    },
+    async createContract(db, data) {
+        const [row] = await db
+            .insert(contracts)
+            .values({
+            ...data,
+            expiresAt: toTimestamp(data.expiresAt),
+        })
+            .returning();
+        return row ?? null;
+    },
+    async updateContract(db, id, data) {
+        const [row] = await db
+            .update(contracts)
+            .set({
+            ...data,
+            expiresAt: data.expiresAt === undefined ? undefined : toTimestamp(data.expiresAt),
+            updatedAt: new Date(),
+        })
+            .where(eq(contracts.id, id))
+            .returning();
+        return row ?? null;
+    },
+    async deleteContract(db, id) {
+        const [existing] = await db
+            .select({ id: contracts.id, status: contracts.status })
+            .from(contracts)
+            .where(eq(contracts.id, id))
+            .limit(1);
+        if (!existing)
+            return { status: "not_found" };
+        if (existing.status !== "draft")
+            return { status: "not_draft" };
+        await db.delete(contracts).where(eq(contracts.id, id));
+        return { status: "deleted" };
+    },
+    // ---------- lifecycle actions ----------
+    /**
+     * Transition a draft contract to `issued`: renders body from the template
+     * version, allocates a contract number if a series is set, timestamps
+     * `issuedAt`. Returns null if contract is missing or not in `draft`.
+     */
+    async issueContract(db, contractId) {
+        return db.transaction(async (tx) => {
+            const [contract] = await tx
+                .select()
+                .from(contracts)
+                .where(eq(contracts.id, contractId))
+                .limit(1);
+            if (!contract)
+                return { status: "not_found" };
+            if (contract.status !== "draft")
+                return { status: "not_draft" };
+            // Render body from template version if referenced
+            let renderedBody = contract.renderedBody;
+            let renderedBodyFormat = contract.renderedBodyFormat;
+            if (contract.templateVersionId) {
+                const [version] = await tx
+                    .select()
+                    .from(contractTemplateVersions)
+                    .where(eq(contractTemplateVersions.id, contract.templateVersionId))
+                    .limit(1);
+                if (version) {
+                    const vars = contract.variables ?? {};
+                    renderedBody = renderTemplate(version.body, version.bodyFormat, vars);
+                    renderedBodyFormat = version.bodyFormat;
+                }
+            }
+            // Allocate contract number if not already set and a series is linked
+            let contractNumber = contract.contractNumber;
+            if (!contractNumber && contract.seriesId) {
+                const allocated = await allocateContractNumber(tx, contract.seriesId);
+                if (allocated)
+                    contractNumber = allocated.number;
+            }
+            const [updated] = await tx
+                .update(contracts)
+                .set({
+                status: "issued",
+                issuedAt: new Date(),
+                renderedBody,
+                renderedBodyFormat,
+                contractNumber,
+                updatedAt: new Date(),
+            })
+                .where(eq(contracts.id, contractId))
+                .returning();
+            return { status: "issued", contract: updated ?? null };
+        });
+    },
+    async sendContract(db, contractId) {
+        const [contract] = await db
+            .select({ id: contracts.id, status: contracts.status })
+            .from(contracts)
+            .where(eq(contracts.id, contractId))
+            .limit(1);
+        if (!contract)
+            return { status: "not_found" };
+        if (contract.status !== "issued" && contract.status !== "sent") {
+            return { status: "not_issued" };
+        }
+        const [updated] = await db
+            .update(contracts)
+            .set({ status: "sent", sentAt: new Date(), updatedAt: new Date() })
+            .where(eq(contracts.id, contractId))
+            .returning();
+        return { status: "sent", contract: updated ?? null };
+    },
+    async voidContract(db, contractId) {
+        const [contract] = await db
+            .select({ id: contracts.id, status: contracts.status })
+            .from(contracts)
+            .where(eq(contracts.id, contractId))
+            .limit(1);
+        if (!contract)
+            return { status: "not_found" };
+        if (contract.status === "void")
+            return { status: "already_void" };
+        const [updated] = await db
+            .update(contracts)
+            .set({ status: "void", voidedAt: new Date(), updatedAt: new Date() })
+            .where(eq(contracts.id, contractId))
+            .returning();
+        return { status: "voided", contract: updated ?? null };
+    },
+    // ---------- signatures ----------
+    listSignatures(db, contractId) {
+        return db
+            .select()
+            .from(contractSignatures)
+            .where(eq(contractSignatures.contractId, contractId))
+            .orderBy(desc(contractSignatures.signedAt));
+    },
+    async signContract(db, contractId, data) {
+        return db.transaction(async (tx) => {
+            const [contract] = await tx
+                .select()
+                .from(contracts)
+                .where(eq(contracts.id, contractId))
+                .limit(1);
+            if (!contract)
+                return { status: "not_found" };
+            if (contract.status !== "issued" && contract.status !== "sent") {
+                return { status: "not_signable" };
+            }
+            const [signature] = await tx
+                .insert(contractSignatures)
+                .values({ ...data, contractId })
+                .returning();
+            // Transition: first signature → signed; two-party → executed if both sides signed.
+            // MVP: single-signer flow → mark as "signed". Callers that need multi-party
+            // workflows should issue additional signatures and explicitly call execute.
+            const [updated] = await tx
+                .update(contracts)
+                .set({ status: "signed", updatedAt: new Date() })
+                .where(eq(contracts.id, contractId))
+                .returning();
+            return { status: "signed", contract: updated ?? null, signature: signature ?? null };
+        });
+    },
+    async executeContract(db, contractId) {
+        const [contract] = await db
+            .select({ id: contracts.id, status: contracts.status })
+            .from(contracts)
+            .where(eq(contracts.id, contractId))
+            .limit(1);
+        if (!contract)
+            return { status: "not_found" };
+        if (contract.status !== "signed")
+            return { status: "not_signed" };
+        const [updated] = await db
+            .update(contracts)
+            .set({ status: "executed", executedAt: new Date(), updatedAt: new Date() })
+            .where(eq(contracts.id, contractId))
+            .returning();
+        return { status: "executed", contract: updated ?? null };
+    },
+    // ---------- attachments ----------
+    listAttachments(db, contractId) {
+        return db
+            .select()
+            .from(contractAttachments)
+            .where(eq(contractAttachments.contractId, contractId))
+            .orderBy(desc(contractAttachments.createdAt));
+    },
+    async createAttachment(db, contractId, data) {
+        const [contract] = await db
+            .select({ id: contracts.id })
+            .from(contracts)
+            .where(eq(contracts.id, contractId))
+            .limit(1);
+        if (!contract)
+            return null;
+        const [row] = await db
+            .insert(contractAttachments)
+            .values({ ...data, contractId })
+            .returning();
+        return row ?? null;
+    },
+    async updateAttachment(db, attachmentId, data) {
+        const [row] = await db
+            .update(contractAttachments)
+            .set(data)
+            .where(eq(contractAttachments.id, attachmentId))
+            .returning();
+        return row ?? null;
+    },
+    async deleteAttachment(db, attachmentId) {
+        const [row] = await db
+            .delete(contractAttachments)
+            .where(eq(contractAttachments.id, attachmentId))
+            .returning({ id: contractAttachments.id });
+        return row ?? null;
+    },
+    // ---------- preview ----------
+    /**
+     * Preview render: substitute variables against an arbitrary body without
+     * touching the database. Used by `/v1/admin/contracts/:id/render` and
+     * `/v1/admin/contracts/templates/:id/preview`.
+     */
+    renderPreview(input) {
+        const body = input.body ?? "";
+        const format = input.bodyFormat ?? "markdown";
+        return renderTemplate(body, format, input.variables);
+    },
+};