bkper 4.25.0 → 4.26.1

package/lib/docs/apps/architecture.md

@@ -0,0 +1,188 @@
+# App Architecture
+
+Bkper platform apps use one Worker bundle per app and environment. The same Worker serves the browser client, app-defined `/api/*` routes, and Bkper event ingress at `/events`.
+
+Treat `/api/*` as the reusable surface for app behavior. The bundled web client is one consumer; scripts, external clients, and agents can call the same routes with bearer authentication.
+
+## Structure
+
+```txt
+my-app/
+├── client/
+│   ├── index.html
+│   ├── package.json
+│   ├── vite.config.ts
+│   └── src/
+│       ├── api/
+│       ├── app/
+│       ├── auth/
+│       ├── components/
+│       └── services/
+├── server/
+│   ├── package.json
+│   └── src/
+│       ├── api/
+│       ├── events/
+│       ├── services/
+│       └── index.ts
+├── scripts/
+├── bkper.yaml
+├── env.d.ts
+├── package.json
+├── package-lock.json
+└── tsconfig.json
+```
+
+The root npm workspace orchestrates development, tests, builds, and deployment. The template keeps browser dependencies in `client/` and Worker dependencies in `server/`. Add a shared package only when both sides actually need one.
+
+## Client
+
+The client uses:
+
+- [Lit](https://lit.dev/) for components and rendering.
+- [Web Awesome](https://webawesome.com/) for UI components.
+- [`@bkper/web-design`](https://www.npmjs.com/package/@bkper/web-design) for Bkper design tokens.
+- [Vite](https://vitejs.dev/) for development and production builds, configured in `client/vite.config.ts`.
+
+Client code has two data paths:
+
+- **Direct Bkper calls** use `bkper-js` for browser-specific behavior.
+- **App API calls** use the generated typed client in `client/src/api/` with `auth.authenticatedFetch()`.
+
+### Client authentication
+
+The client authenticates users with [`@bkper/web-auth`](https://www.npmjs.com/package/@bkper/web-auth). OAuth is preconfigured on the platform, so there are no client IDs, redirect URIs, or consent screens to configure.
+
+```ts
+import { Bkper } from 'bkper-js';
+import { BkperAuth } from '@bkper/web-auth';
+
+const isLocalDev = ['localhost', '127.0.0.1'].includes(window.location.hostname);
+const auth = new BkperAuth({
+    baseUrl: isLocalDev ? window.location.origin : undefined,
+    onLoginSuccess: () => initializeApp(),
+    onLoginRequired: () => showLoginButton(),
+});
+await auth.init();
+
+const bkper = new Bkper({
+    oauthTokenProvider: async () => auth.getAccessToken(),
+});
+```
+
+`@bkper/web-auth` handles login, redirects, and token refresh. The template keeps this behavior behind `client/src/auth/auth-session.ts`.
+
+See the [@bkper/web-auth API Reference](https://bkper.com/docs/api/bkper-web-auth.md) for the full SDK documentation.
+
+## Server Worker
+
+The server runs on [Cloudflare Workers](https://developers.cloudflare.com/workers/) and uses [Hono](https://hono.dev/) with typed OpenAPI routes. It handles:
+
+- app API routes under `/api/*`;
+- Bkper event ingress under `/events`;
+- platform services such as KV and secrets through `c.env`;
+- static client assets through the `ASSETS` binding.
+
+The Worker entry point composes those concerns while routes delegate business behavior to services:
+
+```ts
+import { OpenAPIHono } from '@hono/zod-openapi';
+import { registerApiRoutes } from './api/routes.js';
+import { registerEventRoutes } from './events/routes.js';
+import { appContextMiddleware, type AppEnv } from './app-context.js';
+
+const app = new OpenAPIHono();
+
+app.use('/api/*', appContextMiddleware());
+app.use('/events', appContextMiddleware());
+registerApiRoutes(app);
+registerEventRoutes(app);
+
+app.get('*', c => c.env.ASSETS.fetch(c.req.raw));
+
+export default app;
+```
+
+## App API contract
+
+The default template publishes versioned routes under `/api/v1/*` and exposes their OpenAPI contract at `/openapi.json`.
+
+| Concern                      | Location                              |
+| ---------------------------- | ------------------------------------- |
+| OpenAPI metadata             | `server/src/api/openapi.ts`           |
+| Request and response schemas | `server/src/api/schemas.ts`           |
+| Thin route handlers          | `server/src/api/routes.ts`            |
+| Business behavior            | `server/src/services/`                |
+| Generated client types       | `client/src/api/generated/types.d.ts` |
+| Typed client wrapper         | `client/src/api/app-api.ts`           |
+| Contract snapshot            | `server/test/openapi.snapshot.json`   |
+
+When changing the API:
+
+1. Update schemas, services, routes, and focused unit tests.
+2. Run `npm run api` to regenerate client types.
+3. Review the OpenAPI snapshot when the public contract changes.
+4. Run `npm run check` before release.
+
+Keep existing `/api/v1/*` contracts backward compatible. Additive fields and routes can remain in `v1`; breaking changes belong in a new namespace such as `/api/v2/*`.
+
+### URLs
+
+```txt
+Production API: https://{appId}.bkper.app/api/*
+Preview API:    https://{appId}-preview.bkper.app/api/*
+Local API:      http://localhost:8787/api/*
+
+Production spec: https://{appId}.bkper.app/openapi.json
+Preview spec:    https://{appId}-preview.bkper.app/openapi.json
+Local spec:      http://localhost:8787/openapi.json
+```
+
+Example script call:
+
+```bash
+TOKEN="$(bkper auth token)"
+
+curl \
+  -H "Authorization: Bearer ${TOKEN}" \
+  "https://my-app.bkper.app/api/v1/books"
+```
+
+Replace `my-app` with the app id from `bkper.yaml`.
+
+### Server API authentication
+
+Deployed `/api/*` routes require a Bkper OAuth bearer token. The template client uses `authenticatedFetch()` so token attachment and refresh stay inside `@bkper/web-auth`:
+
+```ts
+const response = await auth.authenticatedFetch('/api/v1/books');
+```
+
+Dispatch validates the incoming bearer token and strips the `Authorization` header before the Worker runs. Server code should not read or forward the token.
+
+When a route calls Bkper, create the SDK without a token provider:
+
+```ts
+import { Bkper } from 'bkper-js';
+
+const bkper = new Bkper();
+const books = await bkper.getBooks();
+```
+
+Platform outbound authentication injects the validated user's OAuth token on Bkper API requests.
+
+## Event handlers
+
+Platform event deliveries reach `/events` on the same Worker. Event adapters live in `server/src/events/`, while reusable business behavior belongs in `server/src/services/`.
+
+Event code uses server-side `new Bkper()` and must not read `bkper-oauth-token`, `bkper-agent-id`, or `Authorization` headers. Dispatch and platform outbound authentication handle the event token and app agent identity.
+
+See [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md) for routing, responses, loop prevention, and event types. Self-hosted handlers process event authentication directly because the platform outbound layer is not involved.
+
+## App shapes
+
+The platform supports different shapes:
+
+- **Full app** — Client UI, `/api/*` backend behavior, and `/events` automation in one Worker. This is the default template.
+- **Event-only app** — Keep `server/` and omit `deployment.client`.
+- **UI-only app** — Keep a minimal Worker for static assets when behavior is truly browser-only. Add `/api/*` when scripts, integrations, or agents should reuse that behavior.

package/lib/docs/apps/configuration.md

@@ -0,0 +1,171 @@
+# App Configuration
+
+The `bkper.yaml` file is the single configuration file for your Bkper app. It defines the app's identity, access control, menu integration, event handling, and deployment settings.
+
+It lives in the root of your project. Use `bkper app sync` to push metadata changes to Bkper, and use `bkper app deploy` to upload built code to the platform.
+
+## Minimal example
+
+```yaml
+id: my-app
+name: My App
+description: A Bkper app that does something useful
+developers: myuser
+```
+
+## Starter example
+
+From the [app template](https://github.com/bkper/bkper-app-template):
+
+```yaml
+id: my-app
+name: My App
+description: A Bkper app that does something useful
+
+logoUrl: https://my-app.bkper.app/images/logo-light.svg
+logoUrlDark: https://my-app.bkper.app/images/logo-dark.svg
+
+website: https://my-app.bkper.app
+ownerName: Bkper
+ownerLogoUrl: https://avatars.githubusercontent.com/u/11943086?v=4
+ownerWebsite: https://bkper.com
+
+developers: someuser *@yoursite.com
+users: someuser *@yoursite.com
+
+menuUrl: https://my-app.bkper.app?bookId=${book.id}
+menuUrlDev: https://my-app-preview.bkper.app?bookId=${book.id}
+menuOpenMode: SIDEBAR
+
+webhookUrl: https://my-app.bkper.app/events
+webhookUrlDev: https://my-app-preview.bkper.app/events
+apiVersion: v5
+events:
+    - TRANSACTION_CHECKED
+
+deployment:
+    server: server/src/index.ts
+    client: client
+    services:
+        - KV
+    secrets: []
+    compatibility_date: '2026-01-28'
+```
+
+### App identity
+
+| Field         | Description                                                                                               |
+| ------------- | --------------------------------------------------------------------------------------------------------- |
+| `id`          | Permanent app identifier. Lowercase letters, numbers, and hyphens only. Cannot be changed after creation. |
+| `name`        | Display name shown in the Bkper UI.                                                                       |
+| `description` | Brief description of what the app does.                                                                   |
+
+### Branding
+
+| Field         | Description                                |
+| ------------- | ------------------------------------------ |
+| `logoUrl`     | App logo for light mode (SVG recommended). |
+| `logoUrlDark` | App logo for dark mode.                    |
+| `website`     | App website or documentation URL.          |
+
+### Ownership
+
+| Field          | Description                                                  |
+| -------------- | ------------------------------------------------------------ |
+| `ownerName`    | Developer or company name.                                   |
+| `ownerLogoUrl` | Owner's logo/avatar URL.                                     |
+| `ownerWebsite` | Owner's website.                                             |
+| `repoUrl`      | Source code repository URL.                                  |
+| `repoPrivate`  | Whether the repository is private.                           |
+| `deprecated`   | Hides from app listings; existing installs continue working. |
+
+### Access control
+
+| Field        | Description                                                                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `developers` | Who can update the app and deploy new versions. Accepts comma- or space-separated Bkper usernames and domain wildcards such as `*@yoursite.com`. |
+| `users`      | Who can install and use the app. Uses the same format as `developers`; leave empty for public apps.                                              |
+
+### Menu integration
+
+| Field          | Description                                                                 |
+| -------------- | --------------------------------------------------------------------------- |
+| `menuUrl`      | Production menu URL. Supports [variable substitution](#menu-url-variables). |
+| `menuUrlDev`   | Development menu URL, typically a preview or local app URL.                 |
+| `menuText`     | Custom menu text (defaults to app name).                                    |
+| `menuOpenMode` | How the app menu opens: `SIDEBAR` (default), `EXPANDED`, or `NEW_TAB`.      |
+
+See [Context Menu](https://bkper.com/docs/build/apps/context-menu.md) for details on building menu integrations.
+
+### Menu URL variables
+
+The following variables can be used in `menuUrl` and `menuUrlDev`:
+
+| Variable                    | Description                              |
+| --------------------------- | ---------------------------------------- |
+| `${book.id}`                | Current book ID                          |
+| `${book.properties.xxx}`    | Book property value                      |
+| `${account.id}`             | Selected account ID                      |
+| `${account.name}`           | Selected account name                    |
+| `${account.properties.xxx}` | Account property value                   |
+| `${group.id}`               | Selected group ID                        |
+| `${group.name}`             | Selected group name                      |
+| `${group.properties.xxx}`   | Group property value                     |
+| `${transactions.ids}`       | Comma-separated selected transaction IDs |
+| `${transactions.query}`     | Current search query                     |
+
+### Event handling
+
+| Field           | Description                                                                         |
+| --------------- | ----------------------------------------------------------------------------------- |
+| `webhookUrl`    | Production webhook URL for receiving events.                                        |
+| `webhookUrlDev` | Development webhook URL (auto-updated by `bkper app dev`).                          |
+| `apiVersion`    | API version for event payloads (currently `v5`).                                    |
+| `events`        | List of [event types](https://bkper.com/docs/build/apps/event-handlers.md#event-types) to subscribe to. |
+
+See [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md) for details on handling events.
+
+### File patterns
+
+| Field          | Description                                                                                                            |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `filePatterns` | List of glob patterns (e.g., `*.ofx`, `*.csv`). When a matching file is uploaded, a `FILE_CREATED` event is triggered. |
+
+### Properties schema
+
+The `propertiesSchema` field defines autocomplete suggestions for custom properties in the Bkper UI, helping users discover the correct property keys and values for your app.
+
+Suggested keys must follow the same custom property rules as user-entered keys, including the 30-character maximum after normalization.
+
+```yaml
+propertiesSchema:
+    book:
+        keys:
+            - my_app_enabled
+        values:
+            - 'true'
+            - 'false'
+    group:
+        keys:
+            - my_app_category
+    account:
+        keys:
+            - my_app_sync_id
+    transaction:
+        keys:
+            - my_app_reference
+```
+
+### Deployment
+
+For apps deployed to the [Bkper Platform](https://bkper.com/docs/build/apps/overview.md):
+
+| Field                           | Description                                                                                                            |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `deployment.server`             | TypeScript entry point for the single server Worker. It serves `/api/*`, `/events`, and static assets.                 |
+| `deployment.client`             | Optional Vite/static client root. Built assets are deployed with the same Worker.                                      |
+| `deployment.services`           | Platform services to provision. Currently: `KV` (key-value storage).                                                   |
+| `deployment.secrets`            | Secret names used by the app. Managed via `bkper app secrets`.                                                         |
+| `deployment.compatibility_date` | [Cloudflare Workers compatibility date](https://developers.cloudflare.com/workers/configuration/compatibility-dates/). |
+
+See [Building & Deploying](https://bkper.com/docs/build/apps/deploying.md) for the full deployment workflow.

package/lib/docs/apps/context-menu.md

@@ -0,0 +1,69 @@
+# Context Menu
+
+Apps can add context menu items on the Transactions page **More** menu in your Books. This lets you open dynamically built URLs with reference to the current Book's context — the active query, selected account, date range, and more.
+
+## How it works
+
+Once you install an App with a menu configuration, a new menu item appears in your Book:
+
+![Custom menu item in the More menu](https://bkper.com/docs/_astro/bkper-report-menu.eu_pyhWe.png)
+
+When clicked, a popup opens carrying the particular context of that book at that moment:
+
+![App menu popup with book context](https://bkper.com/docs/_astro/bkper-app-menu-popup.BQ95Y-ki.png)
+
+## Configuration
+
+Configure the menu URL in your [`bkper.yaml`](https://bkper.com/docs/build/apps/configuration.md):
+
+```yaml
+menuUrl: https://my-app.bkper.app?bookId=${book.id}&query=${transactions.query}
+```
+
+When the user clicks the menu item, the URL expressions `${xxxx}` are replaced with contextual information from the Book:
+
+```
+https://my-app.bkper.app?bookId=abc123&query=account:Sales
+```
+
+Where `abc123` is the current Book id and `account:Sales` is the current query being executed.
+
+### Development URL
+
+Use `menuUrlDev` to keep developer testing separate from production. The app template points it to the preview deployment:
+
+```yaml
+menuUrl: https://my-app.bkper.app?bookId=${book.id}&query=${transactions.query}
+menuUrlDev: https://my-app-preview.bkper.app?bookId=${book.id}&query=${transactions.query}
+```
+
+During local development, you can instead point it to the local Worker URL at `http://localhost:8787`. The development URL is used when an app developer clicks the menu item.
+
+### Menu open mode
+
+Control how the menu opens with `menuOpenMode`:
+
+```yaml
+menuOpenMode: SIDEBAR
+```
+
+| Mode       | Behavior                                                              |
+| ---------- | --------------------------------------------------------------------- |
+| `SIDEBAR`  | Opens in a narrow side panel (default).                               |
+| `EXPANDED` | Opens in a wider panel with more room for complex UIs.                |
+| `NEW_TAB`  | Opens the menu URL in a new browser tab instead of an embedded panel. |
+
+### Available expressions
+
+The menu URL supports these dynamic expressions:
+
+| Expression              | Description               |
+| ----------------------- | ------------------------- |
+| `${book.id}`            | The current Book ID       |
+| `${transactions.query}` | The current query string  |
+| `${account.id}`         | The selected account ID   |
+| `${account.name}`       | The selected account name |
+| `${group.id}`           | The selected group ID     |
+| `${group.name}`         | The selected group name   |
+
+For the full list of accepted expressions, see the [Menu URL variables](https://bkper.com/docs/build/apps/configuration.md#menu-url-variables) reference.

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