@kirjapro/mcp-server 0.5.11 → 0.6.0

package/dist/tools/validation.js

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+import { toResult, READ_ONLY_ANNOTATIONS } from '../utils.js';
+import { VALIDATION_OUTPUT_SHAPE } from '../schemas.js';
+const REFERENCE_OUTPUT_SHAPE = {
+    input: z.string(),
+    reference: z.string(),
+    error: z.string().optional(),
+};
+/**
+ * Validate Finnish Y-tunnus (business ID).
+ * Format: NNNNNNN-C, weights [7, 9, 10, 5, 8, 4, 2].
+ */
+function validateFinnishBusinessId(input) {
+    const match = input.match(/^(\d{7})-(\d)$/);
+    if (!match) {
+        return { valid: false, error: 'Invalid format. Expected 7 digits + hyphen + check digit (e.g. 1234567-8).' };
+    }
+    const [, digits, checkStr] = match;
+    const weights = [7, 9, 10, 5, 8, 4, 2];
+    let sum = 0;
+    for (let i = 0; i < 7; i++) {
+        sum += parseInt(digits[i]) * weights[i];
+    }
+    const remainder = sum % 11;
+    if (remainder === 1) {
+        return { valid: false, error: 'Checksum calculation produces remainder 1, which is invalid for Y-tunnus.' };
+    }
+    const expected = remainder === 0 ? 0 : 11 - remainder;
+    if (expected !== parseInt(checkStr)) {
+        return { valid: false, error: `Check digit should be ${expected}, got ${checkStr}.` };
+    }
+    return { valid: true };
+}
+/**
+ * Validate Finnish IBAN.
+ * Format: FI + 16 digits, mod-97 check.
+ */
+function validateFinnishIBAN(input) {
+    const cleaned = input.replace(/\s/g, '').toUpperCase();
+    if (!/^FI\d{16}$/.test(cleaned)) {
+        return { valid: false, error: 'Finnish IBAN must be FI + 16 digits (18 characters total).' };
+    }
+    // Move first 4 chars to end, convert letters to numbers
+    const rearranged = cleaned.slice(4) + cleaned.slice(0, 4);
+    let numStr = '';
+    for (const ch of rearranged) {
+        const code = ch.charCodeAt(0);
+        if (code >= 65 && code <= 90) {
+            numStr += (code - 55).toString();
+        }
+        else {
+            numStr += ch;
+        }
+    }
+    // Mod 97 using chunk processing (handles large numbers)
+    let remainder = 0;
+    for (let i = 0; i < numStr.length; i += 7) {
+        const chunk = remainder.toString() + numStr.slice(i, i + 7);
+        remainder = parseInt(chunk) % 97;
+    }
+    if (remainder !== 1) {
+        return { valid: false, error: 'IBAN check digits are invalid (mod-97 check failed).' };
+    }
+    return { valid: true };
+}
+/**
+ * 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) {
+        return { reference: '', 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 { reference: digits + checkDigit };
+}
+export function registerValidationTools(server) {
+    server.registerTool('kirjapro_validate_business_id', {
+        description: 'Validate a Finnish business ID (Y-tunnus). Checks format and checksum. No database access — pure computation.',
+        inputSchema: {
+            businessId: z.string().describe('Y-tunnus to validate (e.g. "1234567-8")'),
+        },
+        outputSchema: VALIDATION_OUTPUT_SHAPE,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        const result = validateFinnishBusinessId(params.businessId);
+        return toResult({
+            input: params.businessId,
+            ...result,
+        });
+    });
+    server.registerTool('kirjapro_validate_iban', {
+        description: 'Validate a Finnish IBAN. Checks format (FI + 16 digits) and mod-97 checksum. No database access — pure computation.',
+        inputSchema: {
+            iban: z.string().describe('Finnish IBAN to validate (e.g. "FI2112345678901234")'),
+        },
+        outputSchema: VALIDATION_OUTPUT_SHAPE,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        const result = validateFinnishIBAN(params.iban);
+        return toResult({
+            input: params.iban,
+            ...result,
+        });
+    });
+    server.registerTool('kirjapro_generate_reference', {
+        description: 'Generate a Finnish bank reference number (viitenumero) from a base number. Appends the 7-3-1 weighted check digit. No database access — pure computation.',
+        inputSchema: {
+            baseNumber: z.string().describe('Base number (1-19 digits, e.g. invoice number "00042")'),
+        },
+        outputSchema: REFERENCE_OUTPUT_SHAPE,
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async (params) => {
+        const result = generateReferenceNumber(params.baseNumber);
+        return toResult({
+            input: params.baseNumber,
+            ...result,
+        });
+    });
+}
+// Export for testing
+export { validateFinnishBusinessId, validateFinnishIBAN, generateReferenceNumber };

package/dist/types.d.ts

@@ -0,0 +1,388 @@
+export type AccountType = 'asset' | 'liability' | 'equity' | 'revenue' | 'expense';
+/** VAT rates as strings for Zod enum validation (prevents agent hallucination). */
+export type VatRate = '25.5' | '13.5' | '10' | '0';
+export type InvoiceStatus = 'draft' | 'sent' | 'paid' | 'partial' | 'overdue' | 'cancelled';
+/** VAT rates as strings, matching the VatRate type. */
+export declare const VAT_RATES: readonly ["25.5", "13.5", "10", "0"];
+export interface Account {
+    id: string;
+    account_number: string;
+    name: string;
+    account_type: AccountType;
+    is_active: boolean;
+}
+export interface FiscalYear {
+    id: string;
+    company_id: string;
+    start_date: string;
+    end_date: string;
+    is_closed: boolean;
+}
+export interface Transaction {
+    id: string;
+    fiscal_year_id: string;
+    transaction_date: string;
+    description: string;
+    document_number: string | null;
+    created_at: string;
+}
+export interface JournalEntry {
+    id: string;
+    transaction_id: string;
+    account_id: string;
+    debit_amount: number;
+    credit_amount: number;
+    description: string | null;
+}
+export interface Customer {
+    id: string;
+    customer_number: string;
+    name: string;
+    business_id: string | null;
+    email: string | null;
+    phone: string | null;
+    address: string | null;
+    postal_code: string | null;
+    city: string | null;
+    country: string;
+    payment_term_days: number;
+    is_active: boolean;
+}
+export interface Invoice {
+    id: string;
+    customer_id: string;
+    invoice_number: string;
+    reference_number: string;
+    invoice_date: string;
+    due_date: string;
+    status: InvoiceStatus;
+    subtotal: number;
+    vat_total: number;
+    total: number;
+    notes: string | null;
+}
+export interface InvoiceLine {
+    id: string;
+    invoice_id: string;
+    line_number: number;
+    description: string;
+    quantity: number;
+    unit: string;
+    unit_price: number;
+    vat_rate: number;
+    subtotal: number;
+    vat_amount: number;
+    total: number;
+}
+export interface InvoicePayment {
+    id: string;
+    invoice_id: string;
+    payment_date: string;
+    amount: number;
+    payment_method: string;
+    reference: string | null;
+}
+export interface BankTransaction {
+    id: string;
+    bank_account_id: string;
+    booking_date: string;
+    amount: number;
+    credit_debit: 'credit' | 'debit';
+    counterparty_name: string | null;
+    reference: string | null;
+    message: string | null;
+    reconciled_at: string | null;
+}
+/** Standard paginated response wrapper */
+export interface PaginatedResult<T> {
+    results: T[];
+    total_count: number;
+    has_more: boolean;
+    next_offset: number;
+}
+/** select: id, invoice_number, total, status, invoice_payments(amount) */
+export interface InvoiceWithPayments {
+    id: string;
+    invoice_number: string;
+    total: number;
+    status: InvoiceStatus;
+    invoice_payments: Array<{
+        amount: number;
+    }>;
+}
+/** select: id, invoice_number, total, due_date, invoice_date, customers(name) */
+export interface InvoiceWithCustomer {
+    id: string;
+    invoice_number: string;
+    total: number;
+    due_date: string;
+    invoice_date: string;
+    customers: {
+        name: string;
+    } | null;
+}
+/** select: debit_amount, credit_amount, account:accounts!inner(account_type), transaction:transactions!inner(fiscal_year_id) */
+export interface JournalEntryWithAccountType {
+    debit_amount: number;
+    credit_amount: number;
+    account: {
+        account_type: AccountType;
+    };
+    transaction: {
+        fiscal_year_id: string;
+    };
+}
+/** select: debit_amount, credit_amount, account:accounts!inner(id, account_number, name, account_type), transaction:transactions!inner(fiscal_year_id, transaction_date) */
+export interface JournalEntryWithAccountDetail {
+    debit_amount: number;
+    credit_amount: number;
+    account: {
+        id: string;
+        account_number: string;
+        name: string;
+        account_type: AccountType;
+    };
+    transaction: {
+        fiscal_year_id: string;
+        transaction_date: string;
+    };
+}
+/** select: account_name, iban, current_balance */
+export interface BankAccountBalance {
+    account_name: string | null;
+    iban: string;
+    current_balance: number | null;
+}
+/** select: id, transaction_date, description, document_number, created_at, journal_entries(...) */
+export interface TransactionWithEntries {
+    id: string;
+    transaction_date: string;
+    description: string;
+    document_number: string | null;
+    created_at: string;
+    journal_entries: Array<{
+        id: string;
+        account_id: string;
+        debit_amount: number;
+        credit_amount: number;
+        accounts: {
+            account_number: string;
+            name: string;
+        };
+    }>;
+}
+/** select: id, account_number (minimal lookup) */
+export interface AccountLookup {
+    id: string;
+    account_number: string;
+}
+/** Accumulator row for income statement and balance sheet reports */
+export interface AccountBalanceRow {
+    account_number: string;
+    name: string;
+    account_type: string;
+    debit: number;
+    credit: number;
+    balance: number;
+}
+/** Balance sheet account row */
+export interface BalanceSheetRow {
+    account_number: string;
+    name: string;
+    account_type: string;
+    balance: number;
+}
+/** AR aging bucket with categorized invoices */
+export interface AgingBucketInvoice {
+    invoice_number: string;
+    customer: string | null;
+    total: number;
+    due_date: string;
+    days_overdue: number;
+}
+/** AR aging bucket */
+export interface AgingBucket {
+    label: string;
+    min: number;
+    max: number;
+    count: number;
+    total: number;
+    invoices: AgingBucketInvoice[];
+}
+/** Result item from batch transaction creation */
+export interface CreatedTransactionResult {
+    id: string;
+    description: string;
+    date: string;
+}
+/** Bank account row for list_bank_accounts */
+export interface BankAccountRow {
+    id: string;
+    account_name: string;
+    iban: string;
+    bic: string | null;
+    bank_name: string | null;
+    current_balance: number | null;
+    available_balance: number | null;
+    is_primary: boolean;
+    last_sync_at: string | null;
+    connection_status: string | null;
+}
+/** Bank transaction row for list_bank_transactions */
+export interface BankTransactionRow {
+    id: string;
+    bank_account_id: string;
+    booking_date: string;
+    amount: number;
+    credit_debit: string;
+    counterparty_name: string | null;
+    counterparty_iban: string | null;
+    reference: string | null;
+    message: string | null;
+    reconciled_at: string | null;
+    match_method: string | null;
+    matched_invoice_id: string | null;
+}
+/** VAT breakdown row for invoice detail */
+export interface VatBreakdownRow {
+    vat_rate: number;
+    subtotal: number;
+    vat_amount: number;
+    total: number;
+}
+/** General ledger entry with running balance */
+export interface GeneralLedgerEntry {
+    date: string;
+    description: string;
+    document_number: string | null;
+    transaction_id: string;
+    debit: number;
+    credit: number;
+    running_balance: number;
+}
+/** A single journal entry line produced by template expansion */
+export interface TemplateEntry {
+    accountNumber: string;
+    debitAmount: number;
+    creditAmount: number;
+}
+/** Static definition of a transaction template */
+export interface TransactionTemplate {
+    id: string;
+    description: string;
+    vatRate: number | null;
+    /** Function that expands the template for a given gross amount */
+    expand: (amount: number, opts?: {
+        withholdingRate?: number;
+        tyelRate?: number;
+        accountOverrides?: Record<string, string>;
+    }) => TemplateEntry[];
+}
+export type OfferType = 'tarjous' | 'sopimus';
+export type OfferStatus = 'draft' | 'sent' | 'viewed' | 'accepted' | 'rejected' | 'expired';
+export interface Offer {
+    id: string;
+    company_id: string;
+    customer_id: string | null;
+    type: OfferType;
+    title: string;
+    offer_number: string;
+    content: string | null;
+    status: OfferStatus;
+    valid_from: string | null;
+    valid_until: string | null;
+    subtotal: number;
+    vat_total: number;
+    total: number;
+    notes: string | null;
+    invoice_id: string | null;
+    sent_at: string | null;
+    created_at: string;
+}
+export interface OfferLine {
+    id: string;
+    offer_id: string;
+    line_number: number;
+    description: string;
+    quantity: number;
+    unit: string;
+    unit_price: number;
+    vat_rate: number;
+    subtotal: number;
+    vat_amount: number;
+    total: number;
+}
+/**
+ * Offer status transition map (sender-side, via record_offer_status_change RPC).
+ *
+ * Removals from the naive 6-status graph:
+ * - 'sent → viewed' (Round 2 T1-2): only record_offer_view (public /o/:token
+ *   GET) may flip a sent offer to viewed.
+ * - 'draft → sent' (Round 4 R1-M4): only send-offer-email edge fn may do
+ *   this — it generates the access_token atomically. Direct status flip
+ *   would orphan the offer in 'sent' with NULL token, 404-ing the public
+ *   link.
+ *
+ * Must stay in lockstep with src/lib/offer-types.ts VALID_OFFER_TRANSITIONS.
+ */
+export declare const VALID_OFFER_TRANSITIONS: Record<OfferStatus, OfferStatus[]>;
+export type RecurringFrequency = 'weekly' | 'monthly' | 'quarterly' | 'yearly';
+export interface RecurringInvoice {
+    id: string;
+    company_id: string;
+    customer_id: string;
+    name: string;
+    template_data: Record<string, unknown>;
+    frequency: RecurringFrequency;
+    next_date: string;
+    end_date: string | null;
+    is_active: boolean;
+    auto_send: boolean;
+    last_generated_at: string | null;
+    times_generated: number;
+    created_at: string;
+    updated_at: string;
+}
+export type ReceivedInvoiceStatus = 'new' | 'reviewed' | 'approved' | 'rejected' | 'booked';
+export interface ReceivedInvoice {
+    id: string;
+    company_id: string;
+    sender_business_id: string | null;
+    sender_name: string | null;
+    invoice_number: string | null;
+    invoice_date: string | null;
+    due_date: string | null;
+    total_amount: number | null;
+    vat_amount: number | null;
+    currency: string;
+    payment_reference: string | null;
+    iban: string | null;
+    status: ReceivedInvoiceStatus;
+    transaction_id: string | null;
+    created_at: string;
+}
+export interface AlvSummaryResult {
+    period: {
+        from: string;
+        to: string;
+    };
+    output_vat: Record<string, number>;
+    input_vat: Record<string, number>;
+    net_vat_payable: number;
+    omavero_fields: Record<string, number>;
+}
+export interface PrhBusinessResult {
+    businessId: string;
+    name: string;
+    registrationDate: string | null;
+    companyForm: string | null;
+    address: string | null;
+    postalCode: string | null;
+    city: string | null;
+    country: string | null;
+    website: string | null;
+    phone: string | null;
+    liquidations: unknown[];
+}
+/** Invoice status transition map */
+export declare const VALID_TRANSITIONS: Record<InvoiceStatus, InvoiceStatus[]>;

