@centry-digital/bukku-mcp 1.1.0

package/build/errors/transform.js

@@ -0,0 +1,141 @@
+/**
+ * HTTP to MCP Error Transformation
+ * Converts HTTP error responses into conversational MCP error messages
+ */
+export function transformHttpError(status, body, operation) {
+    // Handle authentication errors (401)
+    if (status === 401) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `Bukku authentication failed for "${operation}". The BUKKU_API_TOKEN environment variable is either missing or invalid. Please check your token and restart the server with the correct credentials.`,
+                },
+            ],
+        };
+    }
+    // Handle permission errors (403)
+    if (status === 403) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `You don't have permission to "${operation}". Please check your Bukku account permissions and ensure you have access to this resource.`,
+                },
+            ],
+        };
+    }
+    // Handle not found errors (404)
+    if (status === 404) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `I couldn't find that item when trying to "${operation}". Try listing the available items first to see what's accessible.`,
+                },
+            ],
+        };
+    }
+    // Handle validation errors (400, 422)
+    if (status === 400 || status === 422) {
+        const parsedBody = body;
+        const errors = parsedBody?.errors;
+        if (errors && typeof errors === 'object') {
+            // Multiple validation errors - show all at once
+            const errorMessages = Object.entries(errors)
+                .map(([field, messages]) => `  - ${field}: ${messages.join(', ')}`)
+                .join('\n');
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Validation failed for "${operation}":\n${errorMessages}\n\nPlease fix these issues and try again.`,
+                    },
+                ],
+            };
+        }
+        else {
+            // Single error message
+            const message = parsedBody?.message || 'Invalid request';
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `${message} when trying to "${operation}". Please check your input and try again.`,
+                    },
+                ],
+            };
+        }
+    }
+    // Handle service unavailable (503)
+    if (status === 503) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `Bukku is temporarily unavailable while trying to "${operation}". Please try again in a few moments.`,
+                },
+            ],
+        };
+    }
+    // Handle server errors (500+)
+    if (status !== null && status >= 500) {
+        // Include response body for debugging server errors
+        // Often these contain validation errors that should have been 400s
+        const parsedBody = body;
+        const bodyText = body ? `\n\nServer response: ${JSON.stringify(parsedBody, null, 2)}` : '';
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `An unexpected error occurred on Bukku's servers while trying to "${operation}". Please try again, and if the issue persists, contact Bukku support.${bodyText}`,
+                },
+            ],
+        };
+    }
+    // Fallback for unknown status codes
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: `An error occurred while trying to "${operation}". Please check your request and try again.`,
+            },
+        ],
+    };
+}
+export function transformNetworkError(error, operation) {
+    // Check if it's a network-related error
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (errorMessage.includes('fetch') ||
+        errorMessage.includes('connect') ||
+        errorMessage.includes('network') ||
+        error instanceof TypeError) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: `Couldn't connect to Bukku while trying to "${operation}". Please check your internet connection and ensure the Bukku API is accessible.`,
+                },
+            ],
+        };
+    }
+    // Fallback for unknown errors
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: `An unexpected error occurred while trying to "${operation}": ${errorMessage}. Please try again.`,
+            },
+        ],
+    };
+}

package/build/errors/transform.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/errors/transform.test.js

