@moatless/bookkeeping 0.1.0

package/dist/types/discarded-item.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Error information from a failed deletion attempt
+ */
+export interface DeletionError {
+    /** When the deletion was attempted */
+    attemptedAt: string;
+    /** HTTP status code from the API */
+    statusCode?: number;
+    /** Error code from the integration (e.g., Fortnox error code) */
+    errorCode?: number | string;
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * Represents a discarded inbox item that should be removed from the source integration.
+ * Stored in inbox/discarded.json in the organization's storage.
+ */
+export interface DiscardedItem {
+    /** Directory name in the inbox folder */
+    dir: string;
+    /** ID of the item in the source integration (e.g., Fortnox file ID) */
+    sourceId: string;
+    /** Which integration the item came from */
+    sourceIntegration: "fortnox" | "bokio";
+    /** Error from the last failed deletion attempt (if any) */
+    lastDeletionError?: DeletionError;
+    /** Number of failed deletion attempts */
+    deletionAttempts?: number;
+}

package/dist/types/discarded-item.js

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

package/dist/types/document.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Exported document format - optimized for Git-based workflow
+ * Using camelCase for TypeScript compatibility
+ *
+ * This format is designed for human-readable YAML exports stored in Git repositories.
+ * It removes database-specific metadata (UUIDs, timestamps, sync data) and focuses
+ * on the document content and parsed data. Git provides version history and timestamps.
+ */
+/**
+ * Monetary amount with currency
+ * Amount is stored as a string to preserve precision
+ */
+export interface DocumentMoneyAmount {
+    amount: string;
+    currency: string;
+}
+/**
+ * Tax detail line item
+ */
+export interface TaxDetail {
+    rate: number;
+    amount: string;
+    description?: string;
+}
+/**
+ * Document kind/type
+ */
+export type DocumentKind = "RECEIPT" | "SUPPLIER_INVOICE" | "CUSTOMER_INVOICE" | "TRAKTAMENTE" | "OTHER";
+/**
+ * Document status in workflow
+ */
+export type DocumentStatus = "DRAFT" | "REVIEWED" | "READY_TO_EXPORT" | "EXPORTED" | "ERROR" | "DISCARDED" | "POSTED";
+/**
+ * Complete exported document with parsed data
+ *
+ * Git-based workflow assumptions:
+ * - Creation/update timestamps: Use git log
+ * - Author information: Use git commit author
+ * - File location: Same directory as YAML file
+ * - Organization context: Repository structure
+ */
+export interface Document {
+    kind: DocumentKind;
+    status: DocumentStatus;
+    fileName: string;
+    mimeType: string;
+    documentDate?: string;
+    documentNumber?: string;
+    description?: string;
+    counterparty?: string;
+    totalAmount?: DocumentMoneyAmount;
+    totalTaxAmount?: DocumentMoneyAmount;
+    subTotal?: DocumentMoneyAmount;
+    taxDetails?: TaxDetail[];
+    dueDate?: string;
+    currencyRate?: number;
+    vendorTaxId?: string;
+    interpretationError?: string;
+    sourceIntegration?: "fortnox" | "bokio";
+    sourceId?: string;
+    uploadedAt?: string;
+    interpretedAt?: string;
+}

package/dist/types/document.js

@@ -0,0 +1,9 @@
+/**
+ * Exported document format - optimized for Git-based workflow
+ * Using camelCase for TypeScript compatibility
+ *
+ * This format is designed for human-readable YAML exports stored in Git repositories.
+ * It removes database-specific metadata (UUIDs, timestamps, sync data) and focuses
+ * on the document content and parsed data. Git provides version history and timestamps.
+ */
+export {};

package/dist/types/exported-document.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Exported document format - optimized for Git-based workflow
+ * Using camelCase for TypeScript compatibility
+ *
+ * This format is designed for human-readable YAML exports stored in Git repositories.
+ * It removes database-specific metadata (UUIDs, timestamps, sync data) and focuses
+ * on the document content and parsed data. Git provides version history and timestamps.
+ */
+/**
+ * Monetary amount with currency
+ * Amount is stored as a string to preserve precision
+ */
+export interface ExportedMoneyAmount {
+    amount: string;
+    currency: string;
+}
+/**
+ * Tax detail line item
+ */
+export interface ExportedTaxDetail {
+    rate: number;
+    amount: string;
+    description?: string;
+}
+/**
+ * Document kind/type
+ */
+export type DocumentKind = "RECEIPT" | "SUPPLIER_INVOICE" | "CUSTOMER_INVOICE" | "TRAKTAMENTE" | "OTHER";
+/**
+ * Document status in workflow
+ */
+export type DocumentStatus = "DRAFT" | "REVIEWED" | "READY_TO_EXPORT" | "EXPORTED" | "ERROR" | "DISCARDED" | "POSTED";
+/**
+ * Complete exported document with parsed data
+ *
+ * Git-based workflow assumptions:
+ * - Creation/update timestamps: Use git log
+ * - Author information: Use git commit author
+ * - File location: Same directory as YAML file
+ * - Organization context: Repository structure
+ */
+export interface ExportedDocument {
+    kind: DocumentKind;
+    status: DocumentStatus;
+    fileName: string;
+    mimeType: string;
+    documentDate?: string;
+    documentNumber?: string;
+    description?: string;
+    counterparty?: string;
+    totalAmount?: ExportedMoneyAmount;
+    totalTaxAmount?: ExportedMoneyAmount;
+    subTotal?: ExportedMoneyAmount;
+    taxDetails?: ExportedTaxDetail[];
+    dueDate?: string;
+    currencyRate?: number;
+    vendorTaxId?: string;
+    interpretationError?: string;
+    sourceIntegration?: "fortnox" | "bokio";
+    sourceId?: string;
+}

package/dist/types/exported-document.js

@@ -0,0 +1,9 @@
+/**
+ * Exported document format - optimized for Git-based workflow
+ * Using camelCase for TypeScript compatibility
+ *
+ * This format is designed for human-readable YAML exports stored in Git repositories.
+ * It removes database-specific metadata (UUIDs, timestamps, sync data) and focuses
+ * on the document content and parsed data. Git provides version history and timestamps.
+ */
+export {};

package/dist/types/exported-fiscal-year.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Exported fiscal year structure for Git storage (YAML format)
+ */
+export interface ExportedFiscalYear {
+    name: string;
+    startDate: string;
+    endDate: string;
+    status: "OPEN" | "CLOSED";
+    externalId?: string;
+}

package/dist/types/exported-fiscal-year.js

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

package/dist/types/exported-inbox-document.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Exported inbox document format - extends ExportedDocument for Git workflow
+ *
+ * Inbox documents are documents that haven't been fully processed yet:
+ * - Not yet linked to a journal entry (journal_entry_id IS NULL), OR
+ * - Linked to a DRAFT journal entry (not yet posted)
+ *
+ * This format includes source tracking and optional suggested journal entries.
+ */
+import type { ExportedDocument } from "./exported-document";
+export interface ExportedInboxDocument extends ExportedDocument {
+    uploadedAt?: string;
+    interpretedAt?: string;
+}

package/dist/types/exported-inbox-document.js

@@ -0,0 +1,10 @@
+/**
+ * Exported inbox document format - extends ExportedDocument for Git workflow
+ *
+ * Inbox documents are documents that haven't been fully processed yet:
+ * - Not yet linked to a journal entry (journal_entry_id IS NULL), OR
+ * - Linked to a DRAFT journal entry (not yet posted)
+ *
+ * This format includes source tracking and optional suggested journal entries.
+ */
+export {};

package/dist/types/fiscal-year.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Exported fiscal year structure for Git storage (YAML format)
+ */
+export interface FiscalYear {
+    name: string;
+    startDate: string;
+    endDate: string;
+    status: "OPEN" | "CLOSED";
+    externalId?: string;
+}

package/dist/types/fiscal-year.js

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

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+export type ApiResponse = {
+    message: string;
+    success: true;
+};
+export * from "./journal-entry";
+export * from "./document";
+export type { Document as InboxDocument } from "./document";
+export * from "./fiscal-year";
+export * from "./ledger-account";
+export * from "./discarded-item";

package/dist/types/index.js

@@ -0,0 +1,10 @@
+// Journal entry types (used across Git YAML, API, and client)
+export * from "./journal-entry";
+// Document types
+export * from "./document";
+// Fiscal year
+export * from "./fiscal-year";
+// Ledger account
+export * from "./ledger-account";
+// Discarded items
+export * from "./discarded-item";

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

@@ -0,0 +1,79 @@
+/**
+ * Unified Journal Entry types
+ *
+ * These types are used throughout the stack:
+ * - Git YAML storage (entry.yaml files)
+ * - Server API responses
+ * - Client state
+ *
+ * All monetary amounts use NUMBER type (not strings).
+ * All field names use camelCase.
+ */
+/**
+ * Monetary amount with currency
+ */
+export interface MoneyAmount {
+    amount: number;
+    currency: string;
+    originalAmount?: number;
+    originalCurrency?: string;
+}
+/**
+ * Single line in a journal entry
+ */
+export interface JournalLine {
+    lineNumber: number;
+    account: string;
+    debit: MoneyAmount;
+    credit: MoneyAmount;
+    memo?: string;
+    taxCode?: string;
+    costCenter?: string;
+    /** Populated by API when account details are available */
+    ledgerAccountName?: string;
+}
+/**
+ * Journal entry series
+ * Different series are used for different transaction types:
+ * - A: General/miscellaneous transactions
+ * - B: Customer invoices (sales)
+ * - C: Customer payments (collections)
+ * - D: Supplier invoices (purchases)
+ * - E: Supplier payments (disbursements)
+ * - I: Period-end accruals and adjustments
+ * - M: Monthly/quarterly tax reporting
+ */
+export type JournalEntrySeries = "A" | "B" | "C" | "D" | "E" | "I" | "M";
+/**
+ * Journal entry status
+ */
+export type JournalEntryStatus = "DRAFT" | "POSTED";
+/**
+ * Complete journal entry
+ */
+export interface JournalEntry {
+    /** Populated by API (derived from directory name), not stored in YAML */
+    id?: string;
+    series?: JournalEntrySeries;
+    entryNumber: number;
+    entryDate: string;
+    description: string;
+    status: JournalEntryStatus;
+    currency: string;
+    externalId?: string;
+    totalDebit: MoneyAmount;
+    totalCredit: MoneyAmount;
+    lines: JournalLine[];
+    postedAt?: string;
+    errorMessage?: string;
+    postingCheckpoint?: string;
+    voucherNumber?: number;
+    voucherSeriesCode?: string;
+    fortnoxFileId?: string;
+    sourceIntegration?: "fortnox" | "bokio";
+    sourceSyncedAt?: string;
+    /** If this entry is a reversal, the external ID of the entry it reverses */
+    reversingEntryExternalId?: string;
+    /** If this entry was reversed/cancelled, the external ID of the reversing entry */
+    reversedByEntryExternalId?: string;
+}

package/dist/types/journal-entry.js

@@ -0,0 +1,12 @@
+/**
+ * Unified Journal Entry types
+ *
+ * These types are used throughout the stack:
+ * - Git YAML storage (entry.yaml files)
+ * - Server API responses
+ * - Client state
+ *
+ * All monetary amounts use NUMBER type (not strings).
+ * All field names use camelCase.
+ */
+export {};

package/dist/types/ledger-account.d.ts

@@ -0,0 +1,5 @@
+export interface LedgerAccount {
+    code: string;
+    name: string;
+    description?: string;
+}

package/dist/types/ledger-account.js

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

package/dist/utils/file-namer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * File naming utilities for journal entries and fiscal years
+ */
+interface JournalEntryInput {
+    voucher_series_code: string | null;
+    voucher_number: number | null;
+    entry_date: string;
+    description: string | null;
+    id?: string;
+}
+/**
+ * Generate directory name for a journal entry
+ * Format: {series}-{voucher-number}-{entry-date}-{description-truncated}
+ * Examples:
+ * - A-042-2024-01-15-invoice-from-acme-corp
+ * - B-001-2024-12-31-year-end-adjustment
+ * - 042-2024-01-15-purchase-equipment (no series)
+ */
+export declare function journalEntryDirName(entry: JournalEntryInput): string;
+/**
+ * Generate file path for a journal entry
+ * Format: journal-entries/FY-{year}/{entry-dir}/entry.yaml
+ */
+export declare function journalEntryPath(fiscalYear: number, series: string | null, entryNumber: number, entryDate: string, description: string): string;
+/**
+ * Get directory path from entry file path
+ * e.g., "journal-entries/FY-2024/A-042-2024-01-15-description/entry.yaml"
+ *       -> "journal-entries/FY-2024/A-042-2024-01-15-description"
+ */
+export declare function journalEntryDirFromPath(entryPath: string): string;
+/**
+ * Generate directory name for a fiscal year
+ * Format: FY-{year}
+ * Examples:
+ * - FY-2024
+ * - FY-2025
+ */
+export declare function fiscalYearDirName(year: number | {
+    start_date: string;
+}): string;
+/**
+ * Sanitize organization name for use as directory name
+ * Examples:
+ * - "Acme Corp AB" → "acme-corp-ab"
+ * - "Widgets & Gadgets Inc." → "widgets-gadgets-inc"
+ */
+export declare function sanitizeOrgName(name: string): string;
+export {};

package/dist/utils/file-namer.js

@@ -0,0 +1,80 @@
+/**
+ * File naming utilities for journal entries and fiscal years
+ */
+/**
+ * Generate directory name for a journal entry
+ * Format: {series}-{voucher-number}-{entry-date}-{description-truncated}
+ * Examples:
+ * - A-042-2024-01-15-invoice-from-acme-corp
+ * - B-001-2024-12-31-year-end-adjustment
+ * - 042-2024-01-15-purchase-equipment (no series)
+ */
+export function journalEntryDirName(entry) {
+    const series = entry.voucher_series_code || "";
+    const voucher = String(entry.voucher_number || "000").padStart(3, "0");
+    const date = entry.entry_date;
+    const description = slugify(entry.description || entry.id?.slice(0, 8) || "entry");
+    // Build parts array and filter out empty strings
+    const parts = [series, voucher, date, description].filter(Boolean);
+    return parts.join("-");
+}
+/**
+ * Generate file path for a journal entry
+ * Format: journal-entries/FY-{year}/{entry-dir}/entry.yaml
+ */
+export function journalEntryPath(fiscalYear, series, entryNumber, entryDate, description) {
+    const fyDir = fiscalYearDirName(fiscalYear);
+    const entryDir = journalEntryDirName({
+        voucher_series_code: series,
+        voucher_number: entryNumber,
+        entry_date: entryDate,
+        description,
+    });
+    return `journal-entries/${fyDir}/${entryDir}/entry.yaml`;
+}
+/**
+ * Get directory path from entry file path
+ * e.g., "journal-entries/FY-2024/A-042-2024-01-15-description/entry.yaml"
+ *       -> "journal-entries/FY-2024/A-042-2024-01-15-description"
+ */
+export function journalEntryDirFromPath(entryPath) {
+    return entryPath.replace(/\/entry\.yaml$/, "");
+}
+/**
+ * Generate directory name for a fiscal year
+ * Format: FY-{year}
+ * Examples:
+ * - FY-2024
+ * - FY-2025
+ */
+export function fiscalYearDirName(year) {
+    if (typeof year === "number") {
+        return `FY-${year}`;
+    }
+    return `FY-${year.start_date.slice(0, 4)}`;
+}
+/**
+ * Convert text to a URL-friendly slug
+ * - Converts to lowercase
+ * - Removes special characters
+ * - Replaces spaces with hyphens
+ * - Truncates to maxLength
+ */
+function slugify(text, maxLength = 30) {
+    return text
+        .toLowerCase()
+        .slice(0, maxLength)
+        .replace(/[^a-z0-9\s-]/g, "") // Remove special chars
+        .replace(/\s+/g, "-") // Spaces to hyphens
+        .replace(/-+/g, "-") // Collapse multiple hyphens
+        .replace(/^-|-$/g, ""); // Trim hyphens
+}
+/**
+ * Sanitize organization name for use as directory name
+ * Examples:
+ * - "Acme Corp AB" → "acme-corp-ab"
+ * - "Widgets & Gadgets Inc." → "widgets-gadgets-inc"
+ */
+export function sanitizeOrgName(name) {
+    return slugify(name, 50);
+}

package/dist/utils/git.d.ts

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

package/dist/utils/git.js

@@ -0,0 +1,41 @@
+import simpleGit from "simple-git";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+const DEFAULT_GITIGNORE = `# Environment files with secrets
+.env
+.env.*
+
+# CLI cache
+.kvitton/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Editor files
+.vscode/
+.idea/
+*.swp
+`;
+/**
+ * Initialize a new git repository with a .gitignore file
+ */
+export async function initGitRepo(repoPath) {
+    const git = simpleGit(repoPath);
+    await git.init();
+    await fs.writeFile(path.join(repoPath, ".gitignore"), DEFAULT_GITIGNORE);
+}
+/**
+ * Stage all changes and commit with the given message.
+ * Returns true if a commit was made, false if there were no changes to commit.
+ */
+export async function commitAll(repoPath, message) {
+    const git = simpleGit(repoPath);
+    await git.add(".");
+    const status = await git.status();
+    if (status.files.length > 0) {
+        await git.commit(message);
+        return true;
+    }
+    return false;
+}

package/dist/utils/index.d.ts

@@ -0,0 +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 { getAgentsTemplate, renderAgentsTemplate, type RenderAgentsTemplateOptions, } from "./templates";
+export { KVITTON_DIR, getKvittonDir, getTokensDir, getCacheDir, } from "./paths";

package/dist/utils/index.js

@@ -0,0 +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 { getAgentsTemplate, renderAgentsTemplate, } from "./templates";
+export { KVITTON_DIR, getKvittonDir, getTokensDir, getCacheDir, } from "./paths";

package/dist/utils/paths.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The hidden directory used for internal storage (tokens, cache, etc.)
+ * inside the accounting repository.
+ */
+export declare const KVITTON_DIR = ".kvitton";
+/**
+ * Get the base .kvitton directory path for a given working directory.
+ */
+export declare function getKvittonDir(cwd: string): string;
+/**
+ * Get the tokens directory path for storing OAuth tokens.
+ */
+export declare function getTokensDir(cwd: string): string;
+/**
+ * Get the cache directory path for storing cached data (e.g., currency rates).
+ */
+export declare function getCacheDir(cwd: string): string;

package/dist/utils/paths.js

@@ -0,0 +1,24 @@
+import * as path from "node:path";
+/**
+ * The hidden directory used for internal storage (tokens, cache, etc.)
+ * inside the accounting repository.
+ */
+export const KVITTON_DIR = ".kvitton";
+/**
+ * Get the base .kvitton directory path for a given working directory.
+ */
+export function getKvittonDir(cwd) {
+    return path.join(cwd, KVITTON_DIR);
+}
+/**
+ * Get the tokens directory path for storing OAuth tokens.
+ */
+export function getTokensDir(cwd) {
+    return path.join(cwd, KVITTON_DIR, "tokens");
+}
+/**
+ * Get the cache directory path for storing cached data (e.g., currency rates).
+ */
+export function getCacheDir(cwd) {
+    return path.join(cwd, KVITTON_DIR, "cache");
+}

package/dist/utils/retry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Retry utility with exponential backoff
+ */
+export interface RetryOptions {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    shouldRetry?: (error: unknown) => boolean;
+    onRetry?: (attempt: number, error: unknown, delayMs: number) => void;
+}
+/**
+ * Default check for rate limit errors
+ */
+export declare function isRateLimitError(error: unknown): boolean;
+/**
+ * Execute a function with retry logic and exponential backoff
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/utils/retry.js

@@ -0,0 +1,48 @@
+/**
+ * Retry utility with exponential backoff
+ */
+/**
+ * Default check for rate limit errors
+ */
+export function isRateLimitError(error) {
+    if (error && typeof error === "object") {
+        const err = error;
+        if (err.code === "RATE_LIMIT_EXCEEDED")
+            return true;
+        if (err.statusCode === 429)
+            return true;
+    }
+    return false;
+}
+/**
+ * Execute a function with retry logic and exponential backoff
+ */
+export async function withRetry(fn, options = {}) {
+    const { maxRetries = 3, baseDelayMs = 2000, shouldRetry = isRateLimitError, onRetry, } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            // Check if we should retry
+            if (attempt < maxRetries && shouldRetry(err)) {
+                // Exponential backoff: 2s, 4s, 8s, ...
+                const delayMs = baseDelayMs * 2 ** attempt;
+                onRetry?.(attempt + 1, err, delayMs);
+                await sleep(delayMs);
+                continue;
+            }
+            // Don't retry - rethrow
+            throw err;
+        }
+    }
+    throw lastError;
+}
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}