bkper-js 1.18.1 → 1.19.0

package/lib/index.d.ts

@@ -371,6 +371,161 @@ export declare class App {
     update(): Promise<App>;
 }
 
+/**
+ * The container of balances of an [[Account]] or [[Group]]
+ *
+ * The container is composed of a list of [[Balances]] for a window of time, as well as its period and cumulative totals.
+ *
+ * @public
+ */
+export declare interface BalancesContainer {
+    /**
+     * @returns The parent BalancesReport of the container
+     */
+    getBalancesReport(): BalancesReport;
+    /**
+     * @returns The [[Account]] or [[Group]] name
+     */
+    getName(): string | undefined;
+    /**
+     * @returns The [[Account]] or [[Group]] name without spaces or special characters.
+     */
+    getNormalizedName(): string | undefined;
+    /**
+     * @returns The [[Group]] associated with this container
+     */
+    getGroup(): Promise<Group | null>;
+    /**
+     * @returns The [[Account]] associated with this container
+     */
+    getAccount(): Promise<Account | null>;
+    /**
+     * @returns The parent BalanceContainer.
+     */
+    getParent(): BalancesContainer | null;
+    /**
+     * @returns The depth in the parent chain up to the root.
+     */
+    getDepth(): number;
+    /**
+     * @returns Gets the credit nature of the BalancesContainer, based on [[Account]] or [[Group]].
+     *
+     * For [[Account]], the credit nature will be the same as the one from the Account
+     *
+     * For [[Group]], the credit nature will be the same, if all accounts containing on it has the same credit nature. False if mixed.
+     *
+     */
+    isCredit(): boolean | undefined;
+    /**
+     *
+     * Tell if this balance container is permament, based on the [[Account]] or [[Group]].
+     *
+     * Permanent are the ones which final balance is relevant and keep its balances over time.
+     *
+     * They are also called [Real Accounts](http://en.wikipedia.org/wiki/Account_(accountancy)#Based_on_periodicity_of_flow)
+     *
+     * Usually represents assets or liabilities, capable of being perceived by the senses or the mind, like bank accounts, money, debts and so on.
+     *
+     * @returns True if its a permanent Account
+     */
+    isPermanent(): boolean | undefined;
+    /**
+     * @returns True if this balance container if from an [[Account]]
+     */
+    isFromAccount(): boolean;
+    /**
+     * @returns True if this balance container if from a [[Group]]
+     */
+    isFromGroup(): boolean;
+    /**
+     * @returns True if the balance container is from a parent group
+     */
+    hasGroupBalances(): boolean;
+    /**
+     * @returns The cumulative balance to the date.
+     */
+    getCumulativeBalance(): Amount;
+    /**
+     * @returns The cumulative raw balance to the date.
+     */
+    getCumulativeBalanceRaw(): Amount;
+    /**
+     * @returns The cumulative balance formatted according to [[Book]] decimal format and fraction digits.
+     */
+    getCumulativeBalanceText(): string;
+    /**
+     * @returns The cumulative raw balance formatted according to [[Book]] decimal format and fraction digits.
+     */
+    getCumulativeBalanceRawText(): string;
+    /**
+     * @returns The balance on the date period.
+     */
+    getPeriodBalance(): Amount;
+    /**
+     * @returns The raw balance on the date period.
+     */
+    getPeriodBalanceRaw(): Amount;
+    /**
+     * @returns The balance on the date period formatted according to [[Book]] decimal format and fraction digits
+     */
+    getPeriodBalanceText(): string;
+    /**
+     * @returns The raw balance on the date period formatted according to [[Book]] decimal format and fraction digits
+     */
+    getPeriodBalanceRawText(): string;
+    /**
+     * @returns All child [[BalancesContainers]].
+     *
+     * **NOTE**: Only for Group balance containers. Accounts returns null.
+     */
+    getBalancesContainers(): BalancesContainer[];
+    /**
+     * Gets a specific [[BalancesContainer]].
+     *
+     * @param name The [[Account]] or [[Group]] name.
+     *
+     * @returns The retrieved [[BalancesContainer]].
+     */
+    getBalancesContainer(name: string): BalancesContainer;
+}
+
+/**
+ * Class representing a Balance Report, generated when calling [Book.getBalanceReport](#book_getbalancesreport)
+ *
+ * @public
+ */
+export declare class BalancesReport {
+    payload: bkper.Balances;
+
+
+
+
+    constructor(book: Book, payload: bkper.Balances);
+    /**
+     * @returns The [[Book]] that generated the report.
+     */
+    getBook(): Book;
+    /**
+     * @returns The [[Periodicity]] of the query used to generate the report.
+     */
+    getPeriodicity(): Periodicity;
+    /**
+     * @returns All [[BalancesContainers]] of the report.
+     */
+    getBalancesContainers(): BalancesContainer[];
+    /**
+     * Gets a specific [[BalancesContainer]].
+     *
+     * @param name The [[Account]] or [[Group]] name.
+     *
+     * @returns The retrieved [[BalancesContainer]].
+     */
+    getBalancesContainer(name: string): BalancesContainer;
+
+
+
+}
+
 /**
  * This is the main entry point of the [bkper-js](https://www.npmjs.com/package/bkper-js) library.
  *
@@ -820,6 +975,25 @@ export declare class Book {
      * Perform update Book, applying pending changes.
      */
     update(): Promise<Book>;
