bkper 4.26.1 → 4.28.1

package/lib/commands/transactions/uncheck.js

@@ -0,0 +1,29 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { getBkperInstance } from '../../bkper-factory.js';
+/**
+ * Marks a checked transaction as unchecked (editable).
+ *
+ * @param bookId - The book ID containing the transaction
+ * @param transactionId - The ID of the transaction to uncheck
+ * @returns The unchecked transaction
+ */
+export function uncheckTransaction(bookId, transactionId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const bkper = getBkperInstance();
+        const book = yield bkper.getBook(bookId);
+        const transaction = yield book.getTransaction(transactionId);
+        if (!transaction) {
+            throw new Error(`Transaction not found: ${transactionId}`);
+        }
+        return transaction.uncheck();
+    });
+}
+//# sourceMappingURL=uncheck.js.map

package/lib/commands/transactions/uncheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uncheck.js","sourceRoot":"","sources":["../../../src/commands/transactions/uncheck.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D;;;;;;GAMG;AACH,MAAM,UAAgB,kBAAkB,CACpC,MAAc,EACd,aAAqB;;QAErB,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;QAC7D,IAAI,CAAC,WAAW,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,0BAA0B,aAAa,EAAE,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,WAAW,CAAC,OAAO,EAAE,CAAC;IACjC,CAAC;CAAA"}

package/lib/commands/transactions/untrash.d.ts

@@ -0,0 +1,10 @@
+import { Transaction } from 'bkper-js';
+/**
+ * Restores a transaction from the trash.
+ *
+ * @param bookId - The book ID containing the transaction
+ * @param transactionId - The ID of the transaction to restore
+ * @returns The restored transaction
+ */
+export declare function untrashTransaction(bookId: string, transactionId: string): Promise<Transaction>;
+//# sourceMappingURL=untrash.d.ts.map

package/lib/commands/transactions/untrash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrash.d.ts","sourceRoot":"","sources":["../../../src/commands/transactions/untrash.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACpC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACtB,OAAO,CAAC,WAAW,CAAC,CAQtB"}

package/lib/commands/transactions/untrash.js

@@ -0,0 +1,29 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { getBkperInstance } from '../../bkper-factory.js';
+/**
+ * Restores a transaction from the trash.
+ *
+ * @param bookId - The book ID containing the transaction
+ * @param transactionId - The ID of the transaction to restore
+ * @returns The restored transaction
+ */
+export function untrashTransaction(bookId, transactionId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const bkper = getBkperInstance();
+        const book = yield bkper.getBook(bookId);
+        const transaction = yield book.getTransaction(transactionId);
+        if (!transaction) {
+            throw new Error(`Transaction not found: ${transactionId}`);
+        }
+        return transaction.untrash();
+    });
+}
+//# sourceMappingURL=untrash.js.map

package/lib/commands/transactions/untrash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrash.js","sourceRoot":"","sources":["../../../src/commands/transactions/untrash.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D;;;;;;GAMG;AACH,MAAM,UAAgB,kBAAkB,CACpC,MAAc,EACd,aAAqB;;QAErB,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;QAC7D,IAAI,CAAC,WAAW,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,0BAA0B,aAAa,EAAE,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,WAAW,CAAC,OAAO,EAAE,CAAC;IACjC,CAAC;CAAA"}

package/lib/docs/apps/architecture.md

@@ -14,7 +14,6 @@ my-app/
 │   ├── vite.config.ts
 │   └── src/
 │       ├── api/
-│       ├── app/
 │       ├── auth/
 │       ├── components/
 │       └── services/
