get_invoice_payments_by_invoice_id

Instructions

Implementation Reference

• src/tools/payments.ts:21-33 (handler)

  The handler function for the 'get_invoice_payments_by_invoice_id' tool. It calls apiList with path `/invoices/${invoice_id}/payments`, logs the response, formats the results with pagination cursor support, and returns them.

  async ({ invoice_id, cursor, per_page }) => {
    try {
      const result = await apiList<EduframeRecord>(`/invoices/${invoice_id}/payments`, { cursor, per_page });
      void logResponse("get_invoice_payments_by_invoice_id", { invoice_id, cursor, per_page }, result);
      const toolResult = formatList(result.records, "payments");
      if (result.nextCursor) {
        toolResult.content.push({ type: "text", text: `\nNext page cursor: ${result.nextCursor}` });
      }
      return toolResult;
    } catch (error) {
      return formatError(error);
    }
  },

• src/tools/payments.ts:15-19 (schema)

  Input schema for the tool: requires invoice_id (positive int), optional cursor (string), and optional per_page (positive int).

  inputSchema: {
    invoice_id: z.number().int().positive().describe("ID of the parent resource"),
    cursor: z.string().optional().describe("Cursor for fetching the next page of results"),
    per_page: z.number().int().positive().optional().describe("Number of results per page (default: 25)"),
  },

• src/tools/payments.ts:9-34 (registration)

  Registration of the tool via server.registerTool() with name 'get_invoice_payments_by_invoice_id', description, annotations, input schema, and handler. The registerPaymentTools function is exported and called from src/tools/index.ts.

  export function registerPaymentTools(server: McpServer): void {
    server.registerTool(
      "get_invoice_payments_by_invoice_id",
      {
        description: "Get all payment records of an invoice",
        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
        inputSchema: {
          invoice_id: z.number().int().positive().describe("ID of the parent resource"),
          cursor: z.string().optional().describe("Cursor for fetching the next page of results"),
          per_page: z.number().int().positive().optional().describe("Number of results per page (default: 25)"),
        },
      },
      async ({ invoice_id, cursor, per_page }) => {
        try {
          const result = await apiList<EduframeRecord>(`/invoices/${invoice_id}/payments`, { cursor, per_page });
          void logResponse("get_invoice_payments_by_invoice_id", { invoice_id, cursor, per_page }, result);
          const toolResult = formatList(result.records, "payments");
          if (result.nextCursor) {
            toolResult.content.push({ type: "text", text: `\nNext page cursor: ${result.nextCursor}` });
          }
          return toolResult;
        } catch (error) {
          return formatError(error);
        }
      },
    );

• src/tools/index.ts:102-102 (registration)

  The registerPaymentTools function is included in the tools array in src/tools/index.ts, which is iterated by registerAllTools() to register all tools with the server.

  registerPaymentTools,

• src/api.ts:122-137 (helper)

  The apiList helper function used by the handler to perform a GET request to a paginated list endpoint and return records with a nextCursor.

  export async function apiList<T>(path: string, query?: Record<string, QueryValue>): Promise<ListResult<T>> {
    const { token } = getConfig();
    const url = buildUrl(path, query);
  
    const response = await fetch(url.toString(), {
      method: "GET",
      headers: buildHeaders(token),
    });
  
    await checkResponse(response);
  
    const records = (await response.json()) as T[];
    const nextCursor = parseNextCursor(response.headers.get("Link"));
  
    return { records, nextCursor };
  }