@moatless/bookkeeping 0.1.0

package/dist/utils/templates.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Get the raw AGENTS.md template with placeholders
+ */
+export declare function getAgentsTemplate(): string;
+export interface RenderAgentsTemplateOptions {
+    companyName: string;
+    provider: "Bokio" | "Fortnox";
+}
+/**
+ * Render the AGENTS.md template with variable substitution
+ */
+export declare function renderAgentsTemplate(options: RenderAgentsTemplateOptions): string;

package/dist/utils/templates.js

@@ -0,0 +1,222 @@
+// Template inlined as string to ensure it's bundled properly
+const AGENTS_TEMPLATE = `# AGENTS.md
+
+This is an accounting data repository for {{COMPANY_NAME}} (Swedish company), storing financial records, journal entries, and documents. It integrates with {{PROVIDER}} (Swedish accounting software) for document management.
+
+## Repository Structure
+
+\`\`\`
+/
+├── accounts.yaml           # Swedish chart of accounts (account codes 1000-9999)
+├── journal-entries/        # Main accounting data organized by fiscal year
+│   └── FY-YYYY/           # Fiscal year folders (FY-2014 through FY-2026)
+│       ├── _fiscal-year.yaml
+│       └── [SERIES]-[NUM]-[DATE]-[DESC]/
+│           ├── entry.yaml
+│           └── *.pdf      # Supporting documents
+│
+├── inbox/                 # Raw incoming documents (no entry yet)
+│   └── [DATE]-[NAME]/
+│       ├── documents.yaml
+│       └── *.pdf
+└── drafts/                # Documents with entries, ready to post
+    └── [DATE]-[NAME]/     # e.g., "2025-12-24-anthropic"
+        ├── documents.yaml
+        ├── entry.yaml
+        └── *.pdf
+\`\`\`
+
+## CLI Commands
+
+Use the \`npx ledgit-cli\` CLI to interact with this repository:
+
+\`\`\`bash
+# Sync data from provider
+npx ledgit-cli sync-journal          # Sync journal entries from accounting provider
+npx ledgit-cli sync-inbox            # Download inbox files from accounting provider
+npx ledgit-cli company-info          # Display company information
+
+# Create journal entries
+npx ledgit-cli create-entry --path <inbox-dir-or-file> \\
+  --tax-code <code> --base-account <acc> --balancing-account <acc> \\
+  --series <A-K> --entry-number <num>
+
+# For raw files (not from inbox), also provide:
+#   --description "Vendor name" --document-date 2025-01-15 --amount 1234.50
+
+# Manage inbox
+npx ledgit-cli discard <inbox-directory>   # Remove item, mark for deletion from provider
+npx ledgit-cli parse-pdf -f <file.pdf>     # Extract text from PDF (for analysis)
+
+# Currency conversion
+npx ledgit-cli convert-currency --amount <num> --currency <code> [--date YYYY-MM-DD]
+  # Converts foreign currency to SEK using Riksbank exchange rates
+  # Caches rates locally for efficiency
+
+# Generate journal entry lines (alternative to create-entry for adding lines)
+npx ledgit-cli generate-lines --inbox-dir <path> \\
+  --tax-code <code> --base-amount <num> --base-account <acc> \\
+  --balancing-account <acc> [--memo "description"] [--currency USD]
+
+# List available tax codes
+npx ledgit-cli list-tax-codes
+
+# Update instructions
+npx ledgit-cli update                # Update AGENTS.md to latest version
+\`\`\`
+
+**Currency Conversion:** Both \`create-entry\` and \`generate-lines\` automatically convert to SEK when \`--currency\` is different from SEK, using Riksbank exchange rates for the entry date.
+
+## Workflow Overview
+
+\`\`\`
+inbox/ → (create-entry) → drafts/ → (user confirms) → journal-entries/ → (sync-journal) → Provider
+\`\`\`
+
+## Bookkeeping New Entries
+
+**Important:** Always ask the user for clarification if anything is unclear about the transaction before creating an entry.
+
+To create a journal entry from an inbox document:
+
+1. **Read the document** - Use \`npx ledgit-cli parse-pdf\` for PDFs to understand the content
+2. **Update documents.yaml** - After parsing, populate missing metadata in \`documents.yaml\`:
+   - \`documentDate\`: Invoice/receipt date (YYYY-MM-DD)
+   - \`description\`: Vendor or document name
+   - \`totalAmount\`: With \`amount\` (string) and \`currency\` (e.g., EUR, SEK)
+3. **Look for similar entries** - Search \`journal-entries/\` and \`drafts/\` for entries from the same vendor or similar transaction types to learn which accounts and tax codes were used previously
+4. **Check accounts** - Review \`accounts.yaml\` for appropriate expense/revenue accounts
+5. **Determine tax code** - Based on vendor location and transaction type (see Tax Codes below). Explain your reasoning and describe the tax code meaning to the user
+6. **Ask for confirmation** - Before creating, confirm with the user: vendor, amount, accounts (with names), and tax code (with description)
+7. **Create entry** - Run \`npx ledgit-cli create-entry\` with the appropriate parameters
+8. **Files moved to drafts** - The inbox item is automatically moved to \`drafts/\` with \`entry.yaml\`
+
+To discard unwanted inbox items:
+\`\`\`bash
+npx ledgit-cli discard inbox/2025-01-15-spam-document
+\`\`\`
+This removes the directory and marks the item for deletion from the provider on next sync.
+
+## Posting Entries
+
+**Important:** Moving entries to \`journal-entries/\` posts them to the real ledger. Always confirm with the user before posting.
+
+When the user confirms draft entries are ready to post:
+
+1. **Determine entry number** - Check existing entries in \`journal-entries/FY-YYYY/\` for the series to find the next available number
+2. **Move to journal-entries** - Rename the draft directory to the proper format:
+   \`\`\`
+   drafts/2025-01-15-anthropic/
+     → journal-entries/FY-2025/A-042-2025-01-15-anthropic/
+   \`\`\`
+   Format: \`{SERIES}-{NUM}-{DATE}-{DESC}/\`
+3. **Update entry.yaml** - Ensure \`entryNumber\` matches the directory and \`status\` is set appropriately
+4. **Sync to provider** - Run \`npx ledgit-cli sync-journal\` to post the entries to {{PROVIDER}}
+
+## Tax Codes
+
+### Common Tax Code Patterns
+
+| Scenario | Tax Code | Accounts |
+|----------|----------|----------|
+| Domestic purchase 25% | \`SE_VAT_25_PURCHASE_DOMESTIC\` | Expense + 2641 + 2440 |
+| Domestic purchase 12% | \`SE_VAT_12_PURCHASE_DOMESTIC\` | Expense + 2641 + 2440 |
+| Non-EU services (US SaaS) | \`SE_VAT_25_PURCHASE_NON_EU_SERVICES_RC\` | 5422 + 2645 + 2614 + 2820 |
+| EU services | \`SE_VAT_25_PURCHASE_EU_SERVICES_RC\` | Expense + 2645 + 2614 + 2440 |
+| Exempt purchase | \`SE_VAT_EXEMPT_PURCHASE\` | Expense + balancing |
+
+**Notes:**
+- \`RC\` = Reverse Charge (buyer reports VAT instead of seller)
+- Use \`--list-tax-codes\` to see all available codes with descriptions
+- Account 2641 = Incoming VAT (domestic), 2645 = Incoming VAT (reverse charge)
+- Account 2614 = Outgoing VAT (reverse charge)
+
+## Entities
+
+### Journal Entry (entry.yaml)
+
+\`\`\`yaml
+series: A              # A=Admin, B=Customer invoices, C=Customer payments,
+                       # D=Supplier invoices, E=Supplier payments, K=Salary
+entryNumber: 1
+entryDate: 2024-01-03
+description: Transaction description
+status: POSTED         # or DRAFT
+currency: SEK
+lines:
+  - account: "1930"    # Account code from accounts.yaml
+    debit: 1000.00     # or credit:
+    memo: Account description
+\`\`\`
+
+### Document Metadata (documents.yaml)
+
+One entry can have multiple supporting documents (e.g., invoice + receipt, contract + amendment).
+
+\`\`\`yaml
+- fileName: invoice.pdf
+  mimeType: application/pdf
+  sourceIntegration: {{PROVIDER_LOWER}}
+  sourceId: UUID-1
+  description: Vendor invoice
+  documentDate: 2024-01-15
+  totalAmount:
+    amount: "1250.00"
+    currency: SEK
+- fileName: receipt.pdf
+  mimeType: application/pdf
+  sourceIntegration: {{PROVIDER_LOWER}}
+  sourceId: UUID-2
+  description: Payment receipt
+  documentDate: 2024-01-16
+\`\`\`
+
+### Fiscal Year (_fiscal-year.yaml)
+
+\`\`\`yaml
+name: FY 2024
+startDate: 2024-01-01
+endDate: 2024-12-31
+status: OPEN
+externalId: "12"       # Provider reference
+\`\`\`
+
+## Account Codes
+
+Swedish BAS account codes are organized by ranges:
+
+- **1xxx** - Assets (Tillgångar)
+- **2xxx** - Liabilities & Equity (Skulder och eget kapital)
+- **3xxx** - Revenue (Intäkter)
+- **4xxx** - Cost of goods sold (Inköp)
+- **5xxx-6xxx** - Operating expenses (Kostnader)
+- **7xxx** - Personnel costs (Personalkostnader)
+- **8xxx** - Financial items (Finansiella poster)
+- **9xxx** - Year-end allocations (Bokslutsdispositioner)
+
+Common accounts:
+- \`1930\` - Business bank account
+- \`2440\` - Supplier payables
+- \`2610\` - Outgoing VAT 25%
+- \`2640\` - Incoming VAT
+- \`2820\` - Short-term liabilities (credit card, etc.)
+- \`4000\` - Cost of goods sold
+- \`5420\` - Software and IT services
+- \`6570\` - Bank charges
+`;
+/**
+ * Get the raw AGENTS.md template with placeholders
+ */
+export function getAgentsTemplate() {
+    return AGENTS_TEMPLATE;
+}
+/**
+ * Render the AGENTS.md template with variable substitution
+ */
+export function renderAgentsTemplate(options) {
+    const template = getAgentsTemplate();
+    return template
+        .replace(/\{\{COMPANY_NAME\}\}/g, options.companyName)
+        .replace(/\{\{PROVIDER\}\}/g, options.provider)
+        .replace(/\{\{PROVIDER_LOWER\}\}/g, options.provider.toLowerCase());
+}

