### Start Example App

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Start the Express application to initiate the OAuth workflow.

```bash
node app.js
```

--------------------------------

### Install Dependencies

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Navigate to the example directory and install required NPM dependencies.

```bash
npm install
```

--------------------------------

### Multi-Tenant Setup

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

Example demonstrating how to manage multiple QuickBooks clients for different users or companies, creating a new client only if it doesn't exist.

```javascript
// Create separate client per user/company
const clients = {};

function getClient(userId, credentials) {
  if (!clients[userId]) {
    clients[userId] = new QuickBooks(
      credentials.consumerKey,
      credentials.consumerSecret,
      credentials.token,
      credentials.tokenSecret,
      credentials.realmId,
      false,  // production
      false,
      null,
      '1.0a'
    );
  }
  return clients[userId];
}

const userClient = getClient('user123', userCredentials);
```

--------------------------------

### Install Node-Quickbooks

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/README.md

Install the node-quickbooks library using npm. This is the first step to integrating QuickBooks with your Node.js application.

```bash
npm install node-quickbooks
```

--------------------------------

### Create Invoice Example

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/crud-operations.md

This example demonstrates how to create a new invoice. It requires a CustomerRef, line items with details like ItemRef and Amount, and transaction dates.

```javascript
qbo.createInvoice({
  CustomerRef: { value: '5' },
  Line: [
    {
      Amount: 100,
      DetailType: 'SalesItemLineDetail',
      SalesItemLineDetail: {
        ItemRef: { value: '1' },
        UnitPrice: 100,
        Qty: 1
      }
    }
  ],
  TxnDate: '2024-01-15',
  DueDate: '2024-02-15'
}, function(err, invoice) {
  if (err) console.error(err);
  else console.log('Invoice created:', invoice.DocNumber);
});
```

--------------------------------

### Development Configuration

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

Configuration example for a development environment, specifying sandbox mode and enabling debug logging.

```javascript
const qbo = new QuickBooks(
  'dev_consumer_key',
  'dev_consumer_secret',
  'dev_oauth_token',
  'dev_oauth_token_secret',
  'dev_realm_id_123456',
  true,   // sandbox
  true,   // debug logging
  null,
  '1.0a'
);
```

--------------------------------

### Ref Example Usage

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/types.md

Illustrates how to use the Ref interface to link entities, such as associating a customer and an item with a transaction.

```javascript
{
  CustomerRef: { value: '5', name: 'Acme Corp' },
  ItemRef: { value: '1', name: 'Service' }
}
```

--------------------------------

### Production Configuration

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

Configuration example for a production environment, disabling sandbox and debug logging, and using environment variables for credentials.

```javascript
const qbo = new QuickBooks(
  process.env.CONSUMER_KEY,
  process.env.CONSUMER_SECRET,
  process.env.OAUTH_TOKEN,
  process.env.OAUTH_TOKEN_SECRET,
  process.env.REALM_ID,
  false,  // production
  false,  // no debug logging
  75,
  '1.0a'
);
```

--------------------------------

### Minimal OAuth 2.0 Setup

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

This snippet shows the minimum configuration required for OAuth 2.0 using environment variables for sensitive credentials.

```javascript
const QuickBooks = require('node-quickbooks');

const qbo = new QuickBooks(
  process.env.CLIENT_ID,
  process.env.CLIENT_SECRET,
  process.env.ACCESS_TOKEN,
  false,
  process.env.REALM_ID,
  process.env.NODE_ENV === 'production' ? false : true,
  process.env.DEBUG === 'true',
  null,
  '2.0',
  process.env.REFRESH_TOKEN
);
```

--------------------------------

### Create Customer Example

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/crud-operations.md

Use this to create a new customer record in QuickBooks. Ensure all required fields like DisplayName, CompanyName, and contact information are provided.

```javascript
qbo.createCustomer({
  DisplayName: 'John Smith',
  CompanyName: 'Acme Inc',
  GivenName: 'John',
  FamilyName: 'Smith',
  Email: { Address: 'john@acme.com' }
}, function(err, customer) {
  if (err) console.error(err);
  else console.log('Created customer ID:', customer.Id);
});
```

--------------------------------

### EntityResponse Example Usage

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/types.md

Provides an example of an EntityResponse for a customer, including the customer details and the response timestamp.

```javascript
{
  Customer: {
    Id: '5',
    DisplayName: 'Acme Corp',
    CompanyName: 'Acme Corporation'
  },
  time: '2024-01-15T10:30:00Z'
}
```

--------------------------------

### Get Preferences Example

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/crud-operations.md

Fetch company preferences. This operation is a special case as it does not require an ID parameter.

```typescript
getPreferences(callback: QuickBooksCallback<EntityResponse<Preferences>>): void
```

```javascript
qbo.getPreferences(function(err, prefs) {
  if (err) console.error(err);
  else console.log('Company preferences:', prefs);
});
```

--------------------------------

### Get Invoice Example

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/crud-operations.md

Retrieve an existing invoice by its ID. The callback function receives the invoice details, including the TotalAmt.

```javascript
qbo.getInvoice('123', function(err, invoice) {
  if (err) console.error(err);
  else console.log('Invoice total:', invoice.TotalAmt);
});
```

--------------------------------

### Read (Get) Operation

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/crud-operations.md

