bkper 4.25.0 → 4.26.0

package/lib/docs/apps/deploying.md

@@ -0,0 +1,181 @@
+# Building & Deploying
+
+## The deployment workflow
+
+Run the template's deterministic checks before releasing:
+
+```bash
+npm run check
+```
+
+1. **Build** — Compile your code
+
+    ```bash
+    npm run build
+    ```
+
+    This runs two build steps:
+    - Client (Vite) to static assets in `dist/client/`
+    - Server Worker bundle (esbuild) to `dist/server/`
+
+    Build output includes size reporting so you can monitor bundle sizes.
+
+2. **Sync** — Update app metadata and managed source
+
+    ```bash
+    bkper app sync
+    ```
+
+    Syncs your `bkper.yaml` configuration to Bkper — name, description, menu URLs, webhook URLs, access control, and branding. For an app using Bkper-managed source, it also safely pushes the current clean, committed branch. Sync does not build or deploy the app.
+
+3. **Deploy** — Upload the local build to the platform
+
+    ```bash
+    bkper app deploy
+    ```
+
+    For a managed-source app, deploy safely pushes and verifies the current commit. It then uploads your existing pre-built code from `dist/` to the Bkper Platform. The command does not run a build. Your app is live at `https://{appId}.bkper.app`.
+
+The app template combines all three after source changes are committed:
+
+```bash
+npm run deploy
+```
+
+Use `npm run deploy:preview` for the preview environment.
+
+> **Caution: Source is not deployment**
+> An ordinary `git push` stores source only and never deploys. `bkper app sync` also does not deploy. Run `bkper app deploy` explicitly when the local build is ready to release.
+See [Shared App Source](https://bkper.com/docs/build/apps/shared-app-source.md) for managed-source setup, cloning, access, and external Git workflows.
+
+### Production
+
+The default deployment target. Your app runs at `https://{appId}.bkper.app`.
+
+```bash
+bkper app deploy
+```
+
+Production serves:
+
+```txt
+Client:       https://{appId}.bkper.app
+API routes:   https://{appId}.bkper.app/api/*
+OpenAPI spec: https://{appId}.bkper.app/openapi.json
+Events:       https://{appId}.bkper.app/events
+```
+
+### Preview
+
+Deploy to a separate preview environment for testing before production:
+
+```bash
+bkper app deploy --preview
+```
+
+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`.
+
+Preview serves:
+
+```txt
+Client:       https://{appId}-preview.bkper.app
+API routes:   https://{appId}-preview.bkper.app/api/*
+OpenAPI spec: https://{appId}-preview.bkper.app/openapi.json
+Events:       https://{appId}-preview.bkper.app/events
+```
+
+Preview has independent secrets and KV storage from production.
+
+There is one app deployment per environment. `/events` is handled by the same Worker as the client assets and `/api/*` routes.
+
+## Secrets management
+
+Secrets are environment variables stored securely on the platform. Declare them in `bkper.yaml`:
+
+```yaml
+deployment:
+    secrets:
+        - EXTERNAL_SERVICE_TOKEN
+```
+
+### Setting secrets
+
+```bash
+# Set for production
+bkper app secrets put EXTERNAL_SERVICE_TOKEN
+
+# Set for preview
+bkper app secrets put EXTERNAL_SERVICE_TOKEN --preview
+```
+
+You'll be prompted to enter the value.
+
+### Listing and deleting
+
+```bash
+# List all secrets
+bkper app secrets list
+
+# Delete a secret
+bkper app secrets delete EXTERNAL_SERVICE_TOKEN
+```
+
+### Accessing in code
+
+Secrets are available as `c.env.SECRET_NAME` in your Hono handlers:
+
+```ts
+app.get('/api/data', async c => {
+    const token = c.env.EXTERNAL_SERVICE_TOKEN;
+    // use token
+});
+```
+
+During local development, use the `.dev.vars` file instead. See [Development Experience](https://bkper.com/docs/build/apps/development.md#local-secrets).
+
+### KV storage
+
+Declare KV in `bkper.yaml`:
+
+```yaml
+deployment:
+    services:
+        - KV
+```
+
+The platform provisions a KV namespace for your app. Access it via `c.env.KV`:
+
+```ts
+await c.env.KV.put('key', 'value', { expirationTtl: 3600 });
+const value = await c.env.KV.get('key');
+```
+
+KV storage is separate between production and preview environments.
+
+## Deployment status
+
+Check the current state of your deployment:
+
+```bash
+bkper app status
+```
+
+## Installing on books
+
+After deploying, install the app on specific books to activate it:
+
+```bash
+# Install on a book
+bkper app install <appId> -b <bookId>
+
+# Uninstall from a book
+bkper app uninstall <appId> -b <bookId>
+```
+
+Once installed, the app's [event handlers](https://bkper.com/docs/build/apps/event-handlers.md) receive events from that book at `/events`, and the app's [context menu](https://bkper.com/docs/build/apps/context-menu.md) appears in the book's UI.
+
+## Next steps
+
+- [Shared App Source](https://bkper.com/docs/build/apps/shared-app-source.md) — Share private source without coupling Git pushes to deployment
+- [Development Experience](https://bkper.com/docs/build/apps/development.md) — Run the app and event delivery locally
+- [App Listing](https://bkper.com/docs/build/apps/app-listing.md) — Prepare the app for installation

package/lib/docs/apps/development.md

@@ -0,0 +1,122 @@
+# Development Experience
+
+Local development uses two composable processes — the worker runtime and the client dev server — that run concurrently.
+
+## What runs
+
+```bash
+npm run dev
+```
+
+The project template runs both processes via `concurrently`:
+
+1. **`vite dev`** — Client dev server with HMR. Changes to Lit components reflect instantly in the browser. Configured in `client/vite.config.ts`.
+2. **`bkper app dev`** — The worker runtime:
+    - **Miniflare** — Simulates the single Cloudflare Worker locally.
+    - **Cloudflare tunnel** — Exposes `/events` via a public URL so Bkper can route webhook events to your machine.
+    - **File watching** — Server changes trigger automatic rebuilds via esbuild.
+
+You can also run them independently: `npm run dev:client` for just the UI, or `npm run dev:server` for the local Worker.
+
+## URLs
+
+| Endpoint                               | URL                                         |
+| -------------------------------------- | ------------------------------------------- |
+| Client (Vite dev server)               | `http://localhost:5173`                     |
+| Server Worker (Miniflare)              | `http://localhost:8787`                     |
+| App API routes                         | `http://localhost:8787/api/*`               |
+| App OpenAPI spec                       | `http://localhost:8787/openapi.json`        |
+| Events (via tunnel to the same Worker) | `https://<random>.trycloudflare.com/events` |
+
+The Vite dev server proxies `/api` requests to `http://localhost:8787` through `client/vite.config.ts`. The app OpenAPI spec is served by the Worker at `http://localhost:8787/openapi.json`. The tunnel URL is automatically registered as `webhookUrlDev`, so development-mode events are routed to your local machine.
+
+## Configuration flags
+
+There is one local Worker. Override its port when needed:
+
+```bash
+bkper app dev --sp 8787
+```
+
+## Client configuration
+
+The client dev server is configured in `client/vite.config.ts`. This standard Vite configuration registers local auth middleware and proxies `/api` requests to the Worker.
+
+### Local development authentication
+
+During local development, the Vite dev server runs `createBkperAuthMiddleware()` from `bkper/dev`. It serves the local `/auth/refresh` endpoint used by `@bkper/web-auth`, obtaining OAuth tokens from your CLI credentials.
+
+The separate Vite proxy configuration forwards `/api` requests to the Miniflare Worker.
+
+Before starting development, run:
+
+```bash
+bkper auth login   # one-time setup
+```
+
+Then `npm run dev` handles local authentication. Direct `bkper-js` calls use `auth.getAccessToken()`, while the typed app API client uses `auth.authenticatedFetch()` to attach and refresh bearer authentication.
+
+Local outbound uses your CLI credentials when the app server or event handler calls Bkper.
+
+If you see authentication errors in the browser, verify you're logged in:
+
+```bash
+bkper auth token   # should print a token
+```
+
+This is the canonical pattern for local development. Do not manually pass tokens or implement custom auth flows.
+
+## Local secrets
+
+Environment variables for local development live in a `.dev.vars` file at the project root:
+
+```bash
+# .dev.vars (gitignored)
+EXTERNAL_SERVICE_TOKEN=your-token-here
+```
+
+Copy from the provided template:
+
+```bash
+cp .dev.vars.example .dev.vars
+```
+
+These variables are available as `c.env.SECRET_NAME` in your Hono handlers during development.
+
+## KV storage
+
+KV data persists locally in the `.mf/kv/` directory during development. This means your data survives restarts — useful for testing caching and state patterns.
+
+```ts
+// Read
+const value = await c.env.KV.get('my-key');
+
+// Write with TTL
+await c.env.KV.put('my-key', 'value', { expirationTtl: 3600 });
+```
+
+See the [Cloudflare KV documentation](https://developers.cloudflare.com/kv/) for more usage patterns.
+
+## Type generation
+
+The `env.d.ts` file provides TypeScript types for the Worker environment — KV bindings, secrets, and other platform services. It's auto-generated based on your `bkper.yaml` configuration and checked into version control.
+
+Rebuild it after changing services or secrets in `bkper.yaml`:
+
+```bash
+bkper app build
+```
+
+## The development loop
+
+1. Run `npm run dev`.
+2. Edit client code and use Vite HMR.
+3. Edit server code and let the Worker reload.
+4. Trigger events in Bkper and inspect handler responses in the activity stream.
+5. Run `npm run check` before considering the change complete.
+
+## Debugging
+
+- **Server errors** — Check the terminal output from `bkper app dev`. Worker runtime errors appear here.
+- **Event handler errors** — Check the Bkper activity stream. Click on an event handler response to see the result or error, and replay failed events.
+- **Client errors** — Use browser DevTools. The Vite dev server provides source maps.

package/lib/docs/apps/event-handlers.md

@@ -0,0 +1,248 @@
+# Event Handlers
+
+Event handlers are the code that reacts to events in your Bkper Books. When a transaction is checked, an account is created, or any other event occurs, your handler receives it and can take action — calculate taxes, sync data between books, post to external services, and more.
+
+![Bkper Event Handler](https://bkper.com/images/bots/bkper-tax-bot/bkper-tax-bot.gif)
+
+## How it works
+
+1. You declare which events your app handles in [`bkper.yaml`](https://bkper.com/docs/build/apps/configuration.md)
+2. Bkper sends an HTTP POST to your webhook URL when those events fire
+3. Your handler processes the event and returns a response
+
+On the [Bkper Platform](https://bkper.com/docs/build/apps/overview.md), events are routed to `/events` on your app's single Worker — including local development via tunnels. For [self-hosted](https://bkper.com/docs/build/apps/self-hosted.md) setups, you configure the webhook URL directly.
+
+## Agent identity
+
+Event handlers **run on behalf of the user who installed the app**. Their transactions and activities are identified in the UI by the app's logo and name:
+
+![Event handler agents identified in the activity stream](https://bkper.com/docs/_astro/bkper-bot-agents.CtsWIZEd.png)
+
+## Responses
+
+Handler responses are recorded in the activity that triggered the event. You can view and replay them by clicking the response at the bottom of the activity:
+
+![Event handler responses in the activity stream](https://bkper.com/docs/_astro/bkper-bot-responses.UQXhqdai.png)
+
+### Response format
+
+Your handler must return a response in this format:
+
+```ts
+{ result?: string | string[] | boolean; error?: string; warning?: string }
+```
+
+- The `result` is recorded as the handler response in the book activity
+- If you return `{ result: false }`, the response is suppressed and not recorded
+- Errors like `{ error: "This is an error" }` show up as error responses
+
+To show the full error stack trace for debugging:
+
+```ts
+try {
+    // handler logic
+} catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+}
+```
+
+### HTML in responses
+
+If you return an **HTML snippet** (e.g., a link) in the result, it will be rendered in the response popup.
+
+## Development mode
+
+Event handlers run in _Development Mode_ when executed by the **developer or owner** of the App.
+
+In development mode, both successful results and errors are shown as responses:
+
+![Event handler error in development mode](https://bkper.com/docs/_astro/bkper-bot-error.4eq2AKEM.png)
+
+You can click a response to **replay** failed executions — useful for debugging without recreating the triggering event.
+
+To find transactions with bot errors in a book, run the query:
+
+```
+error:true
+```
+
+## Preventing loops
+
+When your event handler creates or modifies transactions, those changes fire new events. To prevent infinite loops, check the `event.agent.id` field:
+
+```ts
+function handleEvent(event: bkper.Event) {
+    // Skip events triggered by this app
+    if (event.agent?.id === 'your-app-id') {
+        return { result: false };
+    }
+
+    // Process the event
+    // ...
+}
+```
+
+This pattern is essential for any handler that writes back to the same book.
+
+## Authentication
+
+Platform-hosted event handlers use the same server-side Bkper API pattern as `/api/*` routes:
+
+```ts
+const bkper = new Bkper();
+const book = new Book(event.book, bkper.getConfig());
+```
+
+Dispatch consumes the event delivery token, strips platform headers before your Worker runs, and platform outbound auth injects the OAuth token and app agent identity on Bkper API calls.
+
+Do not read `bkper-oauth-token`, `bkper-agent-id`, or `Authorization` headers in platform app code.
+
+> **Note**
+> During local development, events are routed through the Cloudflare tunnel started by `bkper app dev`. Local outbound uses your CLI credentials when the handler calls Bkper.
+For [self-hosted](https://bkper.com/docs/build/apps/self-hosted.md) setups, the event auth headers are sent to both `webhookUrl` and `webhookUrlDev` and must be handled directly by your infrastructure.
+
+## Event routing pattern
+
+On the Bkper Platform, your server Worker uses [Hono](https://hono.dev) to receive webhook calls at `/events`. A typical pattern routes events by type:
+
+```ts
+import { Bkper, Book } from 'bkper-js';
+
+app.post('/events', async c => {
+    const event: bkper.Event = await c.req.json();
+
+    if (!event.book) {
+        return c.json({ error: 'Missing book in event payload' }, 400);
+    }
+
+    const bkper = new Bkper();
+    const book = new Book(event.book, bkper.getConfig());
+
+    switch (event.type) {
+        case 'TRANSACTION_CHECKED':
+            return c.json(await handleTransactionChecked(book, event));
+        default:
+            return c.json({ result: false });
+    }
+});
+```
+
+## The Event object
+
+The event payload has the following structure:
+
+```ts
+{
+    /** The id of the Book associated to the Event */
+    bookId?: string;
+
+    /** The Book object associated with the Event */
+    book?: {
+        agentId?: string;
+        collection?: Collection;
+        createdAt?: string;
+        datePattern?: string;
+        decimalSeparator?: "DOT" | "COMMA";
+        fractionDigits?: number;
+        id?: string;
+        lastUpdateMs?: string;
+        lockDate?: string;
+        name?: string;
+        ownerName?: string;
+        pageSize?: number;
+        period?: "MONTH" | "QUARTER" | "YEAR";
+        periodStartMonth?: "JANUARY" | "FEBRUARY" | "MARCH" | "APRIL"
+            | "MAY" | "JUNE" | "JULY" | "AUGUST" | "SEPTEMBER"
+            | "OCTOBER" | "NOVEMBER" | "DECEMBER";
+        permission?: "OWNER" | "EDITOR" | "POSTER" | "RECORDER"
+            | "VIEWER" | "NONE";
+        properties?: { [name: string]: string };
+        timeZone?: string;
+        timeZoneOffset?: number;
+    };
+
+    /** The user in charge of the Event */
+    user?: {
+        avatarUrl?: string;
+        name?: string;
+        username?: string;
+    };
+
+    /** The Event agent, such as the App, Bot or Bank institution */
+    agent?: {
+        id?: string;
+        logo?: string;
+        name?: string;
+    };
+
+    /** The creation timestamp, in milliseconds */
+    createdAt?: string;
+
+    /** The event data */
+    data?: {
+        /** The object payload. Depends on the event type. */
+        object?: any;
+        /** The object previous attributes when updated */
+        previousAttributes?: { [name: string]: string };
+    };
+
+    /** The unique id that identifies the Event */
+    id?: string;
+
+    /** The resource associated to the Event */
+    resource?: string;
+
+    /** The type of the Event */
+    type?: EventType;
+}
+```
+
+The event payload is the same structure exposed by the [REST API](https://bkper.com/docs/build/scripts/rest-api.md). If you use TypeScript, add the [`@bkper/bkper-api-types`](https://www.npmjs.com/package/@bkper/bkper-api-types) package to your project for full type definitions.
+
+For update events, `data.previousAttributes` contains the fields that changed and their previous values — useful for computing diffs or reacting only to specific field changes.
+
+## Event types
+
+Declare which events your app handles in `bkper.yaml`:
+
+```yaml
+events:
+    - TRANSACTION_CHECKED
+    - TRANSACTION_POSTED
+    - ACCOUNT_CREATED
+```
+
+The complete current set of event types:
+
+| Event | Description |
+| --- | --- |
+| `FILE_CREATED` | A file was attached to the book. |
+| `FILE_UPDATED` | An attached file was updated. |
+| `TRANSACTION_CREATED` | A draft transaction was created. |
+| `TRANSACTION_UPDATED` | A transaction was updated. |
+| `TRANSACTION_DELETED` | A transaction was deleted. |
+| `TRANSACTION_POSTED` | A draft transaction was posted and now affects balances. |
+| `TRANSACTION_CHECKED` | A posted transaction was checked (reviewed and locked). |
+| `TRANSACTION_UNCHECKED` | A checked transaction was unchecked and becomes editable again. |
+| `TRANSACTION_RESTORED` | A deleted transaction was restored. |
+| `ACCOUNT_CREATED` | An account was created. |
+| `ACCOUNT_UPDATED` | An account was updated. |
+| `ACCOUNT_DELETED` | An account was deleted. |
+| `QUERY_CREATED` | A saved query was created. |
+| `QUERY_UPDATED` | A saved query was updated. |
+| `QUERY_DELETED` | A saved query was deleted. |
+| `GROUP_CREATED` | A group was created. |
+| `GROUP_UPDATED` | A group was updated. |
+| `GROUP_DELETED` | A group was deleted. |
+| `COMMENT_CREATED` | A comment was added. |
+| `COMMENT_DELETED` | A comment was deleted. |
+| `COLLABORATOR_ADDED` | A collaborator was added to the book. |
+| `COLLABORATOR_UPDATED` | A collaborator's permissions were updated. |
+| `COLLABORATOR_REMOVED` | A collaborator was removed from the book. |
+| `INTEGRATION_CREATED` | An integration was created in the book. |
+| `INTEGRATION_UPDATED` | An integration was updated. |
+| `INTEGRATION_DELETED` | An integration was deleted. |
+| `BOOK_CREATED` | A book was created. |
+| `BOOK_AUDITED` | A balances audit completed for the book. |
+| `BOOK_UPDATED` | Book settings were updated. |
+| `BOOK_DELETED` | The book was deleted. |

package/lib/docs/apps/first-app.md

@@ -0,0 +1,76 @@
+# Your First App
+
+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.
+
+## Prerequisites
+
+[Development Setup](https://bkper.com/docs/build/getting-started/setup.md) — the CLI installed and authenticated.
+
+## Walkthrough
+
+1. **Scaffold from the template**
+
+    ```bash
+    bkper app init my-app
+    cd my-app
+    ```
+
+    `bkper app init my-app` creates `./my-app` and uses `my-app` as the app id. The CLI sets your 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.
+
+2. **Install and start developing**
+
+    ```bash
+    npm install
+    npm run dev
+    ```
+
+    This runs the Vite client dev server and the local Worker runtime with automatic event tunneling. See [Development Experience](https://bkper.com/docs/build/apps/development.md) for details.
+
+3. **Open the app**
+
+    Visit [http://localhost:5173](http://localhost:5173). Select a book to see account balances. No OAuth setup required — the platform handles authentication.
+
+4. **Trigger an event**
+
+    Go to any Bkper book and check a transaction. The event handler creates a 20% draft using the original from and to Accounts. It does not affect balances unless posted. See [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md) for the full event model.
+
+5. **Make a change**
+
+    Edit `server/src/events/handlers/transaction-checked.ts` and save. The Worker reloads automatically. Check another transaction to see your change.
+
+6. **Customize your listing**
+
+    Update `bkper.yaml` with your app's description and owner details. Replace the placeholder logos in `client/public/images/`. See [App Listing](https://bkper.com/docs/build/apps/app-listing.md) for publishing details.
+
+7. **Update the README**
+
+    Edit `README.md` for end users — what the app does and how to use it. If your app exposes `/api/*` routes for users or integrators, include the app API base URL, `/openapi.json` URL, and one minimal authenticated example. Keep deeper developer docs in `AGENTS.md`.
+
+8. **Establish shared source**
+
+    Review the app, create its first commit, and sync it:
+
+    ```bash
+    git add .
+    git commit -m "Initial app"
+    bkper app sync
+    ```
+
+    For an eligible standalone app without an external remote, sync creates private Bkper-managed source and configures it as `origin`. Authorized teammates and coding agents can then clone the same codebase with `bkper app clone my-app`. See [Shared App Source](https://bkper.com/docs/build/apps/shared-app-source.md) for access rules and other source workflows.
+
+9. **Check and deploy**
+
+    ```bash
+    npm run check
+    npm run deploy
+    ```
+
+    Deployment is explicit: syncing or pushing source does not deploy the app. 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.
+
+## Next steps
+
+- [Shared App Source](https://bkper.com/docs/build/apps/shared-app-source.md) — Clone and improve one private app codebase together
+- [App Architecture](https://bkper.com/docs/build/apps/architecture.md) — Understand the single Worker client/server structure
+- [App Configuration](https://bkper.com/docs/build/apps/configuration.md) — Full `bkper.yaml` reference
+- [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md) — All event types and patterns
+- [Building & Deploying](https://bkper.com/docs/build/apps/deploying.md) — Preview environments and secrets