package/dist/utils/yaml.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parse YAML string to object
+ */
+export declare function parseYaml<T = unknown>(yaml: string): T;
+/**
+ * Convert data to YAML format with special handling for:
+ * - Monetary values (Json type: {amount, currency})
+ * - Enums (direct string values)
+ * - Nulls (omitted for cleaner output)
+ * - Arrays and nested objects
+ */
+export declare function toYaml(data: unknown): string;

package/dist/utils/yaml.js

@@ -0,0 +1,47 @@
+import YAML from "yaml";
+/**
+ * Parse YAML string to object
+ */
+export function parseYaml(yaml) {
+    return YAML.parse(yaml);
+}
+/**
+ * Convert data to YAML format with special handling for:
+ * - Monetary values (Json type: {amount, currency})
+ * - Enums (direct string values)
+ * - Nulls (omitted for cleaner output)
+ * - Arrays and nested objects
+ */
+export function toYaml(data) {
+    // Remove null values for cleaner output
+    const cleanData = removeNulls(data);
+    return YAML.stringify(cleanData, {
+        indent: 2,
+        lineWidth: 120,
+        minContentWidth: 0,
+        doubleQuotedAsJSON: true,
+    });
+}
+/**
+ * Recursively remove null values from objects and arrays
+ * This produces cleaner YAML output by omitting null fields
+ */
+function removeNulls(obj) {
+    if (obj === null || obj === undefined) {
+        return undefined;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(removeNulls).filter((item) => item !== undefined);
+    }
+    if (typeof obj === "object" && obj !== null) {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const cleanValue = removeNulls(value);
+            if (cleanValue !== undefined) {
+                result[key] = cleanValue;
+            }
+        }
+        return result;
+    }
+    return obj;
+}