All get methods follow the pattern: `get<Entity>(id: string, callback: QuickBooksCallback<EntityResponse<Entity>>): void`. This method is used to retrieve a specific entity by its ID.

```APIDOC
## Read (Get) Operation

### Description
Used to retrieve a specific entity from QuickBooks by its unique identifier.

### Method Signature
```typescript
get<Entity>(id: string, callback: QuickBooksCallback<EntityResponse<Entity>>): void
```

### Parameters
#### ID
- **id** (string) - Required - The QuickBooks entity ID of the item to retrieve.

#### Callback Function
- **callback** (function) - Required - A function that will be called with the result, providing `(err, entity)`.

### Return Type
`EntityResponse<Entity>` - An object containing the retrieved entity.

### Examples
**Get Invoice**
```javascript
qbo.getInvoice('123', function(err, invoice) {
  if (err) console.error(err);
  else console.log('Invoice total:', invoice.TotalAmt);
});
```

**Get Preferences (Special Case)**
This method does not require an ID parameter.

### Method Signature
```typescript
getPreferences(callback: QuickBooksCallback<EntityResponse<Preferences>>): void
```

### Example
```javascript
qbo.getPreferences(function(err, prefs) {
  if (err) console.error(err);
  else console.log('Company preferences:', prefs);
});
```
```

--------------------------------

### Example API Fault Error: ValidationFault

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/errors.md

A concrete example of a ValidationFault, showing a 'Duplicate Name' error with details on the message, code, and the element causing the issue.

```javascript
{
  fault: {
    type: 'ValidationFault',
    error: [
      {
        Message: 'Duplicate Name',
        Detail: 'The name of the object is already in use. You must specify a unique name.',
        code: '6000',
        element: 'DisplayName'
      }
    ]
  }
}
```

--------------------------------

### QueryResponse Example Usage

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/types.md

Shows a typical response structure for a query, containing a list of customers, pagination information, and the time of the response.

```javascript
{
  QueryResponse: {
    Customer: [
      { Id: '5', DisplayName: 'Acme Corp' },
      { Id: '6', DisplayName: 'Widget Inc' }
    ],
    maxResults: 2,
    startPosition: 1
  },
  time: '2024-01-15T10:30:00Z'
}
```

--------------------------------

### Create and Email Invoice

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/00_START_HERE.md

This example demonstrates how to create an invoice with specified customer and line item details, and then send it as a PDF to the customer's email address. Ensure you have a valid QuickBooks Online connection object (qbo) initialized.

```javascript
qbo.createInvoice({
  CustomerRef: { value: '5' },
  Line: [{
    Amount: 100,
    DetailType: 'SalesItemLineDetail',
    SalesItemLineDetail: { ItemRef: { value: '1' }, Qty: 1 }
  }],
  BillEmail: { Address: 'customer@acme.com' }
}, (err, invoice) => {
  if (err) return console.error(err);
  qbo.sendInvoicePdf(invoice.Id, (err) => {
    if (err) return console.error(err);
    console.log('Invoice sent');
  });
});
```

--------------------------------

### List-style Report Response Structure Example

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Demonstrates the JSON format for list-style reports, detailing column definitions and row data.

```json
{
  reportName: 'TransactionList',
  columns: [
    { colTitle: 'Date', colType: 'date' },
    { colTitle: 'Type', colType: 'text' },
    { colTitle: 'Num', colType: 'text' },
    ...
  ],
  rows: [
    {
      colData: [
        { value: '2024-01-15' },
        { value: 'Invoice' },
        ...
      ]
    }
  ]
}
```

--------------------------------

### Generate Monthly Financial Reports

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Example of generating multiple monthly financial reports including Balance Sheet, Profit and Loss, Aged Receivables, and Aged Payables. Requires specifying start and end dates and accounting method.

```javascript
// Generate monthly financial reports
const reportOptions = {
  start_date: '2024-01-01',
  end_date: '2024-01-31',
  accounting_method: 'Accrual'
};

qbo.reportBalanceSheet(reportOptions, function(err, bs) {
  if (err) console.error('Balance Sheet error:', err);
  else console.log('Balance Sheet:', bs);
});

qbo.reportProfitAndLoss(reportOptions, function(err, pl) {
  if (err) console.error('P&L error:', err);
  else console.log('P&L Report:', pl);
});

qbo.reportAgedReceivables(reportOptions, function(err, ar) {
  if (err) console.error('AR error:', err);
  else console.log('Aged Receivables:', ar);
});

qbo.reportAgedPayables(reportOptions, function(err, ap) {
  if (err) console.error('AP error:', err);
  else console.log('Aged Payables:', ap);
});
```

--------------------------------

### Query Invoices with Pagination using Node-QuickBooks

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/README.md

Shows how to retrieve a list of invoices for a specific customer, applying sorting and pagination with limit and offset parameters. The response includes the queried invoices and the starting position of the results.

```javascript
qbo.findInvoices({
  CustomerRef: { value: '5' },
  desc: 'TxnDate',
  limit: 25,
  offset: 0
}, function(err, results) {
  if (err) return console.error(err);
  console.log('Invoices:', results.QueryResponse.Invoice);
  console.log('Position:', results.QueryResponse.startPosition);
});
```

--------------------------------

### Simple Report Response Structure Example

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Illustrates the JSON structure for simple report types, including report name, headers, columns, and nested rows.

