@moatless/bookkeeping 0.3.0 → 0.4.0

package/dist/services/document-download.d.ts

@@ -1,10 +1,4 @@
 import type { IStorageService } from "../storage/interface";
-export interface DocumentMetadata {
-    fileName: string;
-    mimeType?: string;
-    sourceIntegration: string;
-    sourceId: string;
-}
 export interface DownloadableFile {
     id: string;
     contentType: string;
@@ -33,7 +27,7 @@ export interface DownloadFilesOptions {
     entryDir: string;
     journalEntryId: string;
     downloader: FileDownloader;
-    sourceIntegration: string;
+    sourceIntegration: "fortnox" | "bokio";
 }
 /**
  * Download files for a journal entry and save them to documents.yaml

package/dist/services/document-download.js

@@ -77,8 +77,10 @@ export async function downloadFilesForEntry(options) {
             const filePath = path.join(absoluteDir, filename);
             const buffer = Buffer.from(result.data);
             await fs.writeFile(filePath, buffer);
-            // Add to documents list
+            // Add to documents list (downloaded docs are already POSTED in provider)
             existingDocs.push({
+                kind: "FILE",
+                status: "POSTED",
                 fileName: filename,
                 mimeType: file.contentType || result.contentType,
                 sourceIntegration,

package/dist/services/index.d.ts

@@ -1,6 +1,6 @@
 export { JournalService } from "./journal.service";
 export { syncJournalEntries, type SyncJournalConfig, } from "./journal-sync";
-export { downloadFilesForEntry, getExtensionFromMimeType, type DocumentMetadata, type DownloadableFile, type FileDownloader, type DownloadFilesOptions, } from "./document-download";
+export { downloadFilesForEntry, getExtensionFromMimeType, type DownloadableFile, type FileDownloader, type DownloadFilesOptions, } from "./document-download";
 export { syncFortnoxJournalEntries, syncFortnoxChartOfAccounts, type FortnoxSyncProgress, type FortnoxJournalSyncOptions, type FortnoxJournalSyncResult, } from "./fortnox-journal";
 export { syncFortnoxInbox, type FortnoxInboxSyncProgress, type FortnoxInboxSyncOptions, type FortnoxInboxSyncResult, } from "./fortnox-inbox";
 export { syncBokioJournalEntries, syncBokioChartOfAccounts, type BokioSyncProgress, type BokioJournalSyncOptions, type BokioJournalSyncResult, } from "./bokio-journal";

package/dist/services/journal.service.js

@@ -9,9 +9,18 @@ export class JournalService {
     constructor(storage) {
         this.storage = storage;
     }
-    static getEntryKey(entry) {
-        return (entry.externalId ??
-            `${entry.series ?? ""}-${entry.entryNumber}`);
+    static getEntryKey(entry, entryDir) {
+        // If entry has externalId, use it (synced entries)
+        if (entry.externalId) {
+            return entry.externalId;
+        }
+        // For local entries without externalId, use directory path if available
+        // This prevents collisions when multiple entries have same entry number
+        if (entryDir) {
+            return entryDir;
+        }
+        // Fallback for backward compatibility
+        return `${entry.series ?? ""}-${entry.entryNumber}`;
     }
     /**
      * List all journal entries from a fiscal year
@@ -41,7 +50,7 @@ export class JournalService {
                 try {
                     const { content } = await this.storage.readFile(entryPath);
                     const journalEntry = parseYaml(content);
-                    const key = JournalService.getEntryKey(journalEntry);
+                    const key = JournalService.getEntryKey(journalEntry, dir.path);
                     entriesMap.set(key, {
                         entry: journalEntry,
                         entryPath,
@@ -49,7 +58,14 @@ export class JournalService {
                     });
                 }
                 catch (error) {
-                    console.error(`Failed to read ${entryPath}:`, error);
+                    // Warn about missing/invalid entry.yaml but continue processing other entries
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (message.includes("ENOENT")) {
+                        console.warn(`  Warning: Skipping ${dir.path} - missing entry.yaml`);
+                    }
+                    else {
+                        console.warn(`  Warning: Skipping ${dir.path} - ${message}`);
+                    }
                 }
             }
         }

package/dist/skills/cli-usage.d.ts

@@ -0,0 +1,2 @@
+import type { Skill } from "./types";
+export declare const CLI_USAGE_SKILL: Skill;

package/dist/skills/cli-usage.js

@@ -0,0 +1,283 @@
+export const CLI_USAGE_SKILL = {
+    name: "cli-usage",
+    description: "Quick start guide for ledgit CLI - essential commands and workflow. Use when learning ledgit basics, creating entries, syncing data from accounting providers (Fortnox/Bokio), or managing inbox items. Triggers on tasks involving ledgit setup, repository structure, command usage, or git-based bookkeeping workflow.",
+    content: `# Ledgit CLI - Quick Start Guide
+
+Get started with ledgit, a git-based bookkeeping system for Swedish companies integrating with Fortnox or Bokio.
+
+## What is Ledgit?
+
+Ledgit stores accounting data as YAML files in a git repository, providing:
+- Version control for all financial records
+- Human-readable accounting entries
+- Seamless integration with Swedish accounting providers
+- Git workflow for review and approval
+
+## Repository Structure
+
+\`\`\`
+/
+├── accounts.yaml           # Swedish chart of accounts (BAS codes 1000-9999)
+├── journal-entries/        # Main accounting data organized by fiscal year
+│   └── FY-YYYY/           # Fiscal year folders (FY-2024, FY-2025, etc.)
+│       ├── _fiscal-year.yaml
+│       └── [SERIES]-[NUM]-[DATE]-[DESC]/
+│           ├── entry.yaml  # Journal entry data
+│           └── *.pdf       # Supporting documents
+│
+└── inbox/                  # Raw incoming documents (no entry yet)
+    └── [DATE]-[NAME]/
+        ├── documents.yaml  # Document metadata
+        └── *.pdf           # Files to process
+\`\`\`
+
+## Common Workflow
+
+The typical bookkeeping workflow:
+
+\`\`\`
+inbox/ → (create-entry) → journal-entries/ → (git review) → (sync-journal) → Provider
+\`\`\`
+
+**Steps:**
+1. Run \`ledgit sync-inbox\` to download new documents from provider
+2. Review inbox item (read PDF, check \`documents.yaml\`)
+3. Run \`ledgit create-entry\` with appropriate flags
+4. Review changes with \`git diff\`, commit if correct
+5. Run \`ledgit sync-journal\` to post entry back to provider
+
+**Branching:** When running \`create-entry\` on main branch, a new git branch is automatically created (e.g., \`book/V-189-2025-10-15-anthropic\`). Review, commit, and merge when ready.
+
+## Essential Commands
+
+### Syncing Data
+
+\`\`\`bash
+# Download new inbox documents from provider
+ledgit sync-inbox
+
+# Sync journal entries from provider to local repo
+ledgit sync-journal
+
+# Display company information
+ledgit company-info
+\`\`\`
+
+### Creating Entries
+
+\`\`\`bash
+# Create entry from inbox directory
+ledgit create-entry --path <inbox-dir> \\
+  --tax-code <code> \\
+  --base-account <account> \\
+  --balancing-account <account> \\
+  --series <A-K>
+
+# Example: Create entry for AWS invoice
+ledgit create-entry --path inbox/2025-01-15-aws \\
+  --tax-code SE_VAT_25_PURCHASE_NON_EU_SERVICES_RC \\
+  --base-account 5422 \\
+  --balancing-account 2820 \\
+  --series D
+\`\`\`
+
+**Common flags:**
+- \`--path\` - Path to inbox directory or raw file
+- \`--tax-code\` - Swedish VAT code (see \`ledgit list-tax-codes\`)
+- \`--base-account\` - Expense/revenue account (from \`accounts.yaml\`)
+- \`--balancing-account\` - 2440 (payable), 2820 (credit card), or 1930 (bank)
+- \`--series\` - A=Admin, D=Supplier invoices, E=Supplier payments, etc.
+
+**For raw files** (not from inbox):
+- \`--description "Vendor name"\`
+- \`--document-date 2025-01-15\`
+- \`--amount 1234.50\`
+
+### Currency Conversion
+
+\`\`\`bash
+# Convert foreign currency to SEK (automatic Riksbank rates)
+ledgit convert-currency --amount 100 --currency USD --date 2025-01-15
+
+# When creating entries with foreign currency
+ledgit create-entry --path inbox/2025-01-15-stripe \\
+  --currency USD \\
+  --tax-code SE_VAT_25_PURCHASE_NON_EU_SERVICES_RC \\
+  --base-account 5422 \\
+  --balancing-account 2820 \\
+  --series D
+\`\`\`
+
+Amounts are automatically converted to SEK using Riksbank exchange rates for the entry date. Rates are cached locally for efficiency.
+
+### Managing Inbox
+
+\`\`\`bash
+# Discard unwanted inbox item (marks for deletion from provider)
+ledgit discard inbox/2025-01-15-spam-document
+\`\`\`
+
+### Reference Information
+
+\`\`\`bash
+# List all available Swedish tax codes
+ledgit list-tax-codes
+\`\`\`
+
+## Creating Your First Entry
+
+Step-by-step walkthrough:
+
+### 1. Sync Inbox
+\`\`\`bash
+ledgit sync-inbox
+\`\`\`
+This downloads new documents to \`inbox/\` directories.
+
+### 2. Review Document
+Read the PDF or check \`documents.yaml\` for metadata:
+\`\`\`yaml
+- fileName: invoice.pdf
+  description: Vendor Name
+  documentDate: 2025-01-15
+  totalAmount:
+    amount: "1250.00"
+    currency: SEK
+\`\`\`
+
+### 3. Look for Similar Entries
+Search \`journal-entries/\` for entries from the same vendor to learn which accounts and tax codes were used previously.
+
+### 4. Check Accounts
+Review \`accounts.yaml\` for appropriate expense/revenue accounts. Common examples:
+- 5422 - SaaS/Software
+- 6540 - IT services
+- 6530 - Accounting services
+- 5800 - Travel expenses
+
+### 5. Determine Tax Code
+Based on vendor location and transaction type. **For detailed tax code guidance, run:**
+\`\`\`bash
+ledgit skills swedish-bookkeeping
+\`\`\`
+
+Quick reference:
+- Swedish supplier with VAT → \`SE_VAT_25_PURCHASE_DOMESTIC\`
+- EU services → \`SE_VAT_25_PURCHASE_EU_SERVICES_RC\`
+- Non-EU (US/UK) services → \`SE_VAT_25_PURCHASE_NON_EU_SERVICES_RC\`
+
+### 6. Create Entry
+\`\`\`bash
+ledgit create-entry --path inbox/2025-01-15-vendor \\
+  --tax-code SE_VAT_25_PURCHASE_NON_EU_SERVICES_RC \\
+  --base-account 5422 \\
+  --balancing-account 2820 \\
+  --series D
+\`\`\`
+
+### 7. Review and Sync
+\`\`\`bash
+# Review changes
+git diff
+
+# Commit if correct
+git add .
+git commit -m "Add: Vendor Name invoice"
+
+# Post to provider
+ledgit sync-journal
+\`\`\`
+
+## Skills System
+
+Ledgit includes domain-specific skills with detailed guidance. **Always load the relevant skill before creating unfamiliar entries.**
+
+\`\`\`bash
+# List all available skills
+ledgit skills
+
+# Load specific skill
+ledgit skills swedish-bookkeeping   # VAT, tax codes, BAS accounts
+ledgit skills travel-expenses       # Hotels, flights, per diem
+\`\`\`
+
+**When to use skills:**
+- \`swedish-bookkeeping\` - Creating any journal entry, handling VAT/moms, selecting accounts
+- \`travel-expenses\` - Business travel, hotels, flights, traktamente (per diem), mileage
+
+## Entry File Format
+
+Basic \`entry.yaml\` structure:
+
+\`\`\`yaml
+series: D              # A=Admin, B=Customer invoices, C=Customer payments,
+                       # D=Supplier invoices, E=Supplier payments, K=Salary
+entryNumber: 189
+entryDate: 2025-01-15
+description: Vendor Name - Service description
+status: POSTED         # or DRAFT
+currency: SEK
+lines:
+  - account: "5422"    # Expense account (from accounts.yaml)
+    debit: 1000.00
+    memo: SaaS subscription
+  - account: "2645"    # Input VAT (if reverse charge)
+    debit: 250.00
+    memo: Input VAT reverse charge
+  - account: "2614"    # Output VAT (if reverse charge)
+    credit: 250.00
+    memo: Output VAT reverse charge
+  - account: "2820"    # Balancing account
+    credit: 1000.00
+    memo: Credit card payment
+\`\`\`
+
+**Entry must balance:** Total debits must equal total credits.
+
+## Series Codes
+
+| Series | Swedish | Use |
+|--------|---------|-----|
+| A | Administration | Internal adjustments, corrections |
+| B | Kundfakturor | Customer invoices (sales) |
+| C | Kundbetalningar | Customer payments received |
+| D | Leverantörsfakturor | Supplier invoices (purchases) |
+| E | Leverantörsbetalningar | Supplier payments made |
+| K | Löner | Salary and payroll |
+
+Most common: **D** (supplier invoices) and **E** (supplier payments).
+
+## Account Codes Quick Reference
+
+Swedish BAS account ranges:
+- **1xxx** - Assets (bank accounts, receivables)
+- **2xxx** - Liabilities (payables, VAT, credit cards)
+- **3xxx** - Revenue
+- **4xxx** - Cost of Goods Sold
+- **5-6xxx** - Operating Expenses
+- **7xxx** - Personnel costs
+- **8xxx** - Financial items
+
+See \`accounts.yaml\` in your repository for the company's full chart of accounts.
+
+## Common Balancing Accounts
+
+| Account | Name | Use |
+|---------|------|-----|
+| 1930 | Business checking account | Direct debit/immediate payment |
+| 2440 | Supplier payable | When paying later via bank transfer |
+| 2820 | Credit card | Direct credit card charge |
+
+## Next Steps
+
+1. Run \`ledgit company-info\` to verify your setup
+2. Run \`ledgit sync-inbox\` to get documents
+3. Run \`ledgit skills swedish-bookkeeping\` for detailed tax code guidance
+4. Create your first entry following the workflow above
+5. Review with \`git diff\` and commit when ready
+
+**Questions?** Load the appropriate skill for detailed guidance:
+- General bookkeeping → \`ledgit skills swedish-bookkeeping\`
+- Travel expenses → \`ledgit skills travel-expenses\`
+`,
+};

package/dist/skills/index.d.ts

@@ -1,6 +1,7 @@
 export type { Skill } from "./types";
 export { SWEDISH_BOOKKEEPING_SKILL } from "./swedish-bookkeeping";
 export { TRAVEL_EXPENSES_SKILL } from "./travel-expenses";
+export { CLI_USAGE_SKILL } from "./cli-usage";
 import type { Skill } from "./types";
 export declare const SKILLS: Skill[];
 export declare function listSkills(): Skill[];

package/dist/skills/index.js

@@ -1,5 +1,6 @@
 export { SWEDISH_BOOKKEEPING_SKILL } from "./swedish-bookkeeping";
 export { TRAVEL_EXPENSES_SKILL } from "./travel-expenses";
+export { CLI_USAGE_SKILL } from "./cli-usage";
 import { SWEDISH_BOOKKEEPING_SKILL } from "./swedish-bookkeeping";
 import { TRAVEL_EXPENSES_SKILL } from "./travel-expenses";
 export const SKILLS = [

package/dist/types/document.d.ts

@@ -25,11 +25,11 @@ export interface TaxDetail {
 /**
  * Document kind/type
  */
-export type DocumentKind = "RECEIPT" | "SUPPLIER_INVOICE" | "CUSTOMER_INVOICE" | "TRAKTAMENTE" | "OTHER";
+export type DocumentKind = "RECEIPT" | "SUPPLIER_INVOICE" | "CUSTOMER_INVOICE" | "TRAKTAMENTE" | "FILE" | "OTHER";
 /**
  * Document status in workflow
  */
-export type DocumentStatus = "DRAFT" | "REVIEWED" | "READY_TO_EXPORT" | "EXPORTED" | "ERROR" | "DISCARDED" | "POSTED";
+export type DocumentStatus = "DRAFT" | "REVIEWED" | "READY_TO_EXPORT" | "EXPORTED" | "ERROR" | "DISCARDED" | "POSTED" | "PENDING_CONNECTION";
 /**
  * Complete exported document with parsed data
  *
@@ -60,4 +60,7 @@ export interface Document {
     sourceId?: string;
     uploadedAt?: string;
     interpretedAt?: string;
+    errorMessage?: string;
+    linkedToJournalEntry?: boolean;
+    previousSourceIds?: string[];
 }

package/dist/types/journal-entry.d.ts

@@ -66,7 +66,6 @@ export interface JournalEntry {
     lines: JournalLine[];
     postedAt?: string;
     errorMessage?: string;
-    postingCheckpoint?: string;
     voucherNumber?: number;
     voucherSeriesCode?: string;
     fortnoxFileId?: string;
@@ -76,4 +75,6 @@ export interface JournalEntry {
     reversingEntryExternalId?: string;
     /** If this entry was reversed/cancelled, the external ID of the reversing entry */
     reversedByEntryExternalId?: string;
+    /** The external ID of the fiscal year this entry belongs to (e.g., Fortnox year ID) */
+    fiscalYearExternalId?: number;
 }

