@agentrhq/webcmd 0.4.0 → 0.4.2

package/clis/amazon-in/parsers.js

@@ -0,0 +1,252 @@
+export const cleanText = (value) =>
+  typeof value === 'string'
+    ? value.replace(/\u00a0/g, ' ').replace(/\s+/g, ' ').trim()
+    : '';
+
+export function classifyPageState(url, text) {
+  if (/\/(?:ap\/signin|signin)(?:[/?]|$)/i.test(url)) return 'login';
+  if (/enter the characters you see below|sorry, we just need to make sure you're not a robot/i.test(cleanText(text))) {
+    return 'robot';
+  }
+  return 'usable';
+}
+
+export function hasAmazonInAuthCookie(names) {
+  const cookies = new Set(names);
+  return cookies.has('at-acbin') || cookies.has('x-acbin');
+}
+
+export function extractAsin(input) {
+  const value = cleanText(input);
+  if (/^[A-Z0-9]{10}$/i.test(value)) return value.toUpperCase();
+  try {
+    const url = new URL(value);
+    if (!/(^|\.)amazon\.in$/i.test(url.hostname)) return null;
+    return url.pathname.match(/\/(?:dp|gp\/product)\/([A-Z0-9]{10})/i)?.[1]?.toUpperCase() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function buildProductUrl(input) {
+  const asin = extractAsin(input);
+  if (!asin) throw new RangeError('Expected an Amazon.in product URL or 10-character ASIN');
+  return `https://www.amazon.in/dp/${asin}`;
+}
+
+export function parseMoney(text) {
+  const match = cleanText(text).match(/(?:₹|Rs\.?)\s*([\d,]+(?:\.\d{1,2})?)/i);
+  return match ? Number(match[1].replaceAll(',', '')) : null;
+}
+
+export function parseCompactCount(text) {
+  const match = cleanText(text).match(/([\d,.]+)\s*([KM])?/i);
+  if (!match) return null;
+  const scale = match[2]?.toUpperCase() === 'M' ? 1_000_000 : match[2] ? 1_000 : 1;
+  return Math.round(Number(match[1].replaceAll(',', '')) * scale);
+}
+
+export function validatePositiveInteger(value, name, maximum) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 1 || number > maximum) {
+    throw new RangeError(`${name} must be an integer from 1 to ${maximum}`);
+  }
+  return number;
+}
+
+export function parseBoolean(value) {
+  if (typeof value === 'boolean') return value;
+  if (value === undefined || value === null || value === '') return false;
+  if (/^(true|1)$/i.test(String(value))) return true;
+  if (/^(false|0)$/i.test(String(value))) return false;
+  throw new RangeError('place-order must be true or false');
+}
+
+export function validatePriceBounds(minimum, maximum) {
+  const minPrice = minimum === undefined ? null : Number(minimum);
+  const maxPrice = maximum === undefined ? null : Number(maximum);
+  if (minPrice !== null && (!Number.isFinite(minPrice) || minPrice < 0)) {
+    throw new RangeError('minimum price must be zero or greater');
+  }
+  if (maxPrice !== null && (!Number.isFinite(maxPrice) || maxPrice < 0)) {
+    throw new RangeError('maximum price must be zero or greater');
+  }
+  if (minPrice !== null && maxPrice !== null && minPrice > maxPrice) {
+    throw new RangeError('minimum price cannot exceed maximum price');
+  }
+  return { minPrice, maxPrice };
+}
+
+export function buildSearchUrl(query, { minPrice, maxPrice }) {
+  const url = new URL('/s', 'https://www.amazon.in');
+  url.searchParams.set('k', cleanText(query));
+  if (minPrice !== null || maxPrice !== null) {
+    const low = Math.round((minPrice ?? 0) * 100);
+    const high = Math.round((maxPrice ?? 10_000_000) * 100);
+    url.searchParams.set('rh', `p_36:${low}-${high}`);
+  }
+  return url.href;
+}
+
+export function normalizeSearchCards(cards, { minPrice, maxPrice, limit }) {
+  return cards
+    .map((card) => {
+      const price = parseMoney(card.cardPriceText);
+      if (!card.cardAsin || !cleanText(card.cardTitle) || price === null) return null;
+      if (minPrice !== null && price < minPrice) return null;
+      if (maxPrice !== null && price > maxPrice) return null;
+      return {
+        rank: 0,
+        asin: card.cardAsin,
+        title: cleanText(card.cardTitle),
+        price,
+        mrp: parseMoney(card.cardMrpText),
+        rating: Number(cleanText(card.cardRatingText).match(/[\d.]+/)?.[0]) || null,
+        review_count: parseCompactCount(card.cardReviewText),
+        image_url: cleanText(card.cardImageUrl),
+        product_url: `https://www.amazon.in/dp/${card.cardAsin}`,
+        is_sponsored: card.cardSponsored === true,
+      };
+    })
+    .filter(Boolean)
+    .slice(0, limit)
+    .map((row, index) => ({ ...row, rank: index + 1 }));
+}
+
+export function normalizeProductSnapshot(snapshot) {
+  const asin = extractAsin(snapshot.href);
+  const title = cleanText(snapshot.title);
+  const availability = cleanText(snapshot.availabilityText);
+  if (!asin || !title || !availability) throw new Error('Amazon product details are incomplete');
+  const price = parseMoney(snapshot.priceText);
+  if (price === null && !/unavailable|out of stock|currently unavailable/i.test(availability)) {
+    throw new Error('Amazon product price is missing');
+  }
+  const discountMatch = cleanText(snapshot.discountText).match(/-?\s*(\d+(?:\.\d+)?)\s*%/);
+  return {
+    asin,
+    title,
+    price,
+    mrp: parseMoney(snapshot.mrpText),
+    discount: discountMatch ? Number(discountMatch[1]) : null,
+    availability,
+    size: cleanText(snapshot.sizeText),
+    colour: cleanText(snapshot.colourText),
+    image_url: cleanText(snapshot.imageUrl),
+    product_url: `https://www.amazon.in/dp/${asin}`,
+  };
+}
+
+export function normalizeWishlistRows(listName, cards) {
+  return cards.map((card) => {
+    const asin = extractAsin(card.cardHref);
+    const title = cleanText(card.cardTitle);
+    const itemId = cleanText(card.cardItemId);
+    const availability = cleanText(card.cardAvailabilityText);
+    const price = parseMoney(card.cardPriceText);
+    if (!asin || !title || !itemId) throw new Error('Amazon wishlist item details are incomplete');
+    if (price === null && !/unavailable|out of stock|currently unavailable/i.test(availability)) {
+      throw new Error(`Amazon wishlist price is missing for ${asin}`);
+    }
+    return {
+      list_name: cleanText(listName),
+      item_id: itemId,
+      asin,
+      title,
+      price,
+      mrp: parseMoney(card.cardMrpText),
+      availability,
+      size: cleanText(card.cardSizeText),
+      colour: cleanText(card.cardColourText),
+      image_url: cleanText(card.cardImageUrl),
+      product_url: `https://www.amazon.in/dp/${asin}`,
+    };
+  });
+}
+
+export function validateCheckoutArgs(args) {
+  const quantity = validatePositiveInteger(args.quantity ?? 1, 'quantity', 10);
+  const payment = cleanText(args.payment);
+  if (!['upi', 'saved-card', 'new-card', 'cod'].includes(payment)) {
+    throw new RangeError('payment must be upi, saved-card, new-card, or cod');
+  }
+  const cardLast4 = cleanText(args.cardLast4);
+  if (payment === 'saved-card' && !/^\d{4}$/.test(cardLast4)) {
+    throw new RangeError('card-last4 must contain exactly four digits for saved-card');
+  }
+  return {
+    quantity,
+    payment,
+    cardLast4,
+    size: cleanText(args.size),
+    colour: cleanText(args.colour),
+    placeOrder: parseBoolean(args.placeOrder),
+  };
+}
+
+export function normalizeCheckoutReview(snapshot) {
+  const itemPrice = parseMoney(snapshot.itemPriceText);
+  const total = parseMoney(snapshot.totalText);
+  if (itemPrice === null || total === null) throw new Error('Checkout item price or total is missing');
+  const deliveryFee = (parseMoney(snapshot.deliveryFeeText) ?? 0)
+    - (parseMoney(snapshot.deliveryDiscountText) ?? 0);
+  return {
+    itemPrice,
+    deliveryFee,
+    marketplaceFee: parseMoney(snapshot.marketplaceFeeText) ?? 0,
+    total,
+    quantity: Number(snapshot.quantity),
+  };
+}
+
+export function totalsAreConsistent(review) {
+  const expected = review.itemPrice * review.quantity + review.deliveryFee + review.marketplaceFee;
+  return Math.abs(expected - review.total) <= 0.011;
+}
+
+export function classifyCheckoutSnapshot(snapshot) {
+  const url = cleanText(snapshot.url);
+  const text = cleanText(snapshot.text);
+  const reviewReady = /\/checkout\/p\/.+\/spc/i.test(url) && /Order Total:/i.test(text);
+  const awaitingPayment = !reviewReady && (
+    /aips\/process-payment/i.test(url)
+    || /QR code|enter (?:your )?CVV|one.time password|3-D Secure/i.test(text)
+  );
+  const hasPaymentText = Object.hasOwn(snapshot, 'paymentText');
+  const explicitPaymentText = hasPaymentText ? cleanText(snapshot.paymentText) : '';
+  const paymentText = hasPaymentText
+    ? explicitPaymentText || (awaitingPayment ? text : '')
+    : text;
+  const paymentMethod = /UPI|QR code/i.test(paymentText)
+    ? 'upi'
+    : /Cash on Delivery|Pay on Delivery/i.test(paymentText)
+      ? 'cod'
+      : /ending in|credit card|debit card|CVV|3-D Secure/i.test(paymentText)
+        ? 'card'
+        : '';
+  const base = {
+    order_id: text.match(/\b\d{3}-\d{7}-\d{7}\b/)?.[0] ?? '',
+    total: parseMoney(text),
+    payment_method: paymentMethod,
+    action: '',
+  };
+  if (/\/(?:thankyou|buy\/thankyou)\//i.test(url) && /order (?:placed|confirmed)|thank you/i.test(text)) {
+    return { status: 'ordered', ...base };
+  }
+  if (/payment (?:failed|declined|unsuccessful)|transaction failed/i.test(text)) {
+    return { status: 'failed', ...base, action: 'Choose a payment method in the browser; do not retry a charge automatically.' };
+  }
+  if (/(?:QR|session|payment link).{0,30}expired|expired.{0,30}(?:QR|session|payment)/i.test(text)) {
+    return { status: 'expired', ...base, action: 'Return to checkout and create a new payment attempt.' };
+  }
+  if (reviewReady) {
+    return { status: 'review_ready', ...base };
+  }
+  if (awaitingPayment) {
+    return { status: 'awaiting_payment', ...base, action: 'Complete payment in the opened browser, then run checkout-status again.' };
+  }
+  if (/\/ap\/signin/i.test(url) || /enter your (?:email|mobile number)|sign in/i.test(text)) {
+    return { status: 'login_required', ...base, action: 'Sign in in the opened browser, then run checkout-status again.' };
+  }
+  throw new Error('Amazon checkout state is not recognized');
+}