```json
{
  reportName: 'BalanceSheet',
  headers: [...],
  columns: [...],
  rows: [
    {
      header: 'Assets',
      type: 'Group',
      rows: [...] 
    },
    ...
  ],
  startPeriod: '2024-01-31',
  currency: 'USD'
}
```

--------------------------------

### Get Trial Balance Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves the Trial Balance report, listing all general ledger accounts with their debit/credit balances. Filter by end date.

```javascript
qbo.reportTrialBalance({
  end_date: '2024-01-31'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('Trial Balance:', report);
});
```

--------------------------------

### Find Attachables with Pagination

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Paginate query results by specifying 'limit' and 'offset' values. This controls the number of records returned and their starting point.

```javascript
qbo.findAttachables({
  limit: 10,
  offset: 10
}, function(e, attachables) {
  console.log(attachables)
})
```

--------------------------------

### Generate Inventory Valuation Summary Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Use this method to get a summary of inventory items, quantities, and their total valuation. It accepts optional report options and a callback function.

```javascript
qbo.reportInventoryValuationSummary(function(err, report) {
  if (err) console.error(err);
  else console.log('Inventory Valuation:', report);
});
```

--------------------------------

### Get Profit and Loss Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves the Profit and Loss (P&L) report for a specified period. Provide start and end dates.

```javascript
qbo.reportProfitAndLoss({
  start_date: '2024-01-01',
  end_date: '2024-01-31'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('P&L Report:', report);
});
```

--------------------------------

### Initialize QuickBooks Client with Environment Variables

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

Instantiates the QuickBooks client using environment variables for authentication and configuration. Supports both OAuth 2.0 and OAuth 1.0a.

```javascript
const QuickBooks = require('node-quickbooks');

const qbo = new QuickBooks(
  process.env.CLIENT_ID || process.env.CONSUMER_KEY,
  process.env.CLIENT_SECRET || process.env.CONSUMER_SECRET,
  process.env.ACCESS_TOKEN || process.env.OAUTH_TOKEN,
  process.env.OAUTH_TOKEN_SECRET || false,
  process.env.REALM_ID,
  process.env.SANDBOX === 'true',
  process.env.DEBUG === 'true',
  process.env.MINOR_VERSION || null,
  process.env.OAUTH_VERSION || '2.0',
  process.env.REFRESH_TOKEN || null
);
```

--------------------------------

### Get Cash Flow Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves the Cash Flow report, showing cash movements from operations, investing, and financing. Provide the start and end dates.

```javascript
qbo.reportCashFlow({
  start_date: '2024-01-01',
  end_date: '2024-01-31'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('Cash Flow Report:', report);
});
```

--------------------------------

### Initialize QuickBooks Client

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Instantiate the QuickBooks client with your API credentials and configuration. Ensure correct OAuth version and sandbox settings are used.

```javascript
var QuickBooks = require('node-quickbooks')

var qbo = new QuickBooks(consumerKey,
                         consumerSecret,
                         oauthToken,
                         false, // no token secret for oAuth 2.0
                         realmId,
                         false, // use the sandbox?
                         true, // enable debugging?
                         null, // set minorversion, or null for the latest version
                         '2.0', //oAuth version
                         refreshToken);
```

--------------------------------

### QuickBooks Client Constructor Parameters

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

Defines the parameters for initializing the QuickBooks client. These include authentication credentials, company ID, sandbox usage, and optional debugging and API version settings.

```typescript
new QuickBooks(
  consumerKey: string,
  consumerSecret: string,
  oauthToken: string,
  oauthTokenSecret: string | false,
  realmId: string,
  useSandbox: boolean,
  debug?: boolean,
  minorversion?: string | null,
  oauthversion?: string,
  refreshToken?: string | null
)
```

--------------------------------

### Get Bill Payment

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Retrieves a specific bill payment by its ID.

```APIDOC
## GET /billpayment/{id}

### Description
Retrieves a specific bill payment.

### Method
GET

### Endpoint
/billpayment/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the bill payment to retrieve.

### Response
#### Success Response (200)
- **billPayment** (object) - The retrieved bill payment object.

#### Response Example
```json
{
  "Id": "42",
  "Amount": 100.00
}
```
```

--------------------------------

### Create and Send Invoice with Node-QuickBooks

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/README.md

Demonstrates how to create a new invoice with specified details and then send it as a PDF to the customer. Ensure the customer and item references are valid.

```javascript
qbo.createInvoice({
  CustomerRef: { value: '5' },
  Line: [{
    Amount: 100,
    DetailType: 'SalesItemLineDetail',
    SalesItemLineDetail: {
      ItemRef: { value: '1' },
      UnitPrice: 100,
      Qty: 1
    }
  }],
  BillEmail: { Address: 'customer@acme.com' }
}, function(err, invoice) {
  if (err) return console.error(err);
  
  // Send invoice
  qbo.sendInvoicePdf(invoice.Id, function(err) {
    if (err) return console.error(err);
    console.log('Invoice sent');
  });
});
```

--------------------------------

### Get Vendor Balance Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves the current balance owed to each vendor. No specific options are required.

```javascript
qbo.reportVendorBalance(function(err, report) {
  if (err) console.error(err);
  else console.log('Vendor Balances:', report);
});
```

--------------------------------

