bkper-js 2.28.0 → 2.29.1

package/lib/index.d.ts

@@ -125,6 +125,10 @@ export declare class Account extends ResourceProperty<bkper.Account> {
     /**
      * Gets the [[Groups]] of this Account.
      *
+     * When groups are already embedded in the account payload (e.g. from
+     * {@link Bkper.getBook} with includeGroups), resolves them from the
+     * book's cache instead of making API calls.
+     *
      * @returns Promise with the [[Groups]] of this Account
      */
     getGroups(): Promise<Group[]>;
@@ -182,6 +186,81 @@ export declare class Account extends ResourceProperty<bkper.Account> {
 
 }
 
+/**
+ * A AccountsDataTableBuilder is used to setup and build two-dimensional arrays containing accounts.
+ *
+ * @public
+ */
+export declare class AccountsDataTableBuilder {
+    private accounts;
+    private shouldIncludeArchived;
+    private shouldAddGroups;
+    private shouldAddProperties;
+    private shouldAddIds;
+    private shouldAddHiddenProperties;
+    private propertyKeys;
+    constructor(accounts: Account[]);
+    /**
+     * Defines whether the archived accounts should be included.
+     *
+     * @param include - Whether to include archived accounts
+     *
+     * @returns This builder with respective include archived option, for chaining.
+     */
+    archived(include: boolean): AccountsDataTableBuilder;
+    /**
+     * Defines whether include account groups.
+     *
+     * @param include - Whether to include groups
+     *
+     * @returns This builder with respective include groups option, for chaining.
+     */
+    groups(include: boolean): AccountsDataTableBuilder;
+    /**
+     * Defines whether include custom account properties.
+     *
+     * @param include - Whether to include properties
+     *
+     * @returns This builder with respective include properties option, for chaining.
+     */
+    properties(include: boolean): AccountsDataTableBuilder;
+    /**
+     * Defines whether include account ids.
+     *
+     * @param include - Whether to include ids
+     *
+     * @returns This builder with respective include ids option, for chaining.
+     */
+    ids(include: boolean): AccountsDataTableBuilder;
+    /**
+     * Defines whether to include hidden properties (keys ending with underscore "_").
+     * Only relevant when {@link properties} is enabled.
+     * Default is false — hidden properties are excluded.
+     *
+     * @param include - Whether to include hidden properties
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    hiddenProperties(include: boolean): AccountsDataTableBuilder;
+    private getPropertyKeys;
+    private getTypeIndex;
+    private getMaxNumberOfGroups;
+    /**
+     * Sorts groups for an account in hierarchy-path order:
+     * 1. Hierarchical groups (those with parent or children) come first, ordered by:
+     *    - Root group name (alphabetically)
+     *    - Depth within the hierarchy (parent before child)
+     * 2. Free groups (no parent and no children) come last, sorted alphabetically
+     */
+    private sortGroupsHierarchyPath_;
+    /**
+     * Builds a two-dimensional array containing all accounts.
+     *
+     * @returns A promise resolving to a two-dimensional array containing all accounts
+     */
+    build(): Promise<any[][]>;
+}
+
 /**
  * Enum that represents account types.
  *
@@ -939,6 +1018,7 @@ export declare class BalancesDataTableBuilder implements BalancesDataTableBuilde
     private shouldPeriod;
     private shouldRaw;
     private shouldAddProperties;
+    private shouldAddHiddenProperties;
     private maxDepth;
     private expandAllAccounts;
     private expandAllGroups;
@@ -1058,6 +1138,16 @@ export declare class BalancesDataTableBuilder implements BalancesDataTableBuilde
      * @returns This builder with respective include properties option, for chaining.
      */
     properties(include: boolean): BalancesDataTableBuilder;
+    /**
+     * Defines whether to include hidden properties (keys ending with underscore "_").
+     * Only relevant when {@link properties} is enabled.
+     * Default is false — hidden properties are excluded.
+     *
+     * @param include - Whether to include hidden properties
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    hiddenProperties(include: boolean): BalancesDataTableBuilder;
     /**
      * Defines whether should split **TOTAL** [[BalanceType]] into debit and credit.
      *
@@ -2002,6 +2092,78 @@ export declare class Book extends ResourceProperty<bkper.Book> {
      * @returns The Backlog object
      */
     getBacklog(): Promise<Backlog>;
+    /**
+     * Create a {@link AccountsDataTableBuilder}, to build two dimensional Array representations of {@link Account} dataset.
+     *
+     * @param accounts - Optional array of accounts. If not provided, all accounts will be fetched.
+     *
+     * @returns Accounts data table builder.
+     */
+    createAccountsDataTable(accounts?: Account[]): Promise<AccountsDataTableBuilder>;
+    /**
+     * Create a {@link GroupsDataTableBuilder}, to build two dimensional Array representations of {@link Group} dataset.
+     *
+     * @param groups - Optional array of groups. If not provided, all groups will be fetched.
+     *
+     * @returns Groups data table builder.
+     */
+    createGroupsDataTable(groups?: Group[]): Promise<GroupsDataTableBuilder>;
+    /**
+     * Create a {@link TransactionsDataTableBuilder}, to build two dimensional Array representations of {@link Transaction} dataset.
+     *
+     * @param transactions - Array of transactions to include in the table.
+     * @param account - Optional account for balance column display.
+     *
+     * @returns Transactions data table builder.
+     */
+    createTransactionsDataTable(transactions: Transaction[], account?: Account): TransactionsDataTableBuilder;
+}
+
+/**
+ * A BooksDataTableBuilder is used to setup and build two-dimensional arrays containing books.
+ *
+ * @public
+ */
+export declare class BooksDataTableBuilder {
+    private books;
+    private shouldAddProperties;
+    private shouldAddIds;
+    private shouldAddHiddenProperties;
+    private propertyKeys;
+    constructor(books: Book[]);
+    /**
+     * Defines whether to include custom book properties.
+     *
+     * @param include - Whether to include properties
+     *
+     * @returns This builder with respective include properties option, for chaining.
+     */
+    properties(include: boolean): BooksDataTableBuilder;
+    /**
+     * Defines whether to include book ids.
+     *
+     * @param include - Whether to include ids
+     *
+     * @returns This builder with respective include ids option, for chaining.
+     */
+    ids(include: boolean): BooksDataTableBuilder;
+    /**
+     * Defines whether to include hidden properties (keys ending with underscore "_").
+     * Only relevant when {@link properties} is enabled.
+     * Default is false — hidden properties are excluded.
+     *
+     * @param include - Whether to include hidden properties
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    hiddenProperties(include: boolean): BooksDataTableBuilder;
+    private mapPropertyKeys;
+    /**
+     * Builds a two-dimensional array containing all Books.
+     *
+     * @returns A two-dimensional array containing all Books
+     */
+    build(): any[][];
 }
 
 /**
@@ -2861,6 +3023,70 @@ export declare class Group extends ResourceProperty<bkper.Group> {
 
 }
 
+/**
+ * A GroupsDataTableBuilder is used to setup and build two-dimensional arrays containing groups.
+ *
+ * @public
+ */
+export declare class GroupsDataTableBuilder {
+    private groups;
+    private shouldAddProperties;
+    private shouldAddIds;
+    private shouldAddHiddenProperties;
+    private shouldShowTree;
+    private propertyKeys;
+    constructor(groups: Group[]);
+    /**
+     * Defines whether include custom group properties.
+     *
+     * @param include - Whether to include properties
+     *
+     * @returns This builder with respective include properties option, for chaining.
+     */
+    properties(include: boolean): GroupsDataTableBuilder;
+    /**
+     * Defines whether include group ids.
+     *
+     * @param include - Whether to include ids
+     *
+     * @returns This builder with respective include ids option, for chaining.
+     */
+    ids(include: boolean): GroupsDataTableBuilder;
+    /**
+     * Defines whether to include hidden properties (keys ending with underscore "_").
+     * Only relevant when {@link properties} is enabled.
+     * Default is false — hidden properties are excluded.
+     *
+     * @param include - Whether to include hidden properties
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    hiddenProperties(include: boolean): GroupsDataTableBuilder;
+    /**
+     * Defines whether to render groups as an indented tree instead of flat rows with a Parent column.
+     * When enabled, child group names are indented by depth level and the Parent column is removed.
+     * Default is false.
+     *
+     * @param enable - Whether to enable tree rendering
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    tree(enable: boolean): GroupsDataTableBuilder;
+    private mapPropertyKeys;
+    private getStringType;
+    private getTypeIndex;
+    private getHasChildrenIndex;
+    /**
+     * Builds a two-dimensional array containing all Groups.
+     *
+     * @returns A two-dimensional array containing all Groups
+     */
+    build(): any[][];
+    private buildGroupLine;
+    private traverse;
+    private readonly COMPARATOR;
+}
+
 /**
  * This class defines a Integration from an [[User]] to an external service.
  *
@@ -3375,6 +3601,12 @@ export declare class Transaction extends ResourceProperty<bkper.Transaction> {
      * @returns True if a transaction is locked by the book lock/closing date
      */
     isLocked(): boolean;
