[Image: Bkper Agents Model]
## Permissions
Agents can only access books that have been explicitly shared with the user they're acting on behalf of. Your code never has elevated access — it operates within the same permission boundaries as the human user who authorized it.
## Identity
Every API request your app makes includes a `bkper-agent-id` header. This lets Bkper attribute actions to the correct agent, so activities and transactions appear with your app's logo and name throughout the Bkper interface — making it easy for book owners to see which entity performed specific actions:
## Bots vs AI Agents
The distinction between a "bot" and an "AI agent" is about capability, not a different type of Bkper primitive. Both are just apps:
| | **Bot** | **AI Agent** |
| --- | --- | --- |
| **Purpose** | Automating predefined tasks | Autonomously perform tasks |
| **Capabilities** | Follows rules; limited learning; basic interactions | Complex, multi-step actions; learns and adapts; makes decisions independently |
| **Interaction** | Reactive; responds to triggers or commands | Proactive; goal-oriented |
In Bkper, what people call "bots" are typically apps whose primary capability is [event handling](https://bkper.com/docs/build/apps/event-handlers.md) — reacting to things that happen in a book. AI agents go further, combining event handling with LLM reasoning to make decisions.
---
source: /docs/build/getting-started/quick-wins.md
# Quick Wins
You've [set up your environment](https://bkper.com/docs/build/getting-started/setup.md). Here are three ways to start building immediately — from a 1-line shell command to a 20-line script.
## CLI piping
Copy all accounts from one book to another in a single line:
```bash
bkper account list -b $SOURCE_BOOK --format json | bkper account create -b $DEST_BOOK
```
The CLI outputs JSON that feeds directly into the next command. No code, no setup beyond the CLI itself.
Add a property to every matching transaction:
```bash
bkper transaction list -b $BOOK -q "account:Expenses" --format json | \
bkper transaction update -b $BOOK -p "reviewed=true"
```
See [CLI Scripting & Piping](https://bkper.com/docs/build/scripts/cli-pipelines.md) for more patterns.
## Node.js script
A short script that lists all accounts with their current balances:
```ts
import { Bkper } from 'bkper-js';
import { getOAuthToken } from 'bkper';
Bkper.setConfig({
oauthTokenProvider: async () => getOAuthToken(),
});
const bkper = new Bkper();
const book = await bkper.getBook('your-book-id');
const report = await book.getBalancesReport('');
const containers = report.getBalancesContainers();
for (const container of containers) {
console.log(`${container.getName()}: ${container.getCumulativeBalance()}`);
}
```
Run it:
```bash
npm install bkper-js bkper
node script.mjs
```
See [Node.js Scripts](https://bkper.com/docs/build/scripts/node-scripts.md) for more examples.
## Direct API call
Call the REST API from any language. Here's a `curl` example:
```bash
# Get your OAuth token (after running bkper auth login)
TOKEN=$(bkper auth token)
# List your books
curl -s -H "Authorization: Bearer $TOKEN" \
https://api.bkper.app/v5/books | jq '.items[].name'
```
See [Direct API Usage](https://bkper.com/docs/build/scripts/rest-api.md) for the full guide.
## What next?
These quick wins are just the beginning. Depending on what you want to build:
- **More automation** — [CLI Scripting & Piping](https://bkper.com/docs/build/scripts/cli-pipelines.md) for shell-based workflows, [Node.js Scripts](https://bkper.com/docs/build/scripts/node-scripts.md) for complex logic
- **A full app** — [Your First App](https://bkper.com/docs/build/apps/first-app.md) to build and deploy an app with UI and event handling on the [Bkper Platform](https://bkper.com/docs/build/apps/overview.md)
- **Google Workspace** — [Apps Script Development](https://bkper.com/docs/build/google-workspace/apps-script.md) for Sheets automation and triggers
---
source: /docs/build/getting-started/setup.md
# Development Setup
Everything you build on Bkper starts with the CLI. It handles authentication, provides the `bkper-js` library for programmatic access, and manages the full app lifecycle.
## Prerequisites
- [Node.js](https://nodejs.org/) >= 18
## Install and authenticate
1. **Install the CLI**
```bash
npm i -g bkper
```
2. **Authenticate**
```bash
bkper auth login
```
This opens your browser for Google OAuth authentication. Once complete, the CLI stores your credentials locally. All API calls — from the CLI, from scripts, and from `bkper-js` — use this token. To clean up later, run `bkper auth logout`, which revokes the stored refresh token when possible and clears local credentials.
3. **Verify**
```bash
bkper book list
```
You should see a list of your Bkper Books. If you do, you're ready to build.
## What you now have
After setup, you have:
- **CLI commands** — Manage books, accounts, transactions, and apps from the terminal. Run `bkper --help` for the full command list.
- **Auth provider for scripts** — Use `getOAuthToken()` from the `bkper` package in any Node.js script:
```ts
import { Bkper } from 'bkper-js';
import { getOAuthToken } from 'bkper';
Bkper.setConfig({
oauthTokenProvider: async () => getOAuthToken(),
});
```
- **App development tools** — Initialize, develop, and deploy platform apps with `bkper app` commands.
## Optional: API key
For dedicated API quota and project-level usage tracking, you can configure your own API key. This is optional — the default shared quota (60 requests per minute) works for most use cases.
See [Direct API Usage](https://bkper.com/docs/build/scripts/rest-api.md#custom-api-key) for setup instructions.
## Next steps
- [Quick Wins](https://bkper.com/docs/build/getting-started/quick-wins.md) — The fastest ways to create value with Bkper programmatically
- [Your First App](https://bkper.com/docs/build/apps/first-app.md) — Build and deploy a platform app
- [CLI reference](https://bkper.com/docs/build/tools/cli.md) — Overview of CLI capabilities
---
source: /docs/build/google-workspace/apps-script.md
# Apps Script Development
[Google Apps Script](https://developers.google.com/apps-script) is Google's serverless platform for extending Google Workspace. With the `bkper-gs` library, you can build Bkper automations that run inside Google's infrastructure — no servers, no deployment pipeline, and native access to Sheets, Drive, Calendar, and Gmail.
## When to use Apps Script
Use Apps Script when your automation lives in the Google Workspace ecosystem:
- Scheduled jobs that read from or write to Google Sheets
- Spreadsheet triggers (on-edit, on-form-submit) that record transactions
- Custom add-ons distributed to a team or domain
- Workflows that combine Bkper with other Google services (Drive, Calendar, Gmail)
If you need real-time event handling, a web UI, or automation that runs outside Google Workspace, use [Node.js scripts](https://bkper.com/docs/build/scripts/node-scripts.md) or a [platform app](https://bkper.com/docs/build/apps/overview.md) instead.
### Add the library
`bkper-gs` is published as an Apps Script library. To add it to your script:
1. Open your script in the [Apps Script editor](https://script.google.com)
2. Click **+** next to **Libraries** in the left-side panel
3. In the "Script ID" field, enter:
```
1hMJszJGSUVZDB3vmsWrUZfRhY1UWbhS0SQ6Lzl06gm1zhBF3ioTM7mpJ
```
4. Click **Look up**, choose the latest version, and click **Add**
The `BkperApp` global is now available in your script.
### TypeScript definitions
For TypeScript development with autocomplete, install the type definitions:
```bash
npm i -S @bkper/bkper-gs-types
```
Configure `tsconfig.json`:
```json
{
"compilerOptions": {
"typeRoots": ["node_modules/@bkper", "node_modules/@types"]
}
}
```
See [Develop Apps Script using TypeScript](https://developers.google.com/apps-script/guides/typescript) and use [clasp](https://github.com/google/clasp) to push TypeScript projects to Apps Script.
## The BkperApp entry point
`BkperApp` works the same way as `CalendarApp`, `DocumentApp`, and `SpreadsheetApp` — it's a global entry point that follows familiar Apps Script conventions.
The book ID comes from the URL when you open a book at [bkper.com](https://bkper.com):
```js
// Get a book by its ID (from the URL)
const book = BkperApp.getBook('agtzfmJrcGVyLWhyZHIOCxIGTGVkZ2VyGNKJAgw');
```
### Get a book
```js
function getBookName() {
const book = BkperApp.getBook('agtzfmJrcGVyLWhyZHIOCxIGTGVkZ2VyGNKJAgw');
Logger.log(book.getName());
}
```
### Record a transaction
```js
function recordTransaction() {
const book = BkperApp.getBook('agtzfmJrcGVyLWhyZHIOCxIGTGVkZ2VyGNKJAgw');
book.record('#gas 63.23');
}
```
Transactions use the same [shorthand syntax](https://bkper.com/docs/guides/using-bkper/record-transactions.md) you'd use in the Bkper UI.
### Batch record transactions
For bulk operations, pass an array. The library sends all records in a single API call — important for avoiding Apps Script execution time limits:
```js
function importExpenses() {
const book = BkperApp.getBook('agtzfmJrcGVyLWhyZHIOCxIGTGVkZ2VyGNKJAgw');
const transactions = [
'#breakfast 15.40',
'#lunch 27.45',
'#dinner 35.86',
];
book.record(transactions);
}
```
### Query transactions
The `getTransactions()` method returns a `TransactionIterator` for handling large datasets without loading everything into memory:
```js
function listTransactions() {
const book = BkperApp.getBook('agtzfmJrcGVyLWhyZHIOCxIGTGVkZ2VyGNKJAgw');
const iterator = book.getTransactions("account:'Bank' after:01/01/2024");
while (iterator.hasNext()) {
const transaction = iterator.next();
Logger.log(transaction.getDescription());
}
}
```
See [Querying Transactions](https://bkper.com/docs/guides/using-bkper/query-transactions.md) for the full query syntax.
### List accounts with balances
```js
function listAccountBalances() {
const book = BkperApp.getBook('agtzfmJrcGVyLWhyZHIOCxIGTGVkZ2VyGNKJAgw');
const accounts = book.getAccounts();
for (const account of accounts) {
if (account.isPermanent() && account.isActive()) {
Logger.log(`${account.getName()}: ${account.getBalance()}`);
}
}
}
```
## Building triggers
Apps Script triggers let your automation run on a schedule or respond to spreadsheet events — without any always-on infrastructure.
### Time-based (scheduled)
```js
function setupDailySync() {
ScriptApp.newTrigger('syncTransactions')
.timeBased()
.everyDays(1)
.atHour(6)
.create();
}
function syncTransactions() {
const book = BkperApp.getBook('YOUR_BOOK_ID');
const sheet = SpreadsheetApp.openById('YOUR_SHEET_ID').getActiveSheet();
// Read rows from Sheets, record to Bkper
const rows = sheet.getDataRange().getValues();
const transactions = rows.slice(1).map(row => `${row[0]} ${row[1]} ${row[2]}`);
book.record(transactions);
}
```
### Spreadsheet edit trigger
```js
function onEdit(e) {
const sheet = e.source.getActiveSheet();
if (sheet.getName() !== 'Expenses') return;
const row = e.range.getRow();
const amount = sheet.getRange(row, 3).getValue();
const description = sheet.getRange(row, 2).getValue();
if (amount && description) {
const book = BkperApp.getBook('YOUR_BOOK_ID');
book.record(`${description} ${amount}`);
}
}
```
## TypeScript development workflow
For non-trivial scripts, use [clasp](https://github.com/google/clasp) for local development with TypeScript:
```bash
# Install clasp
npm install -g @google/clasp
# Log in
clasp login
# Clone an existing script
clasp clone