### Initialize QuickBooks Client with OAuth 2.0

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/quickbooks-client.md

Instantiate the QuickBooks client for OAuth 2.0 authentication. Ensure you replace placeholders with your actual credentials and tokens.

```javascript
const QuickBooks = require('node-quickbooks');

const qbo = new QuickBooks(
  'your_client_id',
  'your_client_secret',
  'access_token_from_oauth',
  false,                    // no token secret for OAuth 2.0
  'company_id',
  true,                     // use sandbox
  true,                     // enable debug logging
  null,                     // use latest minor version
  '2.0',                    // OAuth 2.0
  'refresh_token'
);
```

--------------------------------

### Initialize QuickBooks Client with OAuth 1.0a

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/quickbooks-client.md

Instantiate the QuickBooks client for OAuth 1.0a authentication. This requires consumer keys, tokens, and realm ID.

```javascript
const qbo = new QuickBooks(
  'consumer_key',
  'consumer_secret',
  'oauth_token',
  'oauth_token_secret',
  'realm_id',
  false,                    // production
  false,                    // no debug logging
  75
);
```

--------------------------------

### ReportOptions Interface

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/types.md

Defines options for report generation, including start date, end date, and accounting method.

```typescript
interface ReportOptions {
  start_date?: string;
  end_date?: string;
  accounting_method?: string;
  [key: string]: any;
}
```

--------------------------------

### QuickBooks Constructor

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/quickbooks-client.md

Initializes a new instance of the QuickBooks client. This constructor requires several authentication and configuration parameters to establish a connection with the QuickBooks API.

```APIDOC
## new QuickBooks()

### Description
Initializes a new instance of the QuickBooks client class.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
```typescript
new QuickBooks(
  consumerKey: string,
  consumerSecret: string,
  oauthToken: string,
  oauthTokenSecret: string | false,
  realmId: string,
  useSandbox: boolean,
  debug?: boolean,
  minorversion?: string | null,
  oauthversion?: string,
  refreshToken?: string | null
)
```

### Parameters Table
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| consumerKey | string | Yes | — | Application consumer key from Intuit Developer Portal |
| consumerSecret | string | Yes | — | Application consumer secret from Intuit Developer Portal |
| oauthToken | string | Yes | — | User-specific OAuth token obtained during authentication |
| oauthTokenSecret | string \| false | Yes | — | User-specific OAuth token secret; set to `false` for OAuth 2.0 |
| realmId | string | Yes | — | QuickBooks company ID (realm ID) |
| useSandbox | boolean | Yes | — | Whether to use sandbox environment for testing |
| debug | boolean | No | false | Enable HTTP request/response logging to console |
| minorversion | string \| null | No | 75 | API minor version number; use null for latest |
| oauthversion | string | No | '1.0a' | OAuth version to use: '1.0a' or '2.0' |
| refreshToken | string \| null | No | null | OAuth 2.0 refresh token for token renewal |

### Instance Properties
| Property | Type | Description |
|---|---|---|
| consumerKey | string | Application consumer key |
| consumerSecret | string | Application consumer secret |
| token | string | Current OAuth token |
| tokenSecret | string \| false | Current OAuth token secret |
| realmId | string | Company ID |
| useSandbox | boolean | Sandbox environment flag |
| debug | boolean | Debug logging flag |
| minorversion | number \| string | API minor version |
| oauthversion | string | OAuth version in use |
| refreshToken | string \| null | Current refresh token |
| endpoint | string | API endpoint URL |

### Static Properties
| Property | Type | Value |
|---|---|---|
| APP_CENTER_BASE | string | 'https://appcenter.intuit.com' |
| V3_ENDPOINT_BASE_URL | string | 'https://sandbox-quickbooks.api.intuit.com/v3/company/' |
| QUERY_OPERATORS | string[] | ['=', 'IN', '<', '>', '<=', '>=', 'LIKE'] |
| TOKEN_URL | string | 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer' |
| REVOKE_URL | string | 'https://developer.api.intuit.com/v2/oauth2/tokens/revoke' |
```

--------------------------------

### Environment Variables for Configuration

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

Recommended environment variables for OAuth 2.0, OAuth 1.0a, and general app configuration. These should be set before initializing the QuickBooks client.

```bash
# OAuth 2.0
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
ACCESS_TOKEN=your_access_token
REFRESH_TOKEN=your_refresh_token
REALM_ID=1234567890

# OAuth 1.0a
CONSUMER_KEY=your_consumer_key
CONSUMER_SECRET=your_consumer_secret
OAUTH_TOKEN=your_oauth_token
OAUTH_TOKEN_SECRET=your_oauth_token_secret

# App Config
NODE_ENV=development
DEBUG=false
SANDBOX=true
MINOR_VERSION=75
```

--------------------------------

### Get Balance Sheet Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves the Balance Sheet report. Specify the end date and accounting method for filtering.

```javascript
qbo.reportBalanceSheet({
  end_date: '2024-01-31',
  accounting_method: 'Accrual'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('Balance Sheet:', report);
});
```

--------------------------------

### Get User Info

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/quickbooks-client.md

Retrieves authorized user information from the OAuth provider. The callback receives an error or the user information.

```typescript
getUserInfo(callback: QuickBooksCallback<any>): void
```

--------------------------------

### Configure QuickBooks API for Sandbox Environment

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

