@jackwener/opencli 1.6.1 → 1.6.2

package/src/clis/xianyu/chat.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './chat.js';
+
+describe('xianyu chat helpers', () => {
+  it('builds goofish im urls from ids', () => {
+    expect(__test__.buildChatUrl('1038951278192', '3650092411')).toBe(
+      'https://www.goofish.com/im?itemId=1038951278192&peerUserId=3650092411',
+    );
+  });
+
+  it('normalizes numeric ids', () => {
+    expect(__test__.normalizeNumericId('1038951278192', 'item_id', '1038951278192')).toBe('1038951278192');
+    expect(__test__.normalizeNumericId(3650092411, 'user_id', '3650092411')).toBe('3650092411');
+  });
+
+  it('rejects non-numeric ids', () => {
+    expect(() => __test__.normalizeNumericId('abc', 'item_id', '1038951278192')).toThrow();
+    expect(() => __test__.normalizeNumericId('3650092411x', 'user_id', '3650092411')).toThrow();
+  });
+});

package/src/clis/xianyu/chat.ts

@@ -0,0 +1,175 @@
+import { AuthRequiredError, SelectorError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+import { normalizeNumericId } from './utils.js';
+
+function buildChatUrl(itemId: string, peerUserId: string): string {
+  return `https://www.goofish.com/im?itemId=${encodeURIComponent(itemId)}&peerUserId=${encodeURIComponent(peerUserId)}`;
+}
+
+function buildExtractChatStateEvaluate(): string {
+  return `
+    (() => {
+      const clean = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const bodyText = document.body?.innerText || '';
+      const requiresAuth = /请先登录|登录后/.test(bodyText);
+
+      const textarea = document.querySelector('textarea');
+      const sendButton = Array.from(document.querySelectorAll('button'))
+        .find((btn) => clean(btn.textContent || '') === '发送');
+      const topbar = document.querySelector('[class*="message-topbar"]');
+      const itemCard = Array.from(document.querySelectorAll('a[href*="/item?id="]'))
+        .find((el) => el.closest('main'));
+      const itemTitleNode =
+        document.querySelector('[class*="container"] [class*="title"]')
+        || document.querySelector('[class*="item-main-info"] [class*="desc"]')
+        || document.querySelector('[class*="headSkuInfo"]')
+        || itemCard?.querySelector('[class*="title"]')
+        || itemCard?.previousElementSibling?.querySelector?.('[class*="title"]');
+
+      const messageRoot = document.querySelector('#message-list-scrollable');
+      const visibleMessages = Array.from(
+        (messageRoot || document).querySelectorAll('[class*="message"], [class*="msg"], [class*="bubble"]')
+      ).map((el) => clean(el.textContent || ''))
+        .filter(Boolean)
+        .filter((text) => !['发送', '闲鱼号', '立即购买'].includes(text))
+        .filter((text) => !/^消息\\d*\\+?$/.test(text))
+        .slice(-20);
+
+      return {
+        requiresAuth,
+        title: clean(document.title || ''),
+        peer_name: clean(topbar?.querySelector('[class*="text1"]')?.textContent || ''),
+        peer_masked_id: clean(topbar?.querySelector('[class*="text2"]')?.textContent || '').replace(/^\\(|\\)$/g, ''),
+        item_title: clean(itemTitleNode?.textContent || ''),
+        item_url: itemCard?.href || '',
+        price: clean(itemCard?.querySelector('[class*="money"]')?.textContent || ''),
+        location: clean(itemCard?.querySelector('[class*="delivery"] + [class*="delivery"], [class*="delivery"]:last-child')?.textContent || ''),
+        can_input: Boolean(textarea && !textarea.disabled),
+        can_send: Boolean(sendButton),
+        visible_messages: visibleMessages,
+      };
+    })()
+  `;
+}
+
+function buildSendMessageEvaluate(text: string): string {
+  return `
+    (() => {
+      const clean = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const textarea = document.querySelector('textarea');
+      if (!textarea || textarea.disabled) {
+        return { ok: false, reason: 'input-not-found' };
+      }
+
+      const setter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value')?.set;
+      if (!setter) {
+        return { ok: false, reason: 'textarea-setter-not-found' };
+      }
+
+      textarea.focus();
+      setter.call(textarea, ${JSON.stringify(text)});
+      textarea.dispatchEvent(new Event('input', { bubbles: true }));
+      textarea.dispatchEvent(new Event('change', { bubbles: true }));
+
+      const sendButton = Array.from(document.querySelectorAll('button'))
+        .find((btn) => clean(btn.textContent || '') === '发送');
+      if (!sendButton) {
+        return { ok: false, reason: 'send-button-not-found' };
+      }
+
+      sendButton.click();
+      return { ok: true };
+    })()
+  `;
+}
+
+cli({
+  site: 'xianyu',
+  name: 'chat',
+  description: '打开闲鱼聊一聊会话，并可选发送消息',
+  domain: 'www.goofish.com',
+  strategy: Strategy.COOKIE,
+  navigateBefore: false,
+  browser: true,
+  args: [
+    { name: 'item_id', required: true, positional: true, help: '闲鱼商品 item_id' },
+    { name: 'user_id', required: true, positional: true, help: '聊一聊对方的 user_id / peerUserId' },
+    { name: 'text', help: 'Message to send after opening the chat' },
+  ],
+  columns: ['status', 'peer_name', 'item_title', 'price', 'location', 'message'],
+  func: async (page, kwargs) => {
+    const itemId = normalizeNumericId(kwargs.item_id, 'item_id', '1038951278192');
+    const userId = normalizeNumericId(kwargs.user_id, 'user_id', '3650092411');
+    const url = buildChatUrl(itemId, userId);
+    const text = String(kwargs.text || '').trim();
+
+    await page.goto(url);
+    await page.wait(2);
+
+    const state = await page.evaluate(buildExtractChatStateEvaluate()) as {
+      requiresAuth?: boolean;
+      title?: string;
+      peer_name?: string;
+      peer_masked_id?: string;
+      item_title?: string;
+      item_url?: string;
+      price?: string;
+      location?: string;
+      can_input?: boolean;
+      can_send?: boolean;
+      visible_messages?: string[];
+    };
+
+    if (state?.requiresAuth) {
+      throw new AuthRequiredError('www.goofish.com', 'Xianyu chat requires a logged-in browser session');
+    }
+
+    if (!state?.can_input) {
+      throw new SelectorError('闲鱼聊天输入框', '未找到可用的聊天输入框，请确认该会话页已正确加载');
+    }
+
+    if (!text) {
+      return [{
+        status: 'ready',
+        peer_name: state.peer_name || '',
+        item_title: state.item_title || '',
+        price: state.price || '',
+        location: state.location || '',
+        message: (state.visible_messages || []).slice(-1)[0] || '',
+        peer_user_id: userId,
+        item_id: itemId,
+        url,
+        item_url: state.item_url || '',
+      }];
+    }
+
+    const sent = await page.evaluate(buildSendMessageEvaluate(text)) as {
+      ok?: boolean;
+      reason?: string;
+    };
+
+    if (!sent?.ok) {
+      throw new SelectorError('闲鱼发送按钮', `消息发送失败：${sent?.reason || 'unknown-reason'}`);
+    }
+
+    await page.wait(1);
+
+    return [{
+      status: 'sent',
+      peer_name: state.peer_name || '',
+      item_title: state.item_title || '',
+      price: state.price || '',
+      location: state.location || '',
+      message: text,
+      peer_user_id: userId,
+      item_id: itemId,
+      url,
+      item_url: state.item_url || '',
+    }];
+  },
+});
+
+export const __test__ = {
+  normalizeNumericId,
+  buildChatUrl,
+};

package/src/clis/xianyu/item.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from 'vitest';
+import { AuthRequiredError, EmptyResultError, SelectorError } from '../../errors.js';
+import { getRegistry } from '../../registry.js';
+import type { IPage } from '../../types.js';
+import { __test__ } from './item.js';
+import './item.js';
+
+function createPageMock(evaluateResult: unknown): IPage {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn().mockResolvedValue(evaluateResult),
+    snapshot: vi.fn().mockResolvedValue(undefined),
+    click: vi.fn().mockResolvedValue(undefined),
+    typeText: vi.fn().mockResolvedValue(undefined),
+    pressKey: vi.fn().mockResolvedValue(undefined),
+    scrollTo: vi.fn().mockResolvedValue(undefined),
+    getFormState: vi.fn().mockResolvedValue({ forms: [], orphanFields: [] }),
+    wait: vi.fn().mockResolvedValue(undefined),
+    tabs: vi.fn().mockResolvedValue([]),
+    selectTab: vi.fn().mockResolvedValue(undefined),
+    networkRequests: vi.fn().mockResolvedValue([]),
+    consoleMessages: vi.fn().mockResolvedValue([]),
+    scroll: vi.fn().mockResolvedValue(undefined),
+    autoScroll: vi.fn().mockResolvedValue(undefined),
+    installInterceptor: vi.fn().mockResolvedValue(undefined),
+    getInterceptedRequests: vi.fn().mockResolvedValue([]),
+    getCookies: vi.fn().mockResolvedValue([]),
+    screenshot: vi.fn().mockResolvedValue(''),
+    waitForCapture: vi.fn().mockResolvedValue(undefined),
+  } as IPage;
+}
+
+describe('xianyu item helpers', () => {
+  it('normalizes numeric item ids', () => {
+    expect(__test__.normalizeNumericId('1040754408976', 'item_id', '1040754408976')).toBe('1040754408976');
+    expect(__test__.normalizeNumericId(1040754408976, 'item_id', '1040754408976')).toBe('1040754408976');
+  });
+
+  it('builds item urls', () => {
+    expect(__test__.buildItemUrl('1040754408976')).toBe(
+      'https://www.goofish.com/item?id=1040754408976',
+    );
+  });
+
+  it('rejects invalid item ids', () => {
+    expect(() => __test__.normalizeNumericId('abc', 'item_id', '1040754408976')).toThrow();
+  });
+});
+
+describe('xianyu item command', () => {
+  const command = getRegistry().get('xianyu/item');
+
+  it('throws AuthRequiredError on login wall before mtop is available', async () => {
+    const page = createPageMock({ error: 'auth-required' });
+    await expect(command!.func!(page, { item_id: '1040754408976' })).rejects.toBeInstanceOf(AuthRequiredError);
+  });
+
+  it('throws EmptyResultError on verification or risk-control pages', async () => {
+    const page = createPageMock({ error: 'blocked' });
+    await expect(command!.func!(page, { item_id: '1040754408976' })).rejects.toBeInstanceOf(EmptyResultError);
+  });
+
+  it('keeps SelectorError for true mtop initialization failures', async () => {
+    const page = createPageMock({ error: 'mtop-not-ready' });
+    await expect(command!.func!(page, { item_id: '1040754408976' })).rejects.toBeInstanceOf(SelectorError);
+  });
+});

