bkper 3.7.0 → 3.8.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.
Files changed (5) hide show
  1. package/README.md +101 -122
  2. package/lib/commands/apps.d.ts.map +1 -1
  3. package/lib/commands/apps.js +2 -10
  4. package/lib/commands/apps.js.map +1 -1
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -8,52 +8,37 @@ The MCP server enables AI assistants and agents to interact with your Bkper book
8
8
 
9
9
  ## Installation
10
10
 
11
- ### Add the package:
11
+ ### npm
12
12
 
13
13
  ```
14
- npm i bkper
15
- ```
16
-
17
- or
18
-
19
- ```
20
- yarn add bkper
21
- ```
22
-
23
- or
24
-
25
- ```
26
- bun add bkper
14
+ npm i -g bkper
27
15
  ```
28
16
 
29
- Optionally, you can install it globally to be able to use the `bkper` command line utility:
17
+ ### yarn
30
18
 
31
19
  ```
32
- npm i -g bkper
20
+ yarn global add bkper
33
21
  ```
34
22
 
35
- or
23
+ ### bun
36
24
 
37
25
  ```
38
- yarn global add bkper
26
+ bun add -g bkper
39
27
  ```
40
28
 
41
29
  ## Commands
42
30
 
43
- - `login` - Logs the user in. Saves the client credentials to a `~/.config/bkper/.bkper-credentials.json` file.
44
- - `logout` - Logs out the user by deleting client credentials.
45
- - `mcp start` - Start the Bkper MCP (Model Context Protocol) server.
46
- - `app -c` - Create a new App based on `./bkperapp.yaml` file.
47
- - `app -u` - Update an existing App based on `./bkperapp.yaml` file.
31
+ - `login` - Logs the user in, storing local credentials.
32
+ - `logout` - Logs out the user by deleting client credentials.
33
+ - `mcp start` - Start the Bkper MCP (Model Context Protocol) server.
34
+ - `apps list` - List all apps you have access to.
35
+ - `apps create` - Create a new App based on `./bkperapp.yaml` file.
36
+ - `apps update` - Update an existing App based on `./bkperapp.yaml` file.
48
37
 
49
38
  ### Examples
50
39
 
51
- ```
52
- npm bkper login
53
- ```
54
-
55
- ```
56
- yarn bkper login
40
+ ```bash
41
+ bkper login
57
42
  ```
58
43
 
59
44
  ### MCP (Model Context Protocol) Server
@@ -68,18 +53,18 @@ bkper mcp start
68
53
 
69
54
  The server runs on stdio and provides the following tools:
70
55
 
71
- - **list_books** - List all books accessible by the authenticated user
72
- - **get_book** - Get details of a specific book by ID
73
- - **get_balances** - Get account balances for a specific date or period
74
- - **list_transactions** - List transactions with filtering options
56
+ - **list_books** - List all books accessible by the authenticated user
57
+ - **get_book** - Get detailed information about a specific book
58
+ - **get_balances** - Get account balances with query filtering
59
+ - **list_transactions** - List transactions with filtering and pagination
60
+ - **create_transactions** - Create transactions in batch
61
+ - **merge_transactions** - Merge duplicate transactions into one
75
62
 
76
63
  #### Prerequisites
77
64
 
78
65
  Before using the MCP server:
79
66
 
80
67
  1. Login using `bkper login` to set up authentication
81
- 2. Enable the [Bkper REST API]
82
- 3. Ensure the `BKPER_API_KEY` environment variable is set.
83
68
 
84
69
  The MCP server uses the same authentication as the CLI, reading credentials from `~/.config/bkper/.bkper-credentials.json`.
85
70
 
@@ -89,20 +74,17 @@ The MCP server uses the same authentication as the CLI, reading credentials from
89
74
 
90
75
  Add to your configuration file:
91
76
 
92
- - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
93
- - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
77
+ - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
78
+ - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
94
79
 
95
80
  ```json
