export_amazon_gift_cards_csv

Instructions

Implementation Reference

• src/index.ts:439-464 (registration)

  Tool registration in MCP tools array, including name, description, and input schema (region required, output_path and max_pages optional).

  {
    name: "export_amazon_gift_cards_csv",
    description:
      "Export Amazon gift card transaction history to CSV file. CSV columns: Date, Description, Amount, Closing Balance, Type (credit/debit), Order ID, Claim Code, Serial Number, Region. Useful for tracking gift card usage and reconciling balances.",
    inputSchema: {
      type: "object",
      properties: {
        region: {
          type: "string",
          description: "Amazon region code",
          enum: getRegionCodes(),
        },
        output_path: {
          type: "string",
          description:
            "Full path to save CSV file. Defaults to ~/Downloads/amazon-{region}-gift-cards-{date}.csv",
        },
        max_pages: {
          type: "number",
          description:
            "Maximum pages of transaction history to fetch. Default: 10. Set to 0 for unlimited.",
          default: 10,
        },
      },
      required: ["region"],
    },

• src/index.ts:443-464 (schema)

  Input schema defining parameters for the tool: region (required, enum of Amazon regions), optional output_path and max_pages.

  inputSchema: {
    type: "object",
    properties: {
      region: {
        type: "string",
        description: "Amazon region code",
        enum: getRegionCodes(),
      },
      output_path: {
        type: "string",
        description:
          "Full path to save CSV file. Defaults to ~/Downloads/amazon-{region}-gift-cards-{date}.csv",
      },
      max_pages: {
        type: "number",
        description:
          "Maximum pages of transaction history to fetch. Default: 10. Set to 0 for unlimited.",
        default: 10,
      },
    },
    required: ["region"],
  },

• src/index.ts:1263-1317 (handler)

  Main tool handler in MCP call switch: validates input, fetches gift card data, formats for CSV, determines output path, exports CSV, returns success/error with file info and balance.

  case "export_amazon_gift_cards_csv": {
    const regionParam = args?.region as string | undefined;
    const regionError = validateRegion(regionParam, args);
    if (regionError) return regionError;
    const region = regionParam!;
  
    const currentPage = await getPage();
    const outputPath = args?.output_path as string | undefined;
    const maxPages = (args?.max_pages as number) ?? 10;
  
    // Extract gift card transactions
    const giftCardData = await extractGiftCardData(currentPage, region, {
      maxPages,
      fetchAllPages: true,
    });
  
    // Convert to CSV format using shared helper
    const csvData = formatGiftCardDataForCSV(giftCardData);
  
    // Generate output path
    const today = new Date().toISOString().split("T")[0];
    const finalPath = getOutputPath(outputPath, "gift-cards", region, {
      endDate: today,
    });
  
    // Export to CSV
    const exportResult = await exportGiftCardTransactionsCSV(
      csvData,
      finalPath,
    );
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              status: exportResult.success ? "success" : "error",
              params: {
                region,
                maxPages,
              },
              balance: giftCardData.balance.balance,
              transactionCount: giftCardData.transactions.length,
              filePath: exportResult.filePath,
              rowCount: exportResult.rowCount,
              error: exportResult.error,
            },
            null,
            2,
          ),
        },
      ],
    };
  }

• src/index.ts:621-637 (helper)

  Transforms nested GiftCardData into flat array of GiftCardTransactionCSVData for CSV export, adding region to each row.

  function formatGiftCardDataForCSV(
    giftCardData: GiftCardData,
  ): GiftCardTransactionCSVData[] {
    return giftCardData.transactions.map((t) => ({
      date: t.date,
      description: t.description,
      amount: t.amount,
      closingBalance: t.closingBalance,
      type: t.type,
      orderId: t.orderId,
      claimCode: t.claimCode,
      serialNumber: t.serialNumber,
      region: giftCardData.region,
    }));
  }
  
  // Handle list tools request

• src/tools/export-csv.ts:139-160 (helper)

  Exports the formatted gift card transactions to CSV file using predefined columns (GIFT_CARD_CSV_COLUMNS), handles errors, returns result with row count.

  export async function exportGiftCardTransactionsCSV(
    transactions: GiftCardTransactionCSVData[],
    outputPath: string,
  ): Promise<ExportResult> {
    try {
      const csv = toCSVWithColumns(transactions, GIFT_CARD_CSV_COLUMNS);
      await writeFile(outputPath, csv, "utf-8");
  
      return {
        success: true,
        filePath: outputPath,
        rowCount: transactions.length,
      };
    } catch (error) {
      return {
        success: false,
        filePath: outputPath,
        rowCount: 0,
        error: String(error),
      };
    }
  }