feat(integration-templates): add quickbooks actions & sycns

docs-v2/integrations/integration-templates/quickbooks.mdx

@@ -0,0 +1,21 @@
+---
+title: 'Quickbooks API Integration Template'
+sidebarTitle: 'Quickbooks'
+---
+
+## Get started with the Quickbooks template
+
+<Card title="How to use integration templates"
+      href="/understand/concepts/templates"
+      icon="book-open">
+    Learn how to use integration templates in Nango
+</Card>
+
+<Card title="Get the Quickbooks template"
+      href="https://github.com/NangoHQ/nango/tree/master/integration-templates/quickbooks"
+      icon="github">
+    Get the latest version of the Quickbooks integration template from GitHub
+</Card>
+
+## Need help with the template?
+Please reach out in the [Slack community](https://nango.dev/slack), we are very active there and happy to help!

docs-v2/mint.json

@@ -302,6 +302,7 @@
                         "integrations/integration-templates/woocommerce",
                         "integrations/integration-templates/workable",
                         "integrations/integration-templates/xero",
+                        "integrations/integration-templates/quickbooks",
                         "integrations/integration-templates/zendesk",
                         "integrations/integration-templates/zoho-crm",
                         "integrations/integration-templates/zoho-mail"

integration-templates/quickbooks/actions/create-account.ts

@@ -0,0 +1,46 @@
+import type { NangoAction, CreateAccount, Account, ProxyConfiguration } from '../../models';
+import { getCompany } from '../utils/getCompany.js';
+import { toQuickBooksAccount, toAccount } from '../mappers/toAccount.js';
+
+/**
+ * This function handles the creation of a account in QuickBooks via the Nango action.
+ * It validates the input account data, maps it to the appropriate QuickBooks account structure,
+ * and sends a request to create the account in the QuickBooks API.
+ * For detailed endpoint documentation, refer to:
+ * https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account#create-an-account
+ *
+ * @param {NangoAction} nango - The Nango action instance to handle API requests.
+ * @param {CreateAccount} input - The account data input that will be sent to QuickBooks.
+ * @throws {nango.ActionError} - Throws an error if the input is missing or lacks required fields.
+ * @returns {Promise<Account>} - Returns the created account object from QuickBooks.
+ */
+export default async function runAction(nango: NangoAction, input: CreateAccount): Promise<Account> {
+    const companyId = await getCompany(nango);
+
+    // Validate if input is present
+    if (!input) {
+        throw new nango.ActionError({
+            message: `Input account object is required. Received: ${JSON.stringify(input)}`
+        });
+    }
+
+    // Ensure that required fields are present for QuickBooks
+    if (!input.name || (!input.account_type && !input.account_sub_type)) {
+        throw new nango.ActionError({
+            message: `Please provide a 'name' and at least one of the following: account_type or account_sub_type. Received: ${JSON.stringify(input)}`
+        });
+    }
+
+    // Map the account input to the QuickBooks account structure
+    const quickBooksAccount = toQuickBooksAccount(input);
+
+    const config: ProxyConfiguration = {
+        baseUrlOverride: 'https://sandbox-quickbooks.api.intuit.com',
+        endpoint: `/v3/company/${companyId}/account`,
+        data: quickBooksAccount
+    };
+
+    const response = await nango.post(config);
+
+    return toAccount(response.data['Account']);
+}

integration-templates/quickbooks/actions/create-credit-memo.ts

@@ -0,0 +1,73 @@
+import type { NangoAction, CreateCreditMemo, CreditMemo, ProxyConfiguration } from '../../models';
+import { getCompany } from '../utils/getCompany.js';
+import { toQuickBooksCreditMemo, toCreditMemo } from '../mappers/toCreditMemo.js';
+
+/**
+ * This function handles the creation of a credit memo in QuickBooks via the Nango action.
+ * It validates the input credit memo data, maps it to the appropriate QuickBooks credit memo structure,
+ * and sends a request to create the credit memo in the QuickBooks API.
+ * For detailed endpoint documentation, refer to:
+ * https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/creditmemo#create-a-credit-memo
+ *
+ * @param {NangoAction} nango - The Nango action instance to handle API requests.
+ * @param {CreateCreditMemo} input - The credit memo data input that will be sent to QuickBooks.
+ * @throws {nango.ActionError} - Throws an error if the input is missing or lacks required fields.
+ * @returns {Promise<CreditMemo>} - Returns the created credit memo object from QuickBooks.
+ */
+export default async function runAction(nango: NangoAction, input: CreateCreditMemo): Promise<CreditMemo> {
+    const companyId = await getCompany(nango);
+
+    // Validate if input is present
+    if (!input) {
+        throw new nango.ActionError({
+            message: `Input credit memo object is required. Received: ${JSON.stringify(input)}`
+        });
+    }
+
+    // Validate required fields
+    if (!input.customer_ref || !input.customer_ref.value) {
+        throw new nango.ActionError({
+            message: `CustomerRef is required and must include a value. Received: ${JSON.stringify(input.customer_ref)}`
+        });
+    }
+
+    if (!input.line || input.line.length === 0) {
+        throw new nango.ActionError({
+            message: `At least one line item is required. Received: ${JSON.stringify(input.line)}`
+        });
+    }
+
+    // Validate each line item
+    for (const line of input.line) {
+        if (!line.detail_type) {
+            throw new nango.ActionError({
+                message: `DetailType is required for each line item. Received: ${JSON.stringify(line)}`
+            });
+        }
+
+        if (line.amount_cents === undefined) {
+            throw new nango.ActionError({
+                message: `amount_cents is required for each line item. Received: ${JSON.stringify(line)}`
+            });
+        }
+
+        if (!line.sales_item_line_detail || !line.sales_item_line_detail.item_ref) {
+            throw new nango.ActionError({
+                message: `SalesItemLineDetail with item_ref is required for each line item. Received: ${JSON.stringify(line.sales_item_line_detail)}`
+            });
+        }
+    }
+
+    // Map the credit memo input to the QuickBooks credit memo structure
+    const quickBooksInvoice = toQuickBooksCreditMemo(input);
+
+    const config: ProxyConfiguration = {
+        baseUrlOverride: 'https://sandbox-quickbooks.api.intuit.com',
+        endpoint: `/v3/company/${companyId}/creditmemo`,
+        data: quickBooksInvoice
+    };
+
+    const response = await nango.post(config);
+
+    return toCreditMemo(response.data['CreditMemo']);
+}

integration-templates/quickbooks/actions/create-customer.ts

@@ -0,0 +1,46 @@
+import type { NangoAction, CreateCustomer, Customer, ProxyConfiguration } from '../../models';
+import { getCompany } from '../utils/getCompany.js';
+import { toQuickBooksCustomer, toCustomer } from '../mappers/toCustomer.js';
+
+/**
+ * This function handles the creation of a customer in QuickBooks via the Nango action.
+ * It validates the input customer data, maps it to the appropriate QuickBooks customer structure,
+ * and sends a request to create the customer in the QuickBooks API.
+ * For detailed endpoint documentation, refer to:
+ * https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/customer#create-a-customer
+ *
+ * @param {NangoAction} nango - The Nango action instance to handle API requests.
+ * @param {CreateCustomer} input - The customer data input that will be sent to QuickBooks.
+ * @throws {nango.ActionError} - Throws an error if the input is missing or lacks required fields.
+ * @returns {Promise<Customer>} - Returns the created customer object from QuickBooks.
+ */
+export default async function runAction(nango: NangoAction, input: CreateCustomer): Promise<Customer> {
+    const companyId = await getCompany(nango);
+
+    // Validate if input is present
+    if (!input) {
+        throw new nango.ActionError({
+            message: `Input customer object is required. Received: ${JSON.stringify(input)}`
+        });
+    }
+
+    // Ensure that required fields are present for QuickBooks
+    if (!input.title && !input.given_name && !input.display_name && !input.suffix) {
+        throw new nango.ActionError({
+            message: `Please provide at least one of the following fields: title, given_name, display_name, or suffix. Received: ${JSON.stringify(input)}`
+        });
+    }
+
+    // Map the customer input to the QuickBooks customer structure
+    const quickBooksCustomer = toQuickBooksCustomer(input);
+
+    const config: ProxyConfiguration = {
+        baseUrlOverride: 'https://sandbox-quickbooks.api.intuit.com',
+        endpoint: `/v3/company/${companyId}/customer`,
+        data: quickBooksCustomer
+    };
+
+    const response = await nango.post(config);
+
+    return toCustomer(response.data['Customer']);
+}

integration-templates/quickbooks/actions/create-invoice.ts

@@ -0,0 +1,73 @@
+import type { NangoAction, CreateInvoice, Invoice, ProxyConfiguration } from '../../models';
+import { getCompany } from '../utils/getCompany.js';
+import { toQuickBooksInvoice, toInvoice } from '../mappers/toInvoice.js';
+
+/**
+ * This function handles the creation of an invoice in QuickBooks via the Nango action.
+ * It validates the input invoice data, maps it to the appropriate QuickBooks invoice structure,
+ * and sends a request to create the invoice in the QuickBooks API.
+ * For detailed endpoint documentation, refer to:
+ * https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/invoice#create-an-invoice
+ *
+ * @param {NangoAction} nango - The Nango action instance to handle API requests.
+ * @param {CreateInvoice} input - The invoice data input that will be sent to QuickBooks.
+ * @throws {nango.ActionError} - Throws an error if the input is missing or lacks required fields.
+ * @returns {Promise<Invoice>} - Returns the created invoice object from QuickBooks.
+ */
+export default async function runAction(nango: NangoAction, input: CreateInvoice): Promise<Invoice> {
+    const companyId = await getCompany(nango);
+
+    // Validate if input is present
+    if (!input) {
+        throw new nango.ActionError({
+            message: `Input invoice object is required. Received: ${JSON.stringify(input)}`
+        });
+    }
+
+    // Validate required fields
+    if (!input.customer_ref || !input.customer_ref.value) {
+        throw new nango.ActionError({
+            message: `CustomerRef is required and must include a value. Received: ${JSON.stringify(input.customer_ref)}`
+        });
+    }
+
+    if (!input.line || input.line.length === 0) {
+        throw new nango.ActionError({
+            message: `At least one line item is required. Received: ${JSON.stringify(input.line)}`
+        });
+    }
+
+    // Validate each line item
+    for (const line of input.line) {
+        if (!line.detail_type) {
+            throw new nango.ActionError({
+                message: `DetailType is required for each line item. Received: ${JSON.stringify(line)}`
+            });
+        }
+
+        if (line.amount_cents === undefined) {
+            throw new nango.ActionError({
+                message: `Amount_cents is required for each line item. Received: ${JSON.stringify(line)}`
+            });
+        }
+
+        if (!line.sales_item_line_detail || !line.sales_item_line_detail.item_ref) {
+            throw new nango.ActionError({
+                message: `SalesItemLineDetail with item_ref is required for each line item. Received: ${JSON.stringify(line.sales_item_line_detail)}`
+            });
+        }
+    }
+
+    // Map the invoice input to the QuickBooks invoice structure
+    const quickBooksInvoice = toQuickBooksInvoice(input);
+
+    const config: ProxyConfiguration = {
+        baseUrlOverride: 'https://sandbox-quickbooks.api.intuit.com',
+        endpoint: `/v3/company/${companyId}/invoice`,
+        data: quickBooksInvoice
+    };
+
+    const response = await nango.post(config);
+
+    return toInvoice(response.data['Invoice']);
+}

integration-templates/quickbooks/actions/create-item.ts

@@ -0,0 +1,46 @@
+import type { NangoAction, CreateItem, Item, ProxyConfiguration } from '../../models';
+import { getCompany } from '../utils/getCompany.js';
+import { toQuickBooksItem, toItem } from '../mappers/toItem.js';
+
+/**
+ * This function handles the creation of an item in QuickBooks via the Nango action.
+ * It validates the input item data, maps it to the appropriate QuickBooks item structure,
+ * and sends a request to create the item in the QuickBooks API.
+ * For detailed endpoint documentation, refer to:
+ * https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/item#create-an-item
+ *
+ * @param {NangoAction} nango - The Nango action instance to handle API requests.
+ * @param {CreateItem} input - The item data input that will be sent to QuickBooks.
+ * @throws {nango.ActionError} - Throws an error if the input is missing or lacks required fields.
+ * @returns {Promise<Item>} - Returns the created item object from QuickBooks.
+ */
+export default async function runAction(nango: NangoAction, input: CreateItem): Promise<Item> {
+    const companyId = await getCompany(nango);
+
+    // Validate if input is present
+    if (!input) {
+        throw new nango.ActionError({
+            message: `Input item object is required. Received: ${JSON.stringify(input)}`
+        });
+    }
+
+    // Ensure that required fields are present for QuickBooks
+    if (!input.name || (!input.expense_accountRef && !input.income_accountRef)) {
+        throw new nango.ActionError({
+            message: `Please provide a 'name' and at least one of the following: 'expense_accountRef' or 'income_accountRef'. Received: ${JSON.stringify(input)}`
+        });
+    }
+
+    // Map the item input to the QuickBooks item structure
+    const quickBooksItem = toQuickBooksItem(input);
+
+    const config: ProxyConfiguration = {
+        baseUrlOverride: 'https://sandbox-quickbooks.api.intuit.com',
+        endpoint: `/v3/company/${companyId}/item`,
+        data: quickBooksItem
+    };
+
+    const response = await nango.post(config);
+
+    return toItem(response.data['Item']);
+}

integration-templates/quickbooks/actions/create-payment.ts

@@ -0,0 +1,52 @@
+import type { NangoAction, CreatePayment, Payment, ProxyConfiguration } from '../../models';
+import { getCompany } from '../utils/getCompany.js';
+import { toQuickBooksPayment, toPayment } from '../mappers/toPayment.js';
+
+/**
+ * This function handles the creation of an invoice in QuickBooks via the Nango action.
+ * It validates the input invoice data, maps it to the appropriate QuickBooks invoice structure,
+ * and sends a request to create the invoice in the QuickBooks API.
+ * For detailed endpoint documentation, refer to:
+ * https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/payment#create-a-payment
+ *
+ * @param {NangoAction} nango - The Nango action instance to handle API requests.
+ * @param {CreatePayment} input - The invoice data input that will be sent to QuickBooks.
+ * @throws {nango.ActionError} - Throws an error if the input is missing or lacks required fields.
+ * @returns {Promise<Payment>} - Returns the created invoice object from QuickBooks.
+ */
+export default async function runAction(nango: NangoAction, input: CreatePayment): Promise<Payment> {
+    const companyId = await getCompany(nango);
+
+    // Validate if input is present
+    if (!input) {
+        throw new nango.ActionError({
+            message: `Input invoice object is required. Received: ${JSON.stringify(input)}`
+        });
+    }
+
+    // Validate required fields
+    if (!input.customer_ref || !input.customer_ref.value) {
+        throw new nango.ActionError({
+            message: `CustomerRef is required and must include a value. Received: ${JSON.stringify(input.customer_ref)}`
+        });
+    }
+
+    if (!input.total_amount_cents) {
+        throw new nango.ActionError({
+            message: `Amount_cents is required for the payment is required. Received: ${JSON.stringify(input)}`
+        });
+    }
+
+    // Map the invoice input to the QuickBooks invoice structure
+    const quickBooksPayment = toQuickBooksPayment(input);
+
+    const config: ProxyConfiguration = {
+        baseUrlOverride: 'https://sandbox-quickbooks.api.intuit.com',
+        endpoint: `/v3/company/${companyId}/payment`,
+        data: quickBooksPayment
+    };
+
+    const response = await nango.post(config);
+
+    return toPayment(response.data['Payment']);
+}