Merge branch 'master' into feat/sdk-add-new-endpoints

docs-v2/host/cloud.mdx

@@ -1,59 +1,63 @@
 ---
 title: 'Cloud vs. self-hosting'
 sidebarTitle: 'Cloud vs. self-hosting'
-description: 'Overview of cloud & self-hosting options.'
+description: 'Overview of the different Nango versions (cloud or self-hosted)'
 ---
 
-| Features | Free Self-Hosting | Cloud | Enterprise Self-Hosting |
-|-|-|-|-|
-| OAuth w/ custom callback URL | ✅ | ✅ (free) | ✅ | 
-| Fully white-label integrations | ✅ | ✅ (free) | ✅ | 
-| API Key auth | ✅| ✅ (free) | ✅ | 
-| Basic auth | ✅ | ✅ (free) | ✅ | 
-| Request proxying | ✅ | ✅ (free) | ✅ | 
-| Management dashboard | ✅  | ✅ (free) | ✅ | 
-| Logs & monitoring | ✅  | ✅ (free) | ✅ | 
-| Encryption at rest | ✅  | ✅ (free) | ✅ | 
-| Programmatic API & SDKs | ✅  | ✅ (free) | ✅ | 
-| Continuous data syncs | ❌  | ✅ | ✅ | 
-| 2-way syncs & write backs (Actions) | ❌  | ✅ | ✅ | 
-| Integration templates | ❌  | ✅ | ✅ | 
-| Custom Syncs | ❌ | ✅ | ✅ | 
-| Custom Actions | ❌ | ✅ | ✅ | 
-| Webhooks from Nango | ❌ | ✅ | ✅ | 
-| Webhooks from external APIs | ❌ | ✅ | ✅ | 
-| Field mappings | ❌ | ✅ | ✅ | 
-| Customization of integration per user | ❌  | ✅ | ✅ | 
-| Rate-limit handling | ❌ | ✅ | ✅ | 
-| Data deletion detection | ❌ | ✅ | ✅ | 
-| API pagination handling | ❌ | ✅ | ✅ | 
-| API response validation | ❌ | ✅ | ✅ | 
-| Auto-scaling | ❌ | ✅ | ✅ | 
-| Auto-upgrades | ❌ | ✅ | ✅ | 
-| Multi-user & team management | ❌ | ✅ | ✅ | 
-| Production-grade support | ❌ | ✅ | ✅ | 
+| Features | Free (self-hosted or cloud) | Paid (self-hosted or cloud) |
+|-|-|-|
+| Best for | (O)Auth for 250+ APIs | 2-way data syncs with 250+ APIs |
+| OAuth w/ custom callback URL | ✅  | ✅ | 
+| Fully white-label integrations | ✅  | ✅ | 
+| API Key auth | ✅  | ✅ | 
+| Basic auth | ✅ | ✅ | 
+| Request proxying | ✅ | ✅ | 
+| Management dashboard | ✅ | ✅ | 
+| Logs & monitoring | ✅ | ✅ | 
+| Encryption at rest | ✅ | ✅ | 
+| Programmatic API & SDKs | ✅ | ✅ | 
+| Continuous data syncs | ❌  | ✅ | 
+| 2-way syncs & write backs (Actions) | ❌  | ✅ | 
+| Integration templates | ❌  | ✅ | 
+| Custom Syncs | ❌ | ✅ | 
+| Custom Actions | ❌ | ✅ | 
+| Webhooks from Nango | ❌ | ✅ | 
+| Webhooks from external APIs | ❌ | ✅ | 
+| Field mappings | ❌ | ✅ | 
+| Customization of integration per user | ❌  | ✅ | 
+| Rate-limit handling | ❌ | ✅ | 
+| Data deletion detection | ❌ | ✅ | 
+| API pagination handling | ❌ | ✅ | 
+| API response validation | ❌ | ✅ | 
+| Auto-scaling | ❌ | ✅ | 
+| Auto-upgrades | ❌ | ✅ | 
+| Multi-user & team management | ❌ | ✅ | 
+| Production-grade support | ❌ | ✅ | 
 
 ## Nango Cloud
 
 Nango Cloud is free to use for features related to authorization and request proxying, without limitations. 
 
