Mattsson
8a6ce7093e
* feat: implement skattekonto drift detection and alerting - Add skattekonto drift computation logic to compare Skatteverket's saldo with GL 1630 sum. - Implement alerting mechanism for significant drift changes, with throttling to prevent alert spamming. - Introduce database functions to sum GL 1630 entries and list unbooked skattekonto rows. feat: create own account transfer detection - Develop logic to detect transfers between a company's own cash accounts based on counterparty IBAN. - Implement tests to validate detection logic under various scenarios, including matching and non-matching IBANs. feat: establish cash accounts as a first-class entity - Create cash_accounts table to manage routable cash accounts, replacing ad-hoc JSONB structures. - Implement functions for listing, upserting, and managing cash accounts, including primary account designation. feat: enhance GL line reconciliation functionality - Modify get_unlinked_1930_lines RPC to accept any account number for reconciliation, improving flexibility for different currencies. - Update related functions to ensure compatibility with the new cash_accounts structure. feat: capture counterparty IBAN in transactions - Add counterparty_iban column to transactions table to facilitate intra-account transfer detection. - Create index for efficient lookups based on counterparty IBAN. * feat: Enhance cash account handling and reconciliation processes - Updated reconciliation routes to enforce cash account validation for all account numbers, including '1930'. - Improved error handling for unknown cash accounts in reconciliation status and unmatched entries routes. - Changed CashAccountSelector to use sessionStorage instead of localStorage for better data privacy. - Fixed mapping for employer payroll taxes to route to the correct account (2730 instead of 2731). - Added safety checks for company IDs in the guessCounterAccount function to prevent injection vulnerabilities. - Introduced atomic RPC for setting primary cash accounts to avoid intermediate states during updates. - Seeded default cash accounts for new companies to ensure reconciliation routes are accessible from day one. - Updated email notifications for drift detection to avoid exposing sensitive financial data. - Enhanced bank reconciliation logic to handle multi-currency transactions correctly. - Renamed and updated tests to reflect changes in the underlying RPCs and ensure accurate coverage. - Migrated existing cash account rules to correct mappings in compliance with Swedish accounting standards.
205 lines
12 KiB
TypeScript
205 lines
12 KiB
TypeScript
import type {
|
|
JournalEntry,
|
|
Invoice,
|
|
Transaction,
|
|
Customer,
|
|
Supplier,
|
|
FiscalPeriod,
|
|
DocumentAttachment,
|
|
Receipt,
|
|
CreditNote,
|
|
ReconciliationMethod,
|
|
InvoiceInboxItem,
|
|
SupplierInvoice,
|
|
} from '@/types'
|
|
|
|
// ============================================================
|
|
// Core Event Types — discriminated union of all system events
|
|
// ============================================================
|
|
|
|
export type CoreEvent =
|
|
// Bookkeeping
|
|
| { type: 'journal_entry.drafted'; payload: { entry: JournalEntry; userId: string; companyId: string } }
|
|
| { type: 'journal_entry.committed'; payload: { entry: JournalEntry; userId: string; companyId: string } }
|
|
| { type: 'journal_entry.corrected'; payload: { original: JournalEntry; storno: JournalEntry; corrected: JournalEntry; userId: string; companyId: string } }
|
|
| { type: 'journal_entry.reversed'; payload: { originalEntry: JournalEntry; reversalEntry: JournalEntry; userId: string; companyId: string } }
|
|
| { type: 'journal_entry.deleted'; payload: { entryId: string; voucherSeries: string; voucherNumber: number; userId: string; companyId: string } }
|
|
// Documents
|
|
| { type: 'document.uploaded'; payload: { document: DocumentAttachment; userId: string; companyId: string } }
|
|
| { type: 'document.accessed'; payload: { document: { id: string; file_name: string }; userId: string; companyId: string } }
|
|
// Invoicing
|
|
| { type: 'invoice.created'; payload: { invoice: Invoice; userId: string; companyId: string } }
|
|
| { type: 'invoice.sent'; payload: { invoice: Invoice; userId: string; companyId: string } }
|
|
| { type: 'invoice.paid'; payload: { invoice: Invoice; paymentAmount: number; paymentDate: string; userId: string; companyId: string } }
|
|
| { type: 'credit_note.created'; payload: { creditNote: CreditNote; userId: string; companyId: string } }
|
|
// Recurring invoices — emitted by the daily cron after a schedule spawns
|
|
// an invoice. `autoSent` tells observers whether the email also went out
|
|
// (false means it was created as draft for manual review).
|
|
| { type: 'recurring_invoice.executed'; payload: {
|
|
scheduleId: string
|
|
invoice: Invoice
|
|
autoSent: boolean
|
|
warning: string | null
|
|
userId: string
|
|
companyId: string
|
|
} }
|
|
// Banking
|
|
| { type: 'transaction.synced'; payload: { transactions: Transaction[]; userId: string; companyId: string } }
|
|
| { type: 'transaction.categorized'; payload: { transaction: Transaction; account: string; taxCode: string; userId: string; companyId: string } }
|
|
| { type: 'transaction.reconciled'; payload: { transaction: Transaction; journalEntryId: string; method: ReconciliationMethod; userId: string; companyId: string } }
|
|
// Bank connection lifecycle — consent + account selection are the
|
|
// GDPR/PSD2 audit points; emitted to event_log for compliance trail.
|
|
| { type: 'bank_connection.consent_granted'; payload: { connectionId: string; bankName: string | null; accountCount: number; consentExpiresAt: string | null; userId: string; companyId: string } }
|
|
| { type: 'bank_connection.account_selection_changed'; payload: { connectionId: string; bankName: string | null; previousStatus: string; newStatus: string; enabledCount: number; totalCount: number; userId: string; companyId: string } }
|
|
| { type: 'bank_connection.revoked'; payload: { connectionId: string; bankName: string | null; userId: string; companyId: string } }
|
|
// Emitted when the PSD2 callback fails to mirror a returned account into
|
|
// cash_accounts. ASVS V16 / ISO 27001 A.8.15 — security-relevant failures
|
|
// must land in a structured audit log (event_log, 30-day TTL) rather than
|
|
// being lost to console.error.
|
|
| { type: 'bank_connection.cash_account_mirror_failed'; payload: {
|
|
connectionId: string
|
|
bankName: string | null
|
|
accountUid: string
|
|
ledgerAccount: string
|
|
currency: string
|
|
reason: string
|
|
userId: string
|
|
companyId: string
|
|
} }
|
|
// Periods
|
|
| { type: 'period.locked'; payload: { period: FiscalPeriod; userId: string; companyId: string } }
|
|
| { type: 'period.unlocked'; payload: { period: FiscalPeriod; userId: string; companyId: string } }
|
|
| { type: 'period.year_closed'; payload: { period: FiscalPeriod; userId: string; companyId: string } }
|
|
// Customers
|
|
| { type: 'customer.created'; payload: { customer: Customer; userId: string; companyId: string } }
|
|
// Suppliers
|
|
| { type: 'supplier.created'; payload: { supplier: Supplier; userId: string; companyId: string } }
|
|
// Receipts
|
|
| { type: 'receipt.extracted'; payload: {
|
|
receipt: Receipt;
|
|
documentId: string | null;
|
|
confidence: number;
|
|
userId: string;
|
|
companyId: string;
|
|
}}
|
|
| { type: 'receipt.matched'; payload: {
|
|
receipt: Receipt;
|
|
transaction: Transaction;
|
|
confidence: number;
|
|
autoMatched: boolean;
|
|
userId: string;
|
|
companyId: string;
|
|
}}
|
|
| { type: 'receipt.confirmed'; payload: {
|
|
receipt: Receipt;
|
|
businessTotal: number;
|
|
privateTotal: number;
|
|
userId: string;
|
|
companyId: string;
|
|
}}
|
|
// Supplier Invoice Lifecycle
|
|
| { type: 'supplier_invoice.registered'; payload: { supplierInvoice: SupplierInvoice; userId: string; companyId: string } }
|
|
| { type: 'supplier_invoice.approved'; payload: { supplierInvoice: SupplierInvoice; userId: string; companyId: string } }
|
|
| { type: 'supplier_invoice.paid'; payload: { supplierInvoice: SupplierInvoice; paymentAmount: number; userId: string; companyId: string } }
|
|
| { type: 'supplier_invoice.credited'; payload: { supplierInvoice: SupplierInvoice; creditNote: SupplierInvoice; userId: string; companyId: string } }
|
|
| { type: 'supplier_invoice.uncredited'; payload: { supplierInvoice: SupplierInvoice; reversedCreditNoteId: string; reversalEntryId: string | null; userId: string; companyId: string } }
|
|
// Payment Matching
|
|
| { type: 'invoice.match_confirmed'; payload: { invoice: Invoice; transaction: Transaction; userId: string; companyId: string } }
|
|
| { type: 'supplier_invoice.match_confirmed'; payload: { supplierInvoice: SupplierInvoice; transaction: Transaction; userId: string; companyId: string } }
|
|
// Supplier Invoice Inbox
|
|
| { type: 'supplier_invoice.received'; payload: { inboxItem: InvoiceInboxItem; userId: string; companyId: string } }
|
|
| { type: 'supplier_invoice.extracted'; payload: { inboxItem: InvoiceInboxItem; confidence: number; userId: string; companyId: string } }
|
|
| { type: 'supplier_invoice.confirmed'; payload: { inboxItem: InvoiceInboxItem; supplierInvoice: SupplierInvoice; userId: string; companyId: string } }
|
|
// Salary
|
|
| { type: 'salary_run.created'; payload: { salaryRunId: string; periodYear: number; periodMonth: number; userId: string; companyId: string } }
|
|
| { type: 'salary_run.approved'; payload: { salaryRunId: string; approvedBy: string; userId: string; companyId: string } }
|
|
| { type: 'salary_run.booked'; payload: { salaryRunId: string; entryIds: string[]; userId: string; companyId: string } }
|
|
| { type: 'agi.generated'; payload: { agiId: string; periodYear: number; periodMonth: number; userId: string; companyId: string } }
|
|
| { type: 'agi.submitted'; payload: { salaryRunId: string; periodYear: number; periodMonth: number; userId: string; companyId: string } }
|
|
// Skatteverket — Skattekonto sync
|
|
| { type: 'skattekonto.synced'; payload: { booked: number; upcoming: number; balanceSkv: number; balanceKfm: number; userId: string; companyId: string } }
|
|
| { type: 'skattekonto.balance.changed'; payload: { previousBalance: number; currentBalance: number; userId: string; companyId: string } }
|
|
| { type: 'skattekonto.transaction.upcoming'; payload: { transaktionsdatum: string; forfallodatum: string; transaktionstext: string; beloppSkatteverket: number; userId: string; companyId: string } }
|
|
| { type: 'skattekonto.connection.expired'; payload: { reason: 'REFRESH_EXHAUSTED' | 'SESSION_EXPIRED' | 'TOKEN_CORRUPTED'; userId: string; companyId: string } }
|
|
// Fired when the SKV saldo and GL 1630 sum diverge beyond the configured
|
|
// tolerance. The drift handler emails the company contact; UI surfaces a
|
|
// dashboard tile via /api/extensions/skatteverket/skattekonto/drift.
|
|
| { type: 'skattekonto.drift_detected'; payload: {
|
|
drift: number // SKV saldo - GL 1630 sum (signed)
|
|
saldoSkatteverket: number
|
|
glSum1630: number
|
|
fetchedAt: number // ms epoch from the snapshot
|
|
unbookedCount: number // skattekonto rows without journal_entry_id ≤ fetchedAt
|
|
userId: string
|
|
companyId: string
|
|
} }
|
|
// Company & account lifecycle
|
|
| { type: 'company.deleted'; payload: { companyId: string; userId: string; archivedAt: string } }
|
|
| { type: 'account.deleted'; payload: { userId: string; deletedAt: string } }
|
|
// MCP telemetry — fired from the MCP dispatcher.
|
|
// Persisted to event_log (30-day TTL) for hot-tool / error-rate / latency analytics.
|
|
// Intentionally lightweight: no args, no result body — only metadata.
|
|
| { type: 'mcp.tool_called'; payload: {
|
|
tool: string // e.g. 'gnubok_create_invoice'
|
|
requiredScope: string | null // from TOOL_SCOPE_MAP, null if unscoped
|
|
actorType: 'user' | 'api_key' | 'mcp_oauth' | 'cron'
|
|
actorId: string | null // api_key id, oauth client, etc.
|
|
actorLabel: string | null // human-readable actor label
|
|
latencyMs: number // wall-clock time inside execute()
|
|
success: boolean // true iff the tool returned without throwing AND was invoked (not denied)
|
|
isError: boolean // matches the JSON-RPC tool-result isError flag returned to the client
|
|
errorCode: string | null // structured error code from tool-result.toToolError when applicable
|
|
errorKind: 'execution' | 'scope_denied' | 'unknown_tool' | null
|
|
requestId: string | number | null // JSON-RPC request id (helps correlate with client-side logs)
|
|
userId: string
|
|
companyId: string
|
|
}}
|
|
// tools/list — informs us whether agents are using progressive discovery
|
|
// (gnubok_search_tools) or pulling the full list. Tool counts vary with
|
|
// the caller's scope set.
|
|
| { type: 'mcp.tools_list_called'; payload: {
|
|
toolCount: number // tools actually returned (post scope filter)
|
|
actorType: 'user' | 'api_key' | 'mcp_oauth' | 'cron'
|
|
actorId: string | null
|
|
actorLabel: string | null
|
|
latencyMs: number
|
|
requestId: string | number | null
|
|
userId: string
|
|
companyId: string
|
|
}}
|
|
// resources/read — informs us which skills/widgets/data resources actually
|
|
// get loaded by agents. `kind` discriminates by URI scheme so we can
|
|
// GROUP BY skill vs widget vs data without parsing URIs.
|
|
| { type: 'mcp.resource_read'; payload: {
|
|
uri: string // e.g. 'gnubok://skill/month-end-close'
|
|
kind: 'widget' | 'skill' | 'data' | 'unknown'
|
|
success: boolean
|
|
errorCode: string | null
|
|
latencyMs: number
|
|
actorType: 'user' | 'api_key' | 'mcp_oauth' | 'cron'
|
|
actorId: string | null
|
|
actorLabel: string | null
|
|
requestId: string | number | null
|
|
userId: string
|
|
companyId: string
|
|
}}
|
|
|
|
// ============================================================
|
|
// Helper Types
|
|
// ============================================================
|
|
|
|
/** All possible event type strings */
|
|
export type CoreEventType = CoreEvent['type']
|
|
|
|
/** Extract the payload type for a given event type */
|
|
export type EventPayload<T extends CoreEventType> = Extract<CoreEvent, { type: T }>['payload']
|
|
|
|
/** Handler function for a specific event type */
|
|
export type EventHandler<T extends CoreEventType> = (payload: EventPayload<T>) => Promise<void> | void
|
|
|
|
/** Subscription: event type + handler */
|
|
export interface EventSubscription<T extends CoreEventType = CoreEventType> {
|
|
eventType: T
|
|
handler: EventHandler<T>
|
|
}
|