list_invoices

Instructions

Implementation Reference

• typescript/src/shared/invoices/listInvoices.ts:31-67 (handler)

  The main handler function for the list_invoices tool. Uses CyberSource InvoicesApi.getAllInvoices to fetch invoices with offset, limit, and optional status filter. Results are masked via maskInvoicesCustomerInfo.

  export const listInvoices = async (
    visaClient: any,
    context: VisaContext,
    params: z.infer<ReturnType<typeof listInvoicesParameters>>
  ) => {
    try {
      const invoiceApiInstance = new cybersourceRestApi.InvoicesApi(visaClient.configuration, visaClient.visaApiClient);
      const opts: { status?: string } = {};
      if (params.status != null && params.status !== '') {
        opts.status = params.status;
      }
      console.log('Sending request with params:', JSON.stringify({ offset: params.offset, limit: params.limit, opts }));
      const result = await new Promise((resolve, reject) => {
        invoiceApiInstance.getAllInvoices(
          params.offset,
          params.limit,
          opts,
          (error: any, data: any, response: any) => {
            if (error) {
              console.error('Error in listInvoices:', JSON.stringify(error));
              reject(error);
            } else {
              console.log('Response from getAllInvoices:', JSON.stringify(response));
              resolve(data);
            }
          }
        );
      });
      
      const typedResult = result as any;
      let maskedResult = maskInvoicesCustomerInfo(typedResult);
      return maskedResult;
    } catch (error) {
      console.error('Failed to list invoices:', error);
      return 'Failed to list invoices';
    }
  };

• typescript/src/shared/invoices/listInvoices.ts:17-25 (schema)

  Parameter schema for list_invoices using Zod: offset (number, required), limit (number, required), status (string, optional).

  export const listInvoicesParameters = (
    context: VisaContext = {} as VisaContext
  ) => {
    return z.object({
      offset: z.number().describe('Pagination offset (required)'),
      limit: z.number().describe('Pagination limit (required)'),
      status: z.string().optional().describe('Filter by status (optional)')
    });
  };

• typescript/src/shared/invoices/listInvoices.ts:71-84 (registration)

  Tool registration object that defines method 'list_invoices', name, description, parameters, actions (invoices:read), and the execute handler.

  const tool = (context: VisaContext): Tool => ({
    method: 'list_invoices',
    name: 'List Invoices',
    description: listInvoicesPrompt(context),
    parameters: listInvoicesParameters(context),
    actions: {
      invoices: {
        read: true,
      },
    },
    execute: listInvoices,
  });
  
  export default tool;

• typescript/src/shared/tools.ts:40-53 (registration)

  The createTools function that aggregates all tools including listInvoicesToolModule into an array for registration.

  export function createTools(context: VisaContext): Tool[] {
    return [
      createInvoiceToolModule(context),
      updateInvoiceToolModule(context),
      getInvoiceToolModule(context),
      listInvoicesToolModule(context),
      sendInvoiceToolModule(context),
      cancelInvoiceToolModule(context),
      createPaymentLinkToolModule(context),
      updatePaymentLinkToolModule(context),
      getPaymentLinkToolModule(context),
      listPaymentLinkToolModule(context)
    ];
  }

• typescript/src/shared/utils/util.ts:127-138 (helper)

  Helper that masks customer PII (name, email) in the invoices array returned by the list_invoices handler.

  export const maskInvoicesCustomerInfo = (
    invoices: any[],
    context?: Context
  ): any[] => {
    try {
      if (!invoices || !Array.isArray(invoices)) return invoices;
      
      return invoices.map(invoice => maskInvoiceCustomerInfo(invoice, context));
    } catch (error) {
      return [];
    }
  };