Building with AI

AI coding agents (Claude, Cursor, Copilot, OpenCode) are effective companions for building Bkper integrations — provided they have the right context. This page covers the patterns and practices that make AI-assisted Bkper development reliable.

Give the AI the right context

AI agents produce better Bkper code when they understand the domain before writing anything. Load context in this order:

1. Core Concepts — the from-to model, account types, and transaction lifecycle are prerequisites. Fetch /docs/core-concepts.md as the first context document.
2. SDK reference — for JavaScript/TypeScript work, fetch /docs/api/bkper-js.md to give the agent accurate method signatures and return types.
3. The relevant guide — if building an automation, load the agent model. If working with Sheets, load the Google Sheets guide.

Every documentation page is available as clean Markdown by appending .md to the URL. See AI Tooling for details.

Prefer bkper-js for JavaScript and TypeScript

The bkper-js SDK is the recommended way to interact with Bkper from JS/TS environments. It provides typed methods, handles pagination, and enforces the double-entry model at the API level.

import Bkper from 'bkper-js';

const app = Bkper.setApiKey('your-api-key');
const book = await app.getBook('book-id');

// List accounts
const accounts = await book.getAccounts();

// Query transactions
const transactions = await book.listTransactions('account:Checking after:2024-01-01');

When instructing an AI agent, specify that it should use bkper-js rather than constructing raw REST calls. The SDK handles authentication, pagination, and type safety automatically.

Install the Bkper skill

If your AI tool supports skills, install the Bkper skill to give it persistent knowledge of the platform:

opencode skills install bkper

The skill teaches the agent about account types, transaction states, query syntax, and financial integrity rules — without consuming context window tokens on every session.

Account discovery pattern

Before recording any transactions, an AI agent should discover the book’s account structure:

// Always discover accounts before recording transactions
const accounts = await book.getAccounts();

// Find accounts by name — never guess account names
const checking = accounts.find(a => a.getName() === 'Checking');
const rent = accounts.find(a => a.getName() === 'Rent');

if (!checking || !rent) {
    throw new Error('Required accounts not found — check account names');
}

Instruct your AI agent to always call book.getAccounts() before any write operation. Guessing account names is the most common source of errors.

Query API exploration

Bkper’s query syntax is powerful and the AI should use it for transaction searches rather than fetching all transactions and filtering in code:

// Search by tag
const rentPayments = await book.listTransactions('#rent');

// Search by date range
const q1 = await book.listTransactions('after:2024-01-01 before:2024-04-01');

// Search by account and tag
const officeExpenses = await book.listTransactions('account:Checking #office-supplies');

Point your AI agent to the transactions guide for the full query syntax reference.

Enforce the double-entry invariant

Every Bkper transaction moves an amount FROM one account TO another. There are no single-leg entries. Instruct your AI agent with this rule explicitly:

Every transaction must have exactly two sides: a from account and a to account. Never create a transaction that affects only one account.

// Correct: two-sided transaction
await book.record('#rent $1500 from Checking to Rent');

// Wrong: single-sided — this will fail
// await book.record('#rent $1500 to Rent');  // No from account

Draft before post

For write operations, use the draft-then-post pattern — record transactions as drafts first, review them, then post:

// Record as draft (default behavior)
const tx = await book.record('#payroll $5000 from Checking to Salaries');

// Review the draft...
console.log(`Draft: ${tx.getDescription()} — ${tx.getAmount()}`);

// Post (confirm) the transaction
await tx.check();

Instruct your AI agent to never post transactions without explicit user confirmation. Treat balance-affecting operations as irreversible by default.

AGENTS.md for Bkper projects

Add an AGENTS.md file to your project root to give AI agents project-specific Bkper context. Template:

AGENTS.md

## Bkper context

This project integrates with Bkper for [describe purpose].

### Key references
- Core Concepts: https://bkper.com/docs/core-concepts.md
- bkper-js SDK: https://bkper.com/docs/api/bkper-js.md
- [Add relevant guide URLs]

### Book structure
- Book ID: [your-book-id]
- Key accounts: [list the accounts this integration uses]
- Common tags: [list tags this integration creates or queries]

### Rules
- Always use bkper-js for API calls (not raw REST)
- Every transaction must have a from and to account
- Never post transactions without user confirmation
- Use draft transactions for any automated recording

This file is loaded automatically by AI coding agents that support the AGENTS.md convention, providing project-specific context without manual prompting.