bkper 4.24.3 → 4.26.0

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

@@ -0,0 +1,86 @@
+# App Listing
+
+All Bkper apps are listed on the Automations Portal at _[app.bkper.com](https://app.bkper.com/) > Automations > Apps_. Each app has its own page with logo, description, and details:
+
+![App listing on the Automations Portal](https://bkper.com/docs/_astro/bkper-app-listing.BgcbAsjE.png)
+
+App listings are populated from the fields you declare in [`bkper.yaml`](https://bkper.com/docs/build/apps/configuration.md). Sync metadata changes with `bkper app sync`. Deploying code is a separate step.
+
+## Listing fields
+
+Make sure your `bkper.yaml` has the following fields populated for a complete listing:
+
+```yaml
+id: your-app-id
+name: Your App Name
+description: A clear description of what your app does
+
+logoUrl: https://your-app.bkper.app/images/logo.svg
+logoUrlDark: https://your-app.bkper.app/images/logo-dark.svg
+
+ownerName: Your Name or Organization
+ownerWebsite: https://yourwebsite.com
+
+website: https://your-app.bkper.app
+```
+
+See [App Configuration](https://bkper.com/docs/build/apps/configuration.md) for the full `bkper.yaml` reference.
+
+## Default visibility
+
+By default, installation is limited to the users you've declared in `bkper.yaml`:
+
+```yaml
+# Specific Bkper usernames
+users: alice bob
+
+# Your entire domain
+users: *@yourcompany.com
+```
+
+Use Bkper usernames for individual access, not email addresses.
+
+Your team can install and use the app, but it doesn't appear in the public Bkper app directory for other users.
+
+## Publishing to all users
+
+To make your app available to all Bkper users, contact us at [support@bkper.com](mailto:support@bkper.com?subject=Publish+Bkper+App). We'll review your app and, once approved, publish it.
+
+### What the review involves
+
+- **Functionality check** — The app works correctly and handles errors gracefully
+- **Security review** — Event handlers are idempotent and include loop prevention
+- **Listing quality** — The app has a clear name, description, logo, and user-facing documentation
+
+### README matters
+
+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.
+
+**README should explain:**
+
+- What the app does from a user's perspective
+- How to use it (step-by-step for non-technical users)
+- What features are available
+- API access details when the app intentionally exposes `/api/*` routes for users or integrators
+
+**API access details should stay concise:**
+
+- App base URL for production and preview
+- OpenAPI spec URL at `/openapi.json`
+- One minimal authenticated example, such as a `curl` call with `Authorization: Bearer <token>`
+
+**README should NOT contain:**
+
+- Tech stack or architecture details
+- Build commands or development setup
+- Project structure or internal file paths
+- Long API references, generated schemas, SDK internals, or route-by-route developer docs
+
+Put developer documentation in `AGENTS.md` or internal docs instead. Keep `README.md` focused on the user experience and any integration entry points users need.
+
+### Where published apps appear
+
+Once published, your app appears in:
+
+- **[bkper.com/apps](https://bkper.com/apps)** — The public app directory
+- **Automations Portal** — Inside every Bkper book, users can find and install your app

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.