@@ -0,0 +1,101 @@
+import { describe, test } from 'node:test';
+import assert from 'node:assert';
+import { transformHttpError, transformNetworkError } from './transform.ts';
+describe('transformHttpError', () => {
+    test('401 error produces auth failure message mentioning BUKKU_API_TOKEN', () => {
+        const result = transformHttpError(401, { message: 'Unauthorized' }, 'create invoice');
+        assert.strictEqual(result.isError, true);
+        assert.ok(Array.isArray(result.content));
+        assert.strictEqual(result.content.length, 1);
+        assert.strictEqual(result.content[0].type, 'text');
+        const text = result.content[0].text;
+        assert.ok(text.includes('Bukku') || text.includes('token'), 'Should mention Bukku or token');
+        assert.ok(text.includes('BUKKU_API_TOKEN'), 'Should mention BUKKU_API_TOKEN');
+        assert.ok(text.length > 20, 'Should suggest next step');
+    });
+    test('403 error produces permission error with suggestion', () => {
+        const result = transformHttpError(403, { message: 'Forbidden' }, 'list contacts');
+        assert.strictEqual(result.isError, true);
+        assert.strictEqual(result.content[0].type, 'text');
+        const text = result.content[0].text;
+        assert.ok(text.toLowerCase().includes('permission') || text.toLowerCase().includes('access'), 'Should mention permission or access');
+        assert.ok(text.length > 20, 'Should suggest next step');
+    });
+    test('404 error suggests listing available items', () => {
+        const result = transformHttpError(404, { message: 'Not found' }, 'get sales invoice');
+        assert.strictEqual(result.isError, true);
+        assert.strictEqual(result.content[0].type, 'text');
+        const text = result.content[0].text;
+        assert.ok(text.toLowerCase().includes("couldn't find") || text.toLowerCase().includes('not found'), 'Should indicate not found');
+        assert.ok(text.toLowerCase().includes('list') || text.toLowerCase().includes('available'), 'Should suggest listing items');
+    });
+    test('400 error shows all validation errors at once', () => {
+        const result = transformHttpError(400, {
+            message: 'Validation failed',
+            errors: {
+                contact_id: ['required'],
+                date: ['invalid format'],
+            },
+        }, 'create invoice');
+        assert.strictEqual(result.isError, true);
+        assert.strictEqual(result.content[0].type, 'text');
+        const text = result.content[0].text;
+        assert.ok(text.includes('contact_id'), 'Should include contact_id error');
+        assert.ok(text.includes('date'), 'Should include date error');
+        assert.ok(text.length > 20, 'Should suggest next step');
+    });
+    test('400 error without errors field shows message', () => {
+        const result = transformHttpError(400, { message: 'Something wrong' }, 'update order');
+        assert.strictEqual(result.isError, true);
+        assert.strictEqual(result.content[0].type, 'text');
+        const text = result.content[0].text;
+        assert.ok(text.includes('Something wrong'), 'Should include error message');
+        assert.ok(text.length > 20, 'Should suggest next step');
+    });
+    test('422 validation error handled like 400', () => {
+        const result = transformHttpError(422, {
+            message: 'Unprocessable',
+            errors: {
+                items: ['at least one item required'],
+            },
+        }, 'create invoice');
+        assert.strictEqual(result.isError, true);
+        assert.strictEqual(result.content[0].type, 'text');
+        const text = result.content[0].text;
+        assert.ok(text.includes('items'), 'Should include items error');
+        assert.ok(text.length > 20, 'Should suggest next step');
+    });
+    test('500 error produces helpful fallback with retry suggestion', () => {
+        const result = transformHttpError(500, { message: 'Internal error' }, 'list invoices');
+        assert.strictEqual(result.isError, true);
+        assert.strictEqual(result.content[0].type, 'text');
+        const text = result.content[0].text;
+        assert.ok(text.toLowerCase().includes('unexpected') || text.toLowerCase().includes('error'), 'Should indicate unexpected error');
+        assert.ok(text.toLowerCase().includes('try') || text.toLowerCase().includes('again'), 'Should suggest trying again');
+    });
+    test('503 error suggests trying later', () => {
+        const result = transformHttpError(503, { message: 'Service unavailable' }, 'create payment');
+        assert.strictEqual(result.isError, true);
+        assert.strictEqual(result.content[0].type, 'text');
+        const text = result.content[0].text;
+        assert.ok(text.toLowerCase().includes('unavailable') || text.toLowerCase().includes('temporarily'), 'Should indicate service unavailable');
+        assert.ok(text.toLowerCase().includes('later') || text.toLowerCase().includes('try'), 'Should suggest trying later');
+    });
+});
+describe('transformNetworkError', () => {
+    test('network error suggests checking connection', () => {
+        const networkError = new TypeError('Failed to fetch');
+        const result = transformNetworkError(networkError, 'list contacts');
+        assert.strictEqual(result.isError, true);
+        assert.strictEqual(result.content[0].type, 'text');
+        const text = result.content[0].text;
+        assert.ok(text.toLowerCase().includes('connect') || text.toLowerCase().includes('network'), 'Should mention connection or network');
+        assert.ok(text.length > 20, 'Should suggest next step');
+    });
+    test('handles unknown error gracefully', () => {
+        const result = transformNetworkError('unknown error', 'create invoice');
+        assert.strictEqual(result.isError, true);
+        assert.strictEqual(result.content[0].type, 'text');
+        assert.ok(result.content[0].text.length > 10, 'Should provide some error message');
+    });
+});

