create-kvitton 0.4.2 → 0.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.js +3342 -228
  2. package/dist/templates/AGENTS.md +94 -12
  3. package/package.json +7 -3
package/dist/templates/AGENTS.md CHANGED
@@ -16,11 +16,11 @@ This is an accounting data repository for {{COMPANY_NAME}} (Swedish company), st
16
16
  │
17
17
  ├── inbox/ # Raw incoming documents (no entry yet)
18
18
  │ └── [DATE]-[NAME]/
19
- │ ├── document.yaml
19
+ │ ├── documents.yaml
20
20
  │ └── *.pdf
21
21
  └── drafts/ # Documents with entries, ready to post
22
- └── [DATE] - [NAME]/ # e.g., "2025-12-24 - anthropic"
23
- ├── document.yaml
22
+ └── [DATE]-[NAME]/ # e.g., "2025-12-24-anthropic"
23
+ ├── documents.yaml
24
24
  ├── entry.yaml
25
25
  └── *.pdf
26
26
  ```
@@ -30,11 +30,87 @@ This is an accounting data repository for {{COMPANY_NAME}} (Swedish company), st
30
30
  Use the `kvitton` CLI to interact with this repository:
31
31
 
32
32
  ```bash
33
- kvitton sync-journal # Sync journal entries from accounting provider
34
- kvitton sync-inbox # Download inbox files from accounting provider
35
- kvitton company-info # Display company information
33
+ # Sync data from provider
34
+ kvitton sync-journal # Sync journal entries from accounting provider
35
+ kvitton sync-inbox # Download inbox files from accounting provider
36
+ kvitton company-info # Display company information
37
+
38
+ # Create journal entries
39
+ kvitton create-entry --path <inbox-dir-or-file> \
40
+ --tax-code <code> --base-account <acc> --balancing-account <acc> \
41
+ --series <A-K> --entry-number <num>
42
+
43
+ # For raw files (not from inbox), also provide:
44
+ # --description "Vendor name" --document-date 2025-01-15 --amount 1234.50
45
+
46
+ # Manage inbox
47
+ kvitton discard <inbox-directory> # Remove item, mark for deletion from provider
48
+ kvitton parse-pdf -f <file.pdf> # Extract text from PDF (for analysis)
49
+
50
+ # List available tax codes
51
+ kvitton create-entry --list-tax-codes
52
+ ```
53
+
54
+ ## Workflow Overview
55
+
56
+ ```
57
+ inbox/ → (create-entry) → drafts/ → (user confirms) → journal-entries/ → (sync-journal) → Provider
36
58
  ```
37
59
 
60
+ ## Bookkeeping New Entries
61
+
62
+ **Important:** Always ask the user for clarification if anything is unclear about the transaction before creating an entry.
63
+
64
+ To create a journal entry from an inbox document:
65
+
66
+ 1. **Read the document** - Use `kvitton parse-pdf` for PDFs to understand the content
67
+ 2. **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
68
+ 3. **Check accounts** - Review `accounts.yaml` for appropriate expense/revenue accounts
69
+ 4. **Determine tax code** - Based on vendor location and transaction type (see Tax Codes below)
70
+ 5. **Ask for confirmation** - Before creating, confirm with the user: vendor, amount, accounts, and tax code
71
+ 6. **Create entry** - Run `kvitton create-entry` with the appropriate parameters
72
+ 7. **Files moved to drafts** - The inbox item is automatically moved to `drafts/` with `entry.yaml`
73
+
74
+ To discard unwanted inbox items:
75
+ ```bash
76
+ kvitton discard inbox/2025-01-15-spam-document
77
+ ```
78
+ This removes the directory and marks the item for deletion from the provider on next sync.
79
+
80
+ ## Posting Entries
81
+
82
+ **Important:** Moving entries to `journal-entries/` posts them to the real ledger. Always confirm with the user before posting.
83
+
84
+ When the user confirms draft entries are ready to post:
85
+
86
+ 1. **Determine entry number** - Check existing entries in `journal-entries/FY-YYYY/` for the series to find the next available number
87
+ 2. **Move to journal-entries** - Rename the draft directory to the proper format:
88
+ ```
89
+ drafts/2025-01-15-anthropic/
90
+ → journal-entries/FY-2025/A-042-2025-01-15-anthropic/
91
+ ```
92
+ Format: `{SERIES}-{NUM}-{DATE}-{DESC}/`
93
+ 3. **Update entry.yaml** - Ensure `entryNumber` matches the directory and `status` is set appropriately
94
+ 4. **Sync to provider** - Run `kvitton sync-journal` to post the entries to {{PROVIDER}}
95
+
96
+ ## Tax Codes
97
+
98
+ ### Common Tax Code Patterns
99
+
100
+ | Scenario | Tax Code | Accounts |
101
+ |----------|----------|----------|
102
+ | Domestic purchase 25% | `SE_VAT_25_PURCHASE_DOMESTIC` | Expense + 2641 + 2440 |
103
+ | Domestic purchase 12% | `SE_VAT_12_PURCHASE_DOMESTIC` | Expense + 2641 + 2440 |
104
+ | Non-EU services (US SaaS) | `SE_VAT_25_PURCHASE_NON_EU_SERVICES_RC` | 5422 + 2645 + 2614 + 2820 |
105
+ | EU services | `SE_VAT_25_PURCHASE_EU_SERVICES_RC` | Expense + 2645 + 2614 + 2440 |
106
+ | Exempt purchase | `SE_VAT_EXEMPT_PURCHASE` | Expense + balancing |
107
+
108
+ **Notes:**
109
+ - `RC` = Reverse Charge (buyer reports VAT instead of seller)
110
+ - Use `--list-tax-codes` to see all available codes with descriptions
111
+ - Account 2641 = Incoming VAT (domestic), 2645 = Incoming VAT (reverse charge)
112
+ - Account 2614 = Outgoing VAT (reverse charge)
113
+
38
114
  ## Entities
39
115
 
40
116
  ### Journal Entry (entry.yaml)
@@ -53,14 +129,18 @@ lines:
53
129
  memo: Account description
54
130
  ```