Use this configuration when testing your integration. Set the `useSandbox` parameter to `true`.

```javascript
const qbo = new QuickBooks(
  consumerKey,
  consumerSecret,
  token,
  tokenSecret,
  realmId,
  true,  // useSandbox = true
  false,  // debug = false
  null,
  '2.0',
  refreshToken
);
```

--------------------------------

### Configure QuickBooks API for Production Environment

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

Use this configuration for live transactions. Set the `useSandbox` parameter to `false` and ensure you have production OAuth credentials.

```javascript
const qbo = new QuickBooks(
  consumerKey,
  consumerSecret,
  token,
  tokenSecret,
  realmId,
  false,  // useSandbox = false
  false,  // debug = false
  null,
  '2.0',
  refreshToken
);
```

--------------------------------

### Get Bill Payment

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Retrieve a specific bill payment by its ID. The callback function receives the bill payment object or an error.

```javascript
qbo.getBillPayment('42', function(err, billPayment) {
  console.log(billPayment)
})
```

--------------------------------

### Perform Batch Operations with Node-QuickBooks

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/README.md

Demonstrates how to execute multiple operations (create, query) in a single batch request. Each operation in the batch is identified by a unique 'bId'.

```javascript
qbo.batch([
  {
    bId: '1',
    operation: 'create',
    Name: 'New Account'
  },
  {
    bId: '2',
    operation: 'query',
    Query: 'SELECT * FROM Customer LIMIT 10'
  }
], function(err, results) {
  if (err) return console.error(err);
  results.forEach(r => console.log(r));
});
```

--------------------------------

### Get Vendor Balance Detail Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves detailed vendor balances including transaction-level information. No specific options are required.

```javascript
qbo.reportVendorBalanceDetail(function(err, report) {
  if (err) console.error(err);
  else console.log('Vendor Balance Detail:', report);
});
```

--------------------------------

### createCustomer

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Creates a new Customer in QuickBooks. Requires an object representing the unsaved customer and a callback function.

```APIDOC
## createCustomer(object, callback)

### Description
Creates the Customer in QuickBooks.

### Parameters
- `object` (object) - Required - The unsaved customer, to be persisted in QuickBooks.
- `callback` (function) - Required - Callback function which is called with any error and the persistent Customer.
```

--------------------------------

### Get Customer Balance Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves a summary of the current balance owed by each customer. No specific options are required for a basic report.

```javascript
qbo.reportCustomerBalance(function(err, report) {
  if (err) console.error(err);
  else console.log('Customer Balances:', report);
});
```

--------------------------------

### Execute QBQL Query

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/quickbooks-client.md

Use this method to run raw QuickBooks Query Language (QBQL) queries against your QuickBooks data. Provide the query string and a callback function to handle the response or errors.

```typescript
query(query: string, callback: QuickBooksCallback<any>): void
```

```javascript
qbo.query('SELECT * FROM Customer WHERE Active = true', function(err, result) {
  if (err) console.error(err);
  else console.log(result.QueryResponse);
});
```

--------------------------------

### OAuth 2.0 Client Initialization

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

Initializes the QuickBooks client using OAuth 2.0. Note that `oauthTokenSecret` must be set to `false`. The `refreshToken` parameter is crucial for obtaining new access tokens.

```javascript
const QuickBooks = require('node-quickbooks');

const qbo = new QuickBooks(
  'your_client_id',
  'your_client_secret',
  'access_token_from_oauth',
  false,
  'company_realm_id',
  true,
  false,
  null,
  '2.0',
  'refresh_token_from_oauth'
);
```

--------------------------------

### Generate Class Sales Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Use this method to retrieve sales revenue by class for a specified period. Requires start and end dates.

```javascript
qbo.reportClassSales({
  start_date: '2024-01-01',
  end_date: '2024-01-31'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('Class Sales:', report);
});
```

--------------------------------

### OAuth 2.0 Initialization

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/README.md

Initialize the QuickBooks client with your credentials for OAuth 2.0 authentication. Ensure you replace placeholders with your actual client ID, secret, access token, and realm ID.

```javascript
const QuickBooks = require('node-quickbooks');

const qbo = new QuickBooks(
  'your_client_id',
  'your_client_secret',
  'access_token',
  false,                    // false for OAuth 2.0
  'realm_id',
  true,                     // use sandbox
  false,                    // no debug
  null,                     // use latest API version
  '2.0',                    // OAuth 2.0
  'refresh_token'
);
```

--------------------------------

### Access and Modify Instance Properties

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

Demonstrates how to read client configuration properties and update tokens or sandbox mode after initialization. The endpoint is automatically updated when sandbox mode changes.

```javascript
const qbo = new QuickBooks(/* ... */);

// Read properties
console.log(qbo.consumerKey);
console.log(qbo.realmId);
console.log(qbo.useSandbox);
console.log(qbo.minorversion);
console.log(qbo.oauthversion);
console.log(qbo.endpoint);  // Full API endpoint URL

// Modify tokens after refresh
qbo.token = newAccessToken;
qbo.refreshToken = newRefreshToken;

// Update sandbox mode
qbo.useSandbox = false;
qbo.endpoint = qbo.useSandbox 
  ? 'https://sandbox-quickbooks.api.intuit.com/v3/company/'
  : 'https://quickbooks.api.intuit.com/v3/company/';

```