package/build/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Bukku MCP Server Entry Point
+ *
+ * Startup sequence:
+ * 1. Validate environment variables (BUKKU_API_TOKEN, BUKKU_COMPANY_SUBDOMAIN)
+ * 2. Create BukkuClient with validated env
+ * 3. Validate API token via lightweight API call
+ * 4. Create MCP server and register tools
+ * 5. Connect via stdio transport
+ * 6. Log startup to stderr
+ */
+export {};

package/build/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * Bukku MCP Server Entry Point
+ *
+ * Startup sequence:
+ * 1. Validate environment variables (BUKKU_API_TOKEN, BUKKU_COMPANY_SUBDOMAIN)
+ * 2. Create BukkuClient with validated env
+ * 3. Validate API token via lightweight API call
+ * 4. Create MCP server and register tools
+ * 5. Connect via stdio transport
+ * 6. Log startup to stderr
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { validateEnv } from "./config/env.js";
+import { BukkuClient } from "./client/bukku-client.js";
+import { registerAllTools } from "./tools/registry.js";
+import { log } from "./utils/logger.js";
+// Read package.json version dynamically
+const packageJsonPath = new URL("../package.json", import.meta.url);
+const pkg = JSON.parse(readFileSync(fileURLToPath(packageJsonPath), "utf-8"));
+/**
+ * Main entry point.
+ * Exits process if configuration or authentication fails.
+ */
+async function main() {
+    // Step 1: Validate environment variables
+    const env = validateEnv();
+    // Step 2: Create authenticated Bukku API client
+    const client = new BukkuClient(env);
+    // Step 3: Validate API token
+    await client.validateToken();
+    // Step 4: Create MCP server
+    const server = new McpServer({
+        name: "bukku",
+        version: pkg.version,
+    });
+    // Step 5: Register all tools
+    const toolCount = registerAllTools(server, client);
+    // Step 6: Connect via stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Step 7: Log startup to stderr
+    log(`Bukku MCP server started (${toolCount} tools registered)`);
+}
+// Execute main and handle fatal errors
+main().catch((error) => {
+    log("Fatal error during startup:", error);
+    process.exit(1);
+});

package/build/tools/cache/reference-cache.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Reference Data Cache
+ *
+ * Transparent in-memory cache for Bukku reference data (tax codes, currencies, etc.)
+ * with 5-minute TTL per roadmap requirement LIST-02.
+ *
+ * Features:
+ * - In-memory Map-based storage
+ * - 5-minute TTL (configurable for testing)
+ * - Lazy deletion: expired entries removed on access
+ * - Cache key = reference data type name (e.g., "tax_codes", "currencies")
+ */
+export declare class ReferenceDataCache {
+    private cache;
+    private readonly ttlMs;
+    /**
+     * Create a new reference data cache
+     * @param ttlMs Time-to-live in milliseconds (default: 5 minutes)
+     */
+    constructor(ttlMs?: number);
+    /**
+     * Get cached data by key
+     * @param key Cache key (reference data type name)
+     * @returns Cached data or undefined if not found or expired
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Store data in cache with TTL
+     * @param key Cache key (reference data type name)
+     * @param data Data to cache
+     */
+    set<T>(key: string, data: T): void;
+    /**
+     * Invalidate a specific cache entry
+     * @param key Cache key to invalidate
+     */
+    invalidate(key: string): void;
+    /**
+     * Clear all cached entries
+     */
+    clear(): void;
+}

package/build/tools/cache/reference-cache.js

