@jackwener/opencli 1.6.1 → 1.6.3

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

@@ -0,0 +1,59 @@
+import { type CliOptions } from '../../src/registry.js';
+import { type AmazonRankingListType } from './shared.js';
+export interface RankingCardPayload {
+    rank_text?: string | null;
+    asin?: string | null;
+    title?: string | null;
+    href?: string | null;
+    price_text?: string | null;
+    rating_text?: string | null;
+    review_count_text?: string | null;
+    card_text?: string | null;
+}
+interface RankingPagePayload {
+    href?: string;
+    title?: string;
+    list_title?: string;
+    category_title?: string;
+    category_path?: string[];
+    cards?: RankingCardPayload[];
+    page_links?: string[];
+    visible_category_links?: Array<{
+        title?: string | null;
+        url?: string | null;
+        node_id?: string | null;
+    }>;
+}
+interface RankingCommandDefinition {
+    commandName: string;
+    listType: AmazonRankingListType;
+    description: string;
+}
+interface RankingNormalizeContext {
+    listType: AmazonRankingListType;
+    rankFallback: number;
+    listTitle: string | null;
+    sourceUrl: string;
+    categoryTitle: string | null;
+    categoryUrl: string | null;
+    categoryPath: string[];
+    visibleCategoryLinks: Array<{
+        title: string;
+        url: string;
+        node_id: string | null;
+    }>;
+}
+declare function parseRank(rawRank: string | null | undefined, fallback: number): number;
+declare function normalizeVisibleCategoryLinks(links: RankingPagePayload['visible_category_links']): Array<{
+    title: string;
+    url: string;
+    node_id: string | null;
+}>;
+export declare function normalizeRankingCandidate(candidate: RankingCardPayload, context: RankingNormalizeContext): Record<string, unknown>;
+export declare function createRankingCliOptions(definition: RankingCommandDefinition): CliOptions;
+export declare const __test__: {
+    parseRank: typeof parseRank;
+    normalizeVisibleCategoryLinks: typeof normalizeVisibleCategoryLinks;
+    normalizeRankingCandidate: typeof normalizeRankingCandidate;
+};
+export {};

package/dist/clis/amazon/rankings.js

@@ -0,0 +1,226 @@
+import { CommandExecutionError } from '../../src/errors.js';
+import { Strategy } from '../../src/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.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/search.js

@@ -1,5 +1,5 @@
-import { CommandExecutionError } from '../../errors.js';
-import { cli, Strategy } from '../../registry.js';
+import { CommandExecutionError } from '../../src/errors.js';
+import { cli, Strategy } from '../../src/registry.js';
 import { buildProvenance, buildSearchUrl, cleanText, extractAsin, normalizeProductUrl, parsePriceText, parseRatingValue, parseReviewCount, assertUsableState, gotoAndReadState, } from './shared.js';
 function normalizeSearchCandidate(candidate, rank, sourceUrl) {
     const productUrl = normalizeProductUrl(candidate.href);

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

@@ -1,13 +1,16 @@
-import type { IPage } from '../../types.js';
+import type { IPage } from '../../src/types.js';
 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

@@ -1,8 +1,10 @@
-import { ArgumentError, CommandExecutionError } from '../../errors.js';
+import { ArgumentError, CommandExecutionError } from '../../src/errors.js';
 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/antigravity/dump.d.ts

@@ -1 +1 @@
-export declare const dumpCommand: import("../../registry.js").CliCommand;
+export declare const dumpCommand: import("../../src/registry.js").CliCommand;

package/dist/clis/antigravity/dump.js

@@ -1,4 +1,4 @@
-import { cli, Strategy } from '../../registry.js';
+import { cli, Strategy } from '../../src/registry.js';
 import * as fs from 'node:fs';
 export const dumpCommand = cli({
     site: 'antigravity',

package/dist/clis/antigravity/extract-code.d.ts

@@ -1 +1 @@
-export declare const extractCodeCommand: import("../../registry.js").CliCommand;
+export declare const extractCodeCommand: import("../../src/registry.js").CliCommand;

package/dist/clis/antigravity/extract-code.js

@@ -1,4 +1,4 @@
-import { cli, Strategy } from '../../registry.js';
+import { cli, Strategy } from '../../src/registry.js';
 export const extractCodeCommand = cli({
     site: 'antigravity',
     name: 'extract-code',

package/dist/clis/antigravity/model.d.ts

@@ -1 +1 @@
-export declare const modelCommand: import("../../registry.js").CliCommand;
+export declare const modelCommand: import("../../src/registry.js").CliCommand;

package/dist/clis/antigravity/model.js

@@ -1,4 +1,4 @@
-import { cli, Strategy } from '../../registry.js';
+import { cli, Strategy } from '../../src/registry.js';
 export const modelCommand = cli({
     site: 'antigravity',
     name: 'model',

package/dist/clis/antigravity/new.d.ts

@@ -1 +1 @@
-export declare const newCommand: import("../../registry.js").CliCommand;
+export declare const newCommand: import("../../src/registry.js").CliCommand;

package/dist/clis/antigravity/new.js

@@ -1,4 +1,4 @@
-import { cli, Strategy } from '../../registry.js';
+import { cli, Strategy } from '../../src/registry.js';
 export const newCommand = cli({
     site: 'antigravity',
     name: 'new',

package/dist/clis/antigravity/read.d.ts

@@ -1 +1 @@
-export declare const readCommand: import("../../registry.js").CliCommand;
+export declare const readCommand: import("../../src/registry.js").CliCommand;

package/dist/clis/antigravity/read.js

@@ -1,4 +1,4 @@
-import { cli, Strategy } from '../../registry.js';
+import { cli, Strategy } from '../../src/registry.js';
 export const readCommand = cli({
     site: 'antigravity',
     name: 'read',

package/dist/clis/antigravity/send.d.ts

@@ -1 +1 @@
-export declare const sendCommand: import("../../registry.js").CliCommand;
+export declare const sendCommand: import("../../src/registry.js").CliCommand;

package/dist/clis/antigravity/send.js

@@ -1,4 +1,4 @@
-import { cli, Strategy } from '../../registry.js';
+import { cli, Strategy } from '../../src/registry.js';
 export const sendCommand = cli({
     site: 'antigravity',
     name: 'send',

package/dist/clis/antigravity/serve.js

@@ -11,8 +11,8 @@
  */
 import { createServer } from 'node:http';
 import { CDPBridge } from '../../browser/cdp.js';
-import { resolveElectronEndpoint } from '../../launcher.js';
-import { EXIT_CODES, getErrorMessage } from '../../errors.js';
+import { resolveElectronEndpoint } from '../../src/launcher.js';
+import { EXIT_CODES, getErrorMessage } from '../../src/errors.js';
 // ─── Helpers ─────────────────────────────────────────────────────────
 function generateMsgId() {
     const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';

package/dist/clis/antigravity/status.d.ts

@@ -1 +1 @@
-export declare const statusCommand: import("../../registry.js").CliCommand;
+export declare const statusCommand: import("../../src/registry.js").CliCommand;

package/dist/clis/antigravity/status.js

@@ -1,4 +1,4 @@
-import { cli, Strategy } from '../../registry.js';
+import { cli, Strategy } from '../../src/registry.js';
 export const statusCommand = cli({
     site: 'antigravity',
     name: 'status',