--------------------------------

### Initiate OAuth Reconnection

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/quickbooks-client.md

Call this method to start the OAuth reconnection flow when a connection has expired. A callback function is provided to handle the result.

```typescript
reconnect(callback: QuickBooksCallback<any>): void
```

--------------------------------

### Find All Customers

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/crud-operations.md

Retrieves all customer records. Ensure the QuickBooks client is initialized before use.

```javascript
qbo.findCustomers(function(err, customers) {
  if (err) console.error(err);
  else console.log('Customers:', customers.QueryResponse.Customer);
});
```

--------------------------------

### Get Balance Sheet Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Generate a balance sheet report, optionally filtering by department ID. The report data is returned in the callback.

```javascript
qbo.reportBalanceSheet({department: '1,4,7'}, function(err, balanceSheet) {
  console.log(balanceSheet)
})
```

--------------------------------

### OAuth 1.0a Client Initialization

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

Initializes the QuickBooks client using OAuth 1.0a. Ensure all parameters, including user-specific tokens and realm ID, are correctly provided. Debugging and API minor version can be specified.

```javascript
const QuickBooks = require('node-quickbooks');

const qbo = new QuickBooks(
  'your_consumer_key',
  'your_consumer_secret',
  'oauth_token_from_user',
  'oauth_token_secret_from_user',
  'company_realm_id',
  true,
  true,
  75,
  '1.0a',
  null
);
```

--------------------------------

### Retrieve Invoice PDF

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/pdf-and-email.md

Use this method to get the PDF data for a specific invoice. The callback receives error information or the PDF data.

```javascript
qbo.getInvoicePdf('123', function(err, pdf) {
  if (err) console.error(err);
  else console.log('PDF data received, size:', pdf.length);
});
```

--------------------------------

### Count Attachables

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Get the total count of attachable records matching the query criteria instead of the full data set. Set `count: true`.

```javascript
qbo.findAttachables({
  count: true
}, function(e, attachables) {
  console.log(attachables)
})
```

--------------------------------

### Create Operation

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/crud-operations.md

All create methods follow a consistent pattern: `create<Entity>(entity: Entity, callback: QuickBooksCallback<EntityResponse<Entity>>): void`. This method is used to create new entities in QuickBooks.

```APIDOC
## Create Operation

### Description
Used to create new entities in QuickBooks.

### Method Signature
```typescript
create<Entity>(entity: Entity, callback: QuickBooksCallback<EntityResponse<Entity>>): void
```

### Parameters
#### Entity Object
- **entity** (Entity) - Required - Object containing entity fields. For new entities, 'Id' and 'SyncToken' should not be included.

#### Callback Function
- **callback** (function) - Required - A function that will be called with the result, providing `(err, response)`.

### Return Type
`EntityResponse<Entity>` - An object containing the created entity, including its assigned 'Id' and 'SyncToken'.

### Examples
**Create Customer**
```javascript
qbo.createCustomer({
  DisplayName: 'John Smith',
  CompanyName: 'Acme Inc',
  GivenName: 'John',
  FamilyName: 'Smith',
  Email: { Address: 'john@acme.com' }
}, function(err, customer) {
  if (err) console.error(err);
  else console.log('Created customer ID:', customer.Id);
});
```

**Create Invoice**
```javascript
qbo.createInvoice({
  CustomerRef: { value: '5' },
  Line: [
    {
      Amount: 100,
      DetailType: 'SalesItemLineDetail',
      SalesItemLineDetail: {
        ItemRef: { value: '1' },
        UnitPrice: 100,
        Qty: 1
      }
    }
  ],
  TxnDate: '2024-01-15',
  DueDate: '2024-02-15'
}, function(err, invoice) {
  if (err) console.error(err);
  else console.log('Invoice created:', invoice.DocNumber);
});
```
```

--------------------------------

### Get Aged Payables Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves amounts owed to vendors, grouped by the age of the bill. Specify an 'end_date' option to filter by a specific date.

```javascript
qbo.reportAgedPayables({
  end_date: '2024-01-31'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('Aged Payables:', report);
});
```

--------------------------------

### Create and Retrieve Entity

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Use this pattern to create a new entity and then immediately retrieve it using its ID. Ensure the entity type is correctly specified.

```javascript
qbo.create<Entity>(data, (err, created) => {
  qbo.get<Entity>(created.Id, (err, entity) => {
    console.log(entity);
  });
});
```

--------------------------------

### Get Profit and Loss Detail Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves a detailed Profit and Loss report with account-level breakdowns. Specify the date range and accounting method.

```javascript
qbo.reportProfitAndLossDetail({
  start_date: '2024-01-01',
  end_date: '2024-12-31',
  accounting_method: 'Cash'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('P&L Detail:', report);
});
```

--------------------------------

### Delete Invoice with ID Only

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/crud-operations.md

Delete an invoice using only its ID. The library will perform an additional GET request to fetch the entity's SyncToken before deletion.

```javascript
// Library will fetch entity first (extra request)
qbo.deleteInvoice('123', function(err, result) {
  if (err) console.error(err);
  else console.log('Invoice deleted');
});
```

--------------------------------

### Fetch All Results (No Pagination)

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/crud-operations.md

Retrieves all customer records without applying pagination limits. Use 'fetchAll: true' for this purpose.