@@ -0,0 +1,63 @@
+/**
+ * Reference Data Cache
+ *
+ * Transparent in-memory cache for Bukku reference data (tax codes, currencies, etc.)
+ * with 5-minute TTL per roadmap requirement LIST-02.
+ *
+ * Features:
+ * - In-memory Map-based storage
+ * - 5-minute TTL (configurable for testing)
+ * - Lazy deletion: expired entries removed on access
+ * - Cache key = reference data type name (e.g., "tax_codes", "currencies")
+ */
+export class ReferenceDataCache {
+    cache = new Map();
+    ttlMs;
+    /**
+     * Create a new reference data cache
+     * @param ttlMs Time-to-live in milliseconds (default: 5 minutes)
+     */
+    constructor(ttlMs = 5 * 60 * 1000) {
+        this.ttlMs = ttlMs;
+    }
+    /**
+     * Get cached data by key
+     * @param key Cache key (reference data type name)
+     * @returns Cached data or undefined if not found or expired
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        // Check expiration (lazy deletion)
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.data;
+    }
+    /**
+     * Store data in cache with TTL
+     * @param key Cache key (reference data type name)
+     * @param data Data to cache
+     */
+    set(key, data) {
+        this.cache.set(key, {
+            data,
+            expiresAt: Date.now() + this.ttlMs,
+        });
+    }
+    /**
+     * Invalidate a specific cache entry
+     * @param key Cache key to invalidate
+     */
+    invalidate(key) {
+        this.cache.delete(key);
+    }
+    /**
+     * Clear all cached entries
+     */
+    clear() {
+        this.cache.clear();
+    }
+}

package/build/tools/configs/account.d.ts

@@ -0,0 +1,17 @@
+import type { CrudEntityConfig } from "../../types/bukku.js";
+/**
+ * Account Entity Configuration
+ *
+ * API: /accounts
+ * Response keys: account (singular), accounts (plural)
+ * Operations: get, create, update, delete ONLY — NO list operation
+ * - List omitted because Phase 5's list-accounts reference data tool already
+ *   occupies that tool name (provides cached quick lookup)
+ * - Use search-accounts (custom tool in account-tools.ts) for filtered search
+ *   of the chart of accounts
+ * - Archive/unarchive handled by custom tools (account-tools.ts), not status
+ *   update, because API expects { is_archived: boolean }
+ * Delete constraint: Only accounts with no children, not in locked system type,
+ * and not used in transactions can be deleted
+ */
+export declare const accountConfig: CrudEntityConfig;

package/build/tools/configs/account.js

@@ -0,0 +1,28 @@
+/**
+ * Account Entity Configuration
+ *
+ * API: /accounts
+ * Response keys: account (singular), accounts (plural)
+ * Operations: get, create, update, delete ONLY — NO list operation
+ * - List omitted because Phase 5's list-accounts reference data tool already
+ *   occupies that tool name (provides cached quick lookup)
+ * - Use search-accounts (custom tool in account-tools.ts) for filtered search
+ *   of the chart of accounts
+ * - Archive/unarchive handled by custom tools (account-tools.ts), not status
+ *   update, because API expects { is_archived: boolean }
+ * Delete constraint: Only accounts with no children, not in locked system type,
+ * and not used in transactions can be deleted
+ */
+export const accountConfig = {
+    entity: "account",
+    apiBasePath: "/accounts",
+    singularKey: "account",
+    pluralKey: "accounts",
+    description: "account",
+    operations: ["get", "create", "update", "delete"],
+    hasStatusUpdate: false,
+    listFilters: [],
+    businessRules: {
+        delete: "Only accounts that are not assigned to locked system type, have no children, and are not used in transactions can be deleted. Use archive-account instead if the account has transaction history.",
+    },
+};

package/build/tools/configs/bank-money-in.d.ts

@@ -0,0 +1,10 @@
+import type { CrudEntityConfig } from "../../types/bukku.js";
+/**
+ * Bank Money In Entity Configuration
+ *
+ * API: /banking/incomes
+ * Response keys: transaction (singular), transactions (plural)
+ * Money In represents incoming cash transactions (deposits, receipts, etc.)
+ * Shares the same status lifecycle as sales/purchase transactions.
+ */
+export declare const bankMoneyInConfig: CrudEntityConfig;

package/build/tools/configs/bank-money-in.js

