Add item and tracking support to invoices

Author: TheRegan

src/consts/deeplinks.ts

@@ -28,3 +28,7 @@ export const bankTransactionDeepLink = (accountId: string, bankTransactionId: st
 export const manualJournalDeepLink = (journalId: string) => {
   return `https://go.xero.com/Journal/View.aspx?invoiceID=${journalId}`;
 };
+
+export const billDeepLink = (orgShortCode: string, billId: string) => {
+  return `https://go.xero.com/organisationlogin/default.aspx?shortcode=${orgShortCode}&redirecturl=/AccountsPayable/Edit.aspx?InvoiceID=${billId}`;
+};

src/handlers/create-xero-invoice.handler.ts

@@ -1,7 +1,7 @@
 import { xeroClient } from "../clients/xero-client.js";
 import { XeroClientResponse } from "../types/tool-response.js";
 import { formatError } from "../helpers/format-error.js";
-import { Invoice } from "xero-node";
+import { Invoice, LineItemTracking } from "xero-node";
 import { getClientHeaders } from "../helpers/get-client-headers.js";
 
 interface InvoiceLineItem {
@@ -10,17 +10,20 @@ interface InvoiceLineItem {
   unitAmount: number;
   accountCode: string;
   taxType: string;
+  itemCode?: string;
+  tracking?: LineItemTracking[];
 }
 
 async function createInvoice(
   contactId: string,
   lineItems: InvoiceLineItem[],
+  type: Invoice.TypeEnum,
   reference: string | undefined,
 ): Promise<Invoice | undefined> {
   await xeroClient.authenticate();
 
   const invoice: Invoice = {
-    type: Invoice.TypeEnum.ACCREC,
+    type: type,
     contact: {
       contactID: contactId,
     },
@@ -53,10 +56,16 @@ async function createInvoice(
 export async function createXeroInvoice(
   contactId: string,
   lineItems: InvoiceLineItem[],
+  type: Invoice.TypeEnum = Invoice.TypeEnum.ACCREC,
   reference?: string,
 ): Promise<XeroClientResponse<Invoice>> {
   try {
-    const createdInvoice = await createInvoice(contactId, lineItems, reference);
+    const createdInvoice = await createInvoice(
+      contactId,
+      lineItems,
+      type,
+      reference,
+    );
 
     if (!createdInvoice) {
       throw new Error("Invoice creation failed.");

src/handlers/update-xero-invoice.handler.ts

@@ -1,7 +1,7 @@
 import { xeroClient } from "../clients/xero-client.js";
 import { XeroClientResponse } from "../types/tool-response.js";
 import { formatError } from "../helpers/format-error.js";
-import { Invoice } from "xero-node";
+import { Invoice, LineItemTracking } from "xero-node";
 import { getClientHeaders } from "../helpers/get-client-headers.js";
 
 interface InvoiceLineItem {
@@ -10,6 +10,8 @@ interface InvoiceLineItem {
   unitAmount: number;
   accountCode: string;
   taxType: string;
+  itemCode?: string;
+  tracking?: LineItemTracking[];
 }
 
 async function getInvoice(invoiceId: string): Promise<Invoice | undefined> {

src/helpers/format-line-item.ts

@@ -2,10 +2,14 @@ import { LineItem } from "xero-node";
 
 export const formatLineItem = (lineItem: LineItem): string => {
   return [
+    `Item ID: ${lineItem.item}`,
+    `Item Code: ${lineItem.itemCode}`,
     `Description: ${lineItem.description}`,
     `Quantity: ${lineItem.quantity}`,
     `Unit Amount: ${lineItem.unitAmount}`,
     `Account Code: ${lineItem.accountCode}`,
     `Tax Type: ${lineItem.taxType}`,
+    `Tracking: ${lineItem.tracking}`,
+    `Line Amount: ${lineItem.lineAmount}`,
   ].join("\n");
 };

src/helpers/get-deeplink.ts

@@ -6,6 +6,7 @@ import {
   paymentDeepLink,
   manualJournalDeepLink,
   quoteDeepLink,
+  billDeepLink,
 } from "../consts/deeplinks.js";
 
 export enum DeepLinkType {
@@ -15,6 +16,7 @@ export enum DeepLinkType {
   MANUAL_JOURNAL,
   QUOTE,
   PAYMENT,
+  BILL,
 }
 
 /**
@@ -44,5 +46,7 @@ export const getDeepLink = async (type: DeepLinkType, itemId: string) => {
       return quoteDeepLink(orgShortCode, itemId);
     case DeepLinkType.PAYMENT:
       return paymentDeepLink(orgShortCode, itemId);
+    case DeepLinkType.BILL:
+      return billDeepLink(orgShortCode, itemId);
   }
 };

src/tools/create/create-invoice.tool.ts

@@ -2,13 +2,26 @@ import { z } from "zod";
 import { createXeroInvoice } from "../../handlers/create-xero-invoice.handler.js";
 import { DeepLinkType, getDeepLink } from "../../helpers/get-deeplink.js";
 import { CreateXeroTool } from "../../helpers/create-xero-tool.js";
+import { Invoice } from "xero-node";
+
+const trackingSchema = z.object({
+  name: z.string().describe("The name of the tracking category. Can be obtained from the list-tracking-categories tool"),
+  option: z.string().describe("The name of the tracking option. Can be obtained from the list-tracking-categories tool"),
+  trackingCategoryID: z.string().describe("The ID of the tracking category. \
+    Can be obtained from the list-tracking-categories tool"),
+});
 
 const lineItemSchema = z.object({
-  description: z.string(),
-  quantity: z.number(),
-  unitAmount: z.number(),
-  accountCode: z.string(),
-  taxType: z.string(),
+  description: z.string().describe("The description of the line item"),
+  quantity: z.number().describe("The quantity of the line item"),
+  unitAmount: z.number().describe("The price per unit of the line item"),
+  accountCode: z.string().describe("The account code of the line item - can be obtained from the list-accounts tool"),
+  taxType: z.string().describe("The tax type of the line item - can be obtained from the list-tax-rates tool"),
+  itemCode: z.string().describe("The item code of the line item - can be obtained from the list-items tool \
+    If the item is not listed, add without an item code and ask the user if they would like to add an item code.").optional(),
+  tracking: z.array(trackingSchema).describe("Up to 2 tracking categories and options can be added to the line item. \
+    Can be obtained from the list-tracking-categories tool. \
+    Only use if prompted by the user.").optional(),
 });
 
 const CreateInvoiceTool = CreateXeroTool(
@@ -18,12 +31,18 @@ const CreateInvoiceTool = CreateXeroTool(
  This deep link can be used to view the invoice in Xero directly. \
  This link should be displayed to the user.",
   {
-    contactId: z.string(),
+    contactId: z.string().describe("The ID of the contact to create the invoice for. \
+      Can be obtained from the list-contacts tool."),
     lineItems: z.array(lineItemSchema),
-    reference: z.string().optional(),
+    type: z.enum(["ACCREC", "ACCPAY"]).describe("The type of invoice to create. \
+      ACCREC is for sales invoices, Accounts Receivable, or customer invoices. \
+      ACCPAY is for purchase invoices, Accounts Payable invoices, supplier invoices, or bills. \
+      If the type is not specified, the default is ACCREC."),
+    reference: z.string().describe("A reference number for the invoice.").optional(),
   },
-  async ({ contactId, lineItems, reference }) => {
-    const result = await createXeroInvoice(contactId, lineItems, reference);
+  async ({ contactId, lineItems, type, reference }) => {
+    const xeroInvoiceType = type === "ACCREC" ? Invoice.TypeEnum.ACCREC : Invoice.TypeEnum.ACCPAY;
+    const result = await createXeroInvoice(contactId, lineItems, xeroInvoiceType, reference);
     if (result.isError) {
       return {
         content: [
@@ -38,7 +57,10 @@ const CreateInvoiceTool = CreateXeroTool(
     const invoice = result.result;
 
     const deepLink = invoice.invoiceID
-      ? await getDeepLink(DeepLinkType.INVOICE, invoice.invoiceID)
+      ? await getDeepLink(
+          invoice.type === Invoice.TypeEnum.ACCREC ? DeepLinkType.INVOICE : DeepLinkType.BILL,
+          invoice.invoiceID,
+        )
       : null;
 
     return {
@@ -49,6 +71,7 @@ const CreateInvoiceTool = CreateXeroTool(
             "Invoice created successfully:",
             `ID: ${invoice?.invoiceID}`,
             `Contact: ${invoice?.contact?.name}`,
+            `Type: ${invoice?.type}`,
             `Total: ${invoice?.total}`,
             `Status: ${invoice?.status}`,
             deepLink ? `Link to view: ${deepLink}` : null,

src/tools/update/update-invoice.tool.ts

@@ -3,12 +3,25 @@ import { updateXeroInvoice } from "../../handlers/update-xero-invoice.handler.js
 import { DeepLinkType, getDeepLink } from "../../helpers/get-deeplink.js";
 import { CreateXeroTool } from "../../helpers/create-xero-tool.js";
 
+const trackingSchema = z.object({
+  name: z.string().describe("The name of the tracking category. Can be obtained from the list-tracking-categories tool"),
+  option: z.string().describe("The name of the tracking option. Can be obtained from the list-tracking-categories tool"),
+  trackingCategoryID: z.string().describe("The ID of the tracking category. \
+    Can be obtained from the list-tracking-categories tool"),
+});
+
 const lineItemSchema = z.object({
-  description: z.string(),
-  quantity: z.number(),
-  unitAmount: z.number(),
-  accountCode: z.string(),
-  taxType: z.string(),
+  description: z.string().describe("The description of the line item"),
+  quantity: z.number().describe("The quantity of the line item"),
+  unitAmount: z.number().describe("The price per unit of the line item"),
+  accountCode: z.string().describe("The account code of the line item - can be obtained from the list-accounts tool"),
+  taxType: z.string().describe("The tax type of the line item - can be obtained from the list-tax-rates tool"),
+  itemCode: z.string().describe("The item code of the line item - can be obtained from the list-items tool \
+    If the item was not populated in the original invoice, \
+    add without an item code unless the user has told you to add an item code.").optional(),
+  tracking: z.array(trackingSchema).describe("Up to 2 tracking categories and options can be added to the line item. \
+    Can be obtained from the list-tracking-categories tool. \
+    Only use if prompted by the user.").optional(),
 });
 
 const UpdateInvoiceTool = CreateXeroTool(
@@ -20,15 +33,16 @@ const UpdateInvoiceTool = CreateXeroTool(
  This deep link can be used to view the contact in Xero directly. \
  This link should be displayed to the user.",
   {
-    invoiceId: z.string(),
+    invoiceId: z.string().describe("The ID of the invoice to update."),
     lineItems: z.array(lineItemSchema).optional().describe(
       "All line items must be provided. Any line items not provided will be removed. Including existing line items. \
       Do not modify line items that have not been specified by the user",
     ),
-    reference: z.string().optional(),
-    dueDate: z.string().optional(),
-    date: z.string().optional(),
-    contactId: z.string().optional(),
+    reference: z.string().optional().describe("A reference number for the invoice."),
+    dueDate: z.string().optional().describe("The due date of the invoice."),
+    date: z.string().optional().describe("The date of the invoice."),
+    contactId: z.string().optional().describe("The ID of the contact to update the invoice for. \
+      Can be obtained from the list-contacts tool."),
   },
   async (
     {
@@ -87,6 +101,7 @@ const UpdateInvoiceTool = CreateXeroTool(
             "Invoice updated successfully:",
             `ID: ${invoice?.invoiceID}`,
             `Contact: ${invoice?.contact?.name}`,
+            `Type: ${invoice?.type}`,
             `Total: ${invoice?.total}`,
             `Status: ${invoice?.status}`,
             deepLink ? `Link to view: ${deepLink}` : null,