bkper 4.13.7 → 4.15.0

package/lib/docs/app-management.md

@@ -12,47 +12,85 @@ Build, deploy, and manage Bkper apps using the `bkper` CLI.
 When scaffolding, developing, or deploying an app, verify each step before proceeding. This prevents broken deployments and silent failures.
 
 ### 1. Init
+
 ```bash
 bkper app init my-app
 ```
+
 Verify:
-- `packages/web/client/`, `packages/web/server/`, `packages/events/`, and `packages/shared/` exist
+
+- `client/` and `server/` exist
 - `bkper.yaml` has `id`, `name`, `description`, and `developers`
 - `package.json` scripts include `dev` and `build`
 
 ### 2. Develop
+
 ```bash
 npm run dev
 ```
+
 Verify:
-- Web server responds: `curl http://localhost:8787` (or the port you configured)
+
+- Server worker responds: `curl http://localhost:8787/health` (or the port you configured)
 - Client dev server is reachable if running separately
-- Events tunnel URL is printed in terminal and registered in Bkper (check `webhookUrlDev` in app settings)
-- If any handler fails to start, fix before writing code
+- If the app declares `events`, the events tunnel URL is printed in terminal and registered in Bkper as `webhookUrlDev`
+- If the worker fails to start, fix before writing code
 
 ### 3. Build
+
 ```bash
 npm run build
 ```
+
 Verify:
-- `dist/web/server/` contains the web worker bundle
-- `dist/events/` contains the events handler bundle
+
+- `dist/server/` contains the server Worker bundle
+- `dist/client/` contains the Vite client build when `deployment.client` is configured
 - No build errors in terminal output
 
 ### 4. Sync & Deploy
+
 ```bash
 bkper app sync && bkper app deploy
 ```
+
 Verify:
+
 - `bkper app status` shows the deployed version
 - URLs in `bkper.yaml` match the deployed domain (`https://{appId}.bkper.app`)
 
+#### Preview testing with menu and events
+
+To test a preview deployment from the Bkper UI, keep production URLs unchanged and point the development URLs to the preview Worker:
+
+```yaml
+menuUrl: https://{appId}.bkper.app?bookId=${book.id}
+menuUrlDev: https://{appId}-preview.bkper.app?bookId=${book.id}
+
+webhookUrl: https://{appId}.bkper.app/events
+webhookUrlDev: https://{appId}-preview.bkper.app/events
+```
+
+Then build, sync metadata, and deploy to preview:
+
+```bash
+npm run build
+bkper app sync
+bkper app deploy --preview
+```
+
+Bkper uses `menuUrlDev` for developer menu access and `webhookUrlDev` for development-mode events. If `bkper app dev` runs later, it may replace `webhookUrlDev` with a local tunnel URL; set it back to the preview URL and run `bkper app sync` before testing preview again.
+
 ### 5. Validate
+
 ```bash
 bkper app install <appId> -b <bookId>
 ```
+
 Verify:
+
 - Menu appears in the book's "More" menu (if configured)
+- App server `/api/*` routes are called with `Authorization: Bearer <token>`
 - Trigger a subscribed event in the book
 - Check the Bkper activity stream for the handler response
 - If the handler writes back to the book, confirm loop prevention is in place (check `event.agent.id`)
@@ -66,11 +104,11 @@ Verify:
 bkper app init my-app
 
 # Start the worker runtime (Miniflare + tunnel + file watching)
-# In your project, use "npm run dev" to run both Vite and workers concurrently
+# In your project, use "npm run dev" to run both Vite and the worker concurrently
 bkper app dev
 
-# Build worker bundles (web server + events handler)
-# In your project, use "npm run build" to build both client (Vite) and workers
+# Build the server Worker bundle
+# In your project, use "npm run build" to build both client (Vite) and worker
 bkper app build
 
 # Sync configuration and deploy to production
@@ -79,14 +117,11 @@ bkper app sync && bkper app deploy
 # Deploy to preview environment (URL: https://{appId}-preview.bkper.app)
 bkper app deploy --preview
 
