bkper-js 2.0.0 → 2.2.0

package/lib/model/BalancesDataTableBuilder.js

@@ -0,0 +1,587 @@
+import { Amount } from "./Amount";
+import { BalanceType } from "./Enums";
+import * as Utils from '../utils.js';
+/**
+ * A BalancesDataTableBuilder is used to setup and build two-dimensional arrays containing balance information.
+ *
+ * @public
+ */
+export class BalancesDataTableBuilder {
+    constructor(book, balancesContainers, periodicity) {
+        this.maxDepth = 0;
+        this.expandAllAccounts = false;
+        this.expandAllGroups = false;
+        this.skipRoot = false;
+        this.book = book;
+        this.balancesContainers = balancesContainers;
+        this.periodicity = periodicity;
+        this.balanceType = BalanceType.TOTAL;
+        this.shouldFormatDate = false;
+        this.shouldHideDates = false;
+        this.shouldHideNames = false;
+        this.shouldFormatValue = false;
+        this.shouldTranspose = false;
+        this.shouldTrial = false;
+        this.shouldPeriod = false;
+        this.shouldRaw = false;
+        this.shouldAddProperties = false;
+    }
+    getBalance(balance, permanent) {
+        return this.getRepresentativeBalance(balance, permanent).toNumber();
+    }
+    getRepresentativeBalance(balance, permanent) {
+        if (balance == null) {
+            return new Amount(0);
+        }
+        if (permanent) {
+            return balance.times(-1);
+        }
+        return balance;
+    }
+    getBalanceText(balance, permanent) {
+        return this.book.formatValue(this.getRepresentativeBalance(balance, permanent));
+    }
+    /**
+     * Defines whether the dates should be formatted based on date pattern and periodicity of the [[Book]].
+     *
+     * @returns This builder with respective formatting option, for chaining.
+     */
+    formatDates(format) {
+        this.shouldFormatDate = format;
+        return this;
+    }
+    /**
+     * Defines whether the value should be formatted based on decimal separator of the [[Book]].
+     *
+     * @returns This builder with respective formatting option, for chaining.
+     */
+    formatValues(format) {
+        this.shouldFormatValue = format;
+        return this;
+    }
+    /**
+     * Defines whether Groups should expand its child accounts. true to expand itself, -1 to expand all subgroups. -2 to expand all accounts.
+     *
+     *
+     * @returns This builder with respective expanded option, for chaining.
+     */
+    expanded(expanded) {
+        if (typeof expanded == "boolean" && expanded == true) {
+            this.maxDepth = 1;
+            this.skipRoot = true;
+        }
+        else if (expanded == -1) {
+            this.expandAllGroups = true;
+        }
+        else if (expanded == -2) {
+            this.expandAllAccounts = true;
+        }
+        else if (typeof expanded == "number" && expanded > 0) {
+            this.maxDepth = expanded;
+        }
+        return this;
+    }
+    /**
+     * Fluent method to set the [[BalanceType]] for the builder.
+     *
+     * @param type The type of balance for this data table
+     *
+     * For **TOTAL** [[BalanceType]], the table format looks like:
+     *
+     * ```
+     *   _____________________
+     *  | Expenses  | -4568.23 |
+     *  | Income    |  5678.93 |
+     *  |    ...    |    ...   |
+     *  |___________|__________|
+     *
+     * ```
+     * Two columns, and each [[Account]] or [[Group]] per line.
+     *
+     * For **PERIOD** or **CUMULATIVE** [[BalanceType]], the table will be a time table, and the format looks like:
+     *
+     * ```
+     *  _____________________________________________
+     *  |            |  Expenses | Income  |    ...   |
+     *  | 15/01/2014 | -2345.23  | 3452.93 |    ...   |
+     *  | 15/02/2014 | -2345.93  | 3456.46 |    ...   |
+     *  | 15/03/2014 | -2456.45  | 3567.87 |    ...   |
+     *  |    ...     |    ...    |   ...   |    ...   |
+     *  |____________|___________|_________|__________|
+     *
+     * ```
+     *
+     * First column will be the Date column, and one column for each [[Account]] or [[Group]].
+     *
+     * @returns This builder with respective balance type, for chaining.
+     */
+    type(type) {
+        this.balanceType = type;
+        return this;
+    }
+    /**
+     * Defines whether should rows and columns should be transposed.
+     *
+     * For **TOTAL** [[BalanceType]], the **transposed** table looks like:
+     *
+     * ```
+     *   _____________________________
+     *  |  Expenses | Income  |  ...  |
+     *  | -4568.23  | 5678.93 |  ...  |
+     *  |___________|_________|_______|
+     *
+     * ```
+     * Two rows, and each [[Account]] or [[Group]] per column.
+     *
+     *
+     * For **PERIOD** or **CUMULATIVE** [[BalanceType]], the **transposed** table will be a time table, and the format looks like:
+     *
+     * ```
+     *   _______________________________________________________________
+     *  |            | 15/01/2014 | 15/02/2014 | 15/03/2014 |    ...    |
+     *  |  Expenses  | -2345.23   | -2345.93   | -2456.45   |    ...    |
+     *  |  Income    |  3452.93   |  3456.46   |  3567.87   |    ...    |
+     *  |     ...    |     ...    |     ...    |     ...    |    ...    |
+     *  |____________|____________|____________|____________|___________|
+     *
+     * ```
+     *
+     * First column will be each [[Account]] or [[Group]], and one column for each Date.
+     *
+     * @returns This builder with respective transposed option, for chaining.
+     */
+    transposed(transposed) {
+        this.shouldTranspose = transposed;
+        return this;
+    }
+    /**
+     * Defines whether the dates should be hidden for **PERIOD** or **CUMULATIVE** [[BalanceType]].
+     *
+     * @returns This builder with respective hide dates option, for chaining.
+     */
+    hideDates(hide) {
+        this.shouldHideDates = hide;
+        return this;
+    }
+    /**
+     * Defines whether the [[Accounts]] and [[Groups]] names should be hidden.
+     *
+     * @returns This builder with respective hide names option, for chaining.
+     */
+    hideNames(hide) {
+        this.shouldHideNames = hide;
+        return this;
+    }
+    /**
+     * Defines whether include custom [[Accounts]] and [[Groups]] properties.
+     *
+     * @returns This builder with respective include properties option, for chaining.
+     */
+    properties(include) {
+        this.shouldAddProperties = include;
+        return this;
+    }
+    /**
+     * Defines whether should split **TOTAL** [[BalanceType]] into debit and credit.
+     *
+     * @returns This builder with respective trial option, for chaining.
+     */
+    trial(trial) {
+        this.shouldTrial = trial;
+        return this;
+    }
+    /**
+     * Defines whether should force use of period balances for **TOTAL** [[BalanceType]].
+     *
+     * @returns This builder with respective trial option, for chaining.
+     */
+    period(period) {
+        this.shouldPeriod = period;
+        return this;
+    }
+    /**
+     * Defines whether should show raw balances, no matter the credit nature of the Account or Group.
+     *
+     * @returns This builder with respective trial option, for chaining.
+     */
+    raw(raw) {
+        this.shouldRaw = raw;
+        return this;
+    }
+    /**
+     *
+     * Builds an two-dimensional array with the balances.
+     *
+     */
+    build() {
+        if (this.balanceType == BalanceType.TOTAL) {
+            return this.buildTotalDataTable_();
+        }
+        else {
+            return this.buildTimeDataTable_();
+        }
+    }
+    ////////////////////////
+    addPropertyKeys(propertyKeys, container) {
+        for (const key of container.getPropertyKeys()) {
+            if (propertyKeys.indexOf(key) <= -1) {
+                propertyKeys.push(key);
+            }
+        }
+    }
+    flattenContainers(containersFlat, propertyKeys) {
+        for (const container of this.balancesContainers) {
+            if (this.expandAllAccounts) {
+                this.flattenAllAccounts(container, containersFlat, propertyKeys);
+                containersFlat.sort(this.sortContainersFunction);
+            }
+            else if (this.expandAllGroups) {
+                this.flattenAllGroups(container, containersFlat, propertyKeys);
+            }
+            else {
+                this.flattenMaxDepth(container, containersFlat, propertyKeys);
+            }
+        }
+    }
+    flattenAllAccounts(container, containersFlat, propertyKeys) {
+        if (container.isFromGroup()) {
+            for (const child of container.getBalancesContainers()) {
+                this.flattenAllAccounts(child, containersFlat, propertyKeys);
+            }
+        }
+        else {
+            containersFlat.push(container);
+            if (this.shouldAddProperties) {
+                this.addPropertyKeys(propertyKeys, container);
+            }
+        }
+    }
+    sortContainersFunction(a, b) {
+        let ret = 0;
+        if (a.isPermanent() && !b.isPermanent()) {
+            ret = -1;
+        }
+        else if (!a.isPermanent() && b.isPermanent()) {
+            ret = 1;
+        }
+        if (ret == 0) {
+            if (a.getParent() && !b.getParent()) {
+                ret = -1;
+            }
+            else if (!a.getParent() && b.getParent()) {
+                ret = 1;
+            }
+        }
+        if (ret == 0) {
+            ret = getBalanceTypeOrdinal(a) - getBalanceTypeOrdinal(b);
+        }
+        if (ret == 0) {
+            ret = a.getName().toLowerCase().localeCompare(b.getName().toLowerCase());
+        }
+        function getBalanceTypeOrdinal(bc) {
+            // ASSET(true, false, "asset"),
+            if (bc.isPermanent() && !bc.isCredit()) {
+                return 0;
+            }
+            // LIABILITY(true, true, "liability"),
+            if (bc.isPermanent() && bc.isCredit()) {
+                return 1;
+            }
+            // INCOMING(false, true, "incoming"),
+            if (!bc.isPermanent() && bc.isCredit()) {
+                return 2;
+            }
+            if (!bc.isPermanent() && !bc.isCredit()) {
+                return 3;
+            }
+            return 4;
+        }
+        return ret;
+    }
+    flattenMaxDepth(container, containersFlat, propertyKeys) {
+        let depth = container.getDepth();
+        if (depth <= this.maxDepth) {
+            if (!this.skipRoot && !this.shouldTranspose) {
+                //@ts-ignore
+                container.json.name = Utils_.repeatString(" ", depth * 4) + container.json.name;
+            }
+            if (!this.skipRoot || depth != 0) {
+                containersFlat.push(container);
+                if (this.shouldAddProperties) {
+                    this.addPropertyKeys(propertyKeys, container);
+                }
+            }
+            const children = container.getBalancesContainers();
+            if (children && children.length > 0) {
+                children.sort(this.sortContainersFunction);
+                for (const child of children) {
+                    this.flattenMaxDepth(child, containersFlat, propertyKeys);
+                }
+            }
+        }
+    }
+    flattenAllGroups(container, containersFlat, propertyKeys) {
+        if (container.isFromGroup()) {
+            if (!this.shouldTranspose) {
+                let depth = container.getDepth();
+                //@ts-ignore
+                container.json.name = Utils_.repeatString(" ", depth * 4) + container.json.name;
+            }
+            containersFlat.push(container);
+            if (this.shouldAddProperties) {
+                this.addPropertyKeys(propertyKeys, container);
+            }
+            if (container.hasGroupBalances()) {
+                const children = container.getBalancesContainers();
+                children.sort(this.sortContainersFunction);
+                for (const child of children) {
+                    this.flattenAllGroups(child, containersFlat, propertyKeys);
+                }
+            }
+        }
+    }
+    buildTotalDataTable_() {
+        var table = new Array();
+        if (this.balancesContainers == null) {
+            return table;
+        }
+        this.balancesContainers.sort((a, b) => {
+            if (a != null && b != null) {
+                return a.getName().toLowerCase().localeCompare(b.getName().toLowerCase());
+            }
+            return -1;
+        });
+        let propertyKeys = [];
+        let containers = new Array();
+        this.flattenContainers(containers, propertyKeys);
+        if (this.shouldAddProperties) {
+            propertyKeys.sort();
+            let header = ['name', 'balance'];
+            for (const key of propertyKeys) {
+                header.push(key);
+            }
+            table.push(header);
+        }
+        for (var i = 0; i < containers.length; i++) {
+            var balances = containers[i];
+            if (balances != null) {
+                var line = new Array();
+                var name = balances.getName();
+                line.push(name);
+                if (this.shouldTrial) {
+                    if (this.shouldFormatValue) {
+                        if (this.shouldPeriod) {
+                            line.push(balances.getPeriodDebitText());
+                            line.push(balances.getPeriodCreditText());
+                        }
+                        else {
+                            line.push(balances.getCumulativeDebitText());
+                            line.push(balances.getCumulativeCreditText());
+                        }
+                    }
+                    else {
+                        if (this.shouldPeriod) {
+                            line.push(balances.getPeriodDebit().toNumber());
+                            line.push(balances.getPeriodCredit().toNumber());
+                        }
+                        else {
+                            line.push(balances.getCumulativeDebit().toNumber());
+                            line.push(balances.getCumulativeCredit().toNumber());
+                        }
+                    }
+                }
+                else {
+                    if (this.shouldFormatValue) {
+                        if (this.shouldPeriod) {
+                            if (this.shouldRaw) {
+                                line.push(balances.getPeriodBalanceRawText());
+                            }
+                            else {
+                                line.push(this.getBalanceText(balances.getPeriodBalanceRaw(), balances.isPermanent()));
+                            }
+                        }
+                        else {
+                            if (this.shouldRaw) {
+                                line.push(balances.getCumulativeBalanceRawText());
+                            }
+                            else {
+                                line.push(this.getBalanceText(balances.getCumulativeBalanceRaw(), balances.isPermanent()));
+                            }
+                        }
+                    }
+                    else {
+                        if (this.shouldPeriod) {
+                            if (this.shouldRaw) {
+                                line.push(balances.getPeriodBalanceRaw().toNumber());
+                            }
+                            else {
+                                line.push(this.getBalance(balances.getPeriodBalanceRaw(), balances.isPermanent()));
+                            }
+                        }
+                        else {
+                            if (this.shouldRaw) {
+                                line.push(balances.getCumulativeBalanceRaw().toNumber());
+                            }
+                            else {
+                                line.push(this.getBalance(balances.getCumulativeBalanceRaw(), balances.isPermanent()));
+                            }
+                        }
+                    }
+                }
+                if (this.shouldAddProperties) {
+                    const properties = balances.getProperties();
+                    for (const key of propertyKeys) {
+                        let propertyValue = properties[key];
+                        if (propertyValue) {
+                            line.push(propertyValue);
+                            continue;
+                        }
+                        line.push('');
+                    }
+                }
+                table.push(line);
+            }
+        }
+        if (this.shouldHideNames) {
+            table = table.map(row => row.slice(1));
+        }
+        if (this.shouldTranspose && table.length > 0) {
+            table = table[0].map((col, i) => table.map(row => row[i]));
+        }
+        return table;
+    }
+    buildTimeDataTable_() {
+        var table = new Array();
+        var dataIndexMap = new Object();
+        var cumulativeBalance = this.balanceType == BalanceType.CUMULATIVE;
+        var header = new Array();
+        header.push("");
+        if (this.balancesContainers == null) {
+            return table;
+        }
+        let propertyKeys = [];
+        let containers = new Array();
+        this.flattenContainers(containers, propertyKeys);
+        for (const container of containers) {
+            header.push(container.getName());
+            var balances = container.getBalances();
+            if (balances != null) {
+                for (const balance of balances) {
+                    var fuzzyDate = balance.getFuzzyDate();
+                    var indexEntry = dataIndexMap[fuzzyDate];
+                    if (indexEntry == null) {
+                        indexEntry = {};
+                        indexEntry.date = balance.getDate();
+                        dataIndexMap[fuzzyDate] = indexEntry;
+                    }
+                    var amount;
+                    if (cumulativeBalance) {
+                        amount = balance.getCumulativeBalanceRaw();
+                    }
+                    else {
+                        amount = balance.getPeriodBalanceRaw();
+                    }
+                    indexEntry[container.getName()] = this.shouldRaw ? amount : this.getRepresentativeBalance(amount, container.isPermanent());
+                }
+            }
+        }
+        table.push(header);
+        var rows = new Array();
+        for (var fuzzy in dataIndexMap) {
+            var rowObject = dataIndexMap[fuzzy];
+            var row = new Array();
+            row.push(rowObject.date);
+            for (const container of containers) {
+                var amount = rowObject[container.getName()];
+                if (amount == null) {
+                    amount = "null_amount";
+                }
+                else {
+                    amount = new Amount(amount);
+                    if (this.shouldFormatValue) {
+                        amount = Utils.formatValue(amount, this.book.getDecimalSeparator(), this.book.getFractionDigits());
+                    }
+                    else {
+                        amount = amount.toNumber();
+                    }
+                }
+                row.push(amount);
+            }
+            rows.push(row);
+        }
+        rows.sort(function (a, b) { return a[0].getTime() - b[0].getTime(); });
+        var lastRow = null;
+        for (var i = 0; i < rows.length; i++) {
+            var row = rows[i];
+            if (i == 0) {
+                //first row, all null values will be 0
+                for (var j = 1; j < row.length; j++) {
+                    var cell = row[j];
+                    if (cell == "null_amount") {
+                        var amount = new Amount(0);
+                        if (this.shouldFormatValue) {
+                            amount = Utils.formatValue(amount, this.book.getDecimalSeparator(), this.book.getFractionDigits());
+                        }
+                        else {
+                            amount = amount.toNumber();
+                        }
+                        row[j] = amount;
+                    }
+                }
+            }
+            else {
+                for (var j = 1; j < row.length; j++) {
+                    var cell = row[j];
+                    if (cell == "null_amount" && cumulativeBalance) {
+                        if (lastRow) {
+                            row[j] = lastRow[j];
+                        }
+                    }
+                    else if (cell == "null_amount") {
+                        var amount = new Amount(0);
+                        if (this.shouldFormatValue) {
+                            amount = Utils.formatValue(amount, this.book.getDecimalSeparator(), this.book.getFractionDigits());
+                        }
+                        else {
+                            amount = amount.toNumber();
+                        }
+                        row[j] = amount;
+                    }
+                }
+            }
+            lastRow = row;
+            table.push(row);
+        }
+        if (this.shouldFormatDate && table.length > 0) {
+            var pattern = Utils.getDateFormatterPattern(this.book.getDatePattern(), this.periodicity);
+            for (var j = 1; j < table.length; j++) {
+                var row = table[j];
+                if (row.length > 0) {
+                    //first column
+                    row[0] = Utils.formatDate(row[0], pattern, this.book.getTimeZone());
+                }
+            }
+        }
+        if (this.shouldAddProperties) {
+            propertyKeys.sort();
+            for (const key of propertyKeys) {
+                var propertyRow = [key];
+                for (const container of containers) {
+                    propertyRow.push(container.getProperty(key) || '');
+                }
+                table.push(propertyRow);
+            }
+        }
+        if (this.shouldHideNames) {
+            table.shift();
+        }
+        if (this.shouldHideDates) {
+            table = table.map(row => row.slice(1));
+        }
+        if (this.shouldTranspose && table.length > 0) {
+            table = table[0].map((col, i) => table.map(row => row[i]));
+        }
+        return table;
+    }
+}
+//# sourceMappingURL=BalancesDataTableBuilder.js.map