+    /**
+     * Gets the status of the transaction.
+     *
+     * @returns The status of the Transaction
+     */
+    getStatus(): TransactionStatus;
     /**
      * Gets all hashtags used in the transaction.
      *
@@ -3736,6 +3968,145 @@ export declare class TransactionList {
     getItems(): Transaction[];
 }
 
+/**
+ * A TransactionsDataTableBuilder is used to setup and build two-dimensional arrays containing transactions.
+ *
+ * @public
+ */
+export declare class TransactionsDataTableBuilder {
+    private book;
+    private transactions;
+    private account;
+    private shouldFormatDates;
+    private shouldFormatValues;
+    private shouldAddUrls;
+    private shouldAddProperties;
+    private shouldAddIds;
+    private shouldAddRecordedAt;
+    private shouldAddHiddenProperties;
+    private propertyKeys;
+    private attachmentHeaders;
+    private remoteIdHeaders;
+    constructor(book: Book, transactions: Transaction[], account?: Account);
+    /**
+     * Defines whether the dates should be formatted, based on date pattern of the [[Book]].
+     *
+     * @param format - Whether to format dates
+     *
+     * @returns This builder with respective formatting option, for chaining.
+     */
+    formatDates(format: boolean): TransactionsDataTableBuilder;
+    /**
+     * Defines whether amounts should be formatted based on [[DecimalSeparator]] of the [[Book]].
+     *
+     * @param format - Whether to format values
+     *
+     * @returns This builder with respective formatting option, for chaining.
+     */
+    formatValues(format: boolean): TransactionsDataTableBuilder;
+    /**
+     * Defines whether to include attachments and url links.
+     *
+     * @param include - Whether to include URLs
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    urls(include: boolean): TransactionsDataTableBuilder;
+    /**
+     * Defines whether to include custom transaction properties.
+     *
+     * @param include - Whether to include properties
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    properties(include: boolean): TransactionsDataTableBuilder;
+    /**
+     * Defines whether to include transaction ids and remote ids.
+     *
+     * @param include - Whether to include ids
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    ids(include: boolean): TransactionsDataTableBuilder;
+    /**
+     * Defines whether to include the "Recorded at" column.
+     *
+     * @param include - Whether to include the recorded at column
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    recordedAt(include: boolean): TransactionsDataTableBuilder;
+    /**
+     * Defines whether to include hidden properties (keys ending with underscore "_").
+     * Only relevant when {@link properties} is enabled.
+     * Default is false — hidden properties are excluded.
+     *
+     * @param include - Whether to include hidden properties
+     *
+     * @returns This builder with respective option, for chaining.
+     */
+    hiddenProperties(include: boolean): TransactionsDataTableBuilder;
+    /**
+     * @deprecated Use {@link urls} instead.
+     */
+    includeUrls(include: boolean): TransactionsDataTableBuilder;
+    /**
+     * @deprecated Use {@link properties} instead.
+     */
+    includeProperties(include: boolean): TransactionsDataTableBuilder;
+    /**
+     * @deprecated Use {@link ids} instead.
+     */
+    includeIds(include: boolean): TransactionsDataTableBuilder;
+    /**
+     * Gets the account used to filter transactions, when applicable.
+     *
+     * @returns The account, when filtering by a single account.
+     */
+    getAccount(): Account | undefined;
+    /**
+     * Builds a two-dimensional array containing all transactions.
+     *
+     * @returns A promise resolving to a two-dimensional array containing all transactions
+     */
+    build(): Promise<any[][]>;
+    private getHeaderLine;
+    private get2DArray_;
+    private shouldShowBalances;
+    private isCreditOnTransaction_;
+    private getPropertyKeys;
+    private getAttachmentHeaders;
+    private getRemoteIdHeaders;
+    private addPropertiesToLine;
+    private addRemoteIdsToLine;
+    private addUrlsToLine;
+    private getUrls;
+}
+
+/**
+ * Enum that represents the status of a Transaction.
+ *
+ * @public
+ */
+export declare enum TransactionStatus {
+    /**
+     * Transaction is in the trash
+     */
+    TRASHED = "TRASHED",
+    /**
+     * Transaction is a draft, not yet posted
+     */
+    DRAFT = "DRAFT",
+    /**
+     * Transaction is posted but not checked
+     */
+    UNCHECKED = "UNCHECKED",
+    /**
+     * Transaction is posted and checked
+     */
+    CHECKED = "CHECKED"
+}
+
 /**
  * This class defines a User on the Bkper platform.
  *

package/lib/index.js

@@ -5,31 +5,35 @@
  *
  * @packageDocumentation
  */
