Get Repayments

Instructions

Implementation Reference

• src/tools/repayments/getRepayments.ts:25-147 (handler)

  Main handler function that registers and implements the getRepayments tool. Calls the API client, formats repayment data with status icons and amount, handles pagination, and returns formatted text response.

  export function registerGetRepaymentsTool(server: McpServer): void {
    // Create API client instance
  
    // Register getRepayments tool
    server.registerTool(
      "getRepayments",
      {
        title: "Get Repayments",
        description:
          "Retrieves customer repayments with AWB details, amounts, and delivery status. Parameters: page (number), order_id (number - optional filter)",
        inputSchema: {
          page: z
            .number()
            .int()
            .min(1)
            .max(1000)
            .optional()
            .describe("Page number for pagination (1-1000, default: 1)"),
          order_id: z
            .number()
            .int()
            .min(1)
            .optional()
            .describe("Filter repayments by specific order ID (optional)"),
        },
      },
      async (args: any) => {
        // Get API key from async context
        const apiKey = apiKeyStorage.getStore();
  
        if (!apiKey) {
          return {
            content: [
              {
                type: "text",
                text: "Error: X-API-KEY header is required",
              },
            ],
          };
        }
  
        // Create API client with customer's API key
        const client = new EuroparcelApiClient(apiKey);
  
        try {
          logger.info("Fetching repayments", args);
  
          const response = await client.getRepayments({
            page: args.page,
            order_id: args.order_id,
          });
  
          logger.info(`Retrieved ${response.list.length} repayments`);
  
          let formattedResponse = `Found ${response.pagination.total} total repayments`;
  
          if (args.order_id) {
            formattedResponse += ` for order #${args.order_id}`;
          }
  
          formattedResponse += `\nPage ${response.pagination.current_page} of ${response.pagination.last_page}\n\n`;
  
          if (response.list.length === 0) {
            formattedResponse += "No repayments found.";
          } else {
            response.list.forEach((repayment: Repayment) => {
              formattedResponse += `📦 AWB: ${repayment.awb}\n`;
              formattedResponse += `   Order ID: ${repayment.order_id}\n`;
              formattedResponse += `   Carrier: ${repayment.carrier_name || repayment.carrier_id}\n`;
              formattedResponse += `   Recipient: ${repayment.recipient_name || "N/A"}\n`;
              formattedResponse += `   Amount: ${formatAmount(repayment.repayment_amount, repayment.repayment_currency)}\n`;
              formattedResponse += `   Status: ${formatStatus(repayment.status)}\n`;
  
              if (repayment.delivered_at) {
                formattedResponse += `   Delivered: ${repayment.delivered_at}\n`;
              }
  
              if (repayment.payout_id) {
                formattedResponse += `   Payout ID: ${repayment.payout_id}\n`;
                if (repayment.bank_iban) {
                  formattedResponse += `   Bank: ${repayment.bank_holder || "N/A"} - ${repayment.bank_iban}\n`;
                }
              }
  
              formattedResponse += "\n";
            });
  
            // Add pagination info if there are more pages
            if (response.pagination.last_page > 1) {
              formattedResponse += `\nShowing ${response.list.length} of ${response.pagination.total} repayments`;
              if (
                response.pagination.current_page < response.pagination.last_page
              ) {
                formattedResponse += `\nUse page: ${response.pagination.current_page + 1} to see more`;
              }
            }
          }
  
          return {
            content: [
              {
                type: "text",
                text: formattedResponse,
              },
            ],
          };
        } catch (error: any) {
          logger.error("Failed to fetch repayments", error);
  
          return {
            content: [
              {
                type: "text",
                text: `Error fetching repayments: ${error.message || "Unknown error"}`,
              },
            ],
          };
        }
      },
    );
  
    logger.info("getRepayments tool registered successfully");
  }

• src/tools/repayments/getRepayments.ts:31-50 (schema)

  Input schema for the getRepayments tool: page (optional, 1-1000) and order_id (optional, integer). Defined inline in the tool registration.

  {
    title: "Get Repayments",
    description:
      "Retrieves customer repayments with AWB details, amounts, and delivery status. Parameters: page (number), order_id (number - optional filter)",
    inputSchema: {
      page: z
        .number()
        .int()
        .min(1)
        .max(1000)
        .optional()
        .describe("Page number for pagination (1-1000, default: 1)"),
      order_id: z
        .number()
        .int()
        .min(1)
        .optional()
        .describe("Filter repayments by specific order ID (optional)"),
    },
  },

• src/tools/repayments/getRepayments.ts:9-18 (helper)

  Helper function to format repayment status with emoji icons (pending, processing, paid, cancelled, failed).

  function formatStatus(status: string): string {
    const statusMap: Record<string, string> = {
      pending: "⏳ Pending",
      processing: "🔄 Processing",
      paid: "✅ Paid",
      cancelled: "❌ Cancelled",
      failed: "⚠️ Failed",
    };
    return statusMap[status] || status;
  }

• src/tools/repayments/getRepayments.ts:21-23 (helper)

  Helper function to format currency amounts with 2 decimal places and currency code.

  function formatAmount(amount: number, currency: string): string {
    return `${amount.toFixed(2)} ${currency}`;
  }

• src/types/index.ts:160-193 (schema)

  TypeScript interfaces: Repayment (order repayment details), RepaymentListResponse (paginated response with list and pagination metadata).

  export interface Repayment {
    awb: string;
    order_id: number;
    carrier_id: string;
    carrier_name: string | null;
    repayment_amount: number;
    repayment_currency: string;
    status: "pending" | "paid" | "cancelled";
    payout_id: number | null;
    bank_iban: string | null;
    bank_holder: string | null;
    recipient_name: string | null;
    delivered_at: string | null;
  }
  
  export interface PayoutReport {
    payout_id: number;
    bank_holder: string | null;
    bank_iban: string | null;
    repayment_amount: number;
    repayment_currency: string;
    status: "pending" | "processing" | "paid" | "failed" | "cancelled";
    paid_at: string | null;
  }
  
  export interface RepaymentListResponse {
    list: Repayment[];
    pagination: {
      total: number;
      per_page: number;
      current_page: number;
      last_page: number;
    };
  }

• src/tools/repayments/index.ts:6-14 (registration)

  Registration funnel: registerRepaymentTools calls registerGetRepaymentsTool which is re-exported.

  export function registerRepaymentTools(server: McpServer): void {
    logger.info("Registering repayment tools...");
  
    // Register all repayment-related tools
    registerGetRepaymentsTool(server);
    registerGetPayoutReportsTool(server);
  
    logger.info("All repayment tools registered successfully");
  }

• src/server.ts:22-22 (registration)

  Top-level registration: registerRepaymentTools(server) is called in createServer().

  registerRepaymentTools(server);