conductor-node 0.0.8 → 0.0.11

package/README.md

@@ -1,12 +1,10 @@
 # Conductor Node.js Library
 
-The Conductor Node.js library provides convenient access to the Conductor API from applications written in server-side JavaScript.
-
-There are zero dependencies.
+The Conductor Node.js library provides convenient access to the Conductor API from applications written in server-side JavaScript. Zero dependencies.
 
 ## Requirements
 
-1. A running version of QuickBooks Desktop with QuickBooks Web Connector configured for Conductor. See the [Conductor Getting Started guide](https://www.notion.so/conductor-io/Conductor-Documentation-Getting-Started-7f0f42593d444337b0b3200c771d98e6) for help.
+1. A running version of QuickBooks Desktop with QuickBooks Web Connector configured for Conductor. See the [Conductor Getting Started guide](https://www.notion.so/conductor-io/Conductor-Documentation-Getting-Started-7f0f42593d444337b0b3200c771d98e6).
 2. A Conductor API key from Danny.
 
 ## Installation
@@ -21,7 +19,7 @@ The package must be configured with your account's secret key, which is availabl
 
 Currently supports executing any [QuickBooks Desktop API](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop) via JSON and receiving the response in JSON. In the future, Conductor will incorporate extensive typings for these APIs.
 
-To send a request to a specific QuickBooks Desktop user, you must also supply the username in their `.qwc` file that you provided them.
+To send a request to a specific QuickBooks Desktop user, you must also supply the username that is in their `.qwc` file that you provided them.
 
 ```ts
 import Conductor from "conductor-node";

package/dist/Client.d.ts

@@ -1,7 +1,6 @@
 import ClientQBD from "./qb/ClientQBD";
 export default class Client {
-    readonly apiKey: string;
-    readonly verbose: boolean;
+    /** QuickBooks Desktop integration. */
     readonly qbd: ClientQBD;
     constructor(apiKey: string, verbose?: boolean);
 }

package/dist/Client.js

@@ -5,13 +5,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const ClientQBD_1 = __importDefault(require("./qb/ClientQBD"));
 class Client {
-    apiKey;
-    verbose;
+    /** QuickBooks Desktop integration. */
     qbd;
     constructor(apiKey, verbose = false) {
-        this.apiKey = apiKey;
-        this.verbose = verbose;
-        this.qbd = new ClientQBD_1.default(this);
+        // Do not assign `apiKey` and `verbose` to the root `Client` to not expose
+        // the properties to the user (amid the integrations, like `ClientQBD`).
+        this.qbd = new ClientQBD_1.default(apiKey, verbose);
     }
 }
 exports.default = Client;

package/dist/qb/ClientQBD.d.ts

@@ -1,24 +1,51 @@
-import type Client from "../Client";
 import type { AccountAdd, AccountQueryRq, AccountRet } from "../qb/qbXMLTypes/Account";
+import type { CustomerQueryRq, CustomerRet } from "../qb/qbXMLTypes/Customer";
 import type { EmployeeAdd, EmployeeMod, EmployeeQueryRq, EmployeeRet } from "../qb/qbXMLTypes/Employee";
+import type { VendorQueryRq, VendorRet } from "../qb/qbXMLTypes/Vendor";
 export default class ClientQBD {
-    private readonly client;
-    constructor(rootClient: Client);
+    private readonly apiKey;
+    private readonly verbose;
+    constructor(apiKey: string, verbose: boolean);
+    /**
+     * Send any QBXML request to QuickBooks Desktop.
+     *
+     * Available APIs: https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop
+     */
     sendRequest(qbwcUsername: string, requestObj: object): Promise<object>;
+    /**
+     * Perform the same activities as a user does in the QB New Account form,
+     * which can be accessed in QB by selecting "Lists" → "Chart of Accounts" →
+     * "Accounts" → "New".
+     *
+     * https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/accountadd
+     */
     accountAdd(qbwcUsername: string, params: AccountAdd): Promise<AccountRet>;
     /**
-     * `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.
+     * `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
      */
     accountQuery(qbwcUsername: string, params: AccountQueryRq): Promise<AccountRet>;
     /**
-     * Adds an employee with personal data about the employee as well as certain payroll-related data.
+     * Returns data for the specified customers.
+     *
+     * Important: We highly recommend that you use the `IncludeRetElement` tag in
+     * your `CustomerQuery` to include any data you want but do NOT include the
+     * `ShipAddress` data in the `Response`, unless you need to get the shipping
+     * address for a particular customer. Excluding the shipping address data will
+     * significantly improve the performance of the `CustomerQuery`.
+     *
+     * https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/customerquery
+     */
+    customerQuery(qbwcUsername: string, params: CustomerQueryRq): Promise<CustomerRet>;
+    /**
+     * 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
      */
@@ -35,4 +62,10 @@ export default class ClientQBD {
      * https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/employeeQuery
      */
     employeeQuery(qbwcUsername: string, params: EmployeeQueryRq): Promise<EmployeeRet>;
+    /**
+     * Queries for the specified vendor or set of vendors.
+     *
+     * https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/vendorQuery
+     */
+    vendorQuery(qbwcUsername: string, params: VendorQueryRq): Promise<VendorRet>;
 }

package/dist/qb/ClientQBD.js

@@ -1,29 +1,43 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const SERVER_URL = "https://conductor.ngrok.io";
 class ClientQBD {
-    client;
-    constructor(rootClient) {
-        this.client = rootClient;
+    apiKey;
+    verbose;
+    constructor(apiKey, verbose) {
+        this.apiKey = apiKey;
+        this.verbose = verbose;
     }
+    /**
+     * Send any QBXML request to QuickBooks Desktop.
+     *
+     * Available APIs: https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop
+     */
     async sendRequest(qbwcUsername, requestObj) {
-        if (this.client.verbose) {
+        if (this.verbose) {
             console.log(`Client sent request for user ${qbwcUsername}:`, JSON.stringify(requestObj, null, 2));
         }
-        const response = await fetch("https://conductor.ngrok.io", {
+        const response = await fetch(SERVER_URL, {
             body: JSON.stringify({ qbwcUsername, requestObj }),
             headers: {
                 "Content-Type": "application/json",
-                Authorization: `Bearer ${this.client.apiKey}`,
+                Authorization: `Bearer ${this.apiKey}`,
             },
             method: "POST",
         });
         const responseObj = (await response.json());
-        if (this.client.verbose) {
+        if (this.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
+    /**
+     * Perform the same activities as a user does in the QB New Account form,
+     * which can be accessed in QB by selecting "Lists" → "Chart of Accounts" →
+     * "Accounts" → "New".
+     *
+     * https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/accountadd
+     */
     async accountAdd(qbwcUsername, params) {
         const response = (await this.sendRequest(qbwcUsername, {
             AccountAddRq: { AccountAdd: params },
@@ -35,12 +49,12 @@ class ClientQBD {
         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.
+     * `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
      */
@@ -55,7 +69,29 @@ class ClientQBD {
         return responseBody;
     }
     /**
-     * Adds an employee with personal data about the employee as well as certain payroll-related data.
+     * Returns data for the specified customers.
+     *
+     * Important: We highly recommend that you use the `IncludeRetElement` tag in
+     * your `CustomerQuery` to include any data you want but do NOT include the
+     * `ShipAddress` data in the `Response`, unless you need to get the shipping
+     * address for a particular customer. Excluding the shipping address data will
+     * significantly improve the performance of the `CustomerQuery`.
+     *
+     * https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/customerquery
+     */
+    async customerQuery(qbwcUsername, params) {
+        const response = (await this.sendRequest(qbwcUsername, {
+            CustomerQueryRq: params,
+        }));
+        const responseBody = response.CustomerQueryRs.CustomerRet;
+        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
      */
@@ -99,5 +135,20 @@ class ClientQBD {
         }
         return responseBody;
     }
+    /**
+     * Queries for the specified vendor or set of vendors.
+     *
+     * https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/vendorQuery
+     */
+    async vendorQuery(qbwcUsername, params) {
+        const response = (await this.sendRequest(qbwcUsername, {
+            VendorQueryRq: params,
+        }));
+        const responseBody = response.VendorQueryRs.VendorRet;
+        if (!responseBody) {
+            throw new Error("No response");
+        }
+        return responseBody;
+    }
 }
 exports.default = ClientQBD;

package/dist/qb/qbXMLTypes/Account.d.ts

@@ -1,4 +1,4 @@
-import type { ActiveStatus, DataExtRet, NameFilter, NameRangeFilter } from "../../qb/qbXMLTypes/shared";
+import type { ActiveStatus, CurrencyFilter, CurrencyRef, DataExtRet, NameFilter, NameRangeFilter, ParentRef, SalesTaxCodeRef } from "../../qb/qbXMLTypes/shared";
 export interface AccountAddRq {
     AccountAdd: AccountAdd;
     IncludeRetElement?: string;
@@ -238,22 +238,6 @@ export interface AccountRet {
     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;
-}
 declare type AccountType = "AccountsPayable" | "AccountsReceivable" | "Bank" | "CostOfGoodsSold" | "CreditCard" | "Equity" | "Expense" | "FixedAsset" | "Income" | "LongTermLiability" | "NonPosting" | "OtherAsset" | "OtherCurrentAsset" | "OtherCurrentLiability" | "OtherExpense" | "OtherIncome";
 declare type SpecialAccountType = "AccountsPayable" | "AccountsReceivable" | "CondenseItemAdjustmentExpenses" | "CostOfGoodsSold" | "DirectDepositLiabilities" | "Estimates" | "ExchangeGainLoss" | "InventoryAssets" | "ItemReceiptAccount" | "OpeningBalanceEquity" | "PayrollExpenses" | "PayrollLiabilities" | "PettyCash" | "PurchaseOrders" | "ReconciliationDifferences" | "RetainedEarnings" | "SalesOrders" | "SalesTaxPayable" | "UncategorizedExpenses" | "UncategorizedIncome" | "UndepositedFunds";
 declare type CashFlowClassification = "Financing" | "Investing" | "None" | "NotApplicable" | "Operating";

package/dist/qb/qbXMLTypes/Customer.d.ts

@@ -0,0 +1,152 @@
+import type { ActiveStatus, AdditionalContactRef, AdditionalNotesRet, ClassFilter, ClassRef, ContactsRet, CurrencyFilter, CurrencyRef, DataExtRet, NameFilter, NameRangeFilter, ParentRef, SalesTaxCodeRef, SalesTaxCountry, ShipAddress, TermsRef, TotalBalanceFilter } from "../../qb/qbXMLTypes/shared";
+export interface CustomerQueryRq {
+    ListID?: string;
+    FullName?: string;
+    MaxReturned?: number;
+    ActiveStatus?: ActiveStatus;
+    FromModifiedDate?: Date;
+    ToModifiedDate?: Date;
+    NameFilter?: NameFilter;
+    NameRangeFilter?: NameRangeFilter;
+    TotalBalanceFilter?: TotalBalanceFilter;
+    CurrencyFilter?: CurrencyFilter;
+    ClassFilter?: ClassFilter;
+    IncludeRetElement?: string;
+    OwnerID?: string;
+}
+export interface CustomerQueryRs {
+    CustomerRet?: CustomerRet;
+}
+export interface CustomerRet {
+    ListID: string;
+    TimeCreated: Date;
+    TimeModified: Date;
+    EditSequence: string;
+    Name: string;
+    FullName: string;
+    IsActive?: boolean;
+    ClassRef?: ClassRef;
+    ParentRef?: ParentRef;
+    Sublevel: number;
+    CompanyName?: string;
+    Salutation?: string;
+    FirstName?: string;
+    MiddleName?: string;
+    LastName?: string;
+    JobTitle?: string;
+    BillAddress?: BillAddress;
+    BillAddressBlock?: BillAddressBlock;
+    ShipAddress?: ShipAddress;
+    ShipAddressBlock?: ShipAddressBlock;
+    ShipToAddress?: ShipToAddress;
+    Phone?: string;
+    AltPhone?: string;
+    Fax?: string;
+    Email?: string;
+    Cc?: string;
+    Contact?: string;
+    AltContact?: string;
+    AdditionalContactRef?: AdditionalContactRef;
+    ContactsRet?: ContactsRet;
+    CustomerTypeRef?: CustomerTypeRef;
+    TermsRef?: TermsRef;
+    SalesRepRef?: SalesRepRef;
+    Balance?: string;
+    TotalBalance?: string;
+    SalesTaxCodeRef?: SalesTaxCodeRef;
+    ItemSalesTaxRef?: ItemSalesTaxRef;
+    SalesTaxCountry?: SalesTaxCountry;
+    ResaleNumber?: string;
+    AccountNumber?: string;
+    CreditLimit?: string;
+    PreferredPaymentMethodRef?: PreferredPaymentMethodRef;
+    CreditCardInfo?: CreditCardInfo;
+    JobStatus?: JobStatus;
+    JobStartDate?: Date;
+    JobProjectedEndDate?: Date;
+    JobEndDate?: Date;
+    JobDesc?: string;
+    JobTypeRef?: JobTypeRef;
+    Notes?: string;
+    AdditionalNotesRet?: AdditionalNotesRet;
+    PreferredDeliveryMethod?: PreferredDeliveryMethod;
+    PriceLevelRef?: PriceLevelRef;
+    ExternalGUID?: string;
+    TaxRegistrationNumber?: string;
+    CurrencyRef?: CurrencyRef;
+    DataExtRet?: DataExtRet;
+}
+interface BillAddress {
+    Addr1?: string;
+    Addr2?: string;
+    Addr3?: string;
+    Addr4?: string;
+    Addr5?: string;
+    City?: string;
+    State?: string;
+    PostalCode?: string;
+    Country?: string;
+    Note?: string;
+}
+interface BillAddressBlock {
+    Addr1?: string;
+    Addr2?: string;
+    Addr3?: string;
+    Addr4?: string;
+    Addr5?: string;
+}
+interface ShipAddressBlock {
+    Addr1?: string;
+    Addr2?: string;
+    Addr3?: string;
+    Addr4?: string;
+    Addr5?: string;
+}
+interface ShipToAddress {
+    Addr1?: string;
+    Addr2?: string;
+    Addr3?: string;
+    Addr4?: string;
+    Addr5?: string;
+    City?: string;
+    State?: string;
+    PostalCode?: string;
+    Country?: string;
+    Note?: string;
+    DefaultShipTo?: boolean;
+}
+interface CustomerTypeRef {
+    ListID?: string;
+    FullName?: string;
+}
+interface SalesRepRef {
+    ListID?: string;
+    FullName?: string;
+}
+interface ItemSalesTaxRef {
+    ListID?: string;
+    FullName?: string;
+}
+interface PreferredPaymentMethodRef {
+    ListID?: string;
+    FullName?: string;
+}
+interface CreditCardInfo {
+    CreditCardNumber?: string;
+    ExpirationMonth?: number;
+    ExpirationYear?: number;
+    NameOnCard?: string;
+    CreditCardAddress?: string;
+    CreditCardPostalCode?: string;
+}
+declare type JobStatus = "Awarded" | "Closed" | "InProgress" | "None" | "NotAwarded" | "Pending";
+interface JobTypeRef {
+    ListID?: string;
+    FullName?: string;
+}
+declare type PreferredDeliveryMethod = "Email" | "Fax" | "None";
+interface PriceLevelRef {
+    ListID?: string;
+    FullName?: string;
+}
+export {};

package/dist/qb/qbXMLTypes/Customer.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/qb/qbXMLTypes/Employee.d.ts

@@ -1,4 +1,4 @@
-import type { ActiveStatus, DataExtRet, NameFilter, NameRangeFilter } from "../../qb/qbXMLTypes/shared";
+import type { ActiveStatus, AdditionalContactRef, AdditionalNotesRet, BillingRateRef, ClassRef, DataExtRet, NameFilter, NameRangeFilter } from "../../qb/qbXMLTypes/shared";
 export interface EmployeeAddRq {
     EmployeeAdd: EmployeeAdd;
     IncludeRetElement?: string;
@@ -295,10 +295,6 @@ interface EmployeeAddress {
      */
     PostalCode?: string;
 }
-interface AdditionalContactRef {
-    ContactName: string;
-    ContactValue: string;
-}
 interface EmergencyContacts {
     PrimaryContact?: {
         ContactName: string;
@@ -326,26 +322,29 @@ declare type MilitaryStatus = "Active" | "Reserve";
 interface AdditionalNotes {
     Note: string;
 }
-interface AdditionalNotesRet {
-    NoteID: number;
-    Date: Date;
-    Note: string;
-}
 interface AdditionalNotesMod {
     NoteID: number;
     Note: string;
 }
-interface BillingRateRef {
-    ListID?: string;
-    FullName?: string;
-}
 interface EmployeePayrollInfo {
     PayPeriod?: PayPeriod;
     ClassRef?: ClassRef;
     ClearEarnings?: boolean;
     Earnings?: Earnings;
+    /**
+     * Indicates whether or not paychecks are generated from time-tracking data.
+     * If you include a blank `IsUsingTimeDataToCreatePaychecks` element in an
+     * `EmployeeMod` message, you’ll receive an error.
+     */
     IsUsingTimeDataToCreatePaychecks?: boolean;
+    /**
+     * Indicates whether time data is used to create paychecks for this employee.
+     */
     UseTimeDataToCreatePaychecks?: UseTimeDataToCreatePaychecks;
+    /**
+     * Describes how “sick time” is accrued for this employee, along with how many
+     * sick hours the employee has accrued.
+     */
     SickHours?: SickHours;
     VacationHours?: VacationHours;
 }
@@ -360,10 +359,6 @@ interface EmployeePayrollInfoMod {
     VacationHours?: VacationHours;
 }
 declare type PayPeriod = "Biweekly" | "Daily" | "Monthly" | "Quarterly" | "Semimonthly" | "Weekly" | "Yearly";
-interface ClassRef {
-    ListID?: string;
-    FullName?: string;
-}
 interface Earnings {
     PayrollItemWageRef?: PayrollItemWageRef;
     Rate?: string;
@@ -375,12 +370,47 @@ interface PayrollItemWageRef {
 }
 declare type UseTimeDataToCreatePaychecks = "DoNotUseTimeData" | "NotSet" | "UseTimeData";
 interface SickHours {
+    /**
+     * The total number of hours currently available for the employee to use. If
+     * this value is empty, it will default to 0.
+     */
     HoursAvailable?: string;
+    /**
+     * Indicates how an employee accrues time off. If you include a blank
+     * `AccrualPeriod` element in an `EmployeeMod` message, you’ll receive an
+     * error. The default value is whatever the QuickBooks user has set in the
+     * QuickBooks Employee Preferences.
+     */
     AccrualPeriod?: AccrualPeriod;
+    /**
+     * The number of hours that the employee will accrue per accrual period. The
+     * default value is whatever the QuickBooks user has set in the QuickBooks
+     * Employee Preferences.
+     */
     HoursAccrued?: string;
+    /**
+     * The maximum number of hours that the employee can accrue. (QuickBooks
+     * itself does not enforce this limit, however. HoursAvailable can be greater
+     * than MaximumHours.) The default value is whatever the QuickBooks user has
+     * set in the QuickBooks Employee Preferences.
+     */
     MaximumHours?: string;
+    /**
+     * Indicates whether or not the hours accrued resets to zero at the beginning
+     * of the new year. If you include a blank `IsResettingHoursEachNewYear`
+     * element in an `EmployeeMod` message, you’ll receive an error.
+     */
     IsResettingHoursEachNewYear?: boolean;
+    /**
+     * When used in the `SickHours` or `VacationHours` aggregates, refers to the
+     * number of sick leave or vacation hours used in the current year.
+     */
     HoursUsed?: string;
+    /**
+     * When used in the `SickHours` or `VacationHours` aggregates, refers to the
+     * date on which sick leave or vacation hours in the current year began to
+     * accrue.
+     */
     AccrualStartDate?: Date;
 }
 declare type AccrualPeriod = "BeginningOfYear" | "EveryHourOnPaycheck" | "EveryPaycheck";