bkper 4.25.0 → 4.26.1

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

package/lib/docs/apps/overview.md

@@ -0,0 +1,106 @@
+# The Bkper Platform
+
+The Bkper Platform is a complete managed environment for building, deploying, and hosting apps on Bkper. It removes infrastructure complexity so you can focus on business logic.
+
+### Hosting
+
+Apps are deployed to `{appId}.bkper.app` on a global edge network powered by [Cloudflare Workers for Platforms](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/). Your app runs close to your users, with zero infrastructure to manage.
+
+Preview environments are built in — deploy to a preview URL to test before going to production.
+
+### App APIs
+
+The same Worker can expose app-defined `/api/*` routes. Treat those routes as the reusable contract for your app behavior:
+
+- The bundled web client can call them.
+- Scripts, external clients, and agents can call them too.
+- The default template documents them with an app OpenAPI spec at `/openapi.json`.
+
+### AI inference
+
+When an app needs model inference, use Bkper AI by default. An authenticated app API route or event establishes the user and app identity, then platform outbound supplies authorization and usage attribution for the Worker's Bkper AI requests. The app does not need provider credentials.
+
+See [Add Bkper AI to an App](https://bkper.com/docs/build/apps/ai.md) for live model discovery, strict structured output, validation, and the client-to-Worker authentication flow.
+
+### Authentication
+
+OAuth is pre-configured. No client IDs, no redirect URIs, no consent screens to build.
+
+- **Web client** — Use `@bkper/web-auth`: `auth.getAccessToken()`. See [App Architecture → Client authentication](https://bkper.com/docs/build/apps/architecture.md#client-authentication).
+- **Server API routes** — Send `Authorization: Bearer <token>` to `/api/*`; dispatch validates it and platform outbound injects auth for server-side Bkper API calls. See [App Architecture → Server API authentication](https://bkper.com/docs/build/apps/architecture.md#server-api-authentication).
+- **Event handlers** — Handle `/events` in the same Worker and call Bkper with server-side `new Bkper()`; dispatch/outbound handle auth and agent identity. See [Event Handlers → Authentication](https://bkper.com/docs/build/apps/event-handlers.md#authentication).
+- **Local development** — The Vite auth middleware uses your CLI credentials. See [Development Experience → Local development authentication](https://bkper.com/docs/build/apps/development.md#local-development-authentication).
+
+### Services
+
+Declare the services you need in [`bkper.yaml`](https://bkper.com/docs/build/apps/configuration.md) and the platform provisions them:
+
+- **KV storage** — Key-value storage for caching and state. Access via `c.env.KV` in your handlers.
+- **Secrets** — Securely stored environment variables. Set via `bkper app secrets put`, access via `c.env.SECRET_NAME`.
+
+### Developer experience
+
+The project template composes the full development environment:
+
+```bash
+npm run dev
+```
+
+This runs two processes concurrently: `vite dev` for the client UI (HMR), and `bkper app dev` for the Worker runtime (Miniflare for `/api/*` and `/events`, plus a Cloudflare tunnel so Bkper can route webhook events to your laptop). Your entire development environment, running locally.
+
+### Shared app source
+
+Bkper can host one private codebase for your app. Authorized teammates and coding agents can clone it, improve it locally, and continue building from the same shared history.
+
+Source synchronization remains separate from deployment. A Git push stores source but never builds or deploys the app.
+
+See [Shared App Source](https://bkper.com/docs/build/apps/shared-app-source.md) for the collaboration workflow, access rules, and external Git options.
+
+### Deployment
+
+Check and deploy the app template:
+
+```bash
+npm run check
+npm run deploy
+```
+
+Your app is live at `{appId}.bkper.app`. The platform handles routing, SSL, and edge distribution.
+
+## What you'd build yourself without it
+
+Without the platform, creating a Bkper app with a UI, event handling, and authentication requires:
+
+| Concern                  | Without the platform                                                                    | With the platform                               |
+| ------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| **Hosting**              | Provision servers, configure domains, SSL, CDN                                          | `bkper app deploy`                              |
+| **Authentication**       | Register OAuth client, build consent screen, handle token refresh, manage redirect URIs | `auth.getAccessToken()`                         |
+| **Event webhooks**       | Set up a public endpoint, configure DNS, handle JWT verification                        | Declare in `bkper.yaml`, platform routes events |
+| **Local dev webhooks**   | Install ngrok or similar, manually configure tunnel URL                                 | `bkper app dev` starts tunnel automatically     |
+| **Secrets**              | Set up a secrets manager, configure access                                              | `bkper app secrets put`                         |
+| **KV storage**           | Deploy Redis/Memcached, manage connections                                              | Declare `KV` in `bkper.yaml`                    |
+| **Preview environments** | Build a staging pipeline                                                                | `bkper app deploy --preview`                    |
+| **Shared app source**    | Operate a separate private Git host                                                     | Managed source for app developers and agents    |
+| **Type safety**          | Manually create type definitions                                                        | `env.d.ts` auto-generated                       |
+
+The platform eliminates all of this. You write business logic, the platform handles infrastructure.
+
+## Getting started
+
+```bash
+# Create a new app from the template
+bkper app init my-app
+cd my-app
+
+# Install dependencies and start developing
+npm install
+npm run dev
+```
+
+This gives you a working app with a client UI, server API routes, and `/events` handling in one Worker — all running locally with full HMR and webhook tunneling.
+
+## Next steps
+
+- [Your First App](https://bkper.com/docs/build/apps/first-app.md) — Build and deploy a complete platform app
+- [Shared App Source](https://bkper.com/docs/build/apps/shared-app-source.md) — Collaborate from one private codebase
+- [App Architecture](https://bkper.com/docs/build/apps/architecture.md) — Understand how platform apps are structured

package/lib/docs/apps/self-hosted.md

@@ -0,0 +1,63 @@
+# Self-Hosted Alternative
+
+The [Bkper Platform](https://bkper.com/docs/build/apps/overview.md) handles hosting, authentication, and deployment for you. However, you can host event handlers on your own infrastructure if you have specific requirements — existing cloud setup, compliance constraints, or legacy apps.
+
+> **Tip**
+> Use the Bkper Platform unless you have a specific reason to self-host. It eliminates the need to manage authentication, secrets, hosting, and deployment yourself.
+## Cloud Functions
+
+A Bkper event handler running on [Google Cloud Functions](https://cloud.google.com/functions/) receives authenticated calls from the `bkper-hrd@appspot.gserviceaccount.com` service account. You need to grant this service account the [Cloud Functions Invoker IAM role](https://cloud.google.com/functions/docs/securing/managing-access-iam) (`roles/cloudfunctions.invoker`).
+
+Set the production endpoint in [`bkper.yaml`](https://bkper.com/docs/build/apps/configuration.md):
+
+```yaml
+webhookUrl: https://us-central1-my-project.cloudfunctions.net/events
+```
+
+### Authentication
+
+An OAuth Access Token **of the user who installed the app** is sent to the production `webhookUrl` endpoint in the `bkper-oauth-token` HTTP header, along with the agent identifier in `bkper-agent-id`, on each event. Your handler uses this token to call the API back on behalf of the user.
+
+Both production (`webhookUrl`) and development (`webhookUrlDev`) endpoints receive OAuth tokens in the `bkper-oauth-token` header.
+
+### Throughput and scaling
+
+Event throughput can be high, especially when processing large batches. Set the [max instance limit](https://cloud.google.com/functions/docs/max-instances#setting_max_instances_limits) — usually **1-2 is enough**. When the function returns `429 Too Many Requests`, the event is automatically retried with incremental backoff until it receives an HTTP `200`.
+
+### Response format
+
+The function response must follow the standard format:
+
+```ts
+{ result?: any, error?: any }
+```
+
+See [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md#response-format) for details on response handling.
+
+### Considerations
+
+- Execution environment is subject to [Cloud Function Quotas](https://cloud.google.com/functions/quotas) — quota counts against the developer account, not the end user
+- Recommended for scenarios where event throughput exceeds **1 event/second/user** and processing can be handled asynchronously
+- Can be combined with context menus built with [Apps Script HTML Service](https://developers.google.com/apps-script/guides/html) or any other UI infrastructure
+
+---
+
+## Generic Webhooks
+
+You can host event handlers on any infrastructure — other cloud providers, containers, on-premise servers.
+
+Configure the same `webhookUrl` property in [`bkper.yaml`](https://bkper.com/docs/build/apps/configuration.md):
+
+```yaml
+webhookUrl: https://my-server.example.com/bkper/events
+```
+
+### Authentication
+
+Calls to the production webhook URL are signed with a JWT token using the [Service to Function](https://cloud.google.com/functions/docs/securing/authenticating#service-to-function) method. You can verify this token to assert the identity of the Bkper service.
+
+> **Note**
+> Cloud Functions handles JWT verification automatically. For other infrastructure, you need to implement verification yourself. We strongly recommend Cloud Functions for this reason.
+### Retry behavior
+
+If your infrastructure returns an HTTP `429` status, the event is automatically retried with incremental backoff until it receives an HTTP `200`. Use this to handle temporary overload gracefully.