bkper-js 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -8,9 +8,12 @@ See what's new and what has changed in bkper-js
 **July 2025**
 * **BREAKING CHANGE:** Refactored `Bkper` class from static methods to constructor-based pattern
 * **BREAKING CHANGE:** Removed deprecated methods: `Transaction.remove()`, `Transaction.restore()`, `Account.getBalance()`, `Account.getBalanceRaw()`
-* **MIGRATION:** Replace `Bkper.setConfig(config); Bkper.getBook(id)` with `const bkper = new Bkper(config); bkper.getBook(id)`
 * **MIGRATION:** Use `transaction.trash()` and `transaction.untrash()` instead of `remove()` and `restore()`
 * **MIGRATION:** Use `Book.getBalancesReport()` instead of `Account.getBalance()` methods
+* Added [Balance](/docs/bkper-js/#balance) class back for improved balance reporting
+* Added [BalancesDataTableBuilder](/docs/bkper-js/#balancesdatatablebuilder) for building balance data tables
+* Added [BalanceType](/docs/bkper-js/#balancetype) enum with TOTAL, PERIOD, and CUMULATIVE options
+* Updated `Book.getDatePattern()` to return default pattern 'dd/MM/yyyy' when not set
 
 **June 2025**   
 * Added [Book.copy](/docs/bkper-js/#book_copy)

package/README.md

@@ -32,12 +32,15 @@ bun add bkper-js
 ```typescript
 import { Bkper } from 'bkper-js';
 
-// Create Bkper instance with configuration
-const bkper = new Bkper({
+// Set global configuration
+Bkper.setConfig({
   apiKeyProvider: () => process.env.BKPER_API_KEY,
   oauthTokenProvider: () => process.env.BKPER_OAUTH_TOKEN
 });
 
+// Create Bkper instance (uses global config)
+const bkper = new Bkper();
+
 // Get a book and work with it
 const book = await bkper.getBook('your-book-id');
 console.log(`Book: ${book.getName()}`);

package/lib/index.d.ts

@@ -623,6 +623,87 @@ export declare class App {
     update(): Promise<App>;
 }
 
+/**
+ * Class that represents an [[Account]] or [[Group]] balance on a window of time (Day / Month / Year).
+ *
+ * @public
+ */
+declare class Balance {
+    json: bkper.Balance;
+    private container;
+    constructor(container: BalancesContainer, balancePlain: bkper.Balance);
+    /**
+     * The day of the balance. Days starts on 1 to 31.
+     *
+     * Day can be 0 (zero) in case of Monthly or Early [[Periodicity]] of the [[BalancesReport]]
+     */
+    getDay(): number;
+    /**
+     * The month of the balance. Months starts on 1 (January) to 12 (December)
+     *
+     * Month can be 0 (zero) in case of Early [[Periodicity]] of the [[BalancesReport]]
+     */
+    getMonth(): number;
+    /**
+     * The year of the balance
+     */
+    getYear(): number;
+    /**
+     * Date object constructed based on [[Book]] time zone offset. Usefull for
+     *
+     * If Month or Day is zero, the date will be constructed with first Month (January) or Day (1).
+     */
+    getDate(): Date;
+    /**
+     * The Fuzzy Date of the balance, based on [[Periodicity]] of the [[BalancesReport]] query, composed by Year, Month and Day.
+     *
+     * The format is **YYYYMMDD**. Very usefull for ordering and indexing
+     *
+     * Month and Day can be 0 (zero), depending on the granularity of the [[Periodicity]].
+     *
+     * *Example:*
+     *
+     * **20180125** - 25, January, 2018 - DAILY Periodicity
+     *
+     * **20180100** - January, 2018 - MONTHLY Periodicity
+     *
+     * **20180000** - 2018 - YEARLY Periodicity
+     */
+    getFuzzyDate(): number;
+    /**
+     * The cumulative balance to the date, based on the credit nature of the container
+     */
+    getCumulativeBalance(): Amount;
+    /**
+     * The raw cumulative balance to the date.
+     */
+    getCumulativeBalanceRaw(): Amount;
+    /**
+     * The cumulative credit to the date.
+     */
+    getCumulativeCredit(): Amount;
+    /**
+     * The cumulative debit to the date.
+     */
+    getCumulativeDebit(): Amount;
+    /**
+     * The balance on the date period, based on credit nature of the container.
+     */
+    getPeriodBalance(): Amount;
+    /**
+     * The raw balance on the date period.
+     */
+    getPeriodBalanceRaw(): Amount;
+    /**
+     * The credit on the date period.
+     */
+    getPeriodCredit(): Amount;
+    /**
+     * The debit on the date period.
+     */
+    getPeriodDebit(): Amount;
+}
+
 /**
  * The container of balances of an [[Account]] or [[Group]]
  *
@@ -642,13 +723,13 @@ export declare interface BalancesContainer {
      *
      * @returns The [[Account]] or [[Group]] name
      */
-    getName: () => string | undefined;
+    getName: () => string;
     /**
      * Gets the [[Account]] or [[Group]] name without spaces or special characters.
      *
      * @returns The [[Account]] or [[Group]] name without spaces or special characters
      */
-    getNormalizedName: () => string | undefined;
+    getNormalizedName: () => string;
     /**
      * Gets the [[Group]] associated with this container.
      *
@@ -667,6 +748,12 @@ export declare interface BalancesContainer {
      * @returns The parent BalanceContainer
      */
     getParent: () => BalancesContainer | null;
+    /**
+     * Gets all [[Balances]] of the container
+     *
+     * @returns All [[Balances]] of the container
+     */
+    getBalances: () => Balance[];
     /**
      * Gets the depth in the parent chain up to the root.
      *
@@ -694,7 +781,7 @@ export declare interface BalancesContainer {
      *
      * @returns True if its a permanent Account
      */
-    isPermanent: () => boolean | undefined;
+    isPermanent: () => boolean;
     /**
      * Gets whether this balance container is from an [[Account]].
      *
@@ -725,6 +812,14 @@ export declare interface BalancesContainer {
      * @returns The cumulative raw balance to the date
      */
     getCumulativeBalanceRaw: () => Amount;
+    /**
+     * The cumulative credit to the date.
+     */
+    getCumulativeCredit(): Amount;
+    /**
+     * The cumulative debit to the date.
+     */
+    getCumulativeDebit(): Amount;
     /**
      * Gets the cumulative balance formatted according to [[Book]] decimal format and fraction digits.
      *
@@ -737,6 +832,14 @@ export declare interface BalancesContainer {
      * @returns The cumulative raw balance formatted according to [[Book]] decimal format and fraction digits
      */
     getCumulativeBalanceRawText: () => string;
+    /**
+     * The cumulative credit formatted according to [[Book]] decimal format and fraction digits.
+     */
+    getCumulativeCreditText(): string;
+    /**
+     * The cumulative credit formatted according to [[Book]] decimal format and fraction digits.
+     */
+    getCumulativeDebitText(): string;
     /**
      * Gets the balance on the date period.
      *
@@ -749,6 +852,14 @@ export declare interface BalancesContainer {
      * @returns The raw balance on the date period
      */
     getPeriodBalanceRaw: () => Amount;
+    /**
+     * The credit on the date period.
+     */
+    getPeriodCredit(): Amount;
+    /**
+     * The debit on the date period.
+     */
+    getPeriodDebit(): Amount;
     /**
      * Gets the balance on the date period formatted according to [[Book]] decimal format and fraction digits.
      *
@@ -761,6 +872,35 @@ export declare interface BalancesContainer {
      * @returns The raw balance on the date period formatted according to [[Book]] decimal format and fraction digits
      */
     getPeriodBalanceRawText: () => string;
+    /**
+     * The credit on the date period formatted according to [[Book]] decimal format and fraction digits
+     */
+    getPeriodCreditText(): string;
+    /**
+     * The debit on the date period formatted according to [[Book]] decimal format and fraction digits
+     */
+    getPeriodDebitText(): string;
+    /**
+     * Gets the custom properties stored in this Account or Group.
+     */
+    getProperties(): {
+        [key: string]: string;
+    };
+    /**
+     *
+     * Gets the property value for given keys. First property found will be retrieved
+     *
+     * @param keys The property key
+     */
+    getProperty(...keys: string[]): string | undefined;
+    /**
+     * Gets the custom properties keys stored in the associated [[Account]] or [[Group]].
+     */
+    getPropertyKeys(): string[];
+    /**
+     * Creates a BalancesDataTableBuilder to generate a two-dimensional array with all [[BalancesContainers]]
+     */
+    createDataTable(): BalancesDataTableBuilder;
     /**
      * Gets all child [[BalancesContainers]].
      *
@@ -779,6 +919,171 @@ export declare interface BalancesContainer {
     getBalancesContainer: (name: string) => BalancesContainer;
 }
 
+/**
+ * A BalancesDataTableBuilder is used to setup and build two-dimensional arrays containing balance information.
+ *
+ * @public
+ */
+declare class BalancesDataTableBuilder implements BalancesDataTableBuilder {
+    private balanceType;
+    private balancesContainers;
+    private periodicity;
+    private shouldFormatDate;
+    private shouldHideDates;
+    private shouldHideNames;
+    private shouldFormatValue;
+    private book;
+    private shouldTranspose;
+    private shouldTrial;
+    private shouldPeriod;
+    private shouldRaw;
+    private shouldAddProperties;
+    private maxDepth;
+    private expandAllAccounts;
+    private expandAllGroups;
+    private skipRoot;
+    constructor(book: Book, balancesContainers: BalancesContainer[], periodicity: Periodicity);
+    private getBalance;
+    private getRepresentativeBalance;
+    private getBalanceText;
+    /**
+     * 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: boolean): BalancesDataTableBuilder;
+    /**
+     * 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: boolean): BalancesDataTableBuilder;
+    /**
+     * 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: boolean | number): BalancesDataTableBuilder;
+    /**
+     * 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: BalanceType): BalancesDataTableBuilder;
+    /**
+     * 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: boolean): BalancesDataTableBuilder;
+    /**
+     * Defines whether the dates should be hidden for **PERIOD** or **CUMULATIVE** [[BalanceType]].
+     *
+     * @returns This builder with respective hide dates option, for chaining.
+     */
+    hideDates(hide: boolean): BalancesDataTableBuilder;
+    /**
+     * Defines whether the [[Accounts]] and [[Groups]] names should be hidden.
+     *
+     * @returns This builder with respective hide names option, for chaining.
+     */
+    hideNames(hide: boolean): BalancesDataTableBuilder;
+    /**
+     * Defines whether include custom [[Accounts]] and [[Groups]] properties.
+     *
+     * @returns This builder with respective include properties option, for chaining.
+     */
+    properties(include: boolean): BalancesDataTableBuilder;
+    /**
+     * Defines whether should split **TOTAL** [[BalanceType]] into debit and credit.
+     *
+     * @returns This builder with respective trial option, for chaining.
+     */
+    trial(trial: boolean): BalancesDataTableBuilder;
+    /**
+     * Defines whether should force use of period balances for **TOTAL** [[BalanceType]].
+     *
+     * @returns This builder with respective trial option, for chaining.
+     */
+    period(period: boolean): BalancesDataTableBuilder;
+    /**
+     * 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: boolean): BalancesDataTableBuilder;
+    /**
+     *
+     * Builds an two-dimensional array with the balances.
+     *
+     */
+    build(): any[][];
+    private addPropertyKeys;
+    private flattenContainers;
+    private flattenAllAccounts;
+    private sortContainersFunction;
+    private flattenMaxDepth;
+    private flattenAllGroups;
+    private buildTotalDataTable_;
+    private buildTimeDataTable_;
+}
+
 /**
  * Class representing a Balance Report, generated when calling [Book.getBalanceReport](#book_getbalancesreport)
  *
@@ -822,31 +1127,59 @@ export declare class BalancesReport {
 
 }
 
+/**
+ * Enum that represents balance types.
+ *
+ * @public
+ */
+declare enum BalanceType {
+    /**
+     * Total balance
+     */
+    TOTAL = "TOTAL",
+    /**
+     * Period balance
+     */
+    PERIOD = "PERIOD",
+    /**
+     * Cumulative balance
+     */
+    CUMULATIVE = "CUMULATIVE"
+}
+
 /**
  * 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 declare 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
+     */
+    static setConfig(config: Config): void;
+    /**
+     * Creates a new Bkper instance using the global configuration set via setConfig().
+     * Make sure to call Bkper.setConfig() before creating instances.
      */
-    constructor(config: Config);
+    constructor();
     /**
      * Gets the [[Book]] with the specified bookId from url param.
      *
@@ -1031,7 +1364,7 @@ export declare class Book {
      *
      * @returns The date pattern of the Book. Current: dd/MM/yyyy | MM/dd/yyyy | yyyy/MM/dd
      */
-    getDatePattern(): string | undefined;
+    getDatePattern(): string;
     /**
      * Sets the date pattern of the Book. Current: dd/MM/yyyy | MM/dd/yyyy | yyyy/MM/dd
      *

package/lib/model/Balance.js

@@ -0,0 +1,120 @@
+import * as Utils from '../utils.js';
+import { Amount } from "./Amount";
+/**
+ * Class that represents an [[Account]] or [[Group]] balance on a window of time (Day / Month / Year).
+ *
+ * @public
+ */
+export class Balance {
+    constructor(container, balancePlain) {
+        this.container = container;
+        this.json = balancePlain;
+    }
+    /**
+     * The day of the balance. Days starts on 1 to 31.
+     *
+     * Day can be 0 (zero) in case of Monthly or Early [[Periodicity]] of the [[BalancesReport]]
+     */
+    getDay() {
+        return this.json.day;
+    }
+    /**
+     * The month of the balance. Months starts on 1 (January) to 12 (December)
+     *
+     * Month can be 0 (zero) in case of Early [[Periodicity]] of the [[BalancesReport]]
+     */
+    getMonth() {
+        return this.json.month;
+    }
+    /**
+     * The year of the balance
+     */
+    getYear() {
+        return this.json.year;
+    }
+    /**
+     * Date object constructed based on [[Book]] time zone offset. Usefull for
+     *
+     * If Month or Day is zero, the date will be constructed with first Month (January) or Day (1).
+     */
+    getDate() {
+        var year = this.getYear();
+        var month = this.getMonth();
+        var day = this.getDay();
+        if (month == null || month == 0) {
+            year++;
+        }
+        if (day == null || day == 0) {
+            month++;
+        }
+        var date = Utils.createDate(year, month, day, this.container.getBalancesReport().getBook().getTimeZoneOffset());
+        return date;
+    }
+    /**
+     * The Fuzzy Date of the balance, based on [[Periodicity]] of the [[BalancesReport]] query, composed by Year, Month and Day.
+     *
+     * The format is **YYYYMMDD**. Very usefull for ordering and indexing
+     *
+     * Month and Day can be 0 (zero), depending on the granularity of the [[Periodicity]].
+     *
+     * *Example:*
+     *
+     * **20180125** - 25, January, 2018 - DAILY Periodicity
+     *
+     * **20180100** - January, 2018 - MONTHLY Periodicity
+     *
+     * **20180000** - 2018 - YEARLY Periodicity
+     */
+    getFuzzyDate() {
+        return this.json.fuzzyDate;
+    }
+    /**
+     * The cumulative balance to the date, based on the credit nature of the container
+     */
+    getCumulativeBalance() {
+        return Utils.getRepresentativeValue(this.getCumulativeBalanceRaw(), this.container.isCredit());
+    }
+    /**
+     * The raw cumulative balance to the date.
+     */
+    getCumulativeBalanceRaw() {
+        return new Amount(this.json.cumulativeBalance);
+    }
+    /**
+     * The cumulative credit to the date.
+     */
+    getCumulativeCredit() {
+        return new Amount(this.json.cumulativeCredit);
+    }
+    /**
+     * The cumulative debit to the date.
+     */
+    getCumulativeDebit() {
+        return new Amount(this.json.cumulativeDebit);
+    }
+    /**
+     * The balance on the date period, based on credit nature of the container.
+     */
+    getPeriodBalance() {
+        return Utils.getRepresentativeValue(this.getPeriodBalanceRaw(), this.container.isCredit());
+    }
+    /**
+     * The raw balance on the date period.
+     */
+    getPeriodBalanceRaw() {
+        return new Amount(this.json.periodBalance);
+    }
+    /**
+     * The credit on the date period.
+     */
+    getPeriodCredit() {
+        return new Amount(this.json.periodCredit);
+    }
+    /**
+     * The debit on the date period.
+     */
+    getPeriodDebit() {
+        return new Amount(this.json.periodDebit);
+    }
+}
+//# sourceMappingURL=Balance.js.map