@striderlabs/mcp-bjs 0.1.0

package/src/browser.ts

@@ -0,0 +1,1050 @@
+import { chromium, Browser, BrowserContext, Page } from "patchright";
+import {
+  saveCookies,
+  loadCookies,
+  saveSessionInfo,
+  loadSessionInfo,
+  clearAuthData,
+  SessionInfo,
+} from "./auth.js";
+
+const BJS_BASE = "https://www.bjs.com";
+
+let browser: Browser | null = null;
+let context: BrowserContext | null = null;
+let page: Page | null = null;
+
+// ── Data Types ────────────────────────────────────────────────────────────────
+
+export interface ProductResult {
+  name: string;
+  itemNumber?: string;
+  price?: string;
+  unitPrice?: string;
+  brand?: string;
+  rating?: string;
+  reviewCount?: string;
+  inStock: boolean;
+  imageUrl?: string;
+  productUrl?: string;
+  isMemberPrice?: boolean;
+}
+
+export interface ProductDetails extends ProductResult {
+  description?: string;
+  features?: string[];
+  dimensions?: string;
+  weight?: string;
+  model?: string;
+  upc?: string;
+}
+
+export interface CartItem {
+  name: string;
+  itemNumber?: string;
+  quantity: number;
+  price: string;
+  lineTotal?: string;
+}
+
+export interface CartSummary {
+  items: CartItem[];
+  subtotal: string;
+  estimatedTax?: string;
+  total: string;
+  itemCount: number;
+  fulfillmentType?: string;
+}
+
+export interface Club {
+  clubId: string;
+  name: string;
+  address: string;
+  city: string;
+  state: string;
+  zip: string;
+  phone?: string;
+  distance?: string;
+  hours?: string;
+  hasGas?: boolean;
+  gasPriceRegular?: string;
+  gasPricePremium?: string;
+  gasPriceDiesel?: string;
+}
+
+export interface Coupon {
+  couponId: string;
+  title: string;
+  description?: string;
+  discount?: string;
+  expiryDate?: string;
+  isClipped: boolean;
+  category?: string;
+}
+
+export interface Order {
+  orderId: string;
+  orderDate: string;
+  status: string;
+  total: string;
+  itemCount?: number;
+  fulfillmentType?: string;
+  trackingNumber?: string;
+}
+
+// ── Browser Lifecycle ─────────────────────────────────────────────────────────
+
+async function initBrowser(): Promise<void> {
+  if (browser) return;
+
+  browser = await chromium.launch({
+    headless: true,
+    channel: "chrome",
+    args: [
+      "--no-sandbox",
+      "--disable-setuid-sandbox",
+      "--disable-blink-features=AutomationControlled",
+    ],
+  });
+
+  context = await browser.newContext({
+    viewport: { width: 1280, height: 720 },
+    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",
+    locale: "en-US",
+    timezoneId: "America/New_York",
+  });
+
+  await loadCookies(context);
+
+  page = await context.newPage();
+  page.setDefaultTimeout(30000);
+}
+
+export async function closeBrowser(): Promise<void> {
+  if (context) await saveCookies(context);
+  if (browser) {
+    await browser.close();
+    browser = null;
+    context = null;
+    page = null;
+  }
+}
+
+async function getPage(): Promise<Page> {
+  await initBrowser();
+  if (!page) throw new Error("Failed to initialize browser page");
+  return page;
+}
+
+// ── Auth ──────────────────────────────────────────────────────────────────────
+
+export async function checkLoginStatus(): Promise<SessionInfo> {
+  const p = await getPage();
+  await p.goto(`${BJS_BASE}/`, { waitUntil: "domcontentloaded" });
+
+  const isLoggedIn = await p.evaluate(() => {
+    const signInBtn = document.querySelector(
+      '[data-testid="sign-in-link"], a[href*="sign-in"], .signin-link'
+    );
+    const accountEl = document.querySelector(
+      '[data-testid="account-menu"], .account-name, .member-name'
+    );
+    return !!accountEl && !signInBtn;
+  });
+
+  let memberName: string | undefined;
+  let memberEmail: string | undefined;
+  let membershipNumber: string | undefined;
+
+  if (isLoggedIn) {
+    try {
+      const info = await p.evaluate(() => {
+        const nameEl = document.querySelector(
+          ".account-name, .member-name, [data-testid='member-name']"
+        );
+        return { name: nameEl?.textContent?.trim() };
+      });
+      memberName = info.name;
+
+      // Try to get more details from the account page
+      await p.goto(`${BJS_BASE}/account/profile`, {
+        waitUntil: "domcontentloaded",
+      });
+      const profileInfo = await p.evaluate(() => {
+        const emailEl = document.querySelector(
+          '[data-testid="email"], .profile-email, input[name="email"]'
+        );
+        const membershipEl = document.querySelector(
+          '[data-testid="membership-number"], .membership-number'
+        );
+        return {
+          email:
+            emailEl?.getAttribute("value") ||
+            emailEl?.textContent?.trim(),
+          membershipNumber: membershipEl?.textContent?.trim(),
+        };
+      });
+      memberEmail = profileInfo.email ?? undefined;
+      membershipNumber = profileInfo.membershipNumber ?? undefined;
+    } catch {
+      // Profile page may redirect if not truly logged in
+    }
+  }
+
+  const session: SessionInfo = {
+    isLoggedIn,
+    memberName,
+    memberEmail,
+    membershipNumber,
+    lastUpdated: new Date().toISOString(),
+  };
+
+  await saveSessionInfo(session);
+  return session;
+}
+
+export async function initiateLogin(): Promise<{
+  loginUrl: string;
+  message: string;
+}> {
+  const p = await getPage();
+  await p.goto(`${BJS_BASE}/account/sign-in`, {
+    waitUntil: "domcontentloaded",
+  });
+  const url = p.url();
+  return {
+    loginUrl: url,
+    message:
+      "Please complete login in the browser window. After signing in, call bjs_status to confirm your session is active.",
+  };
+}
+
+export async function logout(): Promise<{ success: boolean }> {
+  const p = await getPage();
+  try {
+    await p.goto(`${BJS_BASE}/account/sign-out`, {
+      waitUntil: "domcontentloaded",
+    });
+  } catch {
+    // Ignore navigation errors
+  }
+  await clearAuthData();
+  return { success: true };
+}
+
+// ── Product Search ────────────────────────────────────────────────────────────
+
+export async function searchProducts(
+  query: string,
+  maxResults = 10,
+  clubId?: string
+): Promise<ProductResult[]> {
+  const p = await getPage();
+  const url = clubId
+    ? `${BJS_BASE}/search?q=${encodeURIComponent(query)}&storeId=${clubId}`
+    : `${BJS_BASE}/search?q=${encodeURIComponent(query)}`;
+
+  await p.goto(url, { waitUntil: "domcontentloaded" });
+
+  // Wait for results
+  await p
+    .waitForSelector(
+      '[data-testid="product-tile"], .product-item, .product-card',
+      { timeout: 10000 }
+    )
+    .catch(() => {});
+
+  const results = await p.evaluate((max: number) => {
+    const tiles = document.querySelectorAll(
+      '[data-testid="product-tile"], .product-item, .product-card, .product-tile'
+    );
+    const products: {
+      name: string;
+      itemNumber?: string;
+      price?: string;
+      unitPrice?: string;
+      brand?: string;
+      rating?: string;
+      reviewCount?: string;
+      inStock: boolean;
+      imageUrl?: string;
+      productUrl?: string;
+      isMemberPrice?: boolean;
+    }[] = [];
+
+    Array.from(tiles)
+      .slice(0, max)
+      .forEach((tile) => {
+        const nameEl = tile.querySelector(
+          '[data-testid="product-name"], .product-name, h2, h3'
+        );
+        const priceEl = tile.querySelector(
+          '[data-testid="product-price"], .product-price, .price, .sale-price'
+        );
+        const unitPriceEl = tile.querySelector(
+          ".unit-price, .price-per-unit, [data-testid='unit-price']"
+        );
+        const brandEl = tile.querySelector(
+          ".brand, .product-brand, [data-testid='brand']"
+        );
+        const ratingEl = tile.querySelector(".rating, .star-rating, [aria-label*='star']");
+        const reviewEl = tile.querySelector(".review-count, .ratings-count");
+        const imgEl = tile.querySelector("img") as HTMLImageElement | null;
+        const linkEl = tile.querySelector("a") as HTMLAnchorElement | null;
+        const itemNumEl = tile.querySelector(
+          "[data-item-number], [data-sku], [data-testid='item-number']"
+        );
+        const outOfStock = !!(
+          tile.querySelector(".out-of-stock, [data-testid='out-of-stock']") ||
+          tile.textContent?.toLowerCase().includes("out of stock")
+        );
+
+        const name = nameEl?.textContent?.trim();
+        if (!name) return;
+
+        products.push({
+          name,
+          itemNumber:
+            itemNumEl?.getAttribute("data-item-number") ||
+            itemNumEl?.getAttribute("data-sku") ||
+            itemNumEl?.textContent?.trim(),
+          price: priceEl?.textContent?.trim().replace(/\s+/g, " "),
+          unitPrice: unitPriceEl?.textContent?.trim(),
+          brand: brandEl?.textContent?.trim(),
+          rating: ratingEl?.textContent?.trim() || ratingEl?.getAttribute("aria-label"),
+          reviewCount: reviewEl?.textContent?.trim(),
+          inStock: !outOfStock,
+          imageUrl: imgEl?.src,
+          productUrl: linkEl?.href,
+          isMemberPrice: !!(
+            tile.querySelector(".member-price, .club-price") ||
+            tile.textContent?.toLowerCase().includes("member")
+          ),
+        });
+      });
+
+    return products;
+  }, maxResults);
+
+  return results;
+}
+
+export async function getProductDetails(
+  productUrl: string
+): Promise<ProductDetails> {
+  const p = await getPage();
+  const url = productUrl.startsWith("http")
+    ? productUrl
+    : `${BJS_BASE}${productUrl}`;
+  await p.goto(url, { waitUntil: "domcontentloaded" });
+
+  await p
+    .waitForSelector('[data-testid="product-name"], .product-name, h1', {
+      timeout: 10000,
+    })
+    .catch(() => {});
+
+  return await p.evaluate(() => {
+    const nameEl = document.querySelector(
+      "h1, [data-testid='product-name'], .product-name"
+    );
+    const priceEl = document.querySelector(
+      "[data-testid='product-price'], .product-price, .price"
+    );
+    const unitPriceEl = document.querySelector(".unit-price, .price-per-unit");
+    const brandEl = document.querySelector(".brand, [data-testid='brand']");
+    const descEl = document.querySelector(
+      "[data-testid='description'], .product-description, .description"
+    );
+    const ratingEl = document.querySelector(
+      ".rating, .star-rating, [data-testid='rating']"
+    );
+    const reviewEl = document.querySelector(".review-count, .ratings-count");
+    const imgEl = document.querySelector(".product-image img") as HTMLImageElement | null;
+    const itemNumEl = document.querySelector(
+      "[data-testid='item-number'], .item-number"
+    );
+    const modelEl = document.querySelector(
+      "[data-testid='model-number'], .model-number"
+    );
+    const outOfStock = !!(
+      document.querySelector(".out-of-stock, [data-testid='out-of-stock']") ||
+      document.body.textContent?.toLowerCase().includes("out of stock")
+    );
+
+    const featureEls = document.querySelectorAll(
+      ".product-features li, [data-testid='features'] li"
+    );
+    const features = Array.from(featureEls)
+      .map((el) => el.textContent?.trim())
+      .filter(Boolean) as string[];
+
+    return {
+      name: nameEl?.textContent?.trim() || "Unknown",
+      itemNumber: itemNumEl?.textContent?.trim(),
+      price: priceEl?.textContent?.trim().replace(/\s+/g, " "),
+      unitPrice: unitPriceEl?.textContent?.trim(),
+      brand: brandEl?.textContent?.trim(),
+      description: descEl?.textContent?.trim(),
+      features,
+      model: modelEl?.textContent?.trim(),
+      rating: ratingEl?.textContent?.trim(),
+      reviewCount: reviewEl?.textContent?.trim(),
+      inStock: !outOfStock,
+      imageUrl: imgEl?.src,
+      productUrl: window.location.href,
+    };
+  });
+}
+
+// ── Inventory ─────────────────────────────────────────────────────────────────
+
+export async function checkClubInventory(
+  productUrl: string,
+  clubId?: string
+): Promise<{ inStock: boolean; quantity?: string; clubName?: string; message: string }> {
+  const p = await getPage();
+  const url = productUrl.startsWith("http")
+    ? productUrl
+    : `${BJS_BASE}${productUrl}`;
+  await p.goto(url, { waitUntil: "domcontentloaded" });
+
+  if (clubId) {
+    // Try to switch to the specified club
+    await p.evaluate((id: string) => {
+      const clubSelect = document.querySelector(
+        `[data-club-id='${id}'], select[name='club']`
+      ) as HTMLElement | null;
+      if (clubSelect) clubSelect.click();
+    }, clubId);
+    await p.waitForTimeout(1500);
+  }
+
+  return await p.evaluate(() => {
+    const outOfStockEl = document.querySelector(
+      ".out-of-stock, [data-testid='out-of-stock'], .not-available"
+    );
+    const inStockEl = document.querySelector(
+      ".in-stock, [data-testid='in-stock'], .add-to-cart-btn:not([disabled])"
+    );
+    const qtyEl = document.querySelector(
+      ".availability, .stock-quantity, [data-testid='availability']"
+    );
+    const clubNameEl = document.querySelector(
+      ".selected-club, [data-testid='club-name']"
+    );
+
+    const inStock = !outOfStockEl && !!inStockEl;
+    return {
+      inStock,
+      quantity: qtyEl?.textContent?.trim(),
+      clubName: clubNameEl?.textContent?.trim(),
+      message: inStock
+        ? "Item is available at your selected club"
+        : "Item is out of stock at your selected club",
+    };
+  });
+}
+
+// ── Cart ──────────────────────────────────────────────────────────────────────
+
+export async function addToCart(
+  productUrl: string,
+  quantity = 1
+): Promise<{ success: boolean; cartCount?: number; message: string }> {
+  const p = await getPage();
+  const url = productUrl.startsWith("http")
+    ? productUrl
+    : `${BJS_BASE}${productUrl}`;
+  await p.goto(url, { waitUntil: "domcontentloaded" });
+
+  // Set quantity if > 1
+  if (quantity > 1) {
+    const qtyInput = await p
+      .$("input[name='quantity'], input[data-testid='quantity-input']")
+      .catch(() => null);
+    if (qtyInput) {
+      await qtyInput.fill(String(quantity));
+    }
+  }
+
+  // Click Add to Cart
+  const addBtn = await p
+    .$(
+      "[data-testid='add-to-cart-btn'], .add-to-cart-btn, button:has-text('Add to Cart'), button:has-text('Add to club')"
+    )
+    .catch(() => null);
+
+  if (!addBtn) {
+    return { success: false, message: "Could not find Add to Cart button — item may be out of stock" };
+  }
+
+  await addBtn.click();
+  await p.waitForTimeout(2000);
+
+  const cartCount = await p.evaluate(() => {
+    const el = document.querySelector(
+      ".cart-count, .cart-badge, [data-testid='cart-count']"
+    );
+    const text = el?.textContent?.trim();
+    return text ? parseInt(text, 10) : undefined;
+  });
+
+  return {
+    success: true,
+    cartCount,
+    message: `Added ${quantity}x item to cart${cartCount !== undefined ? `. Cart now has ${cartCount} item(s).` : "."}`,
+  };
+}
+
+export async function viewCart(): Promise<CartSummary> {
+  const p = await getPage();
+  await p.goto(`${BJS_BASE}/cart`, { waitUntil: "domcontentloaded" });
+
+  await p
+    .waitForSelector(".cart-item, [data-testid='cart-item']", {
+      timeout: 8000,
+    })
+    .catch(() => {});
+
+  return await p.evaluate(() => {
+    const itemEls = document.querySelectorAll(
+      ".cart-item, [data-testid='cart-item']"
+    );
+    const items: {
+      name: string;
+      quantity: number;
+      price: string;
+      lineTotal?: string;
+    }[] = [];
+
+    itemEls.forEach((el) => {
+      const nameEl = el.querySelector(
+        ".item-name, [data-testid='item-name'], a"
+      );
+      const qtyEl = el.querySelector(
+        "input[name='quantity'], .item-quantity, [data-testid='item-qty']"
+      ) as HTMLInputElement | null;
+      const priceEl = el.querySelector(
+        ".item-price, [data-testid='item-price']"
+      );
+      const totalEl = el.querySelector(
+        ".line-total, [data-testid='line-total']"
+      );
+
+      const name = nameEl?.textContent?.trim();
+      if (!name) return;
+
+      items.push({
+        name,
+        quantity: qtyEl
+          ? parseInt(qtyEl.value || qtyEl.textContent || "1", 10)
+          : 1,
+        price: priceEl?.textContent?.trim() || "N/A",
+        lineTotal: totalEl?.textContent?.trim(),
+      });
+    });
+
+    const subtotalEl = document.querySelector(
+      ".subtotal, [data-testid='subtotal']"
+    );
+    const taxEl = document.querySelector(
+      ".estimated-tax, [data-testid='tax']"
+    );
+    const totalEl = document.querySelector(
+      ".order-total, [data-testid='order-total']"
+    );
+    const fulfillmentEl = document.querySelector(
+      ".fulfillment-type, [data-testid='fulfillment']"
+    );
+
+    return {
+      items,
+      subtotal: subtotalEl?.textContent?.trim() || "N/A",
+      estimatedTax: taxEl?.textContent?.trim(),
+      total: totalEl?.textContent?.trim() || "N/A",
+      itemCount: items.length,
+      fulfillmentType: fulfillmentEl?.textContent?.trim(),
+    };
+  });
+}
+
+export async function removeFromCart(
+  itemName: string
+): Promise<{ success: boolean; message: string }> {
+  const p = await getPage();
+  await p.goto(`${BJS_BASE}/cart`, { waitUntil: "domcontentloaded" });
+
+  const removed = await p.evaluate((name: string) => {
+    const items = document.querySelectorAll(
+      ".cart-item, [data-testid='cart-item']"
+    );
+    for (const item of Array.from(items)) {
+      const nameEl = item.querySelector(".item-name, [data-testid='item-name'], a");
+      if (nameEl?.textContent?.toLowerCase().includes(name.toLowerCase())) {
+        const removeBtn = item.querySelector(
+          ".remove-btn, [data-testid='remove-item'], button:has-text('Remove')"
+        ) as HTMLButtonElement | null;
+        if (removeBtn) {
+          removeBtn.click();
+          return true;
+        }
+      }
+    }
+    return false;
+  }, itemName);
+
+  await p.waitForTimeout(1500);
+
+  return {
+    success: removed,
+    message: removed
+      ? `Removed "${itemName}" from cart`
+      : `Could not find "${itemName}" in cart`,
+  };
+}
+
+export async function startCheckout(
+  fulfillmentType: "pickup" | "delivery" | "ship" = "pickup"
+): Promise<{ checkoutUrl: string; message: string }> {
+  const p = await getPage();
+  await p.goto(`${BJS_BASE}/cart`, { waitUntil: "domcontentloaded" });
+
+  // Try to select fulfillment type
+  await p.evaluate((type: string) => {
+    const tabs = document.querySelectorAll(
+      ".fulfillment-tab, [data-testid='fulfillment-option']"
+    );
+    tabs.forEach((tab) => {
+      if (tab.textContent?.toLowerCase().includes(type)) {
+        (tab as HTMLElement).click();
+      }
+    });
+  }, fulfillmentType);
+
+  await p.waitForTimeout(1000);
+
+  // Click checkout
+  const checkoutBtn = await p
+    .$(
+      "[data-testid='checkout-btn'], .checkout-btn, button:has-text('Checkout'), a:has-text('Checkout')"
+    )
+    .catch(() => null);
+
+  if (checkoutBtn) {
+    await checkoutBtn.click();
+    await p.waitForNavigation({ waitUntil: "domcontentloaded" }).catch(() => {});
+  }
+
+  const url = p.url();
+  return {
+    checkoutUrl: url,
+    message: `Checkout initiated with ${fulfillmentType} fulfillment. URL: ${url}`,
+  };
+}
+
+// ── Membership ────────────────────────────────────────────────────────────────
+
+export async function getMembershipInfo(): Promise<{
+  memberName?: string;
+  membershipNumber?: string;
+  membershipType?: string;
+  membershipExpiry?: string;
+  primaryCard?: string;
+  additionalCards?: number;
+  rewards?: string;
+}> {
+  const p = await getPage();
+  await p.goto(`${BJS_BASE}/account/membership`, {
+    waitUntil: "domcontentloaded",
+  });
+
+  return await p.evaluate(() => {
+    const nameEl = document.querySelector(".member-name, [data-testid='member-name']");
+    const numberEl = document.querySelector(".membership-number, [data-testid='membership-number']");
+    const typeEl = document.querySelector(".membership-type, [data-testid='membership-type']");
+    const expiryEl = document.querySelector(
+      ".membership-expiry, .expiry-date, [data-testid='expiry']"
+    );
+    const rewardsEl = document.querySelector(
+      ".rewards-balance, [data-testid='rewards']"
+    );
+
+    return {
+      memberName: nameEl?.textContent?.trim(),
+      membershipNumber: numberEl?.textContent?.trim(),
+      membershipType: typeEl?.textContent?.trim(),
+      membershipExpiry: expiryEl?.textContent?.trim(),
+      rewards: rewardsEl?.textContent?.trim(),
+    };
+  });
+}
+
+export async function renewMembership(): Promise<{
+  renewUrl: string;
+  message: string;
+}> {
+  const p = await getPage();
+  await p.goto(`${BJS_BASE}/account/membership/renew`, {
+    waitUntil: "domcontentloaded",
+  });
+  return {
+    renewUrl: p.url(),
+    message:
+      "Membership renewal page loaded. Complete the renewal process in the browser.",
+  };
+}
+
+// ── Coupons ───────────────────────────────────────────────────────────────────
+
+export async function getCoupons(
+  category?: string
+): Promise<Coupon[]> {
+  const p = await getPage();
+  const url = category
+    ? `${BJS_BASE}/offers?category=${encodeURIComponent(category)}`
+    : `${BJS_BASE}/offers`;
+  await p.goto(url, { waitUntil: "domcontentloaded" });
+
+  await p
+    .waitForSelector(".coupon-card, [data-testid='coupon'], .offer-card", {
+      timeout: 8000,
+    })
+    .catch(() => {});
+
+  return await p.evaluate(() => {
+    const couponEls = document.querySelectorAll(
+      ".coupon-card, [data-testid='coupon'], .offer-card"
+    );
+    return Array.from(couponEls).map((el) => {
+      const titleEl = el.querySelector(".coupon-title, .offer-title, h3, h4");
+      const descEl = el.querySelector(".coupon-desc, .offer-description");
+      const discountEl = el.querySelector(".discount, .savings, .coupon-value");
+      const expiryEl = el.querySelector(".expiry, .expires, [data-testid='expiry']");
+      const clippedEl = el.querySelector(".clipped, .clipped-badge, [data-testid='clipped']");
+      const categoryEl = el.querySelector(".category, .coupon-category");
+      const idAttr =
+        el.getAttribute("data-coupon-id") ||
+        el.getAttribute("data-offer-id") ||
+        el.getAttribute("id") ||
+        Math.random().toString(36).slice(2);
+
+      return {
+        couponId: idAttr,
+        title: titleEl?.textContent?.trim() || "Untitled Offer",
+        description: descEl?.textContent?.trim(),
+        discount: discountEl?.textContent?.trim(),
+        expiryDate: expiryEl?.textContent?.trim(),
+        isClipped: !!clippedEl,
+        category: categoryEl?.textContent?.trim(),
+      };
+    });
+  });
+}
+
+export async function clipCoupon(
+  couponId: string
+): Promise<{ success: boolean; message: string }> {
+  const p = await getPage();
+  await p.goto(`${BJS_BASE}/offers`, { waitUntil: "domcontentloaded" });
+
+  const clipped = await p.evaluate((id: string) => {
+    const couponEl = document.querySelector(
+      `[data-coupon-id='${id}'], [data-offer-id='${id}'], #${id}`
+    );
+    if (!couponEl) return false;
+    const clipBtn = couponEl.querySelector(
+      ".clip-btn, [data-testid='clip-coupon'], button:has-text('Clip'), button:has-text('Add')"
+    ) as HTMLButtonElement | null;
+    if (clipBtn && !clipBtn.disabled) {
+      clipBtn.click();
+      return true;
+    }
+    return false;
+  }, couponId);
+
+  await p.waitForTimeout(1000);
+
+  return {
+    success: clipped,
+    message: clipped
+      ? `Coupon ${couponId} clipped to your membership card`
+      : `Could not clip coupon ${couponId} — it may already be clipped or not found`,
+  };
+}
+
+export async function getMyClippedCoupons(): Promise<Coupon[]> {
+  const p = await getPage();
+  await p.goto(`${BJS_BASE}/account/coupons`, {
+    waitUntil: "domcontentloaded",
+  });
+
+  await p
+    .waitForSelector(".coupon-card, [data-testid='coupon'], .offer-card", {
+      timeout: 8000,
+    })
+    .catch(() => {});
+
+  return await p.evaluate(() => {
+    const couponEls = document.querySelectorAll(
+      ".coupon-card, [data-testid='coupon'], .offer-card"
+    );
+    return Array.from(couponEls).map((el) => {
+      const titleEl = el.querySelector(".coupon-title, .offer-title, h3, h4");
+      const discountEl = el.querySelector(".discount, .savings, .coupon-value");
+      const expiryEl = el.querySelector(".expiry, .expires");
+      const idAttr =
+        el.getAttribute("data-coupon-id") ||
+        el.getAttribute("data-offer-id") ||
+        Math.random().toString(36).slice(2);
+
+      return {
+        couponId: idAttr,
+        title: titleEl?.textContent?.trim() || "Untitled Offer",
+        discount: discountEl?.textContent?.trim(),
+        expiryDate: expiryEl?.textContent?.trim(),
+        isClipped: true,
+      };
+    });
+  });
+}
+
+// ── Orders ────────────────────────────────────────────────────────────────────
+
+export async function getOrderHistory(maxOrders = 10): Promise<Order[]> {
+  const p = await getPage();
+  await p.goto(`${BJS_BASE}/account/orders`, { waitUntil: "domcontentloaded" });
+
+  await p
+    .waitForSelector(".order-card, [data-testid='order'], .order-item", {
+      timeout: 8000,
+    })
+    .catch(() => {});
+
+  return await p.evaluate((max: number) => {
+    const orderEls = document.querySelectorAll(
+      ".order-card, [data-testid='order'], .order-item"
+    );
+    return Array.from(orderEls)
+      .slice(0, max)
+      .map((el) => {
+        const idEl = el.querySelector(
+          ".order-number, [data-testid='order-id']"
+        );
+        const dateEl = el.querySelector(
+          ".order-date, [data-testid='order-date']"
+        );
+        const statusEl = el.querySelector(
+          ".order-status, [data-testid='order-status']"
+        );
+        const totalEl = el.querySelector(
+          ".order-total, [data-testid='order-total']"
+        );
+        const fulfillmentEl = el.querySelector(
+          ".fulfillment-type, [data-testid='fulfillment']"
+        );
+        const trackingEl = el.querySelector(
+          ".tracking-number, [data-testid='tracking']"
+        );
+        const itemCountEl = el.querySelector(
+          ".item-count, [data-testid='item-count']"
+        );
+
+        return {
+          orderId:
+            idEl?.textContent?.trim() || Math.random().toString(36).slice(2),
+          orderDate: dateEl?.textContent?.trim() || "Unknown",
+          status: statusEl?.textContent?.trim() || "Unknown",
+          total: totalEl?.textContent?.trim() || "N/A",
+          itemCount: itemCountEl
+            ? parseInt(itemCountEl.textContent || "0", 10)
+            : undefined,
+          fulfillmentType: fulfillmentEl?.textContent?.trim(),
+          trackingNumber: trackingEl?.textContent?.trim(),
+        };
+      });
+  }, maxOrders);
+}
+
+export async function getOrderDetails(orderId: string): Promise<{
+  order?: Order;
+  items?: { name: string; quantity: number; price: string }[];
+  deliveryAddress?: string;
+  message: string;
+}> {
+  const p = await getPage();
+  await p.goto(`${BJS_BASE}/account/orders/${orderId}`, {
+    waitUntil: "domcontentloaded",
+  });
+
+  const exists = await p.evaluate(() => {
+    return !document.querySelector(".not-found, .error-page");
+  });
+
+  if (!exists) {
+    return { message: `Order ${orderId} not found` };
+  }
+
+  const details = await p.evaluate(() => {
+    const orderEls = document.querySelectorAll(".order-line-item, [data-testid='order-item']");
+    const items = Array.from(orderEls).map((el) => {
+      const nameEl = el.querySelector(".item-name, a");
+      const qtyEl = el.querySelector(".item-qty, .quantity");
+      const priceEl = el.querySelector(".item-price");
+      return {
+        name: nameEl?.textContent?.trim() || "Unknown item",
+        quantity: parseInt(qtyEl?.textContent || "1", 10),
+        price: priceEl?.textContent?.trim() || "N/A",
+      };
+    });
+
+    const statusEl = document.querySelector(".order-status, [data-testid='order-status']");
+    const dateEl = document.querySelector(".order-date");
+    const totalEl = document.querySelector(".order-total");
+    const addressEl = document.querySelector(".delivery-address, .ship-to");
+    const trackingEl = document.querySelector(".tracking-number");
+
+    return {
+      status: statusEl?.textContent?.trim() || "Unknown",
+      orderDate: dateEl?.textContent?.trim() || "Unknown",
+      total: totalEl?.textContent?.trim() || "N/A",
+      deliveryAddress: addressEl?.textContent?.trim(),
+      trackingNumber: trackingEl?.textContent?.trim(),
+      items,
+    };
+  });
+
+  return {
+    order: {
+      orderId,
+      orderDate: details.orderDate,
+      status: details.status,
+      total: details.total,
+      trackingNumber: details.trackingNumber,
+    },
+    items: details.items,
+    deliveryAddress: details.deliveryAddress,
+    message: `Order ${orderId} details retrieved`,
+  };
+}
+
+// ── Clubs ─────────────────────────────────────────────────────────────────────
+
+export async function findClubs(
+  zipCode: string,
+  radius = 25
+): Promise<Club[]> {
+  const p = await getPage();
+  await p.goto(
+    `${BJS_BASE}/club-finder?zip=${encodeURIComponent(zipCode)}&radius=${radius}`,
+    { waitUntil: "domcontentloaded" }
+  );
+
+  await p
+    .waitForSelector(".club-card, [data-testid='club'], .club-result", {
+      timeout: 10000,
+    })
+    .catch(() => {});
+
+  return await p.evaluate(() => {
+    const clubEls = document.querySelectorAll(
+      ".club-card, [data-testid='club'], .club-result"
+    );
+    return Array.from(clubEls).map((el) => {
+      const nameEl = el.querySelector(".club-name, h2, h3");
+      const addressEl = el.querySelector(".club-address, .address-street");
+      const cityEl = el.querySelector(".city, .club-city");
+      const stateEl = el.querySelector(".state, .club-state");
+      const zipEl = el.querySelector(".zip, .club-zip");
+      const phoneEl = el.querySelector(".phone, .club-phone");
+      const distanceEl = el.querySelector(".distance");
+      const hoursEl = el.querySelector(".hours, .club-hours");
+      const clubId =
+        el.getAttribute("data-club-id") ||
+        el.getAttribute("data-store-id") ||
+        Math.random().toString(36).slice(2);
+      const hasGas = !!(
+        el.querySelector(".gas-station, .fuel") ||
+        el.textContent?.toLowerCase().includes("gas")
+      );
+
+      return {
+        clubId,
+        name: nameEl?.textContent?.trim() || "BJ's Wholesale Club",
+        address: addressEl?.textContent?.trim() || "",
+        city: cityEl?.textContent?.trim() || "",
+        state: stateEl?.textContent?.trim() || "",
+        zip: zipEl?.textContent?.trim() || "",
+        phone: phoneEl?.textContent?.trim(),
+        distance: distanceEl?.textContent?.trim(),
+        hours: hoursEl?.textContent?.trim(),
+        hasGas,
+      };
+    });
+  });
+}
+
+export async function getGasPrices(
+  zipCode?: string
+): Promise<{ clubs: Club[]; lastUpdated: string }> {
+  const p = await getPage();
+  const url = zipCode
+    ? `${BJS_BASE}/gas-prices?zip=${encodeURIComponent(zipCode)}`
+    : `${BJS_BASE}/gas-prices`;
+  await p.goto(url, { waitUntil: "domcontentloaded" });
+
+  await p
+    .waitForSelector(
+      ".gas-station, [data-testid='gas-price'], .fuel-price",
+      { timeout: 10000 }
+    )
+    .catch(() => {});
+
+  const clubs = await p.evaluate(() => {
+    const stationEls = document.querySelectorAll(
+      ".gas-station, [data-testid='gas-station'], .fuel-station"
+    );
+    return Array.from(stationEls).map((el) => {
+      const nameEl = el.querySelector(".station-name, .club-name, h3");
+      const addressEl = el.querySelector(".address");
+      const regularEl = el.querySelector(
+        ".regular-price, [data-grade='regular'], [data-testid='regular']"
+      );
+      const premiumEl = el.querySelector(
+        ".premium-price, [data-grade='premium'], [data-testid='premium']"
+      );
+      const dieselEl = el.querySelector(
+        ".diesel-price, [data-grade='diesel'], [data-testid='diesel']"
+      );
+      const clubId =
+        el.getAttribute("data-club-id") ||
+        el.getAttribute("data-store-id") ||
+        Math.random().toString(36).slice(2);
+
+      return {
+        clubId,
+        name: nameEl?.textContent?.trim() || "BJ's Gas Station",
+        address: addressEl?.textContent?.trim() || "",
+        city: "",
+        state: "",
+        zip: "",
+        hasGas: true,
+        gasPriceRegular: regularEl?.textContent?.trim(),
+        gasPricePremium: premiumEl?.textContent?.trim(),
+        gasPriceDiesel: dieselEl?.textContent?.trim(),
+      };
+    });
+  });
+
+  return {
+    clubs,
+    lastUpdated: new Date().toISOString(),
+  };
+}
+
+// ── Process cleanup ───────────────────────────────────────────────────────────
+
+process.on("exit", () => {
+  if (browser) browser.close();
+});