{"id":19808325,"url":"https://github.com/solidos/money-pane","last_synced_at":"2025-05-01T07:32:21.012Z","repository":{"id":48352501,"uuid":"309318830","full_name":"SolidOS/money-pane","owner":"SolidOS","description":"Insight in your personal finance data","archived":false,"fork":false,"pushed_at":"2025-01-20T09:11:37.000Z","size":788,"stargazers_count":11,"open_issues_count":11,"forks_count":1,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-26T15:54:10.027Z","etag":null,"topics":["not-active"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SolidOS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-11-02T09:23:46.000Z","updated_at":"2025-01-20T09:11:38.000Z","dependencies_parsed_at":"2024-01-14T18:09:41.571Z","dependency_job_id":null,"html_url":"https://github.com/SolidOS/money-pane","commit_stats":null,"previous_names":["solid/money-pane"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SolidOS%2Fmoney-pane","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SolidOS%2Fmoney-pane/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SolidOS%2Fmoney-pane/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SolidOS%2Fmoney-pane/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SolidOS","download_url":"https://codeload.github.com/SolidOS/money-pane/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251840418,"owners_count":21652352,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["not-active"],"created_at":"2024-11-12T09:13:35.876Z","updated_at":"2025-05-01T07:32:21.006Z","avatar_url":"https://github.com/SolidOS.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# money-pane\n\nSolid-compatible personal finance insight applet for solid-panes framework\n\n## DEPRECATED\nThe experiments of the Solid Money-Pane have evolved to what is now\nthe [Prejournal](https://pondersource.github.io/prejournal/) project which is no longer strongly\ntied to Solid.\n\nPlease check out [SolidBase](https://lab.allmende.io/solidbase/solidbase), \n[ValueFlo.ws](https://www.valueflo.ws/) and [Mikorzal](http://mikorizal.org/futures.html) instead,\nwhich may currently be closer to what you're looking for.\n\n## Previously\n[NOTE](https://github.com/solid/money-pane/issues/42#issuecomment-1003326750):\nWe have moved our books from our own custom `HalfLedger` format to the\nmore commonly used [Plain Text Accounting](https://plaintextaccounting.org/)\nstandard (specifially, the [HLedger](https://hledger.org/) dialect).\n\nThis has many advantages, for instance, we get to profit from the existing\necosystem data conversion tools from/to the [H]Ledger format, as well as\n(obviously) the existing reporting tools themselves.\n\nAlso, it will make our work more useful since whatever we build (e.g. importers\nfor CSV formats from specific banks) will be usable by anybody who uses plain\ntext accounting.\n\nWe are only switching the file format, not moving away from the 'store your\npersonal data on your personal data store' philosophy of Solid.\nSince your books would generally not be shared directly with others using WAC,\nthis could also be a local data store (your laptop), it doesn't matter that much\nif it's not an online data store. For this same reason it doesn't matter that much\nwhether we access the data using Solid-CRUD or just straightforward filesystem\naccess (specifically since the most common edit operation would be a lexical append).\nWe could still accept RDF documents into the pod's inbox, for instance when someone\nsubmits an expense, receipt, timesheet, etc from inside some Solid app. That's a parser\nwe could add to the existing ecosystem of Plain Text Accounting parsers. Turtle is not\nas \"plain\" as CSV, but it's after all pretty close in the sense of being both simple\nto read and easy edit by hand. :)\n\nOne first downside is that we no longer have a data format that is self-describing\nin a machine-readable way (in RDF, the link to the ontology acts as a machine-readable\nidentifier of the data format, whereas in Plain Text Accounting files,\nit would be best practice to add a human-readable comment at the top describing\nthe precise file format version. But maybe we can at some point (help to) formalize this notion\nand teach our machines to read such a file format version comment.\n\nThe other downside is we can't as easily include hyperlink references to other data in a meaningful way.\nThere may be a way to do something like that in Plain Text Accounting which we haven't discovered yet\n(at the least, you would expect account names and currency names to act as globally unique identifiers).\nMaybe we'll find a way to bring this part of the RDF philosophy to the Plain Text Accounting world.\n\nFor now, consider this code as deprecated (with, for now, the exception of `./exportToHLedger.js`).\n\nYou can build with `npm install \u0026\u0026 npm run build \u0026\u0026 cd dist \u0026\u0026 npx serve`.\nYou can debug with VSCode + Chrome (see `.vscode/launch.json`).\n\n## Import transaction statements from your bank\n\nCurrently supported csv-file formats:\n* [ASN Bank, The Netherlands](https://webcache.googleusercontent.com/search?q=cache:x3PuJKDKj2cJ:https://www.asnbank.nl/web/file%3Fuuid%3Dfc28db9c-d91e-4a2c-bd3a-30cffb057e8b%26owner%3D6916ad14-918d-4ea8-80ac-f71f0ff1928e%26contentid%3D852+\u0026cd=1\u0026hl=en\u0026ct=clnk\u0026gl=nl)\n* Please add yours!\n\n## Deploy stand-alone\n\nYou can deploy this code as a stand-alone Solid app.\nThe way to do that depends on your html-app hosting provider.\nFor instance, to deploy to https://solid-money.5apps.com/ you would:\n\n```sh\ngit checkout deploy # this branch has dist/ commented out in .gitignore\ngit merge master\nnpm ci\nnpm run build\ngit add dist/\ngit commit --no-verify -am \"build\"\ngit remote add 5apps git@5apps.com:michiel_solid-money.git\ngit push 5apps deploy:master\n```\n\n## Active development\n\nYou can run:\n```sh\nmkdir data\nln -s path/to/your/data/root.js data/root.js\n./node_modules/.bin/ts-node run.ts\n```\n\nData root format:\n```js\n{\n  hours: {\n    2021: ...\n  },\n  invoices: {\n    2021: ...\n  },\n  myIbans: [\n    'some-iban...',\n  ],\n  files: {\n    'path/to/file.csv': {\n      parser: 'asnbank-mt940',\n      account: 'some-iban...',\n    },\n  },\n  mcc: {\n    '0763': 'Groceries',\n  },\n  incassant: {\n    'some=iban...': 'House',\n  },\n  iban: {\n    'some=iban...': 'Transport',\n  },\n  description: {\n    'TIN RABBIT            \u003eNEEDHAM': 'Stuff',\n  },\n  transactionType: {\n    NDIV: 'Services',\n  },\n  budget: {\n    Transport: 200/30, // daily budget amount in main currency e.g. euros\n  },\n  months: {\n    '2021-09',\n  }\n}\n\nTo see a report of your personal spending habits against your self-imposed budget.\nI (Michiel de Jong) am running this with my own data root file now, ping me in\nhttps://gitter.im/federatedbookkeeping/community\nif you want to know more about its format, I can\ncreate an up-to-date anonymized example data root file.\n\n## Some notes about the current data format\n\n(subject to change)\n\n### Tracking the arms of the Y\nEntries from an imported bank statement is interpreted with the Y-model:\n\n```\nArrivals          Departures\n          \\   / \n            * (bank account)\n            |\n            me\n```\n\nA debit entry implies one mutation from `Arrivals` (for instance another IBAN bank account) to `* (bank account)` and another mutation from `* (bank account)` to `me` (account balance increases).\nA credit entry implies one mutation from `me` to `* (bank account)`  (account balance decreases) and another mutation from `* (bank account)` to `Arrivals` (for instance another IBAN bank account).\nIn the `AccountHistoryChunk#mutations: WorldLedgerMutation[]` we track the \"arms\" of the Y, so only the\nmutations from `Arrivals` (for instance another IBAN bank account) to `* (bank account)` and from `* (bank account)` to `Arrivals` (for instance another IBAN bank account),\n*not* the mutations between `* (bank account)` and `me`.\n\nThis may seem unnatural since the entries describe mutations that change the balance between `* (bank account)` and `me`. But each can be derived from the other, it doesn't\nseem useful to store both, the arrivals and departures contain more information, and for matching mutations-to-self (e.g. savings account to current account) we already need\nto list out the arrivals and departures, so for now we decided to leave out the mutations between bank account and customer. It can of course be reconstructed at any time\nusing a method like `AccountHistoryChunk#getAccountMutations`.\n\n\n# Equity Graph\nTo generate the equity graph:\n\n```sh\nnode makeBooks.js \u003e ./data/books.js\nnpx serve\n```\nThen visit http://localhost:5000/chart\n\nThe script `makeBooks.js converts from the data/expenses.js format\nto the ./books.js format.\n\n## entries in ./books.js\nThe data in books.js is optimized for displaying the equity graph,\nand takes the form:\n```js\n{ seriesLiquid, seriesLiquidCredit, seriesLiquidCreditAssets, step }\n```\nHere `step` is the number of days between two dots plotted in the graph (for instance 5).\nThe other items are arrays of numbers.\n\n## entries in data/transactions.js\nThe file data/transactions.js should have a default export that is an array of objects (transactions).\nUse these when a client pays an outstanding invoice.\nThe amount is added to 'liquid' and substracted from 'credit'.\n\n## Example transaction\n```js\n{\n  date: '3 sep 2021',\n  description: 'customer ABC paid invoice XYZ',\n  amount: 123.45\n}\n```\n\n## entries in data/expenses.js\nThe file data/expenses.js should have a default export that is an array of objects (expenses).\n\n### Example expense\n```js\n  {\n    description: 'laptop',\n    file: 'expenses/laptop-michiel.pdf',\n    date: '4 jul 2020',\n    writeOffStart: '4 jul 2020',\n    writeOffEnd: '4 jul 2024', // write off ~ 150 eur per year\n    assetGroup: 'computer equipment',\n    excl: 593.43,\n    vat: 124.62,\n    from: 'nl',\n    incl: 718.05\n  },\n```\n\n### Parsing\n* if `writeOffStart` is missing, default it to `date`\n* if `writeOffEnd` is missing, default it to `date`\n* if `fooi` is missing, default it to 0\n* if `vat` is missing, default it to 0\n* if `excl` is missing, default it to `incl`\n* if `incl` is missing, default it to `salary`\n\n### Formats\n* amounts (i.e. `excl`, `vat`, `incl`, `fooi`, `salary`) can be a Float like 124.62 or a string like 'usd 15.16'\n* `from` can be `nl` or `EU` or `non-EU`\n* dates are of the format '9 aug 2021'\n* `writeOffStrategy` 'monthly' means: `writeOffStartDate` := `date` ; `writeOffEndDate` := `date` + 1 month\n* `writeOffStrategy` 'yearly' means: `writeOffStartDate` := `date` ; `writeOffEndDate` := `date` + 1 year\n\n### Effects\n* increase debt of `excl+fooi` on `date`\n* increase value of `excl+fooi` in assetGroup on `date`\n* increase `vat` to ask back\n* schedule write-off from assetGroup to /dev/null over `writeOffStart -\u003e writeOffEnd`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidos%2Fmoney-pane","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolidos%2Fmoney-pane","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidos%2Fmoney-pane/lists"}