export_amazon_transactions_csv

Instructions

Implementation Reference

• src/index.ts:345-381 (registration)

  Tool registration entry defining the tool name, description, input schema (region, dates, output_path, max_orders), and requirements.

  {
    name: "export_amazon_transactions_csv",
    description:
      "Export Amazon payment transactions to CSV file. Extracts transaction data from each order's detail page. CSV columns include: date, order ID, amount, payment method, card info. For faster bulk transaction export, consider get_amazon_transactions which scrapes the dedicated transactions page.",
    inputSchema: {
      type: "object",
      properties: {
        region: {
          type: "string",
          description: "Amazon region code",
          enum: getRegionCodes(),
        },
        year: {
          type: "number",
          description: "Year to export (defaults to current year)",
        },
        start_date: {
          type: "string",
          description: "Start date in ISO format (YYYY-MM-DD)",
        },
        end_date: {
          type: "string",
          description: "End date in ISO format (YYYY-MM-DD)",
        },
        output_path: {
          type: "string",
          description:
            "Full path to save CSV file. Defaults to ~/Downloads/amazon-{region}-transactions-{year}-{date}.csv",
        },
        max_orders: {
          type: "number",
          description: "Maximum number of orders to process",
        },
      },
      required: ["region"],
    },
  },

• src/index.ts:1085-1157 (handler)

  Primary handler for the tool: validates region, fetches orders enabling transaction extraction, exports transactions to CSV using exportTransactionsCSV, computes timing estimates, and returns structured result with file path and counts.

  case "export_amazon_transactions_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 year = args?.year as number | undefined;
    const startDate = args?.start_date as string | undefined;
    const endDate = args?.end_date as string | undefined;
    const maxOrders = args?.max_orders as number | undefined;
    const outputPath = getOutputPath(
      args?.output_path as string | undefined,
      "transactions",
      region,
      { year, startDate, endDate },
    );
  
    const fetchResult = await fetchOrders(currentPage, amazonPlugin, {
      region,
      year,
      startDate,
      endDate,
      includeItems: false,
      includeShipments: false,
      includeTransactions: true,
      maxOrders,
    });
  
    const timeEstimate = estimateExtractionTime(fetchResult.orders.length, {
      includeItems: false,
      includeShipments: false,
    });
  
    const exportResult = await exportTransactionsCSV(
      fetchResult.transactions,
      outputPath,
    );
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              status: exportResult.success ? "success" : "error",
              params: {
                region,
                year,
                startDate,
                endDate,
                maxOrders,
                outputPath,
              },
              filePath: exportResult.filePath,
              rowCount: exportResult.rowCount,
              error: exportResult.error,
              fetchErrors: fetchResult.errors,
              timing: {
                orderCount: fetchResult.orders.length,
                transactionCount: fetchResult.transactions.length,
                estimate: timeEstimate.formattedEstimate,
                warnings: timeEstimate.warnings,
                recommendations: timeEstimate.recommendations,
              },
            },
            null,
            2,
          ),
        },
      ],
    };
  }

• src/tools/export-csv.ts:113-134 (helper)

  Helper function that converts Transaction array to CSV using predefined TRANSACTION_CSV_COLUMNS and writes to the specified output file path.

  export async function exportTransactionsCSV(
    transactions: Transaction[],
    outputPath: string,
  ): Promise<ExportResult> {
    try {
      const csv = toCSVWithColumns(transactions, TRANSACTION_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),
      };
    }
  }

• src/tools/export-csv.ts:327-344 (helper)

  Helper function to generate or use provided output file path in ~/Downloads with formatted filename like amazon-{region}-transactions-{year}-{date}.csv.

  export function getOutputPath(
    outputPath: string | undefined,
    exportType: "orders" | "items" | "shipments" | "transactions" | "gift-cards",
    region: string,
    options?: {
      year?: number;
      startDate?: string;
      endDate?: string;
    },
  ): string {
    if (outputPath) {
      return outputPath;
    }
  
    const filename = generateExportFilename(exportType, region, options);
    return join(getDefaultDownloadsPath(), filename);
  }

• src/tools/export-csv.ts:12-20 (schema)

  Imports TRANSACTION_CSV_COLUMNS which defines the CSV structure/schema for transactions output.

  import {
    ORDER_CSV_COLUMNS,
    ITEM_CSV_COLUMNS,
    SHIPMENT_CSV_COLUMNS,
    TRANSACTION_CSV_COLUMNS,
    GIFT_CARD_CSV_COLUMNS,
    OrderCSVData,
    GiftCardTransactionCSVData,
  } from "./csv-columns";