package/clis/amazon-in/parsers.test.js

@@ -0,0 +1,230 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ as checkoutTest } from './checkout.js';
+import {
+  buildProductUrl,
+  classifyCheckoutSnapshot,
+  classifyPageState,
+  extractAsin,
+  hasAmazonInAuthCookie,
+  normalizeCheckoutReview,
+  normalizeProductSnapshot,
+  normalizeSearchCards,
+  normalizeWishlistRows,
+  parseCompactCount,
+  parseMoney,
+  totalsAreConsistent,
+  validateCheckoutArgs,
+  validatePositiveInteger,
+  validatePriceBounds,
+} from './parsers.js';
+
+describe('amazon-in parsers', () => {
+  it('normalizes ASINs and parses Indian prices and counts', () => {
+    expect(extractAsin('https://www.amazon.in/dp/B0D2QL339Z?psc=1')).toBe('B0D2QL339Z');
+    expect(buildProductUrl('B0D2QL339Z')).toBe('https://www.amazon.in/dp/B0D2QL339Z');
+    expect(extractAsin('https://amazon.com/dp/B0D2QL339Z')).toBeNull();
+    expect(parseMoney('₹1,499.00')).toBe(1499);
+    expect(parseMoney('Unavailable')).toBeNull();
+    expect(parseCompactCount('39.7K')).toBe(39700);
+    expect(parseCompactCount('3,564 ratings')).toBe(3564);
+  });
+
+  it('validates bounds without silently clamping', () => {
+    expect(validatePriceBounds('300', '500')).toEqual({ minPrice: 300, maxPrice: 500 });
+    expect(() => validatePriceBounds('500', '300')).toThrow(/minimum price/i);
+    expect(validatePositiveInteger('20', 'limit', 50)).toBe(20);
+    expect(() => validatePositiveInteger('51', 'limit', 50)).toThrow(/1 to 50/i);
+  });
+
+  it('classifies login and robot pages before DOM parsing', () => {
+    expect(classifyPageState('https://www.amazon.in/ap/signin', '')).toBe('login');
+    expect(classifyPageState('https://www.amazon.in/', 'Enter the characters you see below')).toBe('robot');
+    expect(classifyPageState('https://www.amazon.in/s?k=shirt', 'Results')).toBe('usable');
+    expect(hasAmazonInAuthCookie(['session-id', 'x-acbin'])).toBe(true);
+    expect(hasAmazonInAuthCookie(['session-id', 'i18n-prefs'])).toBe(false);
+  });
+
+  it('filters search cards inclusively and preserves images', () => {
+    const rows = normalizeSearchCards([
+      {
+        cardAsin: 'B000000001',
+        cardTitle: 'Low',
+        cardPriceText: '₹299',
+        cardImageUrl: 'https://m.media-amazon.com/low.jpg',
+      },
+      {
+        cardAsin: 'B000000002',
+        cardTitle: 'Match',
+        cardPriceText: '₹500',
+        cardImageUrl: 'https://m.media-amazon.com/match.jpg',
+      },
+      {
+        cardAsin: 'B000000003',
+        cardTitle: 'No price',
+        cardPriceText: '',
+        cardImageUrl: '',
+      },
+    ], { minPrice: 300, maxPrice: 500, limit: 10 });
+    expect(rows.map((row) => row.asin)).toEqual(['B000000002']);
+    expect(rows[0].image_url).toBe('https://m.media-amazon.com/match.jpg');
+    expect(rows[0].rank).toBe(1);
+  });
+
+  it('normalizes selected product and wishlist variants', () => {
+    expect(normalizeProductSnapshot({
+      href: 'https://www.amazon.in/dp/B0D2QL339Z?th=1&psc=1',
+      title: 'Besix shirt',
+      priceText: '₹395.00',
+      mrpText: '₹1,499.00',
+      discountText: '-74%',
+      availabilityText: 'In stock',
+      sizeText: 'L',
+      colourText: 'Red',
+      imageUrl: 'https://m.media-amazon.com/image.jpg',
+    })).toEqual({
+      asin: 'B0D2QL339Z',
+      title: 'Besix shirt',
+      price: 395,
+      mrp: 1499,
+      discount: 74,
+      availability: 'In stock',
+      size: 'L',
+      colour: 'Red',
+      image_url: 'https://m.media-amazon.com/image.jpg',
+      product_url: 'https://www.amazon.in/dp/B0D2QL339Z',
+    });
+
+    const [row] = normalizeWishlistRows('Shopping List', [{
+      cardItemId: 'item-1',
+      cardHref: 'https://www.amazon.in/dp/B0D2QL339Z',
+      cardTitle: 'Besix shirt',
+      cardPriceText: '₹395.00',
+      cardMrpText: '₹1,499.00',
+      cardAvailabilityText: 'In stock',
+      cardSizeText: 'L',
+      cardColourText: 'Red',
+      cardImageUrl: 'https://m.media-amazon.com/image.jpg',
+    }]);
+    expect(row).toMatchObject({
+      asin: 'B0D2QL339Z',
+      price: 395,
+      list_name: 'Shopping List',
+    });
+  });
+
+  it('validates checkout payment selectors and totals', () => {
+    expect(validateCheckoutArgs({
+      quantity: 1,
+      payment: 'saved-card',
+      cardLast4: '6764',
+      placeOrder: false,
+    }).payment).toBe('saved-card');
+    expect(validateCheckoutArgs({ quantity: 1, payment: 'upi' }).placeOrder).toBe(false);
+    expect(() => validateCheckoutArgs({
+      quantity: 1,
+      payment: 'saved-card',
+      cardLast4: '',
+    })).toThrow(/card-last4/i);
+    expect(() => validateCheckoutArgs({
+      quantity: 1,
+      payment: 'card-number',
+    })).toThrow(/upi, saved-card, new-card, or cod/i);
+
+    const review = normalizeCheckoutReview({
+      itemPriceText: '₹395',
+      deliveryFeeText: '₹40',
+      deliveryDiscountText: '-₹40',
+      marketplaceFeeText: '₹5',
+      totalText: '₹400',
+      quantity: 1,
+    });
+    expect(review.deliveryFee).toBe(0);
+    expect(totalsAreConsistent(review)).toBe(true);
+    expect(totalsAreConsistent({ ...review, total: 500 })).toBe(false);
+  });
+
+  it('classifies checkout state without submitting', () => {
+    expect(classifyCheckoutSnapshot({
+      url: 'https://www.amazon.in/aips/process-payment',
+      text: 'Complete your payment Payment of ₹ 400.00 QR code is valid',
+    })).toMatchObject({ status: 'awaiting_payment', payment_method: 'upi', total: 400 });
+    expect(classifyCheckoutSnapshot({
+      url: 'https://www.amazon.in/gp/buy/thankyou/handlers/display.html',
+      text: 'Order placed, thank you',
+    }).status).toBe('ordered');
+    expect(classifyCheckoutSnapshot({
+      url: 'https://www.amazon.in/checkout/p/example/spc',
+      text: 'Order Total: ₹400 Pay with UPI',
+    }).status).toBe('review_ready');
+    expect(classifyCheckoutSnapshot({
+      url: 'https://www.amazon.in/checkout/p/example/spc',
+      paymentText: 'Pay by scanning the QR code',
+      text: 'Order Total: ₹400 A UPI QR code will appear on the next page',
+    }).status).toBe('review_ready');
+    expect(classifyCheckoutSnapshot({
+      url: 'https://www.amazon.in/checkout/p/example/spc',
+      paymentText: 'Visa ending in 6764',
+      text: 'Order Total: ₹400 Other methods: Pay with UPI',
+    }).payment_method).toBe('card');
+    expect(classifyCheckoutSnapshot({
+      url: 'https://www.amazon.in/aips/process-payment',
+      paymentText: '',
+      text: 'Complete your payment Payment of ₹400 Scan the QR code',
+    }).payment_method).toBe('upi');
+  });
+
+  it('hands secret entry to the browser before trying Continue', async () => {
+    const page = {
+      wait: () => { throw new Error('must not wait'); },
+      click: () => { throw new Error('must not click Continue'); },
+      evaluate: () => { throw new Error('must not inspect new-card secrets'); },
+    };
+    const row = await checkoutTest.continueAfterPaymentSelection(
+      page,
+      { payment: 'new-card' },
+      { asin: 'B0D2QL339Z', title: 'Shirt', size: 'L', colour: 'Red' },
+      1,
+    );
+    expect(row).toMatchObject({ status: 'action_required', payment_method: 'new-card' });
+
+    let clicks = 0;
+    const savedCardRow = await checkoutTest.continueAfterPaymentSelection({
+      evaluate: async () => ({ needsSecret: true, continueEnabled: false }),
+      click: async () => { clicks += 1; },
+      sleep: () => { throw new Error('must not sleep after finding CVV'); },
+    }, {
+      payment: 'saved-card',
+    }, {
+      asin: 'B0D2QL339Z',
+      title: 'Shirt',
+      size: 'L',
+      colour: 'Red',
+    }, 1);
+    expect(savedCardRow).toMatchObject({ status: 'action_required', payment_method: 'saved-card' });
+    expect(clicks).toBe(0);
+  });
+
+  it('requires one matching line item and never clicks Place Order by default', async () => {
+    expect(() => checkoutTest.assertSingleLineItem({
+      itemCount: 2,
+      asin: 'B0D2QL339Z',
+      quantity: 1,
+    }, {
+      asin: 'B0D2QL339Z',
+    }, {
+      quantity: 1,
+    })).toThrow(/exactly one checkout line item/i);
+
+    let placements = 0;
+    const page = {
+      evaluate: async () => {
+        placements += 1;
+        return { clicked: true, matches: 1 };
+      },
+    };
+    expect(await checkoutTest.submitOrder(page, false)).toBe(false);
+    expect(placements).toBe(0);
+    expect(await checkoutTest.submitOrder(page, true)).toBe(true);
+    expect(placements).toBe(1);
+  });
+});

