@kirjapro/mcp-server 0.6.3 → 0.8.0

package/dist/tools/invoices.js

@@ -1,489 +0,0 @@
-import { z } from "zod";
-import { getSupabase, getCompanyId } from "../auth.js";
-import { addDaysToIsoDate, clampPagination, helsinkiDateString, paginate, toErrorContent, toDryRunResponse, toResult, sanitizeDbError, roundCents, tagCustomer, withIdempotency, IDEMPOTENCY_KEY_SCHEMA, ISO_DATE_SCHEMA, DRY_RUN_SCHEMA, READ_ONLY_ANNOTATIONS, WRITE_ANNOTATIONS, DESTRUCTIVE_ANNOTATIONS, } from "../utils.js";
-import { VALID_TRANSITIONS } from "../types.js";
-/**
- * Generate Finnish reference number (viitenumero) with 7-3-1 check digit.
- */
-function generateReferenceNumber(baseNumber) {
-    const digits = baseNumber.replace(/\D/g, "");
-    if (digits.length < 1 || digits.length > 19) {
-        throw new Error("Base number must be 1-19 digits");
-    }
-    const weights = [7, 3, 1];
-    let sum = 0;
-    for (let i = digits.length - 1, w = 0; i >= 0; i--, w++) {
-        sum += parseInt(digits[i]) * weights[w % 3];
-    }
-    const checkDigit = (10 - (sum % 10)) % 10;
-    return digits + checkDigit;
-}
-const LIST_INVOICES_ROW_SHAPE = {
-    id: z.string().uuid(),
-    invoice_number: z.string(),
-    reference_number: z.string().nullable(),
-    invoice_date: z.string(),
-    due_date: z.string().nullable(),
-    status: z.string(),
-    subtotal: z.number(),
-    vat_total: z.number(),
-    total: z.number(),
-    notes: z.string().nullable(),
-    customers: z
-        .object({
-        name: z.string().nullable(),
-        business_id: z.string().nullable(),
-    })
-        .nullable(),
-};
-const GET_INVOICE_OUTPUT_SHAPE = {
-    id: z.string().uuid(),
-    invoice_number: z.string(),
-    reference_number: z.string().nullable(),
-    invoice_date: z.string(),
-    due_date: z.string().nullable(),
-    status: z.string(),
-    subtotal: z.number(),
-    vat_total: z.number(),
-    total: z.number(),
-    notes: z.string().nullable(),
-    created_at: z.string().nullable(),
-    // `.optional()` is explicit since Zod 4 — bare `z.unknown()` was implicitly
-    // key-optional in Zod 3 but is now required. These three are joined relations
-    // that may be absent when the row is fetched without the corresponding
-    // .select() include.
-    customers: z.unknown().optional(),
-    invoice_lines: z.unknown().optional(),
-    invoice_payments: z.unknown().optional(),
-    vat_breakdown: z.array(z.object({
-        vat_rate: z.number(),
-        subtotal: z.number(),
-        vat_amount: z.number(),
-        total: z.number(),
-    })),
-    paid_total: z.number(),
-    remaining_balance: z.number(),
-};
-export function registerInvoiceTools(server) {
-    // ---- READ: List Invoices ----
-    server.registerTool("kirjapro_list_invoices", {
-        description: "List invoices with customer names. Filter by status (draft, sent, paid, overdue, cancelled).",
-        inputSchema: {
-            status: z
-                .enum(["draft", "sent", "paid", "partial", "overdue", "cancelled"])
-                .optional()
-                .describe("Filter by invoice status"),
-            limit: z
-                .number()
-                .min(1)
-                .max(200)
-                .default(50)
-                .describe("Max results (default 50)"),
-            offset: z.number().min(0).default(0).describe("Skip first N results"),
-        },
-        outputSchema: {
-            results: z.array(z.object(LIST_INVOICES_ROW_SHAPE).passthrough()),
-            total_count: z.number(),
-            has_more: z.boolean(),
-            next_offset: z.number(),
-        },
-        annotations: READ_ONLY_ANNOTATIONS,
-    }, async (params) => {
-        const supabase = getSupabase();
-        const companyId = getCompanyId();
-        const { limit, offset } = clampPagination(params.limit, params.offset);
-        let query = supabase
-            .from("invoices")
-            .select(`
-          id, invoice_number, reference_number, invoice_date, due_date,
-          status, subtotal, vat_total, total, notes,
-          customers ( name, business_id )
-        `, { count: "exact" })
-            .eq("company_id", companyId)
-            .order("invoice_date", { ascending: false })
-            .order("id", { ascending: false });
-        if (params.status) {
-            query = query.eq("status", params.status);
-        }
-        query = query.range(offset, offset + limit - 1);
-        const { data, count, error } = await query;
-        if (error) {
-            return toErrorContent(sanitizeDbError("Failed to list invoices", error));
-        }
-        const tagged = (data || []).map((row) => ({
-            ...row,
-            customers: tagCustomer(row.customers),
-        }));
-        return toResult(paginate(tagged, count || 0, offset, limit));
-    });
-    // ---- WRITE: Create Invoice ----
-    server.registerTool("kirjapro_create_invoice", {
-        description: "Create a new sales invoice with line items. Automatically generates invoice number, reference number (viitenumero), and calculates VAT. Returns the complete invoice.",
-        inputSchema: {
-            customerId: z.string().uuid().describe("Customer UUID"),
-            invoiceDate: ISO_DATE_SCHEMA
-                .describe("Invoice date (YYYY-MM-DD)"),
-            paymentTermDays: z
-                .number()
-                .min(0)
-                .max(365)
-                .default(14)
-                .describe("Payment term in days (default 14)"),
-            notes: z.string().optional().describe("Notes printed on the invoice"),
-            lines: z
-                .array(z.object({
-                description: z.string().min(1).describe("Line item description"),
-                quantity: z.number().min(0).describe("Quantity"),
-                unit: z.string().default("kpl").describe("Unit (kpl, h, kk, etc.)"),
-                unitPrice: z
-                    .number()
-                    .finite()
-                    .min(-1_000_000_000)
-                    .max(1_000_000_000)
-                    .describe("Unit price in EUR (excl. VAT). Can be negative for credit lines."),
-                vatRate: z
-                    .enum(["25.5", "13.5", "10", "0"])
-                    .default("25.5")
-                    .describe("VAT rate"),
-            }))
-                .min(1)
-                .describe("Invoice line items"),
-            idempotencyKey: IDEMPOTENCY_KEY_SCHEMA,
-        },
-        annotations: WRITE_ANNOTATIONS,
-    }, async (params) => {
-        const supabase = getSupabase();
-        const companyId = getCompanyId();
-        return withIdempotency(supabase, companyId, "kirjapro_create_invoice", params.idempotencyKey, params, async () => {
-            // Verify customer exists
-            const { data: customer, error: custError } = await supabase
-                .from("customers")
-                .select("id, name")
-                .eq("id", params.customerId)
-                .eq("company_id", companyId)
-                .single();
-            if (custError || !customer) {
-                return toErrorContent(`Customer ${params.customerId} not found. ` +
-                    `Use kirjapro_list_customers to find customer IDs.`);
-            }
-            // Get next invoice number atomically (advisory-locked)
-            const { data: invoiceNumber, error: numError } = await supabase.rpc("get_next_invoice_number", {
-                p_company_id: companyId,
-            });
-            if (numError || !invoiceNumber) {
-                return toErrorContent(numError ? sanitizeDbError("Failed to generate invoice number", numError) : "Failed to generate invoice number.");
-            }
-            const referenceNumber = generateReferenceNumber(invoiceNumber.replace(/\D/g, ""));
-            const dueDateStr = addDaysToIsoDate(params.invoiceDate, params.paymentTermDays);
-            // Calculate line totals
-            const calculatedLines = params.lines.map((line, i) => {
-                const vatRate = parseFloat(line.vatRate);
-                const subtotal = roundCents(line.quantity * line.unitPrice);
-                const vatAmount = roundCents(subtotal * (vatRate / 100));
-                const total = roundCents(subtotal + vatAmount);
-                return {
-                    line_number: i + 1,
-                    description: line.description,
-                    quantity: line.quantity,
-                    unit: line.unit,
-                    unit_price: line.unitPrice,
-                    vat_rate: vatRate,
-                    subtotal,
-                    vat_amount: vatAmount,
-                    total,
-                };
-            });
-            const subtotal = roundCents(calculatedLines.reduce((s, l) => s + l.subtotal, 0));
-            const vatTotal = roundCents(calculatedLines.reduce((s, l) => s + l.vat_amount, 0));
-            const total = roundCents(subtotal + vatTotal);
-            const { data: invoiceId, error: invError } = await supabase.rpc("create_invoice_with_lines", {
-                p_company_id: companyId,
-                p_customer_id: params.customerId,
-                p_invoice_number: invoiceNumber,
-                p_reference_number: referenceNumber,
-                p_invoice_date: params.invoiceDate,
-                p_due_date: dueDateStr,
-                p_status: "draft",
-                p_subtotal: subtotal,
-                p_vat_total: vatTotal,
-                p_total: total,
-                p_notes: params.notes || "",
-                p_lines: calculatedLines,
-            });
-            if (invError || !invoiceId) {
-                return toErrorContent(invError ? sanitizeDbError("Failed to create invoice", invError) : "Failed to create invoice.");
-            }
-            const { data: invoice, error: fetchError } = await supabase
-                .from("invoices")
-                .select("id, invoice_number, reference_number, invoice_date, due_date, status, subtotal, vat_total, total, notes, created_at")
-                .eq("id", invoiceId)
-                .eq("company_id", companyId)
-                .single();
-            if (fetchError || !invoice) {
-                return toErrorContent(fetchError ? sanitizeDbError("Invoice created but fetch failed", fetchError) : "Invoice created but could not be retrieved.");
-            }
-            return toResult({
-                message: `Invoice ${invoiceNumber} created for ${customer.name}`,
-                invoice: {
-                    ...invoice,
-                    customer_name: customer.name,
-                    lines: calculatedLines,
-                },
-            });
-        });
-    });
-    // ---- WRITE: Record Payment ----
-    server.registerTool("kirjapro_record_payment", {
-        description: 'Record a payment against an invoice. Automatically updates invoice status to "paid" when fully paid, or keeps "sent" if partially paid. Returns payment details and updated invoice status.',
-        inputSchema: {
-            invoiceId: z.string().uuid().describe("Invoice UUID"),
-            paymentDate: ISO_DATE_SCHEMA
-                .describe("Payment date (YYYY-MM-DD)"),
-            amount: z
-                .number()
-                .finite()
-                .min(0.01)
-                .max(1_000_000_000)
-                .describe("Payment amount in EUR"),
-            paymentMethod: z
-                .string()
-                .default("bank_transfer")
-                .describe("Payment method (bank_transfer, cash, card)"),
-            reference: z.string().optional().describe("Payment reference"),
-            notes: z.string().optional().describe("Payment notes"),
-            idempotencyKey: IDEMPOTENCY_KEY_SCHEMA,
-        },
-        annotations: WRITE_ANNOTATIONS,
-    }, async (params) => {
-        const supabase = getSupabase();
-        const companyId = getCompanyId();
-        return withIdempotency(supabase, companyId, "kirjapro_record_payment", params.idempotencyKey, params, async () => {
-            // Fetch invoice with existing payments
-            const { data: invoice, error: invError } = await supabase
-                .from("invoices")
-                .select(`
-          id, invoice_number, total, status,
-          invoice_payments ( amount )
-        `)
-                .eq("id", params.invoiceId)
-                .eq("company_id", companyId)
-                .single();
-            if (invError || !invoice) {
-                return toErrorContent(`Invoice ${params.invoiceId} not found. Use kirjapro_list_invoices to find invoice IDs.`);
-            }
-            if (invoice.status === "paid") {
-                return toErrorContent(`Invoice ${invoice.invoice_number} is already fully paid.`);
-            }
-            if (invoice.status === "cancelled") {
-                return toErrorContent(`Invoice ${invoice.invoice_number} is cancelled and cannot accept payments.`);
-            }
-            const paidSoFar = roundCents((invoice.invoice_payments || []).reduce((s, p) => s + (p.amount || 0), 0));
-            const remaining = roundCents(invoice.total - paidSoFar);
-            if (params.amount > remaining + 0.01) {
-                return toErrorContent(`Payment amount ${params.amount.toFixed(2)} exceeds remaining balance ${remaining.toFixed(2)} EUR ` +
-                    `on invoice ${invoice.invoice_number} (total: ${invoice.total.toFixed(2)}, paid: ${paidSoFar.toFixed(2)}). ` +
-                    `Reduce the payment amount to ${remaining.toFixed(2)} or less.`);
-            }
-            const { data: paymentResult, error: payError } = await supabase.rpc("record_invoice_payment", {
-                p_company_id: companyId,
-                p_invoice_id: params.invoiceId,
-                p_payment_date: params.paymentDate,
-                p_amount: params.amount,
-                p_payment_method: params.paymentMethod,
-                p_reference: params.reference || undefined,
-                p_notes: params.notes || undefined,
-            });
-            if (payError || !paymentResult) {
-                return toErrorContent(payError ? sanitizeDbError("Failed to record payment", payError) : "Failed to record payment.");
-            }
-            const result = paymentResult;
-            return toResult({
-                message: `Payment of ${params.amount.toFixed(2)} EUR recorded on invoice ${invoice.invoice_number}`,
-                payment_id: result.payment_id,
-                invoice_status: result.invoice_status,
-                remaining_balance: result.remaining_balance,
-            });
-        });
-    });
-    // ---- READ: Get Invoice Detail ----
-    server.registerTool("kirjapro_get_invoice", {
-        description: "Get a single invoice with full detail: customer info, line items, payments, VAT breakdown, and remaining balance.",
-        inputSchema: {
-            invoiceId: z.string().uuid().describe("Invoice UUID"),
-        },
-        outputSchema: GET_INVOICE_OUTPUT_SHAPE,
-        annotations: READ_ONLY_ANNOTATIONS,
-    }, async (params) => {
-        const supabase = getSupabase();
-        const companyId = getCompanyId();
-        const { data: invoice, error } = await supabase
-            .from("invoices")
-            .select(`
-          id, invoice_number, reference_number, invoice_date, due_date,
-          status, subtotal, vat_total, total, notes, created_at,
-          customers ( id, name, business_id, email, address, postal_code, city ),
-          invoice_lines ( id, line_number, description, quantity, unit, unit_price, vat_rate, subtotal, vat_amount, total ),
-          invoice_payments ( id, payment_date, amount, payment_method, reference )
-        `)
-            .eq("id", params.invoiceId)
-            .eq("company_id", companyId)
-            .single();
-        if (error || !invoice) {
-            return toErrorContent(`Invoice ${params.invoiceId} not found. Use kirjapro_list_invoices to find invoice IDs.`);
-        }
-        // Calculate VAT breakdown by rate
-        const vatMap = new Map();
-        for (const line of invoice
-            .invoice_lines || []) {
-            const existing = vatMap.get(line.vat_rate) || {
-                vat_rate: line.vat_rate,
-                subtotal: 0,
-                vat_amount: 0,
-                total: 0,
-            };
-            existing.subtotal += line.subtotal || 0;
-            existing.vat_amount += line.vat_amount || 0;
-            existing.total += line.total || 0;
-            vatMap.set(line.vat_rate, existing);
-        }
-        const vatBreakdown = [...vatMap.values()].map((v) => ({
-            ...v,
-            subtotal: roundCents(v.subtotal),
-            vat_amount: roundCents(v.vat_amount),
-            total: roundCents(v.total),
-        }));
-        // Calculate payment totals
-        const payments = invoice.invoice_payments || [];
-        const paidTotal = roundCents(payments.reduce((s, p) => s + (p.amount || 0), 0));
-        const remainingBalance = roundCents(invoice.total - paidTotal);
-        return toResult({
-            ...invoice,
-            customers: tagCustomer(invoice
-                .customers),
-            vat_breakdown: vatBreakdown,
-            paid_total: paidTotal,
-            remaining_balance: remainingBalance,
-        });
-    });
-    // ---- WRITE: Update Invoice Status ----
-    server.registerTool("kirjapro_update_invoice_status", {
-        description: 'Update invoice status with state machine validation. Valid transitions: draft→sent/cancelled, sent→paid/partial/overdue/cancelled/draft, partial→paid/overdue/cancelled, overdue→paid/partial/cancelled/sent, cancelled→draft. "paid" is terminal.',
-        inputSchema: {
-            invoiceId: z.string().uuid().describe("Invoice UUID"),
-            status: z
-                .enum(["draft", "sent", "paid", "partial", "overdue", "cancelled"])
-                .describe("New status"),
-            idempotencyKey: IDEMPOTENCY_KEY_SCHEMA,
-            dryRun: DRY_RUN_SCHEMA,
-        },
-        annotations: WRITE_ANNOTATIONS,
-    }, async (params) => {
-        const supabase = getSupabase();
-        const companyId = getCompanyId();
-        const { data: invoice, error: fetchError } = await supabase
-            .from("invoices")
-            .select("id, invoice_number, status")
-            .eq("id", params.invoiceId)
-            .eq("company_id", companyId)
-            .single();
-        if (fetchError || !invoice) {
-            return toErrorContent(`Invoice ${params.invoiceId} not found. Use kirjapro_list_invoices to find invoice IDs.`);
-        }
-        const currentStatus = invoice.status;
-        const newStatus = params.status;
-        if (currentStatus === newStatus) {
-            return toErrorContent(`Invoice ${invoice.invoice_number} is already in status "${currentStatus}".`);
-        }
-        const validNext = VALID_TRANSITIONS[currentStatus] || [];
-        if (!validNext.includes(newStatus)) {
-            return toErrorContent(`Cannot transition invoice ${invoice.invoice_number} from "${currentStatus}" to "${newStatus}". ` +
-                `Valid next statuses: ${validNext.length > 0 ? validNext.join(", ") : "(none — terminal status)"}.`);
-        }
-        if (params.dryRun) {
-            return toDryRunResponse("kirjapro_update_invoice_status", {
-                action: "update_invoice_status",
-                invoice_number: invoice.invoice_number,
-                previous_status: currentStatus,
-                new_status: newStatus,
-            });
-        }
-        return withIdempotency(supabase, companyId, "kirjapro_update_invoice_status", params.idempotencyKey, params, async () => {
-            const updateFields = { status: newStatus };
-            if (newStatus === "paid") {
-                updateFields.paid_date = helsinkiDateString();
-            }
-            // TOCTOU guard: include current status in the WHERE clause so a
-            // concurrent webhook/cron/MCP call that flipped the status between
-            // our SELECT and this UPDATE causes the UPDATE to match zero rows
-            // instead of silently overwriting the concurrent change. `.select()`
-            // makes PostgREST return the updated row(s) so we can detect this.
-            const { data: updated, error: updateError } = await supabase
-                .from("invoices")
-                .update(updateFields)
-                .eq("id", params.invoiceId)
-                .eq("company_id", companyId)
-                .eq("status", currentStatus)
-                .select("id")
-                .maybeSingle();
-            if (updateError) {
-                return toErrorContent(sanitizeDbError("Failed to update invoice status", updateError));
-            }
-            if (!updated) {
-                return toErrorContent(`Invoice ${invoice.invoice_number} status changed concurrently (was "${currentStatus}" when read). ` +
-                    `Re-read with kirjapro_get_invoice and decide whether to retry.`);
-            }
-            return toResult({
-                message: `Invoice ${invoice.invoice_number} status changed from "${currentStatus}" to "${newStatus}"`,
-                invoice_number: invoice.invoice_number,
-                previous_status: currentStatus,
-                new_status: newStatus,
-            });
-        });
-    });
-    // ---- WRITE: Delete Draft Invoice ----
-    server.registerTool("kirjapro_delete_invoice", {
-        description: 'Delete a draft invoice. Only invoices with status "draft" can be deleted — sent or paid invoices must be cancelled first (Finnish audit trail requirement).',
-        inputSchema: {
-            invoiceId: z.string().uuid().describe("Invoice UUID"),
-            idempotencyKey: IDEMPOTENCY_KEY_SCHEMA,
-            dryRun: DRY_RUN_SCHEMA,
-        },
-        annotations: DESTRUCTIVE_ANNOTATIONS,
-    }, async (params) => {
-        const supabase = getSupabase();
-        const companyId = getCompanyId();
-        const { data: invoice, error: fetchError } = await supabase
-            .from("invoices")
-            .select("id, invoice_number, status")
-            .eq("id", params.invoiceId)
-            .eq("company_id", companyId)
-            .single();
-        if (fetchError || !invoice) {
-            return toErrorContent(`Invoice ${params.invoiceId} not found. Use kirjapro_list_invoices to find invoice IDs.`);
-        }
-        if (invoice.status !== "draft") {
-            return toErrorContent(`Cannot delete invoice ${invoice.invoice_number} — status is "${invoice.status}". ` +
-                `Only draft invoices can be deleted. Use kirjapro_update_invoice_status to cancel it first.`);
-        }
-        if (params.dryRun) {
-            return toDryRunResponse("kirjapro_delete_invoice", {
-                action: "delete_invoice",
-                invoice_number: invoice.invoice_number,
-                note: "Will cascade-delete invoice_payments and invoice_lines rows for this invoice.",
-            });
-        }
-        return withIdempotency(supabase, companyId, "kirjapro_delete_invoice", params.idempotencyKey, params, async () => {
-            const { error: rpcError } = await supabase.rpc("delete_draft_invoice_atomic", {
-                p_company_id: companyId,
-                p_invoice_id: params.invoiceId,
-            });
-            if (rpcError) {
-                return toErrorContent(sanitizeDbError("Failed to delete invoice", rpcError));
-            }
-            return toResult({
-                message: `Draft invoice ${invoice.invoice_number} deleted`,
-                invoice_number: invoice.invoice_number,
-            });
-        });
-    });
-}

package/dist/tools/offers.d.ts

@@ -1,2 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerOfferTools(server: McpServer): void;