cancel_invoice

Instructions

Implementation Reference

• typescript/src/shared/invoices/cancelInvoice.ts:28-54 (handler)

  The main handler function for cancel_invoice. It uses cybersource-rest-client InvoicesApi to call performCancelAction with the invoice_id parameter, then masks customer info before returning the result.

  export const cancelInvoice = async (
    visaClient: any,
    context: VisaContext,
    params: z.infer<ReturnType<typeof cancelInvoiceParameters>>
  ) => {
    try {
      const invoiceApiInstance = new cybersourceRestApi.InvoicesApi(visaClient.configuration, visaClient.visaApiClient);
      
      const result = await new Promise((resolve, reject) => {
        invoiceApiInstance.performCancelAction(params.invoice_id, (error: any, data: any, response: any) => {
          if (error) {
            reject(error);
          } else {
            resolve({
              data,
              status: response['status']
            });
          }
        });
      });
      
      const maskedResult = maskInvoiceCustomerInfo(result);
      return maskedResult;
    } catch (error) {
      return 'Failed to cancel invoice';
    }
  };

• typescript/src/shared/invoices/cancelInvoice.ts:16-22 (schema)

  Input parameter schema for cancel_invoice tool. Defines a required 'invoice_id' string parameter using Zod validation.

  export const cancelInvoiceParameters = (
    context: VisaContext = {} as VisaContext
  ) => {
    return z.object({
      invoice_id: z.string().describe('Invoice ID (required)')
    });
  };

• typescript/src/shared/invoices/cancelInvoice.ts:58-71 (registration)

  Tool registration object for cancel_invoice. Sets method to 'cancel_invoice', name to 'Cancel Invoice', provides description, parameters, and links the execute function.

  const tool = (context: VisaContext): Tool => ({
    method: 'cancel_invoice',
    name: 'Cancel Invoice',
    description: cancelInvoicePrompt(context),
    parameters: cancelInvoiceParameters(context),
    actions: {
      invoices: {
        update: true,
      },
    },
    execute: cancelInvoice,
  });
  
  export default tool;

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

  Aggregation of all tools including cancelInvoiceToolModule in the createTools function which assembles the list of all available tools.

  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:89-118 (helper)

  Helper function maskInvoiceCustomerInfo used by the cancel_invoice handler to mask PII (name and email) in the invoice customer information before returning the response.

  export const maskInvoiceCustomerInfo = (
    invoice: any,
    context?: Context
  ): any => {
    try {
      if (!invoice) return invoice;
      
      const maskedInvoice = JSON.parse(JSON.stringify(invoice));
      
      if (maskedInvoice.customerInformation) {
        if (maskedInvoice.customerInformation.name) {
          maskedInvoice.customerInformation.name = maskPII(maskedInvoice.customerInformation.name, 'end');
        }
        
        if (maskedInvoice.customerInformation.email) {
          const emailParts = maskedInvoice.customerInformation.email.split('@');
          if (emailParts.length === 2) {
            const maskedLocalPart = maskPII(emailParts[0], 'end');
            maskedInvoice.customerInformation.email = `${maskedLocalPart}@${emailParts[1]}`;
          } else {
            maskedInvoice.customerInformation.email = maskPII(maskedInvoice.customerInformation.email, 'end');
          }
        }
      }
      
      return maskedInvoice;
    } catch (error) {
      return 'Failed to mask invoice customer information';
    }
  };