@kansei-link/bantou 0.2.0

package/dist/reports/monthly-report.js

@@ -0,0 +1,230 @@
+// Monthly review report generator.
+//
+// Takes classified transaction data and produces a practitioner-proven
+// monthly review report in Markdown format.
+//
+// Features:
+//   - Category-wise expense breakdown with monthly/yearly comparison
+//   - Anomaly detection (significant deviations from expected patterns)
+//   - Action items (transactions requiring human review)
+//   - Summary KPIs (total expense, income, classification rate)
+/**
+ * Generate a monthly report from raw transactions.
+ *
+ * @param transactions - Array of raw transactions (from freee API, CSV import, etc.)
+ * @param classifier   - TwoStageClassifier instance.
+ * @param exclusion    - ExclusionChecker instance.
+ * @param router       - ConfidenceRouter instance.
+ * @param opts         - Report options.
+ */
+export async function generateMonthlyReport(transactions, classifier, exclusion, router, opts) {
+    const format = opts.format || 'markdown';
+    // 1. Classify all transactions
+    const processed = [];
+    let totalExpense = 0;
+    let totalIncome = 0;
+    let autoCount = 0;
+    for (const tx of transactions) {
+        const exc = exclusion.check(tx);
+        let cls = null;
+        if (!exc.excluded) {
+            cls = await classifier.classify(tx);
+        }
+        const routing = router.route(exc, cls, {
+            amount: tx.amount,
+            partner_name: tx.partner_name,
+            is_new_partner: false,
+            date: tx.date,
+        });
+        const rt = {
+            transaction: tx,
+            category_id: cls?.category_id,
+            category_name_ja: cls?.category_name_ja,
+            confidence: cls?.confidence,
+            excluded: exc.excluded,
+            exclusion_rule: exc.rule_id,
+            action: routing.action,
+            flags: routing.flags,
+        };
+        processed.push(rt);
+        // Accumulate totals (rough heuristic: negative = income, positive = expense)
+        totalExpense += tx.amount;
+        if (routing.action === 'auto_register' || routing.action === 'auto_register_with_log') {
+            autoCount++;
+        }
+    }
+    // 2. Build category aggregates
+    const catMap = new Map();
+    for (const rt of processed) {
+        if (rt.excluded)
+            continue;
+        const catId = rt.category_id || '_unclassified';
+        const catName = rt.category_name_ja || '未分類';
+        if (!catMap.has(catId)) {
+            catMap.set(catId, {
+                category_id: catId,
+                category_name_ja: catName,
+                count: 0,
+                total_amount: 0,
+                transactions: [],
+            });
+        }
+        const agg = catMap.get(catId);
+        agg.count++;
+        agg.total_amount += rt.transaction.amount;
+        agg.transactions.push(rt);
+    }
+    const categories = [...catMap.values()].sort((a, b) => b.total_amount - a.total_amount);
+    // 3. Detect anomalies
+    const anomalies = detectAnomalies(processed, categories);
+    // 4. Build comparison data (if provided)
+    let comparisonCategories;
+    if (opts.compare_transactions && opts.compare_transactions.length > 0) {
+        comparisonCategories = new Map();
+        for (const tx of opts.compare_transactions) {
+            const cls = await classifier.classify(tx);
+            const catId = cls?.category_id || '_unclassified';
+            comparisonCategories.set(catId, (comparisonCategories.get(catId) || 0) + tx.amount);
+        }
+    }
+    // 5. Review items
+    const reviewItems = processed.filter(rt => rt.action === 'human_review');
+    // 6. Rates
+    const total = processed.length;
+    const classifiedCount = processed.filter(rt => rt.category_id && !rt.excluded).length;
+    const classificationRate = total > 0 ? ((classifiedCount / total) * 100).toFixed(1) + '%' : '0%';
+    const autoRegisterRate = total > 0 ? ((autoCount / total) * 100).toFixed(1) + '%' : '0%';
+    // 7. Build markdown
+    let markdown;
+    if (format === 'markdown') {
+        markdown = buildMarkdown(opts.company_name || '(Company)', opts.month, total, totalExpense, totalIncome, classificationRate, autoRegisterRate, categories, anomalies, reviewItems, comparisonCategories, opts.compare_label);
+    }
+    return {
+        ok: true,
+        company_name: opts.company_name,
+        month: opts.month,
+        format,
+        total_transactions: total,
+        total_expense: totalExpense,
+        total_income: totalIncome,
+        classification_rate: classificationRate,
+        auto_register_rate: autoRegisterRate,
+        categories,
+        anomalies,
+        review_items: reviewItems,
+        markdown,
+    };
+}
+// ============================================================
+// Anomaly detection
+// ============================================================
+function detectAnomalies(transactions, categories) {
+    const anomalies = [];
+    // Rule 1: Single transactions > ¥500K
+    for (const rt of transactions) {
+        if (rt.transaction.amount > 500_000 && !rt.excluded) {
+            anomalies.push({
+                type: 'high_amount',
+                severity: rt.transaction.amount > 1_000_000 ? 'critical' : 'warning',
+                description: `高額取引: ¥${rt.transaction.amount.toLocaleString()}`,
+                details: `${rt.transaction.date} ${rt.transaction.memo}`,
+            });
+        }
+    }
+    // Rule 2: 交際費 (entertainment) > ¥100K total — flag for 5,000円基準 review
+    const entertainment = categories.find(c => c.category_id === 'entertainment');
+    if (entertainment && entertainment.total_amount > 100_000) {
+        anomalies.push({
+            type: 'unusual_category',
+            severity: 'warning',
+            description: `交際費合計 ¥${entertainment.total_amount.toLocaleString()} — 5,000円基準/損金算入限度 確認推奨`,
+            details: `${entertainment.count}件の交際費取引`,
+        });
+    }
+    // Rule 3: Unclassified transactions > 10%
+    const unclassified = categories.find(c => c.category_id === '_unclassified');
+    if (unclassified) {
+        const total = transactions.filter(t => !t.excluded).length;
+        const ratio = total > 0 ? unclassified.count / total : 0;
+        if (ratio > 0.1) {
+            anomalies.push({
+                type: 'unusual_category',
+                severity: 'warning',
+                description: `未分類率 ${(ratio * 100).toFixed(1)}% — キーワード辞書の拡充推奨`,
+                details: `${unclassified.count}/${total} 件が未分類`,
+            });
+        }
+    }
+    return anomalies;
+}
+// ============================================================
+// Markdown builder
+// ============================================================
+function buildMarkdown(companyName, month, total, totalExpense, totalIncome, classificationRate, autoRegisterRate, categories, anomalies, reviewItems, comparisonCategories, compareLabel) {
+    const [year, mon] = month.split('-');
+    const title = `${companyName} — ${year}年${parseInt(mon)}月 月次レビューレポート`;
+    let md = `# ${title}\n\n`;
+    md += `> Generated: ${new Date().toISOString().slice(0, 10)} by Cockpit MCP\n\n`;
+    // ── Summary ──
+    md += `## Summary\n\n`;
+    md += `| Metric | Value |\n|---|---|\n`;
+    md += `| Total transactions | ${total} |\n`;
+    md += `| Total expense | ¥${totalExpense.toLocaleString()} |\n`;
+    md += `| Classification rate | ${classificationRate} |\n`;
+    md += `| Auto-register rate | ${autoRegisterRate} |\n`;
+    md += `| Review required | ${reviewItems.length} |\n`;
+    md += `| Anomalies detected | ${anomalies.length} |\n\n`;
+    // ── Anomalies ──
+    if (anomalies.length > 0) {
+        md += `## Anomalies\n\n`;
+        for (const a of anomalies) {
+            const icon = a.severity === 'critical' ? '[CRITICAL]' : '[WARNING]';
+            md += `- ${icon} **${a.description}**\n`;
+            md += `  ${a.details}\n`;
+        }
+        md += '\n';
+    }
+    // ── Category Breakdown ──
+    md += `## Category Breakdown\n\n`;
+    if (comparisonCategories && compareLabel) {
+        md += `| Category | Count | Amount | ${compareLabel} | Change |\n|---|---|---|---|---|\n`;
+        for (const cat of categories) {
+            const prevAmount = comparisonCategories.get(cat.category_id) || 0;
+            const change = prevAmount > 0
+                ? ((cat.total_amount - prevAmount) / prevAmount * 100).toFixed(1) + '%'
+                : 'NEW';
+            const changeSign = cat.total_amount > prevAmount ? '+' : '';
+            md += `| ${cat.category_name_ja} | ${cat.count} | ¥${cat.total_amount.toLocaleString()} | ¥${prevAmount.toLocaleString()} | ${changeSign}${change} |\n`;
+        }
+    }
+    else {
+        md += `| Category | Count | Amount | Share |\n|---|---|---|---|\n`;
+        for (const cat of categories) {
+            const share = totalExpense > 0
+                ? ((cat.total_amount / totalExpense) * 100).toFixed(1) + '%'
+                : '0%';
+            md += `| ${cat.category_name_ja} | ${cat.count} | ¥${cat.total_amount.toLocaleString()} | ${share} |\n`;
+        }
+    }
+    md += '\n';
+    // ── Review Items ──
+    if (reviewItems.length > 0) {
+        md += `## Review Required (${reviewItems.length} items)\n\n`;
+        md += `| Date | Amount | Memo | Reason |\n|---|---|---|---|\n`;
+        for (const rt of reviewItems.slice(0, 30)) {
+            const reason = rt.flags.length > 0
+                ? rt.flags.join(', ')
+                : (rt.excluded ? `Excluded: ${rt.exclusion_rule}` : 'Low confidence');
+            md += `| ${rt.transaction.date} | ¥${rt.transaction.amount.toLocaleString()} | ${rt.transaction.memo.slice(0, 35)} | ${reason} |\n`;
+        }
+        if (reviewItems.length > 30) {
+            md += `| ... | ... | ... | +${reviewItems.length - 30} more |\n`;
+        }
+        md += '\n';
+    }
+    // ── Footer ──
+    md += `---\n\n`;
+    md += `*Generated by @kansei-link/cockpit MCP — automated monthly review*\n`;
+    return md;
+}
+//# sourceMappingURL=monthly-report.js.map