@@ -0,0 +1,22 @@
+/**
+ * Bank Money In Entity Configuration
+ *
+ * API: /banking/incomes
+ * Response keys: transaction (singular), transactions (plural)
+ * Money In represents incoming cash transactions (deposits, receipts, etc.)
+ * Shares the same status lifecycle as sales/purchase transactions.
+ */
+export const bankMoneyInConfig = {
+    entity: "bank-money-in",
+    apiBasePath: "/banking/incomes",
+    singularKey: "transaction",
+    pluralKey: "transactions",
+    description: "bank money in transaction",
+    operations: ["list", "get", "create", "update", "delete"],
+    hasStatusUpdate: true,
+    listFilters: ["contact_id", "account_id", "email_status"],
+    businessRules: {
+        delete: "Only draft and void money in transactions can be deleted. Ready or pending approval transactions cannot be deleted — use update-bank-money-in-status to void a ready transaction instead.",
+        statusTransitions: "Valid transitions: draft -> pending_approval, draft -> ready, pending_approval -> ready, ready -> void. A void transaction is final and cannot be changed. There is no way to revert from ready, pending_approval, or void back to draft.",
+    },
+};

package/build/tools/configs/bank-money-out.d.ts

@@ -0,0 +1,10 @@
+import type { CrudEntityConfig } from "../../types/bukku.js";
+/**
+ * Bank Money Out Entity Configuration
+ *
+ * API: /banking/expenses
+ * Response keys: transaction (singular), transactions (plural)
+ * Money Out represents outgoing cash transactions (payments, disbursements, etc.)
+ * Shares the same status lifecycle as sales/purchase transactions.
+ */
+export declare const bankMoneyOutConfig: CrudEntityConfig;

package/build/tools/configs/bank-money-out.js

@@ -0,0 +1,22 @@
+/**
+ * Bank Money Out Entity Configuration
+ *
+ * API: /banking/expenses
+ * Response keys: transaction (singular), transactions (plural)
+ * Money Out represents outgoing cash transactions (payments, disbursements, etc.)
+ * Shares the same status lifecycle as sales/purchase transactions.
+ */
+export const bankMoneyOutConfig = {
+    entity: "bank-money-out",
+    apiBasePath: "/banking/expenses",
+    singularKey: "transaction",
+    pluralKey: "transactions",
+    description: "bank money out transaction",
+    operations: ["list", "get", "create", "update", "delete"],
+    hasStatusUpdate: true,
+    listFilters: ["contact_id", "account_id", "email_status"],
+    businessRules: {
+        delete: "Only draft and void money out transactions can be deleted. Ready or pending approval transactions cannot be deleted — use update-bank-money-out-status to void a ready transaction instead.",
+        statusTransitions: "Valid transitions: draft -> pending_approval, draft -> ready, pending_approval -> ready, ready -> void. A void transaction is final and cannot be changed. There is no way to revert from ready, pending_approval, or void back to draft.",
+    },
+};

package/build/tools/configs/bank-transfer.d.ts

@@ -0,0 +1,11 @@
+import type { CrudEntityConfig } from "../../types/bukku.js";
+/**
+ * Bank Transfer Entity Configuration
+ *
+ * API: /banking/transfers
+ * Response keys: transaction (singular), transactions (plural)
+ * Transfers are account-to-account movements (no contact involved).
+ * Has fewer list filters than money in/out — only account_id (no contact_id, no email_status).
+ * Shares the same status lifecycle as other banking/sales/purchase transactions.
+ */
+export declare const bankTransferConfig: CrudEntityConfig;

package/build/tools/configs/bank-transfer.js

@@ -0,0 +1,23 @@
+/**
+ * Bank Transfer Entity Configuration
+ *
+ * API: /banking/transfers
+ * Response keys: transaction (singular), transactions (plural)
+ * Transfers are account-to-account movements (no contact involved).
+ * Has fewer list filters than money in/out — only account_id (no contact_id, no email_status).
+ * Shares the same status lifecycle as other banking/sales/purchase transactions.
+ */
+export const bankTransferConfig = {
+    entity: "bank-transfer",
+    apiBasePath: "/banking/transfers",
+    singularKey: "transaction",
+    pluralKey: "transactions",
+    description: "bank transfer",
+    operations: ["list", "get", "create", "update", "delete"],
+    hasStatusUpdate: true,
+    listFilters: ["account_id"],
+    businessRules: {
+        delete: "Only draft and void transfers can be deleted. Ready or pending approval transfers cannot be deleted — use update-bank-transfer-status to void a ready transfer instead.",
+        statusTransitions: "Valid transitions: draft -> pending_approval, draft -> ready, pending_approval -> ready, ready -> void. A void transfer is final and cannot be changed. There is no way to revert from ready, pending_approval, or void back to draft.",
+    },
+};