package/clis/amazon-in/product.js

@@ -0,0 +1,72 @@
+import { ArgumentError, CommandExecutionError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { buildProductUrl, normalizeProductSnapshot } from './parsers.js';
+import { gotoAmazon, SITE } from './shared.js';
+
+cli({
+  site: SITE,
+  name: 'product',
+  access: 'read',
+  description: 'Fetch the current Amazon.in price and selected product variant',
+  domain: 'amazon.in',
+  strategy: Strategy.UI,
+  browser: true,
+  navigateBefore: false,
+  siteSession: 'persistent',
+  args: [
+    {
+      name: 'input',
+      required: true,
+      positional: true,
+      help: 'Amazon.in product URL or ASIN',
+    },
+  ],
+  columns: [
+    'asin', 'title', 'price', 'mrp', 'discount', 'availability',
+    'size', 'colour', 'image_url', 'product_url',
+  ],
+  func: async (page, args) => {
+    let url;
+    try {
+      url = buildProductUrl(args.input);
+    } catch (error) {
+      throw new ArgumentError(error.message);
+    }
+    await gotoAmazon(page, url, 'product page');
+    try {
+      await page.wait({ selector: '#productTitle', timeout: 15 });
+    } catch {
+      throw new CommandExecutionError(
+        'Amazon.in product title did not appear',
+        'The product may be unavailable or the page layout may have changed.',
+      );
+    }
+    const snapshot = await page.evaluate(`
+      (() => {
+        const text = (selector) => (document.querySelector(selector)?.textContent || '')
+          .replace(/\\s+/g, ' ').trim();
+        const image = document.querySelector('#landingImage');
+        const snapshot = {
+          href: location.href,
+          title: text('#productTitle'),
+          priceText: text('#corePrice_feature_div .a-price:not(.a-text-price) .a-offscreen, #priceblock_ourprice, #priceblock_dealprice'),
+          mrpText: text('#corePrice_feature_div .a-price.a-text-price .a-offscreen, .basisPrice .a-offscreen'),
+          discountText: text('#corePrice_feature_div .savingsPercentage, .savingsPercentage'),
+          availabilityText: text('#availability'),
+          sizeText: text('#inline-twister-expanded-dimension-text-size_name, #variation_size_name .selection, #variation_size_name li.swatchSelect .a-button-text'),
+          colourText: text('#inline-twister-expanded-dimension-text-color_name, #variation_color_name .selection, #variation_color_name li.swatchSelect .a-button-text'),
+          imageUrl: image?.getAttribute('data-old-hires') || image?.currentSrc || image?.src || '',
+        };
+        return snapshot;
+      })()
+    `);
+    try {
+      return [normalizeProductSnapshot(snapshot)];
+    } catch (error) {
+      throw new CommandExecutionError(
+        `Amazon.in product details could not be normalized: ${error.message}`,
+        'Check the visible product page for an unavailable item or changed layout.',
+      );
+    }
+  },
+});

package/clis/amazon-in/search.js

@@ -0,0 +1,76 @@
+import {
+  ArgumentError,
+  CommandExecutionError,
+  EmptyResultError,
+} from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import {
+  buildSearchUrl,
+  cleanText,
+  normalizeSearchCards,
+  validatePositiveInteger,
+  validatePriceBounds,
+} from './parsers.js';
+import { argumentValue, gotoAmazon, SITE } from './shared.js';
+
+cli({
+  site: SITE,
+  name: 'search',
+  access: 'read',
+  description: 'Search Amazon.in products with inclusive INR price bounds and images',
+  domain: 'amazon.in',
+  strategy: Strategy.UI,
+  browser: true,
+  navigateBefore: false,
+  siteSession: 'persistent',
+  args: [
+    { name: 'query', required: true, positional: true, help: 'Product search query' },
+    { name: 'min-price', type: 'number', help: 'Inclusive minimum price in rupees' },
+    { name: 'max-price', type: 'number', help: 'Inclusive maximum price in rupees' },
+    { name: 'limit', type: 'int', default: 20, help: 'Maximum results (1-50)' },
+  ],
+  columns: [
+    'rank', 'asin', 'title', 'price', 'mrp', 'rating',
+    'review_count', 'image_url', 'product_url', 'is_sponsored',
+  ],
+  func: async (page, args) => {
+    const query = cleanText(args.query);
+    if (!query) throw new ArgumentError('query must not be empty');
+    const bounds = argumentValue(() => validatePriceBounds(args['min-price'], args['max-price']));
+    const limit = argumentValue(() => validatePositiveInteger(args.limit ?? 20, 'limit', 50));
+    await gotoAmazon(page, buildSearchUrl(query, bounds), 'product search');
+
+    const payload = await page.evaluate(`
+      (() => {
+        const text = (node) => (node?.textContent || '').replace(/\\s+/g, ' ').trim();
+        const cards = [...document.querySelectorAll('[data-component-type="s-search-result"]')]
+          .map((card) => ({
+            cardAsin: (card.getAttribute('data-asin') || '').trim().toUpperCase(),
+            cardTitle: text(card.querySelector('a.a-text-normal.s-line-clamp-2')),
+            cardPriceText: text(card.querySelector('.a-price:not(.a-text-price) .a-offscreen, .a-price .a-offscreen')),
+            cardMrpText: text(card.querySelector('.a-price.a-text-price .a-offscreen')),
+            cardRatingText: text(card.querySelector('[aria-label*="out of 5 stars"], .a-icon-alt')),
+            cardReviewText: text(card.querySelector('a[href*="#customerReviews"], [aria-label*="ratings"]')),
+            cardImageUrl: card.querySelector('img.s-image')?.currentSrc || card.querySelector('img.s-image')?.src || '',
+            cardSponsored: /sponsored/i.test(text(card.querySelector('.puis-sponsored-label-text, [data-component-type="sp-sponsored-result"]'))),
+          }));
+        return {
+          cards,
+          noResults: /no results for|did not match any products/i.test(document.body?.innerText || ''),
+        };
+      })()
+    `);
+    if (!payload || !Array.isArray(payload.cards)) {
+      throw new CommandExecutionError('Amazon.in search returned an unsupported page shape');
+    }
+    const rows = normalizeSearchCards(payload.cards, { ...bounds, limit });
+    if (rows.length === 0) {
+      if (payload.noResults || payload.cards.length > 0) throw new EmptyResultError('amazon-in search');
+      throw new CommandExecutionError(
+        'Amazon.in search exposed no result cards',
+        'The page layout may have changed or a robot challenge may be visible.',
+      );
+    }
+    return rows;
+  },
+});

package/clis/amazon-in/shared.js

@@ -0,0 +1,40 @@
+import {
+  ArgumentError,
+  AuthRequiredError,
+  CommandExecutionError,
+} from '@agentrhq/webcmd/errors';
+import { classifyPageState } from './parsers.js';
+
+export const SITE = 'amazon-in';
+export const DOMAIN = 'amazon.in';
+export const HOME_URL = 'https://www.amazon.in/';
+export const WISHLIST_URL = 'https://www.amazon.in/hz/wishlist/ls';
+
+export function argumentValue(fn) {
+  try {
+    return fn();
+  } catch (error) {
+    if (error instanceof RangeError) throw new ArgumentError(error.message);
+    throw error;
+  }
+}
+
+export async function assertUsablePage(page, context) {
+  const snapshot = await page.evaluate(`
+    (() => ({ url: location.href, text: document.body?.innerText || '' }))()
+  `);
+  const state = classifyPageState(snapshot.url, snapshot.text);
+  if (state === 'login') throw new AuthRequiredError(DOMAIN);
+  if (state === 'robot') {
+    throw new CommandExecutionError(
+      `Amazon robot check blocked ${context}`,
+      'Complete the visible challenge in the Webcmd browser, then retry.',
+    );
+  }
+}
+
+export async function gotoAmazon(page, url, context) {
+  await page.goto(url, { waitUntil: 'load' });
+  await page.wait(2);
+  await assertUsablePage(page, context);
+}