Book

A Book represents a General Ledger for a company or business, but can also represent a Ledger for a project or department

It contains all [[Accounts]] where [[Transactions]] are recorded/posted;

Extends

ResourceProperty<bkper.Book>

Constructors

Constructor

new Book(payload?, config?): Book;

Parameters

Parameter	Type
`payload?`	`Book`
`config?`	`Config`

Returns

Book

Overrides

ResourceProperty<bkper.Book>.constructor

Properties

payload

payload: Book;

The underlying payload data for this resource

Inherited from

ResourceProperty.payload

Methods

audit()

audit(): void;

Trigger Balances Audit async process.

Returns

void

batchCheckTransactions()

batchCheckTransactions(transactions): Promise<void>;

Batch check [[Transactions]] on the Book.

Parameters

Parameter	Type	Description
`transactions`	`Transaction`[]	The transactions to be checked

Returns

Promise<void>

batchCreateAccounts()

batchCreateAccounts(accounts): Promise<Account[]>;

Create [[Accounts]] on the Book, in batch.

Parameters

Parameter	Type	Description
`accounts`	`Account`[]	The accounts to be created

Returns

Promise<Account[]>

The created Accounts

batchCreateGroups()

batchCreateGroups(groups): Promise<Group[]>;

Create [[Groups]] on the Book, in batch.

Parameters

Parameter	Type	Description
`groups`	`Group`[]	The groups to be created

Returns

Promise<Group[]>

The created Groups

batchCreateTransactions()

batchCreateTransactions(transactions): Promise<Transaction[]>;

Batch create [[Transactions]] on the Book.

Parameters

Parameter	Type	Description
`transactions`	`Transaction`[]	The transactions to be created

Returns

Promise<Transaction[]>

The created Transactions

batchPostTransactions()

batchPostTransactions(transactions): Promise<void>;

Batch post [[Transactions]] on the Book.

Parameters

Parameter	Type	Description
`transactions`	`Transaction`[]	The transactions to be posted

Returns

Promise<void>

batchReplayEvents()

batchReplayEvents(events, errorOnly?): Promise<void>;

Replay [[Events]] on the Book, in batch.

Parameters

Parameter	Type	Description
`events`	`Event`[]	The events to be replayed
`errorOnly?`	`boolean`	True to only replay events with errors

Returns

Promise<void>

batchTrashTransactions()

batchTrashTransactions(transactions, trashChecked?): Promise<void>;

Batch trash [[Transactions]] on the Book.

Parameters

Parameter	Type	Description
`transactions`	`Transaction`[]	The transactions to be trashed
`trashChecked?`	`boolean`	True to also trash checked transactions

Returns

Promise<void>

batchUncheckTransactions()

batchUncheckTransactions(transactions): Promise<void>;

Batch uncheck [[Transactions]] on the Book.

Parameters

Parameter	Type	Description
`transactions`	`Transaction`[]	The transactions to be unchecked

Returns

Promise<void>

batchUntrashTransactions()

batchUntrashTransactions(transactions): Promise<void>;

Batch untrash [[Transactions]] on the Book.

Parameters

Parameter	Type	Description
`transactions`	`Transaction`[]	The transactions to be untrashed

Returns

Promise<void>

batchUpdateTransactions()

batchUpdateTransactions(transactions, updateChecked?): Promise<Transaction[]>;

Batch update [[Transactions]] on the Book.

Parameters

Parameter	Type	Description
`transactions`	`Transaction`[]	The transactions to be updated
`updateChecked?`	`boolean`	True to also update checked transactions

Returns

Promise<Transaction[]>

The updated draft Transactions

copy()

copy(
   name,
   copyTransactions?,
fromDate?): Promise<Book>;

Creates a copy of this Book

Parameters

Parameter	Type	Description
`name`	`string`	The name for the copied book
`copyTransactions?`	`boolean`	True to copy transactions from the source book (user must be the Book owner)
`fromDate?`	`number`	Start date to consider if copying transactions (numeric value in YYYYMMDD format)

