feat(quickbooks): add verified financial report contracts

Author: Bill Leoutsakos

apps/sim/tools/quickbooks/read_master_data.ts

@@ -127,7 +127,7 @@ export const quickbooksReadMasterDataTool: ToolConfig<
 > = {
   id: 'quickbooks_read_master_data',
   name: 'QuickBooks Read Master Data',
-  description: 'List or read one account, customer, vendor, item, or employee',
+  description: 'List or read one account, class, customer, department, employee, item, or vendor',
   version: '1.0.0',
   params: {
     accessToken: {
@@ -146,7 +146,8 @@ export const quickbooksReadMasterDataTool: ToolConfig<
       type: 'string',
       required: true,
       visibility: 'user-or-llm',
-      description: 'Master-data entity to read: account, customer, vendor, item, or employee',
+      description:
+        'Master-data entity to read: account, class, customer, department, employee, item, or vendor',
     },
     readMode: {
       type: 'string',

apps/sim/tools/quickbooks/run_financial_report.ts

@@ -0,0 +1,165 @@
+import { ErrorExtractorId } from '@/tools/error-extractors'
+import { QUICKBOOKS_MAX_RESPONSE_BYTES } from '@/tools/quickbooks/client'
+import type {
+  QuickBooksRunFinancialReportParams,
+  QuickBooksRunFinancialReportResponse,
+} from '@/tools/quickbooks/types'
+import {
+  QUICKBOOKS_REPORT_COLUMNS_PROPERTIES,
+  QUICKBOOKS_REPORT_HEADER_PROPERTIES,
+  QUICKBOOKS_REPORT_ROWS_PROPERTIES,
+} from '@/tools/quickbooks/types'
+import {
+  buildQuickBooksReportUrl,
+  getQuickBooksToolHeaders,
+  transformQuickBooksReportResponse,
+} from '@/tools/quickbooks/utils'
+import type { ToolConfig } from '@/tools/types'
+
+export const quickbooksRunFinancialReportTool: ToolConfig<
+  QuickBooksRunFinancialReportParams,
+  QuickBooksRunFinancialReportResponse
+> = {
+  id: 'quickbooks_run_financial_report',
+  name: 'QuickBooks Run Financial Report',
+  description: 'Run a fixed QuickBooks financial report with verified accountant-focused filters',
+  version: '1.0.0',
+  params: {
+    accessToken: {
+      type: 'string',
+      required: true,
+      visibility: 'hidden',
+      description: 'QuickBooks OAuth access token',
+    },
+    realmId: {
+      type: 'string',
+      required: true,
+      visibility: 'hidden',
+      description: 'QuickBooks company ID derived from the connected credential',
+    },
+    reportType: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Fixed QuickBooks financial report to run',
+    },
+    startDate: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Report start date in YYYY-MM-DD format; Intuit recommends periods of six months or less for performance',
+    },
+    endDate: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Report end or as-of date in YYYY-MM-DD format',
+    },
+    accountingMethod: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Use the QuickBooks default, cash basis, or accrual basis',
+    },
+    summarizeBy: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Time period or business dimension used to summarize report columns',
+    },
+    customerId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Single QuickBooks customer ID filter',
+    },
+    vendorId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Single QuickBooks vendor ID filter',
+    },
+    accountId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Single QuickBooks account ID filter',
+    },
+    itemId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Single QuickBooks item ID filter',
+    },
+    classId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Single QuickBooks class ID filter',
+    },
+    departmentId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Single QuickBooks department ID filter',
+    },
+    agingMethod: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Age open balances from the report date or current date',
+    },
+    agingDays: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Positive number of days in each aging period',
+    },
+  },
+  oauth: {
+    required: true,
+    provider: 'quickbooks',
+    requiredScopes: ['com.intuit.quickbooks.accounting'],
+  },
+  errorExtractor: ErrorExtractorId.QUICKBOOKS_FAULT,
+  request: {
+    url: (params) => buildQuickBooksReportUrl(params).toString(),
+    method: 'GET',
+    headers: (params) => getQuickBooksToolHeaders(params.accessToken),
+    retry: { enabled: false },
+    maxResponseBytes: QUICKBOOKS_MAX_RESPONSE_BYTES,
+  },
+  transformResponse: async (response, params) => {
+    if (!params) throw new Error('QuickBooks report parameters are required')
+    return transformQuickBooksReportResponse(response, params.reportType)
+  },
+  outputs: {
+    reportType: {
+      type: 'string',
+      description: 'Financial report type that was run',
+    },
+    header: {
+      type: 'json',
+      description:
+        'Native QuickBooks report header with name, periods, basis, currency, summarization, filters, and options',
+      properties: QUICKBOOKS_REPORT_HEADER_PROPERTIES,
+    },
+    columns: {
+      type: 'json',
+      description: 'Native QuickBooks report column definitions',
+      properties: QUICKBOOKS_REPORT_COLUMNS_PROPERTIES,
+    },
+    rows: {
+      type: 'json',
+      description: 'Native hierarchical QuickBooks report rows and section summaries',
+      properties: QUICKBOOKS_REPORT_ROWS_PROPERTIES,
+    },
+    time: {
+      type: 'string',
+      description: 'QuickBooks response timestamp',
+      optional: true,
+      nullable: true,
+    },
+  },
+}