List Contact Groups (#67)

* Added in list contact groups

* Fix sync issue

* Added in ability to optionall provide specific contact group id, which will show the contacts in the provided contact group id.

Author: arkk1981

README.md

@@ -115,6 +115,7 @@ NOTE: The `XERO_CLIENT_BEARER_TOKEN` will take precedence over the `XERO_CLIENT_
 - `list-payroll-leave-types`: Retrieve a list of all avaliable leave types in Xero Payroll
 - `list-aged-receivables-by-contact`: Retrieves aged receivables for a contact
 - `list-aged-payables-by-contact`: Retrieves aged payables for a contact
+- `list-contact-groups`: Retrieve a list of contact groups
 - `create-contact`: Create a new contact
 - `create-credit-note`: Create a new credit note
 - `create-invoice`: Create a new invoice

src/handlers/list-xero-contact-groups.handler.ts

@@ -0,0 +1,49 @@
+import { xeroClient } from "../clients/xero-client.js";
+import { ContactGroup } from "xero-node";
+import { XeroClientResponse } from "../types/tool-response.js";
+import { formatError } from "../helpers/format-error.js";
+import { getClientHeaders } from "../helpers/get-client-headers.js";
+
+async function getContactGroups(contactGroupId?: string): Promise<ContactGroup[]> {
+  await xeroClient.authenticate();
+
+  if (contactGroupId) {
+    const response = await xeroClient.accountingApi.getContactGroup(
+      xeroClient.tenantId,
+      contactGroupId,
+      getClientHeaders(),
+    );
+    return response.body.contactGroups ?? [];
+  }
+
+  const response = await xeroClient.accountingApi.getContactGroups(
+    xeroClient.tenantId,
+    undefined, // where
+    undefined, // order
+    getClientHeaders(),
+  );
+  return response.body.contactGroups ?? [];
+}
+
+/**
+ * List all contact groups from Xero. If a contactGroupId is provided, it will return only that contact group.
+ */
+export async function listXeroContactGroups(contactGroupId?: string): Promise<
+  XeroClientResponse<ContactGroup[]>
+> {
+  try {
+    const contactGroups = await getContactGroups(contactGroupId);
+
+    return {
+      result: contactGroups,
+      isError: false,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      result: null,
+      isError: true,
+      error: formatError(error),
+    };
+  }
+}

src/tools/list/index.ts

@@ -25,6 +25,7 @@ import ListQuotesTool from "./list-quotes.tool.js";
 import ListReportBalanceSheetTool from "./list-report-balance-sheet.tool.js";
 import ListTaxRatesTool from "./list-tax-rates.tool.js";
 import ListTrialBalanceTool from "./list-trial-balance.tool.js";
+import ListContactGroupsTool from "./list-contact-groups.tool.js";
 
 export const ListTools = [
   ListAccountsTool,
@@ -48,5 +49,6 @@ export const ListTools = [
   ListPayrollLeaveTypesTool,
   ListAgedReceivablesByContact,
   ListAgedPayablesByContact,
-  ListPayrollTimesheetsTool
+  ListPayrollTimesheetsTool,
+  ListContactGroupsTool,
 ];

src/tools/list/list-contact-groups.tool.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { listXeroContactGroups } from "../../handlers/list-xero-contact-groups.handler.js";
+import { CreateXeroTool } from "../../helpers/create-xero-tool.js";
+
+const ListContactGroupsTool = CreateXeroTool(
+  "list-contact-groups",
+  `List all contact groups in Xero.
+  You can optionally specify a contact group ID to retrieve details for that specific group, including its contacts.`,
+  {
+    contactGroupId: z
+      .string()
+      .optional()
+      .describe("Optional ID of the contact group to retrieve"),    
+  },
+  async (args) => {
+    const response = await listXeroContactGroups(args?.contactGroupId);
+    
+    if (response.error !== null) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Error listing contact groups: ${response.error}`,
+          },
+        ],
+      };
+    }
+
+    const contactGroups = response.result;
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Found ${contactGroups?.length || 0} contact groups:`,
+        },
+        ...(contactGroups?.map((contactGroup) => ({
+          type: "text" as const,
+          text: [
+            `Contact Group ID: ${contactGroup.contactGroupID}`,
+            `Name: ${contactGroup.name}`,
+            `Status: ${contactGroup.status}`,
+            contactGroup.contacts
+              ? contactGroup.contacts.map(contact => [
+                  `Contact ID: ${contact.contactID}`,
+                  `Name: ${contact.name}`,
+                ].join('\n')
+              ).join('\n')
+              : "No contacts in this contact group.",            
+          ]
+            .filter(Boolean)
+            .join("\n"),
+        })) || []),
+      ],
+    };
+  },
+);
+
+export default ListContactGroupsTool;