Returns

Promise<Book>

The copied Book object

countTransactions()

countTransactions(query?): Promise<number | undefined>;

Retrieve the number of transactions based on a query.

Parameters

Parameter	Type	Description
`query?`	`string`	The query string

Returns

Promise<number | undefined>

The number of matching transactions

create()

create(): Promise<Book>;

Performs create new Book.

Returns

Promise<Book>

The created Book object

createAccountsDataTable()

createAccountsDataTable(accounts?): Promise<AccountsDataTableBuilder>;

Create a AccountsDataTableBuilder, to build two dimensional Array representations of Account dataset.

Parameters

Parameter	Type	Description
`accounts?`	`Account`[]	Optional array of accounts. If not provided, all accounts will be fetched.

Returns

Promise<AccountsDataTableBuilder>

Accounts data table builder.

createGroupsDataTable()

createGroupsDataTable(groups?): Promise<GroupsDataTableBuilder>;

Create a GroupsDataTableBuilder, to build two dimensional Array representations of Group dataset.

Parameters

Parameter	Type	Description
`groups?`	`Group`[]	Optional array of groups. If not provided, all groups will be fetched.

Returns

Promise<GroupsDataTableBuilder>

Groups data table builder.

createIntegration()

createIntegration(integration): Promise<Integration>;

Creates a new [[Integration]] in the Book.

Parameters

Parameter	Type	Description
`integration`	`Integration` \| `Integration`	The [[Integration]] object or wrapped plain json

Returns

Promise<Integration>

The created [[Integration]] object

createTransactionsDataTable()

createTransactionsDataTable(transactions, account?): TransactionsDataTableBuilder;

Create a TransactionsDataTableBuilder, to build two dimensional Array representations of Transaction dataset.

Parameters

Parameter	Type	Description
`transactions`	`Transaction`[]	Array of transactions to include in the table.
`account?`	`Account`	Optional account for balance column display.

Returns

TransactionsDataTableBuilder

Transactions data table builder.

deleteProperty()

deleteProperty(key): this;

Deletes a custom property.

Parameters

Parameter	Type	Description
`key`	`string`	The property key

Returns

this

This resource, for chaining

Inherited from

ResourceProperty.deleteProperty

formatDate()

formatDate(date, timeZone?): string;

Formats a date according to date pattern of the Book.

Parameters

Parameter	Type	Description
`date`	`Date`	The date to format as string.
`timeZone?`	`string`	The output timezone of the result. Default to script’s timeZone

Returns

string

The formatted date

formatValue()

formatValue(value): string;

Formats a value according to [[DecimalSeparator]] and fraction digits of the Book.

Parameters

Parameter	Type	Description
`value`	\| `number` \| `Amount` \| `null` \| `undefined`	The value to be formatted.

Returns

string

The formatted value

getAccount()

getAccount(idOrName?): Promise<Account | undefined>;

Gets an [[Account]] object by id or name.

Results are cached to avoid repeated server calls. Account-group relationships are included if the full chart was loaded via getAccounts() or when the Book was loaded with includeAccounts=true.

Parameters

Parameter	Type	Description
`idOrName?`	`string`	The id or name of the Account

Returns

Promise<Account | undefined>

The matching Account object

Example

// Get individual account (basic data, cached)
const account = await book.getAccount('Bank Account');

// For account-group relationships, use one of these approaches:
// Option 1: Load book with full data upfront
const bookWithAccounts = await Bkper.getBook(bookId, true);
const accountWithGroups = await bookWithAccounts.getAccount('Bank Account');

// Option 2: Load full chart when needed
await book.getAccounts();
const accountWithGroups2 = await book.getAccount('Bank Account');

getAccounts()

getAccounts(): Promise<Account[]>;

Gets all [[Accounts]] of this Book with full account-group relationships.

Results are cached for performance. Groups are automatically loaded first to ensure proper linking. Consider using Bkper.getBook(id, true) for upfront loading when you know you’ll need all accounts.

