@striderlabs/mcp-gap 0.1.0

package/src/browser.ts

@@ -0,0 +1,902 @@
+import { chromium, Browser, BrowserContext, Page } from 'patchright';
+import { saveCookies, loadCookies, saveSessionInfo, loadSessionInfo, SessionInfo } from './auth.js';
+
+export type Brand = 'gap' | 'old-navy' | 'banana-republic' | 'athleta';
+
+const BRAND_URLS: Record<Brand, string> = {
+  gap: 'https://www.gap.com',
+  'old-navy': 'https://www.oldnavy.com',
+  'banana-republic': 'https://www.bananarepublic.com',
+  athleta: 'https://www.athleta.com',
+};
+
+export interface ProductResult {
+  name: string;
+  price: string;
+  originalPrice?: string;
+  brand: Brand;
+  productId?: string;
+  url?: string;
+  imageUrl?: string;
+  colors?: string[];
+  inStock: boolean;
+  isOnSale: boolean;
+}
+
+export interface ProductDetails {
+  name: string;
+  price: string;
+  originalPrice?: string;
+  brand: Brand;
+  productId: string;
+  url: string;
+  description?: string;
+  availableSizes: string[];
+  availableColors: string[];
+  fitType?: string;
+  material?: string;
+  careInstructions?: string;
+  inStock: boolean;
+  isOnSale: boolean;
+  rating?: string;
+  reviewCount?: string;
+}
+
+export interface StoreInventory {
+  storeId: string;
+  storeName: string;
+  address: string;
+  inStock: boolean;
+  quantity?: string;
+  distance?: string;
+}
+
+export interface CartItem {
+  name: string;
+  size: string;
+  color: string;
+  quantity: number;
+  price: string;
+  productId?: string;
+  brand: Brand;
+}
+
+export interface CartSummary {
+  items: CartItem[];
+  subtotal: string;
+  estimatedTax?: string;
+  promotionDiscount?: string;
+  gapCashApplied?: string;
+  total: string;
+  itemCount: number;
+}
+
+export interface StoreLocation {
+  storeId: string;
+  name: string;
+  address: string;
+  city: string;
+  state: string;
+  zip: string;
+  phone?: string;
+  hours?: string;
+  distance?: string;
+  brands: Brand[];
+}
+
+export interface OrderInfo {
+  orderId: string;
+  status: string;
+  placedDate: string;
+  estimatedDelivery?: string;
+  items: string[];
+  total: string;
+  trackingNumber?: string;
+  carrier?: string;
+}
+
+export interface RewardsInfo {
+  gapCashBalance: string;
+  gapCashExpiry?: string;
+  rewardsPoints: string;
+  memberLevel?: string;
+  nextReward?: string;
+}
+
+export interface ReturnConfirmation {
+  returnId?: string;
+  orderId: string;
+  method: string;
+  instructions: string;
+  labelUrl?: string;
+}
+
+let browser: Browser | null = null;
+let context: BrowserContext | null = null;
+
+async function getBrowser(): Promise<{ browser: Browser; context: BrowserContext }> {
+  if (!browser || !context) {
+    browser = await chromium.launch({
+      headless: true,
+      args: ['--no-sandbox', '--disable-setuid-sandbox'],
+    });
+    context = await browser.newContext({
+      viewport: { width: 1280, height: 720 },
+      locale: 'en-US',
+      timezoneId: 'America/New_York',
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    });
+    await loadCookies(context);
+
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+  }
+  return { browser, context };
+}
+
+async function cleanup(): Promise<void> {
+  if (context) await context.close().catch(() => {});
+  if (browser) await browser.close().catch(() => {});
+  process.exit(0);
+}
+
+async function newPage(): Promise<Page> {
+  const { context } = await getBrowser();
+  const page = await context.newPage();
+  page.setDefaultTimeout(30000);
+  return page;
+}
+
+export async function checkLoginStatus(): Promise<SessionInfo> {
+  const saved = loadSessionInfo();
+  const page = await newPage();
+  try {
+    await page.goto('https://www.gap.com', { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2000);
+
+    const isLoggedIn = await page.evaluate(() => {
+      const accountEl = document.querySelector('[data-testid="account-nav"], .account-nav, [aria-label*="Account"]');
+      if (!accountEl) return false;
+      const text = accountEl.textContent || '';
+      return !text.toLowerCase().includes('sign in') && !text.toLowerCase().includes('log in');
+    });
+
+    const info: SessionInfo = {
+      isLoggedIn,
+      userEmail: saved?.userEmail,
+      userName: saved?.userName,
+      lastUpdated: new Date().toISOString(),
+    };
+
+    if (isLoggedIn) {
+      try {
+        const rewardsText = await page.$eval(
+          '[data-testid="rewards-balance"], .rewards-balance, [class*="reward"]',
+          (el) => el.textContent?.trim() || '',
+        );
+        info.gapCashBalance = rewardsText;
+      } catch {}
+    }
+
+    saveSessionInfo(info);
+    return info;
+  } finally {
+    await page.close();
+  }
+}
+
+export async function initiateLogin(brand: Brand = 'gap'): Promise<{ url: string; instructions: string }> {
+  const baseUrl = BRAND_URLS[brand];
+  const loginUrl = `${baseUrl}/account/login.html`;
+  const page = await newPage();
+  try {
+    await page.goto(loginUrl, { waitUntil: 'domcontentloaded' });
+    return {
+      url: loginUrl,
+      instructions:
+        `To log in to your Gap Inc. account:\n` +
+        `1. Open this URL in your browser: ${loginUrl}\n` +
+        `2. Sign in with your email and password\n` +
+        `3. Once logged in, your session will be saved automatically\n` +
+        `4. Run gap_status to verify your login`,
+    };
+  } finally {
+    await page.close();
+  }
+}
+
+export async function logout(): Promise<void> {
+  const { context: ctx } = await getBrowser();
+  await ctx.clearCookies();
+  const page = await newPage();
+  try {
+    await page.goto('https://www.gap.com/account/logout.html', { waitUntil: 'domcontentloaded' });
+  } catch {}
+  finally {
+    await page.close();
+  }
+}
+
+export async function searchProducts(
+  query: string,
+  brand: Brand = 'gap',
+  maxResults = 10,
+): Promise<ProductResult[]> {
+  const baseUrl = BRAND_URLS[brand];
+  const searchUrl = `${baseUrl}/browse/search.do?searchText=${encodeURIComponent(query)}`;
+  const page = await newPage();
+
+  try {
+    await page.goto(searchUrl, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2500);
+
+    // Try to wait for product grid
+    await page.waitForSelector('[data-testid="product-grid"], .product-card, [class*="productCard"], [class*="product-card"]', {
+      timeout: 8000,
+    }).catch(() => {});
+
+    const products = await page.evaluate(
+      ({ brand, maxResults }: { brand: Brand; maxResults: number }) => {
+        const results: ProductResult[] = [];
+
+        // Multiple selector strategies
+        const selectors = [
+          '[data-testid="product-card"]',
+          '[class*="productCard"]',
+          '[class*="product-card"]',
+          '[class*="ProductCard"]',
+          '.product-card',
+          '[data-component="ProductCard"]',
+        ];
+
+        let cards: Element[] = [];
+        for (const sel of selectors) {
+          const found = Array.from(document.querySelectorAll(sel));
+          if (found.length > 0) {
+            cards = found;
+            break;
+          }
+        }
+
+        for (const card of cards.slice(0, maxResults)) {
+          try {
+            const nameEl = card.querySelector(
+              '[data-testid="product-name"], [class*="productName"], [class*="product-name"], h3, h2, [class*="ProductName"]',
+            );
+            const name = nameEl?.textContent?.trim() || '';
+            if (!name) continue;
+
+            const priceEl = card.querySelector(
+              '[data-testid="price-current"], [class*="priceLabel"], [class*="price-current"], [class*="CurrentPrice"]',
+            );
+            const price = priceEl?.textContent?.trim() || 'N/A';
+
+            const originalPriceEl = card.querySelector(
+              '[data-testid="price-original"], [class*="priceOriginal"], [class*="price-original"], s',
+            );
+            const originalPrice = originalPriceEl?.textContent?.trim();
+
+            const linkEl = card.querySelector('a[href]') as HTMLAnchorElement | null;
+            const url = linkEl?.href || '';
+
+            const imgEl = card.querySelector('img') as HTMLImageElement | null;
+            const imageUrl = imgEl?.src || '';
+
+            const colorEls = Array.from(
+              card.querySelectorAll('[class*="colorSwatch"], [class*="color-swatch"], [aria-label*="color"]'),
+            );
+            const colors = colorEls
+              .map((el) => (el as HTMLElement).getAttribute('aria-label') || el.textContent?.trim() || '')
+              .filter(Boolean);
+
+            const isOnSale = !!originalPrice || card.textContent?.toLowerCase().includes('sale') || false;
+            const inStock = !card.textContent?.toLowerCase().includes('out of stock');
+
+            // Extract product ID from URL
+            const idMatch = url.match(/\/([A-Z0-9]+)(?:\?|$|\/)/);
+            const productId = idMatch?.[1];
+
+            results.push({ name, price, originalPrice, brand, productId, url, imageUrl, colors, inStock, isOnSale });
+          } catch {}
+        }
+        return results;
+      },
+      { brand, maxResults },
+    );
+
+    const { context: ctx } = await getBrowser();
+    await saveCookies(ctx);
+    return products;
+  } finally {
+    await page.close();
+  }
+}
+
+export async function getProductDetails(productUrl: string, brand: Brand = 'gap'): Promise<ProductDetails> {
+  const page = await newPage();
+  try {
+    await page.goto(productUrl, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2500);
+
+    const details = await page.evaluate(
+      ({ productUrl, brand }: { productUrl: string; brand: Brand }) => {
+        const getText = (sel: string) => document.querySelector(sel)?.textContent?.trim() || '';
+        const getAttr = (sel: string, attr: string) =>
+          (document.querySelector(sel) as HTMLElement)?.getAttribute(attr) || '';
+
+        const name = getText(
+          'h1, [data-testid="product-name"], [class*="ProductName"], [class*="product-name"]',
+        );
+
+        const price = getText(
+          '[data-testid="price-current"], [class*="priceLabel"], [class*="CurrentPrice"]',
+        );
+
+        const originalPrice =
+          getText('[data-testid="price-original"], [class*="priceOriginal"], s') || undefined;
+
+        const description = getText(
+          '[data-testid="product-description"], [class*="productDescription"], [class*="product-description"]',
+        );
+
+        // Sizes
+        const sizeEls = Array.from(
+          document.querySelectorAll(
+            '[data-testid="size-selector"] button, [class*="sizeOption"], [class*="size-option"], [aria-label*="size"]',
+          ),
+        );
+        const availableSizes = sizeEls
+          .filter((el) => !(el as HTMLElement).getAttribute('disabled') && !(el as HTMLElement).getAttribute('aria-disabled'))
+          .map((el) => el.textContent?.trim() || '')
+          .filter(Boolean);
+
+        // Colors
+        const colorEls = Array.from(
+          document.querySelectorAll(
+            '[data-testid="color-selector"] button, [class*="colorSwatch"], [class*="color-swatch"]',
+          ),
+        );
+        const availableColors = colorEls
+          .map((el) => (el as HTMLElement).getAttribute('aria-label') || el.textContent?.trim() || '')
+          .filter(Boolean);
+
+        const fitType = getText('[class*="fitType"], [data-testid="fit-type"]') || undefined;
+        const material = getText('[class*="material"], [class*="fabric"]') || undefined;
+
+        const rating = getText('[data-testid="rating"], [class*="ratingValue"]') || undefined;
+        const reviewCount = getText('[data-testid="review-count"], [class*="reviewCount"]') || undefined;
+
+        const isOnSale = !!originalPrice || document.body.textContent?.toLowerCase().includes('sale') || false;
+        const inStock = !document.body.textContent?.toLowerCase().includes('out of stock');
+
+        // Extract product ID from URL
+        const idMatch = productUrl.match(/\/([A-Z0-9]+)(?:\?|$)/);
+        const productId = idMatch?.[1] || '';
+
+        return {
+          name,
+          price,
+          originalPrice,
+          brand,
+          productId,
+          url: productUrl,
+          description,
+          availableSizes,
+          availableColors,
+          fitType,
+          material,
+          inStock,
+          isOnSale,
+          rating,
+          reviewCount,
+        } as ProductDetails;
+      },
+      { productUrl, brand },
+    );
+
+    return details;
+  } finally {
+    await page.close();
+  }
+}
+
+export async function checkStoreInventory(
+  productId: string,
+  zipCode: string,
+  brand: Brand = 'gap',
+): Promise<StoreInventory[]> {
+  const baseUrl = BRAND_URLS[brand];
+  const page = await newPage();
+  try {
+    // Navigate to product page first, then trigger store availability check
+    const productPage = `${baseUrl}/products/${productId}`;
+    await page.goto(productPage, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2000);
+
+    // Try to find and click "Check store availability" button
+    const checkStoreBtn = await page.$(
+      '[data-testid="store-availability"], button:has-text("Find in Store"), button:has-text("Check Store Availability")',
+    );
+
+    if (checkStoreBtn) {
+      await checkStoreBtn.click();
+      await page.waitForTimeout(1000);
+
+      // Enter zip code
+      const zipInput = await page.$('input[placeholder*="zip"], input[placeholder*="ZIP"], input[type="tel"]');
+      if (zipInput) {
+        await zipInput.fill(zipCode);
+        await page.keyboard.press('Enter');
+        await page.waitForTimeout(2000);
+      }
+    }
+
+    const stores = await page.evaluate(() => {
+      const storeEls = Array.from(
+        document.querySelectorAll('[data-testid="store-item"], [class*="storeItem"], [class*="store-item"]'),
+      );
+
+      return storeEls.map((el) => ({
+        storeId: (el as HTMLElement).getAttribute('data-store-id') || '',
+        storeName: el.querySelector('[class*="storeName"], [data-testid="store-name"]')?.textContent?.trim() || '',
+        address: el.querySelector('[class*="storeAddress"], [data-testid="store-address"]')?.textContent?.trim() || '',
+        inStock: !el.textContent?.toLowerCase().includes('out of stock'),
+        distance: el.querySelector('[class*="storeDistance"]')?.textContent?.trim(),
+      }));
+    });
+
+    return stores as StoreInventory[];
+  } finally {
+    await page.close();
+  }
+}
+
+export async function addToCart(
+  productUrl: string,
+  size: string,
+  color: string,
+  quantity = 1,
+): Promise<{ success: boolean; message: string; cartItemCount?: number }> {
+  const page = await newPage();
+  try {
+    await page.goto(productUrl, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2500);
+
+    // Select color
+    const colorBtn = await page.$(
+      `[aria-label="${color}"], button[title="${color}"], [data-color="${color}"]`,
+    );
+    if (colorBtn) {
+      await colorBtn.click();
+      await page.waitForTimeout(500);
+    }
+
+    // Select size
+    const sizeBtn = await page.$(
+      `button[data-size="${size}"], [aria-label="Size ${size}"], button:has-text("${size}")`,
+    );
+    if (!sizeBtn) {
+      return { success: false, message: `Size "${size}" not found or not available. Check gap_product_details for available sizes.` };
+    }
+    await sizeBtn.click();
+    await page.waitForTimeout(500);
+
+    // Set quantity if > 1
+    if (quantity > 1) {
+      const qtyInput = await page.$('input[name="quantity"], [data-testid="quantity-input"]');
+      if (qtyInput) {
+        await qtyInput.fill(String(quantity));
+      }
+    }
+
+    // Click Add to Cart
+    const addBtn = await page.$(
+      '[data-testid="add-to-cart"], button:has-text("Add to Bag"), button:has-text("Add to Cart")',
+    );
+    if (!addBtn) {
+      return { success: false, message: 'Add to Cart button not found.' };
+    }
+    await addBtn.click();
+    await page.waitForTimeout(2000);
+
+    // Check for success confirmation
+    const success = await page.evaluate(() => {
+      const confirmEl = document.querySelector(
+        '[data-testid="cart-confirmation"], [class*="addedToBag"], [class*="cart-confirmation"]',
+      );
+      return !!confirmEl || document.body.textContent?.includes('Added to Bag') || false;
+    });
+
+    const cartCountEl = await page.$('[data-testid="cart-count"], [class*="cartCount"], [class*="bag-count"]');
+    const cartCount = cartCountEl ? parseInt((await cartCountEl.textContent()) || '0') : undefined;
+
+    const { context: ctx } = await getBrowser();
+    await saveCookies(ctx);
+
+    return {
+      success: success || true,
+      message: success ? `Added ${quantity}x "${size}" in "${color}" to your bag.` : 'Item may have been added — please verify in your bag.',
+      cartItemCount: cartCount,
+    };
+  } finally {
+    await page.close();
+  }
+}
+
+export async function viewCart(brand: Brand = 'gap'): Promise<CartSummary> {
+  const baseUrl = BRAND_URLS[brand];
+  const page = await newPage();
+  try {
+    await page.goto(`${baseUrl}/cart`, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2500);
+
+    const cart = await page.evaluate(({ brand }: { brand: Brand }) => {
+      const items: CartItem[] = [];
+
+      const itemEls = Array.from(
+        document.querySelectorAll('[data-testid="cart-item"], [class*="cartItem"], [class*="cart-item"]'),
+      );
+
+      for (const el of itemEls) {
+        try {
+          const name = el.querySelector('[class*="productName"], [data-testid="product-name"], h3')?.textContent?.trim() || '';
+          const price = el.querySelector('[class*="price"], [data-testid="item-price"]')?.textContent?.trim() || '';
+          const sizeEl = el.querySelector('[class*="size"], [data-testid="item-size"]');
+          const colorEl = el.querySelector('[class*="color"], [data-testid="item-color"]');
+          const qtyEl = el.querySelector('input[name="quantity"], [data-testid="item-quantity"], select') as HTMLInputElement | null;
+          const qty = qtyEl ? parseInt(qtyEl.value || qtyEl.textContent || '1') : 1;
+
+          if (name) {
+            items.push({
+              name,
+              size: sizeEl?.textContent?.trim() || 'N/A',
+              color: colorEl?.textContent?.trim() || 'N/A',
+              quantity: qty,
+              price,
+              brand,
+            });
+          }
+        } catch {}
+      }
+
+      const getText = (sel: string) => document.querySelector(sel)?.textContent?.trim() || '';
+
+      return {
+        items,
+        subtotal: getText('[data-testid="subtotal"], [class*="subtotal"]') || '$0.00',
+        estimatedTax: getText('[data-testid="tax"], [class*="tax"]') || undefined,
+        promotionDiscount: getText('[data-testid="promo-discount"], [class*="promo"]') || undefined,
+        gapCashApplied: getText('[data-testid="gap-cash"], [class*="gapCash"]') || undefined,
+        total: getText('[data-testid="order-total"], [class*="orderTotal"], [class*="total"]') || '$0.00',
+        itemCount: items.length,
+      } as CartSummary;
+    }, { brand });
+
+    const { context: ctx } = await getBrowser();
+    await saveCookies(ctx);
+    return cart;
+  } finally {
+    await page.close();
+  }
+}
+
+export async function proceedToCheckout(brand: Brand = 'gap'): Promise<{ url: string; instructions: string }> {
+  const baseUrl = BRAND_URLS[brand];
+  const checkoutUrl = `${baseUrl}/checkout`;
+  return {
+    url: checkoutUrl,
+    instructions:
+      `To complete your purchase:\n` +
+      `1. Open: ${checkoutUrl}\n` +
+      `2. Review your bag and apply any Gap Cash or promo codes\n` +
+      `3. Enter/confirm shipping address\n` +
+      `4. Select shipping method\n` +
+      `5. Confirm payment and place order`,
+  };
+}
+
+export async function getRewardsInfo(brand: Brand = 'gap'): Promise<RewardsInfo> {
+  const baseUrl = BRAND_URLS[brand];
+  const page = await newPage();
+  try {
+    await page.goto(`${baseUrl}/account/rewards.html`, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2500);
+
+    const rewards = await page.evaluate(() => {
+      const getText = (sel: string) => document.querySelector(sel)?.textContent?.trim() || '';
+
+      const gapCashBalance =
+        getText('[data-testid="gap-cash-balance"], [class*="gapCashBalance"], [class*="gap-cash-balance"]') || '$0.00';
+      const gapCashExpiry =
+        getText('[data-testid="gap-cash-expiry"], [class*="gapCashExpiry"]') || undefined;
+      const rewardsPoints =
+        getText('[data-testid="rewards-points"], [class*="rewardsPoints"], [class*="points-balance"]') || '0';
+      const memberLevel =
+        getText('[data-testid="member-level"], [class*="memberLevel"], [class*="tier"]') || undefined;
+      const nextReward =
+        getText('[data-testid="next-reward"], [class*="nextReward"]') || undefined;
+
+      return { gapCashBalance, gapCashExpiry, rewardsPoints, memberLevel, nextReward };
+    });
+
+    const { context: ctx } = await getBrowser();
+    await saveCookies(ctx);
+    return rewards;
+  } finally {
+    await page.close();
+  }
+}
+
+export async function trackOrder(orderId: string, brand: Brand = 'gap'): Promise<OrderInfo> {
+  const baseUrl = BRAND_URLS[brand];
+  const page = await newPage();
+  try {
+    await page.goto(`${baseUrl}/account/orders.html`, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2500);
+
+    // Try to find the specific order
+    const orderLink = await page.$(`[data-order-id="${orderId}"], a:has-text("${orderId}")`);
+    if (orderLink) {
+      await orderLink.click();
+      await page.waitForTimeout(2000);
+    }
+
+    const orderInfo = await page.evaluate(({ orderId }: { orderId: string }) => {
+      const getText = (sel: string) => document.querySelector(sel)?.textContent?.trim() || '';
+
+      const status = getText('[data-testid="order-status"], [class*="orderStatus"], [class*="order-status"]') || 'Unknown';
+      const placedDate = getText('[data-testid="order-date"], [class*="orderDate"]') || '';
+      const estimatedDelivery = getText('[data-testid="estimated-delivery"], [class*="deliveryDate"]') || undefined;
+      const total = getText('[data-testid="order-total"], [class*="orderTotal"]') || '';
+      const trackingNumber = getText('[data-testid="tracking-number"], [class*="trackingNumber"]') || undefined;
+      const carrier = getText('[data-testid="carrier"], [class*="carrier"]') || undefined;
+
+      const itemEls = Array.from(document.querySelectorAll('[data-testid="order-item"], [class*="orderItem"]'));
+      const items = itemEls.map((el) => el.textContent?.trim() || '').filter(Boolean);
+
+      return { orderId, status, placedDate, estimatedDelivery, items, total, trackingNumber, carrier };
+    }, { orderId });
+
+    return orderInfo;
+  } finally {
+    await page.close();
+  }
+}
+
+export async function findStores(
+  zipCode: string,
+  brand?: Brand,
+  radius = 25,
+): Promise<StoreLocation[]> {
+  const baseUrl = brand ? BRAND_URLS[brand] : 'https://www.gap.com';
+  const page = await newPage();
+  try {
+    await page.goto(`${baseUrl}/stores/`, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2000);
+
+    // Enter zip code in store finder
+    const zipInput = await page.$('input[placeholder*="zip"], input[placeholder*="ZIP"], input[name="zip"], input[type="search"]');
+    if (zipInput) {
+      await zipInput.fill(zipCode);
+      await page.keyboard.press('Enter');
+      await page.waitForTimeout(3000);
+    }
+
+    const stores = await page.evaluate(({ brand }: { brand?: Brand }) => {
+      const storeEls = Array.from(
+        document.querySelectorAll('[data-testid="store-result"], [class*="storeResult"], [class*="store-result"], [class*="StoreItem"]'),
+      );
+
+      return storeEls.slice(0, 10).map((el) => {
+        const getText = (sel: string) => el.querySelector(sel)?.textContent?.trim() || '';
+        const name = getText('[class*="storeName"], [data-testid="store-name"], h3, h4') || 'Gap Store';
+        const address = getText('[class*="address"], [data-testid="store-address"]');
+        const phone = getText('[class*="phone"], [data-testid="store-phone"]') || undefined;
+        const hours = getText('[class*="hours"], [data-testid="store-hours"]') || undefined;
+        const distance = getText('[class*="distance"]') || undefined;
+
+        // Parse address parts
+        const parts = address.split(',').map((s: string) => s.trim());
+        const streetAddress = parts[0] || address;
+        const cityState = parts[1] || '';
+        const [city, stateZip] = cityState.split(' ').filter(Boolean).reduce(
+          (acc: [string, string[]], word: string) => {
+            if (/[A-Z]{2}/.test(word) || /\d{5}/.test(word)) acc[1].push(word);
+            else acc[0] += (acc[0] ? ' ' : '') + word;
+            return acc;
+          },
+          ['', []],
+        );
+
+        const detectedBrands: Brand[] = [];
+        const text = el.textContent?.toLowerCase() || '';
+        if (text.includes('gap')) detectedBrands.push('gap');
+        if (text.includes('old navy')) detectedBrands.push('old-navy');
+        if (text.includes('banana republic')) detectedBrands.push('banana-republic');
+        if (text.includes('athleta')) detectedBrands.push('athleta');
+        if (detectedBrands.length === 0 && brand) detectedBrands.push(brand);
+        if (detectedBrands.length === 0) detectedBrands.push('gap');
+
+        return {
+          storeId: (el as HTMLElement).getAttribute('data-store-id') || '',
+          name,
+          address: streetAddress,
+          city: city || '',
+          state: stateZip[0] || '',
+          zip: stateZip[1] || '',
+          phone,
+          hours,
+          distance,
+          brands: detectedBrands,
+        };
+      });
+    }, { brand });
+
+    return stores as StoreLocation[];
+  } finally {
+    await page.close();
+  }
+}
+
+export async function initiateReturn(
+  orderId: string,
+  itemName: string,
+  reason: string,
+  brand: Brand = 'gap',
+): Promise<ReturnConfirmation> {
+  const baseUrl = BRAND_URLS[brand];
+  const page = await newPage();
+  try {
+    await page.goto(`${baseUrl}/account/returns.html`, { waitUntil: 'domcontentloaded' });
+    await page.waitForTimeout(2000);
+
+    // Try to start return for specific order
+    const orderEl = await page.$(`[data-order-id="${orderId}"], button:has-text("Start Return")`);
+    if (orderEl) {
+      await orderEl.click();
+      await page.waitForTimeout(1500);
+    }
+
+    // Select reason
+    const reasonSelect = await page.$('select[name="reason"], [data-testid="return-reason"]');
+    if (reasonSelect) {
+      await (reasonSelect as HTMLSelectElement & { selectOption: (value: string) => Promise<void> }).selectOption?.({ label: reason });
+    }
+
+    const returnUrl = page.url();
+
+    const { context: ctx } = await getBrowser();
+    await saveCookies(ctx);
+
+    return {
+      orderId,
+      method: 'Mail or In-Store Drop-off',
+      instructions:
+        `To complete your return for order ${orderId}:\n` +
+        `1. Visit: ${baseUrl}/account/returns.html\n` +
+        `2. Select the item(s) you wish to return\n` +
+        `3. Choose your return reason: ${reason}\n` +
+        `4. Select return method (mail or in-store)\n` +
+        `5. For mail returns: print prepaid shipping label\n` +
+        `6. For in-store: bring item with original tags and receipt/order confirmation\n\n` +
+        `Items can be returned within 30 days of purchase. Final sale items are not eligible.`,
+      labelUrl: returnUrl !== `${baseUrl}/account/returns.html` ? returnUrl : undefined,
+    };
+  } finally {
+    await page.close();
+  }
+}
+
+export function getSizeGuide(
+  category: string,
+  brand: Brand = 'gap',
+): { category: string; brand: Brand; guide: Record<string, unknown> } {
+  const guides: Record<string, Record<string, unknown>> = {
+    tops: {
+      note: 'Gap tops sizing guide (US sizes)',
+      womens: {
+        XS: { bust: '32-33"', waist: '24-25"', hips: '34-35"' },
+        S: { bust: '34-35"', waist: '26-27"', hips: '36-37"' },
+        M: { bust: '36-37"', waist: '28-29"', hips: '38-39"' },
+        L: { bust: '38-40"', waist: '30-32"', hips: '40-42"' },
+        XL: { bust: '41-43"', waist: '33-35"', hips: '43-45"' },
+        XXL: { bust: '44-46"', waist: '36-38"', hips: '46-48"' },
+      },
+      mens: {
+        XS: { chest: '34-36"', waist: '28-30"' },
+        S: { chest: '36-38"', waist: '30-32"' },
+        M: { chest: '38-40"', waist: '32-34"' },
+        L: { chest: '40-42"', waist: '34-36"' },
+        XL: { chest: '42-44"', waist: '36-38"' },
+        XXL: { chest: '44-46"', waist: '38-40"' },
+      },
+    },
+    bottoms: {
+      note: 'Gap bottoms sizing guide (US sizes)',
+      womens: {
+        '00': { waist: '24"', hips: '34"' },
+        '0': { waist: '25"', hips: '35"' },
+        '2': { waist: '26"', hips: '36"' },
+        '4': { waist: '27"', hips: '37"' },
+        '6': { waist: '28"', hips: '38"' },
+        '8': { waist: '29"', hips: '39"' },
+        '10': { waist: '30"', hips: '40"' },
+        '12': { waist: '31-32"', hips: '41-42"' },
+        '14': { waist: '33-34"', hips: '43-44"' },
+        '16': { waist: '35-36"', hips: '45-46"' },
+      },
+      mens: {
+        '28x30': { waist: '28"', inseam: '30"' },
+        '30x30': { waist: '30"', inseam: '30"' },
+        '32x30': { waist: '32"', inseam: '30"' },
+        '34x30': { waist: '34"', inseam: '30"' },
+        '36x30': { waist: '36"', inseam: '30"' },
+        '28x32': { waist: '28"', inseam: '32"' },
+        '30x32': { waist: '30"', inseam: '32"' },
+        '32x32': { waist: '32"', inseam: '32"' },
+        '34x32': { waist: '34"', inseam: '32"' },
+      },
+    },
+    shoes: {
+      note: 'Gap/Old Navy shoe sizing guide',
+      womensToMens: {
+        '5': '3.5',
+        '5.5': '4',
+        '6': '4.5',
+        '6.5': '5',
+        '7': '5.5',
+        '7.5': '6',
+        '8': '6.5',
+        '8.5': '7',
+        '9': '7.5',
+        '9.5': '8',
+        '10': '8.5',
+        '11': '9.5',
+      },
+      usToEU: {
+        '5': '35',
+        '6': '36',
+        '7': '37-38',
+        '8': '38-39',
+        '9': '39-40',
+        '10': '40-41',
+        '11': '41-42',
+        '12': '42-43',
+      },
+    },
+    kids: {
+      note: 'Gap Kids sizing guide',
+      toddler: {
+        '2T': { height: '32-34"', weight: '25-29 lbs' },
+        '3T': { height: '35-37"', weight: '30-34 lbs' },
+        '4T': { height: '38-40"', weight: '35-40 lbs' },
+        '5T': { height: '41-43"', weight: '41-46 lbs' },
+      },
+      kids: {
+        XS: { height: '44-47"', weight: '47-55 lbs', age: '4-5' },
+        S: { height: '47-52"', weight: '55-68 lbs', age: '6-7' },
+        M: { height: '52-57"', weight: '68-84 lbs', age: '8-9' },
+        L: { height: '57-61"', weight: '84-100 lbs', age: '10-11' },
+        XL: { height: '61-64"', weight: '100-120 lbs', age: '12-13' },
+        XXL: { height: '64-67"', weight: '120-135 lbs', age: '14-15' },
+      },
+    },
+  };
+
+  const normalizedCategory = category.toLowerCase();
+  let guide = guides[normalizedCategory];
+
+  if (!guide) {
+    // Try partial match
+    const key = Object.keys(guides).find((k) => normalizedCategory.includes(k) || k.includes(normalizedCategory));
+    guide = key ? guides[key] : { message: `Size guide for "${category}" not found. Available: ${Object.keys(guides).join(', ')}` };
+  }
+
+  // Athleta has slightly different sizing (athletic fit)
+  if (brand === 'athleta' && guide) {
+    guide = { ...guide, note: 'Athleta sizing — athletic fit, generally runs true to size or slightly small' };
+  }
+
+  return { category, brand, guide };
+}