bkper-js 2.12.2 → 2.12.3

package/CHANGELOG.md

@@ -37,6 +37,7 @@ See what's new and what has changed in bkper-js
 - Deprecated `Integration.getLogo`
 - Added `Integration.getLogoUrl`
 - Added `Integration.getLogoUrlDark`
+- Added `Transaction.getCreatedBy`
 - Replaced axios with native Fetch API for better compatibility with multiple environments
 
 **August 2025**

package/lib/index.d.ts

@@ -1308,6 +1308,8 @@ export declare class Bkper {
  */
 export declare class Book extends Resource<bkper.Book> {
     private config?;
+    private allGroupsLoaded;
+    private allAccountsLoaded;
 
 
 
@@ -1727,11 +1729,30 @@ export declare class Book extends Resource<bkper.Book> {
      */
     updateIntegration(integration: bkper.Integration): Promise<Integration>;
     /**
-     * Gets an [[Account]] object.
+     * Gets an [[Account]] object by id or name.
+     *
+     * Results are cached to avoid repeated server calls. Account-group relationships
+     * are included if the full chart was loaded via getAccounts() or when the Book
+     * was loaded with includeAccounts=true.
      *
      * @param idOrName - The id or name of the Account
      *
      * @returns The matching Account object
+     *
+     * @example
+     * ```typescript
+     * // Get individual account (basic data, cached)
+     * const account = await book.getAccount('Bank Account');
+     *
+     * // For account-group relationships, use one of these approaches:
+     * // Option 1: Load book with full data upfront
+     * const bookWithAccounts = await Bkper.getBook(bookId, true);
+     * const accountWithGroups = await bookWithAccounts.getAccount('Bank Account');
+     *
+     * // Option 2: Load full chart when needed
+     * await book.getAccounts();
+     * const accountWithGroups2 = await book.getAccount('Bank Account');
+     * ```
      */
     getAccount(idOrName?: string): Promise<Account | undefined>;
 
@@ -1741,26 +1762,73 @@ export declare class Book extends Resource<bkper.Book> {
 
 
 
-
     /**
-     * Gets a [[Group]] object.
+     * Gets a [[Group]] object by id or name.
+     *
+     * Results are cached to avoid repeated server calls. Parent/child relationships
+     * are included if all groups were loaded via getGroups() or when the Book was
+     * loaded with includeGroups=true.
      *
      * @param idOrName - The id or name of the Group
      *
      * @returns The matching Group object
+     *
+     * @example
+     * ```typescript
+     * // Get individual group (basic data, cached)
+     * const group = await book.getGroup('Assets');
+     *
+     * // For parent/child relationships, use one of these approaches:
+     * // Option 1: Load book with full hierarchy upfront
+     * const bookWithGroups = await Bkper.getBook(bookId, false, true);
+     * const groupWithTree = await bookWithGroups.getGroup('Assets');
+     *
+     * // Option 2: Load full hierarchy when needed
+     * await book.getGroups();
+     * const groupWithTree2 = await book.getGroup('Assets');
+     * console.log(groupWithTree2.getParent(), groupWithTree2.getChildren());
+     * ```
      */
     getGroup(idOrName?: string): Promise<Group | undefined>;
     /**
-     * Gets all [[Groups]] of this Book.
+     * Gets all [[Groups]] of this Book with complete parent/child hierarchy.
+     *
+     * Results are cached for performance. Group tree relationships are built
+     * during loading. Consider using Bkper.getBook(id, false, true) for
+     * upfront loading when you know you'll need all groups.
      *
      * @returns The retrieved [[Group]] objects
+     *
+     * @example
+     * ```typescript
+     * // Load all groups with complete hierarchy
+     * const groups = await book.getGroups();
+     *
+     * // Alternative: Load book with groups upfront (more efficient)
+     * const bookWithGroups = await Bkper.getBook(bookId, false, true);
+     * const groups2 = await bookWithGroups.getGroups(); // Already cached
+     * ```
      */
     getGroups(): Promise<Group[]>;
 
     /**
-     * Gets all [[Accounts]] of this Book.
+     * Gets all [[Accounts]] of this Book with full account-group relationships.
+     *
+     * Results are cached for performance. Groups are automatically loaded first
+     * to ensure proper linking. Consider using Bkper.getBook(id, true) for
+     * upfront loading when you know you'll need all accounts.
      *
      * @returns The retrieved [[Account]] objects
+     *
+     * @example
+     * ```typescript
+     * // Load all accounts with complete relationships
+     * const accounts = await book.getAccounts();
+     *
+     * // Alternative: Load book with accounts upfront (more efficient)
+     * const bookWithAccounts = await Bkper.getBook(bookId, true);
+     * const accounts2 = await bookWithAccounts.getAccounts(); // Already cached
+     * ```
      */
     getAccounts(): Promise<Account[]>;
 
@@ -1771,6 +1839,7 @@ export declare class Book extends Resource<bkper.Book> {
 
 
 
+
     /**
      * Lists transactions in the Book based on the provided query, limit, and cursor, for pagination.
      *

package/lib/model/Book.js

@@ -44,13 +44,15 @@ import { Backlog } from "./Backlog.js";
 export class Book extends Resource {
     constructor(payload, config) {
         super(payload);
+        this.allGroupsLoaded = false;
+        this.allAccountsLoaded = false;
         this.config = config;
         if (this.payload.permission == Permission.RECORDER) {
             this.payload.groups = this.payload.groups || [];
             this.payload.accounts = this.payload.accounts || [];
         }
-        this.mapGroups(this.payload.groups);
-        this.mapAccounts(this.payload.accounts);
+        this.allGroupsLoaded = this.mapGroups(this.payload.groups);
+        this.allAccountsLoaded = this.mapAccounts(this.payload.accounts);
     }
     /** @internal */
     getConfig() {
@@ -721,11 +723,30 @@ export class Book extends Resource {
         });
     }
     /**
-     * Gets an [[Account]] object.
+     * Gets an [[Account]] object by id or name.
+     *
+     * Results are cached to avoid repeated server calls. Account-group relationships
+     * are included if the full chart was loaded via getAccounts() or when the Book
+     * was loaded with includeAccounts=true.
      *
      * @param idOrName - The id or name of the Account
      *
      * @returns The matching Account object
+     *
+     * @example
+     * ```typescript
+     * // Get individual account (basic data, cached)
+     * const account = await book.getAccount('Bank Account');
+     *
+     * // For account-group relationships, use one of these approaches:
+     * // Option 1: Load book with full data upfront
+     * const bookWithAccounts = await Bkper.getBook(bookId, true);
+     * const accountWithGroups = await bookWithAccounts.getAccount('Bank Account');
+     *
+     * // Option 2: Load full chart when needed
+     * await book.getAccounts();
+     * const accountWithGroups2 = await book.getAccount('Bank Account');
+     * ```
      */
     getAccount(idOrName) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -739,13 +760,14 @@ export class Book extends Resource {
             }
             // Try to get account by name
             if (!account && this.nameAccountMap) {
-                account = this.nameAccountMap.get(idOrName);
+                account = this.nameAccountMap.get(Utils.normalizeName(idOrName));
             }
             // Try to fetch account from server
             if (!account) {
                 const accountPayload = yield AccountService.getAccount(this.getId(), idOrName, this.getConfig());
                 if (accountPayload) {
                     account = new Account(this, accountPayload);
+                    this.updateAccountCache(account);
                 }
             }
             return account;
@@ -755,63 +777,42 @@ export class Book extends Resource {
     updateGroupCache(group) {
         this.updateGroupIdMap(group);
         this.updateGroupNameMap(group);
-        if (this.idGroupMap) {
-            group.buildGroupTree(this.idGroupMap);
-        }
     }
     /** @internal */
     updateGroupIdMap(group) {
-        if (this.idGroupMap) {
-            const id = group.getId();
-            if (id) {
-                this.idGroupMap.set(id, group);
-            }
+        this.idGroupMap = this.idGroupMap || new Map();
+        const id = group.getId();
+        if (id) {
+            this.idGroupMap.set(id, group);
         }
     }
     /** @internal */
     updateGroupNameMap(group) {
-        if (this.nameGroupMap) {
-            const normalizedName = group.getNormalizedName();
-            if (normalizedName) {
-                this.nameGroupMap.set(normalizedName, group);
-            }
+        this.nameGroupMap = this.nameGroupMap || new Map();
+        const normalizedName = group.getNormalizedName();
+        if (normalizedName) {
+            this.nameGroupMap.set(normalizedName, group);
         }
     }
     /** @internal */
     updateAccountCache(account) {
         this.updateAccountIdMap(account);
         this.updateAccountNameMap(account);
-        if (this.idAccountMap || this.nameAccountMap) {
-            this.linkAccountsAndGroups(account);
-        }
     }
     /** @internal */
     updateAccountIdMap(account) {
-        if (this.idAccountMap) {
-            const id = account.getId();
-            if (id) {
-                this.idAccountMap.set(id, account);
-            }
+        this.idAccountMap = this.idAccountMap || new Map();
+        const id = account.getId();
+        if (id) {
+            this.idAccountMap.set(id, account);
         }
     }
     /** @internal */
     updateAccountNameMap(account) {
-        if (this.nameAccountMap) {
-            const normalizedName = account.getNormalizedName();
-            if (normalizedName) {
-                this.nameAccountMap.set(normalizedName, account);
-            }
-        }
-    }
-    /** @internal */
-    linkAccountsAndGroups(account) {
-        var _a;
-        const groupPayloads = account.json().groups || [];
-        for (const groupPayload of groupPayloads) {
-            const group = (_a = this.idGroupMap) === null || _a === void 0 ? void 0 : _a.get(groupPayload.id || "");
-            if (group != null) {
-                group.addAccount(account);
-            }
+        this.nameAccountMap = this.nameAccountMap || new Map();
+        const normalizedName = account.getNormalizedName();
+        if (normalizedName) {
+            this.nameAccountMap.set(normalizedName, account);
         }
     }
     /** @internal */
@@ -835,11 +836,31 @@ export class Book extends Resource {
         }
     }
     /**
-     * Gets a [[Group]] object.
+     * Gets a [[Group]] object by id or name.
+     *
+     * Results are cached to avoid repeated server calls. Parent/child relationships
+     * are included if all groups were loaded via getGroups() or when the Book was
+     * loaded with includeGroups=true.
      *
      * @param idOrName - The id or name of the Group
      *
      * @returns The matching Group object
+     *
+     * @example
+     * ```typescript
+     * // Get individual group (basic data, cached)
+     * const group = await book.getGroup('Assets');
+     *
+     * // For parent/child relationships, use one of these approaches:
+     * // Option 1: Load book with full hierarchy upfront
+     * const bookWithGroups = await Bkper.getBook(bookId, false, true);
+     * const groupWithTree = await bookWithGroups.getGroup('Assets');
+     *
+     * // Option 2: Load full hierarchy when needed
+     * await book.getGroups();
+     * const groupWithTree2 = await book.getGroup('Assets');
+     * console.log(groupWithTree2.getParent(), groupWithTree2.getChildren());
+     * ```
      */
     getGroup(idOrName) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -853,75 +874,123 @@ export class Book extends Resource {
             }
             // Try to get group by name
             if (!group && this.nameGroupMap) {
-                group = this.nameGroupMap.get(idOrName);
+                group = this.nameGroupMap.get(Utils.normalizeName(idOrName));
             }
             // Try to fetch group from server
             if (!group) {
                 const groupPayload = yield GroupService.getGroup(this.getId(), idOrName, this.getConfig());
                 if (groupPayload) {
                     group = new Group(this, groupPayload);
+                    this.updateGroupCache(group);
                 }
             }
             return group;
         });
     }
     /**
-     * Gets all [[Groups]] of this Book.
+     * Gets all [[Groups]] of this Book with complete parent/child hierarchy.
+     *
+     * Results are cached for performance. Group tree relationships are built
+     * during loading. Consider using Bkper.getBook(id, false, true) for
+     * upfront loading when you know you'll need all groups.
      *
      * @returns The retrieved [[Group]] objects
+     *
+     * @example
+     * ```typescript
+     * // Load all groups with complete hierarchy
+     * const groups = await book.getGroups();
+     *
+     * // Alternative: Load book with groups upfront (more efficient)
+     * const bookWithGroups = await Bkper.getBook(bookId, false, true);
+     * const groups2 = await bookWithGroups.getGroups(); // Already cached
+     * ```
      */
     getGroups() {
         return __awaiter(this, void 0, void 0, function* () {
-            if (this.idGroupMap) {
-                return Array.from(this.idGroupMap.values());
+            var _a, _b;
+            if (this.allGroupsLoaded) {
+                return Array.from(((_a = this.idGroupMap) === null || _a === void 0 ? void 0 : _a.values()) || []);
             }
             let groups = yield GroupService.getGroups(this.getId(), this.getConfig());
-            return this.mapGroups(groups);
+            this.allGroupsLoaded = this.mapGroups(groups);
+            return Array.from(((_b = this.idGroupMap) === null || _b === void 0 ? void 0 : _b.values()) || []);
         });
     }
     /** @internal */
     mapGroups(groups) {
         if (!groups) {
-            return [];
+            return false;
         }
         let groupsObj = groups.map((group) => new Group(this, group));
         this.idGroupMap = new Map();
         this.nameGroupMap = new Map();
         for (const group of groupsObj) {
             this.updateGroupCache(group);
+            group.buildGroupTree(this.idGroupMap);
         }
         for (const group of groupsObj) {
             group.buildGroupTree(this.idGroupMap);
         }
-        return groupsObj;
+        return true;
     }
     /**
-     * Gets all [[Accounts]] of this Book.
+     * Gets all [[Accounts]] of this Book with full account-group relationships.
+     *
+     * Results are cached for performance. Groups are automatically loaded first
+     * to ensure proper linking. Consider using Bkper.getBook(id, true) for
+     * upfront loading when you know you'll need all accounts.
      *
      * @returns The retrieved [[Account]] objects
+     *
+     * @example
+     * ```typescript
+     * // Load all accounts with complete relationships
+     * const accounts = await book.getAccounts();
+     *
+     * // Alternative: Load book with accounts upfront (more efficient)
+     * const bookWithAccounts = await Bkper.getBook(bookId, true);
+     * const accounts2 = await bookWithAccounts.getAccounts(); // Already cached
+     * ```
      */
     getAccounts() {
         return __awaiter(this, void 0, void 0, function* () {
-            if (this.idAccountMap) {
-                return Array.from(this.idAccountMap.values());
+            var _a, _b;
+            if (this.allAccountsLoaded) {
+                return Array.from(((_a = this.idAccountMap) === null || _a === void 0 ? void 0 : _a.values()) || []);
             }
+            //Ensure groups are loaded
+            yield this.getGroups();
             let accounts = yield AccountService.getAccounts(this.getId(), this.getConfig());
-            return this.mapAccounts(accounts);
+            this.allAccountsLoaded = this.mapAccounts(accounts);
+            return Array.from(((_b = this.idAccountMap) === null || _b === void 0 ? void 0 : _b.values()) || []);
         });
     }
     /** @internal */
     mapAccounts(accounts) {
         if (!accounts) {
-            return [];
+            return false;
         }
         let accountsObj = accounts.map((account) => new Account(this, account));
         this.idAccountMap = new Map();
         this.nameAccountMap = new Map();
         for (const account of accountsObj) {
             this.updateAccountCache(account);
+            this.linkAccountsAndGroups(account);
         }
         this.ensureGroupsAccountMapsLoaded();
-        return accountsObj;
+        return true;
+    }
+    /** @internal */
+    linkAccountsAndGroups(account) {
+        var _a;
+        const groupPayloads = account.json().groups || [];
+        for (const groupPayload of groupPayloads) {
+            const group = (_a = this.idGroupMap) === null || _a === void 0 ? void 0 : _a.get(groupPayload.id || "");
+            if (group != null) {
+                group.addAccount(account);
+            }
+        }
     }
     /** @internal */
     ensureGroupsAccountMapsLoaded() {

package/package.json

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