+    /**
+     *
+     * Create a [[BalancesReport]] based on query
+     *
+     * @param query The balances report query
+     *
+     * @return The balances report
+     *
+     * Example:
+     *
+     * ```js
+     * var book = BkperApp.getBook("agtzfmJrcGVyLWhyZHITCxIGTGVkZ2VyGICAgPXjx7oKDA");
+     *
+     * var balancesReport = book.getBalancesReport("group:'Equity' after:7/2018 before:8/2018");
+     *
+     * var accountBalance = balancesReport.getBalancesContainer("Bank Account").getCumulativeBalance();
+     * ```
+     */
+    getBalancesReport(query: string): Promise<BalancesReport>;
 }
 
 /**
@@ -1334,6 +1508,14 @@ export declare class Group {
      *  Hide/Show group on main menu.
      */
     setHidden(hidden: boolean): Group;
+    /**
+     * Tell if this is a credit (Incoming and Liabities) group
+     */
+    isCredit(): boolean | undefined;
+    /**
+     * Tell if this is a mixed (Assets/Liabilities or Incoming/Outgoing) group
+     */
+    isMixed(): boolean | undefined;
     /**
      * Tell if the Group is permanent
      */

package/lib/index.js

@@ -8,6 +8,7 @@
 export { Account } from './model/Account.js';
 export { Amount } from "./model/Amount.js";
 export { App } from './model/App.js';
+export { BalancesReport } from './model/BalancesReport.js';
 export { Bkper } from './model/Bkper.js';
 export { Book } from './model/Book.js';
 export { Collection } from './model/Collection.js';

package/lib/model/BalancesContainer.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=BalancesContainer.js.map

package/lib/model/BalancesContainerAccount.js

@@ -0,0 +1,99 @@
+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 { getRepresentativeValue, normalizeName } from "../utils";
+import { Amount } from "./Amount";
+/** @internal */
+export class AccountBalancesContainer {
+    constructor(parent, balancesReport, payload) {
+        this.parent = parent;
+        this.balancesReport = balancesReport;
+        this.payload = payload;
+    }
+    getBalancesReport() {
+        return this.balancesReport;
+    }
+    getName() {
+        return this.payload.name;
+    }
+    getNormalizedName() {
+        return this.payload.normalizedName;
+    }
+    getGroup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return null;
+        });
+    }
+    getAccount() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const account = yield this.balancesReport.getBook().getAccount(this.getNormalizedName());
+            return account || null;
+        });
+    }
+    getParent() {
+        return this.parent;
+    }
+    getDepth() {
+        if (this.depth == null) {
+            const parent = this.getParent();
+            this.depth = parent != null ? parent.getDepth() + 1 : 0;
+        }
+        return this.depth;
+    }
+    isCredit() {
+        return this.payload.credit;
+    }
+    isPermanent() {
+        return this.payload.permanent;
+    }
+    isFromAccount() {
+        return true;
+    }
+    isFromGroup() {
+        return false;
+    }
+    hasGroupBalances() {
+        return false;
+    }
+    getCumulativeBalance() {
+        return getRepresentativeValue(new Amount(this.payload.cumulativeBalance || 0), this.isCredit());
+    }
+    getCumulativeBalanceRaw() {
+        return new Amount(this.payload.cumulativeBalance || 0);
+    }
+    getCumulativeBalanceText() {
+        return this.balancesReport.getBook().formatValue(this.getCumulativeBalance());
+    }
+    getCumulativeBalanceRawText() {
+        return this.balancesReport.getBook().formatValue(this.getCumulativeBalanceRaw());
+    }
+    getPeriodBalance() {
+        return getRepresentativeValue(new Amount(this.payload.periodBalance || 0), this.isCredit());
+    }
+    getPeriodBalanceRaw() {
+        return new Amount(this.payload.periodBalance || 0);
+    }
+    getPeriodBalanceText() {
+        return this.balancesReport.getBook().formatValue(this.getPeriodBalance());
+    }
+    getPeriodBalanceRawText() {
+        return this.balancesReport.getBook().formatValue(this.getPeriodBalanceRaw());
+    }
+    getBalancesContainers() {
+        return [];
+    }
+    getBalancesContainer(name) {
+        const normalizedName = normalizeName(name);
+        if (this.getNormalizedName() == normalizedName) {
+            return this;
+        }
+        throw `${name} does not match ${this.getName()}`;
+    }
+}
+//# sourceMappingURL=BalancesContainerAccount.js.map