```javascript
qbo.findCustomers({
  fetchAll: true
}, function(err, results) {
  if (err) console.error(err);
  else console.log('Total customers:', results.QueryResponse.Customer.length);
});
```

--------------------------------

### Create and Send Purchase Order

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/pdf-and-email.md

Creates a purchase order and then sends it to a specified vendor email address. Requires vendor and item references, and line item details.

```javascript
// 1. Create purchase order
qbo.createPurchaseOrder({
  VendorRef: { value: '10' },
  POEmail: { Address: 'orders@supplier.com' },
  Line: [
    {
      Amount: 500,
      DetailType: 'ItemBasedExpenseLineDetail',
      ItemBasedExpenseLineDetail: {
        ItemRef: { value: '2' },
        UnitPrice: 500,
        Qty: 1
      }
    }
  ],
  TxnDate: '2024-01-15'
}, function(err, po) {
  if (err) {
    console.error('Failed to create PO:', err);
    return;
  }
  
  console.log('PO created:', po.DocNumber);
  
  // 2. Send PO email
  qbo.sendPurchaseOrder(po.Id, function(err, response) {
    if (err) {
      console.error('Failed to send PO:', err);
    } else {
      console.log('PO sent to vendor');
    }
  });
});
```

--------------------------------

### Configure Intuit.ejs Grant URL

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Set the 'grantUrl' option in intuit.ejs to your application's request token endpoint. This example uses 'http://localhost:3000/requestToken'.

```javascript
grantUrl: "http://localhost:3000/requestToken"
```

--------------------------------

### reportCashFlow

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves the Cash Flow report, showing cash inflows and outflows from operations, investing, and financing activities. Supports filtering by start and end dates.

```APIDOC
## reportCashFlow

### Description
Report showing cash inflows and outflows from operations, investing, and financing activities.

### Method Signature
```typescript
reportCashFlow(options?: ReportOptions, callback?: QuickBooksCallback<any>): void
```

### Parameters
- **options** (ReportOptions) - Optional report-specific options and filters.
- **callback** (function) - Called with (err, reportData).

### Request Example
```javascript
qbo.reportCashFlow({
  start_date: '2024-01-01',
  end_date: '2024-01-31'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('Cash Flow Report:', report);
});
```
```

--------------------------------

### createCreditMemo

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Creates a new CreditMemo in QuickBooks. Requires an object representing the unsaved creditMemo and a callback function.

```APIDOC
## createCreditMemo(object, callback)

### Description
Creates the CreditMemo in QuickBooks.

### Parameters
- `object` (object) - Required - The unsaved creditMemo, to be persisted in QuickBooks.
- `callback` (function) - Required - Callback function which is called with any error and the persistent CreditMemo.
```

--------------------------------

### reportProfitAndLossDetail

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves a detailed Profit and Loss (P&L) report with account-level breakdowns. Supports filtering by start date, end date, and accounting method.

```APIDOC
## reportProfitAndLossDetail

### Description
Detailed P&L report with account-level breakdowns.

### Method Signature
```typescript
reportProfitAndLossDetail(options?: ReportOptions, callback?: QuickBooksCallback<any>): void
```

### Parameters
- **options** (ReportOptions) - Optional report-specific options and filters.
- **callback** (function) - Called with (err, reportData).

### Request Example
```javascript
qbo.reportProfitAndLossDetail({
  start_date: '2024-01-01',
  end_date: '2024-12-31',
  accounting_method: 'Cash'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('P&L Detail:', report);
});
```
```

--------------------------------

### Get Aged Payable Detail Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves detailed aged payables, including individual transactions. Specify an 'end_date' option to filter by a specific date.

```javascript
qbo.reportAgedPayableDetail({
  end_date: '2024-01-31'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('Aged Payable Detail:', report);
});
```

--------------------------------

### Create and Email Invoice

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/pdf-and-email.md

Creates an invoice and then sends it to the customer's email address. Requires customer and item references, and line item details.

```javascript
// 1. Create invoice
qbo.createInvoice({
  CustomerRef: { value: '5' },
  BillEmail: { Address: 'customer@acme.com' },
  Line: [
    {
      Amount: 100,
      DetailType: 'SalesItemLineDetail',
      SalesItemLineDetail: {
        ItemRef: { value: '1' },
        UnitPrice: 100,
        Qty: 1
      }
    }
  ],
  TxnDate: '2024-01-15'
}, function(err, invoice) {
  if (err) {
    console.error('Failed to create invoice:', err);
    return;
  }
  
  console.log('Invoice created:', invoice.DocNumber);
  
  // 2. Send invoice PDF via email
  qbo.sendInvoicePdf(invoice.Id, function(err, response) {
    if (err) {
      console.error('Failed to send invoice:', err);
    } else {
      console.log('Invoice sent to customer');
    }
  });
});
```

--------------------------------

### Create a Customer Entity

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/README.md

Use the `createCustomer` method to add a new customer to QuickBooks. The method accepts a customer object and a callback function to handle the response or errors.

```javascript
qbo.createCustomer({
  DisplayName: 'Acme Corp',
  CompanyName: 'Acme Corporation',
  Email: { Address: 'contact@acme.com' }
}, function(err, customer) {
  if (err) console.error(err);
  else console.log('Created:', customer.Id);
});
```

--------------------------------

