@kirjapro/mcp-server 0.5.11 → 0.6.1

package/dist/tools/recurring-invoices.js

@@ -0,0 +1,348 @@
+import { z } from 'zod';
+import { getSupabase, getCompanyId } from '../auth.js';
+import { clampPagination, paginate, toResult, toErrorContent, toDryRunResponse, sanitizeDbError, invokeEdgeFunction, tagCustomer, withIdempotency, IDEMPOTENCY_KEY_SCHEMA, ISO_DATE_SCHEMA, DRY_RUN_SCHEMA, READ_ONLY_ANNOTATIONS, WRITE_ANNOTATIONS, DESTRUCTIVE_ANNOTATIONS } from '../utils.js';
+import { PAGINATED_OUTPUT_SHAPE } from '../schemas.js';
+const RECURRING_INVOICE_DETAIL_OUTPUT_SHAPE = {
+    id: z.string(),
+    name: z.string(),
+    frequency: z.string(),
+    next_date: z.string().nullable(),
+    is_active: z.boolean(),
+    template_data: z.record(z.string(), z.unknown()).nullable(),
+    customer: z.record(z.string(), z.unknown()).nullable(),
+    recent_logs: z.array(z.record(z.string(), z.unknown())),
+};
+export function registerRecurringInvoiceTools(server) {
+    // ---- LIST ----
+    server.registerTool('kirjapro_list_recurring_invoices', {
+        description: 'List recurring invoice templates with pagination. Shows frequency, next generation date, active status, and customer info.',
+        inputSchema: {
+            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'),
+            activeOnly: z.boolean().default(true).describe('Only show active templates (default true)'),
+        },
+        outputSchema: PAGINATED_OUTPUT_SHAPE,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        const supabase = getSupabase();
+        const companyId = getCompanyId();
+        const { limit, offset } = clampPagination(params.limit, params.offset);
+        let query = supabase
+            .from('recurring_invoices')
+            .select('id, name, frequency, next_date, end_date, is_active, auto_send, last_generated_at, times_generated, created_at, customer:customers(id, name)', { count: 'exact' })
+            .eq('company_id', companyId)
+            .order('next_date');
+        if (params.activeOnly) {
+            query = query.eq('is_active', true);
+        }
+        query = query.range(offset, offset + limit - 1);
+        const { data, count, error } = await query;
+        if (error) {
+            return toErrorContent(sanitizeDbError("Failed to list recurring invoices", error));
+        }
+        const tagged = (data || []).map((row) => ({
+            ...row,
+            customer: tagCustomer(row.customer),
+        }));
+        return toResult(paginate(tagged, count || 0, offset, limit));
+    });
+    // ---- GET ----
+    server.registerTool('kirjapro_get_recurring_invoice', {
+        description: 'Get a single recurring invoice template with full details including template data (lines, notes, payment terms) and generation history.',
+        inputSchema: {
+            recurringInvoiceId: z.string().uuid().describe('Recurring invoice UUID'),
+        },
+        outputSchema: RECURRING_INVOICE_DETAIL_OUTPUT_SHAPE,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        const supabase = getSupabase();
+        const companyId = getCompanyId();
+        // Explicit column allowlist — no select('*'). Adding a new column to
+        // recurring_invoices must be a conscious decision here, since template_data
+        // is a free-form JSONB blob the agent could act on.
+        const { data, error } = await supabase
+            .from('recurring_invoices')
+            .select('id, company_id, customer_id, name, frequency, next_date, end_date, is_active, auto_send, template_data, last_generated_at, times_generated, created_at, updated_at, customer:customers(id, name, business_id, email)')
+            .eq('id', params.recurringInvoiceId)
+            .eq('company_id', companyId)
+            .single();
+        if (error || !data) {
+            return toErrorContent(`Recurring invoice ${params.recurringInvoiceId} not found. Use kirjapro_list_recurring_invoices to find IDs.`);
+        }
+        // Fetch recent generation logs
+        const { data: logs } = await supabase
+            .from('recurring_invoice_logs')
+            .select('id, status, scheduled_date, invoice_number, error_message, created_at')
+            .eq('recurring_invoice_id', params.recurringInvoiceId)
+            .eq('company_id', companyId)
+            .order('created_at', { ascending: false })
+            .limit(10);
+        return toResult({
+            ...data,
+            customer: tagCustomer(data
+                .customer),
+            recent_logs: logs || [],
+        });
+    });
+    // ---- CREATE ----
+    server.registerTool('kirjapro_create_recurring_invoice', {
+        description: 'Create a new recurring invoice template. Specify customer, frequency, start date, and invoice line items. Invoices will be generated automatically on the schedule.',
+        inputSchema: {
+            customerId: z.string().uuid().describe('Customer UUID'),
+            name: z.string().min(1).max(200).describe('Template name (e.g. "Monthly hosting fee")'),
+            frequency: z.enum(['weekly', 'monthly', 'quarterly', 'yearly']).describe('Generation frequency'),
+            nextDate: ISO_DATE_SCHEMA.describe('First generation date (YYYY-MM-DD)'),
+            endDate: ISO_DATE_SCHEMA.optional().describe('Stop generating after this date'),
+            autoSend: z.boolean().default(false).describe('Auto-send generated invoices (default false)'),
+            lines: z.array(z.object({
+                description: z.string().describe('Line item description'),
+                quantity: z.number().positive().describe('Quantity'),
+                unit: z.string().default('kpl').describe('Unit (default "kpl")'),
+                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']).describe('VAT rate'),
+            })).min(1).describe('Invoice line items'),
+            notes: z.string().optional().describe('Invoice notes'),
+            paymentTermDays: z.number().min(0).max(365).default(14).describe('Payment term in days'),
+            idempotencyKey: IDEMPOTENCY_KEY_SCHEMA,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async (params) => {
+        const supabase = getSupabase();
+        const companyId = getCompanyId();
+        return withIdempotency(supabase, companyId, 'kirjapro_create_recurring_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)
+                .maybeSingle();
+            if (custError || !customer) {
+                return toErrorContent(`Customer ${params.customerId} not found. Use kirjapro_list_customers to find customer IDs.`);
+            }
+            const templateData = {
+                lines: params.lines.map((l, i) => ({
+                    line_number: i + 1,
+                    description: l.description,
+                    quantity: l.quantity,
+                    unit: l.unit,
+                    unit_price: l.unitPrice,
+                    vat_rate: parseFloat(l.vatRate),
+                })),
+                notes: params.notes || null,
+                payment_terms_days: params.paymentTermDays,
+            };
+            const { data, error } = await supabase
+                .from('recurring_invoices')
+                .insert({
+                company_id: companyId,
+                customer_id: params.customerId,
+                name: params.name,
+                frequency: params.frequency,
+                next_date: params.nextDate,
+                end_date: params.endDate || null,
+                is_active: true,
+                auto_send: params.autoSend,
+                template_data: templateData,
+            })
+                .select('id, name, frequency, next_date, end_date, is_active, auto_send, created_at, updated_at')
+                .single();
+            if (error) {
+                return toErrorContent(sanitizeDbError("Failed to create recurring invoice", error));
+            }
+            return toResult({
+                message: `Recurring invoice "${params.name}" created for ${customer.name} (${params.frequency}, next: ${params.nextDate})`,
+                recurring_invoice: data,
+            });
+        });
+    });
+    // ---- UPDATE ----
+    server.registerTool('kirjapro_update_recurring_invoice', {
+        description: 'Update a recurring invoice template. Only provided fields are changed. Use this to pause/resume (isActive), change schedule, or update line items.',
+        inputSchema: {
+            recurringInvoiceId: z.string().uuid().describe('Recurring invoice UUID'),
+            name: z.string().min(1).max(200).optional().describe('Template name'),
+            frequency: z.enum(['weekly', 'monthly', 'quarterly', 'yearly']).optional().describe('Generation frequency'),
+            nextDate: ISO_DATE_SCHEMA.optional().describe('Next generation date'),
+            endDate: ISO_DATE_SCHEMA.optional().nullable().describe('End date (null to remove)'),
+            isActive: z.boolean().optional().describe('Active status (false to pause)'),
+            autoSend: z.boolean().optional().describe('Auto-send generated invoices'),
+            lines: z.array(z.object({
+                description: z.string().describe('Line item description'),
+                quantity: z.number().positive().describe('Quantity'),
+                unit: z.string().default('kpl').describe('Unit'),
+                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']).describe('VAT rate'),
+            })).min(1).optional().describe('Replace all invoice lines'),
+            notes: z.string().optional().nullable().describe('Invoice notes (null to remove)'),
+            paymentTermDays: z.number().min(0).max(365).optional().describe('Payment term in days'),
+            idempotencyKey: IDEMPOTENCY_KEY_SCHEMA,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async (params) => {
+        const supabase = getSupabase();
+        const companyId = getCompanyId();
+        // Verify exists
+        const { data: existing, error: fetchError } = await supabase
+            .from('recurring_invoices')
+            .select('id, name, template_data, next_date, end_date')
+            .eq('id', params.recurringInvoiceId)
+            .eq('company_id', companyId)
+            .single();
+        if (fetchError || !existing) {
+            return toErrorContent(`Recurring invoice ${params.recurringInvoiceId} not found. Use kirjapro_list_recurring_invoices to find IDs.`);
+        }
+        // Cross-field date validation: the effective nextDate must not be after
+        // the effective endDate. Skipping this lets the caller create a schedule
+        // that will never fire (or immediately auto-deactivate on the next cron
+        // sweep), silently wasting an idempotency slot.
+        const effectiveNext = params.nextDate !== undefined ? params.nextDate : existing.next_date;
+        const effectiveEnd = params.endDate !== undefined ? params.endDate : existing.end_date;
+        if (effectiveEnd && effectiveNext && effectiveEnd < effectiveNext) {
+            return toErrorContent(`endDate (${effectiveEnd}) must not be earlier than nextDate (${effectiveNext}). ` +
+                `Either clear endDate (set to null) or advance nextDate first.`);
+        }
+        const updates = {};
+        if (params.name !== undefined)
+            updates.name = params.name;
+        if (params.frequency !== undefined)
+            updates.frequency = params.frequency;
+        if (params.nextDate !== undefined)
+            updates.next_date = params.nextDate;
+        if (params.endDate !== undefined)
+            updates.end_date = params.endDate;
+        if (params.isActive !== undefined)
+            updates.is_active = params.isActive;
+        if (params.autoSend !== undefined)
+            updates.auto_send = params.autoSend;
+        // Rebuild template_data if lines or notes/payment terms changed
+        if (params.lines !== undefined || params.notes !== undefined || params.paymentTermDays !== undefined) {
+            const currentTemplate = (existing.template_data || {});
+            const newTemplate = { ...currentTemplate };
+            if (params.lines !== undefined) {
+                newTemplate.lines = params.lines.map((l, i) => ({
+                    line_number: i + 1,
+                    description: l.description,
+                    quantity: l.quantity,
+                    unit: l.unit,
+                    unit_price: l.unitPrice,
+                    vat_rate: parseFloat(l.vatRate),
+                }));
+            }
+            if (params.notes !== undefined)
+                newTemplate.notes = params.notes;
+            if (params.paymentTermDays !== undefined)
+                newTemplate.payment_terms_days = params.paymentTermDays;
+            updates.template_data = newTemplate;
+        }
+        if (Object.keys(updates).length === 0) {
+            return toErrorContent('No fields to update. Provide at least one field to change.');
+        }
+        return withIdempotency(supabase, companyId, 'kirjapro_update_recurring_invoice', params.idempotencyKey, params, async () => {
+            const { data, error } = await supabase
+                .from('recurring_invoices')
+                .update(updates)
+                .eq('id', params.recurringInvoiceId)
+                .eq('company_id', companyId)
+                .select('id, name, frequency, next_date, end_date, is_active, auto_send, created_at, updated_at')
+                .single();
+            if (error) {
+                return toErrorContent(sanitizeDbError("Failed to update recurring invoice", error));
+            }
+            return toResult({
+                message: `Recurring invoice "${data.name}" updated`,
+                recurring_invoice: data,
+                fields_changed: Object.keys(updates),
+            });
+        });
+    });
+    // ---- DELETE ----
+    server.registerTool('kirjapro_delete_recurring_invoice', {
+        description: 'Delete a recurring invoice template. Previously generated invoices are NOT affected.',
+        inputSchema: {
+            recurringInvoiceId: z.string().uuid().describe('Recurring invoice UUID'),
+            idempotencyKey: IDEMPOTENCY_KEY_SCHEMA,
+            dryRun: DRY_RUN_SCHEMA,
+        },
+        annotations: DESTRUCTIVE_ANNOTATIONS,
+    }, async (params) => {
+        const supabase = getSupabase();
+        const companyId = getCompanyId();
+        // Verify exists
+        const { data: existing, error: fetchError } = await supabase
+            .from('recurring_invoices')
+            .select('id, name')
+            .eq('id', params.recurringInvoiceId)
+            .eq('company_id', companyId)
+            .single();
+        if (fetchError || !existing) {
+            return toErrorContent(`Recurring invoice ${params.recurringInvoiceId} not found. Use kirjapro_list_recurring_invoices to find IDs.`);
+        }
+        if (params.dryRun) {
+            return toDryRunResponse('kirjapro_delete_recurring_invoice', {
+                action: 'delete_recurring_invoice',
+                name: existing.name,
+                note: 'Previously generated invoices will be unaffected.',
+            });
+        }
+        return withIdempotency(supabase, companyId, 'kirjapro_delete_recurring_invoice', params.idempotencyKey, params, async () => {
+            const { error } = await supabase
+                .from('recurring_invoices')
+                .delete()
+                .eq('id', params.recurringInvoiceId)
+                .eq('company_id', companyId);
+            if (error) {
+                return toErrorContent(sanitizeDbError("Failed to delete recurring invoice", error));
+            }
+            return toResult({
+                message: `Recurring invoice "${existing.name}" deleted. Previously generated invoices are unaffected.`,
+            });
+        });
+    });
+    // ---- TRIGGER ----
+    server.registerTool('kirjapro_trigger_recurring_invoice', {
+        description: 'Manually trigger generation of a recurring invoice now, regardless of its next scheduled date. Returns the generated invoice.',
+        inputSchema: {
+            recurringInvoiceId: z.string().uuid().describe('Recurring invoice UUID'),
+            idempotencyKey: IDEMPOTENCY_KEY_SCHEMA,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async (params) => {
+        const supabase = getSupabase();
+        const companyId = getCompanyId();
+        return withIdempotency(supabase, companyId, 'kirjapro_trigger_recurring_invoice', params.idempotencyKey, params, async () => {
+            // Verify exists and is active
+            const { data: existing, error: fetchError } = await supabase
+                .from('recurring_invoices')
+                .select('id, name, is_active')
+                .eq('id', params.recurringInvoiceId)
+                .eq('company_id', companyId)
+                .single();
+            if (fetchError || !existing) {
+                return toErrorContent(`Recurring invoice ${params.recurringInvoiceId} not found. Use kirjapro_list_recurring_invoices to find IDs.`);
+            }
+            if (!existing.is_active) {
+                return toErrorContent(`Recurring invoice "${existing.name}" is paused. Activate it first with kirjapro_update_recurring_invoice.`);
+            }
+            const result = await invokeEdgeFunction(supabase, 'generate-recurring-invoices', { recurring_invoice_id: params.recurringInvoiceId, company_id: companyId });
+            if (result.error !== null) {
+                return toErrorContent(result.error);
+            }
+            return toResult({
+                message: `Invoice generated from "${existing.name}"`,
+                invoice_id: result.data.invoice_id,
+                invoice_number: result.data.invoice_number,
+            });
+        });
+    });
+}

package/dist/tools/reports.d.ts

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