Returns

Promise<Account[]>

The retrieved [[Account]] objects

Example

// Load all accounts with complete relationships
const accounts = await book.getAccounts();

// Alternative: Load book with accounts upfront (more efficient)
const bookWithAccounts = await Bkper.getBook(bookId, true);
const accounts2 = await bookWithAccounts.getAccounts(); // Already cached

getApps()

getApps(): Promise<App[]>;

Retrieve installed [[Apps]] for this Book.

Returns

Promise<App[]>

The retrieved Apps objects

getAutoPost()

getAutoPost(): boolean | undefined;

Gets the auto post status of the Book.

Returns

boolean | undefined

The auto post status of the Book

getBacklog()

getBacklog(): Promise<Backlog>;

Gets the Backlog of this Book.

Returns

Promise<Backlog>

The Backlog object

getBalancesReport()

getBalancesReport(query): Promise<BalancesReport>;

Create a [[BalancesReport]] based on query.

Parameters

Parameter	Type	Description
`query`	`string`	The balances report query

Returns

Promise<BalancesReport>

The balances report

Example:

var book = BkperApp.getBook("agtzfmJrcGVyLWhyZHITCxIGTGVkZ2VyGICAgPXjx7oKDA");

var balancesReport = book.getBalancesReport("group:'Equity' after:7/2018 before:8/2018");

var accountBalance = balancesReport.getBalancesContainer("Bank Account").getCumulativeBalance();

getClosingDate()

getClosingDate(): string | undefined;

Gets the closing date of the Book in ISO format yyyy-MM-dd.

Returns

string | undefined

The closing date of the Book in ISO format yyyy-MM-dd

getCollaborators()

getCollaborators(): Promise<Collaborator[]>;

Gets all collaborators of this Book.

Returns

Promise<Collaborator[]>

Array of Collaborator objects

getCollection()

getCollection(): Collection | undefined;

Gets the collection of this Book, if any.

Returns

Collection | undefined

The collection of this Book, if any

getDatePattern()

getDatePattern(): string;

Gets the date pattern of the Book.

Returns

string

The date pattern of the Book. Current: dd/MM/yyyy | MM/dd/yyyy | yyyy/MM/dd

getDecimalPlaces()

getDecimalPlaces(): number | undefined;

Gets the number of decimal places supported by this Book.

Returns

number | undefined

The number of decimal places supported by this Book. Same as getFractionDigits

getDecimalSeparator()

getDecimalSeparator(): DecimalSeparator;

Gets the decimal separator of the Book.

Returns

DecimalSeparator

The decimal separator of the Book

getFile()

getFile(id): Promise<File | undefined>;

Retrieve a file by id.

Parameters

Parameter	Type	Description
`id`	`string`	The file ID

Returns

Promise<File | undefined>

The [[File]] object

getFractionDigits()

getFractionDigits(): number | undefined;

Gets the number of fraction digits supported by this Book.

Returns

number | undefined

The number of fraction digits supported by this Book. Same as getDecimalPlaces

getGroup()

getGroup(idOrName?): Promise<Group | undefined>;

Gets a [[Group]] object by id or name.

Results are cached to avoid repeated server calls. Parent/child relationships are included if all groups were loaded via getGroups() or when the Book was loaded with includeGroups=true.

Parameters

Parameter	Type	Description
`idOrName?`	`string`	The id or name of the Group

Returns

Promise<Group | undefined>

The matching Group object

Example

// Get individual group (basic data, cached)
const group = await book.getGroup('Assets');

// For parent/child relationships, use one of these approaches:
// Option 1: Load book with full hierarchy upfront
const bookWithGroups = await Bkper.getBook(bookId, false, true);
const groupWithTree = await bookWithGroups.getGroup('Assets');

// Option 2: Load full hierarchy when needed
await book.getGroups();
const groupWithTree2 = await book.getGroup('Assets');
console.log(groupWithTree2.getParent(), groupWithTree2.getChildren());

