@jackwener/opencli 1.7.12 → 1.7.13

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

@@ -1,5 +1,6 @@
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { canonicalizeProductUrl, normalizeProductId } from './utils.js';
+import { canonicalizeProductUrl, normalizeProductId, requireProductIdArg } from './utils.js';
 function escapeJsString(value) {
     return JSON.stringify(value);
 }
@@ -105,31 +106,38 @@ cli({
     ],
     columns: ['ok', 'product_id', 'url', 'message'],
     func: async (page, kwargs) => {
-        const rawProductId = kwargs['product-id'] ?? kwargs['product-id'];
-        const productId = normalizeProductId(rawProductId);
-        const targetUrl = canonicalizeProductUrl(kwargs.url, productId);
-        if (!productId && !targetUrl) {
-            throw new Error('Either --product-id or --url is required');
+        const rawProductId = kwargs['product-id'];
+        if (!rawProductId && !kwargs.url) {
+            throw new ArgumentError('Either --product-id or --url is required');
         }
+        const productId = rawProductId
+            ? requireProductIdArg(rawProductId, 'product-id')
+            : requireProductIdArg(kwargs.url, '--url');
+        const targetUrl = canonicalizeProductUrl(kwargs.url, productId);
         const finalUrl = targetUrl || canonicalizeProductUrl('', productId);
-        await page.goto(finalUrl);
-        const result = await page.evaluate(buildAddToCartEvaluate(productId));
+        await page.goto(finalUrl).catch((error) => {
+            throw new CommandExecutionError(`coupang add-to-cart navigation failed: ${error?.message || error}`);
+        });
+        const result = await page.evaluate(buildAddToCartEvaluate(productId)).catch((error) => {
+            throw new CommandExecutionError(`coupang add-to-cart evaluation failed: ${error?.message || error}`);
+        });
         const loginHints = result?.loginHints ?? {};
         if (loginHints.hasLoginLink && !loginHints.hasMyCoupang) {
-            throw new Error('Coupang login required. Please log into Coupang in Chrome and retry.');
+            throw new AuthRequiredError('coupang.com', 'Please log into Coupang in Chrome and retry.');
         }
         const actualProductId = normalizeProductId(result?.currentProductId || productId);
         if (result?.reason === 'PRODUCT_MISMATCH') {
-            throw new Error(`Product mismatch: expected ${productId}, got ${actualProductId || 'unknown'}`);
+            const observed = actualProductId ? `got ${actualProductId}` : 'no product id observed';
+            throw new CommandExecutionError(`Product mismatch: expected ${productId}, ${observed}`);
         }
         if (result?.reason === 'OPTION_REQUIRED') {
-            throw new Error('This product requires option selection and is not supported in v1.');
+            throw new CommandExecutionError('This product requires option selection and is not supported in v1.');
         }
         if (result?.reason === 'ADD_TO_CART_BUTTON_NOT_FOUND') {
-            throw new Error('Could not find an add-to-cart button on the product page.');
+            throw new CommandExecutionError('Could not find an add-to-cart button on the product page.');
         }
         if (!result?.ok) {
-            throw new Error('Failed to confirm add-to-cart success.');
+            throw new CommandExecutionError('Failed to confirm add-to-cart success.');
         }
         return [{
                 ok: true,

package/clis/coupang/coupang.test.js

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './search.js';
+import './product.js';
+import './add-to-cart.js';
+import { parseLimitArg, parsePageArg, requireProductIdArg } from './utils.js';
+
+describe('coupang utils — parseLimitArg / parsePageArg (no silent clamp)', () => {
+    it('parseLimitArg returns fallback for empty / undefined', () => {
+        expect(parseLimitArg(undefined, 20, 50)).toBe(20);
+        expect(parseLimitArg(null, 20, 50)).toBe(20);
+        expect(parseLimitArg('', 20, 50)).toBe(20);
+    });
+
+    it('parseLimitArg accepts integers in range', () => {
+        expect(parseLimitArg(1, 20, 50)).toBe(1);
+        expect(parseLimitArg(50, 20, 50)).toBe(50);
+        expect(parseLimitArg('25', 20, 50)).toBe(25);
+    });
+
+    it('parseLimitArg throws ArgumentError on out-of-range / non-integer (no silent clamp)', () => {
+        expect(() => parseLimitArg(0, 20, 50)).toThrow(ArgumentError);
+        expect(() => parseLimitArg(-1, 20, 50)).toThrow(ArgumentError);
+        expect(() => parseLimitArg(51, 20, 50)).toThrow(ArgumentError);
+        expect(() => parseLimitArg(999, 20, 50)).toThrow(ArgumentError);
+        expect(() => parseLimitArg('abc', 20, 50)).toThrow(ArgumentError);
+        expect(() => parseLimitArg(1.5, 20, 50)).toThrow(ArgumentError);
+    });
+
+    it('parsePageArg returns fallback for empty', () => {
+        expect(parsePageArg(undefined, 1)).toBe(1);
+        expect(parsePageArg('', 1)).toBe(1);
+    });
+
+    it('parsePageArg accepts positive integers', () => {
+        expect(parsePageArg(1, 1)).toBe(1);
+        expect(parsePageArg('5', 1)).toBe(5);
+    });
+
+    it('parsePageArg throws ArgumentError on non-positive (no silent lift to 1)', () => {
+        expect(() => parsePageArg(0, 1)).toThrow(ArgumentError);
+        expect(() => parsePageArg(-1, 1)).toThrow(ArgumentError);
+        expect(() => parsePageArg('abc', 1)).toThrow(ArgumentError);
+    });
+});
+
+describe('coupang utils — product id validation', () => {
+    it('extracts numeric ids from ids and URLs', () => {
+        expect(requireProductIdArg('123456789')).toBe('123456789');
+        expect(requireProductIdArg('https://www.coupang.com/vp/products/123456789?itemId=1', '--url')).toBe('123456789');
+    });
+
+    it('rejects malformed product ids instead of building fake URLs', () => {
+        expect(() => requireProductIdArg('abc')).toThrow(ArgumentError);
+        expect(() => requireProductIdArg('abc 123456789')).toThrow(ArgumentError);
+        expect(() => requireProductIdArg('https://www.coupang.com/not-a-product', '--url')).toThrow(ArgumentError);
+        expect(() => requireProductIdArg('https://www.coupang.com/not-a-product/123456789', '--url')).toThrow(ArgumentError);
+        expect(() => requireProductIdArg('https://notcoupang.com/vp/products/123456789', '--url')).toThrow(ArgumentError);
+        expect(() => requireProductIdArg('https://example.com/vp/products/123456789', '--url')).toThrow(ArgumentError);
+    });
+});
+
+describe('coupang adapter registry shape', () => {
+    it('search has product_id column for round-trip into product', () => {
+        const search = getRegistry().get('coupang/search');
+        expect(search).toBeDefined();
+        expect(search.access).toBe('read');
+        expect(search.columns).toContain('product_id');
+        // Listing pairs with detail: id-shaped column present.
+        const idShaped = search.columns.find((c) => /_id$|^id$/.test(c));
+        expect(idShaped).toBe('product_id');
+    });
+
+    it('product cmd is a registered read adapter that pairs with search', () => {
+        const product = getRegistry().get('coupang/product');
+        expect(product).toBeDefined();
+        expect(product.access).toBe('read');
+        expect(product.columns).toContain('product_id');
+        expect(product.columns).toContain('title');
+        expect(product.columns).toContain('price');
+        expect(product.columns).toContain('seller');
+        expect(product.columns).toContain('rating');
+    });
+
+    it('add-to-cart remains write-class', () => {
+        const cart = getRegistry().get('coupang/add-to-cart');
+        expect(cart).toBeDefined();
+        expect(cart.access).toBe('write');
+    });
+});
+
+describe('coupang search — typed errors (no silent fallback)', () => {
+    it('rejects empty query with ArgumentError', async () => {
+        const search = getRegistry().get('coupang/search');
+        // page object is irrelevant — we expect to fail before any browser call.
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(search.func(fakePage, { query: '   ' })).rejects.toThrow(ArgumentError);
+        await expect(search.func(fakePage, { query: '' })).rejects.toThrow(ArgumentError);
+    });
+
+    it('rejects unsupported --filter with ArgumentError', async () => {
+        const search = getRegistry().get('coupang/search');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(search.func(fakePage, { query: 'mouse', filter: 'eco' })).rejects.toThrow(ArgumentError);
+    });
+
+    it('rejects out-of-range --limit with ArgumentError (no silent clamp to 50)', async () => {
+        const search = getRegistry().get('coupang/search');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(search.func(fakePage, { query: 'mouse', limit: 999 })).rejects.toThrow(ArgumentError);
+    });
+
+    it('rejects out-of-range --page with ArgumentError', async () => {
+        const search = getRegistry().get('coupang/search');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(search.func(fakePage, { query: 'mouse', page: 0 })).rejects.toThrow(ArgumentError);
+    });
+});
+
+describe('coupang product — typed errors', () => {
+    it('rejects missing --product-id and --url with ArgumentError', async () => {
+        const product = getRegistry().get('coupang/product');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(product.func(fakePage, {})).rejects.toThrow(ArgumentError);
+    });
+
+    it('rejects malformed product id before navigation', async () => {
+        const product = getRegistry().get('coupang/product');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(product.func(fakePage, { 'product-id': 'abc' })).rejects.toThrow(ArgumentError);
+    });
+
+    it('wraps browser failures as CommandExecutionError', async () => {
+        const product = getRegistry().get('coupang/product');
+        const fakePage = { goto: () => Promise.reject(new Error('browser down')) };
+        await expect(product.func(fakePage, { 'product-id': '123456789' })).rejects.toThrow(CommandExecutionError);
+    });
+});
+
+describe('coupang add-to-cart — typed errors', () => {
+    it('rejects missing --product-id and --url with ArgumentError', async () => {
+        const cart = getRegistry().get('coupang/add-to-cart');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(cart.func(fakePage, {})).rejects.toThrow(ArgumentError);
+    });
+
+    it('rejects malformed product id before navigation', async () => {
+        const cart = getRegistry().get('coupang/add-to-cart');
+        const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+        await expect(cart.func(fakePage, { 'product-id': 'abc' })).rejects.toThrow(ArgumentError);
+    });
+
+    it('wraps browser failures as CommandExecutionError', async () => {
+        const cart = getRegistry().get('coupang/add-to-cart');
+        const fakePage = { goto: () => Promise.reject(new Error('browser down')) };
+        await expect(cart.func(fakePage, { 'product-id': '123456789' })).rejects.toThrow(CommandExecutionError);
+    });
+});

package/clis/coupang/product.js

@@ -0,0 +1,257 @@
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { canonicalizeProductUrl, normalizeProductId, requireProductIdArg } from './utils.js';
+
+function escapeJsString(value) {
+    return JSON.stringify(value);
+}
+
+/**
+ * Build the in-page extractor for a Coupang product detail page.
+ *
+ * Tries three sources in order, mirroring search.js's chain:
+ *  1. JSON-LD <script type="application/ld+json"> (Product schema, most stable)
+ *  2. window.__INITIAL_STATE__ / __NEXT_DATA__ / similar globals (rich)
+ *  3. DOM scrape (fallback when bootstrap state is server-side only)
+ *
+ * Returns either a partial product object or a structured failure
+ * `{ loginHints, ok: false, reason }` so the caller can map it to typed errors.
+ *
+ * Design note (no-silent-empty): empty strings / null fields here MUST mean
+ * "upstream did not provide this field" — they should not be conflated with
+ * "extraction failed". A failed extraction returns ok=false so the caller can
+ * surface AuthRequiredError or EmptyResultError; partial success returns the
+ * fields it found and the caller decides whether to treat the partial row as
+ * usable.
+ */
+function buildProductDetailEvaluate(expectedProductId) {
+    return `
+    (async () => {
+      const expectedProductId = ${escapeJsString(expectedProductId)};
+      const normalizeText = (value) => (value == null ? '' : String(value).trim());
+      const parseNum = (value) => {
+        const text = normalizeText(value).replace(/[^\\d.]/g, '');
+        if (!text) return null;
+        const num = Number(text);
+        return Number.isFinite(num) ? num : null;
+      };
+
+      const loginHints = {
+        hasLoginLink: Boolean(document.querySelector('a[href*="login"], a[title*="로그인"]')),
+        hasMyCoupang: /마이쿠팡/.test(document.body.innerText || ''),
+      };
+
+      const pathMatch = location.pathname.match(/\\/vp\\/products\\/(\\d+)/);
+      const currentProductId = pathMatch?.[1] || '';
+      if (expectedProductId && currentProductId && expectedProductId !== currentProductId) {
+        return { ok: false, reason: 'PRODUCT_MISMATCH', currentProductId, loginHints };
+      }
+
+      // ── Source 1: JSON-LD Product schema ─────────────────────────────
+      const fromJsonLd = (() => {
+        const scripts = Array.from(document.querySelectorAll('script[type="application/ld+json"]'));
+        for (const script of scripts) {
+          try {
+            const docs = JSON.parse(script.textContent || 'null');
+            const items = Array.isArray(docs) ? docs : [docs];
+            for (const doc of items) {
+              if (!doc || typeof doc !== 'object') continue;
+              const t = doc['@type'];
+              const types = Array.isArray(t) ? t : [t];
+              if (!types.some((x) => /Product/i.test(String(x || '')))) continue;
+              const offers = Array.isArray(doc.offers) ? doc.offers[0] : doc.offers;
+              return {
+                title: normalizeText(doc.name),
+                brand: normalizeText(doc.brand?.name || doc.brand),
+                image_url: normalizeText(Array.isArray(doc.image) ? doc.image[0] : doc.image),
+                price: parseNum(offers?.price),
+                rating: parseNum(doc.aggregateRating?.ratingValue),
+                review_count: parseNum(doc.aggregateRating?.reviewCount),
+                seller: normalizeText(offers?.seller?.name),
+              };
+            }
+          } catch { /* malformed ld+json — skip and try next source */ }
+        }
+        return null;
+      })();
+
+      // ── Source 2: bootstrap globals (deeply nested vendorItem etc.) ──
+      const fromBootstrap = (() => {
+        const collect = (root) => {
+          if (!root || typeof root !== 'object') return null;
+          const queue = [root];
+          let depth = 0;
+          while (queue.length && depth < 5000) {
+            const node = queue.shift();
+            depth++;
+            if (!node || typeof node !== 'object') continue;
+            // A product-like leaf usually has both productId and salePrice / finalPrice / itemName.
+            const idCandidate = node.productId || node.product_id || node.id;
+            const titleCandidate = node.itemName || node.productName || node.name;
+            const priceCandidate = node.salePrice ?? node.finalPrice ?? node.sellingPrice ?? node.price;
+            if (idCandidate && titleCandidate && priceCandidate != null && /\\d{6,}/.test(String(idCandidate))) {
+              return {
+                product_id: String(idCandidate),
+                title: normalizeText(titleCandidate),
+                price: parseNum(priceCandidate),
+                original_price: parseNum(node.originalPrice ?? node.basePrice ?? node.listPrice),
+                discount_rate: parseNum(node.discountRate ?? node.discountPercent),
+                rating: parseNum(node.ratingAverage ?? node.rating ?? node.reviewRating),
+                review_count: parseNum(node.reviewCount ?? node.reviewsCount ?? node.ratingCount),
+                seller: normalizeText(node.vendorName ?? node.sellerName ?? node.merchantName),
+                brand: normalizeText(node.brandName ?? node.brand),
+                rocket: normalizeText(node.rocketType ?? node.deliveryBadgeType),
+                delivery_promise: normalizeText(node.deliveryPromise ?? node.arrivalText),
+              };
+            }
+            for (const value of Object.values(node)) {
+              if (value && typeof value === 'object') queue.push(value);
+            }
+          }
+          return null;
+        };
+        const candidates = [
+          window.__INITIAL_STATE__,
+          window.__NEXT_DATA__,
+          window.__APOLLO_STATE__,
+          window.__PRELOADED_STATE__,
+        ];
+        for (const c of candidates) {
+          const found = collect(c);
+          if (found) return found;
+        }
+        return null;
+      })();
+
+      // ── Source 3: DOM fallback ───────────────────────────────────────
+      const fromDom = (() => {
+        const titleNode = document.querySelector(
+          '.prod-buy-header__title, h1.prod-buy-header__title, h1[class*="prod-buy-header"], h2.prod-buy-header__title, h1[class*="ProductName"], h1[class*="product-name"]'
+        );
+        const priceNode = document.querySelector(
+          '.total-price strong, .prod-sale-price strong, [class*="finalPrice"], [class*="sellingPrice"], [class*="price-value"]'
+        );
+        const originalPriceNode = document.querySelector(
+          '.origin-price, .base-price, del[class*="origin"], del[class*="base"], [class*="strike"], [class*="origin-price"]'
+        );
+        const discountNode = document.querySelector(
+          '.discount-percentage, [class*="discount"][class*="percent"], [class*="discountRate"]'
+        );
+        const ratingNode = document.querySelector(
+          '.rating-star-num, [class*="ratingStar"], [class*="rating-star"], [class*="rating-num"], [class*="ProductRating"]'
+        );
+        const reviewCountNode = document.querySelector(
+          '.count, .rating-total-count, [class*="reviewCount"], [class*="review-count"]'
+        );
+        const sellerNode = document.querySelector(
+          '.prod-sale-vendor-name, [class*="vendor-name"], [class*="vendorName"], [class*="sellerName"]'
+        );
+        const imageNode = document.querySelector(
+          '.prod-image__detail, [class*="prod-image"] img, [class*="ProductImage"] img'
+        );
+        return {
+          title: normalizeText(titleNode?.textContent),
+          price: parseNum(priceNode?.textContent),
+          original_price: parseNum(originalPriceNode?.textContent),
+          discount_rate: parseNum(discountNode?.textContent),
+          rating: parseNum(ratingNode?.getAttribute?.('aria-label') || ratingNode?.textContent),
+          review_count: parseNum(reviewCountNode?.textContent),
+          seller: normalizeText(sellerNode?.textContent),
+          image_url: normalizeText(imageNode?.getAttribute?.('src') || imageNode?.getAttribute?.('data-src')),
+        };
+      })();
+
+      // Merge with priority: bootstrap > jsonld > dom (bootstrap is freshest /
+      // closest to the API; jsonld is well-typed; dom is last-resort).
+      const merge = (a, b) => {
+        if (!a) return b;
+        if (!b) return a;
+        const out = { ...a };
+        for (const [k, v] of Object.entries(b)) {
+          if (out[k] == null || out[k] === '') out[k] = v;
+        }
+        return out;
+      };
+      const merged = merge(merge(fromBootstrap, fromJsonLd), fromDom);
+      const hasAnyField = merged && (merged.title || merged.price != null);
+      if (!hasAnyField) {
+        return { ok: false, reason: 'NO_DATA_EXTRACTED', currentProductId, loginHints };
+      }
+
+      return {
+        ok: true,
+        currentProductId,
+        loginHints,
+        data: merged,
+      };
+    })()
+  `;
+}
+
+cli({
+    site: 'coupang',
+    name: 'product',
+    access: 'read',
+    description: 'Read full product detail (price, rating, seller, delivery) for a Coupang product',
+    domain: 'www.coupang.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'product-id', positional: true, required: false, help: 'Coupang product ID (digits only)' },
+        { name: 'url', required: false, help: 'Canonical Coupang product URL (alternative to --product-id)' },
+    ],
+    columns: [
+        'product_id', 'title', 'price', 'original_price', 'discount_rate',
+        'rating', 'review_count', 'seller', 'brand', 'rocket',
+        'delivery_promise', 'image_url', 'url',
+    ],
+    func: async (page, kwargs) => {
+        const rawProductId = kwargs['product-id'];
+        if (!rawProductId && !kwargs.url) {
+            throw new ArgumentError('Either --product-id or --url is required');
+        }
+        const productId = rawProductId
+            ? requireProductIdArg(rawProductId, 'product-id')
+            : requireProductIdArg(kwargs.url, '--url');
+        const targetUrl = canonicalizeProductUrl(kwargs.url, productId);
+        const finalUrl = targetUrl || canonicalizeProductUrl('', productId);
+        await page.goto(finalUrl).catch((error) => {
+            throw new CommandExecutionError(`coupang product navigation failed: ${error?.message || error}`);
+        });
+        await page.wait(2).catch((error) => {
+            throw new CommandExecutionError(`coupang product wait failed: ${error?.message || error}`);
+        });
+        const result = await page.evaluate(buildProductDetailEvaluate(productId)).catch((error) => {
+            throw new CommandExecutionError(`coupang product extraction failed: ${error?.message || error}`);
+        });
+        const loginHints = result?.loginHints ?? {};
+        if (loginHints.hasLoginLink && !loginHints.hasMyCoupang) {
+            throw new AuthRequiredError('coupang.com', 'Please log into Coupang in Chrome and retry.');
+        }
+        if (result?.reason === 'PRODUCT_MISMATCH') {
+            const actualProductId = normalizeProductId(result?.currentProductId || '');
+            const observed = actualProductId ? `got ${actualProductId}` : 'no product id observed';
+            throw new EmptyResultError('coupang product', `Product page redirected: expected ${productId}, ${observed} (item may be sold out or unavailable in your region)`);
+        }
+        if (!result?.ok || !result?.data) {
+            throw new EmptyResultError('coupang product', `No product data extracted from ${finalUrl}. The page may have failed to render or this product is restricted.`);
+        }
+        const actualProductId = normalizeProductId(result?.currentProductId || result.data.product_id || productId);
+        const data = result.data;
+        return [{
+                product_id: actualProductId,
+                title: data.title || null,
+                price: data.price ?? null,
+                original_price: data.original_price ?? null,
+                discount_rate: data.discount_rate ?? null,
+                rating: data.rating ?? null,
+                review_count: data.review_count ?? null,
+                seller: data.seller || null,
+                brand: data.brand || null,
+                rocket: data.rocket || null,
+                delivery_promise: data.delivery_promise || null,
+                image_url: data.image_url || null,
+                url: canonicalizeProductUrl('', actualProductId) || finalUrl,
+            }];
+    },
+});

package/clis/coupang/search.js

@@ -1,5 +1,6 @@
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { mergeSearchItems, normalizeSearchItem, sanitizeSearchItems } from './utils.js';
+import { mergeSearchItems, normalizeSearchItem, parseLimitArg, parsePageArg, sanitizeSearchItems } from './utils.js';
 function escapeJsString(value) {
     return JSON.stringify(value);
 }
@@ -410,32 +411,50 @@ cli({
         { name: 'limit', type: 'int', default: 20, help: 'Max results (max 50)' },
         { name: 'filter', required: false, help: 'Optional search filter (currently supports: rocket)' },
     ],
-    columns: ['rank', 'title', 'price', 'unit_price', 'rating', 'review_count', 'rocket', 'delivery_type', 'delivery_promise', 'url'],
+    columns: ['rank', 'product_id', 'title', 'price', 'unit_price', 'rating', 'review_count', 'rocket', 'delivery_type', 'delivery_promise', 'url'],
     func: async (page, kwargs) => {
         const query = String(kwargs.query || '').trim();
-        const pageNumber = Math.max(Number(kwargs.page || 1), 1);
-        const limit = Math.min(Math.max(Number(kwargs.limit || 20), 1), 50);
+        if (!query) {
+            throw new ArgumentError('query cannot be empty');
+        }
+        const pageNumber = parsePageArg(kwargs.page, 1);
+        const limit = parseLimitArg(kwargs.limit, 20, 50);
         const filter = String(kwargs.filter || '').trim().toLowerCase();
-        if (!query)
-            throw new Error('Query is required');
+        if (filter && filter !== 'rocket') {
+            throw new ArgumentError(`Unsupported --filter "${filter}" (supported: rocket)`);
+        }
         const initialPage = filter ? 1 : pageNumber;
         const url = `https://www.coupang.com/np/search?q=${encodeURIComponent(query)}&channel=user&page=${initialPage}`;
-        await page.goto(url);
+        await page.goto(url).catch((error) => {
+            throw new CommandExecutionError(`coupang search navigation failed: ${error?.message || error}`);
+        });
         if (filter) {
-            const filterResult = await page.evaluate(buildApplyFilterEvaluate(filter));
+            const filterResult = await page.evaluate(buildApplyFilterEvaluate(filter)).catch((error) => {
+                throw new CommandExecutionError(`coupang search filter evaluation failed: ${error?.message || error}`);
+            });
             if (!filterResult?.ok) {
-                throw new Error(`Unsupported or unavailable filter: ${filter}`);
+                throw new EmptyResultError('coupang search', `Filter "${filter}" was not available on the current page; try without --filter or wait for Coupang to render the filter bar.`);
             }
-            await page.wait(3);
+            await page.wait(3).catch((error) => {
+                throw new CommandExecutionError(`coupang search wait failed: ${error?.message || error}`);
+            });
             if (pageNumber > 1) {
-                const locationInfo = await page.evaluate(buildCurrentLocationEvaluate());
+                const locationInfo = await page.evaluate(buildCurrentLocationEvaluate()).catch((error) => {
+                    throw new CommandExecutionError(`coupang search location evaluation failed: ${error?.message || error}`);
+                });
                 const filteredUrl = new URL(locationInfo?.href || url);
                 filteredUrl.searchParams.set('page', String(pageNumber));
-                await page.goto(filteredUrl.toString());
+                await page.goto(filteredUrl.toString()).catch((error) => {
+                    throw new CommandExecutionError(`coupang search filtered navigation failed: ${error?.message || error}`);
+                });
             }
         }
-        await page.autoScroll({ times: filter ? 3 : 2, delayMs: 1500 });
-        const raw = await page.evaluate(buildSearchEvaluate(query, limit, pageNumber));
+        await page.autoScroll({ times: filter ? 3 : 2, delayMs: 1500 }).catch((error) => {
+            throw new CommandExecutionError(`coupang search scroll failed: ${error?.message || error}`);
+        });
+        const raw = await page.evaluate(buildSearchEvaluate(query, limit, pageNumber)).catch((error) => {
+            throw new CommandExecutionError(`coupang search extraction failed: ${error?.message || error}`);
+        });
         const loginHints = raw?.loginHints ?? {};
         const items = Array.isArray(raw?.items) ? raw.items : [];
         const domItems = Array.isArray(raw?.domItems) ? raw.domItems : [];
@@ -444,8 +463,11 @@ cli({
         const normalized = filter
             ? sanitizeSearchItems(normalizedDom, limit)
             : mergeSearchItems(normalizedBase, normalizedDom, limit);
-        if (!normalized.length && loginHints.hasLoginLink && !loginHints.hasMyCoupang) {
-            throw new Error('Coupang login required. Please log into Coupang in Chrome and retry.');
+        if (!normalized.length) {
+            if (loginHints.hasLoginLink && !loginHints.hasMyCoupang) {
+                throw new AuthRequiredError('coupang.com', 'Please log into Coupang in Chrome and retry.');
+            }
+            throw new EmptyResultError('coupang search', `No products matched "${query}". Try a more specific keyword or remove --filter.`);
         }
         return normalized;
     },

package/clis/coupang/utils.js

@@ -1,3 +1,36 @@
+import { ArgumentError } from '@jackwener/opencli/errors';
+
+/**
+ * Parse a positive integer arg (--limit / --page / --review-page).
+ *
+ * Throws ArgumentError on out-of-range / non-integer values rather than
+ * silently clamping. We prefer typed-fail-fast over silent clamping for the
+ * same reason as feedback_typed_fail_fast_for_adapters: callers cannot tell
+ * that their value was rewritten and end up confused why "limit=999" returned
+ * 50 rows.
+ */
+export function parseLimitArg(raw, fallback, max) {
+    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 parsePageArg(raw, fallback) {
+    if (raw === undefined || raw === null || raw === '') {
+        return fallback;
+    }
+    const num = Number(raw);
+    if (!Number.isInteger(num) || num < 1) {
+        throw new ArgumentError(`--page must be a positive integer (got ${raw})`);
+    }
+    return num;
+}
+
 function itemKey(item) {
     return item.url || item.product_id || `${item.title}:${item.price ?? ''}`;
 }
@@ -61,7 +94,28 @@ export function normalizeProductId(raw) {
     if (!text)
         return '';
     const match = text.match(/\/vp\/products\/(\d+)/) || text.match(/\b(\d{6,})\b/);
-    return match?.[1] ?? text;
+    return match?.[1] ?? '';
+}
+export function requireProductIdArg(raw, label = '--product-id') {
+    const text = asString(raw);
+    if (label === '--url') {
+        try {
+            const url = new URL(text.startsWith('http') ? text : `https://www.coupang.com${text}`);
+            const match = url.pathname.match(/^\/vp\/products\/(\d{6,})(?:\/|$)/);
+            const isCoupangHost = url.hostname === 'coupang.com' || url.hostname.endsWith('.coupang.com');
+            if (isCoupangHost && match) {
+                return match[1];
+            }
+        }
+        catch {
+            // Fall through to the typed validation error below.
+        }
+        throw new ArgumentError(`${label} must be a Coupang product URL containing /vp/products/<id>`);
+    }
+    if (!/^\d{6,}$/.test(text)) {
+        throw new ArgumentError(`${label} must be a numeric Coupang product ID`);
+    }
+    return text;
 }
 export function canonicalizeProductUrl(rawUrl, productId) {
     const raw = asString(rawUrl);