package/dist/secrets.d.ts

@@ -0,0 +1,14 @@
+export interface FreeeSecrets {
+    access_token: string;
+    company_id: number;
+    company_name: string;
+    token_expires_at: string;
+    client_id?: string;
+    client_secret?: string;
+    refresh_token?: string;
+}
+export declare function loadFreeeSecrets(secretsPath?: string, opts?: {
+    requireCompanyId?: boolean;
+}): FreeeSecrets;
+export declare function isTokenExpired(secrets: FreeeSecrets, bufferMinutes?: number): boolean;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.js

@@ -0,0 +1,86 @@
+// Secrets loader for Cockpit MCP.
+//
+// Sources freee credentials with env winning over file: environment variables
+// (FREEE_ACCESS_TOKEN / FREEE_COMPANY_ID — as declared in .mcp.json / plugin settings),
+// then the secrets file ~/.claude/secrets/freee-cockpit-dev.json. NEVER logs secret values.
+//
+// Production deployment will source secrets from a different mechanism
+// (= Cloudflare Worker secret store or env vars, not this filesystem path).
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const DEFAULT_SECRETS_PATH = path.join(os.homedir(), '.claude', 'secrets', 'freee-cockpit-dev.json');
+export function loadFreeeSecrets(secretsPath = DEFAULT_SECRETS_PATH, opts = {}) {
+    const requireCompanyId = opts.requireCompanyId !== false; // default: required
+    // Source 1: the secrets file (now OPTIONAL — env vars are a valid alternative).
+    let data = {};
+    const fileExists = fs.existsSync(secretsPath);
+    if (fileExists) {
+        data = JSON.parse(fs.readFileSync(secretsPath, 'utf8'));
+    }
+    // Source 2: environment variables (env wins over file).
+    // This is what makes the documented FREEE_ACCESS_TOKEN / FREEE_COMPANY_ID actually take
+    // effect — previously they were declared in .mcp.json / plugin settings but never read here.
+    const env = process.env;
+    if (env.FREEE_ACCESS_TOKEN)
+        data.access_token = env.FREEE_ACCESS_TOKEN;
+    if (env.FREEE_COMPANY_ID)
+        data.company_id = env.FREEE_COMPANY_ID;
+    if (env.FREEE_COMPANY_NAME)
+        data.company_name = env.FREEE_COMPANY_NAME;
+    if (env.FREEE_TOKEN_EXPIRES_AT)
+        data.token_expires_at = env.FREEE_TOKEN_EXPIRES_AT;
+    if (env.FREEE_CLIENT_ID)
+        data.client_id = env.FREEE_CLIENT_ID;
+    if (env.FREEE_CLIENT_SECRET)
+        data.client_secret = env.FREEE_CLIENT_SECRET;
+    if (env.FREEE_REFRESH_TOKEN)
+        data.refresh_token = env.FREEE_REFRESH_TOKEN;
+    // Neither source provided a token → fail with a message that names BOTH paths.
+    if (!(data.freee_access_token || data.access_token)) {
+        throw new Error('freee access token not found. Provide it via the FREEE_ACCESS_TOKEN environment variable ' +
+            '(plugin settings / .mcp.json), or in the secrets file at ' + secretsPath + ' ' +
+            '(file ' + (fileExists ? 'present but missing access_token' : 'not found') + '). See README.');
+    }
+    // Field name normalization (file may use the freee_X prefix; env uses canonical names).
+    const secrets = {
+        access_token: data.freee_access_token || data.access_token,
+        company_id: Number(data.freee_company_id || data.company_id),
+        company_name: data.freee_company_name || data.company_name || '',
+        token_expires_at: data.freee_token_expires_at || data.token_expires_at || '',
+    };
+    // Optional fields (TODO placeholders are filtered out)
+    const optionalString = (v) => {
+        if (typeof v !== 'string')
+            return undefined;
+        if (v.startsWith('TODO') || v.startsWith('<') || v === '')
+            return undefined;
+        return v;
+    };
+    secrets.client_id = optionalString(data.freee_client_id || data.client_id);
+    secrets.client_secret = optionalString(data.freee_client_secret || data.client_secret);
+    secrets.refresh_token = optionalString(data.freee_refresh_token || data.refresh_token);
+    // Validate
+    if (!secrets.access_token || secrets.access_token.startsWith('<')) {
+        throw new Error('freee access token is missing or placeholder');
+    }
+    if (requireCompanyId && (!secrets.company_id || isNaN(secrets.company_id))) {
+        throw new Error('freee company_id is missing or invalid. Run `npm run doctor:freee` (or the freee_doctor tool) ' +
+            'to list accessible companies and pick the right id, then set FREEE_COMPANY_ID ' +
+            '(or company_id in the secrets file).');
+    }
+    return secrets;
+}
+export function isTokenExpired(secrets, bufferMinutes = 5) {
+    if (!secrets.token_expires_at)
+        return false; // unknown, assume valid
+    const expiresAt = new Date(secrets.token_expires_at).getTime();
+    // A malformed timestamp (e.g. stray spaces "16: 00: 00") yields NaN. Previously the NaN
+    // comparison silently returned false ("not expired"), so the pre-flight guard never fired and
+    // the caller got a cryptic raw 401 instead. Treat an unparseable expiry as expired.
+    if (Number.isNaN(expiresAt))
+        return true;
+    const bufferMs = bufferMinutes * 60 * 1000;
+    return expiresAt - Date.now() < bufferMs;
+}
+//# sourceMappingURL=secrets.js.map