package/dist/yaml/entry-helpers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * YAML helper functions for reading, updating, and validating journal entry files
+ * Used by CLI tools
+ */
+import type { JournalEntry, Document } from "../types";
+import type { JournalLineInput } from "../accounting";
+/**
+ * Read and parse entry.yaml file
+ */
+export declare function readEntryYaml(filePath: string): Promise<JournalEntry>;
+interface DocumentMetadata {
+    fileName: string;
+    mimeType?: string;
+    sourceIntegration?: string;
+    sourceId?: string;
+}
+/**
+ * Read and parse documents.yaml file (list format)
+ */
+export declare function readDocumentsYaml(filePath: string): Promise<DocumentMetadata[]>;
+/**
+ * @deprecated Use readDocumentsYaml instead
+ * Read and parse document.yaml file (legacy single object format)
+ */
+export declare function readDocumentYaml(filePath: string): Promise<Document>;
+/**
+ * Write entry to entry.yaml file
+ */
+export declare function writeEntryYaml(filePath: string, entry: JournalEntry): Promise<void>;
+/**
+ * Update entry with new lines (appending and renumbering)
+ */
+export declare function appendLinesToEntry(entryPath: string, newLines: JournalLineInput[], totals: {
+    totalDebit: number;
+    totalCredit: number;
+}): Promise<void>;
+/**
+ * Read and parse accounts.yaml file
+ */
+export declare function readAccountsYaml(filePath: string): Promise<{
+    code: string;
+    name: string;
+}[]>;
+/**
+ * Validate that account code exists in accounts list
+ */
+export declare function validateAccountExists(accountCode: string, accounts: Array<{
+    code: string;
+}>): boolean;
+/**
+ * Get account name by code
+ */
+export declare function getAccountName(accountCode: string, accounts: Array<{
+    code: string;
+    name: string;
+}>): string | undefined;
+export {};