@@ -44,10 +43,14 @@ The client uses:
 - [`@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:
+Client code has two data paths. Choose based on who owns the behavior:
 
-- **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()`.
+- **Direct Bkper calls** use `bkper-js` for generic Bkper data needed only by the browser UI.
+- **App API calls** use the generated typed client in `client/src/api/` with `auth.authenticatedFetch()` for app-owned behavior, especially when it needs server-only capabilities or more than one caller.
+
+Keep app-owned behavior in one place. Do not implement the same behavior separately in the UI and the app API.
+
+For stateful feature components, co-locate view, controller, and CSS files in one folder under `components/`. Simple presentational components can remain in one file.
 
 ### Client authentication
 
@@ -115,7 +118,7 @@ The default template publishes versioned routes under `/api/v1/*` and exposes th
 | 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`   |
+| Contract snapshot            | `server/test/api/openapi.snapshot.json` |
 
 When changing the API:
 
@@ -126,6 +129,30 @@ When changing the API:
 
 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/*`.
 
+### Reuse Bkper API types
+
+When an app API returns payloads from the Bkper REST API, reference the canonical types from `@bkper/bkper-api-types` instead of recreating their fields in the app. The template's balances endpoint demonstrates this with `bkper.Book`:
+
+```ts
+export const BookSchema = z
+    .custom<bkper.Book>(value => value !== undefined)
+    .openapi('Book', {
+        type: 'object',
+        additionalProperties: true,
+        'x-typescript-type': 'bkper.Book',
+    });
+```
+
+The template's API generator recognizes `x-typescript-type`, imports `@bkper/bkper-api-types`, and emits the canonical reference in `client/src/api/generated/types.d.ts`:
+
+```ts
+Book: bkper.Book;
+```
+
+Both the server and client packages include `@bkper/bkper-api-types` for local typechecking. Run `npm run api` after adding or changing these schemas.
+
+This bridge provides compile-time types but does not validate payload fields at runtime. Use it directly for trusted Bkper-owned responses. Request bodies, especially those used to create or modify Book resources, still require concrete Zod validation.
+
 ### URLs
 
 ```txt
@@ -145,7 +172,7 @@ TOKEN="$(bkper auth token)"
 
 curl \
   -H "Authorization: Bearer ${TOKEN}" \
-  "https://my-app.bkper.app/api/v1/books"
+  "https://my-app.bkper.app/api/v1/ping"
 ```
 
 Replace `my-app` with the app id from `bkper.yaml`.
@@ -155,7 +182,7 @@ Replace `my-app` with the app id from `bkper.yaml`.
 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');
+const response = await auth.authenticatedFetch('/api/v1/ping');
 ```
 
 Dispatch validates the incoming bearer token and strips the `Authorization` header before the Worker runs. Server code should not read or forward the token.
@@ -171,6 +198,12 @@ const books = await bkper.getBooks();
 
 Platform outbound authentication injects the validated user's OAuth token on Bkper API requests.
 
+### Authorize app operations
+
+Authentication identifies the Bkper user, but each app must authorize sensitive data and actions server-side. Client-side checks are not an authorization boundary.
+
+See [App Security](https://bkper.com/docs/build/apps/security.md) for domain restrictions, Book permissions, and app installation checks.
+
 ## 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/`.

package/lib/docs/apps/configuration.md

@@ -95,7 +95,9 @@ deployment:
 | `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.
+`SIDEBAR` and `EXPANDED` Apps can receive live context updates while their iframe stays loaded. `NEW_TAB` Apps receive context only in the URL used to open the tab.
+
+See [Context Menu](https://bkper.com/docs/build/apps/context-menu.md#live-context-updates) for menu URL configuration and live context updates.
 
 ### Menu URL variables
 

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

@@ -53,6 +53,53 @@ menuOpenMode: SIDEBAR
 | `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. |
 
+### Live context updates
+
+Bkper keeps embedded Apps informed of context changes without reloading the iframe, allowing them to preserve their current state. For Apps opened in `SIDEBAR` or `EXPANDED`, Bkper communicates those changes by sending the updated App URL to the iframe when its origin remains the same:
+
+```js
+{
+    type: 'bkper:app-url-changed',
+    url: 'https://my-app.bkper.app?bookId=abc123&query=account:Sales',
+}
+```
+
+Listen for the message in the App:
+
+```js
+const BKPER_ORIGIN = 'https://bkper.app';
+
+window.addEventListener('message', event => {
+    // Verify that the trusted Bkper parent sent the message.
+    if (event.source !== window.parent || event.origin !== BKPER_ORIGIN) return;
+
+    // Verify that this is a valid App URL update.
+    const message = event.data;
+    if (message?.type !== 'bkper:app-url-changed' || typeof message.url !== 'string') return;
+
+    // Parse the updated URL, ignoring malformed URL strings.
+    let nextUrl;
+    try {
+        nextUrl = new URL(message.url);
+
+        // Accept only URLs belonging to this App.
+        if (nextUrl.origin !== window.location.origin) return;
+    } catch {
+        return;
+    }
+
+    // Keep the iframe URL in sync without reloading it.
+    window.history.replaceState(window.history.state, '', nextUrl);
+
+    // Apply the validated context update.
+    handleAppUrlChange(nextUrl);
+});
+```
+
+`handleAppUrlChange` is App logic. The App can update internal state, notify components, refresh data, change its UI, or ignore the message. Bkper only communicates the new URL; it does not reload the iframe or apply the context inside the App.
+
+Apps opened with `NEW_TAB` do not receive this message. Their context is set only by the URL used to open the tab.
+
 ### Available expressions
 
 The menu URL supports these dynamic expressions:

package/lib/docs/apps/development.md

@@ -25,10 +25,10 @@ You can also run them independently: `npm run dev:client` for just the UI, or `n
 | 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`        |
+| App OpenAPI spec                       | `http://localhost:5173/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.
+The Vite dev server proxies `/api` and `/openapi.json` requests to `http://localhost:8787` through `client/vite.config.ts`, so the client and OpenAPI spec share the same local origin just as they do in production. The spec also remains available directly from 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
 
@@ -40,13 +40,13 @@ 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.
+The client dev server is configured in `client/vite.config.ts`. This standard Vite configuration registers local auth middleware and proxies `/api` and `/openapi.json` 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.
+The separate Vite proxy configuration forwards `/api` and `/openapi.json` requests to the Miniflare Worker.
 
 Before starting development, run:
 

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

@@ -1,4 +1,4 @@
-# Event Handlers
+# Bkper Webhooks and 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.
 

package/lib/docs/apps/security.md

@@ -0,0 +1,73 @@
+# App Security
+
+Bkper and each platform app have separate security responsibilities. This guide explains the platform authentication boundary and common authorization checks an app must enforce.
+
+## Authentication and authorization
+
+Authentication identifies the Bkper user making a request. The platform handles this flow for deployed apps.
+
+Authorization determines whether that user may perform a specific operation.
+
+See [App Architecture](https://bkper.com/docs/build/apps/architecture.md) for the client and server authentication flow.
+
+## Authorize app operations
+
+Platform authentication identifies the Bkper user and provides outbound authentication for server-side Bkper requests. Your app must still decide which authenticated users may perform each operation. Protect sensitive data and actions in the server API; client-side checks may improve the UI, but they are not an authorization boundary.
+
+### Restrict an internal app by user domain
+
+For an app intended only for people in one organization, authorize the authenticated user's hosted domain:
+
+```ts
+const ALLOWED_DOMAIN = 'example.com';
+
+const user = await context.bkper.getUser();
+const domain = user.getHostedDomain()?.toLowerCase();
+
+if (domain !== ALLOWED_DOMAIN) {
+    return c.json(buildApiError('FORBIDDEN', 'This app is restricted to your organization'), 403);
+}
+```
+
+### Authorize a Book-backed operation
+
+When an operation acts on a Book, use an explicit permission allowlist appropriate to that operation. For an operation that requires edit access:
+
+```ts
+import { Permission } from 'bkper-js';
+
+const EDIT_PERMISSIONS: readonly Permission[] = [Permission.EDITOR, Permission.OWNER];
+
+const book = await context.bkper.getBook(bookId);
+
+if (!EDIT_PERMISSIONS.includes(book.getPermission())) {
+    return c.json(
+        buildApiError('FORBIDDEN', 'Editor or owner permission required for this operation'),
+        403
+    );
+}
+```
+
+Read, posting, and other operations may require different policies. Choose the minimum authorization appropriate to the behavior instead of treating every authenticated user as authorized.
+
+### Require app installation
+
+Having permission to access a Book does not mean the app is installed in that Book. If an app is only supposed to be used with Books where it is installed, verify installation:
+
+```ts
+const APP_ID = 'my-app';
+
+const book = await context.bkper.getBook(bookId);
+const installedApps = await book.getApps();
+const isInstalled = installedApps.some(app => app.getId() === APP_ID);
+
+if (!isInstalled) {
+    return c.json(buildApiError('FORBIDDEN', 'This app is not installed in this Book'), 403);
+}
+```
+
+## Next Steps
+
+- [App Architecture](https://bkper.com/docs/build/apps/architecture.md) — Understand client and server authentication flows.
+- [Building & Deploying](https://bkper.com/docs/build/apps/deploying.md#setting-secrets) — Store production and preview secrets.
+- [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md#authentication) — Understand authentication for platform and self-hosted events.

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

@@ -1,4 +1,4 @@
-# Self-Hosted Alternative
+# Bkper Self-Hosted Webhooks
 
 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.
 

package/lib/docs/cli/data-management.md

@@ -40,6 +40,12 @@ bkper book create --name "My Company" --fraction-digits 2 \
 # Create a book with custom properties
 bkper book create --name "Project X" -p "code=PX001" -p "department=Engineering"
 
+# Copy a book's structure without transactions
+bkper book copy abc123 --name "My Company Copy"
+
+# Copy a book with transactions from a specific date (source book owner only)
+bkper book copy abc123 --name "My Company 2025" --transactions --from-date 2025-01-01
+
 # Update a book
 bkper book update abc123 --lock-date 2024-12-31
 ```
@@ -58,6 +64,10 @@ bkper book update abc123 --lock-date 2024-12-31
     -   `--time-zone <timezone>` - IANA time zone (e.g. `America/New_York`, `UTC`)
     -   `--period <period>` - Period (`MONTH`, `QUARTER`, or `YEAR`)
     -   `-p, --property <key=value>` - Set a property (repeatable)
+-   `book copy <bookId>` - Copy a book
+    -   `--name <name>` - Name for the copied book (required)
+    -   `--transactions` - Include transactions (source book owner only)
+    -   `--from-date <YYYY-MM-DD>` - Include transactions from this date; requires `--transactions`
 -   `book update <bookId>` - Update a book
     -   `--name <name>` - Book name
     -   `--fraction-digits <digits>` - Number of decimal places (`0`-`8`)
@@ -228,6 +238,10 @@ bkper transaction create -b abc123 --description "Office supplies"
 bkper transaction create -b abc123 --date 2025-01-15 --amount 100.50 \
   --from "Bank Account" --to "Office Supplies" --description "Printer paper"
 
+# Keep a complete AI-derived transaction as a draft
+printf '%s\n' '[{"date":"2025-01-15","amount":"100.50","creditAccount":{"name":"Bank Account"},"debitAccount":{"name":"Office Supplies"},"description":"Extracted printer paper","draft":true}]' | \
+  bkper transaction create -b abc123
+
 # Create a transaction with one local attachment
 bkper transaction create -b abc123 --date 2025-01-15 --amount 23.90 \
   --from "Cash" --to "Meals" --description "Team lunch" --file ./receipt.pdf
@@ -235,6 +249,9 @@ bkper transaction create -b abc123 --date 2025-01-15 --amount 23.90 \
 # Create a file-only draft for receipt capture
 bkper transaction create -b abc123 --file ./invoice.pdf
 
+# Get a transaction by id
+bkper transaction get tx_456 -b abc123
+
 # List transactions for a full year (on:YYYY)
 bkper transaction list -b abc123 -q 'on:2025'
 
@@ -259,9 +276,15 @@ bkper transaction post tx_456 -b abc123
 # Check (reconcile) a transaction
 bkper transaction check tx_456 -b abc123
 
+# Uncheck a transaction
+bkper transaction uncheck tx_456 -b abc123
+
 # Trash a transaction
 bkper transaction trash tx_456 -b abc123
 
+# Restore a transaction from the trash
+bkper transaction untrash tx_456 -b abc123
+
 # Merge two duplicate transactions
 bkper transaction merge tx_123 tx_456 -b abc123
 ```
@@ -269,6 +292,7 @@ bkper transaction merge tx_123 tx_456 -b abc123
 <details>
 <summary>Command reference</summary>
 
+-   `transaction get <id> -b <bookId>` - Get a transaction by ID
 -   `transaction list -b <bookId> -q <query>` - List transactions matching a query (auto-paginates through all results unless `--limit` or `--cursor` is provided)
     -   `--limit <number>` - Fetch one page with up to this many transactions
     -   `--cursor <cursor>` - Cursor for fetching the next page
@@ -294,7 +318,9 @@ bkper transaction merge tx_123 tx_456 -b abc123
     -   `-p, --property <key=value>` - Set a property (repeatable, empty value deletes)
 -   `transaction post <id> -b <bookId>` - Post a draft transaction
 -   `transaction check <id> -b <bookId>` - Check a transaction
+-   `transaction uncheck <id> -b <bookId>` - Uncheck a transaction
 -   `transaction trash <id> -b <bookId>` - Trash a transaction
+-   `transaction untrash <id> -b <bookId>` - Restore a transaction from the trash
 -   `transaction merge <id1> <id2> -b <bookId>` - Merge two transactions
 
 </details>
@@ -518,6 +544,10 @@ python export_bank.py | bkper transaction create -b abc123
 
 The input follows the exact `bkper.Transaction` or `bkper.Account` type from the [Bkper API Types](https://raw.githubusercontent.com/bkper/bkper-api-types/refs/heads/master/index.d.ts). Custom properties go inside the `properties` object.
 
+### AI-derived transaction safety
+
+Always set `"draft": true` for AI-derived transactions, even when complete. It bypasses Book auto-posting, so the transaction stays out of balances until explicitly posted. Do not rely on missing fields; parsing or Account discovery may complete them.
+
 Groups are created explicitly with `bkper group create --name` and optional `--parent` so hierarchy stays deterministic during setup.
 
 The `--property` CLI flag can override or delete properties from the stdin payload:
@@ -582,6 +612,7 @@ Only the fields below are meaningful when creating or updating resources via std
 | `creditAccount` | `{"name":"..."}` or `{"id":"..."}` | Reference to an existing account              |
 | `debitAccount`  | `{"name":"..."}` or `{"id":"..."}` | Reference to an existing account              |
 | `description`   | `string`                           | Free-text description                         |
+| `draft`         | `boolean`                          | `true` forces a draft and bypasses Book auto-posting |
 | `urls`          | `string[]`                         | Attached URLs (e.g. receipts)                 |
 | `remoteIds`     | `string[]`                         | External IDs to prevent duplicates            |
 | `properties`    | `{"key": "value", ...}`            | Custom key/value properties                   |

package/lib/docs/index.md

@@ -11,6 +11,7 @@ For Bkper data, accounting, reporting, tax, or financial-flow tasks, read `core/
 - `apps/ai.md` — Bkper AI integration for Platform apps: authenticated `/api/*` request flow, outbound authorization and app attribution, live model discovery, strict structured output, response validation, error preservation, data minimization, and unit-test boundaries.
 - `apps/first-app.md` — First-app walkthrough: scaffold, install, run locally, trigger an event, customize the listing, establish shared source, check, and deploy.
 - `apps/architecture.md` — App and template architecture: npm workspace structure, Lit/Vite client, Hono Worker, typed `/api/*` contracts, authentication, `/events`, static assets, and supported app shapes.
+- `apps/security.md` — App security responsibilities and server-side authorization: platform authentication boundaries, user-domain restrictions, Book permission allowlists, and app installation checks.
 - `apps/configuration.md` — Complete `bkper.yaml` reference: identity, branding, ownership, access, context menus, event subscriptions, property schemas, and single-Worker deployment settings.
 - `apps/development.md` — Local development: Vite and Worker processes, ports, API proxy, local authentication, secrets, KV, generated environment types, development loop, and debugging.
 - `apps/event-handlers.md` — Event handler behavior: `/events` routing, responses, replay, loop prevention, platform and self-hosted authentication, event payloads, and event types.

package/lib/docs/sdk/bkper-js.md

@@ -636,7 +636,8 @@ It contains all `Accounts` where `Transactions` are recorded/posted;
 - `listEvents(options: ListEventsOptions)` → `Promise<EventList>` — Lists events in the Book based on the provided options.
 - `listFiles(limit?: number, cursor?: string)` → `Promise<FileList>` — Lists files in the Book, for pagination.
 - `listTransactions(query?: string, limit?: number, cursor?: string)` → `Promise<TransactionList>` — Lists transactions in the Book based on the provided query, limit, and cursor, for pagination.
-- `mergeTransactions(transaction1: string | bkper.Transaction | Transaction, transaction2: string | bkper.Transaction | Transaction)` → `Promise<Transaction>` — Merge two `Transactions` into a single new canonical transaction.
+- `mergeTransactions(primary: string | bkper.Transaction | Transaction, secondary: string | bkper.Transaction | Transaction)` → `Promise<Transaction>` — Merge a primary and secondary `Transaction`. Submitted primary fields
+have highest precedence; an id string sends no field overrides.
 - `parseDate(date: string)` → `Date` — Parse a date string according to date pattern and timezone of the Book. Also parse ISO yyyy-mm-dd format.
 - `parseValue(value: string)` → `Amount | undefined` — Parse a value string according to `DecimalSeparator` and fraction digits of the Book.
 - `remove()` → `Promise<Book>` — Warning!
@@ -736,11 +737,6 @@ const groups2 = await bookWithGroups.getGroups(); // Already cached
 
 Requests are sent sequentially in batches of up to 200 IDs.
 
-**mergeTransactions**
-
-The merged transaction is created synchronously. Cleanup of the two
-originals is scheduled asynchronously by the backend.
-
 **remove**
 
 Deletes this Book and all its data (transactions, accounts, groups). Book owner only.

package/package.json

@@ -1,14 +1,23 @@
 {
     "name": "bkper",
-    "version": "4.26.1",
-    "description": "Command line client for Bkper",
+    "version": "4.28.1",
+    "description": "Official Bkper CLI for accounting data, automation, apps, and AI agents",
     "bin": {
         "bkper": "./lib/cli.js"
     },
     "repository": "https://github.com/bkper/bkper-cli.git",
-    "homepage": "https://bkper.com/docs",
+    "homepage": "https://bkper.com/docs/build/tools/cli",
     "author": "mael <mael@bkper.com>",
     "license": "Apache-2.0",
+    "keywords": [
+        "bkper",
+        "cli",
+        "accounting",
+        "bookkeeping",
+        "finance",
+        "automation",
+        "ai-agent"
+    ],
     "private": false,
     "main": "./lib/index.js",
     "module": "./lib/index.js",
@@ -52,8 +61,8 @@
         "upgrade:api": "bun update @bkper/bkper-api-types --latest && bun update bkper-js --latest"
     },
     "dependencies": {
-        "@earendil-works/pi-coding-agent": "0.84.2",
-        "@earendil-works/pi-tui": "0.84.2",
+        "@earendil-works/pi-coding-agent": "0.84.3",
+        "@earendil-works/pi-tui": "0.84.3",
         "bkper-js": "^2.42.0",
         "commander": "^13.1.0",
         "dotenv": "^8.2.0",