-Other features around consuming & syncing data with APIs are paid, with a free tier (cf. [pricing](https://nango.dev/pricing)).
+Other features for the 2-way data syncs with APIs are paid, with a free tier (cf. [pricing](https://nango.dev/pricing)).
 
 Sign up for a free Cloud account:
 
 [![Try Nango Cloud](/images/nango-deploy-button.svg)](https://app.nango.dev/signup)
+
 ## Free Self-Hosting
 
-Free self-hosting features have been designed with easy self-hostability in mind, ensuring that you can deploy them independently in your own environment.
+The same features that are free on Cloud, (O)Auth for all APIs Nango supports, are also available for free self-hosted instances.
+
+Check the sidebar for guides on setting up your self-hosted Nango instance on [AWS](/host/self-host/aws), [GCP](/host/self-host/gcp) or [locally](/host/self-host/local)
 
-These features are widely adopted by many companies in production. They simplify the process of obtaining, storing, and refreshing credentials to access any API. The same features are available for free without limitations on Nango Cloud.
+## Paid Self-Hosting
 
-## Enterprise Self-Hosting
+All paid features available on Nango Cloud are also available on the paid self-hosted version. A [Scale plan](https://www.nango.dev/pricing) subscription is required.
 
-Enterprise self-hosting requires subscribing to a Scale plan. Instructions for Enterprise self-hosting can be communicated upon request.
+Paid self-hosting is optimized for large, regulated Enterprises.
 
-If you are interested in Enterprise self-hosting, please get in touch with us in the [community](https://nango.dev/slack).
+If you are interested in the paid self-hosting version, please get in touch with us in the [community](https://nango.dev/slack) or [book a demo](https://nango.dev/chat).
 
 <Tip>
 **Questions, problems, feedback?** Please reach out in the [Slack community](https://nango.dev/slack).
-</Tip>
+</Tip>

docs-v2/integrations/all/quickbooks.mdx

@@ -22,6 +22,7 @@ API configuration: [`quickbooks`](https://nango.dev/providers.yaml)
 -   [How to register an Application](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0#create-an-app)
 -   [OAuth-related docs](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization)
 -   [List of OAuth scopes](https://developer.intuit.com/app/developer/qbo/docs/learn/scopes#current-scopes)
+-   [Quickbooks API docs](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account)
 
 <Tip>Need help getting started? Get help in the [community](https://nango.dev/slack).</Tip>
 

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,44 @@
+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> {
+    // 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)}`
+        });
+    }
+
+    const companyId = await getCompany(nango);
+    // Map the account input to the QuickBooks account structure
+    const quickBooksAccount = toQuickBooksAccount(input);
+
+    const config: ProxyConfiguration = {
+        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,71 @@
+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> {
+    // 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)}`
+            });
+        }
+    }
+
+    const companyId = await getCompany(nango);
+    // Map the credit memo input to the QuickBooks credit memo structure
+    const quickBooksInvoice = toQuickBooksCreditMemo(input);
+
+    const config: ProxyConfiguration = {
+        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,44 @@
+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> {
+    // 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)}`
+        });
+    }
+
+    const companyId = await getCompany(nango);
+    // Map the customer input to the QuickBooks customer structure
+    const quickBooksCustomer = toQuickBooksCustomer(input);
+
+    const config: ProxyConfiguration = {
+        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,70 @@
+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> {
+    // 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)}`
+            });
+        }
+    }
+
+    const companyId = await getCompany(nango);
+    // Map the invoice input to the QuickBooks invoice structure
+    const quickBooksInvoice = toQuickBooksInvoice(input);
+
+    const config: ProxyConfiguration = {
+        endpoint: `/v3/company/${companyId}/invoice`,
+        data: quickBooksInvoice
+    };
+    const response = await nango.post(config);
+
+    return toInvoice(response.data['Invoice']);
+}