@agentrhq/webcmd 0.2.1 → 0.2.3

package/clis/reddit/popular.js

@@ -12,6 +12,7 @@ cli({
     ],
     columns: ['rank', 'id', 'title', 'subreddit', 'score', 'comments', 'author', 'url', 'created_utc', 'selftext', 'post_hint', 'url_overridden_by_dest', 'preview_image_url', 'gallery_urls'],
     pipeline: [
+        { navigate: 'https://www.reddit.com' },
         { evaluate: `(async () => {
   function decodeHtml(s) {
     if (typeof s !== 'string' || !s) return '';
@@ -43,7 +44,17 @@ cli({
   const res = await fetch('/r/popular.json?limit=' + limit + '&raw_json=1', {
     credentials: 'include'
   });
-  const d = await res.json();
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error('Reddit popular request failed: HTTP ' + res.status + ' ' + text.replace(/\\s+/g, ' ').slice(0, 160));
+  }
+  let d;
+  try {
+    d = JSON.parse(text);
+  } catch {
+    const kind = /^\\s*</.test(text) ? 'HTML' : 'non-JSON';
+    throw new Error('Reddit popular expected JSON but received ' + kind + ': ' + text.replace(/\\s+/g, ' ').slice(0, 160));
+  }
   return (d?.data?.children || []).map(c => ({
     id: c.data.id,
     title: c.data.title,

package/clis/reddit/popular.test.js

@@ -4,6 +4,8 @@ import './popular.js';
 
 describe('reddit popular adapter', () => {
   const command = getRegistry().get('reddit/popular');
+  const evaluate = command?.pipeline?.find((step) => step.evaluate)?.evaluate;
+  const map = command?.pipeline?.find((step) => step.map)?.map;
 
   it('exposes the full post-list shape including the 4 media columns', () => {
     expect(command?.columns).toEqual([
@@ -14,13 +16,20 @@ describe('reddit popular adapter', () => {
   });
 
   it('surfaces media via extractRedditMedia in evaluate + map', () => {
-    expect(command?.pipeline?.[0]?.evaluate).toContain('function extractRedditMedia');
-    expect(command?.pipeline?.[0]?.evaluate).toContain('...extractRedditMedia(c.data)');
-    expect(command?.pipeline?.[1]?.map).toMatchObject({
+    expect(evaluate).toContain('function extractRedditMedia');
+    expect(evaluate).toContain('...extractRedditMedia(c.data)');
+    expect(map).toMatchObject({
       post_hint: '${{ item.post_hint }}',
       url_overridden_by_dest: '${{ item.url_overridden_by_dest }}',
       preview_image_url: '${{ item.preview_image_url }}',
       gallery_urls: '${{ item.gallery_urls }}',
     });
   });
+
+  it('navigates to Reddit and guards HTML responses before JSON parsing', () => {
+    expect(command?.pipeline?.[0]).toEqual({ navigate: 'https://www.reddit.com' });
+    expect(evaluate).toContain('await res.text()');
+    expect(evaluate).toContain('Reddit popular expected JSON');
+    expect(evaluate).not.toContain('await res.json()');
+  });
 });

package/clis/zepto/add-to-cart.js

@@ -0,0 +1,53 @@
+import { CommandExecutionError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { CART_EVALUATE, DOMAIN, SITE, ZEPTO_NAV_OPTIONS, parseQuantityArg, resolveProductInput, safeGoto } from './utils.js';
+
+function addToCartEvaluate(quantity) {
+  return `
+    (async () => {
+      const clean = (value) => value == null ? '' : String(value).replace(/\\s+/g, ' ').trim();
+      const findButton = (pattern) => Array.from(document.querySelectorAll('button, [role="button"]')).find((node) => pattern.test(clean(node.innerText || node.textContent || node.getAttribute('aria-label'))));
+      let button = findButton(/^(ADD|Add to Cart)$/i);
+      if (!button) return { ok: false, message: 'ADD_BUTTON_NOT_FOUND' };
+      button.click();
+      await new Promise((resolve) => setTimeout(resolve, 800));
+      for (let i = 1; i < ${Number(quantity) || 1}; i += 1) {
+        const plus = findButton(/increase quantity by one|\\+|add/i);
+        plus?.click();
+        await new Promise((resolve) => setTimeout(resolve, 300));
+      }
+      const cart = (${CART_EVALUATE});
+      const itemCount = (cart.rows || []).reduce((sum, row) => sum + Number(row.quantity || 0), 0);
+      return { ok: true, message: 'Added to cart', item_count: itemCount };
+    })()
+  `;
+}
+
+cli({
+  site: SITE,
+  name: 'add-to-cart',
+  access: 'write',
+  description: 'Add a Zepto product to cart',
+  domain: DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    { name: 'product', required: true, positional: true, help: 'Product URL from Zepto search results' },
+    { name: 'quantity', type: 'int', default: 1, help: 'Quantity to add (max 12)' },
+  ],
+  columns: ['ok', 'product_id', 'quantity', 'item_count', 'message'],
+  func: async (page, kwargs) => {
+    const product = resolveProductInput(kwargs.product);
+    const quantity = parseQuantityArg(kwargs.quantity, 1, 12);
+    await safeGoto(page, product.url, 'zepto add-to-cart', ZEPTO_NAV_OPTIONS);
+    if (page.wait) await page.wait(2);
+    const result = await page.evaluate(addToCartEvaluate(quantity)).catch((error) => {
+      throw new CommandExecutionError(`zepto add-to-cart failed: ${error?.message || error}`);
+    });
+    if (!result?.ok) throw new CommandExecutionError(result?.message === 'ADD_BUTTON_NOT_FOUND' ? 'Could not find a Zepto add-to-cart button.' : 'Failed to add Zepto item to cart.');
+    return [{ ok: true, product_id: product.productId, quantity, item_count: Number(result.item_count || 0), message: 'Added to cart' }];
+  },
+});
+
+export const __test__ = { addToCartEvaluate };

package/clis/zepto/auth.js

@@ -0,0 +1,59 @@
+import { AuthRequiredError, TimeoutError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { DOMAIN, HOME_URL, SITE, ZEPTO_NAV_OPTIONS, safeGoto } from './utils.js';
+
+function authEvaluate() {
+  return `
+    (() => {
+      const text = document.body?.innerText || '';
+      const loggedIn = !/\\bLogin\\b/i.test(text) && !/please login/i.test(text);
+      return { loggedIn };
+    })()
+  `;
+}
+
+function openLoginEvaluate() {
+  return `
+    (() => {
+      const buttons = Array.from(document.querySelectorAll('button, [role="button"], a'));
+      const button = buttons.find((node) => /\\blogin\\b/i.test(node.innerText || node.textContent || node.getAttribute('aria-label') || ''));
+      button?.dispatchEvent?.(new MouseEvent('click', { bubbles: true, cancelable: true, view: window }));
+      return Boolean(button);
+    })()
+  `;
+}
+
+cli({
+  site: SITE,
+  name: 'login',
+  access: 'write',
+  description: 'Open Zepto login and wait until the browser session is authenticated',
+  domain: DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  defaultWindowMode: 'foreground',
+  siteSession: 'persistent',
+  args: [
+    { name: 'timeout', type: 'int', default: 300, help: 'Maximum seconds to wait for the user to finish login' },
+  ],
+  columns: ['status', 'logged_in', 'site'],
+  func: async (page, kwargs) => {
+    await safeGoto(page, HOME_URL, 'zepto login', ZEPTO_NAV_OPTIONS);
+    if ((await page.evaluate(authEvaluate()).catch(() => ({ loggedIn: false }))).loggedIn) {
+      return [{ status: 'already_logged_in', logged_in: true, site: SITE }];
+    }
+    await page.evaluate(openLoginEvaluate()).catch(() => false);
+    const timeout = Number(kwargs.timeout ?? 300);
+    const deadline = Date.now() + timeout * 1000;
+    while (Date.now() < deadline) {
+      await page.wait(2);
+      if ((await page.evaluate(authEvaluate()).catch(() => ({ loggedIn: false }))).loggedIn) {
+        return [{ status: 'login_complete', logged_in: true, site: SITE }];
+      }
+    }
+    throw new TimeoutError('zepto login', timeout, 'Run webcmd zepto login and complete the login dialog in the browser.');
+  },
+});
+
+export const __test__ = { authEvaluate, openLoginEvaluate };

package/clis/zepto/cart.js

@@ -0,0 +1,23 @@
+import { EmptyResultError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { CART_EVALUATE, DOMAIN, HOME_URL, SITE, ZEPTO_NAV_OPTIONS, normalizeCartRows, safeGoto } from './utils.js';
+
+cli({
+  site: SITE,
+  name: 'cart',
+  access: 'read',
+  description: 'Read Zepto cart line items',
+  domain: DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [],
+  columns: ['rank', 'product_id', 'title', 'pack_size', 'quantity', 'price', 'mrp', 'availability'],
+  func: async (page) => {
+    await safeGoto(page, HOME_URL, 'zepto cart', ZEPTO_NAV_OPTIONS);
+    if (page.wait) await page.wait(1);
+    const rows = normalizeCartRows(await page.evaluate(CART_EVALUATE));
+    if (!rows.length) throw new EmptyResultError('zepto cart', 'Zepto cart is empty or no visible cart items were found.');
+    return rows;
+  },
+});

package/clis/zepto/checkout.js

@@ -0,0 +1,60 @@
+import { AuthRequiredError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { CART_EVALUATE, DOMAIN, HOME_URL, SITE, ZEPTO_NAV_OPTIONS, safeGoto } from './utils.js';
+
+const CHECKOUT_EVALUATE = `
+  (async () => {
+    const clean = (value) => value == null ? '' : String(value).replace(/\\s+/g, ' ').trim();
+    const bodyText = clean(document.body?.innerText || document.body?.textContent || '');
+    if (/please login|\\bLogin\\b/i.test(bodyText) && /cart is empty|please login/i.test(bodyText)) {
+      return { ok: false, stage: 'login', url: location.href };
+    }
+    const cartButton = Array.from(document.querySelectorAll('button, [role="button"], a')).find((node) => /\\bCart\\b/i.test(clean(node.innerText || node.textContent || node.getAttribute('aria-label'))));
+    cartButton?.click();
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+    const text = clean(document.body?.innerText || document.body?.textContent || '');
+    const checkoutButton = Array.from(document.querySelectorAll('button, [role="button"], a')).find((node) => /checkout|proceed|continue/i.test(clean(node.innerText || node.textContent || node.getAttribute('aria-label'))));
+    checkoutButton?.click();
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+    const finalText = clean(document.body?.innerText || document.body?.textContent || '');
+    const cart = (${CART_EVALUATE});
+    return {
+      ok: Boolean(cartButton || checkoutButton || /checkout|payment|address|delivery/i.test(finalText || text)),
+      stage: /login|sign\\s*in|please login/i.test(finalText) ? 'login' :
+        /address/i.test(finalText) ? 'address' :
+        /payment|upi|card|cash/i.test(finalText) ? 'payment-review' :
+        /cart is empty/i.test(finalText) ? 'empty' :
+        'cart',
+      url: location.href,
+      item_count: (cart.rows || []).reduce((sum, row) => sum + Number(row.quantity || 0), 0),
+    };
+  })()
+`;
+
+cli({
+  site: SITE,
+  name: 'checkout',
+  access: 'write',
+  description: 'Open Zepto checkout review without placing an order',
+  domain: DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [],
+  columns: ['ok', 'stage', 'item_count', 'next_action', 'url'],
+  func: async (page) => {
+    await safeGoto(page, HOME_URL, 'zepto checkout', ZEPTO_NAV_OPTIONS);
+    if (page.wait) await page.wait(1);
+    const result = await page.evaluate(CHECKOUT_EVALUATE);
+    if (result?.stage === 'login') throw new AuthRequiredError(DOMAIN, 'Log into Zepto in the Webcmd browser session to open checkout.');
+    return [{
+      ok: Boolean(result?.ok),
+      stage: result?.stage || 'cart',
+      item_count: Number(result?.item_count || 0),
+      next_action: 'Complete visible checkout requirements manually; command stops before final submission.',
+      url: result?.url || HOME_URL,
+    }];
+  },
+});
+
+export const __test__ = { CHECKOUT_EVALUATE };

package/clis/zepto/location.js

@@ -0,0 +1,20 @@
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { DOMAIN, HOME_URL, SITE, ZEPTO_NAV_OPTIONS, normalizeLocationState, readLocationEvaluate, safeGoto } from './utils.js';
+
+cli({
+  site: SITE,
+  name: 'location',
+  access: 'read',
+  description: 'Show the selected Zepto delivery location',
+  domain: DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [],
+  columns: ['selected', 'label', 'area', 'city', 'pincode', 'hasCoordinates', 'source'],
+  func: async (page) => {
+    await safeGoto(page, HOME_URL, 'zepto location', ZEPTO_NAV_OPTIONS);
+    if (page.wait) await page.wait(1);
+    return [normalizeLocationState(await page.evaluate(readLocationEvaluate()))];
+  },
+});

package/clis/zepto/place-order.js

@@ -0,0 +1,47 @@
+import { CommandExecutionError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { DOMAIN, HOME_URL, SITE, ZEPTO_NAV_OPTIONS, safeGoto } from './utils.js';
+
+function parseConfirm(raw) {
+  return raw === true || raw === 'true' || raw === '1' || raw === 1;
+}
+
+function placeOrderEvaluate() {
+  return `
+    (() => {
+      const clean = (value) => value == null ? '' : String(value).replace(/\\s+/g, ' ').trim();
+      const button = Array.from(document.querySelectorAll('button, [role="button"]')).find((node) => /^(place order|pay now|make payment)$/i.test(clean(node.innerText || node.textContent || node.getAttribute('aria-label'))));
+      if (!button) return { ok: false, status: 'blocked', message: 'No final place-order/payment button is visible.' };
+      button.click();
+      return { ok: true, status: 'submitted', message: 'Clicked final Zepto order/payment button.' };
+    })()
+  `;
+}
+
+cli({
+  site: SITE,
+  name: 'place-order',
+  access: 'write',
+  description: 'Submit a real Zepto order only when --confirm true is passed',
+  domain: DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    { name: 'confirm', type: 'boolean', default: false, help: 'Required. Set true to submit a real Zepto order/payment action.' },
+  ],
+  columns: ['status', 'confirmed', 'message'],
+  func: async (page, kwargs) => {
+    if (!parseConfirm(kwargs.confirm)) {
+      return [{ status: 'no-op', confirmed: false, message: 'Pass --confirm true to submit a real Zepto order/payment action.' }];
+    }
+    await safeGoto(page, HOME_URL, 'zepto place-order', ZEPTO_NAV_OPTIONS);
+    const result = await page.evaluate(placeOrderEvaluate()).catch((error) => {
+      throw new CommandExecutionError(`zepto place-order failed: ${error?.message || error}`);
+    });
+    if (!result?.ok) throw new CommandExecutionError(result?.message || 'No final Zepto place-order/payment button is visible.');
+    return [{ status: result.status || 'submitted', confirmed: true, message: result.message || 'Submitted Zepto order.' }];
+  },
+});
+
+export const __test__ = { placeOrderEvaluate };

package/clis/zepto/product.js

@@ -0,0 +1,52 @@
+import { EmptyResultError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { DOMAIN, SITE, ZEPTO_NAV_OPTIONS, cleanText, normalizeProductRow, resolveProductInput, safeGoto } from './utils.js';
+
+function productEvaluate(productId) {
+  return `
+    (() => {
+      const productId = ${JSON.stringify(productId)};
+      const clean = (value) => value == null ? '' : String(value).replace(/\\s+/g, ' ').trim();
+      const text = clean(document.body?.innerText || document.body?.textContent || '');
+      const prices = Array.from(document.querySelectorAll('span,div'))
+        .map((node) => clean(node.textContent))
+        .filter((value) => /^₹\\s*\\d/i.test(value));
+      const title = clean(document.querySelector('h1')?.textContent)
+        || text.split('\\n').map(clean).find((line) => /[A-Za-z]/.test(line) && !/Delivery|Search|Login|Cart|Home|₹|Add to Cart/i.test(line))
+        || '';
+      return {
+        product_id: productId,
+        title,
+        brand: clean(Array.from(document.querySelectorAll('div,span')).find((node) => clean(node.textContent) === 'Brand')?.nextElementSibling?.textContent),
+        pack_size: text.match(/\\b\\d+(?:\\.\\d+)?\\s*(?:kg|g|ml|l|pcs?|pack)\\b/i)?.[0] || '',
+        price: prices[0] || '',
+        mrp: prices[1] || '',
+        availability: /out of stock|unavailable/i.test(text) ? 'Out of stock' : '',
+        url: location.href,
+      };
+    })()
+  `;
+}
+
+cli({
+  site: SITE,
+  name: 'product',
+  access: 'read',
+  description: 'Read Zepto product details',
+  domain: DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    { name: 'product', required: true, positional: true, help: 'Product URL from Zepto search results' },
+  ],
+  columns: ['product_id', 'title', 'brand', 'pack_size', 'price', 'mrp', 'availability', 'url'],
+  func: async (page, kwargs) => {
+    const product = resolveProductInput(kwargs.product);
+    await safeGoto(page, product.url, 'zepto product', ZEPTO_NAV_OPTIONS);
+    if (page.wait) await page.wait(2);
+    const row = normalizeProductRow(await page.evaluate(productEvaluate(product.productId)), 0);
+    if (!row.product_id || !cleanText(row.title)) throw new EmptyResultError('zepto product', `No product details found for ${product.productId}.`);
+    return [row];
+  },
+});

package/clis/zepto/search.js

@@ -0,0 +1,30 @@
+import { AuthRequiredError, EmptyResultError } from '@agentrhq/webcmd/errors';
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { DOMAIN, SITE, ZEPTO_NAV_OPTIONS, buildSearchUrl, normalizeProductRow, parseLimitArg, productCardsEvaluate, safeGoto } from './utils.js';
+
+cli({
+  site: SITE,
+  name: 'search',
+  access: 'read',
+  description: 'Search Zepto products',
+  domain: DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    { name: 'query', required: true, positional: true, help: 'Search query' },
+    { name: 'limit', type: 'int', default: 20, help: 'Maximum products to return (max 50)' },
+  ],
+  columns: ['rank', 'product_id', 'title', 'brand', 'pack_size', 'price', 'mrp', 'availability', 'url'],
+  func: async (page, kwargs) => {
+    const url = buildSearchUrl(kwargs.query);
+    const limit = parseLimitArg(kwargs.limit, 20, 50);
+    await safeGoto(page, url, 'zepto search', ZEPTO_NAV_OPTIONS);
+    if (page.wait) await page.wait(2);
+    const result = await page.evaluate(productCardsEvaluate(limit));
+    if (result?.authRequired) throw new AuthRequiredError(DOMAIN, 'Log into Zepto in the Webcmd browser session to search products.');
+    const rows = (result?.rows || []).map(normalizeProductRow).filter((row) => row.product_id && row.title);
+    if (!rows.length) throw new EmptyResultError('zepto search', `No Zepto products matched "${kwargs.query}".`);
+    return rows;
+  },
+});

package/clis/zepto/utils.js

@@ -0,0 +1,228 @@
+import { ArgumentError, CommandExecutionError } from '@agentrhq/webcmd/errors';
+
+export const SITE = 'zepto';
+export const DOMAIN = 'www.zepto.com';
+export const HOME_URL = 'https://www.zepto.com';
+export const MAX_LIMIT = 50;
+export const ZEPTO_NAV_OPTIONS = { waitUntil: 'none', settleMs: 1500 };
+
+export function cleanText(value) {
+  return typeof value === 'string'
+    ? value.replace(/\u00a0/g, ' ').replace(/\s+/g, ' ').trim()
+    : '';
+}
+
+export function parseMoney(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value > 999 ? value / 100 : value;
+  const match = cleanText(String(value ?? '')).replace(/,/g, '').match(/(\d+(?:\.\d+)?)/);
+  return match ? Number(match[1]) : null;
+}
+
+export function parseLimitArg(raw, fallback, max = MAX_LIMIT) {
+  if (raw === undefined || raw === null || raw === '') return fallback;
+  const num = Number(raw);
+  if (!Number.isInteger(num) || num < 1 || num > max) {
+    throw new ArgumentError(`--limit must be an integer between 1 and ${max} (got ${raw})`);
+  }
+  return num;
+}
+
+export function parseQuantityArg(raw, fallback, max = 12) {
+  if (raw === undefined || raw === null || raw === '') return fallback;
+  const num = Number(raw);
+  if (!Number.isInteger(num) || num < 1 || num > max) {
+    throw new ArgumentError(`--quantity must be an integer between 1 and ${max} (got ${raw})`);
+  }
+  return num;
+}
+
+export function buildSearchUrl(query) {
+  const normalized = cleanText(query);
+  if (!normalized) throw new ArgumentError('zepto search query cannot be empty');
+  return `${HOME_URL}/search?query=${encodeURIComponent(normalized)}`;
+}
+
+export function toZeptoUrl(value) {
+  const text = cleanText(value);
+  if (!text) return '';
+  try {
+    const url = new URL(text.startsWith('http') ? text : text.startsWith('/') ? text : `/${text}`, HOME_URL);
+    if (url.hostname !== DOMAIN && url.hostname !== 'zepto.com') throw new Error('not zepto');
+    url.hostname = DOMAIN;
+    url.hash = '';
+    return url.toString();
+  } catch {
+    return '';
+  }
+}
+
+export function resolveProductInput(input) {
+  const text = cleanText(input);
+  if (!text) throw new ArgumentError('zepto product requires a product URL');
+  const url = toZeptoUrl(text);
+  const match = url && new URL(url).pathname.match(/\/pvid\/([0-9a-f-]{36})(?:\/|$)/i);
+  if (!match) throw new ArgumentError('zepto product expects a Zepto /pn/.../pvid/<id> URL from search results');
+  return { productId: match[1], url };
+}
+
+export function normalizeProductRow(raw, rank) {
+  const url = toZeptoUrl(raw.url || raw.href || '');
+  const productId = cleanText(raw.product_id || raw.productId || raw.id || url.match(/\/pvid\/([0-9a-f-]{36})/i)?.[1] || '');
+  return {
+    rank: rank + 1,
+    product_id: productId,
+    title: cleanText(raw.title || raw.name),
+    brand: cleanText(raw.brand),
+    pack_size: cleanText(raw.pack_size || raw.packSize || raw.size),
+    price: parseMoney(raw.price),
+    mrp: parseMoney(raw.mrp || raw.original_price || raw.originalPrice),
+    availability: cleanText(raw.availability || raw.stock),
+    url,
+  };
+}
+
+function parsePersisted(raw) {
+  try {
+    const outer = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    const value = typeof outer?.value === 'string' ? JSON.parse(outer.value) : outer;
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+export function normalizeLocationState(raw = {}) {
+  const rawAddressText = cleanText(raw.addressText);
+  const addressText = /^select location$/i.test(rawAddressText) ? '' : rawAddressText;
+  const rawLabel = addressText.match(/^(Home|Work|Other)\b/i)?.[1] || '';
+  const label = rawLabel ? rawLabel[0].toUpperCase() + rawLabel.slice(1).toLowerCase() : '';
+  const publicAddressText = addressText
+    .replace(/^(Home|Work|Other)\s*[:-]?\s*/i, '')
+    .replace(/\b(?:house\s*number|floor|flat|apartment|door|building)\b\s*[-:#]?\s*[^,•\n]*/gi, '');
+  const parts = publicAddressText.split(/[,•\n]/).map(cleanText).filter(Boolean);
+  const position = raw.userPosition || raw.userGpsCoords || {};
+  const pincode = cleanText(raw.pincode || raw.pin || addressText.match(/\b\d{6}\b/)?.[0]);
+  const cityPart = parts.length > 1 ? (parts[parts.length - 1].toLowerCase() === 'india' && parts.length > 2 ? parts[parts.length - 2] : parts[parts.length - 1]) : cleanText(raw.city);
+  return {
+    selected: Boolean(addressText || position.latitude || position.longitude || raw.pincode),
+    label,
+    area: label ? '' : parts[0] || '',
+    city: cleanText(cityPart.replace(/\b\d{6}\b/g, '')),
+    pincode,
+    hasCoordinates: Boolean(position.latitude || position.longitude),
+    source: 'browser',
+  };
+}
+
+export async function safeGoto(page, url, label, options) {
+  await page.goto(url, options || ZEPTO_NAV_OPTIONS).catch((error) => {
+    const message = error?.message || String(error);
+    if (/net::ERR_ABORTED|Browser navigate command timed out/i.test(message)) return;
+    throw new CommandExecutionError(`${label} navigation failed: ${error?.message || error}`);
+  });
+}
+
+export function productCardsEvaluate(limit) {
+  return `
+    (() => {
+      const limit = ${Number(limit) || 20};
+      const clean = (value) => value == null ? '' : String(value).replace(/\\s+/g, ' ').trim();
+      const bodyText = clean(document.body?.innerText || document.body?.textContent || '');
+      if (/please login to continue searching|please login/i.test(bodyText) && location.pathname.includes('/search')) {
+        return { authRequired: true, rows: [], href: location.href };
+      }
+      const rows = [];
+      const seen = new Set();
+      const anchors = Array.from(document.querySelectorAll('a[href*="/pn/"][href*="/pvid/"]'));
+      for (const anchor of anchors) {
+        const href = anchor.href || anchor.getAttribute('href') || '';
+        const productId = href.match(/\\/pvid\\/([0-9a-f-]{36})/i)?.[1] || '';
+        if (!productId || seen.has(productId)) continue;
+        let root = anchor;
+        for (let i = 0; i < 6 && root?.parentElement; i += 1) {
+          const rootText = clean(root.innerText || root.textContent || '');
+          if (/₹|ADD|Add to Cart/i.test(rootText)) break;
+          root = root.parentElement;
+        }
+        const texts = Array.from(root.querySelectorAll('*'))
+          .filter((node) => node.children.length === 0)
+          .map((node) => clean(node.textContent))
+          .filter(Boolean);
+        const joined = texts.join(' ');
+        const prices = texts.filter((text) => /₹/.test(text));
+        const title = texts.find((text) => /[A-Za-z]/.test(text) && !/add|cart|off|bestseller|₹|\\d+(?:\\.\\d+)?\\s*(?:kg|g|ml|l|pcs?|pack)/i.test(text)) || clean(anchor.textContent);
+        if (!title) continue;
+        seen.add(productId);
+        rows.push({
+          product_id: productId,
+          title,
+          pack_size: texts.find((text) => /\\b\\d+(?:\\.\\d+)?\\s*(?:kg|g|ml|l|pcs?|pack)\\b/i.test(text)) || '',
+          price: prices[0] || '',
+          mrp: prices[1] || '',
+          availability: /out of stock|unavailable/i.test(joined) ? 'Out of stock' : '',
+          url: href,
+        });
+        if (rows.length >= limit) break;
+      }
+      return { rows, href: location.href };
+    })()
+  `;
+}
+
+export const CART_EVALUATE = `
+  (() => {
+    const clean = (value) => value == null ? '' : String(value).replace(/\\s+/g, ' ').trim();
+    const parse = (key) => {
+      try { return JSON.parse(localStorage.getItem(key) || 'null'); } catch { return null; }
+    };
+    const cart = parse('cart')?.state || {};
+    const content = cart.cartContent || {};
+    const rows = Object.entries(content).map(([id, item]) => {
+      const product = item?.productVariant || item?.product || item || {};
+      const productId = clean(product.id || product.productVariantId || item?.productVariantId || id);
+      const price = Number(item?.superSaverSellingPrice ?? item?.discountedSellingPrice ?? item?.sellingPrice ?? product.price ?? product.discountedSellingPrice ?? product.sellingPrice);
+      const mrp = Number(item?.mrp ?? product.mrp ?? product.mrpPrice);
+      return {
+        product_id: productId,
+        title: clean(product.name || product.productName || item?.title || item?.name),
+        pack_size: clean(product.formattedPacksize || product.packsize || product.unitOfMeasure || item?.quantityText),
+        quantity: Number(item?.quantity || item?.qty || 0),
+        price: Number.isFinite(price) ? (price > 999 ? price / 100 : price) : null,
+        mrp: Number.isFinite(mrp) ? (mrp > 999 ? mrp / 100 : mrp) : null,
+        availability: clean(product.availability || ''),
+      };
+    }).filter((row) => row.product_id && row.title && row.quantity);
+    return { rows, href: location.href, cartId: cart.cartId || '' };
+  })()
+`;
+
+export function normalizeCartRows(result) {
+  return (result?.rows || []).map((row, index) => ({
+    rank: index + 1,
+    product_id: cleanText(row.product_id),
+    title: cleanText(row.title),
+    pack_size: cleanText(row.pack_size),
+    quantity: Number(row.quantity || 0),
+    price: parseMoney(row.price),
+    mrp: parseMoney(row.mrp),
+    availability: cleanText(row.availability),
+  })).filter((row) => row.product_id && row.title && row.quantity);
+}
+
+export function readLocationEvaluate() {
+  return `
+    (() => {
+      const clean = (value) => value == null ? '' : String(value).replace(/\\s+/g, ' ').trim();
+      const parse = (key) => {
+        try { return JSON.parse(localStorage.getItem(key) || 'null'); } catch { return null; }
+      };
+      const persisted = parse('user-position');
+      const state = typeof persisted?.value === 'string' ? JSON.parse(persisted.value)?.state : persisted?.state;
+      return {
+        addressText: clean(document.querySelector('[data-testid="user-address"]')?.textContent || ''),
+        userPosition: state?.userPosition || null,
+        userGpsCoords: state?.userGpsCoords || null,
+      };
+    })()
+  `;
+}