create_invoice

Instructions

Implementation Reference

• typescript/src/shared/invoices/createInvoice.ts:41-85 (handler)

  The main handler function that executes the create_invoice tool logic. It accepts parameters validated by createInvoiceParameters, constructs a request object with merchantId, customer info, order info, and invoice info, then calls the CyberSource InvoicesApi.createInvoice() API. Returns masked result via maskInvoiceCustomerInfo helper.

  export const createInvoice = async (
    visaClient: any,
    context: VisaContext,
    params: z.infer<ReturnType<typeof createInvoiceParameters>>
  ) => {
    try {
      const invoiceApiInstance = new cybersourceRestApi.InvoicesApi(visaClient.configuration, visaClient.visaApiClient);
      
      const requestObj = {
        merchantId: context.merchantId,
        customerInformation: {
          name: params.customerName,
          email: params.customerEmail
        },
        orderInformation: {
          amountDetails: {
            totalAmount: params.totalAmount,
            currency: params.currency
          }
        },
        invoiceInformation: {
          description: params.invoiceInformation?.description,
          dueDate: params.invoiceInformation?.dueDate || new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0],
          invoiceNumber: params.invoice_number,
          sendImmediately: params.invoiceInformation?.sendImmediately !== undefined ? params.invoiceInformation.sendImmediately : true,
          deliveryMode: params.invoiceInformation?.deliveryMode || 'email'
        }
      };
      
      const result = await new Promise((resolve, reject) => {
        invoiceApiInstance.createInvoice(requestObj, (error: any, data: any) => {
          if (error) {
            reject(error);
          } else {
            resolve(data);
          }
        });
      });
      
      const maskedResult = maskInvoiceCustomerInfo(result);
      return maskedResult;
    } catch (error) {
      return 'Failed to create invoice';
    }
  };

• typescript/src/shared/invoices/createInvoice.ts:19-35 (schema)

  Zod schema defining the input parameters for create_invoice tool: invoice_number (string), totalAmount (string), currency (string), customerName (optional string), customerEmail (optional string), and invoiceInformation object (description, dueDate, sendImmediately, deliveryMode).

  export const createInvoiceParameters = (
    context: VisaContext = {} as VisaContext
  ) => {
    return z.object({
      invoice_number: z.string().describe('Unique invoice number (letters & numbers only, <20 chars)'),
      totalAmount: z.string().describe('Invoice total amount e.g. "100.00"'),
      currency: z.string().describe('Invoice currency code e.g. "USD"'),
      customerName: z.string().optional().describe('Customer name for invoice'),
      customerEmail: z.string().optional().describe('Customer email for invoice'),
      invoiceInformation: z.object({
        description: z.string().describe('Short invoice description (max 50 characters)'),
        dueDate: z.string().describe('Due date in YYYY-MM-DD format'),
        sendImmediately: z.boolean().describe('Whether to send the invoice immediately'),
        deliveryMode: z.string().describe('Delivery mode e.g. "email"')
      }).required().describe('Invoice information object'),
    });
  };

• typescript/src/shared/invoices/createInvoice.ts:87-98 (registration)

  Registration of the create_invoice tool as a Tool object with method 'create_invoice', name 'Create Invoice', description, parameters, actions, and execute handler. Exported as default and imported into tools.ts where it's added to the tools array.

  const tool = (context: VisaContext): Tool => ({
    method: 'create_invoice',
    name: 'Create Invoice',
    description: createInvoicePrompt(context),
    parameters: createInvoiceParameters(context),
    actions: {
      invoices: {
        create: true,
      },
    },
    execute: createInvoice,
  });

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

  The create_invoice tool module is imported from './invoices/createInvoice' and added to the array of tools returned by the createTools function.

  createInvoiceToolModule(context),

• typescript/src/shared/utils/util.ts:89-118 (helper)

  Helper function maskInvoiceCustomerInfo that masks PII (name and email) in the invoice result returned by the create_invoice handler, using maskPII utility to preserve privacy.

  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';
    }
  };