bkper 4.12.27 → 4.12.28
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/lib/agent/system-prompt.js +2 -2
- package/lib/commands/apps/init.d.ts +8 -0
- package/lib/commands/apps/init.d.ts.map +1 -1
- package/lib/commands/apps/init.js +66 -4
- package/lib/commands/apps/init.js.map +1 -1
- package/lib/docs/app-building.md +96 -2
- package/lib/docs/app-management.md +1 -1
- package/package.json +1 -1
|
@@ -87,13 +87,13 @@ export function getBkperAgentSystemPrompt() {
|
|
|
87
87
|
|
|
88
88
|
Bkper's accounting model is intentionally non-standard. Generic accounting knowledge — debit/credit, account categories, sign conventions — will lead you to wrong answers here.
|
|
89
89
|
|
|
90
|
-
|
|
90
|
+
The canonical Bkper data model reference:
|
|
91
91
|
|
|
92
92
|
\`\`\`
|
|
93
93
|
${coreConceptsPath}
|
|
94
94
|
\`\`\`
|
|
95
95
|
|
|
96
|
-
|
|
96
|
+
Base all reasoning about Bkper data — books, accounts, groups, transactions, balances, queries, or any accounting or financial flow — on this reference. Prior accounting intuition does not substitute for it.
|
|
97
97
|
|
|
98
98
|
## Reference Routing
|
|
99
99
|
|
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Recursively replaces 'my-app' with the new app name in all string values.
|
|
3
|
+
*/
|
|
4
|
+
export declare function replaceMyAppInObject(obj: unknown, appName: string): unknown;
|
|
5
|
+
/**
|
|
6
|
+
* Replaces the placeholder app id 'my-app' in event handler source files.
|
|
7
|
+
*/
|
|
8
|
+
export declare function updateEventHandlers(projectDir: string, appName: string): void;
|
|
1
9
|
/**
|
|
2
10
|
* Initializes a new Bkper app from the template.
|
|
3
11
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/apps/init.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/apps/init.ts"],"names":[],"mappings":"AAuGA;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAe3E;AAsCD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAwB7E;AAqDD;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgFzD"}
|
|
@@ -96,6 +96,25 @@ function downloadTemplate(targetDir) {
|
|
|
96
96
|
// =============================================================================
|
|
97
97
|
// Project Configuration
|
|
98
98
|
// =============================================================================
|
|
99
|
+
/**
|
|
100
|
+
* Recursively replaces 'my-app' with the new app name in all string values.
|
|
101
|
+
*/
|
|
102
|
+
export function replaceMyAppInObject(obj, appName) {
|
|
103
|
+
if (typeof obj === 'string') {
|
|
104
|
+
return obj.replace(/my-app/g, appName);
|
|
105
|
+
}
|
|
106
|
+
if (Array.isArray(obj)) {
|
|
107
|
+
return obj.map(item => replaceMyAppInObject(item, appName));
|
|
108
|
+
}
|
|
109
|
+
if (obj && typeof obj === 'object') {
|
|
110
|
+
const result = {};
|
|
111
|
+
for (const [key, value] of Object.entries(obj)) {
|
|
112
|
+
result[key] = replaceMyAppInObject(value, appName);
|
|
113
|
+
}
|
|
114
|
+
return result;
|
|
115
|
+
}
|
|
116
|
+
return obj;
|
|
117
|
+
}
|
|
99
118
|
/**
|
|
100
119
|
* Updates the bkper.yaml file with the new app name.
|
|
101
120
|
* Also handles bkperapp.yaml for backward compatibility.
|
|
@@ -120,7 +139,36 @@ function updateBkperYaml(projectDir, appName) {
|
|
|
120
139
|
.map(word => word.charAt(0).toUpperCase() + word.slice(1))
|
|
121
140
|
.join(' ');
|
|
122
141
|
}
|
|
123
|
-
|
|
142
|
+
// Replace all remaining 'my-app' placeholders in URLs and other values
|
|
143
|
+
const updatedConfig = replaceMyAppInObject(config, appName);
|
|
144
|
+
fs.writeFileSync(yamlPath, YAML.stringify(updatedConfig), 'utf8');
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Replaces the placeholder app id 'my-app' in event handler source files.
|
|
148
|
+
*/
|
|
149
|
+
export function updateEventHandlers(projectDir, appName) {
|
|
150
|
+
const eventsDir = path.join(projectDir, 'packages/events/src');
|
|
151
|
+
if (!fs.existsSync(eventsDir)) {
|
|
152
|
+
return;
|
|
153
|
+
}
|
|
154
|
+
function processDir(dir) {
|
|
155
|
+
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
|
156
|
+
const fullPath = path.join(dir, entry.name);
|
|
157
|
+
if (entry.isDirectory()) {
|
|
158
|
+
processDir(fullPath);
|
|
159
|
+
}
|
|
160
|
+
else if (entry.name.endsWith('.ts')) {
|
|
161
|
+
let content = fs.readFileSync(fullPath, 'utf8');
|
|
162
|
+
const original = content;
|
|
163
|
+
// Replace both single and double quoted 'my-app' used as an identifier
|
|
164
|
+
content = content.replace(/(['"])my-app\1/g, `$1${appName}$1`);
|
|
165
|
+
if (content !== original) {
|
|
166
|
+
fs.writeFileSync(fullPath, content, 'utf8');
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
processDir(eventsDir);
|
|
124
172
|
}
|
|
125
173
|
/**
|
|
126
174
|
* Updates the package.json file with the new app name.
|
|
@@ -204,7 +252,16 @@ export function initApp(name) {
|
|
|
204
252
|
console.error('Error updating bkper.yaml:', err instanceof Error ? err.message : err);
|
|
205
253
|
process.exit(1);
|
|
206
254
|
}
|
|
207
|
-
// 5. Update
|
|
255
|
+
// 5. Update event handler loop guards
|
|
256
|
+
try {
|
|
257
|
+
updateEventHandlers(targetDir, name);
|
|
258
|
+
console.log(' Updated event handlers');
|
|
259
|
+
}
|
|
260
|
+
catch (err) {
|
|
261
|
+
console.error('Error updating event handlers:', err instanceof Error ? err.message : err);
|
|
262
|
+
process.exit(1);
|
|
263
|
+
}
|
|
264
|
+
// 6. Update package.json
|
|
208
265
|
try {
|
|
209
266
|
updatePackageJson(targetDir, name);
|
|
210
267
|
console.log(' Updated package.json');
|
|
@@ -213,7 +270,7 @@ export function initApp(name) {
|
|
|
213
270
|
console.error('Error updating package.json:', err instanceof Error ? err.message : err);
|
|
214
271
|
process.exit(1);
|
|
215
272
|
}
|
|
216
|
-
//
|
|
273
|
+
// 7. Install dependencies
|
|
217
274
|
console.log(' Installing dependencies...');
|
|
218
275
|
try {
|
|
219
276
|
yield runCommand('bun', ['install'], targetDir);
|
|
@@ -222,12 +279,17 @@ export function initApp(name) {
|
|
|
222
279
|
catch (err) {
|
|
223
280
|
console.log(' Warning: Could not install dependencies. Run "bun install" manually.');
|
|
224
281
|
}
|
|
225
|
-
//
|
|
282
|
+
// 8. Print success message
|
|
226
283
|
console.log(`
|
|
227
284
|
Done! To get started:
|
|
228
285
|
|
|
229
286
|
cd ${name}
|
|
230
287
|
bun run dev
|
|
288
|
+
|
|
289
|
+
Next steps:
|
|
290
|
+
- Review bkper.yaml: update description, ownerName, ownerWebsite, and repoUrl
|
|
291
|
+
- Replace logo-light.svg and logo-dark.svg in packages/web/client/public/images/
|
|
292
|
+
- Edit README.md to explain what your app does for end users
|
|
231
293
|
`);
|
|
232
294
|
});
|
|
233
295
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/commands/apps/init.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/commands/apps/init.ts"],"names":[],"mappings":"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"}
|
package/lib/docs/app-building.md
CHANGED
|
@@ -55,7 +55,24 @@ To make your app available to all Bkper users, contact us at [support@bkper.com]
|
|
|
55
55
|
|
|
56
56
|
- **Functionality check** — The app works correctly and handles errors gracefully
|
|
57
57
|
- **Security review** — Event handlers are idempotent and include loop prevention
|
|
58
|
-
- **Listing quality** — The app has a clear name, description, and
|
|
58
|
+
- **Listing quality** — The app has a clear name, description, logo, and user-facing documentation
|
|
59
|
+
|
|
60
|
+
### README matters
|
|
61
|
+
|
|
62
|
+
Your app's `README.md` is displayed to end users on the app listing page. Write it for the people who will install and use your app — not for developers.
|
|
63
|
+
|
|
64
|
+
**README should explain:**
|
|
65
|
+
- What the app does from a user's perspective
|
|
66
|
+
- How to use it (step-by-step for non-technical users)
|
|
67
|
+
- What features are available
|
|
68
|
+
|
|
69
|
+
**README should NOT contain:**
|
|
70
|
+
- Tech stack or architecture details
|
|
71
|
+
- Build commands or development setup
|
|
72
|
+
- Project structure or internal file paths
|
|
73
|
+
- API documentation or SDK references
|
|
74
|
+
|
|
75
|
+
Put developer documentation in `AGENTS.md` or internal docs instead. Keep `README.md` focused on the user experience.
|
|
59
76
|
|
|
60
77
|
### Where published apps appear
|
|
61
78
|
|
|
@@ -598,6 +615,8 @@ Deploy to a separate preview environment for testing before production:
|
|
|
598
615
|
bkper app deploy --preview
|
|
599
616
|
```
|
|
600
617
|
|
|
618
|
+
Preview URLs use a dash suffix: `https://{appId}-preview.bkper.app`. For example, an app with `id: my-app` deploys to `https://my-app-preview.bkper.app`.
|
|
619
|
+
|
|
601
620
|
Preview has independent secrets and KV storage from production.
|
|
602
621
|
|
|
603
622
|
### Independent handler deployment
|
|
@@ -1089,6 +1108,81 @@ The complete current set of event types:
|
|
|
1089
1108
|
| `BOOK_UPDATED` | Book settings were updated. |
|
|
1090
1109
|
| `BOOK_DELETED` | The book was deleted. |
|
|
1091
1110
|
|
|
1111
|
+
---
|
|
1112
|
+
source: /docs/build/apps/first-app.md
|
|
1113
|
+
|
|
1114
|
+
# Your First App
|
|
1115
|
+
|
|
1116
|
+
This tutorial walks you through building and deploying a Bkper app from scratch. For the deep reference on any topic — architecture, configuration, development, events, or deployment — follow the links in each step.
|
|
1117
|
+
|
|
1118
|
+
## Prerequisites
|
|
1119
|
+
|
|
1120
|
+
[Development Setup](https://bkper.com/docs/build/getting-started/setup.md) — the CLI installed and authenticated.
|
|
1121
|
+
|
|
1122
|
+
## Walkthrough
|
|
1123
|
+
|
|
1124
|
+
1. **Scaffold from the template**
|
|
1125
|
+
|
|
1126
|
+
```bash
|
|
1127
|
+
bkper app init my-app
|
|
1128
|
+
cd my-app
|
|
1129
|
+
```
|
|
1130
|
+
|
|
1131
|
+
The CLI sets your app ID, package name, URLs, and event-handler loop guards automatically. See [App Configuration](https://bkper.com/docs/build/apps/configuration.md) for the full `bkper.yaml` reference.
|
|
1132
|
+
|
|
1133
|
+
2. **Start developing**
|
|
1134
|
+
|
|
1135
|
+
```bash
|
|
1136
|
+
npm run dev
|
|
1137
|
+
```
|
|
1138
|
+
|
|
1139
|
+
This runs the Vite client dev server and the local worker runtime with automatic webhook tunneling. See [Development Experience](https://bkper.com/docs/build/apps/development.md) for details.
|
|
1140
|
+
|
|
1141
|
+
3. **Open the app**
|
|
1142
|
+
|
|
1143
|
+
Visit [http://localhost:5173](http://localhost:5173). Select a book to see account balances. No OAuth setup required — the platform handles authentication.
|
|
1144
|
+
|
|
1145
|
+
4. **Trigger an event**
|
|
1146
|
+
|
|
1147
|
+
Go to any Bkper book and check (reconcile) a transaction. Your local event handler receives the webhook via the tunnel and creates a 20% draft transaction. See [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md) for the full event model.
|
|
1148
|
+
|
|
1149
|
+
5. **Make a change**
|
|
1150
|
+
|
|
1151
|
+
Edit the handler in `packages/events/src/handlers/transaction-checked.ts` and save. The worker reloads automatically. Check another transaction to see your change.
|
|
1152
|
+
|
|
1153
|
+
6. **Customize your listing**
|
|
1154
|
+
|
|
1155
|
+
Update `bkper.yaml` with your app's description, owner details, and repository URL. Replace the placeholder logos in `packages/web/client/public/images/`. See [App Listing](https://bkper.com/docs/build/apps/app-listing.md) for publishing details.
|
|
1156
|
+
|
|
1157
|
+
7. **Update the README**
|
|
1158
|
+
|
|
1159
|
+
Edit `README.md` for end users — what the app does and how to use it. Keep developer docs in `AGENTS.md`.
|
|
1160
|
+
|
|
1161
|
+
8. **Deploy**
|
|
1162
|
+
|
|
1163
|
+
```bash
|
|
1164
|
+
npm run build
|
|
1165
|
+
bkper app sync
|
|
1166
|
+
bkper app deploy
|
|
1167
|
+
```
|
|
1168
|
+
|
|
1169
|
+
Your app is live at `https://my-app.bkper.app`. See [Building & Deploying](https://bkper.com/docs/build/apps/deploying.md) for preview environments, secrets, and KV.
|
|
1170
|
+
|
|
1171
|
+
## What you built
|
|
1172
|
+
|
|
1173
|
+
| You wrote | Platform handled |
|
|
1174
|
+
| --- | --- |
|
|
1175
|
+
| ~30 lines of UI | OAuth, consent screen, token refresh |
|
|
1176
|
+
| ~40 lines of event logic | Hosting, SSL, edge routing |
|
|
1177
|
+
| `bkper.yaml` | Webhook tunnels, KV, type generation |
|
|
1178
|
+
|
|
1179
|
+
## Next steps
|
|
1180
|
+
|
|
1181
|
+
- [App Architecture](https://bkper.com/docs/build/apps/architecture.md) — Understand the three-package pattern
|
|
1182
|
+
- [App Configuration](https://bkper.com/docs/build/apps/configuration.md) — Full `bkper.yaml` reference
|
|
1183
|
+
- [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md) — All event types and patterns
|
|
1184
|
+
- [Building & Deploying](https://bkper.com/docs/build/apps/deploying.md) — Preview environments and secrets
|
|
1185
|
+
|
|
1092
1186
|
---
|
|
1093
1187
|
source: /docs/build/apps/overview.md
|
|
1094
1188
|
|
|
@@ -1166,7 +1260,7 @@ npm run dev
|
|
|
1166
1260
|
|
|
1167
1261
|
This gives you a working app with a client UI, server API, and event handler — all running locally with full HMR and webhook tunneling.
|
|
1168
1262
|
|
|
1169
|
-
See [Your First App](https://bkper.com/docs/build/
|
|
1263
|
+
See [Your First App](https://bkper.com/docs/build/apps/first-app.md) for a complete walkthrough, or continue to [App Architecture](https://bkper.com/docs/build/apps/architecture.md) to understand how platform apps are structured.
|
|
1170
1264
|
|
|
1171
1265
|
---
|
|
1172
1266
|
source: /docs/build/apps/self-hosted.md
|
|
@@ -76,7 +76,7 @@ bkper app build
|
|
|
76
76
|
# Sync configuration and deploy to production
|
|
77
77
|
bkper app sync && bkper app deploy
|
|
78
78
|
|
|
79
|
-
# Deploy to
|
|
79
|
+
# Deploy to preview environment (URL: https://{appId}-preview.bkper.app)
|
|
80
80
|
bkper app deploy --preview
|
|
81
81
|
|
|
82
82
|
# Deploy only the events handler
|