package/dist/tax-rules/tax-rule-engine.d.ts

@@ -0,0 +1,103 @@
+import { Transaction, ClassificationResult } from '../classifier/types.js';
+import type { TaxRuleResult, InvoiceCheckResult } from './types.js';
+export declare class TaxRuleEngine {
+    private config;
+    private normalizedOverseas;
+    private normalizedDomestic;
+    private normalizedJctIndicators;
+    private normalizedNewspaper;
+    private normalizedFoodBev;
+    private normalizedResidential;
+    private normalizedOverseasAds;
+    private normalizedDomesticAds;
+    private normalizedTakeout;
+    private normalizedFoodPurchase;
+    private normalizedCateringService;
+    constructor(configFile?: string, dataDir?: string);
+    /**
+     * Apply all post-classification rules to a transaction.
+     * Returns a TaxRuleResult describing any adjustments to make.
+     */
+    applyRules(tx: Transaction, classification: ClassificationResult): TaxRuleResult;
+    /**
+     * If the category is in the non_taxable_categories list, immediately set
+     * tax_code to 0 with the configured reason. Returns true if handled.
+     */
+    private resolveNonTaxableCategory;
+    /**
+     * If category is "communications" and the keyword/memo matches a known
+     * overseas SaaS provider, override tax_code to 0 (対象外).
+     *
+     * Exception: if the memo contains a JCT indicator (= the overseas provider
+     * is charging Japanese consumption tax via an invoice), keep tax_code 2.
+     */
+    resolveOverseasSaasTaxCode(tx: Transaction, classification: ClassificationResult, out: TaxRuleResult): void;
+    /**
+     * If category is "advertising" and the keyword/memo matches a known
+     * overseas ad platform, override tax_code to 0 (対象外).
+     *
+     * Google Ads, Meta Ads etc. are invoiced from overseas entities.
+     * Same JCT exception as overseas SaaS.
+     */
+    resolveOverseasAdTaxCode(tx: Transaction, classification: ClassificationResult, out: TaxRuleResult): void;
+    /**
+     * If category is "consumables" or "supplies" and the amount is significant,
+     * determine the correct asset capitalisation tier and add warnings.
+     */
+    resolveAssetCapitalization(tx: Transaction, classification: ClassificationResult, out: TaxRuleResult): void;
+    /**
+     * For professional_fee category, calculate informational withholding tax
+     * (源泉徴収税額) to help tax accountants verify freee entries.
+     */
+    calculateWithholding(tx: Transaction, classification: ClassificationResult, out: TaxRuleResult): void;
+    /**
+     * Determine the correct consumption tax rate based on category and keywords.
+     *
+     * Decision tree (Tier 2 expanded):
+     * - overseas SaaS/ads -> 0% (handled earlier)
+     * - non-taxable categories -> 0% (handled by resolveNonTaxableCategory)
+     * - books_magazines + newspaper keyword -> 8% (軽減税率)
+     * - meeting_meal + takeout/delivery -> 8%
+     * - meeting_meal + food purchase (convenience store) -> 8%
+     * - meeting_meal + catering with service -> 10%
+     * - meeting_meal (default dine-in) -> 10%
+     * - rent + residential keyword -> 0% (非課税)
+     */
+    resolveConsumptionTaxRate(tx: Transaction, classification: ClassificationResult, out: TaxRuleResult): void;
+    /**
+     * Detailed meeting_meal consumption tax resolution (Tier 2).
+     *
+     * Priority order:
+     * 1. Catering with service (配膳あり) -> 10% standard
+     * 2. Takeout / delivery -> 8% reduced
+     * 3. Food purchase (convenience store, supermarket) -> 8% reduced
+     * 4. Default dine-in -> 10% standard
+     */
+    private resolveMeetingMealTaxRate;
+    /**
+     * Validate an invoice registration number and calculate the transitional
+     * period deduction rate.
+     *
+     * @param registrationNumber  T + 13 digits (e.g. "T1234567890123")
+     * @param txDate              Transaction date (YYYY-MM-DD) for period lookup
+     * @param taxAmount           Consumption tax amount for deduction calculation
+     */
+    checkInvoice(registrationNumber: string | undefined, txDate: string, taxAmount?: number): InvoiceCheckResult;
+    /**
+     * Validate T + 13 digits format.
+     */
+    validateRegistrationNumber(num: string | undefined): boolean;
+    /**
+     * Get the transitional period deduction rate for a given date.
+     */
+    getTransitionalPeriod(txDate: string): {
+        deduction_rate: number;
+        label: string;
+    };
+    /**
+     * Check if the memo or matched keyword matches any provider in the list.
+     */
+    private matchesProvider;
+    getVersion(): string;
+}
+//# sourceMappingURL=tax-rule-engine.d.ts.map