Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nef10/swiftbeancountsheetsync
Library to help Sync shared Expenses between a Google Sheet and a Beancount file
https://github.com/nef10/swiftbeancountsheetsync
beancount plaintext-accounting swiftbeancount
Last synced: 12 days ago
JSON representation
Library to help Sync shared Expenses between a Google Sheet and a Beancount file
- Host: GitHub
- URL: https://github.com/nef10/swiftbeancountsheetsync
- Owner: Nef10
- License: mit
- Created: 2020-12-21T10:03:26.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-07-08T01:57:59.000Z (4 months ago)
- Last Synced: 2024-10-10T13:28:50.256Z (29 days ago)
- Topics: beancount, plaintext-accounting, swiftbeancount
- Language: Swift
- Homepage: https://github.com/Nef10/SwiftBeanCount
- Size: 568 KB
- Stars: 2
- Watchers: 2
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SwiftBeanCountSheetSync
[](https://github.com/Nef10/SwiftBeanCountSheetSync/actions?query=workflow%3A%22CI%22) [](https://nef10.github.io/SwiftBeanCountSheetSync/) [](https://github.com/Nef10/SwiftBeanCountSheetSync/blob/master/LICENSE) [](https://github.com/Nef10/SwiftBeanCountSheetSync/releases)  
### ***This project is part for SwiftBeanCount, please check out the main documentation [here](https://github.com/Nef10/SwiftBeanCount).***
## What
This library synchronizes transactions from Beancount files to a Google Sheets with shared transactions. This is helpful when you share expenses with another person who does not use beancount.
## How to use
1) Create an instance of `Uploader` or `Downloader` depending on which way you want to sync, providing the HTTP URL of the Sheet as well as the file URL of the beancount file.
2) Authenticate the user to Google via [GoogleAuthentication](https://github.com/Nef10/GoogleAuthentication).
2) Call `start` on the instance you created in step 1, passing in the authentication instance from step 2.
3) Your completion handler will get a `SyncResult` if the sync was successful. This will include:
- the transactions which need to be added (to the sheet for upload or the ledger for download)
- parsing errors occured while reading the sheet
- configuration which was used for syncing
Please check out the complete documentation [here](https://nef10.github.io/SwiftBeanCountSheetSync/), or have a look at the [SwiftBeanCountSheetSyncApp](https://github.com/Nef10/SwiftBeanCountSheetSyncApp) which uses this library.
## Beancount meta data
The synchronization relies on meta data in your beancount file for configuration. Please add these to your beancount file.
### General configuration
- `commoditySymbol`: The synchronization only works with one commodity which needs to be specified here
- `account`: Account which is used to keep track of the balance between the people
- `tag`: Tag which is appended to all transactions which are or should be synchronized
- `name`: Your name - this will be used to identify the colunms of the sheet
- `dateTolerance`: Tolerance in days which will be used when checking if a transactions already exists
These options are specified globally via `customs` like this (the date does not matter and will be ignored):
```
YYYY-MM-DD custom "sheet-sync-settings" "commoditySymbol" "CAD"
```
### Account configuration
You can attatch `sheet-sync-category` metadata to accounts to map categories from the sheet to accounts and vice-versa in a 1-1 relationship. This is optional, in case no mapping could be found a fallback account / an empty category will be used.
Example:
```
2020-12-26 open Expenses:Communication:Internet
sheet-sync-category: "Internet"
```
## Google Sheet Format
The Google sheet need to be in a specifc format in order to be read. The tab must be named `Expenses`.
The following columns are required to be within colunms A-I, other columns are ignored:
- `Date` in yyyy-MM-dd format
- `Paid to` e.g. Store name, can be an empty string
- `Amount` Use `.` as decimal point. `,` to separate thousand is ok, accouting style with brackets for negative values is supported
- `Category` See account configuration above
- `Part Name1` and `Part Name2`. `Name1` and `Name2` should be the name of the people (e.g. replace them). One of them must be the same as configured as name in the ledger (see above). Each column must contain a number which represents the amount this party is paying for the purchase. Same formatting rules as for amount apply.
- `Who paid` One of the two names
- `Comment` While the column is required, it can be an empty string
## Usage
The library supports the Swift Package Manger, so simply add a dependency in your `Package.swift`:
```
.package(url: "https://github.com/Nef10/SwiftBeanCountSheetSync.git", .upToNextMajor(from: "X.Y.Z")),
```