package/src/clis/xianyu/item.ts

@@ -0,0 +1,172 @@
+import { AuthRequiredError, EmptyResultError, SelectorError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+import { normalizeNumericId } from './utils.js';
+
+function buildItemUrl(itemId: string): string {
+  return `https://www.goofish.com/item?id=${encodeURIComponent(itemId)}`;
+}
+
+function buildFetchItemEvaluate(itemId: string): string {
+  return `
+    (async () => {
+      const clean = (value) => String(value ?? '').replace(/\\s+/g, ' ').trim();
+      const extractRetCode = (ret) => {
+        const first = Array.isArray(ret) ? ret[0] : '';
+        return clean(first).split('::')[0] || '';
+      };
+
+      const waitFor = async (predicate, timeoutMs = 5000) => {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+          if (predicate()) return true;
+          await new Promise((r) => setTimeout(r, 150));
+        }
+        return false;
+      };
+
+      const bodyText = document.body?.innerText || '';
+      if (/请先登录|登录后/.test(bodyText)) {
+        return { error: 'auth-required' };
+      }
+
+      if (/验证码|安全验证|异常访问/.test(bodyText)) {
+        return { error: 'blocked' };
+      }
+
+      await waitFor(() => window.lib?.mtop?.request);
+      if (!window.lib || !window.lib.mtop || typeof window.lib.mtop.request !== 'function') {
+        return { error: 'mtop-not-ready' };
+      }
+
+      let response;
+      try {
+        response = await window.lib.mtop.request({
+          api: 'mtop.taobao.idle.pc.detail',
+          data: { itemId: ${JSON.stringify(itemId)} },
+          type: 'POST',
+          v: '1.0',
+          dataType: 'json',
+          needLogin: false,
+          needLoginPC: false,
+          sessionOption: 'AutoLoginOnly',
+          ecode: 0,
+        });
+      } catch (error) {
+        const ret = error?.ret || [];
+        return {
+          error: 'mtop-request-failed',
+          error_code: extractRetCode(ret),
+          error_message: clean(Array.isArray(ret) ? ret.join(' | ') : error?.message || error),
+        };
+      }
+
+      const retCode = extractRetCode(response?.ret || []);
+      if (retCode && retCode !== 'SUCCESS') {
+        return {
+          error: 'mtop-response-error',
+          error_code: retCode,
+          error_message: clean((response?.ret || []).join(' | ')),
+        };
+      }
+
+      const data = response?.data || {};
+      const item = data.itemDO || {};
+      const seller = data.sellerDO || {};
+      const labels = Array.isArray(item.itemLabelExtList) ? item.itemLabelExtList : [];
+      const findLabel = (name) => labels.find((label) => clean(label.propertyText) === name)?.text || '';
+      const images = Array.isArray(item.imageInfos)
+        ? item.imageInfos.map((entry) => entry?.url).filter(Boolean)
+        : [];
+
+      return {
+        item_id: clean(item.itemId || ${JSON.stringify(itemId)}),
+        title: clean(item.title || ''),
+        description: clean(item.desc || ''),
+        price: clean('¥' + (item.soldPrice || item.defaultPrice || '')).replace(/^¥\\s*$/, ''),
+        original_price: clean(item.originalPrice || ''),
+        want_count: String(item.wantCnt ?? ''),
+        collect_count: String(item.collectCnt ?? ''),
+        browse_count: String(item.browseCnt ?? ''),
+        status: clean(item.itemStatusStr || ''),
+        condition: clean(findLabel('成色')),
+        brand: clean(findLabel('品牌')),
+        category: clean(findLabel('分类')),
+        location: clean(seller.publishCity || seller.city || ''),
+        seller_name: clean(seller.nick || seller.uniqueName || ''),
+        seller_id: String(seller.sellerId || ''),
+        seller_score: clean(seller.xianyuSummary || ''),
+        reply_ratio_24h: clean(seller.replyRatio24h || ''),
+        reply_interval: clean(seller.replyInterval || ''),
+        item_url: ${JSON.stringify(buildItemUrl(itemId))},
+        seller_url: seller.sellerId ? 'https://www.goofish.com/personal?userId=' + seller.sellerId : '',
+        image_count: String(images.length),
+        image_urls: images,
+      };
+    })()
+  `;
+}
+
+cli({
+  site: 'xianyu',
+  name: 'item',
+  description: '查看闲鱼商品详情',
+  domain: 'www.goofish.com',
+  strategy: Strategy.COOKIE,
+  navigateBefore: false,
+  browser: true,
+  args: [
+    { name: 'item_id', required: true, positional: true, help: '闲鱼商品 item_id' },
+  ],
+  columns: ['item_id', 'title', 'price', 'condition', 'brand', 'location', 'seller_name', 'want_count'],
+  func: async (page, kwargs) => {
+    const itemId = normalizeNumericId(kwargs.item_id, 'item_id', '1040754408976');
+
+    await page.goto(buildItemUrl(itemId));
+    await page.wait(2);
+
+    const result = await page.evaluate(buildFetchItemEvaluate(itemId)) as {
+      error?: string;
+      error_code?: string;
+      error_message?: string;
+      title?: string;
+      item_id?: string;
+    } & Record<string, unknown>;
+
+    if (result?.error === 'auth-required') {
+      throw new AuthRequiredError('www.goofish.com', 'Xianyu item detail requires a logged-in browser session');
+    }
+
+    if (result?.error === 'blocked') {
+      throw new EmptyResultError('xianyu item', 'Xianyu item detail is blocked by verification or risk control');
+    }
+
+    if (result?.error === 'mtop-not-ready') {
+      throw new SelectorError('window.lib.mtop', '闲鱼页面未完成初始化，无法调用商品详情接口');
+    }
+
+    if (!result || typeof result !== 'object') {
+      throw new EmptyResultError('xianyu item', '闲鱼商品详情接口未返回有效数据');
+    }
+
+    const errorCode = String(result.error_code || '');
+    const errorMessage = String(result.error_message || '');
+    if (/FAIL_SYS_SESSION_EXPIRED|SESSION_EXPIRED|FAIL_SYS/.test(errorCode) || /FAIL_SYS_SESSION_EXPIRED|SESSION_EXPIRED/.test(errorMessage)) {
+      throw new AuthRequiredError('www.goofish.com', 'Xianyu item detail requires a logged-in browser session');
+    }
+
+    if (result.error) {
+      throw new EmptyResultError('xianyu item', errorMessage || `Xianyu item detail request failed: ${result.error}`);
+    }
+
+    if (!String(result.title || '').trim()) {
+      throw new EmptyResultError('xianyu item', 'No item detail was returned for the specified item_id');
+    }
+
+    return [result];
+  },
+});
+
+export const __test__ = {
+  normalizeNumericId,
+  buildItemUrl,
+};

package/src/clis/xianyu/search.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './search.js';
+
+describe('xianyu search helpers', () => {
+  it('normalizes limit into supported range', () => {
+    expect(__test__.normalizeLimit(undefined)).toBe(20);
+    expect(__test__.normalizeLimit(0)).toBe(1);
+    expect(__test__.normalizeLimit(3.8)).toBe(3);
+    expect(__test__.normalizeLimit(999)).toBe(__test__.MAX_LIMIT);
+  });
+
+  it('builds search URLs with encoded queries', () => {
+    expect(__test__.buildSearchUrl('笔记本电脑')).toBe(
+      'https://www.goofish.com/search?q=%E7%AC%94%E8%AE%B0%E6%9C%AC%E7%94%B5%E8%84%91',
+    );
+  });
+
+  it('extracts item ids from detail URLs', () => {
+    expect(__test__.itemIdFromUrl('https://www.goofish.com/item?id=954988715389&categoryId=126854525')).toBe('954988715389');
+    expect(__test__.itemIdFromUrl('https://www.goofish.com/search?q=test')).toBe('');
+  });
+});

package/src/clis/xianyu/search.ts

@@ -0,0 +1,151 @@
+import { AuthRequiredError, EmptyResultError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+
+const MAX_LIMIT = 50;
+
+function normalizeLimit(value: unknown): number {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return 20;
+  return Math.min(MAX_LIMIT, Math.max(1, Math.floor(n)));
+}
+
+function buildSearchUrl(query: string): string {
+  return `https://www.goofish.com/search?q=${encodeURIComponent(query)}`;
+}
+
+function itemIdFromUrl(url: string): string {
+  const match = url.match(/[?&]id=(\d+)/);
+  return match ? match[1] : '';
+}
+
+function buildExtractResultsEvaluate(limit: number): string {
+  return `
+    (async () => {
+      const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+      const waitFor = async (predicate, timeoutMs = 8000) => {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+          if (predicate()) return true;
+          await wait(150);
+        }
+        return false;
+      };
+
+      const clean = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const selectors = {
+        card: 'a[href*="/item?id="]',
+        title: '[class*="row1-wrap-title"], [class*="main-title"]',
+        attrs: '[class*="row2-wrap-cpv"] span[class*="cpv--"]',
+        priceWrap: '[class*="price-wrap"]',
+        priceNum: '[class*="number"]',
+        priceDec: '[class*="decimal"]',
+        priceDesc: '[class*="price-desc"] [title], [class*="price-desc"] [style*="line-through"]',
+        sellerWrap: '[class*="row4-wrap-seller"]',
+        sellerText: '[class*="seller-text"]',
+        badge: '[class*="credit-container"] [title], [class*="credit-container"] span',
+      };
+
+      await waitFor(() => {
+        const bodyText = document.body?.innerText || '';
+        return Boolean(
+          document.querySelector(selectors.card)
+          || /请先登录|登录后|验证码|安全验证|异常访问/.test(bodyText)
+          || /暂无相关宝贝|未找到相关宝贝|没有找到/.test(bodyText)
+        );
+      });
+
+      const bodyText = document.body?.innerText || '';
+      const requiresAuth = /请先登录|登录后/.test(bodyText);
+      const blocked = /验证码|安全验证|异常访问/.test(bodyText);
+      const empty = /暂无相关宝贝|未找到相关宝贝|没有找到/.test(bodyText);
+
+      const items = Array.from(document.querySelectorAll(selectors.card))
+        .slice(0, ${limit})
+        .map((card) => {
+          const href = card.href || card.getAttribute('href') || '';
+          const title = clean(card.querySelector(selectors.title)?.textContent || '');
+          const attrs = Array.from(card.querySelectorAll(selectors.attrs))
+            .map((node) => clean(node.textContent || ''))
+            .filter(Boolean);
+          const priceWrap = card.querySelector(selectors.priceWrap);
+          const priceNumber = clean(priceWrap?.querySelector(selectors.priceNum)?.textContent || '');
+          const priceDecimal = clean(priceWrap?.querySelector(selectors.priceDec)?.textContent || '');
+          const location = clean(card.querySelector(selectors.sellerWrap)?.querySelector(selectors.sellerText)?.textContent || '');
+          const originalPriceNode = card.querySelector(selectors.priceDesc);
+          const badgeNode = card.querySelector(selectors.badge);
+
+          return {
+            title,
+            url: href,
+            item_id: '',
+            price: clean('¥' + priceNumber + priceDecimal).replace(/^¥\\s*$/, ''),
+            original_price: clean(originalPriceNode?.getAttribute('title') || originalPriceNode?.textContent || ''),
+            condition: attrs[0] || '',
+            brand: attrs[1] || '',
+            extra: attrs.slice(2).join(' | '),
+            location,
+            badge: clean(badgeNode?.getAttribute('title') || badgeNode?.textContent || ''),
+          };
+        })
+        .filter((item) => item.title && item.url);
+
+      return { requiresAuth, blocked, empty, items };
+    })()
+  `;
+}
+
+cli({
+  site: 'xianyu',
+  name: 'search',
+  description: '搜索闲鱼商品',
+  domain: 'www.goofish.com',
+  strategy: Strategy.COOKIE,
+  navigateBefore: false,
+  browser: true,
+  args: [
+    { name: 'query', required: true, positional: true, help: 'Search keyword' },
+    { name: 'limit', type: 'int', default: 20, help: 'Number of results to return' },
+  ],
+  columns: ['item_id', 'rank', 'title', 'price', 'condition', 'brand', 'location', 'badge', 'url'],
+  func: async (page, kwargs) => {
+    const query = String(kwargs.query || '').trim();
+    const limit = normalizeLimit(kwargs.limit);
+
+    await page.goto(buildSearchUrl(query));
+    await page.wait(2);
+    await page.autoScroll({ times: 2 });
+
+    const payload = await page.evaluate(buildExtractResultsEvaluate(limit)) as {
+      requiresAuth?: boolean;
+      blocked?: boolean;
+      empty?: boolean;
+      items?: Array<Record<string, string>>;
+    };
+
+    if (payload?.requiresAuth) {
+      throw new AuthRequiredError('www.goofish.com', 'Xianyu search results require a logged-in browser session');
+    }
+
+    if (payload?.blocked) {
+      throw new EmptyResultError('xianyu search', 'Xianyu returned a verification page or blocked the current browser session');
+    }
+
+    const items = Array.isArray(payload?.items) ? payload.items : [];
+    if (!items.length && !payload?.empty) {
+      throw new EmptyResultError('xianyu search', 'No item cards were found on the current Xianyu search page');
+    }
+
+    return items.map((item, index) => ({
+      rank: index + 1,
+      ...item,
+      item_id: itemIdFromUrl(item.url),
+    }));
+  },
+});
+
+export const __test__ = {
+  MAX_LIMIT,
+  normalizeLimit,
+  buildSearchUrl,
+  itemIdFromUrl,
+};

package/src/clis/xianyu/utils.ts

@@ -0,0 +1,9 @@
+import { ArgumentError } from '../../errors.js';
+
+export function normalizeNumericId(value: unknown, label: string, example: string): string {
+  const normalized = String(value || '').trim();
+  if (!/^\d+$/.test(normalized)) {
+    throw new ArgumentError(`${label} must be a numeric ID`, `Pass a numeric ${label}, for example: ${example}`);
+  }
+  return normalized;
+}