list-quotes

Instructions

Implementation Reference

• src/tools/list/list-quotes.tool.ts:16-74 (handler)

  Core handler logic for the 'list-quotes' tool: invokes the Xero quotes API handler, processes the response, and formats quotes into detailed text blocks for each quote.

  async ({ page, contactId, quoteNumber }) => {
    const response = await listXeroQuotes(page, contactId, quoteNumber);
    if (response.error !== null) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error listing quotes: ${response.error}`,
          },
        ],
      };
    }
  
    const quotes = response.result;
  
    return {
      content: [
        {
          type: "text" as const,
          text: `Found ${quotes?.length || 0} quotes:`,
        },
        ...(quotes?.map((quote) => ({
          type: "text" as const,
          text: [
            `Quote ID: ${quote.quoteID}`,
            `Quote Number: ${quote.quoteNumber}`,
            quote.reference ? `Reference: ${quote.reference}` : null,
            `Status: ${quote.status || "Unknown"}`,
            quote.contact
              ? `Contact: ${quote.contact.name} (${quote.contact.contactID})`
              : null,
            quote.dateString ? `Quote Date: ${quote.dateString}` : null,
            quote.expiryDateString
              ? `Expiry Date: ${quote.expiryDateString}`
              : null,
            quote.title ? `Title: ${quote.title}` : null,
            quote.summary ? `Summary: ${quote.summary}` : null,
            quote.terms ? `Terms: ${quote.terms}` : null,
            quote.lineAmountTypes
              ? `Line Amount Types: ${quote.lineAmountTypes}`
              : null,
            quote.subTotal ? `Sub Total: ${quote.subTotal}` : null,
            quote.totalTax ? `Total Tax: ${quote.totalTax}` : null,
            `Total: ${quote.total || 0}`,
            quote.totalDiscount
              ? `Total Discount: ${quote.totalDiscount}`
              : null,
            quote.currencyCode ? `Currency: ${quote.currencyCode}` : null,
            quote.currencyRate ? `Currency Rate: ${quote.currencyRate}` : null,
            quote.updatedDateUTC
              ? `Last Updated: ${quote.updatedDateUTC}`
              : null,
          ]
            .filter(Boolean)
            .join("\n"),
        })) || []),
      ],
    };
  },

• src/tools/list/list-quotes.tool.ts:12-15 (schema)

  Input schema for the 'list-quotes' tool using Zod: requires 'page' (number), optional 'contactId' and 'quoteNumber' (strings).

    page: z.number(),
    contactId: z.string().optional(),
    quoteNumber: z.string().optional(),
  },

• src/tools/list/index.ts:25-39 (registration)

  Import and registration of ListQuotesTool into the ListTools array, making it available for tool server registration.

  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 ListTrackingCategoriesTool from "./list-tracking-categories.tool.js";
  import ListTrialBalanceTool from "./list-trial-balance.tool.js";
  import ListContactGroupsTool from "./list-contact-groups.tool.js";
  
  export const ListTools = [
    ListAccountsTool,
    ListContactsTool,
    ListCreditNotesTool,
    ListInvoicesTool,
    ListItemsTool,
    ListManualJournalsTool,
    ListQuotesTool,

• src/handlers/list-xero-quotes.handler.ts:34-54 (helper)

  Helper function that fetches quotes from Xero API using the authenticated client, handles pagination, filtering by contact or number, and error formatting.

  export async function listXeroQuotes(
    page: number = 1,
    contactId?: string,
    quoteNumber?: string,
  ): Promise<XeroClientResponse<Quote[]>> {
    try {
      const quotes = await getQuotes(contactId, page, quoteNumber);
  
      return {
        result: quotes,
        isError: false,
        error: null,
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error),
      };
    }
  }