package/lib/model/Bkper.js

@@ -24,30 +24,40 @@ import { Agent } from "./Agent.js";
 /**
  * This is the main entry point of the [bkper-js](https://www.npmjs.com/package/bkper-js) library.
  *
- * You start by setting the API [[Config]] object.
+ * You start by setting the API [[Config]] object using the static setConfig method.
  *
  * Example:
  *
  * ```javascript
- * Bkper.get().setConfig({
+ * Bkper.setConfig({
  *   apiKeyProvider: () => process.env.BKPER_API_KEY,
  *   oauthTokenProvider: () => process.env.BKPER_OAUTH_TOKEN
- * })
+ * });
+ *
+ * const bkper = new Bkper();
+ * const book = await bkper.getBook('bookId');
  * ```
  *
- * Once the config is set, you can start using the library.
+ * Once the config is set, you can create instances and start using the library.
  *
  * @public
  */
 export class Bkper {
     /**
-     * Creates a new Bkper instance with the specified API configuration.
+     * Sets the global API configuration for all Bkper operations.
      *
-     * @param config - The Config object
+     * @param config - The Config object containing API key and OAuth token providers
      */
-    constructor(config) {
+    static setConfig(config) {
         HttpApiRequest.config = config;
     }
+    /**
+     * Creates a new Bkper instance using the global configuration set via setConfig().
+     * Make sure to call Bkper.setConfig() before creating instances.
+     */
+    constructor() {
+        // Uses global configuration set via setConfig()
+    }
     /**
      * Gets the [[Book]] with the specified bookId from url param.
      *

package/lib/model/Enums.js

@@ -108,6 +108,26 @@ export var AccountType;
      */
     AccountType["OUTGOING"] = "OUTGOING";
 })(AccountType || (AccountType = {}));
+/**
+ * Enum that represents balance types.
+ *
+ * @public
+ */
+export var BalanceType;
+(function (BalanceType) {
+    /**
+     * Total balance
+     */
+    BalanceType["TOTAL"] = "TOTAL";
+    /**
+     * Period balance
+     */
+    BalanceType["PERIOD"] = "PERIOD";
+    /**
+     * Cumulative balance
+     */
+    BalanceType["CUMULATIVE"] = "CUMULATIVE";
+})(BalanceType || (BalanceType = {}));
 /**
  * Enum that represents a period slice.
  *

package/package.json

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