@centry-digital/bukku-mcp 1.1.0 → 2.0.0

package/build/tools/validation/double-entry.js

@@ -1,66 +0,0 @@
-/**
- * Double-Entry Validation for Journal Entries
- *
- * Validates that journal entry line items follow the fundamental accounting
- * rule: total debits must equal total credits.
- *
- * This validation runs client-side (before API submission) to provide
- * immediate, conversational error messages to Claude rather than waiting
- * for raw API errors.
- */
-/**
- * Validate double-entry accounting rule: debits must equal credits
- *
- * @param lines - Journal entry line items
- * @param minLines - Minimum number of lines required (default: 2)
- * @returns Validation result with detailed error message if invalid
- *
- * @example
- * ```typescript
- * // Balanced entry
- * validateDoubleEntry([
- *   { debit_amount: 100, account_id: 1 },
- *   { credit_amount: 100, account_id: 2 }
- * ]); // { valid: true }
- *
- * // Unbalanced entry
- * validateDoubleEntry([
- *   { debit_amount: 1500 },
- *   { credit_amount: 1450 }
- * ]);
- * // {
- * //   valid: false,
- * //   error: "Journal entry is unbalanced. Total debits: 1500.00, Total credits: 1450.00. Difference: 50.00. Debits must equal credits in double-entry accounting."
- * // }
- * ```
- */
-export function validateDoubleEntry(lines, minLines = 2) {
-    // Check minimum line count
-    if (lines.length < minLines) {
-        const lineWord = lines.length === 1 ? "line" : "lines";
-        return {
-            valid: false,
-            error: `Journal entries require at least ${minLines} line items (minimum one debit and one credit). This entry has ${lines.length} ${lineWord}.`,
-        };
-    }
-    // Sum debits and credits
-    let totalDebits = 0;
-    let totalCredits = 0;
-    for (const line of lines) {
-        totalDebits += line.debit_amount || 0;
-        totalCredits += line.credit_amount || 0;
-    }
-    // Compare with epsilon tolerance (1 cent)
-    // Using 0.01 instead of Number.EPSILON because currency precision
-    // is 2 decimal places, and differences smaller than 1 cent are
-    // acceptable rounding artifacts
-    const difference = Math.abs(totalDebits - totalCredits);
-    const EPSILON = 0.01;
-    if (difference >= EPSILON) {
-        return {
-            valid: false,
-            error: `Journal entry is unbalanced. Total debits: ${totalDebits.toFixed(2)}, Total credits: ${totalCredits.toFixed(2)}. Difference: ${difference.toFixed(2)}. Debits must equal credits in double-entry accounting.`,
-        };
-    }
-    return { valid: true };
-}

package/build/types/api-responses.d.ts

@@ -1,21 +0,0 @@
-/**
- * Shared API Response Type Helpers
- *
- * These types wrap Bukku API responses and MCP tool result formats
- */
-/**
- * Generic API response type for successful Bukku API calls
- * Used throughout the codebase to type-check API responses
- */
-export type BukkuApiResponse<T> = T;
-/**
- * MCP Tool Result format
- * All MCP tool handlers must return this structure
- */
-export interface ToolResult {
-    content: Array<{
-        type: 'text';
-        text: string;
-    }>;
-    isError?: boolean;
-}

package/build/types/api-responses.js

@@ -1,6 +0,0 @@
-/**
- * Shared API Response Type Helpers
- *
- * These types wrap Bukku API responses and MCP tool result formats
- */
-export {};

package/build/types/bukku.d.ts

