@panoptic-it-solutions/quickbooks-client 0.1.0

package/dist/index.mjs

@@ -0,0 +1,557 @@
+// src/errors.ts
+var QB_ERROR_CODES = {
+  TOKEN_EXPIRED: "QB_TOKEN_EXPIRED",
+  REFRESH_FAILED: "QB_REFRESH_FAILED",
+  UNAUTHORIZED: "QB_UNAUTHORIZED",
+  INVALID_REALM: "QB_INVALID_REALM",
+  API_ERROR: "QB_API_ERROR",
+  RATE_LIMIT: "QB_RATE_LIMIT",
+  NETWORK_ERROR: "QB_NETWORK_ERROR",
+  INVALID_CONFIG: "QB_INVALID_CONFIG",
+  TOKEN_STORE_ERROR: "QB_TOKEN_STORE_ERROR"
+};
+var QuickBooksError = class extends Error {
+  constructor(message, code, status, details) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.name = "QuickBooksError";
+  }
+};
+function handleQuickBooksError(error) {
+  if (error instanceof QuickBooksError) {
+    return error;
+  }
+  if (error instanceof TypeError && error.message.includes("fetch")) {
+    return new QuickBooksError(
+      "Network error connecting to QuickBooks API",
+      QB_ERROR_CODES.NETWORK_ERROR,
+      0,
+      error
+    );
+  }
+  if (typeof error === "object" && error !== null) {
+    const err = error;
+    if (typeof err.status === "number") {
+      if (err.status === 401) {
+        return new QuickBooksError(
+          "Unauthorized access to QuickBooks API",
+          QB_ERROR_CODES.UNAUTHORIZED,
+          401,
+          error
+        );
+      }
+      if (err.status === 403) {
+        return new QuickBooksError(
+          "Access forbidden - check API permissions",
+          QB_ERROR_CODES.UNAUTHORIZED,
+          403,
+          error
+        );
+      }
+      if (err.status === 429) {
+        return new QuickBooksError(
+          "QuickBooks API rate limit exceeded",
+          QB_ERROR_CODES.RATE_LIMIT,
+          429,
+          error
+        );
+      }
+    }
+    const message = String(err.message || "");
+    if (message.includes("token expired") || message.includes("invalid_token")) {
+      return new QuickBooksError(
+        "QuickBooks token expired",
+        QB_ERROR_CODES.TOKEN_EXPIRED,
+        401,
+        error
+      );
+    }
+  }
+  return new QuickBooksError(
+    "An unexpected error occurred with QuickBooks integration",
+    QB_ERROR_CODES.API_ERROR,
+    500,
+    error
+  );
+}
+
+// src/oauth.ts
+var ENDPOINTS = {
+  sandbox: {
+    authorize: "https://appcenter.intuit.com/connect/oauth2",
+    token: "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer",
+    revoke: "https://developer.api.intuit.com/v2/oauth2/tokens/revoke"
+  },
+  production: {
+    authorize: "https://appcenter.intuit.com/connect/oauth2",
+    token: "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer",
+    revoke: "https://developer.api.intuit.com/v2/oauth2/tokens/revoke"
+  }
+};
+var DEFAULT_SCOPES = ["com.intuit.quickbooks.accounting"];
+function generateAuthUrl(config, state) {
+  const env = config.environment || "production";
+  const scopes = config.scopes || DEFAULT_SCOPES;
+  const params = new URLSearchParams({
+    client_id: config.clientId,
+    redirect_uri: config.redirectUri,
+    response_type: "code",
+    scope: scopes.join(" "),
+    state
+  });
+  return `${ENDPOINTS[env].authorize}?${params.toString()}`;
+}
+async function exchangeCodeForTokens(config, code, realmId) {
+  const env = config.environment || "production";
+  const credentials = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
+  const response = await fetch(ENDPOINTS[env].token, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Authorization: `Basic ${credentials}`,
+      Accept: "application/json"
+    },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: config.redirectUri
+    }).toString()
+  });
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({}));
+    throw new QuickBooksError(
+      `Failed to exchange code for tokens: ${response.status}`,
+      QB_ERROR_CODES.UNAUTHORIZED,
+      response.status,
+      errorData
+    );
+  }
+  const data = await response.json();
+  return {
+    access_token: data.access_token,
+    refresh_token: data.refresh_token,
+    realm_id: realmId,
+    expires_at: calculateTokenExpiry(data.expires_in),
+    token_type: data.token_type
+  };
+}
+async function refreshTokens(config, refreshToken, realmId) {
+  const env = config.environment || "production";
+  const credentials = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
+  const response = await fetch(ENDPOINTS[env].token, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Authorization: `Basic ${credentials}`,
+      Accept: "application/json"
+    },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: refreshToken
+    }).toString()
+  });
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({}));
+    throw new QuickBooksError(
+      `Failed to refresh tokens: ${response.status}`,
+      QB_ERROR_CODES.REFRESH_FAILED,
+      response.status,
+      errorData
+    );
+  }
+  const data = await response.json();
+  return {
+    access_token: data.access_token,
+    refresh_token: data.refresh_token,
+    realm_id: realmId,
+    expires_at: calculateTokenExpiry(data.expires_in),
+    token_type: data.token_type
+  };
+}
+async function revokeTokens(config, token) {
+  const env = config.environment || "production";
+  const credentials = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
+  const response = await fetch(ENDPOINTS[env].revoke, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Basic ${credentials}`,
+      Accept: "application/json"
+    },
+    body: JSON.stringify({ token })
+  });
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({}));
+    throw new QuickBooksError(
+      `Failed to revoke tokens: ${response.status}`,
+      QB_ERROR_CODES.API_ERROR,
+      response.status,
+      errorData
+    );
+  }
+}
+function calculateTokenExpiry(expiresIn) {
+  return Math.floor(Date.now() / 1e3) + expiresIn;
+}
+function isTokenExpired(expiresAt, bufferSeconds = 300) {
+  const now = Math.floor(Date.now() / 1e3);
+  return now >= expiresAt - bufferSeconds;
+}
+function generateState() {
+  const array = new Uint8Array(16);
+  crypto.getRandomValues(array);
+  return Array.from(array, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+// src/client.ts
+var API_BASE = {
+  sandbox: "https://sandbox-quickbooks.api.intuit.com",
+  production: "https://quickbooks.api.intuit.com"
+};
+var RATE_LIMIT = 500;
+var RATE_LIMIT_WINDOW_MS = 60 * 1e3;
+var MAX_RETRIES = 3;
+var INITIAL_RETRY_DELAY_MS = 1e3;
+var QuickBooksClient = class {
+  config;
+  tokenStore;
+  requestTimestamps = [];
+  onLog;
+  constructor(options) {
+    this.validateConfig(options);
+    this.config = options;
+    this.tokenStore = options.tokenStore;
+    this.onLog = options.onLog;
+  }
+  validateConfig(options) {
+    if (!options.clientId) {
+      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);
+    }
+    if (!options.redirectUri) {
+      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);
+    }
+  }
+  log(level, message, data) {
+    if (this.onLog) {
+      this.onLog(level, message, data);
+    }
+  }
+  /**
+   * Rate limiting - ensures we don't exceed 500 requests/minute
+   */
+  async checkRateLimit() {
+    const now = Date.now();
+    this.requestTimestamps = this.requestTimestamps.filter(
+      (ts) => now - ts < RATE_LIMIT_WINDOW_MS
+    );
+    if (this.requestTimestamps.length >= RATE_LIMIT) {
+      const oldestTimestamp = this.requestTimestamps[0];
+      const waitTime = RATE_LIMIT_WINDOW_MS - (now - oldestTimestamp) + 100;
+      this.log("warn", `Rate limit reached, waiting ${waitTime}ms`);
+      await new Promise((resolve) => setTimeout(resolve, waitTime));
+    }
+    this.requestTimestamps.push(Date.now());
+  }
+  /**
+   * Get current tokens, refreshing if necessary
+   */
+  async getValidTokens() {
+    const tokens = await this.tokenStore.getTokens();
+    if (!tokens) {
+      throw new QuickBooksError(
+        "No tokens found - please connect to QuickBooks first",
+        QB_ERROR_CODES.UNAUTHORIZED
+      );
+    }
+    if (isTokenExpired(tokens.expires_at)) {
+      this.log("info", "Token expired, refreshing...");
+      try {
+        const newTokens = await refreshTokens(
+          this.config,
+          tokens.refresh_token,
+          tokens.realm_id
+        );
+        await this.tokenStore.storeTokens(newTokens);
+        this.log("info", "Token refreshed successfully");
+        return newTokens;
+      } catch (error) {
+        if (error instanceof QuickBooksError && error.status === 401) {
+          this.log("warn", "Refresh token invalid, clearing tokens");
+          await this.tokenStore.clearTokens();
+        }
+        throw error;
+      }
+    }
+    return tokens;
+  }
+  /**
+   * Make an authenticated API request with retry logic
+   */
+  async request(method, endpoint, body, retryCount = 0) {
+    await this.checkRateLimit();
+    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}`;
+    this.log("debug", `${method} ${endpoint}`, { body });
+    const headers = {
+      Authorization: `Bearer ${tokens.access_token}`,
+      Accept: "application/json"
+    };
+    if (body) {
+      headers["Content-Type"] = "application/json";
+    }
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0
+      });
+      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})`);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        return this.request(method, endpoint, body, retryCount + 1);
+      }
+      if (response.status === 401 && retryCount < 1) {
+        this.log("warn", "Got 401, attempting token refresh");
+        const tokens2 = await this.tokenStore.getTokens();
+        if (tokens2) {
+          const newTokens = await refreshTokens(
+            this.config,
+            tokens2.refresh_token,
+            tokens2.realm_id
+          );
+          await this.tokenStore.storeTokens(newTokens);
+          return this.request(method, endpoint, body, retryCount + 1);
+        }
+      }
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw { status: response.status, ...errorData };
+      }
+      return await response.json();
+    } catch (error) {
+      throw handleQuickBooksError(error);
+    }
+  }
+  /**
+   * Execute a query using QuickBooks Query Language
+   */
+  async query(sql) {
+    const response = await this.request("POST", "/query", void 0);
+    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`;
+    await this.checkRateLimit();
+    const fetchResponse = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${tokens.access_token}`,
+        Accept: "application/json",
+        "Content-Type": "application/text"
+      },
+      body: sql
+    });
+    if (!fetchResponse.ok) {
+      const errorData = await fetchResponse.json().catch(() => ({}));
+      throw handleQuickBooksError({ status: fetchResponse.status, ...errorData });
+    }
+    const data = await fetchResponse.json();
+    const keys = Object.keys(data.QueryResponse).filter(
+      (k) => !["startPosition", "maxResults", "totalCount"].includes(k)
+    );
+    const entityKey = keys[0];
+    return entityKey ? data.QueryResponse[entityKey] : [];
+  }
+  // ============================================
+  // Invoice Methods
+  // ============================================
+  async getInvoice(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);
+  }
+  async createInvoice(invoice) {
+    const response = await this.request("POST", "/invoice", invoice);
+    return response.Invoice;
+  }
+  async updateInvoice(invoice) {
+    const response = await this.request("POST", "/invoice", invoice);
+    return response.Invoice;
+  }
+  async deleteInvoice(id, syncToken) {
+    await this.request("POST", "/invoice", {
+      Id: id,
+      SyncToken: syncToken
+    });
+  }
+  // ============================================
+  // Customer Methods
+  // ============================================
+  async getCustomer(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);
+  }
+  async createCustomer(customer) {
+    const response = await this.request("POST", "/customer", customer);
+    return response.Customer;
+  }
+  async updateCustomer(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}`);
+    return response.Payment;
+  }
+  async getPayments(where) {
+    const sql = where ? `SELECT * FROM Payment WHERE ${where}` : "SELECT * FROM Payment";
+    return this.query(sql);
+  }
+  async createPayment(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}`);
+    return response.Account;
+  }
+  async getAccounts(where) {
+    const sql = where ? `SELECT * FROM Account WHERE ${where}` : "SELECT * FROM Account WHERE Active = true";
+    return this.query(sql);
+  }
+  // ============================================
+  // Vendor Methods
+  // ============================================
+  async getVendor(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);
+  }
+  async createVendor(vendor) {
+    const response = await this.request("POST", "/vendor", vendor);
+    return response.Vendor;
+  }
+  async updateVendor(vendor) {
+    const response = await this.request("POST", "/vendor", vendor);
+    return response.Vendor;
+  }
+  // ============================================
+  // Bill Methods
+  // ============================================
+  async getBill(id) {
+    const response = await this.request("GET", `/bill/${id}`);
+    return response.Bill;
+  }
+  async getBills(where) {
+    const sql = where ? `SELECT * FROM Bill WHERE ${where}` : "SELECT * FROM Bill";
+    return this.query(sql);
+  }
+  async createBill(bill) {
+    const response = await this.request("POST", "/bill", bill);
+    return response.Bill;
+  }
+  async updateBill(bill) {
+    const response = await this.request("POST", "/bill", bill);
+    return response.Bill;
+  }
+  // ============================================
+  // Item Methods
+  // ============================================
+  async getItem(id) {
+    const response = await this.request("GET", `/item/${id}`);
+    return response.Item;
+  }
+  async getItems(where) {
+    const sql = where ? `SELECT * FROM Item WHERE ${where}` : "SELECT * FROM Item WHERE Active = true";
+    return this.query(sql);
+  }
+  async createItem(item) {
+    const response = await this.request("POST", "/item", item);
+    return response.Item;
+  }
+  async updateItem(item) {
+    const response = await this.request("POST", "/item", item);
+    return response.Item;
+  }
+  // ============================================
+  // Utility Methods
+  // ============================================
+  /**
+   * Get company info
+   */
+  async getCompanyInfo() {
+    const tokens = await this.getValidTokens();
+    const response = await this.request(
+      "GET",
+      `/companyinfo/${tokens.realm_id}`
+    );
+    return response.CompanyInfo;
+  }
+  /**
+   * Check if connected to QuickBooks
+   */
+  async isConnected() {
+    try {
+      const tokens = await this.tokenStore.getTokens();
+      return tokens !== null;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Check connection status with details
+   */
+  async getConnectionStatus() {
+    const tokens = await this.tokenStore.getTokens();
+    if (!tokens) {
+      return { isConnected: false, needsRefresh: false };
+    }
+    return {
+      isConnected: true,
+      needsRefresh: isTokenExpired(tokens.expires_at),
+      realmId: tokens.realm_id,
+      expiresAt: tokens.expires_at
+    };
+  }
+};
+export {
+  QB_ERROR_CODES,
+  QuickBooksClient,
+  QuickBooksError,
+  calculateTokenExpiry,
+  exchangeCodeForTokens,
+  generateAuthUrl,
+  generateState,
+  handleQuickBooksError,
+  isTokenExpired,
+  refreshTokens,
+  revokeTokens
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@panoptic-it-solutions/quickbooks-client",
+  "version": "0.1.0",
+  "description": "QuickBooks Online API client with OAuth 2.0, rate limiting, and typed entities",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "biome check src",
+    "format": "biome format --write src",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "quickbooks",
+    "intuit",
+    "oauth",
+    "accounting",
+    "api",
+    "client"
+  ],
+  "author": "Panoptic Technology Ltd",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/panoptic-it-solutions/quickbooks-client"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "@types/node": "^20",
+    "tsup": "^8.0.0",
+    "typescript": "^5",
+    "vitest": "^2.0.0"
+  }
+}