getGroups()

getGroups(): Promise<Group[]>;

Gets all [[Groups]] of this Book with complete parent/child hierarchy.

Results are cached for performance. Group tree relationships are built during loading. Consider using Bkper.getBook(id, false, true) for upfront loading when you know you’ll need all groups.

Returns

Promise<Group[]>

The retrieved [[Group]] objects

Example

// Load all groups with complete hierarchy
const groups = await book.getGroups();

// Alternative: Load book with groups upfront (more efficient)
const bookWithGroups = await Bkper.getBook(bookId, false, true);
const groups2 = await bookWithGroups.getGroups(); // Already cached

getId()

getId(): string;

Gets the unique identifier of this Book.

Returns

string

This Book’s unique identifier

getIntegrations()

getIntegrations(): Promise<Integration[]>;

Gets the existing [[Integrations]] in the Book.

Returns

Promise<Integration[]>

The retrieved Integration objects

getLastUpdateMs()

getLastUpdateMs(): number | undefined;

Gets the last update date of the book, in milliseconds.

Returns

number | undefined

The last update date of the book, in milliseconds

getLockDate()

getLockDate(): string | undefined;

Gets the lock date of the Book in ISO format yyyy-MM-dd.

Returns

string | undefined

The lock date of the Book in ISO format yyyy-MM-dd

getName()

getName(): string | undefined;

Gets the name of this Book.

Returns

string | undefined

The name of this Book

getOwnerName()

getOwnerName(): string | undefined;

Gets the name of the owner of the Book.

Returns

string | undefined

The name of the owner of the Book

getPageSize()

getPageSize(): number | undefined;

Gets the transactions pagination page size.

Returns

number | undefined

The transactions pagination page size

getPeriod()

getPeriod(): Period;

Gets the period slice for balances visualization.

Returns

Period

The period slice for balances visualization

getPeriodStartMonth()

getPeriodStartMonth(): Month;

Gets the start month when YEAR period is set.

Returns

Month

The start month when YEAR period is set

getPermission()

getPermission(): Permission;

Gets the permission for the current user in this Book.

Returns

Permission

The permission for the current user in this Book

getProperties()

getProperties(): object;

Gets the custom properties stored in this resource.

Returns

object

Object with key/value pair properties

Inherited from

ResourceProperty.getProperties

getProperty()

getProperty(...keys): string | undefined;

Gets the property value for given keys. First property found will be retrieved.

Parameters

Parameter	Type	Description
…`keys`	`string`[]	The property keys to search for

Returns

string | undefined

The property value or undefined if not found

Inherited from

ResourceProperty.getProperty

getPropertyKeys()

getPropertyKeys(): string[];

Gets the custom properties keys stored in this resource.

Returns

string[]

Array of property keys sorted alphabetically

Inherited from

ResourceProperty.getPropertyKeys

getSavedQueries()

getSavedQueries(): Promise<Query[]>;

Gets the saved queries from this book.

Returns

Promise<Query[]>

The saved queries from this book

getTimeZone()

getTimeZone(): string | undefined;

Gets the time zone of the Book.

Returns

string | undefined

The time zone of the Book

getTimeZoneOffset()

getTimeZoneOffset(): number | undefined;

Gets the time zone offset of the book, in minutes.

Returns

number | undefined

The time zone offset of the book, in minutes

getTotalTransactions()

getTotalTransactions(): number;

Gets the total number of posted transactions.

Returns

number

The total number of posted transactions

getTotalTransactionsCurrentMonth()

getTotalTransactionsCurrentMonth(): number;

Gets the total number of posted transactions on current month.

Returns

number

The total number of posted transactions on current month

getTotalTransactionsCurrentYear()

getTotalTransactionsCurrentYear(): number;

Gets the total number of posted transactions on current year.

Returns

number

The total number of posted transactions on current year

getTransaction()