package/dist/types.js

@@ -0,0 +1,34 @@
+// Standalone types mirroring the Kirjapro database schema.
+// These are independent from the frontend types to keep the MCP server self-contained.
+/** VAT rates as strings, matching the VatRate type. */
+export const VAT_RATES = ['25.5', '13.5', '10', '0'];
+/**
+ * Offer status transition map (sender-side, via record_offer_status_change RPC).
+ *
+ * Removals from the naive 6-status graph:
+ * - 'sent → viewed' (Round 2 T1-2): only record_offer_view (public /o/:token
+ *   GET) may flip a sent offer to viewed.
+ * - 'draft → sent' (Round 4 R1-M4): only send-offer-email edge fn may do
+ *   this — it generates the access_token atomically. Direct status flip
+ *   would orphan the offer in 'sent' with NULL token, 404-ing the public
+ *   link.
+ *
+ * Must stay in lockstep with src/lib/offer-types.ts VALID_OFFER_TRANSITIONS.
+ */
+export const VALID_OFFER_TRANSITIONS = {
+    draft: ['expired'],
+    sent: ['accepted', 'rejected', 'expired', 'draft'],
+    viewed: ['accepted', 'rejected', 'expired', 'draft'],
+    accepted: [],
+    rejected: ['draft'],
+    expired: ['draft'],
+};
+/** Invoice status transition map */
+export const VALID_TRANSITIONS = {
+    draft: ['sent', 'cancelled'],
+    sent: ['paid', 'partial', 'overdue', 'cancelled', 'draft'],
+    partial: ['paid', 'overdue', 'cancelled'],
+    overdue: ['paid', 'partial', 'cancelled', 'sent'],
+    paid: [],
+    cancelled: ['draft'],
+};