-export { Account } from "./model/Account.js";
-export { Agent } from "./model/Agent.js";
-export { Amount } from "./model/Amount.js";
-export { App } from "./model/App.js";
-export { Backlog } from "./model/Backlog.js";
-export { Balance } from "./model/Balance.js";
-export { BalancesDataTableBuilder } from "./model/BalancesDataTableBuilder.js";
-export { BalancesReport } from "./model/BalancesReport.js";
-export { Billing } from "./model/Billing.js";
-export { Bkper } from "./model/Bkper.js";
-export { Book } from "./model/Book.js";
-export { Collaborator } from "./model/Collaborator.js";
-export { Collection } from "./model/Collection.js";
-export { Connection } from "./model/Connection.js";
-export { File } from "./model/File.js";
-export { Group } from "./model/Group.js";
-export { Integration } from "./model/Integration.js";
-export { Query } from "./model/Query.js";
-export { Template } from "./model/Template.js";
-export { Transaction } from "./model/Transaction.js";
-export { TransactionList } from "./model/TransactionList.js";
-export { Event } from "./model/Event.js";
-export { BotResponse } from "./model/BotResponse.js";
-export { EventList } from "./model/EventList.js";
-export { User } from "./model/User.js";
-export { Periodicity, DecimalSeparator, Permission, Visibility, AccountType, BalanceType, Period, Month, EventType, BotResponseType, } from "./model/Enums.js";
-export { BkperError } from "./model/BkperError.js";
+export { Account } from './model/Account.js';
+export { AccountsDataTableBuilder } from './builders/AccountsDataTableBuilder.js';
+export { Agent } from './model/Agent.js';
+export { Amount } from './model/Amount.js';
+export { App } from './model/App.js';
+export { Backlog } from './model/Backlog.js';
+export { Balance } from './model/Balance.js';
+export { BalancesDataTableBuilder } from './builders/BalancesDataTableBuilder.js';
+export { BalancesReport } from './model/BalancesReport.js';
+export { Billing } from './model/Billing.js';
+export { Bkper } from './model/Bkper.js';
+export { Book } from './model/Book.js';
+export { BooksDataTableBuilder } from './builders/BooksDataTableBuilder.js';
+export { Collaborator } from './model/Collaborator.js';
+export { Collection } from './model/Collection.js';
+export { Connection } from './model/Connection.js';
+export { File } from './model/File.js';
+export { Group } from './model/Group.js';
+export { GroupsDataTableBuilder } from './builders/GroupsDataTableBuilder.js';
+export { Integration } from './model/Integration.js';
+export { Query } from './model/Query.js';
+export { Template } from './model/Template.js';
+export { Transaction } from './model/Transaction.js';
+export { TransactionList } from './model/TransactionList.js';
+export { TransactionsDataTableBuilder } from './builders/TransactionsDataTableBuilder.js';
+export { Event } from './model/Event.js';
+export { BotResponse } from './model/BotResponse.js';
+export { EventList } from './model/EventList.js';
+export { User } from './model/User.js';
+export { Periodicity, DecimalSeparator, Permission, Visibility, AccountType, BalanceType, Period, Month, EventType, BotResponseType, TransactionStatus, } from './model/Enums.js';
+export { BkperError } from './model/BkperError.js';
 //# sourceMappingURL=index.js.map