getTransaction(id): Promise<Transaction | undefined>;

Retrieve a transaction by id.

Parameters

Parameter	Type	Description
`id`	`string`	The transaction ID

Returns

Promise<Transaction | undefined>

The [[Transaction]] object

getVisibility()

getVisibility(): Visibility;

Gets the visibility of the book.

Returns

Visibility

The visibility of the book

getVisibleProperties()

getVisibleProperties(): object;

Gets the visible custom properties stored in this resource. Hidden properties (those ending with ”_”) are excluded from the result.

Returns

object

Object with key/value pair properties, excluding hidden properties

Inherited from

ResourceProperty.getVisibleProperties

json()

json(): Book;

Gets an immutable copy of the JSON payload for this resource.

Returns

Book

An immutable copy of the json payload

Inherited from

ResourceProperty.json

listEvents()

listEvents(
   afterDate,
   beforeDate,
   onError,
   resourceId,
   limit,
cursor?): Promise<EventList>;

Lists events in the Book based on the provided parameters.

Parameters

Parameter	Type	Description
`afterDate`	`string` \| `null`	The start date (inclusive) for the events search range, in RFC3339 format. Can be null
`beforeDate`	`string` \| `null`	The end date (exclusive) for the events search range, in RFC3339 format. Can be null
`onError`	`boolean`	True to search only for events on error
`resourceId`	`string` \| `null`	The ID of the event’s resource (Transaction, Account, or Group). Can be null
`limit`	`number`	The maximum number of events to return
`cursor?`	`string`	The cursor for pagination. Can be null

Returns

Promise<EventList>

An [[EventList]] object containing the list of events

listTransactions()

listTransactions(
   query?,
   limit?,
cursor?): Promise<TransactionList>;

Lists transactions in the Book based on the provided query, limit, and cursor, for pagination.

Parameters

Parameter	Type	Description
`query?`	`string`	The query string to filter transactions
`limit?`	`number`	The maximum number of transactions to return. Default to 100, max to 1000
`cursor?`	`string`	The cursor for pagination

Returns

Promise<TransactionList>

A [[TransactionList]] object containing the list of transactions

parseDate()

parseDate(date): Date;

Parse a date string according to date pattern and timezone of the Book. Also parse ISO yyyy-mm-dd format.

Parameters

Parameter	Type	Description
`date`	`string`	The date string to parse

Returns

Date

The parsed Date object

parseValue()

parseValue(value): Amount | undefined;

Parse a value string according to [[DecimalSeparator]] and fraction digits of the Book.

Parameters

Parameter	Type	Description
`value`	`string`	The value string to parse

Returns

Amount | undefined

The parsed Amount or undefined if parsing fails

remove()

remove(): Promise<Book>;

Warning!

Deletes this Book and all its data (transactions, accounts, groups). Book owner only.

Returns

Promise<Book>

This Book after deletion

round()

round(value): Amount;

Rounds a value according to the number of fraction digits of the Book.

Parameters

Parameter	Type	Description
`value`	`number` \| `Amount`	The value to be rounded

Returns

Amount

The rounded value

setAutoPost()

setAutoPost(autoPost): Book;

Sets the auto post status of the Book.

Parameters

Parameter	Type	Description
`autoPost`	`boolean`	The auto post status to set

Returns

Book

This Book, for chaining

setClosingDate()

setClosingDate(closingDate): Book;

Sets the closing date of the Book in ISO format yyyy-MM-dd.

Parameters

Parameter	Type	Description
`closingDate`	`string` \| `null`	The closing date to set in ISO format yyyy-MM-dd

Returns

Book

This Book, for chaining

setDatePattern()

setDatePattern(datePattern): Book;

Sets the date pattern of the Book. Current: dd/MM/yyyy | MM/dd/yyyy | yyyy/MM/dd

Parameters

Parameter	Type	Description
`datePattern`	`string`	The date pattern to set

Returns

Book

This Book, for chaining

setDecimalSeparator()