package/build/tools/configs/contact-group.d.ts

@@ -0,0 +1,11 @@
+import type { CrudEntityConfig } from "../../types/bukku.js";
+/**
+ * Contact Group Entity Configuration
+ *
+ * API: /contacts/groups
+ * Response keys: group (singular), groups (plural)
+ * Groups organize contacts into categories.
+ * Simplest entity config — no status operations, no entity-specific filters,
+ * no business rules. Factory provides base pagination parameters.
+ */
+export declare const contactGroupConfig: CrudEntityConfig;

package/build/tools/configs/contact-group.js

@@ -0,0 +1,19 @@
+/**
+ * Contact Group Entity Configuration
+ *
+ * API: /contacts/groups
+ * Response keys: group (singular), groups (plural)
+ * Groups organize contacts into categories.
+ * Simplest entity config — no status operations, no entity-specific filters,
+ * no business rules. Factory provides base pagination parameters.
+ */
+export const contactGroupConfig = {
+    entity: "contact-group",
+    apiBasePath: "/contacts/groups",
+    singularKey: "group",
+    pluralKey: "groups",
+    description: "contact group",
+    operations: ["list", "get", "create", "update", "delete"],
+    hasStatusUpdate: false,
+    listFilters: [],
+};

package/build/tools/configs/contact.d.ts

@@ -0,0 +1,14 @@
+import type { CrudEntityConfig } from "../../types/bukku.js";
+/**
+ * Contact Entity Configuration
+ *
+ * API: /contacts
+ * Response keys: contact (singular), contacts (plural) — NOT transaction/transactions
+ * This is the first non-transaction entity; uses custom wrapper keys.
+ * Archive/unarchive is handled by separate custom tools (contact-archive.ts),
+ * NOT the factory status tool, because the API expects { is_archived: boolean }
+ * instead of { status: string }.
+ * List filter: status accepts ALL, ACTIVE, or INACTIVE values.
+ * List filter: type accepts customer, supplier, or employee values.
+ */
+export declare const contactConfig: CrudEntityConfig;

package/build/tools/configs/contact.js

@@ -0,0 +1,25 @@
+/**
+ * Contact Entity Configuration
+ *
+ * API: /contacts
+ * Response keys: contact (singular), contacts (plural) — NOT transaction/transactions
+ * This is the first non-transaction entity; uses custom wrapper keys.
+ * Archive/unarchive is handled by separate custom tools (contact-archive.ts),
+ * NOT the factory status tool, because the API expects { is_archived: boolean }
+ * instead of { status: string }.
+ * List filter: status accepts ALL, ACTIVE, or INACTIVE values.
+ * List filter: type accepts customer, supplier, or employee values.
+ */
+export const contactConfig = {
+    entity: "contact",
+    apiBasePath: "/contacts",
+    singularKey: "contact",
+    pluralKey: "contacts",
+    description: "contact",
+    operations: ["list", "get", "create", "update", "delete"],
+    hasStatusUpdate: false,
+    listFilters: ["group_id", "status", "type", "is_myinvois_ready"],
+    businessRules: {
+        delete: "Only contacts with no linked transactions can be deleted. Archive instead if the contact has transaction history.",
+    },
+};

package/build/tools/configs/delivery-order.d.ts

@@ -0,0 +1,8 @@
+import type { CrudEntityConfig } from "../../types/bukku.js";
+/**
+ * Delivery Order Entity Configuration
+ *
+ * API: /sales/delivery_orders
+ * Response keys: transaction (singular), transactions (plural)
+ */
+export declare const deliveryOrderConfig: CrudEntityConfig;