### Get Customer Balance Detail Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves detailed customer balance information, including transaction-level data. No specific options are required for a basic report.

```javascript
qbo.reportCustomerBalanceDetail(function(err, report) {
  if (err) console.error(err);
  else console.log('Customer Balance Detail:', report);
});
```

--------------------------------

### Create and Send Estimate with Custom Email

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/pdf-and-email.md

Creates an estimate and sends its PDF to a specific email address. Requires customer and item references, and line item details.

```javascript
// 1. Create estimate
qbo.createEstimate({
  CustomerRef: { value: '5' },
  Line: [
    {
      Amount: 1000,
      DetailType: 'SalesItemLineDetail',
      SalesItemLineDetail: {
        ItemRef: { value: '3' },
        UnitPrice: 1000,
        Qty: 1
      }
    }
  ],
  TxnDate: '2024-01-15'
}, function(err, estimate) {
  if (err) {
    console.error('Failed to create estimate:', err);
    return;
  }
  
  console.log('Estimate created:', estimate.DocNumber);
  
  // 2. Send estimate to specified email
  qbo.sendEstimatePdf(estimate.Id, 'project.manager@acme.com', function(err) {
    if (err) {
      console.error('Failed to send estimate:', err);
    } else {
      console.log('Estimate sent to project manager');
    }
  });
});
```

--------------------------------

### Query Method

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/quickbooks-client.md

Executes a raw QuickBooks Query Language (QBQL) query against the QuickBooks API. It takes a QBQL query string and a callback function to handle the response or errors.

```APIDOC
## query

### Description
Executes a raw QuickBooks Query Language (QBQL) query.

### Method Signature
```typescript
query(query: string, callback: QuickBooksCallback<any>): void
```

### Parameters
#### Query Parameters
- **query** (string) - Required - QBQL query string (e.g., 'SELECT * FROM Customer WHERE Active = true')
- **callback** (function) - Required - Called with (err, response)

### Request Example
```javascript
qbo.query('SELECT * FROM Customer WHERE Active = true', function(err, result) {
  if (err) console.error(err);
  else console.log(result.QueryResponse);
});
```

### Callback Type
```typescript
type QuickBooksCallback<T> = (
  err: QuickBooksError | null,
  data?: T,
  res?: any
) => void
```
- **err**: Error object if request failed; null on success
- **data**: Response data on success; undefined on error
- **res**: Raw response object (optional)

### Error Type
```typescript
interface QuickBooksError {
  fault?: {
    error?: Array<{
      Message?: string;
      Detail?: string;
      code?: string;
      element?: string;
    }>;
    type?: string;
  };
  message?: string;
  [key: string]: any;
}
```
```

--------------------------------

### Generate Item Sales Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Obtain sales revenue aggregated by item or product over a given period. Requires an options object with start and end dates, and a callback.

```javascript
qbo.reportItemSales({
  start_date: '2024-01-01',
  end_date: '2024-01-31'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('Item Sales:', report);
});
```

--------------------------------

### reportProfitAndLoss

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves the Profit and Loss (P&L) report, detailing revenues, expenses, and net income/loss for a specified period. Supports filtering by start and end dates.

```APIDOC
## reportProfitAndLoss

### Description
Income statement showing revenues, expenses, and net income/loss for a period.

### Method Signature
```typescript
reportProfitAndLoss(options?: ReportOptions, callback?: QuickBooksCallback<any>): void
```

### Parameters
- **options** (ReportOptions) - Optional report-specific options and filters.
- **callback** (function) - Called with (err, reportData).

### Request Example
```javascript
qbo.reportProfitAndLoss({
  start_date: '2024-01-01',
  end_date: '2024-01-31'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('P&L Report:', report);
});
```
```

--------------------------------

### Find Customers with FetchAll and LIKE filter

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Combine fetching all records with a specific filter using the 'LIKE' operator. This allows for broad searches across all records.

```javascript
qbo.findCustomers([
  {field: 'fetchAll', value: true},
  {field: 'FamilyName', value: 'S%', operator: 'LIKE'}
], function(e, customers) {
  console.log(customers)
})
```

--------------------------------

### Get Aged Receivable Detail Report

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/api-reference/reports.md

Retrieves detailed aged receivables, including individual transactions. An 'end_date' option is commonly used to define the reporting period.

```javascript
qbo.reportAgedReceivableDetail({
  end_date: '2024-01-31'
}, function(err, report) {
  if (err) console.error(err);
  else console.log('Aged Receivable Detail:', report);
});
```

--------------------------------

### getPreferences(callback)

Source: https://github.com/mcohen01/node-quickbooks/blob/master/README.md

Retrieves the Preferences for the authorized QuickBooks realm.

```APIDOC
## getPreferences(callback)

### Description
Retrieves the Preferences from QuickBooks.

### Parameters
#### Callback
- **callback** (function) - Required - Callback function which is called with any error and the Preferences of the authorised realm.
```

--------------------------------

### Configure QuickBooks API to Use Latest Minor Version

Source: https://github.com/mcohen01/node-quickbooks/blob/master/_autodocs/configuration.md

Set the `minorversion` parameter to `null` to automatically use the latest available minor version of the API. This is the recommended approach.

```javascript
const qbo = new QuickBooks(
  // ... other params
  null,   // minorversion = null uses latest
  '2.0',
  refreshToken
);
```