setDecimalSeparator(decimalSeparator): Book;

Sets the decimal separator of the Book

Parameters

Parameter	Type	Description
`decimalSeparator`	`DecimalSeparator`	The decimal separator to set

Returns

Book

This Book, for chaining

setFractionDigits()

setFractionDigits(fractionDigits): Book;

Sets the number of fraction digits (decimal places) supported by this Book.

Parameters

Parameter	Type	Description
`fractionDigits`	`number`	The number of fraction digits to set (0 to 8)

Returns

Book

This Book, for chaining

setLockDate()

setLockDate(lockDate): Book;

Sets the lock date of the Book in ISO format yyyy-MM-dd.

Parameters

Parameter	Type	Description
`lockDate`	`string` \| `null`	The lock date to set in ISO format yyyy-MM-dd

Returns

Book

This Book, for chaining

setName()

setName(name): Book;

Sets the name of the Book.

Parameters

Parameter	Type	Description
`name`	`string`	The name to set

Returns

Book

This Book, for chaining

setPageSize()

setPageSize(pageSize): Book;

Sets the transactions pagination page size.

Parameters

Parameter	Type	Description
`pageSize`	`number`	The page size to set

Returns

Book

This Book, for chaining

setPeriod()

setPeriod(period): Book;

Sets the period slice for balances visualization.

Parameters

Parameter	Type	Description
`period`	`Period`	The period to set

Returns

Book

This Book, for chaining

setPeriodStartMonth()

setPeriodStartMonth(month): Book;

Sets the start month when YEAR period is set.

Parameters

Parameter	Type	Description
`month`	`Month`	The start month to set

Returns

Book

This Book, for chaining

setProperties()

setProperties(properties): this;

Sets the custom properties of this resource.

Parameters

Parameter	Type	Description
`properties`	{ [`key`: `string`]: `string`; }	Object with key/value pair properties

Returns

this

This resource, for chaining

Inherited from

ResourceProperty.setProperties

setProperty()

setProperty(key, value): this;

Sets a custom property in this resource.

Parameters

Parameter	Type	Description
`key`	`string`	The property key
`value`	`string` \| `null` \| `undefined`	The property value, or null/undefined to clean it

Returns

this

This resource, for chaining

Inherited from

ResourceProperty.setProperty

setTimeZone()

setTimeZone(timeZone): Book;

Sets the time zone of the Book.

Parameters

Parameter	Type	Description
`timeZone`	`string`	The time zone to set

Returns

Book

This Book, for chaining

setVisibility()

setVisibility(visibility): Book;

Sets the visibility of the book.

Parameters

Parameter	Type	Description
`visibility`	`Visibility`	The visibility to set

Returns

Book

This Book, for chaining

setVisibleProperties()

setVisibleProperties(properties): this;

Sets the custom properties of this resource, filtering out hidden properties. Hidden properties are those whose keys end with an underscore ”_”.

Parameters

Parameter	Type	Description
`properties`	{ [`key`: `string`]: `string`; }	Object with key/value pair properties

Returns

this

This resource, for chaining

Inherited from

ResourceProperty.setVisibleProperties

setVisibleProperty()

setVisibleProperty(key, value): this;

Sets a custom property in this resource, filtering out hidden properties. Hidden properties are those whose keys end with an underscore ”_”.

Parameters

Parameter	Type	Description
`key`	`string`	The property key
`value`	`string` \| `null` \| `undefined`	The property value, or null/undefined to clean it

Returns

this

This resource, for chaining

Inherited from

ResourceProperty.setVisibleProperty

update()

update(): Promise<Book>;

Perform update Book, applying pending changes.

Returns

Promise<Book>

The updated Book object

updateIntegration()

updateIntegration(integration): Promise<Integration>;

Updates an existing [[Integration]] in the Book.

Parameters

Parameter	Type	Description
`integration`	`Integration`	The [[Integration]] wrapped plain json

Returns

Promise<Integration>

The updated [[Integration]] object