get_amazon_gift_card_balance

Instructions

Implementation Reference

• src/index.ts:411-438 (registration)

  MCP tool registration including name, description, and input schema for get_amazon_gift_card_balance.

  {
    name: "get_amazon_gift_card_balance",
    description:
      "Get current Amazon gift card balance and transaction history. Returns: current balance, last updated timestamp, and paginated transaction history (date, description, amount, closing balance, type, associated order ID, claim code, serial number). Supports fetching complete history across multiple pages.",
    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,
        },
        fetch_all_pages: {
          type: "boolean",
          description:
            "Automatically paginate through all available transaction history. Default: true.",
          default: true,
        },
      },
      required: ["region"],
    },
  },

• src/index.ts:1214-1261 (handler)

  MCP server handler for the tool call: validates input, calls extractGiftCardData, formats response as JSON.

  case "get_amazon_gift_card_balance": {
    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;
    const fetchAllPages = (args?.fetch_all_pages as boolean) ?? true;
  
    const giftCardData = await extractGiftCardData(currentPage, region, {
      maxPages,
      fetchAllPages,
    });
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              status: "success",
              params: {
                region,
                maxPages,
                fetchAllPages,
              },
              balance: giftCardData.balance.balance,
              lastUpdated: giftCardData.balance.lastUpdated.toISOString(),
              transactionCount: giftCardData.transactions.length,
              transactions: giftCardData.transactions.map((t) => ({
                date: t.date.toISOString(),
                description: t.description,
                amount: t.amount,
                closingBalance: t.closingBalance,
                type: t.type,
                orderId: t.orderId,
                claimCode: t.claimCode,
                serialNumber: t.serialNumber,
              })),
            },
            null,
            2,
          ),
        },
      ],
    };
  }

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

  Core tool handler: navigates to Amazon gift card balance page (/gc/balance), extracts current balance, loops through paginated transaction table extracting dates, descriptions, amounts, closing balances, order IDs, claim codes, serial numbers, and transaction types.

  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/amazon/extractors/gift-card.ts:24-83 (schema)

  TypeScript interfaces defining the structure of gift card balance and transaction data returned by the tool.

  export interface GiftCardBalance {
    balance: Money;
    lastUpdated: Date;
  }
  
  /**
   * Gift card transaction types.
   */
  export type GiftCardTransactionType =
    | "applied" // Gift card applied to order (debit)
    | "refund" // Refund credited back to gift card balance
    | "added" // Gift card added/redeemed (credit)
    | "reload" // Gift card reloaded (credit)
    | "promotional" // Promotional credit added
    | "unknown";
  
  /**
   * Gift card transaction entry.
   * Note: This is separate from the order Transaction type as it represents
   * gift card balance activity, not payment transactions.
   */
  export interface GiftCardTransaction {
    /** Transaction date */
    date: Date;
  
    /** Human-readable description */
    description: string;
  
    /** Transaction amount (negative for debits, positive for credits) */
    amount: Money;
  
    /** Closing balance after this transaction */
    closingBalance: Money;
  
    /** Transaction type */
    type: GiftCardTransactionType;
  
    /** Associated order ID (if applicable) */
    orderId?: string;
  
    /** Gift card claim code (for 'added' type, partially masked) */
    claimCode?: string;
  
    /** Gift card serial number (for 'added' type) */
    serialNumber?: string;
  }
  
  /**
   * Complete gift card data.
   */
  export interface GiftCardData {
    /** Current gift card balance */
    balance: GiftCardBalance;
  
    /** Transaction history */
    transactions: GiftCardTransaction[];
  
    /** Region this data was extracted from */
    region: string;
  }

• src/amazon/extractors/gift-card.ts:184-213 (helper)

  Helper function to detect and click the 'Next' pagination button on the gift card activity pages.

  async function goToNextGiftCardPage(page: Page): Promise<boolean> {
    try {
      // Look for the "Next" link in the pagination
      const nextLink = page
        .locator(
          'ul.a-pagination li.a-last a, ul.a-pagination a:has-text("Next")',
        )
        .first();
  
      if ((await nextLink.count()) === 0) {
        return false;
      }
  
      // Check if the link is disabled (no href or disabled class)
      const href = await nextLink.getAttribute("href");
      if (!href) {
        return false;
      }
  
      // Click the next link
      await nextLink.click();
  
      // Wait for navigation
      await page.waitForLoadState("domcontentloaded", { timeout: 10000 });
  
      return true;
    } catch {
      return false;
    }
  }