96
81
  {
97
- "mcpServers": {
98
- "bkper": {
99
- "command": "npx",
100
- "args": ["bkper", "mcp", "start"],
101
- "env": {
102
- "BKPER_API_KEY": "your-api-key-here"
103
- }
82
+ "mcpServers": {
83
+ "bkper": {
84
+ "command": "bkper",
85
+ "args": ["mcp", "start"]
86
+ }
104
87
  }
105
- }
106
88
  }
107
89
  ```
108
90
 
@@ -111,7 +93,7 @@ Add to your configuration file:
111
93
  For other MCP-compatible clients, configure them to run:
112
94
 
113
95
  ```bash
114
- BKPER_API_KEY=your-api-key npx bkper mcp start
96
+ bkper mcp start
115
97
  ```
116
98
 
117
99
  The server communicates via stdio, so any MCP client that supports stdio transport can connect to it.
@@ -120,10 +102,12 @@ The server communicates via stdio, so any MCP client that supports stdio transpo
120
102
 
121
103
  Once connected, the MCP client can:
122
104
 
123
- - List your Bkper books
124
- - Get account balances for any date or period
125
- - Search and filter transactions
126
- - Analyze your financial data
105
+ - List your Bkper books
106
+ - Get detailed book information including group hierarchy
107
+ - Get account balances with flexible query filtering
108
+ - Search and filter transactions with pagination
109
+ - Create transactions in batch
110
+ - Merge duplicate transactions
127
111
 
128
112
  For more information about the Model Context Protocol, visit [modelcontextprotocol.io](https://modelcontextprotocol.io).
129
113
 
@@ -131,24 +115,9 @@ For more information about the Model Context Protocol, visit [modelcontextprotoc
131
115
 
132
116
  ### Environment Variables
133
117
 
134
- The following environment variable is necessary in order to communicate with the [Bkper REST API]:
135
-
136
- ```
137
- BKPER_API_KEY=XXXX
138
- ```
139
-
140
- The `app` command also uses the following variables in order to perform App create/update operations:
118
+ `BKPER_API_KEY` is optional. If not set, uses the Bkper API proxy with a managed API key.
141
119
 
142
- ```
143
- BKPER_CLIENT_SECRET=YYYY
144
- BKPER_USER_EMAILS="someone@gmail.com anotherone@altrostat.com"
145
- BKPER_DEVELOPER_EMAIL=somedeveloer@mycompany.com
146
- ```
147
-
148
- You can add a `.env` file at the root of your project with those variables and bkper will automatically load from it.
149
- Follow [these](https://bkper.com/docs/#rest-api-enabling) steps in order to configure a valid Bkper API key.
150
-
151
- > WARNING: Never upload variables to the source code repository.
120
+ Set it for direct API access with your own quotas and attribution. Follow [these](https://bkper.com/docs/#rest-api-enabling) steps.
152
121
 
153
122
  ### `./bkperapp.yaml` Reference
154
123
 
@@ -167,6 +136,16 @@ logoUrl: https://static.thenounproject.com/png/2318500-200.png
167
136
  # The logo url to be used when in dark mode
168
137
  logoUrlDark: https://static.thenounproject.com/png/2318500-200.png
169
138
 
139
+ # ACCESS CONTROL (safe to version - uses usernames, not emails)
140
+
141
+ # Developers who can update the App. Comma or space separated usernames.
142
+ # Supports domain wildcards for registered custom domains (e.g., *@bkper.com)
143
+ developers: victor, aldo, *@bkper.com
144
+
145
+ # Users who can use the App while not yet published. Comma or space separated usernames.
146
+ # Supports domain wildcards for registered custom domains (e.g., *@acme.com)
147
+ users: maria, *@acme.com
148
+
170
149
  # CONTEXT MENU CONFIGURATION
171
150
 
172
151
  # The menu production url to open in the popup window. See accepted expressions bellow.
@@ -189,69 +168,69 @@ webhookUrl: https://us-central1-bkper-tax-trigger.cloudfunctions.net/events
189
168
  # The events the Bot is capable of processing by the webhook.
190
169
  # This is optional and, if not specified, no events will be processed.
191
170
  events:
192
- - "TRANSACTION_POSTED"
193
- - "TRANSACTION_CHECKED"
194
- - "TRANSACTION_UNCHECKED"
195
- - "TRANSACTION_UPDATED"
196
- - "TRANSACTION_DELETED"
197
- - "TRANSACTION_RESTORED"
198
- - "ACCOUNT_CREATED"
199
- - "ACCOUNT_UPDATED"
200
- - "ACCOUNT_DELETED"
201
- - "GROUP_CREATED"
202
- - "GROUP_UPDATED"
203
- - "GROUP_DELETED"
204
- - "FILE_CREATED"
205
- - "BOOK_UPDATED"
171
+ - "TRANSACTION_POSTED"
172
+ - "TRANSACTION_CHECKED"
173
+ - "TRANSACTION_UNCHECKED"
174
+ - "TRANSACTION_UPDATED"
175
+ - "TRANSACTION_DELETED"
176
+ - "TRANSACTION_RESTORED"
177
+ - "ACCOUNT_CREATED"
178
+ - "ACCOUNT_UPDATED"
179
+ - "ACCOUNT_DELETED"
180
+ - "GROUP_CREATED"
181
+ - "GROUP_UPDATED"
182
+ - "GROUP_DELETED"
183
+ - "FILE_CREATED"
184
+ - "BOOK_UPDATED"
206
185
 
207
186
  # The file patterns the Bot is capable of processing. It accepts wildcards. E.g.
208
187
  filePatterns:
209
- - "radiusbank*.ofx"
210
- - "-*.qif"
211
- - "*.csv"
188
+ - "radiusbank*.ofx"
189
+ - "-*.qif"
190
+ - "*.csv"
212
191
 
213
192
  # Schema to provide autocompletion on properties editor.
214
193
  propertiesSchema:
215
- book:
216
- keys:
217
- - "key1"
218
- - "key2"
219
- values:
220
- - "value2"
221
- - "value2"
222
- group:
223
- keys:
224
- - "key1"
225
- - "key2"
226
- values:
227
- - "value2"
228
- - "value2"
229
- account:
230
- keys:
231
- - "key1"
232
- - "key2"
233
- values:
234
- - "value2"
235
- - "value2"
236
- transaction:
237
- keys:
238
- - "key1"
239
- - "key2"
240
- values:
241
- - "value2"
242
- - "value2"
194
+ book:
195
+ keys:
196
+ - "key1"
197
+ - "key2"
198
+ values:
199
+ - "value2"
200
+ - "value2"
201
+ group:
202
+ keys:
203
+ - "key1"
204
+ - "key2"
205
+ values:
206
+ - "value2"
207
+ - "value2"
208
+ account:
209
+ keys:
210
+ - "key1"
211
+ - "key2"
212
+ values:
213
+ - "value2"
214
+ - "value2"
215
+ transaction:
216
+ keys:
217
+ - "key1"
218
+ - "key2"
219
+ values:
220
+ - "value2"
221
+ - "value2"
243
222
  ```
244
223
 
245
224
  #### Accepted expressions in menuUrl property:
246
225
 
247
- - `${book.id}` - the current book id
248
- - `${book.properties.xxxxx}` - any property value from the current book
249
- - `${transactions.query}` - the current query being executed on transactions list
250
- - `${transactions.ids}` - the ids of selected transactions, splitted by comma
251
- - `${account.id}` - the current account being filterd
252
- - `${account.properties.xxxxx}` - any property value from the current account being filtered
253
- - `${group.id}` - the current group being filterd
254
- - `${group.properties.xxxxx}` - any property value from the current group being filtered
226
+ - `${book.id}` - the current book id
227
+ - `${book.properties.xxxxx}` - any property value from the current book
228
+ - `${transactions.query}` - the current query being executed on transactions list
229
+ - `${transactions.ids}` - the ids of selected transactions, splitted by comma
230
+ - `${account.id}` - the current account being filterd
231
+ - `${account.properties.xxxxx}` - any property value from the current account being filtered
232
+ - `${group.id}` - the current group being filterd
233
+ - `${group.properties.xxxxx}` - any property value from the current group being filtered
255
234
 
256
235
  #### Example:
257
236
 
@@ -270,10 +249,10 @@ import { Bkper } from "bkper-js";
270
249
  import { getOAuthToken } from "bkper";
271
250
 
272
251
  Bkper.setConfig({
273
- oauthTokenProvider: async () => getOAuthToken(),
252
+ oauthTokenProvider: async () => getOAuthToken(),
274
253
  });
275
254
  ```
276
255
 
277
256
  ## Documentation
278
257
 
279
- - [Developer Docs](https://bkper.com/docs)
258
+ - [Developer Docs](https://bkper.com/docs)
package/lib/commands/apps.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/commands/apps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAK/B;;;;GAIG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAIrD;AAyDD;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAI9C;AAED;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAI9C"}
1
+ {"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/commands/apps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAK/B;;;;GAIG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAIrD;AAgDD;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAI9C;AAED;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAI9C"}
package/lib/commands/apps.js CHANGED
@@ -52,8 +52,9 @@ function loadReadme() {
52
52
  return undefined;
53
53
  }
54
54
  /**
55
- * Creates an App instance configured with environment variables.
55
+ * Creates an App instance configured from bkperapp.yaml and environment variables.
56
56
  *
57
+
57
58
  * @returns Configured App instance
58
59
  */
59
60
  function createConfiguredApp() {
@@ -63,15 +64,6 @@ function createConfiguredApp() {
63
64
  if (readme) {
64
65
  app.setReadme(readme);
65
66
  }
66
- if (process.env.BKPER_CLIENT_SECRET) {
67
- app.setClientSecret(process.env.BKPER_CLIENT_SECRET);
68
- }
69
- if (process.env.BKPER_DEVELOPER_EMAIL) {
70
- app.setDeveloperEmail(process.env.BKPER_DEVELOPER_EMAIL);
71
- }
72
- if (process.env.BKPER_USER_EMAILS) {
73
- app.setUserEmails(process.env.BKPER_USER_EMAILS);
74
- }
75
67
  return app;
76
68
  }
77
69
  /**
package/lib/commands/apps.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"apps.js","sourceRoot":"","sources":["../../src/commands/apps.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;GAIG;AACH,MAAM,UAAgB,QAAQ;;QAC5B,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;CAAA;AAED;;;;;GAKG;AACH,SAAS,aAAa;IACpB,IAAI,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,CAAC;SAAM,IAAI,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU;IACjB,IAAI,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QACjC,OAAO,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB;IAC1B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAE1B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,IAAI,MAAM,EAAE,CAAC;QACX,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IAED,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,CAAC;QACpC,GAAG,CAAC,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,EAAE,CAAC;QACtC,GAAG,CAAC,iBAAiB,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,CAAC;QAClC,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAgB,SAAS;;QAC7B,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;QACtC,OAAO,UAAU,CAAC;IACpB,CAAC;CAAA;AAED;;;;GAIG;AACH,MAAM,UAAgB,SAAS;;QAC7B,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;QACtC,OAAO,UAAU,CAAC;IACpB,CAAC;CAAA"}
1
+ {"version":3,"file":"apps.js","sourceRoot":"","sources":["../../src/commands/apps.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;GAIG;AACH,MAAM,UAAgB,QAAQ;;QAC5B,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;CAAA;AAED;;;;;GAKG;AACH,SAAS,aAAa;IACpB,IAAI,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,CAAC;SAAM,IAAI,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU;IACjB,IAAI,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QACjC,OAAO,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB;IAC1B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAE1B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,IAAI,MAAM,EAAE,CAAC;QACX,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAgB,SAAS;;QAC7B,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;QACtC,OAAO,UAAU,CAAC;IACpB,CAAC;CAAA;AAED;;;;GAIG;AACH,MAAM,UAAgB,SAAS;;QAC7B,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;QACtC,OAAO,UAAU,CAAC;IACpB,CAAC;CAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bkper",
3
- "version": "3.7.0",
3
+ "version": "3.8.0",
4
4
  "description": "Node.js command line client for Bkper",
5
5
  "bin": {
6
6
  "bkper": "./lib/cli.js"