-# Deploy only the events handler
-bkper app deploy --events
-
 # Check deployment status
 bkper app status
 ```
 
-> **Note:** `bkper app dev` runs the worker runtime only — Miniflare, file watching, and the Cloudflare tunnel. Miniflare is loaded from the app project's `devDependencies` so each app can keep its local Workers simulator aligned with its own code. The Vite client dev server is configured in the project's `vite.config.ts` and run separately. The project template composes both via `npm run dev` using `concurrently`. If needed, install Miniflare in the app root with `bun add -d miniflare` or `npm install -D miniflare`.
+> **Note:** `bkper app dev` runs one local Worker runtime — Miniflare, file watching, and an optional Cloudflare tunnel to `/events` when the app subscribes to events. Miniflare is loaded from the app project's `devDependencies` so each app can keep its local Workers simulator aligned with its own code. The Vite client dev server is configured in the project's `vite.config.ts` and run separately. The project template composes both via `npm run dev` using `concurrently`. If needed, install Miniflare in the app root with `bun add -d miniflare` or `npm install -D miniflare`.
 
 ---
 
@@ -115,6 +150,8 @@ bkper app secrets list
 bkper app secrets delete EXTERNAL_SERVICE_TOKEN
 ```
 
+Use `--preview` to manage preview secrets.
+
 ---
 
 ## Configuration
@@ -231,6 +268,7 @@ menuPopupHeight: 300
 # EVENT HANDLING (optional)
 # -----------------------------------------------------------------------------
 # When configured, Bkper calls your webhook URL when subscribed events occur.
+# On the Bkper Platform, /events is handled by the same Worker as /api/*.
 
 # Production webhook URL
 webhookUrl: https://${id}.bkper.app/events
@@ -323,19 +361,23 @@ propertiesSchema:
 # -----------------------------------------------------------------------------
 # For apps deployed to Bkper's Workers for Platforms infrastructure.
 deployment:
-    # Web handler (serves UI and API)
-    web:
-        bundle: packages/web/server/dist
-        # assets: packages/web/client/dist  # Static assets (when supported)
+    # Single server Worker entry point. It serves /api/* and /events.
+    server: server/src/index.ts
 
-    # Events handler (processes webhooks)
-    events:
-        bundle: packages/events/dist
+    # Optional Vite/static client root. Built assets are deployed with the same Worker.
+    client: client
 
     # Platform services available to your app (one per type, auto-provisioned)
     # See: https://developers.cloudflare.com/kv/
     services:
         - KV # Key-value storage