package/dist/yaml/entry-helpers.js

@@ -0,0 +1,125 @@
+/**
+ * YAML helper functions for reading, updating, and validating journal entry files
+ * Used by CLI tools
+ */
+import * as fs from "node:fs/promises";
+import { parseYaml, toYaml } from "./yaml-serializer";
+/**
+ * Read and parse entry.yaml file
+ */
+export async function readEntryYaml(filePath) {
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        return parseYaml(content);
+    }
+    catch (err) {
+        throw new Error(`Failed to read entry.yaml at ${filePath}: ${err}`);
+    }
+}
+/**
+ * Read and parse documents.yaml file (list format)
+ */
+export async function readDocumentsYaml(filePath) {
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        return parseYaml(content) || [];
+    }
+    catch (err) {
+        throw new Error(`Failed to read documents.yaml at ${filePath}: ${err}`);
+    }
+}
+/**
+ * @deprecated Use readDocumentsYaml instead
+ * Read and parse document.yaml file (legacy single object format)
+ */
+export async function readDocumentYaml(filePath) {
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        return parseYaml(content);
+    }
+    catch (err) {
+        throw new Error(`Failed to read document.yaml at ${filePath}: ${err}`);
+    }
+}
+/**
+ * Write entry to entry.yaml file
+ */
+export async function writeEntryYaml(filePath, entry) {
+    try {
+        const yaml = toYaml(entry);
+        await fs.writeFile(filePath, yaml, "utf-8");
+    }
+    catch (err) {
+        throw new Error(`Failed to write entry.yaml at ${filePath}: ${err}`);
+    }
+}
+/**
+ * Update entry with new lines (appending and renumbering)
+ */
+export async function appendLinesToEntry(entryPath, newLines, totals) {
+    // Read existing entry
+    const entry = await readEntryYaml(entryPath);
+    // Combine existing and new lines
+    const allLines = [...(entry.lines || [])];
+    // Append new lines with proper formatting
+    for (const newLine of newLines) {
+        allLines.push({
+            lineNumber: newLine.line_number,
+            account: newLine.ledger_account_code,
+            debit: {
+                amount: newLine.debit || 0,
+                currency: "SEK",
+            },
+            credit: {
+                amount: newLine.credit || 0,
+                currency: "SEK",
+            },
+            ...(newLine.memo && { memo: newLine.memo }),
+            ...(newLine.tax_code && { taxCode: newLine.tax_code }),
+            ...(newLine.cost_center_code && {
+                costCenter: newLine.cost_center_code,
+            }),
+        });
+    }
+    // Renumber all lines sequentially
+    allLines.forEach((line, index) => {
+        line.lineNumber = index + 1;
+    });
+    // Update entry
+    entry.lines = allLines;
+    entry.totalDebit = {
+        amount: totals.totalDebit,
+        currency: "SEK",
+    };
+    entry.totalCredit = {
+        amount: totals.totalCredit,
+        currency: "SEK",
+    };
+    // Write back
+    await writeEntryYaml(entryPath, entry);
+}
+/**
+ * Read and parse accounts.yaml file
+ */
+export async function readAccountsYaml(filePath) {
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        const data = parseYaml(content);
+        return data.accounts || [];
+    }
+    catch (err) {
+        throw new Error(`Failed to read accounts.yaml at ${filePath}: ${err}`);
+    }
+}
+/**
+ * Validate that account code exists in accounts list
+ */
+export function validateAccountExists(accountCode, accounts) {
+    return accounts.some((account) => account.code === accountCode);
+}
+/**
+ * Get account name by code
+ */
+export function getAccountName(accountCode, accounts) {
+    return accounts.find((account) => account.code === accountCode)?.name;
+}

