@panoptic-it-solutions/quickbooks-client 0.1.3 → 0.2.0

package/dist/index.js

@@ -141,7 +141,9 @@ function generateAuthUrl(config, state) {
 }
 async function exchangeCodeForTokens(config, code, realmId) {
   const env = config.environment || "production";
-  const credentials = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
+  const credentials = Buffer.from(
+    `${config.clientId}:${config.clientSecret}`
+  ).toString("base64");
   const response = await fetch(ENDPOINTS[env].token, {
     method: "POST",
     headers: {
@@ -175,7 +177,9 @@ async function exchangeCodeForTokens(config, code, realmId) {
 }
 async function refreshTokens(config, refreshToken, realmId) {
   const env = config.environment || "production";
-  const credentials = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
+  const credentials = Buffer.from(
+    `${config.clientId}:${config.clientSecret}`
+  ).toString("base64");
   const response = await fetch(ENDPOINTS[env].token, {
     method: "POST",
     headers: {
@@ -208,7 +212,9 @@ async function refreshTokens(config, refreshToken, realmId) {
 }
 async function revokeTokens(config, token) {
   const env = config.environment || "production";
-  const credentials = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
+  const credentials = Buffer.from(
+    `${config.clientId}:${config.clientSecret}`
+  ).toString("base64");
   const response = await fetch(ENDPOINTS[env].revoke, {
     method: "POST",
     headers: {
@@ -238,7 +244,9 @@ function isTokenExpired(expiresAt, bufferSeconds = 300) {
 function generateState() {
   const array = new Uint8Array(16);
   crypto.getRandomValues(array);
-  return Array.from(array, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return Array.from(array, (byte) => byte.toString(16).padStart(2, "0")).join(
+    ""
+  );
 }
 
 // src/client.ts
@@ -255,24 +263,38 @@ var QuickBooksClient = class {
   tokenStore;
   requestTimestamps = [];
   onLog;
+  minorVersion;
   constructor(options) {
     this.validateConfig(options);
     this.config = options;
     this.tokenStore = options.tokenStore;
     this.onLog = options.onLog;
+    this.minorVersion = options.minorVersion;
   }
   validateConfig(options) {
     if (!options.clientId) {
-      throw new QuickBooksError("clientId is required", QB_ERROR_CODES.INVALID_CONFIG);
+      throw new QuickBooksError(
+        "clientId is required",
+        QB_ERROR_CODES.INVALID_CONFIG
+      );
     }
     if (!options.clientSecret) {
-      throw new QuickBooksError("clientSecret is required", QB_ERROR_CODES.INVALID_CONFIG);
+      throw new QuickBooksError(
+        "clientSecret is required",
+        QB_ERROR_CODES.INVALID_CONFIG
+      );
     }
     if (!options.redirectUri) {
-      throw new QuickBooksError("redirectUri is required", QB_ERROR_CODES.INVALID_CONFIG);
+      throw new QuickBooksError(
+        "redirectUri is required",
+        QB_ERROR_CODES.INVALID_CONFIG
+      );
     }
     if (!options.tokenStore) {
-      throw new QuickBooksError("tokenStore is required", QB_ERROR_CODES.INVALID_CONFIG);
+      throw new QuickBooksError(
+        "tokenStore is required",
+        QB_ERROR_CODES.INVALID_CONFIG
+      );
     }
   }
   log(level, message, data) {
@@ -280,6 +302,14 @@ var QuickBooksClient = class {
       this.onLog(level, message, data);
     }
   }
+  /**
+   * Append minorversion query param to a URL if configured
+   */
+  appendMinorVersion(url) {
+    if (this.minorVersion == null) return url;
+    const separator = url.includes("?") ? "&" : "?";
+    return `${url}${separator}minorversion=${this.minorVersion}`;
+  }
   /**
    * Rate limiting - ensures we don't exceed 500 requests/minute
    */
@@ -336,7 +366,9 @@ var QuickBooksClient = class {
     const tokens = await this.getValidTokens();
     const env = this.config.environment || "production";
     const baseUrl = API_BASE[env];
-    const url = `${baseUrl}/v3/company/${tokens.realm_id}${endpoint}`;
+    const url = this.appendMinorVersion(
+      `${baseUrl}/v3/company/${tokens.realm_id}${endpoint}`
+    );
     this.log("debug", `${method} ${endpoint}`, { body });
     const headers = {
       Authorization: `Bearer ${tokens.access_token}`,
@@ -353,8 +385,11 @@ var QuickBooksClient = class {
       });
       if (response.status === 429 && retryCount < MAX_RETRIES) {
         const retryAfter = response.headers.get("Retry-After");
-        const delay = retryAfter ? parseInt(retryAfter, 10) * 1e3 : INITIAL_RETRY_DELAY_MS * Math.pow(2, retryCount);
-        this.log("warn", `Rate limited, retrying in ${delay}ms (attempt ${retryCount + 1})`);
+        const delay = retryAfter ? parseInt(retryAfter, 10) * 1e3 : INITIAL_RETRY_DELAY_MS * 2 ** retryCount;
+        this.log(
+          "warn",
+          `Rate limited, retrying in ${delay}ms (attempt ${retryCount + 1})`
+        );
         await new Promise((resolve) => setTimeout(resolve, delay));
         return this.request(method, endpoint, body, retryCount + 1);
       }
@@ -387,7 +422,9 @@ var QuickBooksClient = class {
     const tokens = await this.getValidTokens();
     const env = this.config.environment || "production";
     const baseUrl = API_BASE[env];
-    const url = `${baseUrl}/v3/company/${tokens.realm_id}/query`;
+    const url = this.appendMinorVersion(
+      `${baseUrl}/v3/company/${tokens.realm_id}/query`
+    );
     await this.checkRateLimit();
     const fetchResponse = await fetch(url, {
       method: "POST",
@@ -400,7 +437,10 @@ var QuickBooksClient = class {
     });
     if (!fetchResponse.ok) {
       const errorData = await fetchResponse.json().catch(() => ({}));
-      throw handleQuickBooksError({ status: fetchResponse.status, ...errorData });
+      throw handleQuickBooksError({
+        status: fetchResponse.status,
+        ...errorData
+      });
     }
     const data = await fetchResponse.json();
     const keys = Object.keys(data.QueryResponse).filter(
@@ -423,7 +463,9 @@ var QuickBooksClient = class {
       const tokens = await this.getValidTokens();
       const env = this.config.environment || "production";
       const baseUrl = API_BASE[env];
-      const url = `${baseUrl}/v3/company/${tokens.realm_id}/query`;
+      const url = this.appendMinorVersion(
+        `${baseUrl}/v3/company/${tokens.realm_id}/query`
+      );
       await this.checkRateLimit();
       const fetchResponse = await fetch(url, {
         method: "POST",
@@ -436,7 +478,10 @@ var QuickBooksClient = class {
       });
       if (!fetchResponse.ok) {
         const errorData = await fetchResponse.json().catch(() => ({}));
-        throw handleQuickBooksError({ status: fetchResponse.status, ...errorData });
+        throw handleQuickBooksError({
+          status: fetchResponse.status,
+          ...errorData
+        });
       }
       const data = await fetchResponse.json();
       const keys = Object.keys(data.QueryResponse).filter(
@@ -445,7 +490,10 @@ var QuickBooksClient = class {
       const entityKey = keys[0];
       const pageResults = entityKey ? data.QueryResponse[entityKey] : [];
       allResults.push(...pageResults);
-      this.log("debug", `Fetched page at position ${startPosition}, got ${pageResults.length} results (total: ${allResults.length})`);
+      this.log(
+        "debug",
+        `Fetched page at position ${startPosition}, got ${pageResults.length} results (total: ${allResults.length})`
+      );
       if (pageResults.length < maxResults) {
         break;
       }
@@ -457,23 +505,34 @@ var QuickBooksClient = class {
   // Invoice Methods
   // ============================================
   async getInvoice(id) {
-    const response = await this.request("GET", `/invoice/${id}`);
+    const response = await this.request(
+      "GET",
+      `/invoice/${id}`
+    );
     return response.Invoice;
   }
   async getInvoices(where) {
     const sql = where ? `SELECT * FROM Invoice WHERE ${where}` : "SELECT * FROM Invoice";
-    return this.query(sql);
+    return this.queryAll(sql);
   }
   async createInvoice(invoice) {
-    const response = await this.request("POST", "/invoice", invoice);
+    const response = await this.request(
+      "POST",
+      "/invoice",
+      invoice
+    );
     return response.Invoice;
   }
   async updateInvoice(invoice) {
-    const response = await this.request("POST", "/invoice", invoice);
+    const response = await this.request(
+      "POST",
+      "/invoice",
+      invoice
+    );
     return response.Invoice;
   }
   async deleteInvoice(id, syncToken) {
-    await this.request("POST", "/invoice", {
+    await this.request("POST", "/invoice?operation=delete", {
       Id: id,
       SyncToken: syncToken
     });
@@ -482,64 +541,96 @@ var QuickBooksClient = class {
   // Customer Methods
   // ============================================
   async getCustomer(id) {
-    const response = await this.request("GET", `/customer/${id}`);
+    const response = await this.request(
+      "GET",
+      `/customer/${id}`
+    );
     return response.Customer;
   }
   async getCustomers(where) {
     const sql = where ? `SELECT * FROM Customer WHERE ${where}` : "SELECT * FROM Customer";
-    return this.query(sql);
+    return this.queryAll(sql);
   }
   async createCustomer(customer) {
-    const response = await this.request("POST", "/customer", customer);
+    const response = await this.request(
+      "POST",
+      "/customer",
+      customer
+    );
     return response.Customer;
   }
   async updateCustomer(customer) {
-    const response = await this.request("POST", "/customer", customer);
+    const response = await this.request(
+      "POST",
+      "/customer",
+      customer
+    );
     return response.Customer;
   }
   // ============================================
   // Payment Methods
   // ============================================
   async getPayment(id) {
-    const response = await this.request("GET", `/payment/${id}`);
+    const response = await this.request(
+      "GET",
+      `/payment/${id}`
+    );
     return response.Payment;
   }
   async getPayments(where) {
     const sql = where ? `SELECT * FROM Payment WHERE ${where}` : "SELECT * FROM Payment";
-    return this.query(sql);
+    return this.queryAll(sql);
   }
   async createPayment(payment) {
-    const response = await this.request("POST", "/payment", payment);
+    const response = await this.request(
+      "POST",
+      "/payment",
+      payment
+    );
     return response.Payment;
   }
   // ============================================
   // Account Methods
   // ============================================
   async getAccount(id) {
-    const response = await this.request("GET", `/account/${id}`);
+    const response = await this.request(
+      "GET",
+      `/account/${id}`
+    );
     return response.Account;
   }
   async getAccounts(where) {
     const sql = where ? `SELECT * FROM Account WHERE ${where}` : "SELECT * FROM Account WHERE Active = true";
-    return this.query(sql);
+    return this.queryAll(sql);
   }
   // ============================================
   // Vendor Methods
   // ============================================
   async getVendor(id) {
-    const response = await this.request("GET", `/vendor/${id}`);
+    const response = await this.request(
+      "GET",
+      `/vendor/${id}`
+    );
     return response.Vendor;
   }
   async getVendors(where) {
     const sql = where ? `SELECT * FROM Vendor WHERE ${where}` : "SELECT * FROM Vendor";
-    return this.query(sql);
+    return this.queryAll(sql);
   }
   async createVendor(vendor) {
-    const response = await this.request("POST", "/vendor", vendor);
+    const response = await this.request(
+      "POST",
+      "/vendor",
+      vendor
+    );
     return response.Vendor;
   }
   async updateVendor(vendor) {
-    const response = await this.request("POST", "/vendor", vendor);
+    const response = await this.request(
+      "POST",
+      "/vendor",
+      vendor
+    );
     return response.Vendor;
   }
   // ============================================
@@ -551,7 +642,7 @@ var QuickBooksClient = class {
   }
   async getBills(where) {
     const sql = where ? `SELECT * FROM Bill WHERE ${where}` : "SELECT * FROM Bill";
-    return this.query(sql);
+    return this.queryAll(sql);
   }
   async createBill(bill) {
     const response = await this.request("POST", "/bill", bill);
@@ -561,6 +652,148 @@ var QuickBooksClient = class {
     const response = await this.request("POST", "/bill", bill);
     return response.Bill;
   }
+  async deleteBill(id, syncToken) {
+    await this.request("POST", "/bill?operation=delete", {
+      Id: id,
+      SyncToken: syncToken
+    });
+  }
+  // ============================================
+  // BillPayment Methods
+  // ============================================
+  async getBillPayment(id) {
+    const response = await this.request(
+      "GET",
+      `/billpayment/${id}`
+    );
+    return response.BillPayment;
+  }
+  async getBillPayments(where) {
+    const sql = where ? `SELECT * FROM BillPayment WHERE ${where}` : "SELECT * FROM BillPayment";
+    return this.queryAll(sql);
+  }
+  async createBillPayment(billPayment) {
+    const response = await this.request(
+      "POST",
+      "/billpayment",
+      billPayment
+    );
+    return response.BillPayment;
+  }
+  async updateBillPayment(billPayment) {
+    const response = await this.request(
+      "POST",
+      "/billpayment",
+      billPayment
+    );
+    return response.BillPayment;
+  }
+  async deleteBillPayment(id, syncToken) {
+    await this.request("POST", "/billpayment?operation=delete", {
+      Id: id,
+      SyncToken: syncToken
+    });
+  }
+  // ============================================
+  // CreditMemo Methods (customer-facing credit notes)
+  // ============================================
+  async getCreditMemo(id) {
+    const response = await this.request(
+      "GET",
+      `/creditmemo/${id}`
+    );
+    return response.CreditMemo;
+  }
+  async getCreditMemos(where) {
+    const sql = where ? `SELECT * FROM CreditMemo WHERE ${where}` : "SELECT * FROM CreditMemo";
+    return this.queryAll(sql);
+  }
+  async createCreditMemo(creditMemo) {
+    const response = await this.request(
+      "POST",
+      "/creditmemo",
+      creditMemo
+    );
+    return response.CreditMemo;
+  }
+  async updateCreditMemo(creditMemo) {
+    const response = await this.request(
+      "POST",
+      "/creditmemo",
+      creditMemo
+    );
+    return response.CreditMemo;
+  }
+  async deleteCreditMemo(id, syncToken) {
+    await this.request("POST", "/creditmemo?operation=delete", {
+      Id: id,
+      SyncToken: syncToken
+    });
+  }
+  // ============================================
+  // VendorCredit Methods (supplier-side credit notes)
+  // ============================================
+  async getVendorCredit(id) {
+    const response = await this.request(
+      "GET",
+      `/vendorcredit/${id}`
+    );
+    return response.VendorCredit;
+  }
+  async getVendorCredits(where) {
+    const sql = where ? `SELECT * FROM VendorCredit WHERE ${where}` : "SELECT * FROM VendorCredit";
+    return this.queryAll(sql);
+  }
+  async createVendorCredit(vendorCredit) {
+    const response = await this.request(
+      "POST",
+      "/vendorcredit",
+      vendorCredit
+    );
+    return response.VendorCredit;
+  }
+  async updateVendorCredit(vendorCredit) {
+    const response = await this.request(
+      "POST",
+      "/vendorcredit",
+      vendorCredit
+    );
+    return response.VendorCredit;
+  }
+  async deleteVendorCredit(id, syncToken) {
+    await this.request("POST", "/vendorcredit?operation=delete", {
+      Id: id,
+      SyncToken: syncToken
+    });
+  }
+  // ============================================
+  // TaxCode Methods (read-only in QBO API)
+  // ============================================
+  async getTaxCode(id) {
+    const response = await this.request(
+      "GET",
+      `/taxcode/${id}`
+    );
+    return response.TaxCode;
+  }
+  async getTaxCodes(where) {
+    const sql = where ? `SELECT * FROM TaxCode WHERE ${where}` : "SELECT * FROM TaxCode";
+    return this.queryAll(sql);
+  }
+  // ============================================
+  // TaxRate Methods (read-only in QBO API)
+  // ============================================
+  async getTaxRate(id) {
+    const response = await this.request(
+      "GET",
+      `/taxrate/${id}`
+    );
+    return response.TaxRate;
+  }
+  async getTaxRates(where) {
+    const sql = where ? `SELECT * FROM TaxRate WHERE ${where}` : "SELECT * FROM TaxRate";
+    return this.queryAll(sql);
+  }
   // ============================================
   // Item Methods
   // ============================================
@@ -570,7 +803,7 @@ var QuickBooksClient = class {
   }
   async getItems(where) {
     const sql = where ? `SELECT * FROM Item WHERE ${where}` : "SELECT * FROM Item WHERE Active = true";
-    return this.query(sql);
+    return this.queryAll(sql);
   }
   async createItem(item) {
     const response = await this.request("POST", "/item", item);
@@ -581,6 +814,113 @@ var QuickBooksClient = class {
     return response.Item;
   }
   // ============================================
+  // Attachable Methods
+  // ============================================
+  async getAttachable(id) {
+    const response = await this.request(
+      "GET",
+      `/attachable/${id}`
+    );
+    return response.Attachable;
+  }
+  async getAttachables(where) {
+    const sql = where ? `SELECT * FROM Attachable WHERE ${where}` : "SELECT * FROM Attachable";
+    return this.queryAll(sql);
+  }
+  /**
+   * Upload a file and attach it to an entity.
+   * Uses multipart/form-data — the QBO upload endpoint differs from standard CRUD.
+   */
+  async uploadAttachable(file, fileName, contentType, attachTo) {
+    await this.checkRateLimit();
+    const tokens = await this.getValidTokens();
+    const env = this.config.environment || "production";
+    const baseUrl = API_BASE[env];
+    const url = this.appendMinorVersion(
+      `${baseUrl}/v3/company/${tokens.realm_id}/upload`
+    );
+    const metadata = {
+      FileName: fileName,
+      ContentType: contentType
+    };
+    if (attachTo) {
+      metadata.AttachableRef = [
+        {
+          EntityRef: {
+            value: attachTo.entityId,
+            name: attachTo.entityType
+          }
+        }
+      ];
+    }
+    const formData = new FormData();
+    formData.append(
+      "file_metadata_0",
+      new Blob([JSON.stringify(metadata)], { type: "application/json" })
+    );
+    const fileBlob = file instanceof Buffer ? new Blob([file], { type: contentType }) : file;
+    formData.append("file_content_0", fileBlob, fileName);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${tokens.access_token}`,
+          Accept: "application/json"
+        },
+        body: formData
+      });
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw { status: response.status, ...errorData };
+      }
+      const data = await response.json();
+      return data.AttachableResponse[0].Attachable;
+    } catch (error) {
+      throw handleQuickBooksError(error);
+    }
+  }
+  async updateAttachable(attachable) {
+    const response = await this.request(
+      "POST",
+      "/attachable",
+      attachable
+    );
+    return response.Attachable;
+  }
+  async deleteAttachable(id, syncToken) {
+    await this.request("POST", "/attachable?operation=delete", {
+      Id: id,
+      SyncToken: syncToken
+    });
+  }
+  // ============================================
+  // Batch Operations
+  // ============================================
+  /**
+   * Execute a batch of up to 30 operations in a single API call.
+   * Each item needs a unique bId and the entity payload.
+   *
+   * @example
+   * ```ts
+   * const results = await client.batch([
+   *   { bId: "1", operation: "create", Bill: { VendorRef: { value: "1" }, Line: [...] } },
+   *   { bId: "2", operation: "query", optionsData: "SELECT * FROM Vendor WHERE Id = '1'" },
+   * ]);
+   * ```
+   */
+  async batch(items) {
+    if (items.length > 30) {
+      throw new QuickBooksError(
+        "Batch operations are limited to 30 items per request",
+        QB_ERROR_CODES.INVALID_CONFIG
+      );
+    }
+    const response = await this.request("POST", "/batch", {
+      BatchItemRequest: items
+    });
+    return response;
+  }
+  // ============================================
   // Utility Methods
   // ============================================
   /**