@jackwener/opencli 1.6.0 → 1.6.2

package/dist/clis/amazon/rankings.js

@@ -0,0 +1,226 @@
+import { CommandExecutionError } from '../../errors.js';
+import { Strategy } from '../../registry.js';
+import { assertUsableState, buildProvenance, cleanText, extractAsin, extractCategoryNodeId, extractReviewCountFromCardText, firstMeaningfulLine, gotoAndReadState, isRankingPaginationUrl, normalizeProductUrl, parsePriceText, parseRatingValue, parseReviewCount, resolveRankingUrl, toAbsoluteAmazonUrl, uniqueNonEmpty, } from './shared.js';
+function parseRank(rawRank, fallback) {
+    const normalized = cleanText(rawRank);
+    const match = normalized.match(/(\d{1,4})/);
+    if (!match)
+        return fallback;
+    const parsed = Number.parseInt(match[1], 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function normalizeVisibleCategoryLinks(links) {
+    const normalized = (links ?? [])
+        .map((entry) => ({
+        title: cleanText(entry?.title),
+        url: toAbsoluteAmazonUrl(entry?.url) ?? '',
+        node_id: cleanText(entry?.node_id) || extractCategoryNodeId(entry?.url) || null,
+    }))
+        .filter((entry) => Boolean(entry.title) && Boolean(entry.url));
+    const seen = new Set();
+    const deduped = [];
+    for (const entry of normalized) {
+        if (seen.has(entry.url))
+            continue;
+        seen.add(entry.url);
+        deduped.push(entry);
+    }
+    return deduped;
+}
+export function normalizeRankingCandidate(candidate, context) {
+    const productUrl = normalizeProductUrl(candidate.href);
+    const asin = extractAsin(candidate.asin ?? '') ?? extractAsin(productUrl ?? '') ?? null;
+    const title = cleanText(candidate.title) || firstMeaningfulLine(candidate.card_text);
+    const price = parsePriceText(cleanText(candidate.price_text) || candidate.card_text);
+    const ratingText = cleanText(candidate.rating_text) || null;
+    const reviewCountText = cleanText(candidate.review_count_text)
+        || extractReviewCountFromCardText(candidate.card_text)
+        || null;
+    const provenance = buildProvenance(context.sourceUrl);
+    const categoryUrl = context.categoryUrl || context.sourceUrl;
+    return {
+        list_type: context.listType,
+        rank: parseRank(candidate.rank_text, context.rankFallback),
+        asin,
+        title: title || null,
+        product_url: productUrl,
+        price_text: price.price_text,
+        price_value: price.price_value,
+        currency: price.currency,
+        rating_text: ratingText,
+        rating_value: parseRatingValue(ratingText),
+        review_count_text: reviewCountText,
+        review_count: parseReviewCount(reviewCountText),
+        list_title: context.listTitle,
+        category_title: context.categoryTitle,
+        category_url: categoryUrl,
+        category_node_id: extractCategoryNodeId(categoryUrl),
+        category_path: context.categoryPath,
+        visible_category_links: context.visibleCategoryLinks,
+        ...provenance,
+    };
+}
+async function readRankingPage(page, listType, url) {
+    const state = await gotoAndReadState(page, url, 2500, listType);
+    assertUsableState(state, listType);
+    return await page.evaluate(`
+    (() => ({
+      href: window.location.href,
+      title: document.title || '',
+      list_title:
+        document.querySelector('#zg_banner_text')?.textContent
+        || document.querySelector('h1')?.textContent
+        || '',
+      category_title:
+        document.querySelector('#zg_browseRoot .zg_selected')?.textContent
+        || document.querySelector('#wayfinding-breadcrumbs_feature_div ul li:last-child')?.textContent
+        || document.querySelector('#wayfinding-breadcrumbs_container ul li:last-child')?.textContent
+        || '',
+      category_path: Array.from(document.querySelectorAll(
+        '#zg_browseRoot ul li a, #zg_browseRoot ul li span, ' +
+        '#wayfinding-breadcrumbs_feature_div ul li a, #wayfinding-breadcrumbs_feature_div ul li span.a-list-item, ' +
+        '#wayfinding-breadcrumbs_container ul li a, #wayfinding-breadcrumbs_container ul li span.a-list-item'
+      ))
+        .map((entry) => (entry.textContent || '').trim())
+        .filter(Boolean),
+      cards: Array.from(document.querySelectorAll(
+        '.p13n-sc-uncoverable-faceout, .zg-grid-general-faceout, [data-asin][class*="p13n"]'
+      )).map((card) => ({
+        rank_text:
+          card.querySelector('.zg-bdg-text')?.textContent
+          || card.querySelector('[class*="rank"]')?.textContent
+          || '',
+        asin:
+          card.getAttribute('data-asin')
+          || card.getAttribute('id')
+          || '',
+        title:
+          card.querySelector('[class*="line-clamp"]')?.textContent
+          || card.querySelector('img')?.getAttribute('alt')
+          || card.querySelector('a[href*="/dp/"]')?.textContent
+          || '',
+        href:
+          card.querySelector('a[href*="/dp/"], a[href*="/gp/product/"]')?.href
+          || '',
+        price_text:
+          card.querySelector('.a-price .a-offscreen')?.textContent
+          || card.querySelector('.a-color-price')?.textContent
+          || '',
+        rating_text:
+          card.querySelector('[aria-label*="out of 5 stars"]')?.getAttribute('aria-label')
+          || '',
+        review_count_text:
+          card.querySelector('a[href*="#customerReviews"]')?.textContent
+          || card.querySelector('.a-size-small')?.textContent
+          || '',
+        card_text: card.innerText || '',
+      })),
+      page_links: Array.from(document.querySelectorAll('.a-pagination a[href], li.a-normal a[href], li.a-selected a[href]'))
+        .map((anchor) => anchor.href || '')
+        .filter(Boolean),
+      visible_category_links: Array.from(document.querySelectorAll(
+        '#zg_browseRoot a[href], #zg-left-col a[href], [class*="zg-browse"] a[href]'
+      )).map((anchor) => ({
+        title: (anchor.textContent || '').trim(),
+        url: anchor.href || '',
+        node_id:
+          anchor.getAttribute('data-node-id')
+          || anchor.dataset?.nodeid
+          || '',
+      }))
+        .filter((entry) => entry.title && entry.url),
+    }))()
+  `);
+}
+function createEmptyResultHint(commandName) {
+    return [
+        `Open the same Amazon ${commandName} page in shared Chrome and verify ranked items are visible.`,
+        'If the page shows a robot check, clear it manually and retry.',
+    ].join(' ');
+}
+export function createRankingCliOptions(definition) {
+    return {
+        site: 'amazon',
+        name: definition.commandName,
+        description: definition.description,
+        domain: 'amazon.com',
+        strategy: Strategy.COOKIE,
+        navigateBefore: false,
+        args: [
+            {
+                name: 'input',
+                positional: true,
+                help: 'Ranking URL or supported Amazon path. Omit to use the list root.',
+            },
+            {
+                name: 'limit',
+                type: 'int',
+                default: 100,
+                help: 'Maximum number of ranked items to return (default 100)',
+            },
+        ],
+        columns: ['list_type', 'rank', 'asin', 'title', 'price_text', 'rating_value', 'review_count'],
+        func: async (page, kwargs) => {
+            const limit = Math.max(1, Number(kwargs.limit) || 100);
+            const initialUrl = resolveRankingUrl(definition.listType, typeof kwargs.input === 'string' ? kwargs.input : undefined);
+            const queue = [initialUrl];
+            const visited = new Set();
+            const seenEntityKeys = new Set();
+            const results = [];
+            let listTitle = null;
+            while (queue.length > 0 && results.length < limit) {
+                const nextUrl = queue.shift();
+                if (visited.has(nextUrl))
+                    continue;
+                visited.add(nextUrl);
+                const payload = await readRankingPage(page, definition.listType, nextUrl);
+                const sourceUrl = cleanText(payload.href) || nextUrl;
+                listTitle = cleanText(payload.list_title) || cleanText(payload.title) || listTitle;
+                const categoryPath = uniqueNonEmpty(payload.category_path ?? []);
+                const categoryTitle = cleanText(payload.category_title)
+                    || (categoryPath.length > 0 ? categoryPath[categoryPath.length - 1] : '');
+                const visibleCategoryLinks = normalizeVisibleCategoryLinks(payload.visible_category_links);
+                const cards = payload.cards ?? [];
+                for (const card of cards) {
+                    const normalized = normalizeRankingCandidate(card, {
+                        listType: definition.listType,
+                        rankFallback: results.length + 1,
+                        listTitle,
+                        sourceUrl,
+                        categoryTitle: categoryTitle || null,
+                        categoryUrl: sourceUrl,
+                        categoryPath,
+                        visibleCategoryLinks,
+                    });
+                    const dedupeKey = cleanText(String(normalized.asin ?? ''))
+                        || cleanText(String(normalized.product_url ?? ''));
+                    if (dedupeKey && seenEntityKeys.has(dedupeKey))
+                        continue;
+                    if (dedupeKey)
+                        seenEntityKeys.add(dedupeKey);
+                    results.push(normalized);
+                    if (results.length >= limit)
+                        break;
+                }
+                const pageLinks = uniqueNonEmpty(payload.page_links ?? []);
+                for (const href of pageLinks) {
+                    const absolute = toAbsoluteAmazonUrl(href);
+                    if (!absolute || !isRankingPaginationUrl(definition.listType, absolute))
+                        continue;
+                    if (!visited.has(absolute) && !queue.includes(absolute)) {
+                        queue.push(absolute);
+                    }
+                }
+            }
+            if (results.length === 0) {
+                throw new CommandExecutionError(`amazon ${definition.commandName} did not expose any ranked items`, createEmptyResultHint(definition.commandName));
+            }
+            return results.slice(0, limit);
+        },
+    };
+}
+export const __test__ = {
+    parseRank,
+    normalizeVisibleCategoryLinks,
+    normalizeRankingCandidate,
+};

package/dist/clis/amazon/rankings.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clis/amazon/rankings.test.js

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './rankings.js';
+describe('amazon rankings helpers', () => {
+    it('normalizes ranking candidates with unified schema', () => {
+        const result = __test__.normalizeRankingCandidate({
+            rank_text: '#3',
+            asin: 'B0DR31GC3D',
+            title: 'Desk Shelves Desktop Organizer',
+            href: 'https://www.amazon.com/dp/B0DR31GC3D/ref=zg_bs',
+            price_text: '$25.92',
+            rating_text: '4.3 out of 5 stars',
+            review_count_text: '435',
+        }, {
+            listType: 'new_releases',
+            rankFallback: 3,
+            listTitle: 'Amazon New Releases',
+            sourceUrl: 'https://www.amazon.com/gp/new-releases',
+            categoryTitle: 'Home & Kitchen',
+            categoryUrl: 'https://www.amazon.com/gp/new-releases/home-garden',
+            categoryPath: ['Home & Kitchen'],
+            visibleCategoryLinks: [{ title: 'Storage', url: 'https://www.amazon.com/gp/new-releases/storage', node_id: null }],
+        });
+        expect(result.list_type).toBe('new_releases');
+        expect(result.rank).toBe(3);
+        expect(result.asin).toBe('B0DR31GC3D');
+        expect(result.product_url).toBe('https://www.amazon.com/dp/B0DR31GC3D');
+        expect(result.category_title).toBe('Home & Kitchen');
+        expect(result.visible_category_links).toEqual([
+            { title: 'Storage', url: 'https://www.amazon.com/gp/new-releases/storage', node_id: null },
+        ]);
+    });
+    it('deduplicates category links and parses rank fallback', () => {
+        const links = __test__.normalizeVisibleCategoryLinks([
+            { title: 'Kitchen', url: '/gp/new-releases/home-garden' },
+            { title: 'Kitchen', url: 'https://www.amazon.com/gp/new-releases/home-garden' },
+            { title: 'Storage', url: '/gp/new-releases/storage', node_id: '1064954' },
+        ]);
+        expect(links.length).toBe(2);
+        expect(__test__.parseRank('N/A', 8)).toBe(8);
+    });
+});

package/dist/clis/amazon/shared.d.ts

@@ -3,11 +3,14 @@ export declare const SITE = "amazon";
 export declare const DOMAIN = "amazon.com";
 export declare const HOME_URL = "https://www.amazon.com/";
 export declare const BESTSELLERS_URL = "https://www.amazon.com/Best-Sellers/zgbs";
+export declare const NEW_RELEASES_URL = "https://www.amazon.com/gp/new-releases";
+export declare const MOVERS_SHAKERS_URL = "https://www.amazon.com/gp/movers-and-shakers";
 export declare const SEARCH_URL_PREFIX = "https://www.amazon.com/s?k=";
 export declare const PRODUCT_URL_PREFIX = "https://www.amazon.com/dp/";
 export declare const DISCUSSION_URL_PREFIX = "https://www.amazon.com/product-reviews/";
 export declare const STRATEGY = "cookie";
 export declare const PRIMARY_PRICE_SELECTORS: string[];
+export type AmazonRankingListType = 'bestsellers' | 'new_releases' | 'movers_shakers';
 export interface ProvenanceFields {
     source_url: string;
     fetched_at: string;
@@ -31,6 +34,10 @@ export declare function buildSearchUrl(query: string): string;
 export declare function extractAsin(input: string): string | null;
 export declare function buildProductUrl(input: string): string;
 export declare function buildDiscussionUrl(input: string): string;
+export declare function isSupportedRankingPath(listType: AmazonRankingListType, inputUrl: string): boolean;
+export declare function resolveRankingUrl(listType: AmazonRankingListType, input?: string): string;
+export declare function isRankingPaginationUrl(listType: AmazonRankingListType, inputUrl: string): boolean;
+export declare function extractCategoryNodeId(inputUrl: string | null | undefined): string | null;
 export declare function resolveBestsellersUrl(input?: string): string;
 export declare function canonicalizeAmazonUrl(input: string): string;
 export declare function toAbsoluteAmazonUrl(value: string | null | undefined): string | null;
@@ -53,6 +60,10 @@ export declare const __test__: {
     buildProductUrl: typeof buildProductUrl;
     buildDiscussionUrl: typeof buildDiscussionUrl;
     resolveBestsellersUrl: typeof resolveBestsellersUrl;
+    resolveRankingUrl: typeof resolveRankingUrl;
+    isSupportedRankingPath: typeof isSupportedRankingPath;
+    isRankingPaginationUrl: typeof isRankingPaginationUrl;
+    extractCategoryNodeId: typeof extractCategoryNodeId;
     parsePriceText: typeof parsePriceText;
     parseRatingValue: typeof parseRatingValue;
     parseReviewCount: typeof parseReviewCount;

package/dist/clis/amazon/shared.js

@@ -3,6 +3,8 @@ export const SITE = 'amazon';
 export const DOMAIN = 'amazon.com';
 export const HOME_URL = 'https://www.amazon.com/';
 export const BESTSELLERS_URL = 'https://www.amazon.com/Best-Sellers/zgbs';
+export const NEW_RELEASES_URL = 'https://www.amazon.com/gp/new-releases';
+export const MOVERS_SHAKERS_URL = 'https://www.amazon.com/gp/movers-and-shakers';
 export const SEARCH_URL_PREFIX = 'https://www.amazon.com/s?k=';
 export const PRODUCT_URL_PREFIX = 'https://www.amazon.com/dp/';
 export const DISCUSSION_URL_PREFIX = 'https://www.amazon.com/product-reviews/';
@@ -24,6 +26,29 @@ const ROBOT_TEXT_PATTERNS = [
     'Type the characters you see in this image',
     'To discuss automated access to Amazon data please contact',
 ];
+const AMAZON_RANKING_SPECS = {
+    bestsellers: {
+        commandName: 'bestsellers',
+        rootUrl: BESTSELLERS_URL,
+        pathPattern: /(?:^|\/)zgbs(?:\/|$)/i,
+        invalidInputMessage: 'amazon bestsellers expects a best sellers URL or /zgbs path',
+        invalidInputHint: 'Example: opencli amazon bestsellers https://www.amazon.com/Best-Sellers/zgbs',
+    },
+    new_releases: {
+        commandName: 'new-releases',
+        rootUrl: NEW_RELEASES_URL,
+        pathPattern: /\/gp\/new-releases(?:\/|$)/i,
+        invalidInputMessage: 'amazon new-releases expects a new releases URL or /gp/new-releases path',
+        invalidInputHint: 'Example: opencli amazon new-releases https://www.amazon.com/gp/new-releases',
+    },
+    movers_shakers: {
+        commandName: 'movers-shakers',
+        rootUrl: MOVERS_SHAKERS_URL,
+        pathPattern: /\/gp\/movers-and-shakers(?:\/|$)/i,
+        invalidInputMessage: 'amazon movers-shakers expects a movers-and-shakers URL or /gp/movers-and-shakers path',
+        invalidInputHint: 'Example: opencli amazon movers-shakers https://www.amazon.com/gp/movers-and-shakers',
+    },
+};
 export function cleanText(value) {
     return typeof value === 'string'
         ? value.replace(/\u00a0/g, ' ').replace(/\s+/g, ' ').trim()
@@ -80,22 +105,103 @@ export function buildDiscussionUrl(input) {
     }
     return `${DISCUSSION_URL_PREFIX}${asin}`;
 }
-export function resolveBestsellersUrl(input) {
+function getRankingSpec(listType) {
+    return AMAZON_RANKING_SPECS[listType];
+}
+export function isSupportedRankingPath(listType, inputUrl) {
+    try {
+        const url = new URL(inputUrl);
+        return getRankingSpec(listType).pathPattern.test(url.pathname);
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveRankingUrl(listType, input) {
+    const spec = getRankingSpec(listType);
     const normalized = cleanText(input);
-    if (!normalized)
-        return BESTSELLERS_URL;
-    if (normalized === 'root')
-        return BESTSELLERS_URL;
+    if (!normalized || normalized === 'root')
+        return spec.rootUrl;
+    let candidateUrl;
     if (normalized.startsWith('/')) {
-        return new URL(normalized, HOME_URL).toString();
+        candidateUrl = new URL(normalized, HOME_URL).toString();
+    }
+    else if (/^https?:\/\//i.test(normalized)) {
+        candidateUrl = canonicalizeAmazonUrl(normalized);
+    }
+    else if (normalized.includes('amazon.') && normalized.includes('/')) {
+        candidateUrl = canonicalizeAmazonUrl(`https://${normalized.replace(/^\/+/, '')}`);
     }
-    if (/^https?:\/\//i.test(normalized)) {
-        return canonicalizeAmazonUrl(normalized);
+    else {
+        throw new ArgumentError(spec.invalidInputMessage, spec.invalidInputHint);
     }
-    if (normalized.includes('/zgbs/')) {
-        return canonicalizeAmazonUrl(`https://${normalized.replace(/^\/+/, '')}`);
+    if (!isSupportedRankingPath(listType, candidateUrl)) {
+        throw new ArgumentError(spec.invalidInputMessage, spec.invalidInputHint);
     }
-    throw new ArgumentError('amazon bestsellers expects a best sellers URL or /zgbs path', 'Example: opencli amazon bestsellers https://www.amazon.com/Best-Sellers/zgbs');
+    return normalizeRankingInputUrl(candidateUrl);
+}
+function normalizeRankingInputUrl(inputUrl) {
+    try {
+        const url = new URL(inputUrl);
+        const normalizedPathSegments = url.pathname
+            .split('/')
+            .filter(Boolean)
+            .filter((segment) => !/^ref=/i.test(segment));
+        url.pathname = `/${normalizedPathSegments.join('/')}`;
+        url.hash = '';
+        // Ranking pages are frequently shared with tracking refs that can land on unstable variants.
+        // Dropping ref keeps the canonical ranking path while preserving useful params (for example pg=2).
+        url.searchParams.delete('ref');
+        return url.toString();
+    }
+    catch {
+        return inputUrl;
+    }
+}
+export function isRankingPaginationUrl(listType, inputUrl) {
+    const absolute = toAbsoluteAmazonUrl(inputUrl);
+    if (!absolute || !isSupportedRankingPath(listType, absolute))
+        return false;
+    try {
+        const url = new URL(absolute);
+        const ref = cleanText(url.searchParams.get('ref')).toLowerCase();
+        // pg= query param is the most reliable pagination indicator across all ranking lists
+        return url.searchParams.has('pg')
+            || /(?:^|_)pg(?:_|$)/.test(ref)
+            // Amazon ranking pagination refs: zg_bs_pg_ (bestsellers), zg_bsnr_pg_ (new releases), zg_bsms_pg_ (movers & shakers)
+            || /zg_bs(?:nr|ms)?_pg_/.test(ref);
+    }
+    catch {
+        return false;
+    }
+}
+export function extractCategoryNodeId(inputUrl) {
+    const absolute = toAbsoluteAmazonUrl(inputUrl);
+    if (!absolute)
+        return null;
+    try {
+        const url = new URL(absolute);
+        for (const key of ['node', 'nodeid', 'nodeId', 'browseNode']) {
+            const value = cleanText(url.searchParams.get(key));
+            if (/^\d{4,}$/.test(value))
+                return value;
+        }
+        const rhValue = cleanText(url.searchParams.get('rh'));
+        const rhMatch = decodeURIComponent(rhValue).match(/(?:^|,)\s*n:(\d{4,})(?:,|$)/i);
+        if (rhMatch)
+            return rhMatch[1];
+        const pathMatches = [...url.pathname.matchAll(/\/(\d{4,})(?=\/|$)/g)];
+        if (pathMatches.length > 0) {
+            return pathMatches[pathMatches.length - 1][1];
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export function resolveBestsellersUrl(input) {
+    return resolveRankingUrl('bestsellers', input);
 }
 export function canonicalizeAmazonUrl(input) {
     try {
@@ -244,6 +350,10 @@ export const __test__ = {
     buildProductUrl,
     buildDiscussionUrl,
     resolveBestsellersUrl,
+    resolveRankingUrl,
+    isSupportedRankingPath,
+    isRankingPaginationUrl,
+    extractCategoryNodeId,
     parsePriceText,
     parseRatingValue,
     parseReviewCount,

package/dist/clis/amazon/shared.test.js

@@ -30,4 +30,15 @@ describe('amazon shared helpers', () => {
         expect(__test__.resolveBestsellersUrl('/Best-Sellers/zgbs')).toBe('https://www.amazon.com/Best-Sellers/zgbs');
         expect(() => __test__.resolveBestsellersUrl('desk shelf organizer')).toThrow('amazon bestsellers expects a best sellers URL or /zgbs path');
     });
+    it('resolves and validates all ranking list URLs', () => {
+        expect(__test__.resolveRankingUrl('new_releases')).toBe('https://www.amazon.com/gp/new-releases');
+        expect(__test__.resolveRankingUrl('movers_shakers')).toBe('https://www.amazon.com/gp/movers-and-shakers');
+        expect(__test__.resolveRankingUrl('new_releases', '/gp/new-releases/kitchen')).toBe('https://www.amazon.com/gp/new-releases/kitchen');
+        expect(__test__.resolveRankingUrl('bestsellers', 'https://www.amazon.com/Best-Sellers/zgbs/ref=zg_bsnr_tab_bs')).toBe('https://www.amazon.com/Best-Sellers/zgbs');
+        expect(() => __test__.resolveRankingUrl('movers_shakers', 'https://example.com/gp/movers-and-shakers')).toThrow('Invalid Amazon URL');
+    });
+    it('extracts category node id from URL best effort', () => {
+        expect(__test__.extractCategoryNodeId('https://www.amazon.com/Best-Sellers-Home-Kitchen/zgbs/home-garden/3744371')).toBe('3744371');
+        expect(__test__.extractCategoryNodeId('https://www.amazon.com/s?k=desk+organizer&rh=n%3A1064954')).toBe('1064954');
+    });
 });

package/dist/clis/bilibili/comments.js

@@ -3,7 +3,7 @@
  * Uses the /x/v2/reply/main endpoint which is stable and doesn't depend on DOM structure.
  */
 import { cli, Strategy } from '../../registry.js';
-import { apiGet } from './utils.js';
+import { apiGet, resolveBvid } from './utils.js';
 cli({
     site: 'bilibili',
     name: 'comments',
@@ -16,7 +16,7 @@ cli({
     ],
     columns: ['rank', 'author', 'text', 'likes', 'replies', 'time'],
     func: async (page, kwargs) => {
-        const bvid = String(kwargs.bvid).trim();
+        const bvid = await resolveBvid(kwargs.bvid);
         const limit = Math.min(Number(kwargs.limit) || 20, 50);
         // Resolve bvid → aid (required by reply API)
         const view = await apiGet(page, '/x/web-interface/view', { params: { bvid } });

package/dist/clis/bilibili/comments.test.js

@@ -2,7 +2,8 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 const { mockApiGet } = vi.hoisted(() => ({
     mockApiGet: vi.fn(),
 }));
-vi.mock('./utils.js', () => ({
+vi.mock('./utils.js', async (importOriginal) => ({
+    ...(await importOriginal()),
     apiGet: mockApiGet,
 }));
 import { getRegistry } from '../../registry.js';
@@ -47,7 +48,7 @@ describe('bilibili comments', () => {
     });
     it('throws when aid cannot be resolved', async () => {
         mockApiGet.mockResolvedValueOnce({ data: {} }); // no aid
-        await expect(command.func({}, { bvid: 'BV_invalid', limit: 5 })).rejects.toThrow('Cannot resolve aid for bvid: BV_invalid');
+        await expect(command.func({}, { bvid: 'BVinvalid123', limit: 5 })).rejects.toThrow('Cannot resolve aid for bvid: BVinvalid123');
     });
     it('returns empty array when replies is missing', async () => {
         mockApiGet

package/dist/clis/bilibili/download.js

@@ -10,6 +10,7 @@
 import { cli, Strategy } from '../../registry.js';
 import { checkYtdlp, sanitizeFilename } from '../../download/index.js';
 import { downloadMedia } from '../../download/media-download.js';
+import { resolveBvid } from './utils.js';
 cli({
     site: 'bilibili',
     name: 'download',
@@ -23,7 +24,7 @@ cli({
     ],
     columns: ['bvid', 'title', 'status', 'size'],
     func: async (page, kwargs) => {
-        const bvid = kwargs.bvid;
+        const bvid = await resolveBvid(kwargs.bvid);
         const output = kwargs.output;
         const quality = kwargs.quality;
         // Check yt-dlp availability

package/dist/clis/bilibili/subtitle.js

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import { AuthRequiredError, CommandExecutionError, EmptyResultError, SelectorError } from '../../errors.js';
-import { apiGet } from './utils.js';
+import { apiGet, resolveBvid } from './utils.js';
 cli({
     site: 'bilibili',
     name: 'subtitle',
@@ -14,8 +14,9 @@ cli({
     func: async (page, kwargs) => {
         if (!page)
             throw new CommandExecutionError('Browser session required for bilibili subtitle');
+        const bvid = await resolveBvid(kwargs.bvid);
         // 1. 先前往视频详情页 (建立有鉴权的 Session，且这里不需要加载完整个视频)
-        await page.goto(`https://www.bilibili.com/video/${kwargs.bvid}/`);
+        await page.goto(`https://www.bilibili.com/video/${bvid}/`);
         // 2. 利用 __INITIAL_STATE__ 获取基础信息，拿 CID
         const cid = await page.evaluate(`(async () => {
       const state = window.__INITIAL_STATE__ || {};
@@ -27,7 +28,7 @@ cli({
         // 3. 在 Node 端使用 apiGet 获取带 Wbi 签名的字幕列表
         // 之前纯靠 evaluate 里的 fetch 会失败，因为 B 站 /wbi/ 开头的接口强校验 w_rid，未签名直接被风控返回 403 HTML
         const payload = await apiGet(page, '/x/player/wbi/v2', {
-            params: { bvid: kwargs.bvid, cid },
+            params: { bvid, cid },
             signed: true, // 开启 wbi_sign 自动签名
         });
         if (payload.code !== 0) {

package/dist/clis/bilibili/subtitle.test.js

@@ -3,7 +3,8 @@ import { AuthRequiredError, EmptyResultError } from '../../errors.js';
 const { mockApiGet } = vi.hoisted(() => ({
     mockApiGet: vi.fn(),
 }));
-vi.mock('./utils.js', () => ({
+vi.mock('./utils.js', async (importOriginal) => ({
+    ...(await importOriginal()),
     apiGet: mockApiGet,
 }));
 import { getRegistry } from '../../registry.js';

package/dist/clis/bilibili/utils.d.ts

@@ -2,6 +2,11 @@
  * Bilibili shared helpers: WBI signing, authenticated fetch, nav data, UID resolution.
  */
 import type { IPage } from '../../types.js';
+/**
+ * Resolve Bilibili short URL / short code to BV ID.
+ * Supports: BV1MV9NBtENN, XYzsqGa, b23.tv/XYzsqGa, https://b23.tv/XYzsqGa
+ */
+export declare function resolveBvid(input: unknown): Promise<string>;
 export declare function stripHtml(s: string): string;
 export declare function payloadData(payload: any): any;
 export declare function wbiSign(page: IPage, params: Record<string, any>): Promise<Record<string, string>>;

package/dist/clis/bilibili/utils.js

@@ -1,7 +1,37 @@
 /**
  * Bilibili shared helpers: WBI signing, authenticated fetch, nav data, UID resolution.
  */
+import https from 'node:https';
 import { AuthRequiredError, EmptyResultError } from '../../errors.js';
+/**
+ * Resolve Bilibili short URL / short code to BV ID.
+ * Supports: BV1MV9NBtENN, XYzsqGa, b23.tv/XYzsqGa, https://b23.tv/XYzsqGa
+ */
+export function resolveBvid(input) {
+    const trimmed = String(input).trim();
+    if (/^BV[A-Za-z0-9]+$/i.test(trimmed)) {
+        return Promise.resolve(trimmed);
+    }
+    const shortCode = trimmed.replace(/^https?:\/\//, '').replace(/^(www\.)?b23\.tv\//, '');
+    const url = 'https://b23.tv/' + shortCode;
+    return new Promise((resolve, reject) => {
+        const req = https.get(url, (res) => {
+            const location = res.headers.location;
+            if (location) {
+                const match = location.match(/\/video\/(BV[A-Za-z0-9]+)/);
+                if (match) {
+                    res.resume();
+                    resolve(match[1]);
+                    return;
+                }
+            }
+            res.resume();
+            reject(new Error(`Cannot resolve BV ID from short URL: ${trimmed}`));
+        });
+        req.on('error', reject);
+        req.setTimeout(5000, () => { req.destroy(); reject(new Error(`Timeout resolving short URL: ${trimmed}`)); });
+    });
+}
 const MIXIN_KEY_ENC_TAB = [
     46, 47, 18, 2, 53, 8, 23, 32, 15, 50, 10, 31, 58, 3, 45, 35, 27, 43, 5, 49,
     33, 9, 42, 19, 29, 28, 14, 39, 12, 38, 41, 13, 37, 48, 7, 16, 24, 55, 40,

package/dist/clis/bilibili/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clis/bilibili/utils.test.js

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import { resolveBvid } from './utils.js';
+describe('resolveBvid', () => {
+    it('passes through a valid BV ID', async () => {
+        expect(await resolveBvid('BV1MV9NBtENN')).toBe('BV1MV9NBtENN');
+    });
+    it('passes through BV ID with surrounding whitespace', async () => {
+        expect(await resolveBvid('  BV1MV9NBtENN  ')).toBe('BV1MV9NBtENN');
+    });
+    it('handles non-string input via String() coercion', async () => {
+        expect(await resolveBvid('BV123abc')).toBe('BV123abc');
+    });
+    it('rejects invalid input that cannot be resolved', async () => {
+        // A random string that b23.tv won't resolve — should timeout or fail
+        await expect(resolveBvid('not-a-valid-code-99999')).rejects.toThrow();
+    });
+});