List transactions for a payment link

Instructions

Implementation Reference

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

  The registerAllTools function orchestrates registration of all tool modules, including registerLinkTools which registers deonpay_list_link_transactions.

  export function registerAllTools(server: McpServer, client: DeonpayClient): void {
    registerLinkTools(server, client);
    registerCheckoutTools(server, client);
    registerTransactionTools(server, client);
    registerProductTools(server, client);
    registerSubscriptionTools(server, client);
    registerCustomerSubscriptionTools(server, client);
    registerCustomerTools(server, client);
    registerMetricsTools(server, client);
  }

• src/server.ts:14-35 (registration)

  createServer builds the McpServer and calls registerAllTools to register all tools including the link transactions tool.

  export function createServer(config: Config): McpServer {
    const server = new McpServer(
      {
        name: "deonpay-mcp-server",
        version: config.version,
      },
      {
        capabilities: {
          tools: {},
        },
        instructions:
          "DeonPay MCP server. Use these tools to query payments, payment links, " +
          "subscriptions, customers and metrics for the authenticated merchant. " +
          "All amounts are in CENTAVOS (1 MXN = 100). Reads are safe; the writes " +
          "available in this build (create_link, create_checkout_session, " +
          "create_product, create_subscription, update_link, update_product) are " +
          "non-destructive — refunds, cancellations and deletions are not exposed.",
      },
    );
  
    const client = new DeonpayClient(config);
    registerAllTools(server, client);

• src/tools/links.ts:79-94 (handler)

  The deonpay_list_link_transactions tool registration. It is registered on the McpServer with input schema (id, page, limit). The handler calls client.get('/links/{id}/transactions') with compacted pagination params.

  server.registerTool(
    "deonpay_list_link_transactions",
    {
      title: "List transactions for a payment link",
      description:
        "List all transactions associated with a specific payment link. Use this when the user asks 'who paid for this link', 'how much did link X collect', or wants to inspect failed attempts on a single link. Returns paginated transactions with customer info, card brand/last_four, amount in centavos and status. The link can be referenced by UUID or short_code.",
      inputSchema: {
        id: z.string().min(1).describe("Link UUID or short_code."),
        page: PageSchema.optional(),
        limit: LimitSchema.optional(),
      },
    },
    safeHandler(async ({ id, page, limit }) => {
      return client.get(`/links/${encodeURIComponent(id)}/transactions`, compact({ page, limit }));
    }),
  );

• src/schemas/common.ts:8-14 (schema)

  PageSchema and LimitSchema define the reusable pagination input types used by deonpay_list_link_transactions.

  export const PageSchema = z
    .number()
    .int()
    .min(1)
    .default(1)
    .describe("Page number (1-based). Defaults to 1.");

• src/tools/_helpers.ts:57-91 (helper)

  safeHandler wraps the tool's async handler with try/catch, converting thrown errors to MCP-shaped error results. The compact helper strips undefined/null/empty values from the args before passing to the API.

  export function safeHandler<TArgs>(
    fn: (args: TArgs) => Promise<unknown>,
  ): (args: TArgs) => Promise<CallToolResult> {
    return async (args: TArgs) => {
      try {
        const value = await fn(args);
        return jsonResult(value);
      } catch (err) {
        return errorResult(err);
      }
    };
  }
  
  /**
   * Encodes the local part / full email for use in path segments. RFC 3986 says
   * `@` is reserved as a sub-delim, so encodeURIComponent is the safe choice.
   */
  export function encodePathSegment(value: string): string {
    return encodeURIComponent(value);
  }
  
  /**
   * Strips undefined / null / empty-string entries from a body before sending.
   * The DeonPay API accepts missing fields cleanly but treating "" as a valid
   * value would override server-side defaults — usually not what the LLM means.
   */
  export function compact<T extends Record<string, unknown>>(obj: T): Partial<T> {
    const out: Record<string, unknown> = {};
    for (const [key, value] of Object.entries(obj)) {
      if (value === undefined || value === null) continue;
      if (typeof value === "string" && value.trim() === "") continue;
      out[key] = value;
    }
    return out as Partial<T>;
  }