bkper-js 2.7.1 → 2.8.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ See what's new and what has changed in bkper-js
 2025
 ----
 
+**September 2025**
+
+* Added `Collaborator`
+* Added `Collaborator.json`
+* Added `Collaborator.getId`
+* Added `Collaborator.getEmail`
+* Added `Collaborator.getPermission`
+* Added `Collaborator.setEmail`
+* Added `Collaborator.setPermission`
+* Added `Collaborator.create`
+* Added `Collaborator.update`
+* Added `Collaborator.remove`
+* Added `Book.getCollaborators`
+* Replaced axios with native Fetch API for better compatibility with multiple environments
+
 **August 2025**
 
 * Added `Transaction.setFiles`

package/lib/index.d.ts

@@ -15,16 +15,10 @@
  *
  * @public
  */
-export declare class Account {
-    payload: bkper.Account;
+export declare class Account extends Resource<bkper.Account> {
 
     constructor(book: Book, payload?: bkper.Account);
-    /**
-     * Gets an immutable copy of the JSON payload.
-     *
-     * @returns An immutable copy of the json payload
-     */
-    json(): bkper.Account;
+    getConfig(): Config;
     /**
      * Gets the Account internal id.
      *
@@ -442,15 +436,10 @@ export declare class Amount {
  *
  * @public
  */
-export declare class App {
-    payload: bkper.App;
-    constructor(payload?: bkper.App);
-    /**
-     * Gets the wrapped plain JSON object.
-     *
-     * @returns The wrapped plain json object
-     */
-    json(): bkper.App;
+export declare class App extends Resource<bkper.App> {
+    private config?;
+    constructor(payload?: bkper.App, config?: Config);
+    getConfig(): Config;
     /**
      * Sets the webhook url for development.
      *
@@ -497,6 +486,12 @@ export declare class App {
      * @returns True if this App is published
      */
     isPublished(): boolean;
+    /**
+     * Tells if this App is installable.
+     *
+     * @returns True if this App is installable
+     */
+    isInstallable(): boolean;
     /**
      * Checks if this App is conversational.
      *
@@ -529,12 +524,6 @@ export declare class App {
      * @returns This App for chaining
      */
     setUserEmails(emails?: string): App;
-    /**
-     * Gets the name of the owner of this App.
-     *
-     * @returns The name of the owner of this App
-     */
-    getOwnerName(): string | undefined;
     /**
      * Gets the menu url of this App.
      *
@@ -565,12 +554,24 @@ export declare class App {
      * @returns The menu popup height of this App
      */
     getMenuPopupHeight(): string | undefined;
+    /**
+     * Gets the name of the owner of this App.
+     *
+     * @returns The name of the owner of this App
+     */
+    getOwnerName(): string | undefined;
     /**
      * Gets the logo url of the owner of this App.
      *
      * @returns The logo url of the owner of this App
      */
     getOwnerLogoUrl(): string | undefined;
+    /**
+     * Gets the website url of the owner of this App.
+     *
+     * @returns The website url of the owner of this App
+     */
+    getOwnerWebsiteUrl(): string | undefined;
     /**
      * Gets the file patterns the App handles.
      *
@@ -594,11 +595,35 @@ export declare class App {
      */
     setClientSecret(clientSecret?: string): App;
     /**
-     * Sets the readme text.
+     * Gets the website url of this App.
+     *
+     * @returns The website url of this App
+     */
+    getWebsiteUrl(): string | undefined;
+    /**
+     * Tells if the repository is private.
+     *
+     * @returns True if the repository is private
+     */
+    isRepositoryPrivate(): boolean | undefined;
+    /**
+     * Gets the repository url of this App.
+     *
+     * @returns The repository url of this App
+     */
+    getRepositoryUrl(): string | undefined;
+    /**
+     * Gets the readme.md file as text.
+     *
+     * @returns The readme text
+     */
+    getReadme(): string | undefined;
+    /**
+     * Sets the readme.md file as text.
      *
      * @param readme - The readme text to set
      *
-     * @returns This App for chaining
+     * @returns This App, for chaining
      */
     setReadme(readme?: string): App;
     /**
@@ -1162,10 +1187,9 @@ export declare enum BalanceType {
 /**
  * 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 using the static setConfig method.
- *
- * Example:
+ * You can configure the library in two ways:
  *
+ * 1. Using static configuration (traditional approach):
  * ```javascript
  * Bkper.setConfig({
  *   apiKeyProvider: () => process.env.BKPER_API_KEY,
@@ -1176,22 +1200,36 @@ export declare enum BalanceType {
  * const book = await bkper.getBook('bookId');
  * ```
  *
- * Once the config is set, you can create instances and start using the library.
+ * 2. Using per-instance configuration (recommended for Cloudflare Workers):
+ * ```javascript
+ * const bkper = new Bkper({
+ *   apiKeyProvider: () => process.env.BKPER_API_KEY,
+ *   oauthTokenProvider: () => process.env.BKPER_OAUTH_TOKEN
+ * });
+ *
+ * const book = await bkper.getBook('bookId');
+ * ```
  *
  * @public
  */
 export declare class Bkper {
+
+    private config;
     /**
      * Sets the global API configuration for all Bkper operations.
      *
+     * WARNING: This configuration will be shared and should NOT be used on shared environments.
+     *
      * @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.
+     * Creates a new Bkper instance with the provided configuration.
+     *
+     * @param config - The Config object containing API key and OAuth token providers.
+     *                 If not provided, uses the global configuration set via setConfig().
      */
-    constructor();
+    constructor(config?: Config);
     /**
      * Gets the [[Book]] with the specified bookId from url param.
      *
@@ -1262,8 +1300,8 @@ export declare class Bkper {
  *
  * @public
  */
-export declare class Book {
-    payload: bkper.Book;
+export declare class Book extends Resource<bkper.Book> {
+    private config?;
 
 
 
@@ -1272,13 +1310,8 @@ export declare class Book {
 
 
 
-    constructor(payload?: bkper.Book);
-    /**
-     * Gets an immutable copy of the JSON payload for this Book.
-     *
-     * @returns An immutable copy of the JSON payload
-     */
-    json(): bkper.Book;
+    constructor(payload?: bkper.Book, config?: Config);
+    getConfig(): Config;
     /**
      * Gets the unique identifier of this Book.
      *
@@ -1909,16 +1942,10 @@ export declare enum BotResponseType {
  *
  * @public
  */
-export declare class Collaborator {
-    payload: bkper.Collaborator;
+export declare class Collaborator extends Resource<bkper.Collaborator> {
 
     constructor(book: Book, payload?: bkper.Collaborator);
-    /**
-     * Gets an immutable copy of the JSON payload.
-     *
-     * @returns An immutable copy of the json payload
-     */
-    json(): bkper.Collaborator;
+    getConfig(): Config;
     /**
      * Gets the Collaborator internal id.
      *
@@ -1978,15 +2005,10 @@ export declare class Collaborator {
  *
  * @public
  */
-export declare class Collection {
-    payload: bkper.Collection;
-    constructor(payload?: bkper.Collection);
-    /**
-     * Gets an immutable copy of the JSON payload for this Collection.
-     *
-     * @returns The wrapped plain json object
-     */
-    json(): bkper.Collection;
+export declare class Collection extends Resource<bkper.Collection> {
+    private config?;
+    constructor(payload?: bkper.Collection, config?: Config);
+    getConfig(): Config;
     /**
      * Gets the unique identifier of this Collection.
      *
@@ -2119,15 +2141,10 @@ export declare interface Config {
  *
  * @public
  */
-export declare class Connection {
-    payload: bkper.Connection;
-    constructor(payload?: bkper.Connection);
-    /**
-     * Gets an immutable copy of the JSON payload for this Connection.
-     *
-     * @returns An immutable copy of the json payload
-     */
-    json(): bkper.Connection;
+export declare class Connection extends Resource<bkper.Connection> {
+    private config?;
+    constructor(payload?: bkper.Connection, config?: Config);
+    getConfig(): Config;
     /**
      * Gets the id of the Connection.
      *
@@ -2288,17 +2305,12 @@ export declare class Connection {
  *
  * @public
  */
-export declare class Conversation {
-    payload: bkper.Conversation;
+export declare class Conversation extends Resource<bkper.Conversation> {
 
 
-    constructor(agent: Agent, payload?: bkper.Conversation);
-    /**
-     * Gets an immutable copy of the JSON payload for this Conversation.
-     *
-     * @returns The wrapped plain json object
-     */
-    json(): bkper.Conversation;
+    private config?;
+    constructor(agent: Agent, payload?: bkper.Conversation, config?: Config);
+    getConfig(): Config;
     /**
      * Gets the Agent associated to this Conversation.
      *
@@ -2508,16 +2520,10 @@ export declare enum EventType {
  *
  * @public
  */
-export declare class File {
-    payload: bkper.File;
+export declare class File extends Resource<bkper.File> {
 
     constructor(book: Book, payload?: bkper.File);
-    /**
-     * Gets an immutable copy of the JSON payload for this File.
-     *
-     * @returns An immutable copy of the json payload
-     */
-    json(): bkper.File;
+    getConfig(): Config;
     /**
      * Gets the File id.
      *
@@ -2638,8 +2644,7 @@ export declare class File {
  *
  * @public
  */
-export declare class Group {
-    payload: bkper.Group;
+export declare class Group extends Resource<bkper.Group> {
 
 
 
@@ -2647,12 +2652,7 @@ export declare class Group {
 
 
     constructor(book: Book, payload?: bkper.Group);
-    /**
-     * Gets an immutable copy of the json payload.
-     *
-     * @returns An immutable copy of the json payload
-     */
-    json(): bkper.Group;
+    getConfig(): Config;
     /**
      * Gets the id of this Group.
      *
@@ -2890,15 +2890,10 @@ export declare class Group {
  *
  * @public
  */
-export declare class Integration {
-    payload: bkper.Integration;
-    constructor(payload?: bkper.Integration);
-    /**
-     * Gets an immutable copy of the JSON payload for this Integration.
-     *
-     * @returns An immutable copy of the json payload
-     */
-    json(): bkper.Integration;
+export declare class Integration extends Resource<bkper.Integration> {
+    private config?;
+    constructor(payload?: bkper.Integration, config?: Config);
+    getConfig(): Config;
     /**
      * Gets the [[Book]] id of the Integration.
      *
@@ -3005,17 +3000,11 @@ export declare class Integration {
  *
  * @public
  */
-export declare class Message {
-    payload: bkper.Message;
+export declare class Message extends Resource<bkper.Message> {
 
 
-    constructor(conversation: Conversation, payload?: bkper.Message);
-    /**
-     * Gets the wrapped plain json object.
-     *
-     * @returns The wrapped plain json object
-     */
-    json(): bkper.Message;
+    constructor(conversation: Conversation, payload?: bkper.Message, config?: Config);
+    getConfig(): Config;
     /**
      * Gets the Message universal identifier.
      *
@@ -3218,16 +3207,10 @@ export declare enum Permission {
  *
  * @public
  */
-export declare class Query {
-    payload: bkper.Query;
+export declare class Query extends Resource<bkper.Query> {
 
     constructor(book: Book, payload?: bkper.Query);
-    /**
-     * Gets the wrapped plain json object.
-     *
-     * @returns The wrapped plain json object
-     */
-    json(): bkper.Query;
+    getConfig(): Config;
     /**
      * Gets the Query universal identifier.
      *
@@ -3284,21 +3267,47 @@ export declare class Query {
 }
 
 /**
- * This class defines a Template.
- *
- * A Template is a pre-configured setup for [[Books]] and associated Google Sheets that provides users with a starting point for specific accounting or financial management needs.
+ * Abstract base class for all Bkper resources.
+ * Provides common functionality for config management and JSON serialization.
  *
  * @public
  */
-export declare class Template {
-    payload: bkper.Template;
-    constructor(json?: bkper.Template);
+declare abstract class Resource<T = any> {
     /**
-     * Gets an immutable copy of the JSON payload for this Template.
-     *
+     * The underlying payload data for this resource
+     */
+    protected payload: T;
+    /**
+     * Constructs a new Resource
+     * @param payload - The data payload for this resource
+     */
+    constructor(payload?: T);
+    /**
+     * Gets an immutable copy of the JSON payload for this resource.
      * @returns An immutable copy of the json payload
      */
-    json(): bkper.Template;
+    json(): T;
+    /**
+     * Gets the effective configuration for this resource.
+     * Each resource must implement this to either:
+     * - Return its own config (for root containers like Book, Collection)
+     * - Delegate to its container (for contained resources like Account, Transaction)
+     * @returns The resolved configuration
+     */
+    abstract getConfig(): Config;
+}
+
+/**
+ * This class defines a Template.
+ *
+ * A Template is a pre-configured setup for [[Books]] and associated Google Sheets that provides users with a starting point for specific accounting or financial management needs.
+ *
+ * @public
+ */
+export declare class Template extends Resource<bkper.Template> {
+    private config?;
+    constructor(json?: bkper.Template, config?: Config);
+    getConfig(): Config;
     /**
      * Gets the name of the Template.
      *
@@ -3357,16 +3366,10 @@ export declare class Template {
  *
  * @public
  */
-export declare class Transaction {
-    payload: bkper.Transaction;
+export declare class Transaction extends Resource<bkper.Transaction> {
 
     constructor(book: Book, payload?: bkper.Transaction);
-    /**
-     * Gets the JSON representation of the transaction.
-     *
-     * @returns An immutable copy of the json payload
-     */
-    json(): bkper.Transaction;
+    getConfig(): Config;
     /**
      * Gets the book associated with this transaction.
      *
@@ -3861,15 +3864,10 @@ export declare class TransactionList {
  *
  * @public
  */
-export declare class User {
-    payload: bkper.User;
-    constructor(payload?: bkper.User);
-    /**
-     * Gets an immutable copy of the JSON payload for this User.
-     *
-     * @returns An immutable copy of the json payload
-     */
-    json(): bkper.User;
+export declare class User extends Resource<bkper.User> {
+    private config?;
+    constructor(payload?: bkper.User, config?: Config);
+    getConfig(): Config;
     /**
      * Gets the id of the User.
      *

package/lib/model/Account.js

@@ -7,10 +7,11 @@ 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 * 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 { Resource } from "./Resource.js";
 /**
  * This class defines an [Account](https://en.wikipedia.org/wiki/Account_(bookkeeping)) of a [[Book]].
  *
@@ -20,20 +21,13 @@ import { normalizeText } from '../utils.js';
  *
  * @public
  */
-export class Account {
+export class Account extends Resource {
     constructor(book, payload) {
+        super(payload || { createdAt: `${Date.now()}` });
         this.book = book;
-        this.payload = payload || {
-            createdAt: `${Date.now()}`
-        };
     }
-    /**
-     * Gets an immutable copy of the JSON payload.
-     *
-     * @returns An immutable copy of the json payload
-     */
-    json() {
-        return Object.assign({}, this.payload);
+    getConfig() {
+        return this.book.getConfig();
     }
     /**
      * Gets the Account internal id.
@@ -124,7 +118,7 @@ export class Account {
         for (let index = 0; index < keys.length; index++) {
             const key = keys[index];
             let value = this.payload.properties != null ? this.payload.properties[key] : null;
-            if (value != null && value.trim() != '') {
+            if (value != null && value.trim() != "") {
                 return value;
             }
         }
@@ -139,14 +133,14 @@ export class Account {
      * @returns This Account, for chaining
      */
     setProperty(key, value) {
-        if (key == null || key.trim() == '') {
+        if (key == null || key.trim() == "") {
             return this;
         }
         if (this.payload.properties == null) {
             this.payload.properties = {};
         }
         if (!value) {
-            value = '';
+            value = "";
         }
         this.payload.properties[key] = value;
         return this;
@@ -241,8 +235,8 @@ export class Account {
             if (!id) {
                 return [];
             }
-            let groups = yield GroupService.getGroupsByAccountId(this.book.getId(), id);
-            let groupsObj = groups.map(group => new Group(this.book, group));
+            let groups = yield GroupService.getGroupsByAccountId(this.book.getId(), id, this.getConfig());
+            let groupsObj = groups.map((group) => new Group(this.book, group));
             return groupsObj;
         });
     }
@@ -256,7 +250,7 @@ export class Account {
     setGroups(groups) {
         this.payload.groups = undefined;
         if (groups != null) {
-            groups.forEach(group => this.addGroup(group));
+            groups.forEach((group) => this.addGroup(group));
         }
         return this;
     }
@@ -351,7 +345,7 @@ export class Account {
      */
     create() {
         return __awaiter(this, void 0, void 0, function* () {
-            this.payload = yield AccountService.createAccount(this.book.getId(), this.payload);
+            this.payload = yield AccountService.createAccount(this.book.getId(), this.payload, this.getConfig());
             this.updateAccountCache();
             return this;
         });
@@ -363,7 +357,7 @@ export class Account {
      */
     update() {
         return __awaiter(this, void 0, void 0, function* () {
-            this.payload = yield AccountService.updateAccount(this.book.getId(), this.payload);
+            this.payload = yield AccountService.updateAccount(this.book.getId(), this.payload, this.getConfig());
             this.updateAccountCache();
             return this;
         });
@@ -375,7 +369,7 @@ export class Account {
      */
     remove() {
         return __awaiter(this, void 0, void 0, function* () {
-            this.payload = yield AccountService.deleteAccount(this.book.getId(), this.payload);
+            this.payload = yield AccountService.deleteAccount(this.book.getId(), this.payload, this.getConfig());
             this.updateAccountCache(true);
             return this;
         });