get_amazon_gift_card_transactions

Instructions

Implementation Reference

• src/amazon/extractors/gift-card.ts:108-172 (handler)

  Main handler function that implements the tool logic: navigates to Amazon gift card balance page, extracts current balance, paginates through transaction history extracting date, description, amount, closing balance, type, order ID, claim code, serial number for each transaction.

  export async function extractGiftCardData(
    page: Page,
    region: string,
    options: GiftCardExtractionOptions = {},
  ): Promise<GiftCardData> {
    const { maxPages = 10, fetchAllPages = true } = options;
    const regionConfig = getRegionByCode(region);
    const currency = regionConfig?.currency || "USD";
    const url = getGiftCardPageUrl(region);
  
    // Navigate to gift card balance page
    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30000 });
  
    // Wait for the balance table to load
    await page
      .waitForSelector(
        'table.a-bordered tbody tr, [data-testid="gc-balance"], #gc-balance',
        { timeout: 10000 },
      )
      .catch(() => {});
  
    // Extract balance (from first row's closing balance, or dedicated element)
    const balance = await extractBalance(page, currency);
  
    // Extract transactions from all pages
    const allTransactions: GiftCardTransaction[] = [];
    let pageCount = 0;
  
    let hasMorePages = true;
    while (hasMorePages) {
      pageCount++;
  
      // Extract transactions from current page
      const pageTransactions = await extractTransactionsFromTable(page, currency);
      allTransactions.push(...pageTransactions);
  
      // Check if we should continue to next page
      if (!fetchAllPages) {
        hasMorePages = false;
        continue;
      }
      if (maxPages > 0 && pageCount >= maxPages) {
        hasMorePages = false;
        continue;
      }
  
      // Check for and click "Next" pagination button
      hasMorePages = await goToNextGiftCardPage(page);
  
      // Wait for the new page content to load
      await page.waitForTimeout(500);
      await page
        .waitForSelector("table.a-bordered tbody tr", { timeout: 5000 })
        .catch(() => {});
    }
  
    // Deduplicate transactions (in case of overlap between pages)
    const uniqueTransactions = deduplicateTransactions(allTransactions);
  
    return {
      balance,
      transactions: uniqueTransactions,
      region,
    };
  }

• src/index.ts:466-486 (registration)

  Tool registration in the MCP tools list, including name, description, and input schema.

  {
    name: "get_amazon_gift_card_transactions",
    description:
      "Get Amazon gift card transaction history with full details. Returns: current balance, transaction count, and detailed transactions (date, description, amount, closing balance, transaction type, order ID, claim code, serial number). Supports pagination for complete history.",
    inputSchema: {
      type: "object",
      properties: {
        region: {
          type: "string",
          description: "Amazon region code",
          enum: getRegionCodes(),
        },
        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:1319-1356 (handler)

  MCP server request handler for the tool call: validates input, calls extractGiftCardData, formats output using helper, returns JSON response.

  case "get_amazon_gift_card_transactions": {
    const regionParam = args?.region as string | undefined;
    const regionError = validateRegion(regionParam, args);
    if (regionError) return regionError;
    const region = regionParam!;
  
    const currentPage = await getPage();
    const maxPages = (args?.max_pages as number) ?? 10;
  
    // Extract gift card transactions
    const giftCardData = await extractGiftCardData(currentPage, region, {
      maxPages,
      fetchAllPages: true,
    });
  
    // Convert to export format using shared helper
    const exportData = formatGiftCardDataForExport(giftCardData);
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              status: "success",
              params: {
                region,
                maxPages,
              },
              ...exportData,
            },
            null,
            2,
          ),
        },
      ],
    };
  }

• src/index.ts:583-616 (helper)

  Helper function to format GiftCardData into the JSON export structure used by the tool response.

  function formatGiftCardDataForExport(
    giftCardData: GiftCardData,
  ): GiftCardExportData {
    return {
      balance: {
        amount: giftCardData.balance.balance.amount,
        currency: giftCardData.balance.balance.currency,
        formatted: giftCardData.balance.balance.formatted,
      },
      lastUpdated: giftCardData.balance.lastUpdated.toISOString(),
      region: giftCardData.region,
      transactionCount: giftCardData.transactions.length,
      transactions: giftCardData.transactions.map((t) => ({
        date: t.date.toISOString(),
        description: t.description,
        amount: {
          amount: t.amount.amount,
          currency: t.amount.currency,
          currencySymbol: t.amount.currencySymbol,
          formatted: t.amount.formatted,
        },
        closingBalance: {
          amount: t.closingBalance.amount,
          currency: t.closingBalance.currency,
          currencySymbol: t.closingBalance.currencySymbol,
          formatted: t.closingBalance.formatted,
        },
        type: t.type,
        orderId: t.orderId,
        claimCode: t.claimCode,
        serialNumber: t.serialNumber,
      })),
    };
  }

• src/amazon/extractors/gift-card.ts:74-83 (schema)

  TypeScript interface defining the output structure (schema) for gift card data returned by the handler.

  export interface GiftCardData {
    /** Current gift card balance */
    balance: GiftCardBalance;
  
    /** Transaction history */
    transactions: GiftCardTransaction[];
  
    /** Region this data was extracted from */
    region: string;
  }