package/lib/model/BalancesContainerGroup.js

@@ -0,0 +1,160 @@
+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 { Amount } from "./Amount";
+import { getRepresentativeValue, normalizeName } from "../utils";
+import { AccountBalancesContainer } from "./BalancesContainerAccount";
+/** @internal */
+export class GroupBalancesContainer {
+    constructor(parent, balancesReport, payload) {
+        this.parent = parent;
+        this.balancesReport = balancesReport;
+        this.payload = payload;
+    }
+    getBalancesReport() {
+        return this.balancesReport;
+    }
+    getName() {
+        return this.payload.name;
+    }
+    getNormalizedName() {
+        return this.payload.normalizedName;
+    }
+    getGroup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const group = yield this.balancesReport.getBook().getGroup(this.getNormalizedName());
+            return group || null;
+        });
+    }
+    getAccount() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return null;
+        });
+    }
+    getParent() {
+        return this.parent;
+    }
+    getDepth() {
+        if (this.depth == null) {
+            const parent = this.getParent();
+            this.depth = parent != null ? parent.getDepth() + 1 : 0;
+        }
+        return this.depth;
+    }
+    isCredit() {
+        return this.payload.credit;
+    }
+    isPermanent() {
+        return this.payload.permanent;
+    }
+    isFromAccount() {
+        return false;
+    }
+    isFromGroup() {
+        return true;
+    }
+    hasGroupBalances() {
+        const groupContainers = this.getGroupContainers();
+        return groupContainers != null && groupContainers.length > 0;
+    }
+    getCumulativeBalance() {
+        return getRepresentativeValue(new Amount(this.payload.cumulativeBalance || 0), this.isCredit());
+    }
+    getCumulativeBalanceRaw() {
+        return new Amount(this.payload.cumulativeBalance || 0);
+    }
+    getCumulativeBalanceText() {
+        return this.balancesReport.getBook().formatValue(this.getCumulativeBalance());
+    }
+    getCumulativeBalanceRawText() {
+        return this.balancesReport.getBook().formatValue(this.getCumulativeBalanceRaw());
+    }
+    getPeriodBalance() {
+        return getRepresentativeValue(new Amount(this.payload.periodBalance || 0), this.isCredit());
+    }
+    getPeriodBalanceRaw() {
+        return new Amount(this.payload.periodBalance || 0);
+    }
+    getPeriodBalanceText() {
+        return this.balancesReport.getBook().formatValue(this.getPeriodBalance());
+    }
+    getPeriodBalanceRawText() {
+        return this.balancesReport.getBook().formatValue(this.getPeriodBalanceRaw());
+    }
+    getBalancesContainers() {
+        let containers = [];
+        const groupContainers = this.getGroupContainers();
+        if (groupContainers && groupContainers.length > 0) {
+            containers = containers.concat(groupContainers);
+        }
+        const accountContainers = this.getAccountContainers();
+        if (accountContainers && accountContainers.length > 0) {
+            containers = containers.concat(accountContainers);
+        }
+        return containers;
+    }
+    /** @internal */
+    getGroupContainers() {
+        let groupBalances = this.payload.groupBalances;
+        if (this.groupBalances == null && groupBalances != null) {
+            this.groupBalances = [];
+            for (let i = 0; i < groupBalances.length; i++) {
+                const groupBalance = groupBalances[i];
+                this.groupBalances.push(new GroupBalancesContainer(this, this.balancesReport, groupBalance));
+            }
+        }
+        return this.groupBalances || [];
+    }
+    /** @internal */
+    getAccountContainers() {
+        let accountBalances = this.payload.accountBalances;
+        if (this.accountBalances == null && accountBalances != null) {
+            this.accountBalances = [];
+            for (let i = 0; i < accountBalances.length; i++) {
+                const accountBalance = accountBalances[i];
+                this.accountBalances.push(new AccountBalancesContainer(this, this.balancesReport, accountBalance));
+            }
+        }
+        return this.accountBalances || [];
+    }
+    getBalancesContainer(name) {
+        var _a;
+        const normalizedName = normalizeName(name);
+        const rootContainers = this.getBalancesContainers();
+        if (rootContainers == null || rootContainers.length === 0) {
+            throw `${name} not found on group ${this.getName()}`;
+        }
+        if (this.balancesContainersMap == null) {
+            this.balancesContainersMap = this.fillBalancesContainersMap(new Map(), rootContainers);
+        }
+        const balancesContainer = (_a = this.balancesContainersMap) === null || _a === void 0 ? void 0 : _a.get(normalizedName);
+        if (!balancesContainer) {
+            throw `${name} not found on group ${this.getName()}`;
+        }
+        return balancesContainer;
+    }
+    /** @internal */
+    fillBalancesContainersMap(map, containers) {
+        for (let i = 0; i < containers.length; i++) {
+            const container = containers[i];
+            const normalizedName = container.getNormalizedName();
+            if (normalizedName) {
+                if (!map.has(normalizedName)) {
+                    map.set(normalizedName, container);
+                }
+            }
+            const nextContainers = container.getBalancesContainers();
+            if (nextContainers && nextContainers.length > 0) {
+                this.fillBalancesContainersMap(map, nextContainers);
+            }
+        }
+        return map;
+    }
+}
+//# sourceMappingURL=BalancesContainerGroup.js.map

