You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -56,11 +56,11 @@ You can see a full list of options in the **[Config Docs](./docs/CONFIG.md)**.
56
56
**How is this different from [build-your-own-mint](https://github.com/yyx990803/build-your-own-mint)?**
57
57
58
58
-**[build-your-own-mint](https://github.com/yyx990803/build-your-own-mint)** is a set of scripts which solely facilitates the integration between Plaid and Google Sheets. It makes no assumptions about what you want your spreadsheet to look like, and you have to define your own logic to map transactions to spreadsheet updates.
59
-
-**[Mintable](#)** is and end-to-end system that works out of the box. It comes with a setup wizard, a web-based configuration server, pluggable providers (you're not limited to just Plaid & Google Sheets), and a spreadsheet template.
59
+
-**[Mintable](#)** is and end-to-end system that works out of the box. It comes with a setup wizard, a web-based configuration server, [pluggable providers](./docs/PROVIDERS.md) (you're not limited to just Plaid & Google Sheets), and a spreadsheet template.
60
60
61
61
**Do I have to give my data to Plaid and Google? Are there any completely self-hosted alternatives I can use?**
62
62
63
-
- It's pluggable! Plaid & Google Sheets are working right now – contributions are welcome for other providers!
63
+
- It's [pluggable](./docs/PROVIDERS.md)! Plaid & Google Sheets are working right now – contributions are welcome for [other providers](./docs/PROVIDERS.md)!
64
64
65
65
**Do I have to manually run this every time I want new transactions in my spreadsheet?**
All configurations below can be made using the web configuration framework or by editing `mintable.config.json`.
4
4
5
-
`mintable.config.json` is the secret sauce – it contains all of your private tokens and is never sent to third-party servers. This file is ignored by Git – keep a backup somewhere safe as you only have 100 Plaid accounts on the free version.
5
+
`mintable.config.json` is the secret sauce – it contains all of your private tokens and is never sent to third-party servers. This file is ignored by Git – keep a backup somewhere safe.
6
6
7
7
> **Pro Tip:** You can use Dropbox or another trusted service to sync `mintable.config.json` across your machines. Run `ln -s <path_to_cloud_folder>/mintable.config.json .` from the repo root to symlink Mintable to the cloud version.
8
8
9
-
####Automate Updates with a CI Provider
9
+
### Automate Updates with a CI Provider
10
10
11
11
This repo includes config files for both [CircleCI](https://circleci.com/) and [Travis CI](https://travis-ci.com) to run builds automatically.
12
12
@@ -18,53 +18,156 @@ yarn export
18
18
19
19
Run this command and paste the result into an environment variable called `MINTABLE_CONFIG` in your CI provider of choice. Mintable will handle the rest.
20
20
21
-
> **Note:** Some CI providers (like Travis) require you to wrap this variable in single quotes, i.e. `'{ PLAID_TOKEN: "" ...}'`. If you get an error similar to `Unable to parse JSON...` when you run your CI build, give this a try.
21
+
> **Note:** Some CI providers (like Travis) require you to wrap this variable in single quotes, i.e. `'{ "ACCOUNT_PROVIDER": "plaid", ...}'`. If you get an error similar to `Unable to parse JSON...` when you run your CI build, give this a try.
22
22
23
23
> **Warning:** If you choose to use CircleCI, you should turn off **Pass secrets to builds from forked pull requests** under **Build Settings** > **Advanced Settings**.
24
24
25
-
#### Transaction Columns
25
+
###Start Date
26
26
27
-
`TRANSACTION_COLUMNS` specifies a list of [Plaid transaction properties](https://plaid.com/docs/#transactions) (using [`_.get()` syntax](https://lodash.com/docs/4.17.11#get)) to override the default automated columns. Each time you run Mintable, all the contents of these columns will be cleared and overwritten.
27
+
`START_DATE` specifies the lower bound for fetching transactions in `YYYY.MM.DD` format.
28
28
29
-
For example, if you only want to auto-populate the name and amount for each transaction, you could add the following line to your `mintable.config.json` file:
29
+
**Default:**
30
+
31
+
```javascript
32
+
"START_DATE":undefined// If end date is not specified, Mintable will fetch the last 2 months of transactions
33
+
```
34
+
35
+
For example, if you only want to fetch transactions which occur after or on December 1, 2018, you could add the following line to your `mintable.config.json` file:
36
+
37
+
```javascript
38
+
"START_DATE":"2018.12.01"
39
+
```
40
+
41
+
### End Date
42
+
43
+
`END_DATE` specifies the upper bound for fetching transactions in `YYYY.MM.DD` format.
44
+
45
+
**Default:**
46
+
47
+
```javascript
48
+
"END_DATE":undefined// If end date is not specified, Mintable will fetch up until the current date
49
+
```
50
+
51
+
For example, if you only want to fetch transactions which occur before or on December 1, 2018, you could add the following line to your `mintable.config.json` file:
30
52
53
+
```javascript
54
+
"END_DATE":"2018.12.01"
31
55
```
32
-
TRANSACTION_COLUMNS=["name", "amount"]
56
+
57
+
### Transaction Columns
58
+
59
+
`TRANSACTION_COLUMNS` specifies a list of transaction properties (using [`_.get()` syntax](https://lodash.com/docs/4.17.11#get)) to automatically update in your spreadsheet. All the contents of these columns will be cleared and overwritten each time you run Mintable.
> **Warning:** Your mileage may vary if you choose to use additional properties outside the tested defaults (`date`, `amount`, `name`, `account`, `category.0`, `category.1`, `pending`). Proceed at your own risk, you're in uncharted territory.
67
+
For example, if you only want to auto-populate the name and amount for each transaction, you could add the following line to your `mintable.config.json` file:
68
+
69
+
```javascript
70
+
"TRANSACTION_COLUMNS": ["name", "amount"]
71
+
```
36
72
37
-
####Reference Columns
73
+
### Reference Columns
38
74
39
75
`REFERENCE_COLUMNS` specifies a list of additional, non-automated columns for your reference/bookkeeping purposes. Each time you run Mintable, the contents of these columns will be preserved.
40
76
41
-
For example, if you want to add one column to track work expenses, and another to track joint expenses shared with a partner, you could add the following line to your `mintable.config.json` file:
77
+
**Default:**
42
78
79
+
```javascript
80
+
"REFERENCE_COLUMNS": ['notes', 'work', 'joint']
43
81
```
44
-
REFERENCE_COLUMNS=["work", "joint"]
82
+
83
+
For example, if you want to add one column to track work expenses, and another to track joint expenses shared with a partner, you could add the following line to your `mintable.config.json` file:
84
+
85
+
```javascript
86
+
"REFERENCE_COLUMNS": ["work", "joint"]
45
87
```
46
88
47
89
> **Warning:** Since reference columns are not automated by Mintable, they have the potential to get out of sync with transaction data (for example, if your bank deletes a transaction, causing a row to get removed in `TRANSACTION_COLUMNS`)
48
90
49
-
#### Category Overrides
91
+
### Account Provider
92
+
93
+
`ACCOUNT_PROVIDER` specifies which service to use to fetch transactions.
50
94
51
-
`CATEGORY_OVERRIDES` specifies a list of overrides to handle transactions that are routinely miscategorized by Plaid's servers. Overrides take the following format:
95
+
**Default:**
96
+
97
+
```javascript
98
+
"ACCOUNT_PROVIDER":"plaid"
99
+
```
100
+
101
+
### Spreadsheet Provider
102
+
103
+
`SHEET_PROVIDER` specifies which service to use to automate spreadsheet updates.
104
+
105
+
**Default:**
106
+
107
+
```javascript
108
+
"SHEET_PROVIDER":"sheets"// "sheets" = Google Sheets
109
+
```
110
+
111
+
# Provider-Specific Configuration
112
+
113
+
You can see the API definitions for account & spreadsheet providers in the **[provider docs](./docs/PROVIDERS.md)**.
114
+
115
+
## Plaid
116
+
117
+
### Category Overrides
118
+
119
+
`CATEGORY_OVERRIDES` specifies a list of overrides to handle transactions that are routinely miscategorized by Plaid's servers.
120
+
121
+
**Default:**
122
+
123
+
```javascript
124
+
"CATEGORY_OVERRIDES": []
125
+
```
126
+
127
+
Overrides take the following format:
52
128
53
129
*`pattern`: [JavaScript Regular Expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Syntax) to test transaction names against
54
130
*`flags`: [JavaScript Regular Expression flags](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Syntax) (i.e. `i` for case insensitive)
55
131
*`category.0`: Override for first (top-level) category
56
132
*`category.1`: Override for second (level-2) category
57
133
58
-
For example, if you want anything matching `autopay` or `e-payment` to get categorized as `Credit Card Payment`, you could add the following line to your `mintable.config.json` file:
For example, if you want anything matching `autopay` or `e-payment` to get categorized as `Credit Card Payment`, you could add the following lines to your `mintable.config.json` file:
135
+
136
+
```javascript
137
+
"CATEGORY_OVERRIDES": [
138
+
{
139
+
"pattern":".*(autopay|e.payment).*",
140
+
"flags":"i",
141
+
"category.0":"Transfer",
142
+
"category.1":"Credit Card Payments"
143
+
}
144
+
]
62
145
```
63
146
64
-
#### Transaction Provider
147
+
##Google Sheets
65
148
66
-
`ACCOUNT_PROVIDER` specifies which service to use to fetch transactions. At this time, the only possible value is `"plaid"`, but we plan to add other providers in the future.
149
+
### Template Sheet
67
150
68
-
#### Spreadsheet Provider
151
+
`TEMPLATE_SHEET` specifies the template spreadsheet to use when creating a _new_ sheet for a month.
69
152
70
-
`SHEET_PROVIDER` specifies which service to use to automate spreadsheet updates. At this time, the only possible value is `"sheets"`, but we plan to add other providers in the future.
153
+
**Default:**
154
+
155
+
```javascript
156
+
"TEMPLATE_SHEET": {
157
+
// Public template: https://docs.google.com/spreadsheets/d/10fYhPJzABd8KlgAzxtiyFN-L_SebTvM8SaAK_wHk-Fw
Mintable is designed to be pluggable, i.e. you can swap out Plaid or Google Sheets for another service of your choice.
4
+
5
+
This document outlines what Mintable expects of a provider, and what constraints/functionality you need to adhere to/implement if you want to add a new provider.
6
+
7
+
## Transactions (`ACCOUNT_PROVIDER`) API
8
+
9
+
Account providers should provide an exported function which takes in a startDate and endDate, and returns a `Promise` of a raw list of transaction objects, i.e.:
Spreadsheet providers should provide an exported function which takes in a map of sheet name to a list of transactions for that sheet, and return a `Promise` which resolves when all necessary operations to update that sheet are complete, i.e.:
0 commit comments