tillbooks 0.0.0
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.
- package/LICENSE +21 -0
- package/README.md +56 -0
- package/bin/till.mjs +52 -0
- package/dist/money.js +88 -0
- package/dist/money.js.map +1 -0
- package/package.json +62 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Nomadik GmbH
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# TILL
|
|
2
|
+
|
|
3
|
+
**Trusted Independent Ledger Library.** Swiss accounting your agent can actually use.
|
|
4
|
+
|
|
5
|
+
TILL is a free, open-source (MIT), local-first accounting app built for Switzerland. Your books live
|
|
6
|
+
in a single SQLite file on your own machine. They never leave the country, because they never leave
|
|
7
|
+
your laptop.
|
|
8
|
+
|
|
9
|
+
The difference is the interface. Most accounting software is a GUI with an AI button bolted on. TILL
|
|
10
|
+
is built the other way around: an **MCP server is a first-class interface**, so an agent can post
|
|
11
|
+
entries, categorize transactions, draft and chase invoices, prepare the MWST-Abrechnung, and answer
|
|
12
|
+
"how did my quarter go" by talking to the ledger directly. A minimalist Studio gives you human
|
|
13
|
+
oversight of everything the agent did. Agent and human share one ledger.
|
|
14
|
+
|
|
15
|
+
> **Status: pre-alpha.** The scaffold is up and the specs are written. Nothing here is ready to keep
|
|
16
|
+
> real books yet. Do not run your business on it.
|
|
17
|
+
|
|
18
|
+
## Why
|
|
19
|
+
|
|
20
|
+
Switzerland has accounting software. It does not have accounting software an agent can drive, and
|
|
21
|
+
the open-source option (Gäld) is AGPL, which forecloses an open-core model. TILL is a clean-room
|
|
22
|
+
MIT rebuild aimed at the things that actually make Swiss books Swiss:
|
|
23
|
+
|
|
24
|
+
- **QR-bill** (Swiss QR-Rechnung) with the structured-address standard
|
|
25
|
+
- **Three MWST rates** (8.1%, 3.8%, 2.6%) and the MWST-Abrechnung that falls out of them
|
|
26
|
+
- **Kontenrahmen KMU** seeded out of the box
|
|
27
|
+
- **ISO 20022** (camt/pain) for banking
|
|
28
|
+
- de-CH and en from day one
|
|
29
|
+
|
|
30
|
+
## The ledger is not negotiable
|
|
31
|
+
|
|
32
|
+
Posted entries are append-only and immutable. A correction is a **reversing entry**, never a
|
|
33
|
+
destructive edit, exactly as real accounting works. Posting is idempotent: a double-post does not
|
|
34
|
+
double-count. These are asserted in the test suite, not merely promised in a README.
|
|
35
|
+
|
|
36
|
+
## Install
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
npm install -g tillbooks
|
|
40
|
+
till --help
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The package is `tillbooks`. The command is `till`.
|
|
44
|
+
|
|
45
|
+
## Documentation
|
|
46
|
+
|
|
47
|
+
- [Specs](docs/specs/) : the capability specs and the architecture reference
|
|
48
|
+
- [Design](brand/DESIGN.md) : the design law this project builds to
|
|
49
|
+
- [Naming](docs/naming-decision-till.md) : why it is called TILL, with the register evidence
|
|
50
|
+
|
|
51
|
+
## License
|
|
52
|
+
|
|
53
|
+
MIT, Copyright (c) 2026 Nomadik GmbH. See [LICENSE](LICENSE).
|
|
54
|
+
|
|
55
|
+
TILL is an independent project. It is not affiliated with, endorsed by, or derived from bexio AG or
|
|
56
|
+
any other accounting vendor. It is a clean-room implementation built from public documentation.
|
package/bin/till.mjs
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* The `till` command.
|
|
4
|
+
*
|
|
5
|
+
* The package is `tillbooks` (the bare `till` is taken on npm), but a bin name is independent of
|
|
6
|
+
* the package name, so the command itself stays short.
|
|
7
|
+
*
|
|
8
|
+
* Pre-alpha: this is a scaffold. The verbs arrive with Module 1.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
const VERSION = '0.0.0';
|
|
12
|
+
|
|
13
|
+
const USAGE = `till ${VERSION} - Swiss accounting your agent can actually use
|
|
14
|
+
|
|
15
|
+
Usage: till <command> [options]
|
|
16
|
+
|
|
17
|
+
Commands:
|
|
18
|
+
mcp Start the MCP server on stdio (the agent interface)
|
|
19
|
+
version Print the version
|
|
20
|
+
help Print this
|
|
21
|
+
|
|
22
|
+
Status: pre-alpha. The ledger verbs (post, reverse, journal, close) arrive with Module 1.
|
|
23
|
+
Do not keep real books in this yet.
|
|
24
|
+
|
|
25
|
+
Docs: https://github.com/tillbooks/tillbooks
|
|
26
|
+
`;
|
|
27
|
+
|
|
28
|
+
const [, , command = 'help'] = process.argv;
|
|
29
|
+
|
|
30
|
+
switch (command) {
|
|
31
|
+
case 'version':
|
|
32
|
+
case '--version':
|
|
33
|
+
case '-v':
|
|
34
|
+
console.log(VERSION);
|
|
35
|
+
break;
|
|
36
|
+
|
|
37
|
+
case 'mcp':
|
|
38
|
+
console.error('till: the MCP server is not implemented yet (arrives with Module 1).');
|
|
39
|
+
process.exit(1);
|
|
40
|
+
break;
|
|
41
|
+
|
|
42
|
+
case 'help':
|
|
43
|
+
case '--help':
|
|
44
|
+
case '-h':
|
|
45
|
+
console.log(USAGE);
|
|
46
|
+
break;
|
|
47
|
+
|
|
48
|
+
default:
|
|
49
|
+
console.error(`till: unknown command "${command}"\n`);
|
|
50
|
+
console.error(USAGE);
|
|
51
|
+
process.exit(1);
|
|
52
|
+
}
|
package/dist/money.js
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Money, as integer Rappen.
|
|
3
|
+
*
|
|
4
|
+
* There are no floats anywhere on the money path. `0.1 + 0.2 !== 0.3` is not a curiosity here, it
|
|
5
|
+
* is a defect that compounds silently across a year of entries and then fails an audit. Every
|
|
6
|
+
* amount in TILL is an integer count of the currency's minor unit, and CHF has 100 of them.
|
|
7
|
+
*
|
|
8
|
+
* This module is deliberately small and total. It is the bottom of the money path, so it must be
|
|
9
|
+
* boring.
|
|
10
|
+
*/
|
|
11
|
+
export class MoneyError extends Error {
|
|
12
|
+
constructor(message) {
|
|
13
|
+
super(message);
|
|
14
|
+
this.name = 'MoneyError';
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
/** Assert an integer count of minor units. Throws on a float, NaN, or an unsafe magnitude. */
|
|
18
|
+
export function rappen(value) {
|
|
19
|
+
if (!Number.isInteger(value)) {
|
|
20
|
+
throw new MoneyError(`Money must be an integer count of Rappen, got ${value}. ` +
|
|
21
|
+
`Use money.fromFranken() to convert, never a raw float.`);
|
|
22
|
+
}
|
|
23
|
+
if (!Number.isSafeInteger(value)) {
|
|
24
|
+
throw new MoneyError(`Amount ${value} exceeds the safe integer range.`);
|
|
25
|
+
}
|
|
26
|
+
return value;
|
|
27
|
+
}
|
|
28
|
+
export function money(amount, currency = 'CHF') {
|
|
29
|
+
return { amount: rappen(amount), currency };
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Convert a Franken figure to Rappen.
|
|
33
|
+
*
|
|
34
|
+
* Rounds half away from zero, which is what Swiss commercial practice expects and what
|
|
35
|
+
* `Math.round` does NOT do for negatives (`Math.round(-0.5)` is `-0`, not `-1`).
|
|
36
|
+
*/
|
|
37
|
+
export function fromFranken(franken, currency = 'CHF') {
|
|
38
|
+
if (!Number.isFinite(franken)) {
|
|
39
|
+
throw new MoneyError(`Cannot convert a non-finite value: ${franken}`);
|
|
40
|
+
}
|
|
41
|
+
const scaled = franken * 100;
|
|
42
|
+
const rounded = scaled < 0 ? -Math.round(-scaled) : Math.round(scaled);
|
|
43
|
+
return money(rounded, currency);
|
|
44
|
+
}
|
|
45
|
+
/** The Franken value, for display and export only. Never feed this back into arithmetic. */
|
|
46
|
+
export function toFranken(m) {
|
|
47
|
+
return m.amount / 100;
|
|
48
|
+
}
|
|
49
|
+
function sameCurrency(a, b) {
|
|
50
|
+
if (a.currency !== b.currency) {
|
|
51
|
+
throw new MoneyError(`Refusing to mix ${a.currency} and ${b.currency}. Convert through an explicit FX rate first.`);
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
export function add(a, b) {
|
|
55
|
+
sameCurrency(a, b);
|
|
56
|
+
return money(a.amount + b.amount, a.currency);
|
|
57
|
+
}
|
|
58
|
+
export function subtract(a, b) {
|
|
59
|
+
sameCurrency(a, b);
|
|
60
|
+
return money(a.amount - b.amount, a.currency);
|
|
61
|
+
}
|
|
62
|
+
export function negate(m) {
|
|
63
|
+
return money(-m.amount, m.currency);
|
|
64
|
+
}
|
|
65
|
+
export function sum(items, currency = 'CHF') {
|
|
66
|
+
return items.reduce((acc, m) => add(acc, m), money(0, currency));
|
|
67
|
+
}
|
|
68
|
+
export function isZero(m) {
|
|
69
|
+
return m.amount === 0;
|
|
70
|
+
}
|
|
71
|
+
export function equals(a, b) {
|
|
72
|
+
return a.currency === b.currency && a.amount === b.amount;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Format for humans: `CHF 1'234.55`.
|
|
76
|
+
*
|
|
77
|
+
* The Swiss thousands separator is an apostrophe. Not a comma, not a period, not a space.
|
|
78
|
+
*/
|
|
79
|
+
export function format(m) {
|
|
80
|
+
const negative = m.amount < 0;
|
|
81
|
+
const abs = Math.abs(m.amount);
|
|
82
|
+
const whole = Math.trunc(abs / 100);
|
|
83
|
+
const cents = abs % 100;
|
|
84
|
+
const grouped = String(whole).replace(/\B(?=(\d{3})+(?!\d))/g, "'");
|
|
85
|
+
const body = `${grouped}.${String(cents).padStart(2, '0')}`;
|
|
86
|
+
return `${negative ? '-' : ''}${m.currency} ${body}`;
|
|
87
|
+
}
|
|
88
|
+
//# sourceMappingURL=money.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"money.js","sourceRoot":"","sources":["../src/money.ts"],"names":[],"mappings":"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"}
|
package/package.json
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "tillbooks",
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"description": "TILL (Trusted Independent Ledger Library) is a free, open-source (MIT), local-first Swiss accounting app where an AI agent posts entries, categorizes, drafts and chases invoices, and prepares the MWST-Abrechnung through a first-class MCP interface, with a minimalist Studio for human oversight.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"author": "Nomadik GmbH",
|
|
8
|
+
"homepage": "https://tillbooks.ch",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "git+https://github.com/tillbooks/tillbooks.git"
|
|
12
|
+
},
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/tillbooks/tillbooks/issues"
|
|
15
|
+
},
|
|
16
|
+
"bin": {
|
|
17
|
+
"till": "bin/till.mjs"
|
|
18
|
+
},
|
|
19
|
+
"engines": {
|
|
20
|
+
"node": ">=20"
|
|
21
|
+
},
|
|
22
|
+
"keywords": [
|
|
23
|
+
"accounting",
|
|
24
|
+
"swiss",
|
|
25
|
+
"switzerland",
|
|
26
|
+
"bookkeeping",
|
|
27
|
+
"mcp",
|
|
28
|
+
"mcp-server",
|
|
29
|
+
"agent",
|
|
30
|
+
"agent-native",
|
|
31
|
+
"local-first",
|
|
32
|
+
"self-hosted",
|
|
33
|
+
"open-source",
|
|
34
|
+
"double-entry",
|
|
35
|
+
"ledger",
|
|
36
|
+
"qr-bill",
|
|
37
|
+
"qr-rechnung",
|
|
38
|
+
"mwst",
|
|
39
|
+
"vat",
|
|
40
|
+
"iso20022",
|
|
41
|
+
"kmu",
|
|
42
|
+
"bexio-alternative",
|
|
43
|
+
"erp"
|
|
44
|
+
],
|
|
45
|
+
"files": [
|
|
46
|
+
"bin/",
|
|
47
|
+
"dist/",
|
|
48
|
+
"LICENSE",
|
|
49
|
+
"README.md"
|
|
50
|
+
],
|
|
51
|
+
"scripts": {
|
|
52
|
+
"build": "tsc -p tsconfig.json",
|
|
53
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
54
|
+
"test": "node --test test/**/*.test.mjs",
|
|
55
|
+
"check:style": "node scripts/check-style.mjs",
|
|
56
|
+
"check": "npm run typecheck && npm run check:style && npm test"
|
|
57
|
+
},
|
|
58
|
+
"devDependencies": {
|
|
59
|
+
"@types/node": "^22.10.2",
|
|
60
|
+
"typescript": "^5.7.2"
|
|
61
|
+
}
|
|
62
|
+
}
|