conductor-node 0.0.5 → 0.0.8

package/src/qb/ClientQBD.ts

@@ -0,0 +1,152 @@
+import type Client from "@conductor/client/Client";
+import type {
+  AccountAdd,
+  AccountAddRs,
+  AccountQueryRq,
+  AccountQueryRs,
+  AccountRet,
+} from "@conductor/client/qb/qbXMLTypes/Account";
+import type {
+  EmployeeAdd,
+  EmployeeAddRs,
+  EmployeeMod,
+  EmployeeModRs,
+  EmployeeQueryRq,
+  EmployeeQueryRs,
+  EmployeeRet,
+} from "@conductor/client/qb/qbXMLTypes/Employee";
+
+export default class ClientQBD {
+  private readonly client: Client;
+
+  public constructor(rootClient: Client) {
+    this.client = rootClient;
+  }
+
+  public async sendRequest(
+    qbwcUsername: string,
+    requestObj: object
+  ): Promise<object> {
+    if (this.client.verbose) {
+      console.log(
+        `Client sent request for user ${qbwcUsername}:`,
+        JSON.stringify(requestObj, null, 2)
+      );
+    }
+
+    const response = await fetch("https://conductor.ngrok.io", {
+      body: JSON.stringify({ qbwcUsername, requestObj }),
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.client.apiKey}`,
+      },
+      method: "POST",
+    });
+    const responseObj = (await response.json()) as object;
+
+    if (this.client.verbose) {
+      console.log(
+        `Client received response for user ${qbwcUsername}:`,
+        JSON.stringify(responseObj, null, 2)
+      );
+    }
+
+    return responseObj;
+  }
+
+  // https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/accountadd
+  public async accountAdd(
+    qbwcUsername: string,
+    params: AccountAdd
+  ): Promise<AccountRet> {
+    const response = (await this.sendRequest(qbwcUsername, {
+      AccountAddRq: { AccountAdd: params },
+    })) as { AccountAddRs: AccountAddRs };
+    const responseBody = response.AccountAddRs.AccountRet;
+    if (!responseBody) {
+      throw new Error("No response");
+    }
+    return responseBody;
+  }
+
+  /**
+   * `AccountQuery` is a list query that returns data for all accounts that match
+   * the provided filter criteria. Notice that it returns only data internal to
+   * the account itself. It does not return any data about transactions
+   * involving the account. It does, however, return the parent account, if
+   * there is one. You can search across all accounts or you can specify an
+   * account type and search only those.
+   *
+   * https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/accountquery
+   */
+  public async accountQuery(
+    qbwcUsername: string,
+    params: AccountQueryRq
+  ): Promise<AccountRet> {
+    const response = (await this.sendRequest(qbwcUsername, {
+      AccountQueryRq: params,
+    })) as { AccountQueryRs: AccountQueryRs };
+    const responseBody = response.AccountQueryRs.AccountRet;
+    if (!responseBody) {
+      throw new Error("No response");
+    }
+    return responseBody;
+  }
+
+  /**
+   * Adds an employee with personal data about the employee as well as certain payroll-related data.
+   *
+   * https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/employeeAdd
+   */
+  public async employeeAdd(
+    qbwcUsername: string,
+    params: EmployeeAdd
+  ): Promise<EmployeeRet> {
+    const response = (await this.sendRequest(qbwcUsername, {
+      EmployeeAddRq: { EmployeeAdd: params },
+    })) as { EmployeeAddRs: EmployeeAddRs };
+    const responseBody = response.EmployeeAddRs.EmployeeRet;
+    if (!responseBody) {
+      throw new Error("No response");
+    }
+    return responseBody;
+  }
+
+  /**
+   * Modifies an existing employee.
+   *
+   * https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/employeemod
+   */
+  public async employeeMod(
+    qbwcUsername: string,
+    params: EmployeeMod
+  ): Promise<EmployeeRet> {
+    const response = (await this.sendRequest(qbwcUsername, {
+      EmployeeModRq: { EmployeeMod: params },
+    })) as { EmployeeModRs: EmployeeModRs };
+    const responseBody = response.EmployeeModRs.EmployeeRet;
+    if (!responseBody) {
+      throw new Error("No response");
+    }
+    return responseBody;
+  }
+
+  /**
+   * Returns employee data.
+   *
+   * https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/employeeQuery
+   */
+  public async employeeQuery(
+    qbwcUsername: string,
+    params: EmployeeQueryRq
+  ): Promise<EmployeeRet> {
+    const response = (await this.sendRequest(qbwcUsername, {
+      EmployeeQueryRq: params,
+    })) as { EmployeeQueryRs: EmployeeQueryRs };
+    const responseBody = response.EmployeeQueryRs.EmployeeRet;
+    if (!responseBody) {
+      throw new Error("No response");
+    }
+    return responseBody;
+  }
+}

package/src/qb/qbXMLTypes/Account.ts

@@ -0,0 +1,325 @@
+import type {
+  ActiveStatus,
+  DataExtRet,
+  NameFilter,
+  NameRangeFilter,
+} from "@conductor/client/qb/qbXMLTypes/shared";
+
+// https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/accountadd
+export interface AccountAddRq {
+  AccountAdd: AccountAdd;
+  IncludeRetElement?: string;
+}
+
+export interface AccountAddRs {
+  // TODO: Confirm whether this is an array or not.
+  AccountRet?: AccountRet;
+}
+
+export interface AccountAdd {
+  /**
+   * The case-insensitive name of a list object, not including the names of its
+   * ancestors. Name must be unique, unless it is the Name of a “hierarchical”
+   * list object. List objects in different hierarchies can have duplicate names
+   * because their FullNames will still be unique. For example, two objects
+   * could both have the Name kitchen, but they could have unique FullNames,
+   * such as Job12:kitchen and Baker:kitchen. For built-in currencies, Name is
+   * the internationally accepted currency name and is not editable.
+   */
+  Name: string;
+  /**
+   * If `IsActive` is `true`, this object is currently enabled for use by
+   * QuickBooks. The default value is `true`.
+   */
+  IsActive?: boolean;
+  /**
+   * A reference to the list object that is one level above this one. For
+   * example, an inventory item with the `FullName` of
+   * `GermanCars:Mercedes-Benz:CL500I99AA` might have a parent object with the
+   * `FullName` of `GermanCars:Mercedes-Benz`. In a request, if a `ParentRef`
+   * aggregate includes both `FullName` and `ListID`, `FullName` will be
+   * ignored.
+   */
+  ParentRef?: ParentRef;
+  /**
+   * The type of QuickBooks account. You cannot create or modify a non-posting
+   * account through the SDK, because QuickBooks creates these accounts behind
+   * the scenes. This means that you cannot send an AccountAdd request with an
+   * AccountType of NonPosting.
+   */
+  AccountType: AccountType;
+  /**
+   * Account numbers appear in the QuickBooks chart of accounts, Account fields,
+   * and reports and graphs. If the `IsUsingAccountNumber` preference is `false`
+   * (that is, if the QuickBooks user has the account numbers Preference turned
+   * off), you can still set account numbers through the SDK, but the numbers
+   * will not be visible in the user interface.
+   */
+  AccountNumber?: string;
+  /**
+   * The bank account number or an identifying note about the account. If a
+   * `BankNumber` exists in a QuickBooks company file, it will only be returned
+   * to applications that have been granted permission to access sensitive data
+   * and that are using SDK v2.0 or greater.
+   */
+  BankNumber?: string;
+  /**
+   * A descriptive text field.
+   */
+  Desc?: string;
+  /**
+   * The amount of money in, or the value of, this account as of
+   * `OpenBalanceDate`. On a bank statement, the amount of money in the account
+   * at the beginning of the statement period.
+   */
+  OpenBalance?: string;
+  /**
+   * The date when an opening balance was entered for this account.
+   */
+  OpenBalanceDate?: Date;
+  /**
+   * Each item on a sales form is assigned a sales-tax code that indicates
+   * whether the item is taxable or non-taxable, and why. Two general codes,
+   * which can be modified but not deleted, appear on the sales-tax code list by
+   * default: `Non-taxable (Name = NON; Desc = Non-Taxable; IsTaxable = false)`,
+   * `Taxable (Name = TAX; Desc = Taxable; IsTaxable = true)`. A sales-tax code
+   * can be deleted only if it is no longer associated with any customer, item,
+   * or transaction. If the “Do You Charge Sales Tax?” preference within
+   * QuickBooks is set to No, QuickBooks will assign the default non-taxable
+   * sales-tax code to all sales. A `SalesTaxCodeRef` aggregate refers to a
+   * sales-tax code on the list. In a request, if a `SalesTaxCodeRef` aggregate
+   * includes both FullName and `ListID`, FullName will be ignored. In a
+   * Customer message, `SalesTaxCodeRef` refers to the sales-tax code that will
+   * be used for items related to this customer. In an ItemInventory message,
+   * `SalesTaxCodeRef` refers to the type of sales tax that will be charged for
+   * this item, if it is a taxable item and if sales tax is set up within
+   * QuickBooks.
+   */
+  SalesTaxCodeRef?: SalesTaxCodeRef;
+  /**
+   * An internal representation of the tax line associated with this account.
+   */
+  TaxLineID?: number;
+  /**
+   * The currency object contains all of the information needed by QuickBooks to
+   * display and use. For built-in currencies, the name and currency code values
+   * are internationally accepted values and thus are not editable. The comma
+   * format is editable, as is the IsActive status. For user-defined currencies,
+   * every value in the object is editable including name and currency code.
+   * When used with PriceLevels, the CurrencyRef should only be used with “per
+   * item” price levels.
+   */
+  CurrencyRef?: CurrencyRef;
+}
+
+// https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/accountquery
+// FIXME: This does not account for the use of "OR" and "may repeat" in the
+// XMLOps, which might indicate using an array.
+export interface AccountQueryRq {
+  ListID?: string;
+  FullName?: string;
+  /**
+   * Limits the number of objects that a query returns. (To get a count of how
+   * many objects could possibly be returned, use the metaData query attribute.)
+   * If you include a `MaxReturned` value, it must be at least 1.
+   */
+  MaxReturned?: number;
+  /**
+   * Used in filters to select list objects based on whether or not they are
+   * currently enabled for use by QuickBooks. The default value is `ActiveOnly`,
+   * which selects only list objects that are active.
+   */
+  ActiveStatus?: ActiveStatus;
+  FromModifiedDate?: Date;
+  ToModifiedDate?: Date;
+  /**
+   * Filters according to the object’s `Name`.
+   */
+  NameFilter?: NameFilter;
+  /**
+   * Filters according to the object’s `Name`.
+   */
+  NameRangeFilter?: NameRangeFilter;
+  AccountType?: AccountType;
+  CurrencyFilter?: CurrencyFilter;
+}
+
+export interface AccountQueryRs {
+  // TODO: Confirm whether this is an array or not.
+  AccountRet?: AccountRet;
+}
+
+export interface AccountRet {
+  /**
+   * Along with `FullName`, `ListID` is a way to identify a list object. When a
+   * list object is added to QuickBooks through the SDK or through the
+   * QuickBooks user interface, the server assigns it a `ListID`. A `ListID` is
+   * not unique across lists, but it is unique across each particular type of
+   * list. For example, two customers could not have the same `ListID`, and a
+   * customer could not have the same `ListID` as an employee (because Customer
+   * and Employee are both name lists). But a customer could have the same
+   * `ListID` as a non-inventory item.
+   */
+  ListID: string;
+  /**
+   * Time the object was created.
+   */
+  TimeCreated: string;
+  /**
+   * Time the object was last modified.
+   */
+  TimeModified: string;
+  /**
+   * A number that the server generates and assigns to this object. Every time
+   * the object is changed, the server will change its `EditSequence` value.
+   * When you try to modify a list object, you must provide its `EditSequence`.
+   * The server compares the `EditSequence` you provide with the `EditSequence`
+   * in memory to make sure you are dealing with the latest copy of the object.
+   * If you are not, the server will reject the request and return an error.
+   * Because `EditSequence` is only used to check whether two objects match,
+   * there is no reason to interpret its value.
+   */
+  EditSequence: string;
+  /**
+   * The case-insensitive name of a list object, not including the names of its
+   * ancestors. `Name` must be unique, unless it is the `Name` of a
+   * “hierarchical” list object. List objects in different hierarchies can have
+   * duplicate names because their `FullNames` will still be unique. For
+   * example, two objects could both have the `Name` kitchen, but they could
+   * have unique `FullNames`, such as Job12:kitchen and Baker:kitchen. For
+   * built-in currencies, `Name` is the internationally accepted currency name
+   * and is not editable.
+   */
+  Name: string;
+  /**
+   * `FullName` (along with `ListID`) is a way to identify a list object. The
+   * `FullName` is the name prefixed by the names of each ancestor, for example
+   * `Jones:Kitchen:Cabinets`. `FullName` values are not case-sensitive.
+   */
+  FullName: string;
+  /**
+   * If `IsActive` is true, this object is currently enabled for use by
+   * QuickBooks. The default value is `true`.
+   */
+  IsActive?: boolean;
+  /**
+   * A reference to the list object that is one level above this one. For
+   * example, an inventory item with the `FullName` of
+   * `GermanCars:Mercedes-Benz:CL500I99AA` might have a parent object with the
+   * `FullName` of `GermanCars:Mercedes-Benz`. In a request, if a `ParentRef`
+   * aggregate includes both `FullName` and `ListID`, `FullName` will be
+   * ignored.
+   */
+  ParentRef?: ParentRef;
+  /**
+   * The number of ancestors. For example, The customer job with `Name =
+   * carpets` and `FullName = Jones:Building2:carpets` would have a sublevel of
+   * 2.
+   */
+  Sublevel: number;
+  /**
+   * The type of QuickBooks account. You cannot create or modify a non-posting
+   * account through the SDK, because QuickBooks creates these accounts behind
+   * the scenes. This means that you cannot send an `AccountAdd` request with an
+   * `AccountType` of `NonPosting`.
+   */
+  AccountType: AccountType;
+  /**
+   * If `SpecialAccountType` returns a value, then QuickBooks automatically
+   * created this account when it was needed. Some special accounts cannot be
+   * overridden, because QuickBooks uses them exclusively for special purposes.
+   */
+  SpecialAccountType?: SpecialAccountType;
+  /**
+   * Indicates whether the account is used for tax.
+   */
+  IsTaxAccount?: boolean;
+  /**
+   * Account numbers appear in the QuickBooks chart of accounts, `Account`
+   * fields, and reports and graphs. If the `IsUsingAccountNumber` preference is
+   * false (that is, if the QuickBooks user has the account numbers Preference
+   * turned off), you can still set account numbers through the SDK, but the
+   * numbers will not be visible in the user interface.
+   */
+  AccountNumber?: string;
+  BankNumber?: string;
+  Desc?: string;
+  Balance?: string;
+  TotalBalance?: string;
+  SalesTaxCodeRef?: SalesTaxCodeRef;
+  TaxLineInfoRet?: {
+    TaxLineID: number;
+    TaxLineName?: string;
+  };
+  CashFlowClassification?: CashFlowClassification;
+  CurrencyRef?: CurrencyRef;
+  DataExtRet?: DataExtRet;
+}
+
+interface CurrencyFilter {
+  ListID?: string;
+  FullName?: string;
+}
+
+interface ParentRef {
+  ListID?: string;
+  FullName?: string;
+}
+
+interface SalesTaxCodeRef {
+  ListID?: string;
+  FullName?: string;
+}
+
+interface CurrencyRef {
+  ListID?: string;
+  FullName?: string;
+}
+
+type AccountType =
+  | "AccountsPayable"
+  | "AccountsReceivable"
+  | "Bank"
+  | "CostOfGoodsSold"
+  | "CreditCard"
+  | "Equity"
+  | "Expense"
+  | "FixedAsset"
+  | "Income"
+  | "LongTermLiability"
+  | "NonPosting"
+  | "OtherAsset"
+  | "OtherCurrentAsset"
+  | "OtherCurrentLiability"
+  | "OtherExpense"
+  | "OtherIncome";
+
+type SpecialAccountType =
+  | "AccountsPayable"
+  | "AccountsReceivable"
+  | "CondenseItemAdjustmentExpenses"
+  | "CostOfGoodsSold"
+  | "DirectDepositLiabilities"
+  | "Estimates"
+  | "ExchangeGainLoss"
+  | "InventoryAssets"
+  | "ItemReceiptAccount"
+  | "OpeningBalanceEquity"
+  | "PayrollExpenses"
+  | "PayrollLiabilities"
+  | "PettyCash"
+  | "PurchaseOrders"
+  | "ReconciliationDifferences"
+  | "RetainedEarnings"
+  | "SalesOrders"
+  | "SalesTaxPayable"
+  | "UncategorizedExpenses"
+  | "UncategorizedIncome"
+  | "UndepositedFunds";
+
+type CashFlowClassification =
+  | "Financing"
+  | "Investing"
+  | "None"
+  | "NotApplicable"
+  | "Operating";