package/lib/model/BalancesReport.js

@@ -0,0 +1,106 @@
+import { normalizeName } from "../utils";
+import { AccountBalancesContainer } from "./BalancesContainerAccount";
+import { GroupBalancesContainer } from "./BalancesContainerGroup";
+/**
+ * Class representing a Balance Report, generated when calling [Book.getBalanceReport](#book_getbalancesreport)
+ *
+ * @public
+ */
+export class BalancesReport {
+    constructor(book, payload) {
+        this.book = book;
+        this.payload = payload;
+    }
+    /**
+     * @returns The [[Book]] that generated the report.
+     */
+    getBook() {
+        return this.book;
+    }
+    /**
+     * @returns The [[Periodicity]] of the query used to generate the report.
+     */
+    getPeriodicity() {
+        return this.payload.periodicity;
+    }
+    /**
+     * @returns All [[BalancesContainers]] of the report.
+     */
+    getBalancesContainers() {
+        let containers = [];
+        const accountContainers = this.getRootAccountBalancesContainers();
+        if (accountContainers && accountContainers.length > 0) {
+            containers = containers.concat(accountContainers);
+        }
+        const groupContainers = this.getGroupBalancesContainers();
+        if (groupContainers && groupContainers.length > 0) {
+            containers = containers.concat(groupContainers);
+        }
+        return containers;
+    }
+    /**
+     * Gets a specific [[BalancesContainer]].
+     *
+     * @param name The [[Account]] or [[Group]] name.
+     *
+     * @returns The retrieved [[BalancesContainer]].
+     */
+    getBalancesContainer(name) {
+        var _a;
+        const normalizedName = normalizeName(name);
+        const rootContainers = this.getBalancesContainers();
+        if (rootContainers == null || rootContainers.length === 0) {
+            throw `${name} not found`;
+        }
+        if (this.balancesContainersMap == null) {
+            this.balancesContainersMap = this.fillBalancesContainersMap(new Map(), rootContainers);
+        }
+        const balancesContainer = (_a = this.balancesContainersMap) === null || _a === void 0 ? void 0 : _a.get(normalizedName);
+        if (!balancesContainer) {
+            throw `${name} not found`;
+        }
+        return balancesContainer;
+    }
+    /** @internal */
+    getRootAccountBalancesContainers() {
+        if (this.accountBalancesContainers == null && this.payload.accountBalances != null) {
+            this.accountBalancesContainers = [];
+            for (let i = 0; i < this.payload.accountBalances.length; i++) {
+                const accountBalances = this.payload.accountBalances[i];
+                const accountBalancesContainer = new AccountBalancesContainer(null, this, accountBalances);
+                this.accountBalancesContainers.push(accountBalancesContainer);
+            }
+        }
+        return this.accountBalancesContainers || [];
+    }
+    /** @internal */
+    getGroupBalancesContainers() {
+        if (this.groupBalancesContainers == null && this.payload.groupBalances != null) {
+            this.groupBalancesContainers = [];
+            for (let i = 0; i < this.payload.groupBalances.length; i++) {
+                const groupBalances = this.payload.groupBalances[i];
+                const groupBalancesContainer = new GroupBalancesContainer(null, this, groupBalances);
+                this.groupBalancesContainers.push(groupBalancesContainer);
+            }
+        }
+        return this.groupBalancesContainers || [];
+    }
+    /** @internal */
+    fillBalancesContainersMap(map, containers) {
+        for (let i = 0; i < containers.length; i++) {
+            const container = containers[i];
+            const normalizedName = container.getNormalizedName();
+            if (normalizedName) {
+                if (!map.has(normalizedName)) {
+                    map.set(normalizedName, container);
+                }
+            }
+            const nextContainers = container.getBalancesContainers();
+            if (nextContainers && nextContainers.length > 0) {
+                this.fillBalancesContainersMap(map, nextContainers);
+            }
+        }
+        return map;
+    }
+}
+//# sourceMappingURL=BalancesReport.js.map