package/dist/yaml/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./yaml-serializer";
+export * from "./entry-helpers";

package/dist/yaml/index.js

@@ -0,0 +1,2 @@
+export * from "./yaml-serializer";
+export * from "./entry-helpers";

package/dist/yaml/yaml-serializer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Parse YAML string to object
+ */
+export declare function parseYaml<T = unknown>(yaml: string): T;
+/**
+ * Convert data to YAML format with special handling for:
+ * - Monetary values (Json type: {amount, currency})
+ * - Enums (direct string values)
+ * - Nulls (omitted for cleaner output)
+ * - Arrays and nested objects
+ */
+export declare function toYaml(data: unknown): string;
+/**
+ * Convert a single object to YAML
+ */
+export declare function objectToYaml(obj: Record<string, unknown>): string;
+/**
+ * Convert an array of objects to YAML
+ * The output will be a YAML array
+ */
+export declare function arrayToYaml(arr: unknown[]): string;

package/dist/yaml/yaml-serializer.js

@@ -0,0 +1,60 @@
+import YAML from "yaml";
+/**
+ * Parse YAML string to object
+ */
+export function parseYaml(yaml) {
+    return YAML.parse(yaml);
+}
+/**
+ * Convert data to YAML format with special handling for:
+ * - Monetary values (Json type: {amount, currency})
+ * - Enums (direct string values)
+ * - Nulls (omitted for cleaner output)
+ * - Arrays and nested objects
+ */
+export function toYaml(data) {
+    // Remove null values for cleaner output
+    const cleanData = removeNulls(data);
+    return YAML.stringify(cleanData, {
+        indent: 2,
+        lineWidth: 120,
+        minContentWidth: 0,
+        doubleQuotedAsJSON: true,
+    });
+}
+/**
+ * Recursively remove null values from objects and arrays
+ * This produces cleaner YAML output by omitting null fields
+ */
+function removeNulls(obj) {
+    if (obj === null || obj === undefined) {
+        return undefined;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(removeNulls).filter((item) => item !== undefined);
+    }
+    if (typeof obj === "object" && obj !== null) {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const cleanValue = removeNulls(value);
+            if (cleanValue !== undefined) {
+                result[key] = cleanValue;
+            }
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Convert a single object to YAML
+ */
+export function objectToYaml(obj) {
+    return toYaml(obj);
+}
+/**
+ * Convert an array of objects to YAML
+ * The output will be a YAML array
+ */
+export function arrayToYaml(arr) {
+    return toYaml(arr);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "@moatless/bookkeeping",
+	"version": "0.1.0",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/aorwall/ledgit.git",
+		"directory": "packages/bookkeeping"
+	},
+	"main": "dist/index.js",
+	"files": ["dist"],
+	"types": "dist/index.d.ts",
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsc --watch",
+		"type-check": "tsc --noEmit",
+		"test": "bun test",
+		"test:coverage": "bun test --coverage"
+	},
+	"dependencies": {
+		"@moatless/api-client": "workspace:*",
+		"@moatless/fortnox-client": "workspace:*",
+		"@moatless/bokio-client": "workspace:*",
+		"cli-progress": "^3.12.0",
+		"open": "^10.1.0",
+		"simple-git": "^3.22.0",
+		"yaml": "^2.7.1"
+	},
+	"devDependencies": {
+		"@types/cli-progress": "^3.11.6",
+		"@types/node": "^25.0.3",
+		"bun-types": "latest",
+		"typescript": "^5.8.3"
+	}
+}