@@ -1,93 +0,0 @@
-/**
- * Core Bukku API Type Definitions
- *
- * Hand-crafted from OpenAPI specs in .api-specs/
- * These types define the common patterns used across all Bukku API endpoints:
- * - Pagination response structure
- * - Error response format
- * - List query parameters
- * - CRUD entity configuration for the factory pattern
- */
-/**
- * Pagination metadata returned by Bukku list endpoints
- * Derived from resPaging schema in sales.yaml
- */
-export interface BukkuPaging {
-    current_page: number;
-    per_page: number;
-    total: number;
-}
-/**
- * Paginated list response wrapper
- * All list endpoints return { paging: {...}, [pluralKey]: [...] }
- * e.g., { paging: {...}, transactions: [...] }
- */
-export interface BukkuPaginatedResponse<T> {
-    paging: BukkuPaging;
-    [key: string]: T[] | BukkuPaging;
-}
-/**
- * Single item response wrapper
- * All get/create/update endpoints return { [singularKey]: {...} }
- * e.g., { transaction: {...} }
- */
-export interface BukkuSingleResponse<T> {
-    [key: string]: T;
-}
-/**
- * Error response structure
- * Derived from general-error.yaml pattern
- * - message: Human-readable error message
- * - errors: Optional validation errors (field -> error messages[])
- */
-export interface BukkuErrorResponse {
-    message: string;
-    errors?: Record<string, string[]>;
-}
-/**
- * Common list query parameters shared across all list endpoints
- * Derived from parameters/query/* in OpenAPI specs
- */
-export interface BukkuListParams {
-    page?: number;
-    page_size?: number;
-    sort_by?: string;
-    sort_dir?: 'asc' | 'desc';
-    search?: string;
-    date_from?: string;
-    date_to?: string;
-    status?: string;
-}
-/**
- * CRUD operations supported by the factory pattern
- */
-export type CrudOperation = 'list' | 'get' | 'create' | 'update' | 'delete';
-/**
- * Entity configuration for the CRUD factory pattern
- * Defines all the metadata needed to generate MCP tools for a Bukku entity
- */
-export interface CrudEntityConfig {
-    /** Entity identifier (e.g., "sales-invoice") */
-    entity: string;
-    /** API base path (e.g., "/sales/invoices") */
-    apiBasePath: string;
-    /** Response wrapper key for single item (e.g., "transaction") */
-    singularKey: string;
-    /** Response wrapper key for list items (e.g., "transactions") */
-    pluralKey: string;
-    /** Human-readable description for tool metadata (e.g., "sales invoice") */
-    description: string;
-    /** Which CRUD operations this entity supports */
-    operations: CrudOperation[];
-    /** Whether this entity supports status updates (e.g., draft -> posted) */
-    hasStatusUpdate?: boolean;
-    /** Additional list filter parameters beyond the common ones */
-    listFilters?: string[];
-    /** Optional business-rule context surfaced in tool descriptions to guide LLM behavior */
-    businessRules?: {
-        /** Constraints on when delete is allowed and what to do instead (appended to delete tool description) */
-        delete?: string;
-        /** Valid status transitions and lifecycle rules (appended to update-status tool description) */
-        statusTransitions?: string;
-    };
-}

package/build/types/bukku.js

@@ -1,11 +0,0 @@
-/**
- * Core Bukku API Type Definitions
- *
- * Hand-crafted from OpenAPI specs in .api-specs/
- * These types define the common patterns used across all Bukku API endpoints:
- * - Pagination response structure
- * - Error response format
- * - List query parameters
- * - CRUD entity configuration for the factory pattern
- */
-export {};

package/build/utils/logger.d.ts

@@ -1,6 +0,0 @@
-/**
- * Logger utility for MCP server.
- * CRITICAL: All logs must go to stderr, NEVER stdout.
- * MCP servers communicate via stdio - stdout is reserved for protocol messages.
- */
-export declare function log(message: string, ...args: unknown[]): void;

package/build/utils/logger.js

@@ -1,8 +0,0 @@
-/**
- * Logger utility for MCP server.
- * CRITICAL: All logs must go to stderr, NEVER stdout.
- * MCP servers communicate via stdio - stdout is reserved for protocol messages.
- */
-export function log(message, ...args) {
-    console.error(`[bukku-mcp] ${message}`, ...args);
-}