+
+    # Secret names managed with bkper app secrets
+    secrets:
+        - EXTERNAL_SERVICE_TOKEN
+
+    # Cloudflare Workers compatibility date
+    compatibility_date: '2026-01-28'
 ```
 
 </details>
@@ -356,6 +398,7 @@ deployment:
 
 ### Agent
 
+-   `bkper` - Start the interactive Bkper Agent when run in an interactive terminal; print CLI help in non-interactive contexts
 -   `agent` - Start the interactive Bkper Agent
 -   `agent <pi-args...>` - Run Pi CLI with Bkper defaults (system prompt/resources)
 
@@ -364,30 +407,25 @@ deployment:
 -   `app init <name>` - Scaffold a new app from the template
 -   `app list` - List all apps you have access to
 -   `app sync` - Sync [bkper.yaml][bkper.yaml reference] configuration (URLs, description) to Bkper API
--   `app build` - Build worker bundles for deployment
+-   `app build` - Build the server Worker bundle for deployment
 -   `app deploy` - Deploy built artifacts to Cloudflare Workers for Platforms
     -   `-p, --preview` - Deploy to preview environment
-    -   `--events` - Deploy events handler instead of web handler
 -   `app status` - Show deployment status
--   `app logs` - View recent app logs
+-   `app logs [appId]` - View recent app logs. When `appId` is omitted, the app id is read from local app config.
     -   `--since <time>` - ISO8601 or relative lower bound (e.g. `5m`, `1h`, `15d`)
     -   `--until <time>` - ISO8601 or relative upper bound
-    -   `--last <n>` - Show newest N entries after filters (default: 100)
+    -   `--last <n>` - Show newest N requests after filters (default: 100)
     -   `-p, --preview` - Query preview logs instead of production
-    -   `-w, --web` - Filter to the web handler
-    -   `-e, --events` - Filter to the events handler
-    -   `--outcome <outcome>` - Filter by Cloudflare worker outcome
+    -   `-w, --web` - Filter to normal web/API requests
+    -   `-e, --events` - Filter to `/events` requests
+    -   `--level <level>` - Minimum log level threshold (`info`, `warn`, or `error`)
     -   `--status-code <code>` - Filter by HTTP status code
 -   `app undeploy` - Remove app from platform
     -   `-p, --preview` - Remove from preview environment
-    -   `--events` - Remove events handler instead of web handler
     -   `--delete-data` - Permanently delete all associated data (requires confirmation)
     -   `--force` - Skip confirmation prompts (use with `--delete-data` for automation)
 -   `app dev` - Start the worker runtime for local development
     -   `--sp, --server-port <port>` - Server simulation port (default: `8787`)
-    -   `--ep, --events-port <port>` - Events handler port (default: `8791`)
-    -   `-w, --web` - Run only the web handler
-    -   `-e, --events` - Run only the events handler
 
 > **Note:** `sync` and `deploy` are independent operations. Use `sync` to update your app's URLs in Bkper (required for webhooks and menu integration). Use `deploy` to push code to Cloudflare. For a typical deployment workflow, run both: `bkper app sync && bkper app deploy`
 

package/lib/docs/bkper-js.md

@@ -122,6 +122,8 @@ const books = await bkper.getBooks();
 
 See the [@bkper/web-auth documentation](https://bkper.com/docs/api/bkper-web-auth) for more details.
 
+For Bkper Platform app server routes under `/api/*`, send `Authorization: Bearer ${auth.getAccessToken()}` from the client. The server route can use `new Bkper()` without a token provider because platform outbound auth injects the validated user's token on Bkper API calls.
+
 ### API Key (Optional)
 
 API keys are optional and only needed for dedicated quota limits. If not provided, requests use a shared managed quota via the Bkper API proxy.

package/lib/docs/cli-reference.md

@@ -4,7 +4,7 @@
 
 A unified **interface for [Bkper](https://bkper.com)**. Use `bkper` in two complementary modes:
 
--   **Interactive mode** — run `bkper agent` to open the Bkper Agent TUI
+-   **Interactive mode** — run `bkper` or `bkper agent` to open the Bkper Agent TUI
 -   **Command mode** — run `bkper <command>` for explicit CLI workflows, scripts, and automation
 
 With one tool, you can build and deploy Bkper apps, and manage financial data -- books, accounts, transactions, and balances.
@@ -50,9 +50,11 @@ This is the only command that opens the browser OAuth flow. When you are done wo
 ### Interactive mode (recommended)
 
 ```bash
-bkper agent
+bkper
 ```
 
+`bkper agent` starts the same interactive experience. Bare `bkper` only opens the TUI in an interactive terminal; in non-interactive contexts it prints CLI help instead.
+
 ![Bkper CLI Agent TUI](https://raw.githubusercontent.com/bkper/bkper-cli/main/assets/bkper-agent-cli.png)
 
 On first launch, type `/login` and select a provider. We recommend [OpenCode Go](https://opencode.ai/go) for open-weights models and [OpenCode Zen](https://opencode.ai/zen) for frontier models — both give you access to high-quality models with no extra setup.
@@ -108,6 +110,7 @@ bkper agent <pi-args>
 ```
 
 If no Pi arguments are provided, `bkper agent` starts the interactive Bkper Agent experience.
+A bare `bkper` command is a convenience shortcut for the same TUI when run in an interactive terminal.
 If Pi arguments are provided, everything after `bkper agent` is passed through to Pi.
 
 Examples:
@@ -153,9 +156,10 @@ bkper app init my-app
 bkper app dev
 bkper app sync && bkper app deploy
 bkper app logs --last 50
+bkper app logs my-app --level error
 ```
 
-`bkper app logs` reads recent app logs kept for 15 days. The default output is human-readable, and JSON is available with `--json`.
+`bkper app logs` reads recent app logs kept for 15 days. Run it inside an app directory, or pass an app id like `bkper app logs my-app`. Use `--level warn` or `--level error` to focus on requests with warnings or errors. The default output is human-readable, and JSON is available with `--json`.
 
 → [Full App Management reference](https://github.com/bkper/bkper-cli/blob/main/docs/app-management.md)
 

package/lib/docs/index.md

@@ -4,7 +4,7 @@ Reference docs for Bkper tasks. Load only the specific doc(s) relevant to the ta
 
 - **data-management.md** — CLI reference for managing financial data and files: books, accounts, groups, files, transactions, per-account balance queries, query operators (on:, after:, before:, account:, group:), output formats (table/json/csv), batch operations via stdin/piping, collections.
 - **app-management.md** — CLI reference for building and deploying Bkper apps: dev/build/deploy workflow, app install/uninstall, secrets management, app logs, bkper.yaml configuration reference (identity, branding, events, menu integration, deployment).
-- **app-building.md** — Full app-building reference: architecture (packages, client/server/events), development loop, event handlers, deployment patterns, the Bkper Platform, and self-hosted alternatives. Includes authentication patterns for web clients (`@bkper/web-auth`), event handlers (`bkper-oauth-token` headers), and local development. Load this for scaffolding apps, understanding app structure, or debugging the dev/build/deploy lifecycle.
+- **app-building.md** — Full app-building reference: single Worker app architecture (`client/` + `server/`), development loop, `/api/*` routes, `/events` handlers, deployment patterns, the Bkper Platform, and self-hosted alternatives. Includes authentication patterns for web clients (`@bkper/web-auth`), server API routes (`Authorization: Bearer` on `/api/*` with outbound auth injection), platform event handlers (`new Bkper()` with outbound auth injection), and local development.
 - **financial-statements.md** — Step-by-step workflow for aggregate financial reports (balance sheet, P&L): root group discovery, query patterns, date semantics (before: vs after:+before:), common mistakes to avoid.
 - **taxes.md** — Deterministic workflow for tax position and filing summaries: discovering tax-relevant groups, period-based balance queries, persisting a local tax runner. Jurisdiction-agnostic — outputs raw period balances, leaving rate/application to the user.
 - **bkper-js.md** — bkper-js Node.js/browser SDK: Bkper, Book, Account, Transaction, Group, Balance classes, all methods, getBalancesReport, OAuth configuration, library setup.

package/lib/platform/client.d.ts

@@ -12,8 +12,8 @@
  *
  * // Deploy an app
  * const { data, error } = await client.POST('/api/apps/{appId}/deploy', {
- *   params: { path: { appId: 'my-app' }, query: { env: 'dev', type: 'web' } },
- *   body: bundleBuffer,
+ *   params: { path: { appId: 'my-app' }, query: { env: 'preview' } },
+ *   body: formData,
  * });
  * ```
  */

package/lib/platform/client.js

@@ -12,8 +12,8 @@
  *
  * // Deploy an app
  * const { data, error } = await client.POST('/api/apps/{appId}/deploy', {
- *   params: { path: { appId: 'my-app' }, query: { env: 'dev', type: 'web' } },
- *   body: bundleBuffer,
+ *   params: { path: { appId: 'my-app' }, query: { env: 'preview' } },
+ *   body: formData,
  * });
  * ```
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "4.13.7",
+    "version": "4.15.0",
     "description": "Command line client for Bkper",
     "bin": {
         "bkper": "./lib/cli.js"
@@ -51,7 +51,7 @@
         "upgrade:api": "bun update @bkper/bkper-api-types --latest && bun update bkper-js --latest"
     },
     "dependencies": {
-        "@earendil-works/pi-coding-agent": "0.75.5",
+        "@earendil-works/pi-coding-agent": "0.76.0",
         "bkper-js": "^2.35.2",
         "commander": "^13.1.0",
         "dotenv": "^8.2.0",