@rankwrangler/cli 0.11.0 → 0.13.0

package/README.md

@@ -13,10 +13,9 @@ 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/results`,
+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.

package/dist/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to this project will be documented in this file.
 
+## v0.13.0 - 2026-10-28
+
+### Added
+
+- Rebuild the website on HeroUI Pro: Explore and Keywords grids with filter sidebars and counts,
+  KPI bands, BSR sparklines, a pager, and a full Product page.
+- Drive keywords from Brand Analytics searches and keyword themes for every Merch product type,
+  with five relevant keywords selected per product and collection run as gated jobs.
+- Detect Merch products by part number and keep scans Merch-only; the Merch re-check can demote
+  false positives.
+- Push keyword, sync and log changes live over the tRPC WebSocket.
+
+### Changed
+
+- Breaking: public keyword reads replace `state`, `status` and `untrackedReason` with `stage`
+  (`graduated`, `trial`, `dropped`, `untracked`) and `freshness` (`live`, `needsSync`, `syncing`),
+  and add `searchFrequencyRank`.
+- Re-check graduated keywords ahead of trials, tune scan rate and depth with daily provider
+  ceilings, and let live searches win Keepa capacity over background work.
+
+### Fixed
+
+- Answer live catalog searches before saving Product history, and record why failed searches
+  failed.
+- Adapt Ads pacing to 429 responses and drop Keepa's no-category sentinel rank.
+
+## 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

package/dist/cli-keyword-command.js

@@ -1,5 +1,4 @@
 import { parseIntegerOption } from './cli-options.js';
-const KEYWORD_MARKETPLACE_ID = 'ATVPDKIKX0DER';
 export const runKeywordCommand = async (command, client, options, fail) => {
     if (command.verb !== 'results' && options.refresh) {
         fail('INVALID_INPUT', '--refresh is only supported for keyword results');
@@ -16,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}`,
     });
@@ -27,21 +23,15 @@ 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),
+        stage: keywordChoice(options.stage, KEYWORD_STAGES, 'stage', fail),
+        freshness: keywordChoice(options.freshness, KEYWORD_FRESHNESS, 'freshness', fail),
+        cursor: options.cursor ? parseKeywordCursor(options.cursor, fail) : undefined,
         limit: parseIntegerOption({
             value: options.limit,
             optionName: 'limit',
@@ -49,21 +39,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) => {
@@ -73,3 +48,25 @@ const requireKeyword = (args, fail, commandName) => {
     }
     return keyword;
 };
+const KEYWORD_STAGES = ['graduated', 'trial', 'dropped', 'untracked', 'all'];
+const KEYWORD_FRESHNESS = ['live', 'needsSync', 'syncing', 'all'];
+const keywordChoice = (value, choices, name, fail) => {
+    if (value === undefined)
+        return undefined;
+    const match = choices.find(candidate => candidate === value);
+    return match ?? fail('INVALID_INPUT', `--${name} must be ${choices.join(', ')}`);
+};
+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'
+            || (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, sort: parsed.sort };
+    }
+    catch {
+        return fail('INVALID_INPUT', '--cursor must be valid JSON');
+    }
+};

package/dist/cli-options.d.ts

@@ -11,6 +11,8 @@ export interface CliOptionValues {
     includeOfficialBrands?: boolean;
     merch?: string;
     listingStatus?: string;
+    stage?: string;
+    freshness?: string;
     sort?: string;
     minBsr?: string;
     maxBsr?: string;

package/dist/index.js

@@ -16,7 +16,6 @@ const SUPPORTED_COMMANDS = new Set([
     'product:history',
     'keyword:get',
     'keyword:search',
-    'keyword:history',
     'keyword:results',
     'auth:status',
     'auth:set',
@@ -38,7 +37,6 @@ 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' },
@@ -53,6 +51,8 @@ const { positionals, values } = parseArgs({
         includeOfficialBrands: { type: 'boolean' },
         merch: { type: 'string' },
         listingStatus: { type: 'string' },
+        stage: { type: 'string' },
+        freshness: { type: 'string' },
         sort: { type: 'string' },
         minBsr: { type: 'string' },
         maxBsr: { type: 'string' },

package/dist/usage.js

@@ -20,7 +20,6 @@ export const printUsage = (paths) => {
         '  product history <ASIN>',
         '  keyword get <keyword>',
         '  keyword search <text>',
-        '  keyword history <keyword>',
         '  keyword results <keyword>',
         '  auth status',
         '  auth set [apiKey]',
@@ -44,11 +43,10 @@ export const printUsage = (paths) => {
         '  --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 <value>         Product search cursor or keyword search offset',
+        '  --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',
@@ -63,6 +61,8 @@ export const printUsage = (paths) => {
         '  --facet <facet=name>     Repeat for facet filters',
         '  --merch <value>          true,false,unknown,all (default: true)',
         '  --listingStatus <value>  active,deleted,all (default: active)',
+        '  --stage <value>          Keyword search: graduated,trial,dropped,untracked,all (default: graduated)',
+        '  --freshness <value>      Keyword search: live,needsSync,syncing,all (default: all)',
         '  --includeOfficialBrands  Include known official brands in Product search',
         '  --stdin                  Read auth secret from standard input',
         '',
@@ -87,7 +87,7 @@ export const printUsage = (paths) => {
         '  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',
+        '  rw keyword search "retro gardening" --stage trial',
         '  RR_STORAGE_DIR=~/.config/rankwrangler rw config show',
         '  rw --version',
         '  rw changelog',

package/package.json

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