package/lib/model/Account.js

@@ -7,11 +7,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import * as AccountService from "../service/account-service.js";
-import * as GroupService from "../service/group-service.js";
-import { Group } from "./Group.js";
-import { normalizeText } from "../utils.js";
-import { ResourceProperty } from "./ResourceProperty.js";
+import * as AccountService from '../service/account-service.js';
+import { Group } from './Group.js';
+import { normalizeText } from '../utils.js';
+import { ResourceProperty } from './ResourceProperty.js';
 /**
  * This class defines an [Account](https://en.wikipedia.org/wiki/Account_(bookkeeping)) of a [[Book]].
  *
@@ -168,6 +167,10 @@ export class Account extends ResourceProperty {
     /**
      * Gets the [[Groups]] of this Account.
      *
+     * When groups are already embedded in the account payload (e.g. from
+     * {@link Bkper.getBook} with includeGroups), resolves them from the
+     * book's cache instead of making API calls.
+     *
      * @returns Promise with the [[Groups]] of this Account
      */
     getGroups() {
@@ -176,9 +179,20 @@ export class Account extends ResourceProperty {
             if (!id) {
                 return [];
             }
-            let groups = yield GroupService.getGroupsByAccountId(this.book.getId(), id, this.getConfig());
-            let groupsObj = groups.map((group) => new Group(this.book, group));
-            return groupsObj;
+            //Ensure groups are pre-loaded in the book cache to avoid multiple API calls when resolving groups from the payload
+            yield this.book.getGroups();
+            // resolve them from the book's group cache to get properly tree-linked Group objects
+            if (this.payload.groups != null) {
+                const groups = [];
+                for (const groupPayload of this.payload.groups) {
+                    const group = yield this.book.getGroup(groupPayload.id);
+                    if (group) {
+                        groups.push(group);
+                    }
+                }
+                return groups;
+            }
+            return [];
         });
     }
     /**
@@ -191,7 +205,7 @@ export class Account extends ResourceProperty {
     setGroups(groups) {
         this.payload.groups = undefined;
         if (groups != null) {
-            groups.forEach((group) => this.addGroup(group));
+            groups.forEach(group => this.addGroup(group));
         }
         return this;
     }
@@ -228,7 +242,7 @@ export class Account extends ResourceProperty {
                 if (group instanceof Group) {
                     groupObject = group;
                 }
-                else if (typeof group == "string") {
+                else if (typeof group == 'string') {
                     groupObject = yield this.book.getGroup(group);
                 }
                 if (groupObject) {

package/lib/model/BalancesContainerAccount.js

@@ -7,10 +7,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { getRepresentativeValue, normalizeName } from "../utils.js";
-import { Amount } from "./Amount.js";
-import { Balance } from "./Balance.js";
-import { BalancesDataTableBuilder } from "./BalancesDataTableBuilder.js";
+import { getRepresentativeValue, normalizeName } from '../utils.js';
+import { Amount } from './Amount.js';
+import { Balance } from './Balance.js';
+import { BalancesDataTableBuilder } from '../builders/BalancesDataTableBuilder.js';
 /** @internal */
 export class AccountBalancesContainer {
     constructor(parent, balancesReport, payload) {

package/lib/model/BalancesContainerGroup.js

@@ -7,11 +7,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { Amount } from "./Amount.js";
-import { getRepresentativeValue, normalizeName } from "../utils.js";
-import { AccountBalancesContainer } from "./BalancesContainerAccount.js";
-import { Balance } from "./Balance.js";
-import { BalancesDataTableBuilder } from "./BalancesDataTableBuilder.js";
+import { Amount } from './Amount.js';
+import { getRepresentativeValue, normalizeName } from '../utils.js';
+import { AccountBalancesContainer } from './BalancesContainerAccount.js';
+import { Balance } from './Balance.js';
+import { BalancesDataTableBuilder } from '../builders/BalancesDataTableBuilder.js';
 /** @internal */
 export class GroupBalancesContainer {
     constructor(parent, balancesReport, payload) {

package/lib/model/BalancesReport.js

@@ -1,7 +1,7 @@
 import { normalizeName } from '../utils.js';
-import { AccountBalancesContainer } from "./BalancesContainerAccount.js";
-import { GroupBalancesContainer } from "./BalancesContainerGroup.js";
-import { BalancesDataTableBuilder } from './BalancesDataTableBuilder.js';
+import { AccountBalancesContainer } from './BalancesContainerAccount.js';
+import { GroupBalancesContainer } from './BalancesContainerGroup.js';
+import { BalancesDataTableBuilder } from '../builders/BalancesDataTableBuilder.js';
 /**
  * Class representing a Balance Report, generated when calling [Book.getBalanceReport](#book_getbalancesreport)
  *