55
131
 
56
- ### Document Metadata (document.yaml)
132
+ ### Document Metadata (documents.yaml)
57
133
 
58
134
  ```yaml
59
- kind: RECEIPT # RECEIPT, INVOICE, BANK_FILE, etc.
60
- status: DRAFT
61
- fileName: document.pdf
62
- sourceIntegration: {{PROVIDER_LOWER}}
63
- sourceId: UUID
135
+ - fileName: document.pdf
136
+ mimeType: application/pdf
137
+ sourceIntegration: {{PROVIDER_LOWER}}
138
+ sourceId: UUID
139
+ description: Vendor name
140
+ documentDate: 2024-01-15
141
+ totalAmount:
142
+ amount: "1250.00"
143
+ currency: SEK
64
144
  ```
65
145
 
66
146
  ### Fiscal Year (_fiscal-year.yaml)
@@ -91,5 +171,7 @@ Common accounts:
91
171
  - `2440` - Supplier payables
92
172
  - `2610` - Outgoing VAT 25%
93
173
  - `2640` - Incoming VAT
174
+ - `2820` - Short-term liabilities (credit card, etc.)
94
175
  - `4000` - Cost of goods sold
176
+ - `5420` - Software and IT services
95
177
  - `6570` - Bank charges
package/package.json CHANGED
@@ -1,12 +1,14 @@
1
1
  {
2
2
  "name": "create-kvitton",
3
- "version": "0.4.2",
3
+ "version": "0.4.5",
4
4
  "description": "Create a new kvitton bookkeeping repository",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "create-kvitton": "./dist/index.js"
8
8
  },
9
- "files": ["dist"],
9
+ "files": [
10
+ "dist"
11
+ ],
10
12
  "scripts": {
11
13
  "build": "bun scripts/build.ts",
12
14
  "dev": "tsc --watch",
@@ -25,7 +27,9 @@
25
27
  "@types/bun": "latest",
26
28
  "typescript": "^5.0.0",
27
29
  "integrations-bokio": "workspace:*",
28
- "sync": "workspace:*"
30
+ "integrations-fortnox": "workspace:*",
31
+ "shared": "workspace:*",
32
+ "accounting": "workspace:*"
29
33
  },
30
34
  "engines": {
31
35
  "node": ">=18"