Tracking Categories and Options Tools (#69)

* Add list tracking categories tool

* Add create tracking categories tool

* Update and create categories and options

* Cleanup

* Fixes

* Remove tracking category deep link

Because Tracking Categories don't have deep links

* Remove tracking category deep links

---------

Co-authored-by: Regan Ashworth <regan.ashworth@gmail.com>

Author: bristola

src/handlers/create-xero-tracking-category.handler.ts

@@ -0,0 +1,50 @@
+import { xeroClient } from "../clients/xero-client.js";
+import { XeroClientResponse } from "../types/tool-response.js";
+import { formatError } from "../helpers/format-error.js";
+import { getClientHeaders } from "../helpers/get-client-headers.js";
+import { TrackingCategory } from "xero-node";
+
+async function createTrackingCategory(
+  name: string
+): Promise<TrackingCategory | undefined> {
+  xeroClient.authenticate();
+
+  const trackingCategory: TrackingCategory = {
+    name: name
+  };
+
+  const response = await xeroClient.accountingApi.createTrackingCategory(
+    xeroClient.tenantId, // xeroTenantId
+    trackingCategory,
+    undefined, // idempotencyKey
+    getClientHeaders() // options
+  );
+
+  const createdTrackingCategory = response.body.trackingCategories?.[0];
+
+  return createdTrackingCategory;
+}
+
+export async function createXeroTrackingCategory(
+  name: string
+): Promise<XeroClientResponse<TrackingCategory>> {
+  try {
+    const createdTrackingCategory = await createTrackingCategory(name);
+
+    if (!createdTrackingCategory) {
+      throw new Error("Tracking Category creation failed.");
+    }
+
+    return {
+      result: createdTrackingCategory,
+      isError: false,
+      error: null
+    };
+  } catch (error) {
+    return {
+      result: null,
+      isError: true,
+      error: formatError(error)
+    };
+  }
+}

src/handlers/create-xero-tracking-option.handler.ts

@@ -0,0 +1,51 @@
+import { xeroClient } from "../clients/xero-client.js";
+import { XeroClientResponse } from "../types/tool-response.js";
+import { formatError } from "../helpers/format-error.js";
+import { getClientHeaders } from "../helpers/get-client-headers.js";
+import { TrackingOption } from "xero-node";
+
+async function createTrackingOption(
+  trackingCategoryId: string,
+  name: string
+): Promise<TrackingOption | undefined> {
+  xeroClient.authenticate();
+  
+  const response = await xeroClient.accountingApi.createTrackingOptions(
+    xeroClient.tenantId,
+    trackingCategoryId,
+    {
+      name: name
+    },
+    undefined, // idempotencyKey
+    getClientHeaders()
+  );
+
+  const createdTrackingOption = response.body.options?.[0];
+
+  return createdTrackingOption;
+}
+
+export async function createXeroTrackingOptions(
+  trackingCategoryId: string,
+  optionNames: string[]
+): Promise<XeroClientResponse<TrackingOption[]>> {
+  try {
+    const createdOptions = await Promise.all(
+      optionNames.map(async optionName => await createTrackingOption(trackingCategoryId, optionName))
+    );
+
+    return {
+      result: createdOptions
+        .filter(Boolean)
+        .map(option => option as TrackingOption),
+      isError: false,
+      error: null
+    };
+  } catch (error) {
+    return {
+      result: null,
+      isError: true,
+      error: formatError(error)
+    };
+  }
+}

src/handlers/list-xero-tracking-categories.handler.ts

@@ -0,0 +1,41 @@
+import { xeroClient } from "../clients/xero-client.js";
+import { TrackingCategory } from "xero-node";
+import { getClientHeaders } from "../helpers/get-client-headers.js";
+import { XeroClientResponse } from "../types/tool-response.js";
+import { formatError } from "../helpers/format-error.js";
+
+async function getTrackingCategories(
+  includeArchived?: boolean
+): Promise<TrackingCategory[]> {
+  await xeroClient.authenticate();
+
+  const response = await xeroClient.accountingApi.getTrackingCategories(
+    xeroClient.tenantId, // xeroTenantId
+    undefined, // where
+    undefined, // order
+    includeArchived, // includeArchived
+    getClientHeaders()
+  );
+
+  return response.body.trackingCategories ?? [];
+}
+
+export async function listXeroTrackingCategories(
+  includeArchived?: boolean
+): Promise<XeroClientResponse<TrackingCategory[]>> {
+  try {
+    const trackingCategories = await getTrackingCategories(includeArchived);
+
+    return {
+      result: trackingCategories,
+      isError: false,
+      error: null
+    };
+  } catch (error) {
+    return {
+      result: null,
+      isError: true,
+      error: formatError(error)
+    };
+  }
+}

src/handlers/update-xero-tracking-category.handler.ts

@@ -0,0 +1,79 @@
+import { TrackingCategory } from "xero-node";
+import { xeroClient } from "../clients/xero-client.js";
+import { formatError } from "../helpers/format-error.js";
+import { getClientHeaders } from "../helpers/get-client-headers.js";
+import { XeroClientResponse } from "../types/tool-response.js";
+
+type TrackingCategoryStatus = "ACTIVE" | "ARCHIVED";
+
+async function getTrackingCategory(trackingCategoryId: string): Promise<TrackingCategory | undefined> {
+  await xeroClient.authenticate();
+
+  const response = await xeroClient.accountingApi.getTrackingCategory(
+    xeroClient.tenantId,
+    trackingCategoryId,
+    getClientHeaders()
+  );
+
+  return response.body.trackingCategories?.[0];
+}
+
+async function updateTrackingCategory(
+  trackingCategoryId: string,
+  existingTrackingCategory: TrackingCategory,
+  name?: string,
+  status?: TrackingCategoryStatus
+): Promise<TrackingCategory | undefined> {
+  const trackingCategory: TrackingCategory = {
+    trackingCategoryID: trackingCategoryId,
+    name: name ? name : existingTrackingCategory.name,
+    status: status ? TrackingCategory.StatusEnum[status] : existingTrackingCategory.status
+  };
+
+  await xeroClient.accountingApi.updateTrackingCategory(
+    xeroClient.tenantId,
+    trackingCategoryId,
+    trackingCategory,
+    undefined, // idempotencyKey
+    getClientHeaders()
+  );
+
+  return trackingCategory;
+}
+
+export async function updateXeroTrackingCategory(
+  trackingCategoryId: string,
+  name?: string,
+  status?: TrackingCategoryStatus
+): Promise<XeroClientResponse<TrackingCategory>> {
+  try {
+    const existingTrackingCategory = await getTrackingCategory(trackingCategoryId);
+
+    if (!existingTrackingCategory) {
+      throw new Error("Could not find tracking category.");
+    }
+
+    const updatedTrackingCategory = await updateTrackingCategory(
+      trackingCategoryId,
+      existingTrackingCategory,
+      name,
+      status
+    );
+
+    if (!updatedTrackingCategory) {
+      throw new Error("Failed to update tracking category.");
+    }
+
+    return {
+      result: existingTrackingCategory,
+      isError: false,
+      error: null
+    };
+  } catch (error) {
+    return {
+      result: null,
+      isError: true,
+      error: formatError(error),
+    };
+  }
+}

src/handlers/update-xero-tracking-options.handler.ts

@@ -0,0 +1,91 @@
+import { TrackingOption } from "xero-node";
+import { xeroClient } from "../clients/xero-client.js";
+import { formatError } from "../helpers/format-error.js";
+import { getClientHeaders } from "../helpers/get-client-headers.js";
+import { XeroClientResponse } from "../types/tool-response.js";
+
+type TrackingOptionStatus = "ACTIVE" | "ARCHIVED";
+
+interface TrackingOptionItem {
+  trackingOptionId: string,
+  name?: string,
+  status?: TrackingOptionStatus
+}
+
+async function getTrackingOptions(trackingCategoryId: string): Promise<TrackingOption[] | undefined> {
+  await xeroClient.authenticate();
+
+  const response = await xeroClient.accountingApi.getTrackingCategory(
+    xeroClient.tenantId,
+    trackingCategoryId,
+    getClientHeaders()
+  );
+
+  return response.body.trackingCategories?.[0].options;
+}
+
+async function updateTrackingOption(
+  trackingCategoryId: string,
+  trackingOptionId: string,
+  existingTrackingOption: TrackingOption,
+  name?: string,
+  status?: TrackingOptionStatus
+): Promise<TrackingOption | undefined> {
+  const trackingOption: TrackingOption = {
+    trackingOptionID: trackingOptionId,
+    name: name ? name : existingTrackingOption.name,
+    status: status ? TrackingOption.StatusEnum[status] : existingTrackingOption.status
+  };
+
+  await xeroClient.accountingApi.updateTrackingOptions(
+    xeroClient.tenantId,
+    trackingCategoryId,
+    trackingOptionId,
+    trackingOption,
+    undefined, // idempotencyKey
+    getClientHeaders()
+  );
+
+  return trackingOption;
+}
+
+export async function updateXeroTrackingOption(
+  trackingCategoryId: string,
+  options: TrackingOptionItem[]
+): Promise<XeroClientResponse<TrackingOption[]>> {
+  try {
+
+    const existingTrackingOptions = await getTrackingOptions(trackingCategoryId);
+
+    if (!existingTrackingOptions) {
+      throw new Error("Could not find tracking options.");
+    }
+
+    const updatedTrackingOptions = await Promise.all(options?.map(async (option) => {
+      const existingTrackingOption = existingTrackingOptions
+        .find(existingOption => existingOption.trackingOptionID === option.trackingOptionId);
+
+      return existingTrackingOption
+        ? await updateTrackingOption(trackingCategoryId, option.trackingOptionId, existingTrackingOption, option.name, option.status)
+        : undefined;
+    }));
+
+    if (!updatedTrackingOptions) {
+      throw new Error("Failed to update tracking options.");
+    }
+
+    return {
+      result: updatedTrackingOptions
+        .filter(Boolean)
+        .map(option => option as TrackingOption),
+      isError: false,
+      error: null
+    };
+  } catch (error) {
+    return {
+      result: null,
+      isError: true,
+      error: formatError(error),
+    };
+  }
+}

src/helpers/format-tracking-option.ts

@@ -0,0 +1,9 @@
+import { TrackingOption } from "xero-node";
+
+export const formatTrackingOption = (option: TrackingOption): string => {
+  return [
+    `Option ID: ${option.trackingOptionID}`,
+    `Name: ${option.name}`,
+    `Status: ${option.status}`
+  ].join("\n");
+};

src/tools/create/create-tracking-category.tool.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { CreateXeroTool } from "../../helpers/create-xero-tool.js";
+import { createXeroTrackingCategory } from "../../handlers/create-xero-tracking-category.handler.js";
+
+const CreateTrackingCategoryTool = CreateXeroTool(
+  "create-tracking-category",
+  `Create a tracking category in Xero.`,
+  {
+    name: z.string()
+  },
+  async ({ name }) => {
+    const response = await createXeroTrackingCategory(name);
+
+    if (response.isError) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Error while creating tracking category: ${response.error}`
+          }
+        ]
+      };
+    }
+
+    const trackingCategory = response.result;
+    
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Created the tracking category "${trackingCategory.name}" (${trackingCategory.trackingCategoryID}).`
+        },
+      ]
+    };
+  }
+);
+
+export default CreateTrackingCategoryTool;