package/dist/utils/git.d.ts

@@ -2,8 +2,13 @@
  * Initialize a new git repository with a .gitignore file
  */
 export declare function initGitRepo(repoPath: string): Promise<void>;
+/**
+ * Check if a directory is a git repository
+ */
+export declare function isGitRepo(repoPath: string): Promise<boolean>;
 /**
  * Stage all changes and commit with the given message.
  * Returns true if a commit was made, false if there were no changes to commit.
+ * Returns false if the directory is not a git repository.
  */
 export declare function commitAll(repoPath: string, message: string): Promise<boolean>;

package/dist/utils/git.js

@@ -26,11 +26,29 @@ export async function initGitRepo(repoPath) {
     await git.init();
     await fs.writeFile(path.join(repoPath, ".gitignore"), DEFAULT_GITIGNORE);
 }
+/**
+ * Check if a directory is a git repository
+ */
+export async function isGitRepo(repoPath) {
+    try {
+        const git = simpleGit(repoPath);
+        await git.revparse(["--git-dir"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Stage all changes and commit with the given message.
  * Returns true if a commit was made, false if there were no changes to commit.
+ * Returns false if the directory is not a git repository.
  */
 export async function commitAll(repoPath, message) {
+    // Check if it's a git repository first
+    if (!(await isGitRepo(repoPath))) {
+        return false;
+    }
     const git = simpleGit(repoPath);
     await git.add(".");
     const status = await git.status();

package/dist/utils/index.d.ts

@@ -1,6 +1,6 @@
 export { journalEntryDirName, journalEntryPath, journalEntryDirFromPath, fiscalYearDirName, sanitizeOrgName, } from "./file-namer";
 export { parseYaml, toYaml } from "./yaml";
 export { withRetry, isRateLimitError, type RetryOptions } from "./retry";
-export { initGitRepo, commitAll } from "./git";
+export { initGitRepo, commitAll, isGitRepo } from "./git";
 export { getAgentsTemplate, renderAgentsTemplate, type RenderAgentsTemplateOptions, } from "./templates";
 export { LEDGIT_DIR, getLedgitDir, getTokensDir, getCacheDir, } from "./paths";

package/dist/utils/index.js

@@ -1,6 +1,6 @@
 export { journalEntryDirName, journalEntryPath, journalEntryDirFromPath, fiscalYearDirName, sanitizeOrgName, } from "./file-namer";
 export { parseYaml, toYaml } from "./yaml";
 export { withRetry, isRateLimitError } from "./retry";
-export { initGitRepo, commitAll } from "./git";
+export { initGitRepo, commitAll, isGitRepo } from "./git";
 export { getAgentsTemplate, renderAgentsTemplate, } from "./templates";
 export { LEDGIT_DIR, getLedgitDir, getTokensDir, getCacheDir, } from "./paths";

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

@@ -8,16 +8,10 @@ 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[]>;
+export declare function readDocumentsYaml(filePath: string): Promise<Document[]>;
 /**
  * @deprecated Use readDocumentsYaml instead
  * Read and parse document.yaml file (legacy single object format)
@@ -54,4 +48,3 @@ export declare function getAccountName(accountCode: string, accounts: Array<{
     code: string;
     name: string;
 }>): string | undefined;
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@moatless/bookkeeping",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -23,7 +23,7 @@
 	},
 	"dependencies": {
 		"@moatless/api-client": "^0.1.2",
-		"@moatless/bookkeeping-types": "^0.2.0",
+		"@moatless/bookkeeping-types": "^0.3.0",
 		"@moatless/fortnox-client": "^0.1.2",
 		"@moatless/bokio-client": "^0.1.2",
 		"cli-progress": "^3.12.0",