get-upnify-conversion-report

Instructions

Implementation Reference

• handlers/reports.ts:125-159 (handler)

  The main handler function that authenticates using UpnifyAuthenticator, constructs query parameters from input (agrupacion, periodo, situacion), fetches the conversion report from the Upnify API endpoint, handles errors, and returns a formatted success response with the data.

  async getConversionReport(tkIntegracion: string, params: ConversionReportParams) {
      try {
          const { token, userInfo } = await this.auth.getTokenAndUserInfo(tkIntegracion);
          
          const queryParams = new URLSearchParams({
              agrupacion: params.agrupacion.toString(),
              periodo: params.periodo.toString(),
              situacion: params.situacion.toString()
          });
          
          const response = await fetch(`${API_URLS.UPNIFY_BASE}${ENDPOINTS.REPORTS.CONVERSIONS}?${queryParams}`, {
              method: 'GET',
              headers: {
                  'token': token,
                  'Content-Type': 'application/json',
              }
          });
          
          if (!response.ok) {
              const errorText = await response.text();
              throw new Error(`Error al obtener reporte de conversiones: ${response.status} ${response.statusText}. ${errorText}`);
          }
          
          const result = await response.json();
          return {
              success: true,
              message: 'Reporte de conversiones obtenido exitosamente',
              data: result,
              parameters: params,
              tkEmpresa: userInfo.tkEmpresa
          };
      } catch (error) {
          throw new Error(`Error al obtener reporte de conversiones de Upnify: ${error instanceof Error ? error.message : error}`);
      }
  }

• types/interfaces.ts:49-53 (schema)

  TypeScript interface defining the expected input parameters for the get-upnify-conversion-report tool.

  export interface ConversionReportParams {
      agrupacion: number;
      periodo: number;
      situacion: number;
  }

• main.ts:443-457 (registration)

  Registration and dispatch logic in the CallToolRequest handler that validates input parameters using validateConversionReportParams and calls the reportsHandler.getConversionReport method.

  } else if (name === 'get-upnify-conversion-report') {
      const params = args as any;
      if (!validateConversionReportParams(params)) {
          return createErrorResponse(
              new Error('Se requieren todos los parámetros: agrupacion, periodo, situacion'),
              'Validación de parámetros'
          );
      }
  
      try {
          const result = await reportsHandler.getConversionReport(tkIntegracion, params);
          return createSuccessResponse(result);
      } catch (error) {
          return createErrorResponse(error, 'Error al obtener reporte de conversiones de Upnify');
      }

• main.ts:276-302 (registration)

  Tool registration in ListToolsRequestHandler, including name, description, and inputSchema definition matching the ConversionReportParams type.

      name: 'get-upnify-conversion-report',
      description: 'Get conversion report from Upnify by group, executive, origin, or region and period',
      inputSchema: {
          type: 'object',
          properties: {
              agrupacion: { 
                  type: 'integer', 
                  description: 'Group by: 1=Executive, 2=Group, 3=Origin, 4=Region', 
                  enum: [1, 2, 3, 4], 
                  default: 2 
              },
              periodo: { 
                  type: 'integer', 
                  description: 'Period for report filtering. Options: 1=Today, 2=Yesterday, 3=Current week, 4=Last week, 5=Current month, 6=Last month, 8=Current year, 10=Last year, 13=Current semester, 14=Last semester, 17=Current quarter, 18=Last quarter.', 
                  enum: [1, 2, 3, 4, 5, 6, 8, 10, 13, 14, 17, 18], 
                  default: 5 
              },
              situacion: { 
                  type: 'integer', 
                  description: 'Situation: 0=Include discarded, 1=Exclude discarded', 
                  enum: [0, 1], 
                  default: 0 
              }
          },
          required: ['agrupacion', 'periodo', 'situacion']
      }
  }

• utils/validators.ts:47-53 (helper)

  Type guard function used to validate that input parameters include all required fields for the conversion report.

  export function validateConversionReportParams(params: any): params is ConversionReportParams {
      return (
          params.agrupacion !== undefined &&
          params.periodo !== undefined &&
          params.situacion !== undefined
      );
  }