package/lib/model/Book.js

@@ -9,6 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import * as AccountService from '../service/account-service.js';
 import * as BookService from '../service/book-service.js';
+import * as BalancesService from '../service/balances-service.js';
 import * as FileService from '../service/file-service.js';
 import * as GroupService from '../service/group-service.js';
 import * as IntegrationService from '../service/integration-service.js';
@@ -24,6 +25,7 @@ import { Group } from './Group.js';
 import { Integration } from './Integration.js';
 import { Transaction } from './Transaction.js';
 import { TransactionList } from './TransactionList.js';
+import { BalancesReport } from './BalancesReport.js';
 /**
  *
  * A Book represents [General Ledger](https://en.wikipedia.org/wiki/General_ledger) for a company or business, but can also represent a [Ledger](https://en.wikipedia.org/wiki/Ledger) for a project or department
@@ -707,5 +709,29 @@ export class Book {
             return this;
         });
     }
+    /**
+   *
+   * Create a [[BalancesReport]] based on query
+   *
+   * @param query The balances report query
+   *
+   * @return The balances report
+   *
+   * Example:
+   *
+   * ```js
+   * var book = BkperApp.getBook("agtzfmJrcGVyLWhyZHITCxIGTGVkZ2VyGICAgPXjx7oKDA");
+   *
+   * var balancesReport = book.getBalancesReport("group:'Equity' after:7/2018 before:8/2018");
+   *
+   * var accountBalance = balancesReport.getBalancesContainer("Bank Account").getCumulativeBalance();
+   * ```
+   */
+    getBalancesReport(query) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const balances = yield BalancesService.getBalances(this.getId(), query);
+            return new BalancesReport(this, balances);
+        });
+    }
 }
 //# sourceMappingURL=Book.js.map

package/lib/model/Group.js

@@ -162,6 +162,18 @@ export class Group {
         this.payload.hidden = hidden;
         return this;
     }
+    /**
+     * Tell if this is a credit (Incoming and Liabities) group
+     */
+    isCredit() {
+        return this.payload.credit;
+    }
+    /**
+     * Tell if this is a mixed (Assets/Liabilities or Incoming/Outgoing) group
+     */
+    isMixed() {
+        return this.payload.mixed;
+    }
     /**
      * Tell if the Group is permanent
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bkper-js",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "description": "Javascript client for Bkper REST API",
   "main": "./lib/index.js",
   "module": "./lib/index.js",