@rankwrangler/cli 0.10.0 → 0.12.0

package/README.md

@@ -8,18 +8,19 @@ npm install -g @rankwrangler/cli
 rw auth set ak_...
 rw product get B0DV53VS61
 rw product get B0DV53VS61 --shortName
-rw product search "retro gardening shirt"
+rw product search "retro gardening shirt" --maxBsr 300000
+rw keyword results "retro gardening shirt"
 rw product history B0DV53VS61 --bucket week
 rw keyword get "retro gardening shirt"
 rw keyword search "retro gardening"
-rw keyword history "retro gardening shirt" --rangeDays 90
 ```
 
-The public command surface is Product `get/search/history`, keyword `get/search/history`, auth,
-config, version, and changelog. Product `get/history` and keyword reads wait for policy-current
-data and expose no refresh control; Product search retains its separate search contract. Search
-data contains `keyword`, `searchedAt`, and compact results with `organicSearchPlacement`. Output is
-a JSON `{ ok, data }` envelope; failures use `{ ok: false, error }` on stderr.
+The public command surface is Product `get/search/history`, keyword `get/search/results`,
+auth, config, version, and changelog. Product search reads the collected database immediately and
+supports filters, sorting, and cursor pagination. Keyword results returns dated Amazon search
+results with placement and accepts `--refresh` to replace the observed Search run.
+Product `get/history` and other keyword reads use server-owned freshness policy.
+Output is a JSON `{ ok, data }` envelope; failures use `{ ok: false, error }` on stderr.
 The CLI does not expose Catalog, Operation, provider status, or polling commands.
 `--shortName` adds a nullable image-informed `listing.shortName` to a single Product get, waiting
 up to 20 seconds for generation and returning `null` if it is still running.

package/dist/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to this project will be documented in this file.
 
+## v0.12.0 - 2026-10-26
+
+### Added
+
+- Collect keyword candidates once per Merch ASIN through Amazon Ads and once per tracked keyword
+  through autocomplete, sharing cached Jev decisions and popularity-based discovery scheduling.
+- Add a persistent pause/resume control for the keyword pipeline, initialized paused on rollout.
+- Show the live keyword directory with plain status badges, work-priority ordering, BSR popularity
+  and refresh cadence in a Products-style table. Record keyword lifecycle events in Logs.
+
+### Changed
+
+- Breaking: keyword get/search now read the stored keyword directory; keyword search uses an opaque
+  cursor object. Remove Brand Analytics keyword history and its CLI/MCP operation.
+- Retire Search Terms, Brand Analytics report ingestion, metrics and health checks. Migration drops
+  obsolete report tables and demand fields while retaining canonical keywords and product evidence.
+
+## v0.11.0 - 2026-10-23
+
+### Changed
+
+- Breaking: `product.search` is now a query over the collected catalog, with optional text,
+  structured filters, screening metrics, sorting and cursor pagination. It returns
+  `items`, `nextCursor` and dated keyword coverage without waiting for external collection.
+- Preserve the previous external search capability as `keyword.results`, a mutation accepting
+  `term` and optional `refresh`, with dated Product placements in the existing response shape.
+- Use the same catalog filtering and sorting in the dashboard, CLI and MCP. Dashboard filters
+  apply to the full stored catalog rather than only loaded pages.
+
+### Added
+
+- Prepare native text-search indexes and a verified official-brand registry. Research search hides
+  known registry matches by default while retaining unknown brands. The registry starts empty.
+
+- Add adaptive keyword checks, bounded SP-API pagination and dated collection coverage. General
+  searches record interest and return immediately; collection runs independently in the background.
+- Protect Keepa capacity with durable request reservations, measured costs and separate work budgets.
+  Admit new recurring history selectively while preserving every existing Product's eligibility.
+- Add operator collection status and active/admitted refresh counts.
+
 ## v0.10.0 - 2026-10-20
 
 ### Added

package/dist/cli-keyword-command.js

@@ -1,8 +1,13 @@
 import { parseIntegerOption } from './cli-options.js';
-const KEYWORD_MARKETPLACE_ID = 'ATVPDKIKX0DER';
 export const runKeywordCommand = async (command, client, options, fail) => {
-    if (options.refresh) {
-        fail('INVALID_INPUT', '--refresh is not supported for keyword reads');
+    if (command.verb !== 'results' && options.refresh) {
+        fail('INVALID_INPUT', '--refresh is only supported for keyword results');
+    }
+    if (command.verb === 'results') {
+        return await client.keyword.results.mutate({
+            term: requireKeyword(command.args, fail, 'keyword results'),
+            refresh: Boolean(options.refresh),
+        });
     }
     if (command.verb === 'get') {
         return await runKeywordGet(command.args, client, fail);
@@ -10,9 +15,6 @@ export const runKeywordCommand = async (command, client, options, fail) => {
     if (command.verb === 'search') {
         return await runKeywordSearch(command.args, client, options, fail);
     }
-    if (command.verb === 'history') {
-        return await runKeywordHistory(command.args, client, options, fail);
-    }
     fail('UNKNOWN_COMMAND', 'Unknown Keyword command', {
         command: `keyword ${command.verb}`,
     });
@@ -21,21 +23,13 @@ const runKeywordGet = async (args, client, fail) => {
     const keyword = requireKeyword(args, fail, 'keyword get');
     return await client.keyword.get.query({
         keyword,
-        marketplaceId: KEYWORD_MARKETPLACE_ID,
     });
 };
 const runKeywordSearch = async (args, client, options, fail) => {
     const text = requireKeyword(args, fail, 'keyword search');
     return await client.keyword.search.query({
         text,
-        marketplaceId: KEYWORD_MARKETPLACE_ID,
-        cursor: parseIntegerOption({
-            value: options.cursor,
-            optionName: 'cursor',
-            min: 0,
-            max: 1_000_000,
-            defaultValue: 0,
-        }, fail),
+        cursor: options.cursor ? parseKeywordCursor(options.cursor, fail) : undefined,
         limit: parseIntegerOption({
             value: options.limit,
             optionName: 'limit',
@@ -43,21 +37,6 @@ const runKeywordSearch = async (args, client, options, fail) => {
             max: 100,
             defaultValue: 25,
         }, fail),
-        merchOnly: true,
-    });
-};
-const runKeywordHistory = async (args, client, options, fail) => {
-    const keyword = requireKeyword(args, fail, 'keyword history');
-    return await client.keyword.history.query({
-        keyword,
-        marketplaceId: KEYWORD_MARKETPLACE_ID,
-        rangeDays: parseIntegerOption({
-            value: options.rangeDays ?? options.days,
-            optionName: 'rangeDays',
-            min: 7,
-            max: 365,
-            defaultValue: 90,
-        }, fail),
     });
 };
 const requireKeyword = (args, fail, commandName) => {
@@ -67,3 +46,17 @@ const requireKeyword = (args, fail, commandName) => {
     }
     return keyword;
 };
+const parseKeywordCursor = (value, fail) => {
+    try {
+        const parsed = JSON.parse(value);
+        const key = parsed?.key;
+        if (!Array.isArray(key) || key.length !== 7 || !key.slice(0, 6).every(part => typeof part === 'number' && Number.isFinite(part))
+            || typeof key[6] !== 'string' || typeof parsed.asOf !== 'string' || typeof parsed.trialTurn !== 'boolean'
+            || (parsed.sort !== 'work' && parsed.sort !== 'newest'))
+            return fail('INVALID_INPUT', '--cursor must be the JSON nextCursor from keyword search');
+        return { key: [key[0], key[1], key[2], key[3], key[4], key[5], key[6]], asOf: parsed.asOf, trialTurn: parsed.trialTurn, sort: parsed.sort };
+    }
+    catch {
+        return fail('INVALID_INPUT', '--cursor must be valid JSON');
+    }
+};

package/dist/cli-options.d.ts

@@ -2,6 +2,28 @@ import type { CliConfig } from './cli-config';
 import { type HistoryBucket, type HistoryMetricAlias } from './history-options';
 type CliFail = (code: string, message: string, details?: unknown) => never;
 export interface CliOptionValues {
+    textFields?: string;
+    excludeWord?: string[];
+    brand?: string[];
+    excludeBrand?: string[];
+    categoryId?: string[];
+    facet?: string[];
+    includeOfficialBrands?: boolean;
+    merch?: string;
+    listingStatus?: string;
+    sort?: string;
+    minBsr?: string;
+    maxBsr?: string;
+    minPrice?: string;
+    maxPrice?: string;
+    minMonthlySold?: string;
+    maxMonthlySold?: string;
+    updatedAfter?: string;
+    updatedBefore?: string;
+    availableAfter?: string;
+    availableBefore?: string;
+    discoveredAfter?: string;
+    discoveredBefore?: string;
     baseUrl?: string;
     marketplace?: string;
     metrics?: string;

package/dist/cli-product-command.js

@@ -1,7 +1,8 @@
+import { runProductSearch } from './cli-product-search.js';
 import { parseIntegerOption, requireAsins, requireMarketplaceId, requireSingleAsin, resolveHistoryBucket, resolveHistoryMetrics, resolveHistoryWindow, } from './cli-options.js';
 export const runProductCommand = async (command, client, config, options, fail) => {
-    if (command.verb !== 'search' && options.refresh) {
-        fail('INVALID_INPUT', '--refresh is only supported for product search');
+    if (options.refresh) {
+        fail('INVALID_INPUT', '--refresh is only supported for keyword results');
     }
     if (command.verb !== 'get' && options.shortName) {
         fail('INVALID_INPUT', '--shortName is only supported for product get');
@@ -10,7 +11,7 @@ export const runProductCommand = async (command, client, config, options, fail)
         return await runProductGet(command.args, client, config, options, fail);
     }
     if (command.verb === 'search') {
-        return await runProductSearch(command.args, client, options, fail);
+        return await runProductSearch(command.args, client, config, options, fail);
     }
     if (command.verb === 'history') {
         return await runProductHistory(command.args, client, config, options, fail);
@@ -36,16 +37,6 @@ const runProductGet = async (args, client, config, options, fail) => {
         products: asins.map(asin => ({ marketplaceId, asin })),
     });
 };
-const runProductSearch = async (args, client, options, fail) => {
-    const term = args.join(' ').trim();
-    if (!term) {
-        fail('INVALID_INPUT', 'product search requires a keyword');
-    }
-    return await client.product.search.mutate({
-        term,
-        refresh: Boolean(options.refresh),
-    });
-};
 const runProductHistory = async (args, client, config, options, fail) => {
     const asin = requireSingleAsin(args, fail, 'product history');
     const historyOptions = resolveHistoryOptions(options, fail);

package/dist/cli-product-search.d.ts

@@ -0,0 +1,6 @@
+import type { createRankWranglerClient } from '@rankwrangler/http-client';
+import type { CliConfig } from './cli-config';
+import { type CliOptionValues } from './cli-options';
+type CliFail = (code: string, message: string, details?: unknown) => never;
+export declare const runProductSearch: (args: string[], client: ReturnType<typeof createRankWranglerClient>, config: CliConfig, options: CliOptionValues, fail: CliFail) => Promise<unknown>;
+export {};

package/dist/cli-product-search.js

@@ -0,0 +1,99 @@
+import { requireMarketplaceId } from './cli-options.js';
+export const runProductSearch = async (args, client, config, options, fail) => {
+    const term = args.join(' ').trim();
+    const merch = choice(options.merch, ['true', 'false', 'unknown', 'all'], 'merch', fail);
+    return await client.product.search.query({
+        ...(term ? { term } : {}),
+        marketplaceIds: [requireMarketplaceId(options, config)],
+        textFields: choice(options.textFields, ['all', 'title'], 'textFields', fail),
+        excludeWords: options.excludeWord,
+        brands: options.brand,
+        excludeBrands: options.excludeBrand,
+        categoryIds: options.categoryId?.map(value => integer(value, 'categoryId', 1, fail)),
+        facets: options.facet?.map(value => {
+            const separator = value.indexOf('=');
+            if (separator < 1 || separator === value.length - 1) {
+                fail('INVALID_INPUT', '--facet must be facet=name');
+            }
+            return {
+                facet: value.slice(0, separator),
+                name: value.slice(separator + 1),
+            };
+        }),
+        includeOfficialBrands: options.includeOfficialBrands,
+        isMerchListing: merch === undefined
+            ? undefined
+            : merch === 'unknown' || merch === 'all'
+                ? merch
+                : merch === 'true',
+        amazonListingStatus: choice(options.listingStatus, ['active', 'deleted', 'all'], 'listingStatus', fail),
+        salesRank: range(options.minBsr, options.maxBsr, 'Bsr', fail),
+        price: range(options.minPrice, options.maxPrice, 'Price', fail),
+        monthlySold: range(options.minMonthlySold, options.maxMonthlySold, 'MonthlySold', fail),
+        firstAvailableAt: dates(options.availableAfter, options.availableBefore, 'available', fail),
+        updatedAt: dates(options.updatedAfter, options.updatedBefore, 'updated', fail),
+        discoveredAt: dates(options.discoveredAfter, options.discoveredBefore, 'discovered', fail),
+        sort: choice(options.sort, [
+            'relevance',
+            'salesRankAsc',
+            'salesRankDesc',
+            'firstAvailableAtDesc',
+            'firstAvailableAtAsc',
+            'updatedAtAsc',
+            'updatedAtDesc',
+            'discoveredAtDesc',
+            'priceAsc',
+            'priceDesc',
+            'monthlySoldDesc',
+        ], 'sort', fail),
+        limit: options.limit === undefined ? undefined : integer(options.limit, 'limit', 1, fail, 100),
+        cursor: options.cursor,
+    });
+};
+const choice = (value, choices, name, fail) => {
+    if (value === undefined)
+        return undefined;
+    const match = choices.find(candidate => candidate === value);
+    if (match === undefined)
+        fail('INVALID_INPUT', `--${name} must be ${choices.join(', ')}`);
+    return match;
+};
+const integer = (value, name, min, fail, max = Number.MAX_SAFE_INTEGER) => {
+    const parsed = Number(value);
+    if (!value.trim() || !Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+        fail('INVALID_INPUT', `--${name} must be an integer between ${min} and ${max}`);
+    }
+    return parsed;
+};
+const range = (min, max, name, fail) => {
+    if (min === undefined && max === undefined)
+        return undefined;
+    const bounds = {
+        ...(min === undefined ? {} : { min: integer(min, `min${name}`, 0, fail) }),
+        ...(max === undefined ? {} : { max: integer(max, `max${name}`, 0, fail) }),
+    };
+    if (bounds.min !== undefined && bounds.max !== undefined && bounds.min > bounds.max) {
+        fail('INVALID_INPUT', `--min${name} must not exceed --max${name}`);
+    }
+    return bounds;
+};
+const dates = (after, before, name, fail) => {
+    if (after === undefined && before === undefined)
+        return undefined;
+    const parse = (value) => {
+        if (!/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?Z)?$/.test(value) ||
+            !Number.isFinite(new Date(value).getTime()) ||
+            new Date(value).toISOString().slice(0, 10) !== value.slice(0, 10)) {
+            fail('INVALID_INPUT', `--${name}After and --${name}Before require ISO dates`);
+        }
+        return new Date(value).toISOString();
+    };
+    const bounds = {
+        after: after === undefined ? undefined : parse(after),
+        before: before === undefined ? undefined : parse(before),
+    };
+    if (bounds.after && bounds.before && bounds.after > bounds.before) {
+        fail('INVALID_INPUT', `--${name}After must not exceed --${name}Before`);
+    }
+    return bounds;
+};

package/dist/index.js

@@ -16,7 +16,7 @@ const SUPPORTED_COMMANDS = new Set([
     'product:history',
     'keyword:get',
     'keyword:search',
-    'keyword:history',
+    'keyword:results',
     'auth:status',
     'auth:set',
     'auth:clear',
@@ -37,12 +37,33 @@ const { positionals, values } = parseArgs({
         startAt: { type: 'string' },
         endAt: { type: 'string' },
         days: { type: 'string' },
-        rangeDays: { type: 'string' },
         limit: { type: 'string' },
         bucket: { type: 'string' },
         cursor: { type: 'string' },
         refresh: { type: 'boolean' },
         shortName: { type: 'boolean' },
+        textFields: { type: 'string' },
+        excludeWord: { type: 'string', multiple: true },
+        brand: { type: 'string', multiple: true },
+        excludeBrand: { type: 'string', multiple: true },
+        categoryId: { type: 'string', multiple: true },
+        facet: { type: 'string', multiple: true },
+        includeOfficialBrands: { type: 'boolean' },
+        merch: { type: 'string' },
+        listingStatus: { type: 'string' },
+        sort: { type: 'string' },
+        minBsr: { type: 'string' },
+        maxBsr: { type: 'string' },
+        minPrice: { type: 'string' },
+        maxPrice: { type: 'string' },
+        minMonthlySold: { type: 'string' },
+        maxMonthlySold: { type: 'string' },
+        updatedAfter: { type: 'string' },
+        updatedBefore: { type: 'string' },
+        availableAfter: { type: 'string' },
+        availableBefore: { type: 'string' },
+        discoveredAfter: { type: 'string' },
+        discoveredBefore: { type: 'string' },
         stdin: { type: 'boolean' },
     },
     allowPositionals: true,
@@ -122,7 +143,9 @@ const resolveCommandOrFail = (inputPositionals) => {
     if (command) {
         return command;
     }
-    fail('UNKNOWN_COMMAND', 'Unknown command', { command: inputPositionals.join(' ') });
+    fail('UNKNOWN_COMMAND', 'Unknown command', {
+        command: inputPositionals.join(' '),
+    });
     throw new Error('unreachable');
 };
 const isSupportedCommand = (command) => SUPPORTED_COMMANDS.has(`${command.resource}:${command.verb}`);

package/dist/usage.js

@@ -16,11 +16,11 @@ export const printUsage = (paths) => {
         'COMMANDS',
         '  changelog',
         '  product get <ASIN...>',
-        '  product search <keyword>',
+        '  product search [text]',
         '  product history <ASIN>',
         '  keyword get <keyword>',
         '  keyword search <text>',
-        '  keyword history <keyword>',
+        '  keyword results <keyword>',
         '  auth status',
         '  auth set [apiKey]',
         '  auth set --stdin',
@@ -38,16 +38,30 @@ export const printUsage = (paths) => {
         '  --version                Print the CLI version',
         '  --baseUrl <origin>       Override API origin',
         `  -m, --marketplace <id>   Override marketplace (default: ${DEFAULT_MARKETPLACE_ID})`,
-        '  --refresh                Product search refresh (separate Search contract)',
+        '  --refresh                Replace the Search run for keyword results',
         '  --shortName              Generate a design name for one Merch Product',
         '  --metrics <list>         Product history metrics: salesRank,price (default: salesRank,price)',
         '  --bucket <unit>          Product history buckets: auto,day,week,month (default: auto)',
         '  --days <N>               Product history lookback (30-3650, default: 365)',
-        '  --rangeDays <N>          Keyword history lookback (7-365, default: 90)',
         '  --startAt <ISO>          Product history range start (ISO date/time)',
         '  --endAt <ISO>            Product history range end (ISO date/time)',
         '  --limit <N>              Result limit',
-        '  --cursor <N>             Keyword search offset (default: 0)',
+        '  --cursor <value>         Product search cursor or keyword nextCursor JSON',
+        '  --sort <order>           Product search order (default: relevance)',
+        '  --textFields <scope>     Product search text: all,title (default: all)',
+        '  --minBsr/--maxBsr <N>     Product sales-rank bounds',
+        '  --minPrice/--maxPrice <N> Product price bounds in minor currency units',
+        '  --minMonthlySold/--maxMonthlySold <N>  Product demand bounds',
+        '  --availableAfter/--availableBefore <ISO>  First-available bounds',
+        '  --discoveredAfter/--discoveredBefore <ISO>  Discovery bounds',
+        '  --updatedAfter/--updatedBefore <ISO>  Product update bounds',
+        '  --brand/--excludeBrand <name>  Repeat for brand filters',
+        '  --excludeWord <word>     Repeat for excluded words',
+        '  --categoryId <N>         Repeat for category filters',
+        '  --facet <facet=name>     Repeat for facet filters',
+        '  --merch <value>          true,false,unknown,all (default: true)',
+        '  --listingStatus <value>  active,deleted,all (default: active)',
+        '  --includeOfficialBrands  Include known official brands in Product search',
         '  --stdin                  Read auth secret from standard input',
         '',
         'FILES',
@@ -66,11 +80,11 @@ export const printUsage = (paths) => {
         '  printf %s "$MERCHBASE_API_KEY" | rw auth set --stdin',
         `  ${API_KEY_ENV_VAR}=ak_... rw product get B0DV53VS61`,
         '  rw product get B0DV53VS61 B012345678',
-        '  rw product search "retro gardening shirt"',
+        '  rw product search "retro gardening shirt" --maxBsr 300000 --sort salesRankAsc',
+        '  rw keyword results "retro gardening shirt"',
         '  rw product history B0DV53VS61 --bucket week',
         '  rw keyword get "retro gardening shirt"',
         '  rw keyword search "retro gardening" --limit 10',
-        '  rw keyword history "retro gardening shirt" --rangeDays 90',
         '  RR_STORAGE_DIR=~/.config/rankwrangler rw config show',
         '  rw --version',
         '  rw changelog',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rankwrangler/cli",
-    "version": "0.10.0",
+    "version": "0.12.0",
     "description": "Official RankWrangler command line interface",
     "repository": {
         "type": "git",
@@ -30,7 +30,7 @@
     },
     "dependencies": {
         "@merchbaseco/access": "0.4.0",
-        "@rankwrangler/http-client": "^0.10.0",
+        "@rankwrangler/http-client": "^0.12.0",
         "keytar": "7.9.0"
     },
     "devDependencies": {